mythix-orm 1.11.6 → 1.11.7

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

@@ -280,6 +280,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 +380,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 +443,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 +484,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 +586,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;
@@ -1382,10 +1520,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.
   ///

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} {}`;

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;