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

A TypeScript utility for elegant error handling with Result types

//#region src/index.d.ts
/*!
 * Represents a successful operation result
 * @template T The type of the successful data
 */
type Success<T> = {
  data: T;
  error?: never;
  readonly ok: true;
};
/*!
 * Represents a failed operation result
 * @template E The type of the error
 */
type Failure<E> = {
  data?: never;
  error: E;
  readonly ok: false;
};
/*!
 * 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>;
/*!
 * Transforms the data of a successful result using the provided function
 * If the result is a failure, returns the failure unchanged
 *
 * @template T The type of the original successful data
 * @template U The type of the transformed data
 * @template E The type of the error
 * @param result The result to transform
 * @param fn The transformation function
 * @returns A new Result with transformed data or the original failure
 */
declare const map: <T, U, E>(result: Result<T, E>, fn: (data: T) => U) => Result<U, E>;
/*!
 * Transforms the data of a successful result using a function that returns a Result
 * If the result is a failure, returns the failure unchanged
 *
 * @template T The type of the original successful data
 * @template U The type of the transformed data
 * @template E The type of the error
 * @param result The result to transform
 * @param fn The transformation function that returns a Result
 * @returns A new Result with transformed data or a failure
 */
declare const flatMap: <T, U, E>(result: Result<T, E>, fn: (data: T) => Result<U, E>) => Result<U, E>;
/*!
 * Combines multiple results into a single result.
 * If all results are successful, returns a success result containing an array of all data.
 * If any result is a failure, returns the first failure encountered.
 *
 * @template T The type of the successful data
 * @template E The type of the error
 * @param results Array of results to combine
 * @returns A Result containing an array of data or the first failure
 */
declare const all: <T, E>(results: Result<T, E>[]) => Result<T[], E>;
/*!
 * Extracts the data from a successful result or returns a default value
 *
 * @template T The type of the successful data
 * @template E The type of the error
 * @param result The result to unwrap
 * @param defaultValue The default value to return if the result is a failure
 * @returns The data if successful, otherwise the default value
 */
declare const unwrapOr: <T, E>(result: Result<T, E>, defaultValue: T) => T;
/*!
 * Extracts the data from a successful result or computes a default value using the error
 *
 * @template T The type of the successful data
 * @template E The type of the error
 * @param result The result to unwrap
 * @param fn Function that takes the error and returns a default value
 * @returns The data if successful, otherwise the computed default value
 */
declare const unwrapOrElse: <T, E>(result: Result<T, E>, fn: (error: E) => T) => T;
/*!
 * Pattern matching for Result types - handles both success and failure cases
 *
 * @template T The type of the successful data
 * @template E The type of the error
 * @template U The return type of both match functions
 * @param result The result to match against
 * @param handlers Object containing success and failure handler functions
 * @returns The result of calling the appropriate handler function
 */
declare const match: <T, E, U>(result: Result<T, E>, handlers: {
  success: (data: T) => U;
  failure: (error: E) => U;
}) => U;
/*!
 * 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, isError, or the ok property.
 *
 * @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;
//#endregion
export { Failure, MaybePromise, Result, Success, all, failure, flatMap, isError, isSuccess, map, match, success, t, tc, tca, tryCatch, tryCatchAsync, tryCatchSync, unwrapOr, unwrapOrElse };
//# sourceMappingURL=index.d.mts.map