mythix-orm 1.11.6 → 1.12.0

package/README.md

@@ -1,15 +1,106 @@
 # mythix-orm
 
-ORM for Mythix framework
+Mythix ORM aims to replace Sequelize and the few other terrible solutions that the poor destitute Node community has to work with. Mythix ORM has been designed to replace all current ORMs for Node, with a focus on what is lacking in the community, namely good engineering, good documentation, and ease of use.
 
-Mythix ORM aims to replace Sequelize and the few other terrible solutions that the poor destitute Node community has to work with. Mythix ORM is not yet quite ready for prime time however, so please check back soon!
-
-What to expect while you are waiting:
-  1. Advanced, seamless, and powerful (yet simple) query engine that is easy to use, and works across database drivers, even for No-SQL databases. Here is a simple example to fetch users and their roles: `let users = await User.where.id.EQ(Role.where.userID).firstName.EQ('Mythix').lastName.EQ('ORM').Roles.name.EQ('superuser').PROJECT('User', 'Role').all();`
+Mythix ORMs feature set includes:
+  1. An advanced, seamless, and powerful (yet simple) query engine that is easy to use, and works across database drivers, even for No-SQL databases.
   2. Powerful model classes and helpers that don't violate good design patterns, stay out of your face, and have no undocumented auto-magic built in. The model system is also designed to work seamlessly across different databases, including No-SQL databases.
   3. Simple, clean, and slim... Mythix ORM isn't intended to be a sledge hammer, nor a 'batteries included' framework. Instead, it is designed to be a useful tool, and was designed to be easily extended. It can be used for large enterprise applications, or it can be used as a simple slim layer to interact with different databases in a human-friendly way.
-  4. Mythix ORM is modular by design. Instead of being a large bloated library that attempts to handle every database and every type of operation, it instead only provides exactly what you need. Mythix ORM is itself just a base connection, a query engine, and a model and type system. That is all. To interact with databases you can choose between any number of drivers for Mythix ORM, and can use community built plugins for adding features (or simply write your own!).
-  5. Mythix ORM is designed from the ground-up to be extended/modified. Want to change the nature of the Query Engine? Just extend from it and away you go! Want to change the way models behave? No problem! Want to make your own connection? Go for it! Want to add your own custom data types for models? Super easy. Every part of Mythix ORM is designed to be swapped out in a non-global way so that its feature set can be extended and added onto.
-  6. Has complete feature parity (and soon greater functionality) then all existing ORMs for Node. Model validation, hooks, model attributes and data types, model relations, support for multiple databases, an advanced query engine, transactions, transactions inside transactions, useful utility methods, an extensible type system, virtual types, an extensible query generator, support for older Node versions, support for multiple connections and multiplex connections (at the same time), and more!
+  4. A modular design. Instead of being a large bloated library that attempts to handle every database and every type of operation, it instead only provides exactly what you need. Mythix ORM is itself just a base connection, a query engine, and a model and type system. That is all. To interact with databases you can choose between any number of drivers for Mythix ORM (coming soon!), and can use community-built plugins for adding features (or simply write your own!).
+  5. A deliberate design to be extended and added onto. Easily modify the Query Engine to add more features, create your own database driver, modify how models behave, or add your own custom data types. The sky is the limit!
+  6. Complete feature parity (and soon greater functionality) then all existing ORMs for Node. Model validation, hooks, model attributes and data types, model relations, support for multiple databases, an advanced query engine, transactions, transactions inside transactions, useful utility methods, an extensible type system, virtual types, an extensible query generator, support for older Node versions, support for multiple connections and multiplex connections (at the same time), and more!
+
+Mythix ORM is still in its very early stages, and is looking for users! It is stable, and currently has native support for SQLite and PostgreSQL. A mongo driver will be added next, and after that MySQL. If you want to help then drop me a line! All help is welcome.
+
+## Install
+
+```bash
+npm i --save mythix-orm mythix-orm-sqlite
+```
+
+## Documentation
+
+Check out the [WIKI](https://github.com/th317erd/mythix-orm/wiki) for documentation.
+
+## Getting started
+
+Just start creating models!
+
+```javascript
+const { Model, Types }  = require('mythix-orm');
+const SQLiteConnection  = require('mythix-orm-sqlite');
+
+class User extends Model {
+  static fields = {
+    id: {
+      type: Types.XID(),
+      defaultValue: Types.XID.Defaults.XID,
+      allowNull: false,
+      primaryKey: true,
+    },
+    email: {
+      type: Types.STRING(128),
+      allowNull: false,
+      index: true,
+      unique: true,
+    },
+    firstName: {
+      type: Types.STRING(64),
+      allowNull: false,
+      index: true,
+    },
+    lastName: {
+      type: Types.STRING(64),
+      allowNull: false,
+      index: true,
+    },
+  };
+}
+
+// Entry point
+(async function() {
+  // Define a connection, and "bind" our models to it
+  let connection = new SQLiteConnection({
+    models: [
+      User,
+    ],
+  });
+
+  // Fire up our connection
+  await connection.start();
+
+  // Create our tables needed for our User
+  // model in SQLite
+  await connection.createTables([ User ]);
+
+  // Now we can store and load a user
+  let user = new User({
+    email: 'test@example.com',
+    firstName: 'Test',
+    lastName: 'User',
+  });
+
+  // Store user
+  await user.save();
+
+  // Reload user by querying on the
+  // user's email address
+  user = await User.where.email.EQ('test@example.com').first();
+
+  // Serialize to JSON
+  console.log('My user: ', JSON.stringify(user, undefined, 2));
+
+  // Shutdown our connection
+  await connection.stop();
+})();
+```
+
+## Notes
+
+1. The [WIKI](https://github.com/th317erd/mythix-orm/wiki) is still being worked on. Most of the documentation is complete, but there is still a lot more to write. Documentation is the main focus right now. There is a lot more to write. If you have any questions, feel free to drop a line, or open an issue! We will be happy to answer any questions. We aren't "done" until our documentation is pristine.
+2. Right now there are only database drivers for [SQLite](https://www.npmjs.com/package/mythix-orm-sqlite) and [PostgreSQL](https://www.npmjs.com/package/mythix-orm-postgresql). More are planned, with a Mongo driver likely to land next, followed by MySQL. Help wanted!
+3. Check out the [Mythix](https://www.npmjs.com/package/mythix) web-app framework. It is also still in active development, and the documentation is poor (to say the least), but it is up and coming, and will soon have fantastic documentation, and even though still in active development is fully functional. To get started try `npx mythix-cli create 'Test App'`
+
+## Goals
 
-Stay tuned! Mythix ORM should be released and fully documented by Q1 of 2023!
+The `Mythix` suite of technologies are being developed to give a rock-solid full-stack to build web-apps on Node. I got tired of the piecemeal garbage that currently exist in the Node ecosystem for building apps. My end goal is to have `Mythix` technologies take the Node community by storm, providing top-notch technologies for developers to create amazing things. Get involved with me, and let's change the world for the better!

package/lib/connection/connection-base.js

@@ -3,7 +3,6 @@
 const { DateTime }          = require('luxon');
 const EventEmitter          = require('events');
 const Nife                  = require('nife');
-const SqlString             = require('sqlstring');
 const { QueryEngine }       = require('../query-engine');
 const Utils                 = require('../utils');
 const { Model: ModelBase }  = require('../model');
@@ -230,6 +229,8 @@ class ConnectionBase extends EventEmitter {
 
     if (!options.queryGenerator)
       options.queryGenerator = this.createQueryGenerator(options);
+    else
+      options.queryGenerator.setConnection(this);
 
     Object.defineProperties(this, {
       'dialect': {
@@ -280,6 +281,39 @@ class ConnectionBase extends EventEmitter {
     return new QueryGeneratorBase(this);
   }
 
+  /// An `Object.assign` type of operation... with a twist.
+  ///
+  /// `stackAssign` works kinda like `Object.assign`. It has
+  /// the same interface, and accomplishes the same result.
+  /// What it does differently however is that it uses
+  /// `Object.create` on the first argument to create a new
+  /// object, using the first argument as a prototype. It then
+  /// merges all remaining `object` arguments into this newly
+  /// created object.
+  ///
+  /// This is used quite heavily in the underlying Mythix ORM engine.
+  /// It's purpose is to modify `options` arguments as they pass through
+  /// the engine. For example, a `destroy` operation might want to inform
+  /// the projection engine that we don't want any field aliases... and
+  /// so it will `stackAssign` the `options`, setting `noProjectionAliases: true`
+  /// for the "stacked options" object. Javascript--being the prototypical language
+  /// that it is--will *behave* like the objects in question have been
+  /// passed through `Object.assign`, because all the original `options` to
+  /// any operation are still accessible in the prototype, but may have been
+  /// overridden like in our example of a `destroy` operation. This allows the
+  /// engine to easily and quickly override options without mutating the original
+  /// `options` object provided, and still be able to access provided options,
+  /// even if they are not enumerable.
+  ///
+  /// Arguments:
+  ///   obj: object
+  ///     The object to set as the prototype of the newly created object,
+  ///     using `Object.create` on it.
+  ///   ...args: Array<object>
+  ///     The other objects to merge into this object, using `Object.assign`.
+  ///
+  /// Return: object
+  ///   The newly "stacked" and merged object.
   stackAssign(obj, ..._args) {
     let newObj = Object.create(obj || {});
     let args = _args.filter(Boolean);
@@ -347,12 +381,14 @@ class ConnectionBase extends EventEmitter {
   }
 
   /// Get the default order for selecting rows
-  /// from the database. This will call the
-  /// Model's <see name="Model.defaultOrder">Model.static defaultOrder</see> method
-  /// first to see if the model specifies a default order
-  /// for itself. If it doesn't, then the connection
+  /// from the database. The connection
   /// driver itself might specify a default order for
-  /// each table.
+  /// each table, if one isn't specified by the user.
+  ///
+  /// Note:
+  ///   To specify a default order for each model, use
+  ///   the <see>Model.static defaultScope</see> method
+  ///   instead.
   ///
   /// Arguments:
   ///   Model: class <see>Model</see>
@@ -408,6 +444,35 @@ class ConnectionBase extends EventEmitter {
     return true;
   }
 
+  /// A convenience method to get from "model cache".
+  ///
+  /// Model Cache is a simple system to cache
+  /// random results from model methods. This is used
+  /// for things that should never change, for example
+  /// the models fields, the models name, the table
+  /// name for the model, etc... Some of these values
+  /// are initially computed, and then cached using this
+  /// system so operations later on return much quicker.
+  ///
+  /// Note:
+  ///   The underlying cache system uses the `Map` type,
+  ///   so any value can be used as a cache key.
+  ///
+  /// Note:
+  ///   This cache is never cleared or marked as stale, so
+  ///   if using dynamic cache keys, make sure that you
+  ///   properly remove them later to prevent memory leaks.
+  ///
+  /// Arguments:
+  ///   Model: class <see>Model</see>
+  ///     The model class we a caching for.
+  ///   key: any
+  ///     The key to use for our cache.
+  ///   defaultValue?: any
+  ///     The default value to return if no cache entry was found.
+  ///
+  /// Return: any
+  ///   Any value found in the cache.
   _getFromModelCache(Model, key, defaultValue) {
     let cache = this._modelCache.get(Model);
     if (!cache)
@@ -420,6 +485,35 @@ class ConnectionBase extends EventEmitter {
     return value;
   }
 
+  /// A convenience method to set to the "model cache".
+  ///
+  /// Model Cache is a simple system to cache
+  /// random results from model methods. This is used
+  /// for things that should never change, for example
+  /// the models fields, the models name, the table
+  /// name for the model, etc... Some of these values
+  /// are initially computed, and then cached using this
+  /// system so operations later on return much quicker.
+  ///
+  /// Note:
+  ///   The underlying cache system uses the `Map` type,
+  ///   so any value can be used as a cache key.
+  ///
+  /// Note:
+  ///   This cache is never cleared or marked as stale, so
+  ///   if using dynamic cache keys, make sure that you
+  ///   properly remove them later to prevent memory leaks.
+  ///
+  /// Arguments:
+  ///   Model: class <see>Model</see>
+  ///     The model class we a caching for.
+  ///   key: any
+  ///     The key to use for our cache.
+  ///   value: any
+  ///     The value to cache.
+  ///
+  /// Return: any
+  ///   The `value` provided.
   _setToModelCache(Model, key, value) {
     let cache = this._modelCache.get(Model);
     if (!cache) {
@@ -493,6 +587,51 @@ class ConnectionBase extends EventEmitter {
     return 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.
+  ///
+  /// It works by walking the provided query, and calling <see>Model.static finalizeQuery</see>
+  /// on every model it encounters that is used in the query. It will also recursively
+  /// call itself for every new query it encounters that is part of the query,
+  /// for example sub-queries. In this way, you can take on extra conditions to any
+  /// part of a query, throw a "Forbidden" exception if the user is disallowed from querying
+  /// certain data, or whatever you want.
+  ///
+  /// 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:
+  ///   crudOperation: 'create' | 'read' | 'update' | 'delete'
+  ///     The Mythix ORM reports what "type" of operation is being executed
+  ///     using this argument. This is used so one can know if the operation
+  ///     that is about to be executed is a `read`, `update`, or `delete` operation.
+  ///   query: <see>QueryEngine</see>
+  ///     The query to operate upon. This will be walked, calling <see>Model.static finalizeQuery</see>
+  ///     for each unique model encountered, and also recursively walking any sub-queries.
+  ///   options?: object
+  ///     Random options for the operation. These are not used by this method, but instead are
+  ///     the `options` provided to the database operation when it was requested, and are also
+  ///     available for use for any user needs.
+  ///
+  /// Return: <see>QueryEngine</see>
+  ///   The query provided, possibly altered.
+  ///
+  /// See: Model.static finalizeQuery
   async finalizeQuery(crudOperation, queryEngine, options) {
     if (!QueryEngine.isQuery(queryEngine))
       return queryEngine;
@@ -613,7 +752,7 @@ class ConnectionBase extends EventEmitter {
   /// it was created.
   ///
   /// Arguments:
-  ///   Model: Array<class <see>Model</see>> | { [key: string]: class <see>Model</see> }
+  ///   models: Array<class <see>Model</see>> | { [key: string]: class <see>Model</see> }
   ///     The model classes to register with this connection. If no models are bound, then
   ///     they will simply exist in the model pool for this connection. If bound, then
   ///     this connection will bind itself to every model being registered.
@@ -623,13 +762,14 @@ class ConnectionBase extends EventEmitter {
   ///     provided to the connection when it was created. If you specify either of these
   ///     options they simply override the connection's default.
   ///
-  /// Return: class <see>Model</see>
+  /// Return: { [key: string]: class <see>Model</see> }
   ///   The registered model classes, **which may have changed during registration**.
   ///   It is not uncommon for the connection driver itself to modify the model
   ///   classes, or to return a new model classes that inherit from your model classes.
   ///   The classes that are returned should be the classes that you use for this connection,
   ///   and will be the same classes returned by a call to <see>Connection.getModel</see>,
-  ///   or <see>Connection.getModels</see>.
+  ///   or <see>Connection.getModels</see>. An object is returned, where each key is
+  ///   a model name, and each value is a model class.
   registerModels(models, options) {
     if (!models)
       return;
@@ -916,7 +1056,14 @@ class ConnectionBase extends EventEmitter {
   ///   Return the <see>QueryGenerator</see> for this connection,
   ///   or return `null` if none is defined for this connection.
   getQueryGenerator() {
-    return this.queryGenerator;
+    let queryGenerator = this.queryGenerator;
+    if (queryGenerator) {
+      let connection = queryGenerator.getConnection();
+      if (!connection)
+        queryGenerator.setConnection(this);
+    }
+
+    return queryGenerator;
   }
 
   /// Set the <see>QueryGenerator</see> instance for this
@@ -940,15 +1087,10 @@ class ConnectionBase extends EventEmitter {
   }
 
   /// The low-level DB interface for escaping a
-  /// value. By default this function uses the
-  /// [sqlstring](https://www.npmjs.com/package/sqlstring)
-  /// module to escape values. However, the `escape`
-  /// method for whatever database the connection is
-  /// using should be used instead of this. This is
-  /// a "default implementation" that is meant as a
-  /// fallback when a connection doesn't provide its
-  /// own, but each connection should provide its own
-  /// when it is able.
+  /// value. By default this function simply returns
+  /// the value it is provided. It is up to the
+  /// database driver itself to provide a proper
+  /// implementation of this method.
   ///
   /// Note:
   ///   This method escapes "values" that are given in
@@ -957,8 +1099,7 @@ class ConnectionBase extends EventEmitter {
   ///   instead.
   ///
   /// Return: string
-  ///   The value provided, escaped for the specific
-  ///   underlying database driver.
+  ///   The value provided.
   ///
   /// Arguments:
   ///   value: any
@@ -966,10 +1107,7 @@ class ConnectionBase extends EventEmitter {
   ///     a string, or anything else that can be provided to your
   ///     specific database.
   _escape(value) {
-    if (Nife.instanceOf(value, 'string'))
-      return `'${value.replace(/'/g, '\'\'')}'`;
-
-    return SqlString.escape(value);
+    return value;
   }
 
   /// Unlike <see>ConnectionBase._escape</see> --which is
@@ -1060,22 +1198,18 @@ class ConnectionBase extends EventEmitter {
   /// provides as a "fallback" to database drivers that don't
   /// supply their own.
   ///
-  /// It works by first stripping all quotes (single `'`, double `"`, and backtick `` ` ``)
-  /// from the provided `value`. After this, it will split on the period (dot) character
-  /// `.`, and then will map each resulting part through [sqlstring](https://www.npmjs.com/package/sqlstring)
-  /// `escapeId` method, finally re-joining the parts with a period `.` character.
-  ///
-  /// The extra processing is to allow for already escaped identifiers to not be double-escaped.
+  /// This method simply returns the value provided. It is
+  /// expected that each database driver will properly overload
+  /// this method to provide the correct escaping for identifiers.
   ///
   /// Return: string
-  ///   The provided identifier, escaped for the underlying database.
+  ///   The provided identifier.
   ///
   /// Arguments:
   ///  value: string
   ///    The identifier to escape.
   _escapeID(value) {
-    let parts = value.replace(/['"`]/g, '').split(/\.+/g);
-    return parts.map((part) => SqlString.escapeId(part).replace(/^`/, '"').replace(/`$/, '"')).join('.');
+    return value;
   }
 
   /// This method is very similar to <see>ConnectionBase._escapeID</see>,
@@ -1382,10 +1516,10 @@ class ConnectionBase extends EventEmitter {
   /// will be database specific. The database driver connection
   /// is free to override this method.
   ///
-  /// This method will convert a <see>AverageLiteral</see>, a
-  /// <see>CountLiteral</see>, a <see>DistinctLiteral</see>,
-  /// a <see>FieldLiteral</see>, a <see>MaxLiteral</see>, a
-  /// <see>MinLiteral</see>, a <see>SumLiteral</see>, or a
+  /// This method will convert an <see>AverageLiteral</see>,
+  /// <see>CountLiteral</see>, <see>DistinctLiteral</see>,
+  /// <see>FieldLiteral</see>, <see>MaxLiteral</see>,
+  /// <see>MinLiteral</see>, <see>SumLiteral</see>, or a
   /// <see>Literal</see> to a string. If the provided literal
   /// is not one of these types, than an exception will be thrown.
   ///
@@ -2651,7 +2785,7 @@ class ConnectionBase extends EventEmitter {
   /// Create a table/bucket using the provided model class.
   ///
   /// The provided `options` are database specific,
-  /// but might contain things like `ifExists`, for
+  /// but might contain things like `ifNotExists`, for
   /// example.
   ///
   /// Return: any

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

@@ -2,15 +2,95 @@
 
 const LiteralFieldBase = require('./literal-field-base');
 
+/// Define a "count" 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 "count" operation across all matching
+/// rows. It is used by <see>Connection.count</see> to get
+/// the number of matching rows for a query. 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 `COUNT(column)`,
+/// our `COUNT(*)`. This is often used by the projection engine, to project
+/// it as a column to be selected. For example `SELECT COUNT(column) AS count ...`.
+/// It can be used in other places in the query however, such as `ORDER`,
+/// `GROUP BY`, and `HAVING` clauses.
+///
+/// Note:
+///   If no field is provided to `CountLiteral`
+///   then all fields (`*`) is assumed.
+///
+/// Note:
+///   It is common to use the `{ as: 'count' }` option to give the count
+///   literal an alias (name).
+///
+/// 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.CountLiteral`.
+///
+/// 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.CountLiteral('*', { as: 'count' });
+///   let literal2 = new SQLiteConnection.CountLiteral.CountLiteral('*', { as: 'count' });
+///
+/// See: LiteralFieldBase
+///
+/// See: LiteralBase
 class CountLiteral extends LiteralFieldBase {
+  /// Return `false`, informing the engine that
+  /// a field is not required for this literal type.
+  ///
+  /// Return: boolean
+  ///   Return `false`, informing the caller that this literal
+  ///   does not require a field.
   static isFieldRequired() {
     return false;
   }
 
+  /// 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. `'CountLiteral {}'`.
+  ///
+  /// Note:
+  ///   Ultimately, for most connections, this will end up calling
+  ///   <see>QueryGenerator._countLiteralToString</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} {}`;