@stonyx/orm 0.2.1-alpha.3 → 0.2.1-alpha.30

package/README.md

@@ -1,7 +1,11 @@
+[![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.
-`@stonyx/orm` provides a structured way to define models, manage relationships, and persist data in JSON files. It also allows integration with the Stonyx REST server for automatic route setup and access control.
+`@stonyx/orm` provides a structured way to define models, manage relationships, and persist data in JSON files or MySQL. It also allows integration with the Stonyx REST server for automatic route setup and access control.
 
 ## Highlights
 
@@ -9,8 +13,26 @@ A lightweight ORM for Stonyx projects, featuring model definitions, serializers,
 - **Models**: Define attributes with type-safe proxies (`attr`) and relationships (`hasMany`, `belongsTo`).
 - **Serializers**: Map raw data into model-friendly structures, including nested properties.
 - **Transforms**: Apply custom transformations on data values automatically.
-- **DB Integration**: Optional file-based persistence with auto-save support.
+- **DB Integration**: Optional file-based persistence with auto-save support, or MySQL for production workloads.
 - **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
 
@@ -32,9 +54,18 @@ const {
   ORM_USE_REST_SERVER,
   DB_AUTO_SAVE,
   DB_FILE,
+  DB_MODE,
+  DB_DIRECTORY,
   DB_SCHEMA_PATH,
-  DB_SAVE_INTERVAL
-} = process;
+  DB_SAVE_INTERVAL,
+  MYSQL_HOST,
+  MYSQL_PORT,
+  MYSQL_USER,
+  MYSQL_PASSWORD,
+  MYSQL_DATABASE,
+  MYSQL_CONNECTION_LIMIT,
+  MYSQL_MIGRATIONS_DIR,
+} = process.env;
 
 export default {
   orm: {
@@ -44,6 +75,8 @@ export default {
     db: {
       autosave: DB_AUTO_SAVE ?? 'false',
       file: DB_FILE ?? 'db.json',
+      mode: DB_MODE ?? 'file', // 'file' (single db.json) or 'directory' (one file per collection)
+      directory: DB_DIRECTORY ?? 'db', // directory name for collection files when mode is 'directory'
       saveInterval: DB_SAVE_INTERVAL ?? 3600, // 1 hour
       schema: DB_SCHEMA_PATH ?? './config/db-schema.js'
     },
@@ -53,6 +86,16 @@ export default {
       serializer: ORM_SERIALIZER_PATH ?? './serializers',
       transform: ORM_TRANSFORM_PATH ?? './transforms'
     },
+    mysql: MYSQL_HOST ? {
+      host: MYSQL_HOST ?? 'localhost',
+      port: parseInt(MYSQL_PORT ?? '3306'),
+      user: MYSQL_USER ?? 'root',
+      password: MYSQL_PASSWORD ?? '',
+      database: MYSQL_DATABASE ?? 'stonyx',
+      connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
+      migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
+      migrationsTable: '__migrations',
+    } : undefined,
     restServer: {
       enabled: ORM_USE_REST_SERVER ?? 'true',
       route: ORM_REST_ROUTE ?? '/'
@@ -61,16 +104,13 @@ export default {
 };
 ```
 
-Then initialize the Stonyx framework, which auto-initializes all of its modules, including `@stonyx/rest-server`:
-
-```js
-import Stonyx from 'stonyx';
-import config from './config/environment.js';
+Then run the application via the Stonyx CLI, which auto-initializes all modules including the ORM:
 
-new Stonyx(config);
+```bash
+stonyx serve
 ```
 
-For further framework initialization instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
+For further framework instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
 
 ## Models
 
@@ -90,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:
@@ -154,7 +210,7 @@ export default function(value) {
 
 ## Database (DB) Integration
 
-The ORM can automatically save records to a JSON file with optional auto-save intervals.
+The ORM can automatically save records to a JSON file or a directory of collection files, with optional auto-save intervals.
 
 ```js
 import Orm from '@stonyx/orm';
@@ -168,11 +224,47 @@ const dbRecord = Orm.db;
 
 Configuration options are in `config/environment.js`:
 
-* `DB_AUTO_SAVE`: Whether to auto-save.
+* `DB_AUTO_SAVE`: Auto-save mode — `'true'` (cron-based interval), `'false'` (disabled), or `'onUpdate'` (save after every create/update/delete via REST API).
 * `DB_FILE`: File path to store data.
-* `DB_SAVE_INTERVAL`: Interval in seconds for auto-save.
+* `DB_MODE`: Storage mode — `'file'` (single JSON file, default) or `'directory'` (one file per collection in a directory).
+* `DB_DIRECTORY`: Directory name for collection files when mode is `'directory'` (default: `'db'`).
+* `DB_SAVE_INTERVAL`: Interval in seconds for auto-save (only applies when `DB_AUTO_SAVE` is `'true'`).
 * `DB_SCHEMA_PATH`: Path to DB schema.
 
+In directory mode, each collection is stored as `{directory}/{collection}.json` (e.g., `db/animals.json`, `db/owners.json`). The main `db.json` is kept as a skeleton with empty arrays. Migration commands are available: `stonyx db:migrate-to-directory` and `stonyx db:migrate-to-file`.
+
+### MySQL Mode
+
+Set the `MYSQL_HOST` environment variable to enable MySQL persistence. The ORM loads all records into memory on startup and persists CRUD operations to MySQL automatically. Supports schema-aware migration generation, apply, rollback, and drift detection.
+
+| Command | Description |
+|---------|-------------|
+| `stonyx db:generate-migration <desc>` | Generate a migration from model schema diffs |
+| `stonyx db:migrate` | Apply pending migrations |
+| `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.
@@ -289,6 +381,372 @@ GET /animals/1
 
 - Only available on GET endpoints (not POST/PATCH)
 
+## Lifecycle Hooks
+
+The ORM provides a powerful middleware-based hook system that allows you to run custom logic before and after CRUD operations. Hooks are perfect for validation, transformation, side effects, authorization, and auditing.
+
+### Overview
+
+Hooks run at key points in the request lifecycle:
+
+- **Before hooks**: Run before the operation executes. **Can halt operations** by returning a value (status code or response object).
+- **After hooks**: Run after the operation completes (logging, notifications, cache invalidation).
+
+### Event Naming Convention
+
+Events follow the pattern: `{timing}:{operation}:{modelName}`
+
+**Operations:**
+- `list` - GET collection (`/animals`)
+- `get` - GET single record (`/animals/1`)
+- `create` - POST new record (`/animals`)
+- `update` - PATCH existing record (`/animals/1`)
+- `delete` - DELETE record (`/animals/1`)
+
+**Examples:**
+- `before:create:animal` - Before creating an animal
+- `after:list:owner` - After fetching owner collection
+- `before:update:trait` - Before updating a trait
+
+### Hook Context Object
+
+Each hook receives a context object with comprehensive information:
+
+```javascript
+{
+  model: 'animal',           // Model name
+  operation: 'create',       // Operation type
+  request,                   // Express request object
+  params,                    // URL params (e.g., { id: 5 })
+  body,                      // Request body (POST/PATCH)
+  query,                     // Query parameters
+  state,                     // Request state object
+  record,                    // Record instance (after hooks, single operations)
+  records,                   // Record array (after hooks, list operations)
+  response,                  // Response data (after hooks)
+  oldState,                  // Previous record state (update/delete operations only)
+  recordId,                  // Record ID (delete operations in after hooks)
+}
+```
+
+**Important Notes**:
+- `oldState` is only available for `update` and `delete` operations
+- 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 as a deep copy of the record's data before the operation, providing access to the previous field values
+
+### Usage Examples
+
+#### Basic Hook Registration
+
+```javascript
+import { beforeHook, afterHook } from '@stonyx/orm';
+
+// Validation before creating - can halt by returning a value
+beforeHook('create', 'animal', (context) => {
+  const { age } = context.body.data.attributes;
+  if (age < 0) {
+    return 400; // Halt with 400 Bad Request
+  }
+  // Return undefined to continue
+});
+
+// Logging after updates
+afterHook('update', 'animal', (context) => {
+  console.log(`Animal ${context.record.id} was updated`);
+});
+```
+
+#### Halting Operations
+
+Before hooks can halt operations by returning a value:
+
+```javascript
+import { beforeHook } from '@stonyx/orm';
+
+// Return a status code to halt with that HTTP status
+beforeHook('create', 'animal', (context) => {
+  if (!context.body.data.attributes.name) {
+    return 400; // Bad Request
+  }
+});
+
+// Return an object to send a custom response
+beforeHook('delete', 'animal', (context) => {
+  const animal = store.get('animal', context.params.id);
+  if (animal.protected) {
+    return { errors: [{ detail: 'Cannot delete protected animals' }] };
+  }
+});
+
+// Return undefined (or nothing) to allow operation to continue
+beforeHook('update', 'animal', (context) => {
+  console.log('Update proceeding...');
+  // No return = operation continues
+});
+```
+
+#### Data Transformation
+
+```javascript
+// Normalize data before saving
+beforeHook('create', 'owner', (context) => {
+  const attrs = context.body.data.attributes;
+  if (attrs.email) {
+    attrs.email = attrs.email.toLowerCase().trim();
+  }
+});
+```
+
+#### Side Effects
+
+```javascript
+// Send notification after animal is adopted (using oldState to detect changes)
+afterHook('update', 'animal', async (context) => {
+  // Use oldState to compare before/after values
+  if (context.oldState && context.oldState.owner !== context.record.owner) {
+    await sendNotification({
+      type: 'adoption',
+      animalId: context.record.id,
+      previousOwner: context.oldState.owner,
+      newOwner: context.record.owner
+    });
+  }
+});
+
+// Cache invalidation
+afterHook('delete', 'animal', async (context) => {
+  await cache.invalidate(`owner:${context.params.id}:pets`);
+});
+```
+
+#### Change Detection
+
+The `oldState` property (available for `update` and `delete` operations) enables precise change tracking:
+
+```javascript
+// Detect specific field changes
+afterHook('update', 'animal', async (context) => {
+  if (!context.oldState) return; // No old state for create operations
+
+  // Check if a specific field changed
+  if (context.oldState.age !== context.record.age) {
+    console.log(`Age changed from ${context.oldState.age} to ${context.record.age}`);
+  }
+
+  // Track multiple field changes
+  const changedFields = [];
+  for (const key of Object.keys(context.oldState)) {
+    if (context.oldState[key] !== context.record[key]) {
+      changedFields.push(key);
+    }
+  }
+
+  if (changedFields.length > 0) {
+    console.log(`Fields changed: ${changedFields.join(', ')}`);
+  }
+});
+
+// Access deleted record data
+afterHook('delete', 'animal', async (context) => {
+  console.log(`Deleted animal: ${context.oldState.type} (age: ${context.oldState.age})`);
+  // oldState contains full snapshot of the deleted record
+});
+```
+
+#### Authorization
+
+```javascript
+// Additional access control - halt with 403 if unauthorized
+beforeHook('delete', 'animal', (context) => {
+  const user = context.state.currentUser;
+  const animal = store.get('animal', context.params.id);
+
+  if (animal.owner !== user.id && !user.isAdmin) {
+    return 403; // Forbidden
+  }
+});
+```
+
+#### Auditing
+
+```javascript
+// Audit log for all changes with field-level change tracking
+afterHook('update', 'animal', async (context) => {
+  // Compare oldState with current record to capture exact changes
+  const changes = {};
+  if (context.oldState) {
+    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] };
+      }
+    }
+  }
+
+  await auditLog.create({
+    operation: 'update',
+    model: context.model,
+    recordId: context.record.id,
+    userId: context.state.currentUser?.id,
+    timestamp: new Date(),
+    changes // Precise field-level changes: { age: { from: 2, to: 3 } }
+  });
+});
+
+// Audit deletes with full record snapshot
+afterHook('delete', 'animal', async (context) => {
+  await auditLog.create({
+    operation: 'delete',
+    model: context.model,
+    recordId: context.recordId,
+    userId: context.state.currentUser?.id,
+    timestamp: new Date(),
+    deletedData: context.oldState // Full snapshot of deleted record
+  });
+});
+```
+
+#### Error Handling
+
+For after hooks, wrap in try/catch if errors should not propagate:
+
+```javascript
+afterHook('create', 'animal', async (context) => {
+  try {
+    await sendWelcomeEmail(context.record.owner);
+  } catch (error) {
+    // Error is logged but doesn't fail the create operation
+    console.error('Failed to send welcome email:', error);
+  }
+});
+```
+
+### Hook Lifecycle Management
+
+#### Unsubscribing
+
+```javascript
+import { beforeHook } from '@stonyx/orm';
+
+// Get unsubscribe function
+const unsubscribe = beforeHook('create', 'animal', handler);
+
+// Later, remove the hook
+unsubscribe();
+```
+
+#### Clearing Hooks
+
+```javascript
+import { clearHook, clearAllHooks } from '@stonyx/orm';
+
+// Remove all hooks for a specific operation:model
+clearHook('create', 'animal');
+
+// Remove only before hooks
+clearHook('create', 'animal', 'before');
+
+// Remove only after hooks
+clearHook('create', 'animal', 'after');
+
+// Remove ALL hooks (useful for testing)
+clearAllHooks();
+```
+
+### Advanced Patterns
+
+#### Conditional Hooks
+
+```javascript
+beforeHook('update', 'animal', (context) => {
+  // Only validate if age is being updated
+  if ('age' in context.body.data.attributes) {
+    const { age } = context.body.data.attributes;
+    if (age < 0 || age > 50) {
+      return 400; // Bad Request
+    }
+  }
+});
+```
+
+#### Cross-Model Hooks
+
+```javascript
+// Update owner's pet count when animal is created
+afterHook('create', 'animal', async (context) => {
+  const owner = store.get('owner', context.record.owner);
+  if (owner) {
+    owner.petCount = (owner.petCount || 0) + 1;
+  }
+});
+```
+
+#### Sequential Middleware
+
+```javascript
+// Multiple hooks run in registration order
+beforeHook('create', 'post', (context) => {
+  console.log('First middleware');
+  context.customData = { checked: true };
+});
+
+beforeHook('create', 'post', (context) => {
+  console.log('Second middleware');
+  // Can access data from previous hooks
+  if (!context.customData?.checked) {
+    return 403;
+  }
+});
+```
+
+### Hook Execution Order
+
+1. **Before hooks** fire first (sequentially, in registration order)
+2. **Main operation** executes (if no before hook halted)
+3. **After hooks** fire last (sequentially, in registration order)
+
+Before hooks can halt the operation by returning a value. After hooks run after completion and cannot halt.
+
+### Best Practices
+
+1. **Keep hooks focused**: Each hook should do one thing well
+2. **Use async/await**: Hooks support async functions for consistency
+3. **Return values intentionally**: Only return a value from before hooks when you want to halt
+4. **Document side effects**: Make it clear what each hook does
+5. **Test hooks independently**: Write unit tests for hook logic
+6. **Avoid heavy operations**: Keep hooks fast to maintain performance
+7. **Clean up in tests**: Use `clearAllHooks()` in test teardown
+
+### Testing Hooks
+
+```javascript
+import { beforeHook, clearAllHooks } from '@stonyx/orm';
+
+// Clean up after each test
+afterEach(() => {
+  clearAllHooks();
+});
+
+// Test that validation hook halts with 400
+test('validation hook rejects negative age', async () => {
+  beforeHook('create', 'animal', (context) => {
+    if (context.body.data.attributes.age < 0) {
+      return 400;
+    }
+  });
+
+  const response = await fetch('/animals', {
+    method: 'POST',
+    body: JSON.stringify({
+      data: { attributes: { age: -5 } }
+    })
+  });
+
+  assert.strictEqual(response.status, 400, 'Hook halted with 400');
+});
+```
+
 ## Exported Helpers
 
 | Export          | Description                                                             |
@@ -297,9 +755,18 @@ GET /animals/1
 | `belongsTo`     | Define a one-to-one relationship.                                       |
 | `hasMany`       | Define a one-to-many relationship.                                      |
 | `createRecord`  | Instantiate a record with proper serialization and relationships.       |
+| `updateRecord`  | Update an existing record with new data.                                |
 | `store`         | Singleton store for all model instances.                                |
 | `relationships` | Access all relationships (`hasMany`, `belongsTo`, `global`, `pending`). |
+| `beforeHook`    | Register a before hook that can halt operations.                        |
+| `afterHook`     | Register an after hook for post-operation logic.                        |
+| `clearHook`     | Clear hooks for a specific operation:model.                             |
+| `clearAllHooks` | Clear all registered hooks (useful for testing).                        |
+
+## Project Structure
+
+For a full architectural reference, see [project-structure.md](project-structure.md).
 
 ## License
 
-Apache — do what you want, just keep attribution.
+Apache 2.0 — see [LICENSE.md](LICENSE.md).

package/config/environment.js

@@ -4,20 +4,32 @@ const {
   ORM_REST_ROUTE,
   ORM_SERIALIZER_PATH,
   ORM_TRANSFORM_PATH,
+  ORM_VIEW_PATH,
   ORM_USE_REST_SERVER,
   DB_AUTO_SAVE,
   DB_FILE,
+  DB_MODE,
+  DB_DIRECTORY,
   DB_SCHEMA_PATH,
-  DB_SAVE_INTERVAL
-} = process;
+  DB_SAVE_INTERVAL,
+  MYSQL_HOST,
+  MYSQL_PORT,
+  MYSQL_USER,
+  MYSQL_PASSWORD,
+  MYSQL_DATABASE,
+  MYSQL_CONNECTION_LIMIT,
+  MYSQL_MIGRATIONS_DIR,
+} = process.env;
 
 export default {
   logColor: 'white',
   logMethod: 'db',
   
   db: {
-    autosave: DB_AUTO_SAVE ?? 'false',
+    autosave: DB_AUTO_SAVE ?? 'false', // 'true' (cron interval), 'false' (disabled), 'onUpdate' (save after each write op)
     file: DB_FILE ?? 'db.json',
+    mode: DB_MODE ?? 'file', // 'file' (single db.json) or 'directory' (one file per collection)
+    directory: DB_DIRECTORY ?? 'db', // directory name for collection files when mode is 'directory'
     saveInterval: DB_SAVE_INTERVAL ?? 60 * 60, // 1 hour
     schema: DB_SCHEMA_PATH ?? './config/db-schema.js'
   },
@@ -25,10 +37,21 @@ 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',
+    port: parseInt(MYSQL_PORT ?? '3306'),
+    user: MYSQL_USER ?? 'root',
+    password: MYSQL_PASSWORD ?? '',
+    database: MYSQL_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+  } : undefined,
   restServer: {
-    enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or 
+    enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or
     route: ORM_REST_ROUTE ?? '/',
   }
-}
+}