@stonyx/orm 0.2.1-beta.15 → 0.2.1-beta.17

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.15",
+  "version": "0.2.1-beta.17",
   "description": "",
   "main": "src/main.js",
   "type": "module",
@@ -46,7 +46,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.9",
+    "@stonyx/rest-server": "0.2.1-beta.10",
     "@stonyx/utils": "0.2.3-beta.4",
     "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

@@ -106,6 +106,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.js

@@ -1,6 +1,16 @@
 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;
+
   id = attr('number');
 
   constructor(name) {

package/src/mysql/mysql-db.js

@@ -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

@@ -64,6 +64,7 @@ export function introspectModels() {
       columns,
       foreignKeys,
       relationships,
+      memory: modelClass.memory !== false, // default true for backward compat
     };
   }
 

package/src/orm-request.js

@@ -220,8 +220,8 @@ export default class OrmRequest extends Request {
     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/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);
   }