mythix-orm 1.5.1 → 1.5.4

package/lib/connection/connection-base.js

@@ -99,8 +99,16 @@ class ConnectionBase extends EventEmitter {
     this.registerModels(options.models);
   }
 
-  getDefaultOrder(rootModel, options) {
-    return rootModel.getDefaultOrder.call(rootModel, options);
+  getDefaultOrder(Model, options) {
+    let order = Model.defaultOrder(options);
+    if (!order)
+      return;
+
+    order = Nife.arrayFlatten(Nife.toArray(order)).filter(Boolean);
+    if (Nife.isEmpty(order))
+      return;
+
+    return order;
   }
 
   _getFromModelCache(Model, key, defaultValue) {

package/lib/field.js

@@ -1,8 +1,183 @@
 'use strict';
 
+/// Field class, that holds the properties
+/// of all field descriptors that define
+/// the model's fields.
+///
+/// Example:
+///   class User extends Model {
+///     // Each field below is termed a "field descriptor"
+///     // and will eventually be turned into a Field.
+///     static fields = {
+///       id: {
+///         type:         Types.BIGINT,
+///         defaultValue: Types.BIGINT.Default.AUTO_INCREMENT,
+///         allowNull:    false,
+///         primaryKey:   true,
+///       },
+///       email: {
+///         type:         Types.STRING(64),
+///         allowNull:    false,
+///         index:        true,
+///         unique:       true,
+///         valiate:      (value) => {
+///           if (('' + value).indexOf('@') < 0)
+///             throw new Error(`Invalid email address: "${value}"`);
+///         },
+///       },
+///       gender: {
+///         type:         Types.STRING(32),
+///         allowNull:    false,
+///         index:        true,
+///         defaultValue: 'other',
+///         valiate:      (value) => {
+///           if (!(/^(male|female|other)$/).test(value))
+///             throw new Error(`Invalid gender: "${value}"`);
+///         },
+///       },
+///       prefix: {
+///         type:         Types.STRING(10),
+///         allowNull:    true,
+///         index:        true,
+///         get:          ({ self, value }) => {
+///           if (self.gender === 'male')
+///             return 'Mr.';
+///           else if (self.gender === 'female')
+///             return 'Ms.';
+///           else
+///             return value;
+///         },
+///         set:          ({ set, value }) => {
+///           set(value);
+///         },
+///       },
+///       firstName: {
+///         type:         Types.STRING(32),
+///         allowNull:    false,
+///         index:        true,
+///       },
+///       lastName: {
+///         type:         Types.STRING(32),
+///         allowNull:    false,
+///         index:        true,
+///       },
+///     };
+///   }
+///
+/// Interface:
+///   interface DefaultValueContext {
+///     _initial: boolean;        // If `true`, then this is the initial set of the field's value.
+///     connection: Connection;   // The connection from the model.
+///     data: object | undefined; // All attributes provided to the model upon instantiation.
+///     field: Field;             // The field descriptor where this `defaultValue` is defined.
+///     fieldName: string;        // The name of this field where this `defaultValue` is defined.
+///     fieldValue: any;          // The field value as provided to the model instance upon instantiation.
+///     self: Model;              // The model instance.
+///   }
+///
+/// Interface:
+///   interface GetSetContext {
+///     field: Field;       // The field descriptor of this field.
+///     fieldName: string;  // The field name of this field.
+///     get: Function;      // A method to fetch the current value of this field.
+///     self: Model;        // The model instance of this field value.
+///     set: Function;      // A method to set the current value of this field.
+///     value: any;         // The current value of this field.
+///   }
+///
+/// Properties:
+///   type: Type
+///     The type of the field. Can be either a virtual or concrete type.
+///     You can supply either a `Type` instance (`type: new Types.BigIntType()`),
+///     a `Type` class (`type: Types.BigIntType`), a type wrapper
+///     (`type: Types.BIGINT`), or a `Type` instance created through a type
+///     wrapper (`type: Types.BIGINT(8)`).
+///   primaryKey: boolean = false
+///     If `true`, then this field will be the primary key of the model.
+///     It will also be marked as the primary key in the underlying database.
+///   fieldName: string
+///     The name of this field. If not provided, this will
+///     be the key that defined the field. If your model
+///     fields are defined as an `Array` or `Set`, then this
+///     attribute is required, and must be supplied. If
+///     your fields are defined as an `Object`, or a `Map`,
+///     then if this attribute is not supplied, the key
+///     will be used as the `fieldName` instead. The
+///     `fieldName` always takes priority, so if you
+///     have a key and a `fieldName`, then the field name
+///     will take precedence over the key name.
+///  allowNull: boolean = true
+///    If `true`, then this field is allowed to have a `NULL`
+///    value in the underlying database. If `false`, then this
+///    field must not have a `NULL` value in the underlying database.
+///    This has no effect client-side in JavaScript. Even if `allowNull`
+///    is `false`, the field property on your model may still have a
+///    `null` value in JavaScript.
+///  index: boolean = false
+///    If `true`, then this field will be indexed in the database.
+///  unique: boolean = false
+///    If `true`, then add a unique constraint to this field in
+///    the underlying database.
+///  defaultValue: any | Function(context: DefaultValueContext)
+///    Provide a default value for this field. `defaultValue` in
+///    Mythix ORM can be either a literal value, such as a `string`
+///    or a `number`, it can be `null`, or it can be a function. If
+///    it is a function, it will be called when the model is initialized
+///    if no value for the field was provided to the model during instantiation.
+///    As a method, it can have numerous different "flags" set on it, via
+///    the <see>DefaultHelpers.defaultValueFlags</see> factory. Reference this
+///    methods documentation for a better understanding of what default value
+///    flags are, and what they do.
+///  get: Function(context: GetSetContext)
+///    A "getter" for this field. If defined, this will be called any time
+///    the field is accessed. The return value will be the value of the field.
+///    Use the `get` method provided by the `context` argument to get the underlying
+///    field value, or use <see>Model.getDataValue</see> to get the underlying value.<br>
+///    *Note: The provided `get` method, and <see>Model.getDataValue</see> will bypass this method.*<br>
+///    *Note: Do NOT get the field property directly on the model inside this method, or you will enter an infinite recursive loop.*
+///  set: Function(context: GetSetContext)
+///    A "setter" for this field. If defined, this will be called any time
+///    the field is set. This field must call the `set` method provided by
+///    the `context` argument, or it must call <see>Model.setDataValue</see>
+///    on the `self` model instance provided by the `context`.<br>
+///    *Note: The provided `set` method, and <see>Model.setDataValue</see> will bypass this method.*<br>
+///    *Note: Do NOT set the field name directly on the model inside this method, or you will enter an infinite recursive loop.*
+///  validate: async Function(value: any, context: { connection, Model, options })
+///    If this method is provided, then it will be called from <see>Model.onValidate</see>
+///    immediately before an insert or update operation. The return value of this method
+///    is ignored by Mythix ORM (though if you want, you can do something with it if you
+///    overload the `onValidate` method of the model). If validation fails, it is expected
+///    that this method will throw an error. Notice that RegExp or pattern values are not
+///    supported. `validate` MUST be a method. How you implement it is up to you.
+///    The `value` argument is the current value of the field. The `context` argument
+///    is provided by the underlying connection. The `Model` inside the context is the
+///    model class of the current model that is being validated. The `options` inside
+///    the context is simply an object containing the current options for the underlying
+///    connection operation.
 class Field {
+  /// This helps with type checking
   static _isMythixField = true;
 
+  /// Check if the provided `value` is
+  /// a <see>Field</see> class.
+  ///
+  /// This will check if the provided value's
+  /// `prototype` is an instance of <see>Field</see>
+  /// if it is, this method will return `true`.
+  /// If that check fails, then it will see if
+  /// the provided value has a `_isMythixField`
+  /// property that is `true`. If this is the
+  /// case, then this method will return `true`.
+  /// Finally, if all checks have failed, this
+  /// method will return false.
+  ///
+  /// Return: boolean
+  ///   `true` if the provided value is a <see>Field</see>
+  ///    class, or inherits from <see>Field</see>. `false`
+  ///    otherwise.
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   static isFieldClass(value) {
     if (!value)
       return false;
@@ -16,6 +191,26 @@ class Field {
     return false;
   }
 
+  /// Check if the provided `value` is
+  /// a <see>Field</see> instance.
+  ///
+  /// This will check if the provided value
+  /// is an `instanceof` <see>Field</see>,
+  /// if it is this method will return `true`.
+  /// If that check fails, then it will see if
+  /// the provided value has a `value.constructor_isMythixField`
+  /// property that is `true`. If this is the
+  /// case, then this method will return `true`.
+  /// Finally, if all checks have failed, this
+  /// method will return false.
+  ///
+  /// Return: boolean
+  ///   `true` if the provided value is a <see>Field</see>
+  ///    instance, or inherits from <see>Field</see>. `false`
+  ///    otherwise.
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   static isField(value) {
     if (!value)
       return false;
@@ -29,15 +224,37 @@ class Field {
     return false;
   }
 
+  /// Construct a Field.
+  ///
+  /// This method will create a new instance of <see>Field</see>.
+  /// The provided `fieldDefinition` argument is expected to
+  /// be another <see>Field</see>, or an iterable object containing
+  /// the field attributes.
+  ///
+  /// Return: <see>Field</see>
+  /// Arguments:
+  ///   fieldDescription: object | <see>Field</see>
+  ///     The attributes to provide to this field.
   constructor(fieldDefinition) {
     Object.assign(this, fieldDefinition || {});
   }
 
+  /// Clone this field instance.
+  ///
+  /// Return: <see>Field</see>
+  ///   This field, cloned into a new instance.
   clone() {
     const FieldClass = this.constructor;
     return new FieldClass(this);
   }
 
+  /// Set the parent <see>Model</see> class
+  /// for this field.
+  ///
+  /// Return: undefined
+  /// Arguments:
+  ///   Model: class <see>Model</see>
+  ///     The parent model class of this field.
   setModel(Model) {
     this.Model = Model;
   }

package/lib/model.js

@@ -432,7 +432,7 @@ class Model {
 
   /// One can apply a "default scope" to any model simply
   /// by providing this static method on the model. By
-  /// default it will simply return the <see>QueryEngine</see>
+  /// default it will simply return the <see name="derp">QueryEngine</see>
   /// instance (a query) that it was provided.
   ///
   /// The way this works is simple. The caller provides the
@@ -1112,33 +1112,28 @@ class Model {
   /// value from the provided `callback` will be pushed into an array
   /// just like `Array.prototype.map`. The `callback` provided, when called,
   /// will be provided a `context` object, as the single argument to
-  /// the callback. This context object has the following shape:
-  /// ```javascript
-  /// IterationContext = {
-  ///   // The Field instance itself.
-  ///   field,
-  ///   // The name of the field.
-  ///   fieldName,
-  ///   // All the model's fields.
-  ///   fields,
-  ///   // The current index into the list of fields.
-  ///   // This will be set even if the fields are
-  ///   // `object` or `Map` types.
-  ///   index,
-  ///   // A method that when called will halt
-  ///   // iteration and immediately return.
-  ///   stop,
-  ///   // A method that you can call to see
-  ///   // if `stop` has been called... meaning the
-  ///   // iteration process is about to halt.
-  ///   isStopped,
-  /// }
-  /// ```
+  /// the callback.
   ///
   /// At any time you can call the `stop` method provided via the context.
   /// When called, `iterateFields` will stop iterating, and immediately
   /// return an array of results returned by all calls to `callback`.
   ///
+  /// The provided `context` object has the following shape:
+  ///
+  /// Interface:
+  ///   interface IterationContext {
+  ///     field: Field;           // The Field instance itself.
+  ///     fieldName: string;      // The name of the field.
+  ///     fields:                 // All the model's fields.
+  ///       Array<Field> |
+  ///       Set<Field> |
+  ///       Object<string, Field> |
+  //        Map<string, Field>;
+  ///     index: string | number; // The current index into the list of fields.
+  ///     stop: Function;         // A method that when called will halt iteration.
+  ///     isStopped: Function;    // Call this method to see if iteration is about to be halted.
+  ///   }
+  ///
   /// Return: Array<any>
   /// Arguments:
   ///   callback: Function(context: IterationContext)
@@ -1348,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:
@@ -1365,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.$`
@@ -1902,6 +1897,7 @@ class Model {
       if (shouldRunDefaultValueOnInitialize()) {
         defaultValue = defaultValue({
           model:              this,
+          self:               this,
           connection:         this.getConnection(),
           _initial:           true,
           field,
@@ -1942,16 +1938,7 @@ class Model {
   /// fields for the model instance. Unlike
   /// `Model.changes`, which is a getter, you can
   /// pass `options` to this method, which can change
-  /// its behavior. The `options` argument has the
-  /// following shape:
-  /// ```javascript
-  /// {
-  ///   connection: <see>Connection</see>,
-  ///   update: boolean,
-  ///   insert: boolean,
-  ///   // ... any options you wish to pass to `connection.dirtyFieldHelper`
-  /// }
-  /// ```
+  /// its behavior.
   ///
   /// If this method is provided a <see>Connection</see> via the
   /// `connection` options value, then it will assume it is being
@@ -2001,6 +1988,17 @@ class Model {
   /// or since the last time the <see>Model.clearDirty</see> method was
   /// called.
   ///
+  /// The `options` argument has the
+  /// following shape:
+  ///
+  /// Interface:
+  ///   interface DirtyFieldOptions {
+  ///     connection: Connection; // The connection for this operation.
+  ///     update: boolean;        // If `true`, then this is an update operation.
+  ///     insert: boolean;        // If `true`, then this is an insert operation.
+  ///     // ... any options you wish to pass to `connection.dirtyFieldHelper`
+  ///   }
+  ///
   /// Note:
   ///   If this is an "update" or "insert" operation, as defined by
   ///   the `update` or `insert` "options", then the default value
@@ -2008,7 +2006,7 @@ class Model {
   ///   method through the provided `connection`.
   /// Return: DirtyFieldChangeList
   /// Arguments:
-  ///   options?: object
+  ///   options?: DirtyFieldOptions
   ///     Options to provide to the method.
   _getDirtyFields(_options) {
     let options         = _options || {};
@@ -2120,13 +2118,14 @@ class Model {
   ///     The name of the field whose value we wish to get.
   ///   field: <see>Field</see>
   ///     The field definition itself for the value we wish to get.
-  /// See: Field.get
+  /// See: Field
   _getFieldValue(fieldName, field) {
     let value = this.getDataValue(fieldName);
 
     if (typeof field.get === 'function') {
       return field.get.call(this, {
         model:  this,
+        self:   this,
         set:    this.setDataValue.bind(this, fieldName),
         get:    this.getDataValue.bind(this, fieldName),
         value,
@@ -2163,11 +2162,12 @@ class Model {
   ///     The name of the field whose value we wish to get.
   ///   field: <see>Field</see>
   ///     The field definition itself for the value we wish to get.
-  /// See: Field.set
+  /// See: Field
   _setFieldValue(fieldName, field, value) {
     if (typeof field.set === 'function') {
       field.set.call(this, {
         model:  this,
+        self:   this,
         set:    this.setDataValue.bind(this, fieldName),
         get:    this.getDataValue.bind(this, fieldName),
         value,
@@ -2949,8 +2949,8 @@ class Model {
   }
 
   // eslint-disable-next-line no-unused-vars
-  [Symbol.for('nodejs.util.inspect.custom')](depth, inspectOptions, inspect) {
-    return inspect(this.toJSON(), inspectOptions);
+  [Symbol.for('nodejs.util.inspect.custom')]() {
+    return this.toJSON();
   }
 }
 

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

@@ -4,11 +4,61 @@ const Nife                = require('nife');
 const Type                = require('../type');
 const { AUTO_INCREMENT }  = require('../helpers/default-helpers');
 
+/// `BIGINT` type.
+///
+/// This represents a "big integer", or a 64+ bit integer
+/// in any underlying database.
+///
+/// By default, `BIGINT` will use the `number` primitive
+/// to store values in JavaScript client-side. This
+/// choice was made because the `number` primitive is
+/// more commonly dealt with, and its max storage
+/// capacity is the number `9,007,199,254,740,991`, which
+/// is generally far above and beyond what most databases
+/// will ever reach. However, you can pass the
+/// `{ strict: true }` argument to the constructor when
+/// defining the type, and in this case it will instead
+/// use JavaScript's [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
+/// type to store this value client-side.
+///
+/// Example:
+///   class Numbers extends Model {
+///     static fields = {
+///       number1: Types.BIGINT(8, { strict: true }),
+///       number2: new Types.BigIntType(8, { strict: true }),
+///       autoIncrementing: {
+///         type: Types.BIGINT,
+///         defaultValue: Types.BIGINT.Default.AUTO_INCREMENT,
+///       },
+///     };
+///   }
+///
+/// Note:
+///   SQLite currently doesn't support 64bit auto-incrementing
+///   IDs (except on the primary key itself). For this reason,
+///   Mythix ORM supports emulation of BIGINT auto-incrementing
+///   IDs in its [mythix-orm-sqlite](https://www.npmjs.com/package/mythix-orm-sqlite)
+///   driver. You can read more about it in the documentation.
+/// 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 BigIntType 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 `'BIGINT'`
   static getDisplayName() {
     return 'BIGINT';
   }
@@ -17,6 +67,31 @@ class BigIntType 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.
+  ///
+  /// The "options" argument can be used to specify
+  /// if this BIGINT type should be in "strict" mode.
+  /// "strict" mode simply means that the client-side
+  /// storage for the field's value (in JavaScript)
+  /// will actually be a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) type.
+  /// By default, the underlying field value is stored
+  /// as a `number` primitive.
+  ///
+  /// Return: BigIntType
+  /// Arguments:
+  ///   length?: number = 8
+  ///     How many bytes to use in the underlying database to store the value.
+  ///   options?: object
+  ///     Only possible option is `{ strict: true }`, which will change the
+  ///     underlying field to use [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
+  ///     for value storage.
   constructor(length, _options) {
     let options = _options || {};
 
@@ -34,6 +109,23 @@ class BigIntType extends Type {
     });
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, either a
+  /// `number` primitive, or a `BigInt` if in
+  /// "strict" mode. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: number | BigInt | 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;
@@ -45,10 +137,41 @@ class BigIntType extends Type {
     return Number(castValue).valueOf();
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a `number` or a BigInt 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', 'bigint') && 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 `'BIGINT'` or
+  /// `'BIGINT(${this.length})'` if a `length` is provided to
+  /// the type.
+  ///
+  /// 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)