@f0rbit/corpus 0.1.9 → 0.2.1

package/dist/result.d.ts

@@ -0,0 +1,361 @@
+/**
+ * @module Result
+ * @description Extended utilities for working with Result types.
+ *
+ * Provides functional utilities for error handling without exceptions:
+ * - Pattern matching with `match`
+ * - Safe unwrapping with `unwrap_or`, `unwrap`, `unwrap_err`
+ * - Exception-to-Result conversion with `try_catch`, `try_catch_async`
+ * - Fetch wrapper with `fetch_result`
+ * - Composable pipelines with `pipe`
+ */
+import { type Result } from "./types";
+/**
+ * Pattern match on a Result, extracting the value with appropriate handler.
+ *
+ * @param result - The Result to match on
+ * @param on_ok - Handler for success case
+ * @param on_err - Handler for error case
+ * @returns The return value of the matching handler
+ *
+ * @example
+ * ```ts
+ * const result = await fetchUser(id)
+ * const message = match(
+ *   result,
+ *   user => `Hello, ${user.name}!`,
+ *   error => `Failed: ${error.message}`
+ * )
+ * ```
+ */
+export declare const match: <T, E, R>(result: Result<T, E>, on_ok: (value: T) => R, on_err: (error: E) => R) => R;
+/**
+ * Extract value from Result, returning default if error.
+ *
+ * @param result - The Result to unwrap
+ * @param default_value - Value to return if Result is an error
+ * @returns The success value or default
+ *
+ * @example
+ * ```ts
+ * const users = unwrap_or(await fetchUsers(), [])
+ * ```
+ */
+export declare const unwrap_or: <T, E>(result: Result<T, E>, default_value: T) => T;
+/**
+ * Extract value from Result, throwing if error.
+ * Use only when you're certain the Result is Ok, or in tests.
+ *
+ * @param result - The Result to unwrap
+ * @returns The success value
+ * @throws Error if Result is an error
+ *
+ * @example
+ * ```ts
+ * // In tests
+ * const user = unwrap(await createUser(data))
+ * expect(user.name).toBe('Alice')
+ * ```
+ */
+export declare const unwrap: <T, E>(result: Result<T, E>) => T;
+/**
+ * Extract error from Result, throwing if Ok.
+ * Use only when you're certain the Result is Err, or in tests.
+ *
+ * @param result - The Result to unwrap
+ * @returns The error value
+ * @throws Error if Result is Ok
+ *
+ * @example
+ * ```ts
+ * // In tests
+ * const error = unwrap_err(await createUser(invalidData))
+ * expect(error.kind).toBe('validation_error')
+ * ```
+ */
+export declare const unwrap_err: <T, E>(result: Result<T, E>) => E;
+/**
+ * Execute a function and convert exceptions to Result.
+ *
+ * @param fn - Function to execute
+ * @param on_error - Transform caught exception to error type
+ * @returns Result containing success value or transformed error
+ *
+ * @example
+ * ```ts
+ * const result = try_catch(
+ *   () => JSON.parse(input),
+ *   e => ({ kind: 'parse_error', message: format_error(e) })
+ * )
+ * ```
+ */
+export declare const try_catch: <T, E>(fn: () => T, on_error: (e: unknown) => E) => Result<T, E>;
+/**
+ * Execute an async function and convert exceptions to Result.
+ *
+ * @param fn - Async function to execute
+ * @param on_error - Transform caught exception to error type
+ * @returns Promise of Result containing success value or transformed error
+ *
+ * @example
+ * ```ts
+ * const result = await try_catch_async(
+ *   () => db.query('SELECT * FROM users'),
+ *   e => ({ kind: 'database_error', cause: e })
+ * )
+ * ```
+ */
+export declare const try_catch_async: <T, E>(fn: () => Promise<T>, on_error: (e: unknown) => E) => Promise<Result<T, E>>;
+/**
+ * Error types for fetch operations.
+ */
+export type FetchError = {
+    type: "network";
+    cause: unknown;
+} | {
+    type: "http";
+    status: number;
+    status_text: string;
+};
+/**
+ * Fetch wrapper that returns Result instead of throwing.
+ *
+ * @param input - URL or Request to fetch
+ * @param init - Fetch options
+ * @param on_error - Transform FetchError to your error type
+ * @param parse_body - Custom body parser (defaults to JSON)
+ * @returns Promise of Result with parsed response or error
+ *
+ * @example
+ * ```ts
+ * const result = await fetch_result(
+ *   'https://api.example.com/users',
+ *   { headers: { Authorization: `Bearer ${token}` } },
+ *   e => e.type === 'http' ? `HTTP ${e.status}` : 'Network error'
+ * )
+ * ```
+ */
+export declare const fetch_result: <T, E>(input: string | URL | Request, init: RequestInit | undefined, on_error: (e: FetchError) => E, parse_body?: (response: Response) => Promise<T>) => Promise<Result<T, E>>;
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * A composable pipeline for chaining Result operations.
+ *
+ * All operations are lazy - nothing executes until `.result()` or `.unwrap_or()` is called.
+ *
+ * @example
+ * ```ts
+ * const user = await pipe(fetchUser(id))
+ *   .map(user => user.profile)
+ *   .flat_map(profile => fetchAvatar(profile.avatar_id))
+ *   .map(avatar => avatar.url)
+ *   .unwrap_or('/default-avatar.png')
+ * ```
+ */
+export type Pipe<T, E> = {
+    /** Transform the success value */
+    map: <U>(fn: (value: T) => U) => Pipe<U, E>;
+    /** Transform the success value with an async function */
+    map_async: <U>(fn: (value: T) => Promise<U>) => Pipe<U, E>;
+    /** Chain with another Result-returning operation */
+    flat_map: <U>(fn: (value: T) => MaybePromise<Result<U, E>>) => Pipe<U, E>;
+    /** Transform the error value */
+    map_err: <F>(fn: (error: E) => F) => Pipe<T, F>;
+    /** Execute side effect on success (logging, metrics) */
+    tap: (fn: (value: T) => MaybePromise<void>) => Pipe<T, E>;
+    /** Execute side effect on error */
+    tap_err: (fn: (error: E) => MaybePromise<void>) => Pipe<T, E>;
+    /** Extract value with fallback */
+    unwrap_or: (default_value: T) => Promise<T>;
+    /** Get the underlying Result */
+    result: () => Promise<Result<T, E>>;
+};
+/**
+ * Create a composable pipeline from a Result or Promise<Result>.
+ *
+ * @param initial - Starting Result value (sync or async)
+ * @returns A Pipe for chaining operations
+ *
+ * @example
+ * ```ts
+ * // From existing Result
+ * const result = await pipe(ok(42))
+ *   .map(n => n * 2)
+ *   .result()
+ *
+ * // From async operation
+ * const user = await pipe(fetchUser(id))
+ *   .flat_map(u => fetchProfile(u.id))
+ *   .result()
+ * ```
+ */
+export declare const pipe: {
+    <T, E>(initial: MaybePromise<Result<T, E>>): Pipe<T, E>;
+    ok<T>(value: T): Pipe<T, never>;
+    err<E>(error: E): Pipe<never, E>;
+    try<T, E>(fn: () => Promise<T>, on_error: (e: unknown) => E): Pipe<T, E>;
+    fetch<T, E>(input: string | URL | Request, init: RequestInit | undefined, on_error: (e: FetchError) => E, parse_body?: (response: Response) => Promise<T>): Pipe<T, E>;
+};
+/**
+ * Extract value from Result, returning null for any error.
+ * Use for "fetch single resource" patterns where not-found is expected.
+ *
+ * @param result - The Result to convert
+ * @returns The value or null
+ *
+ * @example
+ * ```ts
+ * const user = to_nullable(await store.get(userId))
+ * if (!user) return <NotFound />
+ * ```
+ */
+export declare const to_nullable: <T, E>(result: Result<T, E>) => T | null;
+/**
+ * Extract value from Result, returning fallback for any error.
+ * Use for list endpoints where empty array is acceptable.
+ *
+ * @param result - The Result to convert
+ * @param fallback - Value to return on error
+ * @returns The value or fallback
+ *
+ * @example
+ * ```ts
+ * const items = to_fallback(await store.list(), [])
+ * ```
+ */
+export declare const to_fallback: <T, E>(result: Result<T, E>, fallback: T) => T;
+/**
+ * Return null if error matches predicate, otherwise throw the error.
+ * Use for 404-as-null pattern specifically.
+ *
+ * @param result - The Result to check
+ * @param predicate - Returns true for expected errors (e.g., not_found)
+ * @returns The value or null for expected errors
+ * @throws The error if predicate returns false
+ *
+ * @example
+ * ```ts
+ * const user = null_on(
+ *   await store.get(id),
+ *   e => e.kind === 'not_found'
+ * )
+ * ```
+ */
+export declare const null_on: <T, E>(result: Result<T, E>, predicate: (error: E) => boolean) => T | null;
+/**
+ * Return fallback if error matches predicate, otherwise throw.
+ *
+ * @param result - The Result to check
+ * @param predicate - Returns true for expected errors
+ * @param fallback - Value to return for expected errors
+ * @returns The value or fallback for expected errors
+ * @throws The error if predicate returns false
+ *
+ * @example
+ * ```ts
+ * const count = fallback_on(
+ *   await store.count(),
+ *   e => e.kind === 'not_found',
+ *   0
+ * )
+ * ```
+ */
+export declare const fallback_on: <T, E>(result: Result<T, E>, predicate: (error: E) => boolean, fallback: T) => T;
+/**
+ * Format an unknown error to a string message.
+ *
+ * @param e - Any error value
+ * @returns A string representation
+ *
+ * @example
+ * ```ts
+ * try {
+ *   riskyOperation()
+ * } catch (e) {
+ *   console.error(format_error(e)) // Handles Error, string, or anything
+ * }
+ * ```
+ */
+export declare const format_error: (e: unknown) => string;
+/**
+ * Recursively makes all properties of T optional.
+ *
+ * @example
+ * ```ts
+ * type Config = { api: { url: string; timeout: number } }
+ * type PartialConfig = DeepPartial<Config>
+ * // { api?: { url?: string; timeout?: number } }
+ * ```
+ */
+export type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+/**
+ * Deep merge two objects, with overrides taking precedence.
+ * Only merges plain objects; arrays and null are replaced entirely.
+ *
+ * @param base - The base object to merge into
+ * @param overrides - Partial object with values to override
+ * @returns A new object with merged values
+ *
+ * @example
+ * ```ts
+ * const config = merge_deep(
+ *   { api: { url: 'http://localhost', timeout: 5000 }, debug: false },
+ *   { api: { timeout: 10000 } }
+ * )
+ * // { api: { url: 'http://localhost', timeout: 10000 }, debug: false }
+ * ```
+ */
+export declare const merge_deep: <T extends Record<string, unknown>>(base: T, overrides: DeepPartial<T>) => T;
+/**
+ * Safely access an array element by index, returning a Result.
+ * Unlike bracket notation, this never returns undefined for out-of-bounds access.
+ *
+ * @param array - The array to access
+ * @param index - The index to retrieve (must be non-negative)
+ * @returns Result containing the element or an index_out_of_bounds error
+ *
+ * @example
+ * ```ts
+ * const items = ['a', 'b', 'c']
+ * const second = at(items, 1)   // { ok: true, value: 'b' }
+ * const tenth = at(items, 10)   // { ok: false, error: { kind: 'index_out_of_bounds', index: 10, length: 3 } }
+ * ```
+ */
+export declare const at: <T>(array: readonly T[], index: number) => Result<T, {
+    kind: "index_out_of_bounds";
+    index: number;
+    length: number;
+}>;
+/**
+ * Safely get the first element of an array.
+ *
+ * @param array - The array to access
+ * @returns Result containing the first element or an empty_array error
+ *
+ * @example
+ * ```ts
+ * const head = first([1, 2, 3])  // { ok: true, value: 1 }
+ * const empty = first([])        // { ok: false, error: { kind: 'empty_array' } }
+ * ```
+ */
+export declare const first: <T>(array: readonly T[]) => Result<T, {
+    kind: "empty_array";
+}>;
+/**
+ * Safely get the last element of an array.
+ *
+ * @param array - The array to access
+ * @returns Result containing the last element or an empty_array error
+ *
+ * @example
+ * ```ts
+ * const tail = last([1, 2, 3])  // { ok: true, value: 3 }
+ * const empty = last([])        // { ok: false, error: { kind: 'empty_array' } }
+ * ```
+ */
+export declare const last: <T>(array: readonly T[]) => Result<T, {
+    kind: "empty_array";
+}>;
+export {};
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../result.ts"],"names":[],"mappings":"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"}