@f0rbit/corpus 0.1.9 → 0.2.0

package/dist/concurrency.js

@@ -0,0 +1,108 @@
+/**
+ * @module Concurrency
+ * @description Utilities for controlling concurrent async operations.
+ */
+/**
+ * Semaphore for controlling concurrent operations.
+ *
+ * Limits the number of concurrent async operations by requiring
+ * callers to acquire a permit before proceeding. When all permits
+ * are taken, subsequent acquires wait until a permit is released.
+ *
+ * @example
+ * ```ts
+ * const semaphore = new Semaphore(3) // Allow 3 concurrent operations
+ *
+ * async function rateLimitedFetch(url: string) {
+ *   await semaphore.acquire()
+ *   try {
+ *     return await fetch(url)
+ *   } finally {
+ *     semaphore.release()
+ *   }
+ * }
+ *
+ * // Only 3 fetches will run concurrently
+ * await Promise.all(urls.map(rateLimitedFetch))
+ * ```
+ */
+export class Semaphore {
+    permits;
+    waiting = [];
+    constructor(permits) {
+        this.permits = permits;
+    }
+    /**
+     * Acquire a permit. Resolves immediately if available,
+     * otherwise waits until a permit is released.
+     */
+    async acquire() {
+        if (this.permits > 0) {
+            this.permits--;
+            return;
+        }
+        return new Promise(resolve => {
+            this.waiting.push(resolve);
+        });
+    }
+    /**
+     * Release a permit, allowing the next waiting operation to proceed.
+     */
+    release() {
+        const next = this.waiting.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this.permits++;
+        }
+    }
+}
+/**
+ * Map over array with controlled concurrency.
+ *
+ * Unlike Promise.all which starts all operations at once, this limits
+ * concurrent operations. Results are returned in the same order as inputs.
+ *
+ * @param items - Array of items to process
+ * @param mapper - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent operations
+ * @returns Array of results in the same order as inputs
+ *
+ * @example
+ * ```ts
+ * // Process 100 items, but only 5 at a time
+ * const results = await parallel_map(
+ *   urls,
+ *   async (url, index) => {
+ *     console.log(`Fetching ${index + 1}/${urls.length}`)
+ *     return fetch(url).then(r => r.json())
+ *   },
+ *   5
+ * )
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Use with AI APIs that have rate limits
+ * const summaries = await parallel_map(
+ *   documents,
+ *   doc => summarize(doc),
+ *   3 // Only 3 concurrent API calls
+ * )
+ * ```
+ */
+export const parallel_map = async (items, mapper, concurrency) => {
+    const semaphore = new Semaphore(concurrency);
+    const results = new Array(items.length);
+    await Promise.all(items.map(async (item, index) => {
+        await semaphore.acquire();
+        try {
+            results[index] = await mapper(item, index);
+        }
+        finally {
+            semaphore.release();
+        }
+    }));
+    return results;
+};

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-export { create_corpus, create_store } from './corpus';
-export { create_memory_backend, type MemoryBackendOptions } from './backend/memory';
-export { create_file_backend, type FileBackendConfig } from './backend/file';
-export { create_cloudflare_backend, type CloudflareBackendConfig } from './backend/cloudflare';
-export { create_layered_backend, type LayeredBackendOptions } from './backend/layered';
-export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from './utils';
-export { corpus_snapshots, type CorpusSnapshotRow, type CorpusSnapshotInsert } from './schema';
-export type { ContentType, ParentRef, SnapshotMeta, Snapshot, DataHandle, MetadataClient, DataClient, ListOpts, Backend, Codec, Store, StoreDefinition, DefineStoreOpts, DataKeyContext, PutOpts, CorpusBuilder, Corpus, CorpusError, Result, CorpusEvent, EventHandler, ObservationsClient, } from './types';
-export { ok, err, define_store } from './types';
-export * from './observations';
-export { createCorpusInfra, CORPUS_MIGRATION_SQL, type CorpusInfra, type CorpusInfraConfig } from './sst';
+export { create_corpus, create_store } from "./corpus";
+export { create_memory_backend, type MemoryBackendOptions } from "./backend/memory";
+export { create_file_backend, type FileBackendConfig } from "./backend/file";
+export { create_cloudflare_backend, type CloudflareBackendConfig } from "./backend/cloudflare";
+export { create_layered_backend, type LayeredBackendOptions } from "./backend/layered";
+export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from "./utils";
+export { corpus_snapshots, type CorpusSnapshotRow, type CorpusSnapshotInsert } from "./schema";
+export type { ContentType, ParentRef, SnapshotMeta, Snapshot, DataHandle, MetadataClient, DataClient, ListOpts, Backend, Codec, Parser, Store, StoreDefinition, DefineStoreOpts, DataKeyContext, PutOpts, CorpusBuilder, Corpus, CorpusError, Result, CorpusEvent, EventHandler, ObservationsClient, } from "./types";
+export { ok, err, define_store } from "./types";
+export { match, unwrap_or, unwrap, unwrap_err, try_catch, try_catch_async, fetch_result, pipe, to_nullable, to_fallback, null_on, fallback_on, format_error, type FetchError, type Pipe, } from "./result";
+export { Semaphore, parallel_map } from "./concurrency";
+export * from "./observations";
+export { createCorpusInfra, CORPUS_MIGRATION_SQL, type CorpusInfra, type CorpusInfraConfig } from "./sst";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAC5E,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAEtF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE9F,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE9F,YAAY,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,OAAO,EACP,KAAK,EACL,KAAK,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,OAAO,EACP,aAAa,EACb,MAAM,EACN,WAAW,EACX,MAAM,EACN,WAAW,EACX,YAAY,EACZ,kBAAkB,GACnB,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE/C,cAAc,gBAAgB,CAAA;AAE9B,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEvD,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE/F,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAE/F,YAAY,EACX,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,OAAO,EACP,KAAK,EACL,MAAM,EACN,KAAK,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,OAAO,EACP,aAAa,EACb,MAAM,EACN,WAAW,EACX,MAAM,EACN,WAAW,EACX,YAAY,EACZ,kBAAkB,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEhD,OAAO,EACN,KAAK,EACL,SAAS,EACT,MAAM,EACN,UAAU,EACV,SAAS,EACT,eAAe,EACf,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,WAAW,EACX,OAAO,EACP,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,IAAI,GACT,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAExD,cAAc,gBAAgB,CAAC;AAE/B,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAC"}

package/dist/index.js

@@ -1,10 +1,12 @@
-export { create_corpus, create_store } from './corpus';
-export { create_memory_backend } from './backend/memory';
-export { create_file_backend } from './backend/file';
-export { create_cloudflare_backend } from './backend/cloudflare';
-export { create_layered_backend } from './backend/layered';
-export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from './utils';
-export { corpus_snapshots } from './schema';
-export { ok, err, define_store } from './types';
-export * from './observations';
-export { createCorpusInfra, CORPUS_MIGRATION_SQL } from './sst';
+export { create_corpus, create_store } from "./corpus";
+export { create_memory_backend } from "./backend/memory";
+export { create_file_backend } from "./backend/file";
+export { create_cloudflare_backend } from "./backend/cloudflare";
+export { create_layered_backend } from "./backend/layered";
+export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from "./utils";
+export { corpus_snapshots } from "./schema";
+export { ok, err, define_store } from "./types";
+export { match, unwrap_or, unwrap, unwrap_err, try_catch, try_catch_async, fetch_result, pipe, to_nullable, to_fallback, null_on, fallback_on, format_error, } from "./result";
+export { Semaphore, parallel_map } from "./concurrency";
+export * from "./observations";
+export { createCorpusInfra, CORPUS_MIGRATION_SQL } from "./sst";

package/dist/observations/index.d.ts

@@ -5,7 +5,7 @@
 export * from './types';
 export type { ObservationRow, ObservationInsert } from './schema';
 export { corpus_observations } from './schema';
-export type { ObservationsStorage, StorageQueryOpts, ObservationsCRUD } from './storage';
+export type { ObservationsStorage, StorageQueryOpts, ObservationsCRUD, ObservationsAdapter, ObservationsCRUDBase, ObservationsCRUDOptimized } from './storage';
 export { row_to_observation, row_to_meta, create_observation_row, filter_observation_rows, create_observations_storage } from './storage';
 export { create_observations_client } from './client';
 export * from './utils';

package/dist/observations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../observations/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,SAAS,CAAA;AACvB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAGxF,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAA;AACzI,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAA;AACrD,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../observations/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,SAAS,CAAA;AACvB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA;AAG9J,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAA;AACzI,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAA;AACrD,cAAc,SAAS,CAAA"}

package/dist/observations/storage.d.ts

@@ -58,7 +58,31 @@ export declare function create_observation_row(id: string, type_name: string, so
  */
 export declare function filter_observation_rows(rows: ObservationRow[], opts?: StorageQueryOpts): ObservationRow[];
 /**
- * Simple CRUD interface for observation storage backends.
+ * Base CRUD operations for observation storage backends.
+ * All backends must implement at minimum these operations.
+ */
+export type ObservationsCRUDBase = {
+    get_all: () => Promise<ObservationRow[]>;
+    set_all: (rows: ObservationRow[]) => Promise<void>;
+    get_one: (id: string) => Promise<ObservationRow | null>;
+    add_one: (row: ObservationRow) => Promise<Result<void, CorpusError>>;
+    remove_one: (id: string) => Promise<Result<boolean, CorpusError>>;
+};
+/**
+ * Optional optimized operations for backends with native query capabilities.
+ * When provided, these are used instead of loading all rows into memory.
+ */
+export type ObservationsCRUDOptimized = {
+    query: (opts: StorageQueryOpts) => AsyncIterable<ObservationRow>;
+    delete_by_source: (store_id: string, version: string, path?: string) => Promise<Result<number, CorpusError>>;
+};
+/**
+ * Storage adapter interface for observation backends.
+ * Backends provide base CRUD operations and optionally optimized operations.
+ */
+export type ObservationsAdapter = ObservationsCRUDBase & Partial<ObservationsCRUDOptimized>;
+/**
+ * @deprecated Use ObservationsAdapter instead
  */
 export type ObservationsCRUD = {
     get_all: () => Promise<ObservationRow[]>;
@@ -68,8 +92,13 @@ export type ObservationsCRUD = {
     remove_one: (id: string) => Promise<boolean>;
 };
 /**
- * Create an ObservationsStorage from simple CRUD operations.
- * Used by memory and file backends.
+ * Create an ObservationsStorage from an adapter.
+ *
+ * Backends provide simple CRUD operations and optionally optimized query/delete operations.
+ * When optimized operations are not provided, falls back to loading all rows into memory.
+ *
+ * @param adapter - Storage adapter with base CRUD and optional optimized operations
+ * @returns ObservationsStorage interface for use with create_observations_client
  */
-export declare function create_observations_storage(crud: ObservationsCRUD): ObservationsStorage;
+export declare function create_observations_storage(adapter: ObservationsAdapter | ObservationsCRUD): ObservationsStorage;
 //# sourceMappingURL=storage.d.ts.map

package/dist/observations/storage.d.ts.map

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

package/dist/observations/storage.js

@@ -3,6 +3,7 @@
  * @description Raw storage interface and row conversion utilities for observations.
  */
 import { ok } from '../types';
+import { create_filter_pipeline } from '../utils';
 /**
  * Extract common fields from an observation row (everything except content).
  * Used internally by row_to_observation and row_to_meta.
@@ -63,74 +64,93 @@ export function create_observation_row(id, type_name, source, content, opts) {
         derived_from: opts.derived_from ? JSON.stringify(opts.derived_from) : null
     };
 }
+const observation_filter_pipeline = create_filter_pipeline({
+    filters: [
+        {
+            key: 'type',
+            predicate: (r, type) => {
+                const types = Array.isArray(type) ? type : [type];
+                return types.includes(r.type);
+            }
+        },
+        { key: 'source_store_id', predicate: (r, id) => r.source_store_id === id },
+        { key: 'source_version', predicate: (r, version) => r.source_version === version },
+        { key: 'source_prefix', predicate: (r, prefix) => r.source_version.startsWith(prefix) },
+        { key: 'created_after', predicate: (r, after) => r.created_at > after },
+        { key: 'created_before', predicate: (r, before) => r.created_at < before },
+        { key: 'observed_after', predicate: (r, after) => r.observed_at !== null && r.observed_at > after },
+        { key: 'observed_before', predicate: (r, before) => r.observed_at !== null && r.observed_at < before }
+    ],
+    sort: (a, b) => b.created_at.localeCompare(a.created_at)
+});
 /**
  * Filter and sort observation rows based on query options.
  * Used by in-memory storage implementations (memory backend, file backend).
  */
 export function filter_observation_rows(rows, opts = {}) {
-    let filtered = rows;
-    if (opts.type) {
-        const types = Array.isArray(opts.type) ? opts.type : [opts.type];
-        filtered = filtered.filter(r => types.includes(r.type));
-    }
-    if (opts.source_store_id) {
-        filtered = filtered.filter(r => r.source_store_id === opts.source_store_id);
-    }
-    if (opts.source_version) {
-        filtered = filtered.filter(r => r.source_version === opts.source_version);
-    }
-    if (opts.source_prefix) {
-        filtered = filtered.filter(r => r.source_version.startsWith(opts.source_prefix));
-    }
-    if (opts.created_after) {
-        filtered = filtered.filter(r => r.created_at > opts.created_after);
-    }
-    if (opts.created_before) {
-        filtered = filtered.filter(r => r.created_at < opts.created_before);
-    }
-    if (opts.observed_after) {
-        filtered = filtered.filter(r => r.observed_at && r.observed_at > opts.observed_after);
-    }
-    if (opts.observed_before) {
-        filtered = filtered.filter(r => r.observed_at && r.observed_at < opts.observed_before);
-    }
-    filtered.sort((a, b) => b.created_at.localeCompare(a.created_at));
-    if (opts.limit) {
-        filtered = filtered.slice(0, opts.limit);
-    }
-    return filtered;
+    return observation_filter_pipeline(rows, opts);
 }
 /**
- * Create an ObservationsStorage from simple CRUD operations.
- * Used by memory and file backends.
+ * Create an ObservationsStorage from an adapter.
+ *
+ * Backends provide simple CRUD operations and optionally optimized query/delete operations.
+ * When optimized operations are not provided, falls back to loading all rows into memory.
+ *
+ * @param adapter - Storage adapter with base CRUD and optional optimized operations
+ * @returns ObservationsStorage interface for use with create_observations_client
  */
-export function create_observations_storage(crud) {
+export function create_observations_storage(adapter) {
+    const wrap_add_one = async (row) => {
+        const result = await adapter.add_one(row);
+        if (result === undefined || result === null)
+            return ok(undefined);
+        if (typeof result === 'object' && 'ok' in result)
+            return result;
+        return ok(undefined);
+    };
+    const wrap_remove_one = async (id) => {
+        const result = await adapter.remove_one(id);
+        if (typeof result === 'boolean')
+            return ok(result);
+        if (typeof result === 'object' && 'ok' in result)
+            return result;
+        return ok(false);
+    };
     return {
         async put_row(row) {
-            await crud.add_one(row);
+            const result = await wrap_add_one(row);
+            if (!result.ok)
+                return result;
             return ok(row);
         },
         async get_row(id) {
-            const row = await crud.get_one(id);
+            const row = await adapter.get_one(id);
             return ok(row);
         },
         async *query_rows(opts = {}) {
-            const rows = filter_observation_rows(await crud.get_all(), opts);
-            for (const row of rows) {
-                yield row;
+            if (adapter.query) {
+                yield* adapter.query(opts);
+            }
+            else {
+                const rows = filter_observation_rows(await adapter.get_all(), opts);
+                for (const row of rows) {
+                    yield row;
+                }
             }
         },
         async delete_row(id) {
-            const deleted = await crud.remove_one(id);
-            return ok(deleted);
+            return wrap_remove_one(id);
         },
         async delete_by_source(store_id, version, path) {
-            const rows = await crud.get_all();
+            if (adapter.delete_by_source) {
+                return adapter.delete_by_source(store_id, version, path);
+            }
+            const rows = await adapter.get_all();
             const toKeep = rows.filter(r => !(r.source_store_id === store_id &&
                 r.source_version === version &&
                 (path === undefined || r.source_path === path)));
             const deleted = rows.length - toKeep.length;
-            await crud.set_all(toKeep);
+            await adapter.set_all(toKeep);
             return ok(deleted);
         }
     };

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