Abstract Static fromConverts an object to Opt.
Opt.fromObject({value: 4}) // Some(4)
Opt.fromObject({id: 4, something: '?'}, 'id') // Some(4)
Opt.fromObject({value: null}) // None
Converts Opt to an object.
opt(1).toObject() // {value: 1}
opt(undefined).toObject() // {value: null}
opt(undefined).toObject('id') // {id: null}
Similar to Opt.map, but supports more functions which are called in succession, each on a result of a previous one.
const sq = (x: number) => x * x;
const dec = (x: number) => x - 1;
opt(4).mapFlow(sq, dec) // Some(15)
opt(null).mapFlow(sq, dec) // None
Similar to Opt.chain (in other languages called bind or >>=), but supports more functions passed at once (resembles do notation in Haskell).
It is used to model a sequence of operations where each operation can fail (can return None).
// does addition when first argument is number
const f1 =
(x: string | number) => (y: number) => opt(x).narrow(isNumber).map(z => z + y);
// passes only even numbers
const f2 = (x: number): Opt<number> => x % 2 === 0 ? opt(x) : none;
opt(0).act( // Some(0)
f1(-2), // Some(-2)
f2, // Some(-2)
optNegative, // None
); // None
opt(0).act( // Some(0)
f1(1), // Some(1)
f2, // None
optNegative, // won't get called, still None
); // None
opt(3).act( // Some(3)
f1(1), // Some(4)
f2, // Some(4)
optNegative, // Some(4)
); // Some(4)
Similar to act, but functions return empty values instead of Opt.
It is useful for typical JavaScript functions (e.g. lodash), properly handles undefined/null/NaN at any point of the chain.
import {find} from 'lodash/fp';
const data = [{}, {f: true, a: [{b: 7, c: 1}]}, {a: [{}]}];
opt(data).actToOpt(
find(x => Boolean(x?.f)), // {f: true, a: [{b: 7, c: 1}]}
x => x?.a, // [{b: 7, c: 1}]
find(x => x.b === 8) // undefined
); // None
Applies passed function to this instance and returns function result.
Also known as a reverse function application, |> (Reason/ReScript, F#, OCaml), & (Haskell), # (PureScript) or a pipe operator.
some(1).pipe(x => x.isEmpty) // false
none.pipe(x => x.isEmpty) // true
Supports multiple functions.
opt(1).pipe( // Some(1)
x => x.isEmpty, // false
x => !x, // true
) // true
Functions in call chain
Constructs a function which returns a value for Some or an empty value for None (default is null).
Optionally takes an empty value as a parameter.
opt(1).const()() // 1
opt(undefined).const()() // null
// custom empty value
opt(NaN).const(undefined)() // undefined
Abstract isfalse for Some, true for None.
If you need to narrow a type to Some, use Opt.isSome.
Important: This is not the wrapped value's length.
E.g., opt([1,2,3]).length === 1.
Use Opt.lengthIn for array/string length of the wrapped value.
No-op terminator used to end imperative chains.
const f = (x: unknown): void => opt(x).onBoth(noop, noop).end;
// same as
const g = (x: unknown): void => { opt(x).onBoth(noop, noop); };
Abstract lengthReturns the length of a string or array wrapped in an Opt.
opt('hello').lengthIn() // Some(5)
opt([1, 2, 3]).lengthIn() // Some(3)
opt('').lengthIn() // Some(0)
opt([]).lengthIn() // Some(0)
none.lengthIn() // None
Static fromAbstract toSerializes Opt to a plain JavaScript object.
Static deserializeDeserializes Opt from a plain JavaScript object.
Abstract mapAbstract mapAbstract mapMaps over an array inside the Opt with index.
opt(['a', 'b']).mapWithIndexIn((x, i) => x + i) // Some(['a0', 'b1'])
none.mapWithIndexIn((x, i) => x + i) // None
Maps over a property of objects in an array inside the Opt, discarding nulls and undefined values.
opt([{data: 1}, {}, {data: 2}, null]).mapPropNakedIn('data') // Some([1, 2])
Abstract mapMaps over characters in a string wrapped in an Opt.
opt('hello').mapStr(c => c.toUpperCase()) // Some('HELLO')
opt('').mapStr(c => c.toUpperCase()) // Some('')
none.mapStr(c => c.toUpperCase()) // None
Abstract flatAbstract flatCombination of Opt.flatMap and opt functions.
some(1).chainToOpt(x => x === 1 ? null : x + 1) // None
some(2).chainToOpt(x => x === 1 ? null : x + 1) // Some(3)
Joins (flattens) nested Opt instance, turning an Opt<Opt<T>> into an Opt<T>.
This is equivalent to calling flatMap with the identity function: .join() ~ .flatMap(id).
const nestedOpt: Opt<Opt<number>> = opt(opt(42)); // Some(Some(42))
const flattenedOpt: Opt<number> = nestedOpt.join(); // Some(42)
Abstract orReturns value when Some, throws error otherwise.
Error message.
opt(null).orCrash('unexpected empty value') // crashes with Error('unexpected empty value')
opt(1).orCrash('unexpected empty value') // 1
opt(null).orCrash(() => new CustomException()) // crashes with CustomException
Abstract somesome(1).someOrCrash('fail') // Some(1)
none.someOrCrash('fail') // throws
none.someOrCrash(() => new Error('fail')) // throws Error('fail')
Abstract orAbstract orAbstract orAbstract orAbstract orAbstract caseApplies appropriate function and returns result from the function.
some(1).caseOf(x => x + 1, () => 0) // 2
none.caseOf(x => x + 1, () => 0) // 0
Abstract foldReduces the Opt instance to a single value by applying a function to the value inside Some
or returning a default value for None.
Function to apply to the value inside Some.
Default value to return for None.
opt(1).fold(x => x + 1, 0) // 2
none.fold(x => x + 1, 0) // 0
Applies a reducer function to an array within an Opt instance,
combining its elements into a single value using the array's reduce method.
opt([1, 2, 3]).foldIn((acc, x) => acc + x, 0) // Some(6)
none.foldIn((acc, x) => acc + x, 0) // None
Abstract onCalls appropriate callback and returns without change current instance of Opt.
// prints 1, returns some(1)
some(1).onBoth(x => console.log(x), () => console.log('none'))
// prints "none", returns none
none.onBoth(x => console.log(x), () => console.log('none'))
Abstract onAbstract onAbstract containsCompares inner value with given value using ===. Always false for None.
some(1).contains(1) // true
some(0).contains(1) // false
none.contains(undefined) // false
Similar to JavaScript Array#includes method.
Abstract hasChecks if an array inside the Opt contains the given element.
Element to search for.
Checks if the value inside the Opt is an element of the given array. Flipped version of Opt.hasIn.
The array to check against
true if the value is in the array, false otherwise
opt(1).elemOfIn([1, 2, 3]) // true
opt(4).elemOfIn([1, 2, 3]) // false
none.elemOfIn([1, 2, 3]) // false
opt('cow').elemOfIn(['dog', 'cow', 'pig']) // true
opt('cat').elemOfIn(['dog', 'cow', 'pig']) // false
none.elemOfIn(['dog', 'cow', 'pig']) // false
Checks if the string value inside this Opt is a substring of the given string.
The string to search in
true if the value is a substring of the haystack, false otherwise
opt('ab').elemOfStrIn('abc') // true
opt('a').elemOfStrIn('def') // false
none.elemOfStrIn('abc') // false
Abstract existsAbstract existsChecks if any element in the array inside the Opt satisfies the predicate.
Similar to Array.some from JavaScript.
opt([1]).existsIn(x => x > 0) // Some(true)
opt([-1]).existsIn(x => x > 0) // Some(false)
opt([]).existsIn(x => x > 0) // Some(false)
none.existsIn(x => x > 0) // None
Abstract forAbstract forChecks if all elements in the array inside the Opt satisfy the predicate.
Similar to Array.every from JavaScript.
opt([1]).forAllIn(x => x > 0) // Some(true)
opt([-1]).forAllIn(x => x > 0) // Some(false)
opt([]).forAllIn(x => x > 0) // Some(true)
none.forAllIn(x => x > 0) // None
Abstract orAbstract orAbstract orLess strict version of orElse.
opt(1).orElse(true); // TS2345: Argument of type 'boolean' is not assignable to parameter of type 'number'.
opt(1).orElseAny(true) // 1 :: number | boolean
Abstract altnone.alt(some(0)) // Some(0)
opt(1).alt(some(0)) // Some(1)
none.alt(none) // None
some(1).alt(none) // Some(1)
It can be used to pick first from given possibly missing alternatives.
type Handler = (_: number) => void;
const userHandler: Opt<Handler> = opt(a => console.log('user handling', a));
const systemHandler: Opt<Handler> = opt(a => console.log('system handling', a));
const backupHandler: Opt<Handler> = opt(a => console.log('backup handling', a));
const panicHandler: Handler = a => console.log('PANIC handling', a);
const handler =
userHandler
.alt(systemHandler)
.alt(backupHandler)
.orElse(panicHandler);
handler(250 + 64); // prints "user handling 314"
Abstract altconst inputNull: number | null = null as number | null;
opt(inputNull).altOpt(null) // None
opt(inputNull).altOpt(1) // Some(1)
opt(2).altOpt(1) // Some(2)
type Handler = (_: number) => void;
const userHandler: Handler | null = a => console.log('user handling', a);
const systemHandler: Handler | null = a => console.log('system handling', a);
const backupHandler: Handler | null = a => console.log('backup handling', a);
const panicHandler: Handler = a => console.log('PANIC handling', a);
const handler =
opt(userHandler)
.altOpt(systemHandler)
.altOpt(backupHandler)
.orElse(panicHandler);
handler(250 + 64); // prints "user handling 314"
Abstract bimapAbstract flatAbstract toAbstract zipsome(1).zip(some(true)) // Some([1, true])
some(1).zip(none) // None
none.zip(some(1)) // None
none.zip(none) // None
const formatAddress =
(streetName?: string, streetNumber?: number): string =>
opt(streetName).zip(opt(streetNumber)).map(join(' ')).orElse('');
formatAddress('Strawberry', '12') // 'Strawberry 12'
formatAddress('Strawberry', undefined) // ''
formatAddress(undefined, '12') // ''
formatAddress(undefined, undefined) // ''
Abstract zip3Abstract zip4Abstract zip5Abstract zipZips each element of an array inside the Opt with the corresponding element from another array. If the arrays are of different lengths, the resulting array will have the length of the shorter one.
opt([1, 2]).zipIn([3, 4]) // Some([[1, 3], [2, 4]])
opt([1, 2]).zipIn(null) // None
none.zipIn([1, 2]) // None
Abstract filterAbstract filterFilters each element of an array inside the Opt, returning an Opt of the array with elements that pass the test implemented by the provided function.
opt([1, 2, 3]).filterIn(x => x > 1) // Some([2, 3])
Filter by regular expression. It is a shortcut function for Opt.filter + testRe.
opt('Luffy').filterByRe(/f+/) // Some('Luffy')
opt('Robin').filterByRe(/f+/) // None
Searches for an element within an array inside the Opt instance that matches the given predicate.
This method will return a new Opt containing the first element that satisfies the predicate function. If the Opt instance is None or the value inside is not an array, it will return None.
The type of elements in the array.
The Opt instance containing an array.
A predicate function to test each element.
A new Opt containing the found element or None if no element matches the predicate or if the Opt is None.
opt([1, 2, 3, 4]).findIn(x => x > 2) // Some(3)
opt([1, 2, 3, 4]).findIn(x => x > 5) // None
none.findIn(x => x > 2) // None
opt('x').noneIfEmpty() // Some('x')
opt('').noneIfEmpty() // None
opt([]).noneIfEmpty() // None
opt({}).noneIfEmpty() // None
Returns 0 or 1 for Some depending on whether the predicate holds.
Returns 0 for None.
It is a combination of Opt.filter and Opt.length.
Abstract countCounts the number of elements in the array inside the Opt that satisfy the predicate.
The predicate function to test each element.
An Opt containing the count of elements that satisfy the predicate, or None if the Opt is None.
opt([1, 2, 3]).countIn(x => x > 1) // Some(2)
opt([]).countIn(x => x > 1) // Some(0)
none.countIn(x => x > 1) // None
Abstract narrowNarrows type inside Opt using given type guard.
some('1' as string | number).narrow(isString) // Some('1'): Opt<string>
some(1 as string | number).narrow(isString) // None: Opt<string>
Abstract narrowSimilar to Opt.narrow, but crashes on a narrowing failure.
Optional errorFactory: (() => unknown)Optional crashMessage: stringAbstract printAbstract equalsIs a value of this instance and given other instance the same?
Default comparator function is === (referential equality).
Optional comparator: EqualityFunctionnone.equals(none) // true
some(1).equals(none) // false
some(1).equals(some(1)) // true
some(1).equals(some(2)) // false
some({a: 1}).equals(some({a: 1})) // false (different objects)
some(1).equals(some(2), (x, y) => true) // true (custom comparator function)
const jsonCmp = <T>(a: T, b: T): boolean => JSON.stringify(a) === JSON.stringify(b);
some({a: 1}).equals(some({a: 1}), jsonCmp) // true (comparing values converted to JSON)
Experimental Widen union (typically union of strings to string).
May be removed if it is later found out it's unsafe and unfixable.
type EnumAB = 'a' | 'b';
type EnumABC = 'a' | 'b' | 'c';
const ab = 'a' as EnumAB;
const abc = 'c' as EnumABC;
const correctWiden: Opt<EnumABC> = opt(ab).widen<EnumABC>(); // AB -> ABC: Ok
const wrongWiden: Opt<never> = opt(abc).widen<EnumAB>(); // ABC -> AB: Not Ok, C is not in AB
Abstract propGet a field from a wrapped object. Crash if the field is missing or empty, or opt instance is None. Shortcut of Opt.prop + Opt.orCrash.
Optional errorFactory: string | ((key) => string | Error)interface A {x?: number;}
const aFull: A = {x: 4};
opt(aFull).propOrCrash('x'); // 4
const aEmpty: A = {};
opt(aEmpty).propOrCrash('x'); // crash
// with custom error: "Custom error: x is missing"
opt(aEmpty).propOrCrash('x', 'Custom error: x is missing'); // crash
opt(aEmpty).propOrCrash('x', key => `Custom error: ${key} is missing`); // crash
opt(aEmpty).propOrCrash('x', key => new Error(`Custom error: ${key} is missing`)); // crash
Get a field from a wrapped object. Return null if the field is missing or empty, or opt instance is None.
interface A {x?: number;}
const aFull: A = {x: 4};
opt(aFull).propOrNull('x'); // 4
const aEmpty: A = {};
opt(aEmpty).propOrNull('x'); // null
Get a field from a wrapped object. Return undefined if the field is missing or empty, or opt instance is None.
interface A {x?: number;}
const aFull: A = {x: 4};
opt(aFull).propOrUndef('x'); // 4
const aEmpty: A = {};
opt(aEmpty).propOrUndef('x'); // undefined
Get a field from a wrapped object. Return 0 if the field is missing or empty, or opt instance is None.
interface A {x?: number;}
const aFull: A = {x: 4};
opt(aFull).propOrZero('x'); // 4
const aEmpty: A = {};
opt(aEmpty).propOrZero('x'); // 0
Generates property getters for an Opt
An object with property getter methods
interface Obj { x: number; y: string; z?: number; }
const obj = opt<Obj>({ x: 1, y: 'hello' });
const getters = obj.genPropGetters();
getters.orCrash('x') // 1
getters.orNull('y') // 'hello'
getters.orUndef('z') // undefined
getters.orZero('x') // 1
// with custom error
const gettersWithCustomError = obj.genPropGetters(key => `Custom error: ${key} is missing`);
gettersWithCustomError.orCrash('z') // crashes with 'Custom error: z is missing'
gettersWithCustomError.orCrash('z', 'nope, no z') // crashes with 'nope, no z'
Abstract swapAbstract atGet an item at given index of an array/string wrapped in Opt.
Resulting value is wrapped in Opt.
Non-existent index results in None.
Negative index is interpreted as an index from the end of the array (e.g. a last item of an array lies on an index equal to -1).
opt([1]).at(0) // Some(1)
opt([]).at(0) // None
none.at(0) // None
opt([null]).at(0) // None
opt([1, 2, 3]).at(-1) // Some(3)
opt('Palico').at(0) // Some('P')
Abstract minAbstract maxA convenience function to test this (Opt<string>) against a given regular expression.
Regular expression
Rest ...args: AParameters passed to wrapped function.
opt-wrapped result from the function
const add = (a: number, b: number) => a + b;
opt(add).apply(2, 3) // Some(5)
none.apply(0) // None
It can also be used with curried functions.
const sub = (a: number) => (b: number) => a - b;
opt(sub).apply(10).apply(3) // Some(7)
Opt.apply is only available for functions, otherwise an exception will be thrown when called on Some.
Opt.onFunc for imperative version
Rest ...args: AUnchanged Opt instance
Both lines do the same thing
opt(f).onSome(x => x())
opt(f).onFunc()
const g = (a: number, b: number): void => console.log(a, b);
opt(g).onFunc(1, 2) // calls `g` (prints 1 and 2), returns Some(g)
none.onFunc(79) // None
onFunc is only available for functions, otherwise an exception will be thrown when called on Some.
Opt.apply for functional version
Generated using TypeDoc
Generic container class. It either holds exactly one value - Some, or no value - None (empty).
It simplifies working with possibly empty values and provides many methods/functions which allow creation of processing pipelines (commonly known as "fluent API" in OOP or chain of reverse applications in FP).
Typeparam
T Wrapped value type.