@f0rbit/corpus 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,173 @@
+export type CorpusError = {
+    kind: 'not_found';
+    store_id: string;
+    version: string;
+} | {
+    kind: 'already_exists';
+    store_id: string;
+    version: string;
+} | {
+    kind: 'storage_error';
+    cause: Error;
+    operation: string;
+} | {
+    kind: 'decode_error';
+    cause: Error;
+} | {
+    kind: 'encode_error';
+    cause: Error;
+} | {
+    kind: 'hash_mismatch';
+    expected: string;
+    actual: string;
+} | {
+    kind: 'invalid_config';
+    message: string;
+};
+export type Result<T, E = CorpusError> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export declare const ok: <T>(value: T) => Result<T, never>;
+export declare const err: <E>(error: E) => Result<never, E>;
+export type CorpusEvent = {
+    type: 'meta_get';
+    store_id: string;
+    version: string;
+    found: boolean;
+} | {
+    type: 'meta_put';
+    store_id: string;
+    version: string;
+} | {
+    type: 'meta_delete';
+    store_id: string;
+    version: string;
+} | {
+    type: 'meta_list';
+    store_id: string;
+    count: number;
+} | {
+    type: 'data_get';
+    store_id: string;
+    version: string;
+    found: boolean;
+} | {
+    type: 'data_put';
+    store_id: string;
+    version: string;
+    size_bytes: number;
+    deduplicated: boolean;
+} | {
+    type: 'data_delete';
+    store_id: string;
+    version: string;
+} | {
+    type: 'snapshot_put';
+    store_id: string;
+    version: string;
+    content_hash: string;
+    deduplicated: boolean;
+} | {
+    type: 'snapshot_get';
+    store_id: string;
+    version: string;
+    found: boolean;
+} | {
+    type: 'error';
+    error: CorpusError;
+};
+export type EventHandler = (event: CorpusEvent) => void;
+export type ContentType = "application/json" | "text/plain" | "text/xml" | "image/png" | "image/jpeg" | "application/octet-stream" | (string & {});
+export type ParentRef = {
+    store_id: string;
+    version: string;
+    role?: string;
+};
+export type SnapshotMeta = {
+    store_id: string;
+    version: string;
+    parents: ParentRef[];
+    created_at: Date;
+    invoked_at?: Date;
+    content_hash: string;
+    content_type: ContentType;
+    size_bytes: number;
+    data_key: string;
+    tags?: string[];
+};
+export type Snapshot<T = unknown> = {
+    meta: SnapshotMeta;
+    data: T;
+};
+export type DataHandle = {
+    stream: () => ReadableStream<Uint8Array>;
+    bytes: () => Promise<Uint8Array>;
+};
+export type MetadataClient = {
+    get: (store_id: string, version: string) => Promise<Result<SnapshotMeta, CorpusError>>;
+    put: (meta: SnapshotMeta) => Promise<Result<void, CorpusError>>;
+    delete: (store_id: string, version: string) => Promise<Result<void, CorpusError>>;
+    list: (store_id: string, opts?: ListOpts) => AsyncIterable<SnapshotMeta>;
+    get_latest: (store_id: string) => Promise<Result<SnapshotMeta, CorpusError>>;
+    get_children: (parent_store_id: string, parent_version: string) => AsyncIterable<SnapshotMeta>;
+    find_by_hash: (store_id: string, content_hash: string) => Promise<SnapshotMeta | null>;
+};
+export type DataClient = {
+    get: (data_key: string) => Promise<Result<DataHandle, CorpusError>>;
+    put: (data_key: string, data: ReadableStream<Uint8Array> | Uint8Array) => Promise<Result<void, CorpusError>>;
+    delete: (data_key: string) => Promise<Result<void, CorpusError>>;
+    exists: (data_key: string) => Promise<boolean>;
+};
+export type ListOpts = {
+    limit?: number;
+    cursor?: string;
+    before?: Date;
+    after?: Date;
+    tags?: string[];
+};
+export type Backend = {
+    metadata: MetadataClient;
+    data: DataClient;
+    on_event?: EventHandler;
+};
+export type Codec<T> = {
+    content_type: ContentType;
+    encode: (value: T) => Uint8Array;
+    decode: (bytes: Uint8Array) => T;
+};
+export type Store<T> = {
+    readonly id: string;
+    readonly codec: Codec<T>;
+    put: (data: T, opts?: PutOpts) => Promise<Result<SnapshotMeta, CorpusError>>;
+    get: (version: string) => Promise<Result<Snapshot<T>, CorpusError>>;
+    get_latest: () => Promise<Result<Snapshot<T>, CorpusError>>;
+    get_meta: (version: string) => Promise<Result<SnapshotMeta, CorpusError>>;
+    list: (opts?: ListOpts) => AsyncIterable<SnapshotMeta>;
+    delete: (version: string) => Promise<Result<void, CorpusError>>;
+};
+export type PutOpts = {
+    parents?: ParentRef[];
+    invoked_at?: Date;
+    tags?: string[];
+};
+export type StoreDefinition<Id extends string, T> = {
+    id: Id;
+    codec: Codec<T>;
+    description?: string;
+};
+export declare function define_store<Id extends string, T>(id: Id, codec: Codec<T>, description?: 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>>>;
+    build: () => Corpus<Stores>;
+};
+export type Corpus<Stores extends Record<string, Store<any>> = Record<string, Store<any>>> = {
+    stores: Stores;
+    metadata: MetadataClient;
+    data: DataClient;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,5 @@
+export const ok = (value) => ({ ok: true, value });
+export const err = (error) => ({ ok: false, error });
+export function define_store(id, codec, description) {
+    return { id, codec, description };
+}

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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

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

package/dist/version.js

@@ -0,0 +1,31 @@
+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;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@f0rbit/corpus",
+  "version": "0.1.0",
+  "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",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types.js",
+      "types": "./dist/types.d.ts"
+    },
+    "./schema": {
+      "import": "./dist/schema.js",
+      "types": "./dist/schema.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/f0rbit/corpus.git"
+  },
+  "keywords": [
+    "snapshot",
+    "versioning",
+    "data-store",
+    "lineage",
+    "typescript"
+  ],
+  "author": "f0rbit",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/f0rbit/corpus/issues"
+  },
+  "homepage": "https://github.com/f0rbit/corpus#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "zod": "^3"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.44.7"
+  }
+}