mythix-orm 1.12.0 → 1.13.2

package/README.md

@@ -1,6 +1,8 @@
 # mythix-orm
 
-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](docs/mythix-logo-colored.png)
+
+Mythix ORM aims to replace Sequelize, Prisma, 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 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.
@@ -28,7 +30,7 @@ Just start creating models!
 
 ```javascript
 const { Model, Types }  = require('mythix-orm');
-const SQLiteConnection  = require('mythix-orm-sqlite');
+const { SQLiteConnection }  = require('mythix-orm-sqlite');
 
 class User extends Model {
   static fields = {
@@ -97,10 +99,10 @@ class User extends Model {
 
 ## 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.
+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. 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
 
-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!
+The `Mythix` suite of technologies are being developed to give a rock-solid full-stack framework 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

@@ -396,11 +396,9 @@ class ConnectionBase extends EventEmitter {
   ///   options: object
   ///     Operation specific options (i.e. options for a "select" call)
   ///
-  /// Return: Array<string>
-  ///   An array of fully qualified field names for this model should
-  ///   be returned by this method. An empty array, `null`, or `undefined`
-  ///   are also valid return values (in which case no order will be
-  ///   applied to the given operation).
+  /// Return: Map<string, { value: Field | Literal | string; direction?: '+' | '-'; ... }>
+  ///   Return the field-set for the default ordering to apply to the operation taking place.
+  ///   This `Map` should have the same format as is returned by <see>ModelScope.mergeFields</see>.
   getDefaultOrder(Model, options) {
   }
 

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

@@ -243,9 +243,21 @@ class LiteralBase {
   /// Convert the literal value provided to the `constructor`
   /// to a string.
   ///
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     The connection to use to stringify the literal. If
+  ///     not provided, then a "representation" of the literal
+  ///     (for logging/debugging) will be returned instead.
+  ///   options?: object
+  ///     Any options needed to stringify the literal. These are often
+  ///     literal and/or database specific.
+  ///
   /// Return: string
-  ///   The value provided to the `constructor` as a string.
-  toString() {
+  ///   The stringified literal, ready to be used in the underlying database
+  ///   (if a `connection` was provided), or a logging/debugging representation
+  ///   of the literal if no `connection` is provided.
+  // eslint-disable-next-line no-unused-vars
+  toString(connection, options) {
     if (!this.literal)
       return ('' + this.literal);
 

package/lib/model.js

@@ -1772,8 +1772,22 @@ class Model {
     return this.getWhereWithConnection(options).all(options);
   }
 
-  static fetchAll(options) {
-    return this.all({ ...(options || {}), stream: true });
+  /// This method is similar in nature to <see>Model.static all</see>,
+  /// except that instead of collecting all results into an
+  /// array before returning, it will instead "stream" the results
+  /// from the database using an async generator.
+  ///
+  /// Arguments:
+  ///   options?: object
+  ///     Options for the operation. These are generally
+  ///     database specific. Like the <see>Model.static all</see>
+  ///     method you can supply a `batchSize`.
+  ///
+  /// Return: async * iterator
+  ///   An async generator iterator that will "stream" the
+  ///   results from the database.
+  static cursor(options) {
+    return this.cursor(options);
   }
 
   /// Get the first (limit) rows from the database for this model type.

package/lib/query-engine/model-scope.js

@@ -31,7 +31,7 @@ function applyOrderClause(extraData, ...args) {
   }).filter(Boolean);
 
   let context = this.getOperationContext();
-  let order = this.margeFields(
+  let order = this.mergeFields(
     context.order,
     entities,
     extraData,
@@ -334,8 +334,8 @@ class ModelScope extends QueryEngineBase {
   /// Return: Map<string, { value: Field | Literal | string; direction?: '+' | '-'; ... }>
   ///   Return the new field set. A `Map` will always be returned, but it is possible
   ///   for the `Map` to be empty.
-  margeFields(currentFields, incomingFields, extraData, options) {
-    return QueryUtils.margeFields(this, currentFields, incomingFields, extraData, options);
+  mergeFields(currentFields, incomingFields, extraData, options) {
+    return QueryUtils.mergeFields(this, currentFields, incomingFields, extraData, options);
   }
 
   /// Invert the logic of the following operator.
@@ -487,12 +487,12 @@ class ModelScope extends QueryEngineBase {
   /// There are five variants to this method, `ORDER.ASC`,
   /// `ORDER.DESC`, `ORDER.ADD`, `ORDER.REPLACE`, and `ORDER` (which is an alias for `ORDER.ASC`), .
   /// 1) `ORDER` - Alias for `ORDER.ASC`.
-  /// 2) `ORDER.ASC` - Follow the rules of <see>ModelScope.margeFields</see>. Each field/literal added is in `ASC` order.
-  /// 3) `ORDER.DESC` - Follow the rules of <see>ModelScope.margeFields</see>. Each field/literal added is in `DESC` order.
-  /// 4) `ORDER.ADD` - **DO NOT** follow the rules of <see>ModelScope.margeFields</see>, and instead **add** all fields specified, with their sort order being specified instead by the `+` or `-` prefixes on each field.
-  /// 5) `ORDER.REPLACE` - **DO NOT** follow the rules of <see>ModelScope.margeFields</see>, and instead **replace** the operation fields to the fields specified, with their sort order being specified instead by the `+` or `-` prefixes on each field.
+  /// 2) `ORDER.ASC` - Follow the rules of <see>ModelScope.mergeFields</see>. Each field/literal added is in `ASC` order.
+  /// 3) `ORDER.DESC` - Follow the rules of <see>ModelScope.mergeFields</see>. Each field/literal added is in `DESC` order.
+  /// 4) `ORDER.ADD` - **DO NOT** follow the rules of <see>ModelScope.mergeFields</see>, and instead **add** all fields specified, with their sort order being specified instead by the `+` or `-` prefixes on each field.
+  /// 5) `ORDER.REPLACE` - **DO NOT** follow the rules of <see>ModelScope.mergeFields</see>, and instead **replace** the operation fields to the fields specified, with their sort order being specified instead by the `+` or `-` prefixes on each field.
   ///
-  /// See <see>ModelScope.margeFields</see> to better understand how this method works.
+  /// See <see>ModelScope.mergeFields</see> to better understand how this method works.
   ///
   /// SyntaxType: FunctionDeclaration
   ///
@@ -513,7 +513,7 @@ class ModelScope extends QueryEngineBase {
 
   /// Apply a `GROUP BY` clause to the query.
   ///
-  /// See <see>ModelScope.margeFields</see> to better understand how this method works.
+  /// See <see>ModelScope.mergeFields</see> to better understand how this method works.
   ///
   /// Note:
   ///   This method will flatten all provided arguments into a one dimensional array,
@@ -548,7 +548,7 @@ class ModelScope extends QueryEngineBase {
     }).filter(Boolean);
 
     let context = this.getOperationContext();
-    let groupBy = this.margeFields(
+    let groupBy = this.mergeFields(
       context.groupBy,
       entities,
       {},
@@ -643,7 +643,7 @@ class ModelScope extends QueryEngineBase {
 
   /// Replace, add to, or subtract from the projection of the query.
   ///
-  /// See <see>ModelScope.margeFields</see> to better understand how this method works.
+  /// See <see>ModelScope.mergeFields</see> to better understand how this method works.
   ///
   /// Note:
   ///   This method will flatten all provided arguments into a one dimensional array,
@@ -691,7 +691,7 @@ class ModelScope extends QueryEngineBase {
     }).filter(Boolean);
 
     let context = this.getOperationContext();
-    let projection = this.margeFields(
+    let projection = this.mergeFields(
       context.projection,
       entities,
       {},

package/lib/utils/index.js

@@ -30,7 +30,7 @@ const {
 const {
   parseFilterFieldAndOperator,
   generateQueryFromFilter,
-  margeFields,
+  mergeFields,
 } = QueryUtils;
 
 const {
@@ -69,7 +69,7 @@ module.exports = {
   // QueryUtils
   parseFilterFieldAndOperator,
   generateQueryFromFilter,
-  margeFields,
+  mergeFields,
 
   // AsyncStore
   getContextStore,

package/lib/utils/misc-utils.js

@@ -1,8 +1,25 @@
+///! import `var { Utils: { MiscUtils } } = require('mythix-orm');`
+///!
+///! MiscUtils utilities provide some miscellaneous utility
+///! functions for assisting with some common operations.
+///!
+///! DocScope: MiscUtils
+
 'use strict';
 
 const Nife          = require('nife');
 const { DateTime }  = require('luxon');
 
+/// When provided an async iterator,
+/// collect all results from the iterator
+/// until the iterator is exhausted.
+///
+/// Arguments:
+///   iterator: async * iterator
+///     The async generator iterator to collect items from.
+///
+/// Return: Promise<Array<any>>
+///   Return the collected results as an array.
 async function collect(iterator) {
   let items = [];
 
@@ -12,6 +29,27 @@ async function collect(iterator) {
   return items;
 }
 
+/// Take a timestamp, a string, a Date instance,
+/// or a Luxon [DateTime](https://moment.github.io/luxon/#/) instance
+/// and convert the input to a Luxon [DateTime](https://moment.github.io/luxon/#/) instance.
+///
+/// Arguments:
+///   value: number | string | Date | [DateTime](https://moment.github.io/luxon/#/)
+///     The value to use to create a new Luxon [DateTime](https://moment.github.io/luxon/#/) instance.
+///     If this is a `number` or `bigint`, then it will be assumed this is a timestamp, and
+///     the provided `format` will be ignored. If this is a `string`, the provided `format`
+///     will be used to parse it into a `DateTime` instance. If this is a `Date` instance, then
+///     it will be converted to a Luxon `DateTime` instance. A Luxon `DateTime` instance will
+///     simply be returned.
+///   format?: string
+///     The Luxon [DateTime](https://moment.github.io/luxon/#/) format used to parse
+///     the date/time if the provided `value` is a string. This is only required if
+///     the format is something that Luxon doesn't natively understand (i.e. an ISO format).
+///
+/// Return: [DateTime](https://moment.github.io/luxon/#/)
+///   The newly created Luxon `DateTime` instance. If a Luxon `DateTime`
+///   instance was provided as the `value` argument, then it will simply
+///   be returned.
 function valueToDateTime(value, format) {
   if (DateTime.isDateTime(value)) {
     return value;

package/lib/utils/query-utils.d.ts

@@ -11,7 +11,7 @@ export declare function generateQueryFromFilter(
   filter: Array<GenericObject | Model> | GenericObject | Model,
 ): QueryEngine;
 
-export declare function margeFields(
+export declare function mergeFields(
   connection: ConnectionBase,
   currentFields: Map<string, any>,
   incomingFields: Array<any>

package/lib/utils/query-utils.js

@@ -1,38 +1,15 @@
+///! import `var { Utils: { QueryUtils } } = require('mythix-orm');`
+///!
+///! QueryUtils provide utility functions
+///! for creating and interacting with queries
+///! ([QueryEngine](https://github.com/th317erd/mythix-orm/wiki/QueryEngine)).
+///!
+///! DocScope: QueryUtils
+
 'use strict';
 
 const Nife = require('nife');
 
-// The code below will take a "query object"
-// and convert it into Mythix ORM query.
-//
-// "query objects" are objects with a simple
-// structure and convention to build complex queries.
-//
-// Fields inside these objects can have operators,
-// which are postfixed to the field name. For example,
-// you could create a filter to find a user by name
-// with the following query object:
-// { "firstName=": "John", "lastName!=": "Bob" }
-// which would find all users with the first name
-// of "John", and any last name except "Bob".
-//
-// AND and OR conditions are also supported. These
-// work based of the structure of the object itself.
-// If an array is used, then OR is in effect.
-// If an object is used, then AND is in effect.
-// For example, the following query object:
-// [ { firstName: "John", lastName: "Brown" }, { firstName: "Mary", lastName: "Smith" } ]
-// would result in the following query:
-// WHERE ((firstName = 'John' AND lastName = 'Brown') OR (firstName = 'Mary' AND lastName = 'Smith')),
-// finding either user John Brown, or Mary Smith.
-//
-// IN and NOT IN operators are handled automatically
-// when the operator is either "=" or "!=", and the
-// provided value is an array. For example:
-// { firstName: [ 'John', 'Bob', 'Mary' ] }
-// would result in the following query:
-// WHERE firstName IN ('John', 'Bob', 'Mary')
-
 const FILTER_OPERATORS = {
   '=': (Model, fieldName, query, value) => {
     return query.AND[fieldName].EQ(value);
@@ -70,6 +47,24 @@ const FILTER_OPERATORS = {
   },
 };
 
+/// Take the provided `fieldName`, which might include
+/// an operator as a postfix, and return the operator
+/// and `fieldName` found. If no operator postfix is
+/// present, then the default `=` operator is returned.
+///
+/// Refer to <see>QueryUtils.generateQueryFromFilter</see> for
+/// a better understanding of what this does and why it is needed.
+///
+/// Arguments:
+///   fieldName: string
+///     The field name to parse, with an optional operator postfix added.
+///
+/// Return: { field: string; operator: string; }
+///   Return the parsed `field`, and the parsed `operator`. If no
+///   operator postfix is on the field, then the default is the `=`
+///   operator.
+///
+/// See: QueryUtils.generateQueryFromFilter
 function parseFilterFieldAndOperator(fieldName) {
   let operator = '=';
   let field;
@@ -90,6 +85,75 @@ function parseFilterFieldAndOperator(fieldName) {
   return { field, operator };
 }
 
+/// Take a "query object" and convert it into Mythix ORM query.
+///
+/// "query objects" are objects with a simple
+/// structure and convention to build complex queries.
+///
+/// Fields inside these objects can have operators,
+/// which are postfixed to the field name. For example,
+/// you could create a filter to find a user by name
+/// with the following query object:
+/// `{ "firstName=": "John", "lastName!=": "Bob" }`
+/// which would find all users with the first name
+/// of "John", and any last name except "Bob".
+///
+/// `AND` and `OR` conditions are also supported. These
+/// work based of the structure of the object itself.
+/// If an array is used, then `OR` is in effect.
+/// If an object is used, then `AND` is in effect.
+/// For example, the following query object:
+/// `[ { firstName: "John", lastName: "Brown" }, { firstName: "Mary", lastName: "Smith" } ]`
+/// would result in the following SQL query:
+/// `WHERE ((firstName = 'John' AND lastName = 'Brown') OR (firstName = 'Mary' AND lastName = 'Smith'))`,
+/// finding either user John Brown, or Mary Smith.
+///
+/// `IN` and `NOT IN` operators are handled automatically
+/// when the operator is either `=` or `!=`, and the
+/// provided value is an array. For example:
+/// `{ firstName: [ 'John', 'Bob', 'Mary' ] }`
+/// would result in the following SQL query:
+/// `WHERE firstName IN ('John', 'Bob', 'Mary')`.
+///
+/// Operators that can be postfixed to field names
+/// in the provided `filter` object are as follows:
+/// | Operator | Description |
+/// | -------- | ----------- |
+/// | `=` | Equality operator. If an `Array` of values is provided, then this will turn into a `IN` operation in the underlying database. |
+/// | `!=` | Inverse (not) equality operator. If an `Array` of values is provided, then this will turn into a `NOT IN` operation in the underlying database. |
+/// | `>` | Greater than operator. |
+/// | `>=` | Greater than or equal to operator. |
+/// | `<` | Less than operator. |
+/// | `<=` | Less than or equal to operator. |
+/// | `><` | Between operator. This operator requires that the provided value be an array with exactly two elements: `[ min, max ]`. |
+/// | `<>` | Inverse (not) between operator. This operator requires that the provided value be an array with exactly two elements: `[ min, max ]`. |
+/// | `*` | A `LIKE` wildcard matching operator. The provided value should use `%` for "zero or more" matches, and `_` for "any single character" match. |
+/// | `!*` | A `NOT LIKE` wildcard matching operator. The provided value should use `%` for "zero or more" matches, and `_` for "any single character" match. |
+///
+/// Note:
+///   This is a simple interface to take an "object" and turn it into
+///   a <see>QueryEngine</see>. It doesn't allow multiple models
+///   to be defined at once (table-joins), nor other complex operations.
+///   If you need more complex operations on your query, you will need
+///   to manually create your query... though this method can be used
+///   as a starting point.
+///
+/// Arguments:
+///   connection: <see>Connection</see>
+///     The connection used to create the <see>QueryEngine</see>.
+///   Model: class <see>Model</see>
+///     The model the query is being generated for. The specified
+///     fields provided via the `filter` argument should all be from
+///     this model.
+///   filter: object | Array
+///     An object or an array of objects to build a query from. Any
+///     object will have all its properties `AND`ed together... whereas
+///     any array will have its sub-objects `OR`ed together. i.e.
+///     `[ { prop1 AND prop2 AND prop3 } OR { prop1 AND prop2 AND prop3 } ]`.
+///
+/// Return: <see>QueryEngine</see>
+///   The new query for the `Model` provided, generated from the
+///   provided `filter` argument.
 function generateQueryFromFilter(connection, Model, _filter, _depth) {
   const getOperator = (name) => {
     let func = FILTER_OPERATORS[name];
@@ -180,7 +244,35 @@ function generateQueryFromFilter(connection, Model, _filter, _depth) {
   return query;
 }
 
-function margeFields(queryEngine, currentFields, _incomingFields, extraData, _options) {
+/// Merge fields for a `PROJECT`, `ORDER`,
+/// or `GROUP_BY` <see>QueryEngine</see> operation.
+///
+/// See <see>ModelScope.mergeFields</see> for a more detailed description
+/// of what this method does and how it is used.
+///
+/// Arguments:
+///   queryEngine: <see>QueryEngine</see>
+///     The <see>QueryEngine</see> instance that the `PROJECT`,
+///     `ORDER`, or `GROUP_BY` operation is being applied to.
+///   currentFields: Map<string, object>
+///     A map of the current fields that have been applied to the
+///     given operation.
+///   incomingFields: Array<string | Literal | Model | Field>
+///     A list of all the incoming fields that are supplied to the
+///     `PROJECT`, `ORDER`, or `GROUP_BY` operation that is being carried
+///     out. This will either merge will `currentFields`, or replace
+///     the `currentFields`, depending on the content of this argument.
+///   extraData?: object
+///     If supplied, then merge these extra properties into each field being
+///     added to the list of fields. This is used for example by the `ORDER`
+///     operation to define the `direction` property for each field added.
+///   options?: object
+///     Options for the operation. These are only used when stringifying
+///     literals that are being added to the field list. See <see>LiteralBase.toString</see>
+///     for more information.
+///
+/// See: ModelScope.mergeFields
+function mergeFields(queryEngine, currentFields, _incomingFields, extraData, _options) {
   const RESET = 0;
   const ADD   = 1;
   const SUB   = 2;
@@ -256,7 +348,7 @@ function margeFields(queryEngine, currentFields, _incomingFields, extraData, _op
 
     if (typeof incomingField.isLiteral === 'function' && incomingField.isLiteral(incomingField)) {
       if (!connection)
-        throw new Error('QueryUtils::margeFields: "connection" is required, but not found.');
+        throw new Error('QueryUtils::mergeFields: "connection" is required, but not found.');
 
       let result = incomingField.toString(connection, options);
       addOrRemove(mode, result, result);
@@ -278,7 +370,7 @@ function margeFields(queryEngine, currentFields, _incomingFields, extraData, _op
       continue;
 
     if (!connection)
-      throw new Error('QueryUtils::margeFields: "connection" is required, but not found.');
+      throw new Error('QueryUtils::mergeFields: "connection" is required, but not found.');
 
     if (!incomingField)
       continue;
@@ -330,7 +422,7 @@ function margeFields(queryEngine, currentFields, _incomingFields, extraData, _op
 
     let Model = connection.getModel(def.modelName);
     if (!Model)
-      throw new Error(`QueryUtils::margeFields: Model "${def.modelName}" not found.`);
+      throw new Error(`QueryUtils::mergeFields: Model "${def.modelName}" not found.`);
 
     if (Nife.isEmpty(def.fieldNames)) {
       addOrRemoveAllModelFields(currentMode, Model);
@@ -341,7 +433,7 @@ function margeFields(queryEngine, currentFields, _incomingFields, extraData, _op
     let fieldName = def.fieldNames[0];
     let field     = connection.getField(fieldName, modelName);
     if (!field)
-      throw new Error(`QueryUtils::margeFields: Field "${fieldName}" not found.`);
+      throw new Error(`QueryUtils::mergeFields: Field "${fieldName}" not found.`);
 
     let fullFieldName = `${modelName}:${fieldName}`;
     addOrRemove(currentMode, fullFieldName, field);
@@ -353,5 +445,5 @@ function margeFields(queryEngine, currentFields, _incomingFields, extraData, _op
 module.exports = {
   parseFilterFieldAndOperator,
   generateQueryFromFilter,
-  margeFields,
+  mergeFields,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythix-orm",
-  "version": "1.12.0",
+  "version": "1.13.2",
   "description": "ORM for Mythix framework",
   "main": "lib/index",
   "type": "commonjs",