Add clone() support, fix batch error strings, bump to v0.3.7

- Add Database.clone() for shared-engine multi-handle access
- Fix use-after-free on batch error strings (ERR_SAVE macro)
- Add 6 clone tests (shared data, bidirectional writes, tx, stmt)
- Update README with clone documentation
- Bump version to 0.3.7

Author: semihalev

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  STOOLAP_ENGINE_REF: v0.3.5
+  STOOLAP_ENGINE_REF: v0.3.7
 
 jobs:
   build:

.github/workflows/publish.yml

@@ -9,7 +9,7 @@ permissions:
   id-token: write
 
 env:
-  STOOLAP_ENGINE_REF: v0.3.5
+  STOOLAP_ENGINE_REF: v0.3.7
 
 jobs:
   build:

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.

__test__/index.spec.mjs

@@ -1641,6 +1641,76 @@ describe('Vector support', () => {
   });
 });
 
+// ============================================================
+// Clone
+// ============================================================
+
+describe('Database clone', () => {
+  let db;
+
+  before(async () => {
+    db = await Database.open(':memory:');
+    await db.exec('CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT)');
+    await db.execute('INSERT INTO items VALUES ($1, $2)', [1, 'Alpha']);
+    await db.execute('INSERT INTO items VALUES ($1, $2)', [2, 'Beta']);
+  });
+
+  after(async () => {
+    await db.close();
+  });
+
+  it('should clone a database handle and share data', async () => {
+    const db2 = db.clone();
+    const rows = db2.querySync('SELECT * FROM items ORDER BY id');
+    assert.equal(rows.length, 2);
+    assert.equal(rows[0].name, 'Alpha');
+    assert.equal(rows[1].name, 'Beta');
+    await db2.close();
+  });
+
+  it('should see writes from the original in the clone', async () => {
+    const db2 = db.clone();
+    await db.execute('INSERT INTO items VALUES ($1, $2)', [3, 'Gamma']);
+    const row = db2.queryOneSync('SELECT * FROM items WHERE id = $1', [3]);
+    assert.equal(row.name, 'Gamma');
+    await db2.close();
+  });
+
+  it('should see writes from the clone in the original', async () => {
+    const db2 = db.clone();
+    db2.executeSync('INSERT INTO items VALUES ($1, $2)', [4, 'Delta']);
+    const row = await db.queryOne('SELECT * FROM items WHERE id = $1', [4]);
+    assert.equal(row.name, 'Delta');
+    await db2.close();
+  });
+
+  it('should close independently without affecting the original', async () => {
+    const db2 = db.clone();
+    await db2.close();
+    const rows = db.querySync('SELECT * FROM items ORDER BY id');
+    assert.ok(rows.length > 0);
+  });
+
+  it('should support transactions on cloned handle', async () => {
+    const db2 = db.clone();
+    const tx = db2.beginSync();
+    tx.executeSync('INSERT INTO items VALUES ($1, $2)', [5, 'Epsilon']);
+    tx.commitSync();
+    const row = db2.queryOneSync('SELECT * FROM items WHERE id = $1', [5]);
+    assert.equal(row.name, 'Epsilon');
+    await db2.close();
+  });
+
+  it('should support prepared statements on cloned handle', async () => {
+    const db2 = db.clone();
+    const stmt = db2.prepare('SELECT * FROM items WHERE id = $1');
+    const row = stmt.queryOneSync([1]);
+    assert.equal(row.name, 'Alpha');
+    stmt.finalize();
+    await db2.close();
+  });
+});
+
 // ============================================================
 // Declaration coverage
 // ============================================================

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 }>.
    *

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) {

npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stoolap/lib-darwin-arm64",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "main": "libstoolap.dylib",
   "files": [
     "libstoolap.dylib"

npm/darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stoolap/lib-darwin-x64",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "main": "libstoolap.dylib",
   "files": [
     "libstoolap.dylib"

npm/linux-arm64-gnu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stoolap/lib-linux-arm64-gnu",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "main": "libstoolap.so",
   "files": [
     "libstoolap.so"

npm/linux-x64-gnu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stoolap/lib-linux-x64-gnu",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "main": "libstoolap.so",
   "files": [
     "libstoolap.so"