@f0rbit/corpus 0.1.3 → 0.1.5

package/dist/backend/cloudflare.d.ts

@@ -1,4 +1,8 @@
-import type { Backend, EventHandler } from '../types';
+/**
+ * @module Backends
+ * @description Cloudflare Workers storage backend using D1 and R2.
+ */
+import type { Backend, EventHandler } from "../types";
 type D1Database = {
     prepare: (sql: string) => unknown;
 };
@@ -18,6 +22,42 @@ export type CloudflareBackendConfig = {
     r2: R2Bucket;
     on_event?: EventHandler;
 };
+/**
+ * Creates a Cloudflare Workers storage backend using D1 and R2.
+ * @category Backends
+ * @group Storage Backends
+ *
+ * Uses D1 (SQLite) for metadata storage and R2 (object storage) for binary data.
+ * Requires running `CORPUS_MIGRATION_SQL` on the D1 database before first use.
+ *
+ * This backend is designed for production use in Cloudflare Workers environments,
+ * providing durable, globally distributed storage.
+ *
+ * @param config - Configuration with `d1` (D1 database), `r2` (R2 bucket), and optional `on_event` handler
+ * @returns A Backend instance using Cloudflare D1 + R2
+ *
+ * @example
+ * ```ts
+ * // In a Cloudflare Worker
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const backend = create_cloudflare_backend({
+ *       d1: env.CORPUS_DB,
+ *       r2: env.CORPUS_BUCKET
+ *     })
+ *
+ *     const corpus = create_corpus()
+ *       .with_backend(backend)
+ *       .with_store(define_store('cache', json_codec(CacheSchema)))
+ *       .build()
+ *
+ *     // Use corpus...
+ *   }
+ * }
+ * ```
+ *
+ * @see CORPUS_MIGRATION_SQL for required database setup
+ */
 export declare function create_cloudflare_backend(config: CloudflareBackendConfig): Backend;
 export {};
 //# sourceMappingURL=cloudflare.d.ts.map

package/dist/backend/cloudflare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../backend/cloudflare.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAwF,YAAY,EAAE,MAAM,UAAU,CAAA;AAI3I,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,CAAA;AACvD,KAAK,QAAQ,GAAG;IACd,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;IACnH,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAClF,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;CACvD,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,EAAE,EAAE,UAAU,CAAA;IACd,EAAE,EAAE,QAAQ,CAAA;IACZ,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB,CAAA;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CA8PlF"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../backend/cloudflare.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAwF,YAAY,EAAE,MAAM,UAAU,CAAC;AAI5I,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,CAAC;AACxD,KAAK,QAAQ,GAAG;IACf,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACpH,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnF,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACrC,EAAE,EAAE,UAAU,CAAC;IACf,EAAE,EAAE,QAAQ,CAAC;IACb,QAAQ,CAAC,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CA8OlF"}

package/dist/backend/cloudflare.js

@@ -1,7 +1,47 @@
-import { eq, and, desc, lt, gt, like, sql } from 'drizzle-orm';
-import { drizzle } from 'drizzle-orm/d1';
-import { ok, err } from '../types';
-import { corpus_snapshots } from '../schema';
+/**
+ * @module Backends
+ * @description Cloudflare Workers storage backend using D1 and R2.
+ */
+import { eq, and, desc, lt, gt, like, sql } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/d1";
+import { ok, err } from "../types";
+import { corpus_snapshots } from "../schema";
+/**
+ * Creates a Cloudflare Workers storage backend using D1 and R2.
+ * @category Backends
+ * @group Storage Backends
+ *
+ * Uses D1 (SQLite) for metadata storage and R2 (object storage) for binary data.
+ * Requires running `CORPUS_MIGRATION_SQL` on the D1 database before first use.
+ *
+ * This backend is designed for production use in Cloudflare Workers environments,
+ * providing durable, globally distributed storage.
+ *
+ * @param config - Configuration with `d1` (D1 database), `r2` (R2 bucket), and optional `on_event` handler
+ * @returns A Backend instance using Cloudflare D1 + R2
+ *
+ * @example
+ * ```ts
+ * // In a Cloudflare Worker
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const backend = create_cloudflare_backend({
+ *       d1: env.CORPUS_DB,
+ *       r2: env.CORPUS_BUCKET
+ *     })
+ *
+ *     const corpus = create_corpus()
+ *       .with_backend(backend)
+ *       .with_store(define_store('cache', json_codec(CacheSchema)))
+ *       .build()
+ *
+ *     // Use corpus...
+ *   }
+ * }
+ * ```
+ *
+ * @see CORPUS_MIGRATION_SQL for required database setup
+ */
 export function create_cloudflare_backend(config) {
     const db = drizzle(config.d1);
     const { r2, on_event } = config;
@@ -31,15 +71,15 @@ export function create_cloudflare_backend(config) {
                     .where(and(eq(corpus_snapshots.store_id, store_id), eq(corpus_snapshots.version, version)))
                     .limit(1);
                 const row = rows[0];
-                emit({ type: 'meta_get', store_id, version, found: !!row });
+                emit({ type: "meta_get", store_id, version, found: !!row });
                 if (!row) {
-                    return err({ kind: 'not_found', store_id, version });
+                    return err({ kind: "not_found", store_id, version });
                 }
                 return ok(row_to_meta(row));
             }
             catch (cause) {
-                const error = { kind: 'storage_error', cause: cause, operation: 'metadata.get' };
-                emit({ type: 'error', error });
+                const error = { kind: "storage_error", cause: cause, operation: "metadata.get" };
+                emit({ type: "error", error });
                 return err(error);
             }
         },
@@ -72,26 +112,24 @@ export function create_cloudflare_backend(config) {
                         tags: meta.tags ? JSON.stringify(meta.tags) : null,
                     },
                 });
-                emit({ type: 'meta_put', store_id: meta.store_id, version: meta.version });
+                emit({ type: "meta_put", store_id: meta.store_id, version: meta.version });
                 return ok(undefined);
             }
             catch (cause) {
-                const error = { kind: 'storage_error', cause: cause, operation: 'metadata.put' };
-                emit({ type: 'error', error });
+                const error = { kind: "storage_error", cause: cause, operation: "metadata.put" };
+                emit({ type: "error", error });
                 return err(error);
             }
         },
         async delete(store_id, version) {
             try {
-                await db
-                    .delete(corpus_snapshots)
-                    .where(and(eq(corpus_snapshots.store_id, store_id), eq(corpus_snapshots.version, version)));
-                emit({ type: 'meta_delete', store_id, version });
+                await db.delete(corpus_snapshots).where(and(eq(corpus_snapshots.store_id, store_id), eq(corpus_snapshots.version, version)));
+                emit({ type: "meta_delete", store_id, version });
                 return ok(undefined);
             }
             catch (cause) {
-                const error = { kind: 'storage_error', cause: cause, operation: 'metadata.delete' };
-                emit({ type: 'error', error });
+                const error = { kind: "storage_error", cause: cause, operation: "metadata.delete" };
+                emit({ type: "error", error });
                 return err(error);
             }
         },
@@ -115,31 +153,26 @@ export function create_cloudflare_backend(config) {
             let count = 0;
             for (const row of rows) {
                 const meta = row_to_meta(row);
-                if (opts?.tags?.length && !opts.tags.some(t => meta.tags?.includes(t))) {
+                if (opts?.tags?.length && !opts.tags.every(t => meta.tags?.includes(t))) {
                     continue;
                 }
                 yield meta;
                 count++;
             }
-            emit({ type: 'meta_list', store_id, count });
+            emit({ type: "meta_list", store_id, count });
         },
         async get_latest(store_id) {
             try {
-                const rows = await db
-                    .select()
-                    .from(corpus_snapshots)
-                    .where(eq(corpus_snapshots.store_id, store_id))
-                    .orderBy(desc(corpus_snapshots.created_at))
-                    .limit(1);
+                const rows = await db.select().from(corpus_snapshots).where(eq(corpus_snapshots.store_id, store_id)).orderBy(desc(corpus_snapshots.created_at)).limit(1);
                 const row = rows[0];
                 if (!row) {
-                    return err({ kind: 'not_found', store_id, version: 'latest' });
+                    return err({ kind: "not_found", store_id, version: "latest" });
                 }
                 return ok(row_to_meta(row));
             }
             catch (cause) {
-                const error = { kind: 'storage_error', cause: cause, operation: 'metadata.get_latest' };
-                emit({ type: 'error', error });
+                const error = { kind: "storage_error", cause: cause, operation: "metadata.get_latest" };
+                emit({ type: "error", error });
                 return err(error);
             }
         },
@@ -175,9 +208,9 @@ export function create_cloudflare_backend(config) {
         async get(data_key) {
             try {
                 const object = await r2.get(data_key);
-                emit({ type: 'data_get', store_id: data_key.split('/')[0] ?? data_key, version: data_key, found: !!object });
+                emit({ type: "data_get", store_id: data_key.split("/")[0] ?? data_key, version: data_key, found: !!object });
                 if (!object) {
-                    return err({ kind: 'not_found', store_id: data_key, version: '' });
+                    return err({ kind: "not_found", store_id: data_key, version: "" });
                 }
                 return ok({
                     stream: () => object.body,
@@ -185,8 +218,8 @@ export function create_cloudflare_backend(config) {
                 });
             }
             catch (cause) {
-                const error = { kind: 'storage_error', cause: cause, operation: 'data.get' };
-                emit({ type: 'error', error });
+                const error = { kind: "storage_error", cause: cause, operation: "data.get" };
+                emit({ type: "error", error });
                 return err(error);
             }
         },
@@ -196,8 +229,8 @@ export function create_cloudflare_backend(config) {
                 return ok(undefined);
             }
             catch (cause) {
-                const error = { kind: 'storage_error', cause: cause, operation: 'data.put' };
-                emit({ type: 'error', error });
+                const error = { kind: "storage_error", cause: cause, operation: "data.put" };
+                emit({ type: "error", error });
                 return err(error);
             }
         },
@@ -207,8 +240,8 @@ export function create_cloudflare_backend(config) {
                 return ok(undefined);
             }
             catch (cause) {
-                const error = { kind: 'storage_error', cause: cause, operation: 'data.delete' };
-                emit({ type: 'error', error });
+                const error = { kind: "storage_error", cause: cause, operation: "data.delete" };
+                emit({ type: "error", error });
                 return err(error);
             }
         },

package/dist/backend/file.d.ts

@@ -1,7 +1,42 @@
-import type { Backend, EventHandler } from '../types';
+/**
+ * @module Backends
+ * @description File-system storage backend for local persistence.
+ */
+import type { Backend, EventHandler } from "../types";
 export type FileBackendConfig = {
     base_path: string;
     on_event?: EventHandler;
 };
+/**
+ * Creates a file-system storage backend for local persistence.
+ * @category Backends
+ * @group Storage Backends
+ *
+ * Uses Bun's file APIs for efficient I/O. Metadata is stored as JSON files
+ * per store, and data is stored as binary files in a shared `_data` directory.
+ *
+ * Directory structure:
+ * ```
+ * base_path/
+ *   <store_id>/_meta.json     # Metadata for each store
+ *   _data/<store_id>_<hash>.bin  # Binary data files
+ * ```
+ *
+ * @param config - Configuration with `base_path` (root directory) and optional `on_event` handler
+ * @returns A Backend instance using file-system storage
+ *
+ * @example
+ * ```ts
+ * const backend = create_file_backend({
+ *   base_path: './data/corpus',
+ *   on_event: (e) => console.log(e.type)
+ * })
+ *
+ * const corpus = create_corpus()
+ *   .with_backend(backend)
+ *   .with_store(define_store('documents', json_codec(DocSchema)))
+ *   .build()
+ * ```
+ */
 export declare function create_file_backend(config: FileBackendConfig): Backend;
 //# sourceMappingURL=file.d.ts.map

package/dist/backend/file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../backend/file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAwF,YAAY,EAAE,MAAM,UAAU,CAAA;AAK3I,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB,CAAA;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAqMtE"}
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../backend/file.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAwF,YAAY,EAAE,MAAM,UAAU,CAAC;AAK5I,MAAM,MAAM,iBAAiB,GAAG;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAkMtE"}

package/dist/backend/file.js

@@ -1,26 +1,61 @@
-import { ok, err } from '../types';
-import { mkdir, readdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+/**
+ * @module Backends
+ * @description File-system storage backend for local persistence.
+ */
+import { ok, err } from "../types";
+import { mkdir, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+/**
+ * Creates a file-system storage backend for local persistence.
+ * @category Backends
+ * @group Storage Backends
+ *
+ * Uses Bun's file APIs for efficient I/O. Metadata is stored as JSON files
+ * per store, and data is stored as binary files in a shared `_data` directory.
+ *
+ * Directory structure:
+ * ```
+ * base_path/
+ *   <store_id>/_meta.json     # Metadata for each store
+ *   _data/<store_id>_<hash>.bin  # Binary data files
+ * ```
+ *
+ * @param config - Configuration with `base_path` (root directory) and optional `on_event` handler
+ * @returns A Backend instance using file-system storage
+ *
+ * @example
+ * ```ts
+ * const backend = create_file_backend({
+ *   base_path: './data/corpus',
+ *   on_event: (e) => console.log(e.type)
+ * })
+ *
+ * const corpus = create_corpus()
+ *   .with_backend(backend)
+ *   .with_store(define_store('documents', json_codec(DocSchema)))
+ *   .build()
+ * ```
+ */
 export function create_file_backend(config) {
     const { base_path, on_event } = config;
     function emit(event) {
         on_event?.(event);
     }
     function meta_path(store_id) {
-        return join(base_path, store_id, '_meta.json');
+        return join(base_path, store_id, "_meta.json");
     }
     function data_path(data_key) {
-        return join(base_path, '_data', `${data_key.replace(/\//g, '_')}.bin`);
+        return join(base_path, "_data", `${data_key.replace(/\//g, "_")}.bin`);
     }
     async function read_store_meta(store_id) {
         const path = meta_path(store_id);
         const file = Bun.file(path);
-        if (!await file.exists())
+        if (!(await file.exists()))
             return new Map();
         try {
             const content = await file.text();
             const entries = JSON.parse(content, (key, value) => {
-                if (key === 'created_at' || key === 'invoked_at') {
+                if (key === "created_at" || key === "invoked_at") {
                     return value ? new Date(value) : value;
                 }
                 return value;
@@ -41,9 +76,9 @@ export function create_file_backend(config) {
         async get(store_id, version) {
             const store_meta = await read_store_meta(store_id);
             const meta = store_meta.get(version);
-            emit({ type: 'meta_get', store_id, version, found: !!meta });
+            emit({ type: "meta_get", store_id, version, found: !!meta });
             if (!meta) {
-                return err({ kind: 'not_found', store_id, version });
+                return err({ kind: "not_found", store_id, version });
             }
             return ok(meta);
         },
@@ -51,14 +86,14 @@ export function create_file_backend(config) {
             const store_meta = await read_store_meta(meta.store_id);
             store_meta.set(meta.version, meta);
             await write_store_meta(meta.store_id, store_meta);
-            emit({ type: 'meta_put', store_id: meta.store_id, version: meta.version });
+            emit({ type: "meta_put", store_id: meta.store_id, version: meta.version });
             return ok(undefined);
         },
         async delete(store_id, version) {
             const store_meta = await read_store_meta(store_id);
             store_meta.delete(version);
             await write_store_meta(store_id, store_meta);
-            emit({ type: 'meta_delete', store_id, version });
+            emit({ type: "meta_delete", store_id, version });
             return ok(undefined);
         },
         async *list(store_id, opts) {
@@ -69,7 +104,7 @@ export function create_file_backend(config) {
                     return false;
                 if (opts?.after && meta.created_at <= opts.after)
                     return false;
-                if (opts?.tags?.length && !opts.tags.some(t => meta.tags?.includes(t)))
+                if (opts?.tags?.length && !opts.tags.every(t => meta.tags?.includes(t)))
                     return false;
                 return true;
             })
@@ -80,7 +115,7 @@ export function create_file_backend(config) {
                 yield meta;
                 count++;
             }
-            emit({ type: 'meta_list', store_id, count });
+            emit({ type: "meta_list", store_id, count });
         },
         async get_latest(store_id) {
             const store_meta = await read_store_meta(store_id);
@@ -91,7 +126,7 @@ export function create_file_backend(config) {
                 }
             }
             if (!latest) {
-                return err({ kind: 'not_found', store_id, version: 'latest' });
+                return err({ kind: "not_found", store_id, version: "latest" });
             }
             return ok(latest);
         },
@@ -99,7 +134,7 @@ export function create_file_backend(config) {
             try {
                 const entries = await readdir(base_path, { withFileTypes: true });
                 for (const entry of entries) {
-                    if (!entry.isDirectory() || entry.name.startsWith('_'))
+                    if (!entry.isDirectory() || entry.name.startsWith("_"))
                         continue;
                     const store_meta = await read_store_meta(entry.name);
                     for (const meta of store_meta.values()) {
@@ -109,8 +144,7 @@ export function create_file_backend(config) {
                     }
                 }
             }
-            catch {
-            }
+            catch { }
         },
         async find_by_hash(store_id, content_hash) {
             const store_meta = await read_store_meta(store_id);
@@ -127,9 +161,9 @@ export function create_file_backend(config) {
             const path = data_path(data_key);
             const file = Bun.file(path);
             const found = await file.exists();
-            emit({ type: 'data_get', store_id: data_key.split('/')[0] ?? data_key, version: data_key, found });
+            emit({ type: "data_get", store_id: data_key.split("/")[0] ?? data_key, version: data_key, found });
             if (!found) {
-                return err({ kind: 'not_found', store_id: data_key, version: '' });
+                return err({ kind: "not_found", store_id: data_key, version: "" });
             }
             return ok({
                 stream: () => file.stream(),
@@ -158,7 +192,7 @@ export function create_file_backend(config) {
                 return ok(undefined);
             }
             catch (cause) {
-                return err({ kind: 'storage_error', cause: cause, operation: 'put' });
+                return err({ kind: "storage_error", cause: cause, operation: "put" });
             }
         },
         async delete(data_key) {
@@ -171,7 +205,7 @@ export function create_file_backend(config) {
                 return ok(undefined);
             }
             catch (cause) {
-                return err({ kind: 'storage_error', cause: cause, operation: 'delete' });
+                return err({ kind: "storage_error", cause: cause, operation: "delete" });
             }
         },
         async exists(data_key) {

package/dist/backend/layered.d.ts

@@ -1,8 +1,46 @@
+/**
+ * @module Backends
+ * @description Layered backend for caching and replication strategies.
+ */
 import type { Backend } from '../types';
 export type LayeredBackendOptions = {
     read: Backend[];
     write: Backend[];
     list_strategy?: 'merge' | 'first';
 };
+/**
+ * Creates a layered backend that combines multiple backends with read/write separation.
+ * @category Backends
+ * @group Composite Backends
+ *
+ * Read operations use fallback: tries each read backend in order until one succeeds.
+ * Write operations use fanout: writes to all write backends (fails if any fail).
+ *
+ * Common use cases:
+ * - **Caching**: Memory backend first for reads, file backend for persistence
+ * - **Replication**: Write to multiple backends for redundancy
+ * - **Migration**: Read from old + new backends, write only to new
+ *
+ * @param options - Configuration with `read` backends (tried in order), `write` backends (all receive writes), and optional `list_strategy` ('merge' or 'first')
+ * @returns A Backend that delegates to the configured backends
+ *
+ * @example
+ * ```ts
+ * // Caching layer: memory cache with file persistence
+ * const cache = create_memory_backend()
+ * const storage = create_file_backend({ base_path: './data' })
+ *
+ * const backend = create_layered_backend({
+ *   read: [cache, storage],   // Try cache first, fall back to disk
+ *   write: [cache, storage],  // Write to both
+ * })
+ *
+ * // Migration: read from old and new, write only to new
+ * const backend = create_layered_backend({
+ *   read: [newBackend, oldBackend],
+ *   write: [newBackend],
+ * })
+ * ```
+ */
 export declare function create_layered_backend(options: LayeredBackendOptions): Backend;
 //# sourceMappingURL=layered.d.ts.map

package/dist/backend/layered.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layered.d.ts","sourceRoot":"","sources":["../../backend/layered.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA6E,MAAM,UAAU,CAAA;AAGlH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,KAAK,EAAE,OAAO,EAAE,CAAA;IAChB,aAAa,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;CAClC,CAAA;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CA4I9E"}
+{"version":3,"file":"layered.d.ts","sourceRoot":"","sources":["../../backend/layered.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA6E,MAAM,UAAU,CAAA;AAGlH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,KAAK,EAAE,OAAO,EAAE,CAAA;IAChB,aAAa,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;CAClC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CA4I9E"}

package/dist/backend/layered.js

@@ -1,4 +1,42 @@
+/**
+ * @module Backends
+ * @description Layered backend for caching and replication strategies.
+ */
 import { ok, err } from '../types';
+/**
+ * Creates a layered backend that combines multiple backends with read/write separation.
+ * @category Backends
+ * @group Composite Backends
+ *
+ * Read operations use fallback: tries each read backend in order until one succeeds.
+ * Write operations use fanout: writes to all write backends (fails if any fail).
+ *
+ * Common use cases:
+ * - **Caching**: Memory backend first for reads, file backend for persistence
+ * - **Replication**: Write to multiple backends for redundancy
+ * - **Migration**: Read from old + new backends, write only to new
+ *
+ * @param options - Configuration with `read` backends (tried in order), `write` backends (all receive writes), and optional `list_strategy` ('merge' or 'first')
+ * @returns A Backend that delegates to the configured backends
+ *
+ * @example
+ * ```ts
+ * // Caching layer: memory cache with file persistence
+ * const cache = create_memory_backend()
+ * const storage = create_file_backend({ base_path: './data' })
+ *
+ * const backend = create_layered_backend({
+ *   read: [cache, storage],   // Try cache first, fall back to disk
+ *   write: [cache, storage],  // Write to both
+ * })
+ *
+ * // Migration: read from old and new, write only to new
+ * const backend = create_layered_backend({
+ *   read: [newBackend, oldBackend],
+ *   write: [newBackend],
+ * })
+ * ```
+ */
 export function create_layered_backend(options) {
     const { read, write, list_strategy = 'merge' } = options;
     const metadata = {

package/dist/backend/memory.d.ts

@@ -1,6 +1,36 @@
-import type { Backend, EventHandler } from '../types';
+/**
+ * @module Backends
+ * @description In-memory storage backend for testing and development.
+ */
+import type { Backend, EventHandler } from "../types";
 export type MemoryBackendOptions = {
     on_event?: EventHandler;
 };
+/**
+ * Creates an in-memory storage backend.
+ * @category Backends
+ * @group Storage Backends
+ *
+ * Ideal for testing, development, and ephemeral storage scenarios.
+ * All data is lost when the process ends.
+ *
+ * @param options - Optional configuration with `on_event` handler for observability
+ * @returns A Backend instance using in-memory storage
+ *
+ * @example
+ * ```ts
+ * // Basic usage for testing
+ * const backend = create_memory_backend()
+ * const corpus = create_corpus()
+ *   .with_backend(backend)
+ *   .with_store(define_store('test', text_codec()))
+ *   .build()
+ *
+ * // With event logging
+ * const backend = create_memory_backend({
+ *   on_event: (e) => console.log(`[${e.type}]`, e)
+ * })
+ * ```
+ */
 export declare function create_memory_backend(options?: MemoryBackendOptions): Backend;
 //# sourceMappingURL=memory.d.ts.map

package/dist/backend/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../backend/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAwF,YAAY,EAAE,MAAM,UAAU,CAAA;AAG3I,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB,CAAA;AAED,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAiJ7E"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../backend/memory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAwF,YAAY,EAAE,MAAM,UAAU,CAAC;AAG5I,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,CAAC,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAgJ7E"}