mythix-orm-sql-base 1.9.6 → 1.10.1

package/.biblorc.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/* global __dirname */
+
+const Path = require('path');
+
+module.exports = {
+  rootDir:    __dirname,
+  inputDir:   Path.resolve(__dirname),
+  outputDir:  Path.resolve(__dirname, '..', 'mythix-orm-sql-base.wiki'),
+  files: [
+    {
+      include:  /\/lib\/.*\.js$/,
+      parser:   'typescript',
+      compiler: 'typescript',
+    },
+    {
+      include:  /\/docs\/.*\.md$/,
+      parser:   'markdown',
+      compiler: 'markdown',
+    },
+  ],
+  exclude: [
+    /node_modules|\/spec\//
+  ],
+  generatorOptions: {
+    repositoryURL:  'https://github.com/th317erd/mythix-orm-sql-base',
+    baseURL:        './',
+  },
+};

package/README.md

@@ -1,7 +1,5 @@
 # mythix-orm-sql-base
 
-SQL base support for Mythix ORM
+SQL base support for [Mythix ORM](https://www.npmjs.com/package/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 is not yet quite ready for prime time however, so please check back soon!
-
-This module isn't intended to be used by itself. It is a support module for other SQL-based database drivers.
+This module isn't intended to be used by itself. It is a support module for other SQL database drivers.

package/docs/Home.md

@@ -0,0 +1,3 @@
+SQL base support for [Mythix ORM](https://www.npmjs.com/package/mythix-orm).
+
+This module isn't intended to be used by itself. It is a support module for other SQL database drivers.

package/lib/sql-connection-base.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const SqlString = require('sqlstring');
 const Nife  = require('nife');
 const UUID  = require('uuid');
 const {
@@ -13,11 +14,88 @@ const {
 const SQLQueryGeneratorBase = require('./sql-query-generator-base');
 
 const SAVE_POINT_NAME_CHARS = [ 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P' ];
-const MODEL_RELATIONS       = Symbol.for('_mythixModelRelations');
-
+const MODEL_RELATIONS       = Symbol.for('@_mythix/orm-sql-base/SQLConnectionBase/ModelRelations');
+
+/// `SQLConnectionBase` is a support class for all other
+/// SQL connection drivers built for Mythix ORM. It isn't
+/// intended to be used on its own, but rather to add SQL
+/// support to all other Mythix ORM SQL connections.
+///
+/// Extends: [ConnectionBase](https://github.com/th317erd/mythix-orm/wiki/ConnectionBase)
 class SQLConnectionBase extends ConnectionBase {
   static DefaultQueryGenerator = SQLQueryGeneratorBase;
 
+  /// 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.
+  ///
+  /// Note:
+  ///   This method escapes "values" that are given in
+  ///   the underlying query language of the database.
+  ///   To escape identifiers, use the [ConnectionBase._escapeID](https://github.com/th317erd/mythix-orm/wiki/ConnectionBase#method-_escapeID)
+  ///   instead.
+  ///
+  /// Return: string
+  ///   The value provided, escaped for the specific
+  ///   underlying database driver.
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to escape. This could be a number, a boolean,
+  ///     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);
+  }
+
+  /// Low-level database method for escaping an identifier.
+  /// Each database driver should provide its own version of
+  /// this method. This is the "default" method Mythix ORM
+  /// 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.
+  ///
+  /// Return: string
+  ///   The provided identifier, escaped for the underlying database.
+  ///
+  /// 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('.');
+  }
+
+  /// Prepare an array of values for use in an `IN` statement.
+  /// This method will flatten the provided array, and then
+  /// will filter out all non-primitive values from the array.
+  /// Only `null`, `boolean`, `number`, `bigint`, and `string`
+  /// values will remain in the resulting array. The array is
+  /// also reduced to only unique values, with duplicates removed.
+  ///
+  /// Arguments:
+  ///   array: Array<any>
+  ///     The array to flatten, filter, and remove duplicates from.
+  ///
+  /// Return: Array<any>
+  ///   Return a copy of the array provided, after being flattened, filtered,
+  ///   and duplicates removed.
   prepareArrayValuesForSQL(_array) {
     let array = Nife.arrayFlatten(_array);
 
@@ -37,6 +115,13 @@ class SQLConnectionBase extends ConnectionBase {
     return Nife.uniq(array);
   }
 
+  /// Generate a `SAVEPOINT` name for use in sub-transactions.
+  /// This will generate a UUID v4 ID, and then mutate it so
+  /// that the name is SQL-safe. Finally, it will add an `SP`
+  /// prefix to the `SAVEPOINT` name.
+  ///
+  /// Return: string
+  ///   A random SQL-safe `SAVEPOINT` name.
   generateSavePointName() {
     let id = UUID.v4();
 
@@ -48,6 +133,26 @@ class SQLConnectionBase extends ConnectionBase {
     return `SP${id}`;
   }
 
+  /// Given a `Map` or an `Array` from a projection field-set, find all matching
+  /// projected fields through this connection, and return
+  /// them as an array.
+  ///
+  /// Arguments:
+  ///   projectionFieldMap: Map<string, string> | Array<string>
+  ///     A set of projected fields, as a `Map` or an `Array`. A `Map` type will usually be generated
+  ///     by <see>SQLQueryGeneratorBase.getProjectedFields</see>. The `Map` is expected
+  ///     to have fully qualified field names and expanded literal strings as keys, with
+  ///     the projected database fields (or literals) in database format for values. As
+  ///     an `Array` type, this should be a list of fully qualified field names, or expanded
+  ///     literals as values. An `Array` of field names is generally used when the `columns`
+  ///     from the database result are passed into this method.
+  ///
+  /// Return: Array<[Field](https://github.com/th317erd/mythix-orm/wiki/Field) | string>
+  ///   All fields found from the projection `Map`. Any field that wasn't able to be
+  ///   found on this `connection` will instead just be returned as its raw `string` form.
+  ///   Any raw strings returned are likely literals, and so couldn't be matched to fields.
+  ///   However, they may not always be literals, but instead may be a custom field or field
+  ///   alias that the user requested on the projection.
   findAllFieldsFromFieldProjectionMap(projectionFieldMap) {
     let fullFieldNames = (Array.isArray(projectionFieldMap)) ? projectionFieldMap : Array.from(projectionFieldMap.keys());
 
@@ -64,6 +169,26 @@ class SQLConnectionBase extends ConnectionBase {
     }).filter(Boolean);
   }
 
+  /// This method will take a `{ rows: Array<any>; columns: Array<string>; }` result from
+  /// a `SELECT` statement, and build a map of model data and sub-model data
+  /// to be later turned into model instances by <see>SQLConnectionBase.buildModelsFromModelDataMap</see>.
+  ///
+  /// Arguments:
+  ///   queryEngine: [QueryEngine](https://github.com/th317erd/mythix-orm/wiki/QueryEngine)
+  ///     The query engine that was used to generate the `SELECT` statement that returned these results.
+  ///   result: { rows: Array<any>; columns: Array<string>; }
+  ///     The results as returned by the database, used to build the data map to later construct model instances.
+  ///
+  /// Return: { [key: string]: Array<object> }
+  ///   Return `result` from the database, mapped to the models that were projected. Each key in
+  ///   this object will be a model name, and each value an array of model attributes. The model
+  ///   attributes in each array of models represents a model instance that will be created later
+  ///   using these attributes. There is a special key `Symbol.for('@_mythix/orm-sql-base/SQLConnectionBase/ModelRelations')`
+  ///   that can be present on any object of model attributes (a model). This special key--if present--will be
+  ///   another mapped object that represents "sub-models" that are "owned" by the model that has this
+  ///   special key. This is used when projecting and loading "related models" during a load operation.
+  ///
+  /// See: SQLConnectionBase.buildModelsFromModelDataMap
   buildModelDataMapFromSelectResults(queryEngine, result) {
     if (!result)
       return {};
@@ -249,11 +374,26 @@ class SQLConnectionBase extends ConnectionBase {
     return modelData;
   }
 
-  // eslint-disable-next-line no-unused-vars
-  async enableForeignKeyConstraints(enable) {
-    throw new Error(`${this.constructor.name}::enableForeignKeyConstraints: This operation is not supported for this connection type.`);
-  }
-
+  /// Take the result from a <see>SQLConnectionBase.buildModelDataMapFromSelectResults</see> call
+  /// and instantiate all models defined by the model attribute map.
+  ///
+  /// Arguments:
+  ///   queryEngine: [QueryEngine](https://github.com/th317erd/mythix-orm/wiki/QueryEngine)
+  ///     The query engine that was used to generate the `SELECT` statement that returned these results.
+  ///   modelDataMap: { [key: string]: Array<object> }
+  ///     The result from a call to <see>SQLConnectionBase.buildModelDataMapFromSelectResults</see>.
+  ///   callback?: (RootModel: class [Model](https://github.com/th317erd/mythix-orm/wiki/Model), model: [Model](https://github.com/th317erd/mythix-orm/wiki/Model)) => [Model](https://github.com/th317erd/mythix-orm/wiki/Model)
+  ///     A callback that is called for each *root model* instance created from the provided `modelDataMap`.
+  ///     Sub-models, or other models projected for the operation will not be passed through this callback.
+  ///     Only instances of the "root model" (or "target model") of the query will be passed through this
+  ///     callback. This callback **must** return the original model instance provided to it, or an equivalent
+  ///     model instance (possibly the same instance modified by the callback).
+  ///
+  /// Return: Array<[Model](https://github.com/th317erd/mythix-orm/wiki/Model)>
+  ///   An array of all fully-instantiated "root models" returned from the `SELECT` query, including
+  ///   any "sub-models" that were loaded along-side them. All models will be marked "clean".
+  ///
+  /// See: SQLConnectionBase.buildModelDataMapFromSelectResults
   buildModelsFromModelDataMap(queryEngine, modelDataMap, callback) {
     if (Nife.isEmpty(modelDataMap))
       return [];
@@ -305,6 +445,26 @@ class SQLConnectionBase extends ConnectionBase {
     return rootModels;
   }
 
+  /// Take the `{ rows: Array<any>; columns: Array<string>; }` result from
+  /// the database for a `RETURNING` statement, and update the effected models
+  /// with the results.
+  ///
+  /// This is used by `UPDATE` and `INSERT` statements to sync model attributes
+  /// with the database update/insert operation that just took place.
+  ///
+  /// This will also set all models provided to the call as "persisted".
+  ///
+  /// Arguments:
+  ///   Model: class [Model](https://github.com/th317erd/mythix-orm/wiki/Model)
+  ///     The model class of the array of `storedModels` that are being operated upon.
+  ///   storedModels: Array<[Model](https://github.com/th317erd/mythix-orm/wiki/Model)>
+  ///     The models that were just persisted.
+  ///   results: { rows: Array<any>; columns: Array<string>; }
+  ///     The raw results from the database, used to update all persisted models.
+  ///
+  /// Return: Array<[Model](https://github.com/th317erd/mythix-orm/wiki/Model)>
+  ///   Return `storedModels`, with each model being updated with the returned results
+  ///   from the database, and each model marked as "persisted".
   updateModelsFromResults(Model, storedModels, results) {
     let {
       rows,
@@ -328,6 +488,21 @@ class SQLConnectionBase extends ConnectionBase {
     return storedModels;
   }
 
+  /// Parse the database-specific return value for an
+  /// `UPDATE` or `DELETE` operation to retrieve the
+  /// number of rows that were updated or deleted.
+  ///
+  /// Note:
+  ///   Each database driver should overload this method to
+  ///   properly parse the results of an `UPDATE` or `DELETE`
+  ///   statement to return the number of rows affected.
+  ///
+  /// Arguments:
+  ///   queryResult: any
+  ///     The raw database response for an `UPDATE` or `DELETE` statement.
+  ///
+  /// Return: number
+  ///   The number of rows that were affected by the operation.
   getUpdateOrDeleteChangeCount(queryResult) {
     if (!queryResult)
       return 0;
@@ -343,20 +518,68 @@ class SQLConnectionBase extends ConnectionBase {
 
   // --------------------------------------------- //
 
+  /// For databases that support it, enable or disable foreign key constraints.
+  ///
+  /// Arguments:
+  ///   enable: boolean
+  ///     If `true`, enable foreign key constraints in the underlying database, otherwise
+  ///     disable foreign key constraints in the underlying database.
+  // eslint-disable-next-line no-unused-vars
+  async enableForeignKeyConstraints(enable) {
+    throw new Error(`${this.constructor.name}::enableForeignKeyConstraints: This operation is not supported for this connection type.`);
+  }
+
+  /// Drop the table/bucket defined by `Model`.
+  ///
+  /// Note:
+  ///   Mythix ORM always refers to data-spaces as "tables", even though
+  ///   they might actually be "buckets" for example for no-SQL databases.
+  ///
+  /// Arguments:
+  ///   Model: class [Model](https://github.com/th317erd/mythix-orm/wiki/Model)
+  ///     The model that defines the table to be dropped.
+  ///   options?: object
+  ///     Though these options can be database specific, they are commonly just
+  ///     the following options.
+  ///     | Option | Type | Default Value | Description |
+  ///     | ------ | ---- | ------------- | ----------- |
+  ///     | `ifExists` | `boolean` | `false` | Add an `IF EXISTS` clause to the drop table statement. |
+  ///     | `cascade` | `boolean` | `true` | Add a `CASCADE` clause to the drop table statement (destroying rows in other tables defined by foreign key constraints). |
+  ///
+  /// Return: undefined
+  ///   This method returns nothing.
   async dropTable(Model, options) {
     let queryGenerator  = this.getQueryGenerator();
     let createTableSQL  = queryGenerator.generateDropTableStatement(Model, options);
 
     // Drop table
-    return await this.query(createTableSQL, options);
+    await this.query(createTableSQL, options);
   }
 
+  /// Create the table/bucket defined by `Model`.
+  ///
+  /// Note:
+  ///   Mythix ORM always refers to data-spaces as "tables", even though
+  ///   they might actually be "buckets" for example for no-SQL databases.
+  ///
+  /// Arguments:
+  ///   Model: class [Model](https://github.com/th317erd/mythix-orm/wiki/Model)
+  ///     The model that defines the table to be created.
+  ///   options?: object
+  ///     Though these options can be database specific, they are commonly just
+  ///     the following options.
+  ///     | Option | Type | Default Value | Description |
+  ///     | ------ | ---- | ------------- | ----------- |
+  ///     | `ifNotExists` | `boolean` | `false` | Add an `IF NOT EXISTS` clause to the create table statement. |
+  ///
+  /// Return: undefined
+  ///   This method returns nothing.
   async createTable(Model, options) {
     let queryGenerator  = this.getQueryGenerator();
     let createTableSQL  = queryGenerator.generateCreateTableStatement(Model, options);
 
     // Create table
-    let result = await this.query(createTableSQL, options);
+    await this.query(createTableSQL, options);
 
     // Create indexes and constraints
     let trailingStatements = Nife.toArray(queryGenerator.generateCreateTableStatementOuterTail(Model, options)).filter(Boolean);
@@ -366,8 +589,6 @@ class SQLConnectionBase extends ConnectionBase {
         await this.query(trailingStatement, options);
       }
     }
-
-    return result;
   }
 
   async insert(Model, models, _options) {
@@ -558,6 +779,19 @@ class SQLConnectionBase extends ConnectionBase {
     return this.getUpdateOrDeleteChangeCount(await this.query(sqlStr, options));
   }
 
+  /// Convert the raw `{ rows: Array<any>; columns: Array<string>; }` results
+  /// from a database into an array of mapped objects.
+  ///
+  /// This method simply takes the rows and columns reported by the database
+  /// for a `SELECT` operation, and maps them to objects, where each key is
+  /// a column name, and each value is a column from one of the returned rows.
+  ///
+  /// Arguments:
+  ///   result: { rows: Array<any>; columns: Array<string>; }
+  ///     The raw results as returned by the database.
+  ///
+  /// Return: Array<object>
+  ///   The raw results from the database, with each row mapped to an object.
   queryResultRowsToRawData(result) {
     if (!result)
       return [];
@@ -614,6 +848,10 @@ class SQLConnectionBase extends ConnectionBase {
 
     let batchSize   = options.batchSize || 500;
     let startIndex  = queryContext.offset || 0;
+    let limit       = queryContext.limit;
+
+    if (Nife.instanceOf(limit, 'number') && isFinite(limit) && limit < batchSize)
+      batchSize = limit;
 
     while (true) {
       let query         = queryEngine.clone().LIMIT(batchSize).OFFSET(startIndex);

package/lib/sql-query-generator-base.d.ts

@@ -55,7 +55,6 @@ declare class SQLQueryGeneratorBase extends QueryGeneratorBase {
   public getEscapedTableName(modelOrField: ModelClass | Field, options?: GetEscapedTableNameNameOptions): string;
   public getEscapedProjectionName(Model: ModelClass | null | undefined, field: Field, options?: GetEscapedProjectionNameOptions): string;
   public getEscapedModelFields(Model: ModelClass, options?: GetEscapedModelFieldsOptions): { [key: string]: string };
-  public isFieldIdentifier(value: string): boolean;
   public getProjectedFields(queryEngine: QueryEngine, options?: GenericObject, asMap?: false | undefined): Array<string>;
   public getProjectedFields(queryEngine: QueryEngine, options?: GenericObject, asMap?: true): Map<string, string>;
 
@@ -67,21 +66,13 @@ declare class SQLQueryGeneratorBase extends QueryGeneratorBase {
   ): JoinTableInfo;
 
   public prepareArrayValuesForSQL(array: Array<any>): Array<any>;
-  public parseFieldProjection(value: string, getRawField: boolean): string | Field | undefined;
-  public parseFieldProjectionToFieldMap(selectStatement: string): Map<string, Field | string>;
 
   public generateSelectQueryFieldProjection(
     queryEngine: QueryEngine,
     options?: GenericObject,
-    asMap?: false | undefined,
+    projectedFields?: Map<string, string>,
   ): Array<string>;
 
-  public generateSelectQueryFieldProjection(
-    queryEngine: QueryEngine,
-    options?: GenericObject,
-    asMap?: true,
-  ): Map<string, string>;
-
   public generateSelectQueryOperatorFromQueryEngineOperator(
     queryPart: GenericObject,
     operator: string | LiteralBase,
@@ -174,7 +165,7 @@ declare class SQLQueryGeneratorBase extends QueryGeneratorBase {
 
   public generateInsertStatementTail(
     Model: ModelClass,
-    model: Model,
+    models: Model | Array<Model> | PreparedModels,
     options: GenericObject,
     context: {
       escapedTableName: string,
@@ -225,9 +216,9 @@ declare class SQLQueryGeneratorBase extends QueryGeneratorBase {
   public generateAddColumnStatement(field: Field, options?: GenericObject): string;
 
   public _collectRemoteReturningFields(Model: ModelClass): Array<string>;
-  public _collectReturningFields(
+  public generateReturningClause(
     Model: ModelClass,
-    model: Model,
+    models: Model | Array<Model> | PreparedModels,
     options: GenericObject,
     context: {
       escapedTableName: string,