@bitclaw/sqlite 1.1.0

package/dist/src/json-cache.js

@@ -0,0 +1,289 @@
+// packages/sqlite/src/json-cache.ts
+// levelsio-style JSON file caching for expensive queries
+import { randomBytes } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+const isDevelopment = process.env.NODE_ENV === 'development';
+const isCacheEntry = (data) => {
+    return (data != null &&
+        typeof data === 'object' &&
+        'value' in data &&
+        'metadata' in data &&
+        typeof data.metadata?.createdTime === 'number');
+};
+/**
+ * Simple, fast JSON file cache inspired by levelsio's approach
+ * - Each cache key is a separate JSON file
+ * - Atomic writes using temp files
+ * - TTL-based expiration
+ * - Stale-while-revalidate support
+ * - No external dependencies
+ */
+export class JsonCache {
+    cacheDir;
+    defaultTtl;
+    pendingWrites = new Map();
+    constructor(config) {
+        this.cacheDir = config.cacheDir;
+        this.defaultTtl = config.defaultTtl ?? 300000; // 5 minutes default
+    }
+    /**
+     * Initialize cache directory
+     */
+    async init() {
+        try {
+            await fs.mkdir(this.cacheDir, { recursive: true });
+            if (isDevelopment) {
+            }
+        }
+        catch (error) {
+            console.error('[json-cache] Failed to initialize:', error);
+            throw error;
+        }
+    }
+    /**
+     * Get cache file path for a key
+     */
+    getFilePath(key) {
+        // Sanitize key for filesystem
+        const sanitized = key.replace(/[^a-z0-9-_.]/gi, '_');
+        return join(this.cacheDir, `${sanitized}.json`);
+    }
+    /**
+     * Get value from cache
+     */
+    async get(key) {
+        const filePath = this.getFilePath(key);
+        try {
+            const data = await fs.readFile(filePath, 'utf-8');
+            const parsed = JSON.parse(data);
+            if (!isCacheEntry(parsed)) {
+                await this.delete(key);
+                return null;
+            }
+            const entry = parsed;
+            const now = Date.now();
+            const age = now - entry.metadata.createdTime;
+            // Check if expired
+            if (entry.metadata.ttl && age > entry.metadata.ttl) {
+                // Check stale-while-revalidate
+                if (entry.metadata.swr &&
+                    age <= entry.metadata.ttl + entry.metadata.swr) {
+                    // Return stale value but trigger background revalidation
+                    if (isDevelopment) {
+                    }
+                    return entry.value;
+                }
+                // Expired and past SWR window
+                await this.delete(key);
+                return null;
+            }
+            return entry.value;
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.code === 'ENOENT') {
+                // File doesn't exist - cache miss
+                return null;
+            }
+            console.error(`[json-cache] Error reading ${key}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Set value in cache with atomic write
+     */
+    async set(key, value, options) {
+        const filePath = this.getFilePath(key);
+        // If there's already a pending write for this key, wait for it
+        const pendingWrite = this.pendingWrites.get(key);
+        if (pendingWrite) {
+            await pendingWrite;
+        }
+        // Create new write promise
+        const writePromise = this._atomicWrite(filePath, value, options);
+        this.pendingWrites.set(key, writePromise);
+        try {
+            await writePromise;
+        }
+        finally {
+            this.pendingWrites.delete(key);
+        }
+    }
+    /**
+     * Atomic write using temp file
+     */
+    async _atomicWrite(filePath, value, options) {
+        const entry = {
+            value,
+            metadata: {
+                createdTime: Date.now(),
+                ttl: options?.ttl ?? this.defaultTtl,
+                swr: options?.swr ?? null
+            }
+        };
+        // Ensure directory exists
+        const dir = dirname(filePath);
+        await fs.mkdir(dir, { recursive: true });
+        // Write to temp file first (atomic operation)
+        const tempPath = `${filePath}.${randomBytes(8).toString('hex')}.tmp`;
+        try {
+            await fs.writeFile(tempPath, JSON.stringify(entry, null, isDevelopment ? 2 : 0), 'utf-8');
+            // Atomic rename
+            await fs.rename(tempPath, filePath);
+            if (isDevelopment) {
+            }
+        }
+        catch (error) {
+            // Clean up temp file if it exists
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+    /**
+     * Delete cache entry
+     */
+    async delete(key) {
+        const filePath = this.getFilePath(key);
+        try {
+            await fs.unlink(filePath);
+            if (isDevelopment) {
+            }
+        }
+        catch (error) {
+            if (!(error instanceof Error) ||
+                error.code !== 'ENOENT') {
+                console.error(`[json-cache] Error deleting ${key}:`, error);
+            }
+        }
+    }
+    /**
+     * Check if cache entry exists
+     */
+    async has(key) {
+        const filePath = this.getFilePath(key);
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Clear all cache entries
+     */
+    async clear() {
+        try {
+            const files = await fs.readdir(this.cacheDir);
+            await Promise.all(files
+                .filter(file => file.endsWith('.json'))
+                .map(file => fs.unlink(join(this.cacheDir, file))));
+            if (isDevelopment) {
+            }
+        }
+        catch (error) {
+            console.error('[json-cache] Error clearing cache:', error);
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    async stats() {
+        try {
+            const files = await fs.readdir(this.cacheDir);
+            const jsonFiles = files.filter(file => file.endsWith('.json'));
+            return {
+                size: jsonFiles.length,
+                entries: jsonFiles.map(file => file.replace('.json', ''))
+            };
+        }
+        catch {
+            return { size: 0, entries: [] };
+        }
+    }
+    /**
+     * Clean up expired entries
+     */
+    async cleanup() {
+        try {
+            const files = await fs.readdir(this.cacheDir);
+            const jsonFiles = files.filter(file => file.endsWith('.json'));
+            let cleaned = 0;
+            for (const file of jsonFiles) {
+                const filePath = join(this.cacheDir, file);
+                try {
+                    const data = await fs.readFile(filePath, 'utf-8');
+                    const parsed = JSON.parse(data);
+                    if (!isCacheEntry(parsed)) {
+                        await fs.unlink(filePath);
+                        cleaned++;
+                        continue;
+                    }
+                    const entry = parsed;
+                    const now = Date.now();
+                    const age = now - entry.metadata.createdTime;
+                    // Check if expired (including SWR window)
+                    const totalTtl = entry.metadata.ttl ?? this.defaultTtl;
+                    const swrWindow = entry.metadata.swr ?? 0;
+                    if (age > totalTtl + swrWindow) {
+                        await fs.unlink(filePath);
+                        cleaned++;
+                    }
+                }
+                catch {
+                    // If we can't read/parse the file, delete it
+                    await fs.unlink(filePath);
+                    cleaned++;
+                }
+            }
+            if (isDevelopment && cleaned > 0) {
+            }
+            return cleaned;
+        }
+        catch (error) {
+            console.error('[json-cache] Error during cleanup:', error);
+            return 0;
+        }
+    }
+}
+/**
+ * Factory function to create and initialize a JSON cache instance.
+ * Awaits directory creation so the cache is ready to use immediately.
+ */
+export const createJsonCache = async (config) => {
+    const cache = new JsonCache(config);
+    await cache.init();
+    // Set up periodic cleanup (every hour)
+    if (process.env.NODE_ENV !== 'test') {
+        setInterval(() => {
+            cache.cleanup().catch(error => {
+                console.error('[json-cache] Cleanup failed:', error);
+            });
+        }, 3600000); // 1 hour
+    }
+    return cache;
+};
+/**
+ * Helper function for cachified pattern
+ */
+export const cachified = async (options) => {
+    const { cache, key, getFreshValue, ttl, swr } = options;
+    // Try to get from cache
+    const cached = await cache.get(key);
+    if (cached !== null) {
+        return cached;
+    }
+    // Cache miss - get fresh value
+    const freshValue = await getFreshValue();
+    // Store in cache (don't await - fire and forget)
+    cache.set(key, freshValue, { ttl, swr }).catch(error => {
+        console.error(`[json-cache] Failed to cache ${key}:`, error);
+    });
+    return freshValue;
+};

package/dist/src/pool.d.ts

@@ -0,0 +1,98 @@
+import { EventEmitter } from 'node:events';
+export type PoolMetrics = {
+    totalQueries: number;
+    activeQueries: number;
+    totalDuration: number;
+    errors: number;
+    workerStats: {
+        [workerId: string]: {
+            queries: number;
+            errors: number;
+            totalDuration: number;
+        };
+    };
+};
+export type PoolConfig = {
+    databasePath?: string;
+    poolSize?: number;
+    timeout?: number;
+};
+declare class SQLiteConnectionPool extends EventEmitter {
+    private workers;
+    private maxWorkers;
+    private workerTimeout;
+    private databasePath;
+    private pendingOperations;
+    private nextWorkerIndex;
+    private isShuttingDown;
+    private metrics;
+    constructor(config?: PoolConfig);
+    private initializePool;
+    private handleWorkerMessage;
+    private handleWorkerError;
+    private handleWorkerExit;
+    /**
+     * Execute SQL query with parameters
+     */
+    exec<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+    /**
+     * Execute operations on a specific worker (for transactions)
+     */
+    execOnWorker<T = unknown>(workerIndex: number, sql: string, params?: unknown[]): Promise<T>;
+    /**
+     * Get current pool metrics
+     */
+    getMetrics(): PoolMetrics;
+    /**
+     * Get pool status for health checks
+     */
+    getStatus(): {
+        workers: number;
+        activeQueries: number;
+        isShuttingDown: boolean;
+        totalQueries: number;
+        errorRate: number;
+        avgDuration: number;
+    };
+    /**
+     * Graceful shutdown of the connection pool
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+}
+/**
+ * Create a new connection pool instance
+ */
+export declare function createPool(config?: PoolConfig): SQLiteConnectionPool;
+/**
+ * Get the singleton connection pool instance
+ */
+export declare function getPool(): SQLiteConnectionPool;
+/**
+ * Execute SQL query using the connection pool
+ */
+export declare function exec<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+/**
+ * Get pool metrics for monitoring
+ */
+export declare function getPoolMetrics(): PoolMetrics;
+/**
+ * Get pool status for health checks
+ */
+export declare function getPoolStatus(): {
+    workers: number;
+    activeQueries: number;
+    isShuttingDown: boolean;
+    totalQueries: number;
+    errorRate: number;
+    avgDuration: number;
+};
+/**
+ * Shutdown the connection pool
+ */
+export declare function shutdownPool(timeoutMs?: number): Promise<void>;
+/**
+ * Execute multiple operations atomically on a single worker
+ */
+export declare function withTransaction<T>(operation: (execute: (sql: string, params?: unknown[]) => Promise<unknown>) => Promise<T>): Promise<T>;
+export {};
+//# sourceMappingURL=pool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/pool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0B3C,MAAM,MAAM,WAAW,GAAG;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE;QACX,CAAC,QAAQ,EAAE,MAAM,GAAG;YAClB,OAAO,EAAE,MAAM,CAAC;YAChB,MAAM,EAAE,MAAM,CAAC;YACf,aAAa,EAAE,MAAM,CAAC;SACvB,CAAC;KACH,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,cAAM,oBAAqB,SAAQ,YAAY;IAC7C,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAqB;IAEzC,OAAO,CAAC,iBAAiB,CASrB;IAEJ,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,cAAc,CAAS;IAE/B,OAAO,CAAC,OAAO,CAMb;gBAEU,MAAM,CAAC,EAAE,UAAU;IAgB/B,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,mBAAmB;IAyD3B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAyCxE;;OAEG;IACG,YAAY,CAAC,CAAC,GAAG,OAAO,EAC5B,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC;IAyCb;;OAEG;IACH,UAAU,IAAI,WAAW;IAOzB;;OAEG;IACH,SAAS;;;;;;;;IAiBT;;OAEG;IACG,QAAQ,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAqChD;AAKD;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,oBAAoB,CAQpE;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,oBAAoB,CAK9C;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,CAAC,GAAG,OAAO,EACpC,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;GAEG;AACH,wBAAgB,aAAa;;;;;;;EAE5B;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAcpE;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,SAAS,EAAE,CACT,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,KAC3D,OAAO,CAAC,CAAC,CAAC,GACd,OAAO,CAAC,CAAC,CAAC,CA4BZ"}