@rivetkit/sqlite-wasm 2.2.1-pr.4600.b74ff3b

package/dist/tsup/index.d.ts

@@ -0,0 +1,253 @@
+import { Factory } from '@rivetkit/sqlite';
+
+interface KvVfsOptions {
+    /** Get a single value by key. Returns null if missing. */
+    get: (key: Uint8Array) => Promise<Uint8Array | null>;
+    /** Get multiple values by keys. Returns null for missing keys. */
+    getBatch: (keys: Uint8Array[]) => Promise<(Uint8Array | null)[]>;
+    /** Put a single key-value pair */
+    put: (key: Uint8Array, value: Uint8Array) => Promise<void>;
+    /** Put multiple key-value pairs */
+    putBatch: (entries: [Uint8Array, Uint8Array][]) => Promise<void>;
+    /** Delete multiple keys */
+    deleteBatch: (keys: Uint8Array[]) => Promise<void>;
+    /**
+     * Called when a KV operation fails inside a VFS callback. The VFS must
+     * return a generic SQLite error code to the pager, so the original error
+     * is lost unless the caller captures it through this callback.
+     */
+    onError?: (error: unknown) => void;
+    /** Delete all keys in the half-open range [start, end). */
+    deleteRange: (start: Uint8Array, end: Uint8Array) => Promise<void>;
+}
+
+/**
+ * SQLite raw database with KV storage backend
+ *
+ * This module provides a SQLite API that uses a KV-backed VFS
+ * for storage. Each SqliteVfs instance is independent and can be
+ * used concurrently with other instances.
+ *
+ * Keep this VFS on direct VFS.Base callbacks for minimal wrapper overhead.
+ * Use @rivetkit/sqlite/src/FacadeVFS.js as the reference implementation for
+ * callback ABI and pointer/data conversion behavior.
+ * This implementation is optimized for single-writer semantics because each
+ * actor owns one SQLite database.
+ * SQLite invokes this VFS with byte-range file operations. This VFS maps those
+ * ranges onto fixed-size KV chunks keyed by file tag and chunk index.
+ * We intentionally rely on SQLite's pager cache for hot page reuse and do not
+ * add a second cache in this VFS. This avoids duplicate cache invalidation
+ * logic and keeps memory usage predictable for each actor.
+ */
+
+/**
+ * Common interface for database handles returned by ISqliteVfs.open().
+ * Both the concrete Database class and the pool's TrackedDatabase wrapper
+ * implement this, so consumers can use either interchangeably.
+ */
+interface IDatabase {
+    exec(sql: string, callback?: (row: unknown[], columns: string[]) => void): Promise<void>;
+    run(sql: string, params?: SqliteBindings): Promise<void>;
+    query(sql: string, params?: SqliteBindings): Promise<{
+        rows: unknown[][];
+        columns: string[];
+    }>;
+    close(): Promise<void>;
+    readonly fileName: string;
+}
+/**
+ * Common interface for SQLite VFS backends. Both standalone SqliteVfs and
+ * PooledSqliteHandle implement this so callers can use either interchangeably.
+ */
+interface ISqliteVfs {
+    open(fileName: string, options: KvVfsOptions): Promise<IDatabase>;
+    destroy(): Promise<void>;
+}
+type SQLite3Api = ReturnType<typeof Factory>;
+type SqliteBindings = Parameters<SQLite3Api["bind_collection"]>[1];
+/**
+ * Simple async mutex for serializing database operations
+ * @rivetkit/sqlite calls are not safe to run concurrently on one module instance
+ */
+declare class AsyncMutex {
+    #private;
+    acquire(): Promise<void>;
+    release(): void;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Database wrapper that provides a simplified SQLite API
+ */
+declare class Database implements IDatabase {
+    #private;
+    constructor(sqlite3: SQLite3Api, handle: number, fileName: string, onClose: () => Promise<void>, sqliteMutex: AsyncMutex);
+    /**
+     * Execute SQL with optional row callback
+     * @param sql - SQL statement to execute
+     * @param callback - Called for each result row with (row, columns)
+     */
+    exec(sql: string, callback?: (row: unknown[], columns: string[]) => void): Promise<void>;
+    /**
+     * Execute a parameterized SQL statement (no result rows)
+     * @param sql - SQL statement with ? placeholders
+     * @param params - Parameter values to bind
+     */
+    run(sql: string, params?: SqliteBindings): Promise<void>;
+    /**
+     * Execute a parameterized SQL query and return results
+     * @param sql - SQL query with ? placeholders
+     * @param params - Parameter values to bind
+     * @returns Object with rows (array of arrays) and columns (column names)
+     */
+    query(sql: string, params?: SqliteBindings): Promise<{
+        rows: unknown[][];
+        columns: string[];
+    }>;
+    /**
+     * Close the database
+     */
+    close(): Promise<void>;
+    /**
+     * Get the database file name
+     */
+    get fileName(): string;
+    /**
+     * Get the raw @rivetkit/sqlite API (for advanced usage)
+     */
+    get sqlite3(): SQLite3Api;
+    /**
+     * Get the raw database handle (for advanced usage)
+     */
+    get handle(): number;
+}
+/**
+ * SQLite VFS backed by KV storage.
+ *
+ * Each instance is independent and has its own @rivetkit/sqlite WASM module.
+ * This allows multiple instances to operate concurrently without interference.
+ */
+declare class SqliteVfs implements ISqliteVfs {
+    #private;
+    constructor(wasmModule?: WebAssembly.Module);
+    /**
+     * Open a SQLite database using KV storage backend
+     *
+     * @param fileName - The database file name (typically the actor ID)
+     * @param options - KV storage operations for this database
+     * @returns A Database instance
+     */
+    open(fileName: string, options: KvVfsOptions): Promise<IDatabase>;
+    /**
+     * Force-close all Database handles whose fileName exactly matches the
+     * given name. Snapshots the set to an array before iterating to avoid
+     * mutation during async iteration.
+     *
+     * Uses exact file name match because short names are numeric strings
+     * ('0', '1', ..., '10', '11', ...) and a prefix match like
+     * startsWith('1') would incorrectly match '10', '11', etc., causing
+     * cross-actor corruption. Sidecar files (-journal, -wal, -shm) are not
+     * tracked as separate Database handles, so prefix matching for sidecars
+     * is not needed.
+     */
+    forceCloseByFileName(fileName: string): Promise<{
+        allSucceeded: boolean;
+    }>;
+    /**
+     * Force-close all open Database handles. Best-effort: errors are
+     * swallowed so this is safe to call during instance teardown.
+     */
+    forceCloseAll(): Promise<void>;
+    /**
+     * Tears down this VFS instance and releases internal references.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Alias for destroy to align with DB-style lifecycle naming.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * SQLite VFS Pool - shares WASM SQLite instances across actors to reduce
+ * memory overhead. Instead of one WASM module per actor, multiple actors
+ * share a single instance, with short file names routing to separate KV
+ * namespaces.
+ */
+
+interface SqliteVfsPoolConfig {
+    actorsPerInstance: number;
+    idleDestroyMs?: number;
+}
+/**
+ * Manages a pool of SqliteVfs instances, assigning actors to instances using
+ * bin-packing to maximize density. The WASM module is compiled once and
+ * reused across all instances.
+ */
+declare class SqliteVfsPool {
+    #private;
+    constructor(config: SqliteVfsPoolConfig);
+    /** Number of live WASM instances in the pool. */
+    get instanceCount(): number;
+    /** Number of actors currently assigned to pool instances. */
+    get actorCount(): number;
+    /**
+     * Acquire a pooled VFS handle for the given actor. Returns a
+     * PooledSqliteHandle with sticky assignment. If the actor is already
+     * assigned, the existing handle is returned.
+     *
+     * Bin-packing: picks the instance with the most actors that still has
+     * capacity. If all instances are full, creates a new one using the
+     * cached WASM module.
+     */
+    acquire(actorId: string): Promise<PooledSqliteHandle>;
+    /**
+     * Release an actor's assignment from the pool. Force-closes all database
+     * handles for the actor, recycles or poisons the short name, and
+     * decrements the instance refcount.
+     */
+    release(actorId: string): Promise<void>;
+    /**
+     * Open a database on behalf of an actor, tracked as an in-flight
+     * operation. Used by PooledSqliteHandle to avoid exposing PoolInstance.
+     */
+    openForActor(actorId: string, shortName: string, options: KvVfsOptions): Promise<IDatabase>;
+    /**
+     * Track an in-flight database operation for the given actor. Resolves the
+     * actor's pool instance and wraps the operation with opsInFlight tracking.
+     * If the actor has already been released, the operation runs without
+     * tracking since the instance may already be destroyed.
+     */
+    trackOpForActor<T>(actorId: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Graceful shutdown. Rejects new acquire() calls, cancels idle timers,
+     * force-closes all databases, destroys all VFS instances, and clears pool
+     * state.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * A pooled VFS handle for a single actor. Implements ISqliteVfs so callers
+ * can use it interchangeably with a standalone SqliteVfs. The short name
+ * assigned by the pool is used as the VFS file path, while the caller's
+ * KvVfsOptions routes data to the correct KV namespace.
+ */
+declare class PooledSqliteHandle implements ISqliteVfs {
+    #private;
+    constructor(shortName: string, actorId: string, pool: SqliteVfsPool);
+    /**
+     * Open a database on the shared instance. Uses the pool-assigned short
+     * name as the VFS file path, with the caller's KvVfsOptions for KV
+     * routing. The open call itself is tracked as an in-flight operation,
+     * and the returned Database is wrapped so that exec(), run(), query(),
+     * and close() are also tracked via opsInFlight.
+     */
+    open(_fileName: string, options: KvVfsOptions): Promise<IDatabase>;
+    /**
+     * Release this actor's assignment back to the pool. Idempotent: calling
+     * destroy() more than once is a no-op, preventing double-release from
+     * decrementing the instance refcount below actual.
+     */
+    destroy(): Promise<void>;
+}
+
+export { Database, type IDatabase, type ISqliteVfs, type KvVfsOptions, PooledSqliteHandle, SqliteVfs, SqliteVfsPool, type SqliteVfsPoolConfig };