mythix-orm 1.12.0 → 1.13.1

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,74 @@ 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 +243,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 +347,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 +369,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 +421,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 +432,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 +444,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.1",
   "description": "ORM for Mythix framework",
   "main": "lib/index",
   "type": "commonjs",