@stonyx/orm 0.1.0 → 0.2.1-alpha.0

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/README.md

@@ -1,13 +1,305 @@
-# stonyx-orm
+# @stonyx/orm
 
-## Running the test suite
+A lightweight ORM for Stonyx projects, featuring model definitions, serializers, relationships, transforms, and optional REST server integration.
+`@stonyx/orm` provides a structured way to define models, manage relationships, and persist data in JSON files. It also allows integration with the Stonyx REST server for automatic route setup and access control.
+
+## Highlights
+
+- **Automatic Loading**: Models, serializers, transforms, and access classes are auto-registered from their configured directories.
+- **Models**: Define attributes with type-safe proxies (`attr`) and relationships (`hasMany`, `belongsTo`).
+- **Serializers**: Map raw data into model-friendly structures, including nested properties.
+- **Transforms**: Apply custom transformations on data values automatically.
+- **DB Integration**: Optional file-based persistence with auto-save support.
+- **REST Server Integration**: Automatic route setup with customizable access control.
+
+## Installation
+
+```bash
+npm install @stonyx/orm
+````
+
+## Usage example
+
+This module is part of the **Stonyx framework**. To use it, first configure the `restServer` key in your `environment.js` file:
+
+```js
+const {
+  ORM_ACCESS_PATH,
+  ORM_MODEL_PATH,
+  ORM_REST_ROUTE,
+  ORM_SERIALIZER_PATH,
+  ORM_TRANSFORM_PATH,
+  ORM_USE_REST_SERVER,
+  DB_AUTO_SAVE,
+  DB_FILE,
+  DB_SCHEMA_PATH,
+  DB_SAVE_INTERVAL
+} = process;
+
+export default {
+  orm: {
+    logColor: 'white',
+    logMethod: 'db',
+    
+    db: {
+      autosave: DB_AUTO_SAVE ?? 'false',
+      file: DB_FILE ?? 'db.json',
+      saveInterval: DB_SAVE_INTERVAL ?? 3600, // 1 hour
+      schema: DB_SCHEMA_PATH ?? './config/db-schema.js'
+    },
+    paths: {
+      access: ORM_ACCESS_PATH ?? './access',
+      model: ORM_MODEL_PATH ?? './models',
+      serializer: ORM_SERIALIZER_PATH ?? './serializers',
+      transform: ORM_TRANSFORM_PATH ?? './transforms'
+    },
+    restServer: {
+      enabled: ORM_USE_REST_SERVER ?? 'true',
+      route: ORM_REST_ROUTE ?? '/'
+    }
+  }
+};
+```
+
+Then initialize the Stonyx framework, which auto-initializes all of its modules, including `@stonyx/rest-server`:
+
+```js
+import Stonyx from 'stonyx';
+import config from './config/environment.js';
+
+new Stonyx(config);
+```
+
+For further framework initialization instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
+
+## Models
+
+Define a model with attributes and relationships:
+
+```js
+import { Model, attr, hasMany, belongsTo } from '@stonyx/orm';
+
+export default class OwnerModel extends Model {
+  id = attr('string');
+  age = attr('number');
+  pets = hasMany('animal');
+
+  get totalPets() {
+    return this.pets.length;
+  }
+}
+```
+
+## Serializers
+
+Based on the following sample payload structure which represents a poorly structure third-party data source:
+
+```js
+export default {
+  animals: [
+    { id: 1, type: 'dog', details: { age: 2, c: 'small', x: 'black', location: { type: 'farm', owner: 'angela' }}},
+    //...
+  ]
+}
+```
+
+Map raw data to model fields:
+
+```js
+import { Serializer } from '@stonyx/orm';
+
+export default class AnimalSerializer extends Serializer {
+  map = {
+    age: 'details.age',
+    size: 'details.c',
+    color: 'details.x',
+    owner: 'details.location.owner'
+  }
+}
+```
+
+## Relationships
+
+### belongsTo
+
+```js
+import { belongsTo } from '@stonyx/orm';
+
+class AnimalModel extends Model {
+  owner = belongsTo('owner');
+}
+```
+
+### hasMany
+
+```js
+import { hasMany } from '@stonyx/orm';
+
+class OwnerModel extends Model {
+  pets = hasMany('animal');
+}
+```
+
+## Transforms
+
+Apply custom transforms on field values:
+
+```js
+import { ANIMALS } from '../constants.js';
+
+export default function(value) {
+  return ANIMALS.indexOf(value) || 0;
+}
+```
+
+## Database (DB) Integration
+
+The ORM can automatically save records to a JSON file with optional auto-save intervals.
+
+```js
+import Orm from '@stonyx/orm';
+
+const orm = new Orm();
+await orm.init();
+
+// Access the DB record
+const dbRecord = Orm.db;
+```
+
+Configuration options are in `config/environment.js`:
+
+* `DB_AUTO_SAVE`: Whether to auto-save.
+* `DB_FILE`: File path to store data.
+* `DB_SAVE_INTERVAL`: Interval in seconds for auto-save.
+* `DB_SCHEMA_PATH`: Path to DB schema.
+
+## REST Server Integration
+
+The ORM can automatically register REST routes using your access classes.
+
+```js
+import setupRestServer from '@stonyx/orm/setup-rest-server';
+
+await setupRestServer('/', './access');
+```
+
+Access classes define models and provide custom filtering/authorization logic:
+
+```js
+export default class GlobalAccess {
+  models = ['owner', 'animal'];
+
+  access(request) {
+    if (request.url.endsWith('/owner/angela')) return false;
+    return ['read', 'create', 'update', 'delete'];
+  }
+}
+```
+
+### Include Parameter (Sideloading Relationships)
+
+The ORM supports JSON API-compliant relationship sideloading via the `include` query parameter. This reduces the need for multiple API requests by embedding related records in a single response.
+
+#### Basic Usage
+
+```javascript
+// Fetch animal with owner and traits included
+GET /animals/1?include=owner,traits
+
+// Response:
+{
+  "data": {
+    "type": "animal",
+    "id": 1,
+    "attributes": { "age": 2, "size": "small" },
+    "relationships": {
+      "owner": { "data": { "type": "owner", "id": "angela" } },
+      "traits": { "data": [
+        { "type": "trait", "id": 1 },
+        { "type": "trait", "id": 2 }
+      ]}
+    }
+  },
+  "included": [
+    {
+      "type": "owner",
+      "id": "angela",
+      "attributes": { "age": 36, "gender": "female" },
+      "relationships": { "pets": { "data": [...] } }
+    },
+    {
+      "type": "trait",
+      "id": 1,
+      "attributes": { "type": "habitat", "value": "farm" },
+      "relationships": {}
+    },
+    {
+      "type": "trait",
+      "id": 2,
+      "attributes": { "type": "color", "value": "black" },
+      "relationships": {}
+    }
+  ]
+}
 ```
-npm test
+
+#### Features
+
+- **Comma-separated relationship names:** `?include=owner,traits`
+- **Nested relationship traversal:** `?include=owner.pets,owner.company` (supports multi-level nesting)
+- **Works with collections and single records:** Both GET endpoints support includes
+- **Automatic deduplication:** Each unique record (by type+id) appears only once in included array
+- **Invalid relationships ignored:** Invalid relationship names are silently skipped
+- **Backward compatible:** Omit the include parameter for original behavior (no included array)
+
+#### Examples
+
+```javascript
+// Single resource with single include
+GET /owners/gina?include=pets
+
+// Single resource with multiple includes
+GET /animals/1?include=owner,traits
+
+// Nested includes (NEW!)
+GET /animals/1?include=owner.pets
+
+// Deep nesting (3+ levels)
+GET /scenes/e001-s001?include=slides.dialogue.character
+
+// Collection with includes (deduplicates automatically)
+GET /animals?include=owner
+
+// Combining nested and non-nested includes
+GET /owners?include=pets.traits,company
+
+// No include parameter (backward compatible)
+GET /animals/1
+// Returns: { data: {...} } // No included array
 ```
 
-## TODO:
-- Config validation
-- Use file utils for serializer/model loading
-- Usage Documentation
-- TEST: Core functionality
-- TEST: Base transforms
+**How Nested Includes Work:**
+1. Query param parsed into path segments: `owner.pets` → `['owner', 'pets']`
+2. 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
+
+#### Limitations
+
+- Only available on GET endpoints (not POST/PATCH)
+
+## Exported Helpers
+
+| Export          | Description                                                             |
+| --------------- | ----------------------------------------------------------------------- |
+| `attr`          | Define model attributes with type-safe proxy.                           |
+| `belongsTo`     | Define a one-to-one relationship.                                       |
+| `hasMany`       | Define a one-to-many relationship.                                      |
+| `createRecord`  | Instantiate a record with proper serialization and relationships.       |
+| `store`         | Singleton store for all model instances.                                |
+| `relationships` | Access all relationships (`hasMany`, `belongsTo`, `global`, `pending`). |
+
+## License
+
+Apache — do what you want, just keep attribution.

package/config/environment.js

@@ -1,7 +1,10 @@
 const {
+  ORM_ACCESS_PATH,
   ORM_MODEL_PATH,
+  ORM_REST_ROUTE,
   ORM_SERIALIZER_PATH,
   ORM_TRANSFORM_PATH,
+  ORM_USE_REST_SERVER,
   DB_AUTO_SAVE,
   DB_FILE,
   DB_SCHEMA_PATH,
@@ -19,8 +22,13 @@ export default {
     schema: DB_SCHEMA_PATH ?? './config/db-schema.js'
   },
   paths: {
+    access: ORM_ACCESS_PATH ?? './access', // Optional for restServer access hooks
     model: ORM_MODEL_PATH ?? './models',
     serializer: ORM_SERIALIZER_PATH ?? './serializers',
     transform: ORM_TRANSFORM_PATH ?? './transforms'
+  },
+  restServer: {
+    enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or 
+    route: ORM_REST_ROUTE ?? '/',
   }
 }

package/package.json

@@ -4,17 +4,13 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.0",
+  "version": "0.2.1-alpha.0",
   "description": "",
   "main": "src/main.js",
   "type": "module",
   "exports": {
-    ".": "./src/main.js",
-    "./db": "./src/db.js",
-    "./utils": "./src/utils.js"
-  },
-  "scripts": {
-    "test": "qunit"
+    ".": "./src/index.js",
+    "./db": "./src/exports/db.js"
   },
   "repository": {
     "type": "git",
@@ -25,16 +21,26 @@
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "bugs": {
     "url": "https://github.com/abofs/stonyx-orm/issues"
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "stonyx": "^0.1.0"
+    "stonyx": "^0.2.2",
+    "@stonyx/events": "^0.1.0",
+    "@stonyx/cron": "^0.2.0"
   },
   "devDependencies": {
-    "@stonyx/cron": "^0.1.0",
-    "@stonyx/utils": "^0.1.0",
-    "qunit": "^2.24.1"
+    "@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/attr.js

@@ -0,0 +1,28 @@
+import ModelProperty from './model-property.js';
+
+export default function attr() {
+  const modelProp = new ModelProperty(...arguments);
+
+  return new Proxy(modelProp, {
+    get(target, prop, receiver) {
+      if (prop === 'valueOf' || prop === 'toString') {
+        return () => target.value;
+      }
+
+      if (prop in target) {
+        return Reflect.get(target, prop, receiver);
+      }
+
+      return target.value;
+    },
+
+    set(target, prop, value, receiver) {
+      if (prop === 'value') {
+        target.value = value;
+        return true;
+      }
+
+      return Reflect.set(target, prop, value, receiver);
+    }
+  });
+}

package/src/belongs-to.js

@@ -0,0 +1,63 @@
+import { createRecord, relationships, store } from '@stonyx/orm';
+import { getRelationships } from './relationships.js';
+
+function getOrSet(map, key, defaultValue) {
+  if (!map.has(key)) map.set(key, defaultValue);
+  return map.get(key);
+}
+
+export default function belongsTo(modelName) {
+  const hasManyRelationships = relationships.get('hasMany');
+  const pendingHasManyQueue = relationships.get('pending');
+  const pendingBelongsToQueue = relationships.get('pendingBelongsTo');
+
+  return (sourceRecord, rawData, options) => {
+    if (!rawData) return null;
+
+    const { __name: sourceModelName } = sourceRecord.__model;
+    const relationshipId = sourceRecord.id;
+    const relationshipKey = options._relationshipKey;
+    const relationship = getRelationships('belongsTo', sourceModelName, modelName, relationshipId);
+    const modelStore = store.get(modelName);
+
+    // Try to get existing record
+    const output = typeof rawData === 'object'
+      ? createRecord(modelName, rawData, options)
+      : modelStore.get(rawData);
+
+    // If not found and is a string ID, register as pending
+    if (!output && typeof rawData !== 'object') {
+      const targetId = rawData;
+
+      // Register pending belongsTo
+      const modelPendingMap = getOrSet(pendingBelongsToQueue, modelName, new Map());
+      const targetPendingArray = getOrSet(modelPendingMap, targetId, []);
+
+      targetPendingArray.push({
+        sourceRecord,
+        sourceModelName,
+        relationshipKey,
+        relationshipId
+      });
+
+      relationship.set(relationshipId, null);
+      return null;
+    }
+
+    relationship.set(relationshipId, output || {});
+
+    // Populate hasMany side if the relationship is defined
+    const otherSide = hasManyRelationships.get(modelName)?.get(sourceModelName)?.get(output?.id);
+
+    if (otherSide) {
+      otherSide.push(sourceRecord);
+
+      // Remove pending queue if it was just fulfilled
+      const pendingModelRelationships = pendingHasManyQueue.get(sourceModelName);
+
+      if (pendingModelRelationships) pendingModelRelationships.delete(relationshipId);
+    }
+
+    return output;
+  }
+}