mythix-orm 1.5.1 → 1.5.4

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/lib/types/type.js

@@ -2,6 +2,7 @@
 
 const { checkDefaultValueFlags }  = require('./helpers/default-helpers');
 
+/// Base type class for all other field types.
 class Type {
   static _isMythixFieldType = true;
 
@@ -221,6 +222,28 @@ class Type {
     this._Model = Model;
   }
 
+  /// Cast a value to the underlying field type.
+  ///
+  /// This method is implemented differently for
+  /// every field type. Its job is to cast any
+  /// value provided to the type. For many types,
+  /// if a `null` or `undefined` value is provided,
+  /// then that value will simply be returned.
+  ///
+  /// Interface:
+  ///   interface CastToTypeContext {
+  ///     connection: Connection;  // The connection of the model.
+  ///     field: Field;            // The field descriptor that has this type.
+  ///     Model: class Model;      // The parent Model class of the field.
+  ///     self: Model;             // The model instance.
+  ///     value: any;              // The value that should be cast.
+  ///   };
+  ///
+  /// Return: any
+  /// Arguments:
+  ///   context: CastToTypeContext
+  ///     The "context" passed to `castToType`. This contains
+  ///     all that any type should need to cast a value.
   castToType({ value }) {
     return value;
   }

package/package.json

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