deepbase-json 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 mclasen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# deepbase-json
+
+JSON filesystem driver for DeepBase.
+
+## Installation
+
+```bash
+npm install deepbase
+# deepbase-json is included automatically as a dependency
+```
+
+## Description
+
+Stores data in JSON files on the filesystem. Perfect for:
+
+- ✅ Development and testing
+- ✅ Small to medium datasets
+- ✅ Human-readable data
+- ✅ No external dependencies needed
+- ✅ Version control friendly
+
+## Usage
+
+```javascript
+import DeepBase, { JsonDriver } from 'deepbase';
+
+const db = new DeepBase(new JsonDriver({
+  path: './data',
+  name: 'mydb'
+}));
+
+await db.connect();
+
+await db.set('users', 'alice', { name: 'Alice', age: 30 });
+const alice = await db.get('users', 'alice');
+```
+
+## Options
+
+```javascript
+new JsonDriver({
+  path: './data',              // Directory to store JSON files
+  name: 'default',            // Filename (without .json)
+  nidAlphabet: 'ABC...',      // Alphabet for ID generation
+  nidLength: 10,              // Length of generated IDs
+  stringify: JSON.stringify,  // Custom JSON serializer
+  parse: JSON.parse          // Custom JSON parser
+})
+```
+
+## Features
+
+### Singleton Pattern
+
+Multiple instances pointing to the same file will share the same data:
+
+```javascript
+const db1 = new DeepBase(new JsonDriver({ name: 'mydb' }));
+const db2 = new DeepBase(new JsonDriver({ name: 'mydb' }));
+// Both use the same underlying data
+```
+
+### Custom Serialization
+
+Support for circular references and custom serialization:
+
+```javascript
+import CircularJSON from 'circular-json';
+
+const db = new DeepBase(new JsonDriver({
+  stringify: (obj) => CircularJSON.stringify(obj, null, 4),
+  parse: CircularJSON.parse
+}));
+```
+
+### Atomic Writes
+
+Uses `steno` for atomic file writes, preventing data corruption.
+
+## File Structure
+
+Data is stored as JSON files:
+
+```
+data/
+  mydb.json
+  users.json
+  config.json
+```
+
+## Example Data
+
+```json
+{
+  "users": {
+    "alice": {
+      "name": "Alice",
+      "age": 30
+    },
+    "bob": {
+      "name": "Bob",
+      "age": 25
+    }
+  },
+  "config": {
+    "theme": "dark",
+    "lang": "en"
+  }
+}
+```
+
+## Use Cases
+
+- **Development**: Quick prototyping without database setup
+- **Testing**: Easy to inspect and modify test data
+- **Small Apps**: Perfect for configuration and small datasets
+- **Backup**: Use as secondary driver for data backup
+- **Version Control**: Human-readable, git-friendly format
+
+## Migration
+
+Easy to migrate from JSON to other drivers:
+
+```javascript
+import DeepBase, { JsonDriver } from 'deepbase';
+import MongoDriver from 'deepbase-mongodb';
+
+const db = new DeepBase([
+  new JsonDriver({ path: './data' }),
+  new MongoDriver({ url: 'mongodb://localhost:27017' })
+]);
+
+await db.connect();
+await db.migrate(0, 1); // Migrate JSON to MongoDB
+```
+
+## License
+
+MIT - Copyright (c) Martin Clasen
+

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "deepbase-json",
+  "version": "3.0.0",
+  "description": "⚡ DeepBase JSON - filesystem driver",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    }
+  },
+  "dependencies": {
+    "steno": "^0.4.4"
+  },
+  "peerDependencies": {
+    "deepbase": "^3.0.0"
+  },
+  "scripts": {
+    "test": "mocha test/test.js"
+  },
+  "devDependencies": {
+    "mocha": "^10.8.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clasen/DeepBase.git"
+  },
+  "keywords": [
+    "deepbase",
+    "json",
+    "filesystem",
+    "driver",
+    "database",
+    "persist",
+    "nested",
+    "objects"
+  ],
+  "author": "Martin Clasen",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/clasen/DeepBase/issues"
+  },
+  "homepage": "https://github.com/clasen/DeepBase#readme"
+}
+

package/src/JsonDriver.js

@@ -0,0 +1,141 @@
+import { DeepBaseDriver } from 'deepbase';
+import steno from 'steno';
+import fs from 'fs';
+import * as pathModule from 'path';
+
+export class JsonDriver extends DeepBaseDriver {
+  static _instances = {};
+  
+  constructor({name, path, stringify, parse, ...opts} = {}) {
+    super(opts);
+    
+    this.name = name || "default";
+    this.path = path || './db';
+    this.stringify = stringify || ((obj) => JSON.stringify(obj, null, 4));
+    this.parse = parse || JSON.parse;
+    
+    this.path = pathModule.resolve(this.path);
+    this.fileName = pathModule.join(this.path, `${this.name}.json`);
+    
+    // Singleton pattern per file
+    if (JsonDriver._instances[this.fileName]) {
+      return JsonDriver._instances[this.fileName];
+    }
+    
+    this.obj = {};
+    JsonDriver._instances[this.fileName] = this;
+  }
+  
+  async connect() {
+    if (!fs.existsSync(this.path)) {
+      fs.mkdirSync(this.path, { recursive: true });
+    }
+    
+    if (fs.existsSync(this.fileName)) {
+      const fileContent = fs.readFileSync(this.fileName, "utf8");
+      this.obj = fileContent ? this.parse(fileContent) : {};
+    }
+  }
+  
+  async disconnect() {
+    await this._saveToFile();
+  }
+  
+  async get(...args) {
+    const value = this._getRecursive(this.obj, args.slice());
+    return typeof value === 'object' && value !== null 
+      ? this.parse(this.stringify(value)) 
+      : value;
+  }
+  
+  async set(...args) {
+    if (args.length < 2) {
+      this.obj = args[0];
+      await this._saveToFile();
+      return [];
+    }
+    
+    const keys = args.slice(0, -1);
+    const value = args[args.length - 1];
+    
+    this._setRecursive(this.obj, keys, value);
+    await this._saveToFile();
+    return keys;
+  }
+  
+  async del(...keys) {
+    if (keys.length === 0) {
+      this.obj = {};
+      return this._saveToFile();
+    }
+    
+    const key = keys.pop();
+    const parentObj = this._getRecursive(this.obj, keys.slice());
+    
+    if (parentObj && parentObj.hasOwnProperty(key)) {
+      delete parentObj[key];
+      return this._saveToFile();
+    }
+  }
+  
+  async inc(...args) {
+    const i = args.pop();
+    return this.upd(...args, n => n + i);
+  }
+  
+  async dec(...args) {
+    const i = args.pop();
+    return this.upd(...args, n => n - i);
+  }
+  
+  async add(...keys) {
+    const value = keys.pop();
+    const id = this.nanoid();
+    await this.set(...[...keys, id], value);
+    return [...keys, id];
+  }
+  
+  async upd(...args) {
+    const func = args.pop();
+    return this.set(...args, func(await this.get(...args)));
+  }
+  
+  _setRecursive(obj, keys, value) {
+    if (keys.length === 1) {
+      obj[keys[0]] = value;
+      return;
+    }
+    
+    const key = keys.shift();
+    if (!obj.hasOwnProperty(key) || typeof obj[key] !== "object") {
+      obj[key] = {};
+    }
+    
+    this._setRecursive(obj[key], keys, value);
+  }
+  
+  _getRecursive(obj, keys) {
+    if (keys.length === 0) return obj;
+    if (keys.length === 1) {
+      return obj === null || obj[keys[0]] === undefined ? null : obj[keys[0]];
+    }
+    
+    const key = keys.shift();
+    if (!obj.hasOwnProperty(key)) return null;
+    
+    return this._getRecursive(obj[key], keys);
+  }
+  
+  async _saveToFile() {
+    return new Promise((resolve, reject) => {
+      const serializedData = this.stringify(this.obj);
+      steno.writeFile(this.fileName, serializedData, err => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+}
+
+export default JsonDriver;
+

package/src/index.js

@@ -0,0 +1,4 @@
+import { JsonDriver } from './JsonDriver.js';
+export { JsonDriver } from './JsonDriver.js';
+export default JsonDriver;
+

package/test/test.js

@@ -0,0 +1,248 @@
+import assert from 'assert';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { DeepBase } from '../../core/src/index.js';
+import { JsonDriver } from '../src/JsonDriver.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const testDataPath = path.join(__dirname, 'test-data');
+
+describe('JsonDriver', function() {
+  let db;
+  let testCounter = 0;
+
+  before(function() {
+    // Clean up test data before all tests
+    if (fs.existsSync(testDataPath)) {
+      fs.rmSync(testDataPath, { recursive: true, force: true });
+    }
+  });
+
+  beforeEach(async function() {
+    // Use unique name for each test to avoid singleton conflicts
+    testCounter++;
+    db = new DeepBase(new JsonDriver({ 
+      name: `test-${testCounter}`, 
+      path: testDataPath 
+    }));
+    await db.connect();
+  });
+
+  afterEach(async function() {
+    await db.disconnect();
+    if (fs.existsSync(testDataPath)) {
+      fs.rmSync(testDataPath, { recursive: true, force: true });
+    }
+  });
+
+  describe('Basic Operations', function() {
+    it('should set and get a simple value', async function() {
+      await db.set('key', 'value');
+      const result = await db.get('key');
+      assert.strictEqual(result, 'value');
+    });
+
+    it('should set and get nested values', async function() {
+      await db.set('user', 'name', 'Alice');
+      await db.set('user', 'age', 30);
+      
+      const name = await db.get('user', 'name');
+      const age = await db.get('user', 'age');
+      
+      assert.strictEqual(name, 'Alice');
+      assert.strictEqual(age, 30);
+    });
+
+    it('should get entire nested object', async function() {
+      await db.set('user', 'name', 'Bob');
+      await db.set('user', 'age', 25);
+      
+      const user = await db.get('user');
+      assert.deepStrictEqual(user, { name: 'Bob', age: 25 });
+    });
+
+    it('should return null for non-existent keys', async function() {
+      const result = await db.get('nonexistent');
+      assert.strictEqual(result, null);
+    });
+  });
+
+  describe('Delete Operations', function() {
+    it('should delete a key', async function() {
+      await db.set('temp', 'value');
+      await db.del('temp');
+      
+      const result = await db.get('temp');
+      assert.strictEqual(result, null);
+    });
+
+    it('should delete nested key', async function() {
+      await db.set('user', 'name', 'Alice');
+      await db.set('user', 'age', 30);
+      await db.del('user', 'age');
+      
+      const user = await db.get('user');
+      assert.deepStrictEqual(user, { name: 'Alice' });
+    });
+
+    it('should clear all data', async function() {
+      await db.set('key1', 'value1');
+      await db.set('key2', 'value2');
+      await db.del();
+      
+      const all = await db.get();
+      assert.deepStrictEqual(all, {});
+    });
+  });
+
+  describe('Add Operation', function() {
+    it('should add item with auto-generated ID', async function() {
+      const path = await db.add('users', { name: 'Charlie' });
+      
+      assert.strictEqual(path.length, 2);
+      assert.strictEqual(path[0], 'users');
+      assert.strictEqual(typeof path[1], 'string');
+      assert.strictEqual(path[1].length, 10);
+      
+      const user = await db.get(...path);
+      assert.deepStrictEqual(user, { name: 'Charlie' });
+    });
+
+    it('should add multiple items with unique IDs', async function() {
+      const path1 = await db.add('items', { value: 1 });
+      const path2 = await db.add('items', { value: 2 });
+      
+      assert.notStrictEqual(path1[1], path2[1]);
+    });
+  });
+
+  describe('Increment/Decrement', function() {
+    it('should increment a value', async function() {
+      await db.set('counter', 10);
+      await db.inc('counter', 5);
+      
+      const result = await db.get('counter');
+      assert.strictEqual(result, 15);
+    });
+
+    it('should decrement a value', async function() {
+      await db.set('counter', 20);
+      await db.dec('counter', 8);
+      
+      const result = await db.get('counter');
+      assert.strictEqual(result, 12);
+    });
+
+    it('should increment nested value', async function() {
+      await db.set('user', 'balance', 100);
+      await db.inc('user', 'balance', 50);
+      
+      const balance = await db.get('user', 'balance');
+      assert.strictEqual(balance, 150);
+    });
+  });
+
+  describe('Update Operation', function() {
+    it('should update value with function', async function() {
+      await db.set('name', 'alice');
+      await db.upd('name', name => name.toUpperCase());
+      
+      const result = await db.get('name');
+      assert.strictEqual(result, 'ALICE');
+    });
+
+    it('should update nested value with function', async function() {
+      await db.set('user', 'age', 25);
+      await db.upd('user', 'age', age => age + 1);
+      
+      const age = await db.get('user', 'age');
+      assert.strictEqual(age, 26);
+    });
+  });
+
+  describe('Keys, Values, Entries', function() {
+    beforeEach(async function() {
+      await db.set('users', 'alice', { age: 30 });
+      await db.set('users', 'bob', { age: 25 });
+    });
+
+    it('should get keys', async function() {
+      const keys = await db.keys('users');
+      assert.deepStrictEqual(keys.sort(), ['alice', 'bob']);
+    });
+
+    it('should get values', async function() {
+      const values = await db.values('users');
+      assert.strictEqual(values.length, 2);
+      assert.ok(values.some(v => v.age === 30));
+      assert.ok(values.some(v => v.age === 25));
+    });
+
+    it('should get entries', async function() {
+      const entries = await db.entries('users');
+      assert.strictEqual(entries.length, 2);
+      assert.ok(entries.some(([k, v]) => k === 'alice' && v.age === 30));
+      assert.ok(entries.some(([k, v]) => k === 'bob' && v.age === 25));
+    });
+  });
+
+  describe('Persistence', function() {
+    it('should persist data to file', async function() {
+      // Use a separate db for this test
+      const persistDb = new DeepBase(new JsonDriver({ 
+        name: 'persist-test', 
+        path: testDataPath 
+      }));
+      await persistDb.connect();
+      await persistDb.set('persistent', 'data');
+      await persistDb.disconnect();
+      
+      const filePath = path.join(testDataPath, 'persist-test.json');
+      assert.ok(fs.existsSync(filePath));
+      
+      const content = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      assert.deepStrictEqual(content, { persistent: 'data' });
+    });
+
+    it('should load existing data on connect', async function() {
+      // Use a separate db for this test
+      const db1 = new DeepBase(new JsonDriver({ 
+        name: 'reload-test', 
+        path: testDataPath 
+      }));
+      await db1.connect();
+      await db1.set('existing', 'value');
+      await db1.disconnect();
+      
+      // Create new instance pointing to same file
+      const db2 = new DeepBase(new JsonDriver({ 
+        name: 'reload-test', 
+        path: testDataPath 
+      }));
+      await db2.connect();
+      
+      const result = await db2.get('existing');
+      assert.strictEqual(result, 'value');
+      
+      await db2.disconnect();
+    });
+  });
+
+  describe('Singleton Pattern', function() {
+    it('should return same instance for same file', function() {
+      const driver1 = new JsonDriver({ name: 'singleton', path: testDataPath });
+      const driver2 = new JsonDriver({ name: 'singleton', path: testDataPath });
+      
+      assert.strictEqual(driver1, driver2);
+    });
+
+    it('should return different instances for different files', function() {
+      const driver1 = new JsonDriver({ name: 'file1', path: testDataPath });
+      const driver2 = new JsonDriver({ name: 'file2', path: testDataPath });
+      
+      assert.notStrictEqual(driver1, driver2);
+    });
+  });
+});
+