@stonyx/orm 0.2.1-alpha.31 → 0.2.1-alpha.33

package/README.md

@@ -17,6 +17,23 @@ A lightweight ORM for Stonyx projects, featuring model definitions, serializers,
 - **REST Server Integration**: Automatic route setup with customizable access control.
 - **Lifecycle Hooks**: Middleware-based before/after hooks for validation, authorization, side effects, and auditing.
 
+## Public API vs Internals
+
+Records use a proxy that exposes model attributes as direct properties. Always use direct property access for reading and writing field values:
+
+```js
+// Correct: read/write via the proxy
+const age = record.age;
+record.age = 5;
+
+// Correct: iterate fields using the record directly
+for (const key of Object.keys(record.serialize())) {
+  console.log(key, record[key]);
+}
+```
+
+All properties prefixed with `__` (`__data`, `__relationships`, `__model`, `__serializer`, `__serialized`) are **internal implementation details** and must not be accessed by consumer code. Bypassing the proxy by reading or writing `__data` directly skips type transforms and change tracking, which can lead to silent data corruption.
+
 ## Installation
 
 ```bash
@@ -417,7 +434,7 @@ Each hook receives a context object with comprehensive information:
 - It contains a deep copy of the record's state **before** the operation executes (captured before the `before` hook fires)
 - The deep copy is created via JSON serialization (`JSON.parse(JSON.stringify())`) to ensure complete isolation
 - For `delete` operations, `recordId` is provided in after hooks since the record may no longer exist in the store
-- `oldState` is captured from `record.__data` or the record itself, providing access to the raw data structure
+- `oldState` is captured as a deep copy of the record's data before the operation, providing access to the previous field values
 
 ### Usage Examples
 
@@ -520,8 +537,8 @@ afterHook('update', 'animal', async (context) => {
 
   // Track multiple field changes
   const changedFields = [];
-  for (const key in context.record.__data) {
-    if (context.oldState[key] !== context.record.__data[key]) {
+  for (const key of Object.keys(context.oldState)) {
+    if (context.oldState[key] !== context.record[key]) {
       changedFields.push(key);
     }
   }
@@ -560,9 +577,9 @@ afterHook('update', 'animal', async (context) => {
   // Compare oldState with current record to capture exact changes
   const changes = {};
   if (context.oldState) {
-    for (const [key, newValue] of Object.entries(context.record.__data || context.record)) {
-      if (context.oldState[key] !== newValue) {
-        changes[key] = { from: context.oldState[key], to: newValue };
+    for (const key of Object.keys(context.oldState)) {
+      if (context.oldState[key] !== context.record[key]) {
+        changes[key] = { from: context.oldState[key], to: context.record[key] };
       }
     }
   }

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.31",
+  "version": "0.2.1-alpha.33",
   "description": "",
   "main": "src/main.js",
   "type": "module",

package/src/belongs-to.js

@@ -21,9 +21,13 @@ export default function belongsTo(modelName) {
     const modelStore = store.get(modelName);
 
     // Try to get existing record
-    const output = typeof rawData === 'object'
-      ? createRecord(modelName, rawData, options)
-      : modelStore.get(rawData);
+    let output;
+
+    if (typeof rawData === 'object') {
+      output = createRecord(modelName, rawData, options);
+    } else if (modelStore) {
+      output = modelStore.get(rawData);
+    }
 
     // If not found and is a string ID, register as pending
     if (!output && typeof rawData !== 'object') {

package/src/has-many.js

@@ -27,6 +27,10 @@ export default function hasMany(modelName) {
       let record;
 
       if (typeof elementData !== 'object') {
+        if (!modelStore) {
+          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+        }
+
         record = modelStore.get(elementData);
 
         if (!record) {

package/src/main.js

@@ -111,9 +111,9 @@ export default class Orm {
 
     if (config.orm.mysql) {
       const { default: MysqlDB } = await import('./mysql/mysql-db.js');
-      this.mysqlDb = new MysqlDB();
-      this.db = this.mysqlDb;
-      promises.push(this.mysqlDb.init());
+      this.sqlDb = new MysqlDB();
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
     } else if (this.options.dbType !== 'none') {
       const db = new DB();
       this.db = db;
@@ -131,9 +131,9 @@ export default class Orm {
       return modelClass?.memory === true;
     };
 
-    // Wire up MySQL reference for on-demand queries from store.find()/findAll()
-    if (this.mysqlDb) {
-      Orm.store._mysqlDb = this.mysqlDb;
+    // Wire up SQL adapter reference for on-demand queries from store.find()/findAll()
+    if (this.sqlDb) {
+      Orm.store._sqlDb = this.sqlDb;
     }
 
     Orm.ready = await Promise.all(promises);
@@ -141,11 +141,11 @@ export default class Orm {
   }
 
   async startup() {
-    if (this.mysqlDb) await this.mysqlDb.startup();
+    if (this.sqlDb) await this.sqlDb.startup();
   }
 
   async shutdown() {
-    if (this.mysqlDb) await this.mysqlDb.shutdown();
+    if (this.sqlDb) await this.sqlDb.shutdown();
   }
 
   static get db() {

package/src/manage-record.js

@@ -23,6 +23,8 @@ export function createRecord(modelName, rawData={}, userOptions={}) {
   const globalRelationships = relationships.get('global');
   const pendingRelationships = relationships.get('pending');
 
+  if (!modelStore) throw new Error(`Model store for '${modelName}' is not registered. Ensure the model is defined before creating records.`);
+
   assignRecordId(modelName, rawData);
   if (modelStore.has(rawData.id)) return modelStore.get(rawData.id);
 
@@ -108,10 +110,10 @@ export function updateRecord(record, rawData, userOptions={}) {
 function assignRecordId(modelName, rawData) {
   if (rawData.id) return;
 
-  // In MySQL mode with numeric IDs, defer to MySQL auto-increment
-  if (Orm.instance?.mysqlDb && !isStringIdModel(modelName)) {
+  // In SQL mode with numeric IDs, defer to database auto-increment
+  if (Orm.instance?.sqlDb && !isStringIdModel(modelName)) {
     rawData.id = `__pending_${Date.now()}_${Math.random()}`;
-    rawData.__pendingMysqlId = true;
+    rawData.__pendingSqlId = true;
     return;
   }
 

package/src/mysql/mysql-db.js

@@ -352,7 +352,7 @@ export default class MysqlDB {
     const insertData = this._recordToRow(record, schema);
 
     // For auto-increment models, remove the pending ID
-    const isPendingId = record.__data.__pendingMysqlId;
+    const isPendingId = record.__data.__pendingSqlId;
 
     if (isPendingId) {
       delete insertData.id;
@@ -380,7 +380,7 @@ export default class MysqlDB {
         response.data.id = realId;
       }
 
-      delete record.__data.__pendingMysqlId;
+      delete record.__data.__pendingSqlId;
     }
   }
 

package/src/orm-request.js

@@ -385,9 +385,9 @@ export default class OrmRequest extends Request {
       // Execute main handler
       const response = await handler(request, state);
 
-      // Persist to MySQL for write operations
-      if (Orm.instance.mysqlDb && WRITE_OPERATIONS.has(operation)) {
-        await Orm.instance.mysqlDb.persist(operation, this.model, context, response);
+      // Persist to SQL database for write operations
+      if (Orm.instance.sqlDb && WRITE_OPERATIONS.has(operation)) {
+        await Orm.instance.sqlDb.persist(operation, this.model, context, response);
       }
 
       // Add response and relevant records to context

package/src/record.js

@@ -3,12 +3,17 @@ import { getComputedProperties } from "./serializer.js";
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from './plural-registry.js';
 export default class Record {
+  /** @private */
   __data = {};
+  /** @private */
   __relationships = {};
+  /** @private */
   __serialized = false;
 
   constructor(model, serializer) {
+    /** @private */
     this.__model = model;
+    /** @private */
     this.__serializer = serializer;
 
   }

package/src/store.js

@@ -22,15 +22,15 @@ export default class Store {
   }
 
   /**
-   * Async authoritative read. Always queries MySQL for memory: false models.
+   * Async authoritative read. Always queries the SQL database 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) {
+    // For views in non-SQL mode, use view resolver
+    if (Orm.instance?.isView?.(modelName) && !this._sqlDb) {
       const resolver = new ViewResolver(modelName);
       return resolver.resolveOne(id);
     }
@@ -40,12 +40,12 @@ export default class Store {
       return this.get(modelName, id);
     }
 
-    // For memory: false models, always query MySQL
-    if (this._mysqlDb) {
-      return this._mysqlDb.findRecord(modelName, id);
+    // For memory: false models, always query the SQL database
+    if (this._sqlDb) {
+      return this._sqlDb.findRecord(modelName, id);
     }
 
-    // Fallback to store (JSON mode or no MySQL)
+    // Fallback to store (JSON mode or no SQL adapter)
     return this.get(modelName, id);
   }
 
@@ -57,8 +57,8 @@ export default class Store {
    * @returns {Promise<Record[]>}
    */
   async findAll(modelName, conditions) {
-    // For views in non-MySQL mode, use view resolver
-    if (Orm.instance?.isView?.(modelName) && !this._mysqlDb) {
+    // For views in non-SQL mode, use view resolver
+    if (Orm.instance?.isView?.(modelName) && !this._sqlDb) {
       const resolver = new ViewResolver(modelName);
       const records = await resolver.resolveAll();
 
@@ -75,9 +75,9 @@ export default class Store {
       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);
+    // For memory: false models (or filtered queries), always query the SQL database
+    if (this._sqlDb) {
+      return this._sqlDb.findAll(modelName, conditions);
     }
 
     // Fallback to store (JSON mode) — apply conditions in-memory if provided
@@ -101,8 +101,8 @@ export default class Store {
    * @returns {Promise<Record[]>}
    */
   async query(modelName, conditions = {}) {
-    if (this._mysqlDb) {
-      return this._mysqlDb.findAll(modelName, conditions);
+    if (this._sqlDb) {
+      return this._sqlDb.findAll(modelName, conditions);
     }
 
     // Fallback: filter in-memory store
@@ -125,10 +125,10 @@ export default class Store {
   _memoryResolver = null;
 
   /**
-   * Set by Orm during init — reference to the MysqlDB instance for on-demand queries.
-   * @type {MysqlDB|null}
+   * Set by Orm during init — reference to the SQL adapter instance for on-demand queries.
+   * @type {object|null}
    */
-  _mysqlDb = null;
+  _sqlDb = null;
 
   /**
    * Check if a model is configured for in-memory storage.