deepbase-json 3.8.1 → 3.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepbase-json",
-  "version": "3.8.1",
+  "version": "3.8.4",
   "description": "⚡ DeepBase JSON - filesystem driver",
   "type": "module",
   "main": "src/index.cjs",
@@ -18,7 +18,7 @@
     "steno": "^0.4.4"
   },
   "peerDependencies": {
-    "deepbase": "^3.8.1"
+    "deepbase": "^3.8.4"
   },
   "devDependencies": {
     "mocha": "^10.8.2"

package/src/JsonDriver.js

@@ -7,7 +7,16 @@ import lockfile from 'proper-lockfile';
 export class JsonDriver extends DeepBaseDriver {
   static _instances = {};
   
-  constructor({name, path, stringify, parse, multiProcess, ...opts} = {}) {
+  constructor({
+    name,
+    path,
+    stringify,
+    parse,
+    multiProcess,
+    encodeForMemory,
+    decodeFromMemory,
+    ...opts
+  } = {}) {
     super(opts);
     
     this.name = name || "default";
@@ -15,6 +24,8 @@ export class JsonDriver extends DeepBaseDriver {
     this.stringify = stringify || ((obj) => JSON.stringify(obj, null, 4));
     this.parse = parse || JSON.parse;
     this.multiProcess = multiProcess || false;
+    this.encodeForMemory = encodeForMemory || (value => value);
+    this.decodeFromMemory = decodeFromMemory || (value => value);
     
     this.path = pathModule.resolve(this.path);
     this.fileName = pathModule.join(this.path, `${this.name}.json`);
@@ -31,11 +42,15 @@ export class JsonDriver extends DeepBaseDriver {
     // Queue for serializing concurrent operations
     this._operationQueue = Promise.resolve();
     this._queueLock = false;
+    this._disposing = false;
+    this._disposed = false;
+    this._disposePromise = null;
     
     JsonDriver._instances[this.fileName] = this;
   }
   
   _connectSync() {
+    this._assertUsable();
     if (this._connected) return;
 
     if (!fs.existsSync(this.path)) {
@@ -44,10 +59,11 @@ export class JsonDriver extends DeepBaseDriver {
 
     if (fs.existsSync(this.fileName)) {
       const fileContent = fs.readFileSync(this.fileName, "utf8");
-      this.obj = fileContent ? this.parse(fileContent) : {};
+      const parsed = fileContent ? this.parse(fileContent) : {};
+      this.obj = this._encodeForMemory(parsed, []);
     } else {
       // Create the file so proper-lockfile can lock it in multiProcess mode
-      fs.writeFileSync(this.fileName, this.stringify(this.obj));
+      fs.writeFileSync(this.fileName, this._serializeMemory());
     }
 
     this._connected = true;
@@ -58,19 +74,25 @@ export class JsonDriver extends DeepBaseDriver {
   }
   
   async disconnect() {
+    if (this._disposed) {
+      return;
+    }
+    if (this._disposePromise) {
+      return this._disposePromise;
+    }
+    await this._operationQueue;
     await this._saveToFile();
     this._connected = false;
   }
   
   async get(...args) {
+    this._assertUsable();
     // In multiProcess mode, re-read from disk for fresh data
     if (this.multiProcess) {
       this._refreshFromDisk();
     }
     const value = this._getRecursive(this.obj, args.slice());
-    return typeof value === 'object' && value !== null 
-      ? this.parse(this.stringify(value)) 
-      : value;
+    return this._decodeFromMemory(value, args);
   }
 
   getSync(...args) {
@@ -79,21 +101,20 @@ export class JsonDriver extends DeepBaseDriver {
     }
     this._connectSync();
     const value = this._getRecursive(this.obj, args.slice());
-    return typeof value === 'object' && value !== null
-      ? this.parse(this.stringify(value))
-      : value;
+    return this._decodeFromMemory(value, args);
   }
   
   async set(...args) {
     return this._queueOperation(async () => {
       if (args.length < 2) {
-        this.obj = args[0];
+        const value = this._encodeForMemory(args[0], []);
+        this.obj = value;
         await this._saveToFile();
         return [];
       }
       
       const keys = args.slice(0, -1);
-      const value = args[args.length - 1];
+      const value = this._encodeForMemory(args[args.length - 1], keys);
       
       // Make a copy to avoid modifying the original array
       this._setRecursive(this.obj, keys.slice(), value);
@@ -143,7 +164,8 @@ export class JsonDriver extends DeepBaseDriver {
     return this._queueOperation(async () => {
       const func = args.pop();
       const currentValue = this._getRecursive(this.obj, args.slice());
-      const newValue = func(currentValue);
+      const decodedValue = this._decodeFromMemory(currentValue, args);
+      const newValue = func(decodedValue);
       await this._setInternal(...args, newValue);
       return args;
     });
@@ -191,13 +213,14 @@ export class JsonDriver extends DeepBaseDriver {
   // Internal set without queuing (for use within queued operations)
   async _setInternal(...args) {
     if (args.length < 2) {
-      this.obj = args[0];
+      const value = this._encodeForMemory(args[0], []);
+      this.obj = value;
       await this._saveToFile();
       return [];
     }
     
     const keys = args.slice(0, -1);
-    const value = args[args.length - 1];
+    const value = this._encodeForMemory(args[args.length - 1], keys);
     
     this._setRecursive(this.obj, keys.slice(), value);
     await this._saveToFile();
@@ -208,12 +231,14 @@ export class JsonDriver extends DeepBaseDriver {
   _refreshFromDisk() {
     if (fs.existsSync(this.fileName)) {
       const fileContent = fs.readFileSync(this.fileName, "utf8");
-      this.obj = fileContent ? this.parse(fileContent) : {};
+      const parsed = fileContent ? this.parse(fileContent) : {};
+      this.obj = this._encodeForMemory(parsed, []);
     }
   }
 
   // Queue operations to prevent race conditions
   async _queueOperation(operation) {
+    this._assertUsable();
     const previousOperation = this._operationQueue;
     
     let resolver;
@@ -248,6 +273,62 @@ export class JsonDriver extends DeepBaseDriver {
       resolver();
     }
   }
+
+  async dispose({ clearMemory = true, releaseInstance = true } = {}) {
+    if (this._disposePromise) {
+      return this._disposePromise;
+    }
+
+    this._disposing = true;
+    this._disposePromise = (async () => {
+      try {
+        await this._operationQueue;
+        if (this._connected) {
+          await this._saveToFile();
+        }
+        this._connected = false;
+
+        if (clearMemory) {
+          this.obj = {};
+        }
+        if (releaseInstance && JsonDriver._instances[this.fileName] === this) {
+          delete JsonDriver._instances[this.fileName];
+        }
+
+        this._disposed = true;
+      } catch (error) {
+        this._disposing = false;
+        this._disposePromise = null;
+        throw error;
+      }
+    })();
+
+    return this._disposePromise;
+  }
+
+  _assertUsable() {
+    if (this._disposing || this._disposed) {
+      throw new Error('JsonDriver has been disposed');
+    }
+  }
+
+  _clone(value) {
+    return typeof value === 'object' && value !== null
+      ? this.parse(this.stringify(value))
+      : value;
+  }
+
+  _encodeForMemory(value, path) {
+    return this.encodeForMemory(this._clone(value), path.map(String));
+  }
+
+  _decodeFromMemory(value, path) {
+    return this.decodeFromMemory(this._clone(value), path.map(String));
+  }
+
+  _serializeMemory() {
+    return this.stringify(this._decodeFromMemory(this.obj, []));
+  }
   
   _setRecursive(obj, keys, value) {
     if (keys.length === 0) return;
@@ -278,7 +359,7 @@ export class JsonDriver extends DeepBaseDriver {
   }
   
   async _saveToFile() {
-    const serializedData = this.stringify(this.obj);
+    const serializedData = this._serializeMemory();
     if (this.multiProcess) {
       // Sync write ensures data is on disk before lock release
       fs.writeFileSync(this.fileName, serializedData);

package/src/index.d.ts

@@ -1,4 +1,6 @@
-import { DeepBaseDriver, DeepBaseDriverOptions } from 'deepbase';
+import { DeepBaseDriver, DeepBaseDriverOptions, DisposeOptions } from 'deepbase';
+
+export type MemoryTransform = (value: unknown, path: string[]) => unknown;
 
 export interface JsonDriverOptions extends DeepBaseDriverOptions {
     name?: string;
@@ -7,6 +9,10 @@ export interface JsonDriverOptions extends DeepBaseDriverOptions {
     parse?: (str: string) => any;
     /** Enable cross-process file locking for safe multi-process access */
     multiProcess?: boolean;
+    /** Transform a defensive copy before it enters the in-memory cache */
+    encodeForMemory?: MemoryTransform;
+    /** Transform a defensive copy when it leaves the in-memory cache */
+    decodeFromMemory?: MemoryTransform;
 }
 
 export class JsonDriver extends DeepBaseDriver {
@@ -17,7 +23,11 @@ export class JsonDriver extends DeepBaseDriver {
     fileName: string;
     stringify: (obj: any) => string;
     parse: (str: string) => any;
-    obj: Record<string, any>;
+    encodeForMemory: MemoryTransform;
+    decodeFromMemory: MemoryTransform;
+    obj: unknown;
+
+    dispose(options?: DisposeOptions): Promise<void>;
 }
 
 export default JsonDriver;

package/test/test.js

@@ -315,6 +315,215 @@ describe('JsonDriver', function() {
     });
   });
 
+  describe('Memory transforms', function() {
+    function transformSecrets(value, path, transform) {
+      if (path.at(-1) === 'privateKey' || path.at(-1) === 'mnemonic') {
+        return transform(value);
+      }
+      if (Array.isArray(value)) {
+        return value.map((item, index) =>
+          transformSecrets(item, [...path, String(index)], transform)
+        );
+      }
+      if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(
+          Object.entries(value).map(([key, item]) => [
+            key,
+            transformSecrets(item, [...path, key], transform)
+          ])
+        );
+      }
+      return value;
+    }
+
+    function createMemoryTransforms() {
+      return {
+        encodeForMemory(value, path) {
+          return transformSecrets(value, path, secret => ({ sealed: secret }));
+        },
+        decodeFromMemory(value, path) {
+          return transformSecrets(value, path, sealed => {
+            if (!sealed || typeof sealed !== 'object' || !('sealed' in sealed)) {
+              throw new Error('Authentication failed');
+            }
+            return sealed.sealed;
+          });
+        }
+      };
+    }
+
+    it('encodes only secrets while preserving queryable structure', async function() {
+      const driver = new JsonDriver({
+        name: 'memory-transform',
+        path: testDataPath,
+        ...createMemoryTransforms()
+      });
+      const secureDb = new DeepBase(driver);
+      await secureDb.connect();
+
+      const account = {
+        address: '0x123',
+        privateKey: 'secret',
+        wallet: { mnemonic: 'words' }
+      };
+      await secureDb.set('account', account);
+      account.privateKey = 'caller-mutation';
+
+      assert.strictEqual(driver.obj.account.address, '0x123');
+      assert.deepStrictEqual(driver.obj.account.privateKey, { sealed: 'secret' });
+      assert.deepStrictEqual(driver.obj.account.wallet.mnemonic, { sealed: 'words' });
+      assert.strictEqual(await secureDb.get('account', 'address'), '0x123');
+
+      const decoded = await secureDb.get('account');
+      assert.deepStrictEqual(decoded, {
+        address: '0x123',
+        privateKey: 'secret',
+        wallet: { mnemonic: 'words' }
+      });
+      decoded.address = 'returned-mutation';
+      assert.strictEqual(driver.obj.account.address, '0x123');
+      await secureDb.dispose();
+    });
+
+    it('decodes values, entries and upd callbacks without exposing cache references', async function() {
+      const driver = new JsonDriver({
+        name: 'memory-collections',
+        path: testDataPath,
+        ...createMemoryTransforms()
+      });
+      const secureDb = new DeepBase(driver);
+      await secureDb.connect();
+      await secureDb.set('accounts', 'main', {
+        address: '0x123',
+        privateKey: 'old-secret'
+      });
+
+      assert.deepStrictEqual(await secureDb.values('accounts'), [{
+        address: '0x123',
+        privateKey: 'old-secret'
+      }]);
+      assert.deepStrictEqual(await secureDb.entries('accounts'), [[
+        'main',
+        { address: '0x123', privateKey: 'old-secret' }
+      ]]);
+
+      const addedPath = await driver.add('accounts', {
+        address: '0x456',
+        privateKey: 'added-secret'
+      });
+      assert.deepStrictEqual(
+        driver.obj.accounts[addedPath.at(-1)].privateKey,
+        { sealed: 'added-secret' }
+      );
+
+      await secureDb.upd('accounts', 'main', account => {
+        assert.strictEqual(account.privateKey, 'old-secret');
+        account.privateKey = 'new-secret';
+        return account;
+      });
+      assert.deepStrictEqual(driver.obj.accounts.main.privateKey, { sealed: 'new-secret' });
+      await secureDb.dispose();
+    });
+
+    it('keeps the existing decoded disk format and encodes parsed data on load', async function() {
+      const options = {
+        name: 'memory-persistence',
+        path: testDataPath,
+        ...createMemoryTransforms()
+      };
+      const firstDriver = new JsonDriver(options);
+      const firstDb = new DeepBase(firstDriver);
+      await firstDb.connect();
+      await firstDb.set('account', { address: '0x123', privateKey: 'secret' });
+      await firstDb.dispose();
+
+      const filePath = path.join(testDataPath, 'memory-persistence.json');
+      assert.deepStrictEqual(JSON.parse(fs.readFileSync(filePath, 'utf8')), {
+        account: { address: '0x123', privateKey: 'secret' }
+      });
+
+      const secondDriver = new JsonDriver(options);
+      const secondDb = new DeepBase(secondDriver);
+      await secondDb.connect();
+      assert.deepStrictEqual(secondDriver.obj.account.privateKey, { sealed: 'secret' });
+      assert.strictEqual(await secondDb.get('account', 'privateKey'), 'secret');
+      await secondDb.dispose();
+    });
+
+    it('does not modify cache when encoding fails', async function() {
+      const driver = new JsonDriver({
+        name: 'memory-encode-failure',
+        path: testDataPath,
+        encodeForMemory(value, path) {
+          if (path.at(-1) === 'privateKey') {
+            throw new Error('Encoding failed');
+          }
+          return value;
+        }
+      });
+      const secureDb = new DeepBase(driver);
+      await secureDb.connect();
+      await secureDb.set('account', 'address', '0x123');
+
+      await assert.rejects(
+        secureDb.set('account', 'privateKey', 'secret'),
+        /Encoding failed/
+      );
+      assert.deepStrictEqual(driver.obj, { account: { address: '0x123' } });
+      await secureDb.dispose();
+    });
+
+    it('throws authentication errors instead of returning cached ciphertext', async function() {
+      const driver = new JsonDriver({
+        name: 'memory-auth-failure',
+        path: testDataPath,
+        ...createMemoryTransforms()
+      });
+      const secureDb = new DeepBase(driver);
+      await secureDb.connect();
+      await secureDb.set('account', 'privateKey', 'secret');
+      driver.obj.account.privateKey = { invalid: 'ciphertext' };
+
+      await assert.rejects(
+        secureDb.get('account', 'privateKey'),
+        /Authentication failed/
+      );
+      driver.obj.account.privateKey = { sealed: 'secret' };
+      await secureDb.dispose();
+    });
+  });
+
+  describe('Dispose', function() {
+    it('waits for pending writes, clears memory and releases the singleton', async function() {
+      const driver = db.getDriver(0);
+      let releaseWrite;
+      let writeStarted;
+      const writeGate = new Promise(resolve => { releaseWrite = resolve; });
+      const started = new Promise(resolve => { writeStarted = resolve; });
+      const saveToFile = driver._saveToFile.bind(driver);
+      driver._saveToFile = async () => {
+        writeStarted();
+        await writeGate;
+        return saveToFile();
+      };
+
+      const pendingWrite = db.set('account', 'address', '0x123');
+      await started;
+      const disposal = db.dispose({ clearMemory: true, releaseInstance: true });
+
+      assert.strictEqual(JsonDriver._instances[driver.fileName], driver);
+      releaseWrite();
+      await Promise.all([pendingWrite, disposal]);
+
+      assert.deepStrictEqual(driver.obj, {});
+      assert.strictEqual(JsonDriver._instances[driver.fileName], undefined);
+      assert.notStrictEqual(
+        new JsonDriver({ name: driver.name, path: driver.path }),
+        driver
+      );
+    });
+  });
+
   describe('Queue / Stack (add + pop + shift)', function() {
     it('should work as FIFO queue with add + shift', async function() {
       // Enqueue items