Latest
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359import type * as HKT from "./hkt.ts";import type * as TC from "./type_classes.ts";import type { Lazy, Predicate } from "./types.ts";
import { createSequenceStruct, createSequenceTuple } from "./sequence.ts";import { flow, identity, isNotNil, pipe } from "./fns.ts";import { createDo } from "./derivations.ts";
/******************************************************************************* * Types ******************************************************************************/
/** * The None type represents the non-existence of a value. */export type None = { tag: "None" };
/** * The Some type represents the existence of a value. */export type Some<V> = { tag: "Some"; value: V };
/** * The Option<A> represents a type A that may or may not exist. It's the functional * progamming equivalent of A | undefined | null. */export type Option<A> = Some<A> | None;
/******************************************************************************* * Kind Registration ******************************************************************************/
export const URI = "Option";
export type URI = typeof URI;
declare module "./hkt.ts" { // deno-lint-ignore no-explicit-any export interface Kinds<_ extends any[]> { [URI]: Option<_[0]>; }}
/******************************************************************************* * Constructors ******************************************************************************/
/** * The cannonical implementation of the None type. Since all None values are equivalent there * is no reason to construct more than one object instance. */export const none: Option<never> = { tag: "None" };
/** * The some constructer takes any value and wraps it in the Some type. */export const some = <A>(value: A): Option<A> => ({ tag: "Some", value });
/** * constNone is a thunk that returns the canonical none instance. */export const constNone = <A = never>(): Option<A> => none;
/** * fromNullable takes a potentially null or undefined value and maps null or undefined to * None and non-null and non-undefined values to Some<NonNullable<A>> * * @example * const a: number | undefined = undefined; * const b: number | undefined = 2; * const optionNumber = fromNullable(a); // None * const optionNumber = fromNullable(b); // Some<number> * const numberArray = [1, 2, 3]; * const optionFourthEntry = fromNullable(numberArray[3]); // None */export const fromNullable = <A>(a: A): Option<NonNullable<A>> => isNotNil(a) ? some(a) : none;
/** * fromPredicate will test the value a with the predicate. If * the predicate evaluates to false then the function will return a None, * otherwise the value wrapped in Some * * @example * const fromPositiveNumber = fromPredicate((n: number) => n > 0); * const a = fromPositiveNumber(-1); // None * const a = fromPositiveNumber(1); // Some<number> */export const fromPredicate = <A>(predicate: Predicate<A>) => ( a: A, ): Option<A> => (predicate(a) ? some(a) : none);
/** * tryCatch takes a thunk that can potentially throw and wraps it * in a try/catch statement. If the thunk throws then tryCatch returns * None, otherwise it returns the result of the thunk wrapped in a Some. */export const tryCatch = <A>(f: Lazy<A>): Option<A> => { try { return some(f()); } catch (e) { return none; }};
/******************************************************************************* * Destructors ******************************************************************************/
/** * fold is the standard catamorphism on an Option<A>. It operates like a switch case * operator over the two potential cases for an Option type. One supplies functions for * handling the Some case and the None case with matching return types and fold calls * the correct function for the given option. * * @example * const toNumber = fold((a: number) => a, () => 0); * const a = toNumber(some(1)); // 1 * const b = toNumber(none); // 0 */export const fold = <A, B>(onNone: () => B, onSome: (a: A) => B) => (ta: Option<A>): B => (isNone(ta) ? onNone() : onSome(ta.value));
/** * getOrElse operates like a simplified fold. One supplies a thunk that returns a default * inner value of the Option for the cases where the option is None. * * @example * const toNumber = getOrElse(() => 0); * const a = toNumber(some(1)); // 1 * const b = toNumber(none); // 0 */export const getOrElse = <B>(onNone: () => B) => (ta: Option<B>): B => isNone(ta) ? onNone() : ta.value;
/** * toNullable returns either null or the inner value of an Option. This is useful for * interacting with code that handles null but has no concept of the Option type. */export const toNull = <A>(ma: Option<A>): A | null => isNone(ma) ? null : ma.value;
/** * toUndefined returns either undefined or the inner value of an Option. This is useful for * interacting with code that handles undefined but has no concept of the Option type. */export const toUndefined = <A>(ma: Option<A>): A | undefined => isNone(ma) ? undefined : ma.value;
/******************************************************************************* * Combinators ******************************************************************************/
/** * mapNullable is useful for piping an option's values through functions that may return * null or undefined. * * @example * const a = pipe( * some([1, 2, 3]), * mapNullable(numbers => numbers[3]) * ); // None (Option<number>) */export const mapNullable = <A, B>(f: (a: A) => B | null | undefined) => ( ma: Option<A>, ): Option<B> => (isNone(ma) ? none : fromNullable(f(ma.value)));
/******************************************************************************* * Guards ******************************************************************************/
/** * Tests wether an Option is None. Can be used as a predicate. */export const isNone = <A>(m: Option<A>): m is None => m.tag === "None";
/** * Tests wether an Option is Some. Can be used as a predicate. */export const isSome = <A>(m: Option<A>): m is Some<A> => m.tag === "Some";
/******************************************************************************* * Modules ******************************************************************************/
export const Functor: TC.Functor<URI> = { map: (fab) => (ta) => isNone(ta) ? ta : some(fab(ta.value)),};
export const Apply: TC.Apply<URI> = { ap: (tfab) => (ta) => isNone(tfab) || isNone(ta) ? none : some(tfab.value(ta.value)), map: Functor.map,};
export const Applicative: TC.Applicative<URI> = { of: some, ap: Apply.ap, map: Functor.map,};
export const Chain: TC.Chain<URI> = { ap: Apply.ap, map: Functor.map, chain: (fatb) => (ta) => (isSome(ta) ? fatb(ta.value) : ta),};
export const Monad: TC.Monad<URI> = { of: Applicative.of, ap: Apply.ap, map: Functor.map, join: Chain.chain(identity), chain: Chain.chain,};
export const MonadThrow: TC.MonadThrow<URI> = { of: Applicative.of, ap: Apply.ap, map: Functor.map, join: Chain.chain(identity), chain: Chain.chain, throwError: constNone,};
export const Alt: TC.Alt<URI> = { map: Functor.map, alt: (tb) => (ta) => (isNone(ta) ? tb : ta),};
export const Alternative: TC.Alternative<URI> = { of: Applicative.of, ap: Apply.ap, map: Functor.map, alt: Alt.alt, zero: constNone,};
export const Extends: TC.Extend<URI> = { map: Monad.map, extend: (ftab) => flow(ftab, some),};
export const Filterable: TC.Filterable<URI> = { filter: (predicate) => (ta) => isNone(ta) ? ta : predicate(ta.value) ? ta : none,};
export const Foldable: TC.Foldable<URI> = { reduce: (faba, a) => (tb) => (isSome(tb) ? faba(a, tb.value) : a),};
export const Plus: TC.Plus<URI> = { alt: Alt.alt, map: Monad.map, zero: constNone,};
export const Traversable: TC.Traversable<URI> = { map: Functor.map, reduce: Foldable.reduce, traverse: (A) => (favi) => (ta) => isNone(ta) ? A.of(constNone()) : pipe(favi(ta.value), A.map(some)),};
/******************************************************************************* * Module Getters ******************************************************************************/
/** * Generates a Show module for an option with inner type of A. * * @example * const Show = getShow({ show: (n: number) => n.toString() }); // Show<Option<number>> * const a = Show.show(some(1)); // "Some(1)" * const b = Show.show(none); // "None" */export const getShow = <A>({ show }: TC.Show<A>): TC.Show<Option<A>> => ({ show: (ma) => (isNone(ma) ? "None" : `${"Some"}(${show(ma.value)})`),});
/** * Generates a Setoid module for an option with inner type of A. * * @example * const Setoid = getSetoid({ equals: (a: number, b: number) => a === b }); * const a = Setoid.equals(some(1), some(2)); // false * const b = Setoid.equals(some(1), some(1)); // true * const c = Setoid.equals(none, none); // true * const d = Setoid.equals(some(1), none); // false */export const getSetoid = <A>(S: TC.Setoid<A>): TC.Setoid<Option<A>> => ({ equals: (a) => (b) => a === b || ((isSome(a) && isSome(b)) ? S.equals(a.value)(b.value) : (isNone(a) && isNone(b))),});
export const getOrd = <A>(O: TC.Ord<A>): TC.Ord<Option<A>> => ({ ...getSetoid(O), lte: (a) => (b) => { if (a === b) { return true; } if (isNone(a)) { return true; } if (isNone(b)) { return false; } return O.lte(a.value)(b.value); },});
export const getSemigroup = <A>( S: TC.Semigroup<A>,): TC.Semigroup<Option<A>> => ({ concat: (x) => (y) => isNone(x) ? y : isNone(y) ? x : of(S.concat(x.value)(y.value)),});
export const getMonoid = <A>(M: TC.Monoid<A>): TC.Monoid<Option<A>> => ({ ...getSemigroup(M), empty: constNone,});
/******************************************************************************* * Pipeables ******************************************************************************/
export const { of, ap, map, join, chain } = Monad;
export const { reduce, traverse } = Traversable;
export const { zero, alt } = Alternative;
export const { filter } = Filterable;
export const { extend } = Extends;
export const sequenceTuple = createSequenceTuple(Apply);
export const sequenceStruct = createSequenceStruct(Apply);
export const exists = <A>(predicate: Predicate<A>) => (ta: Option<A>): boolean => isSome(ta) && predicate(ta.value);
/******************************************************************************* * Do ******************************************************************************/
export const { Do, bind, bindTo } = createDo(Monad);