mythix-orm 1.11.6 → 1.12.0

package/lib/connection/literals/sum-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 `SUM(column)`. This is
+/// often used by the projection engine, to project it as a column
+/// to be selected. For example `SELECT SUM(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.SumLiteral`.
+///
+/// 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.SumLiteral('User:age');
+///   let literal2 = new SQLiteConnection.Literals.SumLiteral('User:age');
+///
+/// See: LiteralFieldBase
+///
+/// See: LiteralBase
 class SumLiteral 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. `'SumLiteral {}'`.
+  ///
+  /// Note:
+  ///   Ultimately, for most connections, this will end up calling
+  ///   <see>QueryGenerator._sumLiteralToString</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/query-generator-base.js

@@ -2,8 +2,49 @@
 
 /// The base query generator class.
 ///
+/// A "query generator" is an interface that will take
+/// parameters (usually a <see>QueryEngine</see> or a
+/// <see>Model</see>) and generate database query statements
+/// from the input. For SQL type databases this would mean
+/// generating `SELECT`, `INSERT`, `UPDATE`, and `DELETE`
+/// statements, as well as generators for creating and altering
+/// tables, among other things.
+///
+/// The methods of this class are generally many, with the
+/// design pattern for most generators being that nearly
+/// all methods are split apart and added to the class, allowing
+/// by deliberate design much finer control when using overloaded
+/// methods, to modify or replace any parts of the generator.
+///
+/// Any connection can be provided a custom query generator
+/// interface via the `queryGenerator` option that can be
+/// used when instantiating a connection. Most connections
+/// will supply their own by default.
+///
+/// A connection should always be bound to a query generator
+/// instance. If not when first created, then at least when
+/// provided to a connection. The connection is a required
+/// part of the generator interface, and will do things, such
+/// as for example, escaping values and ids using the connection
+/// itself. The connection may be used for other operations as
+/// well.
+///
+/// Note:
+///   Some database drivers may not have a generator at all. Though
+///   database drivers commonly do have a database statement generator,
+///   a connection isn't required to have one.
+///
 /// Alias: QueryGenerator
 class QueryGeneratorBase {
+  /// Construct a new query generator
+  ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     The connection that this interface is for. Sometimes the connection
+  ///     isn't yet available when creating the query generator, so this argument
+  ///     is optional. When provided to a <see>Connection</see>, the connection
+  ///     will call <see>QueryGenerator.setConnection</see> with itself to set
+  ///     the connection for the query generator.
   constructor(connection) {
     Object.defineProperties(this, {
       'connection': {
@@ -15,57 +56,289 @@ class QueryGeneratorBase {
     });
   }
 
+  /// Get the <see>Connection</see> bound to this
+  /// query generator.
+  ///
+  /// Return: <see>Connection</see>
+  ///   The connection bound to this query generator. A connection
+  ///   should always be bound before any generating methods of
+  ///   the class are called.
+  getConnection() {
+    return this.connection;
+  }
+
+  /// Set the <see>Connection</see> bound to this
+  /// query generator.
+  ///
+  /// Arguments:
+  ///   connection: <see>Connection</see>
+  ///     The connection to bind to this query generator.
+  ///
+  /// Return: <see>QueryGenerator</see>
+  ///   Return `this` to allow for chaining.
+  setConnection(connection) {
+    this.connection = connection;
+    return this;
+  }
+
+  /// This call proxies to <see>Connection.stackAssign</see>.
+  /// Refer to the documentation of that method for more information.
+  ///
+  /// See: Connection.stackAssign
   stackAssign(obj, ...args) {
     return this.connection.stackAssign(obj, ...args);
   }
 
+  /// This call proxies to <see>Connection.escape</see>.
+  /// Refer to the documentation of that method for more information.
+  ///
+  /// See: Connection.escape
   escape(...args) {
     return this.connection.escape(...args);
   }
 
+  /// This call proxies to <see>Connection.escapeID</see>.
+  /// Refer to the documentation of that method for more information.
+  ///
+  /// See: Connection.escapeID
   escapeID(...args) {
     return this.connection.escapeID(...args);
   }
 
+  /// Convert an <see>AverageLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>AverageLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _averageLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_averageLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>CountLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>CountLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _countLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_countLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>DistinctLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>DistinctLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _distinctLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_distinctLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>FieldLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>FieldLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _fieldLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_fieldLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>MaxLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>MaxLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _maxLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_maxLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>MinLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>MinLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _minLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_minLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Convert an <see>SumLiteral</see> into a
+  /// string representation for the underlying database.
+  ///
+  /// It is expected that each database driver will implement
+  /// this method. By default it will simply throw an
+  /// "unsupported" error.
+  ///
+  /// Refer to the specific documentation for your database
+  /// driver for more information.
+  ///
+  /// Arguments:
+  ///   literal: <see>SumLiteral</see>
+  ///     The literal to stringify for the underlying database.
+  ///   options?: object
+  ///     Options for the stringify process. These are often database
+  ///     driver specific. However, one common option is the `as`
+  ///     option, which will allow you to give your literal an alias.
+  ///
+  /// Return: string
+  ///   The literal, converted into the proper string for the underlying
+  ///   database.
   // eslint-disable-next-line no-unused-vars
   _sumLiteralToString(literal, options) {
     throw new Error(`${this.constructor.name}::_sumLiteralToString: This operation is not supported for this connection type.`);
   }
 
+  /// Take a <see>QueryEngine</see> instance and
+  /// convert it into a query. For SQL type databases
+  /// this would turn a <see>QueryEngine</see> into a
+  /// `SELECT` statement. For other types of databases,
+  /// this should return a "fetch" query--or string representation
+  /// of such a query--in the database's native query language.
+  ///
+  /// Arguments:
+  ///   queryEngine: <see>QueryEngine</see>
+  ///     The query engine instance to stringify.
+  ///   options?: object
+  ///     Connection and operation specific options. These
+  ///     generally aren't needed, but are provided in case
+  ///     the underlying connection needs them.
+  ///
+  /// Return: string
+  ///   A "fetch" query in the databases native query language,
+  ///   generated from the provided `queryEngine`.
   // eslint-disable-next-line no-unused-vars
   toConnectionString(queryEngine, options) {
     return '<not supported by connection>';
   }
+
+  /// Get the "default value" for the given field
+  /// for the underlying database. This is used
+  /// primarily for "CREATE TABLE" statements.
+  ///
+  /// By default, the implementation of this method
+  /// is empty. It is expected that each database driver
+  /// will implement their own version of this method.
+  ///
+  /// Arguments:
+  ///   field: <see>Field</see>
+  ///     The field instance we are getting a "default value"
+  ///     from.
+  ///   fieldName: string
+  ///     The name of the field that we are getting the "default value"
+  ///     from. This should always be the same as `field.fieldName`.
+  ///   options?: object
+  ///     Options for the operation. These will likely be connection
+  ///     specific. Please refer to the documentation of your specific
+  ///     connection for more details.
+  ///
+  /// Return: any
+  ///   Though in most cases this method will return a string for
+  ///   most database drivers in most situations, it may return other
+  ///   types as well, such as literals, or other raw values.
+  ///   Please refer to the documentation of your specific
+  ///   connection for more details.
+  // eslint-disable-next-line no-unused-vars
+  getFieldDefaultValue(field, fieldName, _options) {
+  }
 }
 
 module.exports = QueryGeneratorBase;

package/lib/field.js

@@ -133,7 +133,7 @@
 ///    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
+///    the <see>Helpers.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)

package/lib/model.js

@@ -345,7 +345,7 @@ class Model {
   /// Just be cautious if you set a `connection` property, as you might overwrite any
   /// connection currently set on the context. Any properties you set here will be available
   /// in any child function calls (inside this context scope), and can be accessed via a
-  /// call to <see>Model.getModelContext</see>.
+  /// call to <see>Model.static getModelContext</see>.
   ///
   /// Note:
   ///   An `AsyncLocalStorage` context might not exist when this call is made,
@@ -381,7 +381,7 @@ class Model {
   /// This method will return a connection in the following
   /// order: 1) The provided `connection` argument, if supplied,
   /// 2) The `connection` property on the "model context" from
-  /// <see>Model.getModelContext</see> from `AsyncLocalStorage`,
+  /// <see>Model.static getModelContext</see> from `AsyncLocalStorage`,
   /// if one is available, and 3) Finally the bound connection, if
   /// available, which is found by searching the `static Model._mythixBoundConnection`
   /// property of the class.
@@ -677,6 +677,58 @@ class Model {
     return this.constructor.defaultScope(queryEngine);
   }
 
+  /// Finalize a query before using it for database operations.
+  ///
+  /// `finalizeQuery` is called on **every** query immediately
+  /// before it is used for a database operation. Its only purpose
+  /// is to potentially modify the query before the database operation
+  /// occurs. This can be extremely useful for things like "row level permissions",
+  /// or ensuring that a certain type of query always has certain conditions.
+  ///
+  /// Because it is asynchronous by design, it is possible to finalize the
+  /// query using other asynchronous operations; for example validating
+  /// authentication tokens, or fetching user roles from the database.
+  ///
+  /// This is called by <see>Connection.finalizeQuery</see> for each unique
+  /// model found in the query.
+  ///
+  /// Interface:
+  ///   interface FinalizeQueryContext {
+  ///     type: 'create' | 'read' | 'updated' | 'delete'; // The operation type that is about to happen in the underlying database.
+  ///     query: QueryEngine; // The query being operated upon. Modify and return this.
+  ///     queryDepth: number; // The depth we are at while walking the query. Will be 0 for root level, 1 for first sub-query, etc...
+  ///     operationIndex: number; // The "operation stack" index we are at
+  ///     operation: object; // The "operation" on the query operation stack we are working on
+  ///     operations: Array<object>; // The query "operation stack"
+  ///     parent: object | null; // The parent "operation"
+  ///     contextKey: string; // The name of the key that this query is a value of for this "operation" object. This is usually "value" for most operations, but it could be something else.
+  ///     options: object; // The options passed into the operation by the user
+  ///   }
+  ///
+  ///
+  /// Note:
+  ///   "With great power comes great responsibility." Use `finalizeQuery` intelligently. It can
+  ///   cause a noticeable performance hit, and can really make things hard to debug and
+  ///   understand if you don't clearly document.
+  ///
+  /// Note:
+  ///   `'create'` isn't actually currently supported, since no queries are
+  ///   ever used in an `INSERT` operation. It is reserved for future use.
+  ///
+  /// Arguments:
+  ///   context: FinalizeQueryContext
+  ///     All provided values in a single context. You will want to modify `query`
+  ///     and return it... or if you don't modify it, simply return it. The `contextKey`
+  ///     might be a little confusing. It is the name of the key the query is a value on.
+  ///     For example, in an `EQ` operation, this would be "value".
+  ///     i.e. an `EQ` operation looks something like the following on the operation stack:
+  ///     `{ operator: 'EQ', value: query }`. The reason it is provided is if you need to
+  ////    directly get or set a value on the operation frame (`operation`).
+  ///
+  /// Return: <see>QueryEngine</see>
+  ///   The query provided, possibly altered.
+  ///
+  /// See: Connection.finalizeQuery
   // eslint-disable-next-line no-unused-vars
   static finalizeQuery({ type, query, queryDepth, operationIndex, operation, operations, parent, contextKey, options }) {
     return query;