Interface Optional<T>

An Optional is similar to a Stream but contains no more than one item. All stream properties, such as laziness, statelessness and implementing the iteration protocol, fully apply to optionals.

Like streams, optionals support intermediate and terminal operations. When a terminal operation is executed, the result value is computed. This process is described as:

  • "An optional resolves to a value" if there is an item.
  • "An optional resolves to empty" if there is no item.
interface Optional<T> {
    "[iterator]"(): Iterator<T, undefined, any>;
    every(predicate: (item: T, index: 0) => boolean): boolean;
    filter(predicate: (item: T, index: 0) => boolean): Optional<T>;
    filter<U>(predicate: (item: T, index: 0) => item is U): Optional<U>;
    flat<D extends number = 1>(depth?: D): Optional<FlatIterable<T, D>>;
    flatMap<U>(
        mapper: (item: T, index: 0) => Iterable<U, any, any>,
    ): Optional<U>;
    flatMapToStream<U>(
        mapper: (item: T, index: 0) => Iterable<U, any, any>,
    ): Stream<U>;
    forEach(effect: (item: T, index: number) => void): void;
    get(): T;
    is(item: T): boolean;
    isPresent(): boolean;
    map<U>(mapper: (item: T) => U): Optional<U>;
    mapNullable<U>(
        mapper: (item: T, index: 0) => undefined | null | U,
    ): Optional<U>;
    orElse<U>(other: U): T | U;
    orElseGet<U>(get: () => U): T | U;
    orElseThrow(createError: () => Error): T;
    orNull(): null | T;
    orUndefined(): undefined | T;
    peek(effect: (item: T, index: 0) => void): Optional<T>;
    resolve(): { has: true; val: T } | { has: false; val?: undefined };
    size(): number;
    some(predicate: (item: T, index: 0) => boolean): boolean;
    toArray(): T[];
    toSet(): Set<T>;
    toStream(): Stream<T>;
}

Type Parameters

  • T

    The type element in this Optional

Hierarchy

  • Iterable<T, undefined>
    • Optional

Methods

[iterator] every filter flat flatMap flatMapToStream forEach get is isPresent map mapNullable orElse orElseGet orElseThrow orNull orUndefined peek resolve size some toArray toSet toStream

Methods

[iterator]

  • "[iterator]"(): Iterator<T, undefined, any>

  • Returns an iterator that yields an item if this optional contains an item; otherwise, the iterator yields no items.

    Returns Iterator<T, undefined, any>

    An iterator over this optional

every

  • every(predicate: (item: T, index: 0) => boolean): boolean

  • Returns true if the optional has an item and the predicate evaluates to true for it, or if the optional is empty.

    Parameters

    • predicate: (item: T, index: 0) => boolean

      A function to test the item. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns boolean

    true if the predicate evaluates to true or the optional is empty, false otherwise.

filter

  • filter(predicate: (item: T, index: 0) => boolean): Optional<T>

  • Returns an optional resolving to the original item if this optional has an item and the predicate evaluates to true for it, or resolving to empty otherwise.

    Parameters

    • predicate: (item: T, index: 0) => boolean

      A function to evaluate the item. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns Optional<T>

    An optional containing the item if the predicate evaluates to true for it.

  • filter<U>(predicate: (item: T, index: 0) => item is U): Optional<U>

  • Returns an optional with a possibly narrowed type. Resolves to the original item if this optional contains an item and the predicate evaluates to true for it; otherwise, resolves to empty. For example, this can be used to filter out null values from the optional.

    streamOf('a', null, 'b')
       .head()
       .filter<string>(item => typeof item === 'string')
       .toArray() satisfies string[]

    Type Parameters

    • U

    Parameters

    • predicate: (item: T, index: 0) => item is U

      A type predicate to test the item and narrow its type. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns Optional<U>

    An Optional containing the item if the predicate is satisfied; otherwise, an empty optional.

flat

  • flat<D extends number = 1>(depth?: D): Optional<FlatIterable<T, D>>

  • Returns an optional with the following behavior:

    • If this optional is empty, resolves to empty.
    • If this optional is not empty, creates an iterable yielding the item, flattens it as described in Stream.flat, and resolves to the first item of the flattened iterable.

    Type Parameters

    • D extends number = 1

    Parameters

    • Optionaldepth: D

      The depth of flattening. Defaults to 1.

    Returns Optional<FlatIterable<T, D>>

    An Optional containing the first item of the flattened iterable.

flatMap

  • flatMap<U>(mapper: (item: T, index: 0) => Iterable<U, any, any>): Optional<U>

  • Creates an optional with the following behavior:

    • If this optional contains an item, applies mapper to it, and retrieves the first item from the returned iterable. If there is an item, resolves to it; otherwise, resolves to empty.
    • If this optional is empty, resolves to empty.

    Type Parameters

    • U

    Parameters

    • mapper: (item: T, index: 0) => Iterable<U, any, any>

      A function that takes an item and returns an iterable to create an optional from. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns Optional<U>

    An optional containing the first item of the iterable returned by mapper, or empty if the iterable has no items or this optional is empty.

flatMapToStream

  • flatMapToStream<U>(
        mapper: (item: T, index: 0) => Iterable<U, any, any>,
    ): Stream<U>

  • Creates a Stream with the following behavior:

    • If this optional contains an item, applies mapper to it and uses the returned iterable as input for the created stream.
    • If this optional is empty, the created stream is empty.

    Type Parameters

    • U

    Parameters

    • mapper: (item: T, index: 0) => Iterable<U, any, any>

      A function that takes an item and returns an iterable to create a new stream from. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns Stream<U>

    A stream created from the iterable returned by mapper, or an empty stream if this optional is empty.

forEach

  • forEach(effect: (item: T, index: number) => void): void

  • If this optional contains an item, invokes effect for it.

    Parameters

    • effect: (item: T, index: number) => void

      The effect to apply to this optional's item. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns void

get

  • get(): T

  • If this optional contains an item, returns that item; otherwise, throws an error.

    Returns T

    The item, if this optional has an item

    Throws

    An error if this optional is empty

is

  • is(item: T): boolean

  • Returns true if this optional contains an item and it strictly equals (===) the provided item; otherwise, returns false.

    Parameters

    • item: T

      The item to compare against the optional's item.

    Returns boolean

    true if the item is equal to the optional's item.

isPresent

  • isPresent(): boolean

  • Returns true if this optional contains an item; otherwise, returns false.

    Returns boolean

    true if this optional has an item

map

  • map<U>(mapper: (item: T) => U): Optional<U>

  • Returns an optional with the following behavior:

    • If this optional contains an item, invokes mapper with this item as an argument and resolves to the value returned by mapper.
    • If this optional is empty, resolves to empty.

    Type Parameters

    • U

    Parameters

    • mapper: (item: T) => U

      The function to transform an item.

    Returns Optional<U>

    An optional containing the result of applying mapper to the item, or an empty optional if this optional is empty.

mapNullable

  • mapNullable<U>(mapper: (item: T, index: 0) => undefined | null | U): Optional<U>

  • Returns an optional with the following behavior:

    • If this optional has an item, invokes mapper passing this item as an argument; if mapper returns null or undefined, resolves to empty; otherwise resolves to the value returned by mapper.
    • If this optional is empty, resolves to empty.

    Type Parameters

    • U

    Parameters

    • mapper: (item: T, index: 0) => undefined | null | U

      The function to transform an item with. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns Optional<U>

    An optional containing the non-null and non-undefined result of applying mapper to the item, or an empty optional otherwise

orElse

  • orElse<U>(other: U): T | U

  • If this optional has an item, returns that item; otherwise, returns other.

    Type Parameters

    • U

    Parameters

    • other: U

      Value to return if this optional is empty

    Returns T | U

    The item, if this optional has an item, or other otherwise

orElseGet

  • orElseGet<U>(get: () => U): T | U

  • If this optional has an item, returns that item; otherwise, returns the value returned by get.

    Type Parameters

    • U

    Parameters

    • get: () => U

      Function to take the result from if this optional is empty

    Returns T | U

    The item if present, otherwise the value returned by get

orElseThrow

  • orElseThrow(createError: () => Error): T

  • If this optional has an item, returns that item; otherwise throws an error created by createError

    Parameters

    • createError: () => Error

      Function to create an error if this optional is empty

    Returns T

    The item if present

    Throws

    The error created by createError if the optional is empty

orNull

  • orNull(): null | T

  • If this optional has an item, returns that item; otherwise returns null

    Returns null | T

    The item if present, otherwise null

orUndefined

  • orUndefined(): undefined | T

  • If this optional has an item, returns that item; otherwise returns undefined

    Returns undefined | T

    The item if present, otherwise undefined

peek

  • peek(effect: (item: T, index: 0) => void): Optional<T>

  • Returns an optional that resolves just like this optional, but when resolving to an item, additionally executes effect on that item before yielding it. One possible usage for this method is mutating the item in place.

    Parameters

    • effect: (item: T, index: 0) => void

      The effect to execute. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns Optional<T>

    The optional that resolves just like this one, but executes effect on the item before it is yielded

resolve

  • resolve(): { has: true; val: T } | { has: false; val?: undefined }

  • Returns {has: true, val: item} if this optional contains an item, or {has: false} otherwise. val? undefined only exists for type-safe destructuring; there won't be a val if the optional is empty.

    Returns { has: true; val: T } | { has: false; val?: undefined }

    An object indicating whether the optional contains an item, and the item itself if present.

size

  • size(): number

  • Returns 1 if this optional has an item; otherwise, returns 0.

    Returns number

    1 if this optional has an item; otherwise 0.

some

  • some(predicate: (item: T, index: 0) => boolean): boolean

  • Returns true if this optional has an item and predicate evaluates to true for it; false otherwise.

    Parameters

    • predicate: (item: T, index: 0) => boolean

      The predicate to test an item. For compatibility with Stream, it receives the index as a second argument, which is always 0 in this case.

    Returns boolean

    true if the optional has an item and the predicate returns true, otherwise false.

toArray

  • toArray(): T[]

  • If this optional has an item, returns an array containing that item as the only element; otherwise, returns an empty array.

    Returns T[]

    An array containing the item if present, or an empty array if the optional is empty.

toSet

  • toSet(): Set<T>

  • If this optional has an item, returns a set containing that item as the only element; otherwise, returns an empty set.

    Returns Set<T>

    A set containing the item if present, or an empty set if the optional is empty.

toStream

  • toStream(): Stream<T>

  • Returns a Stream with an item provided by this optional if it has an item; otherwise, the stream is empty.

    Returns Stream<T>

    A stream containing the item if present, or an empty stream if the optional is empty.

Settings

Member Visibility

On This Page

Methods