@stoolap/node 0.3.5 → 0.3.7

package/README.md

@@ -108,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 |
@@ -189,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stoolap/node",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "High-performance Node.js driver for Stoolap embedded SQL database",
   "main": "index.js",
   "types": "index.d.ts",
@@ -18,11 +18,11 @@
     "bench": "node benchmark.mjs"
   },
   "optionalDependencies": {
-    "@stoolap/lib-darwin-arm64": "0.3.5",
-    "@stoolap/lib-darwin-x64": "0.3.5",
-    "@stoolap/lib-linux-arm64-gnu": "0.3.5",
-    "@stoolap/lib-linux-x64-gnu": "0.3.5",
-    "@stoolap/lib-win32-x64-msvc": "0.3.5"
+    "@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*);
@@ -112,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;
@@ -156,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) {
@@ -1510,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");
@@ -1586,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;
@@ -3023,10 +3050,10 @@ static napi_value wrap_tx_exec_batch(napi_env env, napi_callback_info info) {
     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);
       if (stmt) S.stmt_finalize(stmt);
-      THROW(env, msg ? msg : "Transaction batch exec error");
+      THROW(env, _eb);
     }
 
     total_affected += affected;
@@ -3202,7 +3229,7 @@ static napi_value wrap_db_exec_batch_buf(napi_env env, napi_callback_info info)
   int use_stmt = (S.tx_stmt_exec != NULL);
   if (use_stmt) {
     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"); }
+    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++) {
@@ -3217,12 +3244,12 @@ static napi_value wrap_db_exec_batch_buf(napi_env env, napi_callback_info info)
     } else {
       rc = S.tx_exec_p(tx, sql, vals, decoded, &affected);
     }
-    if (rc != STOOLAP_OK) { const char* msg = S.tx_errmsg(tx); if (stmt) S.stmt_finalize(stmt); S.tx_rollback(tx); THROW(env, msg ? msg : "Batch exec error"); }
+    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;
   }
   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);
 }
 
@@ -3278,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);