@stonyx/orm 0.2.1-beta.9 → 0.2.1-beta.91

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,
@@ -18,6 +19,20 @@ const {
   MYSQL_DATABASE,
   MYSQL_CONNECTION_LIMIT,
   MYSQL_MIGRATIONS_DIR,
+  PG_HOST,
+  PG_PORT,
+  PG_USER,
+  PG_PASSWORD,
+  PG_DATABASE,
+  PG_CONNECTION_LIMIT,
+  PG_MIGRATIONS_DIR,
+  TIMESCALE_HOST,
+  TIMESCALE_PORT,
+  TIMESCALE_USER,
+  TIMESCALE_PASSWORD,
+  TIMESCALE_DATABASE,
+  TIMESCALE_CONNECTION_LIMIT,
+  TIMESCALE_MIGRATIONS_DIR,
 } = process.env;
 
 export default {
@@ -36,7 +51,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',
@@ -48,6 +64,26 @@ export default {
     migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
     migrationsTable: '__migrations',
   } : undefined,
+  postgres: PG_HOST ? {
+    host: PG_HOST ?? 'localhost',
+    port: parseInt(PG_PORT ?? '5432'),
+    user: PG_USER ?? 'postgres',
+    password: PG_PASSWORD ?? '',
+    database: PG_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(PG_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: PG_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+  } : undefined,
+  timescale: TIMESCALE_HOST ? {
+    host: TIMESCALE_HOST ?? 'localhost',
+    port: parseInt(TIMESCALE_PORT ?? '5432'),
+    user: TIMESCALE_USER ?? 'postgres',
+    password: TIMESCALE_PASSWORD ?? '',
+    database: TIMESCALE_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(TIMESCALE_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: TIMESCALE_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+  } : undefined,
   restServer: {
     enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or
     route: ORM_REST_ROUTE ?? '/',

package/dist/aggregates.d.ts

@@ -0,0 +1,21 @@
+type AggregateType = 'count' | 'avg' | 'sum' | 'min' | 'max';
+interface AggregateRecord {
+    __data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare class AggregateProperty {
+    readonly __kind: "AggregateProperty";
+    readonly aggregateType: AggregateType;
+    readonly relationship: string | undefined;
+    readonly field: string | undefined;
+    readonly mysqlFunction: string;
+    readonly resultType: 'float' | 'number';
+    constructor(aggregateType: AggregateType, relationship?: string, field?: string);
+    compute(relatedRecords: AggregateRecord[]): number | null;
+}
+export declare function count(relationship: string): AggregateProperty;
+export declare function avg(relationshipOrField: string, field?: string): AggregateProperty;
+export declare function sum(relationshipOrField: string, field?: string): AggregateProperty;
+export declare function min(relationshipOrField: string, field?: string): AggregateProperty;
+export declare function max(relationshipOrField: string, field?: string): AggregateProperty;
+export {};

package/dist/aggregates.js

@@ -0,0 +1,93 @@
+export class AggregateProperty {
+    __kind = 'AggregateProperty';
+    aggregateType;
+    relationship;
+    field;
+    mysqlFunction;
+    resultType;
+    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;
+        }
+        if (this.aggregateType === 'count')
+            return relatedRecords.length;
+        const field = this.field;
+        if (!field)
+            return null;
+        switch (this.aggregateType) {
+            case 'sum':
+                return relatedRecords.reduce((acc, record) => {
+                    const val = parseFloat(record?.__data?.[field] ?? record?.[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?.[field] ?? record?.[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?.[field] ?? record?.[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?.[field] ?? record?.[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/dist/attr.d.ts

@@ -0,0 +1,2 @@
+import ModelProperty from './model-property.js';
+export default function attr(type?: string, defaultValue?: unknown): ModelProperty;

package/dist/attr.js

@@ -0,0 +1,22 @@
+import ModelProperty from './model-property.js';
+export default function attr(type, defaultValue) {
+    const modelProp = new ModelProperty(type, defaultValue);
+    return new Proxy(modelProp, {
+        get(target, prop, receiver) {
+            if (prop === 'valueOf' || prop === 'toString') {
+                return () => target.value;
+            }
+            if (prop in target) {
+                return Reflect.get(target, prop, receiver);
+            }
+            return target.value;
+        },
+        set(target, prop, value, receiver) {
+            if (prop === 'value') {
+                target.value = value;
+                return true;
+            }
+            return Reflect.set(target, prop, value, receiver);
+        }
+    });
+}

package/dist/belongs-to.d.ts

@@ -0,0 +1,11 @@
+import type { SourceRecord } from './types/orm-types.js';
+interface BelongsToOptions {
+    _relationshipKey?: string;
+    [key: string]: unknown;
+}
+type RelationshipHandler = ((sourceRecord: SourceRecord, rawData: unknown, options: BelongsToOptions) => unknown) & {
+    __relatedModelName: string;
+    __relationshipType: 'belongsTo';
+};
+export default function belongsTo(modelName: string): RelationshipHandler;
+export {};

package/dist/belongs-to.js

@@ -0,0 +1,59 @@
+import { createRecord, store } from '@stonyx/orm';
+import { getRelationships, getHasManyRegistry, getPendingRegistry, getPendingBelongsToRegistry } from './relationships.js';
+function getOrSet(map, key, defaultValue) {
+    if (!map.has(key))
+        map.set(key, defaultValue);
+    return map.get(key);
+}
+export default function belongsTo(modelName) {
+    const hasManyRelationships = getHasManyRegistry();
+    const pendingHasManyQueue = getPendingRegistry();
+    const pendingBelongsToQueue = getPendingBelongsToRegistry();
+    const fn = (sourceRecord, rawData, options) => {
+        if (!rawData)
+            return null;
+        const { __name: sourceModelName } = sourceRecord.__model;
+        const relationshipId = sourceRecord.id;
+        const relationshipKey = options._relationshipKey;
+        const relationship = getRelationships('belongsTo', sourceModelName, modelName, relationshipId);
+        const modelStore = store.get(modelName);
+        // Try to get existing record
+        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') {
+            const targetId = rawData;
+            // Register pending belongsTo
+            const modelPendingMap = getOrSet(pendingBelongsToQueue, modelName, new Map());
+            const targetPendingArray = getOrSet(modelPendingMap, targetId, []);
+            targetPendingArray.push({
+                sourceRecord,
+                sourceModelName,
+                relationshipKey,
+                relationshipId
+            });
+            relationship.set(relationshipId, null);
+            return null;
+        }
+        relationship.set(relationshipId, output || {});
+        // Populate hasMany side if the relationship is defined
+        const outputRecord = typeof output === 'object' && output !== null && 'id' in output ? output : undefined;
+        const otherSide = outputRecord ? hasManyRelationships.get(modelName)?.get(sourceModelName)?.get(outputRecord.id) : undefined;
+        if (otherSide) {
+            otherSide.push(sourceRecord);
+            // Remove pending queue if it was just fulfilled
+            const pendingModelRelationships = pendingHasManyQueue.get(sourceModelName);
+            if (pendingModelRelationships)
+                pendingModelRelationships.delete(relationshipId);
+        }
+        return output;
+    };
+    Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+    Object.defineProperty(fn, '__relationshipType', { value: 'belongsTo' });
+    return fn;
+}

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/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 }
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,148 @@
+#!/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 instanceof Error ? err.message : String(err)}`);
+            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 instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
+run();

package/dist/commands.d.ts

@@ -0,0 +1,7 @@
+interface Command {
+    description: string;
+    bootstrap: boolean;
+    run: (args?: string[]) => Promise<void>;
+}
+declare const commands: Record<string, Command>;
+export default commands;