@stonyx/orm 0.2.1-beta.71 → 0.2.1-beta.72

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.71",
+  "version": "0.2.1-beta.72",
   "description": "",
   "main": "src/main.js",
   "type": "module",
@@ -24,6 +24,11 @@
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "files": [
+    "src",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true

package/.claude/code-style-rules.md

@@ -1,44 +0,0 @@
-# Stonyx Code Style Rules
-
-Strict prettier/eslint rules to apply across all Stonyx projects. These will be formalized into an ESLint/Prettier config once enough patterns are collected.
-
----
-
-## Rules
-
-### 1. Destructure config objects in function signatures
-
-When a function receives a config/options object and only uses specific properties, destructure them in the function signature rather than accessing them via dot notation in the body.
-
-**Bad:**
-```javascript
-export async function getPool(mysqlConfig) {
-  pool = mysql.createPool({
-    host: mysqlConfig.host,
-    port: mysqlConfig.port,
-    user: mysqlConfig.user,
-    password: mysqlConfig.password,
-    database: mysqlConfig.database,
-    connectionLimit: mysqlConfig.connectionLimit,
-    // ...
-  });
-}
-```
-
-**Good:**
-```javascript
-export async function getPool({ host, port, user, password, database, connectionLimit }) {
-  pool = mysql.createPool({
-    host,
-    port,
-    user,
-    password,
-    database,
-    connectionLimit,
-    // ...
-  });
-}
-```
-
-**Source:** PR #14, `src/mysql/connection.js`
-**ESLint rule (candidate):** `prefer-destructuring` (with custom config for function parameters)

package/.claude/hooks.md

@@ -1,250 +0,0 @@
-# Middleware Hooks System
-
-The ORM provides a powerful middleware-based hook system that allows custom logic before and after CRUD operations. **Before hooks can halt operations** by returning a value.
-
-## Architecture
-
-**Hook Registry**: [src/hooks.js](src/hooks.js) - Stores before/after hooks in Maps
-**Integration**: [src/orm-request.js](src/orm-request.js) - `_withHooks()` wrapper executes hooks
-**Exports**: [src/index.js](src/index.js) - Exports `beforeHook`, `afterHook`, `clearHook`, `clearAllHooks`
-
-## API
-
-### `beforeHook(operation, model, handler)`
-
-Register a before hook that runs before the operation executes.
-
-```javascript
-import { beforeHook } from '@stonyx/orm';
-
-beforeHook('create', 'animal', (context) => {
-  // Validate, transform, authorize...
-  if (invalid) {
-    return 400; // Halt with status code
-  }
-  // Return undefined to continue
-});
-```
-
-**Handler return values:**
-- `undefined` / no return - Operation continues
-- **Any other value** - Halts operation and returns that value:
-  - Integer (e.g., `403`) - HTTP status code
-  - Object - JSON response body
-
-**Returns:** Unregister function
-
-### `afterHook(operation, model, handler)`
-
-Register an after hook that runs after the operation completes.
-
-```javascript
-import { afterHook } from '@stonyx/orm';
-
-afterHook('update', 'animal', (context) => {
-  console.log(`Updated animal ${context.record.id}`);
-  // After hooks cannot halt (operation already complete)
-});
-```
-
-**Returns:** Unregister function
-
-### `clearHook(operation, model, [type])`
-
-Clear registered hooks for a specific operation:model.
-
-```javascript
-import { clearHook } from '@stonyx/orm';
-
-clearHook('create', 'animal');           // Clear both before and after
-clearHook('create', 'animal', 'before'); // Clear only before hooks
-clearHook('create', 'animal', 'after');  // Clear only after hooks
-```
-
-### `clearAllHooks()`
-
-Clear all registered hooks (useful for testing).
-
-```javascript
-import { clearAllHooks } from '@stonyx/orm';
-
-afterEach(() => {
-  clearAllHooks();
-});
-```
-
-## 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`)
-
-## Context Object
-
-Each hook receives a context object:
-
-```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 (includes filter for access control)
-
-  // For update/delete operations:
-  oldState,                  // Deep copy of record BEFORE operation
-
-  // For after hooks only:
-  response,                  // Handler response
-  record,                    // Affected record (create/update/get)
-  records,                   // All records (list)
-  recordId,                  // Record ID (delete only, since record no longer exists)
-}
-```
-
-**Notes:**
-- `oldState` is captured via `JSON.parse(JSON.stringify())` before operation executes
-- For delete operations, `recordId` is available since the record may no longer exist
-- `oldState` enables precise field-level change detection
-
-## Implementation Details
-
-**Hook Wrapper** (`src/orm-request.js`):
-
-```javascript
-_withHooks(operation, handler) {
-  return async (request, state) => {
-    const context = { model, operation, request, params, body, query, state };
-
-    // Capture old state for update/delete
-    if (operation === 'update' || operation === 'delete') {
-      const existingRecord = store.get(this.model, getId(request.params));
-      if (existingRecord) {
-        context.oldState = JSON.parse(JSON.stringify(existingRecord.__data || existingRecord));
-      }
-    }
-
-    // Run before hooks sequentially (can halt by returning a value)
-    for (const hook of getBeforeHooks(operation, this.model)) {
-      const result = await hook(context);
-      if (result !== undefined) {
-        return result;  // Halt - return status/response
-      }
-    }
-
-    // Execute main handler
-    const response = await handler(request, state);
-
-    // Enrich context for after hooks
-    context.response = response;
-    context.record = /* fetched from store */;
-    context.records = /* for list operations */;
-    context.recordId = /* for delete operations */;
-
-    // Run after hooks sequentially
-    for (const hook of getAfterHooks(operation, this.model)) {
-      await hook(context);
-    }
-
-    return response;
-  };
-}
-```
-
-## Usage Examples
-
-### Validation (Halting)
-
-```javascript
-beforeHook('create', 'animal', (context) => {
-  const { age } = context.body.data.attributes;
-  if (age < 0) {
-    return 400; // Halt with Bad Request
-  }
-});
-```
-
-### Custom Error Response
-
-```javascript
-beforeHook('delete', 'animal', (context) => {
-  const animal = store.get('animal', context.params.id);
-  if (animal.protected) {
-    return { errors: [{ detail: 'Cannot delete protected animals' }] };
-  }
-});
-```
-
-### Change Detection with oldState
-
-```javascript
-afterHook('update', 'animal', (context) => {
-  if (!context.oldState) return;
-
-  // Detect specific field changes
-  if (context.oldState.owner !== context.record.owner) {
-    console.log(`Owner changed from ${context.oldState.owner} to ${context.record.owner}`);
-  }
-});
-```
-
-### Audit Logging
-
-```javascript
-afterHook('update', 'animal', async (context) => {
-  const changes = {};
-  if (context.oldState) {
-    for (const [key, newValue] of Object.entries(context.record.__data)) {
-      if (context.oldState[key] !== newValue) {
-        changes[key] = { from: context.oldState[key], to: newValue };
-      }
-    }
-  }
-
-  await auditLog.create({
-    operation: 'update',
-    model: context.model,
-    recordId: context.record.id,
-    changes // { age: { from: 2, to: 3 } }
-  });
-});
-```
-
-### Delete Auditing
-
-```javascript
-afterHook('delete', 'animal', async (context) => {
-  await auditLog.create({
-    operation: 'delete',
-    model: context.model,
-    recordId: context.recordId,
-    deletedData: context.oldState // Full snapshot
-  });
-});
-```
-
-## Key Differences from Event-Based System
-
-| Feature | Event-Based (Old) | Middleware-Based (Current) |
-|---------|-------------------|---------------------------|
-| Execution | Parallel (fire-and-forget) | Sequential |
-| Can halt operation | No | Yes (return any value) |
-| Error handling | Isolated (logged) | Propagated (halts operation) |
-| Middleware order | Not guaranteed | Registration order |
-| Context modification | Not reliable | Reliable (sequential) |
-| API | `subscribe('before:create:animal')` | `beforeHook('create', 'animal')` |
-
-## Testing
-
-**Location**: `test/integration/orm-test.js`
-**Coverage**: Comprehensive hook tests including:
-- Before/after hooks for all operations
-- Halting with status codes
-- Halting with custom response objects
-- Sequential execution order
-- Unsubscribe functionality
-- clearHook functionality

package/.claude/index.md

@@ -1,292 +0,0 @@
-# Stonyx-ORM Guide for Claude
-
-## Detailed Guides
-
-- [Usage Patterns](usage-patterns.md) — Model definitions, serializers, transforms, CRUD, DB schema, persistence, access control, REST API, and include parameters
-- [Views](views.md) — Read-only computed views with aggregate helpers, in-memory resolver, and MySQL VIEW auto-generation
-- [Middleware Hooks System](hooks.md) — Before/after hooks for CRUD operations, halting, context object, change detection, and testing
-- [Code Style Rules](code-style-rules.md) — Strict prettier/eslint rules to apply across all Stonyx projects
-
----
-
-## Project Overview
-
-**stonyx-orm** is a lightweight Object-Relational Mapping (ORM) library designed specifically for the Stonyx framework. It provides structured data modeling, relationship management, serialization, and persistence to JSON files, with optional REST API integration.
-
-## Core Problem It Solves
-
-1. **Data Modeling**: Clean, type-safe model definitions with attributes and relationships
-2. **Data Serialization**: Transforms messy third-party data into structured model instances
-3. **Relationship Management**: Automatic bidirectional relationships (hasMany, belongsTo)
-4. **Data Persistence**: File-based JSON storage with auto-save
-5. **REST API Generation**: Auto-generated RESTful endpoints with access control
-6. **Data Transformation**: Custom type conversion and formatting
-7. **Middleware Hooks**: Before/after hooks for all CRUD operations with halting capability
-8. **Views**: Read-only computed projections over model data with aggregate helpers (count, avg, sum, min, max)
-
----
-
-## Architecture Overview
-
-### Key Components
-
-1. **Orm** ([src/main.js](src/main.js)) - Singleton that initializes and manages the entire system
-2. **Store** ([src/store.js](src/store.js)) - In-memory storage (nested Maps: `Map<modelName, Map<recordId, record>>`)
-3. **Model** ([src/model.js](src/model.js)) - Base class for all models
-4. **Record** ([src/record.js](src/record.js)) - Individual model instances
-5. **Serializer** ([src/serializer.js](src/serializer.js)) - Maps raw data to model format
-6. **DB** ([src/db.js](src/db.js)) - JSON file persistence layer
-7. **Relationships** ([src/has-many.js](src/has-many.js), [src/belongs-to.js](src/belongs-to.js)) - Relationship handlers
-8. **Include Logic** (inline in [src/orm-request.js](src/orm-request.js)) - Parses include query params, traverses relationships, collects and deduplicates included records
-9. **Hooks** ([src/hooks.js](src/hooks.js)) - Middleware-based hook registry for CRUD lifecycle
-10. **MySQL Driver** ([src/mysql/mysql-db.js](src/mysql/mysql-db.js)) - MySQL persistence, migrations, schema introspection. Loads records in topological order. `_rowToRawData()` converts TINYINT(1) → boolean, remaps FK columns, strips timestamps.
-11. **View** ([src/view.js](src/view.js)) - Read-only base class for computed views (does NOT extend Model)
-12. **Aggregates** ([src/aggregates.js](src/aggregates.js)) - AggregateProperty class + helper functions (count, avg, sum, min, max)
-13. **ViewResolver** ([src/view-resolver.js](src/view-resolver.js)) - In-memory view resolver (iterates source model, computes aggregates + resolve map)
-
-### Project Structure
-
-```
-stonyx-orm/
-├── src/
-│   ├── index.js                  # Main exports (includes hook functions)
-│   ├── main.js                   # Orm class
-│   ├── model.js                  # Base Model
-│   ├── record.js                 # Record instances
-│   ├── serializer.js             # Base Serializer
-│   ├── store.js                  # In-memory storage
-│   ├── db.js                     # JSON persistence
-│   ├── attr.js                   # Attribute helper (Proxy-based)
-│   ├── has-many.js               # One-to-many relationships
-│   ├── belongs-to.js             # Many-to-one relationships
-│   ├── relationships.js          # Relationship registry
-│   ├── manage-record.js          # createRecord/updateRecord
-│   ├── model-property.js         # Transform handler
-│   ├── transforms.js             # Built-in transforms
-│   ├── hooks.js                  # Middleware hook registry
-│   ├── setup-rest-server.js      # REST integration
-│   ├── orm-request.js            # CRUD request handler with hooks + includes
-│   ├── meta-request.js           # Meta endpoint (dev only)
-│   ├── migrate.js                # JSON DB mode migration (file <-> directory)
-│   ├── commands.js               # CLI commands (db:migrate-*, etc.)
-│   ├── utils.js                  # Pluralize wrapper for dasherized names
-│   ├── plural-registry.js        # Plural name registry (populated at init, supports Model.pluralName overrides)
-│   ├── view.js                   # View base class (read-only, source, resolve, memory)
-│   ├── aggregates.js             # AggregateProperty + count/avg/sum/min/max helpers
-│   ├── view-resolver.js          # In-memory view resolver
-│   ├── exports/
-│   │   └── db.js                 # Convenience re-export of DB instance
-│   └── mysql/
-│       ├── mysql-db.js           # MySQL driver (CRUD persistence, record loading)
-│       ├── connection.js         # mysql2 connection pool
-│       ├── query-builder.js      # SQL builders (INSERT/UPDATE/DELETE/SELECT) with identifier validation
-│       ├── schema-introspector.js # Model-to-MySQL schema introspection
-│       ├── migration-generator.js # Schema diff and .sql migration generation
-│       ├── migration-runner.js   # Migration apply/rollback with transactions
-│       └── type-map.js           # ORM attr types -> MySQL column types (supports custom transform mysqlType)
-├── config/
-│   └── environment.js            # Default configuration
-├── test/
-│   ├── integration/              # Integration tests
-│   ├── unit/                     # Unit tests
-│   └── sample/                   # Test fixtures
-│       ├── models/               # Example models
-│       ├── serializers/          # Example serializers
-│       ├── transforms/           # Custom transforms
-│       ├── access/               # Access control
-│       ├── views/                # Example views
-│       ├── db-schema.js          # DB schema
-│       └── payload.js            # Test data
-└── package.json
-```
-
----
-
-## Configuration
-
-Located in [config/environment.js](config/environment.js), overridable via environment variables:
-
-```javascript
-config.orm = {
-  paths: {
-    model: './models',
-    serializer: './serializers',
-    transform: './transforms',
-    access: './access',
-    view: './views'
-  },
-  db: {
-    autosave: 'false',
-    file: 'db.json',
-    mode: 'file', // 'file' (single db.json) or 'directory' (one file per collection)
-    directory: 'db', // directory name for collection files when mode is 'directory'
-    saveInterval: 3600,
-    schema: './config/db-schema.js'
-  },
-  restServer: {
-    enabled: 'true',
-    route: '/'
-  }
-}
-```
-
----
-
-## Storage Modes
-
-The ORM supports two storage modes, configured via `db.mode`:
-
-- **`'file'`** (default): All data is stored in a single `db.json` file.
-- **`'directory'`**: Each collection is stored as a separate file in the configured directory — `{directory}/{collection}.json` (e.g., `db/animals.json`, `db/owners.json`). The main `db.json` is kept as a skeleton with empty arrays.
-
-**Migration CLI commands:**
-- `stonyx-db-file-to-directory` — Splits a single `db.json` into per-collection files in the directory.
-- `stonyx-db-directory-to-file` — Merges per-collection files back into a single `db.json`.
-
-**Mode validation:** On startup, the ORM warns if the configured mode doesn't match the actual file state (e.g., mode is `'file'` but a `db/` directory exists, or mode is `'directory'` but no directory is found).
-
----
-
-## Design Patterns
-
-1. **Singleton**: Orm, Store, DB classes
-2. **Proxy**: `attr()` uses Proxies for type-safe access
-3. **Registry**: Relationships in nested Maps
-4. **Factory**: `createRecord()` function
-5. **Observer**: Auto-save via Cron
-6. **Middleware**: Hook system with halting capability
-7. **Convention over Configuration**: Auto-discovery by naming
-
-**Naming Conventions:**
-- Models: `{PascalCase}Model` (e.g., `AnimalModel`)
-- Serializers: `{PascalCase}Serializer` (e.g., `AnimalSerializer`)
-- Transforms: Original filename (e.g., `animal.js`)
-- Plural names: Auto-pluralized by default (e.g., `animal` → `animals`). Override with `static pluralName` on the model class (e.g., `static pluralName = 'people'`). All call sites use `getPluralName()` from the plural registry, **not** `pluralize()` directly.
-
----
-
-## Testing
-
-**Test Runner**: QUnit via `stonyx test` (auto-bootstraps and runs `test/**/*-test.js`)
-
-**Test Structure:**
-- **Integration**: [test/integration/orm-test.js](test/integration/orm-test.js) - Full pipeline test
-- **Unit**: [test/unit/transforms/](test/unit/transforms/) - Transform tests
-- **Sample**: [test/sample/](test/sample/) - Test fixtures
-
-**Key Test Data:**
-- [test/sample/payload.js](test/sample/payload.js) - Raw vs serialized data
-- Demonstrates transformation from messy external data to clean models
-
----
-
-## Critical Files for Common Tasks
-
-**Understanding Core Behavior:**
-- [src/main.js](src/main.js) - Initialization flow
-- [src/store.js](src/store.js) - Record storage/retrieval
-- [src/manage-record.js](src/manage-record.js) - CRUD operations
-
-**Understanding Relationships:**
-- [src/relationships.js](src/relationships.js) - Registry system
-- [src/has-many.js](src/has-many.js) - One-to-many logic
-- [src/belongs-to.js](src/belongs-to.js) - Many-to-one logic
-
-**Understanding Data Flow:**
-- [src/serializer.js](src/serializer.js) - Raw → Model mapping
-- [src/model-property.js](src/model-property.js) - Transform application
-- [src/transforms.js](src/transforms.js) - Built-in transforms
-
-**Understanding REST API:**
-- [src/setup-rest-server.js](src/setup-rest-server.js) - Endpoint registration
-- [src/orm-request.js](src/orm-request.js) - Request handling with hooks
-
-**Understanding Hooks:**
-- [src/hooks.js](src/hooks.js) - Hook registry (beforeHooks, afterHooks Maps)
-- [src/orm-request.js](src/orm-request.js) - `_withHooks()` wrapper
-
----
-
-## Key Insights
-
-**Strengths:**
-- Zero-config REST API generation
-- Clean declarative model definitions
-- Automatic relationship management
-- File-based (no database setup needed)
-- Flexible serialization for messy data
-- Middleware hooks with halting capability
-
-**Use Cases:**
-- Rapid prototyping
-- Small to medium applications
-- Third-party API consumption with normalization
-- Development/testing environments
-- Applications needing quick REST APIs
-
-**Dependencies:**
-- `stonyx` - Main framework (peer)
-- `@stonyx/utils` - File/string utilities
-- `@stonyx/events` - Pub/sub event system (event names initialized on startup; hooks use separate middleware-based registry)
-- `@stonyx/cron` - Scheduled tasks (used by DB for auto-save)
-- `@stonyx/rest-server` - REST API
-- `mysql2` - Optional peer dependency for MySQL mode
-
----
-
-## Quick Reference
-
-**Import the ORM:**
-```javascript
-import {
-  Orm, Model, View, Serializer, attr, hasMany, belongsTo,
-  createRecord, updateRecord, store,
-  beforeHook, afterHook, clearHook, clearAllHooks,
-  count, avg, sum, min, max
-} from '@stonyx/orm';
-```
-
-**Initialize:**
-```javascript
-const orm = new Orm({ dbType: 'json' });
-await orm.init();
-```
-
-**Access Database:**
-```javascript
-await Orm.db.save();
-```
-
-**Common Operations:**
-```javascript
-// Create
-const record = createRecord('modelName', data);
-
-// Read
-const record = store.get('modelName', id);
-const all = store.get('modelName');
-
-// Update
-updateRecord(record, newData);
-
-// Delete
-store.remove('modelName', id);
-```
-
-**Register Hooks:**
-```javascript
-// Before hook (can halt)
-const unsubscribe = beforeHook('create', 'animal', (ctx) => {
-  if (invalid) return 400;
-});
-
-// After hook
-afterHook('update', 'animal', (ctx) => {
-  console.log('Updated:', ctx.record.id);
-});
-
-// Cleanup
-unsubscribe();           // Remove specific hook
-clearHook('create', 'animal'); // Clear all hooks for operation
-clearAllHooks();         // Clear everything
-```