@stonyx/orm 0.0.7 → 0.2.0

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,16 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.0.7",
+  "version": "0.2.0",
   "description": "",
   "main": "src/main.js",
   "type": "module",
   "exports": {
-    ".": "./src/main.js",
-    "./db": "./src/db.js",
-    "./utils": "./src/utils.js"
+    ".": "./src/index.js",
+    "./db": "./src/exports/db.js"
   },
   "scripts": {
-    "test": "qunit"
+    "test": "qunit --require ./stonyx-bootstrap.cjs"
   },
   "repository": {
     "type": "git",
@@ -25,16 +24,21 @@
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "bugs": {
     "url": "https://github.com/abofs/stonyx-orm/issues"
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "stonyx": "^0.0.7"
+    "stonyx": "^0.2.2"
   },
   "devDependencies": {
-    "@stonyx/cron": "^0.0.6",
-    "@stonyx/utils": "^0.0.4",
-    "qunit": "^2.24.1"
+    "@stonyx/cron": "^0.2.0",
+    "@stonyx/rest-server": "^0.2.0",
+    "@stonyx/utils": "^0.2.2",
+    "qunit": "^2.24.1",
+    "sinon": "^21.0.0"
   }
 }

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;
+  }
+}

package/src/db.js

@@ -1,18 +1,26 @@
-/**
- * TODO:
- * 
- * ORM DB usage assumes that 100% of the data is ORM driven
- * With that assumption, we can safely do the following
- * - On save: Remove computed properties (getters) from data set
- * - On load: Compute computed properties from data set
- *   - Error handling: Warn of non-ORM properties found in data (but load them)
- *   - Optional configuration flag to disable these warnings
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
+
 import Cron from '@stonyx/cron';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
+import Orm, { createRecord, store } from '@stonyx/orm';
 import { createFile, updateFile, readFile } from '@stonyx/utils/file';
-import { deepCopy } from '@stonyx/utils/object';
+
+export const dbKey = '__db';
 
 export default class DB {
   constructor() {
@@ -21,10 +29,22 @@ export default class DB {
     DB.instance = this;
   }
 
-  async init() {
-    await this.retrieve();
+  async getSchema() {
+    const { rootPath } = config;
+    const { file, schema } = config.orm.db;
+
+    if (!file) throw new Error('Configuration Error: ORM DB file path must be defined.');
 
+    return (await import(`${rootPath}/${schema}`)).default;
+  }
+
+  async init() {
     const { autosave, saveInterval } = config.orm.db;
+    
+    store.set(dbKey, new Map());
+    Orm.instance.models[`${dbKey}Model`] = await this.getSchema();
+
+    this.record = await this.getRecord();
 
     if (autosave !== 'true') return;
 
@@ -33,74 +53,28 @@ export default class DB {
 
   async create() {
     const { rootPath } = config;
-    const { file, schema } = config.orm.db;
-
-    if (!file) throw new Error('Configuration Error: ORM DB file path must be defined.');
-
-    let dbSchema;
-
-    try {
-      dbSchema = (await import(`${rootPath}/${schema}`)).default;
-    } catch (error) {
-      dbSchema = {};
-      log.db('Unable to load DB schema from file, using empty schema instead');
-    }
+    const { file } = config.orm.db;
 
-    const data = deepCopy(dbSchema);
-    
-    createFile(`${rootPath}/${file}`, data, { json: true });
+    createFile(`${rootPath}/${file}`, {}, { json: true });
 
-    return data;
+    return {};
   }
   
   async save() {
     const { file } = config.orm.db;
+    const jsonData = this.record.format();
+    delete jsonData.id; // Don't save id
 
-    await updateFile(file, this.data, { json: true });
+    await updateFile(`${config.rootPath}/${file}`, jsonData, { json: true });
 
     log.db(`DB has been successfully saved to ${file}`);
   }
 
-  async retrieve() {
+  async getRecord() {
     const { file } = config.orm.db;
 
-    this.data = await readFile(file, { json: true, missingFileCallback: this.create.bind(this) });
-  }
-
-  /** TODO: We need ORM specific reload logic that replaces models attributes when loading from DB */
-  // _tempORMSerializeMeta(data) {
-  //   const { meta } = data;
-
-  //   // HACK: Create map to ensure we have no duplicate references
-  //   // This will no longer be necessary once once gatherer method prevents duplicates
-  //   const referenceIds = {};
-  //   const { shipmentReportReferences } = meta;
+    const data = await readFile(file, { json: true, missingFileCallback: this.create.bind(this) });
 
-  //   // Fix reference dates & remove duplicates
-  //   for (let i = shipmentReportReferences.length - 1; i >= 0; i--) {
-  //     const record = shipmentReportReferences[i];
-
-  //     if (!referenceIds[record.id]) {
-  //       referenceIds[record.id] = record;
-  //     } else {
-  //       shipmentReportReferences.splice(i, 1);
-  //     }
-
-  //     if (!record.date) continue;
-
-  //     record.date = new Date(record.date);
-  //   }
-
-  //   // Re-compute
-  //   const metaModel = new MODELS.MetaModel();
-
-  //   // Serialize computed properties
-  //   for (const [key, method] of getComputedProperties(metaModel)) {
-  //      const value = method.bind(meta)();
-      
-  //      meta[key] = value;
-  //   }
-
-  //   return data;
-  // }
+    return createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false });
+  }
 }

package/src/exports/db.js

@@ -0,0 +1,7 @@
+import Orm from '@stonyx/orm';
+
+const { db } = Orm;
+
+export default db;
+export const data = db.record;
+export const saveDB = db.save.bind(db);

package/src/has-many.js

@@ -0,0 +1,61 @@
+import { createRecord, relationships, store } from '@stonyx/orm';
+import { getRelationships } from './relationships.js';
+import { getOrSet, makeArray } from '@stonyx/utils/object';
+import { dbKey } from './db.js';
+
+function queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, id) {
+  pendingRelationshipQueue.push({
+    pendingRelationship: getOrSet(pendingRelationships, modelName, new Map()),
+    id
+  });
+
+  return null;
+}
+
+export default function hasMany(modelName) {
+  const globalRelationships = relationships.get('global');
+  const pendingRelationships = relationships.get('pending');
+
+  return (sourceRecord, rawData, options) => {
+    const { __name: sourceModelName } = sourceRecord.__model;
+    const relationshipId = sourceRecord.id;
+    const relationship = getRelationships('hasMany', sourceModelName, modelName, relationshipId);
+    const modelStore = store.get(modelName);
+    const pendingRelationshipQueue = [];
+
+    const output = !rawData ? [] : makeArray(rawData).map(elementData => {
+      let record;
+
+      if (typeof elementData !== 'object') {
+        record = modelStore.get(elementData);
+
+        if (!record) {
+          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+        }
+      } else {
+        if (elementData !== Object(elementData)) {
+          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+        }
+
+        record = createRecord(modelName, elementData, options);
+      }
+
+      // Populate belongTo side if the relationship is defined
+      const otherSide = relationships.get('belongsTo').get(modelName)?.get(sourceModelName)?.get(record.id);
+
+      if (otherSide) Object.assign(otherSide, sourceRecord);
+
+      return record;
+    }).filter(value => value);
+
+    relationship.set(relationshipId, output);
+        
+    // Assign global relationship
+    if (options.global || sourceModelName === dbKey) getOrSet(globalRelationships, modelName, []).push(output);
+
+    // Assign pending relationships
+    for (const { pendingRelationship, id } of pendingRelationshipQueue) getOrSet(pendingRelationship, id, []).push(output);
+
+    return output;
+  }
+}