Implement the 9.1 roadmap: sync-path UDFs, JS virtual tables, changeset rebasing, ergonomics parity, tag store, compat shim and query spans

binding.gyp

@@ -68,7 +68,8 @@
         "src/function.cc",
         "src/node_sqlite3.cc",
         "src/session.cc",
-        "src/statement.cc"
+        "src/statement.cc",
+        "src/vtab.cc"
       ],
       "defines": [ "NAPI_VERSION=<(napi_build_version)", "NAPI_DISABLE_CPP_EXCEPTIONS=1" ]
     }

contrib/check-jsdoc.js

@@ -86,10 +86,12 @@ function signatureFrom(lines, i) {
 // Count top-level commas in a balanced parameter list (angles included so
 // generic parameter defaults with `<K = string>` do not confuse depth).
 function countParams(list) {
+    // A trailing comma is formatting, not a parameter.
+    const trimmed = list.replace(/,\s*$/, '');
     let depth = 0;
     let count = 0;
     let seen = false;
-    for (const c of list) {
+    for (const c of trimmed) {
         if (c === '(' || c === '<' || c === '[' || c === '{') depth++;
         else if (c === ')' || c === '>' || c === ']' || c === '}') {
             depth--;

deps/sqlite3.gyp

@@ -90,6 +90,9 @@
           # ~30 KB of extra amalgamation code is accepted in exchange for
           # column metadata (stmt.columns) and db.tableInfo().
           'SQLITE_ENABLE_COLUMN_METADATA',
+          # Phase 6 (observability): sqlite3_normalized_sql compiles only
+          # with this define.
+          'SQLITE_ENABLE_NORMALIZE',
           'SQLITE_DEFAULT_MEMSTATUS=0'
         ],
       },
@@ -113,6 +116,8 @@
         'SQLITE_ENABLE_STAT4',
         # See the direct_dependent_settings copy above (Deliverable 07).
         'SQLITE_ENABLE_COLUMN_METADATA',
+        # See the direct_dependent_settings copy above (Phase 6).
+        'SQLITE_ENABLE_NORMALIZE',
         'SQLITE_DEFAULT_MEMSTATUS=0'
       ],
       'conditions': [

docs/install.md

@@ -7,9 +7,18 @@ This is the complete installation guide. Requirements: **Node.js >= 24**
 npm install @appthreat/sqlite3
 pnpm add @appthreat/sqlite3
 yarn add @appthreat/sqlite3
-bun add @appthreat/sqlite3
 ```
 
+### Bun: install works, runtime does not (yet)
+
+The package installs under Bun and the binding loads — but Bun 1.4's
+N-API implementation cannot run this addon's row delivery: synchronous
+reads and async completions fail with `Invalid argument` where every
+supported Node works. This is **not specific to recent versions** —
+v9.0.2 fails identically — and it is tracked as a Bun N-API gap, not a
+package bug. On the Bun runtime, use Bun's own built-in `bun:sqlite`;
+this package is for Node (>= 24) and Electron (>= 35).
+
 Nothing is downloaded at install time and nothing is compiled at install time
 on the platforms below — the prebuilt binaries ship inside the npm tarball
 itself.

docs/performance.md

@@ -380,20 +380,26 @@ The same arithmetic applies to aggregates (`step` is one round trip per
 row) and collations (O(n log n) round trips for a sort — sorting in JS
 after `all()` is faster for anything but small or one-off sorts).
 
-### Future direction: UDFs on the synchronous fast path
-
-The refusal of JS functions on the sync methods is policy, not the
-structural limit above. On `getSync`/`runSync`/`allSync` the JS thread
-is already the one executing SQL, so a callback could be invoked
-re-entrantly — a direct call with no cross-thread round trip, the way
-`node:sqlite` runs UDFs inline — and unlike collations, a function has
-an error channel (`sqlite3_result_error`), so failures are reportable
-mid-query. The current build refuses instead with an explicit error
-(`src/function.cc`, `SyncRefusalMessage`). Landing inline sync-path
-invocation would make the natural `... AND vers_compare(?, vers)`
-shape genuinely fast, closing the gap the README's comparison table
-attributes to `node:sqlite`. Deliberate follow-up work, out of scope
-for this release.
+### UDFs on the synchronous fast path (shipped in 9.1)
+
+The former refusal of JS functions on the sync methods was policy, not a
+structural limit, and 9.1 removed it: on `getSync`/`runSync`/`allSync`
+the JS thread is already the one executing SQL, so the callback is
+invoked re-entrantly — a direct call with no cross-thread round trip,
+the way `node:sqlite` runs UDFs inline — and unlike collations, a
+function has an error channel (`sqlite3_result_error`), so failures are
+reported mid-query with the thrown value attached as `cause`. The
+natural `... AND vers_compare(?, vers)` shape is now a plain function
+call per row on the sync path.
+
+Two guardrails came with it: a UDF cannot drive *its own* statement
+re-entrantly (the one hard rule SQLite has; other statements on the
+connection work, the connection mutex being recursive), and functions
+cannot be registered or removed from inside a sync-invoked callback
+(the registration handlers dispatch inline, and swapping an
+implementation sqlite is mid-stepping on is not a supported sqlite
+operation). JS collations and the JS progress callback still refuse on
+the sync path, as before: they have no error channel.
 
 ## Where this package loses
 

examples/kysely-dialect.mjs

@@ -0,0 +1,95 @@
+// A zero-dependency Kysely dialect for @appthreat/sqlite3 (Phase 6).
+// Kysely's SqliteDialect is written against better-sqlite3's sync
+// surface; this adapter maps the same contract onto this package's
+// async-first connection — prepared statements carry the `readonly`
+// flag Kysely's driver checks, and iterate() provides the streaming
+// reads its SELECTs want.
+//
+// Requires kysely as a peer: `npm install kysely`.
+
+import {
+    Kysely,
+    SqliteAdapter,
+    SqliteIntrospector,
+    SqliteQueryCompiler,
+} from 'kysely';
+
+/**
+ * Builds a Kysely instance over one @appthreat/sqlite3 connection.
+ *
+ * @param {import('@appthreat/sqlite3').Database} db the connection.
+ * @param {{ onCreateConnection?: (db: unknown) => Promise<void> | void }} [hooks]
+ *   `onCreateConnection` runs once per connection (where pragmas go).
+ */
+export function kyselyFor(db, hooks = {}) {
+    const dialect = {
+        createAdapter: () => new SqliteAdapter(),
+        createQueryCompiler: () => new SqliteQueryCompiler(),
+        createIntrospector: (database) =>
+            new SqliteIntrospector(database, dialect),
+        createDriver: () => ({
+            async init() {
+                if (hooks.onCreateConnection) {
+                    await hooks.onCreateConnection(db);
+                }
+                // Kysely prepares one statement per compiled query; the
+                // cache keeps re-issued queries (its identity columns
+                // lookups, its selects) off the prepare path.
+                db.cacheStatements();
+            },
+            async acquireConnection() {
+                return {
+                    async executeQuery(compiledQuery) {
+                        const { sql, parameters } = compiledQuery;
+                        const stmt = await db.prepare(sql);
+                        try {
+                            if (stmt.readonly) {
+                                return { rows: await stmt.all(parameters) };
+                            }
+                            const run = await stmt.run(parameters);
+                            return {
+                                rows: [],
+                                insertId:
+                                    run.lastID !== undefined &&
+                                    run.lastID !== null
+                                        ? run.lastID
+                                        : undefined,
+                                numUpdatedOrDeletedRows:
+                                    run.changes !== undefined &&
+                                    run.changes !== null
+                                        ? BigInt(run.changes)
+                                        : undefined,
+                            };
+                        } finally {
+                            await stmt.finalize();
+                        }
+                    },
+                };
+            },
+            async releaseConnection() {
+                /* one long-lived connection */
+            },
+            async beginTransaction() {
+                await db.exec('BEGIN');
+            },
+            async commitTransaction() {
+                await db.exec('COMMIT');
+            },
+            async rollbackTransaction() {
+                await db.exec('ROLLBACK');
+            },
+            async destroy() {
+                // The caller owns the connection (it passed it in);
+                // close it yourself after kysely.destroy().
+            },
+        }),
+    };
+    return new Kysely({ dialect });
+}
+
+// Usage:
+//   const db = await sqlite3.open('app.db');
+//   const kysely = kyselyFor(db, {
+//       onCreateConnection: (c) => c.pragma('journal_mode = WAL'),
+//   });
+//   const rows = await kysely.selectFrom('users').selectAll().execute();