@itsezz/try-catch/dist/index.d.ts

A TypeScript utility for elegant error handling with Result types

/*!
 * Represents a successful operation result
 * @template T The type of the successful data
 */
type Success<T> = {
    data: T;
    error?: never;
};
/*!
 * Represents a failed operation result
 * @template E The type of the error
 */
type Failure<E> = {
    data?: never;
    error: E;
};
/*!
 * Union type representing either a successful or failed operation result
 * @template T The type of the successful data
 * @template E The type of the error, defaults to Error
 */
type Result<T, E = Error> = Success<T> | Failure<E>;
/*!
 * Represents a value that might be a Promise or a direct value
 * @template T The type of the value
 */
type MaybePromise<T> = T | Promise<T>;
/*!
 * Type guard to check if a result represents a successful operation
 *
 * @template T The type of the successful data
 * @template E The type of the error
 * @param result The result to check
 * @returns True if the result represents a successful operation
 */
declare const isSuccess: <T, E>(result: Result<T, E>) => result is Success<T>;
/*!
 * Type guard to check if a result represents a failed operation
 *
 * @template T The type of the successful data
 * @template E The type of the error
 * @param result The result to check
 * @returns True if the result represents a failed operation
 */
declare const isError: <T, E>(result: Result<T, E>) => result is Failure<E>;
/*!
 * Creates a success result with the given data
 *
 * @template T The type of the successful data
 * @param data The data to include in the success result
 * @returns A Success object containing the data
 */
declare const success: <T>(data: T) => Success<T>;
/*!
 * Creates a failure result with the given error
 *
 * @template E The type of the error
 * @param error The error to include in the failure result
 * @returns A Failure object containing the error
 */
declare const failure: <E>(error: E) => Failure<E>;
/*!
 * Safely executes a function or awaits a promise, capturing any errors
 *
 * This utility provides a consistent way to handle both synchronous and asynchronous
 * operations that might throw errors. It returns a Result object that can be checked
 * with isSuccess or isError.
 *
 * @template T The type of the successful result
 * @template E The type of the error, defaults to unknown
 * @param fnOrPromise The function to execute, promise to await, or async function to call
 * @returns A Result object for synchronous functions or Promise<Result> for promises and async functions, containing either data or error
 */
declare function tryCatch<T, E = unknown>(fn: () => Promise<T>): Promise<Result<T, E>>;
declare function tryCatch<T, E = unknown>(fn: () => T): Result<T, E>;
declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>;
/*!
 * Safely executes a synchronous function, capturing any errors
 *
 * This utility is specifically for synchronous operations that might throw errors.
 * It guarantees a synchronous Result return type, never a Promise.
 *
 * @template T The type of the successful result
 * @template E The type of the error, defaults to unknown
 * @param fn The synchronous function to execute
 * @returns A Result object containing either data or error
 */
declare function tryCatchSync<T, E = unknown>(fn: () => T): Result<T, E>;
/*!
 * Safely executes an asynchronous function or awaits a promise, capturing any errors
 *
 * This utility is specifically for asynchronous operations that might throw errors.
 * It guarantees a Promise<Result> return type.
 *
 * @template T The type of the successful result
 * @template E The type of the error, defaults to unknown
 * @param fnOrPromise The async function to execute or promise to await
 * @returns A Promise<Result> containing either data or error
 */
declare function tryCatchAsync<T, E = unknown>(fn: () => Promise<T>): Promise<Result<T, E>>;
declare function tryCatchAsync<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>;
/*!
 * Short alias for tryCatch - safely executes a function or awaits a promise
 *
 * @template T The type of the successful result
 * @template E The type of the error, defaults to unknown
 * @param fnOrPromise The function to execute, promise to await, or async function to call
 * @returns A Result object for synchronous functions or Promise<Result> for promises and async functions, containing either data or error
 */
declare const t: typeof tryCatch;
/*!
 * Short alias for tryCatchSync - safely executes a synchronous function
 *
 * @template T The type of the successful result
 * @template E The type of the error, defaults to unknown
 * @param fn The synchronous function to execute
 * @returns A Result object containing either data or error
 */
declare const tc: typeof tryCatchSync;
/*!
 * Short alias for tryCatchAsync - safely executes an async function or awaits a promise
 *
 * @template T The type of the successful result
 * @template E The type of the error, defaults to unknown
 * @param fnOrPromise The async function to execute or promise to await
 * @returns A Promise<Result> containing either data or error
 */
declare const tca: typeof tryCatchAsync;

export { type Failure, type MaybePromise, type Result, type Success, failure, isError, isSuccess, success, t, tc, tca, tryCatch, tryCatchAsync, tryCatchSync };