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
Readonly @@typePrivate _valuefalse 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); };
Static fromSerializes Opt to a plain JavaScript object.
Static deserializeDeserializes Opt from a plain JavaScript object.
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])
Combination 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)
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
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
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.
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
Get 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'
A 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
Returns 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
Maps 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 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
Returns 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
some(1).someOrCrash('fail') // Some(1)
none.someOrCrash('fail') // throws
none.someOrCrash(() => new Error('fail')) // throws Error('fail')
Applies appropriate function and returns result from the function.
some(1).caseOf(x => x + 1, () => 0) // 2
none.caseOf(x => x + 1, () => 0) // 0
Reduces 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
Calls 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'))
Compares 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.
Checks if an array inside the Opt contains the given element.
Element to search for.
Checks 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
Checks 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
none.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"
const 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"
Less 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
some(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) // ''
Filters 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])
Zips 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
Counts 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
Narrows 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>
Similar to Opt.narrow, but crashes on a narrowing failure.
Optional _crashMessage: stringOptional _errorFactory: (() => unknown)Is a value of this instance and given other instance the same?
Default comparator function is === (referential equality).
none.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)
Get 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')
Generated using TypeDoc
Opt with a value inside.
Not Exported
See
Opt