mythix-orm-sql-base 1.10.1 → 1.11.0

package/lib/sql-query-generator-base.js

@@ -15,6 +15,12 @@ const DefaultHelpers  = Types.DefaultHelpers;
 const LiteralBase     = Literals.LiteralBase;
 
 /// The "base" SQL generator for all SQL-type databases.
+///
+/// This class is used to generate SQL statements for the
+/// underlying SQL database. Database drivers can and often
+/// will create their own class that extends from this class.
+///
+/// Extends: [QueryGeneratorBase](https://github.com/th317erd/mythix-orm/wiki/QueryGeneratorBase)
 class SQLQueryGeneratorBase extends QueryGeneratorBase {
   /// Escape a field name, usually for a projection alias.
   /// This method is primarily used for generating aliases
@@ -3045,6 +3051,20 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
     return `TRUNCATE TABLE ${escapedTableName}`;
   }
 
+  /// Generate an `ALTER TABLE` statement
+  /// to rename the table.
+  ///
+  /// Arguments:
+  ///   Model: class [Model](https://github.com/th317erd/mythix-orm/wiki/Model)
+  ///     The model that defines the table being altered.
+  ///   newModelAttributes: object
+  ///     An object that contains a `tableName` key for the new table name
+  ///   options?: object
+  ///     Options for the operation.
+  ///
+  /// Return: Array<string>
+  ///   An array of `ALTER TABLE` statements to change the table's name. For
+  ///   most databases this will probably only be a single statement.
   generateAlterTableStatement(Model, newModelAttributes, options) {
     if (Nife.isEmpty(newModelAttributes))
       return [];
@@ -3060,6 +3080,23 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
     return statements;
   }
 
+  /// Generate an `ALTER TABLE ... DROP COLUMN` statement.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to drop from the database.
+  ///   options?:
+  ///     Options for the operation. Though these might contain
+  ///     database specific options, generic options that should
+  ///     work for most databases are:
+  ///     | Option | Type | Default Value | Description |
+  ///     | ------ | ---- | ------------- | ----------- |
+  ///     | `ifExists` | `boolean` | `false` | If `true`, then add an `IF EXISTS` clause to the `ALTER TABLE` statement. |
+  ///     | `cascade` | `boolean` | `true` | If `true`, then add a `CASCADE` clause to the `ALTER TABLE` statement. |
+  ///
+  /// Return: string
+  ///   An `ALTER TABLE` statement to drop the column specified
+  ///   by the provided `field`.
   generateDropColumnStatement(field, _options) {
     let Model   = field.Model;
     let options = _options || {};
@@ -3067,15 +3104,46 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
     return `ALTER TABLE ${this.getEscapedTableName(Model, options)} DROP COLUMN${(options.ifExists) ? ' IF EXISTS' : ''} ${this.getEscapedColumnName(Model, field, { ...options, columnNameOnly: true })} ${(options.cascade !== false) ? 'CASCADE' : 'RESTRICT'}`;
   }
 
+  /// Generate an `ALTER TABLE ... RENAME COLUMN` statement.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to rename in the database.
+  ///   newField: object | [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     A raw object containing a `columnName` or `fieldName` properties, or a `Field` instance
+  ///     containing a `columnName` or `fieldName`. This will be used as the new name
+  ///     of the column.
+  ///   options?:
+  ///     Options for the operation.
+  ///
+  /// Return: string
+  ///   An `ALTER TABLE` statement to rename the column specified
+  ///   by the provided `field`.
   generateAlterColumnRenameStatement(field, newField, _options) {
     let Model             = field.Model;
     let options           = _options || {};
     let prefix            = `ALTER TABLE ${this.getEscapedTableName(Model, options)}`;
     let escapedColumnName = this.getEscapedColumnName(Model, field, { ...options, columnNameOnly: true });
 
-    return `${prefix} RENAME COLUMN ${escapedColumnName} TO ${this.escapeID(newField.columnName)}`;
+    return `${prefix} RENAME COLUMN ${escapedColumnName} TO ${this.escapeID(newField.columnName || newField.fieldName)}`;
   }
 
+  /// Generate an `ALTER TABLE` statement to add or remove
+  /// a `NOT NULL` constraint on the specified `field`.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to add or remove the constraint from in the database.
+  ///   newField: object | [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     A raw object containing an `allowNull` property, or a `Field` instance
+  ///     containing a `allowNull` property. If `true`, then a `NOT NULL` constraint
+  ///     will be added. If `false`, then any `NOT NULL` constraint will be dropped.
+  ///   options?:
+  ///     Options for the operation.
+  ///
+  /// Return: string
+  ///   An `ALTER TABLE` statement to add or remove the `NOT NULL` constraint
+  ///   of the specified `field`.
   generateAlterColumnSetOrDropNullConstraintStatement(field, newField, _options) {
     let Model             = field.Model;
     let options           = _options || {};
@@ -3085,6 +3153,26 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
     return `${prefix} ALTER COLUMN ${escapedColumnName} ${(newField.allowNull) ? 'DROP' : 'SET'} NOT NULL`;
   }
 
+  /// Generate an `ALTER TABLE` statement to add or remove
+  /// a `DEFAULT` value for the specified `field`.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to add or remove the `DEFAULT` value from in the database.
+  ///   newField: object | [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     A raw object or a `Field` instance defining how the field is being altered.
+  ///     This argument is not used by this method, but is passed through when calling
+  ///     other alter table generators.
+  ///   newDefaultValue: any
+  ///     The new `DEFAULT` value to apply to the column. If this argument is `undefined`,
+  ///     then any `DEFAULT` value applied to the column will be dropped. This value must
+  ///     already be escaped and ready for the underlying database to consume.
+  ///   options?:
+  ///     Options for the operation.
+  ///
+  /// Return: string
+  ///   An `ALTER TABLE ... ALTER COLUMN ... DROP | SET DEFAULT` statement to add or set
+  ///   a `DEFAULT` value for this column.
   generateAlterColumnSetDefaultStatement(field, newField, newDefaultValue, _options) {
     let Model             = field.Model;
     let options           = _options || {};
@@ -3097,6 +3185,25 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
       return `${prefix} ALTER COLUMN ${escapedColumnName} SET DEFAULT ${newDefaultValue}`;
   }
 
+  /// Generate an `ALTER TABLE` statement to change the
+  /// type of the `field` specified.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to change the type on in the database.
+  ///   newField: object | [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     A raw object or a `Field` instance defining how the field is being altered.
+  ///     This argument is not used by this method, but is passed through when calling
+  ///     other alter table generators.
+  ///   newFieldType: string
+  ///     The new type to change the field/column to. This must be a raw type that
+  ///     the underlying database supports, in database format.
+  ///   options?:
+  ///     Options for the operation.
+  ///
+  /// Return: string
+  ///   An `ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE` statement to alter
+  ///   the column's data type.
   generateAlterColumnChangeTypeStatement(field, newField, newFieldType, _options) {
     let Model             = field.Model;
     let options           = _options || {};
@@ -3106,6 +3213,22 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
     return `${prefix} ALTER COLUMN ${escapedColumnName} SET DATA TYPE ${newFieldType}`;
   }
 
+  /// Generate an `ALTER TABLE` statement to add or remove
+  /// a `PRIMARY KEY` constraint on the specified `field`.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to add or remove the constraint from in the database.
+  ///   newField: object | [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     A raw object containing an `primaryKey` property, or a `Field` instance
+  ///     containing a `primaryKey` property. If `true`, then a `PRIMARY KEY` constraint
+  ///     will be added. If `false`, then any `PRIMARY KEY` constraint will be dropped.
+  ///   options?:
+  ///     Options for the operation.
+  ///
+  /// Return: string
+  ///   An `ALTER TABLE` statement to add or remove the `PRIMARY KEY` constraint
+  ///   of the specified `field`.
   generateAlterColumnChangePrimaryKeyConstraintStatement(field, newField, _options) {
     let Model             = field.Model;
     let options           = _options || {};
@@ -3118,6 +3241,22 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
       return `${prefix} ALTER COLUMN ${escapedColumnName} DROP CONSTRAINT PRIMARY KEY`;
   }
 
+  /// Generate an `ALTER TABLE` statement to add or remove
+  /// a `UNIQUE` constraint on the specified `field`.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to add or remove the constraint from in the database.
+  ///   newField: object | [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     A raw object containing an `unique` property, or a `Field` instance
+  ///     containing a `unique` property. If `true`, then a `UNIQUE` constraint
+  ///     will be added. If `false`, then any `UNIQUE` constraint will be dropped.
+  ///   options?:
+  ///     Options for the operation.
+  ///
+  /// Return: string
+  ///   An `ALTER TABLE` statement to add or remove a `UNIQUE` constraint
+  ///   of the specified `field`.
   generateAlterColumnChangeUniqueConstraintStatement(field, newField, _options) {
     let Model             = field.Model;
     let options           = _options || {};
@@ -3130,6 +3269,28 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
       return `${prefix} ALTER COLUMN ${escapedColumnName} DROP CONSTRAINT UNIQUE`;
   }
 
+  /// Generate multiple `ALTER TABLE` statements to change the
+  /// `field` provided to match the `newFieldAttributes` provided.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to alter in the database.
+  ///   newFieldAttributes: object | [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     A raw object containing field properties, or a `Field` instance. Any differing
+  ///     properties between these two "fields" will generate an `ALTER TABLE` statement
+  ///     for that difference. For example, if the `columnName` between both "fields" is
+  ///     different, then an `ALTER TABLE` statement will be generated to change the column's
+  ///     name. Properties that are checked for differences are: `primaryKey`, `unique`, `index`,
+  ///     `columnName` & `fieldName`, `allowNull`, `type`, and `defaultValue`. If any of these
+  ///     differ between the two provided "fields", then an `ALTER TABLE` statement will be generated
+  ///     to update the column to match the new properties of `newFieldAttributes`.
+  ///   options?:
+  ///     Options for the operation.
+  ///
+  /// Return: Array<string>
+  ///   Multiple `ALTER TABLE` statements to alter the specified `field`
+  ///   to match the new properties defined by `newFieldAttributes`. If
+  ///   no changes are detected, then an empty array will be returned instead.
   generateAlterColumnStatements(field, _newFieldAttributes, _options) {
     if (Nife.isEmpty(_newFieldAttributes))
       return [];
@@ -3225,6 +3386,22 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
     return statements.filter(Boolean);
   }
 
+  /// Generate an `ALTER TABLE ... ADD COLUMN` statement.
+  ///
+  /// Arguments:
+  ///   field: [Field](https://github.com/th317erd/mythix-orm/wiki/Field)
+  ///     The field to add to the database.
+  ///   options?:
+  ///     Options for the operation. Though these might contain
+  ///     database specific options, generic options that should
+  ///     work for most databases are:
+  ///     | Option | Type | Default Value | Description |
+  ///     | ------ | ---- | ------------- | ----------- |
+  ///     | `ifNotExists` | `boolean` | `false` | If `true`, then add an `IF NOT EXISTS` clause to the `ALTER TABLE` statement. |
+  ///
+  /// Return: string
+  ///   An `ALTER TABLE ... ADD COLUMN` statement to add the column specified
+  ///   by the provided `field`.
   generateAddColumnStatement(field, _options) {
     let Model   = field.Model;
     let options = _options || {};
@@ -3233,6 +3410,22 @@ class SQLQueryGeneratorBase extends QueryGeneratorBase {
     return `${prefix} ADD COLUMN${(options.ifNotExists) ? ' IF NOT EXISTS' : ''} ${this.generateColumnDeclarationStatement(Model, field, options)}`;
   }
 
+  /// Convert the provided `queryEngine` into
+  /// a `SELECT` statement.
+  ///
+  /// This is similar to a `toSQL` method in other ORMs.
+  /// It is usually called directly from the `queryEngine` itself,
+  /// i.e. `queryEngine.toString()` will call this method.
+  ///
+  /// Arguments:
+  ///   queryEngine: [QueryEngine](https://github.com/th317erd/mythix-orm/wiki/QueryEngine)
+  ///     The query engine to use to generate a `SELECT` statement.
+  ///   options?: object
+  ///     Options for the operation. These are simply passed off to <see>SQLQueryGeneratorBase.generateSelectStatement</see>.
+  ///
+  /// Return: string
+  ///   A fully formatted `SELECT` statement, that was generated from
+  ///   the provided `queryEngine`.
   toConnectionString(queryEngine, options) {
     return this.generateSelectStatement(queryEngine, options);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythix-orm-sql-base",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "SQL base support for Mythix ORM",
   "main": "lib/index",
   "type": "commonjs",
@@ -34,7 +34,7 @@
   },
   "homepage": "https://github.com/th317erd/mythix-orm-sql-base#readme",
   "peerDependencies": {
-    "mythix-orm": "^1.12.0"
+    "mythix-orm": "^1.13.1"
   },
   "dependencies": {
     "luxon": "^3.1.0",