@f0rbit/corpus 0.1.3 → 0.1.5

package/dist/sst.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sst.d.ts","sourceRoot":"","sources":["../sst.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAClC,WAAW,CAUb;AAED,eAAO,MAAM,oBAAoB,imBAkBhC,CAAA"}
+{"version":3,"file":"sst.d.ts","sourceRoot":"","sources":["../sst.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAClC,WAAW,CAUb;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,imBAkBhC,CAAA"}

package/dist/sst.js

@@ -1,3 +1,24 @@
+/**
+ * SST infrastructure helper for creating Corpus resources.
+ *
+ * Generates resource names for D1 database and R2 bucket based on a prefix.
+ * Returns objects compatible with SST resource definitions.
+ *
+ * @param name - Base name prefix for resources
+ * @param config - Optional overrides for resource names
+ * @returns Resource definitions with database and bucket names
+ *
+ * @example
+ * ```ts
+ * // In sst.config.ts
+ * const corpus = createCorpusInfra('myapp')
+ *
+ * const db = new sst.cloudflare.D1(corpus.database.name)
+ * const bucket = new sst.cloudflare.R2(corpus.bucket.name)
+ *
+ * // Resource names: 'myappDb', 'myappBucket'
+ * ```
+ */
 export function createCorpusInfra(name, config) {
     const database_name = config?.database_name ?? `${name}Db`;
     const bucket_name = config?.bucket_name ?? `${name}Bucket`;
@@ -8,6 +29,23 @@ export function createCorpusInfra(name, config) {
         bucket_name,
     };
 }
+/**
+ * SQL migration script to create required D1 tables for the Cloudflare backend.
+ *
+ * Must be executed on the D1 database before using `create_cloudflare_backend()`.
+ * Creates the `corpus_snapshots` table and required indexes.
+ *
+ * Safe to run multiple times (uses IF NOT EXISTS).
+ *
+ * @example
+ * ```ts
+ * // Run migration via wrangler
+ * // wrangler d1 execute <database-name> --command "$(cat migration.sql)"
+ *
+ * // Or programmatically in a Worker
+ * await env.CORPUS_DB.exec(CORPUS_MIGRATION_SQL)
+ * ```
+ */
 export const CORPUS_MIGRATION_SQL = `
 CREATE TABLE IF NOT EXISTS corpus_snapshots (
   store_id TEXT NOT NULL,

package/dist/types.d.ts

@@ -1,3 +1,36 @@
+/**
+ * @module Types
+ * @description Type definitions for the corpus library.
+ */
+/**
+ * Error types that can occur during Corpus operations.
+ * @category Types
+ * @group Error Types
+ *
+ * Uses discriminated unions for type-safe error handling via the `kind` field:
+ * - `not_found` - Requested snapshot or data does not exist
+ * - `already_exists` - Attempted to create a snapshot that already exists
+ * - `storage_error` - Backend storage operation failed (includes cause and operation name)
+ * - `decode_error` - Failed to decode data using the store's codec
+ * - `encode_error` - Failed to encode data using the store's codec
+ * - `hash_mismatch` - Content hash verification failed (data corruption)
+ * - `invalid_config` - Configuration error during setup
+ *
+ * @example
+ * ```ts
+ * const result = await store.get('nonexistent')
+ * if (!result.ok) {
+ *   switch (result.error.kind) {
+ *     case 'not_found':
+ *       console.log(`Version ${result.error.version} not found`)
+ *       break
+ *     case 'storage_error':
+ *       console.log(`Storage failed during ${result.error.operation}:`, result.error.cause)
+ *       break
+ *   }
+ * }
+ * ```
+ */
 export type CorpusError = {
     kind: 'not_found';
     store_id: string;
@@ -24,6 +57,11 @@ export type CorpusError = {
     kind: 'invalid_config';
     message: string;
 };
+/**
+ * A discriminated union representing either success or failure.
+ * @category Types
+ * @group Result Types
+ */
 export type Result<T, E = CorpusError> = {
     ok: true;
     value: T;
@@ -31,7 +69,46 @@ export type Result<T, E = CorpusError> = {
     ok: false;
     error: E;
 };
+/**
+ * Creates a successful Result containing a value.
+ *
+ * @category Core
+ * @group Result Helpers
+ * @param value - The success value to wrap
+ * @returns A Result with `ok: true` and the value
+ *
+ * @example
+ * ```ts
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) return err('Division by zero')
+ *   return ok(a / b)
+ * }
+ *
+ * const result = divide(10, 2)
+ * if (result.ok) {
+ *   console.log(result.value) // 5
+ * }
+ * ```
+ */
 export declare const ok: <T>(value: T) => Result<T, never>;
+/**
+ * Creates a failed Result containing an error.
+ *
+ * @category Core
+ * @group Result Helpers
+ * @param error - The error to wrap
+ * @returns A Result with `ok: false` and the error
+ *
+ * @example
+ * ```ts
+ * function parsePositive(s: string): Result<number, string> {
+ *   const n = parseInt(s, 10)
+ *   if (isNaN(n)) return err('Not a number')
+ *   if (n <= 0) return err('Must be positive')
+ *   return ok(n)
+ * }
+ * ```
+ */
 export declare const err: <E>(error: E) => Result<never, E>;
 export type CorpusEvent = {
     type: 'meta_get';
@@ -87,6 +164,32 @@ export type ParentRef = {
     version: string;
     role?: string;
 };
+/**
+ * Metadata about a stored snapshot (without the actual data).
+ *
+ * Key fields:
+ * - `store_id` - Which store this snapshot belongs to
+ * - `version` - Unique, time-sortable identifier for this snapshot
+ * - `content_hash` - SHA-256 hash of the encoded data (enables deduplication)
+ * - `data_key` - Key to retrieve the actual data from the backend
+ * - `parents` - Links to parent snapshots for building data lineage graphs
+ * - `tags` - Optional labels for filtering and organization
+ *
+ * @category Types
+ * @group Snapshot Types
+ * @example
+ * ```ts
+ * const result = await store.put(data, {
+ *   parents: [{ store_id: 'source', version: 'abc123' }],
+ *   tags: ['draft', 'reviewed']
+ * })
+ *
+ * if (result.ok) {
+ *   const meta = result.value
+ *   console.log(`Stored ${meta.size_bytes} bytes as version ${meta.version}`)
+ * }
+ * ```
+ */
 export type SnapshotMeta = {
     store_id: string;
     version: string;
@@ -129,16 +232,83 @@ export type ListOpts = {
     after?: Date;
     tags?: string[];
 };
+/**
+ * Interface that storage backends implement.
+ *
+ * A Backend provides two clients:
+ * - `metadata` - For storing/retrieving snapshot metadata (versions, hashes, etc.)
+ * - `data` - For storing/retrieving the actual binary content
+ *
+ * Built-in backends:
+ * - `create_memory_backend()` - In-memory, ephemeral storage
+ * - `create_file_backend()` - Local filesystem persistence
+ * - `create_cloudflare_backend()` - Cloudflare D1 + R2
+ * - `create_layered_backend()` - Combines multiple backends
+ *
+ * @category Types
+ * @group Backend Types
+ * @example
+ * ```ts
+ * // Custom backend implementation
+ * const myBackend: Backend = {
+ *   metadata: { get, put, delete, list, get_latest, get_children, find_by_hash },
+ *   data: { get, put, delete, exists },
+ *   on_event: (event) => console.log('Event:', event.type)
+ * }
+ * ```
+ */
 export type Backend = {
     metadata: MetadataClient;
     data: DataClient;
     on_event?: EventHandler;
 };
+/**
+ * Serialization interface for encoding/decoding store data.
+ *
+ * A Codec converts between typed values and binary data:
+ * - `encode` - Converts a value to bytes for storage
+ * - `decode` - Converts bytes back to a typed value
+ * - `content_type` - MIME type stored in metadata
+ *
+ * Built-in codecs:
+ * - `json_codec(schema)` - JSON with Zod validation on decode
+ * - `text_codec()` - Plain UTF-8 text
+ * - `binary_codec()` - Raw binary pass-through
+ *
+ * @category Types
+ * @group Codec Types
+ * @example
+ * ```ts
+ * // Custom codec for MessagePack
+ * const msgpack_codec = <T>(schema: ZodSchema<T>): Codec<T> => ({
+ *   content_type: 'application/msgpack',
+ *   encode: (value) => encode(value),
+ *   decode: (bytes) => schema.parse(decode(bytes))
+ * })
+ * ```
+ */
 export type Codec<T> = {
     content_type: ContentType;
     encode: (value: T) => Uint8Array;
     decode: (bytes: Uint8Array) => T;
 };
+/**
+ * A typed store for managing versioned data snapshots.
+ *
+ * Stores provide the main API for reading and writing data:
+ * - `put(data, opts?)` - Store a new snapshot, returns metadata with version
+ * - `get(version)` - Retrieve a specific snapshot by version
+ * - `get_latest()` - Get the most recent snapshot
+ * - `get_meta(version)` - Get just the metadata (without data)
+ * - `list(opts?)` - Iterate over snapshot metadata with filtering
+ * - `delete(version)` - Remove a snapshot's metadata
+ *
+ * Stores automatically deduplicate: storing the same content twice creates
+ * two metadata entries pointing to the same underlying data.
+ *
+ * @category Types
+ * @group Store Types
+ */
 export type Store<T> = {
     readonly id: string;
     readonly codec: Codec<T>;
@@ -154,12 +324,70 @@ export type PutOpts = {
     invoked_at?: Date;
     tags?: string[];
 };
+/**
+ * Context passed to data_key_fn for generating custom storage paths.
+ */
+export type DataKeyContext = {
+    store_id: string;
+    version: string;
+    content_hash: string;
+    tags?: string[];
+};
 export type StoreDefinition<Id extends string, T> = {
     id: Id;
     codec: Codec<T>;
     description?: string;
+    /** Custom function to generate data_key (storage path). If not provided, uses `store_id/content_hash`. */
+    data_key_fn?: (ctx: DataKeyContext) => string;
+};
+export type DefineStoreOpts = {
+    description?: string;
+    /** Custom function to generate data_key (storage path). If not provided, uses `store_id/content_hash`. */
+    data_key_fn?: (ctx: DataKeyContext) => string;
 };
-export declare function define_store<Id extends string, T>(id: Id, codec: Codec<T>, description?: string): StoreDefinition<Id, T>;
+/**
+ * Helper to define a type-safe store definition.
+ *
+ * The `id` becomes the key in `corpus.stores`, providing type-safe access
+ * to the store after building the corpus.
+ *
+ * @category Core
+ * @group Helpers
+ * @param id - Unique identifier for the store (becomes the key in corpus.stores)
+ * @param codec - Serialization codec for the store's data type
+ * @param opts - Optional configuration (description, custom data_key_fn)
+ * @returns A StoreDefinition to pass to `create_corpus().with_store()`
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const PostSchema = z.object({
+ *   title: z.string(),
+ *   body: z.string(),
+ *   published: z.boolean()
+ * })
+ *
+ * const posts = define_store('posts', json_codec(PostSchema), { description: 'Blog posts' })
+ *
+ * // With custom path generation based on tags
+ * const hansard = define_store('hansard', text_codec(), {
+ *   data_key_fn: (ctx) => {
+ *     const date = ctx.tags?.find(t => t.startsWith('date:'))?.slice(5) ?? 'unknown'
+ *     return `australia-house/raw/${date}/${ctx.version}`
+ *   }
+ * })
+ *
+ * const corpus = create_corpus()
+ *   .with_backend(backend)
+ *   .with_store(posts)
+ *   .build()
+ *
+ * // Type-safe: corpus.stores.posts expects Post type
+ * await corpus.stores.posts.put({ title: 'Hello', body: '...', published: true })
+ * ```
+ */
+export declare function define_store<Id extends string, T>(id: Id, codec: Codec<T>, opts?: DefineStoreOpts | string): StoreDefinition<Id, T>;
 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>>>;

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -1,5 +1,94 @@
+/**
+ * @module Types
+ * @description Type definitions for the corpus library.
+ */
+/**
+ * Creates a successful Result containing a value.
+ *
+ * @category Core
+ * @group Result Helpers
+ * @param value - The success value to wrap
+ * @returns A Result with `ok: true` and the value
+ *
+ * @example
+ * ```ts
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) return err('Division by zero')
+ *   return ok(a / b)
+ * }
+ *
+ * const result = divide(10, 2)
+ * if (result.ok) {
+ *   console.log(result.value) // 5
+ * }
+ * ```
+ */
 export const ok = (value) => ({ ok: true, value });
+/**
+ * Creates a failed Result containing an error.
+ *
+ * @category Core
+ * @group Result Helpers
+ * @param error - The error to wrap
+ * @returns A Result with `ok: false` and the error
+ *
+ * @example
+ * ```ts
+ * function parsePositive(s: string): Result<number, string> {
+ *   const n = parseInt(s, 10)
+ *   if (isNaN(n)) return err('Not a number')
+ *   if (n <= 0) return err('Must be positive')
+ *   return ok(n)
+ * }
+ * ```
+ */
 export const err = (error) => ({ ok: false, error });
-export function define_store(id, codec, description) {
-    return { id, codec, description };
+/**
+ * Helper to define a type-safe store definition.
+ *
+ * The `id` becomes the key in `corpus.stores`, providing type-safe access
+ * to the store after building the corpus.
+ *
+ * @category Core
+ * @group Helpers
+ * @param id - Unique identifier for the store (becomes the key in corpus.stores)
+ * @param codec - Serialization codec for the store's data type
+ * @param opts - Optional configuration (description, custom data_key_fn)
+ * @returns A StoreDefinition to pass to `create_corpus().with_store()`
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const PostSchema = z.object({
+ *   title: z.string(),
+ *   body: z.string(),
+ *   published: z.boolean()
+ * })
+ *
+ * const posts = define_store('posts', json_codec(PostSchema), { description: 'Blog posts' })
+ *
+ * // With custom path generation based on tags
+ * const hansard = define_store('hansard', text_codec(), {
+ *   data_key_fn: (ctx) => {
+ *     const date = ctx.tags?.find(t => t.startsWith('date:'))?.slice(5) ?? 'unknown'
+ *     return `australia-house/raw/${date}/${ctx.version}`
+ *   }
+ * })
+ *
+ * const corpus = create_corpus()
+ *   .with_backend(backend)
+ *   .with_store(posts)
+ *   .build()
+ *
+ * // Type-safe: corpus.stores.posts expects Post type
+ * await corpus.stores.posts.put({ title: 'Hello', body: '...', published: true })
+ * ```
+ */
+export function define_store(id, codec, opts) {
+    // Support old signature: define_store(id, codec, description)
+    if (typeof opts === 'string') {
+        return { id, codec, description: opts };
+    }
+    return { id, codec, description: opts?.description, data_key_fn: opts?.data_key_fn };
 }

package/dist/utils.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @module Utilities
+ * @description Utility functions for hashing, versioning, and codecs.
+ */
+import type { Codec } from "./types";
+/**
+ * Computes the SHA-256 hash of binary data.
+ * @category Utilities
+ * @group Hashing
+ *
+ * Returns a lowercase hexadecimal string (64 characters).
+ * Used internally for content-addressable storage and deduplication.
+ *
+ * @param data - The binary data to hash
+ * @returns A lowercase hex string of the SHA-256 hash
+ *
+ * @example
+ * ```ts
+ * const data = new TextEncoder().encode('Hello, world!')
+ * const hash = await compute_hash(data)
+ * // => '315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3'
+ * ```
+ */
+export declare function compute_hash(data: Uint8Array): Promise<string>;
+/**
+ * Generates a unique, time-sortable version string.
+ *
+ * Format: base64url-encoded timestamp, with optional `.N` suffix when multiple
+ * versions are generated within the same millisecond.
+ *
+ * Versions sort lexicographically in chronological order, making them suitable
+ * for use as database keys where ordering matters.
+ *
+ * @category Utilities
+ * @group Versioning
+ * @returns A unique version string like `AZJx4vM` or `AZJx4vM.1`
+ *
+ * @example
+ * ```ts
+ * const v1 = generate_version() // => 'AZJx4vM'
+ * const v2 = generate_version() // => 'AZJx4vM.1' (same millisecond)
+ * const v3 = generate_version() // => 'AZJx4vN' (next millisecond)
+ *
+ * // Versions sort chronologically
+ * [v3, v1, v2].sort() // => [v1, v2, v3]
+ * ```
+ */
+export declare function generate_version(): string;
+type ZodLike<T> = {
+    parse: (data: unknown) => T;
+};
+/**
+ * Creates a JSON codec with schema validation.
+ *
+ * Data is serialized to JSON on encode and validated against the schema on decode.
+ * Works with both Zod 3.x and 4.x (uses structural typing, not Zod imports).
+ *
+ * Note: Validation only happens on decode. Invalid data passed to encode will
+ * serialize but may fail validation when decoded later.
+ *
+ * @category Codecs
+ * @group Codec Factories
+ * @param schema - A Zod schema (or any object with a `parse` method)
+ * @returns A Codec for JSON serialization with validation
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const UserSchema = z.object({
+ *   id: z.string().uuid(),
+ *   name: z.string(),
+ *   createdAt: z.coerce.date()
+ * })
+ *
+ * const codec = json_codec(UserSchema)
+ * const users = define_store('users', codec)
+ *
+ * // Decoding validates and transforms data
+ * const bytes = codec.encode({ id: '...', name: 'Alice', createdAt: '2024-01-01' })
+ * const user = codec.decode(bytes) // createdAt is now a Date object
+ * ```
+ */
+export declare function json_codec<T>(schema: ZodLike<T>): Codec<T>;
+/**
+ * Creates a plain text codec using UTF-8 encoding.
+ *
+ * No validation is performed - any string can be encoded and any valid
+ * UTF-8 bytes can be decoded.
+ *
+ * @category Codecs
+ * @group Codec Factories
+ * @returns A Codec for plain text strings
+ *
+ * @example
+ * ```ts
+ * const notes = define_store('notes', text_codec())
+ *
+ * await corpus.stores.notes.put('Meeting notes for 2024-01-15...')
+ *
+ * const result = await corpus.stores.notes.get_latest()
+ * if (result.ok) {
+ *   console.log(result.value.data) // string
+ * }
+ * ```
+ */
+export declare function text_codec(): Codec<string>;
+/**
+ * Creates a pass-through codec for raw binary data.
+ *
+ * No transformation is performed - bytes are stored and retrieved as-is.
+ * Use for images, PDFs, pre-serialized data, or any binary content.
+ *
+ * @category Codecs
+ * @group Codec Factories
+ * @returns A Codec for raw binary data
+ *
+ * @example
+ * ```ts
+ * const images = define_store('images', binary_codec())
+ *
+ * // Store an image
+ * const imageData = await fetch('photo.png').then(r => r.arrayBuffer())
+ * await corpus.stores.images.put(new Uint8Array(imageData))
+ *
+ * // Store pre-serialized protobuf
+ * const protoBytes = MyMessage.encode(message).finish()
+ * await corpus.stores.images.put(protoBytes)
+ * ```
+ */
+export declare function binary_codec(): Codec<Uint8Array>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAIpE;AAKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CA0BzC;AAGD,KAAK,OAAO,CAAC,CAAC,IAAI;IAAE,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAA;CAAE,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAM1D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC,CAM1C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,IAAI,KAAK,CAAC,UAAU,CAAC,CAMhD"}