fairlie-functional/dist/src/index.d.mts

A lightweight functional library in typescript that helps dealing with failures the rail way

/** Represent a successful result */
export type Success<A> = {
    status: 'success';
    value: A;
};
/** Represent a failed result */
export type Failure<E> = {
    status: 'failure';
    error: E;
};
export type Result<A, E> = Success<A> | Failure<E>;
/**
 * A function that has one input and a success/failure output.
 * It can be seen as a railway switch that directs the input to either the success track or the failure track.
 */
export type SwitchFunction<V, A, E> = (value: V) => Result<A, E>;
/**
 * An asynchronous function that has one input and a success/failure output.
 * It can be seen as a railway switch that directs the input to either the success track or the failure track.
 */
export type AsyncSwitchFunction<V, A, E> = (value: V) => Promise<Result<A, E>>;
/**
 * A function that takes an input and return an output
 */
export type TransformFunction<V, A> = (value: V) => A;
/**
 * An asynchronous function that takes an input and return an output
 */
export type AsyncTransformFunction<V, A> = (value: V) => Promise<A>;
/**
 * A function that has one input and a success/failure output.
 * It can be seen as a railway switch that directs the input to either the success track or the failure track.
 */
export type RecoverSwitchFunction<A, E> = (error: E) => Success<A>;
/**
 * An asynchronous function that has one input and a success/failure output.
 * It can be seen as a railway switch that directs the input to either the success track or the failure track.
 */
export type AsyncRecoverSwitchFunction<A, E> = (error: E) => Promise<Success<A>>;
/**
 * Return a successful response
 * @param value a successful value
 */
export declare const succeed: <A>(value: A) => Success<A>;
/**
 * Return a failure result
 * @param error an error value
 */
export declare const failWith: <E>(error: E) => Failure<E>;
/**
 * Return the successful value otherwise a default value
 * @param defaultValue the default value
 * @returns the successful otherwise the default value
 */
export declare const withDefault: <A, E>(defaultValue: A) => (result: Result<A, E>) => A;
/**
 * A function that connects two switch functions
   together, passing the success output of the first function to the input
   of the second function, and propagating the failure output to the error
   track.
 * @param f1 the first switch function
 * @param f2 the second switch function
 * @returns a composite switch function
 */
export declare function bindTwo<V, A, B, E>(f1: SwitchFunction<V, A, E>, f2: SwitchFunction<A, B, E>): SwitchFunction<V, B, E>;
/**
 * A function that connects two asynchronous switch functions
   together, passing the success output of the first function to the input
   of the second function, and propagating the failure output to the error
   track.
 * @param f1 the first asynchronous switch function
 * @param f2 the second asynchronous switch function
 * @returns a composite async switch function
 */
export declare function bindTwoAsync<V, A, B, E>(f1: AsyncSwitchFunction<V, A, E>, f2: AsyncSwitchFunction<A, B, E>): AsyncSwitchFunction<V, B, E>;
/**
 * A function that connects three switch functions
   together, passing the success output of the first function to the input
   of the second function, and then passing the success output of the second function
   to the third function and propagating the failure output to the error
   track.
 * @param f1 the first switch function
 * @param f2 the second switch function
 * @param f3 the third switch function
 * @returns a successful result or a failure
 */
export declare function bindThree<V, A, B, C, E>(f1: SwitchFunction<V, A, E>, f2: SwitchFunction<A, B, E>, f3: SwitchFunction<B, C, E>): SwitchFunction<V, C, E>;
/**
 * A function that connects three switch functions asynchronously
   together, passing the success output of the first function to the input
   of the second function, and then passing the success output of the second function
   to the third function and propagating the failure output to the error
   track.
 * @param f1 the first switch function
 * @param f2 the second switch function
 * @param f3 the third switch function
 * @returns a successful result or a failure
 */
export declare function bindThreeAsync<V, A, B, C, E>(f1: AsyncSwitchFunction<V, A, E>, f2: AsyncSwitchFunction<A, B, E>, f3: AsyncSwitchFunction<B, C, E>): AsyncSwitchFunction<V, C, E>;
/**
* A function that connects multiple switch functions
 together, passing the success output of the current function to the input
 of the next function, and propagating the failure output to the error
 track.
* @param functions the first switch function
* @returns a successful result or a failure
*/
export declare function bindSimilar<A, E>(functions: [
    SwitchFunction<A, A, E>,
    SwitchFunction<A, A, E>,
    ...SwitchFunction<A, A, E>[]
]): SwitchFunction<A, A, E>;
/**
 * A function that connects multiple switch functions asynchronously
   together, passing the success output of the current function to the input
   of the next function, and propagating the failure output to the error
   track.
 * @param functions the first switch function
 * @returns a successful result or a failure
 */
export declare function bindSimilarAsync<A, E>(functions: [
    AsyncSwitchFunction<A, A, E>,
    AsyncSwitchFunction<A, A, E>,
    ...AsyncSwitchFunction<A, A, E>[]
]): AsyncSwitchFunction<A, A, E>;
/**
 * The bypass function takes a switch function that expects a failure value as an input
 * and returns a success or failure value as an output
 * @param altFunc the first switch function
 * @returns a successful result or a failure
 */
export declare function bypass<V, A, E>(altFunc: SwitchFunction<E, A, E>): (value: Result<V, E>) => Result<V | A, E>;
/**
* The bypass function takes an asynchronous switch function that expects a failure value as an input
* and returns a success or failure value as an output
* @param altFunc the first switch function
* @returns a successful result or a failure
*/
export declare function bypassAsync<V, A, E>(altFunc: AsyncSwitchFunction<E, A, E>): (value: Result<V, E>) => Promise<Result<V | A, E>>;
/**
 * The recover function takes a recovery function that expects a failure value as an input
 * and returns only a success value as an output
 * @param altFunc the first switch function
 * @returns a successful result or a failure
 */
export declare function recover<V, A, E>(altFunc: RecoverSwitchFunction<A, E>): (value: Result<V, E>) => Result<V | A, E>;
/**
* The recover function takes a asynchronous recovery function that expects a failure value as an input
* and returns only a success value as an output
* @param altFunc the first switch function
* @returns a successful result or a failure
*/
export declare function recoverAsync<V, A, E>(altFunc: AsyncRecoverSwitchFunction<A, E>): (value: Result<V, E>) => Promise<Result<V | A, E>>;
/**
* The fallback function takes a switch function that expects the input value as an input
* and returns a success or failure value as an output. In short, it will fallback to that
* function if the first fail
* @param f1 the first switch function
* @param fallbackF2 the fallback function
* @returns a successful result or a failure
*/
export declare function orFallback<V, A, E>(f1: SwitchFunction<V, A, E>, fallbackF2: SwitchFunction<V, A, E>): SwitchFunction<V, A, E>;
/**
* The fallback function takes an asynchronous switch function that expects the input value as an input
* and returns a success or failure value as an output. In short, it will fallback to that
* function if the first fail
* @param f1 the first switch function
* @param fallbackF2 the fallback function
* @returns a successful result or a failure
*/
export declare function orFallbackAsync<V, A, E>(f1: AsyncSwitchFunction<V, A, E>, fallbackF2: AsyncSwitchFunction<V, A, E>): AsyncSwitchFunction<V, A, E>;
/**
 * Take a simple transformation function which takes an input and return an output and
 * convert it to a switch
 * @param transform a transformer function
 * @returns a switch function
 */
export declare function transformToSwitch<V, A, E>(transform: TransformFunction<V, A>): SwitchFunction<V, A, E>;
/**
* Take a simple transformation function which takes an input and return an output and
* convert it to an asynchronous switch
* @param transform a transformer function
* @returns an asynchronous switch function
*/
export declare function transformToAsyncSwitch<V, A, E>(transform: TransformFunction<V, A>): AsyncSwitchFunction<V, A, E>;