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

package/project-structure.md

@@ -1,343 +0,0 @@
-# Project Documentation: @stonyx/orm
-
-> Last audited: 2026-02-09 | Auto-generated by project-docs-auditor
-
----
-
-## Table of Contents
-1. [Overview](#overview)
-2. [Tech Stack](#tech-stack)
-3. [Architecture](#architecture)
-4. [Directory Map](#directory-map)
-5. [Key Files Reference](#key-files-reference)
-6. [Data Flow](#data-flow)
-7. [API / Routes](#api--routes)
-8. [Database & Models](#database--models)
-9. [Authentication & Authorization](#authentication--authorization)
-10. [Configuration & Environment](#configuration--environment)
-11. [Development Guide](#development-guide)
-12. [Testing](#testing)
-13. [Deployment & CI/CD](#deployment--cicd)
-14. [Conventions & Standards](#conventions--standards)
-15. [Known Issues & Technical Debt](#known-issues--technical-debt)
-
----
-
-## Overview
-
-A lightweight ORM for the Stonyx framework that provides structured data modeling with type-safe attributes, bidirectional relationships, serializers for third-party data normalization, and automatic REST API generation. Supports both JSON file-based persistence and MySQL as storage backends.
-
-## Tech Stack
-
-| Category | Technology | Version | Notes |
-|----------|-----------|---------|-------|
-| Language | JavaScript (ES Modules) | Node 24.13.0 | `"type": "module"` in package.json |
-| Framework | Stonyx | file ref | Core framework (peer dependency) |
-| Database (JSON) | Built-in `DB` class | N/A | File-based JSON persistence |
-| Database (SQL) | MySQL via mysql2 | ^3.0.0 | Optional peer dependency |
-| Test Framework | QUnit | ^2.24.1 | Via `stonyx test` runner |
-| Test Mocking | Sinon | ^21.0.0 | Stubs and spies |
-| Package Manager | pnpm | N/A | Local `file:` references for sibling packages |
-
-## Architecture
-
-The ORM follows a **singleton + registry** pattern. A single `Orm` instance manages models, serializers, and transforms. Records are stored in an in-memory `Store` (nested Maps) and optionally persisted to JSON files or MySQL.
-
-```
-                         ┌──────────────┐
-                         │   Orm (main) │  Singleton, initializes everything
-                         └──────┬───────┘
-              ┌────────────┬────┴────┬────────────┐
-              v            v         v            v
-         ┌────────┐  ┌─────────┐ ┌────┐   ┌──────────────┐
-         │ Models │  │Serializers│ │ DB │   │ REST Server  │
-         └───┬────┘  └────┬─────┘ └──┬─┘   │  Integration │
-             │             │          │      └──────┬───────┘
-             v             v          v             v
-         ┌────────┐  ┌──────────┐ ┌─────┐   ┌───────────┐
-         │ Record │──│ Store    │ │JSON │   │OrmRequest  │
-         │(instance)│ │(Map<Map>)│ │/MySQL│  │(CRUD+Hooks)│
-         └────────┘  └──────────┘ └─────┘   └───────────┘
-```
-
-**Key Design Patterns:**
-- **Singleton**: Orm, Store, DB, MysqlDB classes
-- **Proxy**: `attr()` wraps `ModelProperty` in a Proxy for type-safe get/set
-- **Registry**: Relationships tracked in nested Maps (`hasMany`, `belongsTo`, `global`, `pending`, `pendingBelongsTo`)
-- **Factory**: `createRecord()` instantiates records with serialization
-- **Middleware**: Hook system with sequential before/after execution and halting capability
-- **Convention over Configuration**: Auto-discovery of models, serializers, transforms, and access classes by filesystem directory
-
-## Directory Map
-
-```
-stonyx-orm/
-├── src/
-│   ├── index.js                     # Public exports barrel
-│   ├── main.js                      # Orm singleton class
-│   ├── model.js                     # Base Model class
-│   ├── record.js                    # Record instances (data + relationships)
-│   ├── serializer.js                # Base Serializer + computed properties
-│   ├── store.js                     # In-memory store (Map<model, Map<id, Record>>)
-│   ├── db.js                        # JSON file persistence layer
-│   ├── attr.js                      # Attribute helper (Proxy-based)
-│   ├── model-property.js            # Transform handler for attributes
-│   ├── transforms.js                # Built-in transforms (boolean, number, string, etc.)
-│   ├── has-many.js                  # One-to-many relationship handler
-│   ├── belongs-to.js                # Many-to-one relationship handler
-│   ├── relationships.js             # Relationship registry + helpers
-│   ├── manage-record.js             # createRecord / updateRecord
-│   ├── hooks.js                     # Middleware hook registry (before/after)
-│   ├── orm-request.js               # REST CRUD handler with hooks + includes
-│   ├── meta-request.js              # Dev-only meta endpoint
-│   ├── setup-rest-server.js         # REST route registration
-│   ├── migrate.js                   # JSON DB mode migration (file <-> directory)
-│   ├── commands.js                  # CLI commands (db:migrate-*, etc.)
-│   ├── utils.js                     # Pluralize wrapper for dasherized names
-│   ├── exports/
-│   │   └── db.js                    # Convenience re-export of DB instance
-│   └── mysql/
-│       ├── mysql-db.js              # MySQL driver class (CRUD persistence)
-│       ├── connection.js            # mysql2 connection pool management
-│       ├── query-builder.js         # SQL query builders (INSERT/UPDATE/DELETE/SELECT)
-│       ├── schema-introspector.js   # Introspects models into MySQL schemas
-│       ├── migration-generator.js   # Generates .sql migration files from schema diffs
-│       ├── migration-runner.js      # Applies/rollbacks migrations with transactions
-│       └── type-map.js              # ORM attr types -> MySQL column types
-├── config/
-│   └── environment.js               # Default ORM configuration
-├── test/
-│   ├── config/
-│   │   └── environment.js           # Test-specific config overrides
-│   ├── integration/
-│   │   ├── orm-test.js              # Full pipeline integration tests
-│   │   └── db-directory-test.js     # Directory-mode DB tests
-│   ├── unit/
-│   │   ├── commands-test.js         # CLI command structure tests
-│   │   ├── create-record-test.js    # Record creation tests
-│   │   ├── relationships-test.js    # Relationship wiring tests
-│   │   ├── environment-test.js      # Environment config tests
-│   │   ├── orm-lifecycle-test.js    # Startup/shutdown lifecycle tests
-│   │   ├── mysql/
-│   │   │   └── mysql-db-startup-test.js  # MySQL startup behavior tests
-│   │   ├── transforms/             # Per-transform unit tests
-│   │   └── utils/
-│   │       └── get-computed-properties-test.js
-│   └── sample/                      # Test fixtures
-│       ├── models/                  # Example model definitions
-│       ├── serializers/             # Example serializers
-│       ├── transforms/              # Custom transform functions
-│       ├── access/                  # Access control classes
-│       ├── db-schema.js             # Test DB schema
-│       ├── constants.js             # Test constants
-│       └── payload.js               # Sample raw + expected data
-├── .claude/                         # Claude AI assistant context docs
-├── .github/workflows/
-│   ├── ci.yml                       # PR CI pipeline
-│   └── publish.yml                  # NPM publish workflow
-├── package.json
-├── .nvmrc                           # Node v24.13.0
-├── .npmignore
-├── .gitignore
-└── LICENSE.md                       # Apache 2.0
-```
-
-## Key Files Reference
-
-| File / Path | Purpose | Category |
-|-------------|---------|----------|
-| `src/main.js` | Orm singleton: initialization, model/serializer/transform loading, DB + REST setup | Core |
-| `src/index.js` | Public API barrel export (Model, Serializer, attr, hooks, etc.) | Core |
-| `src/store.js` | In-memory record storage with relationship-aware unload/cascade | Core |
-| `src/record.js` | Record instances: serialize, format, toJSON (JSON:API), unload | Core |
-| `src/serializer.js` | Base serializer: path mapping, property setup, computed properties | Serialization |
-| `src/manage-record.js` | `createRecord` / `updateRecord` with pending relationship fulfillment | CRUD |
-| `src/orm-request.js` | REST request handler: CRUD routes, hooks wrapper, includes, filters, fields | REST API |
-| `src/hooks.js` | Middleware hook registry: before/after hooks with halting | Middleware |
-| `src/db.js` | JSON file persistence: read, save, directory mode, auto-save via cron | Persistence |
-| `src/mysql/mysql-db.js` | MySQL driver: load records on init, persist CRUD, migration prompts | Persistence |
-| `src/mysql/schema-introspector.js` | Model introspection to MySQL schema + DDL generation | MySQL |
-| `src/mysql/migration-generator.js` | Schema diff and `.sql` migration file generation | MySQL |
-| `src/commands.js` | CLI commands for DB migrations (file/directory mode + MySQL) | CLI |
-| `config/environment.js` | Default configuration with env var overrides | Config |
-
-## Data Flow
-
-**Typical REST request lifecycle:**
-
-1. **Request arrives** at auto-generated route (e.g., `POST /animals`) via `@stonyx/rest-server`
-2. **Access control** (`OrmRequest.auth`) calls the access class's `access()` method -- returns permissions, filter function, or denial
-3. **Before hooks** run sequentially -- can halt the operation by returning a value (status code or response object)
-4. **Handler executes** the CRUD operation (reads from / writes to the in-memory `Store`)
-5. **MySQL persistence** (if configured) -- `MysqlDB.persist()` writes to MySQL after in-memory mutation
-6. **After hooks** run sequentially with enriched context (record, response, oldState)
-7. **Auto-save** (if `autosave: 'onUpdate'`) writes the entire store to the JSON file
-8. **Response** returned as JSON:API format with optional `included` sideloaded relationships
-
-**Record creation flow:**
-
-1. `createRecord(modelName, rawData, options)` called
-2. Auto-increment ID assigned if missing (or pending MySQL ID in MySQL mode)
-3. Model + Serializer instantiated, Record wrapper created
-4. `record.serialize()` maps raw data through serializer paths, applies transforms, wires relationships
-5. Record stored in `Store` by ID
-6. Global, pending hasMany, and pending belongsTo relationships fulfilled
-
-## API / Routes
-
-Auto-generated REST endpoints for each model with an access class:
-
-| Method | Route Pattern | Operation | Notes |
-|--------|--------------|-----------|-------|
-| GET | `/:models` | List collection | Supports `?filter[path]=value`, `?fields[model]=attr1,attr2`, `?include=rel1,rel2.nested` |
-| GET | `/:models/:id` | Get single record | Same query params as list; returns 404 if not found |
-| POST | `/:models` | Create record | Body: `{ data: { type, id?, attributes } }`; 400 if no type; 409 if duplicate ID |
-| PATCH | `/:models/:id` | Update record | Body: `{ data: { attributes } }`; updates only provided fields |
-| DELETE | `/:models/:id` | Delete record | Removes from store; no response body |
-| GET | `/:models/:id/:relationship` | Related resource | Returns full related records (array for hasMany, single for belongsTo) |
-| GET | `/:models/:id/relationships/:relationship` | Relationship linkage | Returns JSON:API linkage objects with `links.self` and `links.related` |
-
-**Include parameter** supports comma-separated relationships and dot-notation nesting: `?include=owner.pets,traits`
-
-**Fields parameter** supports sparse fieldsets: `?fields[animals]=age,size`
-
-**Filter parameter** supports dot-path filtering: `?filter[owner]=angela`
-
-## Database & Models
-
-### Model Definition
-
-Models extend `Model` and define attributes with `attr(type)` and relationships with `hasMany(model)` / `belongsTo(model)`. Getters become computed properties.
-
-### In-Memory Store
-
-`Store.data` is a `Map<modelName, Map<recordId, Record>>`. O(1) lookup by model + ID.
-
-### JSON File Persistence
-
-Two modes configured via `db.mode`:
-- **`'file'`** (default): Single `db.json` file
-- **`'directory'`**: Per-collection files in a directory (e.g., `db/animals.json`)
-
-Auto-save modes: `'true'` (cron interval), `'false'` (disabled), `'onUpdate'` (after each write operation)
-
-### MySQL Persistence
-
-Enabled when `MYSQL_HOST` env var is set. Uses mysql2 connection pool. On init, loads all records from MySQL into the in-memory store. CRUD operations persist to MySQL after in-memory mutation. Supports:
-- Schema introspection from model definitions
-- Migration generation via schema diffs (`.snapshot.json`)
-- Migration apply/rollback with transactions
-- Schema drift detection on startup
-- Auto-increment ID re-keying after INSERT
-
-### Relationship System
-
-| Type | Handler | Storage | Resolution |
-|------|---------|---------|------------|
-| `hasMany` | `src/has-many.js` | Array of Records | Inline objects, ID references, or pending queue |
-| `belongsTo` | `src/belongs-to.js` | Single Record or null | Inline object, ID reference, or pending queue |
-
-Relationships are bidirectional: creating a `belongsTo` automatically populates the inverse `hasMany`, and vice versa. Pending relationships resolve when the target record is created later.
-
-## Authentication & Authorization
-
-Access control is defined via access classes in the configured `paths.access` directory:
-
-```javascript
-export default class GlobalAccess {
-  models = ['owner', 'animal']; // or '*' for all
-  access(request) {
-    // Return false → 403 Forbidden
-    // Return ['read', 'create', 'update', 'delete'] → allowed methods
-    // Return (record) => boolean → filter function for collections
-  }
-}
-```
-
-Method mapping: `GET → 'read'`, `POST → 'create'`, `DELETE → 'delete'`, `PATCH → 'update'`
-
-## Configuration & Environment
-
-Located in `config/environment.js`. All values overridable via environment variables:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `DB_AUTO_SAVE` | `'false'` | Auto-save mode: `'true'`, `'false'`, or `'onUpdate'` |
-| `DB_FILE` | `'db.json'` | JSON file path |
-| `DB_MODE` | `'file'` | `'file'` or `'directory'` |
-| `DB_DIRECTORY` | `'db'` | Directory name for collection files |
-| `DB_SAVE_INTERVAL` | `3600` | Auto-save interval in seconds |
-| `DB_SCHEMA_PATH` | `'./config/db-schema.js'` | Path to DB schema |
-| `ORM_MODEL_PATH` | `'./models'` | Models directory |
-| `ORM_SERIALIZER_PATH` | `'./serializers'` | Serializers directory |
-| `ORM_TRANSFORM_PATH` | `'./transforms'` | Transforms directory |
-| `ORM_ACCESS_PATH` | `'./access'` | Access classes directory |
-| `ORM_USE_REST_SERVER` | `'true'` | Enable auto REST route generation |
-| `ORM_REST_ROUTE` | `'/'` | Base route for REST endpoints |
-| `MYSQL_HOST` | undefined | Enables MySQL mode when set |
-| `MYSQL_PORT` | `3306` | MySQL port |
-| `MYSQL_USER` | `'root'` | MySQL user |
-| `MYSQL_PASSWORD` | `''` | MySQL password |
-| `MYSQL_DATABASE` | `'stonyx'` | MySQL database name |
-| `MYSQL_CONNECTION_LIMIT` | `10` | Connection pool size |
-| `MYSQL_MIGRATIONS_DIR` | `'migrations'` | Migration files directory |
-
-## Development Guide
-
-| Task | Command |
-|------|---------|
-| Install deps | `pnpm install` |
-| Run tests | `stonyx test` (or `npm test`) |
-| Node version | v24.13.0 (see `.nvmrc`) |
-| Generate MySQL migration | `stonyx db:generate-migration <description>` |
-| Apply MySQL migrations | `stonyx db:migrate` |
-| Rollback MySQL migration | `stonyx db:migrate:rollback` |
-| Migration status | `stonyx db:migrate:status` |
-| Migrate DB file→directory | `stonyx db:migrate-to-directory` |
-| Migrate DB directory→file | `stonyx db:migrate-to-file` |
-
-**Local development** uses `file:../package-name` references in `package.json` for sibling Stonyx packages.
-
-## Testing
-
-| Aspect | Detail |
-|--------|--------|
-| Framework | QUnit via `stonyx test` |
-| Mocking | Sinon |
-| Unit tests | `test/unit/` — transforms, commands, relationships, environment, lifecycle, MySQL startup |
-| Integration tests | `test/integration/` — full ORM pipeline, directory-mode DB |
-| Test fixtures | `test/sample/` — models, serializers, transforms, access, payload, constants |
-| Test config | `test/config/environment.js` |
-
-## Deployment & CI/CD
-
-| Pipeline | Trigger | Workflow |
-|----------|---------|----------|
-| CI | Pull requests to `dev` or `main` | Shared via `abofs/stonyx-workflows/.github/workflows/ci.yml@main` |
-| Publish | Push to `main`, manual dispatch | Shared via `abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main` |
-
-Published to npm as `@stonyx/orm` with public access and provenance.
-
-## Conventions & Standards
-
-- **Files**: kebab-case (e.g., `phone-number.js`)
-- **Models**: PascalCase + `Model` suffix (e.g., `PhoneNumberModel`)
-- **Serializers**: PascalCase + `Serializer` suffix (e.g., `AnimalSerializer`)
-- **Transforms**: Original filename as key (e.g., `animal.js` → `'animal'` transform)
-- **Model names in code**: kebab-case (e.g., `'phone-number'`)
-- **REST routes**: Pluralized, dasherized (e.g., `/phone-numbers`)
-- **Relationship URLs**: Dasherized (e.g., `phoneNumbers` → `/phone-numbers`)
-- **ES Modules**: All files use `import`/`export`
-- **License headers**: Apache 2.0 in core source files
-- **Git workflow**: Feature branches → `dev` → `main`
-
-## Known Issues & Technical Debt
-
-See [improvements.md](improvements.md) for detailed findings. Key items:
-
-- `config/environment.js` contains a stray `console.log(MYSQL_HOST)` statement
-- `getOrSet` utility is duplicated across `has-many.js` and `belongs-to.js`
-- `getRelationshipInfo()` is duplicated across `orm-request.js`, `schema-introspector.js`, and `meta-request.js`
-- `getCollectionKeys()` and `getDirPath()` are duplicated between `db.js` and `migrate.js`
-- Package exports in `package.json` are missing `./commands` and `./hooks` entries (present in code but not in the outline docs)
-- The outline doc (`/.claude/personal/outline.md`) references files that don't exist (`src/include-parser.js`, `src/include-collector.js`, `stonyx-bootstrap.cjs`) and lists version as `0.1.0` (actual: `0.2.1-beta.1`)

package/test-events-setup.js

@@ -1,41 +0,0 @@
-/**
- * Debug script to verify event setup
- */
-
-import Stonyx from 'stonyx';
-import config from './config/environment.js';
-import Orm from './src/main.js';
-import { subscribe } from '@stonyx/events';
-
-// Override paths for tests
-Object.assign(config.paths, {
-  access: './test/sample/access',
-  model: './test/sample/models',
-  serializer: './test/sample/serializers',
-  transform: './test/sample/transforms'
-});
-
-// Override db settings for tests
-Object.assign(config.db, {
-  file: './test/sample/db.json',
-  schema: './test/sample/db-schema.js'
-});
-
-new Stonyx(config, import.meta.dirname);
-
-const orm = new Orm();
-await orm.init();
-
-console.log('ORM initialized');
-console.log('Store keys:', Array.from(Orm.store.data.keys()));
-
-// Try subscribing to an event
-try {
-  const unsubscribe = subscribe('before:create:animal', (context) => {
-    console.log('Hook called!', context);
-  });
-  console.log('✓ Successfully subscribed to before:create:animal');
-  unsubscribe();
-} catch (error) {
-  console.error('✗ Failed to subscribe:', error.message);
-}

package/test-hooks-manual.js

@@ -1,54 +0,0 @@
-/**
- * Manual test script for hooks functionality
- * Run with: node test-hooks-manual.js
- */
-
-import { setup, subscribe, emit } from '@stonyx/events';
-
-console.log('Testing hooks system...\n');
-
-// Setup events
-const eventNames = ['before:create:animal', 'after:create:animal'];
-setup(eventNames);
-
-let beforeCalled = false;
-let afterCalled = false;
-let contextReceived = null;
-
-// Subscribe to hooks
-const unsubscribe1 = subscribe('before:create:animal', async (context) => {
-  console.log('✓ before:create:animal hook called');
-  console.log('  Context:', JSON.stringify(context, null, 2));
-  beforeCalled = true;
-  contextReceived = context;
-});
-
-const unsubscribe2 = subscribe('after:create:animal', async (context) => {
-  console.log('✓ after:create:animal hook called');
-  console.log('  Context:', JSON.stringify(context, null, 2));
-  afterCalled = true;
-});
-
-// Simulate hook execution
-const testContext = {
-  model: 'animal',
-  operation: 'create',
-  body: { data: { type: 'animals', attributes: { name: 'Test' } } }
-};
-
-console.log('Emitting before:create:animal...');
-await emit('before:create:animal', testContext);
-
-console.log('\nEmitting after:create:animal...');
-await emit('after:create:animal', { ...testContext, record: { id: 1, name: 'Test' } });
-
-console.log('\n--- Test Results ---');
-console.log('Before hook called:', beforeCalled ? '✓ PASS' : '✗ FAIL');
-console.log('After hook called:', afterCalled ? '✓ PASS' : '✗ FAIL');
-console.log('Context passed correctly:', contextReceived?.model === 'animal' ? '✓ PASS' : '✗ FAIL');
-
-// Cleanup
-unsubscribe1();
-unsubscribe2();
-
-console.log('\n✓ Hooks system working correctly!');

package/test-hooks-with-logging.js

@@ -1,52 +0,0 @@
-/**
- * Test to verify hooks wrapper is being called
- */
-
-import { emit } from '@stonyx/events';
-
-// Simulate the _withHooks wrapper
-function _withHooks(operation, handler, model) {
-  console.log(`Creating wrapper for ${operation} on ${model}`);
-
-  return async (request, state) => {
-    console.log(`Wrapper called for ${operation} on ${model}`);
-
-    const context = {
-      model,
-      operation,
-      request,
-    };
-
-    console.log(`About to emit before:${operation}:${model}`);
-    await emit(`before:${operation}:${model}`, context);
-    console.log(`Emitted before hook`);
-
-    const response = await handler(request, state);
-    console.log(`Handler completed`);
-
-    context.response = response;
-    await emit(`after:${operation}:${model}`, context);
-    console.log(`Emitted after hook`);
-
-    return response;
-  };
-}
-
-// Simulate a handler
-const createHandler = ({ body }) => {
-  console.log('Original handler called');
-  return { data: { id: 1, ...body } };
-};
-
-// Create wrapped handler
-const wrappedHandler = _withHooks('create', createHandler, 'animal');
-
-// Simulate a request
-const mockRequest = {
-  body: { name: 'Test' }
-};
-
-console.log('\n=== Testing wrapper ===');
-const result = await wrappedHandler(mockRequest, {});
-console.log('Result:', result);
-console.log('\n✓ Wrapper test completed');