@photostructure/sqlite 0.3.0 → 0.5.0

package/src/enhance.ts

@@ -0,0 +1,552 @@
+/**
+ * Enhancement utilities for adding better-sqlite3-style methods to any
+ * compatible database, including `node:sqlite` DatabaseSync and this package's
+ * DatabaseSync.
+ *
+ * This module provides the `enhance()` function which adds `.pragma()`,
+ * `.transaction()`, and statement modes (`.pluck()`, `.raw()`, `.expand()`)
+ * to database instances that don't have them (e.g., node:sqlite DatabaseSync).
+ */
+
+import { createTransaction } from "./transaction";
+import type { PragmaOptions } from "./types/pragma-options";
+import type { TransactionFunction } from "./types/transaction";
+
+/**
+ * Minimal interface for a database that can be enhanced. This matches the
+ * subset of functionality needed by pragma() and transaction().
+ */
+export interface EnhanceableDatabaseSync {
+  /** Execute SQL without returning results */
+  exec(sql: string): void;
+  /** Prepare a statement that can return results */
+  prepare(sql: string): { all(): unknown[] };
+  /** Whether the database connection is open */
+  readonly isOpen?: boolean;
+  /** Whether a transaction is currently active */
+  readonly isTransaction: boolean;
+}
+
+/**
+ * Statement mode matching better-sqlite3's mutually exclusive modes.
+ * - "flat": Default — rows as `{ column: value }` objects
+ * - "pluck": First column value only
+ * - "raw": Rows as arrays of values
+ * - "expand": Rows namespaced by table, e.g. `{ users: { id: 1 }, posts: { title: "..." } }`
+ */
+type StatementMode = "flat" | "pluck" | "raw" | "expand";
+
+/**
+ * A statement enhanced with better-sqlite3-style `.pluck()`, `.raw()`, and
+ * `.expand()` methods. These are mutually exclusive — enabling one disables
+ * the others.
+ */
+export interface EnhancedStatementMethods {
+  /**
+   * Causes the statement to return only the first column value of each row.
+   *
+   * When plucking is turned on, raw and expand modes are turned off.
+   *
+   * @param toggle Enable (true) or disable (false) pluck mode. Defaults to true.
+   * @returns The same statement for chaining.
+   *
+   * @example
+   * ```typescript
+   * const count = db.prepare("SELECT COUNT(*) FROM users").pluck().get();
+   * // Returns: 42 (not { "COUNT(*)": 42 })
+   *
+   * const names = db.prepare("SELECT name FROM users").pluck().all();
+   * // Returns: ["Alice", "Bob"] (not [{ name: "Alice" }, { name: "Bob" }])
+   * ```
+   */
+  pluck(toggle?: boolean): this;
+
+  /**
+   * Causes the statement to return rows as arrays of values instead of objects.
+   *
+   * When raw mode is turned on, pluck and expand modes are turned off.
+   *
+   * @param toggle Enable (true) or disable (false) raw mode. Defaults to true.
+   * @returns The same statement for chaining.
+   *
+   * @example
+   * ```typescript
+   * const rows = db.prepare("SELECT id, name FROM users").raw().all();
+   * // Returns: [[1, "Alice"], [2, "Bob"]] (not [{ id: 1, name: "Alice" }, ...])
+   * ```
+   */
+  raw(toggle?: boolean): this;
+
+  /**
+   * Causes the statement to return data namespaced by table. Each key in a row
+   * object will be a table name, and each corresponding value will be a nested
+   * object containing that table's columns. Columns from expressions or
+   * subqueries are placed under the special `$` namespace.
+   *
+   * When expand mode is turned on, pluck and raw modes are turned off.
+   *
+   * Requires the statement to have a `.columns()` method (available on real
+   * statements but not minimal mocks).
+   *
+   * @param toggle Enable (true) or disable (false) expand mode. Defaults to true.
+   * @returns The same statement for chaining.
+   *
+   * @example
+   * ```typescript
+   * const rows = db.prepare("SELECT u.id, u.name, p.title FROM users u JOIN posts p ON ...").expand().all();
+   * // Returns: [{ users: { id: 1, name: "Alice" }, posts: { title: "Hello" } }]
+   * ```
+   */
+  expand(toggle?: boolean): this;
+
+  /** The database instance this statement was prepared from. */
+  readonly database: EnhanceableDatabaseSync;
+}
+
+/**
+ * Interface for an enhanced database with pragma() and transaction() methods.
+ */
+export interface EnhancedMethods {
+  /**
+   * Executes a PRAGMA statement and returns its result.
+   *
+   * @param source The PRAGMA command (without "PRAGMA" prefix)
+   * @param options Optional configuration
+   * @returns Array of rows, or single value if `simple: true`
+   *
+   * @example
+   * ```typescript
+   * db.pragma('cache_size', { simple: true }); // -16000
+   * db.pragma('journal_mode = wal');
+   * ```
+   */
+  pragma(source: string, options?: PragmaOptions): unknown;
+
+  /**
+   * Creates a function that always runs inside a transaction.
+   *
+   * @param fn The function to wrap in a transaction
+   * @returns A transaction function with `.deferred`, `.immediate`,
+   * `.exclusive` variants
+   *
+   * @example
+   * ```typescript
+   * const insertMany = db.transaction((items) => {
+   *   for (const item of items) insert.run(item);
+   * });
+   * insertMany(['a', 'b', 'c']); // All in one transaction
+   * ```
+   */
+  transaction<F extends (...args: any[]) => any>(fn: F): TransactionFunction<F>;
+}
+
+/**
+ * A database instance that has been enhanced with pragma(), transaction(),
+ * and statement modes (pluck/raw/expand) on statements returned by prepare().
+ */
+export type EnhancedDatabaseSync<T extends EnhanceableDatabaseSync> = Omit<
+  T,
+  "prepare"
+> &
+  EnhancedMethods & {
+    prepare(
+      ...args: Parameters<T["prepare"]>
+    ): ReturnType<T["prepare"]> & EnhancedStatementMethods;
+  };
+
+/** Symbol to track whether prepare() has been wrapped */
+const ENHANCED_PREPARE = Symbol.for("@photostructure/sqlite:enhancedPrepare");
+
+/**
+ * Extract the first column value from a row object or array.
+ */
+function extractFirstColumn(row: unknown): unknown {
+  if (row == null) return row;
+  if (Array.isArray(row)) return row[0];
+  const keys = Object.keys(row as Record<string, unknown>);
+  return keys.length > 0
+    ? (row as Record<string, unknown>)[keys[0]!]
+    : undefined;
+}
+
+/**
+ * Build a column-to-table mapping from statement metadata, used by expand mode.
+ * Returns an array parallel to column order: each entry is the table name
+ * (or "$" for expressions/subqueries) and the column name.
+ */
+function buildColumnTableMap(
+  stmt: any,
+): Array<{ table: string; column: string }> | undefined {
+  if (typeof stmt.columns !== "function") return undefined;
+  const cols: Array<{ name: string; table: string | null }> = stmt.columns();
+  return cols.map((c) => ({
+    table: c.table ?? "$",
+    column: c.name,
+  }));
+}
+
+/**
+ * Transform a row array into a table-namespaced expanded object.
+ * Uses array indices to match columns, avoiding data loss from duplicate names.
+ */
+function expandRowFromArray(
+  row: unknown[],
+  columnMap: Array<{ table: string; column: string }>,
+): Record<string, Record<string, unknown>> {
+  const result: Record<string, Record<string, unknown>> = {};
+  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;
+}
+
+/**
+ * Transform a flat row object into a table-namespaced expanded object.
+ * Fallback for mocks without setReturnArrays — cannot handle duplicate column
+ * names correctly, but mocks typically don't produce them.
+ */
+function expandRowFromObject(
+  row: Record<string, unknown>,
+  columnMap: Array<{ table: string; column: string }>,
+): Record<string, Record<string, unknown>> {
+  const result: Record<string, Record<string, unknown>> = {};
+  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;
+}
+
+/**
+ * Validate a boolean toggle argument, matching better-sqlite3's pattern.
+ */
+function validateToggle(value: unknown): boolean {
+  const use = value === undefined ? true : value;
+  if (typeof use !== "boolean") {
+    throw new TypeError("Expected first argument to be a boolean");
+  }
+  return use;
+}
+
+/**
+ * Transform a row based on the current statement mode.
+ */
+function transformRow(
+  row: unknown,
+  mode: StatementMode,
+  columnMap: Array<{ table: string; column: string }> | undefined,
+): unknown {
+  if (row == null || mode === "flat") return row;
+  if (mode === "pluck") return extractFirstColumn(row);
+  if (mode === "expand") {
+    // columnMap is guaranteed non-null here — setMode() throws if columns() is
+    // unavailable, so we'll never reach this branch with columnMap == null.
+    // Prefer array-based expand (used when setReturnArrays is available)
+    // to correctly handle duplicate column names across tables.
+    // Fall back to object-based expand for mocks without setReturnArrays.
+    if (Array.isArray(row)) {
+      return expandRowFromArray(row, columnMap!);
+    }
+    return expandRowFromObject(row as Record<string, unknown>, columnMap!);
+  }
+  // "raw" mode is handled natively by setReturnArrays(), so no transform needed
+  return row;
+}
+
+/**
+ * Add `.pluck()`, `.raw()`, and `.expand()` methods to a statement instance.
+ * These modes are mutually exclusive — enabling one disables the others,
+ * matching better-sqlite3's behavior.
+ */
+function enhanceStatement<S extends { all(): unknown[] }>(
+  stmt: S,
+): S & EnhancedStatementMethods {
+  // Idempotency: if already enhanced, return as-is
+  if (typeof (stmt as any).pluck === "function") {
+    return stmt as S & EnhancedStatementMethods;
+  }
+
+  let mode: StatementMode = "flat";
+  let columnMap: Array<{ table: string; column: string }> | undefined;
+
+  // Cast to any to avoid TypeScript strictness around bound method signatures.
+  // At runtime these are native C++ methods that accept variadic bind parameters.
+  const originalGet: any =
+    typeof (stmt as any).get === "function"
+      ? (stmt as any).get.bind(stmt)
+      : undefined;
+  const originalAll: any = (stmt as any).all.bind(stmt);
+  const originalIterate: any =
+    typeof (stmt as any).iterate === "function"
+      ? (stmt as any).iterate.bind(stmt)
+      : undefined;
+
+  // Toggle helper matching better-sqlite3's mode switching:
+  // enable(true) sets to target mode; enable(false) resets to flat ONLY if
+  // currently in that mode, otherwise leaves mode unchanged.
+  function setMode(target: StatementMode, use: boolean): void {
+    if (use) {
+      mode = target;
+      // Cache column map on first expand() call
+      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 use=false and mode !== target, no-op (matches better-sqlite3)
+
+    // Sync native array mode: both raw and expand need arrays from the native layer.
+    // Expand needs arrays to correctly handle duplicate column names across tables.
+    if (typeof (stmt as any).setReturnArrays === "function") {
+      (stmt as any).setReturnArrays(mode === "raw" || mode === "expand");
+    }
+  }
+
+  Object.defineProperty(stmt, "pluck", {
+    value: function pluck(toggle?: boolean): S {
+      setMode("pluck", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+
+  Object.defineProperty(stmt, "raw", {
+    value: function raw(toggle?: boolean): S {
+      setMode("raw", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+
+  Object.defineProperty(stmt, "expand", {
+    value: function expand(toggle?: boolean): S {
+      setMode("expand", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+
+  if (originalGet != null) {
+    Object.defineProperty(stmt, "get", {
+      value: (...params: any[]) => {
+        const row = originalGet(...params);
+        return transformRow(row, mode, columnMap);
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  Object.defineProperty(stmt, "all", {
+    value: (...params: any[]) => {
+      const rows = originalAll(...params);
+      if (mode === "flat" || mode === "raw") return rows;
+      return rows.map((row: unknown) => transformRow(row, mode, columnMap));
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+
+  if (originalIterate != null) {
+    Object.defineProperty(stmt, "iterate", {
+      value: function* (...params: any[]) {
+        const iter = originalIterate(...params);
+        for (const row of iter) {
+          yield transformRow(row, mode, columnMap);
+        }
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  return stmt as S & EnhancedStatementMethods;
+}
+
+/**
+ * Implementation of pragma() that works on any EnhanceableDatabaseSync.
+ */
+function pragmaImpl(
+  this: EnhanceableDatabaseSync,
+  source: string,
+  options?: PragmaOptions,
+): unknown {
+  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;
+
+  // Validate that simple is a boolean if provided
+  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();
+}
+
+/**
+ * Implementation of transaction() that works on any EnhanceableDatabaseSync.
+ */
+function transactionImpl<F extends (...args: any[]) => any>(
+  this: EnhanceableDatabaseSync,
+  fn: F,
+): TransactionFunction<F> {
+  // createTransaction expects DatabaseSyncInstance but only uses the subset
+  // defined in EnhanceableDatabaseSync, so this cast is safe
+  return createTransaction(this as any, fn);
+}
+
+/**
+ * Checks if a database instance already has the enhanced methods.
+ */
+function hasEnhancedMethods(
+  db: EnhanceableDatabaseSync,
+): db is EnhanceableDatabaseSync & EnhancedMethods {
+  return (
+    typeof (db as any).pragma === "function" &&
+    typeof (db as any).transaction === "function"
+  );
+}
+
+/**
+ * Ensures that `.pragma()`, `.transaction()`, and statement modes
+ * (`.pluck()`, `.raw()`, `.expand()`) are available on the given database.
+ *
+ * This function can enhance:
+ * - `node:sqlite` DatabaseSync instances (adds the methods)
+ * - `@photostructure/sqlite` DatabaseSync instances (adds the methods)
+ * - Any object with compatible `exec()`, `prepare()`, and `isTransaction`
+ *
+ * The enhancement is done by adding methods directly to the instance, not the
+ * prototype, so it won't affect other instances or the original class.
+ *
+ * @param db The database instance to enhance
+ * @returns The same instance with `.pragma()`, `.transaction()`, and
+ * `.pluck()` / `.raw()` / `.expand()` (on prepared statements) guaranteed
+ *
+ * @example
+ * ```typescript
+ * import { DatabaseSync, enhance } from '@photostructure/sqlite';
+ *
+ * const db = enhance(new DatabaseSync(':memory:'));
+ *
+ * // better-sqlite3-style pragma
+ * db.pragma('journal_mode = wal');
+ *
+ * // better-sqlite3-style transactions
+ * const insertMany = db.transaction((items) => {
+ *   for (const item of items) insert.run(item);
+ * });
+ *
+ * // better-sqlite3-style pluck
+ * const count = db.prepare("SELECT COUNT(*) FROM users").pluck().get();
+ * const names = db.prepare("SELECT name FROM users").pluck().all();
+ * ```
+ */
+export function enhance<T extends EnhanceableDatabaseSync>(
+  db: T,
+): EnhancedDatabaseSync<T> {
+  // Add pragma and transaction if not already present
+  if (!hasEnhancedMethods(db)) {
+    // Using Object.defineProperty to make them non-enumerable like native methods
+    Object.defineProperty(db, "pragma", {
+      value: pragmaImpl,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+
+    Object.defineProperty(db, "transaction", {
+      value: transactionImpl,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  // Wrap prepare() to add pluck() to returned statements
+  if (!(db as any)[ENHANCED_PREPARE]) {
+    const originalPrepare: any = db.prepare.bind(db);
+
+    Object.defineProperty(db, "prepare", {
+      value: (...args: any[]) => {
+        const stmt = originalPrepare(...args);
+        enhanceStatement(stmt);
+        // Add stmt.database back-reference for better-sqlite3 compat
+        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 as unknown as EnhancedDatabaseSync<T>;
+}
+
+/**
+ * Type guard to check if a database has enhanced methods.
+ *
+ * @param db The database to check
+ * @returns True if the database has `.pragma()` and `.transaction()` methods
+ *
+ * @example
+ * ```typescript
+ * import { isEnhanced } from '@photostructure/sqlite';
+ *
+ * if (isEnhanced(db)) {
+ *   db.pragma('cache_size', { simple: true });
+ * }
+ * ```
+ */
+export function isEnhanced(
+  db: EnhanceableDatabaseSync,
+): db is EnhanceableDatabaseSync & EnhancedMethods {
+  return hasEnhancedMethods(db);
+}

package/src/index.ts

@@ -17,6 +17,7 @@ export type { AggregateOptions } from "./types/aggregate-options";
 export type { ChangesetApplyOptions } from "./types/changeset-apply-options";
 export type { DatabaseSyncInstance } from "./types/database-sync-instance";
 export type { DatabaseSyncOptions } from "./types/database-sync-options";
+export type { PragmaOptions } from "./types/pragma-options";
 export type { SessionOptions } from "./types/session-options";
 export type { SQLTagStoreInstance } from "./types/sql-tag-store-instance";
 export type { SqliteAuthorizationActions } from "./types/sqlite-authorization-actions";
@@ -24,9 +25,23 @@ export type { SqliteAuthorizationResults } from "./types/sqlite-authorization-re
 export type { SqliteChangesetConflictTypes } from "./types/sqlite-changeset-conflict-types";
 export type { SqliteChangesetResolution } from "./types/sqlite-changeset-resolution";
 export type { SqliteOpenFlags } from "./types/sqlite-open-flags";
-export type { StatementSyncInstance } from "./types/statement-sync-instance";
+export type {
+  StatementColumnMetadata,
+  StatementSyncInstance,
+} from "./types/statement-sync-instance";
+export type { TransactionFunction, TransactionMode } from "./types/transaction";
 export type { UserFunctionOptions } from "./types/user-functions-options";
 
+// Enhancement utilities for adding better-sqlite3-style methods to any compatible database
+export {
+  enhance,
+  isEnhanced,
+  type EnhanceableDatabaseSync,
+  type EnhancedDatabaseSync,
+  type EnhancedMethods,
+  type EnhancedStatementMethods,
+} from "./enhance";
+
 // Use _dirname() helper that works in both CJS/ESM and Jest
 const binding = nodeGypBuild(join(_dirname(), ".."));
 
@@ -52,25 +67,54 @@ export type SqliteConstants = SqliteOpenFlags &
 
 /**
  * Options for creating a prepared statement.
+ *
+ * **Note:** The per-statement override options (`readBigInts`, `returnArrays`,
+ * `allowBareNamedParameters`, `allowUnknownNamedParameters`) are a **Node.js v25+**
+ * feature. On Node.js v24 and earlier, `node:sqlite` silently ignores these options.
+ * This library implements them for forward compatibility with Node.js v25+.
  */
 export interface StatementOptions {
   /** If true, the prepared statement's expandedSQL property will contain the expanded SQL. @default false */
   readonly expandedSQL?: boolean;
   /** If true, anonymous parameters are enabled for the statement. @default false */
   readonly anonymousParameters?: boolean;
+  /**
+   * If true, read integer values as JavaScript BigInt. Overrides database-level setting.
+   * **Node.js v25+ feature** - silently ignored by `node:sqlite` on v24 and earlier.
+   * @default database default
+   */
+  readonly readBigInts?: boolean;
+  /**
+   * If true, return results as arrays rather than objects. Overrides database-level setting.
+   * **Node.js v25+ feature** - silently ignored by `node:sqlite` on v24 and earlier.
+   * @default database default
+   */
+  readonly returnArrays?: boolean;
+  /**
+   * If true, allows bare named parameters (without prefix). Overrides database-level setting.
+   * **Node.js v25+ feature** - silently ignored by `node:sqlite` on v24 and earlier.
+   * @default database default
+   */
+  readonly allowBareNamedParameters?: boolean;
+  /**
+   * If true, unknown named parameters are ignored. Overrides database-level setting.
+   * **Node.js v25+ feature** - silently ignored by `node:sqlite` on v24 and earlier.
+   * @default database default
+   */
+  readonly allowUnknownNamedParameters?: boolean;
 }
 
 export interface Session {
   /**
    * Generate a changeset containing all changes recorded by the session.
-   * @returns A Buffer containing the changeset data.
+   * @returns A Uint8Array containing the changeset data.
    */
-  changeset(): Buffer;
+  changeset(): Uint8Array;
   /**
    * Generate a patchset containing all changes recorded by the session.
-   * @returns A Buffer containing the patchset data.
+   * @returns A Uint8Array containing the patchset data.
    */
-  patchset(): Buffer;
+  patchset(): Uint8Array;
   /**
    * Close the session and release its resources.
    */
@@ -133,8 +177,20 @@ export interface SqliteModule {
  * const readOnlyDb = new DatabaseSync('./data.db', { readOnly: true });
  * ```
  */
-export const DatabaseSync =
-  binding.DatabaseSync as SqliteModule["DatabaseSync"];
+// Store the native binding's DatabaseSync
+const _DatabaseSync = binding.DatabaseSync;
+// Wrapper around the native constructor to enforce usage of `new` with the correct error code.
+// We use a function wrapper instead of a Proxy for better performance and explicit prototype handling.
+export const DatabaseSync = function DatabaseSync(this: any, ...args: any[]) {
+  if (!new.target) {
+    const err = new TypeError("Cannot call constructor without `new`");
+    (err as NodeJS.ErrnoException).code = "ERR_CONSTRUCT_CALL_REQUIRED";
+    throw err;
+  }
+  return Reflect.construct(_DatabaseSync, args, new.target);
+} as unknown as SqliteModule["DatabaseSync"];
+Object.setPrototypeOf(DatabaseSync, _DatabaseSync);
+DatabaseSync.prototype = _DatabaseSync.prototype;
 
 // node:sqlite implements createTagStore and SQLTagStore entirely in native C++.
 // We use a TypeScript implementation instead, attached via prototype extension.
@@ -148,6 +204,15 @@ export const DatabaseSync =
   return new SQLTagStore(this, capacity);
 };
 
+// NOTE: .pragma() and .transaction() are NOT added to the prototype by default.
+// This keeps DatabaseSync 100% API-compatible with node:sqlite.
+// Users who want better-sqlite3-style methods should use enhance():
+//
+//   import { DatabaseSync, enhance } from '@photostructure/sqlite';
+//   const db = enhance(new DatabaseSync(':memory:'));
+//   db.pragma('journal_mode', { simple: true });
+//   db.transaction(() => { ... });
+
 /**
  * The StatementSync class represents a prepared SQL statement.
  * This class should not be instantiated directly; use DatabaseSync.prepare() instead.
@@ -159,8 +224,18 @@ export const DatabaseSync =
  * stmt.finalize();
  * ```
  */
-export const StatementSync =
-  binding.StatementSync as SqliteModule["StatementSync"];
+// Store the native binding's StatementSync for internal use
+const _StatementSync = binding.StatementSync;
+// Export a wrapper that throws ERR_ILLEGAL_CONSTRUCTOR when called directly
+// but preserves instanceof checks and prototype chain
+export const StatementSync = function StatementSync() {
+  const err = new TypeError("Illegal constructor");
+  (err as NodeJS.ErrnoException).code = "ERR_ILLEGAL_CONSTRUCTOR";
+  throw err;
+} as unknown as SqliteModule["StatementSync"];
+// Use the native prototype directly so instanceof checks work correctly
+// (stmt instanceof StatementSync will check if StatementSync.prototype is in stmt's chain)
+StatementSync.prototype = _StatementSync.prototype;
 
 /**
  * The Session class for recording database changes.