@stonyx/orm 0.2.1-beta.3 → 0.2.1-beta.31

package/.claude/index.md

@@ -65,6 +65,7 @@ stonyx-orm/
 │   ├── migrate.js                # JSON DB mode migration (file <-> directory)
 │   ├── commands.js               # CLI commands (db:migrate-*, etc.)
 │   ├── utils.js                  # Pluralize wrapper for dasherized names
+│   ├── plural-registry.js        # Plural name registry (populated at init, supports Model.pluralName overrides)
 │   ├── exports/
 │   │   └── db.js                 # Convenience re-export of DB instance
 │   └── mysql/
@@ -150,6 +151,7 @@ The ORM supports two storage modes, configured via `db.mode`:
 - Models: `{PascalCase}Model` (e.g., `AnimalModel`)
 - Serializers: `{PascalCase}Serializer` (e.g., `AnimalSerializer`)
 - Transforms: Original filename (e.g., `animal.js`)
+- Plural names: Auto-pluralized by default (e.g., `animal` → `animals`). Override with `static pluralName` on the model class (e.g., `static pluralName = 'people'`). All call sites use `getPluralName()` from the plural registry, **not** `pluralize()` directly.
 
 ---
 

package/.claude/usage-patterns.md

@@ -31,6 +31,23 @@ export default class AnimalModel extends Model {
 - Use `hasMany(modelName)` for one-to-many
 - Getters work as computed properties
 - Relationships auto-establish bidirectionally
+- Override auto-pluralization with `static pluralName` (see [Overriding Plural Names](#overriding-plural-names))
+
+### Overriding Plural Names
+
+By default, model names are auto-pluralized (e.g., `animal` → `animals`) for REST routes, JSON:API URLs, and DB table names. When auto-pluralization produces the wrong result, override it with `static pluralName`:
+
+```javascript
+import { Model, attr } from '@stonyx/orm';
+
+export default class PersonModel extends Model {
+  static pluralName = 'people';
+
+  name = attr('string');
+}
+```
+
+The override is picked up automatically during ORM initialization — no additional registration is needed. All internal call sites (REST routes, JSON:API type references, MySQL table names, foreign key references) use the overridden value.
 
 ## 2. Serializers (Data Transformation)
 

package/README.md

@@ -109,6 +109,22 @@ export default class OwnerModel extends Model {
 }
 ```
 
+### Overriding Plural Names
+
+By default, model names are auto-pluralized for REST routes, JSON:API URLs, and DB table names (e.g., `animal` → `animals`). When auto-pluralization produces the wrong result, override it with `static pluralName`:
+
+```js
+import { Model, attr } from '@stonyx/orm';
+
+export default class PersonModel extends Model {
+  static pluralName = 'people';
+
+  name = attr('string');
+}
+```
+
+The override is picked up automatically during ORM initialization. All routes, JSON:API type references, and MySQL table names will use the overridden value.
+
 ## Serializers
 
 Based on the following sample payload structure which represents a poorly structure third-party data source:

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.3",
+  "version": "0.2.1-beta.31",
   "description": "",
   "main": "src/main.js",
   "type": "module",
@@ -33,21 +33,25 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "stonyx": "0.2.3-beta.2",
-    "@stonyx/events": "0.1.1-beta.2",
-    "@stonyx/cron": "0.2.1-beta.3"
+    "stonyx": "0.2.3-beta.6",
+    "@stonyx/events": "0.1.1-beta.7",
+    "@stonyx/cron": "0.2.1-beta.12"
   },
   "peerDependencies": {
-    "mysql2": "^3.0.0"
+    "mysql2": "^3.0.0",
+    "@stonyx/rest-server": ">=0.2.1-beta.14"
   },
   "peerDependenciesMeta": {
     "mysql2": {
       "optional": true
+    },
+    "@stonyx/rest-server": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.4",
-    "@stonyx/utils": "0.2.3-beta.3",
+    "@stonyx/rest-server": "0.2.1-beta.16",
+    "@stonyx/utils": "0.2.3-beta.5",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/src/index.js

@@ -26,4 +26,10 @@ export { default } from './main.js';
 export { store, relationships } from './main.js';
 export { Model, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
-export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
+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';
@@ -66,7 +67,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 });
@@ -106,6 +110,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 !== false;
+    };
+
+    // 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;
   }

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 (default for backward compatibility)
+   * - false → never cached; find() always queries MySQL
+   *
+   * Override in subclass: static memory = false;
+   */
+  static memory = true;
+  static pluralName = undefined;
+
   id = attr('number');
 
   constructor(name) {

package/src/mysql/mysql-db.js

@@ -6,7 +6,7 @@ import { buildInsert, buildUpdate, buildDelete, buildSelect } from './query-buil
 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';
@@ -17,7 +17,7 @@ const defaultDeps = {
   introspectModels, 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);
 
@@ -136,7 +148,97 @@ export default class MysqlDB {
         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();
+    const schema = schemas[modelName];
+
+    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();
+    const schema = schemas[modelName];
+
+    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) {

package/src/mysql/schema-introspector.js

@@ -1,7 +1,7 @@
 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';
 
 function getRelationshipInfo(property) {
@@ -51,19 +51,21 @@ export function introspectModels() {
 
     // Build foreign keys from belongsTo relationships
     for (const relName of Object.keys(relationships.belongsTo)) {
+      const modelName = camelCaseToKebabCase(relName);
       const fkColumn = `${relName}_id`;
       foreignKeys[fkColumn] = {
-        references: pluralize(relName),
+        references: getPluralName(modelName),
         column: 'id',
       };
     }
 
     schemas[name] = {
-      table: pluralize(name),
+      table: getPluralName(name),
       idType,
       columns,
       foreignKeys,
       relationships,
+      memory: modelClass.memory !== false, // default true for backward compat
     };
   }
 
@@ -129,7 +131,7 @@ export function getTopologicalOrder(schemas) {
 
     // Visit dependencies (belongsTo targets) first
     for (const relName of Object.keys(schema.relationships.belongsTo)) {
-      visit(relName);
+      visit(camelCaseToKebabCase(relName));
     }
 
     order.push(name);

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
@@ -357,7 +357,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 +388,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 +424,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 +447,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 +474,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 +483,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') {

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) {
@@ -43,7 +43,7 @@ export default async function(route, accessPath, metaRoute) {
 
   // Configure endpoints for models 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

@@ -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);
   }