@photostructure/sqlite 0.5.0 → 1.0.0

package/src/index.ts

@@ -3,7 +3,10 @@ import nodeGypBuild from "node-gyp-build";
 import { join } from "node:path";
 import { _dirname } from "./dirname";
 import { SQLTagStore } from "./sql-tag-store";
-import { DatabaseSyncInstance } from "./types/database-sync-instance";
+import {
+  DatabaseSyncInstance,
+  DatabaseSyncLimits,
+} from "./types/database-sync-instance";
 import { DatabaseSyncOptions } from "./types/database-sync-options";
 import { SQLTagStoreInstance } from "./types/sql-tag-store-instance";
 import { SqliteAuthorizationActions } from "./types/sqlite-authorization-actions";
@@ -15,7 +18,10 @@ import { StatementSyncInstance } from "./types/statement-sync-instance";
 
 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 {
+  DatabaseSyncInstance,
+  DatabaseSyncLimits,
+} 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";
@@ -204,6 +210,82 @@ DatabaseSync.prototype = _DatabaseSync.prototype;
   return new SQLTagStore(this, capacity);
 };
 
+// Limit name to SQLite limit ID mapping (matches upstream kLimitMapping order)
+const LIMIT_MAPPING: ReadonlyArray<{
+  name: keyof DatabaseSyncLimits;
+  id: number;
+}> = [
+  { name: "length", id: 0 },
+  { name: "sqlLength", id: 1 },
+  { name: "column", id: 2 },
+  { name: "exprDepth", id: 3 },
+  { name: "compoundSelect", id: 4 },
+  { name: "vdbeOp", id: 5 },
+  { name: "functionArg", id: 6 },
+  { name: "attach", id: 7 },
+  { name: "likePatternLength", id: 8 },
+  { name: "variableNumber", id: 9 },
+  { name: "triggerDepth", id: 10 },
+];
+
+const INT_MAX = 2147483647;
+
+// WeakMap to cache limits objects per database instance
+const limitsCache = new WeakMap<DatabaseSyncInstance, DatabaseSyncLimits>();
+
+function validateLimitValue(value: unknown): number {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new TypeError(
+      "Limit value must be a non-negative integer or Infinity.",
+    );
+  }
+  if (value === Infinity) {
+    return INT_MAX;
+  }
+  if (!Number.isFinite(value) || value !== Math.trunc(value)) {
+    throw new TypeError(
+      "Limit value must be a non-negative integer or Infinity.",
+    );
+  }
+  if (value < 0) {
+    throw new RangeError("Limit value must be non-negative.");
+  }
+  return value;
+}
+
+function createLimitsObject(db: DatabaseSyncInstance): DatabaseSyncLimits {
+  const obj = Object.create(null) as DatabaseSyncLimits;
+  for (const { name, id } of LIMIT_MAPPING) {
+    Object.defineProperty(obj, name, {
+      get() {
+        return db.getLimit(id);
+      },
+      set(value: unknown) {
+        const validated = validateLimitValue(value);
+        db.setLimit(id, validated);
+      },
+      enumerable: true,
+      configurable: false,
+    });
+  }
+  return obj;
+}
+
+if (!Object.getOwnPropertyDescriptor(DatabaseSync.prototype, "limits")) {
+  Object.defineProperty(DatabaseSync.prototype, "limits", {
+    get(this: DatabaseSyncInstance) {
+      let obj = limitsCache.get(this);
+      if (obj == null) {
+        obj = createLimitsObject(this);
+        limitsCache.set(this, obj);
+      }
+      return obj;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}
+
 // 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():

package/src/sqlite_impl.cpp

@@ -324,6 +324,8 @@ Napi::Object DatabaseSync::Init(Napi::Env env, Napi::Object exports) {
        InstanceMethod("createSession", &DatabaseSync::CreateSession),
        InstanceMethod("applyChangeset", &DatabaseSync::ApplyChangeset),
        InstanceMethod("setAuthorizer", &DatabaseSync::SetAuthorizer),
+       InstanceMethod("getLimit", &DatabaseSync::GetLimit),
+       InstanceMethod("setLimit", &DatabaseSync::SetLimit),
        InstanceMethod("backup", &DatabaseSync::Backup),
        InstanceMethod("location", &DatabaseSync::LocationMethod),
        InstanceAccessor("isOpen", &DatabaseSync::IsOpenGetter, nullptr),
@@ -561,6 +563,69 @@ DatabaseSync::DatabaseSync(const Napi::CallbackInfo &info)
         }
         config.set_enable_defensive(defensive_val.As<Napi::Boolean>().Value());
       }
+
+      // Validate and parse 'limits' option
+      Napi::Value limits_val = options.Get("limits");
+      if (!limits_val.IsUndefined()) {
+        if (!limits_val.IsObject() || limits_val.IsNull()) {
+          node::THROW_ERR_INVALID_ARG_TYPE(
+              info.Env(), "The \"options.limits\" argument must be an object.");
+          return;
+        }
+
+        Napi::Object limits_obj = limits_val.As<Napi::Object>();
+
+        // Limit name to SQLite limit ID mapping (matches upstream
+        // kLimitMapping)
+        static const struct {
+          const char *name;
+          int id;
+        } kLimitNames[] = {
+            {"length", SQLITE_LIMIT_LENGTH},
+            {"sqlLength", SQLITE_LIMIT_SQL_LENGTH},
+            {"column", SQLITE_LIMIT_COLUMN},
+            {"exprDepth", SQLITE_LIMIT_EXPR_DEPTH},
+            {"compoundSelect", SQLITE_LIMIT_COMPOUND_SELECT},
+            {"vdbeOp", SQLITE_LIMIT_VDBE_OP},
+            {"functionArg", SQLITE_LIMIT_FUNCTION_ARG},
+            {"attach", SQLITE_LIMIT_ATTACHED},
+            {"likePatternLength", SQLITE_LIMIT_LIKE_PATTERN_LENGTH},
+            {"variableNumber", SQLITE_LIMIT_VARIABLE_NUMBER},
+            {"triggerDepth", SQLITE_LIMIT_TRIGGER_DEPTH},
+        };
+
+        for (const auto &limit : kLimitNames) {
+          Napi::Value val = limits_obj.Get(limit.name);
+          if (!val.IsUndefined()) {
+            if (!val.IsNumber()) {
+              std::string msg = std::string("The \"options.limits.") +
+                                limit.name + "\" argument must be an integer.";
+              node::THROW_ERR_INVALID_ARG_TYPE(info.Env(), msg.c_str());
+              return;
+            }
+
+            double dval = val.As<Napi::Number>().DoubleValue();
+            if (dval != std::trunc(dval) || std::isinf(dval) ||
+                std::isnan(dval)) {
+              std::string msg = std::string("The \"options.limits.") +
+                                limit.name + "\" argument must be an integer.";
+              node::THROW_ERR_INVALID_ARG_TYPE(info.Env(), msg.c_str());
+              return;
+            }
+
+            int limit_val = static_cast<int>(dval);
+            if (limit_val < 0) {
+              std::string msg = std::string("The \"options.limits.") +
+                                limit.name +
+                                "\" argument must be non-negative.";
+              node::THROW_ERR_OUT_OF_RANGE(info.Env(), msg.c_str());
+              return;
+            }
+
+            config.set_initial_limit(limit.id, limit_val);
+          }
+        }
+      }
     }
 
     // Store configuration for later use
@@ -1007,6 +1072,14 @@ void DatabaseSync::InternalOpen(DatabaseOpenConfiguration config) {
       throw ex;
     }
   }
+
+  // Apply initial limits from constructor options
+  for (size_t i = 0; i < config_.initial_limits().size(); i++) {
+    if (config_.initial_limits()[i].has_value()) {
+      sqlite3_limit(connection_, static_cast<int>(i),
+                    *config_.initial_limits()[i]);
+    }
+  }
 }
 
 void DatabaseSync::InternalClose() {
@@ -1957,6 +2030,11 @@ StatementSync::~StatementSync() {
   // See: commit 4da0638, nodejs/node-addon-api#660
 }
 
+inline int StatementSync::ResetStatement() {
+  reset_generation_++;
+  return sqlite3_reset(statement_);
+}
+
 Napi::Value StatementSync::Run(const Napi::CallbackInfo &info) {
   Napi::Env env = info.Env();
 
@@ -1994,7 +2072,7 @@ Napi::Value StatementSync::Run(const Napi::CallbackInfo &info) {
     // correct value. This fixes an issue where RETURNING queries would
     // report changes: 0 on the first call.
     // See: https://github.com/nodejs/node/issues/57344
-    int result = sqlite3_reset(statement_);
+    int result = ResetStatement();
 
     if (result != SQLITE_OK) {
       std::string error = sqlite3_errmsg(database_->connection());
@@ -2073,15 +2151,15 @@ Napi::Value StatementSync::Get(const Napi::CallbackInfo &info) {
       Napi::Value value = CreateResult();
       // Reset statement after fetching result to release locks (like Node.js
       // OnScopeLeave)
-      sqlite3_reset(statement_);
+      ResetStatement();
       return value;
     } else if (result == SQLITE_DONE) {
       // Reset statement to release locks even when no rows returned
-      sqlite3_reset(statement_);
+      ResetStatement();
       return env.Undefined();
     } else {
       // Reset statement before throwing to release locks
-      sqlite3_reset(statement_);
+      ResetStatement();
       std::string error = sqlite3_errmsg(database_->connection());
       ThrowEnhancedSqliteErrorWithDB(env, database_, database_->connection(),
                                      result, error);
@@ -2089,7 +2167,7 @@ Napi::Value StatementSync::Get(const Napi::CallbackInfo &info) {
     }
   } catch (const std::exception &e) {
     // Reset statement on exception to release locks
-    sqlite3_reset(statement_);
+    ResetStatement();
     ThrowErrSqliteErrorWithDb(env, database_, e.what());
     return env.Undefined();
   }
@@ -2132,11 +2210,11 @@ Napi::Value StatementSync::All(const Napi::CallbackInfo &info) {
         results.Set(index++, CreateResult());
       } else if (result == SQLITE_DONE) {
         // Reset statement to release locks (like Node.js OnScopeLeave)
-        sqlite3_reset(statement_);
+        ResetStatement();
         break;
       } else {
         // Reset statement before throwing to release locks
-        sqlite3_reset(statement_);
+        ResetStatement();
         std::string error = sqlite3_errmsg(database_->connection());
         node::THROW_ERR_SQLITE_ERROR(env, error.c_str());
         return env.Undefined();
@@ -2146,7 +2224,7 @@ Napi::Value StatementSync::All(const Napi::CallbackInfo &info) {
     return results;
   } catch (const std::exception &e) {
     // Reset statement on exception to release locks
-    sqlite3_reset(statement_);
+    ResetStatement();
     node::THROW_ERR_SQLITE_ERROR(env, e.what());
     return env.Undefined();
   }
@@ -2170,7 +2248,7 @@ Napi::Value StatementSync::Iterate(const Napi::CallbackInfo &info) {
   }
 
   // Reset the statement first
-  int r = sqlite3_reset(statement_);
+  int r = ResetStatement();
   if (r != SQLITE_OK) {
     node::THROW_ERR_SQLITE_ERROR(info.Env(),
                                  sqlite3_errmsg(database_->connection()));
@@ -2839,7 +2917,7 @@ void StatementSync::Reset() {
     return; // Silent return, error should have been caught earlier
   }
 
-  sqlite3_reset(statement_);
+  ResetStatement();
   sqlite3_clear_bindings(statement_);
 }
 
@@ -2912,6 +2990,7 @@ StatementSyncIterator::~StatementSyncIterator() {}
 void StatementSyncIterator::SetStatement(StatementSync *stmt) {
   stmt_ = stmt;
   done_ = false;
+  statement_reset_generation_ = stmt->reset_generation_;
 }
 
 Napi::Value StatementSyncIterator::Next(const Napi::CallbackInfo &info) {
@@ -2927,6 +3006,11 @@ Napi::Value StatementSyncIterator::Next(const Napi::CallbackInfo &info) {
     return env.Undefined();
   }
 
+  if (statement_reset_generation_ != stmt_->reset_generation_) {
+    node::THROW_ERR_INVALID_STATE(env, "iterator was invalidated");
+    return env.Undefined();
+  }
+
   if (done_) {
     Napi::Object result = CreateObjectWithNullPrototype(env);
     result.Set("done", true);
@@ -3675,6 +3759,45 @@ int DatabaseSync::AuthorizerCallback(void *user_data, int action_code,
   }
 }
 
+Napi::Value DatabaseSync::GetLimit(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  if (!IsOpen()) {
+    node::THROW_ERR_INVALID_STATE(env, "database is not open");
+    return env.Undefined();
+  }
+
+  if (info.Length() < 1 || !info[0].IsNumber()) {
+    node::THROW_ERR_INVALID_ARG_TYPE(env,
+                                     "The limit ID argument must be a number.");
+    return env.Undefined();
+  }
+
+  int limit_id = info[0].As<Napi::Number>().Int32Value();
+  int current_value = sqlite3_limit(connection_, limit_id, -1);
+  return Napi::Number::New(env, current_value);
+}
+
+Napi::Value DatabaseSync::SetLimit(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  if (!IsOpen()) {
+    node::THROW_ERR_INVALID_STATE(env, "database is not open");
+    return env.Undefined();
+  }
+
+  if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber()) {
+    node::THROW_ERR_INVALID_ARG_TYPE(
+        env, "The limit ID and value arguments must be numbers.");
+    return env.Undefined();
+  }
+
+  int limit_id = info[0].As<Napi::Number>().Int32Value();
+  int new_value = info[1].As<Napi::Number>().Int32Value();
+  int old_value = sqlite3_limit(connection_, limit_id, new_value);
+  return Napi::Number::New(env, old_value);
+}
+
 // Thread validation implementations
 bool DatabaseSync::ValidateThread(Napi::Env env) const {
   if (std::this_thread::get_id() != creation_thread_) {

package/src/sqlite_impl.h

@@ -4,6 +4,7 @@
 #include <napi.h>
 #include <sqlite3.h>
 
+#include <array>
 #include <atomic>
 #include <climits>
 #include <map>
@@ -119,6 +120,14 @@ public:
   bool get_open_uri() const { return open_uri_; }
   void set_open_uri(bool flag) { open_uri_ = flag; }
 
+  static constexpr size_t kNumLimits = 11;
+  void set_initial_limit(int sqlite_limit_id, int value) {
+    initial_limits_.at(sqlite_limit_id) = value;
+  }
+  const std::array<std::optional<int>, kNumLimits> &initial_limits() const {
+    return initial_limits_;
+  }
+
 private:
   std::string location_;
   bool read_only_ = false;
@@ -131,6 +140,7 @@ private:
   bool allow_unknown_named_params_ = false;
   bool defensive_ = true; // Node.js v25+ defaults to true
   bool open_uri_ = false;
+  std::array<std::optional<int>, kNumLimits> initial_limits_{};
 };
 
 // Main database class
@@ -179,6 +189,10 @@ public:
   // Backup support
   Napi::Value Backup(const Napi::CallbackInfo &info);
 
+  // Limits API
+  Napi::Value GetLimit(const Napi::CallbackInfo &info);
+  Napi::Value SetLimit(const Napi::CallbackInfo &info);
+
   // Authorization API
   Napi::Value SetAuthorizer(const Napi::CallbackInfo &info);
 
@@ -311,6 +325,10 @@ private:
   // Bare named parameters mapping (bare name -> full name with prefix)
   std::optional<std::map<std::string, std::string>> bare_named_params_;
 
+  // Generation counter for iterator invalidation
+  uint64_t reset_generation_ = 0;
+  inline int ResetStatement();
+
   bool ValidateThread(Napi::Env env) const;
   friend class DatabaseSync;
   friend class StatementSyncIterator;
@@ -335,6 +353,7 @@ private:
 
   StatementSync *stmt_;
   bool done_;
+  uint64_t statement_reset_generation_ = 0;
 };
 
 // Session class for SQLite changesets

package/src/types/database-sync-instance.ts

@@ -164,6 +164,49 @@ export interface DatabaseSyncInstance {
       | null,
   ): void;
 
+  /**
+   * An object with getters and setters for each SQLite limit.
+   * Setting a property changes the limit immediately.
+   * Setting a property to `Infinity` resets the limit to its compile-time maximum.
+   * @see https://sqlite.org/c3ref/limit.html
+   */
+  readonly limits: DatabaseSyncLimits;
+
+  /** @internal Native method to get a SQLite limit by ID. */
+  getLimit(limitId: number): number;
+  /** @internal Native method to set a SQLite limit by ID. Returns old value. */
+  setLimit(limitId: number, value: number): number;
+
   /** Dispose of the database resources using the explicit resource management protocol. */
   [Symbol.dispose](): void;
 }
+
+/**
+ * Represents the configurable SQLite limits for a database connection.
+ * Each property corresponds to a SQLite limit constant.
+ * @see https://sqlite.org/c3ref/limit.html
+ */
+export interface DatabaseSyncLimits {
+  /** Maximum length of any string or BLOB or table row, in bytes. */
+  length: number;
+  /** Maximum length of an SQL statement, in bytes. */
+  sqlLength: number;
+  /** Maximum number of columns in a table, result set, or index. */
+  column: number;
+  /** Maximum depth of the parse tree on any expression. */
+  exprDepth: number;
+  /** Maximum number of terms in a compound SELECT statement. */
+  compoundSelect: number;
+  /** Maximum number of instructions in a virtual machine program. */
+  vdbeOp: number;
+  /** Maximum number of arguments on a function. */
+  functionArg: number;
+  /** Maximum number of attached databases. */
+  attach: number;
+  /** Maximum length of the pattern argument to the LIKE or GLOB operators. */
+  likePatternLength: number;
+  /** Maximum index number of any parameter in an SQL statement. */
+  variableNumber: number;
+  /** Maximum depth of recursion for triggers. */
+  triggerDepth: number;
+}

package/src/types/database-sync-options.ts

@@ -66,4 +66,23 @@ export interface DatabaseSyncOptions {
    * @default true
    */
   readonly open?: boolean;
+  /**
+   * An object specifying initial SQLite limits to set when opening the database.
+   * Each property corresponds to a SQLite limit constant. Only integer values are
+   * accepted (no Infinity). Omitted properties retain their default values.
+   * @see https://sqlite.org/c3ref/limit.html
+   */
+  readonly limits?: {
+    readonly length?: number;
+    readonly sqlLength?: number;
+    readonly column?: number;
+    readonly exprDepth?: number;
+    readonly compoundSelect?: number;
+    readonly vdbeOp?: number;
+    readonly functionArg?: number;
+    readonly attach?: number;
+    readonly likePatternLength?: number;
+    readonly variableNumber?: number;
+    readonly triggerDepth?: number;
+  };
 }