@stonyx/orm 0.2.1-beta.2 → 0.2.1-beta.21

package/src/orm-request.js

@@ -1,6 +1,9 @@
 import { Request } from '@stonyx/rest-server';
-import { createRecord, store } from '@stonyx/orm';
-import { pluralize } from '@stonyx/utils/string';
+import Orm, { createRecord, updateRecord, store } from '@stonyx/orm';
+import { camelCaseToKebabCase } from '@stonyx/utils/string';
+import { getPluralName } from './plural-registry.js';
+import { getBeforeHooks, getAfterHooks } from './hooks.js';
+import config from 'stonyx/config';
 
 const methodAccessMap = {
   GET: 'read',
@@ -9,15 +12,62 @@ const methodAccessMap = {
   PATCH: 'update',
 };
 
+const WRITE_OPERATIONS = new Set(['create', 'update', 'delete']);
+
+// Helper to detect relationship type from function
+function getRelationshipInfo(property) {
+  if (typeof property !== 'function') return null;
+  const fnStr = property.toString();
+  if (fnStr.includes(`getRelationships('belongsTo',`)) {
+    return { type: 'belongsTo', isArray: false };
+  }
+  if (fnStr.includes(`getRelationships('hasMany',`)) {
+    return { type: 'hasMany', isArray: true };
+  }
+  return null;
+}
+
+// Helper to introspect model relationships
+function getModelRelationships(modelName) {
+  const { modelClass } = Orm.instance.getRecordClasses(modelName);
+  if (!modelClass) return {};
+
+  const model = new modelClass(modelName);
+  const relationships = {};
+
+  for (const [key, property] of Object.entries(model)) {
+    if (key.startsWith('__')) continue;
+    const info = getRelationshipInfo(property);
+    if (info) {
+      relationships[key] = info;
+    }
+  }
+
+  return relationships;
+}
+
+// Helper to build base URL from request
+function getBaseUrl(request) {
+  const protocol = request.protocol || 'http';
+  const host = request.get('host');
+  return `${protocol}://${host}`;
+}
+
 function getId({ id }) {
   if (isNaN(id)) return id;
 
   return parseInt(id);
 }
 
-function buildResponse(data, includeParam, recordOrRecords) {
+function buildResponse(data, includeParam, recordOrRecords, options = {}) {
+  const { links, baseUrl } = options;
   const response = { data };
 
+  // Add top-level links
+  if (links) {
+    response.links = links;
+  }
+
   if (!includeParam) return response;
 
   const includes = parseInclude(includeParam);
@@ -25,7 +75,7 @@ function buildResponse(data, includeParam, recordOrRecords) {
 
   const includedRecords = collectIncludedRecords(recordOrRecords, includes);
   if (includedRecords.length > 0) {
-    response.included = includedRecords.map(record => record.toJSON());
+    response.included = includedRecords.map(record => record.toJSON({ baseUrl }));
   }
 
   return response;
@@ -163,80 +213,284 @@ export default class OrmRequest extends Request {
   constructor({ model, access }) {
     super(...arguments);
 
+    this.model = model;
     this.access = access;
-    const pluralizedModel = pluralize(model);
+    const pluralizedModel = getPluralName(model);
 
-    this.handlers = {
-      get: {
-        [`/${pluralizedModel}`]: (request, { filter: accessFilter }) => {
-          const allRecords = Array.from(store.get(model).values());
+    const modelRelationships = getModelRelationships(model);
 
-          const queryFilters = parseFilters(request.query);
-          const queryFilterPredicate = createFilterPredicate(queryFilters);
-          const fieldsMap = parseFields(request.query);
-          const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+    // Define raw handlers first
+    const getCollectionHandler = async (request, { filter: accessFilter }) => {
+      const allRecords = await store.findAll(model);
 
-          let recordsToReturn = allRecords;
-          if (accessFilter) recordsToReturn = recordsToReturn.filter(accessFilter);
-          if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
+      const queryFilters = parseFilters(request.query);
+      const queryFilterPredicate = createFilterPredicate(queryFilters);
+      const fieldsMap = parseFields(request.query);
+      const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
-          const data = recordsToReturn.map(record => record.toJSON({ fields: modelFields }));
-          return buildResponse(data, request.query?.include, recordsToReturn);
-        },
+      let recordsToReturn = allRecords;
+      if (accessFilter) recordsToReturn = recordsToReturn.filter(accessFilter);
+      if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
 
-        [`/${pluralizedModel}/:id`]: (request) => {
-          const record = store.get(model, getId(request.params));
-          if (!record) return 404;
+      const baseUrl = getBaseUrl(request);
+      const data = recordsToReturn.map(record => record.toJSON({ fields: modelFields, baseUrl }));
 
-          const fieldsMap = parseFields(request.query);
-          const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+      return buildResponse(data, request.query?.include, recordsToReturn, {
+        links: { self: `${baseUrl}/${pluralizedModel}` },
+        baseUrl
+      });
+    };
 
-          return buildResponse(record.toJSON({ fields: modelFields }), request.query?.include, record);
-        }
-      },
+    const getSingleHandler = async (request) => {
+      const record = await store.find(model, getId(request.params));
+      if (!record) return 404;
 
-      patch: {
-        [`/${pluralizedModel}/:id`]: async ({ body, params }) => {
-          const record = store.get(model, getId(params));
-          const { attributes } = body?.data || {};
+      const fieldsMap = parseFields(request.query);
+      const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+
+      const baseUrl = getBaseUrl(request);
+      return buildResponse(record.toJSON({ fields: modelFields, baseUrl }), request.query?.include, record, {
+        links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
+        baseUrl
+      });
+    };
+
+    const createHandler = async ({ body, query }) => {
+      const { type, id, attributes, relationships: rels } = body?.data || {};
+
+      if (!type) return 400; // Bad request
 
-          if (!attributes) return 400; // Bad request
+      const fieldsMap = parseFields(query);
+      const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
-          // 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;
+      // Check for duplicate ID
+      if (id !== undefined && await store.find(model, id)) return 409; // Conflict
 
-            record[key] = value
-          };
+      const { id: _ignoredId, ...sanitizedAttributes } = attributes || {};
 
-          return { data: record.toJSON() };
+      // Extract relationship IDs from JSON:API relationships object
+      if (rels) {
+        for (const [key, value] of Object.entries(rels)) {
+          const relData = value?.data;
+          if (relData && relData.id !== undefined) {
+            sanitizedAttributes[key] = relData.id;
+          }
         }
-      },
+      }
 
-      post: {
-        [`/${pluralizedModel}`]: ({ body, query }) => {
-          const { type, attributes } = body?.data || {};
+      const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
+      const record = createRecord(model, recordAttributes, { serialize: false });
 
-          if (!type) return 400; // Bad request
+      return { data: record.toJSON({ fields: modelFields }) };
+    };
 
-          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 updateHandler = async ({ body, params }) => {
+      const record = await store.find(model, getId(params));
+      const { attributes, relationships: rels } = body?.data || {};
 
-          const record = createRecord(model, attributes, { serialize: false });
+      if (!attributes && !rels) return 400; // Bad request
 
-          return { data: record.toJSON({ fields: modelFields }) };
+      // Apply attribute updates 1 by 1 to utilize built-in transform logic, ignore id key
+      if (attributes) {
+        for (const [key, value] of Object.entries(attributes)) {
+          if (!record.hasOwnProperty(key)) continue;
+          if (key === 'id') continue;
+
+          record[key] = value
+        };
+      }
+
+      // Apply relationship updates via updateRecord to properly resolve references
+      if (rels) {
+        const relUpdates = {};
+        for (const [key, value] of Object.entries(rels)) {
+          const relData = value?.data;
+          if (relData && relData.id !== undefined) {
+            relUpdates[key] = relData.id;
+          }
         }
-      },
+        if (Object.keys(relUpdates).length > 0) {
+          updateRecord(record, relUpdates);
+        }
+      }
+
+      return { data: record.toJSON() };
+    };
 
+    const deleteHandler = ({ params }) => {
+      store.remove(model, getId(params));
+      return 204;
+    };
+
+    // Wrap handlers with hooks
+    this.handlers = {
+      get: {
+        '/': this._withHooks('list', getCollectionHandler),
+        '/:id': this._withHooks('get', getSingleHandler),
+        ...this._generateRelationshipRoutes(model, pluralizedModel, modelRelationships)
+      },
+      patch: {
+        '/:id': this._withHooks('update', updateHandler)
+      },
+      post: {
+        '/': this._withHooks('create', createHandler)
+      },
       delete: {
-        [`/${pluralizedModel}/:id`]: ({ params }) => {
-          store.remove(model, getId(params));
+        '/:id': this._withHooks('delete', deleteHandler)
+      }
+    }
+  }
+
+  // Wraps a handler with before/after hook execution
+  _withHooks(operation, handler) {
+    return async (request, state) => {
+      // Build context object for hooks
+      const context = {
+        model: this.model,
+        operation,
+        request,
+        params: request.params,
+        body: request.body,
+        query: request.query,
+        state,
+      };
+
+      // Capture old state for operations that modify data
+      if (operation === 'update' || operation === 'delete') {
+        const existingRecord = await store.find(this.model, getId(request.params));
+        if (existingRecord) {
+          // Deep copy the record's data to preserve old state
+          context.oldState = JSON.parse(JSON.stringify(existingRecord.__data || existingRecord));
         }
+        if (operation === 'delete') {
+          context.recordId = getId(request.params);
+        }
+      }
+
+      // Run before hooks sequentially (can halt by returning a value)
+      for (const hook of getBeforeHooks(operation, this.model)) {
+        const result = await hook(context);
+        if (result !== undefined) {
+          // Hook returned a value - halt operation and return result
+          return result;
+        }
+      }
+
+      // Execute main handler
+      const response = await handler(request, state);
+
+      // Persist to MySQL for write operations
+      if (Orm.instance.mysqlDb && WRITE_OPERATIONS.has(operation)) {
+        await Orm.instance.mysqlDb.persist(operation, this.model, context, response);
+      }
+
+      // Add response and relevant records to context
+      context.response = response;
+
+      if (operation === 'get' && response?.data && !Array.isArray(response.data)) {
+        context.record = await store.find(this.model, getId(request.params));
+      } else if (operation === 'list' && response?.data) {
+        context.records = await store.findAll(this.model);
+      } else if (operation === 'create' && response?.data?.id) {
+        // For create, get the record from store using the ID from the response
+        const recordId = isNaN(response.data.id) ? response.data.id : parseInt(response.data.id);
+        context.record = store.get(this.model, recordId);
+      } else if (operation === 'update' && response?.data) {
+        context.record = store.get(this.model, getId(request.params));
+      } else if (operation === 'delete') {
+        // For delete, the record may no longer exist, but we have oldState
+        context.recordId = getId(request.params);
+      }
+
+      // Run after hooks sequentially
+      for (const hook of getAfterHooks(operation, this.model)) {
+        await hook(context);
       }
+
+      // Auto-save DB after write operations when configured
+      if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation)) {
+        await Orm.db.save();
+      }
+
+      return response;
+    };
+  }
+
+  _generateRelationshipRoutes(model, pluralizedModel, modelRelationships) {
+    const routes = {};
+
+    for (const [relationshipName, info] of Object.entries(modelRelationships)) {
+      // Dasherize the relationship name for URL paths (e.g., accessLinks -> access-links)
+      const dasherizedName = camelCaseToKebabCase(relationshipName);
+
+      // Related resource route: GET /:id/{relationship}
+      routes[`/:id/${dasherizedName}`] = async (request) => {
+        const record = await store.find(model, getId(request.params));
+        if (!record) return 404;
+
+        const relatedData = record.__relationships[relationshipName];
+        const baseUrl = getBaseUrl(request);
+
+        let data;
+        if (info.isArray) {
+          // hasMany - return array
+          data = (relatedData || []).map(r => r.toJSON({ baseUrl }));
+        } else {
+          // belongsTo - return single or null
+          data = relatedData ? relatedData.toJSON({ baseUrl }) : null;
+        }
+
+        return {
+          links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}` },
+          data
+        };
+      };
+
+      // Relationship linkage route: GET /:id/relationships/{relationship}
+      routes[`/:id/relationships/${dasherizedName}`] = async (request) => {
+        const record = await store.find(model, getId(request.params));
+        if (!record) return 404;
+
+        const relatedData = record.__relationships[relationshipName];
+        const baseUrl = getBaseUrl(request);
+
+        let data;
+        if (info.isArray) {
+          // hasMany - return array of linkage objects
+          data = (relatedData || []).map(r => ({ type: r.__model.__name, id: r.id }));
+        } else {
+          // belongsTo - return single linkage or null
+          data = relatedData ? { type: relatedData.__model.__name, id: relatedData.id } : null;
+        }
+
+        return {
+          links: {
+            self: `${baseUrl}/${pluralizedModel}/${request.params.id}/relationships/${dasherizedName}`,
+            related: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}`
+          },
+          data
+        };
+      };
     }
+
+    // Catch-all for invalid relationship names on related resource route
+    routes[`/:id/:relationship`] = async (request) => {
+      const record = await store.find(model, getId(request.params));
+      if (!record) return 404;
+
+      // If we reach here, relationship doesn't exist (valid ones were registered above)
+      return 404;
+    };
+
+    // Catch-all for invalid relationship names on relationship linkage route
+    routes[`/:id/relationships/:relationship`] = async (request) => {
+      const record = await store.find(model, getId(request.params));
+      if (!record) return 404;
+
+      return 404;
+    };
+
+    return routes;
   }
 
   auth(request, state) {

package/src/plural-registry.js

@@ -0,0 +1,12 @@
+import { pluralize } from './utils.js';
+
+const registry = new Map();
+
+export function registerPluralName(modelName, modelClass) {
+  const plural = modelClass.pluralName || pluralize(modelName);
+  registry.set(modelName, plural);
+}
+
+export function getPluralName(modelName) {
+  return registry.get(modelName) || pluralize(modelName);
+}

package/src/record.js

@@ -1,5 +1,7 @@
 import { store } from './index.js';
 import { getComputedProperties } from "./serializer.js";
+import { camelCaseToKebabCase } from '@stonyx/utils/string';
+import { getPluralName } from './plural-registry.js';
 export default class Record {
   __data = {};
   __relationships = {};
@@ -8,6 +10,7 @@ export default class Record {
   constructor(model, serializer) {
     this.__model = model;
     this.__serializer = serializer;
+
   }
 
   serialize(rawData, options={}) {
@@ -51,8 +54,11 @@ export default class Record {
   toJSON(options = {}) {
     if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
 
+    const { fields, baseUrl } = options;
     const { __data:data } = this;
-    const { fields } = options;
+    const modelName = this.__model.__name;
+    const pluralizedModelName = getPluralName(modelName);
+    const recordId = data.id;
     const relationships = {};
     const attributes = {};
 
@@ -69,19 +75,40 @@ export default class Record {
 
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (fields && !fields.has(key)) continue;
-      relationships[key] = {
-        data: Array.isArray(childRecord)
+
+      const relationshipData = Array.isArray(childRecord)
         ? childRecord.map(r => ({ type: r.__model.__name, id: r.id }))
-        : childRecord ? { type: childRecord.__model.__name, id: childRecord.id } : null
-      };
+        : childRecord ? { type: childRecord.__model.__name, id: childRecord.id } : null;
+
+      // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
+      const dasherizedKey = camelCaseToKebabCase(key);
+
+      relationships[dasherizedKey] = { data: relationshipData };
+
+      // Add links to relationship if baseUrl provided
+      if (baseUrl) {
+        relationships[dasherizedKey].links = {
+          self: `${baseUrl}/${pluralizedModelName}/${recordId}/relationships/${dasherizedKey}`,
+          related: `${baseUrl}/${pluralizedModelName}/${recordId}/${dasherizedKey}`
+        };
+      }
     }
 
-    return {
+    const result = {
       attributes,
       relationships,
-      id: data.id,
-      type: this.__model.__name,
+      id: recordId,
+      type: modelName,
     };
+
+    // Add resource links if baseUrl provided
+    if (baseUrl) {
+      result.links = {
+        self: `${baseUrl}/${pluralizedModelName}/${recordId}`
+      };
+    }
+
+    return result;
   }
 
   unload(options={}) {

package/src/serializer.js

@@ -71,8 +71,8 @@ export default class Serializer {
       const handler = model[key];
       const data = query(rawData, pathPrefix, subPath);
 
-      // Ignore null values on updates (TODO: What if we want it set to null?)
-      if (data === null && options.update) continue;
+      // Ignore null/undefined values on updates (TODO: What if we want it set to null?)
+      if ((data === null || data === undefined) && options.update) continue;
 
       // Relationship handling
       if (typeof handler === 'function') {

package/src/setup-rest-server.js

@@ -5,6 +5,7 @@ import MetaRequest from './meta-request.js';
 import RestServer from '@stonyx/rest-server';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { dbKey } from './db.js';
+import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
 
 export default async function(route, accessPath, metaRoute) {
@@ -42,7 +43,9 @@ export default async function(route, accessPath, metaRoute) {
 
   // Configure endpoints for models with access configuration
   for (const [model, access] of Object.entries(accessFiles)) {
-    RestServer.instance.mountRoute(OrmRequest, { name, options: { model, access } }); 
+    const pluralizedModel = getPluralName(model);
+    const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
+    RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });
   }
 
   // Mount the meta route when metaRoute config is enabled

package/src/store.js

@@ -9,12 +9,117 @@ export default class Store {
     this.data = new Map();
   }
 
+  /**
+   * Synchronous memory-only access.
+   * Returns the record if it exists in the in-memory store, undefined otherwise.
+   * Does NOT query the database. For memory:false models, use find() instead.
+   */
   get(key, id) {
     if (!id) return this.data.get(key);
 
     return this.data.get(key)?.get(id);
   }
 
+  /**
+   * Async authoritative read. Always queries MySQL for memory: false models.
+   * For memory: true models, returns from store (already loaded on boot).
+   * @param {string} modelName - The model name
+   * @param {string|number} id - The record ID
+   * @returns {Promise<Record|undefined>}
+   */
+  async find(modelName, id) {
+    // For memory: true models, the store is authoritative
+    if (this._isMemoryModel(modelName)) {
+      return this.get(modelName, id);
+    }
+
+    // For memory: false models, always query MySQL
+    if (this._mysqlDb) {
+      return this._mysqlDb.findRecord(modelName, id);
+    }
+
+    // Fallback to store (JSON mode or no MySQL)
+    return this.get(modelName, id);
+  }
+
+  /**
+   * Async read for all records of a model. Always queries MySQL for memory: false models.
+   * For memory: true models, returns from store.
+   * @param {string} modelName - The model name
+   * @param {Object} [conditions] - Optional WHERE conditions
+   * @returns {Promise<Record[]>}
+   */
+  async findAll(modelName, conditions) {
+    // For memory: true models without conditions, return from store
+    if (this._isMemoryModel(modelName) && !conditions) {
+      const modelStore = this.get(modelName);
+      return modelStore ? Array.from(modelStore.values()) : [];
+    }
+
+    // For memory: false models (or filtered queries), always query MySQL
+    if (this._mysqlDb) {
+      return this._mysqlDb.findAll(modelName, conditions);
+    }
+
+    // Fallback to store (JSON mode) — apply conditions in-memory if provided
+    const modelStore = this.get(modelName);
+    if (!modelStore) return [];
+
+    const records = Array.from(modelStore.values());
+
+    if (!conditions || Object.keys(conditions).length === 0) return records;
+
+    return records.filter(record =>
+      Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+    );
+  }
+
+  /**
+   * Async query — always hits MySQL, never reads from memory cache.
+   * Use for complex queries, aggregations, or when you need guaranteed freshness.
+   * @param {string} modelName - The model name
+   * @param {Object} conditions - WHERE conditions
+   * @returns {Promise<Record[]>}
+   */
+  async query(modelName, conditions = {}) {
+    if (this._mysqlDb) {
+      return this._mysqlDb.findAll(modelName, conditions);
+    }
+
+    // Fallback: filter in-memory store
+    const modelStore = this.get(modelName);
+    if (!modelStore) return [];
+
+    const records = Array.from(modelStore.values());
+
+    if (Object.keys(conditions).length === 0) return records;
+
+    return records.filter(record =>
+      Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+    );
+  }
+
+  /**
+   * Set by Orm during init — resolves memory flag for a model name.
+   * @type {Function|null}
+   */
+  _memoryResolver = null;
+
+  /**
+   * Set by Orm during init — reference to the MysqlDB instance for on-demand queries.
+   * @type {MysqlDB|null}
+   */
+  _mysqlDb = null;
+
+  /**
+   * Check if a model is configured for in-memory storage.
+   * @private
+   */
+  _isMemoryModel(modelName) {
+    if (this._memoryResolver) return this._memoryResolver(modelName);
+    return true; // default to memory if resolver not set yet
+  }
+
   set(key, value) {
     this.data.set(key, value);
   }

package/src/utils.js

@@ -0,0 +1,12 @@
+import { pluralize as basePluralize } from '@stonyx/utils/string';
+
+// Wrapper to handle dasherized model names (e.g., "access-link" → "access-links")
+export function pluralize(word) {
+  if (word.includes('-')) {
+    const parts = word.split('-');
+    const pluralizedLast = basePluralize(parts.pop());
+    return [...parts, pluralizedLast].join('-');
+  }
+
+  return basePluralize(word);
+}