@stonyx/orm 0.2.1-alpha.0 → 0.2.1-alpha.10

package/.claude/usage-patterns.md

@@ -0,0 +1,234 @@
+# 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)

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

package/.github/workflows/publish.yml

@@ -1,7 +1,8 @@
 name: Publish to NPM
 
 on:
-  # Manual trigger (kept for flexibility)
+  repository_dispatch:
+    types: [cascade-publish]
   workflow_dispatch:
     inputs:
       version-type:
@@ -9,7 +10,6 @@ on:
         required: true
         type: choice
         options:
-          - alpha
           - patch
           - minor
           - major
@@ -17,127 +17,35 @@ on:
         description: 'Custom version (optional, overrides version-type)'
         required: false
         type: string
-
-  # Auto-publish alpha on PR
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: [main, dev]
-
-  # Auto-publish stable on merge to main
+    branches: [main]
   push:
     branches: [main]
 
+concurrency:
+  group: ${{ github.event_name == 'repository_dispatch' && 'cascade-update' || format('publish-{0}', github.ref) }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
-  id-token: write  # Required for npm provenance
-  pull-requests: write  # For PR comments
+  id-token: write
+  pull-requests: write
 
 jobs:
   publish:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-          # For PR events, check out the PR branch
-          ref: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
-
-      - 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'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
-
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      # Determine version type based on trigger
-      - name: Determine version bump type
-        id: version-type
-        run: |
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
-            echo "type=alpha" >> $GITHUB_OUTPUT
-          elif [ "${{ github.event_name }}" = "push" ]; then
-            echo "type=patch" >> $GITHUB_OUTPUT
-          elif [ "${{ github.event.inputs.custom-version }}" != "" ]; then
-            echo "type=custom" >> $GITHUB_OUTPUT
-          else
-            echo "type=${{ github.event.inputs.version-type }}" >> $GITHUB_OUTPUT
-          fi
-
-      # Version bumping
-      - name: Bump version (custom)
-        if: steps.version-type.outputs.type == 'custom'
-        run: pnpm version ${{ github.event.inputs.custom-version }} --no-git-tag-version
-
-      - name: Bump version (alpha)
-        if: steps.version-type.outputs.type == 'alpha'
-        run: pnpm version prerelease --preid=alpha --no-git-tag-version
-
-      - name: Bump version (patch/minor/major)
-        if: steps.version-type.outputs.type == 'patch' || steps.version-type.outputs.type == 'minor' || steps.version-type.outputs.type == 'major'
-        run: pnpm version ${{ steps.version-type.outputs.type }} --no-git-tag-version
-
-      - name: Get package version
-        id: package-version
-        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
-
-      # Publishing
-      - name: Publish to NPM (alpha)
-        if: contains(steps.package-version.outputs.version, 'alpha')
-        run: pnpm publish --tag alpha --access public --no-git-checks
-
-      - name: Publish to NPM (stable)
-        if: "!contains(steps.package-version.outputs.version, 'alpha')"
-        run: pnpm publish --access public
-
-      # Only commit and tag for stable releases (push to main or manual stable)
-      - name: Commit version bump and create tag
-        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !contains(steps.package-version.outputs.version, 'alpha'))
-        run: |
-          git add package.json
-          git commit -m "chore: release v${{ steps.package-version.outputs.version }}"
-          git tag v${{ steps.package-version.outputs.version }}
-          git push origin main --tags
-
-      - name: Create GitHub Release
-        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !contains(steps.package-version.outputs.version, 'alpha'))
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: v${{ steps.package-version.outputs.version }}
-          release_name: v${{ steps.package-version.outputs.version }}
-          draft: false
-          prerelease: false
-
-      # Add PR comment with alpha version info
-      - name: Comment on PR with alpha version
-        if: github.event_name == 'pull_request'
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const version = '${{ steps.package-version.outputs.version }}';
-            const packageName = require('./package.json').name;
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: `## 🚀 Alpha Version Published\n\n**Version:** \`${version}\`\n\n**Install:**\n\`\`\`bash\npnpm add ${packageName}@${version}\n# or\npnpm add ${packageName}@alpha  # latest alpha\n\`\`\`\n\nThis alpha version is now available for testing!`
-            });
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
+    with:
+      version-type: ${{ github.event.inputs.version-type }}
+      custom-version: ${{ github.event.inputs.custom-version }}
+      cascade-source: ${{ github.event.client_payload.source_package || '' }}
+    secrets: inherit
+
+  cascade:
+    needs: publish
+    uses: abofs/stonyx-workflows/.github/workflows/cascade.yml@main
+    with:
+      package-name: ${{ needs.publish.outputs.package-name }}
+      published-version: ${{ needs.publish.outputs.published-version }}
+    secrets: inherit