mythix-orm 1.11.6 → 1.12.0

package/lib/connection/literals/distinct-literal.js

@@ -2,7 +2,78 @@
 
 const LiteralFieldBase = require('./literal-field-base');
 
+/// Define a "distinct" literal for the underlying database.
+///
+/// Literals are special types in Mythix ORM that are used to
+/// define "literal values" for the underlying database.
+///
+/// This literal defines a "distinct" operation across a single
+/// column, or entire rows. Distinct is a little different than
+/// most other literals. Whereas most other literals are simply
+/// used as "values"--either identifiers, methods, or values--this
+/// `DistinctLiteral` defines an entire state for a query. It can modify
+/// the projection, the order, or modify the query in other ways. On
+/// some database drivers, it may cause the engine to take an entirely
+/// different path to fetch the data requested. `DistinctLiteral` requires
+/// a field, or another literal. It may or may not use this field in
+/// underlying database operations. However, to remain
+/// consistent in the interface and across databases, it is required.
+/// There are some cases in which a `DistinctLiteral` may not alter how
+/// a query is carried out. One of these is if it is used as an argument to another
+/// literal. For example, if one were to use a `DistinctLiteral` inside a
+/// `CountLiteral`, then it would count distinctly across rows, not modify how the
+/// query is carried out: `new CountLiteral(new DistinctLiteral('User:id'))`.
+///
+/// There are two primary ways to access literals in Mythix ORM. The
+/// first is to simply import them. The second way literals can be
+/// accessed is via the connection class itself. All Mythix ORM connection
+/// classes export all literals on the `static Literals` attribute of
+/// the class. So for example, you could access literals like `SQLiteConnection.Literals.DistinctLiteral`.
+///
+/// All built-in Mythix ORM literals--except `Literal` and `LiteralBase`--accept a field
+/// as their first argument. This field can be a fully qualified field name, an actual
+/// <see>Field</see> instance, or another literal. The second argument to all literal constructors
+/// is an `options` object, that generally contains connection-specific (and operation-specific) options...
+/// however, there are common options that can be supplied, such as `as: string;` which allows you to
+/// define an alias for the defined field, and `noProjectionAliases: boolean;`, which allows you to disable
+/// the column alias entirely.
+///
+/// Note:
+///   The `DistinctLiteral` is rarely used directly. Normally you would want to
+///   call `query.DISTINCT` instead, which internally uses this literal.
+///
+/// Example:
+///   const { Literals } = require('mythix-orm');
+///   const { SQLiteConnection } = require('mythix-orm-sqlite');
+///   let literal1 = new Literals.DistinctLiteral('User:firstName');
+///   let literal2 = new SQLiteConnection.Literals.DistinctLiteral('User:firstName');
+///
+/// See: LiteralFieldBase
+///
+/// See: LiteralBase
 class DistinctLiteral extends LiteralFieldBase {
+  /// Convert this literal to a string to be used in a database query.
+  ///
+  /// This method proxies the conversion of this literal to the connection
+  /// by calling <see>Connection.literalToString</see>. If no connection
+  /// is provided when this is called, then the literal will be converted
+  /// to a string representing it for debugging, i.e. `'CountLiteral {}'`.
+  ///
+  /// Note:
+  ///   Ultimately, for most connections, this will end up calling
+  ///   <see>QueryGenerator._distinctLiteralToString</see>.
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     The connection to use to stringify this literal. If none is provided,
+  ///     then a string representing this object will be returned instead.
+  ///   options?: object
+  ///     A connection and operation specific set of options that can be provided.
+  ///     This might for example be `{ as: 'name' }` to provided a field alias, or
+  ///     `{ isProjection: true }` to define that this is being stringified for use
+  ///     as a field in the query projection. Normally the end-user won't care about
+  ///     any literal options, except `as`, which is commonly used to give your literal
+  ///     an alias.
   toString(connection, options) {
     if (!connection)
       return `${this.constructor.name} {}`;

package/lib/connection/literals/field-literal.js

@@ -2,7 +2,61 @@
 
 const LiteralFieldBase = require('./literal-field-base');
 
+/// Define a "field" literal for the underlying database.
+///
+/// Literals are special types in Mythix ORM that are used to
+/// define "literal values" for the underlying database.
+///
+/// This literal defines a "field" in the underlying database.
+/// It could for example be used in a projection, an `ORDER`,
+/// or a `GROUP BY` clause.
+///
+/// There are two primary ways to access literals in Mythix ORM. The
+/// first is to simply import them. The second way literals can be
+/// accessed is via the connection class itself. All Mythix ORM connection
+/// classes export all literals on the `static Literals` attribute of
+/// the class. So for example, you could access literals like `SQLiteConnection.Literals.FieldLiteral`.
+///
+/// All built-in Mythix ORM literals--except `Literal` and `LiteralBase`--accept a field
+/// as their first argument. This field can be a fully qualified field name, an actual
+/// <see>Field</see> instance, or another literal. The second argument to all literal constructors
+/// is an `options` object, that generally contains connection-specific (and operation-specific) options...
+/// however, there are common options that can be supplied, such as `as: string;` which allows you to
+/// define an alias for the defined field, and `noProjectionAliases: boolean;`, which allows you to disable
+/// the column alias entirely.
+///
+/// Example:
+///   const { Literals } = require('mythix-orm');
+///   const { SQLiteConnection } = require('mythix-orm-sqlite');
+///   let literal1 = new Literals.FieldLiteral('User:age');
+///   let literal2 = new SQLiteConnection.Literals.FieldLiteral('User:age');
+///
+/// See: LiteralFieldBase
+///
+/// See: LiteralBase
 class FieldLiteral extends LiteralFieldBase {
+  /// Convert this literal to a string to be used in a database query.
+  ///
+  /// This method proxies the conversion of this literal to the connection
+  /// by calling <see>Connection.literalToString</see>. If no connection
+  /// is provided when this is called, then the literal will be converted
+  /// to a string representing it for debugging, i.e. `'FieldLiteral {}'`.
+  ///
+  /// Note:
+  ///   Ultimately, for most connections, this will end up calling
+  ///   <see>QueryGenerator._fieldLiteralToString</see>.
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     The connection to use to stringify this literal. If none is provided,
+  ///     then a string representing this object will be returned instead.
+  ///   options?: object
+  ///     A connection and operation specific set of options that can be provided.
+  ///     This might for example be `{ as: 'name' }` to provided a field alias, or
+  ///     `{ isProjection: true }` to define that this is being stringified for use
+  ///     as a field in the query projection. Normally the end-user won't care about
+  ///     any literal options, except `as`, which is commonly used to give your literal
+  ///     an alias.
   toString(connection, options) {
     if (!connection)
       return `${this.constructor.name} {}`;

package/lib/connection/literals/literal-base.d.ts

@@ -9,6 +9,7 @@ declare class LiteralBase {
   public static isLiteralClass(value: any): boolean;
   public static isLiteral(value: any): boolean;
   public static isLiteralType(value: any): boolean;
+  public static isAggregate(): boolean;
 
   public constructor(literal: any, options?: GenericObject);
   public fullyQualifiedNameToDefinition(fullyQualifiedName: LiteralBase | string | Field): LiteralBase | FullyQualifiedFieldDefinition;

package/lib/connection/literals/literal-base.js

@@ -3,9 +3,46 @@
 const ModelUtils = require('../../utils/model-utils');
 const Field = require('../../field');
 
+/// `LiteralBase` is the class all other literals inherit from.
+///
+/// Literals are special types in Mythix ORM that are used to
+/// define "literal values" for the underlying database.
+///
+/// This literal--being the top most ancestor of all other literals--
+/// defines common behavior for literals.
+///
+/// See: AverageLiteral
+///
+/// See: CountLiteral
+///
+/// See: DistinctLiteral
+///
+/// See: FieldLiteral
+///
+/// See: Literal
+///
+/// See: MaxLiteral
+///
+/// See: MinLiteral
+///
+/// See: SumLiteral
+///
 class LiteralBase {
+  /// Assist with type-checking
   static _isMythixLiteral = true;
 
+  /// Use this method to check if a class
+  /// is a Mythix ORM Literal. It will return
+  /// `true` if the provided value is a class
+  /// that inherits from <see>LiteralBase</see>, or
+  /// if the provided value has an attribute
+  /// named `_isMythixLiteral` that is truthy.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: Function
+  ///     Value to check.
   static isLiteralClass(value) {
     if (!value)
       return false;
@@ -19,6 +56,25 @@ class LiteralBase {
     return false;
   }
 
+  /// Check to see if the provided value is
+  /// an *instance* of a Mythix ORM <see>LiteralBase</see>.
+  /// Unlike <see>LiteralBase.static isLiteralClass</see>, which
+  /// checks if a *class* is a <see>LiteralBase</see>, this will check
+  /// to see if an *instance* is an instance of a
+  /// Mythix ORM <see>LiteralBase</see>. It will return
+  /// `true` if the provided value is an `instanceof`
+  /// <see>LiteralBase</see>, or if the value's `constructor`
+  /// property has a truthy `_isMythixLiteral` property
+  /// (`value.constructor._isMythixLiteral`)
+  ///
+  /// Note:
+  ///   This method is also a matching instance method.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     Value to check
   static isLiteral(value) {
     if (!value)
       return false;
@@ -39,10 +95,49 @@ class LiteralBase {
     return this.constructor.isLiteral(value);
   }
 
+  /// Check to see if the provided value is
+  /// an *instance* of *`this`* literal type.
+  /// Unlike <see>LiteralBase.static isLiteral</see>, which
+  /// checks if an *instance* is any <see>LiteralBase</see>
+  /// type, this will check if the provided literal is
+  /// exactly *`this`* type of literal. It will return
+  /// `true` if the provided value is an `instanceof`
+  /// `this` literal class, or if the value's `constructor`
+  /// property has a name that is equal to `this` literal's
+  /// class name.
+  /// (`value.constructor.name === this.name`)
+  ///
+  /// Example:
+  ///   console.log(CountLiteral.isLiteralType(new AverageLiteral('User:age')))
+  ///   // false
+  ///
+  ///   console.log(CountLiteral.isLiteralType(new CountLiteral('*')))
+  ///   // true
+  ///
+  /// Note:
+  ///   This method is also a matching instance method.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     Value to check
   static isLiteralType(value) {
+    if (value && value instanceof this)
+      return true;
+
     return (this.isLiteral(value) && value.constructor && value.constructor.name === this.name);
   }
 
+  /// Used internally in the engine to know if
+  /// a literal being operated upon is an aggregating
+  /// literal or not.
+  ///
+  /// Note:
+  ///   This method is also a matching instance method.
+  ///
+  /// Return: boolean
+  ///   Return `true`, informing the caller that this literal is used for aggregate operations.
   static isAggregate() {
     return false;
   }
@@ -51,6 +146,13 @@ class LiteralBase {
     return this.constructor.isAggregate();
   }
 
+  /// Construct a new literal.
+  ///
+  /// Arguments:
+  ///   literal: string
+  ///     The literal value you wish to insert into the query.
+  ///   options?: object
+  ///     Literal, connection, and operation specific options.
   constructor(literal, options) {
     Object.defineProperties(this, {
       'literal': {
@@ -68,6 +170,17 @@ class LiteralBase {
     });
   }
 
+  /// Take the value provided as either a <see>Field</see>
+  /// instance, or a fully qualified field name, then return the field
+  /// definition for it.
+  ///
+  /// If a literal is provided instead, then simply return the literal
+  /// without modifying it.
+  ///
+  /// Note:
+  ///   This is the inverse operation of <see>LiteralBase.definitionToField</see>
+  ///
+  /// See: ModelUtils.parseQualifiedName
   fullyQualifiedNameToDefinition(fullyQualifiedName) {
     if (LiteralBase.isLiteral(fullyQualifiedName))
       return fullyQualifiedName;
@@ -91,11 +204,21 @@ class LiteralBase {
     return definition;
   }
 
+  /// Take a field definition and return the actual <see>Field</see>
+  /// instance for it.
+  ///
+  /// If a literal is provided... or a value that isn't understood
+  /// (such as a string), then it is simply returned unmodified.
+  ///
+  /// Note:
+  ///   This is the inverse operation of <see>LiteralBase.fullyQualifiedNameToDefinition</see>
+  ///
+  /// See: ModelUtils.parseQualifiedName
   definitionToField(connection, definition) {
     if (LiteralBase.isLiteral(definition))
       return definition;
 
-    if (!definition.fieldNames)
+    if (!definition || !definition.fieldNames)
       return definition;
 
     let field = connection.getField(definition.fieldNames[0], definition.modelName);
@@ -117,10 +240,22 @@ class LiteralBase {
     return field;
   }
 
+  /// Convert the literal value provided to the `constructor`
+  /// to a string.
+  ///
+  /// Return: string
+  ///   The value provided to the `constructor` as a string.
   toString() {
-    return this.literal;
+    if (!this.literal)
+      return ('' + this.literal);
+
+    return this.literal.toString();
   }
 
+  /// Return the raw value provided to the `constructor`.
+  ///
+  /// Return: any
+  ///   The raw value provided to the `constructor`.
   valueOf() {
     return this.literal;
   }

package/lib/connection/literals/literal-field-base.js

@@ -3,11 +3,42 @@
 const Nife        = require('nife');
 const LiteralBase = require('./literal-base');
 
+/// LiteralFieldBase is the ancestor that all
+/// literals dealing with fields inherit from
+/// (which is nearly all literals). Its primary
+/// function is to enforce being provided fields
+/// when the child literal requires them, and to
+/// fetch those fields when the engine needs them.
+///
+/// See: LiteralBase
+///
+/// See: Literal
 class LiteralFieldBase extends LiteralBase {
+  /// This is provided so each child class
+  /// can overload it. By default it returns
+  /// `true`. However, any literal that inherits
+  /// from this literal may override it to instead
+  /// return `false`. The <see>CountLiteral</see>
+  /// does exactly this for example.
+  ///
+  /// Return: boolean
+  ///   Returns `true` by default, children can change the return value.
   static isFieldRequired() {
     return true;
   }
 
+  /// Construct a new field-based literal. The
+  /// first argument should be a fully qualified field name,
+  /// a <see>Field</see> instance, or another literal.
+  ///
+  /// Arguments:
+  ///   field: string | <see>Field</see> | <see>LiteralBase</see>
+  ///     The "field" that this literal is representing. If this is a
+  ///     string, then it is expected to be a fully qualified field name.
+  ///     If instead this is a <see>Field</see>, then that defines the
+  ///     field. Finally, this can also be another literal.
+  ///   options?: object
+  ///     Connection, Literal, and operation specific options for this literal.
   constructor(fullyQualifiedName, options) {
     super(undefined, options);
 
@@ -35,6 +66,15 @@ class LiteralFieldBase extends LiteralBase {
     });
   }
 
+  /// Get the fully qualified field name of the field
+  /// that this literal is representing.
+  ///
+  /// Return: string
+  ///   The fully qualified field name of the field this literal
+  ///   is representing. This would be the same field provided to the
+  ///   `constructor` when the literal was first created.
+  ///
+  /// See: ModelUtils.parseQualifiedName
   getFullyQualifiedFieldName() {
     let definition = this.definition || {};
     if (!definition.modelName || Nife.isEmpty(definition.fieldNames))
@@ -43,6 +83,12 @@ class LiteralFieldBase extends LiteralBase {
     return `${definition.modelName}:${definition.fieldNames[0]}`;
   }
 
+  /// Get the field represented by this literal.
+  ///
+  /// Return: <see>Field</see>
+  ///   The field that this literal is representing. This will
+  ///   be the field given to the `constructor` when the literal
+  ///   was first created.
   getField(connection) {
     if (!this.definition)
       return;
@@ -50,6 +96,10 @@ class LiteralFieldBase extends LiteralBase {
     return this.definitionToField(connection, this.definition);
   }
 
+  /// Return the raw field definition for
+  /// the provided field.
+  ///
+  /// See: ModelUtils.parseQualifiedName
   valueOf() {
     return this.definition;
   }

package/lib/connection/literals/literal.js

@@ -2,7 +2,22 @@
 
 const LiteralBase  = require('./literal-base');
 
+/// This literal type simply defines a pure "literal".
+/// It will represent any "raw" value you want to insert
+/// directly into any query. This can be useful for custom
+/// database operations, math, or anything else you need
+/// in "raw" form in the database.
+///
+/// Note:
+///   **Caution should be taken if using this for values. Values defined by this literal won't ever be escaped.**
 class Literal extends LiteralBase {
+  /// Construct a pure vanilla "literal" for the underlying database.
+  ///
+  /// Arguments:
+  ///   literal: any
+  ///     The literal value you want to stringify for the underlying database query engine.
+  ///   options?: object
+  ///     Connection, literal, and operation specific options.
   constructor(literal, options) {
     super(literal, options);
   }

package/lib/connection/literals/max-literal.js

@@ -2,11 +2,78 @@
 
 const LiteralFieldBase = require('./literal-field-base');
 
+/// Define an "average" literal for the underlying database.
+///
+/// Literals are special types in Mythix ORM that are used to
+/// define "literal values" for the underlying database.
+///
+/// This literal defines an "average" operation across a single
+/// column. It is used by <see>Connection.average</see> to get
+/// the average across all rows for a single column in the underlying
+/// database. When serialized using the <see>QueryGenerator</see>
+/// for the connection, it will turn into a database method that
+/// is appropriate for the underlying database. For example, with
+/// SQL type databases this would turn into `MAX(column)`. This is
+/// often used by the projection engine, to project it as a column
+/// to be selected. For example `SELECT MAX(column) ...`. It can
+/// be used in other places in the query however, such as `ORDER`,
+/// `GROUP BY`, and `HAVING` clauses.
+///
+/// There are two primary ways to access literals in Mythix ORM. The
+/// first is to simply import them. The second way literals can be
+/// accessed is via the connection class itself. All Mythix ORM connection
+/// classes export all literals on the `static Literals` attribute of
+/// the class. So for example, you could access literals like `SQLiteConnection.Literals.MaxLiteral`.
+///
+/// All built-in Mythix ORM literals--except `Literal` and `LiteralBase`--accept a field
+/// as their first argument. This field can be a fully qualified field name, an actual
+/// <see>Field</see> instance, or another literal. The second argument to all literal constructors
+/// is an `options` object, that generally contains connection-specific (and operation-specific) options...
+/// however, there are common options that can be supplied, such as `as: string;` which allows you to
+/// define an alias for the defined field, and `noProjectionAliases: boolean;`, which allows you to disable
+/// the column alias entirely.
+///
+/// Example:
+///   const { Literals } = require('mythix-orm');
+///   const { SQLiteConnection } = require('mythix-orm-sqlite');
+///   let literal1 = new Literals.MaxLiteral('User:age');
+///   let literal2 = new SQLiteConnection.Literals.MaxLiteral('User:age');
+///
+/// See: LiteralFieldBase
+///
+/// See: LiteralBase
 class MaxLiteral extends LiteralFieldBase {
+  /// Return `true`, letting the caller know that
+  /// this is an "aggregating literal".
+  ///
+  /// Return: boolean
+  ///   Return `true`, informing the caller that this literal is used for aggregate operations.
   static isAggregate() {
     return true;
   }
 
+  /// Convert this literal to a string to be used in a database query.
+  ///
+  /// This method proxies the conversion of this literal to the connection
+  /// by calling <see>Connection.literalToString</see>. If no connection
+  /// is provided when this is called, then the literal will be converted
+  /// to a string representing it for debugging, i.e. `'MaxLiteral {}'`.
+  ///
+  /// Note:
+  ///   Ultimately, for most connections, this will end up calling
+  ///   <see>QueryGenerator._maxLiteralToString</see>.
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     The connection to use to stringify this literal. If none is provided,
+  ///     then a string representing this object will be returned instead.
+  ///   options?: object
+  ///     A connection and operation specific set of options that can be provided.
+  ///     This might for example be `{ as: 'name' }` to provided a field alias, or
+  ///     `{ isProjection: true }` to define that this is being stringified for use
+  ///     as a field in the query projection. Normally the end-user won't care about
+  ///     any literal options, except `as`, which is commonly used to give your literal
+  ///     an alias.
   toString(connection, options) {
     if (!connection)
       return `${this.constructor.name} {}`;

package/lib/connection/literals/min-literal.js

@@ -2,11 +2,78 @@
 
 const LiteralFieldBase = require('./literal-field-base');
 
+/// Define an "average" literal for the underlying database.
+///
+/// Literals are special types in Mythix ORM that are used to
+/// define "literal values" for the underlying database.
+///
+/// This literal defines an "average" operation across a single
+/// column. It is used by <see>Connection.average</see> to get
+/// the average across all rows for a single column in the underlying
+/// database. When serialized using the <see>QueryGenerator</see>
+/// for the connection, it will turn into a database method that
+/// is appropriate for the underlying database. For example, with
+/// SQL type databases this would turn into `MIN(column)`. This is
+/// often used by the projection engine, to project it as a column
+/// to be selected. For example `SELECT MIN(column) ...`. It can
+/// be used in other places in the query however, such as `ORDER`,
+/// `GROUP BY`, and `HAVING` clauses.
+///
+/// There are two primary ways to access literals in Mythix ORM. The
+/// first is to simply import them. The second way literals can be
+/// accessed is via the connection class itself. All Mythix ORM connection
+/// classes export all literals on the `static Literals` attribute of
+/// the class. So for example, you could access literals like `SQLiteConnection.Literals.MinLiteral`.
+///
+/// All built-in Mythix ORM literals--except `Literal` and `LiteralBase`--accept a field
+/// as their first argument. This field can be a fully qualified field name, an actual
+/// <see>Field</see> instance, or another literal. The second argument to all literal constructors
+/// is an `options` object, that generally contains connection-specific (and operation-specific) options...
+/// however, there are common options that can be supplied, such as `as: string;` which allows you to
+/// define an alias for the defined field, and `noProjectionAliases: boolean;`, which allows you to disable
+/// the column alias entirely.
+///
+/// Example:
+///   const { Literals } = require('mythix-orm');
+///   const { SQLiteConnection } = require('mythix-orm-sqlite');
+///   let literal1 = new Literals.MinLiteral('User:age');
+///   let literal2 = new SQLiteConnection.Literals.MinLiteral('User:age');
+///
+/// See: LiteralFieldBase
+///
+/// See: LiteralBase
 class MinLiteral extends LiteralFieldBase {
+  /// Return `true`, letting the caller know that
+  /// this is an "aggregating literal".
+  ///
+  /// Return: boolean
+  ///   Return `true`, informing the caller that this literal is used for aggregate operations.
   static isAggregate() {
     return true;
   }
 
+  /// Convert this literal to a string to be used in a database query.
+  ///
+  /// This method proxies the conversion of this literal to the connection
+  /// by calling <see>Connection.literalToString</see>. If no connection
+  /// is provided when this is called, then the literal will be converted
+  /// to a string representing it for debugging, i.e. `'MinLiteral {}'`.
+  ///
+  /// Note:
+  ///   Ultimately, for most connections, this will end up calling
+  ///   <see>QueryGenerator._minLiteralToString</see>.
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     The connection to use to stringify this literal. If none is provided,
+  ///     then a string representing this object will be returned instead.
+  ///   options?: object
+  ///     A connection and operation specific set of options that can be provided.
+  ///     This might for example be `{ as: 'name' }` to provided a field alias, or
+  ///     `{ isProjection: true }` to define that this is being stringified for use
+  ///     as a field in the query projection. Normally the end-user won't care about
+  ///     any literal options, except `as`, which is commonly used to give your literal
+  ///     an alias.
   toString(connection, options) {
     if (!connection)
       return `${this.constructor.name} {}`;