@photostructure/sqlite 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,13 +2,60 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] (2026-02-06)
+
+### Added
+
+- **Statement modes via `enhance()`**: `stmt.pluck()`, `stmt.raw()`, `stmt.expand()` for better-sqlite3 compatibility
+  - `.pluck()` returns only the first column value from queries
+  - `.raw()` returns rows as arrays instead of objects
+  - `.expand()` returns rows namespaced by table, correctly handling duplicate column names across JOINs
+  - All three modes are mutually exclusive, matching better-sqlite3's toggle semantics
+- **`stmt.database`**: Back-reference from prepared statements to their parent database instance
+- **`EnhancedStatementMethods` type**: TypeScript interface for `pluck()`, `raw()`, `expand()`, and `database`
+
+## [0.4.0] (2026-02-04)
+
+API compatible with `node:sqlite` from Node.js v25.6.1.
+
+### Added
+
+- **`enhance()` function**: Adds better-sqlite3-style `.pragma()` and `.transaction()` methods to any compatible database instance
+- **`isEnhanced()` type guard**: Check if a database has enhanced methods
+- **Transaction helper**: Automatic BEGIN/COMMIT/ROLLBACK with savepoint support for nested transactions
+- **Pragma convenience method**: Simple API for reading and setting SQLite pragmas with `simple` option
+- **Node.js test sync script**: `npm run sync:tests` downloads and adapts upstream Node.js SQLite tests
+- **Percentile extension**: `SQLITE_ENABLE_PERCENTILE` now enabled, adding `percentile()`, `median()`, `percentile_cont()`, `percentile_disc()` SQL functions (Node.js v25+)
+- **Prepare options**: `db.prepare(sql, options)` now accepts per-statement options (`readBigInts`, `returnArrays`, `allowBareNamedParameters`, `allowUnknownNamedParameters`) to override database-level defaults. This is a Node.js v25+ feature; `node:sqlite` on v24 and earlier silently ignores these options.
+- **StatementColumnMetadata type**: `stmt.columns()` now returns richer metadata including `column`, `database`, `table`, and `type` properties alongside `name`
+- **SQLite 3.51.2**: Updated from 3.51.1
+
+### Changed
+
+- **BREAKING**: Removed API extensions to achieve exact parity with `node:sqlite`:
+  - Removed `stmt.finalize()` method (use database close for cleanup)
+  - Removed `stmt.finalized` property
+  - Removed `stmt[Symbol.dispose]` (still available on `DatabaseSync` and `Session`)
+  - Removed `db.backup()` instance method (use standalone `backup(db, path)` function instead)
+- **BREAKING**: `Session.changeset()` and `Session.patchset()` now return `Uint8Array` instead of `Buffer` to match `node:sqlite` API
+- **BREAKING**: Defensive mode now defaults to `true` instead of `false` to match Node.js v25+ behavior. Use `{ defensive: false }` to restore old behavior.
+
+### Fixed
+
+- **Alpine Linux / musl stability**: Fixed native crashes by removing N-API reference cleanup from destructors that corrupted V8 JIT state
+- **Session lifecycle management**: Fixed use-after-free, double-free, and mutex deadlock when databases are garbage collected before their sessions
+- **Worker thread stability**: Added cleanup hooks and exception handling for worker thread termination
+- **Callback error preservation**: `applyChangeset()` now preserves the original error message when JavaScript callbacks throw
+- `createTagStore()` now throws errors with `code: 'ERR_INVALID_STATE'` property when database is closed, matching Node.js error format
+
 ## [0.3.0] (2025-12-16)
 
 ### Changed
 
-- **BREAKING**: `SQLTagStore.size` changed from method to getter for Node.js API parity (Node.js PR #60246)
+- **BREAKING**: `SQLTagStore.size` changed from method to getter for Node.js API parity ([Node.js PR #60246](https://github.com/nodejs/node/pull/60246))
   - Before: `sql.size()`
   - After: `sql.size`
+  - **Note**: This change was merged into Node.js main on December 11, 2025 and will appear in a future Node.js release. Current Node.js v24.x still uses `sql.size()` as a method.
 
 ## [0.2.1] (2025-12-01)
 
@@ -30,11 +77,11 @@ All notable changes to this project will be documented in this file.
 - **Defensive mode**: `enableDefensive()` method to prevent SQL from deliberately corrupting the database
 - **Statement enhancements**: `setAllowUnknownNamedParameters()` method, `finalized` property
 - **Type identification**: `sqlite-type` symbol property on DatabaseSync (Node.js PR #59405)
-- **Enhanced SQLite errors**: New properties `sqliteCode`, `sqliteExtendedCode`, `code`, `sqliteErrorString`, `systemErrno`
+- **SQLite error properties**: `sqliteCode`, `sqliteExtendedCode`, `code`, `sqliteErrorString`, `systemErrno`
 - **ARM64 prebuilds**: macOS Apple Silicon and Windows ARM64 binaries
 - **Tagged template literals**: `db.createTagStore()` for cached prepared statements (Node.js PR #58748)
 - **Authorization API**: `db.setAuthorizer()` for security callbacks (Node.js PR #59928)
-- **Standalone backup**: `backup(srcDb, destFile, options?)` for one-liner database backups with progress callbacks
+- **Standalone backup**: `backup(srcDb, destFile, options?)` for database backups with progress callbacks
 
 ### Fixed
 
@@ -48,16 +95,16 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
-- Initial release of `@photostructure/sqlite` - standalone SQLite for Node.js 20+
-- Full compatibility with Node.js built-in SQLite module API
+- Initial release of `@photostructure/sqlite`, standalone SQLite for Node.js 20+
+- Compatible with Node.js built-in SQLite module API
 - Core SQLite operations with `DatabaseSync` and `StatementSync` classes
-- User-defined scalar and aggregate functions with full window function support
-- Database backup and restoration capabilities
+- User-defined scalar and aggregate functions with window function support
+- Database backup and restoration
 - SQLite sessions and changesets for change tracking
-- Extension loading support with automatic platform-specific file resolution
-- TypeScript definitions with complete type coverage
+- Extension loading with automatic platform-specific file resolution
+- TypeScript definitions
 - Cross-platform prebuilt binaries for Windows, macOS, and Linux (x64, ARM64)
-- Comprehensive test suite with 89+ tests covering all functionality
+- Test suite with 89+ tests
 - Memory safety validation with Valgrind and sanitizers
 - Performance benchmarking suite comparing to better-sqlite3
 - Automated synchronization from Node.js upstream SQLite implementation
@@ -65,15 +112,15 @@ All notable changes to this project will be documented in this file.
 
 ### Features
 
-- **Synchronous API**: Fast, blocking database operations ideal for scripts and tools
-- **Parameter binding**: Support for all SQLite data types including BigInt
+- **Synchronous API**: Blocking database operations for scripts and tools
+- **Parameter binding**: All SQLite data types including BigInt
 - **Error handling**: Detailed error messages with SQLite error codes
 - **Resource limits**: Control memory usage and query complexity
 - **Safe integer handling**: JavaScript-safe integer conversion with overflow detection
-- **Multi-process support**: Safe concurrent access from multiple Node.js processes
-- **Worker thread support**: Full functionality in worker threads
-- **URI filename support**: Full SQLite URI syntax support for advanced database configuration
-- **Strict tables**: Support for SQLite's strict table mode
+- **Multi-process support**: Concurrent access from multiple Node.js processes
+- **Worker thread support**: Works in worker threads
+- **URI filename support**: SQLite URI syntax for advanced database configuration
+- **Strict tables**: SQLite strict table mode
 - **Double-quoted strings**: Configurable SQL syntax compatibility
 
 ### Platform Support
@@ -83,6 +130,8 @@ All notable changes to this project will be documented in this file.
 - macOS (x64, ARM64)
 - Linux (x64, ARM64), (glibc 2.28+, musl)
 
+[0.5.0]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v0.5.0
+[0.4.0]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v0.4.0
 [0.3.0]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v0.3.0
 [0.2.1]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v0.2.1
 [0.2.0]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v0.2.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@photostructure/sqlite.svg)](https://www.npmjs.com/package/@photostructure/sqlite)
 [![CI](https://github.com/photostructure/node-sqlite/actions/workflows/build.yml/badge.svg)](https://github.com/photostructure/node-sqlite/actions/workflows/build.yml)
 
-Native SQLite for Node.js 20+ without the experimental flag. Drop-in replacement for `node:sqlite`. Updated to Node.js v25 for latest features and native Symbol.dispose resource management.
+Native SQLite for Node.js 20+ without the experimental flag. Drop-in replacement for `node:sqlite`. Synced with Node.js v25.6.1 for the latest features including native `Symbol.dispose` resource management.
 
 ## Installation
 
@@ -27,17 +27,18 @@ db.close();
 
 ## Features
 
-- 100% compatible with Node.js v25 built-in `node:sqlite` module\*
+- 100% compatible with Node.js v25.6.1 built-in `node:sqlite` module\*
 - Zero dependencies - native SQLite implementation
 - Synchronous API - no async overhead
-- Performance matches leading SQLite libraries
+- Performance comparable to better-sqlite3
 - Full SQLite feature set ([details](./doc/features.md))
 - TypeScript support with complete type definitions
 - Cross-platform prebuilt binaries (Windows/macOS/Linux, x64/ARM64)
 - User-defined functions and aggregates
 - Database backups and session/changeset support
 - Session class exposed for advanced replication workflows
-- Native Symbol.dispose for improved resource management
+- Native `Symbol.dispose` for resource management
+- `enhance()` function for better-sqlite3 style `.pragma()` and `.transaction()` methods
 - URI filename support for advanced configuration
 - Worker thread safe
 - [Compare with other libraries →](./doc/library-comparison.md)
@@ -69,12 +70,6 @@ db.close();
 - [Build Flags & Configuration](./doc/build-flags.md)
 - [Library Comparison](./doc/library-comparison.md)
 
-## Support
-
-- 🐛 [Issues](https://github.com/photostructure/node-sqlite/issues)
-- 💬 [Discussions](https://github.com/photostructure/node-sqlite/discussions)
-- 📧 [Security](./SECURITY.md)
-
 ## License
 
 MIT - see [LICENSE](./LICENSE) for details.

package/binding.gyp

@@ -11,13 +11,12 @@
         "src/upstream/sqlite3.c"
       ],
       "include_dirs": [
-        "<!@(node -p \"require('node-addon-api').include\")",
         "src",
         "src/upstream",
         "src/shims"
       ],
       "dependencies": [
-        "<!(node -p \"require('node-addon-api').gyp\")"
+        "<!(node -p \"require('node-addon-api').targets + ':node_addon_api_except'\")"
       ],
       # SQLite build flags - see doc/build-flags.md for comprehensive documentation
       # including comparison with Node.js configuration and rationale for our choices
@@ -40,6 +39,7 @@
         "SQLITE_ENABLE_JSON1",
         "SQLITE_ENABLE_MATH_FUNCTIONS",
         "SQLITE_ENABLE_NORMALIZE",
+        "SQLITE_ENABLE_PERCENTILE",
         "SQLITE_ENABLE_PREUPDATE_HOOK",
         "SQLITE_ENABLE_RBU",
         "SQLITE_ENABLE_RTREE",

package/dist/index.cjs

@@ -36,7 +36,9 @@ __export(index_exports, {
   StatementSync: () => StatementSync,
   backup: () => backup,
   constants: () => constants,
-  default: () => index_default
+  default: () => index_default,
+  enhance: () => enhance,
+  isEnhanced: () => isEnhanced
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_gyp_build = __toESM(require("node-gyp-build"));
@@ -187,7 +189,9 @@ var SQLTagStore = class {
   maxCapacity;
   constructor(db, capacity = DEFAULT_CAPACITY) {
     if (!db.isOpen) {
-      throw new Error("Database is not open");
+      const err = new Error("database is not open");
+      err.code = "ERR_INVALID_STATE";
+      throw err;
     }
     this.database = db;
     this.maxCapacity = capacity;
@@ -248,19 +252,15 @@ var SQLTagStore = class {
   }
   /**
    * Get a cached statement or prepare a new one.
-   * If a cached statement has been finalized, it's evicted and a new one is prepared.
    */
   getOrPrepare(strings) {
     if (!this.database.isOpen) {
-      throw new Error("Database is not open");
+      throw new Error("database is not open");
     }
     const sql = this.buildSQL(strings);
     const cached = this.cache.get(sql);
     if (cached) {
-      if (!cached.finalized) {
-        return cached;
-      }
-      this.cache.delete(sql);
+      return cached;
     }
     const stmt = this.database.prepare(sql);
     this.cache.set(sql, stmt);
@@ -278,13 +278,314 @@ var SQLTagStore = class {
   }
 };
 
+// src/transaction.ts
+var savepointCounter = 0;
+function createTransaction(db, fn) {
+  if (typeof fn !== "function") {
+    throw new TypeError("Expected first argument to be a function");
+  }
+  const variants = {
+    deferred: createVariant(db, fn, "deferred"),
+    immediate: createVariant(db, fn, "immediate"),
+    exclusive: createVariant(db, fn, "exclusive")
+  };
+  const defaultFn = variants.deferred;
+  for (const variant of Object.values(variants)) {
+    Object.defineProperties(variant, {
+      deferred: { value: variants.deferred, enumerable: true },
+      immediate: { value: variants.immediate, enumerable: true },
+      exclusive: { value: variants.exclusive, enumerable: true },
+      database: { value: db, enumerable: true }
+    });
+  }
+  return defaultFn;
+}
+function createVariant(db, fn, mode) {
+  const beginStatement = getBeginStatement(mode);
+  return function transactionWrapper(...args) {
+    const isNested = db.isTransaction;
+    let begin;
+    let commit;
+    let rollback;
+    if (isNested) {
+      const savepointName = `\`_txn_${++savepointCounter}\``;
+      begin = `SAVEPOINT ${savepointName}`;
+      commit = `RELEASE ${savepointName}`;
+      rollback = `ROLLBACK TO ${savepointName}`;
+    } else {
+      begin = beginStatement;
+      commit = "COMMIT";
+      rollback = "ROLLBACK";
+    }
+    db.exec(begin);
+    try {
+      const result = fn.apply(this, args);
+      if (result !== null && typeof result === "object" && "then" in result) {
+        throw new TypeError(
+          "Transaction function must not return a Promise. SQLite transactions are synchronous and cannot span across async operations. Use synchronous code within transactions."
+        );
+      }
+      db.exec(commit);
+      return result;
+    } catch (error) {
+      if (db.isTransaction) {
+        db.exec(rollback);
+        if (isNested) {
+          db.exec(commit);
+        }
+      }
+      throw error;
+    }
+  };
+}
+function getBeginStatement(mode) {
+  switch (mode) {
+    case "deferred":
+      return "BEGIN DEFERRED";
+    case "immediate":
+      return "BEGIN IMMEDIATE";
+    case "exclusive":
+      return "BEGIN EXCLUSIVE";
+    default:
+      throw new Error(`Unknown transaction mode: ${mode}`);
+  }
+}
+
+// src/enhance.ts
+var ENHANCED_PREPARE = /* @__PURE__ */ Symbol.for("@photostructure/sqlite:enhancedPrepare");
+function extractFirstColumn(row) {
+  if (row == null) return row;
+  if (Array.isArray(row)) return row[0];
+  const keys = Object.keys(row);
+  return keys.length > 0 ? row[keys[0]] : void 0;
+}
+function buildColumnTableMap(stmt) {
+  if (typeof stmt.columns !== "function") return void 0;
+  const cols = stmt.columns();
+  return cols.map((c) => ({
+    table: c.table ?? "$",
+    column: c.name
+  }));
+}
+function expandRowFromArray(row, columnMap) {
+  const result = {};
+  for (let i = 0; i < columnMap.length && i < row.length; i++) {
+    const { table, column } = columnMap[i];
+    result[table] ??= {};
+    result[table][column] = row[i];
+  }
+  return result;
+}
+function expandRowFromObject(row, columnMap) {
+  const result = {};
+  const keys = Object.keys(row);
+  for (let i = 0; i < keys.length && i < columnMap.length; i++) {
+    const { table, column } = columnMap[i];
+    result[table] ??= {};
+    result[table][column] = row[keys[i]];
+  }
+  return result;
+}
+function validateToggle(value) {
+  const use = value === void 0 ? true : value;
+  if (typeof use !== "boolean") {
+    throw new TypeError("Expected first argument to be a boolean");
+  }
+  return use;
+}
+function transformRow(row, mode, columnMap) {
+  if (row == null || mode === "flat") return row;
+  if (mode === "pluck") return extractFirstColumn(row);
+  if (mode === "expand") {
+    if (Array.isArray(row)) {
+      return expandRowFromArray(row, columnMap);
+    }
+    return expandRowFromObject(row, columnMap);
+  }
+  return row;
+}
+function enhanceStatement(stmt) {
+  if (typeof stmt.pluck === "function") {
+    return stmt;
+  }
+  let mode = "flat";
+  let columnMap;
+  const originalGet = typeof stmt.get === "function" ? stmt.get.bind(stmt) : void 0;
+  const originalAll = stmt.all.bind(stmt);
+  const originalIterate = typeof stmt.iterate === "function" ? stmt.iterate.bind(stmt) : void 0;
+  function setMode(target, use) {
+    if (use) {
+      mode = target;
+      if (target === "expand" && columnMap == null) {
+        columnMap = buildColumnTableMap(stmt);
+        if (columnMap == null) {
+          throw new TypeError(
+            "expand() requires the statement to have a columns() method"
+          );
+        }
+      }
+    } else if (mode === target) {
+      mode = "flat";
+    }
+    if (typeof stmt.setReturnArrays === "function") {
+      stmt.setReturnArrays(mode === "raw" || mode === "expand");
+    }
+  }
+  Object.defineProperty(stmt, "pluck", {
+    value: function pluck(toggle) {
+      setMode("pluck", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false
+  });
+  Object.defineProperty(stmt, "raw", {
+    value: function raw(toggle) {
+      setMode("raw", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false
+  });
+  Object.defineProperty(stmt, "expand", {
+    value: function expand(toggle) {
+      setMode("expand", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false
+  });
+  if (originalGet != null) {
+    Object.defineProperty(stmt, "get", {
+      value: (...params) => {
+        const row = originalGet(...params);
+        return transformRow(row, mode, columnMap);
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+  }
+  Object.defineProperty(stmt, "all", {
+    value: (...params) => {
+      const rows = originalAll(...params);
+      if (mode === "flat" || mode === "raw") return rows;
+      return rows.map((row) => transformRow(row, mode, columnMap));
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false
+  });
+  if (originalIterate != null) {
+    Object.defineProperty(stmt, "iterate", {
+      value: function* (...params) {
+        const iter = originalIterate(...params);
+        for (const row of iter) {
+          yield transformRow(row, mode, columnMap);
+        }
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+  }
+  return stmt;
+}
+function pragmaImpl(source, options) {
+  if (typeof source !== "string") {
+    throw new TypeError("Expected first argument to be a string");
+  }
+  if (options != null && typeof options !== "object") {
+    throw new TypeError("Expected second argument to be an options object");
+  }
+  const simple = options?.simple === true;
+  if (options != null && "simple" in options && typeof options.simple !== "boolean") {
+    throw new TypeError('Expected the "simple" option to be a boolean');
+  }
+  const stmt = this.prepare(`PRAGMA ${source}`);
+  if (simple) {
+    return extractFirstColumn(stmt.all()[0]);
+  }
+  return stmt.all();
+}
+function transactionImpl(fn) {
+  return createTransaction(this, fn);
+}
+function hasEnhancedMethods(db) {
+  return typeof db.pragma === "function" && typeof db.transaction === "function";
+}
+function enhance(db) {
+  if (!hasEnhancedMethods(db)) {
+    Object.defineProperty(db, "pragma", {
+      value: pragmaImpl,
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+    Object.defineProperty(db, "transaction", {
+      value: transactionImpl,
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+  }
+  if (!db[ENHANCED_PREPARE]) {
+    const originalPrepare = db.prepare.bind(db);
+    Object.defineProperty(db, "prepare", {
+      value: (...args) => {
+        const stmt = originalPrepare(...args);
+        enhanceStatement(stmt);
+        Object.defineProperty(stmt, "database", {
+          value: db,
+          writable: false,
+          configurable: true,
+          enumerable: false
+        });
+        return stmt;
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+    Object.defineProperty(db, ENHANCED_PREPARE, {
+      value: true,
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+  return db;
+}
+function isEnhanced(db) {
+  return hasEnhancedMethods(db);
+}
+
 // src/index.ts
 var binding = (0, import_node_gyp_build.default)((0, import_node_path2.join)(_dirname(), ".."));
-var DatabaseSync = binding.DatabaseSync;
+var _DatabaseSync = binding.DatabaseSync;
+var DatabaseSync = function DatabaseSync2(...args) {
+  if (!new.target) {
+    const err = new TypeError("Cannot call constructor without `new`");
+    err.code = "ERR_CONSTRUCT_CALL_REQUIRED";
+    throw err;
+  }
+  return Reflect.construct(_DatabaseSync, args, new.target);
+};
+Object.setPrototypeOf(DatabaseSync, _DatabaseSync);
+DatabaseSync.prototype = _DatabaseSync.prototype;
 DatabaseSync.prototype.createTagStore = function(capacity) {
   return new SQLTagStore(this, capacity);
 };
-var StatementSync = binding.StatementSync;
+var _StatementSync = binding.StatementSync;
+var StatementSync = function StatementSync2() {
+  const err = new TypeError("Illegal constructor");
+  err.code = "ERR_ILLEGAL_CONSTRUCTOR";
+  throw err;
+};
+StatementSync.prototype = _StatementSync.prototype;
 var Session = binding.Session;
 var constants = binding.constants;
 var backup = binding.backup;
@@ -296,6 +597,8 @@ var index_default = binding;
   Session,
   StatementSync,
   backup,
-  constants
+  constants,
+  enhance,
+  isEnhanced
 });
 //# sourceMappingURL=index.cjs.map