velocious 1.0.85 → 1.0.87

package/src/database/migrator.js

@@ -1,10 +1,15 @@
 import {digg} from "diggerize"
 import * as inflection from "inflection"
 import {Logger} from "../logger.js"
+import restArgsError from "../utils/rest-args-error.js"
 import TableData from "./table-data/index.js"
 
 export default class VelociousDatabaseMigrator {
-  constructor({configuration}) {
+  constructor({configuration, ...restArgs}) {
+    restArgsError(restArgs)
+
+    if (!configuration) throw new Error("configuration argument is required")
+
     this.configuration = configuration
     this.logger = new Logger(this)
   }
@@ -62,13 +67,21 @@ export default class VelociousDatabaseMigrator {
           requireMigration: async () => {
             const migrationImport = await importCallback(migration.fullPath)
 
-            return migrationImport.default
+            if (!migrationImport) {
+              throw new Error(`Migration file must export migration class: ${migration.fullPath}`)
+            }
+
+            return migrationImport
           }
         })
       }
     })
   }
 
+  /**
+   * @param {*} requireContext
+   * @returns {Promise<void>}
+   */
   async migrateFilesFromRequireContext(requireContext) {
     const files = requireContext
       .keys()
@@ -111,6 +124,9 @@ export default class VelociousDatabaseMigrator {
     })
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async loadMigrationsVersions() {
     this.migrationsVersions = {}
 
@@ -142,6 +158,9 @@ export default class VelociousDatabaseMigrator {
     }
   }
 
+  /**
+   * @returns {Promise<boolean>}
+   */
   async migrationsTableExist(db) {
     const schemaTable = await db.getTableByName("schema_migrations", {throwError: false})
 
@@ -150,10 +169,12 @@ export default class VelociousDatabaseMigrator {
     return true
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async executeRequireContext(requireContext) {
     const migrationFiles = requireContext.keys()
-
-    files = migrationFiles
+    const files = migrationFiles
       .map((file) => {
         const match = file.match(/^(\d{14})-(.+)\.js$/)
 
@@ -165,7 +186,7 @@ export default class VelociousDatabaseMigrator {
 
         return {
           file,
-          fullPath: `${migrationsPath}/${file}`,
+          fullPath: `${migrationsPath}/${file}`, // eslint-disable-line no-undef
           date,
           migrationClassName
         }
@@ -181,6 +202,9 @@ export default class VelociousDatabaseMigrator {
     }
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async reset() {
     const dbs = await this.configuration.getCurrentConnections()
 
@@ -205,7 +229,7 @@ export default class VelociousDatabaseMigrator {
             }
 
             break
-          } catch (error) {
+          } catch (error) { // eslint-disable-line no-unused-vars
             if (errors.length > 0 && anyTableDropped) {
               // Retry
             } else {
@@ -217,13 +241,69 @@ export default class VelociousDatabaseMigrator {
     }
   }
 
-  async runMigrationFile({migration, requireMigration}) {
+  /**
+   * @param {{date: number}[]} files
+   * @param {function(string) : void} importCallback Function to import a file
+   * @returns {Promise<void>}
+   */
+  async rollback(files, importCallback) {
+    const latestMigrationVersion = await this._latestMigrationVersion()
+
+    if (!latestMigrationVersion) {
+      throw new Error("No migrations have been run yet")
+    }
+
+    const latestMigrationVersionNumber = parseInt(latestMigrationVersion)
+    const migration = files.find((file) => file.date == latestMigrationVersionNumber)
+
+    if (!migration) {
+      throw new Error(`Migration file for version ${latestMigrationVersionNumber} not found`)
+    }
+
+    await this.runMigrationFile({
+      migration,
+      requireMigration: async () => await importCallback(migration.fullPath),
+      direction: "down"
+    })
+  }
+
+  /**
+   * @returns {Promise<string | null>} The latest migration version
+   */
+  async _latestMigrationVersion() {
+    if (!this.migrationsVersions) await this.loadMigrationsVersions()
+
+    let highestVersion
+
+    for (const dbIdentifier in this.migrationsVersions) {
+      for (const migrationVersion in this.migrationsVersions[dbIdentifier]) {
+        if (!highestVersion || migrationVersion > highestVersion) {
+          highestVersion = migrationVersion
+        }
+      }
+    }
+
+    return highestVersion
+  }
+
+  /**
+   * @param {object} args
+   * @param {object} args.migration
+   * @param {function() : void} args.requireMigration
+   * @param {string} args.direction
+   */
+  async runMigrationFile({migration, requireMigration, direction = "up"}) {
     if (!this.configuration) throw new Error("No configuration set")
     if (!this.configuration.isDatabasePoolInitialized()) await this.configuration.initializeDatabasePool()
     if (!this.migrationsVersions) await this.loadMigrationsVersions()
 
     const dbs = await this.configuration.getCurrentConnections()
     const migrationClass = await requireMigration()
+
+    if (!migrationClass || typeof migrationClass !== "function") {
+      throw new Error(`Migration ${migration.file} must export a default migration class. Type: ${typeof migrationClass}`)
+    }
+
     const migrationDatabaseIdentifiers = migrationClass.getDatabaseIdentifiers() || ["default"]
 
     for (const dbIdentifier in dbs) {
@@ -239,9 +319,18 @@ export default class VelociousDatabaseMigrator {
         continue
       }
 
-      if (this.hasRunMigrationVersion(dbIdentifier, migration.date)) {
-        this.logger.debug(`${dbIdentifier} has already run migration ${migration.file}`)
-        continue
+      if (direction == "up") {
+        if (this.hasRunMigrationVersion(dbIdentifier, migration.date)) {
+          this.logger.debug(`${dbIdentifier} has already run migration ${migration.file}`)
+          continue
+        }
+      } else if (direction == "down") {
+        if (!this.hasRunMigrationVersion(dbIdentifier, migration.date)) {
+          this.logger.debug(`${dbIdentifier} hasn't run migration ${migration.file}`)
+          continue
+        }
+      } else {
+        throw new Error(`Unknown direction: ${direction}`)
       }
 
       this.logger.debug(`Running migration on ${dbIdentifier}: ${migration.file}`, {migrationDatabaseIdentifiers})
@@ -252,23 +341,35 @@ export default class VelociousDatabaseMigrator {
         configuration: this.configuration,
         db
       })
+      const dateString = `${digg(migration, "date")}`
+
+      if (direction == "up") {
+        if (migrationInstance.change) {
+          await migrationInstance.change()
+        } else if (migrationInstance.up) {
+          await migrationInstance.up()
+        } else {
+          throw new Error(`'change' or 'up' didn't exist on migration: ${migration.file}`)
+        }
 
-      if (migrationInstance.change) {
-        await migrationInstance.change()
-      } else if (migrationInstance.up) {
-        await migrationInstance.up()
-      } else {
-        throw new Error(`'change' or 'up' didn't exist on migration: ${migration.file}`)
-      }
+        const existingSchemaMigrations = await db.newQuery()
+          .from("schema_migrations")
+          .where({version: dateString})
+          .results()
 
-      const dateString = digg(migration, "date")
-      const existingSchemaMigrations = await db.newQuery()
-        .from("schema_migrations")
-        .where({version: `${dateString}`})
-        .results()
+        if (existingSchemaMigrations.length == 0) {
+          await db.insert({tableName: "schema_migrations", data: {version: dateString}})
+        }
+      } else if (direction == "down") {
+        if (migrationInstance.down) {
+          await migrationInstance.down()
+        } else {
+          throw new Error(`'down' didn't exist on migration: ${migration.file}`)
+        }
 
-      if (existingSchemaMigrations.length == 0) {
-        await db.insert({tableName: "schema_migrations", data: {version: dateString}})
+        await db.delete({tableName: "schema_migrations", conditions: {version: dateString}})
+      } else {
+        throw new Error(`Unknown direction: ${direction}`)
       }
     }
   }

package/src/database/pool/single-multi-use.js

@@ -1,7 +1,7 @@
 import BasePool from "./base.js"
 
 export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
-  checkin(connection) {
+  checkin(connection) { // eslint-disable-line no-unused-vars
     // Do nothing
   }
 

package/src/database/query/alter-table-base.js

@@ -4,6 +4,12 @@ import restArgsError from "../../utils/rest-args-error.js"
 import TableData from "../table-data/index.js"
 
 export default class VelociousDatabaseQueryAlterTableBase extends QueryBase {
+  /**
+   * @param {object} args
+   * @template Tdriver extends import("../driver/base.js").default
+   * @param {Tdriver} args.driver
+   * @param {TableData} args.tableData
+   */
   constructor({driver, tableData, ...restArgs}) {
     restArgsError(restArgs)
 
@@ -13,6 +19,9 @@ export default class VelociousDatabaseQueryAlterTableBase extends QueryBase {
     this.tableData = tableData
   }
 
+  /**
+   * @returns {string[]}
+   */
   toSqls() {
     const databaseType = this.getDriver().getType()
     const sqls = []
@@ -30,6 +39,8 @@ export default class VelociousDatabaseQueryAlterTableBase extends QueryBase {
         sql += column.getSQL({driver: this.getDriver(), forAlterTable: true})
       } else if (column.getNewName()) {
         sql += `RENAME COLUMN ${options.quoteColumnName(column.getName())} TO ${options.quoteColumnName(column.getNewName())}`
+      } else if (column.getDropColumn()) {
+        sql += `DROP COLUMN ${options.quoteColumnName}`
       } else {
         if (databaseType == "mssql" || databaseType == "pgsql") {
           sql += "ALTER COLUMN "

package/src/database/query/base.js

@@ -18,6 +18,9 @@ export default class VelociousDatabaseQueryBase {
     return this._driver
   }
 
+  /**
+   * @returns {import("../query-parser/options.js").default}
+   */
   getOptions() {
     return this._options
   }
@@ -26,6 +29,10 @@ export default class VelociousDatabaseQueryBase {
     return this.getDriver().getType()
   }
 
+  /**
+   * @interface
+   * @returns {string[]}
+   */
   toSql() {
     throw new Error("'toSql' wasn't implemented")
   }

package/src/database/query/create-database-base.js

@@ -7,6 +7,9 @@ export default class VelociousDatabaseQueryCreateDatabaseBase extends QueryBase
     this.ifNotExists = ifNotExists
   }
 
+  /**
+   * @returns {string[]}
+   */
   toSql() {
     const {databaseName} = this
     let sql = "CREATE DATABASE"

package/src/database/query/create-index-base.js

@@ -1,4 +1,3 @@
-import {digs} from "diggerize"
 import QueryBase from "./base.js"
 
 export default class VelociousDatabaseQueryCreateIndexBase extends QueryBase {
@@ -35,6 +34,9 @@ export default class VelociousDatabaseQueryCreateIndexBase extends QueryBase {
     return indexName
   }
 
+  /**
+   * @returns {string}
+   */
   toSql() {
     const databaseType = this.getDriver().getType()
     const indexName = this.name || this.generateIndexName()

package/src/database/query/create-table-base.js

@@ -14,6 +14,9 @@ export default class VelociousDatabaseQueryCreateTableBase extends QueryBase {
     this.tableData = tableData
   }
 
+  /**
+   * @returns {string[]}
+   */
   toSql() {
     const databaseType = this.getDatabaseType()
     const driver = this.getDriver()

package/src/database/query/drop-table-base.js

@@ -13,6 +13,9 @@ export default class VelociousDatabaseQueryDropTableBase extends QueryBase {
     this.tableName = tableName
   }
 
+  /**
+   * @returns {string[]}
+   */
   toSql() {
     const databaseType = this.getDatabaseType()
     const options = this.getOptions()
@@ -40,6 +43,6 @@ export default class VelociousDatabaseQueryDropTableBase extends QueryBase {
 
     sqls.push(sql)
 
-    return [sql]
+    return sqls
   }
 }

package/src/database/query/from-base.js

@@ -1,8 +1,15 @@
 export default class VelociousDatabaseQueryFromBase {
+  /**
+   * @returns {import("../query-parser/options.js").default}
+   */
   getOptions() {
     return this.query.getOptions()
   }
 
+  /**
+   * @interface
+   * @returns {string[]}
+   */
   toSql() {
     throw new Error("'toSql' wasn't implemented")
   }

package/src/database/query/index.js

@@ -35,6 +35,9 @@ export default class VelociousDatabaseQuery {
     this._wheres = wheres
   }
 
+  /**
+   * @returns {VelociousDatabaseQuery}
+   */
   clone() {
     const newQuery = new VelociousDatabaseQuery({
       driver: this.driver,
@@ -56,6 +59,9 @@ export default class VelociousDatabaseQuery {
     return newQuery
   }
 
+  /**
+   * @returns {Promise<number>}
+   */
   async count() {
     // Generate count SQL
     let sql = `COUNT(${this.driver.quoteTable(this.modelClass.tableName())}.${this.driver.quoteColumn(this.modelClass.primaryKey())})`
@@ -94,8 +100,14 @@ export default class VelociousDatabaseQuery {
     return countResult
   }
 
+  /**
+   * @returns {import("../query-parser/options.js").default}
+   */
   getOptions() { return this.driver.options() }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async destroyAll() {
     const records = await this.toArray()
 
@@ -104,6 +116,10 @@ export default class VelociousDatabaseQuery {
     }
   }
 
+  /**
+   * @param {number|string} recordId
+   * @returns {Promise<InstanceType<this["modelClass"]>>}
+   */
   async find(recordId) {
     const conditions = {}
 
@@ -119,6 +135,10 @@ export default class VelociousDatabaseQuery {
     return record
   }
 
+  /**
+   * @param {object} conditions
+   * @returns {Promise<InstanceType<this["modelClass"]>>}
+   */
   async findBy(conditions) {
     const newConditions = {}
 
@@ -131,6 +151,10 @@ export default class VelociousDatabaseQuery {
     return await this.clone().where(newConditions).first()
   }
 
+  /**
+   * @param {...Parameters<this["findOrInitializeBy"]>} args
+   * @returns {Promise<InstanceType<this["modelClass"]>>}
+   */
   async findOrCreateBy(...args) {
     const record = await this.findOrInitializeBy(...args)
 
@@ -141,6 +165,10 @@ export default class VelociousDatabaseQuery {
     return record
   }
 
+  /**
+   * @param {object} conditions
+   * @returns {Promise<InstanceType<this["modelClass"]>>}
+   */
   async findByOrFail(conditions) {
     const newConditions = {}
 
@@ -159,6 +187,11 @@ export default class VelociousDatabaseQuery {
     return model
   }
 
+  /**
+   * @param {object} conditions
+   * @param {function() : void} callback
+   * @returns {Promise<InstanceType<this["modelClass"]>>}
+   */
   async findOrInitializeBy(conditions, callback) {
     const record = await this.findBy(conditions)
 
@@ -173,6 +206,9 @@ export default class VelociousDatabaseQuery {
     return newRecord
   }
 
+  /**
+   * @returns {Promise<InstanceType<this["modelClass"]>>}
+   */
   async first() {
     const newQuery = this.clone().limit(1).reorder(`${this.driver.quoteTable(this.modelClass.tableName())}.${this.driver.quoteColumn(this.modelClass.orderableColumn())}`)
     const results = await newQuery.toArray()
@@ -180,6 +216,10 @@ export default class VelociousDatabaseQuery {
     return results[0]
   }
 
+  /**
+   * @param {string|FromPlain} from
+   * @returns {this}
+   */
   from(from) {
     if (typeof from == "string") from = new FromPlain({plain: from, query: this})
 
@@ -189,11 +229,19 @@ export default class VelociousDatabaseQuery {
     return this
   }
 
+  /**
+   * @param {string} group
+   * @returns {this}
+   */
   group(group) {
     this._groups.push(group)
     return this
   }
 
+  /**
+   * @param {string|JoinPlain} join
+   * @returns {this}
+   */
   joins(join) {
     if (typeof join == "string") {
       join = new JoinPlain({plain: join, query: this})
@@ -207,6 +255,9 @@ export default class VelociousDatabaseQuery {
     return this
   }
 
+  /**
+   * @returns {Promise<InstanceType<this["modelClass"]>>}
+   */
   async last() {
     const primaryKey = this.modelClass.primaryKey()
     const tableName = this.modelClass.tableName()
@@ -215,16 +266,28 @@ export default class VelociousDatabaseQuery {
     return results[0]
   }
 
+  /**
+   * @param {number} value
+   * @returns {this}
+   */
   limit(value) {
     this._limit = value
     return this
   }
 
+  /**
+   * @param {number} value
+   * @returns {this}
+   */
   offset(value) {
     this._offset = value
     return this
   }
 
+  /**
+   * @param {*} order
+   * @returns {this}
+   */
   order(order) {
     if (typeof order == "number" || typeof order == "string") order = new OrderPlain({plain: order, query: this})
 
@@ -234,6 +297,10 @@ export default class VelociousDatabaseQuery {
     return this
   }
 
+  /**
+   * @param {number} pageNumber
+   * @returns {this}
+   */
   page(pageNumber) {
     const perPage = this._perPage || 30
     const offset = (pageNumber - 1) * perPage
@@ -245,22 +312,37 @@ export default class VelociousDatabaseQuery {
     return this
   }
 
+  /**
+   * @param {number} perPage
+   * @returns {this}
+   */
   perPage(perPage) {
     this._perPage = perPage
     return this
   }
 
+  /**
+   * @param {string} data
+   * @returns {this}
+   */
   preload(data) {
     incorporate(this._preload, data)
     return this
   }
 
+  /**
+   * @param {string|OrderPlain} order
+   * @returns {this}
+   */
   reorder(order) {
     this._orders = []
     this.order(order)
     return this
   }
 
+  /**
+   * @returns {this}
+   */
   reverseOrder() {
     for (const order of this._orders) {
       order.setReverseOrder(true)
@@ -269,6 +351,10 @@ export default class VelociousDatabaseQuery {
     return this
   }
 
+  /**
+   * @param {string|SelectPlain} select
+   * @returns {this}
+   */
   select(select) {
     if (Array.isArray(select)) {
       for (const selectInArray of select) {
@@ -286,23 +372,28 @@ export default class VelociousDatabaseQuery {
     return this
   }
 
+  /**
+   * @returns {Promise<Array<object>>} Array of results from the database
+   */
   async _executeQuery() {
     const sql = this.toSql()
     const results = await this.driver.query(sql)
 
-    this.logger.debug("SQL:", sql)
+    this.logger.debug(() => ["SQL:", sql])
 
     return results
   }
 
+  /**
+   * @returns {Promise<Array<object>>} Array of results from the database
+   */
   async results() {
     return await this._executeQuery()
   }
 
   /**
    * Converts query results to array of model instances
-   *
-   * @returns {Promise<Array>} Array of model instances
+   * @returns {Promise<Array<InstanceType<this["modelClass"]>>>}
    */
   async toArray() {
     const models = []
@@ -330,13 +421,12 @@ export default class VelociousDatabaseQuery {
 
   /**
    * Generates SQL string representing this query
-   *
-   * @returns {String} SQL string representing this query
+   * @returns {string} SQL string representing this query
    */
   toSql() { return this.driver.queryToSql(this) }
 
   /**
-   * @param {Object|String} where
+   * @param {object|string} where
    * @returns {VelociousDatabaseQuery} This query instance
    */
   where(where) {

package/src/database/query/insert-base.js

@@ -16,10 +16,16 @@ export default class VelociousDatabaseQueryInsertBase {
     this.tableName = tableName
   }
 
+  /**
+   * @returns {import("../query-parser/options.js").default}
+   */
   getOptions() {
     return this.driver.options()
   }
 
+  /**
+   * @returns {string} SQL statement
+   */
   toSql() {
     const {driver} = this
 

package/src/database/query/join-base.js

@@ -1,4 +1,7 @@
 export default class VelociousDatabaseQueryJoinBase {
+  /**
+   * @returns {import("../query-parser/options.js").default}
+   */
   getOptions() {
     return this.query.driver.options()
   }

package/src/database/query/order-base.js

@@ -1,4 +1,7 @@
 export default class VelociousDatabaseQueryOrderBase {
+  /**
+   * @returns {import("../query-parser/options.js").default}
+   */
   getOptions() {
     return this.query.driver.options()
   }

package/src/database/query/select-base.js

@@ -1,4 +1,7 @@
 export default class VelociousDatabaseQuerySelectBase {
+  /**
+   * @returns {import("../query-parser/options.js").default}
+   */
   getOptions() {
     return this.query.driver.options()
   }