mythix-orm 1.7.2 → 1.8.1

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)

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

@@ -3,19 +3,83 @@
 const Nife  = require('nife');
 const Type  = require('../type');
 
-const DEFAULT_STRING_LENGTH = 65565;
+const DEFAULT_TEXT_LENGTH = 65565;
 
+/// `TEXT` type.
+///
+/// This represents a "text" of any size for the
+/// underlying database driver, usually a "TEXT" type.
+///
+/// If no "length" is specified when you create the type,
+/// then a default length of `65565` is assumed.
+///
+/// In most databases, a "TEXT" type is used for storing
+/// large text blobs. Most databases will store this type
+/// outside of the engine in a separate file space, and
+/// so this type can be a little slower than other types,
+/// however the tradeoff is that you can store a large
+/// amount of text.
+///
+/// Example:
+///   class TextBlobs extends Model {
+///     static fields = {
+///       text1: Types.TEXT(65535),
+///       text2: Types.TEXT, // default length = 65535
+///       text3: new Types.TextType(65535),
+///     };
+///   }
+///
+/// See: Type
 class TextType 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 `'TEXT'`
   static getDisplayName() {
     return 'TEXT';
   }
 
+  /// Construct a new `TEXT` 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;
+    this.length = length || DEFAULT_TEXT_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 +87,41 @@ class TextType 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 `'TEXT'`.
+  ///
+  /// 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/uuid-v1-type.js

@@ -7,6 +7,55 @@ const { defaultValueFlags } = require('../helpers/default-helpers');
 
 let CALLABLE_PROP_NAMES = [ 'node', 'clockseq', 'msecs', 'nsecs', 'random', 'buffer', 'offset' ];
 
+/// `UUID` (version 1) type.
+///
+/// This represents a string based UUID,
+/// using UUID version 1. The underlying
+/// database type is the same as <see>StringType</see>,
+/// which is usually a "VARCHAR" type.
+///
+/// An optional "prefix" can be specified for this
+/// type, which will allow you to prefix your ids.
+///
+/// This type will automatically decide its own "length"
+/// based on the length of a UUIDV1, plus the length of
+/// any prefix you provide.
+///
+/// See the [uuid](https://www.npmjs.com/package/uuid)
+/// module to properly understand the options for this
+/// field type.
+///
+/// Example:
+///   class UUIDs extends Model {
+///     static fields = {
+///       uuid1: Types.UUIDV1({
+///         prefix: 'USER_',
+///         node: ...,
+///         clockseq: ...,
+///         msecs: ...,
+///         nsecs: ...,
+///         random: ...,
+///         rng: ...,
+///         buffer: ...,
+///         offset: ...,
+///       }),
+///       uuid2: new Types.UUIDV1Type({
+///         prefix: 'USER_',
+///         ...,
+///       }),
+///       uuidWithDefault: {
+///         type: Types.UUIDV1({ ... }),
+///         defaultValue: Types.UUIDV1.Default.UUIDV1,
+///       },
+///     };
+///   }
+///
+/// Properties:
+///   Default: object = { UUIDV1 }
+///     `UUIDV1` is a method that can be used as the `defaultValue` of a <see>Field</see>
+///     to have this field auto-generate UUIDs for new models.
+///
+/// See: Type
 class UUIDV1Type extends UUIDBaseType {
   static Default = {
     UUIDV1: defaultValueFlags(function(context) {
@@ -23,10 +72,35 @@ class UUIDV1Type extends UUIDBaseType {
     }),
   };
 
+  /// 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 `'UUIDV1'`
   static getDisplayName() {
     return 'UUIDV1';
   }
 
+  /// This is an internal method that is used by the
+  /// type. It prepares the arguments needed for the
+  /// [uuid](https://www.npmjs.com/package/uuid) module
+  /// based on the options provided to the type when
+  /// created. It will return arguments that can be
+  /// properly passed to [uuid.v1](https://www.npmjs.com/package/uuid#uuidv1options-buffer-offset).
+  ///
+  /// Return: Array<any>
+  ///   An array of arguments to pass to `uuid.v1`
+  ///
+  /// Arguments:
+  ///   options: object
+  ///     The "options" object provided to the type when
+  ///     it was initially created.
   getArgsForUUID(options) {
     let uuidOptions = {};
 
@@ -53,6 +127,23 @@ class UUIDV1Type extends UUIDBaseType {
     return args;
   }
 
+  /// This is an internal method that is used by the
+  /// type. It validates the arguments that will be passed
+  /// to the [uuid.v1](https://www.npmjs.com/package/uuid#uuidv1options-buffer-offset) method.
+  /// If incorrect options were provided to the type
+  /// when the type was specified, then this will throw
+  /// a validation exception.
+  ///
+  /// Note:
+  ///   The provided "options" are not validated until
+  ///   the first UUID is generated for the first time.
+  ///
+  /// Return: undefined
+  ///
+  /// Arguments:
+  ///   uuidArgs: Array<any>
+  ///     The arguments that will be passed to [uuid.v1](https://www.npmjs.com/package/uuid#uuidv1options-buffer-offset).
+  ///     If an issue is detected than an exception will be thrown.
   validateOptions(uuidArgs) {
     let uuidOptions = uuidArgs[0];
 
@@ -66,6 +157,38 @@ class UUIDV1Type extends UUIDBaseType {
       throw new Error('UUIDV1Type::Default::UUIDV1: One of "options.rng" or "option.random" options are required for the specified type. Try "type: Types.UUIDV1({ rng: () => Array[16] })" or "type: Types.UUIDV1({ random: Function | Array[16] })" for your type instead.');
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `UUIDV1`
+  /// string primitive. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// The provided value will be given to [uuid.validate](https://www.npmjs.com/package/uuid#uuidvalidatestr)
+  /// to validate that it is a correct UUIDV1. If the provided value
+  /// is not a valid UUIDV1, then this method will throw an exception.
+  ///
+  /// If your UUID is prefixed with the `prefix`
+  /// option, then that will be stripped off first
+  /// before the provided value is handed off to
+  /// [uuid.validate](https://www.npmjs.com/package/uuid#uuidvalidatestr)
+  /// for validation. The prefix will be added back after validation.
+  ///
+  /// Note:
+  ///   If a valid UUID is given without a prefix, then the
+  ///   specified prefix (if any) will simply be added to
+  ///   the returned result.
+  ///
+  /// 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(args) {
     let { value } = args;
     if (value == null)
@@ -77,6 +200,16 @@ class UUIDV1Type extends UUIDBaseType {
     return this.addPrefix(value);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a valid UUIDV1, ignoring any prefix.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     if (!Nife.instanceOf(value, 'string'))
       return false;

package/lib/types/concrete/uuid-v3-type.js

@@ -7,6 +7,51 @@ const { defaultValueFlags } = require('../helpers/default-helpers');
 
 let CALLABLE_PROP_NAMES = [ 'name', 'namespace', 'buffer', 'offset' ];
 
+/// `UUID` (version 3) type.
+///
+/// This represents a string based UUID,
+/// using UUID version 3. The underlying
+/// database type is the same as <see>StringType</see>,
+/// which is usually a "VARCHAR" type.
+///
+/// An optional "prefix" can be specified for this
+/// type, which will allow you to prefix your ids.
+///
+/// This type will automatically decide its own "length"
+/// based on the length of a UUIDV3, plus the length of
+/// any prefix you provide.
+///
+/// See the [uuid](https://www.npmjs.com/package/uuid)
+/// module to properly understand the options for this
+/// field type.
+///
+/// Example:
+///   class UUIDs extends Model {
+///     static fields = {
+///       uuid1: Types.UUIDV3({
+///         prefix: 'USER_',
+///         name: ...,
+///         namespace: ...,
+///         buffer: ...,
+///         offset: ...,
+///       }),
+///       uuid2: new Types.UUIDV3Type({
+///         prefix: 'USER_',
+///         ...,
+///       }),
+///       uuidWithDefault: {
+///         type: Types.UUIDV3({ ... }),
+///         defaultValue: Types.UUIDV3.Default.UUIDV3,
+///       },
+///     };
+///   }
+///
+/// Properties:
+///   Default: object = { UUIDV3 }
+///     `UUIDV3` is a method that can be used as the `defaultValue` of a <see>Field</see>
+///     to have this field auto-generate UUIDs for new models.
+///
+/// See: Type
 class UUIDV3Type extends UUIDBaseType {
   static Default = {
     UUIDV3: defaultValueFlags(function(context) {
@@ -23,10 +68,35 @@ class UUIDV3Type extends UUIDBaseType {
     }),
   };
 
+  /// 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 `'UUIDV3'`
   static getDisplayName() {
     return 'UUIDV3';
   }
 
+  /// This is an internal method that is used by the
+  /// type. It prepares the arguments needed for the
+  /// [uuid](https://www.npmjs.com/package/uuid) module
+  /// based on the options provided to the type when
+  /// created. It will return arguments that can be
+  /// properly passed to [uuid.v3](https://www.npmjs.com/package/uuid#uuidv3name-namespace-buffer-offset).
+  ///
+  /// Return: Array<any>
+  ///   An array of arguments to pass to `uuid.v3`
+  ///
+  /// Arguments:
+  ///   options: object
+  ///     The "options" object provided to the type when
+  ///     it was initially created.
   getArgsForUUID(options) {
     let uuidOptions = {};
 
@@ -62,6 +132,23 @@ class UUIDV3Type extends UUIDBaseType {
     return args;
   }
 
+  /// This is an internal method that is used by the
+  /// type. It validates the arguments that will be passed
+  /// to the [uuid.v3](https://www.npmjs.com/package/uuid#uuidv3name-namespace-buffer-offset) method.
+  /// If incorrect options were provided to the type
+  /// when the type was specified, then this will throw
+  /// a validation exception.
+  ///
+  /// Note:
+  ///   The provided "options" are not validated until
+  ///   the first UUID is generated for the first time.
+  ///
+  /// Return: undefined
+  ///
+  /// Arguments:
+  ///   uuidArgs: Array<any>
+  ///     The arguments that will be passed to [uuid.v3](https://www.npmjs.com/package/uuid#uuidv3name-namespace-buffer-offset).
+  ///     If an issue is detected than an exception will be thrown.
   validateOptions(uuidArgs) {
     let [ name, namespace ] = uuidArgs;
 
@@ -75,6 +162,38 @@ class UUIDV3Type extends UUIDBaseType {
       throw new Error('UUIDV3Type::Default::UUIDV3: "options.namespace" option is required for the specified type. Try "type: Types.UUIDV3({ namespace: Function | String | Array[16] })" for your type instead.');
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `UUIDV3`
+  /// string primitive. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// The provided value will be given to [uuid.validate](https://www.npmjs.com/package/uuid#uuidvalidatestr)
+  /// to validate that it is a correct UUIDV3. If the provided value
+  /// is not a valid UUIDV3, then this method will throw an exception.
+  ///
+  /// If your UUID is prefixed with the `prefix`
+  /// option, then that will be stripped off first
+  /// before the provided value is handed off to
+  /// [uuid.validate](https://www.npmjs.com/package/uuid#uuidvalidatestr)
+  /// for validation. The prefix will be added back after validation.
+  ///
+  /// Note:
+  ///   If a valid UUID is given without a prefix, then the
+  ///   specified prefix (if any) will simply be added to
+  ///   the returned result.
+  ///
+  /// 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(args) {
     let { value } = args;
     if (value == null)
@@ -86,6 +205,16 @@ class UUIDV3Type extends UUIDBaseType {
     return this.addPrefix(value);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a valid UUIDV3, ignoring any prefix.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     if (!Nife.instanceOf(value, 'string'))
       return false;