Class Option<T>

Returns a new option that is only present if both values (this, and the argument) are present. The value returned is the value contained in the option received as argument.

This method behaves similar to the && operator, but translated to optional values instead of booleans.

Example

const some = Option.Some('foo')
const another = Option.Some(5)
const result = some.and(another) // Some(5)
const none = Option.None()
const result2 = none.and(another) // None
const result3 = some.and(none) // None
Copy

Similar to and, but allowing the second optional to be generated lazily. The provided fn is not executed if this is None.

Example

const some = Option.Some(5)
const newSome = some.andThen(value => Option.Some(value * 2)) // Some(10)
const none = Option.None<number>()
const newNone = none.andThen(value => Option.Some(value * 2)) // None
Copy

Returns true if and only of both optionals are some and both have the same value. Comparison is done using ===.

Example

Option.None().equals(Option.None()) // true
Option.Some(10).equals(Option.None()) // false
Option.None().equals(Option.Some('foo')) // false
Option.Some('bar').equals(Option.Some('bar')) // true
Copy

Returns true if and only of both optionals are some and the provided equality check returns true.

Example

// If both are None, the equality function is not even called
Option.None().equalsWith(Option.None(), () => false) // true

// If one is some and the other is none, the equality function is not even called
Option.Some(10).equalsWith(Option.None(), () => true) // false
Option.None().equalsWith(Option.Some('foo'), () => true) // false

// If both are some the equality function is called
Option.Some(10).equalsWith(Option.Some(15), (a, b) => a % 5 === b % 5) // true
Option.Some(7).equalsWith(Option.Some(15), (a, b) => a % 5 === b % 5) // false
Copy

If there is a value present returns it, otherwise throws the error specified as argument.

This is the right method to use when you an error should be raised if the optional is empty.

Throws

The provided error if the Option instance does not contain a value.

Example

const some = Option.Some('foo')
some.expect(new Error('No value')) // 'foo'
const none = Option.None()
none.expect(new Error('No value')) // throws Error: 'No value'
Copy

Filters the value contained in the Option instance using the provided predicate function.

• If the Option instance does not contain a value (None), it returns a new Option without a value.
• If the Option instance contains a value (Some) and the predicate function returns true when applied to the value, it returns a new Option with the same value.
• If the Option instance contains a value (Some) and the predicate function returns false when applied to the value, it returns a new Option without a value (None).

Example

const opt1 = Option.Some(5)
const newOpt1 = opt1.filter(value => value > 3) // Some(5)
const opt2 = Option.None<number>()
const newOpt2 = opt2.filter(value => value > 3) // None
Copy

Flattens nested options. An Option<Option<T>> returns an Option<T> with the same value inside (or no value in case of None).

In case the option is not nested, it returns the same option.

There is a type safer alternative to this method as an exported function flatten

Example

const some = Option.Some(Option.Some('foo'))
some.flatten() // Some('foo')
const none = Option.None()
none.flatten() // None
Copy

If the instance contains a value returns that value. If the instance is empty it inserts the value provided by argument, and returns the value.

Notice that if the instance already had a value this method does not replace it and the argument is ignored.

Example

const opt1 = Option.None()
opt1.getOrInsert('foo') // 'foo'
opt1.isPresent() // true

const opt2 = Option.Some('bar')
opt2.getOrInsert('foo') // 'bar'
Copy

Similar to insert but allowing the inserted value to be calculated lazily.

If the instance is Some the value inside the option is present and the generator function is ignored.

If the instance is None, the provided function is called, and the result is inserted into the instance and returned.

Example

const opt1 = Option.None()
opt1.getOrInsertWith(() => 'foo') // 'foo'
opt1.isPresent() // true

const opt2 = Option.Some('bar')
opt2.getOrInsertWith(() => 'foo') // 'bar'
Copy

Executes the provided function if the Option instance does not contain a value. It always returns itself.

It's a nice method to chain with others

const a: Option<number>

a.ifNone(() => {
  // ... do something
}).andThen((value) => {
  // ... only executed if the first block was not.
})
Copy

Example

const some = Option.Some('foo')
some.ifNone(() => console.log('No value')) // does nothing
const none = Option.None()
none.ifNone(() => console.log('No value')) // logs 'No value' to the console
Copy

Allows to execute a block of code only if the instance is Some. It always returns the current instance.

It also allows to expressive chains like this:

let opt: Option<number>
opt.ifSome((value) => {
  console.log(`value: ${value}`)
}).orElse(() => {
  console.log('no value')
})
Copy

Example

const some = Option.Some('foo')
const res1 = some.ifSome(value => console.log(value)) // logs 'foo' to the console
res1 === some // true
const none = Option.None()
const res2 = none.ifSome(value => console.log(value)) // does nothing
res2 === none // true
Copy

Inserts a value into the Option instance, replacing the current value if it exists.

Example

const none = Option.None()
none.insert('foo') // Some('foo')
const some = Option.Some('bar')
some.insert('foo') // Some('foo')
Copy

Useful to evaluate what's inside the optional. If the instance is Some it executes the block of code with the value as argument. No mutability is done. Nonthing is returned.

If the instance is None, nothing happens.

Example

const some = Option.Some('foo')
some.inspect(value => console.log(value)) // logs 'foo' to the console
const none = Option.None()
none.inspect(value => console.log(value)) // does nothing
Copy

Returns true if the instance does not contain a value. Returns false otherwise.

Example

const none = Option.None()
none.isNone() // true
const some = Option.Some('foo')
some.isNone() // false
Copy

Checks if the Option instance contains a value.

Example

const none = Option.None()
none.isSome() // false
const some = Option.Some('foo')
some.isSome() // true
Copy

Returns true if and only if the current instance is Some and the value fulfills the given predicate.

This is the options equivalent to do something like the following but in the world of optionals.

if (a && myCondition(a)) {
  //...
}
Copy

Example

const some = Option.Some(5)
const result = some.isSomeAnd(value => value > 3) // true
const none = Option.None<number>()
const result2 = none.isSomeAnd(value => value > 3) // false
Copy

Returns true if and only if the current instance is Some and the value does not fulfill the given predicate.

This is the options equivalent to do something like the following but in the world of optionals.

if (a && !myCondition(a)) {
  //...
}
Copy

Example

const some = Option.Some(5)
const result = some.isSomeBut(value => value > 3) // false
const none = Option.None<number>()
const result2 = none.isSomeBut(value => value > 3) // false
Copy

Transforms the value contained in the Option instance using the provided mapping function. If the Option instance does not contain a value (None), it returns a new Option without a value. If the Option instance contains a value (Some), it applies the mapping function to the value and returns a new option with the mapped value.

Example

const some = Option.Some(5)
const newSome = some.map(value => value * 2) // Some(10)
const none = Option.None<number>()
const newNone = none.map(value => value * 2) // None
Copy

Returns the value inside the optional after applying the given transformation. If the optional is empty it returns the default value

Example

const some = Option.Some(5)
const result = some.mapOr(0, value => value * 2) // 10
const none = Option.None<number>()
const result2 = none.mapOr(0, value => value * 2) // 0
Copy

Returns the value inside the optional after applying the given transformation. If the optional is empty it execs the generator function and returns the result of it.

The generator function is not called if there is a value.

Example

const some = Option.Some(5)
const result = some.mapOrElse(() => 0, value => value * 2) // 10
const none = Option.None<number>()
const result2 = none.mapOrElse(() => 0, value => value * 2) // 0
Copy

Returns a new Option instance that is only present if any of the instances (this, and the argument) are present. If this is present it returns the value contained in this. Otherwise returns the value contained in the argument

This operation behaves similar to the || but adapted from booleans to options.

Example

const some = Option.Some('foo')
const another = Option.Some('bar')
const result = some.or(another) // Some('foo')
const none = Option.None()
const result2 = none.or(another) // Some('bar')
const result3 = some.or(none) // Some('foo')
const result4 = none.or(none) // None
Copy

Similar to or but allowing to generate the second option lazily. The generator fn will only be called if needed.

Example

const some = Option.Some('foo')
const result = some.orElse(() => Option.Some('bar')) // Some('foo')
const none = Option.None()
const result2 = none.orElse(() => Option.Some('bar')) // Some('bar')
const result3 = none.orElse(() => Option.None()) // None
Copy

Replaces the contained value of an option with the one provided as argument.

Example

const opt1 = Option.Some('foo')
const oldSome = opt1.replace('bar') // Some('foo')
opt1.unwrap() // 'bar'
const opt2 = Option.None()
const oldNone = opt2.replace('foo') // None
opt2.unwrap() // 'foo'
Copy

Takes the value inside the instance and returned inside a new Option.

If the instance is Some, it gets transformed into None

If the instance is None, it gets unnafected and theresult is None.

Example

const opt1 = Option.Some('foo')
const taken = opt1.take() // Some('foo')
opt1.isNone() // true
const none = Option.None()
const takenFromNone = none.take() // None
none.isNone() // true
Copy

If the instance is None returns None. If the value inside the instnace pass the predicate, the instance gets transformed to None and the value is returned

Example

const opt1 = Option.Some(5)
const result1 = opt1.takeIf(value => value > 3) // Some(5)
opt1.isNone() // true
const opt2 = Option.Some(2)
const result2 = opt2.takeIf(value => value > 3) // Some(5)
opt2.isSome() // true
opt2.unwrap() // 2
const opt3 = Option.None<number>()
const result3 = opt3.takeIf(value => value > 3) // None
opt3.isNone() // true
Copy

Converts the Option instance to an array. If the instance is None it returns an empty array If the instance is Some it returns an array of size 1 containing the value.

Example

const some = Option.Some('foo')
some.toArray() // ['foo']
const none = Option.None()
none.toArray() // []
Copy

Unwraps the value contained in the Option instance. If the Option instance does not contain a value (None), it throws an error. If the Option instance contains a value (Some), it returns the value.

This method is better suited for testing or inspection. Use it with care. There are safer alternatives to this operation like unwrapOr, unwrapOrElse, getOrInsert, getOrInsertWith, take or takeIf.

If the desire is throw an error in case of a missing value, expect it's a better alternative that allows for more expressive errors.

Throws

If the Option instance does not contain a value.

Example

const some = Option.Some('foo')
some.unwrap() // 'foo'
const none = Option.None()
none.unwrap() // throws Error
Copy

Unwraps the value contained in the Option instance or returns a default value if the Option instance does not contain a value. This is a safer alternative to unwrap where the normal flow of the program can be ensured.

Example

const some = Option.Some('foo')
some.unwrapOr('bar') // 'foo'
const none = Option.None()
none.unwrapOr('bar') // 'bar'
Copy

Returns the contained value. If there is no value it executes the provided function and returns the result of that. This is a safer alternative to plain unwrap that ensures that the flow of the program can continue in case there is a missing value.

Example

const some = Option.Some('foo')
some.unwrapOrElse(() => 'bar') // 'foo'
const none = Option.None()
none.unwrapOrElse(() => 'bar') // 'bar'
Copy

Returns a new Option instance that is only present if exactly one of the instances (this, and the argument) are present. The value is the value of the present optional or None if both are None.

This operation behaves similar to the xor (exclusive or) operation but adapted from booleans to options.

Example

const some = Option.Some('foo')
const another = Option.Some('bar')
const result = some.xor(another) // None
const none = Option.None()
const result2 = none.xor(another) // Some('bar')
const result3 = some.xor(none) // Some('foo')
const result4 = none.xor(none) // None
Copy

Combines 2 options into an option with a tuple of size 2 inside. In case tha any of the options (this, or the argument) is none, the result is going to be none.

Example

const some1 = Option.Some('foo')
const some2 = Option.Some(5)
const result = some1.zip(some2) // Some(['foo', 5])
const none = Option.None()
const result2 = some1.zip(none) // None
Copy

Combines 2 options and then applies a transformation. The result is an option types as the result of the transformation. If any of the original options is empty the result will be empty.

Example

const some1 = Option.Some('foo')
const some2 = Option.Some(5)
const result = some1.zipWith(some2, (a, b) => a + b) // Some('foo5')
const none = Option.None()
const result2 = some1.zipWith(none, (a, b) => a + b) // None
Copy

Creates an empty optional value (represents no value).

Example

const none = Option.None()
none.isNone() // true
Copy

Creates an instance of Option with a value. (Some)

Example

const some = Option.Some('foo')
some.unwrap() === 'foo' // true
Copy

Creates an instance of Option from a nullable value. If the provided value is null or undefined, it returns an Option without a value (None). Otherwise, it wraps the provided value in an Option (Some).

Example

const nullable: string | null = null
const maybe = Option.fromNullable(nullable) // None
const nullable2: string | null = 'foo'
const maybe2 = Option.fromNullable(nullable2) // Some('foo')
Copy