mythix-orm 1.11.7 → 1.12.0

package/lib/connection/connection-base.js

@@ -3,7 +3,6 @@
 const { DateTime }          = require('luxon');
 const EventEmitter          = require('events');
 const Nife                  = require('nife');
-const SqlString             = require('sqlstring');
 const { QueryEngine }       = require('../query-engine');
 const Utils                 = require('../utils');
 const { Model: ModelBase }  = require('../model');
@@ -230,6 +229,8 @@ class ConnectionBase extends EventEmitter {
 
     if (!options.queryGenerator)
       options.queryGenerator = this.createQueryGenerator(options);
+    else
+      options.queryGenerator.setConnection(this);
 
     Object.defineProperties(this, {
       'dialect': {
@@ -751,7 +752,7 @@ class ConnectionBase extends EventEmitter {
   /// it was created.
   ///
   /// Arguments:
-  ///   Model: Array<class <see>Model</see>> | { [key: string]: class <see>Model</see> }
+  ///   models: Array<class <see>Model</see>> | { [key: string]: class <see>Model</see> }
   ///     The model classes to register with this connection. If no models are bound, then
   ///     they will simply exist in the model pool for this connection. If bound, then
   ///     this connection will bind itself to every model being registered.
@@ -761,13 +762,14 @@ class ConnectionBase extends EventEmitter {
   ///     provided to the connection when it was created. If you specify either of these
   ///     options they simply override the connection's default.
   ///
-  /// Return: class <see>Model</see>
+  /// Return: { [key: string]: class <see>Model</see> }
   ///   The registered model classes, **which may have changed during registration**.
   ///   It is not uncommon for the connection driver itself to modify the model
   ///   classes, or to return a new model classes that inherit from your model classes.
   ///   The classes that are returned should be the classes that you use for this connection,
   ///   and will be the same classes returned by a call to <see>Connection.getModel</see>,
-  ///   or <see>Connection.getModels</see>.
+  ///   or <see>Connection.getModels</see>. An object is returned, where each key is
+  ///   a model name, and each value is a model class.
   registerModels(models, options) {
     if (!models)
       return;
@@ -1054,7 +1056,14 @@ class ConnectionBase extends EventEmitter {
   ///   Return the <see>QueryGenerator</see> for this connection,
   ///   or return `null` if none is defined for this connection.
   getQueryGenerator() {
-    return this.queryGenerator;
+    let queryGenerator = this.queryGenerator;
+    if (queryGenerator) {
+      let connection = queryGenerator.getConnection();
+      if (!connection)
+        queryGenerator.setConnection(this);
+    }
+
+    return queryGenerator;
   }
 
   /// Set the <see>QueryGenerator</see> instance for this
@@ -1078,15 +1087,10 @@ class ConnectionBase extends EventEmitter {
   }
 
   /// The low-level DB interface for escaping a
-  /// value. By default this function uses the
-  /// [sqlstring](https://www.npmjs.com/package/sqlstring)
-  /// module to escape values. However, the `escape`
-  /// method for whatever database the connection is
-  /// using should be used instead of this. This is
-  /// a "default implementation" that is meant as a
-  /// fallback when a connection doesn't provide its
-  /// own, but each connection should provide its own
-  /// when it is able.
+  /// value. By default this function simply returns
+  /// the value it is provided. It is up to the
+  /// database driver itself to provide a proper
+  /// implementation of this method.
   ///
   /// Note:
   ///   This method escapes "values" that are given in
@@ -1095,8 +1099,7 @@ class ConnectionBase extends EventEmitter {
   ///   instead.
   ///
   /// Return: string
-  ///   The value provided, escaped for the specific
-  ///   underlying database driver.
+  ///   The value provided.
   ///
   /// Arguments:
   ///   value: any
@@ -1104,10 +1107,7 @@ class ConnectionBase extends EventEmitter {
   ///     a string, or anything else that can be provided to your
   ///     specific database.
   _escape(value) {
-    if (Nife.instanceOf(value, 'string'))
-      return `'${value.replace(/'/g, '\'\'')}'`;
-
-    return SqlString.escape(value);
+    return value;
   }
 
   /// Unlike <see>ConnectionBase._escape</see> --which is
@@ -1198,22 +1198,18 @@ class ConnectionBase extends EventEmitter {
   /// provides as a "fallback" to database drivers that don't
   /// supply their own.
   ///
-  /// It works by first stripping all quotes (single `'`, double `"`, and backtick `` ` ``)
-  /// from the provided `value`. After this, it will split on the period (dot) character
-  /// `.`, and then will map each resulting part through [sqlstring](https://www.npmjs.com/package/sqlstring)
-  /// `escapeId` method, finally re-joining the parts with a period `.` character.
-  ///
-  /// The extra processing is to allow for already escaped identifiers to not be double-escaped.
+  /// This method simply returns the value provided. It is
+  /// expected that each database driver will properly overload
+  /// this method to provide the correct escaping for identifiers.
   ///
   /// Return: string
-  ///   The provided identifier, escaped for the underlying database.
+  ///   The provided identifier.
   ///
   /// Arguments:
   ///  value: string
   ///    The identifier to escape.
   _escapeID(value) {
-    let parts = value.replace(/['"`]/g, '').split(/\.+/g);
-    return parts.map((part) => SqlString.escapeId(part).replace(/^`/, '"').replace(/`$/, '"')).join('.');
+    return value;
   }
 
   /// This method is very similar to <see>ConnectionBase._escapeID</see>,
@@ -2789,7 +2785,7 @@ class ConnectionBase extends EventEmitter {
   /// Create a table/bucket using the provided model class.
   ///
   /// The provided `options` are database specific,
-  /// but might contain things like `ifExists`, for
+  /// but might contain things like `ifNotExists`, for
   /// example.
   ///
   /// Return: any

package/lib/connection/query-generator-base.js

@@ -2,8 +2,49 @@
 
 /// The base query generator class.
 ///
+/// A "query generator" is an interface that will take
+/// parameters (usually a <see>QueryEngine</see> or a
+/// <see>Model</see>) and generate database query statements
+/// from the input. For SQL type databases this would mean
+/// generating `SELECT`, `INSERT`, `UPDATE`, and `DELETE`
+/// statements, as well as generators for creating and altering
+/// tables, among other things.
+///
+/// The methods of this class are generally many, with the
+/// design pattern for most generators being that nearly
+/// all methods are split apart and added to the class, allowing
+/// by deliberate design much finer control when using overloaded
+/// methods, to modify or replace any parts of the generator.
+///
+/// Any connection can be provided a custom query generator
+/// interface via the `queryGenerator` option that can be
+/// used when instantiating a connection. Most connections
+/// will supply their own by default.
+///
+/// A connection should always be bound to a query generator
+/// instance. If not when first created, then at least when
+/// provided to a connection. The connection is a required
+/// part of the generator interface, and will do things, such
+/// as for example, escaping values and ids using the connection
+/// itself. The connection may be used for other operations as
+/// well.
+///
+/// Note:
+///   Some database drivers may not have a generator at all. Though
+///   database drivers commonly do have a database statement generator,
+///   a connection isn't required to have one.
+///
 /// Alias: QueryGenerator
 class QueryGeneratorBase {
+  /// Construct a new query generator
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     The connection that this interface is for. Sometimes the connection
+  ///     isn't yet available when creating the query generator, so this argument
+  ///     is optional. When provided to a <see>Connection</see>, the connection
+  ///     will call <see>QueryGenerator.setConnection</see> with itself to set
+  ///     the connection for the query generator.
   constructor(connection) {
     Object.defineProperties(this, {
       'connection': {
@@ -15,57 +56,289 @@ class QueryGeneratorBase {
     });
   }
 
+  /// Get the <see>Connection</see> bound to this
+  /// query generator.
+  ///
+  /// Return: <see>Connection</see>
+  ///   The connection bound to this query generator. A connection
+  ///   should always be bound before any generating methods of
+  ///   the class are called.
+  getConnection() {
+    return this.connection;
+  }
+
+  /// Set the <see>Connection</see> bound to this
+  /// query generator.
+  ///
+  /// Arguments:
+  ///   connection: <see>Connection</see>
+  ///     The connection to bind to this query generator.
+  ///
+  /// Return: <see>QueryGenerator</see>
+  ///   Return `this` to allow for chaining.
+  setConnection(connection) {
+    this.connection = connection;
+    return this;
+  }
+
+  /// This call proxies to <see>Connection.stackAssign</see>.
+  /// Refer to the documentation of that method for more information.
+  ///
+  /// See: Connection.stackAssign
   stackAssign(obj, ...args) {
     return this.connection.stackAssign(obj, ...args);
   }
 
+  /// This call proxies to <see>Connection.escape</see>.
+  /// Refer to the documentation of that method for more information.
+  ///
+  /// See: Connection.escape
   escape(...args) {
     return this.connection.escape(...args);
   }
 
+  /// This call proxies to <see>Connection.escapeID</see>.
+  /// Refer to the documentation of that method for more information.
+  ///
+  /// See: Connection.escapeID
   escapeID(...args) {
     return this.connection.escapeID(...args);
   }
 
+  /// Convert an <see>AverageLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>AverageLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _averageLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_averageLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>CountLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>CountLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _countLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_countLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>DistinctLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>DistinctLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _distinctLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_distinctLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>FieldLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>FieldLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _fieldLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_fieldLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>MaxLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>MaxLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _maxLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_maxLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>MinLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>MinLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _minLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_minLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>SumLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>SumLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _sumLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_sumLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Take a <see>QueryEngine</see> instance and
+  /// convert it into a query. For SQL type databases
+  /// this would turn a <see>QueryEngine</see> into a
+  /// `SELECT` statement. For other types of databases,
+  /// this should return a "fetch" query--or string representation
+  /// of such a query--in the database's native query language.
+  ///
+  /// Arguments:
+  ///   queryEngine: <see>QueryEngine</see>
+  ///     The query engine instance to stringify.
+  ///   options?: object
+  ///     Connection and operation specific options. These
+  ///     generally aren't needed, but are provided in case
+  ///     the underlying connection needs them.
+  ///
+  /// Return: string
+  ///   A "fetch" query in the databases native query language,
+  ///   generated from the provided `queryEngine`.
   // eslint-disable-next-line no-unused-vars
   toConnectionString(queryEngine, options) {
     return '<not supported by connection>';
   }
+
+  /// Get the "default value" for the given field
+  /// for the underlying database. This is used
+  /// primarily for "CREATE TABLE" statements.
+  ///
+  /// By default, the implementation of this method
+  /// is empty. It is expected that each database driver
+  /// will implement their own version of this method.
+  ///
+  /// Arguments:
+  ///   field: <see>Field</see>
+  ///     The field instance we are getting a "default value"
+  ///     from.
+  ///   fieldName: string
+  ///     The name of the field that we are getting the "default value"
+  ///     from. This should always be the same as `field.fieldName`.
+  ///   options?: object
+  ///     Options for the operation. These will likely be connection
+  ///     specific. Please refer to the documentation of your specific
+  ///     connection for more details.
+  ///
+  /// Return: any
+  ///   Though in most cases this method will return a string for
+  ///   most database drivers in most situations, it may return other
+  ///   types as well, such as literals, or other raw values.
+  ///   Please refer to the documentation of your specific
+  ///   connection for more details.
+  // eslint-disable-next-line no-unused-vars
+  getFieldDefaultValue(field, fieldName, _options) {
+  }
 }
 
 module.exports = QueryGeneratorBase;

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

@@ -4,27 +4,27 @@
 
 'use strict';
 
-const APPLY                       = Symbol.for('@_apply');
-const CALLABLE                    = Symbol.for('@_callable');
-const CONSTRUCT                   = Symbol.for('@_construct');
-const DEFINE_PROPERTY             = Symbol.for('@_defineProperty');
-const DELETE_PROPERTY             = Symbol.for('@_deleteProperty');
-const GET                         = Symbol.for('@_get');
-const GET_OWN_PROPERTY_DESCRIPTOR = Symbol.for('@_getOwnPropertyDescriptor');
-const GET_PROTOTYPEOF             = Symbol.for('@_getPrototypeOf');
-const HAS                         = Symbol.for('@_has');
-const IS_EXTENSIBLE               = Symbol.for('@_isExtensible');
-const MISSING                     = Symbol.for('@_missing');
-const OWN_KEYS                    = Symbol.for('@_ownKeys');
-const PREVENT_EXTENSIONS          = Symbol.for('@_preventExtensions');
-const SET                         = Symbol.for('@_set');
-const SET_PROTOTYPEOF             = Symbol.for('@_setPrototypeOf');
-const PROXY                       = Symbol.for('@__proxy');
-const TARGET                      = Symbol.for('@__target');
-const SELF                        = Symbol.for('@__rootInstance');
-const AUTO_CALL_CALLER            = Symbol.for('@__autoCallCaller');
-const AUTO_CALL_CALLED            = Symbol.for('@__autoCallCalled');
-const AUTO_CALL                   = Symbol.for('@__autoCall');
+const APPLY                       = Symbol.for('@_mythix/orm/ProxyClass/apply');
+const CALLABLE                    = Symbol.for('@_mythix/orm/ProxyClass/callable');
+const CONSTRUCT                   = Symbol.for('@_mythix/orm/ProxyClass/construct');
+const DEFINE_PROPERTY             = Symbol.for('@_mythix/orm/ProxyClass/defineProperty');
+const DELETE_PROPERTY             = Symbol.for('@_mythix/orm/ProxyClass/deleteProperty');
+const GET                         = Symbol.for('@_mythix/orm/ProxyClass/get');
+const GET_OWN_PROPERTY_DESCRIPTOR = Symbol.for('@_mythix/orm/ProxyClass/getOwnPropertyDescriptor');
+const GET_PROTOTYPEOF             = Symbol.for('@_mythix/orm/ProxyClass/getPrototypeOf');
+const HAS                         = Symbol.for('@_mythix/orm/ProxyClass/has');
+const IS_EXTENSIBLE               = Symbol.for('@_mythix/orm/ProxyClass/isExtensible');
+const MISSING                     = Symbol.for('@_mythix/orm/ProxyClass/missing');
+const OWN_KEYS                    = Symbol.for('@_mythix/orm/ProxyClass/ownKeys');
+const PREVENT_EXTENSIONS          = Symbol.for('@_mythix/orm/ProxyClass/preventExtensions');
+const SET                         = Symbol.for('@_mythix/orm/ProxyClass/set');
+const SET_PROTOTYPEOF             = Symbol.for('@_mythix/orm/ProxyClass/setPrototypeOf');
+const PROXY                       = Symbol.for('@__mythix/orm/ProxyClass/proxy');
+const TARGET                      = Symbol.for('@__mythix/orm/ProxyClass/target');
+const SELF                        = Symbol.for('@__mythix/orm/ProxyClass/rootInstance');
+const AUTO_CALL_CALLER            = Symbol.for('@__mythix/orm/ProxyClass/autoCallCaller');
+const AUTO_CALL_CALLED            = Symbol.for('@__mythix/orm/ProxyClass/autoCallCalled');
+const AUTO_CALL                   = Symbol.for('@__mythix/orm/ProxyClass/autoCall');
 
 function shouldSkipProxy(prop) {
   if (prop === 'bind' || prop === 'call' || prop === 'apply')
@@ -39,6 +39,26 @@ function shouldSkipProxy(prop) {
   return false;
 }
 
+/// This is essentially a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+/// converted into class form. What that means is that instead of defining a
+/// proxy by passing it a "handlers" object to it, this instead *is* the handler
+/// for all classes that inherit from it. Just like a `Proxy`, inheriting from
+/// this class will allow the child-class to intercept property gets and sets,
+/// intercept method calls, property deletion, etc...
+///
+/// It works by returning `this` inside the `constructor` wrapped in a
+/// `Proxy`. The `Proxy` it creates is then managed by the class instance itself.
+/// For example, during key access, if a key the user is requesting is not found,
+/// the proxy will call the instance method `MISSING` on the class. This allows
+/// the child class to provide a method for `MISSING`, and then respond to key
+/// access for keys that don't actually exist on the instance.
+///
+/// That is just one example of many. This class provides full `Proxy` support,
+/// and so has methods (or stubs) for every feature available natively to a `Proxy`.
+/// Instance methods are keyed by symbols. This is to try and reduce the chance
+/// of a name collision... keeping this class useful for many scenarios. For example,
+/// the `MISSING` method above is actually `Symbol.for('@_mythix/orm/ProxyClass/missing')`,
+/// that is assigned to the constant <see>ProxyClass.MISSING</see>.
 class ProxyClass {
   static APPLY = APPLY;
   static CALLABLE = CALLABLE;
@@ -175,6 +195,8 @@ class ProxyClass {
     return proxy;
   }
 
+  /// Construct the class instance, with
+  /// `this` returned wrapped in a `Proxy`.
   constructor() {
     Object.defineProperties(this, {
       [AUTO_CALL_CALLER]: {
@@ -195,6 +217,65 @@ class ProxyClass {
     return proxy;
   }
 
+  /// Any method of the instance wrapped in an
+  /// `__autoCall` factory will be automatically
+  /// called by the engine if not called by the user.
+  ///
+  /// This works by the `ProxyClass` pushing the auto-call
+  /// into a queue when the method key is accessed. If another
+  /// key is accessed (any other key), then the `ProxyClass` will
+  /// check if the auto-call method has been called yet. If it
+  /// hasn't, then the `ProxyClass` will call it, providing no
+  /// arguments, and using the return value of the call for the
+  /// pending key access. If the auto-call method is simply called,
+  /// then the queue is cleared, and the return value simply returned
+  /// to the user.
+  ///
+  /// Example:
+  ///   class Greeter extends ProxyClass {
+  ///     greet = this.__autoCall((name) => {
+  ///       if (arguments.length === 0) {
+  ///         // An auto-call, or the user didn't
+  ///         // provide any arguments.
+  ///         console.log('Hello whoever you are!');
+  ///       } else {
+  ///         // Was definitely called by the user
+  ///         console.log(`Hello ${name}!`);
+  ///       }
+  ///     });
+  ///
+  ///     finish() {
+  ///       // finish operation
+  ///     }
+  ///   }
+  ///
+  ///   // Example 1
+  ///   let greeter = new Greeter();
+  ///   greeter.greet.finish();
+  ///   //           ^---- Auto call happens here
+  ///   // output: Hello whoever you are!
+  ///
+  ///   // Example 2
+  ///   greeter.greet('Wyatt Greenway').finish();
+  ///   // No auto-call happens... this is a manual call.
+  ///   // output: Hello Wyatt Greenway!
+  ///
+  /// Note:
+  ///   For an auto-call to work, a key access attempt must happen
+  ///   after the auto-call method is accessed. This is almost always
+  ///   the case, because in interacting with the object you are almost
+  ///   guaranteed to access a key again, i.e. `.toString` if converting
+  ///   to a string, `.toJSON` if converting to JSON, iterator access,
+  ///   or even debugging the object.
+  ///
+  /// Arguments:
+  ///   caller: Function
+  ///     The method implementation for the class. This method will
+  ///     be used by the factory to create an auto-call method for
+  ///     the class.
+  ///
+  /// Return: Function
+  ///   The `caller` method provided, wrapped into an auto-call factory method.
   __autoCall(caller) {
     this[AUTO_CALL_CALLER] = caller;
     this[AUTO_CALL_CALLED] = false;
@@ -202,6 +283,60 @@ class ProxyClass {
     return this;
   }
 
+  /// This is a factory much like <see>ProxyClass.__autoCall</see>
+  /// for creating instance methods. It differs however in that
+  /// the method returned by this factory isn't auto-called, but
+  /// instead an *optional* call.
+  ///
+  /// The way it works is that the method provided is returned,
+  /// itself wrapped in a `Proxy`. If it is called, then the
+  /// `Proxy` will pass the call through to the method, and return
+  /// the result. Being a `Proxy`, it passes all key access back
+  /// to the original class instance, allowing the method itself
+  /// to mimic the class instance. This allows for instance methods
+  /// that can *optionally* be called, but if they aren't called,
+  /// will act as though you are still interacting with the instance
+  /// of the class itself.
+  ///
+  /// Example:
+  ///   class Greeter extends ProxyClass {
+  ///     constructor() {
+  ///       super();
+  ///
+  ///       this.greetName = undefined;
+  ///     }
+  ///
+  ///     name = this.__call((name) => {
+  ///       this.greetName = name;
+  ///     });
+  ///
+  ///     greet() {
+  ///       if (this.greetName) {
+  ///         console.log(`Hello ${this.greetName}!`);
+  ///       } else {
+  ///         console.log('Hello whoever you are!');
+  ///       }
+  ///     }
+  ///   }
+  ///
+  ///   // Example 1
+  ///   let greeter = new Greeter();
+  ///   greeter.name.greet();
+  ///   //          ^---- optional call here
+  ///   // output: Hello whoever you are!
+  ///
+  ///   // Example 2
+  ///   greeter.name('Wyatt Greenway').greet();
+  ///   // output: Hello Wyatt Greenway!
+  ///
+  /// Arguments:
+  ///   caller: Function
+  ///     The method implementation for the class. This method will
+  ///     be used by the factory to create an optional call method for
+  ///     the class.
+  ///
+  /// Return: Function
+  ///   The `caller` method provided, wrapped into an optional call factory method.
   __call(caller) {
     return ProxyClass.createProxy.call(this, caller.bind(this[PROXY]));
   }

package/lib/utils/async-store.js

@@ -1,3 +1,29 @@
+///! import `var { Utils: { AsyncStore } } = require('mythix-orm');`
+///!
+///! AsyncStore utilities provide the only global
+///! used in mythix-orm. The global used here is an
+///! [AsyncLocalStorage](https://nodejs.org/docs/latest-v18.x/api/async_context.html#class-asynclocalstorage) instance used to track
+///! connections (and transactions) through asynchronous
+///! calls in the engine.
+///!
+///! The `node:async_hooks` module is imported inside a
+///! `try/catch` block, so if your Javascript engine doesn't
+///! support `AsyncLocalStorage`, this will fail, and silently
+///! fallback to running the engine with no `AsyncLocalStorage`
+///! support... which simply means that connection instances need
+///! to be manually passed around everywhere.
+///!
+///! **!WARNING!: Never set the `'connection'` key, 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
+///! and all other custom keys are available for use, though it would be
+///! wise for you to prefix your key names, so as to avoid future name collisions
+///! that might occur due to newer versions of Mythix ORM, or name collisions with
+///! other 3rd party plugins or code that might set keys on the context as well.
+///!
+///! DocScope: AsyncStore
+
 'use strict';
 
 let globalAsyncStore = global._mythixGlobalAsyncLocalStore;
@@ -14,10 +40,33 @@ if (!globalAsyncStore) {
   }
 }
 
+/// Fetch the AsyncLocalStorage store.
+/// This calls `.getStore()` on the global
+/// `AsyncLocalStorage` instance.
+///
+/// Return: any
+///   The value from a `.getStore()` call on the global `AsyncLocalStorage` instance.
+///   This will be `undefined` if no `AsyncLocalStorage` context is in scope.
 function getContextStore() {
   return globalAsyncStore.getStore();
 }
 
+/// Get a specific value from the global `AsyncLocalStorage` context
+/// by name.
+///
+/// Arguments:
+///   key: any
+///     The name of the property to return. The `AsyncLocalStorage`
+///     context internally uses a `Map` instance, so the `key` provided
+///     can be of any type.
+///   defaultValue: any
+///     The default value to return if the key specified is not found.
+///
+/// Return:
+///   Return the property named by `key` if one is found, otherwise
+///   return the `defaultValue` that was provided. If the global `AsyncLocalStorage` context is not
+///   in scope when this is called, then the `defaultValue` will always be
+///   returned.
 function getContextValue(key, defaultValue) {
   let store = globalAsyncStore.getStore();
   while (store) {
@@ -33,19 +82,47 @@ function getContextValue(key, defaultValue) {
   return defaultValue;
 }
 
+/// Set a specific value on the global `AsyncLocalStorage` context
+/// by name. A `Map` instance is used internally, so the `key` can
+/// be of any type.
+///
+/// Note:
+///   The global `AsyncLocalStorage` context must be in scope for this method to work.
+///
+/// Arguments:
+///   key: any
+///     The key you wish to set on the global `AsyncLocalStorage` context.
+///   value: any
+///     The value you wish to set on the global `AsyncLocalStorage` context.
+///
+/// Return: undefined
+///   This method returns nothing.
 function setContextValue(key, value) {
   let store = globalAsyncStore.getStore();
   if (!store || !store.context)
     return;
 
-  return store.context.set(key, value);
+  store.context.set(key, value);
 }
 
+/// Run an asynchronous method in the global `AsyncLocalStorage` context.
+///
+/// Running a method this way will provide the method, and all calls within
+/// its scope the global `AsyncLocalStorage` context.
+///
+/// Arguments:
+///   context: Map | null
+///     The context `Map` to use for the operation.
+///   callback: Function
+///     The asynchronous method to call and provide the context to.
+///
+/// Return: any
+///   The return value from the callback.
 function runInContext(context, callback) {
   return globalAsyncStore.run(
     {
-      parent: globalAsyncStore.getStore(),
-      context,
+      parent:  globalAsyncStore.getStore(),
+      context: context || new Map(),
     },
     callback,
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythix-orm",
-  "version": "1.11.7",
+  "version": "1.12.0",
   "description": "ORM for Mythix framework",
   "main": "lib/index",
   "type": "commonjs",
@@ -47,7 +47,6 @@
     "inflection": "^2.0.0",
     "luxon": "^3.1.0",
     "nife": "^1.12.1",
-    "sqlstring": "^2.3.3",
     "uuid": "^9.0.0",
     "xid-js": "^1.0.1"
   },