fp-ts-std/dist/types/Option.d.ts

The missing pseudo-standard library for fp-ts.

/**
 * Utility functions to accommodate `fp-ts/Option`.
 *
 * @since 0.1.0
 */
import type { Endomorphism } from "fp-ts/Endomorphism";
import type { Eq } from "fp-ts/Eq";
import type { Option } from "fp-ts/Option";
import * as O from "fp-ts/Option";
import * as L from "./Lazy";
type Lazy<A> = L.Lazy<A>;
import type { Bounded } from "fp-ts/Bounded";
import type { Enum } from "./Enum";
/**
 * Unwrap the value from within an `Option`, throwing `msg` if `None`.
 *
 * @example
 * import { unsafeExpect } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 *
 * assert.throws(
 *   () => unsafeExpect('foo')(O.none),
 *   Error('Unwrapped `None`', { cause: Error('foo') }),
 * )
 *
 * @category 3 Functions
 * @since 0.16.0
 */
export declare const unsafeExpect: (msg: string) => <A>(x: Option<A>) => A;
/**
 * Unwrap the value from within an `Option`, throwing if `None`.
 *
 * @example
 * import { unsafeUnwrap } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 *
 * assert.deepStrictEqual(unsafeUnwrap(O.some(5)), 5)
 *
 * @category 3 Functions
 * @since 0.1.0
 */
export declare const unsafeUnwrap: <A>(x: Option<A>) => A;
/**
 * A thunked `None` constructor. Enables specifying the type of the `Option`
 * without a type assertion. Helpful in certain circumstances in which type
 * inferrence isn't smart enough to unify with the `Option<never>` of the
 * standard `None` constructor.
 *
 * @example
 * import { noneAs } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 *
 * assert.deepStrictEqual(noneAs<any>(), O.none)
 *
 * @category 3 Functions
 * @since 0.12.0
 */
export declare const noneAs: <A>() => Option<A>;
/**
 * Given an unwrapped value and an associated `Eq` instance for determining
 * equivalence, inverts an `Option` that may contain the same value, something
 * else, or nothing.
 *
 * This can be useful for circumstances in which you want to in a sense toggle
 * an `Option` value.
 *
 * @example
 * import { invert } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 * import * as S from 'fp-ts/string'
 *
 * const f = invert(S.Eq)('x')
 *
 * assert.deepStrictEqual(f(O.none), O.some('x'))
 * assert.deepStrictEqual(f(O.some('y')), O.some('x'))
 * assert.deepStrictEqual(f(O.some('x')), O.none)
 *
 * @category 3 Functions
 * @since 0.12.0
 */
export declare const invert: <A>(eq: Eq<A>) => (val: A) => Endomorphism<Option<A>>;
/**
 * Extracts monoidal identity if `None`.
 *
 * @example
 * import { toMonoid } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 * import * as Str from 'fp-ts/string'
 *
 * const f = toMonoid(Str.Monoid)
 *
 * assert.deepStrictEqual(f(O.some('x')), 'x')
 * assert.deepStrictEqual(f(O.none), '')
 *
 * @category 2 Typeclass Methods
 * @since 0.12.0
 */
export declare const toMonoid: <A>(G: import("fp-ts/lib/Monoid").Monoid<A>) => (x: Option<A>) => A;
/**
 * Conditionally returns the provided `Option` or `None`. The dual to
 * `memptyUnless`. The lazy value is evaluated only if the condition passes.
 *
 * @example
 * import { constant } from 'fp-ts/function'
 * import { memptyWhen } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 *
 * assert.deepStrictEqual(memptyWhen(true)(constant(O.some('x'))), O.none)
 * assert.deepStrictEqual(memptyWhen(true)(constant(O.none)), O.none)
 * assert.deepStrictEqual(memptyWhen(false)(constant(O.some('x'))), O.some('x'))
 * assert.deepStrictEqual(memptyWhen(false)(constant(O.none)), O.none)
 *
 * @category 2 Typeclass Methods
 * @since 0.13.0
 */
export declare const memptyWhen: (x: boolean) => <A>(m: Lazy<Option<A>>) => Option<A>;
/**
 * Conditionally returns the provided `Option` or `None`. The dual to
 * `memptyWhen`. The lazy value is evaluated only if the condition passes.
 *
 * @example
 * import { constant } from 'fp-ts/function'
 * import { memptyUnless } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 *
 * assert.deepStrictEqual(memptyUnless(true)(constant(O.some('x'))), O.some('x'))
 * assert.deepStrictEqual(memptyUnless(true)(constant(O.none)), O.none)
 * assert.deepStrictEqual(memptyUnless(false)(constant(O.some('x'))), O.none)
 * assert.deepStrictEqual(memptyUnless(false)(constant(O.none)), O.none)
 *
 * @category 2 Typeclass Methods
 * @since 0.13.0
 */
export declare const memptyUnless: (x: boolean) => <A>(m: Lazy<Option<A>>) => Option<A>;
/**
 * Conditionally lifts a value to `Some` or returns `None`. The lazy value is
 * evaluated only if the condition passes.
 *
 * @example
 * import { constant } from 'fp-ts/function'
 * import { pureIf } from 'fp-ts-std/Option'
 * import { Predicate } from 'fp-ts/Predicate'
 *
 * const person = { name: 'Hodor', age: 40 }
 * const isMagicNumber: Predicate<number> = n => n === 42
 *
 * const mname = pureIf(isMagicNumber(person.age))(constant(person.name))
 *
 * @category 2 Typeclass Methods
 * @since 0.13.0
 */
export declare const pureIf: (x: boolean) => <A>(y: Lazy<A>) => Option<A>;
/**
 * Like `altAll`, but flaps an input across an array of functions to produce
 * the `Option` values, short-circuiting upon a non-empty value. Useful given
 * `Option`'s eagerness.
 *
 * @example
 * import { constant } from 'fp-ts/function'
 * import { altAllBy } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 *
 * assert.deepStrictEqual(
 *   altAllBy([constant(O.none), O.some])('foo'),
 *   O.some('foo'),
 * )
 *
 * @category 2 Typeclass Methods
 * @since 0.15.0
 */
export declare const altAllBy: <A, B>(fs: Array<(x: A) => Option<B>>) => (x: A) => Option<B>;
/**
 * Derive a `Bounded` instance for `Option<A>` in which the top and bottom
 * bounds are `Some(B.top)` and `None` respectively.
 *
 * @example
 * import { getBounded } from 'fp-ts-std/Option'
 * import * as O from 'fp-ts/Option'
 * import * as Bool from 'fp-ts-std/Boolean'
 *
 * assert.deepStrictEqual(
 *   getBounded(Bool.Bounded).top,
 *   O.some(true),
 * )
 *
 * @category 1 Typeclass Instances
 * @since 0.17.0
 */
export declare const getBounded: <A>(B: Bounded<A>) => Bounded<Option<A>>;
/**
 * Derive an `Enum` instance for `Option<A>` given an `Enum` instance for `A`.
 *
 * @example
 * import { universe } from 'fp-ts-std/Enum'
 * import { Enum as EnumBool } from 'fp-ts-std/Boolean'
 * import * as O from 'fp-ts/Option'
 * import { getEnum as getEnumO } from 'fp-ts-std/Option'
 *
 * const EnumBoolO = getEnumO(EnumBool)
 *
 * assert.deepStrictEqual(
 *   universe(EnumBoolO),
 *   [O.none, O.some(false), O.some(true)],
 * )
 *
 * @category 1 Typeclass Instances
 * @since 0.17.0
 */
export declare const getEnum: <A>(E: Enum<A>) => Enum<Option<A>>;
/**
 * Pattern match against two `Option`s simultaneously.
 *
 * @example
 * import { constant, flow } from 'fp-ts/function'
 * import * as O from 'fp-ts/Option'
 * import Option = O.Option
 * import { match2 } from 'fp-ts-std/Option'
 * import * as Str from 'fp-ts-std/String'
 *
 * const f: (x: Option<string>) => (y: Option<number>) => string = match2(
 *   constant('Who are you?'),
 *   Str.prepend('Your name is '),
 *   flow(Str.fromNumber, Str.prepend('Your age is ')),
 *   name => age => `You are ${name}, ${age}`,
 * )
 *
 * assert.strictEqual(f(O.none)(O.some(40)), 'Your age is 40')
 * assert.strictEqual(f(O.some("Hodor"))(O.some(40)), 'You are Hodor, 40')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const match2: <A, B, C>(onNone: Lazy<C>, onSomeFst: (x: A) => C, onSomeSnd: (x: B) => C, onSomeBoth: (x: A) => (y: B) => C) => (mx: Option<A>) => (my: Option<B>) => C;
export {};
//# sourceMappingURL=Option.d.ts.map