deepbase-json 3.10.0 → 3.11.0

package/README.md

@@ -244,6 +244,12 @@ new DeepBase(drivers, options)
 - `await db.last(...path)` - Get last key at path (same order as `keys()`)
 - `await db.values(...path)` - Get values at path
 - `await db.entries(...path)` - Get entries at path
+- `db.query(...path)` - Chain a query over the object at path (`where`, `orderBy`, `skip`, `take`, `select`) and run it with `toArray()`, `first()`, `count()` or `any()`
+
+`query()` reads the object at the path with `get()` and evaluates the chain in
+memory, so it walks the object already read: v1 pushes no filters to the driver
+and uses no indexes. Terminals resolve to `{ id, value }` records, where `id` is
+the property name and `value` the stored value.
 
 ### Migration Methods
 
@@ -484,58 +490,63 @@ await db.set("a", "b", "circular", "self", await db.get("a", "b"));
 
 ## 🔒 Secure Storage with Encryption
 
-You can create encrypted storage by extending DeepBase with custom serialization:
+Use the built-in plugin to encrypt every value with AES-256-GCM before it
+reaches the driver. With `JsonDriver`, values stay encrypted both on disk and
+in its internal memory cache; no custom serialization or memory hooks are needed.
 
 ```javascript
-import CryptoJS from 'crypto-js';
 import DeepBase from 'deepbase';
+import { encryptedValues } from 'deepbase/plugins/encryption';
 import { JsonDriver } from 'deepbase-json';
 
-class DeepbaseSecure extends DeepBase {
-  constructor(opts) {
-    const encryptionKey = opts.encryptionKey;
-    delete opts.encryptionKey;
-
-    // Create JSON driver with encryption
-    const driver = new JsonDriver({
-      ...opts,
-      stringify: (obj) => {
-        const iv = CryptoJS.lib.WordArray.random(128 / 8);
-        const encrypted = CryptoJS.AES.encrypt(
-          JSON.stringify(obj), 
-          encryptionKey, 
-          { iv }
-        );
-        return iv.toString(CryptoJS.enc.Hex) + ':' + encrypted.toString();
-      },
-      parse: (encryptedData) => {
-        const [ivHex, encrypted] = encryptedData.split(':');
-        const iv = CryptoJS.enc.Hex.parse(ivHex);
-        const bytes = CryptoJS.AES.decrypt(encrypted, encryptionKey, { iv });
-        return JSON.parse(bytes.toString(CryptoJS.enc.Utf8));
-      }
-    });
-
-    super(driver);
-  }
+const encodedKey = process.env.DEEPBASE_ENCRYPTION_KEY;
+if (!encodedKey) {
+  throw new Error('DEEPBASE_ENCRYPTION_KEY is required');
 }
 
-// Create an encrypted database
-const secureDB = new DeepbaseSecure({
+const encryptionKey = Buffer.from(encodedKey, 'base64');
+const encryption = encryptedValues({
+  activeKeyId: 'primary',
+  keys: { primary: encryptionKey }
+});
+
+const driver = new JsonDriver({
   path: '/var/lib/myapp/data',
-  name: 'secure_db',
-  encryptionKey: 'your-secret-key-here'
+  name: 'secure_db'
 });
+const secureDB = new DeepBase(driver).use(encryption);
+
+try {
+  await secureDB.set('config', {
+    service: 'my-app',
+    accessToken: 'example-token',
+    retries: 0
+  });
+
+  await secureDB.inc('config', 'retries', 1);
+  const config = await secureDB.get('config'); // Decrypted for the application
+} finally {
+  await secureDB.dispose({ clearMemory: true, releaseInstance: true });
+  encryptionKey.fill(0);
+}
+```
 
-await secureDB.connect();
+Provide a base64-encoded, randomly generated 32-byte key through your
+application's secret manager or environment. The application reads it explicitly;
+the plugin requires a 32-byte `Buffer` or `Uint8Array` and never supplies a
+default key. Keep the key available under the same `keyId` to reopen the database.
 
-// Use it like a regular DeepBase instance
-await secureDB.set("users", "admin", { password: "secret123" });
-const admin = await secureDB.get("users", "admin");
-console.log(admin); // { password: 'secret123' }
+Object keys, array lengths, and empty containers remain visible. Plaintext
+exists while your application supplies or reads values, including inside
+`upd()` callbacks; the plugin does not cache decrypted values. Disposal clears
+the JSON driver's cache and the plugin's internal key copies.
 
-// But the file on disk is encrypted!
-```
+Authentication failures, malformed envelopes, and unknown key IDs throw.
+Existing plaintext data is encrypted when rewritten through the plugin;
+registering it does not migrate existing data automatically.
+
+See the [encryption plugin documentation](../core/docs/plugins/encryption.md)
+for additional keys and key rotation.
 
 ## 🛠️ Creating Custom Drivers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepbase-json",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "⚡ DeepBase JSON - filesystem driver",
   "type": "module",
   "main": "src/index.cjs",
@@ -18,10 +18,7 @@
     "steno": "^0.4.4"
   },
   "peerDependencies": {
-    "deepbase": "^3.10.0"
-  },
-  "scripts": {
-    "test": "mocha test/test.js"
+    "deepbase": "^3.11.0"
   },
   "devDependencies": {
     "mocha": "^10.8.2"
@@ -45,5 +42,8 @@
   "bugs": {
     "url": "https://github.com/clasen/DeepBase/issues"
   },
-  "homepage": "https://github.com/clasen/DeepBase/tree/main/packages/driver-json"
-}
+  "homepage": "https://github.com/clasen/DeepBase/tree/main/packages/driver-json",
+  "scripts": {
+    "test": "mocha test/test.js"
+  }
+}

package/src/JsonDriver.js

@@ -1,4 +1,4 @@
-import { DeepBaseDriver } from 'deepbase';
+import { DeepBaseDriver, evaluateQuery, removeKey } from 'deepbase';
 import steno from 'steno';
 import fs from 'fs';
 import * as pathModule from 'path';
@@ -107,6 +107,11 @@ export class JsonDriver extends DeepBaseDriver {
     const value = this._getRecursive(this.obj, args.slice());
     return this._decodeFromMemory(value, args);
   }
+
+  async query(path, steps) {
+    this._assertUsable();
+    return evaluateQuery(await this.get(...path), steps, { path });
+  }
   
   async set(...args) {
     return this._queueOperation(async () => {
@@ -137,8 +142,7 @@ export class JsonDriver extends DeepBaseDriver {
       const key = keys.pop();
       const parentObj = this._getRecursive(this.obj, keys.slice());
       
-      if (parentObj && parentObj.hasOwnProperty(key)) {
-        delete parentObj[key];
+      if (removeKey(parentObj, key)) {
         return this._saveToFile();
       }
     });

package/test/test.js

@@ -4,6 +4,8 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { fork } from 'child_process';
 import { DeepBase } from '../../core/src/index.js';
+import { arrayScenarios } from '../../core/test/array-scenario.js';
+import { seedQueryFixture, queryScenarios } from '../../core/test/query-scenario.js';
 import { JsonDriver } from '../src/JsonDriver.js';
 import { SqliteDriver } from '../../driver-sqlite/src/SqliteDriver.js';
 
@@ -905,6 +907,26 @@ describe('JsonDriver', function() {
       JsonDriver._instances = {};
     });
   });
+
+  describe('query()', function() {
+    beforeEach(async function() {
+      await seedQueryFixture(db);
+    });
+
+    for (const scenario of queryScenarios) {
+      it(scenario.title, async function() {
+        await scenario.run(db);
+      });
+    }
+  });
+
+  describe('array operations', function() {
+    for (const scenario of arrayScenarios) {
+      it(scenario.title, async function() {
+        await scenario.run(db);
+      });
+    }
+  });
 });
 
 describe('Multi-Driver: JsonDriver + SqliteDriver (add + pop + shift)', function() {