feat(sqlite): add StatementSync.prototype.iterate method

doc/api/sqlite.md

@@ -287,6 +287,25 @@ object. If the prepared statement does not return any results, this method
 returns `undefined`. The prepared statement [parameters are bound][] using the
 values in `namedParameters` and `anonymousParameters`.
 
+### `statement.iterate([namedParameters][, ...anonymousParameters])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `namedParameters` {Object} An optional object used to bind named parameters.
+  The keys of this object are used to configure the mapping.
+* `...anonymousParameters` {null|number|bigint|string|Buffer|Uint8Array} Zero or
+  more values to bind to anonymous parameters.
+* Returns: {Iterator} An iterable iterator of objects. Each object corresponds to a row
+  returned by executing the prepared statement. The keys and values of each
+  object correspond to the column names and values of the row.
+
+This method executes a prepared statement and returns an iterator of
+objects. If the prepared statement does not return any results, this method
+returns an empty iterator. The prepared statement [parameters are bound][] using
+the values in `namedParameters` and `anonymousParameters`.
+
 ### `statement.run([namedParameters][, ...anonymousParameters])`
 
 <!-- YAML

src/env_properties.h

@@ -194,8 +194,10 @@
   V(ipv4_string, "IPv4")                                                       \
   V(ipv6_string, "IPv6")                                                       \
   V(isclosing_string, "isClosing")                                             \
+  V(isfinished_string, "isFinished")                                           \
   V(issuer_string, "issuer")                                                   \
   V(issuercert_string, "issuerCertificate")                                    \
+  V(iterator_string, "Iterator")                                               \
   V(jwk_crv_string, "crv")                                                     \
   V(jwk_d_string, "d")                                                         \
   V(jwk_dp_string, "dp")                                                       \
@@ -241,6 +243,7 @@
   V(nistcurve_string, "nistCurve")                                             \
   V(node_string, "node")                                                       \
   V(nsname_string, "nsname")                                                   \
+  V(num_cols_string, "num_cols")                                               \
   V(object_string, "Object")                                                   \
   V(ocsp_request_string, "OCSPRequest")                                        \
   V(oncertcb_string, "oncertcb")                                               \
@@ -288,6 +291,7 @@
   V(priority_string, "priority")                                               \
   V(process_string, "process")                                                 \
   V(promise_string, "promise")                                                 \
+  V(prototype_string, "prototype")                                             \
   V(psk_string, "psk")                                                         \
   V(pubkey_string, "pubkey")                                                   \
   V(public_exponent_string, "publicExponent")                                  \
@@ -309,6 +313,7 @@
   V(require_string, "require")                                                 \
   V(resource_string, "resource")                                               \
   V(retry_string, "retry")                                                     \
+  V(return_string, "return")                                                   \
   V(salt_length_string, "saltLength")                                          \
   V(scheme_string, "scheme")                                                   \
   V(scopeid_string, "scopeid")                                                 \
@@ -332,6 +337,7 @@
   V(standard_name_string, "standardName")                                      \
   V(start_time_string, "startTime")                                            \
   V(state_string, "state")                                                     \
+  V(statement_string, "statement")                                             \
   V(stats_string, "stats")                                                     \
   V(status_string, "status")                                                   \
   V(stdio_string, "stdio")                                                     \

src/node_sqlite.cc

@@ -22,6 +22,7 @@ using v8::ConstructorBehavior;
 using v8::Context;
 using v8::DontDelete;
 using v8::Exception;
+using v8::External;
 using v8::Function;
 using v8::FunctionCallback;
 using v8::FunctionCallbackInfo;
@@ -790,6 +791,180 @@ void StatementSync::All(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(Array::New(isolate, rows.data(), rows.size()));
 }
 
+void StatementSync::IterateReturnCallback(
+    const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  auto isolate = env->isolate();
+  auto context = isolate->GetCurrentContext();
+
+  auto self = args.This();
+  // iterator has fetch all result or break, prevent next func to return result
+  self->Set(context, env->isfinished_string(), Boolean::New(isolate, true))
+      .ToChecked();
+
+  auto external_stmt = Local<External>::Cast(
+      self->Get(context, env->statement_string()).ToLocalChecked());
+  auto stmt = static_cast<StatementSync*>(external_stmt->Value());
+  if (!stmt->IsFinalized()) {
+    sqlite3_reset(stmt->statement_);
+  }
+
+  LocalVector<Name> keys(isolate, {env->done_string(), env->value_string()});
+  LocalVector<Value> values(isolate,
+                            {Boolean::New(isolate, true), Null(isolate)});
+
+  DCHECK_EQ(keys.size(), values.size());
+  Local<Object> result = Object::New(
+      isolate, Null(isolate), keys.data(), values.data(), keys.size());
+  args.GetReturnValue().Set(result);
+}
+
+void StatementSync::IterateNextCallback(
+    const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  auto isolate = env->isolate();
+  auto context = isolate->GetCurrentContext();
+
+  auto self = args.This();
+
+  // skip iteration if is_finished
+  auto is_finished = Local<Boolean>::Cast(
+      self->Get(context, env->isfinished_string()).ToLocalChecked());
+  if (is_finished->Value()) {
+    LocalVector<Name> keys(isolate, {env->done_string(), env->value_string()});
+    LocalVector<Value> values(isolate,
+                              {Boolean::New(isolate, true), Null(isolate)});
+
+    DCHECK_EQ(keys.size(), values.size());
+    Local<Object> result = Object::New(
+        isolate, Null(isolate), keys.data(), values.data(), keys.size());
+    args.GetReturnValue().Set(result);
+    return;
+  }
+
+  auto external_stmt = Local<External>::Cast(
+      self->Get(context, env->statement_string()).ToLocalChecked());
+  auto stmt = static_cast<StatementSync*>(external_stmt->Value());
+  auto num_cols =
+      Local<Integer>::Cast(
+          self->Get(context, env->num_cols_string()).ToLocalChecked())
+          ->Value();
+
+  THROW_AND_RETURN_ON_BAD_STATE(
+      env, stmt->IsFinalized(), "statement has been finalized");
+
+  int r = sqlite3_step(stmt->statement_);
+  if (r != SQLITE_ROW) {
+    CHECK_ERROR_OR_THROW(
+        env->isolate(), stmt->db_->Connection(), r, SQLITE_DONE, void());
+
+    // cleanup when no more rows to fetch
+    sqlite3_reset(stmt->statement_);
+    self->Set(context, env->isfinished_string(), Boolean::New(isolate, true))
+        .ToChecked();
+
+    LocalVector<Name> keys(isolate, {env->done_string(), env->value_string()});
+    LocalVector<Value> values(isolate,
+                              {Boolean::New(isolate, true), Null(isolate)});
+
+    DCHECK_EQ(keys.size(), values.size());
+    Local<Object> result = Object::New(
+        isolate, Null(isolate), keys.data(), values.data(), keys.size());
+    args.GetReturnValue().Set(result);
+    return;
+  }
+
+  LocalVector<Name> row_keys(isolate);
+  row_keys.reserve(num_cols);
+  LocalVector<Value> row_values(isolate);
+  row_values.reserve(num_cols);
+  for (int i = 0; i < num_cols; ++i) {
+    Local<Name> key;
+    if (!stmt->ColumnNameToName(i).ToLocal(&key)) return;
+    Local<Value> val;
+    if (!stmt->ColumnToValue(i).ToLocal(&val)) return;
+    row_keys.emplace_back(key);
+    row_values.emplace_back(val);
+  }
+
+  Local<Object> row = Object::New(
+      isolate, Null(isolate), row_keys.data(), row_values.data(), num_cols);
+
+  LocalVector<Name> keys(isolate, {env->done_string(), env->value_string()});
+  LocalVector<Value> values(isolate, {Boolean::New(isolate, false), row});
+
+  DCHECK_EQ(keys.size(), values.size());
+  Local<Object> result = Object::New(
+      isolate, Null(isolate), keys.data(), values.data(), keys.size());
+  args.GetReturnValue().Set(result);
+}
+
+void StatementSync::Iterate(const FunctionCallbackInfo<Value>& args) {
+  StatementSync* stmt;
+  ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
+  Environment* env = Environment::GetCurrent(args);
+  THROW_AND_RETURN_ON_BAD_STATE(
+      env, stmt->IsFinalized(), "statement has been finalized");
+  auto isolate = env->isolate();
+  auto context = env->context();
+  int r = sqlite3_reset(stmt->statement_);
+  CHECK_ERROR_OR_THROW(
+      env->isolate(), stmt->db_->Connection(), r, SQLITE_OK, void());
+
+  if (!stmt->BindParams(args)) {
+    return;
+  }
+
+  Local<Function> next_func =
+      Function::New(context, StatementSync::IterateNextCallback)
+          .ToLocalChecked();
+  Local<Function> return_func =
+      Function::New(context, StatementSync::IterateReturnCallback)
+          .ToLocalChecked();
+
+  LocalVector<Name> keys(isolate, {env->next_string(), env->return_string()});
+  LocalVector<Value> values(isolate, {next_func, return_func});
+
+  Local<Object> global = context->Global();
+  Local<Value> js_iterator;
+  Local<Value> js_iterator_prototype;
+  if (!global->Get(context, env->iterator_string()).ToLocal(&js_iterator))
+    return;
+  if (!js_iterator.As<Object>()
+           ->Get(context, env->prototype_string())
+           .ToLocal(&js_iterator_prototype))
+    return;
+
+  DCHECK_EQ(keys.size(), values.size());
+  Local<Object> iterable_iterator = Object::New(
+      isolate, js_iterator_prototype, keys.data(), values.data(), keys.size());
+
+  auto num_cols_pd = v8::PropertyDescriptor(
+      v8::Integer::New(isolate, sqlite3_column_count(stmt->statement_)), false);
+  num_cols_pd.set_enumerable(false);
+  num_cols_pd.set_configurable(false);
+  iterable_iterator
+      ->DefineProperty(context, env->num_cols_string(), num_cols_pd)
+      .ToChecked();
+
+  auto stmt_pd =
+      v8::PropertyDescriptor(v8::External::New(isolate, stmt), false);
+  stmt_pd.set_enumerable(false);
+  stmt_pd.set_configurable(false);
+  iterable_iterator->DefineProperty(context, env->statement_string(), stmt_pd)
+      .ToChecked();
+
+  auto is_finished_pd =
+      v8::PropertyDescriptor(v8::Boolean::New(isolate, false), true);
+  stmt_pd.set_enumerable(false);
+  stmt_pd.set_configurable(false);
+  iterable_iterator
+      ->DefineProperty(context, env->isfinished_string(), is_finished_pd)
+      .ToChecked();
+
+  args.GetReturnValue().Set(iterable_iterator);
+}
+
 void StatementSync::Get(const FunctionCallbackInfo<Value>& args) {
   StatementSync* stmt;
   ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
@@ -987,6 +1162,7 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
     tmpl->SetClassName(FIXED_ONE_BYTE_STRING(isolate, "StatementSync"));
     tmpl->InstanceTemplate()->SetInternalFieldCount(
         StatementSync::kInternalFieldCount);
+    SetProtoMethod(isolate, tmpl, "iterate", StatementSync::Iterate);
     SetProtoMethod(isolate, tmpl, "all", StatementSync::All);
     SetProtoMethod(isolate, tmpl, "get", StatementSync::Get);
     SetProtoMethod(isolate, tmpl, "run", StatementSync::Run);

src/node_sqlite.h

@@ -93,6 +93,7 @@ class StatementSync : public BaseObject {
                                              DatabaseSync* db,
                                              sqlite3_stmt* stmt);
   static void All(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void Iterate(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void Get(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void Run(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SourceSQLGetter(const v8::FunctionCallbackInfo<v8::Value>& args);
@@ -118,6 +119,11 @@ class StatementSync : public BaseObject {
   bool BindValue(const v8::Local<v8::Value>& value, const int index);
   v8::MaybeLocal<v8::Value> ColumnToValue(const int column);
   v8::MaybeLocal<v8::Name> ColumnNameToName(const int column);
+
+  static void IterateNextCallback(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void IterateReturnCallback(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
 };
 
 using Sqlite3ChangesetGenFunc = int (*)(sqlite3_session*, int*, void**);

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

@@ -84,6 +84,34 @@ suite('StatementSync.prototype.all()', () => {
   });
 });
 
+suite('StatementSync.prototype.iterate()', () => {
+  test('executes a query and returns an empty iterator on no results', (t) => {
+    const db = new DatabaseSync(nextDb());
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    t.assert.deepStrictEqual(stmt.iterate().toArray(), []);
+  });
+
+  test('executes a query and returns all results', (t) => {
+    const db = new DatabaseSync(nextDb());
+    let stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    t.assert.deepStrictEqual(stmt.run(), { changes: 0, lastInsertRowid: 0 });
+    stmt = db.prepare('INSERT INTO storage (key, val) VALUES (?, ?)');
+    t.assert.deepStrictEqual(
+      stmt.run('key1', 'val1'),
+      { changes: 1, lastInsertRowid: 1 },
+    );
+    t.assert.deepStrictEqual(
+      stmt.run('key2', 'val2'),
+      { changes: 1, lastInsertRowid: 2 },
+    );
+    stmt = db.prepare('SELECT * FROM storage ORDER BY key');
+    t.assert.deepStrictEqual(stmt.iterate().toArray(), [
+      { __proto__: null, key: 'key1', val: 'val1' },
+      { __proto__: null, key: 'key2', val: 'val2' },
+    ]);
+  });
+});
+
 suite('StatementSync.prototype.run()', () => {
   test('executes a query and returns change metadata', (t) => {
     const db = new DatabaseSync(nextDb());