safety-number-one/dist/esm/global.d.ts

Utility functions to work with Promises, functions and async functions safely by converting throws to Result Tuple types

import type { ResultTuple } from "nice-types";
declare global {
    /**
     * Utility function await a Promise safely to prevent it from throwing and
     * returns a `ResultTuple`.
     *
     * ### Alternatively
     * 1. Run a synchronous function with global util `$runFnSafely`.
     * 1. Run an async function with global util `$runAsyncFnSafely`.
     *
     * ### Important Note
     * Make sure you do not pass in a synchronous function call like
     * ```typescript
     * function test() {
     *     throw new Error('testing');
     * }
     * $awaitPromiseSafely(test());
     * ```
     * This will not work, as it will throw before control flow even passes to
     * `$awaitPromiseSafely`, effectively making this function call useless.
     *
     * ## Prefer `$runAsyncFnSafely`
     * The execution starts at the promise creator function's call site, and only
     * when the first await is found, then the whole thing becomes a Promise and
     * get passed into this `$awaitPromiseSafely` wrapper as its argument, and
     * execution gets yielded to the await in this function. So potentially,
     * during the time between calling `$awaitPromiseSafely` and creating the
     * promise, it might have already thrown in a synchronous manner, see the
     * important note above on how it could happen. Which is why
     * `$runAsyncFnSafely` is a safer alternative since the initial call is
     * already protected by a try/catch inside `$runAsyncFnSafely`, but the
     * downside being an additional function call stack.
     */
    function $awaitPromiseSafely<T extends Promise<any>, SuccessfulReturnType extends Awaited<T>>(promise: T): Promise<ResultTuple<SuccessfulReturnType, Error>>;
    /**
     * Utility function run an async function safely to prevent it from
     * throwing and returns a `ResultTuple`.
     *
     * ### Alternatively
     * 1. Run a synchronous function with global util `$runFnSafely`.
     * 1. Await a Promise with global util `$awaitPromiseSafely`.
     *
     * ### Unknown original function return type
     * Sometimes you want to deal with functions that can be synchronous or async,
     * i.e. the function return type is not known at compile time. In such cases
     * choose `$runAsyncFnSafely` instead of `$runFnSafely` for compatibility.
     * Because even if a synchronous function is passed in, this will still await
     * it, which is equivalent to `Promise.resolve(value)`.
     * However if you do know that the function will be synchronous, prefer
     * `$runFnSafely` for a non `Promise<T>` wrapped return type.
     */
    function $runAsyncFnSafely<T extends (...args: any) => any, FnArgs extends Parameters<T>, SuccessfulReturnType extends Awaited<ReturnType<T>>>(fn: T, ...args: FnArgs): Promise<ResultTuple<SuccessfulReturnType, Error>>;
    /**
     * Utility function run a synchronous function safely to prevent it from
     * throwing and returns a `ResultTuple`.
     *
     * ### Alternatively
     * 1. Run an async function with global util `$runAsyncFnSafely`.
     * 1. Await a Promise with global util `$awaitPromiseSafely`.
     */
    function $runFnSafely<T extends (...args: any) => any, FnArgs extends Parameters<T>, SuccessfulReturnType extends ReturnType<T>>(fn: T, ...args: FnArgs): ResultTuple<SuccessfulReturnType, Error>;
}
//# sourceMappingURL=global.d.ts.map