@photostructure/sqlite 0.3.0 → 0.4.0

package/src/enhance.ts

@@ -0,0 +1,228 @@
+/**
+ * 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()` and
+ * `.transaction()` methods 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 a transaction is currently active */
+  readonly isTransaction: boolean;
+}
+
+/**
+ * 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() and transaction() methods.
+ */
+export type EnhancedDatabaseSync<T extends EnhanceableDatabaseSync> = T &
+  EnhancedMethods;
+
+/**
+ * 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}`);
+  const rows = stmt.all() as Record<string, unknown>[];
+
+  if (simple) {
+    // Return the first column of the first row, or undefined if no rows
+    const firstRow = rows[0];
+    if (firstRow == null) {
+      return undefined;
+    }
+    const keys = Object.keys(firstRow);
+    const firstKey = keys[0];
+    if (firstKey == null) {
+      return undefined;
+    }
+    return firstRow[firstKey];
+  }
+
+  return rows;
+}
+
+/**
+ * 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()` and `.transaction()` methods are available on the
+ * given database.
+ *
+ * This function can enhance:
+ * - `node:sqlite` DatabaseSync instances (adds the methods)
+ * - `@photostructure/sqlite` DatabaseSync instances (no-op, already has these
+ *   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()` and `.transaction()` methods
+ * guaranteed
+ *
+ * @example
+ * ```typescript
+ * // With node:sqlite
+ * import { DatabaseSync } from 'node:sqlite';
+ * import { enhance } from '@photostructure/sqlite';
+ *
+ * const db = enhance(new DatabaseSync(':memory:'));
+ *
+ * // Now you can use better-sqlite3-style methods
+ * db.pragma('journal_mode = wal');
+ * const insertMany = db.transaction((items) => {
+ *   for (const item of items) insert.run(item);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With @photostructure/sqlite (no-op, already enhanced)
+ * import { DatabaseSync, enhance } from '@photostructure/sqlite';
+ *
+ * const db = enhance(new DatabaseSync(':memory:'));
+ * // db already had these methods, enhance() just returns it unchanged
+ * ```
+ */
+export function enhance<T extends EnhanceableDatabaseSync>(
+  db: T,
+): EnhancedDatabaseSync<T> {
+  // If already enhanced, return as-is
+  if (hasEnhancedMethods(db)) {
+    return db;
+  }
+
+  // Add methods directly to the instance
+  // 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,
+  });
+
+  return db 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,22 @@ 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,
+} from "./enhance";
+
 // Use _dirname() helper that works in both CJS/ESM and Jest
 const binding = nodeGypBuild(join(_dirname(), ".."));
 
@@ -52,25 +66,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 +176,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 +203,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 +223,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.

package/src/shims/node_errors.h

@@ -11,25 +11,33 @@ namespace node {
 inline void THROW_ERR_INVALID_STATE(Napi::Env env,
                                     const char *message = nullptr) {
   const char *msg = message ? message : "Invalid state";
-  Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+  Napi::Error error = Napi::Error::New(env, msg);
+  error.Set("code", Napi::String::New(env, "ERR_INVALID_STATE"));
+  error.ThrowAsJavaScriptException();
 }
 
 inline void THROW_ERR_INVALID_ARG_TYPE(Napi::Env env,
                                        const char *message = nullptr) {
   const char *msg = message ? message : "Invalid argument type";
-  Napi::TypeError::New(env, msg).ThrowAsJavaScriptException();
+  Napi::TypeError error = Napi::TypeError::New(env, msg);
+  error.Set("code", Napi::String::New(env, "ERR_INVALID_ARG_TYPE"));
+  error.ThrowAsJavaScriptException();
 }
 
 inline void THROW_ERR_OUT_OF_RANGE(Napi::Env env,
                                    const char *message = nullptr) {
   const char *msg = message ? message : "Value out of range";
-  Napi::RangeError::New(env, msg).ThrowAsJavaScriptException();
+  Napi::RangeError error = Napi::RangeError::New(env, msg);
+  error.Set("code", Napi::String::New(env, "ERR_OUT_OF_RANGE"));
+  error.ThrowAsJavaScriptException();
 }
 
 inline void THROW_ERR_INVALID_ARG_VALUE(Napi::Env env,
                                         const char *message = nullptr) {
   const char *msg = message ? message : "Invalid argument value";
-  Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+  Napi::Error error = Napi::Error::New(env, msg);
+  error.Set("code", Napi::String::New(env, "ERR_INVALID_ARG_VALUE"));
+  error.ThrowAsJavaScriptException();
 }
 
 inline void THROW_ERR_SQLITE_ERROR(Napi::Env env,
@@ -37,7 +45,9 @@ inline void THROW_ERR_SQLITE_ERROR(Napi::Env env,
   // Check for both null and empty string - on Windows (MSVC),
   // std::exception::what() can sometimes return an empty string
   const char *msg = (message && message[0] != '\0') ? message : "SQLite error";
-  Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+  Napi::Error error = Napi::Error::New(env, msg);
+  error.Set("code", Napi::String::New(env, "ERR_SQLITE_ERROR"));
+  error.ThrowAsJavaScriptException();
 }
 
 // Database-aware version available when sqlite_impl.h is included
@@ -45,24 +55,33 @@ inline void THROW_ERR_SQLITE_ERROR(Napi::Env env,
 // issues
 
 inline void THROW_ERR_CONSTRUCT_CALL_REQUIRED(Napi::Env env) {
-  Napi::TypeError::New(env, "Class constructor cannot be invoked without 'new'")
-      .ThrowAsJavaScriptException();
+  Napi::TypeError error = Napi::TypeError::New(
+      env, "Class constructor cannot be invoked without 'new'");
+  error.Set("code", Napi::String::New(env, "ERR_CONSTRUCT_CALL_REQUIRED"));
+  error.ThrowAsJavaScriptException();
+}
+
+inline void THROW_ERR_ILLEGAL_CONSTRUCTOR(Napi::Env env) {
+  Napi::TypeError error = Napi::TypeError::New(env, "Illegal constructor");
+  error.Set("code", Napi::String::New(env, "ERR_ILLEGAL_CONSTRUCTOR"));
+  error.ThrowAsJavaScriptException();
 }
 
 inline void THROW_ERR_INVALID_URL_SCHEME(Napi::Env env,
-                                         const char *scheme = nullptr) {
-  std::string msg = "Invalid URL scheme";
-  if (scheme) {
-    msg += ": ";
-    msg += scheme;
-  }
-  Napi::TypeError::New(env, msg).ThrowAsJavaScriptException();
+                                         const char * /*scheme*/ = nullptr) {
+  // Message must match Node.js exactly
+  Napi::TypeError error =
+      Napi::TypeError::New(env, "The URL must be of scheme file:");
+  error.Set("code", Napi::String::New(env, "ERR_INVALID_URL_SCHEME"));
+  error.ThrowAsJavaScriptException();
 }
 
 inline void THROW_ERR_LOAD_SQLITE_EXTENSION(Napi::Env env,
                                             const char *message = nullptr) {
   const char *msg = message ? message : "Failed to load SQLite extension";
-  Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+  Napi::Error error = Napi::Error::New(env, msg);
+  error.Set("code", Napi::String::New(env, "ERR_LOAD_SQLITE_EXTENSION"));
+  error.ThrowAsJavaScriptException();
 }
 
 // Macro wrappers for compatibility (removed to avoid conflicts)

package/src/shims/sqlite_errors.h

@@ -81,6 +81,14 @@ inline const char *GetSqliteErrorCodeName(int code) {
 }
 
 // Enhanced SQLite error that includes system errno information
+// Error format matches Node.js node:sqlite for API compatibility:
+// - code: 'ERR_SQLITE_ERROR' (constant, matches Node.js)
+// - errcode: number (SQLite error code, matches Node.js)
+// - errstr: string (SQLite error string, matches Node.js)
+// We also add extra properties for enhanced debugging:
+// - sqliteCode: number (same as errcode, for backward compat)
+// - sqliteExtendedCode: number (extended SQLite error code)
+// - sqliteErrorString: string (same as errstr, for backward compat)
 inline void ThrowEnhancedSqliteError(Napi::Env env, sqlite3 *db,
                                      int sqlite_code,
                                      const std::string &message) {
@@ -89,7 +97,16 @@ inline void ThrowEnhancedSqliteError(Napi::Env env, sqlite3 *db,
   // truncated or corrupted error messages
   Napi::Error error = Napi::Error::New(env, message.c_str());
 
-  // Add SQLite error code information
+  // Node.js compatible properties
+  error.Set("code", Napi::String::New(env, "ERR_SQLITE_ERROR"));
+  error.Set("errcode", Napi::Number::New(env, sqlite_code));
+
+  const char *err_str = sqlite3_errstr(sqlite_code);
+  if (err_str) {
+    error.Set("errstr", Napi::String::New(env, err_str));
+  }
+
+  // Our enhanced properties (for backward compatibility and debugging)
   error.Set("sqliteCode", Napi::Number::New(env, sqlite_code));
 
   if (db) {
@@ -104,12 +121,11 @@ inline void ThrowEnhancedSqliteError(Napi::Env env, sqlite3 *db,
     }
   }
 
-  // Set a standard error code property for compatibility
+  // Keep original code name as sqliteCodeName for debugging
   const char *code_name = GetSqliteErrorCodeName(sqlite_code);
-  error.Set("code", Napi::String::New(env, code_name));
+  error.Set("sqliteCodeName", Napi::String::New(env, code_name));
 
   // Also set the human-readable error string
-  const char *err_str = sqlite3_errstr(sqlite_code);
   if (err_str) {
     error.Set("sqliteErrorString", Napi::String::New(env, err_str));
   }
@@ -126,7 +142,9 @@ inline void ThrowEnhancedSqliteError(Napi::Env env, sqlite3 *db,
 inline void ThrowSqliteError(Napi::Env env, sqlite3 *db,
                              const std::string &message) {
   if (db) {
-    int errcode = sqlite3_errcode(db);
+    // Use extended error code (e.g., 1555 for SQLITE_CONSTRAINT_PRIMARYKEY)
+    // instead of basic code (e.g., 19 for SQLITE_CONSTRAINT) to match Node.js
+    int errcode = sqlite3_extended_errcode(db);
     ThrowEnhancedSqliteError(env, db, errcode, message);
   } else {
     // Fallback to simple error when no db handle available
@@ -136,12 +154,20 @@ inline void ThrowSqliteError(Napi::Env env, sqlite3 *db,
 }
 
 // Helper to throw from a SqliteException with captured error info
+// Uses same format as ThrowEnhancedSqliteError for consistency
 inline void
 ThrowFromSqliteException(Napi::Env env,
                          const photostructure::sqlite::SqliteException &ex) {
   Napi::Error error = Napi::Error::New(env, ex.what());
 
-  // Add all captured error information
+  // Node.js compatible properties
+  error.Set("code", Napi::String::New(env, "ERR_SQLITE_ERROR"));
+  error.Set("errcode", Napi::Number::New(env, ex.sqlite_code()));
+  if (!ex.error_string().empty()) {
+    error.Set("errstr", Napi::String::New(env, ex.error_string().c_str()));
+  }
+
+  // Our enhanced properties (for backward compatibility and debugging)
   error.Set("sqliteCode", Napi::Number::New(env, ex.sqlite_code()));
   error.Set("sqliteExtendedCode", Napi::Number::New(env, ex.extended_code()));
 
@@ -149,9 +175,9 @@ ThrowFromSqliteException(Napi::Env env,
     error.Set("systemErrno", Napi::Number::New(env, ex.system_errno()));
   }
 
-  // Set the error code name
+  // Keep original code name as sqliteCodeName for debugging
   const char *code_name = GetSqliteErrorCodeName(ex.sqlite_code());
-  error.Set("code", Napi::String::New(env, code_name));
+  error.Set("sqliteCodeName", Napi::String::New(env, code_name));
 
   // Also set the human-readable error string
   // Use c_str() explicitly to avoid potential ABI issues on Windows ARM

package/src/sql-tag-store.ts

@@ -25,7 +25,9 @@ export class SQLTagStore {
 
   constructor(db: DatabaseSyncInstance, capacity: number = DEFAULT_CAPACITY) {
     if (!db.isOpen) {
-      throw new Error("Database is not open");
+      const err = new Error("database is not open");
+      (err as NodeJS.ErrnoException).code = "ERR_INVALID_STATE";
+      throw err;
     }
     this.database = db;
     this.maxCapacity = capacity;
@@ -101,23 +103,18 @@ export class SQLTagStore {
 
   /**
    * 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.
    */
   private getOrPrepare(strings: TemplateStringsArray): StatementSyncInstance {
     if (!this.database.isOpen) {
-      throw new Error("Database is not open");
+      throw new Error("database is not open");
     }
 
     const sql = this.buildSQL(strings);
 
-    // Check cache - evict if finalized
+    // Check cache
     const cached = this.cache.get(sql);
     if (cached) {
-      if (!cached.finalized) {
-        return cached;
-      }
-      // Statement was finalized externally - remove from cache
-      this.cache.delete(sql);
+      return cached;
     }
 
     // Prepare new statement and cache it