mythix-orm 1.14.0 → 1.15.0

package/.nvmrc

@@ -0,0 +1 @@
+24.13.0

package/lib/connection/connection-base.js

@@ -824,7 +824,7 @@ class ConnectionBase extends EventEmitter {
     let modelNames  = Object.keys(models);
     let newContext  = new Map();
 
-    newContext.set('connection', connection);
+    newContext.set(Utils.CONNECTION_KEY, connection);
 
     for (let i = 0, il = modelNames.length; i < il; i++) {
       let modelName         = modelNames[i];
@@ -865,6 +865,53 @@ class ConnectionBase extends EventEmitter {
     });
   }
 
+  /// Capture the current AsyncLocalStorage context and return a function
+  /// that will execute callbacks within that captured context.
+  ///
+  /// This is useful for preserving database context across event emitters,
+  /// setTimeout, or other callbacks where context might otherwise be lost.
+  ///
+  /// Return: Function
+  ///   A function that takes a callback and executes it in the captured context.
+  ///
+  /// Example:
+  ///   const runInDbContext = connection.captureContext();
+  ///
+  ///   eventEmitter.on('data', () => {
+  ///     runInDbContext(async () => {
+  ///       // Models work here - context is preserved
+  ///       const user = await User.where.id.EQ('123').first();
+  ///     });
+  ///   });
+  ///
+  /// See: <see>Utils.AsyncStore.captureContext</see>
+  captureContext() {
+    return Utils.captureContext();
+  }
+
+  /// Wrap a callback function to preserve the current AsyncLocalStorage context.
+  ///
+  /// This is a convenience wrapper for use with event handlers and other callbacks
+  /// where you want to ensure database context is preserved.
+  ///
+  /// Arguments:
+  ///   callback: Function
+  ///     The callback function to wrap.
+  ///
+  /// Return: Function
+  ///   A wrapped version of the callback that will execute in the captured context.
+  ///
+  /// Example:
+  ///   eventEmitter.on('data', connection.bindCallback(async (data) => {
+  ///     // Context preserved - models work here
+  ///     const user = await User.where.id.EQ(data.userId).first();
+  ///   }));
+  ///
+  /// See: <see>Utils.AsyncStore.bindCallback</see>
+  bindCallback(callback) {
+    return Utils.bindCallback(callback);
+  }
+
   /// Find a specific field across all registered models.
   ///
   /// This method is similar to [Array.find](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find),

package/lib/model.js

@@ -422,7 +422,7 @@ class Model {
     if (connection)
       return connection;
 
-    connection = AsyncStore.getContextValue('connection');
+    connection = AsyncStore.getContextValue(AsyncStore.CONNECTION_KEY);
     if (connection)
       return connection;
 
@@ -465,8 +465,36 @@ class Model {
 
   static getConnection(_connection) {
     let connection = this._getConnection(_connection);
-    if (!connection)
-      throw new Error(`${this.getModelName()}::getConnection: No connection bound to model. You need to provide a connection for this operation.`);
+    if (!connection) {
+      let modelName       = this.getModelName();
+      let modelContext    = this.getModelContext();
+      let globalContext   = AsyncStore.getContextValue(AsyncStore.CONNECTION_KEY);
+      let boundConnection = this._mythixBoundConnection;
+      let debugInfo       = AsyncStore.getContextDebugInfo();
+
+      let errorMessage = [
+        `${modelName}.getConnection(): No connection available.`,
+        '',
+        'Resolution order checked:',
+        `  1. Explicit argument:              ${_connection ? 'provided' : 'not provided'}`,
+        `  2. Model context (${modelName}):     ${modelContext?.connection ? 'found' : 'not set'}`,
+        `  3. Global context (CONNECTION_KEY): ${globalContext ? 'found' : 'not set'}`,
+        `  4. Bound connection:               ${boundConnection ? 'found' : 'not set'}`,
+        '',
+        'Context debug info:',
+        `  - Inside AsyncLocalStorage context: ${debugInfo.hasContext ? 'yes' : 'no'}`,
+        `  - Context keys: [${debugInfo.contextKeys.map((k) => (typeof k === 'symbol' ? k.toString() : `"${k}"`)).join(', ')}]`,
+        `  - Parent depth: ${debugInfo.parentDepth}`,
+        '',
+        'Possible solutions:',
+        '  - Wrap your code in connection.createContext(callback)',
+        '  - Pass a connection explicitly: Model.where(connection).field.EQ(value)',
+        '  - Ensure bindModels is enabled when creating the connection',
+        '  - For event handlers, use connection.bindCallback(callback)',
+      ].join('\n');
+
+      throw new Error(errorMessage);
+    }
 
     return connection;
   }

package/lib/types/concrete/char-type.js

@@ -57,7 +57,7 @@ class CharType extends Type {
     if (value == null)
       return value;
 
-    if (!Nife.instanceOf('string') || value.length !== 1)
+    if (!Nife.instanceOf(value, 'string') || value.length !== 1)
       throw new TypeError(`CharType::castToType: Value provided ("${value}") can not be cast into a char. Please provide a string that is one character wide.`);
 
     return value.charAt(0);

package/lib/types/concrete/numeric-type.js

@@ -105,7 +105,7 @@ class NumericType extends Type {
 
     let number = parseFloat(('' + value));
     if (!isFinite(number))
-      throw new TypeError(`FloatType::castToType: Value provided ("${value}") can not be cast into an floating point number.`);
+      throw new TypeError(`NumericType::castToType: Value provided ("${value}") can not be cast into a floating point number.`);
 
     return number;
   }

package/lib/utils/async-store.js

@@ -13,7 +13,7 @@
 ///! support... which simply means that connection instances need
 ///! to be manually passed around everywhere.
 ///!
-///! **!WARNING!: Never set the `'connection'` key, or a string key
+///! **!WARNING!: Never set the <see>CONNECTION_KEY</see> Symbol, or a string key
 ///! that matches one of your model names to this `AsyncLocalStorage` context
 ///! unless you know exactly what you are doing. These keys are reserved
 ///! by Mythix ORM to pass connections and transactions through calls.** Any
@@ -26,12 +26,23 @@
 
 'use strict';
 
+/// The Symbol key used to store the connection in AsyncLocalStorage context.
+/// This is exported so users can access the context directly if needed.
+///
+/// Example:
+///   const { CONNECTION_KEY } = require('mythix-orm').Utils.AsyncStore;
+///   const connection = AsyncStore.getContextValue(CONNECTION_KEY);
+const CONNECTION_KEY = Symbol.for('mythix-orm:connection');
+
 let globalAsyncStore = global._mythixGlobalAsyncLocalStore;
+let AsyncLocalStorageClass = null;
+let debugEnabled = process.env.MYTHIX_ORM_DEBUG === '1' || process.env.MYTHIX_ORM_DEBUG === 'true';
 
 if (!globalAsyncStore) {
   try {
-    const { AsyncLocalStorage } = require('async_hooks');
-    global._mythixGlobalAsyncLocalStore = globalAsyncStore = new AsyncLocalStorage();
+    const asyncHooks = require('async_hooks');
+    AsyncLocalStorageClass = asyncHooks.AsyncLocalStorage;
+    global._mythixGlobalAsyncLocalStore = globalAsyncStore = new AsyncLocalStorageClass();
   } catch (error) {
     global._mythixGlobalAsyncLocalStore = globalAsyncStore = {
       getStore: () => undefined,
@@ -40,6 +51,33 @@ if (!globalAsyncStore) {
   }
 }
 
+/// Enable or disable debug mode for AsyncStore operations.
+/// When enabled, context operations will be logged to console.
+///
+/// Debug mode can also be enabled via the `MYTHIX_ORM_DEBUG=1` environment variable.
+///
+/// Arguments:
+///   enabled: boolean
+///     Whether to enable debug logging.
+///
+/// Return: undefined
+function setDebug(enabled) {
+  debugEnabled = !!enabled;
+}
+
+/// Check if debug mode is currently enabled.
+///
+/// Return: boolean
+///   True if debug mode is enabled.
+function isDebugEnabled() {
+  return debugEnabled;
+}
+
+function debugLog(...args) {
+  if (debugEnabled)
+    console.log('[mythix-orm:AsyncStore]', ...args);
+}
+
 /// Fetch the AsyncLocalStorage store.
 /// This calls `.getStore()` on the global
 /// `AsyncLocalStorage` instance.
@@ -51,6 +89,22 @@ function getContextStore() {
   return globalAsyncStore.getStore();
 }
 
+/// Check if code is currently running inside an AsyncLocalStorage context.
+///
+/// Return: boolean
+///   True if a context exists, false otherwise.
+function hasContext() {
+  return globalAsyncStore.getStore() !== undefined;
+}
+
+/// Check if a connection is available in the current AsyncLocalStorage context.
+///
+/// Return: boolean
+///   True if a connection is available in context, false otherwise.
+function hasConnection() {
+  return !!getContextValue(CONNECTION_KEY);
+}
+
 /// Get a specific value from the global `AsyncLocalStorage` context
 /// by name.
 ///
@@ -119,6 +173,8 @@ function setContextValue(key, value) {
 /// Return: any
 ///   The return value from the callback.
 function runInContext(context, callback) {
+  debugLog('Entering context with keys:', context ? [...context.keys()] : []);
+
   return globalAsyncStore.run(
     {
       parent:  globalAsyncStore.getStore(),
@@ -128,9 +184,115 @@ function runInContext(context, callback) {
   );
 }
 
+/// Capture the current AsyncLocalStorage context and return a function
+/// that will execute callbacks within that captured context.
+///
+/// This is useful for preserving context across event emitters, setTimeout,
+/// or other callbacks where context might otherwise be lost.
+///
+/// Note:
+///   This uses AsyncLocalStorage.snapshot() when available (Node.js 20+),
+///   with a fallback implementation for older versions.
+///
+/// Return: Function
+///   A function that takes a callback and executes it in the captured context.
+///   If no context exists when captured, callbacks will run without context.
+///
+/// Example:
+///   const runInCapturedContext = captureContext();
+///
+///   eventEmitter.on('someEvent', () => {
+///     runInCapturedContext(() => {
+///       // Models work here - context is preserved
+///       const user = await User.where.id.EQ('123').first();
+///     });
+///   });
+function captureContext() {
+  // Use native snapshot() if available (Node.js 20+)
+  if (AsyncLocalStorageClass && typeof AsyncLocalStorageClass.snapshot === 'function') {
+    debugLog('Capturing context via snapshot()');
+    return AsyncLocalStorageClass.snapshot();
+  }
+
+  // Fallback: manually capture current store
+  const capturedStore = globalAsyncStore.getStore();
+  debugLog('Capturing context manually, has context:', !!capturedStore);
+
+  return function runInCapturedContext(callback) {
+    if (!capturedStore)
+      return callback();
+
+    return globalAsyncStore.run(capturedStore, callback);
+  };
+}
+
+/// Wrap a callback function to preserve the current AsyncLocalStorage context.
+///
+/// This is a convenience wrapper around <see>captureContext</see> for use with
+/// event handlers and other callbacks.
+///
+/// Arguments:
+///   callback: Function
+///     The callback function to wrap.
+///
+/// Return: Function
+///   A wrapped version of the callback that will execute in the captured context.
+///
+/// Example:
+///   eventEmitter.on('data', bindCallback(async (data) => {
+///     // Context preserved - models work here
+///     await processData(data);
+///   }));
+function bindCallback(callback) {
+  const runInCapturedContext = captureContext();
+
+  return function boundCallback(...args) {
+    return runInCapturedContext(() => callback.apply(this, args));
+  };
+}
+
+/// Get debugging information about the current context state.
+/// Useful for troubleshooting context-related issues.
+///
+/// Return: object
+///   An object containing:
+///   - hasContext: boolean - whether a context exists
+///   - hasConnection: boolean - whether a connection is in context
+///   - contextKeys: Array - keys present in the current context
+///   - parentDepth: number - how many parent contexts exist
+function getContextDebugInfo() {
+  let store = globalAsyncStore.getStore();
+  let parentDepth = 0;
+  let contextKeys = [];
+
+  if (store && store.context)
+    contextKeys = [...store.context.keys()];
+
+  let tempStore = store;
+  while (tempStore && tempStore.parent) {
+    parentDepth++;
+    tempStore = tempStore.parent;
+  }
+
+  return {
+    hasContext:    !!store,
+    hasConnection: hasConnection(),
+    contextKeys,
+    parentDepth,
+  };
+}
+
 module.exports = {
+  CONNECTION_KEY,
   getContextValue,
   setContextValue,
   runInContext,
   getContextStore,
+  hasContext,
+  hasConnection,
+  captureContext,
+  bindCallback,
+  setDebug,
+  isDebugEnabled,
+  getContextDebugInfo,
 };

package/lib/utils/index.js

@@ -34,10 +34,18 @@ const {
 } = QueryUtils;
 
 const {
+  CONNECTION_KEY,
   getContextStore,
   getContextValue,
   setContextValue,
   runInContext,
+  hasContext,
+  hasConnection,
+  captureContext,
+  bindCallback,
+  setDebug,
+  isDebugEnabled,
+  getContextDebugInfo,
 } = AsyncStore;
 
 module.exports = {
@@ -72,8 +80,16 @@ module.exports = {
   mergeFields,
 
   // AsyncStore
+  CONNECTION_KEY,
   getContextStore,
   getContextValue,
   setContextValue,
   runInContext,
+  hasContext,
+  hasConnection,
+  captureContext,
+  bindCallback,
+  setDebug,
+  isDebugEnabled,
+  getContextDebugInfo,
 };

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "mythix-orm",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "ORM for Mythix framework",
   "main": "lib/index",
   "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "scripts": {
     "coverage": "clear ; node ./node_modules/.bin/nyc ./node_modules/.bin/jasmine",
     "test": "node ./node_modules/.bin/jasmine",
@@ -34,20 +37,20 @@
   "homepage": "https://github.com/th317erd/mythix-orm#readme",
   "devDependencies": {
     "@spothero/eslint-plugin-spothero": "github:spothero/eslint-plugin-spothero",
-    "@types/node": "^18.11.18",
-    "better-sqlite3": "^8.0.1",
+    "@types/node": "^22.15.0",
+    "better-sqlite3": "^12.6.2",
     "colors": "^1.4.0",
-    "diff": "^5.1.0",
-    "eslint": "^8.31.0",
-    "jasmine": "^4.5.0",
-    "nyc": "^15.1.0"
+    "diff": "^7.0.0",
+    "eslint": "^8.57.1",
+    "jasmine": "^5.6.0",
+    "nyc": "^17.1.0"
   },
   "dependencies": {
     "events": "^3.3.0",
-    "inflection": "^2.0.1",
-    "luxon": "^3.2.1",
+    "inflection": "^3.0.0",
+    "luxon": "^3.7.2",
     "nife": "^1.12.1",
-    "uuid": "^9.0.0",
+    "uuid": "^11.1.0",
     "xid-js": "^1.0.1"
   },
   "nyc": {