mythix-orm 1.5.6 → 1.6.1

package/lib/types/concrete/foreign-key-type.d.ts

@@ -0,0 +1,32 @@
+import ConnectionBase from '../../connection/connection-base';
+import Field from '../../field';
+import { ModelClass } from '../../model';
+import Type, { TypeWrapper } from '../type';
+
+export declare interface ForeignKeyTypeWrapper extends TypeWrapper<ForeignKeyType> {
+  (fullyQualifiedName: string | ForeignKeyTypeOptions, options?: ForeignKeyTypeOptions): ForeignKeyType;
+}
+
+export declare interface ForeignKeyTypeOptions {
+  Field?: Field;
+  modelName?: string;
+  fieldName?: string;
+  onDelete?: 'CASCADE' | 'SET NULL' | 'NO ACTION' | 'SET DEFAULT' | 'RESTRICT'
+  onUpdate?: 'CASCADE' | 'SET NULL' | 'NO ACTION' | 'SET DEFAULT' | 'RESTRICT'
+}
+
+export declare class ForeignKeyType extends Type {
+  public constructor(fullyQualifiedName: string | ForeignKeyTypeOptions, options?: ForeignKeyTypeOptions);
+  public parseOptionsAndCheckForErrors(SourceModel: ModelClass, sourceField: Field, connection: ConnectionBase): { Model: ModelClass, Field: Field };
+  public getOptions(): ForeignKeyTypeOptions;
+  public getTargetModel(connection?: ConnectionBase): ModelClass;
+  public getTargetModelName(connection?: ConnectionBase): string;
+  public getTargetField(connection?: ConnectionBase): Field;
+  public getTargetFieldName(connection?: ConnectionBase): string;
+
+  declare public targetModel: ModelClass | undefined;
+  declare public targetField: Field | undefined;
+  declare public fullyQualifiedName: string;
+}
+
+export const FOREIGN_KEY: ForeignKeyTypeWrapper;

package/lib/types/concrete/foreign-key-type.js

@@ -4,19 +4,127 @@ const Nife        = require('nife');
 const Type        = require('../type');
 const ModelUtils  = require('../../utils/model-utils');
 
+/// `FOREIGN_KEY` type.
+///
+/// This represents a foreign key to another column. It takes
+/// on the type of the column it points to. For example, if it
+/// points to an INTEGER column, then it will also be the same
+/// type of integer.
+///
+/// Foreign keys are one of the ways Mythix ORM knows that models
+/// are related, along with the `Model` and `Models` virtual types.
+/// The "target" field must be a fully qualified field name. A
+/// fully qualified field name is a name that is also prefixed by
+/// the model that owns it. For example, `'User:firstName'` would
+/// be a fully qualified field name, but `'firstName'` would not be.
+///
+/// Client-side storage for this field will be backed by
+/// the same type as the field the foreign key targets.
+///
+/// Example:
+///   class Role extends Model {
+///     static fields = {
+///       userID: {
+///         type: Types.FOREIGN_KEY('User:id', {
+///           onDelete: 'CASCADE',
+///           onUpdate: 'CASCADE',
+///         }),
+///         allowNull: false,
+///       },
+///       roleMetaID: {
+///         type: Types.FOREIGN_KEY({
+///           modelName: 'RoleMeta',
+///           fieldName: 'id',
+///           onDelete: 'CASCADE',
+///           onUpdate: 'CASCADE',
+///         }),
+///         allowNull: false,
+///       },
+///     };
+///   }
+///
+/// See: Type
 class ForeignKeyType extends Type {
+  /// Check if this is a foreign key type.
+  ///
+  /// There are multiple different "type checking"
+  /// static methods that exist for all field types.
+  /// This is one of them. It checks if the type
+  /// class is a foreign key type. This returns
+  /// `true` for `FOREIGN_KEY`.
+  ///
+  /// Return: boolean
+  ///   Return `true`, as the `FOREIGN_KEY` type is a
+  ///   foreign key field.
   static isForeignKey() {
     return true;
   }
 
+  /// 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 `'FOREIGN_KEY'`
   static getDisplayName() {
     return 'FOREIGN_KEY';
   }
 
-  getDisplayName() {
-    return this.constructor.getDisplayName();
-  }
-
+  /// Construct a new `ForeignKeyType` type.
+  ///
+  /// This constructor has two call patterns.
+  /// First, it can be called the shorthand way
+  /// with a string (a fully qualified field name)
+  /// as the first argument, and the field `options`
+  /// as the second argument. Or, you can simply pass
+  /// a single `options` argument, that must contain
+  /// a `modelName` and `fieldName` property that are
+  /// strings.
+  ///
+  /// Interface:
+  ///   interface ForeignKeyTypeOptions {
+  ///     // A direct field from a model, used for the target field
+  ///     // directly. i.e. `Field: User.fields.id`.
+  ///     // If this is present and valid then it
+  ///     // will supersede the `modelName` and `fieldName`
+  ///     // properties.
+  ///     Field?: Field;
+  ///
+  ///     // The model name that owns the target field
+  ///     modelName?: string;
+  ///
+  ///     // The field name of the target field on the
+  ///     // target `modelName`.
+  ///     fieldName?: string;
+  ///
+  ///     // onDelete specifies what action to take when
+  ///     // a row in the target table is deleted.
+  ///     onDelete?: 'CASCADE' | 'SET NULL' | 'NO ACTION' | 'SET DEFAULT' | 'RESTRICT'
+  ///
+  ///     // onUpdate specifies what action to take when
+  ///     // a row in the target table is updated
+  ///     // (specifically the target column).
+  ///     onUpdate?: 'CASCADE' | 'SET NULL' | 'NO ACTION' | 'SET DEFAULT' | 'RESTRICT'
+  ///   }
+  ///
+  /// Return: ForeignKeyType
+  ///   A new instance of the `ForeignKeyType` type.
+  ///
+  /// Arguments:
+  ///   fullyQualifiedName: string | object
+  ///     1) The fully qualified name of the target field as
+  ///     a string (i.e. `'User:id'`), optionally followed
+  ///     an `options` argument, or 2) the one and only
+  ///     `options` argument requiring `modelName` and
+  ///     `fieldName` properties.
+  ///   options?: object
+  ///     If `fullyQualifiedName` is defined as a string, then
+  ///     this will be the options to the field.
   constructor(_fullyQualifiedName, _options) {
     if (arguments.length === 0)
       throw new TypeError('ForeignKeyType::constructor: You must specify a fully qualified field name, or provide complete options.');
@@ -49,6 +157,22 @@ class ForeignKeyType extends Type {
     this.fullyQualifiedName = fullyQualifiedName;
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, which is
+  /// the type of the field that it targets.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: any
+  ///   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)
@@ -71,6 +195,18 @@ class ForeignKeyType extends Type {
     return targetField.type.castToType(args);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value valid.
+  /// It does so by calling the `isValidValue` of
+  /// the type that it inherits from its target
+  /// field.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value, options) {
     let targetField = this.getTargetField(options && options.connection);
     if (!targetField)
@@ -79,12 +215,29 @@ class ForeignKeyType extends Type {
     return targetField.type.isValidValue(value, options);
   }
 
+  /// This is called when the field is first initialized on
+  /// any model instance. It will verify the options provided
+  /// to the field, and ensure that it can find the target
+  /// field requested. If it can't find the target field
+  /// requested for any reason, then it will throw an exception.
+  ///
+  /// Return: { Model: ModelClass, Field: Field }
+  ///   Return the target model and field.
+  ///
+  /// Arguments:
+  ///   SourceModel: ModelClass
+  ///     The source model (model owning this foreign key field).
+  ///   sourceField:
+  ///     The source field (the field containing this foreign key type).
+  ///   connection: <see>Connection</see>
+  ///     The database connection. This is needed to fetch the target
+  ///     field and model.
   parseOptionsAndCheckForErrors(SourceModel, sourceField, connection) {
     let options             = this.options;
     let fullyQualifiedName  = this.fullyQualifiedName;
-    let Model               = options.Model;
     let Field               = options.Field;
     let fieldName           = options.fieldName;
+    let Model               = (Field && Field.Model);
 
     if (!Model) {
       if (options.modelName) {
@@ -98,9 +251,6 @@ class ForeignKeyType extends Type {
       }
     }
 
-    if (!Model)
-      throw new TypeError(`ForeignKeyType::parseOptionsAndCheckForErrors: No target model found for field "${SourceModel.getModelName()}:${sourceField.fieldName}". You must specify a model.`);
-
     if (!Field) {
       let modelName = Model.getModelName();
 
@@ -115,12 +265,42 @@ class ForeignKeyType extends Type {
     if (!Field)
       throw new TypeError(`ForeignKeyType::parseOptionsAndCheckForErrors: No target field found for "${SourceModel.getModelName()}:${sourceField.fieldName}". You must specify a field.`);
 
+    if (!Model)
+      Model = Field.Model;
+
+    if (!Model)
+      throw new TypeError(`ForeignKeyType::parseOptionsAndCheckForErrors: No target model found for field "${SourceModel.getModelName()}:${sourceField.fieldName}". You must specify a model.`);
+
     return {
       Model,
       Field,
     };
   }
 
+  /// Initialize a model instance against this type.
+  ///
+  /// Initialize is called whenever a model instance is
+  /// created. Note that the type instance is shared
+  /// across all model instances. `initialize` is still
+  /// called for every model instance that is created however,
+  /// because the type class can modify the model it
+  /// exists on. For example, the `Model` and `Models` type
+  /// inject custom relational methods onto each model instance.
+  ///
+  /// This specific `initialize` for the `ForeignKeyType`
+  /// only runs once however. The first owning model instance
+  /// that is created will call this method, and at that point
+  /// the target field will be looked up and found. After this
+  /// first lookup, the target field will be cached for all
+  /// future model instances of the same type.
+  ///
+  /// Return: undefined
+  ///
+  /// Arguments:
+  ///   connection: <see>Connection</see>
+  ///     The database connection of the calling model instance.
+  ///   self: Model
+  ///     The actual model instance that is calling this method.
   initialize(connection, self) {
     if (this.targetModel)
       return;
@@ -138,23 +318,43 @@ class ForeignKeyType extends Type {
     Object.defineProperties(this, {
       'targetModel': {
         writable:     true,
-        enumberable:  false,
+        enumerable:   false,
         configurable: true,
         value:        Model,
       },
       'targetField': {
         writable:     true,
-        enumberable:  false,
+        enumerable:   false,
         configurable: true,
         value:        Field,
       },
     });
   }
 
+  /// Get the options that were passed to the
+  /// `ForeignKeyType` on creation.
+  ///
+  /// Return: object
+  ///   The options object that was given to the field.
   getOptions() {
     return this.options;
   }
 
+  /// Fetch the target model, which is the model
+  /// owning the target field.
+  ///
+  /// Note:
+  ///   If this is called before any model has been initialized,
+  ///   or before a connection has been bound to your models, then
+  ///   you **must** provide a `connection` or this method will fail.
+  ///
+  /// Return: ModelClass
+  ///   The target field's owning model.
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     A database connection, which will be used to fiend the
+  ///     target field and owning model.
   getTargetModel(connection) {
     if (connection && !this.targetModel)
       this.initialize(connection);
@@ -162,11 +362,42 @@ class ForeignKeyType extends Type {
     return this.targetModel;
   }
 
+  /// Fetch the name of target model, which is the model
+  /// owning the target field.
+  ///
+  /// Note:
+  ///   If this is called before any model has been initialized,
+  ///   or before a connection has been bound to your models, then
+  ///   you **must** provide a `connection` or this method will fail.
+  ///
+  /// Return: string
+  ///   The target field's owning model name.
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     A database connection, which will be used to fiend the
+  ///     target field and owning model.
   getTargetModelName(connection) {
     let targetModel = this.getTargetModel(connection);
     return targetModel.getModelName();
   }
 
+  /// Fetch the target field. You can always access
+  /// the owning model via the `field.Model` property
+  /// on the field.
+  ///
+  /// Note:
+  ///   If this is called before any model has been initialized,
+  ///   or before a connection has been bound to your models, then
+  ///   you **must** provide a `connection` or this method will fail.
+  ///
+  /// Return: <see>Field</see>
+  ///   The target field from the target model.
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     A database connection, which will be used to fiend the
+  ///     target field.
   getTargetField(connection) {
     if (connection && !this.targetModel)
       this.initialize(connection);
@@ -174,6 +405,20 @@ class ForeignKeyType extends Type {
     return this.targetField;
   }
 
+  /// Fetch the target field's name.
+  ///
+  /// Note:
+  ///   If this is called before any model has been initialized,
+  ///   or before a connection has been bound to your models, then
+  ///   you **must** provide a `connection` or this method will fail.
+  ///
+  /// Return: string
+  ///   The target field's name.
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     A database connection, which will be used to fiend the
+  ///     target field.
   getTargetFieldName(connection) {
     let targetField = this.getTargetField(connection);
     if (!targetField)
@@ -190,6 +435,25 @@ class ForeignKeyType extends Type {
     return targetField.type.toConnectionType(connection, options);
   }
 
+  /// Stringify the type itself. **This will be
+  /// the type of the target field**.
+  ///
+  /// 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 target field type instead.
+  ///
+  /// 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 of the target field type.
   toString(...args) {
     if (args.length === 0)
       return 'ForeignKeyType {}';

package/lib/types/concrete/index.d.ts

@@ -0,0 +1,19 @@
+export * from './bigint-type';
+export * from './blob-type';
+export * from './boolean-type';
+export * from './char-type';
+export * from './date-type';
+export * from './datetime-type';
+export * from './foreign-key-type';
+export * from './integer-type';
+export * from './numeric-type';
+export * from './real-type';
+export * from './serialized-type';
+export * from './string-type';
+export * from './text-type';
+export * from './uuid-v1-type';
+export * from './uuid-v3-type';
+export * from './uuid-v4-type';
+export * from './uuid-v5-type';
+export * from './xid-type';
+export { default as UUIDBaseType } from './uuid-base';

package/lib/types/concrete/index.js

@@ -18,6 +18,7 @@ const { UUIDV3, UUIDV3Type }          = require('./uuid-v3-type');
 const { UUIDV4, UUIDV4Type }          = require('./uuid-v4-type');
 const { UUIDV5, UUIDV5Type }          = require('./uuid-v5-type');
 const { XID, XIDType }                = require('./xid-type');
+const UUIDBaseType                    = require('./uuid-base');
 
 module.exports = {
   BigIntType,
@@ -38,6 +39,7 @@ module.exports = {
   UUIDV4Type,
   UUIDV5Type,
   XIDType,
+  UUIDBaseType,
   BIGINT,
   BLOB,
   BOOLEAN,

package/lib/types/concrete/integer-type.d.ts

@@ -0,0 +1,16 @@
+import { AutoIncrementDefaultValueProvider } from '../helpers/default-helpers';
+import Type, { TypeWrapper } from '../type';
+
+export declare interface IntegerTypeWrapper extends TypeWrapper<IntegerType> {
+  (length?: number): IntegerType;
+}
+
+export declare class IntegerType extends Type {
+  declare public static Default: {
+    AUTO_INCREMENT: AutoIncrementDefaultValueProvider;
+  };
+
+  public constructor(length?: number);
+}
+
+export const INTEGER: IntegerTypeWrapper;

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

@@ -33,6 +33,7 @@ const { AUTO_INCREMENT }  = require('../helpers/default-helpers');
 ///   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 = {
@@ -47,16 +48,13 @@ class IntegerType extends Type {
   /// 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';
   }
 
-  getDisplayName() {
-    return this.constructor.getDisplayName();
-  }
-
   /// Construct a new `BIGINT` type.
   ///
   /// The `length` argument--as on all
@@ -67,6 +65,7 @@ class IntegerType extends Type {
   /// makes sense to the database.
   ///
   /// Return: IntegerType
+  ///
   /// Arguments:
   ///   length?: number
   ///     How many bytes to use in the underlying database to store the value.
@@ -92,6 +91,7 @@ class IntegerType extends Type {
   ///   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 }) {
@@ -113,6 +113,7 @@ class IntegerType extends Type {
   /// return `true`.
   ///
   /// Return: boolean
+  ///
   /// Arguments:
   ///   value: any
   ///     The value to check.
@@ -130,6 +131,7 @@ class IntegerType extends Type {
   /// when no `connection` is provided is `'INTEGER'`.
   ///
   /// Return: string
+  ///
   /// Arguments:
   ///   connection?: <see>Connection</see>
   ///     An optional connection. If provided, send this

package/lib/types/concrete/numeric-type.d.ts

@@ -0,0 +1,11 @@
+import Type, { TypeWrapper } from '../type';
+
+export declare interface NumericTypeWrapper extends TypeWrapper<NumericType> {
+  (precision?: number, scale?: number): NumericType;
+}
+
+export declare class NumericType extends Type {
+  public constructor(precision?: number, scale?: number);
+}
+
+export const NUMERIC: NumericTypeWrapper;

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

@@ -35,6 +35,7 @@ const DEFAULT_DECIMAL_PLACES  = 6;
 ///       numeric3: new Types.NumericType(10, 3),
 ///     };
 ///   }
+///
 /// See: Type
 class NumericType extends Type {
   /// Get the "display" name for this type.
@@ -45,16 +46,13 @@ class NumericType extends Type {
   /// 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';
   }
 
-  getDisplayName() {
-    return this.constructor.getDisplayName();
-  }
-
   /// Construct a new `NUMERIC` type.
   ///
   /// The `precision` argument specifies the
@@ -65,6 +63,7 @@ class NumericType extends Type {
   /// digits after the decimal point.
   ///
   /// Return: NumericType
+  ///
   /// Arguments:
   ///   precision?: number = 20
   ///     The total number of allowed digits in the number. This
@@ -97,6 +96,7 @@ class NumericType extends Type {
   ///   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 }) {
@@ -118,6 +118,7 @@ class NumericType extends Type {
   /// return `true`.
   ///
   /// Return: boolean
+  ///
   /// Arguments:
   ///   value: any
   ///     The value to check.
@@ -135,6 +136,7 @@ class NumericType extends Type {
   /// when no `connection` is provided is `'NUMERIC'`.
   ///
   /// Return: string
+  ///
   /// Arguments:
   ///   connection?: <see>Connection</see>
   ///     An optional connection. If provided, send this

package/lib/types/concrete/real-type.d.ts

@@ -0,0 +1,11 @@
+import Type, { TypeWrapper } from '../type';
+
+export declare interface RealTypeWrapper extends TypeWrapper<RealType> {
+  (length?: number, scale?: number): RealType;
+}
+
+export declare class RealType extends Type {
+  public constructor(length?: number, scale?: number);
+}
+
+export const REAL: RealTypeWrapper;