mythix-orm 1.5.2 → 1.5.3

package/lib/connection/connection-base.js

@@ -100,7 +100,7 @@ class ConnectionBase extends EventEmitter {
   }
 
   getDefaultOrder(rootModel, options) {
-    return rootModel.getDefaultOrder.call(rootModel, options);
+    return rootModel.defaultOrder.call(rootModel, options);
   }
 
   _getFromModelCache(Model, key, defaultValue) {

package/lib/model.js

@@ -1343,7 +1343,7 @@ class Model {
   /// query being operated on.
   ///
   /// Note:
-  ///   Internally, Mythix ORM will call `this.connection.getDefaultOrder(options)`,
+  ///   Internally, Mythix ORM will call `this.connection.defaultOrder(options)`,
   ///   which--if not overloaded--will simply call this method from the
   ///   model itself.
   /// Note:
@@ -1360,7 +1360,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" ]`.
-  static getDefaultOrder(options) {
+  static defaultOrder(options) {
   }
 
   /// This method is called anytime a `Model.where` or `Model.$`

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

@@ -54,6 +54,9 @@ class BigIntType extends 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 `'BIGINT'`
   static getDisplayName() {
@@ -155,7 +158,10 @@ class BigIntType extends Type {
   /// 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.
+  /// for this type instead. The "standard" type returned
+  /// when no `connection` is provided is `'BIGINT'` or
+  /// `'BIGINT(${this.length})'` if a `length` is provided to
+  /// the type.
   ///
   /// Return: string
   /// Arguments:

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

@@ -4,7 +4,36 @@
 
 const Type = require('../type');
 
+/// `BLOB` type.
+///
+/// This represents a "blob", or random binary data.
+///
+/// BlobType expects that the value you provide to the
+/// field will be a `Buffer` instance. If it isn't it
+/// will throw an error when `castToType` is called.
+/// `null` and `undefined` are also acceptable values
+/// for a BlobType field.
+///
+/// Example:
+///   class Blobs extends Model {
+///     static fields = {
+///       blob1: Types.BLOB(1024),
+///       blob2: new Types.BlobType(1024),
+///     };
+///   }
+///
+/// See: Type
 class BlobType 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 `'BLOB'`
   static getDisplayName() {
     return 'BLOB';
   }
@@ -13,12 +42,40 @@ class BlobType extends Type {
     return this.constructor.getDisplayName();
   }
 
+  /// Construct a new `BLOB` type.
+  ///
+  /// The `length` argument is the number
+  /// of bytes to use in the database to
+  /// store the data.
+  ///
+  /// Return: BlobType
+  /// Arguments:
+  ///   length?: number
+  ///     How many bytes to use in the underlying database to store the value.
   constructor(length) {
     super(length);
 
     this.length = length || null;
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// Unlike most type casters, this doesn't
+  /// do any casting. You must provide either
+  /// a `Buffer`, `null`, or `undefined` as
+  /// the value to your blob field. If any
+  /// other type of value is provided then
+  /// an exception will be thrown.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: Buffer | 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;
@@ -29,10 +86,38 @@ class BlobType extends Type {
     return value;
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a `Buffer`. If it is, it will return `true`,
+  /// otherwise it will return `false`.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     return Buffer.isBuffer(value);
   }
 
+  /// 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 `'BLOB'`.
+  ///
+  /// 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)

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

@@ -2,7 +2,30 @@
 
 const Type = require('../type');
 
+/// `BOOLEAN` type.
+///
+/// This represents a "boolean" type for the underlying database.
+///
+/// Example:
+///   class Booleans extends Model {
+///     static fields = {
+///       boolean1: Types.BOOLEAN,
+///       boolean2: new Types.BooleanType(),
+///     };
+///   }
+///
+/// See: Type
 class BooleanType 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 `'BOOLEAN'`
   static getDisplayName() {
     return 'BOOLEAN';
   }
@@ -11,23 +34,73 @@ class BooleanType extends Type {
     return this.constructor.getDisplayName();
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `boolean`
+  /// primitive. It has some special edge-cases
+  /// to be aware of. If a string value matching
+  /// `'true'` or `'TRUE'` is given, then this
+  /// will result in `true`. If a value matching
+  /// `'false'` or `'FALSE'` is provided, then
+  /// the result will be `false`. Otherwise,
+  /// the result of `!!value` is returned.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: boolean | 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;
 
-    if (value === 'true')
+    if (value === 'true' || value === 'TRUE')
       return true;
 
-    if (value === 'false')
+    if (value === 'false' || value === 'FALSE')
       return false;
 
     return !!value;
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// either `true` or `false` exactly, as a primitive.
+  /// If `typeof value === 'boolean'` then this method
+  /// will return `true`, otherwise it will return `false`.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     return (value === true || value === false);
   }
 
+  /// 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 `'BOOLEAN'`.
+  ///
+  /// 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)

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

@@ -3,7 +3,31 @@
 const Nife  = require('nife');
 const Type  = require('../type');
 
+/// `CHAR` type.
+///
+/// This represents a "char" type for the underlying database,
+/// which is a single character.
+///
+/// Example:
+///   class Booleans extends Model {
+///     static fields = {
+///       char1: Types.CHAR,
+///       char2: new Types.CharType(),
+///     };
+///   }
+///
+/// See: Type
 class CharType 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 `'CHAR'`
   static getDisplayName() {
     return 'CHAR';
   }
@@ -12,6 +36,25 @@ class CharType extends Type {
     return this.constructor.getDisplayName();
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `string`
+  /// primitive with a length of one character.
+  /// If the provided value is not a `string` or
+  /// a `String`, or if the string provided has
+  /// a character length greater than one, then
+  /// an exception will be thrown.
+  ///
+  /// 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;
@@ -22,10 +65,39 @@ class CharType extends Type {
     return value.charAt(0);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a `string` or a `String` with a length
+  /// of one character. If it is, then this will
+  /// return `true`, otherwise it will return `false`.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     return (Nife.instanceOf(value, 'string') && value.length === 1);
   }
 
+  /// 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 `'CHAR'`.
+  ///
+  /// 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)

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

@@ -7,11 +7,56 @@ const { DATE_NOW }  = require('../helpers/default-helpers');
 
 moment.suppressDeprecationWarnings = true;
 
+/// `DATE` type.
+///
+/// This represents a "date", a date without time
+/// in the underlying database.
+///
+/// Client-side storage for this field will be backed by
+/// a [moment](https://momentjs.com/docs/) instance.
+///
+/// You can optionally provide a `format` argument when constructing
+/// this type. **This is a client-side format only**. It doesn't
+/// specify the format for storing the value in the database. Instead
+/// it is used to parse provided date strings, and when serializing the
+/// field (for example via <see>Model.toJSON</see>).
+///
+/// Example:
+///   class Dates extends Model {
+///     static fields = {
+///       date1: Types.DATE('YYYY-MM-DD'),
+///       date2: new Types.DateType(),
+///     };
+///   }
+///
+/// Properties:
+///   Default: object = { NOW }
+///     `NOW` is a method that can be used as the `defaultValue` of a <see>Field</see>
+///     to have this field use "NOW" time. There are a number of different ways
+///     to use this `defaultValue` method. If you use just `Types.DATE.Default.NOW`,
+///     then it will use the underlying databases 'NOW' function, setting the field
+///     to remote database time. Available also are the following:<br>
+///     1. `Types.DATE.Default.NOW` = Remote database 'NOW' time, set on insert only.<br>
+///     2. `Types.DATE.Default.NOW.UPDATE` = Remote database 'NOW' time, set on insert and update.<br>
+///     3. `Types.DATE.Default.NOW.LOCAL` = Local (client-side) 'NOW' time, set on insert only.<br>
+///     4. `Types.DATE.Default.NOW.LOCAL.UPDATE` = Local (client-side) 'NOW' time, set on insert and update.<br>
+///     *Note: It is highly recommended that you **do not** use `LOCAL` time unless you know exactly what you are doing, as clock-drift between machines may become an issue.*
+/// See: Type
 class DateType extends Type {
   static Default = {
     NOW: DATE_NOW,
   };
 
+  /// 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 `'DATE'`
   static getDisplayName() {
     return 'DATE';
   }
@@ -20,12 +65,52 @@ class DateType extends Type {
     return this.constructor.getDisplayName();
   }
 
+  /// Construct a new `DATE` type.
+  ///
+  /// The `format` argument will specify the
+  /// date format for this field. See the
+  /// [moment](https://momentjs.com/docs/#/displaying/format/) docs
+  /// for a reference on this format.
+  ///
+  /// This format **is not** the format that will be used
+  /// to store the `DATE` field in the database. Instead, this
+  /// is a client-side only format, to define how to parse
+  /// provided date strings, and to format on serialize
+  /// when calling <see>Model.toJSON</see>.
+  ///
+  /// Return: DateType
+  /// Arguments:
+  ///   format?: string
+  ///     Specify the client-side formatting for this date field.
+  ///     This will be used for parsing date strings, and for serializing
+  ///     the field.
   constructor(format) {
     super(format);
 
     this.format = format || 'YYYY-MM-DD';
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a [moment](https://momentjs.com/docs/)
+  /// instance. If the provided value results in
+  /// an invalid date, then an exception will be thrown.
+  /// Once a valid [moment](https://momentjs.com/docs/) instance
+  /// is constructed from the value provided,
+  /// `dateTime.startOf('day')` is returned, forcing
+  /// this `DATE` type to zero its time (start at the
+  /// beginning of the date specified).
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: moment | 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, connection }) {
     if (value == null)
       return value;
@@ -37,16 +122,71 @@ class DateType extends Type {
     return dateTime.startOf('day');
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a valid date. It does so by calling
+  /// `moment(value).isValid()`. If this check
+  /// results in `true`, then this method will
+  /// return `true`, otherwise it will return `false`.
+  ///
+  /// See the [moment](https://momentjs.com/docs/) library documentation for more information.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     return moment(value).isValid();
   }
 
+  /// 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 `'DATE'`.
+  ///
+  /// 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)
       : 'DATE';
   }
 
+  /// Serialize the field value.
+  ///
+  /// This will be called whenever the field's value
+  /// needs to be serialized. If a `connection` argument
+  /// is provided, then this method will assume that the
+  /// connection is serializing it for storage in the database.
+  /// In this case, <see>connection.convertDateToDBTime</see> is
+  /// called and provided the `value` for the connection to turn
+  /// the date into a proper value for the underlying database.
+  ///
+  /// If no `connection` is provided, then the date will be serialized
+  /// according to the provided `format` specified by the user. If
+  /// no format was specified by the user, then it will be serialized
+  /// to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
+  ///
+  /// Return: string | null | undefined
+  /// Arguments:
+  ///   value: moment
+  ///     The date value to serialize.
+  ///   connection?: <see>Connection</see>
+  ///     A connection instance, which if provided, will
+  ///     proxy serialization to the underlying database connection
+  ///     via the <see>connection.convertDateToDBTime</see> method.
   serialize(value, connection) {
     if (value == null)
       return (connection) ? null : value;
@@ -60,6 +200,34 @@ class DateType extends Type {
     return value.toISOString();
   }
 
+  /// Deserialize the field value.
+  ///
+  /// This method is used to deserialize a provided
+  /// field value. If the value provided is a `moment`
+  /// instance, then simply return it. Otherwise,
+  /// if a string is provided, convert it to a `moment`
+  /// instance, using the `format` provided (if any).
+  ///
+  /// The `connection` argument is not used by this
+  /// method, but is provided if the user wishes to
+  /// overload this method.
+  ///
+  /// If `null` or `undefined` are provided as a value
+  /// then that value will simply be returned as-is.
+  ///
+  /// Note:
+  ///   This method is called by `castToType` to cast
+  ///   incoming values into `moment` instances.
+  /// Return: moment
+  /// Arguments:
+  ///   value: string | moment | null | undefined
+  ///     The value to deserialize.
+  ///   connection?: <see>Connection</see>
+  ///     An optional connection that might be provided
+  ///     depending on how and where this method is called from.
+  ///     This method does nothing with the `connection`. It is
+  ///     simply provided for if the user wishes to overload this
+  ///     method.
   // eslint-disable-next-line no-unused-vars
   deserialize(_value, connection) {
     let value = _value;

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

@@ -7,11 +7,56 @@ const { DATETIME_NOW }  = require('../helpers/default-helpers');
 
 moment.suppressDeprecationWarnings = true;
 
+/// `DATETIME` type.
+///
+/// This represents a "date time", a date with a time
+/// in the underlying database.
+///
+/// Client-side storage for this field will be backed by
+/// a [moment](https://momentjs.com/docs/) instance.
+///
+/// You can optionally provide a `format` argument when constructing
+/// this type. **This is a client-side format only**. It doesn't
+/// specify the format for storing the value in the database. Instead
+/// it is used to parse provided date strings, and when serializing the
+/// field (for example via <see>Model.toJSON</see>).
+///
+/// Example:
+///   class DatesWithTimes extends Model {
+///     static fields = {
+///       dateTime1: Types.DATETIME('YYYY-MM-DD HH:mm:ss'),
+///       dateTime2: new Types.DateTimeType(),
+///     };
+///   }
+///
+/// Properties:
+///   Default: object = { NOW }
+///     `NOW` is a method that can be used as the `defaultValue` of a <see>Field</see>
+///     to have this field use "NOW" time. There are a number of different ways
+///     to use this `defaultValue` method. If you use just `Types.DATETIME.Default.NOW`,
+///     then it will use the underlying databases 'NOW' function, setting the field
+///     to remote database time. Available also are the following:<br>
+///     1. `Types.DATETIME.Default.NOW` = Remote database 'NOW' time, set on insert only.<br>
+///     2. `Types.DATETIME.Default.NOW.UPDATE` = Remote database 'NOW' time, set on insert and update.<br>
+///     3. `Types.DATETIME.Default.NOW.LOCAL` = Local (client-side) 'NOW' time, set on insert only.<br>
+///     4. `Types.DATETIME.Default.NOW.LOCAL.UPDATE` = Local (client-side) 'NOW' time, set on insert and update.<br>
+///     *Note: It is highly recommended that you **do not** use `LOCAL` time unless you know exactly what you are doing, as clock-drift between machines may become an issue.*
+/// See: Type
 class DateTimeType extends Type {
   static Default = {
     NOW: DATETIME_NOW,
   };
 
+  /// 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 `'DATETIME'`
   static getDisplayName() {
     return 'DATETIME';
   }
@@ -20,13 +65,54 @@ class DateTimeType extends Type {
     return this.constructor.getDisplayName();
   }
 
-  constructor(length, format) {
-    super(length, format);
+  /// Construct a new `DATETIME` type.
+  ///
+  /// The `format` argument will specify the
+  /// date format for this field. See the
+  /// [moment](https://momentjs.com/docs/#/displaying/format/) docs
+  /// for a reference on this format.
+  ///
+  /// This format **is not** the format that will be used
+  /// to store the `DATETIME` field in the database. Instead, this
+  /// is a client-side only format, to define how to parse
+  /// provided date strings, and to format on serialize
+  /// when calling <see>Model.toJSON</see>.
+  ///
+  /// The `length` argument is used by some database drivers
+  /// to modify the precision of the underlying timestamp/datetime value.
+  ///
+  /// Return: DateTimeType
+  /// Arguments:
+  ///   format?: string
+  ///     Specify the client-side formatting for this date field.
+  ///     This will be used for parsing date strings, and for serializing
+  ///     the field.
+  ///   length?: number
+  ///     Used by some database drivers to specify the precision of the time
+  ///     when stored in the database.
+  constructor(format, length) {
+    super(format, length);
 
-    this.length = length || null;
     this.format = format;
+    this.length = length || null;
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a [moment](https://momentjs.com/docs/)
+  /// instance. If the provided value results in
+  /// an invalid date, then an exception will be thrown.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: moment | 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, connection }) {
     if (value == null)
       return value;
@@ -38,16 +124,71 @@ class DateTimeType extends Type {
     return dateTime;
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a valid date. It does so by calling
+  /// `moment(value).isValid()`. If this check
+  /// results in `true`, then this method will
+  /// return `true`, otherwise it will return `false`.
+  ///
+  /// See the [moment](https://momentjs.com/docs/) library documentation for more information.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     return moment(value).isValid();
   }
 
+  /// 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 `'DATETIME'`.
+  ///
+  /// 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)
       : 'DATETIME';
   }
 
+  /// Serialize the field value.
+  ///
+  /// This will be called whenever the field's value
+  /// needs to be serialized. If a `connection` argument
+  /// is provided, then this method will assume that the
+  /// connection is serializing it for storage in the database.
+  /// In this case, <see>connection.convertDateToDBTime</see> is
+  /// called and provided the `value` for the connection to turn
+  /// the date into a proper value for the underlying database.
+  ///
+  /// If no `connection` is provided, then the date will be serialized
+  /// according to the provided `format` specified by the user. If
+  /// no format was specified by the user, then it will be serialized
+  /// to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
+  ///
+  /// Return: string | null | undefined
+  /// Arguments:
+  ///   value: moment
+  ///     The date value to serialize.
+  ///   connection?: <see>Connection</see>
+  ///     A connection instance, which if provided, will
+  ///     proxy serialization to the underlying database connection
+  ///     via the <see>connection.convertDateToDBTime</see> method.
   serialize(_value, connection) {
     let value = _value;
     if (value == null)
@@ -65,6 +206,34 @@ class DateTimeType extends Type {
     return value.toISOString();
   }
 
+  /// Deserialize the field value.
+  ///
+  /// This method is used to deserialize a provided
+  /// field value. If the value provided is a `moment`
+  /// instance, then simply return it. Otherwise,
+  /// if a string is provided, convert it to a `moment`
+  /// instance, using the `format` provided (if any).
+  ///
+  /// The `connection` argument is not used by this
+  /// method, but is provided if the user wishes to
+  /// overload this method.
+  ///
+  /// If `null` or `undefined` are provided as a value
+  /// then that value will simply be returned as-is.
+  ///
+  /// Note:
+  ///   This method is called by `castToType` to cast
+  ///   incoming values into `moment` instances.
+  /// Return: moment
+  /// Arguments:
+  ///   value: string | moment | null | undefined
+  ///     The value to deserialize.
+  ///   connection?: <see>Connection</see>
+  ///     An optional connection that might be provided
+  ///     depending on how and where this method is called from.
+  ///     This method does nothing with the `connection`. It is
+  ///     simply provided for if the user wishes to overload this
+  ///     method.
   // eslint-disable-next-line no-unused-vars
   deserialize(_value, connection) {
     let value = _value;

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

@@ -4,11 +4,51 @@ const Nife                = require('nife');
 const Type                = require('../type');
 const { AUTO_INCREMENT }  = require('../helpers/default-helpers');
 
+/// `INTEGER` type.
+///
+/// This represents an "integer" of any size (less than 64bits)
+/// for the underlying database driver.
+///
+/// The `INTEGER` type is used for specifying all integer types.
+/// Its `length` argument is used to specify the number of bytes
+/// used in the backing storage of the field value. Each database
+/// driver will interpret this `length` differently. For example,
+/// a MySQL driver may choose to use a `TINYINT`, `SMALLINT`, a
+/// `MEDIUMINT` based on the number of bytes specified.
+///
+/// Example:
+///   class Integers extends Model {
+///     static fields = {
+///       integer1: Types.INTEGER(4),
+///       integer2: Types.INTEGER,
+///       integer3: new Types.BigIntType(1),
+///       autoIncrementing: {
+///         type: Types.INTEGER,
+///         defaultValue: Types.INTEGER.Default.AUTO_INCREMENT,
+///       },
+///     };
+///   }
+///
+/// Properties:
+///   Default: object = { AUTO_INCREMENT }
+///     `AUTO_INCREMENT` is a method that can be used as the `defaultValue` of a <see>Field</see>
+///     to have this field auto-increment in the underlying database.
+/// See: Type
 class IntegerType extends Type {
   static Default = {
     AUTO_INCREMENT,
   };
 
+  /// 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 `'INTEGER'`
   static getDisplayName() {
     return 'INTEGER';
   }
@@ -17,12 +57,43 @@ class IntegerType extends Type {
     return this.constructor.getDisplayName();
   }
 
+  /// Construct a new `BIGINT` type.
+  ///
+  /// The `length` argument--as on all
+  /// integer types in Mythix ORM--specifies
+  /// the number of bytes to use for this type
+  /// in the database. Each underlying database
+  /// driver will interpret this value in a way that
+  /// makes sense to the database.
+  ///
+  /// Return: IntegerType
+  /// Arguments:
+  ///   length?: number
+  ///     How many bytes to use in the underlying database to store the value.
+  ///     Depending on the database driver, a length of `0` may be interpreted
+  ///     as a single bit.
   constructor(length) {
     super(length);
 
     this.length = length || null;
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `number`
+  /// primitive. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: number | 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;
@@ -34,10 +105,39 @@ class IntegerType extends Type {
     return Math.round(number);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a `number` instance, and if it is finite.
+  /// If both conditions are true, then it will
+  /// return `true`.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     return (Nife.instanceOf(value, 'number') && isFinite(value));
   }
 
+  /// 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 `'INTEGER'`.
+  ///
+  /// 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)

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

@@ -6,7 +6,47 @@ const Type  = require('../type');
 const DEFAULT_TOTAL_DIGITS    = 20;
 const DEFAULT_DECIMAL_PLACES  = 6;
 
+/// `NUMERIC` type.
+/// Also known as `NUMBER`, or `DECIMAL` in some databases.
+///
+/// This represents a "real" number of high precision and
+/// accuracy in the underlying database driver. Unlike the
+/// <see>RealType</see>, which suffers from precision and
+/// rounding errors, this will be precise to very large
+/// and very small values in most databases.
+///
+/// The `precision`, and `scale` arguments are named after
+/// PostgreSQL, and need some explaining, as their names do
+/// not match their intent very well. `precision` is the total
+/// number of digits a number can have. For example, the number
+/// 123.456 has a `precision` of `6`, because it contains six
+/// digits. The `scale` specifies the number of digits that
+/// are desired *after* the decimal place. A scale of `0` would
+/// essentially mean that you want an integer (no decimal places),
+/// whereas a `scale` of `2` would mean you want two decimal places.
+/// It is important to call out that different database drivers
+/// may interpret and use these values differently.
+///
+/// Example:
+///   class Numeric extends Model {
+///     static fields = {
+///       numeric1: Types.NUMERIC(20, 6),
+///       numeric2: Types.NUMERIC,
+///       numeric3: new Types.NumericType(10, 3),
+///     };
+///   }
+/// See: Type
 class NumericType 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 `'NUMERIC'`
   static getDisplayName() {
     return 'NUMERIC';
   }
@@ -15,6 +55,27 @@ class NumericType extends Type {
     return this.constructor.getDisplayName();
   }
 
+  /// Construct a new `NUMERIC` type.
+  ///
+  /// The `precision` argument specifies the
+  /// total number of digits (including decimal places)
+  /// allowed for each number. The `scale` argument
+  /// specifies the number of digits allowed after the decimal
+  /// place. A `scale` of `0` is valid, meaning you want no
+  /// digits after the decimal point.
+  ///
+  /// Return: NumericType
+  /// Arguments:
+  ///   precision?: number = 20
+  ///     The total number of allowed digits in the number. This
+  ///     includes decimal places. So a number of 123.456 would
+  ///     need a `precision` of `6`, since it contains six total
+  ///     digits.
+  ///   scale?: number = 6
+  ///     How many digits are allowed after the decimal point.
+  ///     A value of `2` would allow two digits after the decimal
+  ///     point. A value of `0` would allow no digits after the decimal
+  ///     point, essentially turning this into an integer.
   constructor(precision, scale) {
     super(precision, scale);
 
@@ -22,6 +83,22 @@ class NumericType extends Type {
     this.scale = scale || DEFAULT_DECIMAL_PLACES;
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `number`
+  /// primitive. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: number | 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;
@@ -33,10 +110,39 @@ class NumericType extends Type {
     return number;
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a `number` instance, and if it is finite.
+  /// If both conditions are true, then it will
+  /// return `true`.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     return (Nife.instanceOf(value, 'number') && isFinite(value));
   }
 
+  /// 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 `'NUMERIC'`.
+  ///
+  /// 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)

package/lib/types/helpers/default-helpers.js

@@ -80,13 +80,13 @@ function generatePermutations(func, flags) {
     return func.apply(this, args);
   }, Object.assign({}, flags, { onUpdate: true }));
 
-  masterFunc.INSERT = defaultValueFlags(function(...args) {
-    return func.apply(this, args);
-  }, Object.assign({}, flags, { onInsert: true }));
+  // masterFunc.INSERT = defaultValueFlags(function(...args) {
+  //   return func.apply(this, args);
+  // }, Object.assign({}, flags, { onInsert: true }));
 
-  masterFunc.ALWAYS = defaultValueFlags(function(...args) {
-    return func.apply(this, args);
-  }, Object.assign({}, flags, { onStore: true }));
+  // masterFunc.ALWAYS = defaultValueFlags(function(...args) {
+  //   return func.apply(this, args);
+  // }, Object.assign({}, flags, { onStore: true }));
 
   return masterFunc;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythix-orm",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "ORM for Mythix framework",
   "main": "lib/index.js",
   "type": "commonjs",