neat-catch/dist/index.d.ts

A comprehensive utility library for elegant error handling in TypeScript and JavaScript. Handle both sync and async operations with clean tuple-based results.

/**
 * A utility function that executes a sync or async function and returns a tuple
 * where the first element is the data (or null if error) and the second element
 * is the error (or null if successful)
 *
 * @param fn - The sync or async function to execute
 * @param errorTransformer - Optional function to transform caught errors
 * @returns A tuple of [data | null, error | null] (wrapped in Promise for async functions)
 */
declare function neatCatch<TFn extends () => any, E = Error>(fn: TFn, errorTransformer?: (error: unknown) => E): ReturnType<TFn> extends Promise<any> ? Promise<[Awaited<ReturnType<TFn>>, null] | [null, E]> : [ReturnType<TFn>, null] | [null, E];
declare function createNeatWrapper<TArgs extends any[], TReturn, E = Error>(fn: (...args: TArgs) => TReturn, errorTransformer?: (error: unknown) => E): <TOverride = TReturn>(...args: TArgs) => [TOverride, null] | [null, E];
declare function createNeatWrapper<TArgs extends any[], TReturn, E = Error>(fn: (...args: TArgs) => Promise<TReturn>, errorTransformer?: (error: unknown) => E): <TOverride = TReturn>(...args: TArgs) => Promise<[TOverride, null] | [null, E]>;
/**
 * Utility for handling multiple async operations and collecting results/errors.
 * The index of results and errors corresponds to the index of the input operations.
 *
 * @param operations - An array of functions returning Promises
 * @param errorTransformer - Optional function to transform caught errors
 * @returns An object with either all results or all errors
 */
declare function neatCatchAll<T extends readonly any[], E = Error>(operations: {
    [K in keyof T]: () => Promise<T[K]>;
}, errorTransformer?: (error: unknown) => E): Promise<{
    results: {
        [K in keyof T]: T[K] | null;
    } | null;
    errors: {
        [K in keyof T]: E | null;
    } | null;
}>;
type NeatCatchRetryOptions<E = Error> = {
    maxRetries?: number;
    delay?: number;
    backoff?: "linear" | "exponential";
    errorTransformer?: (error: unknown, attempt: number) => E;
    shouldRetry?: (error: unknown, attempt: number) => boolean;
};
/**
 * Utility for retrying operations with neat error handling
 *
 * @param fn - The async function to execute
 * @param options - Configuration options for retries
 * @returns A tuple of [data | null, error | null] after retries
 */
declare function neatCatchRetry<T, E = Error>(fn: () => Promise<T>, options?: NeatCatchRetryOptions<E>): Promise<[T, null] | [null, E]>;
/**
 * Common error transformers for convenience
 */
declare const errorTransformers: {
    /**
     * Transforms any error into a simple message string
     */
    toString: (error: unknown) => string;
    /**
     * Transforms errors into a structured object with message and stack
     */
    toObject: (error: unknown) => {
        message: string;
        stack?: string;
        name?: string;
        cause?: unknown;
    };
    /**
     * Transforms errors into a structured object with timestamp
     */
    withTimestamp: (error: unknown) => {
        error: unknown;
        timestamp: number;
        isoString: string;
    };
    /**
     * Transforms HTTP fetch errors into structured format
     */
    fetchError: (error: unknown) => {
        message: string;
        status?: number;
        statusText?: string;
        url?: string;
        isNetworkError: boolean;
        isTimeout: boolean;
    };
    /**
     * Wraps an error with additional context information
     */
    withContext: <T extends Record<string, unknown>>(context: T) => (error: unknown) => T & {
        error: unknown;
    };
    /**
     * Simplifies errors by extracting only the message and discarding other properties
     */
    toSimpleError: (error: unknown) => {
        message: string;
    };
    /**
     * Transforms errors for logging purposes with detailed information
     */
    forLogging: (error: unknown) => {
        message: string;
        stack?: string;
        name?: string;
        timestamp: number;
        environment?: string;
    };
};
type NeatCatchResult<T, E = Error> = [T, null] | [null, E];

export { type NeatCatchResult, type NeatCatchRetryOptions, createNeatWrapper, neatCatch as default, errorTransformers, neatCatch, neatCatchAll, neatCatchRetry };