@stonyx/orm 0.1.0 → 0.2.0

package/src/index.js

@@ -0,0 +1,28 @@
+/*
+ * 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 Model from './model.js';
+import Serializer from './serializer.js';
+
+import attr from './attr.js';
+import belongsTo from './belongs-to.js';
+import hasMany from './has-many.js';
+import { createRecord, updateRecord } from './manage-record.js';
+
+export { default } from './main.js';
+export { store, relationships } from './main.js';
+export { Model, Serializer }; // base classes
+export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers

package/src/main.js

@@ -14,50 +14,85 @@
  * limitations under the License.
  */
 
-import DB from "@stonyx/orm/db";
-import config from "stonyx/config";
-import BaseModel from "./model.js";
-import BaseSerializer from "./serializer.js";
-import ModelProperty from "./model-property.js";
-import Record from "./record.js";
-import { makeArray } from "@stonyx/utils/object";
-import { forEachFileImport } from "@stonyx/utils/file";
-import { kebabCaseToPascalCase, pluralize } from "@stonyx/utils/string";
-import baseTransforms from "./transforms.js";
+import DB from './db.js';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { forEachFileImport } from '@stonyx/utils/file';
+import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
+import setupRestServer from './setup-rest-server.js';
+import baseTransforms from './transforms.js';
+import Store from './store.js';
+import Serializer from './serializer.js';
+
+const defaultOptions = {
+  dbType: 'json'
+}
 
 export default class Orm {
-  initialized = false;
+  static initialized = false;
+  static relationships = new Map();
+  static store = new Store();
   
   models = {};
   serializers = {};
   transforms = { ...baseTransforms };
+  warnings = new Set();
 
-  constructor() {
+  constructor(options={}) {
     if (Orm.instance) return Orm.instance;
 
+    const { relationships } = Orm;
+
+    // Declare relationship maps
+    for (const key of ['hasMany', 'belongsTo', 'global', 'pending', 'pendingBelongsTo']) {
+      relationships.set(key, new Map());
+    }
+
+    this.options = { ...defaultOptions, ...options };
+
     Orm.instance = this;
   }
 
   async init() {
-    const { paths } = config.orm;
+    const { paths, restServer } = config.orm;
     const promises = ['Model', 'Serializer', 'Transform'].map(type => {
       const lowerCaseType = type.toLowerCase();
       const path = paths[lowerCaseType];
+
       if (!path) throw new Error(`Configuration Error: ORM path for "${type}" must be defined.`);
 
       return forEachFileImport(path, (exported, { name }) => {
         // Transforms keep their original name, everything else gets converted to PascalCase with the type suffix
         const alias = type === 'Transform' ? name : `${kebabCaseToPascalCase(name)}${type}`;
 
+        if (type === 'Model') Orm.store.set(name, new Map());
+
         return this[pluralize(lowerCaseType)][alias] = exported;
-      }, { ignoreAccessFailure: true, rawName: true });
+      }, { ignoreAccessFailure: true, rawName: true, recursive: true, recursiveNaming: true });
     });
 
-    promises.push(new DB().init());
-
+    // Wait for imports before db & rest server setup
     await Promise.all(promises);
-    
-    this.initialized = true;
+
+    if (this.options.dbType !== 'none') {
+      const db = new DB();
+      this.db = db;
+      
+      promises.push(db.init());
+    }
+
+    if (restServer.enabled === 'true') {
+      promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
+    }
+
+    Orm.ready = await Promise.all(promises);
+    Orm.initialized = true;
+  }
+
+  static get db() {
+    if (!Orm.initialized) throw new Error('ORM has not been initialized yet');
+
+    return Orm.instance.db;
   }
 
   getRecordClasses(modelName) {
@@ -65,36 +100,20 @@ export default class Orm {
   
     return {
       modelClass: this.models[`${modelClassPrefix}Model`],
-      serializerClass: this.serializers[`${modelClassPrefix}Serializer`] || BaseSerializer
+      serializerClass: this.serializers[`${modelClassPrefix}Serializer`] || Serializer
     };
   }
-}
-
-export { BaseModel, BaseSerializer };
 
-export function attr() {
-  return new ModelProperty(...arguments);
-}
-
-export function belongsTo(modelName) {
-  return rawData => createRecord(modelName, rawData);
-}
+  // Queue warnings to avoid the same error from being logged in the same iteration
+  warn(message) {
+    this.warnings.add(message);
 
-export function hasMany(modelName) {
-  return rawData => makeArray(rawData).map(elementData => createRecord(modelName, elementData));
+    setTimeout(() => {
+      this.warnings.forEach(warning => log.warn(warning));
+      this.warnings.clear();
+    }, 0);
+  }
 }
 
-export function createRecord(modelName, rawData={}) {
-  if (!Orm.instance.initialized) throw new Error("ORM is not ready");
-
-  const { modelClass, serializerClass } = Orm.instance.getRecordClasses(modelName);
-
-  if (!modelClass) throw new Error(`A model named "${modelName}" does not exist`);
-
-  const model = new modelClass(modelName);
-  const serializer = new serializerClass(model);
-  const record = new Record(model, serializer);
-
-  record.serialize(rawData);
-  return record;
-}
+export const store = Orm.store;
+export const relationships = Orm.relationships;

package/src/manage-record.js

@@ -0,0 +1,103 @@
+import Orm, { store, relationships } from '@stonyx/orm';
+import Record from './record.js';
+
+const defaultOptions = {
+  isDbRecord: false,
+  serialize: true,
+  transform: true
+};
+
+export function createRecord(modelName, rawData={}, userOptions={}) {
+  const orm = Orm.instance;
+  const { initialized } = Orm;
+  const options = { ...defaultOptions, ...userOptions };
+
+  if (!initialized && !options.isDbRecord) throw new Error('ORM is not ready');
+
+  const modelStore = store.get(modelName);
+  const globalRelationships = relationships.get('global');
+  const pendingRelationships = relationships.get('pending');
+
+  assignRecordId(modelName, rawData);
+  if (modelStore.has(rawData.id)) return modelStore.get(rawData.id);
+
+  const { modelClass, serializerClass } = orm.getRecordClasses(modelName);
+
+  if (!modelClass) throw new Error(`A model named '${modelName}' does not exist`);
+
+  const model = new modelClass(modelName);
+  const serializer = new serializerClass(model);
+  const record = new Record(model, serializer);
+
+  record.serialize(rawData, options);
+  modelStore.set(record.id, record);
+
+  // populate global hasMany relationships
+  const globalHasMany = globalRelationships.get(modelName);
+  if (globalHasMany) for (const relationship of globalHasMany) relationship.push(record);
+
+  // populate pending hasMany relationships and clear the queue
+  const pendingHasMany = pendingRelationships.get(modelName)?.get(record.id);
+  if (pendingHasMany) {
+    for (const relationship of pendingHasMany) relationship.push(record);
+    pendingHasMany.splice(0);
+  }
+
+  // Fulfill pending belongsTo relationships
+  const pendingBelongsToQueue = relationships.get('pendingBelongsTo');
+  const pendingBelongsTo = pendingBelongsToQueue.get(modelName)?.get(record.id);
+
+  if (pendingBelongsTo) {
+    const belongsToReg = relationships.get('belongsTo');
+    const hasManyReg = relationships.get('hasMany');
+
+    for (const { sourceRecord, sourceModelName, relationshipKey, relationshipId } of pendingBelongsTo) {
+      // Update the belongsTo relationship on the source record
+      sourceRecord.__relationships[relationshipKey] = record;
+      sourceRecord[relationshipKey] = record; // Also update the direct property
+
+      // Update the belongsTo relationship registry
+      const sourceModelReg = belongsToReg.get(sourceModelName);
+      if (sourceModelReg) {
+        const targetModelReg = sourceModelReg.get(modelName);
+        if (targetModelReg) {
+          targetModelReg.set(relationshipId, record);
+        }
+      }
+
+      // Wire inverse hasMany if it exists
+      const inverseHasMany = hasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
+
+      if (inverseHasMany && !inverseHasMany.includes(sourceRecord)) {
+        inverseHasMany.push(sourceRecord);
+      }
+    }
+
+    // Clear the pending queue
+    pendingBelongsTo.length = 0;
+  }
+
+  return record;
+}
+
+export function updateRecord(record, rawData, userOptions={}) {
+  if (!rawData) throw new Error('rawData must be passed in to updateRecord call');
+
+  const options = { ...defaultOptions, ...userOptions, update:true };
+
+  record.serialize(rawData, options);
+}
+
+/**
+ * gets the next available id based on last record entry.
+ * 
+ * Note/TODO: Records going into a db should get their id from the db instead
+ * Atm, i think the best way to do that would be as an id override that happens after the
+ * record is created
+ */
+function assignRecordId(modelName, rawData) {
+  if (rawData.id) return;
+
+  const modelStore = Array.from(store.get(modelName).values());
+  rawData.id = modelStore.length ? modelStore.at(-1).id + 1 : 1;
+}

package/src/meta-request.js

@@ -0,0 +1,55 @@
+import { Request } from '@stonyx/rest-server';
+import Orm from '@stonyx/orm';
+import config from 'stonyx/config';
+import { dbKey } from './db.js';
+
+export default class MetaRequest extends Request {
+  constructor() {
+    super(...arguments);
+    
+    this.handlers = {
+      get: {
+        '/meta': () => {
+          try {
+            const { models } = Orm.instance;
+            const metadata = {};
+
+            for (const [modelName, modelClass] of Object.entries(models)) {
+              const name = modelName.slice(0, -5).toLowerCase();
+
+              if (name === dbKey) continue;
+
+              const model = new modelClass(modelName);
+              const properties = {};
+
+              // Get regular properties and relationships
+              for (const [key, property] of Object.entries(model)) {
+                // Skip internal properties
+                if (key.startsWith('__')) continue;
+
+                if (property?.constructor?.name === 'ModelProperty') {
+                  properties[key] = { type: property.type };
+                } else if (typeof property === 'function') {
+                  const isBelongsTo = property.toString().includes(`getRelationships('belongsTo',`);
+                  const isHasMany = property.toString().includes(`getRelationships('hasMany',`);
+
+                  if (isBelongsTo || isHasMany) properties[key] = { [isBelongsTo ? 'belongsTo' : 'hasMany']: name };
+                }
+              }
+
+              metadata[name] = properties;
+            }
+
+            return metadata;            
+          } catch (error) {
+            return { error: error.message };
+          }
+        },
+      },
+    }
+  }
+
+  auth() {
+    if (!config.orm.restServer.metaRoute) return 403;
+  }
+}

package/src/model-property.js

@@ -17,6 +17,11 @@ export default class ModelProperty {
   }
 
   set value(newValue) {
+    if (this.ignoreFirstTransform) {
+      delete this.ignoreFirstTransform;
+      return this._value = newValue;
+    }
+
     this._value = Orm.instance.transforms[this.type](newValue);
   }
 }

package/src/model.js

@@ -1,4 +1,8 @@
-export default class BaseModel {
+import { attr } from '@stonyx/orm';
+
+export default class Model {
+  id = attr('number');
+
   constructor(name) {
     this.__name = name;
   }

package/src/orm-request.js

@@ -0,0 +1,189 @@
+import { Request } from '@stonyx/rest-server';
+import { createRecord, store } from '@stonyx/orm';
+import { pluralize } from '@stonyx/utils/string';
+
+const methodAccessMap = {
+  GET: 'read',
+  POST: 'create',
+  DELETE: 'delete',
+  PATCH: 'update',
+};
+
+function getId({ id }) {
+  if (isNaN(id)) return id;
+
+  return parseInt(id);
+}
+
+function buildResponse(data, includeParam, recordOrRecords) {
+  const response = { data };
+
+  if (!includeParam) return response;
+
+  const includes = parseInclude(includeParam);
+  if (includes.length === 0) return response;
+
+  const includedRecords = collectIncludedRecords(recordOrRecords, includes);
+  if (includedRecords.length > 0) {
+    response.included = includedRecords.map(record => record.toJSON());
+  }
+
+  return response;
+}
+
+/**
+ * Recursively traverse an include path and collect related records
+ * @param {Array<Record>} currentRecords - Records to process at current depth
+ * @param {Array<string>} includePath - Full path array (e.g., ['owner', 'pets', 'traits'])
+ * @param {number} depth - Current depth in the path
+ * @param {Map} seen - Deduplication map
+ * @param {Array} included - Accumulator for included records
+ */
+function traverseIncludePath(currentRecords, includePath, depth, seen, included) {
+  if (depth >= includePath.length) return; // Reached end of path
+
+  const relationshipName = includePath[depth];
+  const nextRecords = [];
+
+  for (const record of currentRecords) {
+    if (!record.__relationships) continue;
+    if (!(relationshipName in record.__relationships)) continue;
+
+    const relatedRecords = record.__relationships[relationshipName];
+    if (!relatedRecords) continue;
+
+    // Handle both belongsTo (single) and hasMany (array)
+    const recordsToProcess = Array.isArray(relatedRecords)
+      ? relatedRecords
+      : [relatedRecords];
+
+    for (const relatedRecord of recordsToProcess) {
+      if (!relatedRecord) continue;
+
+      const type = relatedRecord.__model.__name;
+      const id = relatedRecord.id;
+
+      // Initialize Set for this type if needed
+      if (!seen.has(type)) {
+        seen.set(type, new Set());
+      }
+
+      // Check if we've already seen this type+id combination
+      if (!seen.get(type).has(id)) {
+        seen.get(type).add(id);
+        included.push(relatedRecord);
+        nextRecords.push(relatedRecord); // Prepare for next depth level
+      } else if (depth < includePath.length - 1) {
+        // Even if we've seen this record, we might need it for deeper traversal
+        nextRecords.push(relatedRecord);
+      }
+    }
+  }
+
+  // If there are more segments in the path, recursively process
+  if (depth < includePath.length - 1 && nextRecords.length > 0) {
+    traverseIncludePath(nextRecords, includePath, depth + 1, seen, included);
+  }
+}
+
+function collectIncludedRecords(data, includes) {
+  if (!includes || includes.length === 0) return [];
+  if (!data) return [];
+
+  const seen = new Map(); // Map<type, Set<id>> for deduplication
+  const included = [];
+
+  // Normalize to array for consistent processing
+  const records = Array.isArray(data) ? data : [data];
+
+  // Process each include path
+  for (const includePath of includes) {
+    traverseIncludePath(records, includePath, 0, seen, included);
+  }
+
+  return included;
+}
+
+function parseInclude(includeParam) {
+  if (!includeParam || typeof includeParam !== 'string') return [];
+
+  return includeParam
+    .split(',')
+    .map(rel => rel.trim())
+    .filter(rel => rel.length > 0)
+    .map(rel => rel.split('.')); // Parse nested paths: "owner.pets" → ["owner", "pets"]
+}
+
+export default class OrmRequest extends Request {
+  constructor({ model, access }) {
+    super(...arguments);
+
+    this.access = access;
+    const pluralizedModel = pluralize(model);
+
+    this.handlers = {
+      get: {
+        [`/${pluralizedModel}`]: (request, { filter }) => {
+          const allRecords = Array.from(store.get(model).values());
+          const recordsToReturn = filter ? allRecords.filter(filter) : allRecords;
+          const data = recordsToReturn.map(record => record.toJSON());
+
+          return buildResponse(data, request.query?.include, recordsToReturn);
+        },
+
+        [`/${pluralizedModel}/:id`]: (request) => {
+          const record = store.get(model, getId(request.params));
+
+          if (!record) return 404; // Record not found
+
+          return buildResponse(record.toJSON(), request.query?.include, record);
+        }
+      },
+
+      patch: {
+        [`/${pluralizedModel}/:id`]: async ({ body, params }) => {
+          const record = store.get(model, getId(params));
+          const { attributes } = body?.data || {};
+
+          if (!attributes) return 400; // Bad request
+
+          // Apply updates 1 by 1 to utilize built-in transform logic, ignore id key
+          for (const [key, value] of Object.entries(attributes)) {
+            if (!record.hasOwnProperty(key)) continue;
+            if (key === 'id') continue;
+
+            record[key] = value
+          };
+
+          return { data: record.toJSON() };
+        }
+      },
+
+      post: {
+        [`/${pluralizedModel}`]: ({ body }) => {
+          const { attributes } = body?.data || {};
+
+          if (!attributes) return 400; // Bad request
+
+          const record = createRecord(model, attributes, { serialize: false });
+
+          return { data: record.toJSON() };
+        }
+      },
+
+      delete: {
+        [`/${pluralizedModel}/:id`]: ({ params }) => {
+          store.remove(model, getId(params));
+        }
+      }
+    }
+  }
+
+  auth(request, state) {
+    const access = this.access(request);
+
+    if (!access) return 403;
+    if (Array.isArray(access) && !access.includes(methodAccessMap[request.method])) return 403;
+    if (typeof access === 'function') state.filter = access;
+  }
+}

package/src/record.js

@@ -1,7 +1,8 @@
-import DB from "@stonyx/orm/db";
-
+import { store } from './index.js';
+import { getComputedProperties } from "./serializer.js";
 export default class Record {
   __data = {};
+  __relationships = {};
   __serialized = false;
 
   constructor(model, serializer) {
@@ -9,20 +10,83 @@ export default class Record {
     this.__serializer = serializer;
   }
 
-  serialize(rawData) {
+  serialize(rawData, options={}) {
     const { __data:data } = this;
     
-    if (this.__serialized)  return data;
+    if (this.__serialized && !options.update) {
+      const relatedIds = {};
+
+      for (const [ key, childRecord ] of Object.entries(this.__relationships)) {
+        relatedIds[key] = Array.isArray(childRecord) 
+        ? childRecord.map(r => r.id)
+        : childRecord?.id ?? null;
+      }
+
+      return { ...data, ...relatedIds };
+    }
 
     const normalizedData = this.__serializer.normalize(rawData);
-    this.__serializer.setProperties(normalizedData, this);
+    this.__serializer.setProperties(normalizedData, this, options);
 
     return data;
   }
 
-  save() {
-    const { __name:key } = this.__model;
+  // Similar to serialize, but preserves top level relationship records
+  format() {
+    if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
+    
+    const { __data:data } = this;
+    const records = {};
+
+    for (const [ key, childRecord ] of Object.entries(this.__relationships)) {
+      records[key] = Array.isArray(childRecord) 
+      ? childRecord.map(r => r.serialize())
+      : childRecord?.serialize() ?? null;
+    }
+
+    return { ...data, ...records };
+  }
+
+  // Formats record for JSON API output
+  toJSON() {
+    if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
     
-    new DB().data[key] = this.serialize();
+    const { __data:data } = this;
+    const relationships = {};
+    const attributes = { ...data };
+    delete attributes.id;
+
+    for (const [key, getter] of getComputedProperties(this.__model)) {
+      attributes[key] = getter.call(this);
+    }
+
+    for (const [ key, childRecord ] of Object.entries(this.__relationships)) {
+      relationships[key] = {
+        data: Array.isArray(childRecord) 
+        ? childRecord.map(r => ({ type: r.__model.__name, id: r.id }))
+        : childRecord ? { type: childRecord.__model.__name, id: childRecord.id } : null
+      };
+    }
+
+    return {
+      attributes,
+      relationships,
+      id: data.id,
+      type: this.__model.__name,
+    };
+  }
+
+  unload(options={}) {
+    store.unloadRecord(this.__model.__name, this.id, options);
+  }
+
+  clean() {
+    try {
+      for (const key of Object.keys(this)) {
+        delete this[key];
+      }
+    } catch {
+      // Ignore errors during cleanup, as some keys may not be deletable
+    }
   }
 }

package/src/relationships.js

@@ -0,0 +1,43 @@
+import { relationships } from "@stonyx/orm";
+
+export default class Relationships {
+  constructor() {
+    if (Relationships.instance) return Relationships.instance;
+    Relationships.instance = this;
+
+    this.data = new Map();
+  }
+
+  get(key) {
+    return this.data.get(key);
+  }
+
+  set(key, value) {
+    this.data.set(key, value);
+  }
+}
+
+// TODO: Refactor mapping to remove a level of iteration
+export function getRelationships(type, sourceModel, targetModel, relationshipId) {
+  const allRelationships = relationships.get(type);
+  
+  // create relationship map for this type of it doesn't already exist
+  if (!allRelationships.has(sourceModel)) allRelationships.set(sourceModel, new Map());
+  
+  const modelRelationship = allRelationships.get(sourceModel);
+
+  if (!modelRelationship.has(targetModel)) modelRelationship.set(targetModel, new Map());
+
+  const relationship = modelRelationship.get(targetModel);
+
+  // TODO: Determine whether already having id should be handled differently
+  //if (relationship.has(relationshipId)) return;
+
+  return relationship;
+}
+
+export function getHasManyRelationships(sourceModel, targetModel) {
+  return relationships.get('hasMany').get(sourceModel)?.get(targetModel);
+}
+
+export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending'];