deepbase-sqlite 3.5.1 → 3.6.4

package/README.md

@@ -5,9 +5,14 @@ SQLite driver for DeepBase.
 ## Installation
 
 ```bash
-npm install deepbase deepbase-sqlite
+npm install deepbase deepbase-sqlite --ignore-scripts=false
 ```
 
+> `deepbase-sqlite` depends on `better-sqlite3`, a native module. Its install
+> script downloads a prebuilt binary (or compiles from source as a fallback).
+> If your environment disables npm lifecycle scripts, see
+> [Troubleshooting](#troubleshooting) below.
+
 ## Description
 
 Stores data in SQLite database files. Perfect for:
@@ -77,6 +82,8 @@ Efficiently stores nested objects using a key-value schema:
 - Values are stored as JSON
 - Fast lookups for both exact keys and partial paths
 
+Each row also stores a monotonic `seq` so reads that rebuild objects use `ORDER BY seq, key`. That matches JavaScript insertion order for sibling keys and keeps `shift()` / `pop()` (via `DeepBase.keys()`) aligned with `JsonDriver`. Existing databases pick up `seq` via `ALTER TABLE` on connect (legacy rows default to `0`, then tie-break by `key`).
+
 ### ACID Compliance
 
 SQLite provides:
@@ -141,12 +148,12 @@ CREATE TABLE deepbase (
 Example data:
 
 ```
-key                    | value
------------------------|------------------
-users.alice.name       | "Alice"
-users.alice.age        | 30
-users.bob.name         | "Bob"
-users.bob.age          | 25
+key                   | value
+----------------------|------------------
+users.alice.name      | "Alice"
+users.alice.age       | 30
+users.bob.name        | "Bob"
+users.bob.age         | 25
 config.theme           | "dark"
 config.lang            | "en"
 ```
@@ -262,6 +269,52 @@ await db.set('users', userId, 'profile', data);
 await db.set(`user_${userId}_profile`, data);
 ```
 
+## Troubleshooting
+
+### `Could not locate the bindings file` / `better_sqlite3.node` missing
+
+This error means `better-sqlite3`'s native binding was never fetched or built.
+It almost always comes from npm install scripts being disabled, which prevents
+`better-sqlite3`'s `install` script from downloading the prebuilt binary.
+
+Check whether scripts are disabled:
+
+```bash
+npm config get ignore-scripts   # should be "false"
+cat ~/.npmrc 2>/dev/null        # look for `ignore-scripts=true`
+cat .npmrc 2>/dev/null
+```
+
+Fix — rebuild the native binding in the project that uses `deepbase-sqlite`:
+
+```bash
+npm rebuild better-sqlite3 --ignore-scripts=false
+```
+
+If `npm rebuild` still doesn't fetch a prebuild (common when `ignore-scripts`
+is persisted in `.npmrc`), do a clean reinstall of just that package:
+
+```bash
+rm -rf node_modules/better-sqlite3
+npm i --ignore-scripts=false
+```
+
+Verify the binding landed:
+
+```bash
+ls node_modules/better-sqlite3/build/Release/better_sqlite3.node
+```
+
+Notes:
+
+- `npm i <pkg> --ignore-scripts=false` only runs scripts if the install
+  actually changes `node_modules`. When npm reports `up to date`, no install
+  scripts run — use `npm rebuild` or remove the package folder first.
+- In monorepos or CI, prefer setting `ignore-scripts=false` for the install
+  step rather than passing it as a one-off flag.
+- When this happens at runtime, `deepbase-sqlite` will throw an error with
+  code `DEEPBASE_SQLITE_BINDING_MISSING` and a pointer back to this section.
+
 ## License
 
 MIT - Copyright (c) Martin Clasen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepbase-sqlite",
-  "version": "3.5.1",
+  "version": "3.6.4",
   "description": "⚡ DeepBase SQLite - SQLite database driver",
   "type": "module",
   "main": "src/index.cjs",
@@ -17,7 +17,7 @@
     "better-sqlite3": "^11.8.1"
   },
   "peerDependencies": {
-    "deepbase": "^3.5.1"
+    "deepbase": "^3.6.4"
   },
   "scripts": {
     "test": "mocha test/test.js"

package/src/SqliteDriver.js

@@ -52,14 +52,30 @@ export class SqliteDriver extends DeepBaseDriver {
     SqliteDriver._instances[this.fileName] = this;
   }
 
-  async connect() {
+  _connectSync() {
     if (this._connected) return;
 
     if (!fs.existsSync(this.path)) {
       fs.mkdirSync(this.path, { recursive: true });
     }
 
-    this.db = new Database(this.fileName);
+    try {
+      this.db = new Database(this.fileName);
+    } catch (err) {
+      if (this._isMissingNativeBinding(err)) {
+        const hint =
+          'deepbase-sqlite: the native binding for "better-sqlite3" is missing. ' +
+          'This usually means npm install scripts were disabled (e.g. `ignore-scripts=true` in your .npmrc). ' +
+          'Fix it with: `npm rebuild better-sqlite3 --ignore-scripts=false`, ' +
+          'or reinstall with `npm i --ignore-scripts=false`. ' +
+          'See https://github.com/clasen/DeepBase/tree/main/packages/driver-sqlite#troubleshooting';
+        const wrapped = new Error(hint);
+        wrapped.cause = err;
+        wrapped.code = 'DEEPBASE_SQLITE_BINDING_MISSING';
+        throw wrapped;
+      }
+      throw err;
+    }
 
     const cfg = PRAGMA[this.pragma];
     if (cfg) {
@@ -75,15 +91,27 @@ export class SqliteDriver extends DeepBaseDriver {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS deepbase (
         key TEXT PRIMARY KEY,
-        value TEXT NOT NULL
+        value TEXT NOT NULL,
+        seq INTEGER NOT NULL DEFAULT 0
       )${withoutRowid}
     `);
 
+    const tableCols = this.db.prepare('PRAGMA table_info(deepbase)').all();
+    if (!tableCols.some((c) => c.name === 'seq')) {
+      this.db.exec('ALTER TABLE deepbase ADD COLUMN seq INTEGER NOT NULL DEFAULT 0');
+    }
+
     this.getStmt = this.db.prepare('SELECT value FROM deepbase WHERE key = ?');
-    this.setStmt = this.db.prepare('INSERT OR REPLACE INTO deepbase (key, value) VALUES (?, ?)');
+    this.setStmt = this.db.prepare(`
+      INSERT INTO deepbase (key, value, seq)
+      VALUES (?, ?, (SELECT IFNULL(MAX(seq), 0) + 1 FROM deepbase))
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `);
     this.delStmt = this.db.prepare('DELETE FROM deepbase WHERE key = ?');
-    this.getAllStmt = this.db.prepare('SELECT key, value FROM deepbase');
-    this.getKeysLikeStmt = this.db.prepare("SELECT key, value FROM deepbase WHERE key LIKE ? ESCAPE '!'");
+    this.getAllStmt = this.db.prepare('SELECT key, value FROM deepbase ORDER BY seq, key');
+    this.getKeysLikeStmt = this.db.prepare(
+      "SELECT key, value FROM deepbase WHERE key LIKE ? ESCAPE '!' ORDER BY seq, key",
+    );
     this.delChildrenStmt = this.db.prepare("DELETE FROM deepbase WHERE key LIKE ? ESCAPE '!'");
     this.hasChildrenStmt = this.db.prepare("SELECT 1 FROM deepbase WHERE key LIKE ? ESCAPE '!' LIMIT 1");
 
@@ -116,6 +144,10 @@ export class SqliteDriver extends DeepBaseDriver {
     this._connected = true;
   }
 
+  async connect() {
+    this._connectSync();
+  }
+
   async disconnect() {
     if (this.db) {
       this.db.close();
@@ -128,6 +160,11 @@ export class SqliteDriver extends DeepBaseDriver {
     return this._getSync(args);
   }
 
+  getSync(...args) {
+    this._connectSync();
+    return this._getSync(args);
+  }
+
   _getSync(args) {
     if (args.length === 0) {
       return this._getRootObject();
@@ -236,6 +273,16 @@ export class SqliteDriver extends DeepBaseDriver {
     return result;
   }
 
+  _isMissingNativeBinding(err) {
+    if (!err) return false;
+    const msg = String(err.message || '');
+    return (
+      err.code === 'MODULE_NOT_FOUND' ||
+      msg.includes('Could not locate the bindings file') ||
+      msg.includes('better_sqlite3.node')
+    );
+  }
+
   _escapeLikePattern(str) {
     return str.replace(/[!%_]/g, '!$&');
   }

package/test/test.js

@@ -85,6 +85,21 @@ for (const pragma of PRAGMA_MODES) {
         await db.set('complex', complexObj);
         assert.deepStrictEqual(await db.get('complex'), complexObj);
       });
+
+      it('getSync returns same value as get (sync API)', async function () {
+        await db.set('syncKey', 'syncValue');
+        await db.set('syncNested', 'a', 1);
+        const driver = db.getDriver(0);
+        assert.strictEqual(driver.getSync('syncKey'), 'syncValue');
+        assert.strictEqual(driver.getSync('syncNested', 'a'), 1);
+        assert.strictEqual(driver.getSync('nonexistent'), null);
+      });
+
+      it('getSync lazy-connects when not connected', function () {
+        const driver = new SqliteDriver({ name: 'getSync-lazy', path: testDataPath });
+        assert.strictEqual(driver.getSync('key'), null);
+        assert.ok(driver._connected);
+      });
     });
 
     describe('Keys with Dots', function () {