@stonyx/orm 0.2.0 → 0.2.1-alpha.1

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/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

@@ -0,0 +1,35 @@
+name: Publish to NPM
+
+on:
+  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, dev]
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+  pull-requests: write
+
+jobs:
+  publish:
+    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 }}
+    secrets: inherit

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.0",
+  "version": "0.2.1-alpha.1",
   "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,19 @@ export default class OrmRequest extends Request {
       },
 
       post: {
-        [`/${pluralizedModel}`]: ({ body }) => {
-          const { attributes } = body?.data || {};
+        [`/${pluralizedModel}`]: ({ body, query }) => {
+          const { type, attributes } = body?.data || {};
 
-          if (!attributes) return 400; // Bad request
+          if (!type) return 400; // Bad request
+
+          const fieldsMap = parseFields(query);
+          const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+          // Check for duplicate ID
+          if (attributes?.id !== undefined && store.get(model, attributes.id)) return 409; // Conflict
 
           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
       };