add .execIterator for streaming rows

.changeset/witty-impalas-dance.md

@@ -0,0 +1,5 @@
+---
+"@effect/wa-sqlite": patch
+---
+
+add .execIterator for streaming rows

src/sqlite-api.js

@@ -470,6 +470,20 @@ export function Factory(Module) {
     return rows
   }
 
+  // @ts-ignore
+  sqlite3.execIterator = function* (db, sql) {
+    for (const stmt of sqlite3.statements(db, sql)) {
+      let columns
+      while (sqlite3.step(stmt) === SQLite.SQLITE_ROW) {
+        columns = columns ?? sqlite3.column_names(stmt)
+        const row = sqlite3.row(stmt)
+        // @ts-ignore
+        row.columns = columns
+        yield row
+      }
+    }
+  }
+
   sqlite3.finalize = (function () {
     const fname = "sqlite3_finalize"
     const f = Module.cwrap(fname, ...decl("n:n"), { async })

src/types/index.d.ts

@@ -542,17 +542,25 @@ declare interface SQLiteAPI {
    * @see https://www.sqlite.org/c3ref/exec.html
    * @param db database pointer
    * @param zSQL queries
-   * @param callback called for each output row
-   * @returns Promise resolving to `SQLITE_OK` (rejects on error)
+   * @returns An array of rows, each containing an array of column values
    */
-  exec(
+  exec(db: number, zSQL: string): Array<Array<any>>
+
+  /**
+   * One-step query execution interface
+   *
+   * The implementation of this function uses {@link row}, which makes a
+   * copy of blobs and returns BigInt for integers outside the safe integer
+   * bounds for Number.
+   * @see https://www.sqlite.org/c3ref/exec.html
+   * @param db database pointer
+   * @param zSQL queries
+   * @returns An iterator of rows, each containing an array of column values
+   */
+  execIterator(
     db: number,
     zSQL: string,
-    callback?: (
-      row: Array<SQLiteCompatibleType | null>,
-      columns: string[],
-    ) => void,
-  ): Array<Array<any>>
+  ): Iterable<Array<any> & { readonly columns: Array<string> }>
 
   /**
    * Destroy a prepared statement object compiled by {@link statements}