starddb 1.0.0

package/README.md

@@ -0,0 +1,64 @@
+# StarDDB (Star Document-database)
+
+> "Shoot for the moon. Even if you miss, you'll land among the stars." - Norman Vincent Peale
+
+StarDDB is a simple to use, lightweight (single file implementation) DB for efficient JSON-like storage management.
+
+## Features
+
+- Concurrency support via field-level operation queuing
+- Easy-to-use API
+- Automatic background persistence
+- Nested document support
+- File locking for multi-process safety
+- Path traversal protection
+
+## Installation
+
+```bash
+npm install starddb
+```
+
+## Quick Start
+
+```javascript
+const { StarDDBField, StarDDB } = require("starddb");
+
+// Create a field and queue operations
+const field = new StarDDBField(0);
+field.update("set", 1);
+field.update("mult", 5);
+field.update("div", 0.5);
+await field.flush();
+console.log(field.value);  // 10
+
+// Use with a database file
+const db = new StarDDB("./data.json", 5);
+const hook = db.db();
+hook.health.update("sub", 30);
+hook.mana.update("mult", 2);
+await db.close();
+```
+
+## API
+
+### StarDDBField(value, maxQueueSize)
+
+- `value` — Initial value (any JSON-serializable type)
+- `maxQueueSize` — Maximum queued operations (default: 10000)
+
+**Methods:**
+- `update(method, value)` — Queue an operation. Methods: `set`, `add`, `sub`, `mult`, `div`
+- `flush()` — Returns a promise that resolves when all queued operations are processed
+
+### StarDDB(database, saveTime, databaseHook, options)
+
+- `database` — Path to the JSON database file
+- `saveTime` — Seconds between automatic saves
+- `databaseHook` — Optional pre-loaded object (skips file read)
+- `options.safeRoot` — Optional root directory to restrict path traversal
+
+**Methods:**
+- `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

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "starddb",
+  "version": "1.0.0",
+  "description": "A lightweight JSON document database with field-level operation queuing and concurrency support",
+  "main": "stardb.js",
+  "files": [
+    "stardb.js"
+  ],
+  "scripts": {
+    "test": "node tests/single_field.js && node tests/multi_field.js && node tests/test_crawl.js && node tests/test_errors.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucidityai/stardb.git"
+  },
+  "keywords": [
+    "json",
+    "database",
+    "document-db",
+    "queue",
+    "concurrency",
+    "lightweight",
+    "embedded"
+  ],
+  "author": "lucidityai",
+  "license": "MIT",
+  "dependencies": {
+    "proper-lockfile": "^4.1.2"
+  }
+}

package/stardb.js

@@ -0,0 +1,212 @@
+const fs = require('fs');
+const path = require('path');
+const lockfile = require('proper-lockfile');
+
+const VALID_METHODS = new Set(['set', 'add', 'sub', 'mult', 'div']);
+const MAX_QUEUE_SIZE = 10000;
+const MAX_RECURSION_DEPTH = 100;
+
+class StarDDBField {
+  constructor(value = null, maxQueueSize = MAX_QUEUE_SIZE) {
+    this.value = value;
+    this.queue = [];
+    this._running = false;
+    this._processingDone = Promise.resolve();
+    this._maxQueueSize = maxQueueSize;
+  }
+
+  update(method, value) {
+    if (!VALID_METHODS.has(method)) {
+      throw new Error(`Invalid operation "${method}". Valid operations: ${[...VALID_METHODS].join(', ')}`);
+    }
+    if (method === 'div' && value === 0) {
+      throw new Error('Division by zero is not allowed');
+    }
+    this.queue.push({ method, value });
+    if (this.queue.length > this._maxQueueSize) {
+      this.queue.pop(); // Remove the item we just pushed
+      throw new Error(`Queue is full (max size: ${this._maxQueueSize}). Wait for pending operations to complete.`);
+    }
+    if (!this._running) {
+      this._running = true;
+      this._processingDone = this._runList();
+    }
+  }
+
+  async _runList() {
+    while (true) {
+      const item = this.queue.shift();
+      if (!item) {
+        this._running = false;
+        return;
+      }
+
+      switch (item.method) {
+        case 'set':
+          this.value = item.value;
+          break;
+        case 'add':
+          this.value += item.value;
+          break;
+        case 'sub':
+          this.value -= item.value;
+          break;
+        case 'mult':
+          this.value *= item.value;
+          break;
+        case 'div':
+          if (item.value === 0) {
+            console.error('[StarDDB] Division by zero skipped');
+            break;
+          }
+          this.value /= item.value;
+          break;
+        default:
+          console.error(`[StarDDB] Unknown method "${item.method}" dropped`);
+      }
+
+      await new Promise(resolve => setImmediate(resolve));
+    }
+  }
+
+  /**
+   * Returns a promise that resolves when all queued operations are processed.
+   */
+  async flush() {
+    await this._processingDone;
+  }
+}
+
+function _crawlDb(hook, depth = 0) {
+  if (depth > MAX_RECURSION_DEPTH) {
+    throw new Error(`Max recursion depth (${MAX_RECURSION_DEPTH}) exceeded. Nested objects are too deep.`);
+  }
+  for (const key in hook) {
+    if (typeof hook[key] === 'object' && hook[key] !== null && !Array.isArray(hook[key])) {
+      _crawlDb(hook[key], depth + 1);
+    } else {
+      hook[key] = new StarDDBField(hook[key]);
+    }
+  }
+  return hook;
+}
+
+function _serializeDb(hook, depth = 0) {
+  if (depth > MAX_RECURSION_DEPTH) {
+    throw new Error(`Max recursion depth (${MAX_RECURSION_DEPTH}) exceeded during serialization.`);
+  }
+  const result = {};
+  for (const key in hook) {
+    if (hook[key] instanceof StarDDBField) {
+      result[key] = hook[key].value;
+    } else if (typeof hook[key] === 'object' && hook[key] !== null) {
+      result[key] = _serializeDb(hook[key], depth + 1);
+    } else {
+      result[key] = hook[key];
+    }
+  }
+  return result;
+}
+
+async function _safeSave(dbPath, databaseHook) {
+  let release = null;
+  try {
+    release = await lockfile.lock(dbPath, { stale: 10000 });
+    const data = _serializeDb(databaseHook);
+    fs.writeFileSync(dbPath, JSON.stringify(data), 'utf8');
+  } catch (err) {
+    console.error(`[StarDDB] Failed to save database to ${dbPath}:`, err.message);
+    throw err;
+  } finally {
+    if (release) {
+      try {
+        await release();
+      } catch (err) {
+        console.error(`[StarDDB] Failed to release lock on ${dbPath}:`, err.message);
+      }
+    }
+  }
+}
+
+/**
+ * Sanitize and validate a database path.
+ * If safeRoot is provided, ensures the resolved path stays within it.
+ */
+function _sanitizePath(dbPath, safeRoot = null) {
+  const resolved = path.resolve(dbPath);
+  if (safeRoot !== null) {
+    const root = path.resolve(safeRoot);
+    if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+      throw new Error(
+        `Database path escapes safe root "${root}". Resolved path: "${resolved}"`
+      );
+    }
+  }
+  return resolved;
+}
+
+class StarDDB {
+  constructor(database, saveTime, databaseHook = null, options = {}) {
+    this.database = _sanitizePath(database, options.safeRoot || null);
+
+    if (databaseHook === null) {
+      if (!fs.existsSync(this.database)) {
+        throw new Error(`Database file does not exist: ${this.database}`);
+      }
+      try {
+        const data = fs.readFileSync(this.database, 'utf8');
+        databaseHook = JSON.parse(data);
+      } catch (err) {
+        console.error(`[StarDDB] Failed to read database file ${this.database}:`, err.message);
+        throw err;
+      }
+    }
+
+    this.databaseHook = _crawlDb(databaseHook);
+
+    this._saveInterval = setInterval(async () => {
+      try {
+        await _safeSave(this.database, this.databaseHook);
+      } catch (err) {
+        // Error already logged in _safeSave
+      }
+    }, saveTime * 1000);
+  }
+
+  db() {
+    return this.databaseHook;
+  }
+
+  /**
+   * Wait for all pending field operations to complete.
+   */
+  async flush() {
+    const promises = [];
+    for (const key in this.databaseHook) {
+      if (this.databaseHook[key] instanceof StarDDBField) {
+        promises.push(this.databaseHook[key].flush());
+      } else if (typeof this.databaseHook[key] === 'object' && this.databaseHook[key] !== null) {
+        this._collectFlush(this.databaseHook[key], promises);
+      }
+    }
+    await Promise.all(promises);
+  }
+
+  _collectFlush(node, promises) {
+    for (const key in node) {
+      if (node[key] instanceof StarDDBField) {
+        promises.push(node[key].flush());
+      } else if (typeof node[key] === 'object' && node[key] !== null) {
+        this._collectFlush(node[key], promises);
+      }
+    }
+  }
+
+  async close() {
+    clearInterval(this._saveInterval);
+    await this.flush();
+    await _safeSave(this.database, this.databaseHook);
+  }
+}
+
+module.exports = { StarDDBField, StarDDB };