@stonyx/orm 0.2.1-beta.6 → 0.2.1-beta.61

package/src/belongs-to.js

@@ -11,7 +11,7 @@ export default function belongsTo(modelName) {
   const pendingHasManyQueue = relationships.get('pending');
   const pendingBelongsToQueue = relationships.get('pendingBelongsTo');
 
-  return (sourceRecord, rawData, options) => {
+  const fn = (sourceRecord, rawData, options) => {
     if (!rawData) return null;
 
     const { __name: sourceModelName } = sourceRecord.__model;
@@ -60,4 +60,7 @@ export default function belongsTo(modelName) {
 
     return output;
   }
+
+  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+  return fn;
 }

package/src/has-many.js

@@ -16,7 +16,7 @@ export default function hasMany(modelName) {
   const globalRelationships = relationships.get('global');
   const pendingRelationships = relationships.get('pending');
 
-  return (sourceRecord, rawData, options) => {
+  const fn = (sourceRecord, rawData, options) => {
     const { __name: sourceModelName } = sourceRecord.__model;
     const relationshipId = sourceRecord.id;
     const relationship = getRelationships('hasMany', sourceModelName, modelName, relationshipId);
@@ -58,4 +58,7 @@ export default function hasMany(modelName) {
 
     return output;
   }
+
+  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+  return fn;
 }

package/src/index.js

@@ -15,15 +15,24 @@
  */
 
 import Model from './model.js';
+import View from './view.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';
+import { count, avg, sum, min, max } from './aggregates.js';
 
 export { default } from './main.js';
 export { store, relationships } from './main.js';
-export { Model, Serializer }; // base classes
+export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
-export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
+export { count, avg, sum, min, max }; // aggregate helpers
+export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
+
+// Store API:
+// store.get(model, id)   — sync, memory-only
+// store.find(model, id)  — async, MySQL for memory:false models
+// store.findAll(model)   — async, all records
+// store.query(model, conditions) — async, always hits MySQL

package/src/main.js

@@ -19,6 +19,7 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
+import { registerPluralName } from './plural-registry.js';
 import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
@@ -36,6 +37,7 @@ export default class Orm {
   
   models = {};
   serializers = {};
+  views = {};
   transforms = { ...baseTransforms };
   warnings = new Set();
 
@@ -66,7 +68,10 @@ export default class Orm {
         // 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());
+        if (type === 'Model') {
+          Orm.store.set(name, new Map());
+          registerPluralName(name, exported);
+        }
 
         return this[pluralize(lowerCaseType)][alias] = exported;
       }, { ignoreAccessFailure: true, rawName: true, recursive: true, recursiveNaming: true });
@@ -75,14 +80,28 @@ export default class Orm {
     // Wait for imports before db & rest server setup
     await Promise.all(promises);
 
+    // Discover views from paths.view (separate from model/serializer/transform)
+    if (paths.view) {
+      await forEachFileImport(paths.view, (exported, { name }) => {
+        const alias = `${kebabCaseToPascalCase(name)}View`;
+        Orm.store.set(name, new Map());
+        registerPluralName(name, exported);
+        this.views[alias] = exported;
+      }, { ignoreAccessFailure: true, rawName: true, recursive: true, recursiveNaming: true });
+    }
+
     // Setup event names for hooks after models are loaded
     const eventNames = [];
     const operations = ['list', 'get', 'create', 'update', 'delete'];
+    const viewOperations = ['list', 'get'];
     const timings = ['before', 'after'];
 
     for (const modelName of Orm.store.data.keys()) {
+      const isView = this.isView(modelName);
+      const ops = isView ? viewOperations : operations;
+
       for (const timing of timings) {
-        for (const operation of operations) {
+        for (const operation of ops) {
           eventNames.push(`${timing}:${operation}:${modelName}`);
         }
       }
@@ -106,6 +125,17 @@ export default class Orm {
       promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
     }
 
+    // Wire up memory resolver so store.find() can check model memory flags
+    Orm.store._memoryResolver = (modelName) => {
+      const { modelClass } = this.getRecordClasses(modelName);
+      return modelClass?.memory === true;
+    };
+
+    // Wire up MySQL reference for on-demand queries from store.find()/findAll()
+    if (this.mysqlDb) {
+      Orm.store._mysqlDb = this.mysqlDb;
+    }
+
     Orm.ready = await Promise.all(promises);
     Orm.initialized = true;
   }
@@ -126,13 +156,27 @@ export default class Orm {
 
   getRecordClasses(modelName) {
     const modelClassPrefix = kebabCaseToPascalCase(modelName);
-  
+
+    // Check views first, then models
+    const viewClass = this.views[`${modelClassPrefix}View`];
+    if (viewClass) {
+      return {
+        modelClass: viewClass,
+        serializerClass: this.serializers[`${modelClassPrefix}Serializer`] || Serializer
+      };
+    }
+
     return {
       modelClass: this.models[`${modelClassPrefix}Model`],
       serializerClass: this.serializers[`${modelClassPrefix}Serializer`] || Serializer
     };
   }
 
+  isView(modelName) {
+    const modelClassPrefix = kebabCaseToPascalCase(modelName);
+    return !!this.views[`${modelClassPrefix}View`];
+  }
+
   // Queue warnings to avoid the same error from being logged in the same iteration
   warn(message) {
     this.warnings.add(message);

package/src/manage-record.js

@@ -14,6 +14,11 @@ export function createRecord(modelName, rawData={}, userOptions={}) {
 
   if (!initialized && !options.isDbRecord) throw new Error('ORM is not ready');
 
+  // Guard: read-only views cannot have records created directly
+  if (orm?.isView?.(modelName) && !options.isDbRecord) {
+    throw new Error(`Cannot create records for read-only view '${modelName}'`);
+  }
+
   const modelStore = store.get(modelName);
   const globalRelationships = relationships.get('global');
   const pendingRelationships = relationships.get('pending');
@@ -83,6 +88,12 @@ export function createRecord(modelName, rawData={}, userOptions={}) {
 export function updateRecord(record, rawData, userOptions={}) {
   if (!rawData) throw new Error('rawData must be passed in to updateRecord call');
 
+  // Guard: read-only views cannot be updated
+  const modelName = record?.__model?.__name;
+  if (modelName && Orm.instance?.isView?.(modelName)) {
+    throw new Error(`Cannot update records for read-only view '${modelName}'`);
+  }
+
   const options = { ...defaultOptions, ...userOptions, update:true };
 
   record.serialize(rawData, options);

package/src/model-property.js

@@ -22,8 +22,8 @@ export default class ModelProperty {
       return this._value = newValue;
     }
 
-    if (newValue === undefined || newValue === null) return;
+    if (newValue === undefined) return;
 
-    this._value = Orm.instance.transforms[this.type](newValue);
+    this._value = newValue === null ? null : Orm.instance.transforms[this.type](newValue);
   }
 }

package/src/model.js

@@ -1,6 +1,17 @@
 import { attr } from '@stonyx/orm';
 
 export default class Model {
+  /**
+   * Controls whether records of this model are loaded into memory on startup.
+   *
+   * - true  → loaded on boot, kept in store
+   * - false → never cached; find() always queries MySQL (default)
+   *
+   * Override in subclass: static memory = true;
+   */
+  static memory = false;
+  static pluralName = undefined;
+
   id = attr('number');
 
   constructor(name) {

package/src/mysql/migration-generator.js

@@ -1,4 +1,4 @@
-import { introspectModels, buildTableDDL, schemasToSnapshot, getTopologicalOrder } from './schema-introspector.js';
+import { introspectModels, introspectViews, buildTableDDL, buildViewDDL, schemasToSnapshot, viewSchemasToSnapshot, getTopologicalOrder } from './schema-introspector.js';
 import { readFile, createFile, createDirectory, fileExists } from '@stonyx/utils/file';
 import path from 'path';
 import config from 'stonyx/config';
@@ -16,9 +16,18 @@ export async function generateMigration(description = 'migration') {
   const previousSnapshot = await loadLatestSnapshot(migrationsPath);
   const diff = diffSnapshots(previousSnapshot, currentSnapshot);
 
+  // Don't return early — check view changes too before deciding
   if (!diff.hasChanges) {
-    log.db('No schema changes detected.');
-    return null;
+    // Check if there are view changes before returning null
+    const viewSchemasPrelim = introspectViews();
+    const currentViewSnapshotPrelim = viewSchemasToSnapshot(viewSchemasPrelim);
+    const previousViewSnapshotPrelim = extractViewsFromSnapshot(previousSnapshot);
+    const viewDiffPrelim = diffViewSnapshots(previousViewSnapshotPrelim, currentViewSnapshotPrelim);
+
+    if (!viewDiffPrelim.hasChanges) {
+      log.db('No schema changes detected.');
+      return null;
+    }
   }
 
   const upStatements = [];
@@ -85,17 +94,71 @@ export async function generateMigration(description = 'migration') {
     downStatements.push(`ALTER TABLE \`${table}\` ADD FOREIGN KEY (\`${column}\`) REFERENCES \`${references.references}\`(\`${references.column}\`) ON DELETE SET NULL;`);
   }
 
+  // View migrations — views are created AFTER tables (dependency order)
+  const viewSchemas = introspectViews();
+  const currentViewSnapshot = viewSchemasToSnapshot(viewSchemas);
+  const previousViewSnapshot = extractViewsFromSnapshot(previousSnapshot);
+  const viewDiff = diffViewSnapshots(previousViewSnapshot, currentViewSnapshot);
+
+  if (viewDiff.hasChanges) {
+    upStatements.push('');
+    upStatements.push('-- Views');
+    downStatements.push('');
+    downStatements.push('-- Views');
+
+    // Added views
+    for (const name of viewDiff.addedViews) {
+      try {
+        const ddl = buildViewDDL(name, viewSchemas[name], schemas);
+        upStatements.push(ddl + ';');
+        downStatements.unshift(`DROP VIEW IF EXISTS \`${viewSchemas[name].viewName}\`;`);
+      } catch (error) {
+        upStatements.push(`-- WARNING: Could not generate DDL for view '${name}': ${error.message}`);
+      }
+    }
+
+    // Removed views
+    for (const name of viewDiff.removedViews) {
+      upStatements.push(`-- WARNING: View '${name}' was removed. Uncomment to drop view:`);
+      upStatements.push(`-- DROP VIEW IF EXISTS \`${previousViewSnapshot[name].viewName}\`;`);
+      downStatements.push(`-- Recreate view for removed view '${name}' manually if needed`);
+    }
+
+    // Changed views (source or aggregates changed)
+    for (const name of viewDiff.changedViews) {
+      try {
+        const ddl = buildViewDDL(name, viewSchemas[name], schemas);
+        upStatements.push(ddl + ';');
+      } catch (error) {
+        upStatements.push(`-- WARNING: Could not generate DDL for changed view '${name}': ${error.message}`);
+      }
+    }
+  }
+
+  const combinedHasChanges = diff.hasChanges || viewDiff.hasChanges;
+
+  if (!combinedHasChanges) {
+    log.db('No schema changes detected.');
+    return null;
+  }
+
+  // Merge view snapshot into the main snapshot
+  const combinedSnapshot = { ...currentSnapshot };
+  for (const [name, viewSnap] of Object.entries(currentViewSnapshot)) {
+    combinedSnapshot[name] = viewSnap;
+  }
+
   const sanitizedDescription = description.replace(/\s+/g, '_').replace(/[^a-zA-Z0-9_]/g, '');
   const timestamp = Math.floor(Date.now() / 1000);
   const filename = `${timestamp}_${sanitizedDescription}.sql`;
   const content = `-- UP\n${upStatements.join('\n')}\n\n-- DOWN\n${downStatements.join('\n')}\n`;
 
   await createFile(path.join(migrationsPath, filename), content);
-  await createFile(path.join(migrationsPath, '.snapshot.json'), JSON.stringify(currentSnapshot, null, 2));
+  await createFile(path.join(migrationsPath, '.snapshot.json'), JSON.stringify(combinedSnapshot, null, 2));
 
   log.db(`Migration generated: ${filename}`);
 
-  return { filename, content, snapshot: currentSnapshot };
+  return { filename, content, snapshot: combinedSnapshot };
 }
 
 export async function loadLatestSnapshot(migrationsPath) {
@@ -186,3 +249,38 @@ export function detectSchemaDrift(schemas, snapshot) {
   const current = schemasToSnapshot(schemas);
   return diffSnapshots(snapshot, current);
 }
+
+export function extractViewsFromSnapshot(snapshot) {
+  const views = {};
+  for (const [name, entry] of Object.entries(snapshot)) {
+    if (entry.isView) views[name] = entry;
+  }
+  return views;
+}
+
+export function diffViewSnapshots(previous, current) {
+  const addedViews = [];
+  const removedViews = [];
+  const changedViews = [];
+
+  for (const name of Object.keys(current)) {
+    if (!previous[name]) {
+      addedViews.push(name);
+    } else if (
+      current[name].viewQuery !== previous[name].viewQuery ||
+      current[name].source !== previous[name].source
+    ) {
+      changedViews.push(name);
+    }
+  }
+
+  for (const name of Object.keys(previous)) {
+    if (!current[name]) {
+      removedViews.push(name);
+    }
+  }
+
+  const hasChanges = addedViews.length > 0 || removedViews.length > 0 || changedViews.length > 0;
+
+  return { hasChanges, addedViews, removedViews, changedViews };
+}

package/src/mysql/mysql-db.js

@@ -1,12 +1,12 @@
 import { getPool, closePool } from './connection.js';
 import { ensureMigrationsTable, getAppliedMigrations, getMigrationFiles, applyMigration, parseMigrationFile } from './migration-runner.js';
-import { introspectModels, getTopologicalOrder, schemasToSnapshot } from './schema-introspector.js';
+import { introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot } from './schema-introspector.js';
 import { loadLatestSnapshot, detectSchemaDrift } from './migration-generator.js';
 import { buildInsert, buildUpdate, buildDelete, buildSelect } from './query-builder.js';
 import { createRecord, store } from '@stonyx/orm';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
-import { pluralize } from '../utils.js';
+import { getPluralName } from '../plural-registry.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import path from 'path';
@@ -14,10 +14,10 @@ import path from 'path';
 const defaultDeps = {
   getPool, closePool, ensureMigrationsTable, getAppliedMigrations,
   getMigrationFiles, applyMigration, parseMigrationFile,
-  introspectModels, getTopologicalOrder, schemasToSnapshot,
+  introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
   loadLatestSnapshot, detectSchemaDrift,
   buildInsert, buildUpdate, buildDelete, buildSelect,
-  createRecord, store, confirm, readFile, pluralize, config, log, path
+  createRecord, store, confirm, readFile, getPluralName, config, log, path
 };
 
 export default class MysqlDB {
@@ -33,7 +33,7 @@ export default class MysqlDB {
   async init() {
     this.pool = await this.deps.getPool(this.mysqlConfig);
     await this.deps.ensureMigrationsTable(this.pool, this.mysqlConfig.migrationsTable);
-    await this.loadAllRecords();
+    await this.loadMemoryRecords();
   }
 
   async startup() {
@@ -59,7 +59,7 @@ export default class MysqlDB {
         }
 
         // Reload records after applying migrations
-        await this.loadAllRecords();
+        await this.loadMemoryRecords();
       } else {
         this.deps.log.warn('Skipping pending migrations. Schema may be outdated.');
       }
@@ -80,7 +80,7 @@ export default class MysqlDB {
             const { up } = this.deps.parseMigrationFile(result.content);
             await this.deps.applyMigration(this.pool, result.filename, up, this.mysqlConfig.migrationsTable);
             this.deps.log.db(`Applied migration: ${result.filename}`);
-            await this.loadAllRecords();
+            await this.loadMemoryRecords();
           }
         } else {
           this.deps.log.warn('Skipping initial migration. Tables may not exist.');
@@ -111,11 +111,23 @@ export default class MysqlDB {
     // No-op: MySQL persists data immediately via persist()
   }
 
-  async loadAllRecords() {
+  /**
+   * Loads only models with memory: true into the in-memory store on startup.
+   * Models with memory: false are skipped — accessed on-demand via find()/findAll().
+   */
+  async loadMemoryRecords() {
     const schemas = this.deps.introspectModels();
     const order = this.deps.getTopologicalOrder(schemas);
+    const Orm = (await import('@stonyx/orm')).default;
 
     for (const modelName of order) {
+      // Check the model's memory flag — skip non-memory models
+      const { modelClass } = Orm.instance.getRecordClasses(modelName);
+      if (modelClass?.memory === false) {
+        this.deps.log.db(`Skipping memory load for '${modelName}' (memory: false)`);
+        continue;
+      }
+
       const schema = schemas[modelName];
       const { sql, values } = this.deps.buildSelect(schema.table);
 
@@ -137,6 +149,143 @@ export default class MysqlDB {
       }
     }
 
+    // Load views with memory: true
+    const viewSchemas = this.deps.introspectViews();
+
+    for (const [viewName, viewSchema] of Object.entries(viewSchemas)) {
+      const { modelClass: viewClass } = Orm.instance.getRecordClasses(viewName);
+      if (viewClass?.memory !== true) {
+        this.deps.log.db(`Skipping memory load for view '${viewName}' (memory: false)`);
+        continue;
+      }
+
+      const schema = { table: viewSchema.viewName, columns: viewSchema.columns || {}, foreignKeys: viewSchema.foreignKeys || {} };
+      const { sql, values } = this.deps.buildSelect(schema.table);
+
+      try {
+        const [rows] = await this.pool.execute(sql, values);
+
+        for (const row of rows) {
+          const rawData = this._rowToRawData(row, schema);
+          this.deps.createRecord(viewName, rawData, { isDbRecord: true, serialize: false, transform: false });
+        }
+      } catch (error) {
+        if (error.code === 'ER_NO_SUCH_TABLE') {
+          this.deps.log.db(`View '${viewSchema.viewName}' does not exist yet. Skipping load for '${viewName}'.`);
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * @deprecated Use loadMemoryRecords() instead. Kept for backward compatibility.
+   */
+  async loadAllRecords() {
+    return this.loadMemoryRecords();
+  }
+
+  /**
+   * Find a single record by ID from MySQL.
+   * Does NOT cache the result in the store for memory: false models.
+   * @param {string} modelName
+   * @param {string|number} id
+   * @returns {Promise<Record|undefined>}
+   */
+  async findRecord(modelName, id) {
+    const schemas = this.deps.introspectModels();
+    let schema = schemas[modelName];
+
+    // Check views if not found in models
+    if (!schema) {
+      const viewSchemas = this.deps.introspectViews();
+      const viewSchema = viewSchemas[modelName];
+      if (viewSchema) {
+        schema = { table: viewSchema.viewName, columns: viewSchema.columns || {}, foreignKeys: viewSchema.foreignKeys || {} };
+      }
+    }
+
+    if (!schema) return undefined;
+
+    const { sql, values } = this.deps.buildSelect(schema.table, { id });
+
+    try {
+      const [rows] = await this.pool.execute(sql, values);
+
+      if (rows.length === 0) return undefined;
+
+      const rawData = this._rowToRawData(rows[0], schema);
+      const record = this.deps.createRecord(modelName, rawData, { isDbRecord: true, serialize: false, transform: false });
+
+      // Don't let memory:false records accumulate in the store
+      // The caller keeps the reference; the store doesn't retain it
+      this._evictIfNotMemory(modelName, record);
+
+      return record;
+    } catch (error) {
+      if (error.code === 'ER_NO_SUCH_TABLE') return undefined;
+      throw error;
+    }
+  }
+
+  /**
+   * Find all records of a model from MySQL, with optional conditions.
+   * @param {string} modelName
+   * @param {Object} [conditions] - Optional WHERE conditions (key-value pairs)
+   * @returns {Promise<Record[]>}
+   */
+  async findAll(modelName, conditions) {
+    const schemas = this.deps.introspectModels();
+    let schema = schemas[modelName];
+
+    // Check views if not found in models
+    if (!schema) {
+      const viewSchemas = this.deps.introspectViews();
+      const viewSchema = viewSchemas[modelName];
+      if (viewSchema) {
+        schema = { table: viewSchema.viewName, columns: viewSchema.columns || {}, foreignKeys: viewSchema.foreignKeys || {} };
+      }
+    }
+
+    if (!schema) return [];
+
+    const { sql, values } = this.deps.buildSelect(schema.table, conditions);
+
+    try {
+      const [rows] = await this.pool.execute(sql, values);
+
+      const records = rows.map(row => {
+        const rawData = this._rowToRawData(row, schema);
+        return this.deps.createRecord(modelName, rawData, { isDbRecord: true, serialize: false, transform: false });
+      });
+
+      // Don't let memory:false records accumulate in the store
+      for (const record of records) {
+        this._evictIfNotMemory(modelName, record);
+      }
+
+      return records;
+    } catch (error) {
+      if (error.code === 'ER_NO_SUCH_TABLE') return [];
+      throw error;
+    }
+  }
+
+  /**
+   * Remove a record from the in-memory store if its model has memory: false.
+   * The record object itself survives — the caller retains the reference.
+   * This prevents on-demand queries from leaking records into the store.
+   * @private
+   */
+  _evictIfNotMemory(modelName, record) {
+    const store = this.deps.store;
+
+    // Use the memory resolver if available (set by Orm.init)
+    if (store._memoryResolver && !store._memoryResolver(modelName)) {
+      const modelStore = store.get?.(modelName) ?? store.data?.get(modelName);
+      if (modelStore) modelStore.delete(record.id);
+    }
   }
 
   _rowToRawData(row, schema) {
@@ -175,6 +324,10 @@ export default class MysqlDB {
   }
 
   async persist(operation, modelName, context, response) {
+    // Views are read-only — no-op for all write operations
+    const Orm = (await import('@stonyx/orm')).default;
+    if (Orm.instance?.isView?.(modelName)) return;
+
     switch (operation) {
       case 'create':
         return this._persistCreate(modelName, context, response);