@f0rbit/corpus 0.1.8 → 0.2.0

package/dist/result.d.ts

@@ -0,0 +1,280 @@
+/**
+ * @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;
+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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"}

package/dist/result.js

@@ -0,0 +1,319 @@
+/**
+ * @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 { ok, err } 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 const match = (result, on_ok, on_err) => {
+    if (result.ok)
+        return on_ok(result.value);
+    return on_err(result.error);
+};
+/**
+ * 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 const unwrap_or = (result, default_value) => (result.ok ? result.value : default_value);
+/**
+ * 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 const unwrap = (result) => {
+    if (!result.ok)
+        throw new Error(`unwrap called on error result: ${JSON.stringify(result.error)}`);
+    return result.value;
+};
+/**
+ * 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 const unwrap_err = (result) => {
+    if (result.ok)
+        throw new Error(`unwrap_err called on ok result: ${JSON.stringify(result.value)}`);
+    return result.error;
+};
+/**
+ * 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 const try_catch = (fn, on_error) => {
+    try {
+        return ok(fn());
+    }
+    catch (e) {
+        return err(on_error(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 const try_catch_async = async (fn, on_error) => {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        return err(on_error(e));
+    }
+};
+/**
+ * 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 const fetch_result = async (input, init, on_error, parse_body = r => r.json()) => {
+    try {
+        const response = await fetch(input, init);
+        if (!response.ok) {
+            return err(on_error({ type: "http", status: response.status, status_text: response.statusText }));
+        }
+        return ok(await parse_body(response));
+    }
+    catch (e) {
+        return err(on_error({ type: "network", cause: e }));
+    }
+};
+const create_pipe = (promised) => ({
+    map: (fn) => create_pipe(promised.then((r) => {
+        if (r.ok)
+            return ok(fn(r.value));
+        return err(r.error);
+    })),
+    map_async: (fn) => create_pipe(promised.then(async (r) => {
+        if (r.ok)
+            return ok(await fn(r.value));
+        return err(r.error);
+    })),
+    flat_map: (fn) => create_pipe(promised.then((r) => {
+        if (r.ok)
+            return fn(r.value);
+        return err(r.error);
+    })),
+    map_err: (fn) => create_pipe(promised.then((r) => {
+        if (r.ok)
+            return ok(r.value);
+        return err(fn(r.error));
+    })),
+    tap: (fn) => create_pipe(promised.then(async (r) => {
+        if (r.ok)
+            await fn(r.value);
+        return r;
+    })),
+    tap_err: (fn) => create_pipe(promised.then(async (r) => {
+        if (!r.ok)
+            await fn(r.error);
+        return r;
+    })),
+    unwrap_or: (default_value) => promised.then(r => (r.ok ? r.value : default_value)),
+    result: () => promised,
+});
+/**
+ * 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 const pipe = (initial) => create_pipe(Promise.resolve(initial));
+/** Create a pipe starting with an Ok value */
+pipe.ok = (value) => pipe(ok(value));
+/** Create a pipe starting with an Err value */
+pipe.err = (error) => pipe(err(error));
+/** Create a pipe from a function that may throw */
+pipe.try = (fn, on_error) => pipe(try_catch_async(fn, on_error));
+/** Create a pipe from a fetch operation */
+pipe.fetch = (input, init, on_error, parse_body) => pipe(fetch_result(input, init, on_error, parse_body));
+/**
+ * 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 const to_nullable = (result) => (result.ok ? result.value : 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 const to_fallback = (result, fallback) => (result.ok ? result.value : fallback);
+/**
+ * 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 const null_on = (result, predicate) => {
+    if (result.ok)
+        return result.value;
+    if (predicate(result.error))
+        return null;
+    throw result.error;
+};
+/**
+ * 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 const fallback_on = (result, predicate, fallback) => {
+    if (result.ok)
+        return result.value;
+    if (predicate(result.error))
+        return fallback;
+    throw result.error;
+};
+/**
+ * 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 const format_error = (e) => (e instanceof Error ? e.message : String(e));

package/dist/types.d.ts

@@ -214,10 +214,12 @@ export type Snapshot<T = unknown> = {
     meta: SnapshotMeta;
     data: T;
 };
+/** @internal */
 export type DataHandle = {
     stream: () => ReadableStream<Uint8Array>;
     bytes: () => Promise<Uint8Array>;
 };
+/** @internal */
 export type MetadataClient = {
     get: (store_id: string, version: string) => Promise<Result<SnapshotMeta, CorpusError>>;
     put: (meta: SnapshotMeta) => Promise<Result<void, CorpusError>>;
@@ -227,6 +229,7 @@ export type MetadataClient = {
     get_children: (parent_store_id: string, parent_version: string) => AsyncIterable<SnapshotMeta>;
     find_by_hash: (store_id: string, content_hash: string) => Promise<SnapshotMeta | null>;
 };
+/** @internal */
 export type DataClient = {
     get: (data_key: string) => Promise<Result<DataHandle, CorpusError>>;
     put: (data_key: string, data: ReadableStream<Uint8Array> | Uint8Array) => Promise<Result<void, CorpusError>>;
@@ -301,6 +304,34 @@ export type Codec<T> = {
     encode: (value: T) => Uint8Array;
     decode: (bytes: Uint8Array) => T;
 };
+/**
+ * Structural type for schema validators (Zod, Valibot, or custom).
+ *
+ * Any object with a `parse(data: unknown) => T` method satisfies this interface.
+ * Used by `json_codec()` to validate data on decode without importing a specific library.
+ *
+ * @category Types
+ * @group Codec Types
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * // Zod schemas satisfy Parser<T>
+ * const UserSchema = z.object({ name: z.string() })
+ * const codec = json_codec(UserSchema) // works!
+ *
+ * // Custom parsers work too
+ * const myParser: Parser<number> = {
+ *   parse: (data) => {
+ *     if (typeof data !== 'number') throw new Error('Expected number')
+ *     return data
+ *   }
+ * }
+ * ```
+ */
+export type Parser<T> = {
+    parse: (data: unknown) => T;
+};
 /**
  * A typed store for managing versioned data snapshots.
  *
@@ -335,6 +366,7 @@ export type PutOpts = {
 };
 /**
  * Context passed to data_key_fn for generating custom storage paths.
+ * @internal
  */
 export type DataKeyContext = {
     store_id: string;
@@ -397,6 +429,7 @@ export type DefineStoreOpts = {
  * ```
  */
 export declare function define_store<Id extends string, T>(id: Id, codec: Codec<T>, opts?: DefineStoreOpts | string): StoreDefinition<Id, T>;
+/** @internal */
 export type CorpusBuilder<Stores extends Record<string, Store<any>> = {}> = {
     with_backend: (backend: Backend) => CorpusBuilder<Stores>;
     with_store: <Id extends string, T>(definition: StoreDefinition<Id, T>) => CorpusBuilder<Stores & Record<Id, Store<T>>>;