@bitclaw/sqlite 1.1.0

package/dist/src/ttl-cache.js

@@ -0,0 +1,92 @@
+// packages/sqlite/src/ttl-cache.ts
+// In-memory TTL cache for server-side deduplication across HTTP requests.
+// Complements json-cache (persistent, file-based) with a lightweight
+// in-memory cache that auto-expires and auto-prunes.
+/**
+ * In-memory TTL cache backed by a Map.
+ *
+ * Designed for server-side deduplication of expensive lookups (auth sessions,
+ * membership checks, bootstrap data) across HTTP requests. Entries expire
+ * after `ttl` milliseconds and are automatically pruned when the map exceeds
+ * `maxSize`.
+ *
+ * Unlike WeakMap per-request caching (which deduplicates within a single
+ * request), TTLCache deduplicates across requests — e.g. when TanStack
+ * Router replays `beforeLoad` on client hydration, the server returns the
+ * cached result instantly (0 DB queries).
+ *
+ * @example
+ * ```typescript
+ * import { TTLCache } from '@bitclaw/sqlite/ttl-cache';
+ *
+ * type BootstrapData = { user: User; workspaces: Workspace[] };
+ *
+ * const bootstrapCache = new TTLCache<BootstrapData>({ ttl: 30_000 });
+ *
+ * // In your server function:
+ * const cached = bootstrapCache.get(sessionId);
+ * if (cached) return cached;
+ *
+ * const data = await expensiveQuery();
+ * bootstrapCache.set(sessionId, data);
+ * return data;
+ * ```
+ */
+export class TTLCache {
+    cache = new Map();
+    ttl;
+    maxSize;
+    constructor(options = {}) {
+        this.ttl = options.ttl ?? 30_000;
+        this.maxSize = options.maxSize ?? 100;
+    }
+    /** Get a cached value if it exists and hasn't expired. */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /** Check if a non-expired entry exists for the given key. */
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    /** Store a value with the configured TTL. Auto-prunes if maxSize exceeded. */
+    set(key, value) {
+        this.cache.set(key, {
+            value,
+            expiresAt: Date.now() + this.ttl
+        });
+        if (this.cache.size > this.maxSize) {
+            this.prune();
+        }
+    }
+    /** Remove a specific entry. */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /** Remove all entries. */
+    clear() {
+        this.cache.clear();
+    }
+    /** Number of entries (including potentially expired ones). */
+    get size() {
+        return this.cache.size;
+    }
+    /** Remove all expired entries. */
+    prune() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.cache) {
+            if (entry.expiresAt <= now) {
+                this.cache.delete(key);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+}

package/dist/src/worker.d.ts

@@ -0,0 +1,38 @@
+type DatabaseConfig = {
+    path: string;
+    options: {
+        verbose?: ((message?: unknown, ...additionalArgs: unknown[]) => void) | undefined;
+        fileMustExist: boolean;
+    };
+};
+type WorkerMessage = {
+    id: string;
+    sql: string;
+    params?: unknown[];
+    type?: string;
+};
+type WorkerResponse = {
+    id: string;
+    result?: unknown;
+    error?: {
+        message: string;
+        code?: string;
+        errno?: number;
+    };
+    workerId: string;
+    durationMs: number;
+    success: boolean;
+};
+export declare class SQLiteWorker {
+    private db;
+    private config;
+    private workerId;
+    constructor(config?: DatabaseConfig);
+    private initializeDatabase;
+    handleMessage(message: WorkerMessage): Promise<WorkerResponse>;
+    private executeQuery;
+    shutdown(): void;
+    getWorkerId(): string;
+}
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/src/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/worker.ts"],"names":[],"mappings":"AAoEA,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QACP,OAAO,CAAC,EACJ,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC,GAC3D,SAAS,CAAC;QACd,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;CACH,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AA6DF,qBAAa,YAAY;IACvB,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,CAAC,EAAE,cAAc;YAKrB,kBAAkB;IAkD1B,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IA6CpE,OAAO,CAAC,YAAY;IAoDpB,QAAQ,IAAI,IAAI;IAchB,WAAW,IAAI,MAAM;CAGtB"}

package/dist/src/worker.js

@@ -0,0 +1,294 @@
+// packages/sqlite/src/worker.ts
+// SQLite Worker Thread - Optimized for Hetzner VPS deployment
+// Uses bun:sqlite for 3-6x faster reads compared to better-sqlite3
+import { Database } from 'bun:sqlite';
+import { parentPort, workerData } from 'node:worker_threads';
+const isDevelopment = process.env.NODE_ENV === 'development';
+const isTest = process.env.NODE_ENV === 'test';
+// ---------------------------------------------------------------------------
+// Prepared-statement LRU cache for optimal performance
+// ---------------------------------------------------------------------------
+class StatementCache {
+    cache = new Map();
+    maxSize = 256;
+    hits = 0;
+    misses = 0;
+    get(sql) {
+        const stmt = this.cache.get(sql);
+        if (stmt) {
+            this.hits += 1;
+            // Move to end (LRU behavior)
+            this.cache.delete(sql);
+            this.cache.set(sql, stmt);
+            return stmt;
+        }
+        return null;
+    }
+    set(sql, stmt) {
+        this.misses += 1;
+        // If at capacity, remove oldest
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(sql, stmt);
+    }
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            size: this.cache.size,
+            hitRate: total > 0 ? (this.hits / total) * 100 : 0
+        };
+    }
+    clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+    }
+}
+const stmtCache = new StatementCache();
+// Worker-specific database configuration
+async function getDbConfig() {
+    const envPath = workerData?.databasePath ??
+        process.env.DATABASE_PATH;
+    if (envPath) {
+        return {
+            path: envPath,
+            options: {
+                verbose: undefined,
+                fileMustExist: false
+            }
+        };
+    }
+    if (isTest) {
+        return {
+            path: ':memory:',
+            options: {
+                verbose: undefined,
+                fileMustExist: false
+            }
+        };
+    }
+    if (isDevelopment) {
+        return {
+            path: './data/app.db',
+            options: {
+                verbose: undefined,
+                fileMustExist: false
+            }
+        };
+    }
+    // Production
+    return {
+        path: '/data/app.db',
+        options: { verbose: undefined, fileMustExist: false }
+    };
+}
+function getOrCreateStatement(db, sql) {
+    // Normalize SQL for better cache hits
+    const normalizedSql = sql.trim().replace(/\s+/g, ' ');
+    let stmt = stmtCache.get(normalizedSql);
+    if (stmt) {
+        return stmt;
+    }
+    // Cache miss → prepare + insert (bun:sqlite uses .query() instead of .prepare())
+    stmt = db.query(normalizedSql);
+    stmtCache.set(normalizedSql, stmt);
+    return stmt;
+}
+// SQLite Worker class
+export class SQLiteWorker {
+    db = null;
+    config;
+    workerId;
+    constructor(config) {
+        this.config = config;
+        this.workerId = `worker-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
+    }
+    async initializeDatabase() {
+        if (this.db)
+            return;
+        // Get config if not provided
+        if (!this.config) {
+            this.config = await getDbConfig();
+        }
+        try {
+            // bun:sqlite constructor options differ from better-sqlite3
+            this.db = new Database(this.config.path, {
+                create: !this.config.options.fileMustExist,
+                readonly: false
+            });
+            // ✅ OPTIMIZED: Enhanced multi-worker SQLite configuration
+            // bun:sqlite uses run() for PRAGMA statements instead of pragma()
+            if (this.config.path !== ':memory:') {
+                // WAL mode with optimized settings
+                this.db.run('PRAGMA journal_mode = WAL');
+                // ✅ CRITICAL: Reduced timeout for better worker coordination
+                this.db.run('PRAGMA busy_timeout = 5000');
+                // ✅ PERFORMANCE: More frequent checkpoints for multi-worker
+                this.db.run('PRAGMA wal_autocheckpoint = 100');
+                // ✅ CONCURRENCY: Enable shared cache for same-process workers
+                // Note: cache_shared is not available in bun:sqlite, skip it
+            }
+            // ✅ PERFORMANCE: Optimized PRAGMA settings for workers
+            this.db.run('PRAGMA foreign_keys = ON');
+            this.db.run('PRAGMA synchronous = NORMAL'); // Optimal for WAL mode
+            // ✅ MEMORY: 4MB per worker cache
+            this.db.run('PRAGMA cache_size = -4000');
+            this.db.run('PRAGMA temp_store = MEMORY');
+            // ✅ CONCURRENCY: Optimized mmap for multi-worker
+            this.db.run('PRAGMA mmap_size = 67108864'); // 64MB
+            // ✅ PERFORMANCE: Enable query planner optimizations
+            this.db.run('PRAGMA optimize');
+        }
+        catch (error) {
+            console.error(`[${this.workerId}] Failed to initialize database:`, error);
+            throw error;
+        }
+    }
+    async handleMessage(message) {
+        const start = performance.now();
+        let success = false;
+        let result;
+        let error;
+        try {
+            if (message.sql === '__SHUTDOWN__') {
+                this.shutdown();
+                return {
+                    id: message.id,
+                    result: { shutdown: true },
+                    workerId: this.workerId,
+                    durationMs: performance.now() - start,
+                    success: true
+                };
+            }
+            // Lazy initialization
+            if (!this.db) {
+                await this.initializeDatabase();
+            }
+            result = this.executeQuery(message.sql, message.params || []);
+            success = true;
+        }
+        catch (err) {
+            // err (not error) to avoid shadowing the outer `error` return variable
+            const e = err instanceof Error ? err : new Error(String(err));
+            error = {
+                message: e.message,
+                code: e.code,
+                errno: e.errno
+            };
+        }
+        return {
+            id: message.id,
+            result,
+            error,
+            workerId: this.workerId,
+            durationMs: performance.now() - start,
+            success
+        };
+    }
+    executeQuery(sql, params) {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        const sqlUpper = sql.trim().toUpperCase();
+        try {
+            const stmt = getOrCreateStatement(this.db, sql);
+            let result;
+            if (sqlUpper.startsWith('SELECT')) {
+                if (sqlUpper.includes('LIMIT 1') || sqlUpper.includes('COUNT(*)')) {
+                    // bun:sqlite uses .get() with params directly
+                    result = stmt.get(...params);
+                }
+                else {
+                    result = stmt.all(...params);
+                }
+            }
+            else if (sqlUpper.startsWith('INSERT') ||
+                sqlUpper.startsWith('UPDATE') ||
+                sqlUpper.startsWith('DELETE')) {
+                // bun:sqlite .run() returns { changes, lastInsertRowid }
+                const runResult = stmt.run(...params);
+                result = {
+                    changes: runResult.changes,
+                    lastInsertRowid: runResult.lastInsertRowid
+                };
+            }
+            else {
+                this.db.run(sql);
+                result = { success: true };
+            }
+            return result;
+        }
+        catch (error) {
+            const e = error instanceof Error ? error : new Error(String(error));
+            console.error(`[${this.workerId}] SQL FAILED:`, {
+                sql: `${sql.substring(0, 60)}...`,
+                error: e.message,
+                code: e.code,
+                errno: e.errno,
+                params: params?.length || 0
+            });
+            throw error;
+        }
+    }
+    shutdown() {
+        if (this.db) {
+            try {
+                // Clear prepared statement cache
+                stmtCache.clear();
+                this.db.close();
+                this.db = null;
+            }
+            catch (error) {
+                console.error(`[${this.workerId}] Error during shutdown:`, error);
+            }
+        }
+    }
+    getWorkerId() {
+        return this.workerId;
+    }
+}
+// Worker thread main execution
+if (parentPort) {
+    const worker = new SQLiteWorker();
+    parentPort.on('message', async (message) => {
+        try {
+            if (!message.id) {
+                console.error(`[${worker.getWorkerId()}] CRITICAL: Message missing ID:`, message);
+                parentPort?.postMessage({
+                    id: 'unknown',
+                    error: { message: 'Message missing ID' },
+                    workerId: worker.getWorkerId(),
+                    durationMs: 0,
+                    success: false
+                });
+                return;
+            }
+            const response = await worker.handleMessage(message);
+            if (!response.id) {
+                console.error(`[${worker.getWorkerId()}] CRITICAL: Response missing ID:`, response);
+                response.id = message.id;
+            }
+            parentPort?.postMessage(response);
+        }
+        catch (error) {
+            const e = error instanceof Error ? error : new Error(String(error));
+            parentPort?.postMessage({
+                id: message.id || 'unknown',
+                error: {
+                    message: e.message,
+                    code: e.code,
+                    errno: e.errno
+                },
+                workerId: worker.getWorkerId(),
+                durationMs: 0,
+                success: false
+            });
+        }
+    });
+}

package/dist/src/write-mutex.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A simple async mutex that serializes write access to a resource.
+ * Bun is single-threaded, so this works as a plain promise queue —
+ * no atomic operations needed.
+ */
+export declare class WriteMutex {
+    private queue;
+    /**
+     * Acquire the mutex, execute the function, then release.
+     * Only one function runs at a time per mutex instance.
+     */
+    acquire<T>(fn: () => T | Promise<T>): Promise<T>;
+}
+/**
+ * A map of named mutexes for per-resource write serialization.
+ * Useful for per-workspace or per-database write locking.
+ */
+export declare class WriteMutexMap {
+    private mutexes;
+    /**
+     * Acquire the mutex for a given key, execute the function, then release.
+     */
+    withLock<T>(key: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Remove a mutex for a key (e.g., when evicting a connection).
+     */
+    delete(key: string): void;
+    /**
+     * Get the number of tracked mutexes.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=write-mutex.d.ts.map

package/dist/src/write-mutex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-mutex.d.ts","sourceRoot":"","sources":["../../src/write-mutex.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAoC;IAEjD;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAkBvD;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAiC;IAEhD;;OAEG;IACG,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IASpE;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/src/write-mutex.js

@@ -0,0 +1,60 @@
+// packages/sqlite/src/write-mutex.ts
+// Promise-based per-resource write mutex for SQLite concurrency
+/**
+ * A simple async mutex that serializes write access to a resource.
+ * Bun is single-threaded, so this works as a plain promise queue —
+ * no atomic operations needed.
+ */
+export class WriteMutex {
+    queue = Promise.resolve();
+    /**
+     * Acquire the mutex, execute the function, then release.
+     * Only one function runs at a time per mutex instance.
+     */
+    async acquire(fn) {
+        let release;
+        const gate = new Promise(resolve => {
+            release = resolve;
+        });
+        // Chain onto the queue so we wait for prior operations
+        const prior = this.queue;
+        this.queue = gate;
+        await prior;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+}
+/**
+ * A map of named mutexes for per-resource write serialization.
+ * Useful for per-workspace or per-database write locking.
+ */
+export class WriteMutexMap {
+    mutexes = new Map();
+    /**
+     * Acquire the mutex for a given key, execute the function, then release.
+     */
+    async withLock(key, fn) {
+        let mutex = this.mutexes.get(key);
+        if (!mutex) {
+            mutex = new WriteMutex();
+            this.mutexes.set(key, mutex);
+        }
+        return mutex.acquire(fn);
+    }
+    /**
+     * Remove a mutex for a key (e.g., when evicting a connection).
+     */
+    delete(key) {
+        this.mutexes.delete(key);
+    }
+    /**
+     * Get the number of tracked mutexes.
+     */
+    get size() {
+        return this.mutexes.size;
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@bitclaw/sqlite",
+  "version": "1.1.0",
+  "description": "High-performance SQLite worker pool and utilities using bun:sqlite",
+  "files": ["dist", "scripts", "LICENSE", "README.md"],
+  "type": "module",
+  "exports": {
+    "./pool": { "types": "./dist/src/pool.d.ts", "default": "./dist/src/pool.js" },
+    "./worker": { "types": "./dist/src/worker.d.ts", "default": "./dist/src/worker.js" },
+    "./connection": { "types": "./dist/src/connection.d.ts", "default": "./dist/src/connection.js" },
+    "./json-cache": { "types": "./dist/src/json-cache.d.ts", "default": "./dist/src/json-cache.js" },
+    "./retry": { "types": "./dist/src/retry.d.ts", "default": "./dist/src/retry.js" },
+    "./write-mutex": { "types": "./dist/src/write-mutex.d.ts", "default": "./dist/src/write-mutex.js" },
+    "./prisma-immediate-tx": { "types": "./dist/src/prisma-immediate-tx.d.ts", "default": "./dist/src/prisma-immediate-tx.js" },
+    "./query-logger": { "types": "./dist/src/query-logger.d.ts", "default": "./dist/src/query-logger.js" },
+    "./ttl-cache": { "types": "./dist/src/ttl-cache.d.ts", "default": "./dist/src/ttl-cache.js" },
+    "./cache-lock": { "types": "./dist/src/cache-lock.d.ts", "default": "./dist/src/cache-lock.js" },
+    "./load-test-utils": { "types": "./dist/scripts/load-test-utils.d.ts", "default": "./dist/scripts/load-test-utils.js" }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "knip": "knip",
+    "benchmark": "bun scripts/benchmark.ts",
+    "benchmark:quick": "bun scripts/benchmark.ts --quick",
+    "prepublishOnly": "npm run build && npm run test",
+    "publish:dev": "npm run build && npm publish --tag dev --access public",
+    "publish:patch": "npm whoami && npm version patch && git push --follow-tags && npm publish --access public",
+    "publish:minor": "npm whoami && npm version minor && git push --follow-tags && npm publish --access public",
+    "publish:major": "npm whoami && npm version major && git push --follow-tags && npm publish --access public"
+  },
+  "keywords": ["sqlite", "bun", "worker-pool", "json-cache", "ttl-cache"],
+  "author": "bitclaw",
+  "license": "MIT",
+  "engines": { "bun": ">=1.3.0" },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "knip": "^6.12.1",
+    "@types/bun": "^1.3.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.3"
+  }
+}