@stoolap/node 0.3.4 → 0.3.7

package/README.md

@@ -1,11 +1,13 @@
 # @stoolap/node
 
-High-performance Node.js driver for [Stoolap](https://github.com/stoolap/stoolap), a modern embedded SQL database with MVCC, time-travel queries, and full ACID compliance.
+High-performance JavaScript driver for [Stoolap](https://github.com/stoolap/stoolap), a modern embedded SQL database with MVCC, time-travel queries, and full ACID compliance.
 
-Built with a native N-API C addon for minimal overhead. Provides both async and sync APIs.
+Built with a native N-API C addon for minimal overhead. Works with Node.js, Bun, and Deno. Provides both async and sync APIs.
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![Bun](https://img.shields.io/badge/bun-compatible-f472b6.svg)](https://bun.sh)
+[![Deno](https://img.shields.io/badge/deno-compatible-000000.svg)](https://deno.com)
 
 ## Installation
 
@@ -106,6 +108,7 @@ Sync methods run on the main thread. Faster for simple operations but block the
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `Database.openSync(path)` | `Database` | Open a database |
+| `clone()` | `Database` | Clone handle (shared engine, own state) |
 | `executeSync(sql, params?)` | `RunResult` | Execute DML statement |
 | `execSync(sql)` | `void` | Execute a DDL statement |
 | `querySync(sql, params?)` | `Object[]` | Query rows as objects |
@@ -187,6 +190,24 @@ Controls the durability vs. performance trade-off:
 | `compression` | | Set both `wal_compression` and `snapshot_compression` |
 | `compression_threshold` | `64` | Minimum bytes before compressing an entry |
 
+#### Cloning
+
+`clone()` creates a new `Database` handle that shares the same underlying engine (data, indexes, transactions) but has its own executor and error state. Useful for concurrent access patterns such as worker threads.
+
+```js
+const db = await Database.open('./mydata');
+const db2 = db.clone();
+
+// Both see the same data
+await db.execute('INSERT INTO users VALUES ($1, $2)', [1, 'Alice']);
+const row = db2.queryOneSync('SELECT * FROM users WHERE id = $1', [1]);
+// { id: 1, name: 'Alice' }
+
+// Each clone must be closed independently
+await db2.close();
+await db.close();
+```
+
 #### Raw Query Format
 
 `queryRaw` / `queryRawSync` return `{ columns: string[], rows: any[][] }` instead of an array of objects. Faster when you don't need named keys.

package/index.d.ts

@@ -17,6 +17,12 @@ export declare class Database {
    * Open a database synchronously.
    */
   static openSync(path: string): Database;
+  /**
+   * Clone this database handle. The clone shares the same underlying engine
+   * (data, indexes, transactions) but has its own executor and error state.
+   * Each clone must be closed independently.
+   */
+  clone(): Database;
   /**
    * Execute a DDL/DML statement. Returns Promise<{ changes: number }>.
    *

package/lib/database.js

@@ -128,6 +128,14 @@ class Database {
     return this.#stoolap.dbExecBatchBuf(this.#ptr, sql, batchBuf);
   }
 
+  // -- Clone --
+
+  clone() {
+    this.#checkOpen();
+    const clonedPtr = this.#stoolap.dbClone(this.#ptr);
+    return new Database(clonedPtr, this.#stoolap);
+  }
+
   // -- Execute (DML) --
 
   async execute(sql, params) {
@@ -312,7 +320,7 @@ class Database {
 
   async begin() {
     const txPtr = await this._beginAsync();
-    const tx = new Transaction(txPtr, this.#stoolap, this);
+    const tx = new Transaction(txPtr, this.#stoolap, this, this.#ptr);
     this._trackChild(tx);
     return tx;
   }
@@ -320,7 +328,7 @@ class Database {
   beginSync() {
     this.#checkOpen();
     const txPtr = this.#stoolap.txBegin(this.#ptr);
-    const tx = new Transaction(txPtr, this.#stoolap, this);
+    const tx = new Transaction(txPtr, this.#stoolap, this, this.#ptr);
     this._trackChild(tx);
     return tx;
   }

package/lib/transaction.js

@@ -6,15 +6,17 @@ const { parseRows, parseRaw } = require("./parse");
 class Transaction {
   #ptr = null;
   #stoolap = null;
+  #dbPtr = null;
   #pendingAsync = 0;
   #tail = Promise.resolve();
   #closingPromise = null;
   #owner = null;
 
-  constructor(ptr, stoolap, owner) {
+  constructor(ptr, stoolap, owner, dbPtr) {
     this.#ptr = ptr;
     this.#stoolap = stoolap;
     this.#owner = owner || null;
+    this.#dbPtr = dbPtr || null;
   }
 
   _invalidate() {
@@ -177,7 +179,7 @@ class Transaction {
   executeBatchSync(sql, paramsArray) {
     this.#checkSyncReady();
     if (paramsArray.length > 0 && Array.isArray(paramsArray[0])) {
-      return this.#stoolap.txExecBatch(this.#ptr, sql, paramsArray);
+      return this.#stoolap.txExecBatch(this.#dbPtr, this.#ptr, sql, paramsArray);
     }
     let totalChanges = 0;
     for (const params of paramsArray) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stoolap/node",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "description": "High-performance Node.js driver for Stoolap embedded SQL database",
   "main": "index.js",
   "types": "index.d.ts",
@@ -13,15 +13,16 @@
   ],
   "scripts": {
     "install": "node-gyp rebuild",
+    "build": "node-gyp rebuild",
     "test": "node --test __test__/index.spec.mjs",
     "bench": "node benchmark.mjs"
   },
   "optionalDependencies": {
-    "@stoolap/lib-darwin-arm64": "0.3.4",
-    "@stoolap/lib-darwin-x64": "0.3.4",
-    "@stoolap/lib-linux-arm64-gnu": "0.3.4",
-    "@stoolap/lib-linux-x64-gnu": "0.3.4",
-    "@stoolap/lib-win32-x64-msvc": "0.3.4"
+    "@stoolap/lib-darwin-arm64": "0.3.7",
+    "@stoolap/lib-darwin-x64": "0.3.7",
+    "@stoolap/lib-linux-arm64-gnu": "0.3.7",
+    "@stoolap/lib-linux-x64-gnu": "0.3.7",
+    "@stoolap/lib-win32-x64-msvc": "0.3.7"
   },
   "devDependencies": {
     "better-sqlite3": "^12.6.2",

package/src/stoolap.c

@@ -12,6 +12,7 @@
 #include <stdlib.h>
 #include <string.h>
 #include <stdint.h>
+#include <stdio.h>
 
 #ifdef _WIN32
   #include <windows.h>
@@ -68,6 +69,7 @@ typedef struct {
 typedef const char* (*fn_version)(void);
 typedef int32_t (*fn_open)(const char*, StoolapDB**);
 typedef int32_t (*fn_open_mem)(StoolapDB**);
+typedef int32_t (*fn_clone)(StoolapDB*, StoolapDB**);
 typedef int32_t (*fn_close)(StoolapDB*);
 typedef const char* (*fn_errmsg)(const StoolapDB*);
 typedef int32_t (*fn_exec)(StoolapDB*, const char*, int64_t*);
@@ -85,6 +87,8 @@ typedef int32_t (*fn_tx_exec)(StoolapTx*, const char*, int64_t*);
 typedef int32_t (*fn_tx_exec_p)(StoolapTx*, const char*, const StoolapValue*, int32_t, int64_t*);
 typedef int32_t (*fn_tx_query)(StoolapTx*, const char*, StoolapRows**);
 typedef int32_t (*fn_tx_query_p)(StoolapTx*, const char*, const StoolapValue*, int32_t, StoolapRows**);
+typedef int32_t (*fn_tx_stmt_exec)(StoolapTx*, StoolapStmt*, const StoolapValue*, int32_t, int64_t*);
+typedef int32_t (*fn_tx_stmt_query)(StoolapTx*, StoolapStmt*, const StoolapValue*, int32_t, StoolapRows**);
 typedef int32_t (*fn_tx_commit)(StoolapTx*);
 typedef int32_t (*fn_tx_rollback)(StoolapTx*);
 typedef const char* (*fn_tx_errmsg)(const StoolapTx*);
@@ -110,6 +114,7 @@ static struct {
   fn_version version;
   fn_open open;
   fn_open_mem open_mem;
+  fn_clone clone;
   fn_close close;
   fn_errmsg errmsg;
   fn_exec exec;
@@ -127,6 +132,8 @@ static struct {
   fn_tx_exec_p tx_exec_p;
   fn_tx_query tx_query;
   fn_tx_query_p tx_query_p;
+  fn_tx_stmt_exec tx_stmt_exec;
+  fn_tx_stmt_query tx_stmt_query;
   fn_tx_commit tx_commit;
   fn_tx_rollback tx_rollback;
   fn_tx_errmsg tx_errmsg;
@@ -152,6 +159,8 @@ static LibHandle lib_handle = NULL;
 /* ---- Helpers ---- */
 
 #define THROW(env, msg) do { napi_throw_error(env, NULL, msg); return NULL; } while(0)
+#define ERR_SAVE(msg, fallback) \
+  char _eb[512]; snprintf(_eb, sizeof(_eb), "%s", (msg) ? (msg) : (fallback))
 #define CHECK(env, status) if ((status) != napi_ok) return NULL
 
 static napi_value make_changes(napi_env env, int64_t n) {
@@ -1506,6 +1515,7 @@ static napi_value fn_load_library(napi_env env, napi_callback_info info) {
   LOAD(version,       "stoolap_version");
   LOAD(open,          "stoolap_open");
   LOAD(open_mem,      "stoolap_open_in_memory");
+  LOAD(clone,         "stoolap_clone");
   LOAD(close,         "stoolap_close");
   LOAD(errmsg,        "stoolap_errmsg");
   LOAD(exec,          "stoolap_exec");
@@ -1523,6 +1533,10 @@ static napi_value fn_load_library(napi_env env, napi_callback_info info) {
   LOAD(tx_exec_p,     "stoolap_tx_exec_params");
   LOAD(tx_query,      "stoolap_tx_query");
   LOAD(tx_query_p,    "stoolap_tx_query_params");
+  /* Optional symbols — not in all engine versions */
+  S.tx_stmt_exec  = (fn_tx_stmt_exec) DLSYM(lib_handle, "stoolap_tx_stmt_exec");
+  S.tx_stmt_query = (fn_tx_stmt_query)DLSYM(lib_handle, "stoolap_tx_stmt_query");
+
   LOAD(tx_commit,     "stoolap_tx_commit");
   LOAD(tx_rollback,   "stoolap_tx_rollback");
   LOAD(tx_errmsg,     "stoolap_tx_errmsg");
@@ -1578,6 +1592,27 @@ static napi_value fn_db_open(napi_env env, napi_callback_info info) {
   return ext;
 }
 
+/* dbClone(external): external */
+static napi_value fn_db_clone(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
+
+  StoolapDB* db;
+  napi_get_value_external(env, argv[0], (void**)&db);
+
+  StoolapDB* cloned = NULL;
+  int32_t rc = S.clone(db, &cloned);
+  if (rc != STOOLAP_OK) {
+    const char* msg = S.errmsg(db);
+    THROW(env, msg ? msg : "Failed to clone database");
+  }
+
+  napi_value ext;
+  napi_create_external(env, cloned, NULL, NULL, &ext);
+  return ext;
+}
+
 /* dbClose(external): void */
 static napi_value fn_db_close(napi_env env, napi_callback_info info) {
   size_t argc = 1;
@@ -2948,22 +2983,37 @@ static napi_value wrap_tx_rollback_async(napi_env env, napi_callback_info info)
  * Batch exec in C — copies SQL once, pre-allocates param buffers,
  * loops param sets in C. Eliminates N × JS↔C crossings + N×malloc/free. */
 static napi_value wrap_tx_exec_batch(napi_env env, napi_callback_info info) {
-  size_t argc = 3;
-  napi_value argv[3];
+  size_t argc = 4;
+  napi_value argv[4];
   napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
 
+  StoolapDB* db;
+  napi_get_value_external(env, argv[0], (void**)&db);
+
   StoolapTx* tx;
-  napi_get_value_external(env, argv[0], (void**)&tx);
+  napi_get_value_external(env, argv[1], (void**)&tx);
 
-  GET_SQL_STRING(env, argv[1], sql);
+  GET_SQL_STRING(env, argv[2], sql);
 
   uint32_t batch_len;
-  napi_get_array_length(env, argv[2], &batch_len);
+  napi_get_array_length(env, argv[3], &batch_len);
   if (batch_len == 0) return make_changes(env, 0);
 
+  /* Prepare statement once if tx_stmt_exec is available */
+  StoolapStmt* stmt = NULL;
+  int use_stmt = (S.tx_stmt_exec != NULL);
+  int32_t rc;
+  if (use_stmt) {
+    rc = S.prepare(db, sql, &stmt);
+    if (rc != STOOLAP_OK) {
+      const char* msg = S.errmsg(db);
+      THROW(env, msg ? msg : "Prepare error");
+    }
+  }
+
   /* Get param count from first element — pre-allocate ONCE */
   napi_value first_arr;
-  napi_get_element(env, argv[2], 0, &first_arr);
+  napi_get_element(env, argv[3], 0, &first_arr);
   uint32_t param_count;
   napi_get_array_length(env, first_arr, &param_count);
 
@@ -2974,7 +3024,7 @@ static napi_value wrap_tx_exec_batch(napi_env env, napi_callback_info info) {
 
   for (uint32_t i = 0; i < batch_len; i++) {
     napi_value params_arr;
-    napi_get_element(env, argv[2], i, &params_arr);
+    napi_get_element(env, argv[3], i, &params_arr);
 
     /* Convert params into pre-allocated buffers */
     int tbuf_cnt = 0;
@@ -2982,23 +3032,28 @@ static napi_value wrap_tx_exec_batch(napi_env env, napi_callback_info info) {
       napi_value elem;
       napi_get_element(env, params_arr, j, &elem);
       if (js_to_value(env, elem, &vals[j], tbufs, &tbuf_cnt) != 0) {
-        /* Cleanup on error */
         for (int k = 0; k < tbuf_cnt; k++) free(tbufs[k]);
         free(vals); free(tbufs);
+        if (stmt) S.stmt_finalize(stmt);
         THROW(env, "Failed to convert parameters");
       }
     }
 
     int64_t affected = 0;
-    int32_t rc = S.tx_exec_p(tx, sql, vals, (int32_t)param_count, &affected);
+    if (use_stmt) {
+      rc = S.tx_stmt_exec(tx, stmt, vals, (int32_t)param_count, &affected);
+    } else {
+      rc = S.tx_exec_p(tx, sql, vals, (int32_t)param_count, &affected);
+    }
 
     /* Free only text buffers, keep vals/tbufs arrays for reuse */
     for (int k = 0; k < tbuf_cnt; k++) { free(tbufs[k]); tbufs[k] = NULL; }
 
     if (rc != STOOLAP_OK) {
+      ERR_SAVE(S.tx_errmsg(tx), "Transaction batch exec error");
       free(vals); free(tbufs);
-      const char* msg = S.tx_errmsg(tx);
-      THROW(env, msg ? msg : "Transaction batch exec error");
+      if (stmt) S.stmt_finalize(stmt);
+      THROW(env, _eb);
     }
 
     total_affected += affected;
@@ -3006,6 +3061,7 @@ static napi_value wrap_tx_exec_batch(napi_env env, napi_callback_info info) {
 
   free(vals);
   free(tbufs);
+  if (stmt) S.stmt_finalize(stmt);
   return make_changes(env, total_affected);
 }
 
@@ -3170,23 +3226,30 @@ static napi_value wrap_db_exec_batch_buf(napi_env env, napi_callback_info info)
   int32_t rc = S.begin(db, &tx);
   if (rc != STOOLAP_OK) { const char* msg = S.errmsg(db); THROW(env, msg ? msg : "Begin error"); }
   StoolapStmt* stmt = NULL;
-  rc = S.prepare(db, sql, &stmt);
-  if (rc != STOOLAP_OK) { S.tx_rollback(tx); const char* msg = S.errmsg(db); THROW(env, msg ? msg : "Prepare error"); }
+  int use_stmt = (S.tx_stmt_exec != NULL);
+  if (use_stmt) {
+    rc = S.prepare(db, sql, &stmt);
+    if (rc != STOOLAP_OK) { ERR_SAVE(S.errmsg(db), "Prepare error"); S.tx_rollback(tx); THROW(env, _eb); }
+  }
   int64_t total = 0;
   for (uint32_t i = 0; i < row_count; i++) {
     StoolapValue vals[MAX_STACK_PARAMS];
     size_t consumed = 0;
     int decoded = decode_params_buf(ptr, (size_t)(end - ptr), vals, ppr, &consumed);
-    if (decoded != ppr) { S.stmt_finalize(stmt); S.tx_rollback(tx); THROW(env, "Batch param decode error"); }
+    if (decoded != ppr) { if (stmt) S.stmt_finalize(stmt); S.tx_rollback(tx); THROW(env, "Batch param decode error"); }
     ptr += consumed;
     int64_t affected = 0;
-    rc = S.stmt_exec(stmt, vals, decoded, &affected);
-    if (rc != STOOLAP_OK) { const char* msg = S.stmt_errmsg(stmt); S.stmt_finalize(stmt); S.tx_rollback(tx); THROW(env, msg ? msg : "Batch exec error"); }
+    if (use_stmt) {
+      rc = S.tx_stmt_exec(tx, stmt, vals, decoded, &affected);
+    } else {
+      rc = S.tx_exec_p(tx, sql, vals, decoded, &affected);
+    }
+    if (rc != STOOLAP_OK) { ERR_SAVE(S.tx_errmsg(tx), "Batch exec error"); if (stmt) S.stmt_finalize(stmt); S.tx_rollback(tx); THROW(env, _eb); }
     total += affected;
   }
-  S.stmt_finalize(stmt);
+  if (stmt) S.stmt_finalize(stmt);
   rc = S.tx_commit(tx);
-  if (rc != STOOLAP_OK) { const char* msg = S.errmsg(db); THROW(env, msg ? msg : "Commit error"); }
+  if (rc != STOOLAP_OK) { THROW(env, "Commit error"); }
   return make_changes(env, total);
 }
 
@@ -3242,6 +3305,7 @@ static napi_value Init(napi_env env, napi_value exports) {
   EXPORT_FN(env, exports, "loadLibrary",   fn_load_library);
   EXPORT_FN(env, exports, "dbOpen",        fn_db_open);
   EXPORT_FN(env, exports, "dbOpenAsync",   fn_db_open_async);
+  EXPORT_FN(env, exports, "dbClone",       fn_db_clone);
   EXPORT_FN(env, exports, "dbClose",       fn_db_close);
   EXPORT_FN(env, exports, "dbCloseAsync",  fn_db_close_async);
   EXPORT_FN(env, exports, "dbExec",        fn_db_exec);