starddb 1.0.0 → 1.0.1

package/README.md

@@ -48,7 +48,7 @@ await db.close();
 - `maxQueueSize` — Maximum queued operations (default: 10000)
 
 **Methods:**
-- `update(method, value)` — Queue an operation. Methods: `set`, `add`, `sub`, `mult`, `div`
+- `update(method, value)` — Queue an operation. Methods: `set`, `add`, `sub`, `mult`, `div`, `push`
 - `flush()` — Returns a promise that resolves when all queued operations are processed
 
 ### StarDDB(database, saveTime, databaseHook, options)
@@ -62,3 +62,24 @@ await db.close();
 - `db()` — Get the database hook (object of StarDDBField instances)
 - `flush()` — Wait for all field operations to complete
 - `close()` — Flush, save, and stop the background save interval
+- `addField(keyPath, value)` — Add a new field to a nested dict at runtime. `keyPath` is a dot-separated string (`"players.newGuy"`) or array of keys. Plain object values are automatically crawled into `StarDDBField` instances. Throws if the path doesn't exist or the key already exists.
+
+**`push` operation:**
+```javascript
+// Append a value to an array field
+hook.scores.update("push", 30);
+```
+
+**`addField` examples:**
+```javascript
+// Add a primitive or array field
+db.addField("players.newGuy", 0);
+db.addField("players.newGuy.inventory", []);
+
+// Add a nested object (crawled automatically)
+db.addField("players.newGuy", { coins: 0, level: 1 });
+hook.players.newGuy.coins.update("add", 5);
+
+// Use an array of keys to avoid dot ambiguity
+db.addField(["some.weird.key", "nested"], 42);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starddb",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A lightweight JSON document database with field-level operation queuing and concurrency support",
   "main": "stardb.js",
   "files": [

package/stardb.js

@@ -2,7 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const lockfile = require('proper-lockfile');
 
-const VALID_METHODS = new Set(['set', 'add', 'sub', 'mult', 'div']);
+const VALID_METHODS = new Set(['set', 'add', 'sub', 'mult', 'div', 'push']);
 const MAX_QUEUE_SIZE = 10000;
 const MAX_RECURSION_DEPTH = 100;
 
@@ -61,6 +61,13 @@ class StarDDBField {
           }
           this.value /= item.value;
           break;
+        case 'push':
+          if (!Array.isArray(this.value)) {
+            console.error('[StarDDB] push called on non-array field');
+            break;
+          }
+          this.value.push(item.value);
+          break;
         default:
           console.error(`[StarDDB] Unknown method "${item.method}" dropped`);
       }
@@ -202,6 +209,36 @@ class StarDDB {
     }
   }
 
+  /**
+   * Add a new field to a nested dict at runtime.
+   * keyPath can be a dot-separated string ("players.newPlayer") or an array of keys.
+   * value can be a primitive, array, or plain object (which will be crawled into StarDDBFields).
+   */
+  addField(keyPath, value) {
+    const keys = Array.isArray(keyPath) ? keyPath : keyPath.split('.');
+    if (keys.length === 0) throw new Error('keyPath must not be empty');
+
+    let node = this.databaseHook;
+    for (let i = 0; i < keys.length - 1; i++) {
+      const k = keys[i];
+      if (!(k in node) || node[k] instanceof StarDDBField) {
+        throw new Error(`Path "${keys.slice(0, i + 1).join('.')}" does not exist or is a leaf field, not a nested object`);
+      }
+      node = node[k];
+    }
+
+    const lastKey = keys[keys.length - 1];
+    if (lastKey in node) {
+      throw new Error(`Field "${keys.join('.')}" already exists. Use .update() to modify existing fields.`);
+    }
+
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      node[lastKey] = _crawlDb(Object.assign({}, value));
+    } else {
+      node[lastKey] = new StarDDBField(value);
+    }
+  }
+
   async close() {
     clearInterval(this._saveInterval);
     await this.flush();