@stonyx/orm 0.2.0 → 0.2.3-alpha.0

package/.claude/{CLAUDE.md → project-structure.md}

@@ -12,6 +12,7 @@
 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. **Event System**: Pub/sub events for CRUD operations with before/after hooks
 
 ---
 
@@ -28,28 +29,29 @@
 7. **Relationships** ([src/has-many.js](src/has-many.js), [src/belongs-to.js](src/belongs-to.js)) - Relationship handlers
 8. **Include Parser** ([src/include-parser.js](src/include-parser.js)) - Parses include query params
 9. **Include Collector** ([src/include-collector.js](src/include-collector.js)) - Collects and deduplicates included records
+10. **Events** (from `@stonyx/events`) - Pub/sub event system for CRUD hooks
 
 ### Project Structure
 
 ```
 stonyx-orm/
 ├── src/
-│   ├── index.js                  # Main exports
+│   ├── index.js                  # Main exports (includes ormEvents)
 │   ├── main.js                   # Orm class
 │   ├── model.js                  # Base Model
 │   ├── record.js                 # Record instances
 │   ├── serializer.js             # Base Serializer
-│   ├── store.js                  # In-memory storage
+│   ├── store.js                  # In-memory storage (emits delete events)
 │   ├── 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
+│   ├── manage-record.js          # createRecord/updateRecord (emits create events)
 │   ├── model-property.js         # Transform handler
 │   ├── transforms.js             # Built-in transforms
 │   ├── setup-rest-server.js      # REST integration
-│   ├── orm-request.js            # CRUD request handler
+│   ├── orm-request.js            # CRUD request handler (emits update events)
 │   └── meta-request.js           # Meta endpoint (dev only)
 ├── config/
 │   └── environment.js            # Default configuration
@@ -380,9 +382,138 @@ config.orm = {
 **Dependencies:**
 - `stonyx` - Main framework (peer)
 - `@stonyx/utils` - File/string utilities
-- `@stonyx/cron` - Scheduled tasks
+- `@stonyx/events` - Pub/sub event system for CRUD hooks
+- `@stonyx/cron` - Scheduled tasks (used by DB for auto-save)
 - `@stonyx/rest-server` - REST API
 
+## Event System
+
+The ORM emits events during CRUD operations, allowing applications to hook into the data lifecycle.
+
+### Event Architecture
+
+**Event Source**: `@stonyx/events` (Events class)
+**Integration**: `src/index.js` initializes singleton `ormEvents` instance
+**Event Registration**: 6 events registered on initialization:
+- `create:before`, `create:after`
+- `update:before`, `update:after`
+- `delete:before`, `delete:after`
+
+### Event Emission Points
+
+**CREATE Events** - `src/manage-record.js`:
+```javascript
+// Line ~34: Before serialization
+Events.instance?.emit('create:before', {
+  model: modelName,
+  record,
+  rawData,
+  options
+});
+
+// Line ~88: After record fully created
+Events.instance?.emit('create:after', {
+  model: modelName,
+  record,
+  data: record.__data,
+  rawData,
+  options
+});
+```
+
+**UPDATE Events** - `src/orm-request.js` (PATCH handler):
+```javascript
+// Line ~155: Before applying updates
+const oldData = { ...record.__data };
+Events.instance?.emit('update:before', {
+  model,
+  record,
+  data: record.__data,
+  oldData,
+  rawData: attributes,
+  options: {}
+});
+
+// Line ~173: After updates applied
+Events.instance?.emit('update:after', {
+  model,
+  record,
+  data: record.__data,
+  oldData,
+  rawData: attributes,
+  options: {}
+});
+```
+
+**DELETE Events** - `src/store.js` (unloadRecord):
+```javascript
+// Line ~45: Before cleanup
+Events.instance?.emit('delete:before', {
+  model,
+  record,
+  data: { ...record.__data },
+  options
+});
+
+// Line ~65: After deletion
+Events.instance?.emit('delete:after', {
+  model,
+  record: null,
+  data: null,
+  options
+});
+```
+
+### Design Decisions
+
+**Fire Without Await**: Events are emitted without `await` to maintain backward compatibility
+- `createRecord()` remains synchronous
+- `unloadRecord()` remains synchronous
+- Synchronous handlers execute immediately
+- Async handlers run in background
+
+**Optional Chaining**: Uses `Events.instance?.emit()` for zero overhead when not used
+
+**Error Isolation**: Event errors are caught in Events class, never crash ORM operations
+
+### Usage Patterns
+
+**Auditing**:
+```javascript
+import { ormEvents } from '@stonyx/orm';
+
+ormEvents.subscribe('update:after', ({ model, data, oldData }) => {
+  auditLog.write({
+    action: 'update',
+    model,
+    changes: diff(oldData, data),
+    timestamp: Date.now()
+  });
+});
+```
+
+**Auto-Timestamps**:
+```javascript
+ormEvents.subscribe('create:before', ({ record }) => {
+  record.__data.createdAt = new Date().toISOString();
+});
+
+ormEvents.subscribe('update:before', ({ record }) => {
+  record.__data.updatedAt = new Date().toISOString();
+});
+```
+
+**Cache Invalidation**:
+```javascript
+ormEvents.subscribe('update:after', ({ model, record }) => {
+  cache.invalidate(`${model}:${record.id}`);
+});
+
+ormEvents.subscribe('delete:after', ({ model, record }) => {
+  if (record) cache.invalidate(`${model}:${record.id}`);
+});
+```
+
 ---
 
 ## Critical Files for Common Tasks
@@ -412,7 +543,7 @@ config.orm = {
 
 **Import the ORM:**
 ```javascript
-import { Orm, Model, Serializer, attr, hasMany, belongsTo, createRecord, updateRecord, store } from '@stonyx/orm';
+import { Orm, Model, Serializer, attr, hasMany, belongsTo, createRecord, updateRecord, store, ormEvents } from '@stonyx/orm';
 ```
 
 **Initialize:**

package/.github/workflows/publish.yml

@@ -0,0 +1,143 @@
+name: Publish to NPM
+
+on:
+  # Manual trigger (kept for flexibility)
+  workflow_dispatch:
+    inputs:
+      version-type:
+        description: 'Version type'
+        required: true
+        type: choice
+        options:
+          - alpha
+          - patch
+          - minor
+          - major
+      custom-version:
+        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
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write  # Required for npm provenance
+  pull-requests: write  # For PR comments
+
+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!`
+            });

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.0",
+  "version": "0.2.3-alpha.0",
   "description": "",
   "main": "src/main.js",
   "type": "module",
@@ -12,9 +12,6 @@
     ".": "./src/index.js",
     "./db": "./src/exports/db.js"
   },
-  "scripts": {
-    "test": "qunit --require ./stonyx-bootstrap.cjs"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/abofs/stonyx-orm.git"
@@ -25,20 +22,25 @@
     "Stone Costa <stone.costa@synamicd.com>"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "bugs": {
     "url": "https://github.com/abofs/stonyx-orm/issues"
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "stonyx": "^0.2.2"
+    "stonyx": "^0.2.2",
+    "@stonyx/events": "^0.1.0",
+    "@stonyx/cron": "^0.2.0"
   },
   "devDependencies": {
-    "@stonyx/cron": "^0.2.0",
     "@stonyx/rest-server": "^0.2.0",
     "@stonyx/utils": "^0.2.2",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
+  },
+  "scripts": {
+    "test": "qunit --require ./stonyx-bootstrap.cjs"
   }
-}
+}

package/src/model-property.js

@@ -22,6 +22,8 @@ export default class ModelProperty {
       return this._value = newValue;
     }
 
+    if (newValue === undefined || newValue === null) return;
+
     this._value = Orm.instance.transforms[this.type](newValue);
   }
 }

package/src/orm-request.js

@@ -114,6 +114,51 @@ function parseInclude(includeParam) {
     .map(rel => rel.split('.')); // Parse nested paths: "owner.pets" → ["owner", "pets"]
 }
 
+function parseFields(query) {
+  const fields = new Map();
+  if (!query) return fields;
+
+  for (const [key, value] of Object.entries(query)) {
+    const match = key.match(/^fields\[(\w+)\]$/);
+    if (match && typeof value === 'string') {
+      const modelName = match[1];
+      const fieldNames = value.split(',').map(f => f.trim()).filter(f => f);
+      fields.set(modelName, new Set(fieldNames));
+    }
+  }
+
+  return fields;
+}
+
+function parseFilters(query) {
+  const filters = [];
+  if (!query) return filters;
+
+  for (const [key, value] of Object.entries(query)) {
+    const match = key.match(/^filter\[(.+)\]$/);
+    if (match && typeof value === 'string') {
+      filters.push({ path: match[1].split('.'), value });
+    }
+  }
+
+  return filters;
+}
+
+function createFilterPredicate(filters) {
+  if (filters.length === 0) return null;
+
+  return (record) => filters.every(({ path, value }) => {
+    let current = record;
+
+    for (const segment of path) {
+      if (current == null) return false;
+      current = current[segment];
+    }
+
+    return String(current) === value;
+  });
+}
+
 export default class OrmRequest extends Request {
   constructor({ model, access }) {
     super(...arguments);
@@ -123,20 +168,30 @@ export default class OrmRequest extends Request {
 
     this.handlers = {
       get: {
-        [`/${pluralizedModel}`]: (request, { filter }) => {
+        [`/${pluralizedModel}`]: (request, { filter: accessFilter }) => {
           const allRecords = Array.from(store.get(model).values());
-          const recordsToReturn = filter ? allRecords.filter(filter) : allRecords;
-          const data = recordsToReturn.map(record => record.toJSON());
 
+          const queryFilters = parseFilters(request.query);
+          const queryFilterPredicate = createFilterPredicate(queryFilters);
+          const fieldsMap = parseFields(request.query);
+          const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+
+          let recordsToReturn = allRecords;
+          if (accessFilter) recordsToReturn = recordsToReturn.filter(accessFilter);
+          if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
+
+          const data = recordsToReturn.map(record => record.toJSON({ fields: modelFields }));
           return buildResponse(data, request.query?.include, recordsToReturn);
         },
 
         [`/${pluralizedModel}/:id`]: (request) => {
           const record = store.get(model, getId(request.params));
+          if (!record) return 404;
 
-          if (!record) return 404; // Record not found
+          const fieldsMap = parseFields(request.query);
+          const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
-          return buildResponse(record.toJSON(), request.query?.include, record);
+          return buildResponse(record.toJSON({ fields: modelFields }), request.query?.include, record);
         }
       },
 
@@ -160,14 +215,17 @@ export default class OrmRequest extends Request {
       },
 
       post: {
-        [`/${pluralizedModel}`]: ({ body }) => {
-          const { attributes } = body?.data || {};
+        [`/${pluralizedModel}`]: (request) => {
+          const { attributes } = request.body?.data || {};
 
           if (!attributes) return 400; // Bad request
 
+          const fieldsMap = parseFields(request.query);
+          const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+
           const record = createRecord(model, attributes, { serialize: false });
 
-          return { data: record.toJSON() };
+          return { data: record.toJSON({ fields: modelFields }) };
         }
       },
 

package/src/record.js

@@ -48,21 +48,29 @@ export default class Record {
   }
 
   // Formats record for JSON API output
-  toJSON() {
+  toJSON(options = {}) {
     if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
-    
+
     const { __data:data } = this;
+    const { fields } = options;
     const relationships = {};
-    const attributes = { ...data };
-    delete attributes.id;
+    const attributes = {};
+
+    for (const [key, value] of Object.entries(data)) {
+      if (key === 'id') continue;
+      if (fields && !fields.has(key)) continue;
+      attributes[key] = value;
+    }
 
     for (const [key, getter] of getComputedProperties(this.__model)) {
+      if (fields && !fields.has(key)) continue;
       attributes[key] = getter.call(this);
     }
 
-    for (const [ key, childRecord ] of Object.entries(this.__relationships)) {
+    for (const [key, childRecord] of Object.entries(this.__relationships)) {
+      if (fields && !fields.has(key)) continue;
       relationships[key] = {
-        data: Array.isArray(childRecord) 
+        data: Array.isArray(childRecord)
         ? childRecord.map(r => ({ type: r.__model.__name, id: r.id }))
         : childRecord ? { type: childRecord.__model.__name, id: childRecord.id } : null
       };