mythix-orm 1.7.2 → 1.8.0

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

@@ -83,6 +83,10 @@ declare class ConnectionBase extends EventEmitter {
   public toQueryEngine(queryEngineLike: any): QueryEngine | undefined;
   public registerModel<T = ModelClass>(Model: T): T;
   public registerModels(models: Models | Array<ModelClass>): 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;
@@ -260,6 +260,84 @@ class ConnectionBase extends EventEmitter {
     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 context     = this.buildConnectionContext(_connection);
+    let connection  = _connection || this;
+
+    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>
@@ -343,17 +523,19 @@ class Model {
 
     let connectionOptions = connection.getOptions();
     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.`);
     }
@@ -1424,6 +1606,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

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

@@ -5,17 +5,74 @@ const Type  = require('../type');
 
 const DEFAULT_STRING_LENGTH = 256;
 
+/// `STRING` type.
+///
+/// This represents a "string" of any size for the
+/// underlying database driver, usually a "VARCHAR" type.
+///
+/// If no "length" is specified when you create the type,
+/// then a default length of `256` is assumed.
+///
+/// Example:
+///   class Strings extends Model {
+///     static fields = {
+///       string1: Types.STRING(16),
+///       string2: Types.STRING, // default length = 256
+///       string3: new Types.StringType(64),
+///     };
+///   }
+///
+/// See: Type
 class StringType extends Type {
+  /// Get the "display" name for this type.
+  ///
+  /// This method is called from <see>Model.toString</see>
+  /// when stringifying the model for representation.
+  ///
+  /// Note:
+  ///   This is also an instance method that can be called from
+  ///   an instance of the type.
+  ///
+  /// Return: string
+  ///   Return the string value `'STRING'`
   static getDisplayName() {
     return 'STRING';
   }
 
+  /// Construct a new `STRING` type.
+  ///
+  /// The `length` argument specifies
+  /// the number of characters to use for this string
+  /// in the database.
+  ///
+  /// Return: StringType
+  ///
+  /// Arguments:
+  ///   length?: number
+  ///     How many characters to use in the underlying database to store the value.
   constructor(length) {
     super(length);
 
     this.length = length || DEFAULT_STRING_LENGTH;
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `string`
+  /// primitive. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: string | null | undefined
+  ///   Return the incoming `value`, cast to this
+  ///   type. `null` and `undefined` are simply
+  ///   returned without casting.
+  ///
+  /// Arguments:
+  ///   context: <see name="CastToTypeContext">Type.castToType</see>
   castToType({ value }) {
     if (value == null)
       return value;
@@ -23,10 +80,41 @@ class StringType extends Type {
     return ('' + value);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a `string` (or `String`) instance.
+  /// Both an empty string, and a string that is nothing
+  /// except whitespace are considered "valid".
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     return Nife.instanceOf(value, 'string');
   }
 
+  /// Stringify the type itself.
+  ///
+  /// If a `connection` argument is provided, then this
+  /// will go through the connection to generate the type
+  /// for the underlying database. If no connection is
+  /// provided, then a "standard" SQL type will be returned
+  /// for this type instead. The "standard" type returned
+  /// when no `connection` is provided is `'VARCHAR'`.
+  ///
+  /// Return: string
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     An optional connection. If provided, send this
+  ///     type through <see>Type.toConnectionType</see>
+  ///     to have the connection itself generate the underlying
+  ///     type for the database. If `connection` is not provided,
+  ///     then this will simply return a "standard" generic matching
+  ///     SQL type.
   toString(connection) {
     return (connection)
       ? this.toConnectionType(connection)