@cometloop/safe 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,378 @@
+type Falsy = false | 0 | '' | null | undefined | 0n | void;
+/**
+ * Strips falsy members from E via distributive conditional.
+ * When E is purely falsy (e.g. null, false, 0), the result is `never`,
+ * making the parseError return type unsatisfiable — a compile error.
+ *
+ * For union types like `string | null`, the falsy member (`null`) is
+ * stripped, so `parseError` must return `string` — which means
+ * `(e: unknown) => e?.message ?? null` correctly fails to compile.
+ */
+type NonFalsy<E> = E extends Falsy ? never : E;
+type SafeOk<T> = readonly [T, null] & {
+    readonly ok: true;
+    readonly value: T;
+    readonly error: null;
+};
+type SafeErr<E> = readonly [null, E] & {
+    readonly ok: false;
+    readonly value: null;
+    readonly error: E;
+};
+type SafeResult<T, E = Error> = SafeOk<T> | SafeErr<E>;
+type SafeOkObj<T> = {
+    readonly ok: true;
+    readonly data: T;
+    readonly error: null;
+};
+type SafeErrObj<E> = {
+    readonly ok: false;
+    readonly data: null;
+    readonly error: E;
+};
+type SafeResultObj<T, E = Error> = SafeOkObj<T> | SafeErrObj<E>;
+declare function ok<T>(value: T): SafeOk<T>;
+declare function err<E>(error: E): SafeErr<E>;
+declare function okObj<T>(data: T): SafeOkObj<T>;
+declare function errObj<E>(error: E): SafeErrObj<E>;
+declare class TimeoutError extends Error {
+    constructor(ms: number);
+}
+type RetryConfig = {
+    times: number;
+    waitBefore?: (attempt: number) => number;
+};
+type SafeHooks<T, E, TContext extends unknown[] = [], TOut = T> = {
+    parseResult?: (response: T) => TOut;
+    onSuccess?: (result: TOut, context: TContext) => void;
+    onError?: (error: E, context: TContext) => void;
+    onSettled?: (result: TOut | null, error: E | null, context: TContext) => void;
+    onHookError?: (error: unknown, hookName: string) => void;
+    /** Fallback error value returned when `parseError` throws. */
+    defaultError?: E;
+};
+type SafeAsyncHooks<T, E, TContext extends unknown[] = [], TOut = T> = SafeHooks<T, E, TContext, TOut> & {
+    onRetry?: (error: E, attempt: number, context: TContext) => void;
+    retry?: RetryConfig;
+    abortAfter?: number;
+};
+/**
+ * Configuration for creating a pre-configured safe instance
+ * @typeParam E - The error type that parseError returns
+ * @typeParam TResult - The return type of parseResult (inferred from parseResult)
+ */
+type CreateSafeConfig<E, TResult = never> = {
+    /**
+     * Error mapping function applied to all caught errors.
+     *
+     * If `parseError` throws, the exception is caught and reported via `onHookError`
+     * (hookName `'parseError'`). The `defaultError` value is returned as the error
+     * result; if `defaultError` is not provided, the raw caught error is normalized
+     * to an `Error` instance via `new Error(String(e))`.
+     */
+    parseError: (e: unknown) => NonFalsy<E>;
+    /**
+     * Fallback error value returned when `parseError` throws.
+     * Must be provided alongside `parseError` in `createSafe`.
+     */
+    defaultError: E;
+    /** Optional response transform applied to all successful results. Per-call parseResult overrides this. */
+    parseResult?: (response: unknown) => TResult;
+    /** Optional default success hook (result is unknown since T varies per call) */
+    onSuccess?: (result: unknown) => void;
+    /** Optional default error hook (receives the mapped error type E) */
+    onError?: (error: E) => void;
+    /** Optional default settled hook — fires after success or error */
+    onSettled?: (result: unknown, error: E | null) => void;
+    /** Optional default retry hook for async operations */
+    onRetry?: (error: E, attempt: number) => void;
+    /** Optional default retry configuration for async operations */
+    retry?: RetryConfig;
+    /** Optional default timeout for all async operations in milliseconds */
+    abortAfter?: number;
+    /** Optional callback invoked when any hook throws. Receives the thrown error and the hook name. */
+    onHookError?: (error: unknown, hookName: string) => void;
+};
+/**
+ * A pre-configured safe instance with a fixed error type
+ * Methods do not accept parseError parameter (already configured)
+ * @typeParam E - The error type used by all methods
+ * @typeParam TResult - The factory parseResult return type (never = no factory parseResult)
+ */
+type SafeInstance<E, TResult = never> = {
+    sync: <T, TOut = [TResult] extends [never] ? T : TResult>(fn: () => T, hooks?: SafeHooks<T, E, [], TOut>) => SafeResult<TOut, E>;
+    async: <T, TOut = [TResult] extends [never] ? T : TResult>(fn: (signal?: AbortSignal) => Promise<T>, hooks?: SafeAsyncHooks<T, E, [], TOut>) => Promise<SafeResult<TOut, E>>;
+    wrap: <TArgs extends unknown[], T, TOut = [TResult] extends [never] ? T : TResult>(fn: (...args: TArgs) => T, hooks?: SafeHooks<T, E, TArgs, TOut>) => (...args: TArgs) => SafeResult<TOut, E>;
+    wrapAsync: <TArgs extends unknown[], T, TOut = [TResult] extends [never] ? T : TResult>(fn: (...args: TArgs) => Promise<T>, hooks?: SafeAsyncHooks<T, E, TArgs, TOut>) => (...args: TArgs) => Promise<SafeResult<TOut, E>>;
+    all: <T extends Record<string, (signal?: AbortSignal) => Promise<any>>>(fns: T) => Promise<SafeResult<{
+        [K in keyof T]: [TResult] extends [never] ? T[K] extends (signal?: AbortSignal) => Promise<infer V> ? V : never : TResult;
+    }, E>>;
+    allSettled: <T extends Record<string, (signal?: AbortSignal) => Promise<any>>>(fns: T) => Promise<{
+        [K in keyof T]: SafeResult<[
+            TResult
+        ] extends [never] ? T[K] extends (signal?: AbortSignal) => Promise<infer V> ? V : never : TResult, E>;
+    }>;
+};
+/**
+ * Object-style variant of SafeInstance where all methods return SafeResultObj instead of SafeResult tuples.
+ * Created by wrapping a SafeInstance with withObjects().
+ */
+type SafeObjectInstance<E, TResult = never> = {
+    sync: <T, TOut = [TResult] extends [never] ? T : TResult>(fn: () => T, hooks?: SafeHooks<T, E, [], TOut>) => SafeResultObj<TOut, E>;
+    async: <T, TOut = [TResult] extends [never] ? T : TResult>(fn: (signal?: AbortSignal) => Promise<T>, hooks?: SafeAsyncHooks<T, E, [], TOut>) => Promise<SafeResultObj<TOut, E>>;
+    wrap: <TArgs extends unknown[], T, TOut = [TResult] extends [never] ? T : TResult>(fn: (...args: TArgs) => T, hooks?: SafeHooks<T, E, TArgs, TOut>) => (...args: TArgs) => SafeResultObj<TOut, E>;
+    wrapAsync: <TArgs extends unknown[], T, TOut = [TResult] extends [never] ? T : TResult>(fn: (...args: TArgs) => Promise<T>, hooks?: SafeAsyncHooks<T, E, TArgs, TOut>) => (...args: TArgs) => Promise<SafeResultObj<TOut, E>>;
+    all: <T extends Record<string, (signal?: AbortSignal) => Promise<any>>>(fns: T) => Promise<SafeResultObj<{
+        [K in keyof T]: [TResult] extends [never] ? T[K] extends (signal?: AbortSignal) => Promise<infer V> ? V : never : TResult;
+    }, E>>;
+    allSettled: <T extends Record<string, (signal?: AbortSignal) => Promise<any>>>(fns: T) => Promise<{
+        [K in keyof T]: SafeResultObj<[
+            TResult
+        ] extends [never] ? T[K] extends (signal?: AbortSignal) => Promise<infer V> ? V : never : TResult, E>;
+    }>;
+};
+
+/**
+ * Execute a synchronous function and return a result tuple instead of throwing.
+ *
+ * Catches any error thrown by `fn` and returns `[null, error]`.
+ * On success, returns `[result, null]`.
+ *
+ * @param fn - The synchronous function to execute.
+ * @param parseError - Optional function to transform the caught error into a custom type `E`.
+ *   If `parseError` throws, the exception is caught and reported via `onHookError`
+ *   (hookName `'parseError'`). The `defaultError` value is returned if provided;
+ *   otherwise the raw caught error is normalized to an `Error` instance.
+ * @param hooks - Optional hooks for side effects (`parseResult`, `onSuccess`, `onError`, `onSettled`).
+ * @returns A `SafeResult<T, E>` tuple: `[value, null]` on success or `[null, error]` on failure.
+ *
+ * @example
+ * ```typescript
+ * const [user, error] = safe.sync(() => JSON.parse(rawJson))
+ *
+ * // With custom error parsing and hooks
+ * const [value, err] = safe.sync(
+ *   () => riskyOperation(),
+ *   (e) => ({ code: 'PARSE_ERROR', message: String(e) }),
+ *   { onError: (error) => console.error(error.code) }
+ * )
+ * ```
+ */
+declare function safeSync<T>(fn: () => T): SafeResult<T, Error>;
+declare function safeSync<T, TOut = T>(fn: () => T, hooks: SafeHooks<T, Error, [], TOut>): SafeResult<TOut, Error>;
+declare function safeSync<T, E>(fn: () => T, parseError: (e: unknown) => NonFalsy<E>): SafeResult<T, E>;
+declare function safeSync<T, E, TOut = T>(fn: () => T, parseError: (e: unknown) => NonFalsy<E>, hooks: SafeHooks<T, E, [], TOut> & {
+    defaultError: E;
+}): SafeResult<TOut, E>;
+/**
+ * Execute an asynchronous function and return a result tuple instead of throwing.
+ *
+ * Catches any error thrown or rejected by `fn` and returns `[null, error]`.
+ * On success, returns `[result, null]`. Supports retry and timeout via hooks.
+ *
+ * @param fn - The async function to execute. Receives an optional `AbortSignal` when `abortAfter` is configured.
+ * @param parseError - Optional function to transform the caught error into a custom type `E`.
+ *   If `parseError` throws, the exception is caught and reported via `onHookError`
+ *   (hookName `'parseError'`). The `defaultError` value is returned if provided;
+ *   otherwise the raw caught error is normalized to an `Error` instance.
+ * @param hooks - Optional hooks including `retry`, `abortAfter`, `onRetry`, `parseResult`, `onSuccess`, `onError`, `onSettled`.
+ * @returns A `Promise<SafeResult<T, E>>` tuple: `[value, null]` on success or `[null, error]` on failure.
+ *
+ * @example
+ * ```typescript
+ * const [data, error] = await safe.async(() => fetch('/api/users').then(r => r.json()))
+ *
+ * // With retry and timeout
+ * const [data, error] = await safe.async(
+ *   (signal) => fetch('/api/users', { signal }).then(r => r.json()),
+ *   { retry: { times: 3 }, abortAfter: 5000 }
+ * )
+ * ```
+ */
+declare function safeAsync<T>(fn: (signal?: AbortSignal) => Promise<T>): Promise<SafeResult<T, Error>>;
+declare function safeAsync<T, TOut = T>(fn: (signal?: AbortSignal) => Promise<T>, hooks: SafeAsyncHooks<T, Error, [], TOut>): Promise<SafeResult<TOut, Error>>;
+declare function safeAsync<T, E>(fn: (signal?: AbortSignal) => Promise<T>, parseError: (e: unknown) => NonFalsy<E>): Promise<SafeResult<T, E>>;
+declare function safeAsync<T, E, TOut = T>(fn: (signal?: AbortSignal) => Promise<T>, parseError: (e: unknown) => NonFalsy<E>, hooks: SafeAsyncHooks<T, E, [], TOut> & {
+    defaultError: E;
+}): Promise<SafeResult<TOut, E>>;
+/**
+ * Wrap a synchronous function so it returns a result tuple instead of throwing.
+ *
+ * Returns a new function with the same parameter signature that catches
+ * errors and returns `[null, error]` instead of throwing. The original
+ * arguments are passed through to hooks as context.
+ *
+ * @param fn - The synchronous function to wrap.
+ * @param parseError - Optional function to transform the caught error into a custom type `E`.
+ *   If `parseError` throws, the exception is caught and reported via `onHookError`
+ *   (hookName `'parseError'`). The `defaultError` value is returned if provided;
+ *   otherwise the raw caught error is normalized to an `Error` instance.
+ * @param hooks - Optional hooks for side effects (`parseResult`, `onSuccess`, `onError`, `onSettled`). Hooks receive the original call arguments as context.
+ * @returns A wrapped function `(...args) => SafeResult<T, E>`.
+ *
+ * @example
+ * ```typescript
+ * const safeJsonParse = safe.wrap(JSON.parse)
+ * const [data, error] = safeJsonParse('{"valid": true}')
+ *
+ * // With hooks that receive the original arguments
+ * const safeDivide = safe.wrap(
+ *   (a: number, b: number) => { if (b === 0) throw new Error('Division by zero'); return a / b },
+ *   { onError: (error, [a, b]) => console.error(`Failed to divide ${a} by ${b}`) }
+ * )
+ * ```
+ */
+declare function wrap<TArgs extends unknown[], T>(fn: (...args: TArgs) => T): (...args: TArgs) => SafeResult<T, Error>;
+declare function wrap<TArgs extends unknown[], T, TOut = T>(fn: (...args: TArgs) => T, hooks: SafeHooks<T, Error, TArgs, TOut>): (...args: TArgs) => SafeResult<TOut, Error>;
+declare function wrap<TArgs extends unknown[], T, E>(fn: (...args: TArgs) => T, parseError: (e: unknown) => NonFalsy<E>): (...args: TArgs) => SafeResult<T, E>;
+declare function wrap<TArgs extends unknown[], T, E, TOut = T>(fn: (...args: TArgs) => T, parseError: (e: unknown) => NonFalsy<E>, hooks: SafeHooks<T, E, TArgs, TOut> & {
+    defaultError: E;
+}): (...args: TArgs) => SafeResult<TOut, E>;
+/**
+ * Wrap an asynchronous function so it returns a result tuple instead of throwing.
+ *
+ * Returns a new function with the same parameter signature that catches
+ * errors and returns `[null, error]` instead of throwing. Supports retry
+ * and timeout via hooks.
+ *
+ * **Note on `abortAfter`:** When configured, `abortAfter` acts as an external
+ * deadline — the promise is rejected with a `TimeoutError` after the specified
+ * duration, but the wrapped function does **not** receive an `AbortSignal`.
+ * This means the underlying operation will continue running in the background
+ * even after the timeout fires. If you need cooperative cancellation (e.g.
+ * passing a signal to `fetch`), use {@link safeAsync | safe.async} instead,
+ * which passes the signal directly to the function:
+ *
+ * ```typescript
+ * // Cooperative cancellation with safe.async
+ * const [data, error] = await safe.async(
+ *   (signal) => fetch('/api/data', { signal }),
+ *   { abortAfter: 5000 }
+ * )
+ * ```
+ *
+ * @param fn - The async function to wrap.
+ * @param parseError - Optional function to transform the caught error into a custom type `E`.
+ *   If `parseError` throws, the exception is caught and reported via `onHookError`
+ *   (hookName `'parseError'`). The `defaultError` value is returned if provided;
+ *   otherwise the raw caught error is normalized to an `Error` instance.
+ * @param hooks - Optional hooks including `retry`, `abortAfter`, `onRetry`, `parseResult`, `onSuccess`, `onError`, `onSettled`. Hooks receive the original call arguments as context.
+ * @returns A wrapped function `(...args) => Promise<SafeResult<T, E>>`.
+ *
+ * @example
+ * ```typescript
+ * const safeFetchUser = safe.wrapAsync(
+ *   (id: string) => fetch(`/api/users/${id}`).then(r => r.json())
+ * )
+ * const [user, error] = await safeFetchUser('123')
+ *
+ * // With retry
+ * const safeFetch = safe.wrapAsync(
+ *   (url: string) => fetch(url).then(r => r.json()),
+ *   { retry: { times: 3, waitBefore: (attempt) => attempt * 1000 } }
+ * )
+ * ```
+ */
+declare function wrapAsync<TArgs extends unknown[], T>(fn: (...args: TArgs) => Promise<T>): (...args: TArgs) => Promise<SafeResult<T, Error>>;
+declare function wrapAsync<TArgs extends unknown[], T, TOut = T>(fn: (...args: TArgs) => Promise<T>, hooks: SafeAsyncHooks<T, Error, TArgs, TOut>): (...args: TArgs) => Promise<SafeResult<TOut, Error>>;
+declare function wrapAsync<TArgs extends unknown[], T, E>(fn: (...args: TArgs) => Promise<T>, parseError: (e: unknown) => NonFalsy<E>): (...args: TArgs) => Promise<SafeResult<T, E>>;
+declare function wrapAsync<TArgs extends unknown[], T, E, TOut = T>(fn: (...args: TArgs) => Promise<T>, parseError: (e: unknown) => NonFalsy<E>, hooks: SafeAsyncHooks<T, E, TArgs, TOut> & {
+    defaultError: E;
+}): (...args: TArgs) => Promise<SafeResult<TOut, E>>;
+/**
+ * Run multiple safe-wrapped async operations in parallel and return all values or the first error.
+ *
+ * Short-circuits: returns immediately when any operation fails, without waiting
+ * for remaining operations to settle. If all succeed, returns
+ * `ok({ key: value, ... })` with unwrapped values. If any fail, returns `err(firstError)`.
+ *
+ * @param promises - An object map of `Promise<SafeResult<T, E>>` entries.
+ * @returns A `Promise<SafeResult<{ [K]: V }, E>>` — all values on success, first error on failure.
+ *
+ * @example
+ * ```typescript
+ * const [data, error] = await safe.all({
+ *   user: safe.async(() => fetchUser()),
+ *   posts: safe.async(() => fetchPosts()),
+ * })
+ * if (error) return handleError(error)
+ * data.user   // User
+ * data.posts  // Post[]
+ * ```
+ */
+declare function safeAll<T extends Record<string, Promise<SafeResult<any, any>>>>(promises: T): Promise<SafeResult<{
+    [K in keyof T]: T[K] extends Promise<SafeResult<infer V, any>> ? V : never;
+}, T[keyof T] extends Promise<SafeResult<any, infer E>> ? E : never>>;
+/**
+ * Run multiple safe-wrapped async operations in parallel and return all individual results.
+ *
+ * Accepts an object map of `Promise<SafeResult>` entries. Always returns all results
+ * as named SafeResult entries — never fails at the group level.
+ *
+ * @param promises - An object map of `Promise<SafeResult<T, E>>` entries.
+ * @returns A `Promise<{ [K]: SafeResult<V, E> }>` — each key maps to its individual result.
+ *
+ * @example
+ * ```typescript
+ * const results = await safe.allSettled({
+ *   user: safe.async(() => fetchUser()),
+ *   posts: safe.async(() => fetchPosts()),
+ * })
+ * if (results.user.ok) {
+ *   results.user.value  // User
+ * }
+ * if (!results.posts.ok) {
+ *   results.posts.error  // Error
+ * }
+ * ```
+ */
+declare function safeAllSettled<T extends Record<string, Promise<SafeResult<any, any>>>>(promises: T): Promise<{
+    [K in keyof T]: Awaited<T[K]>;
+}>;
+declare const safe: {
+    readonly sync: typeof safeSync;
+    readonly async: typeof safeAsync;
+    readonly wrap: typeof wrap;
+    readonly wrapAsync: typeof wrapAsync;
+    readonly all: typeof safeAll;
+    readonly allSettled: typeof safeAllSettled;
+};
+
+/**
+ * Create a pre-configured safe instance with a fixed error mapping function
+ *
+ * Returns a new safe object where all methods use the configured parseError.
+ * The error type E is automatically inferred from the parseError return type.
+ * If parseResult is provided, TResult is inferred from its return type
+ * and becomes the default result type for all methods.
+ *
+ * @example
+ * ```typescript
+ * const appSafe = createSafe({
+ *   parseError: (e) => ({
+ *     code: 'UNKNOWN_ERROR',
+ *     message: e instanceof Error ? e.message : 'Unknown error',
+ *   }),
+ *   onError: (error) => logger.error(error.code),
+ * })
+ *
+ * const [result, error] = appSafe.sync(() => JSON.parse(data))
+ * // error is typed as { code: string; message: string }
+ *
+ * // With parseResult for runtime validation:
+ * const validatedSafe = createSafe({
+ *   parseError: (e) => toAppError(e),
+ *   parseResult: (response) => schema.parse(response),
+ * })
+ * // All methods return SafeResult<z.infer<typeof schema>, AppError>
+ * ```
+ */
+declare function createSafe<E, TResult = never>(config: CreateSafeConfig<E, TResult>): SafeInstance<E, TResult>;
+
+declare function withObjects<T, E>(result: SafeResult<T, E>): SafeResultObj<T, E>;
+declare function withObjects<T, E>(result: Promise<SafeResult<T, E>>): Promise<SafeResultObj<T, E>>;
+declare function withObjects<A extends unknown[], T, E>(fn: (...args: A) => SafeResult<T, E>): (...args: A) => SafeResultObj<T, E>;
+declare function withObjects<A extends unknown[], T, E>(fn: (...args: A) => Promise<SafeResult<T, E>>): (...args: A) => Promise<SafeResultObj<T, E>>;
+declare function withObjects<E, TResult>(instance: SafeInstance<E, TResult>): SafeObjectInstance<E, TResult>;
+
+export { type CreateSafeConfig, type NonFalsy, type RetryConfig, type SafeAsyncHooks, type SafeErr, type SafeErrObj, type SafeHooks, type SafeInstance, type SafeObjectInstance, type SafeOk, type SafeOkObj, type SafeResult, type SafeResultObj, TimeoutError, createSafe, err, errObj, ok, okObj, safe, withObjects };