@bitclaw/sqlite 1.1.0

package/dist/scripts/load-test-utils.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env bun
+/**
+ * Shared load test utilities for application-level HTTP throughput testing.
+ *
+ * Unlike benchmark.ts (which tests raw SQLite pool.exec() calls), these utilities
+ * measure end-to-end HTTP performance through the full stack: HTTP server, middleware,
+ * ORM (Prisma), SSR rendering, etc.
+ *
+ * Usage:
+ *   Import into app-specific load tests:
+ *     import { runLoadTest, formatResults } from '@bitclaw/sqlite/load-test-utils'
+ *
+ *   Or run directly for a quick test:
+ *     bun run packages/sqlite/scripts/load-test-utils.ts --url http://localhost:3001
+ */
+/* ------------------------------------------------------------------
+ * Percentile calculation (reused from benchmark.ts)
+ * ------------------------------------------------------------------ */
+export function percentile(sorted, p) {
+    if (!sorted.length)
+        return 0;
+    const idx = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(idx);
+    const hi = Math.ceil(idx);
+    const loVal = sorted[lo] ?? 0;
+    const hiVal = sorted[hi] ?? 0;
+    if (lo === hi)
+        return loVal;
+    return loVal + (hiVal - loVal) * (idx - lo);
+}
+/* ------------------------------------------------------------------
+ * Single request measurement
+ * ------------------------------------------------------------------ */
+export async function measureResponseTime(url, method = 'GET', body, headers) {
+    const start = performance.now();
+    try {
+        const response = await fetch(url, {
+            method,
+            body: method !== 'GET' ? body : undefined,
+            headers: {
+                Accept: 'text/html,application/json',
+                'User-Agent': 'sqlite-saas-load-test/1.0',
+                ...headers
+            }
+        });
+        const responseBody = await response.text();
+        const latencyMs = performance.now() - start;
+        return {
+            statusCode: response.status,
+            latencyMs,
+            success: response.status >= 200 && response.status < 400,
+            bodySize: responseBody.length
+        };
+    }
+    catch {
+        return {
+            statusCode: 0,
+            latencyMs: performance.now() - start,
+            success: false,
+            bodySize: 0
+        };
+    }
+}
+/* ------------------------------------------------------------------
+ * Worker loop for sustained load
+ * ------------------------------------------------------------------ */
+async function workerLoop(url, method, body, headers, endTs, results) {
+    while (performance.now() < endTs) {
+        const result = await measureResponseTime(url, method, body, headers);
+        results.push(result);
+    }
+}
+/* ------------------------------------------------------------------
+ * Run a single scenario (one endpoint at one concurrency level)
+ * ------------------------------------------------------------------ */
+async function runScenario(baseUrl, endpoint, concurrency, durationSec, warmupRequests) {
+    const url = `${baseUrl}${endpoint.path}`;
+    const method = endpoint.method ?? 'GET';
+    const label = endpoint.label ?? endpoint.path;
+    // Warm-up phase
+    if (warmupRequests > 0) {
+        const warmups = Array.from({ length: Math.min(warmupRequests, concurrency) }, () => measureResponseTime(url, method, endpoint.body, endpoint.headers));
+        await Promise.allSettled(warmups);
+    }
+    // Measurement phase
+    const results = [];
+    const endTs = performance.now() + durationSec * 1000;
+    const workers = Array.from({ length: concurrency }, () => workerLoop(url, method, endpoint.body, endpoint.headers, endTs, results));
+    await Promise.allSettled(workers);
+    // Calculate metrics
+    const latencies = results.map(r => r.latencyMs).sort((a, b) => a - b);
+    const successCount = results.filter(r => r.success).length;
+    const failCount = results.length - successCount;
+    const totalBodySize = results.reduce((sum, r) => sum + r.bodySize, 0);
+    const statusCodes = {};
+    for (const r of results) {
+        statusCodes[r.statusCode] = (statusCodes[r.statusCode] ?? 0) + 1;
+    }
+    return {
+        endpoint: endpoint.path,
+        label,
+        method,
+        concurrency,
+        durationSec,
+        totalRequests: results.length,
+        successCount,
+        failCount,
+        successRate: results.length > 0 ? (successCount / results.length) * 100 : 0,
+        throughput: results.length / durationSec,
+        p50: percentile(latencies, 50),
+        p95: percentile(latencies, 95),
+        p99: percentile(latencies, 99),
+        min: latencies[0] ?? 0,
+        max: latencies.at(-1) ?? 0,
+        avg: latencies.length > 0
+            ? latencies.reduce((a, b) => a + b, 0) / latencies.length
+            : 0,
+        statusCodes,
+        avgBodySize: results.length > 0 ? totalBodySize / results.length : 0
+    };
+}
+/* ------------------------------------------------------------------
+ * Main load test runner
+ * ------------------------------------------------------------------ */
+export async function runLoadTest(config) {
+    const startedAt = new Date().toISOString();
+    const scenarios = [];
+    const warmup = config.warmupRequests ?? 5;
+    for (const endpoint of config.endpoints) {
+        for (const concurrency of config.concurrencyLevels) {
+            const _label = endpoint.label ?? endpoint.path;
+            const result = await runScenario(config.baseUrl, endpoint, concurrency, config.durationSec, warmup);
+            scenarios.push(result);
+        }
+    }
+    return {
+        baseUrl: config.baseUrl,
+        startedAt,
+        completedAt: new Date().toISOString(),
+        scenarios
+    };
+}
+/* ------------------------------------------------------------------
+ * Format results as a table
+ * ------------------------------------------------------------------ */
+export function formatResults(results) {
+    const lines = [];
+    lines.push('');
+    lines.push('='.repeat(100));
+    lines.push('  APPLICATION-LEVEL LOAD TEST RESULTS');
+    lines.push(`  Target: ${results.baseUrl}`);
+    lines.push(`  Started: ${results.startedAt}`);
+    lines.push(`  Completed: ${results.completedAt}`);
+    lines.push('='.repeat(100));
+    lines.push('');
+    // Summary table header
+    const header = [
+        'Endpoint'.padEnd(25),
+        'Conc'.padStart(5),
+        'Req/s'.padStart(8),
+        'Total'.padStart(7),
+        'P50ms'.padStart(8),
+        'P95ms'.padStart(8),
+        'P99ms'.padStart(8),
+        'Success'.padStart(8),
+        'AvgBody'.padStart(8)
+    ].join(' | ');
+    lines.push(header);
+    lines.push('-'.repeat(header.length));
+    for (const s of results.scenarios) {
+        const row = [
+            s.label.padEnd(25).slice(0, 25),
+            String(s.concurrency).padStart(5),
+            s.throughput.toFixed(0).padStart(8),
+            String(s.totalRequests).padStart(7),
+            s.p50.toFixed(1).padStart(8),
+            s.p95.toFixed(1).padStart(8),
+            s.p99.toFixed(1).padStart(8),
+            `${s.successRate.toFixed(1)}%`.padStart(8),
+            formatBytes(s.avgBodySize).padStart(8)
+        ].join(' | ');
+        lines.push(row);
+    }
+    lines.push('');
+    // Pool-level comparison note
+    lines.push('-'.repeat(100));
+    lines.push('  NOTE: Pool-level benchmarks (raw pool.exec) show 6,102-13,781 req/s.');
+    lines.push('  Application-level throughput is lower due to HTTP overhead, middleware,');
+    lines.push('  Prisma ORM, SSR rendering, and serialization.');
+    lines.push('-'.repeat(100));
+    lines.push('');
+    // Status code breakdown
+    lines.push('  Status Code Breakdown:');
+    for (const s of results.scenarios) {
+        const codes = Object.entries(s.statusCodes)
+            .map(([code, count]) => `${code}:${count}`)
+            .join(', ');
+        lines.push(`    ${s.label} @${s.concurrency}: ${codes}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${Math.round(bytes)}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+/* ------------------------------------------------------------------
+ * CLI: run directly for a quick smoke test
+ * ------------------------------------------------------------------ */
+async function main() {
+    const args = process.argv.slice(2);
+    const urlIdx = args.indexOf('--url');
+    const baseUrl = (urlIdx !== -1 ? args[urlIdx + 1] : undefined) ?? 'http://localhost:3001';
+    if (args.includes('--help')) {
+        process.exit(0);
+    }
+    // Quick smoke test against the provided URL
+    const _results = await runLoadTest({
+        baseUrl,
+        endpoints: [{ path: '/', label: 'Homepage' }],
+        concurrencyLevels: [1, 10],
+        durationSec: 5,
+        warmupRequests: 3
+    });
+}
+// Run if executed directly
+if (import.meta.path === Bun.main) {
+    main().catch(err => {
+        console.error('Load test failed:', err);
+        process.exit(1);
+    });
+}

package/dist/src/cache-lock.d.ts

@@ -0,0 +1,25 @@
+import type { Database } from 'bun:sqlite';
+export type LockResult = {
+    acquired: boolean;
+    owner: string;
+};
+export declare class CacheLock {
+    private readonly db;
+    private readonly acquireStmt;
+    private readonly checkOwnerStmt;
+    private readonly releaseStmt;
+    private readonly forceReleaseStmt;
+    private readonly refreshStmt;
+    private readonly isLockedStmt;
+    private readonly pruneExpiredStmt;
+    private readonly deleteExpiredStmt;
+    constructor(db: Database);
+    acquire(key: string, ttlMs: number, owner?: string): LockResult;
+    release(key: string, owner: string): boolean;
+    forceRelease(key: string): boolean;
+    refresh(key: string, ttlMs: number, owner: string): boolean;
+    isLocked(key: string): boolean;
+    pruneExpired(): number;
+    withLock<T>(key: string, ttlMs: number, fn: () => T | Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=cache-lock.d.ts.map

package/dist/src/cache-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-lock.d.ts","sourceRoot":"","sources":["../../src/cache-lock.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAE9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;gBAEvB,EAAE,EAAE,QAAQ;IAyCxB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU;IA+B/D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAK5C,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKlC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAU3D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK9B,YAAY,IAAI,MAAM;IAKhB,QAAQ,CAAC,CAAC,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC;CAYd"}

package/dist/src/cache-lock.js

@@ -0,0 +1,95 @@
+// packages/sqlite/src/cache-lock.ts
+// DB-backed distributed locks for mutual exclusion using bun:sqlite
+import { randomUUID } from 'node:crypto';
+export class CacheLock {
+    db;
+    acquireStmt;
+    checkOwnerStmt;
+    releaseStmt;
+    forceReleaseStmt;
+    refreshStmt;
+    isLockedStmt;
+    pruneExpiredStmt;
+    deleteExpiredStmt;
+    constructor(db) {
+        this.db = db;
+        db.run(`
+      CREATE TABLE IF NOT EXISTS cache_locks (
+        key TEXT PRIMARY KEY,
+        owner TEXT NOT NULL,
+        expiration INTEGER NOT NULL
+      )
+    `);
+        db.run(`
+      CREATE INDEX IF NOT EXISTS idx_cache_locks_expiration
+        ON cache_locks (expiration)
+    `);
+        this.deleteExpiredStmt = db.query('DELETE FROM cache_locks WHERE key = $key AND expiration <= $now');
+        this.acquireStmt = db.query('INSERT OR IGNORE INTO cache_locks (key, owner, expiration) VALUES ($key, $owner, $expiration)');
+        this.checkOwnerStmt = db.query('SELECT owner FROM cache_locks WHERE key = $key');
+        this.releaseStmt = db.query('DELETE FROM cache_locks WHERE key = $key AND owner = $owner');
+        this.forceReleaseStmt = db.query('DELETE FROM cache_locks WHERE key = $key');
+        this.refreshStmt = db.query('UPDATE cache_locks SET expiration = $expiration WHERE key = $key AND owner = $owner');
+        this.isLockedStmt = db.query('SELECT 1 FROM cache_locks WHERE key = $key AND expiration > $now LIMIT 1');
+        this.pruneExpiredStmt = db.query('DELETE FROM cache_locks WHERE expiration <= $now');
+    }
+    acquire(key, ttlMs, owner) {
+        const actualOwner = owner ?? randomUUID();
+        const now = Date.now();
+        const expiration = now + ttlMs;
+        const result = this.db.transaction(() => {
+            // Remove expired lock for this key first
+            this.deleteExpiredStmt.run({ $key: key, $now: now });
+            // Try to insert — OR IGNORE means it fails silently if key exists
+            this.acquireStmt.run({
+                $key: key,
+                $owner: actualOwner,
+                $expiration: expiration
+            });
+            // Check who owns the lock
+            const row = this.checkOwnerStmt.get({ $key: key });
+            if (row && row.owner === actualOwner) {
+                return { acquired: true, owner: actualOwner };
+            }
+            return { acquired: false, owner: row?.owner ?? '' };
+        });
+        return result.immediate();
+    }
+    release(key, owner) {
+        const result = this.releaseStmt.run({ $key: key, $owner: owner });
+        return result.changes > 0;
+    }
+    forceRelease(key) {
+        const result = this.forceReleaseStmt.run({ $key: key });
+        return result.changes > 0;
+    }
+    refresh(key, ttlMs, owner) {
+        const expiration = Date.now() + ttlMs;
+        const result = this.refreshStmt.run({
+            $key: key,
+            $owner: owner,
+            $expiration: expiration
+        });
+        return result.changes > 0;
+    }
+    isLocked(key) {
+        const row = this.isLockedStmt.get({ $key: key, $now: Date.now() });
+        return row != null;
+    }
+    pruneExpired() {
+        const result = this.pruneExpiredStmt.run({ $now: Date.now() });
+        return result.changes;
+    }
+    async withLock(key, ttlMs, fn) {
+        const result = this.acquire(key, ttlMs);
+        if (!result.acquired) {
+            throw new Error(`Failed to acquire lock: ${key}`);
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            this.release(key, result.owner);
+        }
+    }
+}

package/dist/src/connection.d.ts

@@ -0,0 +1,26 @@
+import { Database } from 'bun:sqlite';
+export type ConnectionConfig = {
+    path: string;
+    readonly?: boolean;
+    verbose?: boolean;
+};
+/**
+ * Initialize a SQLite database with optimal settings
+ */
+export declare function initializeConnection(config: ConnectionConfig): Database;
+/**
+ * Close database connection gracefully
+ */
+export declare function closeConnection(db: Database): void;
+/**
+ * Check database health
+ */
+export declare function checkHealth(db: Database): {
+    healthy: boolean;
+    details: Record<string, unknown>;
+};
+/**
+ * Get database statistics
+ */
+export declare function getStats(db: Database): Record<string, unknown>;
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/connection.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ,CA+BvE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAalD;AAkCD;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CA6BA;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiB9D"}

package/dist/src/connection.js

@@ -0,0 +1,132 @@
+// packages/sqlite/src/connection.ts
+// Database connection initialization and configuration
+// Uses bun:sqlite for 3-6x faster reads compared to better-sqlite3
+import { Database } from 'bun:sqlite';
+/**
+ * Initialize a SQLite database with optimal settings
+ */
+export function initializeConnection(config) {
+    const db = new Database(config.path, {
+        readonly: config.readonly ?? false,
+        create: true
+    });
+    // Apply optimal PRAGMA settings
+    if (config.path !== ':memory:') {
+        // WAL mode for better concurrency
+        db.run('PRAGMA journal_mode = WAL');
+        // Reduced busy timeout for worker coordination
+        db.run('PRAGMA busy_timeout = 5000');
+        // More frequent checkpoints
+        db.run('PRAGMA wal_autocheckpoint = 100');
+        // Note: cache_shared is not available in bun:sqlite
+    }
+    // Performance optimizations
+    db.run('PRAGMA foreign_keys = ON');
+    db.run('PRAGMA synchronous = NORMAL'); // Safe with WAL
+    db.run('PRAGMA cache_size = -4000'); // 4MB cache
+    db.run('PRAGMA temp_store = MEMORY');
+    db.run('PRAGMA mmap_size = 67108864'); // 64MB mmap
+    // Query optimizer
+    db.run('PRAGMA optimize');
+    return db;
+}
+/**
+ * Close database connection gracefully
+ */
+export function closeConnection(db) {
+    try {
+        // Checkpoint WAL before closing
+        try {
+            db.run('PRAGMA wal_checkpoint(TRUNCATE)');
+        }
+        catch (error) {
+            console.warn('[db] WAL checkpoint failed:', error);
+        }
+        db.close();
+    }
+    catch (error) {
+        console.error('[db] Error closing connection:', error);
+    }
+}
+/**
+ * Whitelist of allowed PRAGMA names to prevent SQL injection
+ * via string interpolation in getPragmaValue.
+ */
+const ALLOWED_PRAGMAS = new Set([
+    'journal_mode',
+    'wal_autocheckpoint',
+    'busy_timeout',
+    'cache_size',
+    'foreign_keys',
+    'synchronous',
+    'temp_store',
+    'mmap_size',
+    'page_size',
+    'locking_mode',
+    'page_count',
+    'wal_checkpoint'
+]);
+/**
+ * Helper to get a PRAGMA value
+ */
+function getPragmaValue(db, pragma) {
+    if (!ALLOWED_PRAGMAS.has(pragma)) {
+        throw new Error(`PRAGMA "${pragma}" is not allowed. Allowed PRAGMAs: ${[...ALLOWED_PRAGMAS].join(', ')}`);
+    }
+    const result = db.query(`PRAGMA ${pragma}`).get();
+    return result ? Object.values(result)[0] : null;
+}
+/**
+ * Check database health
+ */
+export function checkHealth(db) {
+    try {
+        // Simple query to verify database is accessible
+        const result = db.query('SELECT 1 as health').get();
+        const walInfo = db.query('PRAGMA wal_checkpoint').all();
+        const pageCount = getPragmaValue(db, 'page_count');
+        const pageSize = getPragmaValue(db, 'page_size');
+        return {
+            healthy: result.health === 1,
+            details: {
+                accessible: true,
+                journalMode: getPragmaValue(db, 'journal_mode'),
+                pageCount,
+                pageSize,
+                databaseSize: pageCount * pageSize,
+                walInfo
+            }
+        };
+    }
+    catch (error) {
+        return {
+            healthy: false,
+            details: {
+                error: error instanceof Error ? error.message : String(error),
+                accessible: false
+            }
+        };
+    }
+}
+/**
+ * Get database statistics
+ */
+export function getStats(db) {
+    try {
+        return {
+            journalMode: getPragmaValue(db, 'journal_mode'),
+            pageCount: getPragmaValue(db, 'page_count'),
+            pageSize: getPragmaValue(db, 'page_size'),
+            cacheSize: getPragmaValue(db, 'cache_size'),
+            mmapSize: getPragmaValue(db, 'mmap_size'),
+            walAutocheckpoint: getPragmaValue(db, 'wal_autocheckpoint'),
+            synchronous: getPragmaValue(db, 'synchronous'),
+            foreignKeys: getPragmaValue(db, 'foreign_keys')
+        };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}

package/dist/src/json-cache.d.ts

@@ -0,0 +1,89 @@
+export type CacheEntry<T> = {
+    value: T;
+    metadata: {
+        createdTime: number;
+        ttl: number | null;
+        swr?: number | null;
+    };
+};
+export type CacheOptions = {
+    ttl?: number;
+    swr?: number;
+};
+export type JsonCacheConfig = {
+    cacheDir: string;
+    defaultTtl?: 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 declare class JsonCache {
+    private cacheDir;
+    private defaultTtl;
+    private pendingWrites;
+    constructor(config: JsonCacheConfig);
+    /**
+     * Initialize cache directory
+     */
+    init(): Promise<void>;
+    /**
+     * Get cache file path for a key
+     */
+    private getFilePath;
+    /**
+     * Get value from cache
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set value in cache with atomic write
+     */
+    set<T = unknown>(key: string, value: T, options?: CacheOptions): Promise<void>;
+    /**
+     * Atomic write using temp file
+     */
+    private _atomicWrite;
+    /**
+     * Delete cache entry
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if cache entry exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clear all cache entries
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    stats(): Promise<{
+        size: number;
+        entries: string[];
+    }>;
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): Promise<number>;
+}
+/**
+ * Factory function to create and initialize a JSON cache instance.
+ * Awaits directory creation so the cache is ready to use immediately.
+ */
+export declare const createJsonCache: (config: JsonCacheConfig) => Promise<JsonCache>;
+/**
+ * Helper function for cachified pattern
+ */
+export declare const cachified: <T>(options: {
+    cache: JsonCache;
+    key: string;
+    getFreshValue: () => Promise<T>;
+    ttl?: number;
+    swr?: number;
+}) => Promise<T>;
+//# sourceMappingURL=json-cache.d.ts.map

package/dist/src/json-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-cache.d.ts","sourceRoot":"","sources":["../../src/json-cache.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAC1B,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE;QACR,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAoC;gBAE7C,MAAM,EAAE,eAAe;IAKnC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IA+CtD;;OAEG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,IAAI,CAAC;IAoBhB;;OAEG;YACW,YAAY;IA4C1B;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBxC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAc3D;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;CA+CjC;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,eAAe,KACtB,OAAO,CAAC,SAAS,CAenB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,EAAE,SAAS;IAC1C,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,KAAG,OAAO,CAAC,CAAC,CAkBZ,CAAC"}