@stonyx/orm 0.2.1-beta.8 → 0.2.1-beta.81

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-orm/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-orm/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/orm.svg)](https://www.npmjs.com/package/@stonyx/orm)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # @stonyx/orm
 
 A lightweight ORM for Stonyx projects, featuring model definitions, serializers, relationships, transforms, and optional REST server integration.
@@ -13,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
@@ -109,6 +130,22 @@ export default class OwnerModel extends Model {
 }
 ```
 
+### Overriding Plural Names
+
+By default, model names are auto-pluralized for REST routes, JSON:API URLs, and DB table names (e.g., `animal` → `animals`). When auto-pluralization produces the wrong result, override it with `static pluralName`:
+
+```js
+import { Model, attr } from '@stonyx/orm';
+
+export default class PersonModel extends Model {
+  static pluralName = 'people';
+
+  name = attr('string');
+}
+```
+
+The override is picked up automatically during ORM initialization. All routes, JSON:API type references, and MySQL table names will use the overridden value.
+
 ## Serializers
 
 Based on the following sample payload structure which represents a poorly structure third-party data source:
@@ -207,6 +244,27 @@ Set the `MYSQL_HOST` environment variable to enable MySQL persistence. The ORM l
 | `stonyx db:migrate:rollback` | Rollback the most recent migration |
 | `stonyx db:migrate:status` | Show migration status |
 
+### Running MySQL Tests
+
+The ORM includes integration tests that run against a real MySQL database. These are optional — all other tests work without MySQL.
+
+**One-time setup:**
+
+```bash
+# Requires local MySQL 8.0+ running
+./scripts/setup-test-db.sh
+```
+
+This creates a `stonyx_orm_test` database with a `stonyx_test` user. Safe to re-run.
+
+**Running tests:**
+
+```bash
+npm test
+```
+
+MySQL integration tests run automatically when MySQL is available. In CI (where `CI=true`), they skip gracefully.
+
 ## REST Server Integration
 
 The ORM can automatically register REST routes using your access classes.
@@ -376,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
 
@@ -479,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);
     }
   }
@@ -519,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/config/environment.js

@@ -4,6 +4,7 @@ const {
   ORM_REST_ROUTE,
   ORM_SERIALIZER_PATH,
   ORM_TRANSFORM_PATH,
+  ORM_VIEW_PATH,
   ORM_USE_REST_SERVER,
   DB_AUTO_SAVE,
   DB_FILE,
@@ -36,7 +37,8 @@ export default {
     access: ORM_ACCESS_PATH ?? './access', // Optional for restServer access hooks
     model: ORM_MODEL_PATH ?? './models',
     serializer: ORM_SERIALIZER_PATH ?? './serializers',
-    transform: ORM_TRANSFORM_PATH ?? './transforms'
+    transform: ORM_TRANSFORM_PATH ?? './transforms',
+    view: ORM_VIEW_PATH ?? './views'
   },
   mysql: MYSQL_HOST ? {
     host: MYSQL_HOST ?? 'localhost',

package/package.json

@@ -4,13 +4,17 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.8",
+  "version": "0.2.1-beta.81",
   "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"
@@ -24,6 +28,11 @@
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "files": [
+    "src",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -33,21 +42,26 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "stonyx": "0.2.3-beta.2",
-    "@stonyx/events": "0.1.1-beta.3",
-    "@stonyx/cron": "0.2.1-beta.4"
+    "@stonyx/cron": "0.2.1-beta.29",
+    "@stonyx/events": "0.1.1-beta.9",
+    "stonyx": "0.2.3-beta.11"
   },
   "peerDependencies": {
+    "@stonyx/rest-server": ">=0.2.1-beta.14",
     "mysql2": "^3.0.0"
   },
   "peerDependenciesMeta": {
     "mysql2": {
       "optional": true
+    },
+    "@stonyx/rest-server": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.5",
-    "@stonyx/utils": "0.2.3-beta.3",
+    "@stonyx/rest-server": "0.2.1-beta.30",
+    "@stonyx/utils": "0.2.3-beta.7",
+    "mysql2": "^3.20.0",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/src/aggregates.js

@@ -0,0 +1,93 @@
+export class AggregateProperty {
+  constructor(aggregateType, relationship, field) {
+    this.aggregateType = aggregateType;
+    this.relationship = relationship;
+    this.field = field;
+    this.mysqlFunction = aggregateType.toUpperCase();
+    this.resultType = aggregateType === 'avg' ? 'float' : 'number';
+  }
+
+  compute(relatedRecords) {
+    if (!relatedRecords || !Array.isArray(relatedRecords) || relatedRecords.length === 0) {
+      if (this.aggregateType === 'min' || this.aggregateType === 'max') return null;
+      return 0;
+    }
+
+    switch (this.aggregateType) {
+      case 'count':
+        return relatedRecords.length;
+
+      case 'sum':
+        return relatedRecords.reduce((acc, record) => {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          return acc + (isNaN(val) ? 0 : val);
+        }, 0);
+
+      case 'avg': {
+        let sum = 0;
+        let count = 0;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val)) {
+            sum += val;
+            count++;
+          }
+        }
+        return count === 0 ? 0 : sum / count;
+      }
+
+      case 'min': {
+        let min = null;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val) && (min === null || val < min)) min = val;
+        }
+        return min;
+      }
+
+      case 'max': {
+        let max = null;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val) && (max === null || val > max)) max = val;
+        }
+        return max;
+      }
+
+      default:
+        return null;
+    }
+  }
+}
+
+export function count(relationship) {
+  return new AggregateProperty('count', relationship);
+}
+
+export function avg(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('avg', relationshipOrField, field);
+  }
+  return new AggregateProperty('avg', undefined, relationshipOrField);
+}
+
+export function sum(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('sum', relationshipOrField, field);
+  }
+  return new AggregateProperty('sum', undefined, relationshipOrField);
+}
+
+export function min(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('min', relationshipOrField, field);
+  }
+  return new AggregateProperty('min', undefined, relationshipOrField);
+}
+
+export function max(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('max', relationshipOrField, field);
+  }
+  return new AggregateProperty('max', undefined, relationshipOrField);
+}

package/src/belongs-to.js

@@ -11,7 +11,7 @@ export default function belongsTo(modelName) {
   const pendingHasManyQueue = relationships.get('pending');
   const pendingBelongsToQueue = relationships.get('pendingBelongsTo');
 
-  return (sourceRecord, rawData, options) => {
+  const fn = (sourceRecord, rawData, options) => {
     if (!rawData) return null;
 
     const { __name: sourceModelName } = sourceRecord.__model;
@@ -21,9 +21,13 @@ export default function belongsTo(modelName) {
     const modelStore = store.get(modelName);
 
     // Try to get existing record
-    const output = typeof rawData === 'object'
-      ? createRecord(modelName, rawData, options)
-      : modelStore.get(rawData);
+    let output;
+
+    if (typeof rawData === 'object') {
+      output = createRecord(modelName, rawData, options);
+    } else if (modelStore) {
+      output = modelStore.get(rawData);
+    }
 
     // If not found and is a string ID, register as pending
     if (!output && typeof rawData !== 'object') {
@@ -60,4 +64,7 @@ export default function belongsTo(modelName) {
 
     return output;
   }
+
+  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+  return fn;
 }

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/db.js

@@ -147,15 +147,25 @@ export default class DB {
       const collectionKeys = this.getCollectionKeys();
 
       // Write each collection to its own file in parallel
-      await Promise.all(collectionKeys.map(key =>
-        updateFile(path.join(dirPath, `${key}.json`), jsonData[key] || [], { json: true })
-      ));
+      // Use createFile for new files, updateFile for existing ones
+      await Promise.all(collectionKeys.map(async key => {
+        const filePath = path.join(dirPath, `${key}.json`);
+        const exists = await fileExists(filePath);
+        const data = jsonData[key] || [];
+
+        if (exists) await updateFile(filePath, data, { json: true });
+        else await createFile(filePath, data, { json: true });
+      }));
 
       // Write empty-array skeleton to db.json
       const skeleton = {};
       for (const key of collectionKeys) skeleton[key] = [];
 
-      await updateFile(`${config.rootPath}/${file}`, skeleton, { json: true });
+      const dbFilePath = `${config.rootPath}/${file}`;
+      const dbFileExists = await fileExists(dbFilePath);
+
+      if (dbFileExists) await updateFile(dbFilePath, skeleton, { json: true });
+      else await createFile(dbFilePath, skeleton, { json: true });
 
       log.db(`DB has been successfully saved to ${config.orm.db.directory}/ directory`);
       return;

package/src/has-many.js

@@ -16,7 +16,7 @@ export default function hasMany(modelName) {
   const globalRelationships = relationships.get('global');
   const pendingRelationships = relationships.get('pending');
 
-  return (sourceRecord, rawData, options) => {
+  const fn = (sourceRecord, rawData, options) => {
     const { __name: sourceModelName } = sourceRecord.__model;
     const relationshipId = sourceRecord.id;
     const relationship = getRelationships('hasMany', sourceModelName, modelName, relationshipId);
@@ -27,6 +27,10 @@ export default function hasMany(modelName) {
       let record;
 
       if (typeof elementData !== 'object') {
+        if (!modelStore) {
+          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+        }
+
         record = modelStore.get(elementData);
 
         if (!record) {
@@ -58,4 +62,7 @@ export default function hasMany(modelName) {
 
     return output;
   }
+
+  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+  return fn;
 }

package/src/index.js

@@ -15,15 +15,24 @@
  */
 
 import Model from './model.js';
+import View from './view.js';
 import Serializer from './serializer.js';
 
 import attr from './attr.js';
 import belongsTo from './belongs-to.js';
 import hasMany from './has-many.js';
 import { createRecord, updateRecord } from './manage-record.js';
+import { count, avg, sum, min, max } from './aggregates.js';
 
 export { default } from './main.js';
 export { store, relationships } from './main.js';
-export { Model, Serializer }; // base classes
+export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
-export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
+export { count, avg, sum, min, max }; // aggregate helpers
+export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
+
+// Store API:
+// store.get(model, id)   — sync, memory-only
+// store.find(model, id)  — async, MySQL for memory:false models
+// store.findAll(model)   — async, all records
+// store.query(model, conditions) — async, always hits MySQL