velocious 1.0.97 → 1.0.98

package/src/database/drivers/base.js

@@ -1,3 +1,37 @@
+// @ts-check
+
+/**
+ * @typedef {object} CreateIndexSqlArgs
+ * @property {Array<string | import("./../table-data/table-column.js").default>} columns
+ * @property {boolean} [ifNotExists]
+ * @property {string} [name]
+ * @property {boolean} [unique]
+ * @property {string} tableName
+ */
+/**
+ * @typedef {object} DropTableSqlArgsType
+ * @property {boolean} [cascade]
+ * @property {boolean} [ifExists]
+ */
+/**
+ * @typedef {object} DeleteSqlArgsType
+ * @property {string} tableName
+ * @property {{[key: string]: any}} conditions
+ */
+/**
+ * @typedef {object} InsertSqlArgsType
+ * @property {string[]} [columns]
+ * @property {{[key: string]: any}} [data]
+ * @property {boolean} [multiple]
+ * @property {boolean} [returnLastInsertedColumnNames]
+ * @property {Array<Array<any>>} [rows]
+ * @property {string} tableName
+ */
+/**
+ * @typedef {Record<string, any>} QueryRowType
+ * @typedef {Array<QueryRowType>} QueryResultType
+ */
+
 import {Logger} from "../../logger.js"
 import Query from "../query/index.js"
 import Handler from "../handler.js"
@@ -10,6 +44,9 @@ import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/src/wait.js"
 
 export default class VelociousDatabaseDriversBase {
+  /** @type {number | undefined} */
+  idSeq = undefined
+
   /**
    * @param {object} config
    * @param {import("../../configuration.js").default} configuration
@@ -55,18 +92,36 @@ export default class VelociousDatabaseDriversBase {
 
   /**
    * @interface
+   * @param {import("../table-data/index.js").default} _tableData
    * @returns {Promise<string[]>}
    */
-  alterTableSql() {
+  alterTableSql(_tableData) { // eslint-disable-line no-unused-vars
     throw new Error("alterTableSql not implemented")
   }
 
   /**
-   * @param {...Parameters<this["createTableSql"]>} args
-   * @returns {void}
+   * @interface
+   * @returns {Promise<void>}
+   */
+  connect() {
+    throw new Error("'connect' not implemented")
+  }
+
+  /**
+   * @interface
+   * @param {CreateIndexSqlArgs} indexData
+   * @returns {string}
+   */
+  createIndexSql(indexData) { // eslint-disable-line no-unused-vars
+    throw new Error("'createIndexSql' not implemented")
+  }
+
+  /**
+   * @param {import("../table-data/index.js").default} tableData
+   * @returns {Promise<void>}
    */
-  async createTable(...args) {
-    const sqls = this.createTableSql(...args)
+  async createTable(tableData) {
+    const sqls = this.createTableSql(tableData)
 
     for (const sql of sqls) {
       await this.query(sql)
@@ -74,21 +129,40 @@ export default class VelociousDatabaseDriversBase {
   }
 
   /**
-   * @param {...Parameters<this["deleteSql"]>} args
-   * @returns {void}
+   * @interface
+   * @param {import("../table-data/index.js").default} tableData
+   * @returns {string[]}
    */
-  async delete(...args) {
-    const sql = this.deleteSql(...args)
+  createTableSql(tableData) { // eslint-disable-line no-unused-vars
+    throw new Error("'createTableSql' not implemented")
+  }
+
+  /**
+   * @param {DeleteSqlArgsType} args
+   * @returns {Promise<void>}
+   */
+  async delete(args) {
+    const sql = this.deleteSql(args)
 
     await this.query(sql)
   }
 
   /**
-   * @param {...Parameters<this['dropTableSql']>} args
-   * @returns {void}
+   * @interface
+   * @param {DeleteSqlArgsType} args
+   * @returns {string}
    */
-  async dropTable(...args) {
-    const sqls = this.dropTableSql(...args)
+  deleteSql(args) { // eslint-disable-line no-unused-vars
+    throw new Error(`'deleteSql' not implemented`)
+  }
+
+  /**
+   * @param {string} tableName
+   * @param {DropTableSqlArgsType} [args]
+   * @returns {Promise<void>}
+   */
+  async dropTable(tableName, args) {
+    const sqls = this.dropTableSql(tableName, args)
 
     for (const sql of sqls) {
       await this.query(sql)
@@ -97,16 +171,23 @@ export default class VelociousDatabaseDriversBase {
 
   /**
    * @interface
-   * @param {string} _tableName
-   * @param {object} _args
-   * @param {boolean} _args.cascade
-   * @param {boolean} _args.ifExists
+   * @param {string} tableName
+   * @param {DropTableSqlArgsType} [args]
    * @returns {string}
    */
-  dropTableSql(_tableName, _args) { // eslint-disable-line no-unused-vars
+  dropTableSql(tableName, args) { // eslint-disable-line no-unused-vars
     throw new Error("dropTableSql not implemented")
   }
 
+  /**
+   * @interface
+   * @param {any} value
+   * @returns {any}
+   */
+  escape(value) { // eslint-disable-line no-unused-vars
+    throw new Error("'escape' not implemented")
+  }
+
   /**
    * @returns {object}
    */
@@ -124,7 +205,7 @@ export default class VelociousDatabaseDriversBase {
   }
 
   /**
-   * @returns {number}
+   * @returns {number | undefined}
    */
   getIdSeq() {
     return this.idSeq
@@ -138,6 +219,12 @@ export default class VelociousDatabaseDriversBase {
     throw new Error(`${this.constructor.name}#getTables not implemented`)
   }
 
+  /**
+   * @param {string} name
+   * @param {object} [args]
+   * @param {boolean} args.throwError
+   * @returns {Promise<import("./base-table.js").default | undefined>}
+   */
   async getTableByName(name, args) {
     const tables = await this.getTables()
     const table = tables.find((table) => table.getName() == name)
@@ -148,21 +235,32 @@ export default class VelociousDatabaseDriversBase {
   }
 
   /**
-   * @param {object} args
-   * @param {Array} args.columns
-   * @param {object} args.data
-   * @param {boolean} args.multiple
-   * @param {boolean} args.returnLastInsertedColumnNames
-   * @param {Array} args.rows
-   * @param {string} args.tableName
+   * @interface
+   * @returns {string}
+   */
+  getType() {
+    throw new Error("'type' not implemented")
+  }
+
+  /**
+   * @param {InsertSqlArgsType} args
    * @returns {Promise<void>}
    */
-  async insert(...args) {
-    const sql = this.insertSql(...args)
+  async insert(args) {
+    const sql = this.insertSql(args)
 
     await this.query(sql)
   }
 
+  /**
+   * @interface
+   * @param {InsertSqlArgsType} args
+   * @returns {string}
+   */
+  insertSql(args) { // eslint-disable-line no-unused-vars
+    throw new Error("'insertSql' not implemented")
+  }
+
   /**
    * @interface
    * @returns {Promise<number>}
@@ -171,6 +269,10 @@ export default class VelociousDatabaseDriversBase {
     throw new Error(`${this.constructor.name}#lastInsertID not implemented`)
   }
 
+  /**
+   * @param {any} value
+   * @returns {any}
+   */
   _convertValue(value) {
     if (value instanceof Date) {
       return strftime("%F %T.%L", value)
@@ -179,6 +281,14 @@ export default class VelociousDatabaseDriversBase {
     return value
   }
 
+  /**
+   * @interface
+   * @returns {import("../query-parser/options.js").default}
+   */
+  options() {
+    throw new Error("'options' not implemented.")
+  }
+
   /**
    * @param {string} value
    * @returns {string}
@@ -230,7 +340,7 @@ export default class VelociousDatabaseDriversBase {
 
   /**
    * @param {string} tableName
-   * @returns {Promise<Array>}
+   * @returns {Promise<QueryResultType>}
    */
   async select(tableName) {
     const query = this.newQuery()
@@ -243,13 +353,21 @@ export default class VelociousDatabaseDriversBase {
   }
 
   /**
-   * @param {number} newIdSeq
+   * @param {number | undefined} newIdSeq
    * @returns {void}
    */
   setIdSeq(newIdSeq) {
     this.idSeq = newIdSeq
   }
 
+  /**
+   * @interface
+   * @returns {boolean}
+   */
+  shouldSetAutoIncrementWhenPrimaryKey() {
+    throw new Error(`'shouldSetAutoIncrementWhenPrimaryKey' not implemented`)
+  }
+
   /**
    * @param {string} tableName
    * @returns {Promise<boolean>}
@@ -263,6 +381,10 @@ export default class VelociousDatabaseDriversBase {
     return false
   }
 
+  /**
+   * @param {() => Promise<void>} callback
+   * @returns {Promise<any>}
+   */
   async transaction(callback) {
     const savePointName = this.generateSavePointName()
     let transactionStarted = false
@@ -293,7 +415,11 @@ export default class VelociousDatabaseDriversBase {
         await this.commitTransaction()
       }
     } catch (error) {
-      this.logger.debug("Transaction error", error.message)
+      if (error instanceof Error) {
+        this.logger.debug("Transaction error", error.message)
+      } else {
+        this.logger.debug("Transaction error", error)
+      }
 
       if (savePointStarted) {
         this.logger.debug("Rollback savepoint", savePointName)
@@ -347,7 +473,7 @@ export default class VelociousDatabaseDriversBase {
 
   /**
    * @param {string} sql
-   * @returns {Promise<Array<Record<string, any>>>}
+   * @returns {Promise<QueryResultType>}
    */
   async query(sql) {
     let tries = 0
@@ -358,7 +484,7 @@ export default class VelociousDatabaseDriversBase {
       try {
         return await this._queryActual(sql)
       } catch (error) {
-        if (tries < 5 && this.retryableDatabaseError(error)) {
+        if (error instanceof Error && tries < 5 && this.retryableDatabaseError(error)) {
           await wait(100)
           this.logger.warn(`Retrying query because failed with: ${error.stack}`)
           // Retry
@@ -367,8 +493,26 @@ export default class VelociousDatabaseDriversBase {
         }
       }
     }
+
+    throw new Error("'query' unexpected came here")
   }
 
+  /**
+   * @interface
+   * @param {string} sql
+   * @returns {Promise<QueryResultType>}
+   */
+  _queryActual(sql) { // eslint-disable-line no-unused-vars
+    throw new Error(`queryActual not implemented`)
+  }
+
+  /**
+   * @interface
+   * @param {Query} _query
+   * @returns {string}
+   */
+  queryToSql(_query) { throw new Error("queryToSql not implemented") } // eslint-disable-line no-unused-vars
+
   /**
    * @interface
    * @param {Error} _error
@@ -514,18 +658,46 @@ export default class VelociousDatabaseDriversBase {
   }
 
   /**
-   * @param {object} args
-   * @param {object} args.conditions
-   * @param {object} args.data
-   * @param {string} args.tableName
+   * @typedef {object}UpdateSqlArgsType
+   * @property {object} conditions
+   * @property {object} data
+   * @property {string} tableName
+   */
+  /**
+   * @param {UpdateSqlArgsType} args
    * @returns {Promise<void>}
    */
-  async update(...args) {
-    const sql = this.updateSql(...args)
+  async update(args) {
+    const sql = this.updateSql(args)
 
     await this.query(sql)
   }
 
+  /**
+   * @interface
+   * @param {UpdateSqlArgsType} args
+   * @returns {string}
+   */
+  updateSql(args) { // eslint-disable-line no-unused-vars
+    throw new Error("'disableForeignKeys' not implemented")
+  }
+
+  /**
+   * @interface
+   * @returns {Promise<void>}
+   */
+  disableForeignKeys() {
+    throw new Error("'disableForeignKeys' not implemented")
+  }
+
+  /**
+   * @interface
+   * @returns {Promise<void>}
+   */
+  enableForeignKeys() {
+    throw new Error("'enableForeignKeys' not implemented")
+  }
+
   /**
    * @param {function() : void} callback
    * @returns {Promise<any>}

package/src/database/drivers/mssql/index.js

@@ -202,9 +202,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
   }
 
   /**
-   * @param {object} args
-   * @param {string} args.tableName
-   * @param {object} args.conditions
+   * @param {import("../base.js").DeleteSqlArgsType} args
    */
   deleteSql({tableName, conditions}) {
     const deleteInstruction = new Delete({conditions, driver: this, tableName})

package/src/database/drivers/sqlite/sql/alter-table.js

@@ -136,9 +136,11 @@ export default class VelociousDatabaseConnectionDriversSqliteSqlAlterTable exten
         tableName,
         unique: actualTableIndex.getUnique()
       }
-      const sql = new CreateIndexBase(createIndexArgs).toSql()
+      const createIndexSQLs = new CreateIndexBase(createIndexArgs).toSqls()
 
-      sqls.push(sql)
+      for (const createIndexSQL of createIndexSQLs) {
+        sqls.push(createIndexSQL)
+      }
     }
 
     return sqls

package/src/database/handler.js

@@ -1,4 +1,9 @@
+// @ts-check
+
 export default class VelociousDatabaseHandler {
+  /**
+   * @returns {VelociousDatabaseHandler}
+   */
   clone() {
     const newHandler = new VelociousDatabaseHandler()
 

package/src/database/migration/index.js

@@ -1,21 +1,40 @@
+// @ts-check
+
+/**
+ * @typedef {object} AddColumnArgsType
+ * @property {any} default
+ * @property {object} foreignKey
+ * @property {boolean} nullable
+ * @property {boolean} primaryKey
+ * @property {boolean} unique
+ */
+
 import * as inflection from "inflection"
 import restArgsError from "../../utils/rest-args-error.js"
 import TableData from "../table-data/index.js"
+class NotImplementedError extends Error {}
+
+export {NotImplementedError}
 
 export default class VelociousDatabaseMigration {
+  /**
+   * @param {string[]} databaseIdentifiers
+   * @returns {void}
+   */
   static onDatabases(databaseIdentifiers) {
     this._databaseIdentifiers = databaseIdentifiers
   }
 
+  /** @returns {string[] | undefined} */
   static getDatabaseIdentifiers() {
     return this._databaseIdentifiers
   }
 
   /**
    * @param {object} args
-   * @param {string} args.configuration
+   * @param {import("../../configuration.js").default} args.configuration
    * @param {string} args.databaseIdentifier
-   * @param {object} args.db
+   * @param {import("../drivers/base.js").default} args.db
    */
   constructor({configuration, databaseIdentifier = "default", db}) {
     if (!databaseIdentifier) throw new Error("No database identifier given")
@@ -32,12 +51,25 @@ export default class VelociousDatabaseMigration {
     return this._databaseIdentifier
   }
 
+  /** @returns {import("../drivers/base.js").default} */
   getDriver() { return this._db }
   connection() { return this.getDriver() }
 
+  async change() {
+    throw new NotImplementedError("'change' not implemented")
+  }
+
+  async up() {
+    throw new NotImplementedError("'change' not implemented")
+  }
+
+  async down() {
+    throw new NotImplementedError("'change' not implemented")
+  }
+
   /**
    * @param {string} sql
-   * @returns {Promise<Array>}
+   * @returns {Promise<import("../drivers/base.js").QueryResultType>}
    */
   async execute(sql) {
     return await this.connection().query(sql)
@@ -47,12 +79,7 @@ export default class VelociousDatabaseMigration {
    * @param {string} tableName
    * @param {string} columnName
    * @param {string} columnType
-   * @param {object} args
-   * @param {object} args.default
-   * @param {object} args.foreignKey
-   * @param {object} args.nullable
-   * @param {object} args.primaryKey
-   * @param {object} args.unique
+   * @param {AddColumnArgsType} [args]
    * @returns {Promise<void>}
    */
   async addColumn(tableName, columnName, columnType, args) {
@@ -88,13 +115,16 @@ export default class VelociousDatabaseMigration {
     }
   }
 
+  /**
+   * @typedef {object} AddIndexArgsType
+   * @property {boolean} [ifNotExists]
+   * @property {string} [name]
+   * @property {boolean} [unique]
+   */
   /**
    * @param {string} tableName
-   * @param {Array} columns
-   * @param {object} args
-   * @param {boolean} args.ifNotExists
-   * @param {string} args.name
-   * @param {boolean} args.unique
+   * @param {Array<string | import("../table-data/table-column.js").default>} columns
+   * @param {AddIndexArgsType} [args]
    * @returns {Promise<void>}
    */
   async addIndex(tableName, columns, args) {
@@ -175,8 +205,13 @@ export default class VelociousDatabaseMigration {
    */
   async changeColumnNull(tableName, columnName, nullable) {
     const table = await this.getDriver().getTableByName(tableName)
+
+    if (!table) throw new Error(`Table ${tableName} does not exist`)
+
     const column = await table.getColumnByName(columnName)
 
+    if (!column) throw new Error(`Column ${columnName} does not exist in table ${tableName}`)
+
     await column.changeNullable(nullable)
   }
 
@@ -187,20 +222,34 @@ export default class VelociousDatabaseMigration {
    */
   async columnExists(tableName, columnName) {
     const table = await this.getDriver().getTableByName(tableName)
+
+    if (!table) throw new Error(`Table ${tableName} does not exist`)
+
     const column = await table.getColumnByName(columnName)
 
+    if (!column) throw new Error(`Column ${columnName} does not exist in table ${tableName}`)
+
     return Boolean(column)
   }
 
+  /**
+   * @typedef {object} CreateTableIdArgsType
+   * @property {any} [default]
+   * @property {string} [type]
+   */
+  /**
+   * @typedef {object} CreateTableArgsType
+   * @property {CreateTableIdArgsType | false} [id]
+   */
   /**
    * @param {string} tableName
-   * @param {function() : void} arg1
+   * @param {function(TableData) : void} arg1
    * @returns {Promise<void>}
    */
   /**
    * @param {string} tableName
-   * @param {object} arg1
-   * @param {function() : void} arg2
+   * @param {CreateTableArgsType} arg1
+   * @param {function(TableData) : void} arg2
    * @returns {Promise<void>}
    */
   async createTable(tableName, arg1, arg2) {
@@ -218,7 +267,16 @@ export default class VelociousDatabaseMigration {
     const {id = {}, ...restArgs} = args
     const databaseIdentifier = this._getDatabaseIdentifier()
     const databasePool = this.configuration.getDatabasePool(databaseIdentifier)
-    const {default: idDefault, type: idType = databasePool.primaryKeyType(), ...restArgsId} = id
+    let idDefault, idType, restArgsId
+
+    if (id !== false) {
+      ({default: idDefault, type: idType, ...restArgsId} = id)
+    }
+
+    if (!idType) {
+      idType = databasePool.primaryKeyType()
+    }
+
     const tableData = new TableData(tableName)
 
     restArgsError(restArgs)
@@ -227,7 +285,7 @@ export default class VelociousDatabaseMigration {
     if (!(idType in tableData)) throw new Error(`Unsupported primary key type: ${idType}`)
 
     if (id !== false) {
-      tableData[idType]("id", {autoIncrement: true, default: idDefault, null: false, primaryKey: true})
+      tableData.addColumn("id", {autoIncrement: true, default: idDefault, null: false, primaryKey: true, type: idType})
     }
 
     if (callback) {

package/src/database/migrator/files-finder.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import fs from "fs/promises"
 import * as inflection from "inflection"
 
@@ -17,36 +19,33 @@ export default class VelociousDatabaseMigratorFilesFinder {
   }
 
   /**
-   * @returns {Promise<Array<{
-   *   file: string,
-   *   fullPath: string,
-   *   date: number,
-   *   migrationClassName: string
-   * }>>}
+   * @returns {Promise<Array<import("./types.js").MigrationObjectType>>}
    */
   async findFiles() {
     let files = await fs.readdir(this.path)
 
-    files = files
-      .map((file) => {
-        const match = file.match(/^(\d{14})-(.+)\.js$/)
+    /** @type {import("./types.js").MigrationObjectType[]} */
+    let result = []
+
+    for (const file of files) {
+      const match = file.match(/^(\d{14})-(.+)\.js$/)
 
-        if (!match) return null
+      if (!match) continue
 
-        const date = parseInt(match[1])
-        const migrationName = match[2]
-        const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
+      const date = parseInt(match[1])
+      const migrationName = match[2]
+      const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
 
-        return {
-          file,
-          fullPath: `${this.path}/${file}`,
-          date,
-          migrationClassName
-        }
+      result.push({
+        file,
+        fullPath: `${this.path}/${file}`,
+        date,
+        migrationClassName
       })
-      .filter((migration) => Boolean(migration))
-      .sort((migration1, migration2) => migration1.date - migration2.date)
+    }
+
+    result = result.sort((migration1, migration2) => migration1.date - migration2.date)
 
-    return files
+    return result
   }
 }