@stonyx/orm 0.2.1-beta.9 → 0.2.1-beta.90

package/.claude/usage-patterns.md

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

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,51 +0,0 @@
-name: Publish to NPM
-
-on:
-  repository_dispatch:
-    types: [cascade-publish]
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      custom-version:
-        description: 'Custom version (optional, overrides version-type)'
-        required: false
-        type: string
-  pull_request:
-    types: [opened, synchronize, reopened]
-    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
-  pull-requests: write
-
-jobs:
-  publish:
-    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

package/improvements.md

@@ -1,139 +0,0 @@
-# Code Improvements: @stonyx/orm
-
-> Audited: 2026-02-09 | Auto-generated by project-docs-auditor
-
----
-
-## Summary
-
-The codebase is well-structured with clear separation of concerns and consistent patterns. The main areas for improvement are: a debug `console.log` left in production config, duplicated utility functions across multiple files, and documentation that has drifted from the actual code. The MySQL driver is well-tested and cleanly DI'd, but the JSON persistence side lacks equivalent test coverage.
-
-**Findings by priority:**
-| Priority | Count |
-|----------|-------|
-| High | 2 |
-| Medium | 6 |
-| Low | 5 |
-
----
-
-## High Priority
-
-### [H1] Stray `console.log` in production config
-- **Category:** Debug Leak
-- **Files:** `config/environment.js`
-- **Lines:** L57
-- **Problem:** `console.log(MYSQL_HOST)` is left at the bottom of the environment config file. This will log the MySQL host (or `undefined`) on every application startup, leaking configuration details to stdout.
-- **Suggestion:** Remove the `console.log(MYSQL_HOST)` line entirely.
-- **Impact:** Eliminates unintended log noise and prevents leaking configuration values in production.
-
-### [H2] Duplicated `getRelationshipInfo()` function
-- **Category:** WET Code
-- **Files:** `src/orm-request.js` (L18-28), `src/mysql/schema-introspector.js` (L6-14), `src/meta-request.js` (L33-34)
-- **Problem:** The pattern of inspecting a function's `toString()` for `getRelationships('belongsTo',` or `getRelationships('hasMany',` is repeated in three separate files with slight variations. Each independently detects relationship type from a property.
-- **Suggestion:** Extract a shared `getRelationshipInfo(property)` function into `src/relationships.js` (which already acts as the relationship utility module) and import it from all three consumers.
-- **Impact:** Single source of truth for relationship detection. Changes to the detection pattern only need to happen in one place.
-
----
-
-## Medium Priority
-
-### [M1] Duplicated `getOrSet` helper
-- **Category:** WET Code
-- **Files:** `src/has-many.js` (imports from `@stonyx/utils/object`), `src/belongs-to.js` (L4-7)
-- **Problem:** `belongs-to.js` defines its own local `getOrSet(map, key, defaultValue)` function identical to the one available from `@stonyx/utils/object` that `has-many.js` already imports.
-- **Suggestion:** Replace the local `getOrSet` in `belongs-to.js` with `import { getOrSet } from '@stonyx/utils/object'`.
-- **Impact:** Eliminates duplicated code and maintains consistency with `has-many.js`.
-
-### [M2] Duplicated `getCollectionKeys()` and `getDirPath()`
-- **Category:** WET Code
-- **Files:** `src/db.js` (L42-61), `src/migrate.js` (L7-26)
-- **Problem:** Both files contain identical `getCollectionKeys()` and `getDirPath()` functions. The migration module duplicated these from the DB class as standalone functions.
-- **Suggestion:** Export these methods from `src/db.js` (or extract into a shared `src/db-utils.js`) and import them in `src/migrate.js`.
-- **Impact:** Eliminates duplication and ensures migration logic always matches DB logic.
-
-### [M3] `TYPES` array missing `pendingBelongsTo`
-- **Category:** Bug Risk
-- **Files:** `src/relationships.js` (L43)
-- **Lines:** L43
-- **Problem:** `export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending']` is missing `'pendingBelongsTo'`, which is a relationship type initialized in `src/main.js` (L48). The `TYPES` array is used by `store.unloadAllRecords()` (L75) for cleanup, meaning `pendingBelongsTo` entries won't be cleaned up when unloading all records for a model.
-- **Suggestion:** Add `'pendingBelongsTo'` to the `TYPES` array.
-- **Impact:** Prevents potential stale pending belongsTo references when unloading all records for a model.
-
-### [M4] `introspectModels` called repeatedly on every persist operation
-- **Category:** Performance
-- **Files:** `src/mysql/mysql-db.js` (L147, L193, L231)
-- **Problem:** `_persistCreate`, `_persistUpdate`, and `_persistDelete` all call `this.deps.introspectModels()` on every single write operation. Schema introspection iterates all models, creates instances, and inspects properties. Since model schemas don't change at runtime, this is unnecessary repeated work.
-- **Suggestion:** Cache the introspected schemas in `MysqlDB.init()` (or lazily on first access) and reuse the cached result in persist methods.
-- **Impact:** Reduces CPU overhead on every write operation, especially significant with frequent CRUD activity.
-
-### [M5] `startup()` also calls `introspectModels()` separately from `loadAllRecords()`
-- **Category:** Performance
-- **Files:** `src/mysql/mysql-db.js` (L69, L88)
-- **Problem:** `startup()` calls `introspectModels()` at L69 for drift detection, but `loadAllRecords()` (called at L62 inside the migration-apply branch) also calls `introspectModels()` at L88. When migrations are applied, `introspectModels()` runs three times: once in `loadAllRecords` (via init), once in reloaded `loadAllRecords`, and once for drift check.
-- **Suggestion:** Same as M4 — cache the result.
-- **Impact:** Reduces redundant schema introspection calls during startup.
-
-### [M6] No test coverage for JSON DB `save()` and `getRecord()` flows
-- **Category:** Test Gap
-- **Files:** `src/db.js`
-- **Problem:** The JSON file persistence layer (`DB` class) lacks unit tests for its core `save()`, `getRecord()`, `getRecordFromDirectory()`, `getRecordFromFile()`, and `validateMode()` methods. The MySQL driver has thorough unit tests via dependency injection, but the JSON DB has no equivalent.
-- **Suggestion:** Add unit tests for `src/db.js`, potentially using the same DI pattern used by `MysqlDB` to mock file operations.
-- **Impact:** Increases confidence in the JSON persistence path, which is the default storage mode.
-
----
-
-## Low Priority
-
-### [L1] Documentation references non-existent files
-- **Category:** Stale Docs
-- **Files:** `.claude/index.md` (L38-39), `.claude/personal/outline.md` (L1107)
-- **Problem:** The `.claude/index.md` references `src/include-parser.js` and `src/include-collector.js` which don't exist — include parsing is inline in `src/orm-request.js`. The outline references `stonyx-bootstrap.cjs` which doesn't exist.
-- **Suggestion:** Remove the `include-parser.js` and `include-collector.js` references from `.claude/index.md` and the `stonyx-bootstrap.cjs` reference from the outline. Update the architecture section to point to `src/orm-request.js` for include logic.
-- **Impact:** Prevents confusion when navigating docs.
-
-### [L2] Outdated version in outline doc
-- **Category:** Stale Docs
-- **Files:** `.claude/personal/outline.md` (L1076)
-- **Problem:** Lists version as `0.1.0` but `package.json` shows `0.2.1-beta.1`.
-- **Suggestion:** Update or remove the version reference. Since `package.json` is the source of truth, the docs shouldn't duplicate it.
-- **Impact:** Minor — prevents stale version confusion.
-
-### [L3] Outline docs missing `./commands` and `./hooks` package exports
-- **Category:** Stale Docs
-- **Files:** `.claude/personal/outline.md` (L884-889)
-- **Problem:** The package.json `exports` section in the outline doc only shows `"."` and `"./db"`, but the actual `package.json` also exports `"./migrate"`, `"./commands"`, and `"./hooks"`.
-- **Suggestion:** Update the outline's package.json section to match the actual exports.
-- **Impact:** Minor — ensures docs reflect the full public API surface.
-
-### [L4] Outline references old event-based system
-- **Category:** Stale Docs
-- **Files:** `.claude/index.md` (L204)
-- **Problem:** States `@stonyx/events - Pub/sub event system (optional, not used for hooks)`. However, `@stonyx/events` is imported and `setup(eventNames)` is called in `src/main.js` (L91). The events are set up but the hooks system uses its own registry. This is confusing — events are initialized but the hooks use a separate middleware pattern.
-- **Suggestion:** Clarify that `@stonyx/events` is still initialized for event names during ORM setup, but the actual hook dispatch uses the middleware-based system in `src/hooks.js`.
-- **Impact:** Reduces confusion about the relationship between `@stonyx/events` and the hooks system.
-
-### [L5] Manual test scripts in project root
-- **Category:** Dead Code
-- **Files:** `test-hooks-with-logging.js`, `test-events-setup.js`, `test-hooks-manual.js`
-- **Problem:** Three manual test scripts remain in the project root from the hooks implementation. They were used to verify functionality when the test harness had linking issues, but are not part of the test suite and won't run via `npm test`.
-- **Suggestion:** Either move them to `test/manual/` or remove them if the hooks implementation is considered stable and the test harness issues are resolved.
-- **Impact:** Cleaner project root; reduces confusion about which test files are authoritative.
-
----
-
-## Refactoring Roadmap
-
-**Quick wins (do first):**
-1. **H1** — Delete one line (`console.log(MYSQL_HOST)`) in config
-2. **M1** — Replace local `getOrSet` in `belongs-to.js` with import
-3. **M3** — Add `'pendingBelongsTo'` to `TYPES` array
-
-**Medium effort:**
-4. **H2** — Extract shared `getRelationshipInfo` into `relationships.js`
-5. **M2** — Extract shared `getCollectionKeys`/`getDirPath` from `db.js`
-
-**Longer term:**
-6. **M4/M5** — Cache introspected schemas in MysqlDB
-7. **M6** — Add DB unit tests
-8. **L1-L4** — Documentation cleanup pass