@stonyx/orm 0.2.1-beta.76 → 0.2.1-beta.78

package/README.md

@@ -17,6 +17,23 @@ A lightweight ORM for Stonyx projects, featuring model definitions, serializers,
 - **REST Server Integration**: Automatic route setup with customizable access control.
 - **Lifecycle Hooks**: Middleware-based before/after hooks for validation, authorization, side effects, and auditing.
 
+## Public API vs Internals
+
+Records use a proxy that exposes model attributes as direct properties. Always use direct property access for reading and writing field values:
+
+```js
+// Correct: read/write via the proxy
+const age = record.age;
+record.age = 5;
+
+// Correct: iterate fields using the record directly
+for (const key of Object.keys(record.serialize())) {
+  console.log(key, record[key]);
+}
+```
+
+All properties prefixed with `__` (`__data`, `__relationships`, `__model`, `__serializer`, `__serialized`) are **internal implementation details** and must not be accessed by consumer code. Bypassing the proxy by reading or writing `__data` directly skips type transforms and change tracking, which can lead to silent data corruption.
+
 ## Installation
 
 ```bash
@@ -417,7 +434,7 @@ Each hook receives a context object with comprehensive information:
 - It contains a deep copy of the record's state **before** the operation executes (captured before the `before` hook fires)
 - The deep copy is created via JSON serialization (`JSON.parse(JSON.stringify())`) to ensure complete isolation
 - For `delete` operations, `recordId` is provided in after hooks since the record may no longer exist in the store
-- `oldState` is captured from `record.__data` or the record itself, providing access to the raw data structure
+- `oldState` is captured as a deep copy of the record's data before the operation, providing access to the previous field values
 
 ### Usage Examples
 
@@ -520,8 +537,8 @@ afterHook('update', 'animal', async (context) => {
 
   // Track multiple field changes
   const changedFields = [];
-  for (const key in context.record.__data) {
-    if (context.oldState[key] !== context.record.__data[key]) {
+  for (const key of Object.keys(context.oldState)) {
+    if (context.oldState[key] !== context.record[key]) {
       changedFields.push(key);
     }
   }
@@ -560,9 +577,9 @@ afterHook('update', 'animal', async (context) => {
   // Compare oldState with current record to capture exact changes
   const changes = {};
   if (context.oldState) {
-    for (const [key, newValue] of Object.entries(context.record.__data || context.record)) {
-      if (context.oldState[key] !== newValue) {
-        changes[key] = { from: context.oldState[key], to: newValue };
+    for (const key of Object.keys(context.oldState)) {
+      if (context.oldState[key] !== context.record[key]) {
+        changes[key] = { from: context.oldState[key], to: context.record[key] };
       }
     }
   }

package/package.json

@@ -4,13 +4,17 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.76",
+  "version": "0.2.1-beta.78",
   "description": "",
   "main": "src/main.js",
   "type": "module",
+  "bin": {
+    "stonyx-orm": "./src/cli.js"
+  },
   "exports": {
     ".": "./src/index.js",
     "./db": "./src/exports/db.js",
+    "./standalone-db": "./src/standalone-db.js",
     "./migrate": "./src/migrate.js",
     "./commands": "./src/commands.js",
     "./hooks": "./src/hooks.js"

package/src/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone CLI for ORM database operations.
+ *
+ * Performs CRUD operations on the JSON database without requiring
+ * the full Stonyx bootstrap. Supports both file and directory modes.
+ *
+ * Usage:
+ *   stonyx-orm create <collection> <json-data>
+ *   stonyx-orm list <collection>
+ *   stonyx-orm get <collection> <id>
+ *   stonyx-orm delete <collection> <id>
+ *
+ * Configuration (environment variables):
+ *   DB_MODE      — 'file' or 'directory' (default: 'directory')
+ *   DB_PATH      — Path to db.json (default: 'db.json')
+ *   DB_DIRECTORY  — Directory name for collection files (default: 'db')
+ *
+ * Configuration (CLI flag):
+ *   --config <path>  — Path to a JSON config file with { mode, dbPath, directory }
+ */
+
+import StandaloneDB from './standalone-db.js';
+import fs from 'fs/promises';
+
+const USAGE = `Usage: stonyx-orm <command> [options]
+
+Commands:
+  create <collection> <json-data>   Create a record
+  list   <collection>               List all records
+  get    <collection> <id>          Get a record by ID
+  delete <collection> <id>          Delete a record by ID
+
+Options:
+  --config <path>   Path to JSON config file
+  --help            Show this help message
+
+Environment variables:
+  DB_MODE       'file' or 'directory' (default: 'directory')
+  DB_PATH       Path to db.json (default: 'db.json')
+  DB_DIRECTORY  Directory name for collection files (default: 'db')`;
+
+async function loadConfig(args) {
+  const config = {};
+
+  // Check for --config flag
+  const configIndex = args.indexOf('--config');
+
+  if (configIndex !== -1 && args[configIndex + 1]) {
+    const configPath = args[configIndex + 1];
+
+    try {
+      const content = await fs.readFile(configPath, 'utf-8');
+      Object.assign(config, JSON.parse(content));
+    } catch (err) {
+      console.error(`Error reading config file '${configPath}': ${err.message}`);
+      process.exit(1);
+    }
+
+    // Remove --config and its value from args
+    args.splice(configIndex, 2);
+  }
+
+  // Environment variables override config file, config file overrides defaults
+  return {
+    mode: process.env.DB_MODE || config.mode || 'directory',
+    dbPath: process.env.DB_PATH || config.dbPath || 'db.json',
+    directory: process.env.DB_DIRECTORY || config.directory || 'db',
+  };
+}
+
+function parseArgs(argv) {
+  // Strip node binary and script path
+  const args = argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  return args;
+}
+
+async function run() {
+  const args = parseArgs(process.argv);
+  const config = await loadConfig(args);
+  const db = new StandaloneDB(config);
+
+  const [command, collection, ...rest] = args;
+
+  if (!command) {
+    console.error('Error: No command specified.\n');
+    console.log(USAGE);
+    process.exit(1);
+  }
+
+  if (!collection && command !== '--help') {
+    console.error(`Error: No collection specified for '${command}' command.\n`);
+    console.log(USAGE);
+    process.exit(1);
+  }
+
+  try {
+    switch (command) {
+      case 'list': {
+        const records = await db.list(collection);
+        console.log(JSON.stringify(records, null, 2));
+        break;
+      }
+
+      case 'get': {
+        const id = rest[0];
+
+        if (!id) {
+          console.error("Error: 'get' command requires an <id> argument.");
+          process.exit(1);
+        }
+
+        const record = await db.get(collection, id);
+
+        if (!record) {
+          console.error(`Record with id '${id}' not found in '${collection}'.`);
+          process.exit(1);
+        }
+
+        console.log(JSON.stringify(record, null, 2));
+        break;
+      }
+
+      case 'create': {
+        const jsonStr = rest.join(' ');
+
+        if (!jsonStr) {
+          console.error("Error: 'create' command requires <json-data> argument.");
+          process.exit(1);
+        }
+
+        let data;
+
+        try {
+          data = JSON.parse(jsonStr);
+        } catch {
+          console.error(`Error: Invalid JSON data: ${jsonStr}`);
+          process.exit(1);
+        }
+
+        const created = await db.create(collection, data);
+        console.log(JSON.stringify(created, null, 2));
+        break;
+      }
+
+      case 'delete': {
+        const deleteId = rest[0];
+
+        if (!deleteId) {
+          console.error("Error: 'delete' command requires an <id> argument.");
+          process.exit(1);
+        }
+
+        const removed = await db.delete(collection, deleteId);
+        console.log(JSON.stringify(removed, null, 2));
+        break;
+      }
+
+      default:
+        console.error(`Error: Unknown command '${command}'.\n`);
+        console.log(USAGE);
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+run();

package/src/record.js

@@ -3,12 +3,17 @@ import { getComputedProperties } from "./serializer.js";
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from './plural-registry.js';
 export default class Record {
+  /** @private */
   __data = {};
+  /** @private */
   __relationships = {};
+  /** @private */
   __serialized = false;
 
   constructor(model, serializer) {
+    /** @private */
     this.__model = model;
+    /** @private */
     this.__serializer = serializer;
 
   }

package/src/standalone-db.js

@@ -0,0 +1,176 @@
+/**
+ * Standalone JSON database layer for CLI usage.
+ *
+ * Reads and writes directly to JSON files without requiring the Stonyx
+ * bootstrap, ORM init, or any framework dependencies. Supports both
+ * single-file and directory modes.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+export default class StandaloneDB {
+  /**
+   * @param {Object} options
+   * @param {string} options.dbPath - Path to db.json (file mode) or parent of db dir (directory mode)
+   * @param {string} [options.mode='directory'] - 'file' or 'directory'
+   * @param {string} [options.directory='db'] - Directory name when mode is 'directory'
+   */
+  constructor(options = {}) {
+    this.mode = options.mode || 'directory';
+    this.dbPath = options.dbPath || 'db.json';
+    this.directory = options.directory || 'db';
+  }
+
+  /**
+   * Resolve the directory path for directory mode.
+   */
+  getDirPath() {
+    const dbDir = path.dirname(path.resolve(this.dbPath));
+    return path.join(dbDir, this.directory);
+  }
+
+  /**
+   * List available collections by inspecting either the db.json keys
+   * or the files in the db directory.
+   */
+  async getCollections() {
+    if (this.mode === 'directory') {
+      const dirPath = this.getDirPath();
+
+      try {
+        const files = await fs.readdir(dirPath);
+        return files
+          .filter(f => f.endsWith('.json'))
+          .map(f => f.replace('.json', ''));
+      } catch {
+        return [];
+      }
+    }
+
+    // File mode — read db.json and return its top-level keys
+    try {
+      const data = await this._readJSON(this.dbPath);
+      return Object.keys(data).filter(key => Array.isArray(data[key]));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Read all records for a collection.
+   */
+  async readCollection(collection) {
+    if (this.mode === 'directory') {
+      const filePath = path.join(this.getDirPath(), `${collection}.json`);
+      return this._readJSON(filePath);
+    }
+
+    const data = await this._readJSON(this.dbPath);
+    return data[collection] || [];
+  }
+
+  /**
+   * Write all records for a collection.
+   */
+  async writeCollection(collection, records) {
+    if (this.mode === 'directory') {
+      const dirPath = this.getDirPath();
+      await fs.mkdir(dirPath, { recursive: true });
+
+      const filePath = path.join(dirPath, `${collection}.json`);
+      await this._writeJSON(filePath, records);
+      return;
+    }
+
+    // File mode — read full db, update collection, write back
+    let data;
+
+    try {
+      data = await this._readJSON(this.dbPath);
+    } catch {
+      data = {};
+    }
+
+    data[collection] = records;
+    await this._writeJSON(this.dbPath, data);
+  }
+
+  /**
+   * Get a single record by id.
+   */
+  async get(collection, id) {
+    const records = await this.readCollection(collection);
+    const numericId = Number(id);
+
+    return records.find(r =>
+      r.id === id || r.id === numericId
+    ) || null;
+  }
+
+  /**
+   * List all records in a collection.
+   */
+  async list(collection) {
+    return this.readCollection(collection);
+  }
+
+  /**
+   * Create a new record. Auto-assigns an integer id if none provided.
+   */
+  async create(collection, data) {
+    const records = await this.readCollection(collection);
+
+    if (!data.id) {
+      const maxId = records.reduce((max, r) => {
+        const rid = typeof r.id === 'number' ? r.id : 0;
+        return rid > max ? rid : max;
+      }, 0);
+
+      data.id = maxId + 1;
+    }
+
+    // Check for duplicate id
+    const existing = records.find(r => r.id === data.id);
+    if (existing) {
+      throw new Error(`Record with id ${data.id} already exists in '${collection}'`);
+    }
+
+    records.push(data);
+    await this.writeCollection(collection, records);
+
+    return data;
+  }
+
+  /**
+   * Delete a record by id.
+   */
+  async delete(collection, id) {
+    const records = await this.readCollection(collection);
+    const numericId = Number(id);
+
+    const index = records.findIndex(r =>
+      r.id === id || r.id === numericId
+    );
+
+    if (index === -1) {
+      throw new Error(`Record with id '${id}' not found in '${collection}'`);
+    }
+
+    const [removed] = records.splice(index, 1);
+    await this.writeCollection(collection, records);
+
+    return removed;
+  }
+
+  // -- Private helpers --
+
+  async _readJSON(filePath) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content);
+  }
+
+  async _writeJSON(filePath, data) {
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  }
+}