mcard-js 2.1.35 → 2.1.36

package/README.md

@@ -2,14 +2,14 @@
 
 Full-featured TypeScript implementation of MCard content-addressable storage, supporting both browser and Node.js environments.
 
-[![Tests](https://img.shields.io/badge/tests-814%20passed%20(52%20files)-brightgreen)](./tests)
+[![Tests](https://img.shields.io/badge/tests-864%20passed%20(54%20files)-brightgreen)](./tests)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
 
 ## Features
 
 - **Content Addressing**: SHA-256 via Web Crypto API (browser) or Node.js crypto
-- **3 Interchangeable Storage Engines**: `IndexedDBEngine` (browser), `SqliteNodeEngine` (Node.js/better-sqlite3), `SqliteWasmEngine` (browser/sql.js) — verified by 162 cross-engine interchangeability tests
+- **5 Interchangeable Storage Engines**: `IndexedDBEngine` (browser), `SqliteNodeEngine` (Node.js/better-sqlite3), `SqliteWasmEngine` (browser/sql.js), `DuckDBNodeEngine` (Node.js/@duckdb/node-api), `DuckDBWasmEngine` (browser/@duckdb/duckdb-wasm)
 - **UTF-8 Handles**: International support (文檔, مستند, ドキュメント, документ)
 - **Monadic API**: Maybe, Either, IO monads for functional composition
 - **PTR Runtime**: Polynomial Type Runtime with polyglot execution (JS, Python, Rust, C, WASM, Lean)
@@ -99,6 +99,39 @@ const count = db.countSync();
 db.close();
 ```
 
+### DuckDB (Node.js — Alternative OLAP Engine)
+```typescript
+import { DuckDBNodeEngine } from './storage/DuckDBNodeEngine';
+
+// Async factory — in-memory or file-backed
+const db = await DuckDBNodeEngine.create(':memory:');
+// or: await DuckDBNodeEngine.create('./mcard.duckdb');
+
+// Same StorageEngine interface as SQLite
+const card = await MCard.create('Hello from DuckDB!');
+await db.add(card);
+
+const retrieved = await db.get(card.hash);
+console.log(retrieved?.getContentAsText());
+
+await db.close();
+```
+
+### DuckDB WASM (Browser — In-Browser OLAP)
+```typescript
+import { DuckDBWasmEngine } from './storage/DuckDBWasmEngine';
+
+// Runs DuckDB entirely in WebAssembly via Web Worker
+const db = new DuckDBWasmEngine();
+await db.init(); // Downloads WASM bundle from CDN
+
+// Same StorageEngine interface
+const card = await MCard.create('Hello from DuckDB WASM!');
+await db.add(card);
+
+await db.close();
+```
+
 ## Database Schema
 
 The SQLite backend uses schemas matching the Python implementation for full interoperability.

package/dist/index.d.cts

@@ -1,11 +1,202 @@
-import { M as MCard } from './StorageAdapter-DdDUiIvH.cjs';
-export { P as Page, S as StorageEngine } from './StorageAdapter-DdDUiIvH.cjs';
+import { S as StorageEngine, M as MCard, P as Page } from './StorageAdapter-DdDUiIvH.cjs';
 import { CardCollection, Either, IO, Maybe } from './index.browser.cjs';
 export { ALGORITHM_HIERARCHY, ContentHandle, ContentTypeInterpreter, EVENT_CONSTANTS, ErrorCodes, ExecutionResult, FaroSidecar, FaroSidecarConfig, GTime, HandleValidationError, HashValidator, IndexedDBEngine, JsonRpcRequest, JsonRpcResponse, LensProtocol, LivenessMetric, MCardStore, PolynomialTerm, PrimeHash, Reader, SafetyViolation, ServiceWorkerPTR, State, ValidationRegistry, VerificationStatus, Writer, computeHash, validateHandle, validationRegistry } from './index.browser.cjs';
 export { SqliteWasmEngine } from './storage/SqliteWasmEngine.cjs';
 export { SqliteNodeEngine } from './storage/SqliteNodeEngine.cjs';
 import '@grafana/faro-web-sdk';
 
+/**
+ * DuckDBNodeEngine — DuckDB storage backend for Node.js
+ *
+ * Implements the same StorageEngine interface as SqliteNodeEngine,
+ * using @duckdb/node-api (the "Neo" async client).
+ *
+ * Schema is loaded from the canonical SQL files via MCardSchema singleton
+ * with DuckDB-specific dialect transforms — single source of truth.
+ *
+ * Canonical schema files:
+ *   schema/mcard_schema.sql            (REQUIRED — core tables)
+ *   schema/mcard_vector_schema.sql     (optional — vector/graph/FTS)
+ *
+ * Usage:
+ *   const engine = await DuckDBNodeEngine.create(':memory:');
+ *   // ... use same StorageEngine interface as SqliteNodeEngine ...
+ *   await engine.close();
+ */
+
+/**
+ * DuckDB storage engine for Node.js.
+ *
+ * Because DuckDB init is async, use the static factory:
+ *   const engine = await DuckDBNodeEngine.create(':memory:');
+ */
+declare class DuckDBNodeEngine implements StorageEngine {
+    private instance;
+    private conn;
+    private dbPath;
+    private constructor();
+    /**
+     * Create a new DuckDBNodeEngine (async factory).
+     *
+     * @param dbPath  Path to DuckDB file, or ':memory:' for in-memory
+     */
+    static create(dbPath?: string): Promise<DuckDBNodeEngine>;
+    /**
+     * Initialize schema from canonical SQL files via MCardSchema singleton.
+     */
+    private setupDatabase;
+    /**
+     * Close the DuckDB connection.
+     */
+    close(): Promise<void>;
+    getDbPath(): string;
+    /**
+     * Read all row objects from a SQL query (convenience wrapper).
+     */
+    private query;
+    /**
+     * Execute a statement (write operation).
+     */
+    private exec;
+    /**
+     * Bind parameters to a prepared statement.
+     * DuckDB uses 1-based indexing for parameters.
+     */
+    private bindParams;
+    /**
+     * Convert a DuckDB row object to an MCard.
+     */
+    private static rowToCard;
+    add(card: MCard): Promise<string>;
+    get(hash: string): Promise<MCard | null>;
+    delete(hash: string): Promise<void>;
+    getPage(pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    count(): Promise<number>;
+    searchByHash(hashPrefix: string): Promise<MCard[]>;
+    search(queryStr: string, pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    getAll(): Promise<MCard[]>;
+    clear(): Promise<void>;
+    registerHandle(handle: string, hash: string): Promise<void>;
+    resolveHandle(handle: string): Promise<string | null>;
+    getByHandle(handle: string): Promise<MCard | null>;
+    updateHandle(handle: string, newHash: string): Promise<string>;
+    getHandleHistory(handle: string): Promise<{
+        previousHash: string;
+        changedAt: string;
+    }[]>;
+    pruneHandleHistory(handle: string, options?: {
+        olderThan?: string;
+        deleteAll?: boolean;
+    }): Promise<number>;
+    getAllHandles(): Promise<{
+        handle: string;
+        hash: string;
+    }[]>;
+    removeHandle(handle: string): Promise<void>;
+    renameHandle(oldHandle: string, newHandle: string): Promise<void>;
+    deleteHistoryEntry(handle: string, previousHash: string): Promise<void>;
+}
+
+/**
+ * DuckDBWasmEngine — DuckDB WASM storage backend for browsers.
+ *
+ * Implements the same StorageEngine interface as SqliteWasmEngine,
+ * using @duckdb/duckdb-wasm (AsyncDuckDB with Web Worker).
+ *
+ * This engine is BROWSER-ONLY. For Node.js, use DuckDBNodeEngine.
+ *
+ * Schema is loaded from the canonical SQL files via MCardSchema singleton
+ * with DuckDB-specific dialect transforms — single source of truth.
+ *
+ * Usage (browser):
+ *   const engine = new DuckDBWasmEngine();
+ *   await engine.init();
+ *   // ... use same StorageEngine interface as SqliteWasmEngine ...
+ *   await engine.close();
+ */
+
+/**
+ * DuckDB WASM storage engine for browsers.
+ *
+ * Uses @duckdb/duckdb-wasm which runs DuckDB entirely in WebAssembly
+ * inside a Web Worker. Provides the full `StorageEngine` interface
+ * with the same DuckDB dialect transforms as `DuckDBNodeEngine`.
+ *
+ * Browser-only: For Node.js, use `DuckDBNodeEngine` with `@duckdb/node-api`.
+ */
+declare class DuckDBWasmEngine implements StorageEngine {
+    private db;
+    private conn;
+    private worker;
+    /**
+     * Initialize the DuckDB WASM engine.
+     *
+     * Spins up a Web Worker with the DuckDB WASM bundle from jsDelivr CDN.
+     * Must be called before any operations.
+     *
+     * @param customBundles  Optional custom bundle URLs (for self-hosted WASM)
+     */
+    init(customBundles?: {
+        mainModule: string;
+        mainWorker: string;
+        pthreadWorker?: string;
+    }): Promise<void>;
+    /**
+     * Initialize schema from canonical SQL files via MCardSchema singleton.
+     */
+    private setupDatabase;
+    private ensureConn;
+    /**
+     * Close the DuckDB WASM connection and terminate the worker.
+     */
+    close(): Promise<void>;
+    /**
+     * Run a query and return row objects.
+     * duckdb-wasm conn.query() returns an Arrow Table.
+     */
+    private query;
+    /**
+     * Execute a write statement.
+     */
+    private exec;
+    /**
+     * Convert Arrow Table to array of plain objects.
+     */
+    private arrowToObjects;
+    /**
+     * Convert a row object to an MCard.
+     */
+    private static rowToCard;
+    add(card: MCard): Promise<string>;
+    get(hash: string): Promise<MCard | null>;
+    delete(hash: string): Promise<void>;
+    getPage(pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    count(): Promise<number>;
+    searchByHash(hashPrefix: string): Promise<MCard[]>;
+    search(queryStr: string, pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    getAll(): Promise<MCard[]>;
+    clear(): Promise<void>;
+    registerHandle(handle: string, hash: string): Promise<void>;
+    resolveHandle(handle: string): Promise<string | null>;
+    getByHandle(handle: string): Promise<MCard | null>;
+    updateHandle(handle: string, newHash: string): Promise<string>;
+    getHandleHistory(handle: string): Promise<{
+        previousHash: string;
+        changedAt: string;
+    }[]>;
+    pruneHandleHistory(handle: string, options?: {
+        olderThan?: string;
+        deleteAll?: boolean;
+    }): Promise<number>;
+    getAllHandles(): Promise<{
+        handle: string;
+        hash: string;
+    }[]>;
+    removeHandle(handle: string): Promise<void>;
+    renameHandle(oldHandle: string, newHandle: string): Promise<void>;
+    deleteHistoryEntry(handle: string, previousHash: string): Promise<void>;
+}
+
 /**
  * SandboxWorker - Execute code in isolated Web Worker
  *
@@ -1057,4 +1248,4 @@ declare class CLMRunner {
     private buildRunCLM;
 }
 
-export { CLMRunner, CardCollection, Either, FileIO, IO, LLMConfig, LLMRuntime, index as Lambda, LambdaRuntime, Loader, MCard, Maybe, SandboxWorker, chatMonad, promptMonad };
+export { CLMRunner, CardCollection, DuckDBNodeEngine, DuckDBWasmEngine, Either, FileIO, IO, LLMConfig, LLMRuntime, index as Lambda, LambdaRuntime, Loader, MCard, Maybe, Page, SandboxWorker, StorageEngine, chatMonad, promptMonad };

package/dist/index.d.ts

@@ -1,11 +1,202 @@
-import { M as MCard } from './StorageAdapter-DdDUiIvH.js';
-export { P as Page, S as StorageEngine } from './StorageAdapter-DdDUiIvH.js';
+import { S as StorageEngine, M as MCard, P as Page } from './StorageAdapter-DdDUiIvH.js';
 import { CardCollection, Either, IO, Maybe } from './index.browser.js';
 export { ALGORITHM_HIERARCHY, ContentHandle, ContentTypeInterpreter, EVENT_CONSTANTS, ErrorCodes, ExecutionResult, FaroSidecar, FaroSidecarConfig, GTime, HandleValidationError, HashValidator, IndexedDBEngine, JsonRpcRequest, JsonRpcResponse, LensProtocol, LivenessMetric, MCardStore, PolynomialTerm, PrimeHash, Reader, SafetyViolation, ServiceWorkerPTR, State, ValidationRegistry, VerificationStatus, Writer, computeHash, validateHandle, validationRegistry } from './index.browser.js';
 export { SqliteWasmEngine } from './storage/SqliteWasmEngine.js';
 export { SqliteNodeEngine } from './storage/SqliteNodeEngine.js';
 import '@grafana/faro-web-sdk';
 
+/**
+ * DuckDBNodeEngine — DuckDB storage backend for Node.js
+ *
+ * Implements the same StorageEngine interface as SqliteNodeEngine,
+ * using @duckdb/node-api (the "Neo" async client).
+ *
+ * Schema is loaded from the canonical SQL files via MCardSchema singleton
+ * with DuckDB-specific dialect transforms — single source of truth.
+ *
+ * Canonical schema files:
+ *   schema/mcard_schema.sql            (REQUIRED — core tables)
+ *   schema/mcard_vector_schema.sql     (optional — vector/graph/FTS)
+ *
+ * Usage:
+ *   const engine = await DuckDBNodeEngine.create(':memory:');
+ *   // ... use same StorageEngine interface as SqliteNodeEngine ...
+ *   await engine.close();
+ */
+
+/**
+ * DuckDB storage engine for Node.js.
+ *
+ * Because DuckDB init is async, use the static factory:
+ *   const engine = await DuckDBNodeEngine.create(':memory:');
+ */
+declare class DuckDBNodeEngine implements StorageEngine {
+    private instance;
+    private conn;
+    private dbPath;
+    private constructor();
+    /**
+     * Create a new DuckDBNodeEngine (async factory).
+     *
+     * @param dbPath  Path to DuckDB file, or ':memory:' for in-memory
+     */
+    static create(dbPath?: string): Promise<DuckDBNodeEngine>;
+    /**
+     * Initialize schema from canonical SQL files via MCardSchema singleton.
+     */
+    private setupDatabase;
+    /**
+     * Close the DuckDB connection.
+     */
+    close(): Promise<void>;
+    getDbPath(): string;
+    /**
+     * Read all row objects from a SQL query (convenience wrapper).
+     */
+    private query;
+    /**
+     * Execute a statement (write operation).
+     */
+    private exec;
+    /**
+     * Bind parameters to a prepared statement.
+     * DuckDB uses 1-based indexing for parameters.
+     */
+    private bindParams;
+    /**
+     * Convert a DuckDB row object to an MCard.
+     */
+    private static rowToCard;
+    add(card: MCard): Promise<string>;
+    get(hash: string): Promise<MCard | null>;
+    delete(hash: string): Promise<void>;
+    getPage(pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    count(): Promise<number>;
+    searchByHash(hashPrefix: string): Promise<MCard[]>;
+    search(queryStr: string, pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    getAll(): Promise<MCard[]>;
+    clear(): Promise<void>;
+    registerHandle(handle: string, hash: string): Promise<void>;
+    resolveHandle(handle: string): Promise<string | null>;
+    getByHandle(handle: string): Promise<MCard | null>;
+    updateHandle(handle: string, newHash: string): Promise<string>;
+    getHandleHistory(handle: string): Promise<{
+        previousHash: string;
+        changedAt: string;
+    }[]>;
+    pruneHandleHistory(handle: string, options?: {
+        olderThan?: string;
+        deleteAll?: boolean;
+    }): Promise<number>;
+    getAllHandles(): Promise<{
+        handle: string;
+        hash: string;
+    }[]>;
+    removeHandle(handle: string): Promise<void>;
+    renameHandle(oldHandle: string, newHandle: string): Promise<void>;
+    deleteHistoryEntry(handle: string, previousHash: string): Promise<void>;
+}
+
+/**
+ * DuckDBWasmEngine — DuckDB WASM storage backend for browsers.
+ *
+ * Implements the same StorageEngine interface as SqliteWasmEngine,
+ * using @duckdb/duckdb-wasm (AsyncDuckDB with Web Worker).
+ *
+ * This engine is BROWSER-ONLY. For Node.js, use DuckDBNodeEngine.
+ *
+ * Schema is loaded from the canonical SQL files via MCardSchema singleton
+ * with DuckDB-specific dialect transforms — single source of truth.
+ *
+ * Usage (browser):
+ *   const engine = new DuckDBWasmEngine();
+ *   await engine.init();
+ *   // ... use same StorageEngine interface as SqliteWasmEngine ...
+ *   await engine.close();
+ */
+
+/**
+ * DuckDB WASM storage engine for browsers.
+ *
+ * Uses @duckdb/duckdb-wasm which runs DuckDB entirely in WebAssembly
+ * inside a Web Worker. Provides the full `StorageEngine` interface
+ * with the same DuckDB dialect transforms as `DuckDBNodeEngine`.
+ *
+ * Browser-only: For Node.js, use `DuckDBNodeEngine` with `@duckdb/node-api`.
+ */
+declare class DuckDBWasmEngine implements StorageEngine {
+    private db;
+    private conn;
+    private worker;
+    /**
+     * Initialize the DuckDB WASM engine.
+     *
+     * Spins up a Web Worker with the DuckDB WASM bundle from jsDelivr CDN.
+     * Must be called before any operations.
+     *
+     * @param customBundles  Optional custom bundle URLs (for self-hosted WASM)
+     */
+    init(customBundles?: {
+        mainModule: string;
+        mainWorker: string;
+        pthreadWorker?: string;
+    }): Promise<void>;
+    /**
+     * Initialize schema from canonical SQL files via MCardSchema singleton.
+     */
+    private setupDatabase;
+    private ensureConn;
+    /**
+     * Close the DuckDB WASM connection and terminate the worker.
+     */
+    close(): Promise<void>;
+    /**
+     * Run a query and return row objects.
+     * duckdb-wasm conn.query() returns an Arrow Table.
+     */
+    private query;
+    /**
+     * Execute a write statement.
+     */
+    private exec;
+    /**
+     * Convert Arrow Table to array of plain objects.
+     */
+    private arrowToObjects;
+    /**
+     * Convert a row object to an MCard.
+     */
+    private static rowToCard;
+    add(card: MCard): Promise<string>;
+    get(hash: string): Promise<MCard | null>;
+    delete(hash: string): Promise<void>;
+    getPage(pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    count(): Promise<number>;
+    searchByHash(hashPrefix: string): Promise<MCard[]>;
+    search(queryStr: string, pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    getAll(): Promise<MCard[]>;
+    clear(): Promise<void>;
+    registerHandle(handle: string, hash: string): Promise<void>;
+    resolveHandle(handle: string): Promise<string | null>;
+    getByHandle(handle: string): Promise<MCard | null>;
+    updateHandle(handle: string, newHash: string): Promise<string>;
+    getHandleHistory(handle: string): Promise<{
+        previousHash: string;
+        changedAt: string;
+    }[]>;
+    pruneHandleHistory(handle: string, options?: {
+        olderThan?: string;
+        deleteAll?: boolean;
+    }): Promise<number>;
+    getAllHandles(): Promise<{
+        handle: string;
+        hash: string;
+    }[]>;
+    removeHandle(handle: string): Promise<void>;
+    renameHandle(oldHandle: string, newHandle: string): Promise<void>;
+    deleteHistoryEntry(handle: string, previousHash: string): Promise<void>;
+}
+
 /**
  * SandboxWorker - Execute code in isolated Web Worker
  *
@@ -1057,4 +1248,4 @@ declare class CLMRunner {
     private buildRunCLM;
 }
 
-export { CLMRunner, CardCollection, Either, FileIO, IO, LLMConfig, LLMRuntime, index as Lambda, LambdaRuntime, Loader, MCard, Maybe, SandboxWorker, chatMonad, promptMonad };
+export { CLMRunner, CardCollection, DuckDBNodeEngine, DuckDBWasmEngine, Either, FileIO, IO, LLMConfig, LLMRuntime, index as Lambda, LambdaRuntime, Loader, MCard, Maybe, Page, SandboxWorker, StorageEngine, chatMonad, promptMonad };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcard-js",
-    "version": "2.1.35",
+    "version": "2.1.36",
     "description": "MCard - Content-addressable storage with cryptographic hashing, handle resolution, and vector search for Node.js and browsers",
     "type": "module",
     "main": "dist/index.js",
@@ -58,6 +58,8 @@
         "yaml": "^2.8.2"
     },
     "optionalDependencies": {
+        "@duckdb/duckdb-wasm": "^1.33.1-dev20.0",
+        "@duckdb/node-api": "^1.5.0-r.1",
         "better-sqlite3": "^11.6.0",
         "sqlite-vec": "^0.1.7-alpha.2"
     },