mythix-orm 1.7.2 → 1.8.1

package/lib/connection/connection-base.d.ts

@@ -81,8 +81,12 @@ declare class ConnectionBase extends EventEmitter {
   public getOptions(): ConnectionBaseOptions;
   public isStarted(): boolean;
   public toQueryEngine(queryEngineLike: any): QueryEngine | undefined;
-  public registerModel<T = ModelClass>(Model: T): T;
-  public registerModels(models: Models | Array<ModelClass>): Models | undefined;
+  public registerModel<T = ModelClass>(Model: T, options?: GenericObject): T;
+  public registerModels(models: Models | Array<ModelClass>, options?: GenericObject): Models | undefined;
+  public getContextValue(key: any, defaultValue?: any): any;
+  public setContextValue(key: any, value: any): any;
+  public buildConnectionContext(connection?: ConnectionBase): Map<any, any>;
+  public createContext(callback: Function, connection?: ConnectionBase, thisArg?: any): Promise<any>;
   public findModelField(finder: IterateFieldsCallback): Array<Field>;
   public parseQualifiedName(fullyQualifiedName: string): FullyQualifiedFieldDefinition;
   public getModels(): Models;

package/lib/connection/connection-base.js

@@ -227,7 +227,7 @@ class ConnectionBase extends EventEmitter {
       return;
 
     if (!QueryEngine.isQuery(queryEngine)) {
-      if (Object.prototype.hasOwnProperty.call(queryEngine, 'where'))
+      if ('where' in queryEngine)
         queryEngine = queryEngine.where(this);
       else
         queryEngine = undefined;
@@ -236,15 +236,15 @@ class ConnectionBase extends EventEmitter {
     return queryEngine;
   }
 
-  registerModel(_Model) {
-    let Model = _Model.bindConnection(this);
+  registerModel(_Model, options) {
+    let Model = _Model.bindConnection(this, options);
 
     this._models[Model.getModelName()] = Model;
 
     return Model;
   }
 
-  registerModels(models) {
+  registerModels(models, options) {
     if (!models)
       return;
 
@@ -254,12 +254,90 @@ class ConnectionBase extends EventEmitter {
       let key   = keys[i];
       let Model = models[key];
 
-      this.registerModel(Model);
+      this.registerModel(Model, options);
     }
 
     return this._models;
   }
 
+  /// Get a value from the `AsyncLocalStorage` context.
+  ///
+  /// [AsyncLocalStorage](https://nodejs.org/docs/latest-v16.x/api/async_context.html)
+  /// is used primarily for two purposes: 1) to provide a connection to models, and 2) to
+  /// pass a transaction connection down through the call stack. However, it can
+  /// also be used for any "context" level values the user wishes to store.
+  ///
+  /// Note:
+  ///   An `AsyncLocalStorage` context might not exist when this call is made,
+  ///   in which case this method will return `undefined`, or the `defaultValue`
+  ///   if any was provided.
+  ///
+  /// Return: any
+  ///
+  /// Arguments:
+  ///   key: any
+  ///     The key for the value you wish to fetch.
+  ///     The underlying "context" provided by `AsyncLocalStorage`
+  ///     is a `Map`, so the "key" can be any value.
+  ///   defaultValue?: any
+  ///     The default value to return if there is no current `AsyncLocalStorage`
+  ///     context, or if the requested key is not found.
+  getContextValue(key, defaultValue) {
+    return Utils.getContextValue(key, defaultValue);
+  }
+
+  /// Set a value onto the `AsyncLocalStorage` context.
+  ///
+  /// [AsyncLocalStorage](https://nodejs.org/docs/latest-v16.x/api/async_context.html)
+  /// is used primarily for two purposes: 1) to provide a connection to models, and 2) to
+  /// pass a transaction connection down through the call stack. However, it can
+  /// also be used for any "context" level values the user wishes to store.
+  ///
+  /// Note:
+  ///   An `AsyncLocalStorage` context might not exist when this call is made,
+  ///   in which case this method will do nothing, and silently return.
+  ///
+  /// Return: any
+  ///
+  /// Arguments:
+  ///   key: any
+  ///     The key for the value you wish to set.
+  ///     The underlying "context" provided by `AsyncLocalStorage`
+  ///     is a `Map`, so the "key" can be any value.
+  ///   value: any
+  ///     The value to set to the specified key.
+  setContextValue(key, value) {
+    return Utils.setContextValue(key, value);
+  }
+
+  buildConnectionContext(_connection) {
+    let connection  = _connection || this;
+    let models      = connection._models;
+    let modelNames  = Object.keys(models);
+    let newContext  = new Map();
+
+    newContext.set('connection', connection);
+
+    for (let i = 0, il = modelNames.length; i < il; i++) {
+      let modelName         = modelNames[i];
+      let Model             = models[modelName];
+      let currentModelScope = Model.getModelContext();
+
+      newContext.set(modelName, { ...currentModelScope, connection });
+    }
+
+    return newContext;
+  }
+
+  async createContext(callback, _connection, thisArg) {
+    let connection  = _connection || this;
+    let context     = this.buildConnectionContext(connection);
+
+    return await Utils.runInContext(context, async () => {
+      return await callback.call(thisArg, connection);
+    });
+  }
+
   findModelField(finder) {
     let modelMap    = this.getModels();
     let modelNames  = Object.keys(modelMap);
@@ -1248,7 +1326,7 @@ class ConnectionBase extends EventEmitter {
 
   // eslint-disable-next-line no-unused-vars
   async query(sql, options) {
-    throw new Error(`${this.constructor.name}::transaction: This operation is not supported for this connection type.`);
+    throw new Error(`${this.constructor.name}::query: This operation is not supported for this connection type.`);
   }
 
   // eslint-disable-next-line no-unused-vars

package/lib/field.js

@@ -67,6 +67,7 @@
 /// Interface:
 ///   interface DefaultValueContext {
 ///     _initial: boolean;        // If `true`, then this is the initial set of the field's value.
+///     _static: boolean;         // If `true`, then this will be used in a "static" context, such as the `DEFAULT` of the DB.
 ///     connection: Connection;   // The connection from the model.
 ///     data: object | undefined; // All attributes provided to the model upon instantiation.
 ///     field: Field;             // The field descriptor where this `defaultValue` is defined.
@@ -113,8 +114,15 @@
 ///    This has no effect client-side in JavaScript. Even if `allowNull`
 ///    is `false`, the field property on your model may still have a
 ///    `null` value in JavaScript.
-///  index: boolean = false
+///  index: Array<boolean | string> | boolean = false
 ///    If `true`, then this field will be indexed in the database.
+///    If an array is provided, then it must be an array containing
+///    other field names to combine with this field to create a combined
+///    index. For example: `index: [ true, 'firstName', 'lastName', [ 'firstName', 'lastName' ] ]`
+///    would create four indexes: `true` means index this field, `firstName` would create
+///    the combination index `this_field_first_name`, `lastName` would create the
+///    combination index `this_field_last_name`, and `[ 'firstName', 'lastName ]` would
+///    create the combination index `this_field_first_name_last_name`.
 ///  unique: boolean = false
 ///    If `true`, then add a unique constraint to this field in
 ///    the underlying database.

package/lib/model.d.ts

@@ -15,7 +15,7 @@ export declare interface ModelOptions extends GenericObject {
 export declare type ModelClass = typeof Model;
 
 export declare interface Models {
-  [ key: string ]: ModelClass;
+  [key: string]: ModelClass;
 }
 
 export declare interface HookContext {
@@ -25,11 +25,11 @@ export declare interface HookContext {
 }
 
 export declare interface DirtyChanges {
-  [ key: string ]: { previous: any; current: any };
+  [key: string]: { previous: any; current: any };
 }
 
-export declare type LooseFields = Array<Field | FieldDefinition> | { [ key: string ]: Field | FieldDefinition } | Map<string, Field | FieldDefinition> | Set<Field | FieldDefinition>;
-export declare type Fields = Array<Field> | { [ key: string ]: Field } | Map<string, Field> | Set<Field>;
+export declare type LooseFields = Array<Field | FieldDefinition> | { [key: string]: Field | FieldDefinition } | Map<string, Field | FieldDefinition> | Set<Field | FieldDefinition>;
+export declare type Fields = Array<Field> | { [key: string]: Field } | Map<string, Field> | Set<Field>;
 
 export declare interface IterateFieldsContext {
   field: Field;
@@ -54,6 +54,18 @@ export declare class Model {
   public static isModel(value: any): boolean;
   public static toString(showFields: boolean): string;
 
+  static getContextValue(key: any, defaultValue?: any): any;
+  getContextValue(key: any, defaultValue?: any): any;
+
+  static setContextValue(key: any, value: any): void;
+  setContextValue(key: any, value: any): void;
+
+  public static getModelContext(): GenericObject;
+  getModelContext(): GenericObject;
+
+  static updateModelContext(value: GenericObject): void;
+  updateModelContext(value: GenericObject): void;
+
   public static _getConnection(connection?: ConnectionBase): ConnectionBase;
   public _getConnection(connection?: ConnectionBase): ConnectionBase;
 

package/lib/model.js

@@ -5,6 +5,7 @@ const Inflection      = require('inflection');
 const Type            = require('./types/type');
 const DefaultHelpers  = require('./types/helpers/default-helpers');
 const Field           = require('./field');
+const AsyncStore      = require('./utils/async-store');
 const ModelUtils      = require('./utils/model-utils');
 
 /// Used as a unique key for cache.
@@ -45,24 +46,21 @@ function bindStaticWhereToModelClass(ModelClass) {
     set:          function() {},
     get:          function() {
       const self = this;
+      let connection = self._getConnection();
+      if (connection)
+        return self.getQueryEngine(connection);
 
       function unboundWhere(_connection, _propName) {
         let connection = _connection;
-
-        if (arguments.length === 0) {
-          connection = self._getConnection();
-          if (!connection)
-            throw new Error(`${self.getModelName()}::where: Model has no bound connection. You need to provide a connection by calling "${self.getModelName()}.where(connection)" instead.`);
-
-          return self.getQueryEngine(connection);
-        }
-
         if (!connection) {
           connection = self._getConnection();
           if (!connection)
             throw new Error(`${self.getModelName()}::where: Model has no bound connection. You need to provide a connection by calling "${self.getModelName()}.where(connection)" instead.`);
         }
 
+        if (arguments.length === 0)
+          return self.getQueryEngine(connection);
+
         let propName = _propName;
 
         if (connection.constructor && !connection.constructor._isMythixConnection) {
@@ -94,7 +92,12 @@ function bindStaticWhereToModelClass(ModelClass) {
           // This will throw an exception
           // if no connection is available
           let queryEngine = self.getQueryEngine(connection);
-          return queryEngine[propName];
+          let prop        = queryEngine[propName];
+
+          if (typeof prop === 'function' && typeof prop.bind === 'function')
+            prop = prop.bind(queryEngine);
+
+          return prop;
         },
       });
     },
@@ -223,6 +226,146 @@ class Model {
     return this.toString((depth !== 0));
   }
 
+  /// Get a value from the `AsyncLocalStorage` context.
+  ///
+  /// [AsyncLocalStorage](https://nodejs.org/docs/latest-v16.x/api/async_context.html)
+  /// is used primarily for two purposes: 1) to provide a connection to models, and 2) to
+  /// pass a transaction connection down through the call stack. However, it can
+  /// also be used for any "context" level values the user wishes to store.
+  ///
+  /// Note:
+  ///   An `AsyncLocalStorage` context might not exist when this call is made,
+  ///   in which case this method will return `undefined`, or the `defaultValue`
+  ///   if any was provided.
+  ///
+  /// Return: any
+  ///
+  /// Arguments:
+  ///   key: any
+  ///     The key for the value you wish to fetch.
+  ///     The underlying "context" provided by `AsyncLocalStorage`
+  ///     is a `Map`, so the "key" can be any value.
+  ///   defaultValue?: any
+  ///     The default value to return if there is no current `AsyncLocalStorage`
+  ///     context, or if the requested key is not found.
+  static getContextValue(key, defaultValue) {
+    return AsyncStore.getContextValue(key, defaultValue);
+  }
+
+  getContextValue(key, defaultValue) {
+    return this.constructor.getContextValue(key, defaultValue);
+  }
+
+  /// Set a value onto the `AsyncLocalStorage` context.
+  ///
+  /// [AsyncLocalStorage](https://nodejs.org/docs/latest-v16.x/api/async_context.html)
+  /// is used primarily for two purposes: 1) to provide a connection to models, and 2) to
+  /// pass a transaction connection down through the call stack. However, it can
+  /// also be used for any "context" level values the user wishes to store.
+  ///
+  /// Note:
+  ///   An `AsyncLocalStorage` context might not exist when this call is made,
+  ///   in which case this method will do nothing, and silently return.
+  ///
+  /// Return: any
+  ///
+  /// Arguments:
+  ///   key: any
+  ///     The key for the value you wish to set.
+  ///     The underlying "context" provided by `AsyncLocalStorage`
+  ///     is a `Map`, so the "key" can be any value.
+  ///   value: any
+  ///     The value to set to the specified key.
+  static setContextValue(key, value) {
+    return AsyncStore.setContextValue(key, value);
+  }
+
+  setContextValue(key, value) {
+    return this.constructor.setContextValue(key, value);
+  }
+
+  /// Get this Model class's "model context" from the `AsyncLocalStorage` context.
+  ///
+  /// [AsyncLocalStorage](https://nodejs.org/docs/latest-v16.x/api/async_context.html)
+  /// is used primarily for two purposes: 1) to provide a connection to models, and 2) to
+  /// pass a transaction connection down through the call stack. However, it can
+  /// also be used for any "context" level values the user wishes to store.
+  ///
+  /// When a <see>Connection.createContext</see> or <see>Connection.transaction</see>
+  /// call is made, a "model context" (that is just an Object instance) is created for each
+  /// model the connection is aware of, and the `connection` instance is added to this
+  /// context, allowing models to lookup the "context connection" when a call to
+  /// <see>Model._getConnection</see> is made. By default, these "model contexts"
+  /// that are stored inside the `AsyncLocalStorage` context only contain a "connection"
+  /// property. However, these model contexts were designed as Object instances so that
+  /// the user may also use them, or so they can be used for future features. Each model
+  /// also has its own "model context" so that if the application is using more than
+  /// one connection, then a different connection can be specified for each model and
+  /// stored in the same `AsyncLocalStorage` context.
+  ///
+  /// Note:
+  ///   An `AsyncLocalStorage` context might not exist when this call is made,
+  ///   in which case this method will simply return an empty object.
+  ///
+  /// Return: object
+  ///   The model class's "model context" stored in `AsyncLocalStorage`.
+  ///   This will be an empty object if no `AsyncLocalStorage` context is
+  ///   available.
+  static getModelContext() {
+    return AsyncStore.getContextValue(this.getModelName(), {});
+  }
+
+  getModelContext() {
+    return this.constructor.getModelContext();
+  }
+
+  /// Update this Model class's "model context" from the `AsyncLocalStorage` context.
+  ///
+  /// [AsyncLocalStorage](https://nodejs.org/docs/latest-v16.x/api/async_context.html)
+  /// is used primarily for two purposes: 1) to provide a connection to models, and 2) to
+  /// pass a transaction connection down through the call stack. However, it can
+  /// also be used for any "context" level values the user wishes to store.
+  ///
+  /// When a <see>Connection.createContext</see> or <see>Connection.transaction</see>
+  /// call is made, a "model context" (that is just an Object instance) is created for each
+  /// model the connection is aware of, and the `connection` instance is added to this
+  /// context, allowing models to lookup the "context connection" when a call to
+  /// <see>Model._getConnection</see> is made. By default, these "model contexts"
+  /// that are stored inside the `AsyncLocalStorage` context only contain a "connection"
+  /// property. However, these model contexts were designed as Object instances so that
+  /// the user may also use them, or so they can be used for future features. Each model
+  /// also has its own "model context" so that if the application is using more than
+  /// one connection, then a different connection can be specified for each model and
+  /// stored in the same `AsyncLocalStorage` context.
+  ///
+  /// This method allows you to update this "model context" for the model. The `value`
+  /// argument **must** be an Object instance. You can specify any properties you want.
+  /// Just be cautious if you set a `connection` property, as you might overwrite any
+  /// connection currently set on the context. Any properties you set here will be available
+  /// in any child function calls (inside this context scope), and can be accessed via a
+  /// call to <see>Model.getModelContext</see>.
+  ///
+  /// Note:
+  ///   An `AsyncLocalStorage` context might not exist when this call is made,
+  ///   in which case this method will simply return an empty object.
+  ///
+  /// Return: undefined
+  ///
+  /// Arguments:
+  ///   value: object
+  ///     The new properties you wish to merge with the current "model context".
+  static updateModelContext(value) {
+    let context = AsyncStore.getContextValue(this.getModelName());
+    if (!context)
+      return;
+
+    Object.assign(context, value);
+  }
+
+  updateModelContext(value) {
+    return this.constructor.updateModelContext(value);
+  }
+
   /// Get the underlying connection bound to
   /// the model's class. Connection binding is
   /// optional, so this method can also be provided
@@ -233,6 +376,32 @@ class Model {
   /// or fallback to a "bound" connection (if one can
   /// be found).
   ///
+  /// This method will return a connection in the following
+  /// order: 1) The provided `connection` argument, if supplied,
+  /// 2) The `connection` property on the "model context" from
+  /// <see>Model.getModelContext</see> from `AsyncLocalStorage`,
+  /// if one is available, and 3) Finally the bound connection, if
+  /// available, which is found by searching the `static Model._mythixBoundConnection`
+  /// property of the class.
+  ///
+  /// Note:
+  ///   This is a low-level "global fallback" method. Any connection for a model
+  ///   will first be searched by calling <see>Model.getConnection</see>,
+  ///   which will call this static method if no connection can be found.
+  ///   The <see>Model.getConnection</see> will also search the model instance
+  ///   for a `connection` property, which can be supplied to any model when
+  ///   it is instantiated.
+  ///
+  /// Note:
+  //    A provided `connection`, either via the model instance `model.connection`,
+  ///   or via the provided `connection` argument to the <see>Model.getConnection</see>
+  ///   method (and eventually this method) will take priority over any `connection`
+  ///   provided by the "model context" from `AsyncLocalStorage`. This can be an important
+  ///   detail when using <see>Connection.transaction</see> or <see>Connection.createContext</see>,
+  ///   because if a connection is directly specified by the user, the transaction connection
+  ///   **will not** take priority. So if you are using transactions or a connection context,
+  ///   be careful how you directly specify connections.
+  ///
   /// Return: <see>Connection</see>
   ///
   /// Arguments:
@@ -243,7 +412,18 @@ class Model {
   ///     then attempt to fallback to the bound connection,
   ///     if any is available.
   static _getConnection(_connection) {
-    return _connection || this._mythixBoundConnection;
+    if (_connection)
+      return _connection;
+
+    let { connection } = this.getModelContext();
+    if (connection)
+      return connection;
+
+    connection = AsyncStore.getContextValue('connection');
+    if (connection)
+      return connection;
+
+    return this._mythixBoundConnection;
   }
 
   /// See <see>Model.static _getConnection</see>
@@ -278,6 +458,14 @@ class Model {
     return this.constructor._getConnection();
   }
 
+  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.`);
+
+    return connection;
+  }
+
   /// Get the underlying connection bound to
   /// the model's class. Connection binding is
   /// optional, so this method can also be provided
@@ -290,6 +478,15 @@ class Model {
   /// you wish to provide your own model specific
   /// connection.
   ///
+  /// This method will also search for a `modelInstance.connection`,
+  /// and return that connection if found.
+  ///
+  /// Note:
+  ///   `static getConnection` is simply a proxy for
+  ///   `static _getConnection`, whereas this instance
+  ///   method will also attempt to find a connection
+  ///   on the model instance itself.
+  ///
   /// Return: <see>Connection</see>
   ///
   /// Arguments:
@@ -299,14 +496,6 @@ class Model {
   ///     Otherwise, if not provided, or a falsy value,
   ///     then attempt to fallback to the bound connection,
   ///     if any is available.
-  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.`);
-
-    return connection;
-  }
-
   getConnection(_connection) {
     if (_connection)
       return _connection;
@@ -334,26 +523,28 @@ class Model {
   ///   connection?: <see>Connection</see>
   ///     The connection instance to bind to
   ///     this model class.
-  static bindConnection(connection) {
+  static bindConnection(connection, options) {
     let ModelClass = this;
 
     // Ensure that the model fields
     // are constructed properly
     ModelClass.getFields();
 
-    let connectionOptions = connection.getOptions();
+    let connectionOptions = { ...(connection.getOptions() || {}), ...(options || {}) };
     if (connectionOptions && connectionOptions.bindModels === false) {
-      let modelName = ModelClass.getModelName();
+      // let modelName = ModelClass.getModelName();
 
-      ModelClass = class BoundModel extends ModelClass {
-        static getModelName() {
-          return modelName;
-        }
-      };
+      // ModelClass = class BoundModel extends ModelClass {
+      //   static getModelName() {
+      //     return modelName;
+      //   }
+      // };
 
-      ModelClass.fields = ModelClass.mergeFields();
-      ModelClass._sortedFields = null; // Clear cache
-    } else {
+      // ModelClass.fields = ModelClass.mergeFields();
+      // ModelClass._sortedFields = null; // Clear cache
+
+      return ModelClass;
+    } else if (connectionOptions.forceConnectionBinding !== true) {
       if (Object.prototype.hasOwnProperty.call(ModelClass, '_mythixBoundConnection') && ModelClass._mythixBoundConnection)
         throw new Error(`${this.getModelName()}:bindConnection: Model is already bound to a connection. You can not bind a model to a connection more than once.`);
     }
@@ -362,7 +553,7 @@ class Model {
       enumerable:   false,
       configurable: true,
       get:          () => {
-        return ModelClass.getQueryEngine(connection);
+        return ModelClass.getQueryEngine(ModelClass._getConnection() || connection);
       },
       set:          () => {},
     };
@@ -1424,6 +1615,7 @@ class Model {
   ///   Prefix a field name with `+` to specify ASCending order, i.e.
   ///   `[ "+User:id" ]`. Prefix the field name with `-` to specify
   ///   DESCending order, i.e. `[ "-User:id" ]`.
+  // eslint-disable-next-line no-unused-vars
   static defaultOrder(options) {
   }
 

package/lib/proxy-class/proxy-class.js

@@ -27,6 +27,9 @@ const AUTO_CALL_CALLED            = Symbol.for('@__autoCallCalled');
 const AUTO_CALL                   = Symbol.for('@__autoCall');
 
 function shouldSkipProxy(prop) {
+  if (prop === 'bind' || prop === 'call' || prop === 'apply')
+    return true;
+
   if (prop === PROXY || prop === TARGET || prop === SELF || prop === AUTO_CALL_CALLER || prop === AUTO_CALL_CALLED || prop === AUTO_CALL)
     return true;
 

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

@@ -20,6 +20,10 @@ const MiscUtils     = require('../../utils/misc-utils');
 /// it is used to parse provided date strings, and when serializing the
 /// field (for example via <see>Model.toJSON</see>).
 ///
+/// Note:
+///   A `BigInt` timestamp is used to store the date
+///   in the underlying database.
+///
 /// Example:
 ///   class Dates extends Model {
 ///     static fields = {

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

@@ -20,6 +20,10 @@ const MiscUtils         = require('../../utils/misc-utils');
 /// it is used to parse provided date strings, and when serializing the
 /// field (for example via <see>Model.toJSON</see>).
 ///
+/// Note:
+///   A `BigInt` timestamp is used to store the date
+///   and time in the underlying database.
+///
 /// Example:
 ///   class DatesWithTimes extends Model {
 ///     static fields = {

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

@@ -27,7 +27,7 @@ const Type = require('../type');
 /// then the side-effect will be that this field may be serialized
 /// and stored more often than actually needed. This system was
 /// designed this way because it is likely better to get a false
-/// positive and save your data, then not check at all and lose data.
+/// positive and save your data than to not check at all and lose data.
 /// If needed, you can always create your own child type of
 /// `SerializedType`, and overload the `isDirty` method, or provided
 /// an `isDirty` method to the field `options` to check