@stoolap/node 0.3.5 → 0.4.0

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 |
@@ -126,7 +127,7 @@ import { Database, RunResult } from '@stoolap/node';
 
 #### Persistence
 
-File-based databases persist data to disk using WAL (Write-Ahead Logging) and periodic snapshots. Data survives process restarts.
+File-based databases persist data to disk using WAL (Write-Ahead Logging) and an immutable volume-based storage engine. Hot data lives in memory, cold data is sealed into columnar `.vol` files with zone maps, bloom filters, and LZ4 compression. Data survives process restarts.
 
 ```js
 const db = await Database.open('./mydata');
@@ -147,18 +148,18 @@ await db2.close();
 Pass configuration as query parameters in the path:
 
 ```js
-// Maximum durability: fsync on every WAL write
-const db = await Database.open('./mydata?sync=full');
+// Maximum durability: fsync on every write
+const db = await Database.open('./mydata?sync_mode=full');
 
-// High throughput: no fsync, larger buffers
-const db = await Database.open('./mydata?sync=none&wal_buffer_size=131072');
+// High throughput: no fsync, data durable at checkpoint
+const db = await Database.open('./mydata?sync_mode=none');
 
-// Custom snapshot interval with compression
-const db = await Database.open('./mydata?snapshot_interval=60&compression=on');
+// Custom checkpoint interval with compression
+const db = await Database.open('./mydata?checkpoint_interval=60&compression=on');
 
 // Multiple options
 const db = await Database.open(
-  './mydata?sync=full&snapshot_interval=120&keep_snapshots=10&wal_max_size=134217728'
+  './mydata?sync_mode=normal&checkpoint_interval=120&compact_threshold=4'
 );
 ```
 
@@ -168,26 +169,40 @@ Controls the durability vs. performance trade-off:
 
 | Mode | Value | Description |
 |------|-------|-------------|
-| `none` | `sync=none` | No fsync. Fastest, data may be lost on crash |
-| `normal` | `sync=normal` | Fsync on commit batches. Good balance (default) |
-| `full` | `sync=full` | Fsync on every WAL write. Slowest, maximum durability |
+| `none` | `sync_mode=none` | No fsync. Data durable only after checkpoint |
+| `normal` | `sync_mode=normal` | Fsync every 1 second (batched). DDL fsyncs immediately (default) |
+| `full` | `sync_mode=full` | Fsync on every write. Maximum durability |
 
 ##### All Configuration Parameters
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `sync` | `normal` | Sync mode: `none`, `normal`, or `full` |
-| `snapshot_interval` | `300` | Seconds between automatic snapshots (5 min) |
-| `keep_snapshots` | `5` | Number of snapshot files to retain |
-| `wal_flush_trigger` | `32768` | WAL flush trigger size in bytes (32 KB) |
-| `wal_buffer_size` | `65536` | WAL buffer size in bytes (64 KB) |
-| `wal_max_size` | `67108864` | Max WAL file size before rotation (64 MB) |
-| `commit_batch_size` | `100` | Commits to batch before syncing (normal mode) |
-| `sync_interval_ms` | `10` | Minimum ms between syncs (normal mode) |
+| `sync_mode` | `normal` | Sync mode: `none`, `normal`, or `full` |
+| `checkpoint_interval` | `60` | Seconds between checkpoint cycles (seal + compact + WAL truncate) |
+| `compact_threshold` | `4` | Number of cold volumes before compaction merges them |
+| `checkpoint_on_close` | `on` | Seal all hot rows on clean shutdown for fast startup |
 | `wal_compression` | `on` | LZ4 compression for WAL entries |
-| `snapshot_compression` | `on` | LZ4 compression for snapshots |
-| `compression` | | Set both `wal_compression` and `snapshot_compression` |
-| `compression_threshold` | `64` | Minimum bytes before compressing an entry |
+| `volume_compression` | `on` | LZ4 compression for cold volume files |
+| `compression` | `on` | Shorthand: set both `wal_compression` and `volume_compression` |
+| `keep_snapshots` | `5` | Number of backup snapshot files to retain |
+
+#### 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
 

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/lib/transaction.js

@@ -179,7 +179,12 @@ class Transaction {
   executeBatchSync(sql, paramsArray) {
     this.#checkSyncReady();
     if (paramsArray.length > 0 && Array.isArray(paramsArray[0])) {
-      return this.#stoolap.txExecBatch(this.#dbPtr, 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.5",
+  "version": "0.4.0",
   "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.4.0",
+    "@stoolap/lib-darwin-x64": "0.4.0",
+    "@stoolap/lib-linux-arm64-gnu": "0.4.0",
+    "@stoolap/lib-linux-x64-gnu": "0.4.0",
+    "@stoolap/lib-win32-x64-msvc": "0.4.0"
   },
   "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>
@@ -23,6 +24,7 @@
   typedef HMODULE LibHandle;
 #else
   #include <dlfcn.h>
+  #include <alloca.h>
   #define DLOPEN(path)       dlopen(path, RTLD_NOW | RTLD_LOCAL)
   #define DLSYM(lib, name)   dlsym(lib, name)
   #define DLERROR()          dlerror()
@@ -68,6 +70,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 +115,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 +160,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 +1516,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 +1593,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 +3051,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 +3230,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 +3245,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 +3306,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);