@rivetkit/sqlite-vfs 2.1.5 → 2.1.6-rc.1

package/dist/tsup/index.d.ts

@@ -32,6 +32,29 @@ interface KvVfsOptions {
  * 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];
 /**
@@ -47,9 +70,9 @@ declare class AsyncMutex {
 /**
  * Database wrapper that provides a simplified SQLite API
  */
-declare class Database {
+declare class Database implements IDatabase {
     #private;
-    constructor(sqlite3: SQLite3Api, handle: number, fileName: string, onClose: () => void, sqliteMutex: AsyncMutex);
+    constructor(sqlite3: SQLite3Api, handle: number, fileName: string, onClose: () => Promise<void>, sqliteMutex: AsyncMutex);
     /**
      * Execute SQL with optional row callback
      * @param sql - SQL statement to execute
@@ -76,6 +99,10 @@ declare class Database {
      * Close the database
      */
     close(): Promise<void>;
+    /**
+     * Get the database file name
+     */
+    get fileName(): string;
     /**
      * Get the raw @rivetkit/sqlite API (for advanced usage)
      */
@@ -91,9 +118,9 @@ declare class Database {
  * Each instance is independent and has its own @rivetkit/sqlite WASM module.
  * This allows multiple instances to operate concurrently without interference.
  */
-declare class SqliteVfs {
+declare class SqliteVfs implements ISqliteVfs {
     #private;
-    constructor();
+    constructor(wasmModule?: WebAssembly.Module);
     /**
      * Open a SQLite database using KV storage backend
      *
@@ -101,7 +128,27 @@ declare class SqliteVfs {
      * @param options - KV storage operations for this database
      * @returns A Database instance
      */
-    open(fileName: string, options: KvVfsOptions): Promise<Database>;
+    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.
      */
@@ -112,4 +159,87 @@ declare class SqliteVfs {
     close(): Promise<void>;
 }
 
-export { Database, type KvVfsOptions, SqliteVfs };
+/**
+ * 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 };