sqlite: add StatementSync.prototype[Symbol.dispose]()

This extends explicit resource management support to prepared
statements, allowing a StatementSync to be deterministically
finalized via a `using` declaration, mirroring the existing
DatabaseSync and Session dispose methods.

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
PR-URL: #64232
Backport-PR-URL: #66128
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: araujogui

doc/api/sqlite.md

@@ -1279,6 +1279,15 @@ added: v22.5.0
 The source SQL text of the prepared statement. This property is a
 wrapper around [`sqlite3_sql()`][].
 
+### `statement[Symbol.dispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Finalizes the prepared statement. If the prepared statement is already
+finalized, then this is a no-op.
+
 ## Class: `SQLTagStore`
 
 <!-- YAML

src/node_sqlite.cc

@@ -1058,10 +1058,7 @@ void DatabaseSync::FinalizeStatements() {
 }
 
 void DatabaseSync::UntrackStatement(StatementSync* statement) {
-  auto it = statements_.find(statement);
-  if (it != statements_.end()) {
-    statements_.erase(it);
-  }
+  statements_.erase(statement);
 }
 
 inline bool DatabaseSync::IsOpen() {
@@ -2669,6 +2666,10 @@ StatementSync::StatementSync(Environment* env,
 }
 
 StatementSync::~StatementSync() {
+  Close();
+}
+
+void StatementSync::Close() {
   if (!IsFinalized()) {
     db_->UntrackStatement(this);
     Finalize();
@@ -2689,6 +2690,12 @@ inline bool StatementSync::IsFinalized() {
   return statement_ == nullptr;
 }
 
+void StatementSync::Close(const FunctionCallbackInfo<Value>& args) {
+  StatementSync* stmt;
+  ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
+  stmt->Close();
+}
+
 inline int StatementSync::ResetStatement() {
   reset_generation_++;
   return sqlite3_reset(statement_);
@@ -3727,6 +3734,7 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
         isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
     SetProtoMethod(
         isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
+    SetProtoDispose(isolate, tmpl, StatementSync::Close);
     env->set_sqlite_statement_sync_constructor_template(tmpl);
   }
   return tmpl;

src/node_sqlite.h

@@ -284,6 +284,7 @@ class StatementSync : public BaseObject {
       const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void Close(const v8::FunctionCallbackInfo<v8::Value>& args);
   v8::MaybeLocal<v8::Value> ColumnToValue(const int column);
   v8::MaybeLocal<v8::Name> ColumnNameToName(const int column);
   bool GetCachedColumnNames(v8::LocalVector<v8::Name>* keys);
@@ -295,6 +296,7 @@ class StatementSync : public BaseObject {
 
  private:
   ~StatementSync() override;
+  void Close();
   BaseObjectPtr<DatabaseSync> db_;
   sqlite3_stmt* statement_;
   bool return_arrays_ = false;

test/parallel/test-sqlite-statement-sync.js

@@ -969,3 +969,46 @@ suite('options.allowBareNamedParameters', () => {
     );
   });
 });
+
+
+suite('StatementSync.prototype[Symbol.dispose]()', () => {
+  test('finalizes an open statement', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+    const stmt = db.prepare('SELECT * FROM storage');
+    stmt[Symbol.dispose]();
+    t.assert.throws(() => stmt.get(), {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
+
+  test('does not throw on an already-finalized statement', () => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt[Symbol.dispose]();
+    stmt[Symbol.dispose]();
+  });
+
+  test('works with a using declaration', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+    let captured;
+    {
+      using stmt = db.prepare('SELECT * FROM storage');
+      captured = stmt;
+      t.assert.deepStrictEqual(stmt.all(), []);
+    }
+    t.assert.throws(() => captured.get(), {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
+
+  test('closing the database after dispose does not double-finalize', () => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt[Symbol.dispose]();
+    db.close();
+  });
+});