@xnetjs/sqlite 0.0.2 → 0.1.0

package/dist/{adapter-I7yAV6iu.d.ts → adapter-imtxkmXZ.d.ts}

@@ -1,4 +1,4 @@
-import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from './types-C_aHfRDF.js';
+import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult, c as SQLBatchRead, l as SQLiteNodeBatchApplyInput, m as SQLiteNodeBatchApplyResult, e as SQLiteOperationStats } from './types-BTabr_VP.js';
 
 /**
  * @xnetjs/sqlite - SQLite adapter interface definitions
@@ -67,6 +67,14 @@ interface SQLiteAdapter {
      * @param sql - SQL statements (may be multiple, separated by semicolons)
      */
     exec(sql: string): Promise<void>;
+    /**
+     * Execute several reads in one call, returning one row array per read
+     * (positionally). For worker/port-backed adapters this crosses the RPC
+     * boundary ONCE for the whole batch instead of once per query — the
+     * amortization matters for multi-query screens and chunked hydrates
+     * (exploration 0263). In-process adapters may simply loop.
+     */
+    queryBatch?(reads: SQLBatchRead[]): Promise<SQLRow[][]>;
     /**
      * Execute a function within a transaction.
      * Automatically commits on success, rolls back on error.
@@ -81,6 +89,24 @@ interface SQLiteAdapter {
      * })
      */
     transaction<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute a list of SQL statements inside one transaction.
+     *
+     * This is primarily for proxy/worker-backed adapters where a callback
+     * transaction would cross a serialization boundary. Implementations should
+     * execute all operations atomically and roll back on the first failure.
+     */
+    transactionBatch?(operations: Array<{
+        sql: string;
+        params?: SQLValue[];
+    }>): Promise<void>;
+    /**
+     * Execute a node-store batch using compact typed row payloads.
+     *
+     * Worker-backed adapters can use this to avoid transferring a very large
+     * array of repeated SQL strings over Comlink.
+     */
+    applyNodeBatch?(input: SQLiteNodeBatchApplyInput): Promise<SQLiteNodeBatchApplyResult>;
     /**
      * Begin a manual transaction.
      * Must be followed by commit() or rollback().
@@ -129,6 +155,19 @@ interface SQLiteAdapter {
      * Vacuum the database to reclaim space.
      */
     vacuum(): Promise<void>;
+    /**
+     * Return freelist pages to the filesystem under `auto_vacuum=INCREMENTAL`,
+     * optionally capped at `maxPages`. Returns the number of pages freed.
+     *
+     * This exists because `exec('PRAGMA incremental_vacuum')` is a silent
+     * near-no-op on the WASM build: SQLite frees ONE page per `sqlite3_step` of
+     * that pragma, and the oo1 `exec` path steps a statement only once when no
+     * rows are collected — so the freelist shrank by a single page per call.
+     * Implementations must step the pragma to completion. Optional: adapters
+     * for engines that step pragmas fully anyway (or that never run under
+     * incremental auto-vacuum) may omit it; callers fall back to `exec`.
+     */
+    incrementalVacuum?(maxPages?: number): Promise<number>;
     /**
      * Checkpoint WAL file (for WAL mode databases).
      * Returns the number of frames checkpointed.
@@ -140,6 +179,14 @@ interface SQLiteAdapter {
      * or 'memory' if using in-memory fallback.
      */
     getStorageMode(): Promise<'opfs' | 'memory'> | 'opfs' | 'memory';
+    /**
+     * Optional cumulative operation counters for import diagnostics.
+     */
+    getOperationStats?(): Promise<SQLiteOperationStats> | SQLiteOperationStats;
+    /**
+     * Reset cumulative operation counters when starting a focused measurement.
+     */
+    resetOperationStats?(): Promise<void> | void;
 }
 /**
  * Prepared statement for repeated execution.

package/dist/adapters/electron.d.ts

@@ -1,7 +1,7 @@
-import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-I7yAV6iu.js';
-import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from '../types-C_aHfRDF.js';
-import Database from 'better-sqlite3';
-export { a as SCHEMA_DDL, S as SCHEMA_VERSION } from '../schema-CjkXTqxn.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, l as SQLiteNodeBatchApplyInput, m as SQLiteNodeBatchApplyResult, E as ElectronSQLiteDiagnostics } from '../types-BTabr_VP.js';
+import DatabaseType from 'better-sqlite3';
+export { a as SCHEMA_DDL, S as SCHEMA_VERSION } from '../schema-C4gufY3B.js';
 
 /**
  * @xnetjs/sqlite - Electron SQLite adapter using better-sqlite3
@@ -26,17 +26,34 @@ export { a as SCHEMA_DDL, S as SCHEMA_VERSION } from '../schema-CjkXTqxn.js';
  */
 declare class ElectronSQLiteAdapter implements SQLiteAdapter {
     private db;
+    /** Optional read-only secondary connection (exploration 0230, Phase 0.5). */
+    private readDb;
     private config;
     private inTransaction;
     private statementCache;
+    private readStatementCache;
+    /** Priority scheduler fronting the writer connection (exploration 0230). */
+    private scheduler;
+    /** Read-only reader-thread pool for heavy parallel reads (Phase 1). */
+    private readerPool;
+    /** Monotonic clock of the most recent commit, for read-your-writes routing. */
+    private lastCommitAt;
     open(config: SQLiteConfig): Promise<void>;
     close(): Promise<void>;
     isOpen(): boolean;
     query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
+    queryBatch(reads: Array<{
+        sql: string;
+        params?: SQLValue[];
+    }>): Promise<SQLRow[][]>;
     queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
     run(sql: string, params?: SQLValue[]): Promise<RunResult>;
     exec(sql: string): Promise<void>;
     transaction<T>(fn: () => Promise<T>): Promise<T>;
+    transactionBatch(operations: Array<{
+        sql: string;
+        params?: SQLValue[];
+    }>): Promise<void>;
     /**
      * Synchronous transaction for performance-critical batch operations.
      * Prefer this over async transaction when the body is synchronous.
@@ -51,20 +68,67 @@ declare class ElectronSQLiteAdapter implements SQLiteAdapter {
     applySchema(version: number, sql: string): Promise<boolean>;
     getDatabaseSize(): Promise<number>;
     vacuum(): Promise<void>;
+    incrementalVacuum(maxPages?: number): Promise<number>;
     checkpoint(): Promise<number>;
     getStorageMode(): 'opfs' | 'memory';
     /**
-     * Get a statement from cache or prepare it.
+     * Apply a node-store batch with cooperative yielding (exploration 0230).
+     *
+     * A bulk import is the one synchronous op long enough to head-of-line block
+     * interactive reads on the data-process thread. This splits the batch into
+     * chunks, each its own exclusive transaction, and yields to the event loop
+     * between chunks so a queued interactive read (or a reader-pool read) can
+     * interleave. Whole-batch atomicity is traded for yield points — safe here
+     * because node-batch writes are idempotent LWW upserts.
+     */
+    applyNodeBatch(input: SQLiteNodeBatchApplyInput): Promise<SQLiteNodeBatchApplyResult>;
+    /** Scheduler queue depths (diagnostics / desktop perf panel). */
+    getSchedulerSnapshot(): ElectronSQLiteDiagnostics['scheduler'];
+    /** Reader-thread pool occupancy, or null when no pool is configured. */
+    getReaderPoolStats(): ElectronSQLiteDiagnostics['readerPool'];
+    /**
+     * WAL growth: `-wal` sidecar size + page count. Long-lived readers can pin an
+     * old snapshot and hold back checkpointing; our one-shot reader selects don't,
+     * so this should stay bounded. Surfaced to the diagnostics seam (0230).
+     */
+    getWalStats(): Promise<ElectronSQLiteDiagnostics['wal']>;
+    /** Run a passive WAL checkpoint; returns frames checkpointed (best-effort). */
+    checkpointWal(): Promise<number>;
+    private runCheckpoint;
+    /** Combined point-in-time diagnostics for the desktop diagnostics seam. */
+    getDiagnostics(): Promise<ElectronSQLiteDiagnostics>;
+    /** Whether a heavy, non-transactional read should be offloaded to the pool. */
+    private shouldUsePool;
+    /** Reads within the configured window after a commit route to the writer. */
+    private inReadYourWritesWindow;
+    /** Pick the connection (+ its statement cache) a plain read should use. */
+    private readConnection;
+    /**
+     * Run `apply` as a single atomic chunk transaction. Scheduled as one write-lane
+     * job so it is indivisible w.r.t. the scheduler — no queued read or write can
+     * interleave mid-chunk — while the surrounding `applyNodeBatch` yields *between*
+     * chunks. `apply` is fully synchronous (no awaits), so `inTransaction` is set
+     * only for its duration and is invisible to other async callers.
+     */
+    private runChunkTransaction;
+    private queryRaw;
+    private queryOneRaw;
+    private runRaw;
+    private execRaw;
+    /**
+     * Get a statement from cache or prepare it on the writer connection.
      * Statement caching significantly improves performance for repeated queries.
      */
     private getOrPrepare;
+    /** Statement cache keyed per connection (writer + read-only differ). */
+    private getOrPrepareOn;
     private ensureOpen;
     private wrapError;
     /**
      * Get the underlying better-sqlite3 database instance.
      * Use for advanced operations not covered by the interface.
      */
-    getRawDatabase(): Database.Database;
+    getRawDatabase(): DatabaseType.Database;
     /**
      * Create a batch writer for efficient bulk inserts.
      */