option-t
Version:
A toolkit of Nullable/Option/Result type implementation in ECMAScript. Their APIs are inspired by Rust's `Option<T>` and `Result<T, E>`.
145 lines (144 loc) • 6.41 kB
TypeScript
/**
*
* This is [_result type_](https://en.wikipedia.org/wiki/Result_type).
*
* ## CAUTION:
*
* ### Be careful to use `===` or `Object.is()` to compare the equality of this type
*
* You should use `equal` operator to check the equality for two objects of this type
* instead of `===` or `Object.is()`.
* Operators for this type sometimes return the inputted object directly
* to avoid an unnecessary objecti allocation.
*
* We use this design by the assumption that we would not compare `a` and `b` usually in the following case.
* It usually suggest some design problems if you would like to compare these `a` and `b`.
*
* ```typescript
* const a = createOk(val);
* const b = andThen(a, someOperation);
* ```
*/
export type Result<T, E> = Ok<T> | Err<E>;
/**
* This type contain a success value _T_.
*
* You can create this type value and get an inner value in this type by hand.
* But we recommend to use the factory {@link createOk()} and utility functions for forward compatibility.
* And we don't recommend to implement this type for your type too.
*
* - {@link createOk()} to create a value of `Ok(T)`.
* - {@link isOk()} to check whether the value is `Ok(T)`.
* - {@link unwrapOk()} to get an inner value in `Ok(T)`.
* - `unwrapOr()` to get either an inner value in `Ok(T)` or a fallback default value.
* - ...and more.
*/
export interface Ok<out T> {
/**
* Don't touch this property directly from an user project
* except 3rd party project that does not install this package but uses a value returned from an other project.
* Instead, use {@link isOk()} or {@link isErr()} operator to get an inner value.
*
* Historically, this type was created to target a JSVM that supports ES5.
* Then there was no well optimized `Symbol` to achieve a private property.
* We don't have a plan to change this into private property keep the backward compatibility.
*/
readonly ok: true;
/**
* Don't touch this property directly from an user project
* except 3rd party project that does not install this package but uses a value returned from an other project.
* Instead, use {@link unwrapOk()} operator to get an inner value.
*
* Historically, this type was created to target a JSVM that supports ES5.
* Then there was no well optimized `Symbol` to achieve a private property.
* We don't have a plan to change this into private property keep the backward compatibility.
*/
readonly val: T;
/**
* Don't touch this property directly from an user project.
* Instead, use {@link unwrapErr()} operator to get an inner value.
*
* Historically, this type was created to target a JSVM that supports ES5.
* Then there was no well optimized `Symbol` to achieve a private property.
* We don't have a plan to change this into private property keep the backward compatibility.
*/
readonly err: null;
}
export declare function isOk<T, E>(input: Result<T, E>): input is Ok<T>;
export declare function createOk<T>(val: T): Ok<T>;
/**
* This type contain a failure information _E_.
*
* You can create this type value and get an inner value in this type by hand.
* But we recommend to use the factory {@link createErr()} and utility functions for forward compatibility.
* And we don't recommend to implement this type for your type too.
*
* - {@link createErr()} to create a value of `Err(E)`.
* - {@link isErr()} to check whether the value is `Err(E)`.
* - {@link unwrapErr()} to get an inner failure information in `Err(E)`.
* - ...and more.
*/
export interface Err<out E> {
/**
* Don't touch this property directly from an user project
* except 3rd party project that does not install this package but uses a value returned from an other project.
* Instead, use {@link isOk()} or {@link isErr()} operator to get an inner value.
*
* Historically, this type was created to target a JSVM that supports ES5.
* Then there was no well optimized `Symbol` to achieve a private property.
* We don't have a plan to change this into private property keep the backward compatibility.
*/
readonly ok: false;
/**
* Don't touch this property directly from an user project
* except 3rd party project that does not install this package but uses a value returned from an other project.
* Instead, use {@link unwrapOk()} operator to get an inner value.
*
* Historically, this type was created to target a JSVM that supports ES5.
* Then there was no well optimized `Symbol` to achieve a private property.
* We don't have a plan to change this into private property keep the backward compatibility.
*/
readonly val: null;
/**
* Don't touch this property directly from an user project
* except 3rd party project that does not install this package but uses a value returned from an other project.
* Instead, use {@link unwrapErr()} operator to get an inner value.
*
* Historically, this type was created to target a JSVM that supports ES5.
* Then there was no well optimized `Symbol` to achieve a private property.
* We don't have a plan to change this into private property keep the backward compatibility.
*/
readonly err: E;
}
export declare function isErr<T, E>(input: Result<T, E>): input is Err<E>;
export declare function createErr<E>(err: E): Err<E>;
/**
* Return the inner `T` of a `Ok(T)`.
*
* @throws {TypeError}
* Throws if the self is a `Err`.
*/
export declare function unwrapOk<T>(input: Result<T, unknown>): T;
/**
* Return the inner `E` of a `Err(E)`.
*
* @throws {TypeError}
* Throws if the self is a `Ok`.
*/
export declare function unwrapErr<E>(input: Result<unknown, E>): E;
/**
* Return _input_ as `T` if the passed _input_ is `Ok(T)`.
* Otherwise, throw `TypeError` with the passed `msg`.
*
* @throws {TypeError}
* Throws if the self is a `Err`.
*/
export declare function expectOk<T>(input: Result<T, unknown>, msg: string): T;
/**
* Return _input_ as `E` if the passed _input_ is `Err(E)`.
* Otherwise, throw `TypeError` with the passed `msg`.
*
* @throws {TypeError}
* Throws if the self is a `Ok`.
*/
export declare function expectErr<E>(input: Result<unknown, E>, msg: string): E;