mythix-orm 1.5.6 → 1.6.2

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

@@ -3,15 +3,74 @@
 const Nife  = require('nife');
 const Type  = require('../type');
 
+/// `REAL` type.
+/// Also known as `FLOAT`, or `DOUBLE` in some databases.
+///
+/// This represents a "real" number of low precision and
+/// accuracy in the underlying database driver. Unlike the
+/// <see>NumericType</see>, which is high precision, this
+/// type can suffer from rounding errors, and won't be as
+/// precise <see>NumericType</see>.
+///
+/// The `length` argument is the total number of bytes needed
+/// to store the underlying value. If `4`, then this will generally
+/// be a `FLOAT` or equivalent type in the underlying database driver.
+/// If `8`, then it will generally be a `DOUBLE` or equivalent type.
+/// The `scale` argument 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 Real extends Model {
+///     static fields = {
+///       real1: Types.REAL(4, 6),  // FLOAT
+///       real2: Types.REAL(8, 6),  // DOUBLE
+///       real3: Types.REAL,        // FLOAT (default)
+///     };
+///   }
+///
+/// See: Type
 class RealType 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 `'REAL'`
   static getDisplayName() {
     return 'REAL';
   }
 
-  getDisplayName() {
-    return this.constructor.getDisplayName();
-  }
-
+  /// Construct a new `REAL` type.
+  ///
+  /// The `length` argument specifies the total number of
+  /// bytes needed to store this value (default = `4`).
+  /// The `scale` argument specifies the number of digits
+  /// desired after the decimal place. A `scale` of `0` is valid,
+  /// meaning you want no digits after the decimal point.
+  /// Note that this is dependant on database driver support.
+  ///
+  /// Return: RealType
+  ///
+  /// Arguments:
+  ///   length?: number = 4
+  ///     The number of bytes needed to store the value. Use `4`
+  ///     to end up with a `FLOAT` on most database drivers, or
+  ///     `8` for a `DOUBLE`.
+  ///   scale?: number = 6
+  ///     How many digits are desired 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. This
+  ///     depends on the underlying database to support it.
   constructor(length, scale) {
     super(length, scale);
 
@@ -19,6 +78,23 @@ class RealType extends Type {
     this.scale = scale;
   }
 
+  /// 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;
@@ -30,10 +106,41 @@ class RealType 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 `'FLOAT'`.
+  ///
+  /// 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/serialized-type.d.ts

@@ -0,0 +1,25 @@
+import ConnectionBase from '../../connection/connection-base';
+import Type, { CheckDirtyContext, TypeWrapper } from '../type';
+
+export declare interface SerializedTypeWrapper extends TypeWrapper<SerializedType> {
+  (options: Type | SerializedTypeOptions): SerializedType;
+}
+
+interface SerializeCallContext {
+  value: any;
+  connection: ConnectionBase | undefined;
+}
+
+export declare interface SerializedTypeOptions {
+  type: Type;
+  serialize?: (context: SerializeCallContext) => any;
+  deserialize?: (context: SerializeCallContext) => any;
+  isDirty?: (context: CheckDirtyContext) => any;
+}
+
+export declare class SerializedType extends Type {
+  public constructor(options: Type | SerializedTypeOptions);
+  public getOptions(): SerializedTypeOptions;
+}
+
+export const SERIALIZED: SerializedTypeWrapper;

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

@@ -2,15 +2,108 @@
 
 const Type = require('../type');
 
+/// A field type that serializes and deserializes raw objects.
+///
+/// The `SERIALIZED` type can be used to serialize
+/// other data into a single field value. By default this
+/// field type is configured to serialize `JSON`.
+/// However, it can be configured to serialize and
+/// deserialize in any encoding you desire.
+///
+/// Something important to note right up front is that
+/// this type hooks into the model instance's "dirty" system,
+/// and will call your provided `serialize` and `deserialize`
+/// methods to check if your object has *internally* become
+/// dirty. For example, if you use this type for a field called
+/// `metadata` on your `User` model, and you have an instance
+/// of that user model you are working with, and you *internally*
+/// change the `metadata` field like so `user.metadata.class = 'wizard';`
+/// then this field type will detect that the `metadata` attribute
+/// of your model is "dirty" by serializing the `metadata` value
+/// and comparing it to the "undirty" serialized value, even if
+/// the actual value of the `metadata` field itself hasn't changed.
+/// For this reason it is important that your serializer sort
+/// the serialized data if possible. If sorting isn't possible,
+/// then the side-effect will be that this field may be serialized
+/// and stored more often than actually needed. This system was
+/// designed this way because it is likely better to get a false
+/// positive and save your data, then not check at all and lose data.
+/// If needed, you can always create your own child type of
+/// `SerializedType`, and overload the `isDirty` method, or provided
+/// an `isDirty` method to the field `options` to check
+/// for dirtiness yourself, based on what makes sense with your
+/// serializing algorithm.
+///
+/// See: Type
 class SerializedType 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 `'SERIALIZED'`
   static getDisplayName() {
     return 'SERIALIZED';
   }
 
-  getDisplayName() {
-    return this.constructor.getDisplayName();
-  }
-
+  /// Construct a new instance of the `SerializedType` type.
+  ///
+  /// Interface:
+  ///   interface SerializeCallContext {
+  ///     // The value to serialize or deserialize
+  ///     value: any;
+  ///
+  ///     // The database driver connection.
+  ///     connection: Connection;
+  ///   }
+  ///
+  /// Interface:
+  ///   interface SerializedTypeOptions {
+  ///     // Method to serialize data. Note how the
+  ///     // return type is `any`. Though commonly an
+  ///     // underlying `STRING` type will be used for
+  ///     // the field value, that isn't a requirement.
+  ///     // For example, you might want to encode a bitmask
+  ///     // into a `BIGINT`. The world is your oyster.
+  ///     //
+  ///     // Unlike other fields, `null` and `undefined` are
+  ///     // not simply returned. They are left up to the
+  ///     // serializer and deserializer to handle and do
+  ///     // with as they want. For this reason, you need
+  ///     // to properly handle `null` and `undefined` values,
+  ///     // even if you just return them (allowing the underlying
+  ///     // database field to contain a `NULL` value).
+  ///     serialize?: (context: SerializeCallContext) => any;
+  ///
+  ///     // Deserialize the data provided.
+  ///     deserialize?: (context: SerializeCallContext) => any;
+  ///
+  ///     // The underlying storage type of this field. This will
+  ///     // commonly be a `STRING` of some larger size, but isn't
+  ///     // required to be. It can be any type that works for your
+  ///     // serializer and deserializer.
+  ///     type: Type;
+  ///
+  ///     // Provide your own method to detect
+  ///     // "dirtiness" of the field's value
+  ///     // See the "isDirty" method of this
+  ///     // class for more information.
+  ///     isDirty?: (context: CheckDirtyContext) => any;
+  ///   }
+  ///
+  /// Return: SerializedType
+  ///
+  /// Arguments:
+  ///   options?: Type | SerializedTypeOptions
+  ///     If this is a `Type`, then it will specify
+  ///     the underlying field type that will store
+  ///     the serialized value, and is the same as
+  ///     specifying the `{ type: Type }` option.
   constructor(_options) {
     let options = _options;
     if (Type.isTypeClass(options) || Type.isType(options))
@@ -42,26 +135,97 @@ class SerializedType extends Type {
     Object.defineProperties(this, {
       'options': {
         writable:     true,
-        enumberable:  false,
+        enumerable:   false,
         configurable: true,
         value:        options,
       },
     });
   }
 
+  /// Get the options passed to the field
+  /// when it was defined.
+  ///
+  /// Return: object
+  ///   The options object provided to the field.
   getOptions() {
     return this.options;
   }
 
+  /// Call initialize on the underling type
+  /// field.
+  ///
+  /// See: Type.initialize
   initialize(connection, self) {
     let options = this.getOptions();
     options.type.initialize(connection, self);
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value by calling
+  /// <see>SerializedType.deserialize</see> on the type with the provided
+  /// value. If <see>SerializedType.deserialize</see> detects that the type
+  /// is the same as the underlying storage type (i.e.
+  /// `STRING`), then it will deserialize and return the
+  /// value. However, if the provided value is not the
+  /// type of the underlying storage field type, and the
+  /// value is not `null` or `undefined`, then it will
+  /// be assumed to already be deserialized and will be
+  /// simply returned.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: any | null | undefined
+  ///   Return the incoming `value`, cast to this
+  ///   type (deserialized). `null` and `undefined` are simply
+  ///   returned without casting by the default built-in JSON
+  ///   deserializer... however, they may be treated differently
+  ///   for other serializers.
+  ///
+  /// Arguments:
+  ///   context: <see name="CastToTypeContext">Type.castToType</see>
   castToType({ value, connection }) {
     return this.deserialize(value, connection);
   }
 
+  /// This is called whenever the model's field
+  /// owning this type is changed. This method
+  /// will update the "dirty" serialized cache
+  /// contained on the model for this type. This
+  /// is later used to see if the field value is
+  /// dirty because any of the internal data of
+  /// the field value has changed (via a serialize
+  /// call that compares the value to last serialize).
+  ///
+  /// In short, this updates the last serialize cache
+  /// to compare it with a serialize on insert/update
+  /// to see if the serialized data is "dirty".
+  ///
+  /// Interface:
+  ///   interface SetFieldValueContext {
+  ///     // The field value that was just set onto the field.
+  ///     value: any;
+  ///
+  ///     // The field that contains this type
+  ///     field: Field;
+  ///
+  ///     // The name of the field that contains this type
+  ///     fieldName: string;
+  ///
+  ///     // The model instance itself
+  ///     self: Model;
+  ///   }
+  ///
+  /// Note:
+  ///   Because type instances for fields are shared across model
+  ///   instances, the actual "dirty" cache is stored on the model
+  ///   itself in a `_typeData` property on the model instance.
+  ///
+  /// Return: undefined
+  ///
+  /// Arguments:
+  ///   context: SetFieldValueContext
   onSetFieldValue({ value, fieldName, self }) {
     // we make a copy here
     // so that when the value is modified
@@ -70,6 +234,42 @@ class SerializedType extends Type {
     self._typeData[fieldName] = clonedValue;
   }
 
+  /// Check if this field is dirty, including if
+  /// the object value stored on the field has changed
+  /// since the last persist.
+  ///
+  /// This compares the current value of the field
+  /// to the last persisted value by serializing the
+  /// field's value and comparing it to the last serialized
+  /// value when the field was persisted/loaded.
+  ///
+  /// Interface:
+  ///   interface CheckDirtyContext {
+  ///     // The current field value to check.
+  ///     value: any;
+  ///
+  ///     // The field that contains this type
+  ///     field: Field;
+  ///
+  ///     // The name of the field that contains this type
+  ///     fieldName: string;
+  ///
+  ///     // The model instance itself
+  ///     self: Model;
+  ///
+  ///     // The underlying database connection
+  ///     // that is attempting to insert or update
+  ///     // this field
+  ///     connection: Connection;
+  ///   }
+  ///
+  /// Return: any
+  ///   If `undefined` is returned, then this field is not considered
+  ///   dirty. If any other value is returned, then that will be used
+  ///   as the "dirty" value for the field.
+  ///
+  /// Arguments:
+  ///   context: CheckDirtyContext
   isDirty(context) {
     let options = this.getOptions();
     if (typeof options.isDirty === 'function')
@@ -84,10 +284,38 @@ class SerializedType extends Type {
       return value;
   }
 
+  /// Validate the underlying field value.
+  /// For the `SerializedType` this simply
+  /// always returns `true`.
+  ///
+  /// Return: boolean
+  ///   Always return `true`.
   isValidValue() {
     return true;
   }
 
+  /// Serialize the field's value, and
+  /// return the serialized result.
+  ///
+  /// Note that if no `connection` is provided
+  /// the current field's value is simply returned.
+  /// This is because it is assumed that serializing
+  /// will only be happening when the database driver
+  /// connection requests it, otherwise you likely
+  /// just want the raw value of the field.
+  ///
+  /// Return: any
+  ///   The underlying field's value if no `connection`
+  ///   argument was provided, or the serialized result
+  ///   if a `connection` argument was provided.
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to serialize. If no `connection` argument
+  ///     is provided, then this value will simply be returned.
+  ///   connection?: <see>Connection</see>
+  ///     The database driver connection requesting that this
+  ///     field's value be serialized for storage.
   serialize(value, connection) {
     if (!connection)
       return value;
@@ -101,6 +329,41 @@ class SerializedType extends Type {
     return options.serialize({ value, connection });
   }
 
+  /// Deserialize the field's value, and
+  /// return the deserialized result.
+  ///
+  /// This is called any time `castToType`
+  /// is called. If the value provided is
+  /// not the same type as the underlying
+  /// storage type (i.e. `STRING`), and the
+  /// value is also not `null` or `undefined`,
+  /// then the value is simply returned. This
+  /// is because it is assumed if the value
+  /// isn't of the same type as storage
+  /// (i.e. `string` type), then it is already
+  /// deserialized, so will simply be returned.
+  /// `null` and `undefined` are handed directly
+  /// off to the provided `serialize` and `deserialize`
+  /// methods, so make sure your serializer can
+  /// properly handle these values (even if that
+  /// means simply returning them).
+  ///
+  /// Return: any
+  ///   The underlying field's value. If the value
+  ///   provided has a type that matches the underlying
+  ///   storage type (i.e. typeof value === 'string' && internalType === 'STRING')
+  ///   then the value will first be passed through the
+  ///   provided `deserialize` method before it is returned.
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to deserialize. If this is *not*
+  ///     the same type as the underlying storage type,
+  ///     and is also *not* `null` or `undefined`, then
+  ///     the value will simply be returned.
+  ///   connection?: <see>Connection</see>
+  ///     The database driver connection requesting that this
+  ///     field's value be deserialized (usually during load).
   deserialize(value, connection) {
     let options   = this.getOptions();
     let innerType = options.type;
@@ -111,6 +374,25 @@ class SerializedType extends Type {
     return options.deserialize({ value, connection });
   }
 
+  /// Stringify the type itself. **This will be
+  /// the type of the underlying storage 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 underlying storage 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 underlying storage field type.
   toString(connection) {
     let options   = this.getOptions();
     let innerType = options.type;

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

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

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

@@ -10,10 +10,6 @@ class StringType extends Type {
     return 'STRING';
   }
 
-  getDisplayName() {
-    return this.constructor.getDisplayName();
-  }
-
   constructor(length) {
     super(length);
 

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

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

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

@@ -10,10 +10,6 @@ class TextType extends Type {
     return 'TEXT';
   }
 
-  getDisplayName() {
-    return this.constructor.getDisplayName();
-  }
-
   constructor(length) {
     super(length);
 

package/lib/types/concrete/uuid-base.d.ts

@@ -0,0 +1,13 @@
+import Type from '../type';
+
+declare class UUIDBaseType extends Type {
+  getPrefix(options?: { prefix: string; }): string;
+  stripPrefix(value: string): { prefix: string; id: string };
+  addPrefix(value: string): string;
+  getBaseLength(): number;
+  getTotalLength(): number;
+  validateOptions(uuidArgs: Array<any>): void;
+  getArgsForUUID(options)
+}
+
+export default UUIDBaseType;

package/lib/types/concrete/uuid-base.js

@@ -12,7 +12,7 @@ class UUIDBaseType extends Type {
     Object.defineProperties(this, {
       'options': {
         writable:     true,
-        enumberable:  false,
+        enumerable:   false,
         configurable: true,
         value:        options,
       },
@@ -72,6 +72,9 @@ class UUIDBaseType extends Type {
       ? this.toConnectionType(connection)
       : `VARCHAR(${this.getTotalLength()})`;
   }
+
+  validateOptions() {
+  }
 }
 
 module.exports = UUIDBaseType;

package/lib/types/concrete/uuid-v1-type.d.ts

@@ -0,0 +1,31 @@
+import { DefaultValueProvider } from '../helpers/default-helpers';
+import { TypeWrapper } from '../type';
+import UUIDBaseType from './uuid-base';
+
+export declare interface UUIDV1TypeWrapper extends TypeWrapper<UUIDV1Type> {
+  (options?: UUIDV1TypeOptions): UUIDV1Type;
+}
+
+export declare interface UUIDV1TypeOptions {
+  prefix?: string;
+  node?: Array<number>;
+  clockseq?: number;
+  msecs?: number;
+  nsecs?: number;
+  random?: Array<number>;
+  rng?: () => Array<number>;
+  buffer?: Buffer;
+  offset?: number;
+}
+
+export declare class UUIDV1Type extends UUIDBaseType {
+  declare public static Default: {
+    UUIDV1: DefaultValueProvider;
+  }
+
+  constructor(options?: UUIDV1TypeOptions);
+  getOptions(): UUIDV1TypeOptions;
+  getArgsForUUID(options: UUIDV1TypeOptions): Array<any>;
+}
+
+export const UUIDV1: UUIDV1TypeWrapper;

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

@@ -27,10 +27,6 @@ class UUIDV1Type extends UUIDBaseType {
     return 'UUIDV1';
   }
 
-  getDisplayName() {
-    return this.constructor.getDisplayName();
-  }
-
   getArgsForUUID(options) {
     let uuidOptions = {};