@xnetjs/sqlite 0.0.3 → 0.1.0

package/dist/adapters/expo.d.ts

@@ -1,5 +1,5 @@
-import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-t2aqQ__n.js';
-import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from '../types-DMrj3K4o.js';
+import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-imtxkmXZ.js';
+import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from '../types-BTabr_VP.js';
 
 /**
  * @xnetjs/sqlite - Expo SQLite adapter using expo-sqlite
@@ -31,6 +31,10 @@ declare class ExpoSQLiteAdapter implements SQLiteAdapter {
     isOpen(): boolean;
     query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
     queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
+    queryBatch(reads: Array<{
+        sql: string;
+        params?: SQLValue[];
+    }>): Promise<SQLRow[][]>;
     run(sql: string, params?: SQLValue[]): Promise<RunResult>;
     exec(sql: string): Promise<void>;
     transaction<T>(fn: () => Promise<T>): Promise<T>;

package/dist/adapters/expo.js

@@ -4,7 +4,7 @@ import {
 import {
   SCHEMA_DDL,
   SCHEMA_VERSION
-} from "../chunk-NVD7G7DZ.js";
+} from "../chunk-W3L4FXU5.js";
 
 // src/adapters/expo.ts
 var ExpoSQLiteAdapter = class {
@@ -53,6 +53,13 @@ var ExpoSQLiteAdapter = class {
     const result = await this.db.getFirstAsync(sql, params ?? []);
     return result ?? null;
   }
+  async queryBatch(reads) {
+    const results = [];
+    for (const read of reads) {
+      results.push(await this.query(read.sql, read.params));
+    }
+    return results;
+  }
   async run(sql, params) {
     this.ensureOpen();
     const result = await this.db.runAsync(sql, params ?? []);

package/dist/adapters/memory.d.ts

@@ -1,5 +1,5 @@
-import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-t2aqQ__n.js';
-import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from '../types-DMrj3K4o.js';
+import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-imtxkmXZ.js';
+import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from '../types-BTabr_VP.js';
 
 /**
  * @xnetjs/sqlite - In-memory SQLite adapter for testing
@@ -22,6 +22,10 @@ declare class MemorySQLiteAdapter implements SQLiteAdapter {
     isOpen(): boolean;
     query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
     queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
+    queryBatch(reads: Array<{
+        sql: string;
+        params?: SQLValue[];
+    }>): Promise<SQLRow[][]>;
     run(sql: string, params?: SQLValue[]): Promise<RunResult>;
     exec(sql: string): Promise<void>;
     transaction<T>(fn: () => Promise<T>): Promise<T>;

package/dist/adapters/memory.js

@@ -1,7 +1,7 @@
 import {
   SCHEMA_DDL_CORE,
   SCHEMA_VERSION
-} from "../chunk-NVD7G7DZ.js";
+} from "../chunk-W3L4FXU5.js";
 
 // src/adapters/memory.ts
 var MemorySQLiteAdapter = class {
@@ -47,6 +47,13 @@ SQL: ${sql}`);
     const rows = await this.query(sql, params);
     return rows[0] ?? null;
   }
+  async queryBatch(reads) {
+    const results = [];
+    for (const read of reads) {
+      results.push(await this.query(read.sql, read.params));
+    }
+    return results;
+  }
   async run(sql, params) {
     this.ensureOpen();
     try {

package/dist/adapters/reader-thread.d.ts

@@ -0,0 +1,78 @@
+import { S as SQLValue, a as SQLRow } from '../types-BTabr_VP.js';
+import DatabaseType from 'better-sqlite3';
+
+/**
+ * @xnetjs/sqlite - Read-only reader thread for the Electron reader pool
+ *
+ * Runs in a Node `worker_threads` worker spawned by {@link ReaderPool}
+ * (exploration 0230). It opens its **own** `better-sqlite3` connection to the
+ * same database file in **read-only** mode and serves SELECTs against the WAL
+ * snapshot. Because native SQLite + WAL allows one writer concurrent with many
+ * readers — each on its own connection — these threads run genuinely in parallel
+ * on other cores, unlike the browser (where the `opfs-sahpool` VFS holds an
+ * exclusive handle and a second connection is impossible, exploration 0228).
+ *
+ * Each reader uses one-shot autocommit selects (no long-lived read transaction),
+ * so every query observes the latest committed snapshot and nothing holds back
+ * the writer's WAL checkpoint.
+ *
+ * The request handler is exported so it can be unit-tested against an in-process
+ * connection without spawning a worker.
+ */
+
+/** A read request sent from the pool to a reader thread. */
+type ReaderRequest = {
+    id: number;
+    op: 'query';
+    sql: string;
+    params?: SQLValue[];
+} | {
+    id: number;
+    op: 'queryOne';
+    sql: string;
+    params?: SQLValue[];
+} | {
+    id: number;
+    op: 'ping';
+};
+/** A reader thread's response, correlated back to the request by `id`. */
+type ReaderResponse = {
+    id: number;
+    ok: true;
+    rows: SQLRow[];
+} | {
+    id: number;
+    ok: true;
+    row: SQLRow | null;
+} | {
+    id: number;
+    ok: true;
+    pong: true;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+/** Signal the pool the reader booted (or failed to). `id` is always 0. */
+type ReaderReady = {
+    id: 0;
+    ready: true;
+} | {
+    id: 0;
+    ready: false;
+    error: string;
+};
+/**
+ * Execute one reader request against `db`, caching prepared statements per
+ * connection. Pure and synchronous — `better-sqlite3` is synchronous, which is
+ * exactly why a reader thread fully occupies a core for the duration of a query.
+ */
+declare function handleReaderRequest(db: DatabaseType.Database, cache: Map<string, DatabaseType.Statement>, req: ReaderRequest): ReaderResponse;
+/**
+ * Open a read-only connection for a reader thread. Applies connection-local
+ * pragmas only — `journal_mode` is owned by the writer and cannot be set on a
+ * read-only handle, but the reader transparently observes the file's WAL.
+ */
+declare function openReaderConnection(dbPath: string): Promise<DatabaseType.Database>;
+
+export { type ReaderReady, type ReaderRequest, type ReaderResponse, handleReaderRequest, openReaderConnection };

package/dist/adapters/reader-thread.js

@@ -0,0 +1,57 @@
+// src/adapters/reader-thread.ts
+function handleReaderRequest(db, cache, req) {
+  try {
+    if (req.op === "ping") {
+      return { id: req.id, ok: true, pong: true };
+    }
+    let stmt = cache.get(req.sql);
+    if (!stmt) {
+      stmt = db.prepare(req.sql);
+      cache.set(req.sql, stmt);
+    }
+    if (req.op === "query") {
+      const rows = req.params ? stmt.all(...req.params) : stmt.all();
+      return { id: req.id, ok: true, rows };
+    }
+    const row = req.params ? stmt.get(...req.params) : stmt.get();
+    return { id: req.id, ok: true, row: row ?? null };
+  } catch (err) {
+    return { id: req.id, ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+async function openReaderConnection(dbPath) {
+  const { default: Database } = await import("better-sqlite3");
+  const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+  db.pragma("busy_timeout = 5000");
+  db.pragma("cache_size = -32000");
+  db.pragma("temp_store = MEMORY");
+  return db;
+}
+async function bootstrapReaderThread() {
+  const { parentPort, workerData, isMainThread } = await import("worker_threads");
+  if (isMainThread || !parentPort) return;
+  const dbPath = workerData?.dbPath;
+  if (!dbPath) {
+    parentPort.postMessage({ id: 0, ready: false, error: "reader thread: missing dbPath" });
+    return;
+  }
+  try {
+    const db = await openReaderConnection(dbPath);
+    const cache = /* @__PURE__ */ new Map();
+    parentPort.on("message", (req) => {
+      parentPort.postMessage(handleReaderRequest(db, cache, req));
+    });
+    parentPort.postMessage({ id: 0, ready: true });
+  } catch (err) {
+    parentPort.postMessage({
+      id: 0,
+      ready: false,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+void bootstrapReaderThread();
+export {
+  handleReaderRequest,
+  openReaderConnection
+};

package/dist/adapters/web-proxy.d.ts

@@ -1,5 +1,8 @@
-import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-t2aqQ__n.js';
-import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult, k as SQLiteNodeBatchApplyInput, l as SQLiteNodeBatchApplyResult, d as SQLiteOperationStats } from '../types-DMrj3K4o.js';
+import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-imtxkmXZ.js';
+import { b as SQLiteConfig, a as SQLRow, S as SQLValue, c as SQLBatchRead, R as RunResult, l as SQLiteNodeBatchApplyInput, m as SQLiteNodeBatchApplyResult, e as SQLiteOperationStats } from '../types-BTabr_VP.js';
+import { a as SchedulerOpStats } from '../worker-scheduler-D04DqMmR.js';
+
+type TabRole = 'leader' | 'follower';
 
 /**
  * @xnetjs/sqlite - Main thread proxy for SQLite Web Worker
@@ -26,13 +29,50 @@ declare class WebSQLiteProxy implements SQLiteAdapter {
     private _config;
     private inTransaction;
     private operationStats;
+    /** 'single-tab' = the pre-0263 per-tab worker path (or multiTab: false). */
+    private role;
+    private roleHandle;
+    private router;
+    private unsubscribeLeaderServe;
+    private unsubscribeRouterEvents;
+    /** The Comlink port into the LEADER's SQLite worker (follower role only). */
+    private followerPort;
+    private readonly guard;
+    /** Resolvers waiting for the connection to come back after leader loss. */
+    private reconnectWaiters;
+    /** Serializes role transitions (promotion vs. reattach can race). */
+    private transition;
     private createWorkerProxy;
     open(config: SQLiteConfig): Promise<void>;
+    private openSingleTab;
+    private openMultiTab;
+    private becomeLeaderOnRouter;
+    private attachToLeader;
+    /** This tab won the leadership lock after the previous leader went away. */
+    private promoteToLeader;
+    /** Another tab became leader; drop the dead port and fetch a fresh one. */
+    private reattachFollower;
+    private enqueueTransition;
+    private notifyReconnected;
+    private whenReconnected;
+    private teardownMultiTab;
+    /**
+     * Run a worker RPC with follower protections: leader loss REJECTS in-flight
+     * calls immediately instead of hanging, and `retryable` (idempotent read)
+     * calls transparently re-issue once the connection is re-established —
+     * against this tab's own worker if it was promoted, or the new leader's.
+     */
+    private rpc;
     resetStorage(config: SQLiteConfig): Promise<void>;
     close(): Promise<void>;
     isOpen(): boolean;
     query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
     queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
+    /**
+     * Execute several reads in ONE worker round-trip. N queries previously cost
+     * N postMessage round-trips; a batch costs one (exploration 0263).
+     */
+    queryBatch(reads: SQLBatchRead[]): Promise<SQLRow[][]>;
     run(sql: string, params?: SQLValue[]): Promise<RunResult>;
     exec(sql: string): Promise<void>;
     transaction<T>(_fn: () => Promise<T>): Promise<T>;
@@ -62,8 +102,11 @@ declare class WebSQLiteProxy implements SQLiteAdapter {
     applySchema(version: number, sql: string): Promise<boolean>;
     getDatabaseSize(): Promise<number>;
     vacuum(): Promise<void>;
+    incrementalVacuum(maxPages?: number): Promise<number>;
     checkpoint(): Promise<number>;
     getStorageMode(): Promise<'opfs' | 'memory'>;
+    /** This tab's multi-tab role: 'leader', 'follower', or 'single-tab'. */
+    getTabRole(): TabRole | 'single-tab';
     /**
      * Create a MessagePort connected directly to the SQLite worker.
      *
@@ -72,6 +115,15 @@ declare class WebSQLiteProxy implements SQLiteAdapter {
      * (e.g. the data worker) so its storage calls skip the main thread.
      */
     createMessagePort(): Promise<MessagePort>;
+    /**
+     * Worker-side scheduler stats: per-lane p50/p95 queue+exec latency and
+     * coalesce hits (exploration 0263). Complements getOperationStats(), which
+     * counts main-thread RPCs — together they give "how many round-trips" and
+     * "how long each op spent in the worker".
+     */
+    getSchedulerOpStats(): Promise<SchedulerOpStats>;
+    /** Zero the worker-side scheduler stats for a focused measurement. */
+    resetSchedulerOpStats(): Promise<void>;
     getOperationStats(): SQLiteOperationStats;
     resetOperationStats(): void;
 }