@stonyx/orm 0.2.1-alpha.2 → 0.2.1-alpha.21

package/.claude/usage-patterns.md

@@ -0,0 +1,300 @@
+# Usage Patterns
+
+## 1. Model Definition
+
+Models extend `Model` and use decorators for attributes and relationships:
+
+```javascript
+// test/sample/models/animal.js
+import { Model, attr, belongsTo, hasMany } from '@stonyx/orm';
+
+export default class AnimalModel extends Model {
+  // Attributes with type transforms
+  type = attr('animal');      // Custom transform
+  age = attr('number');       // Built-in transform
+  size = attr('string');
+
+  // Relationships
+  owner = belongsTo('owner'); // Many-to-one
+  traits = hasMany('trait');  // One-to-many
+
+  // Computed properties
+  get tag() {
+    return `${this.owner.id}'s ${this.size} animal`;
+  }
+}
+```
+
+**Key Points:**
+- Use `attr(type)` for simple attributes
+- Use `belongsTo(modelName)` for many-to-one
+- Use `hasMany(modelName)` for one-to-many
+- Getters work as computed properties
+- Relationships auto-establish bidirectionally
+- Override auto-pluralization with `static pluralName` (see [Overriding Plural Names](#overriding-plural-names))
+
+### Overriding Plural Names
+
+By default, model names are auto-pluralized (e.g., `animal` → `animals`) for REST routes, JSON:API URLs, and DB table names. When auto-pluralization produces the wrong result, override it with `static pluralName`:
+
+```javascript
+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 — no additional registration is needed. All internal call sites (REST routes, JSON:API type references, MySQL table names, foreign key references) use the overridden value.
+
+## 2. Serializers (Data Transformation)
+
+Serializers map raw data paths to model properties:
+
+```javascript
+// test/sample/serializers/animal.js
+import { Serializer } from '@stonyx/orm';
+
+export default class AnimalSerializer extends Serializer {
+  map = {
+    // Nested path mapping
+    age: 'details.age',
+    size: 'details.c',
+    owner: 'details.location.owner',
+
+    // Custom transformation function
+    traits: ['details', ({ x:color }) => {
+      const traits = [{ id: 1, type: 'habitat', value: 'farm' }];
+      if (color) traits.push({ id: 2, type: 'color', value: color });
+      return traits;
+    }]
+  }
+}
+```
+
+**Key Points:**
+- `map` object defines field mappings
+- Supports nested paths (`'details.age'`)
+- Custom functions for complex transformations
+- Handlers receive raw data subset
+
+## 3. Custom Transforms
+
+Transforms convert data types:
+
+```javascript
+// test/sample/transforms/animal.js
+const codeEnumMap = { 'dog': 1, 'cat': 2, 'bird': 3 };
+
+export default function(value) {
+  return codeEnumMap[value] || 0;
+}
+```
+
+**Built-in Transforms:**
+- Type: `boolean`, `number`, `float`, `string`, `date`, `timestamp`
+- Math: `round`, `ceil`, `floor`
+- String: `trim`, `uppercase`
+- Utility: `passthrough`
+
+## 4. CRUD Operations
+
+```javascript
+import { createRecord, updateRecord, store } from '@stonyx/orm';
+
+// Create
+createRecord('owner', { id: 'bob', age: 30 });
+
+// Read
+const owner = store.get('owner', 'bob');
+const allOwners = store.get('owner');
+
+// Update
+updateRecord(owner, { age: 31 });
+// Or direct: owner.age = 31;
+
+// Delete
+store.remove('owner', 'bob');
+```
+
+## 5. Database Schema
+
+The DB schema is a Model defining top-level collections:
+
+```javascript
+// test/sample/db-schema.js
+import { Model, hasMany } from '@stonyx/orm';
+
+export default class DBModel extends Model {
+  owners = hasMany('owner');
+  animals = hasMany('animal');
+  traits = hasMany('trait');
+}
+```
+
+## 6. Persistence
+
+```javascript
+import Orm from '@stonyx/orm';
+
+// Save to file
+await Orm.db.save();
+
+// Data auto-serializes to JSON file
+// Reload using createRecord with serialize:false, transform:false
+```
+
+## 7. Access Control
+
+```javascript
+// test/sample/access/global-access.js
+export default class GlobalAccess {
+  models = ['owner', 'animal']; // or '*' for all
+
+  access(request) {
+    // Deny specific access
+    if (request.url.endsWith('/owner/angela')) return false;
+
+    // Filter collections
+    if (request.url.endsWith('/owner')) {
+      return record => record.id !== 'angela';
+    }
+
+    // Grant CRUD permissions
+    return ['read', 'create', 'update', 'delete'];
+  }
+}
+```
+
+## 8. REST API (Auto-generated)
+
+```javascript
+// Endpoints auto-generated for models:
+// GET    /owners          - List all
+// GET    /owners/:id       - Get one
+// POST   /animals          - Create
+// PATCH  /animals/:id      - Update (attributes and/or relationships)
+// DELETE /animals/:id      - Delete
+```
+
+**PATCH supports both attributes and relationships:**
+```javascript
+// Update attributes only
+PATCH /animals/1
+{ data: { type: 'animal', attributes: { age: 5 } } }
+
+// Update relationship only
+PATCH /animals/1
+{ data: { type: 'animal', relationships: { owner: { data: { type: 'owner', id: 'gina' } } } } }
+
+// Update both
+PATCH /animals/1
+{ data: { type: 'animal', attributes: { age: 5 }, relationships: { owner: { data: { type: 'owner', id: 'gina' } } } } }
+```
+
+## 9. Include Parameter (Sideloading)
+
+GET endpoints support sideloading related records with **nested relationship traversal**:
+
+```javascript
+// Single-level includes
+GET /animals/1?include=owner,traits
+
+// Nested includes (NEW!)
+GET /animals/1?include=owner.pets,owner.company
+
+// Deep nesting (3+ levels)
+GET /scenes/e001-s001?include=slides.dialogue.character
+
+// Response structure (unchanged)
+{
+  data: { type: 'animal', id: 1, attributes: {...}, relationships: {...} },
+  included: [
+    { type: 'owner', id: 'angela', ... },
+    { type: 'animal', id: 7, ... },    // owner's other pets
+    { type: 'animal', id: 11, ... },   // owner's other pets
+    { type: 'company', id: 'acme', ... } // owner's company (if requested)
+  ]
+}
+```
+
+**How Nested Includes Work:**
+1. Query param parsed into path segments: `owner.pets` -> `[['owner'], ['owner', 'pets'], ['traits']]`
+2. `traverseIncludePath()` recursively traverses relationships depth-first
+3. Deduplication still by type+id (no duplicates in included array)
+4. Gracefully handles null/missing relationships at any depth
+5. Each included record gets full `toJSON()` representation
+
+**Key Functions:**
+- `parseInclude()` - Splits comma-separated includes and parses nested paths
+- `traverseIncludePath()` - Recursively traverses relationship paths
+- `collectIncludedRecords()` - Orchestrates traversal and deduplication
+- All implemented in [src/orm-request.js](src/orm-request.js)
+
+## 10. Views (Read-Only Computed Data)
+
+Views are read-only projections that compute derived data from existing models. They work in both JSON mode (in-memory) and MySQL mode (auto-generated SQL VIEWs). See the full guide at [views.md](views.md).
+
+### Defining a View
+
+```javascript
+// views/owner-stats.js
+import { View, attr, belongsTo, count, avg } from '@stonyx/orm';
+
+export default class OwnerStatsView extends View {
+  static source = 'owner';  // Required: model whose records produce view records
+
+  animalCount = count('pets');     // COUNT of hasMany relationship
+  averageAge = avg('pets', 'age'); // AVG of a field on related records
+  owner = belongsTo('owner');      // Link back to source record
+}
+```
+
+### Aggregate Helpers
+
+| Helper | Example | JS Behavior | MySQL |
+|--------|---------|-------------|-------|
+| `count(rel)` | `count('pets')` | `records.length` | `COUNT(table.id)` |
+| `avg(rel, field)` | `avg('pets', 'age')` | Average of values | `AVG(table.field)` |
+| `sum(rel, field)` | `sum('pets', 'age')` | Sum of values | `SUM(table.field)` |
+| `min(rel, field)` | `min('pets', 'age')` | Minimum value | `MIN(table.field)` |
+| `max(rel, field)` | `max('pets', 'age')` | Maximum value | `MAX(table.field)` |
+
+### Resolve Map (Escape Hatch)
+
+For fields that can't be expressed as aggregates:
+
+```javascript
+export default class OwnerStatsView extends View {
+  static source = 'owner';
+  static resolve = {
+    gender: 'gender',              // String path from source data
+    score: (owner) => owner.__data.age * 10,  // Function
+  };
+
+  gender = attr('string');  // Must also define as attr()
+  score = attr('number');
+  animalCount = count('pets');
+}
+```
+
+### Querying Views
+
+```javascript
+const stats = await store.findAll('owner-stats');
+const stat = await store.find('owner-stats', ownerId);
+```
+
+### Read-Only Enforcement
+
+```javascript
+createRecord('owner-stats', data);   // Throws: Cannot create records for read-only view
+updateRecord(viewRecord, data);       // Throws: Cannot update records for read-only view
+store.remove('owner-stats', id);      // Throws: Cannot remove records from read-only view
+```
+
+### REST API
+
+Only GET endpoints are mounted for views — no POST, PATCH, or DELETE.

package/.claude/views.md

@@ -0,0 +1,292 @@
+# Views
+
+Views are read-only, model-like structures that compute derived data from existing models. They work in both JSON file mode (in-memory computation) and MySQL mode (auto-generated SQL VIEWs).
+
+## What Views Are
+
+A View defines a read-only projection over source model data. Use views when you need:
+- Aggregated data (counts, averages, sums) derived from model relationships
+- Computed read-only summaries that shouldn't be persisted as separate records
+- MySQL VIEWs that are auto-generated from your JavaScript definition
+
+## Defining a View
+
+Views extend the `View` base class and are placed in the `views/` directory (configurable via `paths.view`).
+
+```javascript
+// views/owner-stats.js
+import { View, attr, belongsTo, count, avg } from '@stonyx/orm';
+
+export default class OwnerStatsView extends View {
+  static source = 'owner'; // The model whose records are iterated
+
+  animalCount = count('pets');    // COUNT of hasMany relationship
+  averageAge = avg('pets', 'age'); // AVG of a field on related records
+  owner = belongsTo('owner');     // Link back to the source record
+}
+```
+
+### File Naming
+
+- File: `owner-stats.js` → Class: `OwnerStatsView` → Store name: `'owner-stats'`
+- Directory: configured via `paths.view` (default: `'./views'`)
+- Environment variable: `ORM_VIEW_PATH`
+
+### Key Static Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `source` | `undefined` | **(Required)** The model name whose records produce view records |
+| `groupBy` | `undefined` | Field name to group source records by (one view record per unique value) |
+| `resolve` | `undefined` | Optional escape-hatch map for custom derivations |
+| `memory` | `false` | `false` = computed on demand; `true` = cached on startup |
+| `readOnly` | `true` | **Enforced** — cannot be overridden to `false` |
+| `pluralName` | `undefined` | Custom plural name (same as Model) |
+
+## Aggregate Helpers
+
+Aggregate helpers define fields that compute values from related records. Each helper knows both its JavaScript computation logic and its MySQL SQL translation.
+
+| Helper | JS Behavior | MySQL Translation |
+|--------|-------------|-------------------|
+| `count(relationship)` | `relatedRecords.length` | `COUNT(table.id)` |
+| `avg(relationship, field)` | Average of field values | `AVG(table.field)` |
+| `sum(relationship, field)` | Sum of field values | `SUM(table.field)` |
+| `min(relationship, field)` | Minimum field value | `MIN(table.field)` |
+| `max(relationship, field)` | Maximum field value | `MAX(table.field)` |
+
+### Empty/Null Handling
+
+- `count` with empty/null relationship → `0`
+- `avg` with empty/null relationship → `0`
+- `sum` with empty/null relationship → `0`
+- `min` with empty/null relationship → `null`
+- `max` with empty/null relationship → `null`
+- Non-numeric values are filtered/treated as 0
+
+## Resolve Map (Escape Hatch)
+
+For computed fields that can't be expressed as aggregates, use `static resolve`:
+
+```javascript
+export default class OwnerStatsView extends View {
+  static source = 'owner';
+
+  static resolve = {
+    gender: 'gender',           // String path: maps from source record data
+    score: (owner) => {         // Function: custom computation
+      return owner.__data.age * 10;
+    },
+    nestedVal: 'details.nested', // Nested string paths supported
+  };
+
+  // Must also define as attr() for the serializer to process
+  gender = attr('string');
+  score = attr('number');
+  nestedVal = attr('passthrough');
+
+  animalCount = count('pets');
+}
+```
+
+**Important:** Each resolve map entry needs a corresponding `attr()` field definition on the view.
+
+## GroupBy Views
+
+GroupBy views produce one view record per unique value of a field on the source model, with aggregates computed within each group.
+
+### Defining a GroupBy View
+
+```javascript
+import { View, attr, count, avg, sum } from '@stonyx/orm';
+
+export default class AnimalCountBySizeView extends View {
+  static source = 'animal';
+  static groupBy = 'size';    // Group animals by their size field
+
+  id = attr('string');         // The group key becomes the id
+  animalCount = count();       // Count records in each group
+  averageAge = avg('age');     // Average of 'age' field within each group
+}
+```
+
+### Aggregate Helpers in GroupBy Views
+
+In groupBy views, aggregate helpers operate on the group's records rather than on relationships:
+
+| Helper | GroupBy Behavior | MySQL Translation |
+|--------|-----------------|-------------------|
+| `count()` | Number of records in the group | `COUNT(*)` |
+| `sum('field')` | Sum of field across group records | `SUM(source.field)` |
+| `avg('field')` | Average of field across group records | `AVG(source.field)` |
+| `min('field')` | Minimum field value in the group | `MIN(source.field)` |
+| `max('field')` | Maximum field value in the group | `MAX(source.field)` |
+
+Relationship aggregates (e.g., `count('traits')`) also work — they flatten related records across all group members and aggregate the combined set.
+
+### Resolve Map in GroupBy Views
+
+The resolve map behaves differently in groupBy views:
+- **Function resolvers** receive the **array of group records** (not a single record)
+- **String path resolvers** take the value from the **first record** in the group
+
+```javascript
+export default class LeagueStatsView extends View {
+  static source = 'game-stats';
+  static groupBy = 'competition';
+
+  static resolve = {
+    totalGoals: (groupRecords) => {
+      return groupRecords.reduce((sum, r) => {
+        const fs = r.__data.finalScore;
+        return fs ? sum + fs[0] + fs[1] : sum;
+      }, 0);
+    },
+  };
+
+  matchCount = count();
+  totalGoals = attr('number');
+}
+```
+
+### MySQL DDL for GroupBy Views
+
+```sql
+CREATE OR REPLACE VIEW `animal-count-by-sizes` AS
+SELECT
+  `animals`.`size` AS `id`,
+  COUNT(*) AS `animalCount`,
+  AVG(`animals`.`age`) AS `averageAge`
+FROM `animals`
+GROUP BY `animals`.`size`
+```
+
+## Querying Views
+
+Views use the same store API as models:
+
+```javascript
+// All view records (computed fresh each call in JSON mode)
+const stats = await store.findAll('owner-stats');
+
+// Single view record by source ID
+const stat = await store.find('owner-stats', ownerId);
+
+// With conditions
+const filtered = await store.findAll('owner-stats', { animalCount: 5 });
+```
+
+## Read-Only Enforcement
+
+Views are strictly read-only at all layers:
+
+```javascript
+// All of these throw errors:
+createRecord('owner-stats', data);        // Error: Cannot create records for read-only view
+updateRecord(viewRecord, data);            // Error: Cannot update records for read-only view
+store.remove('owner-stats', id);           // Error: Cannot remove records from read-only view
+
+// Internal use only — bypasses guard:
+createRecord('owner-stats', data, { isDbRecord: true }); // Used by resolver/loader
+```
+
+## REST API Behavior
+
+When a view is included in an access configuration, only GET endpoints are mounted:
+
+- `GET /view-plural-name` — Returns list of view records
+- `GET /view-plural-name/:id` — Returns single view record
+- `GET /view-plural-name/:id/{relationship}` — Related resources
+- No POST, PATCH, DELETE endpoints
+
+## JSON Mode (In-Memory Resolver)
+
+In JSON/non-MySQL mode, the ViewResolver:
+
+1. Iterates all records of the `source` model from the store
+2. For each source record:
+   - Computes aggregate properties from relationships
+   - Applies resolve map entries (string paths or functions)
+   - Maps regular attr fields from source data
+3. Creates view records via `createRecord` with `isDbRecord: true`
+4. Returns computed array
+
+## MySQL Mode
+
+In MySQL mode:
+
+1. **Schema introspection** generates VIEW metadata via `introspectViews()`
+2. **DDL generation** creates `CREATE OR REPLACE VIEW` SQL from aggregates and relationships
+3. **Queries** use `SELECT * FROM \`view_name\`` just like tables
+4. **Migrations** include `CREATE OR REPLACE VIEW` after table statements
+5. **persist()** is a no-op for views
+6. **loadMemoryRecords()** loads views with `memory: true` from the MySQL VIEW
+
+### Generated SQL Example
+
+For `OwnerStatsView` with `count('pets')` and `avg('pets', 'age')`:
+
+```sql
+CREATE OR REPLACE VIEW `owner-stats` AS
+SELECT
+  `owners`.`id` AS `id`,
+  COUNT(`animals`.`id`) AS `animalCount`,
+  AVG(`animals`.`age`) AS `avgAge`
+FROM `owners`
+  LEFT JOIN `animals` ON `animals`.`owner_id` = `owners`.`id`
+GROUP BY `owners`.`id`
+```
+
+## Migration Support
+
+Views are handled in migrations alongside tables:
+
+- **Added views** → `CREATE OR REPLACE VIEW ...` in UP, `DROP VIEW IF EXISTS ...` in DOWN
+- **Removed views** → Commented `DROP VIEW` warning in UP (matching model removal pattern)
+- **Changed views** → `CREATE OR REPLACE VIEW ...` in UP (replaces automatically)
+- Views appear AFTER table statements in migrations (dependency order)
+- Snapshots include view entries with `isView: true` and `viewQuery`
+
+## Memory Flag
+
+- `static memory = false` (default) — View records are computed fresh on each query
+- `static memory = true` — View records are loaded from MySQL VIEW on startup and cached
+
+## Testing Views
+
+```javascript
+import QUnit from 'qunit';
+import { store } from '@stonyx/orm';
+
+QUnit.test('view returns computed data', async function(assert) {
+  // Create source data
+  createRecord('owner', { id: 1, name: 'Alice' }, { serialize: false });
+  createRecord('animal', { id: 1, age: 3, owner: 1 }, { serialize: false });
+
+  // Query the view
+  const results = await store.findAll('owner-stats');
+  const stat = results.find(r => r.id === 1);
+
+  assert.strictEqual(stat.__data.animalCount, 1);
+});
+```
+
+## Architecture
+
+### Source Files
+
+| File | Purpose |
+|------|---------|
+| `src/view.js` | View base class |
+| `src/aggregates.js` | AggregateProperty class + helper functions |
+| `src/view-resolver.js` | In-memory view resolver |
+| `src/mysql/schema-introspector.js` | `introspectViews()`, `buildViewDDL()` |
+| `src/mysql/migration-generator.js` | `diffViewSnapshots()`, view migration generation |
+
+### Key Design Decisions
+
+1. **View does NOT extend Model** — conceptually separate; shared behavior is minimal
+2. **Driver-agnostic API** — No SQL in view definitions; MySQL driver generates SQL automatically
+3. **Aggregate helpers follow the transform pattern** — Each knows both JS computation and MySQL mapping
+4. **Resolve map mirrors Serializer.map** — String paths or function resolvers
+5. **View schemas are separate** — `introspectViews()` is separate from `introspectModels()`

package/.github/workflows/ci.yml

@@ -2,35 +2,15 @@ name: CI
 
 on:
   pull_request:
-    branches:
-      - dev
-      - main
+    branches: [dev, main]
 
 concurrency:
   group: ci-${{ github.head_ref || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 24.13.0
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
+    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main