@stonyx/orm 0.2.1-beta.7 → 0.2.1-beta.70

package/src/mysql/schema-introspector.js

@@ -1,19 +1,25 @@
 import Orm from '@stonyx/orm';
 import { getMysqlType } from './type-map.js';
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
-import { pluralize } from '../utils.js';
+import { getPluralName } from '../plural-registry.js';
 import { dbKey } from '../db.js';
+import { AggregateProperty } from '../aggregates.js';
 
 function getRelationshipInfo(property) {
   if (typeof property !== 'function') return null;
   const fnStr = property.toString();
+  const modelName = property.__relatedModelName || null;
 
-  if (fnStr.includes(`getRelationships('belongsTo',`)) return 'belongsTo';
-  if (fnStr.includes(`getRelationships('hasMany',`)) return 'hasMany';
+  if (fnStr.includes(`getRelationships('belongsTo',`)) return { type: 'belongsTo', modelName };
+  if (fnStr.includes(`getRelationships('hasMany',`)) return { type: 'hasMany', modelName };
 
   return null;
 }
 
+function sanitizeTableName(name) {
+  return name.replace(/[-/]/g, '_');
+}
+
 export function introspectModels() {
   const { models } = Orm.instance;
   const schemas = {};
@@ -34,12 +40,12 @@ export function introspectModels() {
     for (const [key, property] of Object.entries(model)) {
       if (key.startsWith('__')) continue;
 
-      const relType = getRelationshipInfo(property);
+      const relInfo = getRelationshipInfo(property);
 
-      if (relType === 'belongsTo') {
-        relationships.belongsTo[key] = true;
-      } else if (relType === 'hasMany') {
-        relationships.hasMany[key] = true;
+      if (relInfo?.type === 'belongsTo') {
+        relationships.belongsTo[key] = relInfo.modelName;
+      } else if (relInfo?.type === 'hasMany') {
+        relationships.hasMany[key] = relInfo.modelName;
       } else if (property?.constructor?.name === 'ModelProperty') {
         if (key === 'id') {
           idType = property.type;
@@ -50,20 +56,21 @@ export function introspectModels() {
     }
 
     // Build foreign keys from belongsTo relationships
-    for (const relName of Object.keys(relationships.belongsTo)) {
+    for (const [relName, targetModelName] of Object.entries(relationships.belongsTo)) {
       const fkColumn = `${relName}_id`;
       foreignKeys[fkColumn] = {
-        references: pluralize(relName),
+        references: sanitizeTableName(getPluralName(targetModelName)),
         column: 'id',
       };
     }
 
     schemas[name] = {
-      table: pluralize(name),
+      table: sanitizeTableName(getPluralName(name)),
       idType,
       columns,
       foreignKeys,
       relationships,
+      memory: modelClass.memory === true,
     };
   }
 
@@ -71,7 +78,8 @@ export function introspectModels() {
 }
 
 export function buildTableDDL(name, schema, allSchemas = {}) {
-  const { table, idType, columns, foreignKeys } = schema;
+  const { idType, columns, foreignKeys } = schema;
+  const table = sanitizeTableName(schema.table);
   const lines = [];
 
   // Primary key
@@ -98,7 +106,8 @@ export function buildTableDDL(name, schema, allSchemas = {}) {
 
   // Foreign key constraints
   for (const [fkCol, fkDef] of Object.entries(foreignKeys)) {
-    lines.push(`  FOREIGN KEY (\`${fkCol}\`) REFERENCES \`${fkDef.references}\`(\`${fkDef.column}\`) ON DELETE SET NULL`);
+    const refTable = sanitizeTableName(fkDef.references);
+    lines.push(`  FOREIGN KEY (\`${fkCol}\`) REFERENCES \`${refTable}\`(\`${fkDef.column}\`) ON DELETE SET NULL`);
   }
 
   return `CREATE TABLE IF NOT EXISTS \`${table}\` (\n${lines.join(',\n')}\n)`;
@@ -128,8 +137,8 @@ export function getTopologicalOrder(schemas) {
     if (!schema) return;
 
     // Visit dependencies (belongsTo targets) first
-    for (const relName of Object.keys(schema.relationships.belongsTo)) {
-      visit(relName);
+    for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
+      visit(targetModelName);
     }
 
     order.push(name);
@@ -142,6 +151,164 @@ export function getTopologicalOrder(schemas) {
   return order;
 }
 
+export function introspectViews() {
+  const orm = Orm.instance;
+  if (!orm.views) return {};
+
+  const schemas = {};
+
+  for (const [viewKey, viewClass] of Object.entries(orm.views)) {
+    const name = camelCaseToKebabCase(viewKey.slice(0, -4)); // Remove 'View' suffix
+
+    const source = viewClass.source;
+    if (!source) continue;
+
+    const model = new viewClass(name);
+    const columns = {};
+    const foreignKeys = {};
+    const aggregates = {};
+    const relationships = { belongsTo: {}, hasMany: {} };
+
+    for (const [key, property] of Object.entries(model)) {
+      if (key.startsWith('__')) continue;
+      if (key === 'id') continue;
+
+      if (property instanceof AggregateProperty) {
+        aggregates[key] = property;
+        continue;
+      }
+
+      const relInfo = getRelationshipInfo(property);
+
+      if (relInfo?.type === 'belongsTo') {
+        relationships.belongsTo[key] = relInfo.modelName;
+        const fkColumn = `${key}_id`;
+        foreignKeys[fkColumn] = {
+          references: sanitizeTableName(getPluralName(relInfo.modelName)),
+          column: 'id',
+        };
+      } else if (relInfo?.type === 'hasMany') {
+        relationships.hasMany[key] = relInfo.modelName;
+      } else if (property?.constructor?.name === 'ModelProperty') {
+        const transforms = Orm.instance.transforms;
+        columns[key] = getMysqlType(property.type, transforms[property.type]);
+      }
+    }
+
+    schemas[name] = {
+      viewName: sanitizeTableName(getPluralName(name)),
+      source,
+      groupBy: viewClass.groupBy || undefined,
+      columns,
+      foreignKeys,
+      aggregates,
+      relationships,
+      isView: true,
+      memory: viewClass.memory !== false ? false : false, // Views default to memory:false
+    };
+  }
+
+  return schemas;
+}
+
+export function buildViewDDL(name, viewSchema, modelSchemas = {}) {
+  if (!viewSchema.source) {
+    throw new Error(`View '${name}' must define a source model`);
+  }
+
+  const sourceModelName = viewSchema.source;
+  const sourceSchema = modelSchemas[sourceModelName];
+  const sourceTable = sanitizeTableName(sourceSchema
+    ? sourceSchema.table
+    : getPluralName(sourceModelName));
+
+  const selectColumns = [];
+  const joins = [];
+  const hasAggregates = Object.keys(viewSchema.aggregates || {}).length > 0;
+  const groupByField = viewSchema.groupBy;
+
+  // ID column: groupBy field or source table PK
+  if (groupByField) {
+    selectColumns.push(`\`${sourceTable}\`.\`${groupByField}\` AS \`id\``);
+  } else {
+    selectColumns.push(`\`${sourceTable}\`.\`id\` AS \`id\``);
+  }
+
+  // Aggregate columns
+  for (const [key, aggProp] of Object.entries(viewSchema.aggregates || {})) {
+    if (aggProp.relationship === undefined) {
+      // Field-level aggregate (groupBy views)
+      if (aggProp.aggregateType === 'count') {
+        selectColumns.push(`COUNT(*) AS \`${key}\``);
+      } else {
+        selectColumns.push(`${aggProp.mysqlFunction}(\`${sourceTable}\`.\`${aggProp.field}\`) AS \`${key}\``);
+      }
+    } else {
+      // Relationship aggregate
+      const relName = aggProp.relationship;
+      const relTable = sanitizeTableName(getPluralName(relName));
+
+      if (aggProp.aggregateType === 'count') {
+        selectColumns.push(`${aggProp.mysqlFunction}(\`${relTable}\`.\`id\`) AS \`${key}\``);
+      } else {
+        const field = aggProp.field;
+        selectColumns.push(`${aggProp.mysqlFunction}(\`${relTable}\`.\`${field}\`) AS \`${key}\``);
+      }
+
+      // Add LEFT JOIN for the relationship if not already added
+      const joinKey = `${relTable}`;
+      if (!joins.find(j => j.table === joinKey)) {
+        const fkColumn = `${sourceModelName}_id`;
+        joins.push({
+          table: relTable,
+          condition: `\`${relTable}\`.\`${fkColumn}\` = \`${sourceTable}\`.\`id\``
+        });
+      }
+    }
+  }
+
+  // Regular columns (from resolve map string paths or direct attr fields)
+  for (const [key, mysqlType] of Object.entries(viewSchema.columns || {})) {
+    selectColumns.push(`\`${sourceTable}\`.\`${key}\` AS \`${key}\``);
+  }
+
+  // Build JOIN clauses
+  const joinClauses = joins.map(j =>
+    `LEFT JOIN \`${j.table}\` ON ${j.condition}`
+  ).join('\n  ');
+
+  // Build GROUP BY
+  let groupBy = '';
+  if (groupByField) {
+    groupBy = `\nGROUP BY \`${sourceTable}\`.\`${groupByField}\``;
+  } else if (hasAggregates) {
+    groupBy = `\nGROUP BY \`${sourceTable}\`.\`id\``;
+  }
+
+  const viewName = sanitizeTableName(viewSchema.viewName);
+  const sql = `CREATE OR REPLACE VIEW \`${viewName}\` AS\nSELECT\n  ${selectColumns.join(',\n  ')}\nFROM \`${sourceTable}\`${joinClauses ? '\n  ' + joinClauses : ''}${groupBy}`;
+
+  return sql;
+}
+
+export function viewSchemasToSnapshot(viewSchemas) {
+  const snapshot = {};
+
+  for (const [name, schema] of Object.entries(viewSchemas)) {
+    snapshot[name] = {
+      viewName: schema.viewName,
+      source: schema.source,
+      ...(schema.groupBy ? { groupBy: schema.groupBy } : {}),
+      columns: { ...schema.columns },
+      foreignKeys: { ...schema.foreignKeys },
+      isView: true,
+      viewQuery: buildViewDDL(name, schema),
+    };
+  }
+
+  return snapshot;
+}
+
 export function schemasToSnapshot(schemas) {
   const snapshot = {};
 

package/src/orm-request.js

@@ -1,7 +1,7 @@
 import { Request } from '@stonyx/rest-server';
 import Orm, { createRecord, updateRecord, store } from '@stonyx/orm';
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
-import { pluralize } from './utils.js';
+import { getPluralName } from './plural-registry.js';
 import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import config from 'stonyx/config';
 
@@ -215,13 +215,13 @@ export default class OrmRequest extends Request {
 
     this.model = model;
     this.access = access;
-    const pluralizedModel = pluralize(model);
+    const pluralizedModel = getPluralName(model);
 
     const modelRelationships = getModelRelationships(model);
 
     // Define raw handlers first
-    const getCollectionHandler = (request, { filter: accessFilter }) => {
-      const allRecords = Array.from(store.get(model).values());
+    const getCollectionHandler = async (request, { filter: accessFilter }) => {
+      const allRecords = await store.findAll(model);
 
       const queryFilters = parseFilters(request.query);
       const queryFilterPredicate = createFilterPredicate(queryFilters);
@@ -241,8 +241,8 @@ export default class OrmRequest extends Request {
       });
     };
 
-    const getSingleHandler = (request) => {
-      const record = store.get(model, getId(request.params));
+    const getSingleHandler = async (request) => {
+      const record = await store.find(model, getId(request.params));
       if (!record) return 404;
 
       const fieldsMap = parseFields(request.query);
@@ -255,7 +255,7 @@ export default class OrmRequest extends Request {
       });
     };
 
-    const createHandler = ({ body, query }) => {
+    const createHandler = async ({ body, query }) => {
       const { type, id, attributes, relationships: rels } = body?.data || {};
 
       if (!type) return 400; // Bad request
@@ -264,7 +264,7 @@ export default class OrmRequest extends Request {
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
       // Check for duplicate ID
-      if (id !== undefined && store.get(model, id)) return 409; // Conflict
+      if (id !== undefined && await store.find(model, id)) return 409; // Conflict
 
       const { id: _ignoredId, ...sanitizedAttributes } = attributes || {};
 
@@ -285,7 +285,7 @@ export default class OrmRequest extends Request {
     };
 
     const updateHandler = async ({ body, params }) => {
-      const record = store.get(model, getId(params));
+      const record = await store.find(model, getId(params));
       const { attributes, relationships: rels } = body?.data || {};
 
       if (!attributes && !rels) return 400; // Bad request
@@ -323,21 +323,27 @@ export default class OrmRequest extends Request {
     };
 
     // Wrap handlers with hooks
+    const isView = Orm.instance?.isView?.(model);
+
     this.handlers = {
       get: {
         '/': this._withHooks('list', getCollectionHandler),
         '/:id': this._withHooks('get', getSingleHandler),
         ...this._generateRelationshipRoutes(model, pluralizedModel, modelRelationships)
       },
-      patch: {
+    };
+
+    // Views are read-only — no write endpoints
+    if (!isView) {
+      this.handlers.patch = {
         '/:id': this._withHooks('update', updateHandler)
-      },
-      post: {
+      };
+      this.handlers.post = {
         '/': this._withHooks('create', createHandler)
-      },
-      delete: {
+      };
+      this.handlers.delete = {
         '/:id': this._withHooks('delete', deleteHandler)
-      }
+      };
     }
   }
 
@@ -357,7 +363,7 @@ export default class OrmRequest extends Request {
 
       // Capture old state for operations that modify data
       if (operation === 'update' || operation === 'delete') {
-        const existingRecord = store.get(this.model, getId(request.params));
+        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));
@@ -388,9 +394,9 @@ export default class OrmRequest extends Request {
       context.response = response;
 
       if (operation === 'get' && response?.data && !Array.isArray(response.data)) {
-        context.record = store.get(this.model, getId(request.params));
+        context.record = await store.find(this.model, getId(request.params));
       } else if (operation === 'list' && response?.data) {
-        context.records = Array.from(store.get(this.model).values());
+        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);
@@ -424,8 +430,8 @@ export default class OrmRequest extends Request {
       const dasherizedName = camelCaseToKebabCase(relationshipName);
 
       // Related resource route: GET /:id/{relationship}
-      routes[`/:id/${dasherizedName}`] = (request) => {
-        const record = store.get(model, getId(request.params));
+      routes[`/:id/${dasherizedName}`] = async (request) => {
+        const record = await store.find(model, getId(request.params));
         if (!record) return 404;
 
         const relatedData = record.__relationships[relationshipName];
@@ -447,8 +453,8 @@ export default class OrmRequest extends Request {
       };
 
       // Relationship linkage route: GET /:id/relationships/{relationship}
-      routes[`/:id/relationships/${dasherizedName}`] = (request) => {
-        const record = store.get(model, getId(request.params));
+      routes[`/:id/relationships/${dasherizedName}`] = async (request) => {
+        const record = await store.find(model, getId(request.params));
         if (!record) return 404;
 
         const relatedData = record.__relationships[relationshipName];
@@ -474,8 +480,8 @@ export default class OrmRequest extends Request {
     }
 
     // Catch-all for invalid relationship names on related resource route
-    routes[`/:id/:relationship`] = (request) => {
-      const record = store.get(model, getId(request.params));
+    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)
@@ -483,8 +489,8 @@ export default class OrmRequest extends Request {
     };
 
     // Catch-all for invalid relationship names on relationship linkage route
-    routes[`/:id/relationships/:relationship`] = (request) => {
-      const record = store.get(model, getId(request.params));
+    routes[`/:id/relationships/:relationship`] = async (request) => {
+      const record = await store.find(model, getId(request.params));
       if (!record) return 404;
 
       return 404;

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,7 +1,7 @@
 import { store } from './index.js';
 import { getComputedProperties } from "./serializer.js";
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
-import { pluralize } from './utils.js';
+import { getPluralName } from './plural-registry.js';
 export default class Record {
   __data = {};
   __relationships = {};
@@ -57,7 +57,7 @@ export default class Record {
     const { fields, baseUrl } = options;
     const { __data:data } = this;
     const modelName = this.__model.__name;
-    const pluralizedModelName = pluralize(modelName);
+    const pluralizedModelName = getPluralName(modelName);
     const recordId = data.id;
     const relationships = {};
     const attributes = {};

package/src/serializer.js

@@ -71,8 +71,8 @@ export default class Serializer {
       const handler = model[key];
       const data = query(rawData, pathPrefix, subPath);
 
-      // Ignore null/undefined values on updates (TODO: What if we want it set to null?)
-      if ((data === null || data === undefined) && options.update) continue;
+      // Skip fields not present in the update payload (undefined = not provided)
+      if (data === undefined && options.update) continue;
 
       // Relationship handling
       if (typeof handler === 'function') {
@@ -86,6 +86,13 @@ export default class Serializer {
         continue;
       }
 
+      // Aggregate property handling — use the rawData value, not the aggregate descriptor
+      if (handler?.constructor?.name === 'AggregateProperty') {
+        parsedData[key] = data;
+        record[key] = data;
+        continue;
+      }
+
       // Direct assignment handling
       if (handler?.constructor?.name !== 'ModelProperty') {
         parsedData[key] = handler;

package/src/setup-rest-server.js

@@ -5,7 +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 { pluralize } from './utils.js';
+import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
 
 export default async function(route, accessPath, metaRoute) {
@@ -41,9 +41,9 @@ export default async function(route, accessPath, metaRoute) {
   // Remove "/" prefix and name mount point accordingly
   const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
 
-  // Configure endpoints for models with access configuration
+  // Configure endpoints for models and views with access configuration
   for (const [model, access] of Object.entries(accessFiles)) {
-    const pluralizedModel = pluralize(model);
+    const pluralizedModel = getPluralName(model);
     const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
     RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });
   }

package/src/store.js

@@ -1,5 +1,6 @@
-import { relationships } from '@stonyx/orm';
+import Orm, { relationships } from '@stonyx/orm';
 import { TYPES } from './relationships.js';
+import ViewResolver from './view-resolver.js';
 
 export default class Store {
   constructor() {
@@ -9,17 +10,145 @@ 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 views in non-MySQL mode, use view resolver
+    if (Orm.instance?.isView?.(modelName) && !this._mysqlDb) {
+      const resolver = new ViewResolver(modelName);
+      return resolver.resolveOne(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 views in non-MySQL mode, use view resolver
+    if (Orm.instance?.isView?.(modelName) && !this._mysqlDb) {
+      const resolver = new ViewResolver(modelName);
+      const records = await resolver.resolveAll();
+
+      if (!conditions || Object.keys(conditions).length === 0) return records;
+
+      return records.filter(record =>
+        Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+      );
+    }
+
+    // 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 false; // default to non-memory if resolver not set yet
+  }
+
   set(key, value) {
     this.data.set(key, value);
   }
 
   remove(key, id) {
+    // Guard: read-only views cannot have records removed
+    if (Orm.instance?.isView?.(key)) {
+      throw new Error(`Cannot remove records from read-only view '${key}'`);
+    }
+
     if (id) return this.unloadRecord(key, id);
 
     this.unloadAllRecords(key);