mythix-orm 1.5.1 → 1.5.4

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;