@f0rbit/corpus 0.1.3 → 0.1.5

package/dist/utils.js

@@ -0,0 +1,174 @@
+/**
+ * @module Utilities
+ * @description Utility functions for hashing, versioning, and codecs.
+ */
+/**
+ * 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 async function compute_hash(data) {
+    const hash_buffer = await crypto.subtle.digest('SHA-256', data);
+    const hash_array = new Uint8Array(hash_buffer);
+    return Array.from(hash_array).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+let last_timestamp = 0;
+let sequence = 0;
+/**
+ * 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 function generate_version() {
+    const now = Date.now();
+    if (now === last_timestamp) {
+        sequence++;
+    }
+    else {
+        last_timestamp = now;
+        sequence = 0;
+    }
+    // base64url encode the timestamp (no padding, url-safe)
+    const timestamp_bytes = new Uint8Array(8);
+    const view = new DataView(timestamp_bytes.buffer);
+    view.setBigUint64(0, BigInt(now), false); // big-endian for lexicographic sorting
+    // trim leading zeros for compactness
+    let start = 0;
+    while (start < 7 && timestamp_bytes[start] === 0)
+        start++;
+    const trimmed = timestamp_bytes.slice(start);
+    const base64 = btoa(String.fromCharCode(...trimmed))
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+    return sequence > 0 ? `${base64}.${sequence}` : base64;
+}
+/**
+ * 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 function json_codec(schema) {
+    return {
+        content_type: "application/json",
+        encode: (value) => new TextEncoder().encode(JSON.stringify(value)),
+        decode: (bytes) => schema.parse(JSON.parse(new TextDecoder().decode(bytes))),
+    };
+}
+/**
+ * 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 function text_codec() {
+    return {
+        content_type: "text/plain",
+        encode: (value) => new TextEncoder().encode(value),
+        decode: (bytes) => new TextDecoder().decode(bytes),
+    };
+}
+/**
+ * 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 function binary_codec() {
+    return {
+        content_type: "application/octet-stream",
+        encode: (value) => value,
+        decode: (bytes) => bytes,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f0rbit/corpus",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A functional snapshotting library for TypeScript with versioned data storage, lineage tracking, and multiple backend support",
   "module": "dist/index.js",
   "main": "dist/index.js",
@@ -31,7 +31,10 @@
     "build": "tsc -p tsconfig.build.json",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "docs:dev": "cd docs && bun run dev",
+    "docs:build": "cd docs && bun run build",
+    "docs:preview": "cd docs && bun run preview"
   },
   "repository": {
     "type": "git",

package/dist/codec.d.ts

@@ -1,9 +0,0 @@
-import type { Codec } from "./types";
-type ZodLike<T> = {
-    parse: (data: unknown) => T;
-};
-export declare function json_codec<T>(schema: ZodLike<T>): Codec<T>;
-export declare function text_codec(): Codec<string>;
-export declare function binary_codec(): Codec<Uint8Array>;
-export {};
-//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGrC,KAAK,OAAO,CAAC,CAAC,IAAI;IAAE,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAA;CAAE,CAAC;AAElD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAM1D;AAED,wBAAgB,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC,CAM1C;AAED,wBAAgB,YAAY,IAAI,KAAK,CAAC,UAAU,CAAC,CAMhD"}

package/dist/codec.js

@@ -1,21 +0,0 @@
-export function json_codec(schema) {
-    return {
-        content_type: "application/json",
-        encode: (value) => new TextEncoder().encode(JSON.stringify(value)),
-        decode: (bytes) => schema.parse(JSON.parse(new TextDecoder().decode(bytes))),
-    };
-}
-export function text_codec() {
-    return {
-        content_type: "text/plain",
-        encode: (value) => new TextEncoder().encode(value),
-        decode: (bytes) => new TextDecoder().decode(bytes),
-    };
-}
-export function binary_codec() {
-    return {
-        content_type: "application/octet-stream",
-        encode: (value) => value,
-        decode: (bytes) => bytes,
-    };
-}

package/dist/hash.d.ts

@@ -1,2 +0,0 @@
-export declare function compute_hash(data: Uint8Array): Promise<string>;
-//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../hash.ts"],"names":[],"mappings":"AAAA,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAIpE"}

package/dist/hash.js

@@ -1,5 +0,0 @@
-export async function compute_hash(data) {
-    const hash_buffer = await crypto.subtle.digest('SHA-256', data);
-    const hash_array = new Uint8Array(hash_buffer);
-    return Array.from(hash_array).map(b => b.toString(16).padStart(2, '0')).join('');
-}

package/dist/store.d.ts

@@ -1,3 +0,0 @@
-import type { Backend, Store, StoreDefinition } from './types';
-export declare function create_store<T>(backend: Backend, definition: StoreDefinition<string, T>): Store<T>;
-//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAA8C,MAAM,SAAS,CAAA;AAK1G,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CA+IlG"}

package/dist/store.js

@@ -1,125 +0,0 @@
-import { ok, err } from './types';
-import { compute_hash } from './hash';
-import { generate_version } from './version';
-export function create_store(backend, definition) {
-    const { id, codec } = definition;
-    function emit(event) {
-        backend.on_event?.(event);
-    }
-    function make_data_key(store_id, content_hash) {
-        return `${store_id}/${content_hash}`;
-    }
-    return {
-        id,
-        codec,
-        async put(data, opts) {
-            const version = generate_version();
-            let bytes;
-            try {
-                bytes = codec.encode(data);
-            }
-            catch (cause) {
-                const error = { kind: 'encode_error', cause: cause };
-                emit({ type: 'error', error });
-                return err(error);
-            }
-            const content_hash = await compute_hash(bytes);
-            // deduplication: reuse existing data_key if content already exists
-            const existing = await backend.metadata.find_by_hash(id, content_hash);
-            const deduplicated = existing !== null;
-            const data_key = deduplicated ? existing.data_key : make_data_key(id, content_hash);
-            if (!deduplicated) {
-                const data_result = await backend.data.put(data_key, bytes);
-                if (!data_result.ok) {
-                    emit({ type: 'error', error: data_result.error });
-                    return data_result;
-                }
-            }
-            emit({ type: 'data_put', store_id: id, version, size_bytes: bytes.length, deduplicated });
-            const meta = {
-                store_id: id,
-                version,
-                parents: opts?.parents ?? [],
-                created_at: new Date(),
-                invoked_at: opts?.invoked_at,
-                content_hash,
-                content_type: codec.content_type,
-                size_bytes: bytes.length,
-                data_key,
-                tags: opts?.tags,
-            };
-            const meta_result = await backend.metadata.put(meta);
-            if (!meta_result.ok) {
-                emit({ type: 'error', error: meta_result.error });
-                return meta_result;
-            }
-            emit({ type: 'snapshot_put', store_id: id, version, content_hash, deduplicated });
-            return ok(meta);
-        },
-        async get(version) {
-            const meta_result = await backend.metadata.get(id, version);
-            if (!meta_result.ok) {
-                emit({ type: 'snapshot_get', store_id: id, version, found: false });
-                return meta_result;
-            }
-            const meta = meta_result.value;
-            const data_result = await backend.data.get(meta.data_key);
-            if (!data_result.ok) {
-                emit({ type: 'error', error: data_result.error });
-                return data_result;
-            }
-            const bytes = await data_result.value.bytes();
-            let data;
-            try {
-                data = codec.decode(bytes);
-            }
-            catch (cause) {
-                const error = { kind: 'decode_error', cause: cause };
-                emit({ type: 'error', error });
-                return err(error);
-            }
-            emit({ type: 'snapshot_get', store_id: id, version, found: true });
-            return ok({ meta, data });
-        },
-        async get_latest() {
-            const meta_result = await backend.metadata.get_latest(id);
-            if (!meta_result.ok) {
-                return meta_result;
-            }
-            const meta = meta_result.value;
-            const data_result = await backend.data.get(meta.data_key);
-            if (!data_result.ok) {
-                return data_result;
-            }
-            const bytes = await data_result.value.bytes();
-            let data;
-            try {
-                data = codec.decode(bytes);
-            }
-            catch (cause) {
-                const error = { kind: 'decode_error', cause: cause };
-                emit({ type: 'error', error });
-                return err(error);
-            }
-            return ok({ meta, data });
-        },
-        async get_meta(version) {
-            return backend.metadata.get(id, version);
-        },
-        list(opts) {
-            return backend.metadata.list(id, opts);
-        },
-        async delete(version) {
-            const meta_result = await backend.metadata.get(id, version);
-            if (!meta_result.ok) {
-                return meta_result;
-            }
-            const delete_meta_result = await backend.metadata.delete(id, version);
-            if (!delete_meta_result.ok) {
-                return delete_meta_result;
-            }
-            emit({ type: 'meta_delete', store_id: id, version });
-            return ok(undefined);
-        },
-    };
-}

package/dist/version.d.ts

@@ -1,7 +0,0 @@
-/**
- * Generates a unique, sortable version string.
- * Format: base64url-encoded timestamp with optional sequence suffix for same-millisecond calls.
- * Versions sort lexicographically in chronological order.
- */
-export declare function generate_version(): string;
-//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../version.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CA0BzC"}

package/dist/version.js

@@ -1,31 +0,0 @@
-let last_timestamp = 0;
-let sequence = 0;
-/**
- * Generates a unique, sortable version string.
- * Format: base64url-encoded timestamp with optional sequence suffix for same-millisecond calls.
- * Versions sort lexicographically in chronological order.
- */
-export function generate_version() {
-    const now = Date.now();
-    if (now === last_timestamp) {
-        sequence++;
-    }
-    else {
-        last_timestamp = now;
-        sequence = 0;
-    }
-    // base64url encode the timestamp (no padding, url-safe)
-    const timestamp_bytes = new Uint8Array(8);
-    const view = new DataView(timestamp_bytes.buffer);
-    view.setBigUint64(0, BigInt(now), false); // big-endian for lexicographic sorting
-    // trim leading zeros for compactness
-    let start = 0;
-    while (start < 7 && timestamp_bytes[start] === 0)
-        start++;
-    const trimmed = timestamp_bytes.slice(start);
-    const base64 = btoa(String.fromCharCode(...trimmed))
-        .replace(/\+/g, '-')
-        .replace(/\//g, '_')
-        .replace(/=/g, '');
-    return sequence > 0 ? `${base64}.${sequence}` : base64;
-}