@xnetjs/sqlite 0.0.2 → 0.1.0

package/dist/adapters/web.d.ts

@@ -1,5 +1,5 @@
-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 { 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 } from '../types-BTabr_VP.js';
 
 /**
  * @xnetjs/sqlite - Web SQLite adapter using @sqlite.org/sqlite-wasm
@@ -8,6 +8,37 @@ import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from '.
  * Must run in a Web Worker for OPFS access.
  */
 
+/**
+ * Per-phase timing of {@link WebSQLiteAdapter.open}. Every prior cold-open
+ * exploration (0204→0249) timed the layer the stall was *in*, so the cost kept
+ * hopping to the next un-timed layer; by the 0253 capture both `queueMs` and
+ * `execMs` read 0 and the ~17 s lived entirely in this `open()` window, which no
+ * timer bracketed. These fields split it so the dominant sub-phase is named in
+ * one boot-log line. All durations are milliseconds, rounded.
+ */
+interface OpenPhaseTimings {
+    /** Dynamic `import('@sqlite.org/sqlite-wasm')` (bundle parse/download). */
+    wasmImportMs: number;
+    /** `sqlite3InitModule()` — WASM instantiate. */
+    wasmInitMs: number;
+    /** `installOpfsSAHPoolVfs()` — acquires the pool's sync access handles; INCLUDES any lock-retry backoff. */
+    vfsInstallMs: number;
+    /** `reserveMinimumCapacity()` — may acquire more handles / grow the pool. */
+    reserveCapacityMs: number;
+    /** `new OpfsSAHPoolDb()` — open the database file in the pool. */
+    dbOpenMs: number;
+    /** All post-open `PRAGMA` settings (page_size/cache/mmap/journal/…). */
+    pragmasMs: number;
+    /** Whole `open()` span (import → last pragma). */
+    totalOpenMs: number;
+}
+/**
+ * Remove xNet's OPFS-backed SQLite storage for the supplied database path.
+ *
+ * This must run in a worker because the SAH-pool VFS uses synchronous OPFS
+ * handles. It is intentionally scoped to xNet's SQLite VFS directory.
+ */
+declare function resetWebSQLiteOpfsStorage(config: SQLiteConfig): Promise<void>;
 /**
  * SQLite adapter for web browsers using @sqlite.org/sqlite-wasm.
  *
@@ -33,17 +64,58 @@ declare class WebSQLiteAdapter implements SQLiteAdapter {
     private poolUtil;
     private _config;
     private inTransaction;
+    /**
+     * Monotonic time of the open transaction's last operation. Lets the worker
+     * host distinguish a LIVE manual transaction from one abandoned by a client
+     * that died between BEGIN and COMMIT (PowerSync-style lease recovery, 0263).
+     */
+    private lastTransactionActivityAt;
     private storageMode;
+    /**
+     * Per-phase timing of the last {@link open} call, or null until it runs.
+     * Read by the worker host to emit `[xNet] sqlite open phases` (exploration
+     * 0253). Diagnostic only — never affects behaviour.
+     */
+    private openPhaseTimings;
+    /** ms spent in `applySchema()` during {@link createWebSQLiteAdapter}, for the open-phases line. */
+    schemaApplyMs: number;
+    /** How many times the OPFS lock-retry backoff fired during the last {@link open} (0 = first try). */
+    openRetryAttempts: number;
+    /**
+     * Prepared-statement LRU for the hot query/run path (exploration 0263).
+     * `db.exec()` re-parses the SQL on every call; the hot path repeats a small
+     * statement set, so cached `oo1.Stmt` handles skip the parse+prepare cost.
+     * Cleared (finalizing all handles) on {@link exec} — the DDL/script path —
+     * and on {@link close}.
+     */
+    private stmts;
+    /** Per-phase timing of the last {@link open}, or null if it hasn't run. */
+    getOpenPhaseTimings(): OpenPhaseTimings | null;
     open(config: SQLiteConfig): Promise<void>;
     close(): Promise<void>;
     isOpen(): boolean;
     getStorageMode(): 'opfs' | 'memory';
+    /** True while a manual BEGIN…COMMIT/ROLLBACK transaction is open. */
+    isInTransaction(): boolean;
+    /** ms since the open transaction last executed an operation (0 when none). */
+    transactionIdleMs(): number;
+    /** Stamp transaction liveness — called by ops that run inside one. */
+    private touchTransaction;
+    /**
+     * Fetch (or prepare and cache) the statement for `sql`, or null when the SQL
+     * must bypass the cache: `db.prepare()` compiles only the FIRST statement of
+     * a multi-statement string, whereas `db.exec()` runs them all — serving such
+     * SQL from the cache would silently drop statements.
+     */
+    private getCachedStmt;
     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: SQLBatchRead[]): Promise<SQLRow[][]>;
     run(sql: string, params?: SQLValue[]): Promise<RunResult>;
     exec(sql: string): Promise<void>;
     private execSync;
     transaction<T>(fn: () => Promise<T>): Promise<T>;
+    applyNodeBatch(input: SQLiteNodeBatchApplyInput): Promise<SQLiteNodeBatchApplyResult>;
     beginTransaction(): Promise<void>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
@@ -53,12 +125,27 @@ declare class WebSQLiteAdapter implements SQLiteAdapter {
     applySchema(version: number, sql: string): Promise<boolean>;
     getDatabaseSize(): Promise<number>;
     vacuum(): Promise<void>;
+    incrementalVacuum(maxPages?: number): Promise<number>;
     checkpoint(): Promise<number>;
     private ensureOpen;
 }
+/**
+ * Step `PRAGMA incremental_vacuum` to completion (or `maxPages`), returning
+ * the number of pages freed. SQLite frees ONE page per `sqlite3_step` of this
+ * pragma; the oo1 `exec` path steps a statement only once when it collects no
+ * rows, so `exec('PRAGMA incremental_vacuum')` silently freed a single page
+ * per call — the compaction reclaim was a near-no-op (caught by the local
+ * bloat-seed validation, 2026-07-05). Exported for the engine-level test.
+ */
+declare function stepIncrementalVacuumToCompletion(db: {
+    prepare(sql: string): {
+        step(): boolean;
+        finalize(): unknown;
+    };
+}, maxPages?: number): number;
 /**
  * Create a WebSQLiteAdapter with schema applied.
  */
 declare function createWebSQLiteAdapter(config: SQLiteConfig): Promise<WebSQLiteAdapter>;
 
-export { WebSQLiteAdapter, createWebSQLiteAdapter };
+export { type OpenPhaseTimings, WebSQLiteAdapter, createWebSQLiteAdapter, resetWebSQLiteOpfsStorage, stepIncrementalVacuumToCompletion };

package/dist/adapters/web.js

@@ -1,9 +1,15 @@
 import {
   WebSQLiteAdapter,
-  createWebSQLiteAdapter
-} from "../chunk-BXYZU3OL.js";
-import "../chunk-HIREU5S5.js";
+  createWebSQLiteAdapter,
+  resetWebSQLiteOpfsStorage,
+  stepIncrementalVacuumToCompletion
+} from "../chunk-BBZDKLA3.js";
+import "../chunk-SV475UL5.js";
+import "../chunk-CBU263LI.js";
+import "../chunk-W3L4FXU5.js";
 export {
   WebSQLiteAdapter,
-  createWebSQLiteAdapter
+  createWebSQLiteAdapter,
+  resetWebSQLiteOpfsStorage,
+  stepIncrementalVacuumToCompletion
 };

package/dist/browser-support.d.ts

@@ -16,6 +16,30 @@ interface BrowserSupport {
     /** Warning message for soft failures (app can still work with fallback) */
     warning?: string;
 }
+interface PersistentStorageStatus {
+    /** Browser exposes persistence APIs. */
+    supported: boolean;
+    /** Whether the site is currently persisted. */
+    persisted: boolean | null;
+    /** Whether the explicit persistence request was granted. */
+    granted: boolean | null;
+    /** Whether this status was produced by an explicit persistence request. */
+    requested: boolean;
+    /** Whether the app can present a user action to request persistence. */
+    requestable: boolean;
+    /** Durable-storage state for UI and diagnostics. */
+    state: 'granted' | 'not-granted' | 'unsupported' | 'error';
+    /** User-facing explanation of the result. */
+    message: string;
+    /** Optional usage estimate in bytes. */
+    usageBytes?: number;
+    /** Optional quota estimate in bytes. */
+    quotaBytes?: number;
+}
+interface PersistentStorageRequestOptions {
+    /** Request persistent mode instead of only checking current state. */
+    request?: boolean;
+}
 /**
  * Check if the current browser supports SQLite-WASM with OPFS.
  *
@@ -46,6 +70,37 @@ interface BrowserSupport {
  * ```
  */
 declare function checkBrowserSupport(): Promise<BrowserSupport>;
+/**
+ * Check whether persistent storage is already enabled without prompting or
+ * spending a browser heuristic-based permission request during startup.
+ */
+declare function checkPersistentStorage(): Promise<PersistentStorageStatus>;
+/**
+ * Whether `navigator.storage.persist()` can be called without showing the
+ * user a permission prompt.
+ *
+ * Chromium and WebKit decide the request silently from heuristics (install,
+ * notification permission, engagement) and re-evaluate it fresh on every
+ * call, so requesting at startup is free. Gecko (desktop Firefox) shows a
+ * modal doorhanger, so requests there must stay behind a user gesture.
+ * Firefox on iOS (FxiOS) runs WebKit, but we treat anything Firefox-branded
+ * as prompt-capable — the worst case is skipping a free request.
+ */
+declare function isSilentPersistRequestSafe(): boolean;
+/**
+ * Watch the `persistent-storage` permission for changes (e.g. a grant that
+ * lands mid-session after the user enables notifications or installs the
+ * app). Querying is free — it never spends or triggers a request.
+ *
+ * Calls `onChange` with the new state whenever the browser reports a
+ * change. No-op on browsers without the Permissions API or the
+ * `persistent-storage` permission name. Returns an unsubscribe function.
+ */
+declare function watchPersistentStoragePermission(onChange: (state: PermissionState) => void): () => void;
+/**
+ * Request persistent storage where supported and summarize the result.
+ */
+declare function requestPersistentStorage(options?: PersistentStorageRequestOptions): Promise<PersistentStorageStatus>;
 /**
  * Show an unsupported browser message to the user.
  *
@@ -63,5 +118,14 @@ declare function checkBrowserSupport(): Promise<BrowserSupport>;
  * ```
  */
 declare function showUnsupportedBrowserMessage(reason: string): void;
+/**
+ * Record that this session opened on the non-durable `:memory:` fallback
+ * (another tab/worker held the OPFS handles, or OPFS is unavailable).
+ * Multi-tab leadership routing (0263) should drive this count to ~zero —
+ * the counter is how we verify that in the field. Returns the new total.
+ */
+declare function recordMemoryFallbackSession(): number;
+/** Total sessions on this device that fell back to `:memory:` storage. */
+declare function getMemoryFallbackSessionCount(): number;
 
-export { type BrowserSupport, checkBrowserSupport, showUnsupportedBrowserMessage };
+export { type BrowserSupport, type PersistentStorageRequestOptions, type PersistentStorageStatus, checkBrowserSupport, checkPersistentStorage, getMemoryFallbackSessionCount, isSilentPersistRequestSafe, recordMemoryFallbackSession, requestPersistentStorage, showUnsupportedBrowserMessage, watchPersistentStoragePermission };

package/dist/browser-support.js

@@ -1,8 +1,20 @@
 import {
   checkBrowserSupport,
-  showUnsupportedBrowserMessage
-} from "./chunk-ZRR5D2OD.js";
+  checkPersistentStorage,
+  getMemoryFallbackSessionCount,
+  isSilentPersistRequestSafe,
+  recordMemoryFallbackSession,
+  requestPersistentStorage,
+  showUnsupportedBrowserMessage,
+  watchPersistentStoragePermission
+} from "./chunk-S6MT6KCI.js";
 export {
   checkBrowserSupport,
-  showUnsupportedBrowserMessage
+  checkPersistentStorage,
+  getMemoryFallbackSessionCount,
+  isSilentPersistRequestSafe,
+  recordMemoryFallbackSession,
+  requestPersistentStorage,
+  showUnsupportedBrowserMessage,
+  watchPersistentStoragePermission
 };

package/dist/chunk-5HC5V73T.js

@@ -0,0 +1,191 @@
+// src/adapters/worker-scheduler.ts
+var LANE_ORDER = ["interactive", "bulk", "write"];
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function firstOpGapFields(report, openedAtMs) {
+  return {
+    firstOpAfterOpen: true,
+    idleBeforeFirstOpMs: Math.round(report.enqueuedAt - openedAtMs),
+    sinceOpenMs: Math.round(report.startedAt - openedAtMs)
+  };
+}
+function percentileMs(samples, p) {
+  if (samples.length === 0) return 0;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const rank = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p / 100 * sorted.length) - 1));
+  return Math.round(sorted[rank]);
+}
+var SCHEDULER_STATS_SAMPLE_CAP = 512;
+var LaneStatsAccumulator = class {
+  ops = 0;
+  maxExecMs = 0;
+  queueSamples = [];
+  execSamples = [];
+  cursor = 0;
+  record(queueMs, execMs) {
+    this.ops += 1;
+    if (execMs > this.maxExecMs) this.maxExecMs = execMs;
+    if (this.queueSamples.length < SCHEDULER_STATS_SAMPLE_CAP) {
+      this.queueSamples.push(queueMs);
+      this.execSamples.push(execMs);
+    } else {
+      this.queueSamples[this.cursor] = queueMs;
+      this.execSamples[this.cursor] = execMs;
+      this.cursor = (this.cursor + 1) % SCHEDULER_STATS_SAMPLE_CAP;
+    }
+  }
+  stats() {
+    return {
+      ops: this.ops,
+      queueP50Ms: percentileMs(this.queueSamples, 50),
+      queueP95Ms: percentileMs(this.queueSamples, 95),
+      execP50Ms: percentileMs(this.execSamples, 50),
+      execP95Ms: percentileMs(this.execSamples, 95),
+      maxExecMs: Math.round(this.maxExecMs)
+    };
+  }
+  reset() {
+    this.ops = 0;
+    this.maxExecMs = 0;
+    this.queueSamples.length = 0;
+    this.execSamples.length = 0;
+    this.cursor = 0;
+  }
+};
+var WorkerScheduler = class {
+  /**
+   * @param onOp optional per-operation timing reporter (boot diagnostics, 0229).
+   */
+  constructor(onOp) {
+    this.onOp = onOp;
+  }
+  queues = {
+    interactive: [],
+    bulk: [],
+    write: []
+  };
+  /** In-flight + queued reads keyed by `coalesceKey`, to collapse duplicates. */
+  coalesced = /* @__PURE__ */ new Map();
+  running = false;
+  /** Aggregated op timing per lane (exploration 0263). */
+  laneStats = {
+    interactive: new LaneStatsAccumulator(),
+    bulk: new LaneStatsAccumulator(),
+    write: new LaneStatsAccumulator()
+  };
+  coalescedHits = 0;
+  /**
+   * Enqueue `fn` on `lane`. Returns a promise that settles with `fn`'s result.
+   *
+   * When `coalesceKey` is provided (reads only — they're idempotent), an
+   * identical key that is already queued or in flight returns the SAME promise
+   * instead of enqueuing a second execution. The key is dropped once that
+   * execution settles, so a later identical read re-runs against fresh data.
+   */
+  schedule(lane, fn, coalesceKey, label, detail) {
+    if (coalesceKey !== void 0) {
+      const inflight = this.coalesced.get(coalesceKey);
+      if (inflight) {
+        this.coalescedHits += 1;
+        return inflight;
+      }
+    }
+    const promise = new Promise((resolve, reject) => {
+      this.queues[lane].push({
+        run: fn,
+        resolve,
+        reject,
+        lane,
+        label,
+        detail,
+        enqueuedAt: nowMs()
+      });
+    });
+    if (coalesceKey !== void 0) {
+      this.coalesced.set(coalesceKey, promise);
+      const clear = () => {
+        if (this.coalesced.get(coalesceKey) === promise) this.coalesced.delete(coalesceKey);
+      };
+      promise.then(clear, clear);
+    }
+    void this.pump();
+    return promise;
+  }
+  /** Current queue depths and in-flight flag. */
+  snapshot() {
+    return {
+      interactive: this.queues.interactive.length,
+      bulk: this.queues.bulk.length,
+      write: this.queues.write.length,
+      inFlight: this.running
+    };
+  }
+  /** Cumulative op counts, coalesce hits, and per-lane latency percentiles. */
+  opStats() {
+    const lanes = {
+      interactive: this.laneStats.interactive.stats(),
+      bulk: this.laneStats.bulk.stats(),
+      write: this.laneStats.write.stats()
+    };
+    return {
+      ops: lanes.interactive.ops + lanes.bulk.ops + lanes.write.ops,
+      coalescedHits: this.coalescedHits,
+      lanes
+    };
+  }
+  /** Zero the op-stats counters for a focused before/after measurement. */
+  resetOpStats() {
+    this.coalescedHits = 0;
+    for (const lane of LANE_ORDER) {
+      this.laneStats[lane].reset();
+    }
+  }
+  /** Pull the next job, highest-priority non-empty lane first (FIFO within a lane). */
+  next() {
+    for (const lane of LANE_ORDER) {
+      const job = this.queues[lane].shift();
+      if (job) return job;
+    }
+    return void 0;
+  }
+  /** Drain the queues one job at a time. Re-entrant-safe via the `running` latch. */
+  async pump() {
+    if (this.running) return;
+    this.running = true;
+    try {
+      let job;
+      while (job = this.next()) {
+        const startedAt = nowMs();
+        try {
+          job.resolve(await job.run());
+        } catch (err) {
+          job.reject(err);
+        } finally {
+          const endedAt = nowMs();
+          const queueMs = startedAt - job.enqueuedAt;
+          const execMs = endedAt - startedAt;
+          this.laneStats[job.lane].record(queueMs, execMs);
+          if (this.onOp) {
+            this.onOp({
+              lane: job.lane,
+              label: job.label,
+              detail: job.detail,
+              queueMs,
+              execMs,
+              enqueuedAt: job.enqueuedAt,
+              startedAt
+            });
+          }
+        }
+      }
+    } finally {
+      this.running = false;
+    }
+  }
+};
+
+export {
+  firstOpGapFields,
+  WorkerScheduler
+};