velocious 1.0.96 → 1.0.98

package/src/database/migrator/types.js

@@ -0,0 +1,29 @@
+/**
+ * @typedef {object} MigrationObjectType
+ * @property {number} date
+ * @property {string} file
+ * @property {string} [fullPath]
+ * @property {string} migrationClassName
+ */
+
+/**
+ * @typedef {function() : typeof import("../migration/index.js").default} ImportCallbackType
+ */
+
+/**
+ * @typedef {function(string) : Promise<typeof import("../migration/index.js").default>} ImportFullpathCallbackType
+ */
+
+/**
+ * @typedef {() => Promise<typeof import("../migration/index.js").default>} RequireMigrationType
+ */
+
+/**
+ * @typedef {(id: string) => {default: typeof import("../migration/index.js").default}} RequireMigrationContextRequireType
+ * @typedef {RequireMigrationContextRequireType & {
+ *   keys: () => string[],
+ *   id: string
+ * }} RequireMigrationContextType
+ */
+
+export {}

package/src/database/migrator.js

@@ -1,10 +1,16 @@
+// @ts-check
+
 import {digg} from "diggerize"
 import * as inflection from "inflection"
 import {Logger} from "../logger.js"
+import {NotImplementedError} from "./migration/index.js"
 import restArgsError from "../utils/rest-args-error.js"
 import TableData from "./table-data/index.js"
 
 export default class VelociousDatabaseMigrator {
+  /** @type {Record<string, Record<string, boolean>>} */
+  migrationsVersions = {}
+
   /**
    * @param {object} args
    * @param {import("../configuration.js").default} args.configuration
@@ -60,8 +66,8 @@ export default class VelociousDatabaseMigrator {
 
   /**
    * @param {string} dbIdentifier
-   * @param {string} version
-   * @returns {Promise<boolean>}
+   * @param {number} version
+   * @returns {boolean}
    */
   hasRunMigrationVersion(dbIdentifier, version) {
     if (!this.migrationsVersions) throw new Error("Migrations versions hasn't been loaded yet")
@@ -74,12 +80,18 @@ export default class VelociousDatabaseMigrator {
     return false
   }
 
+  /**
+   * @param {import("./migrator/types.js").MigrationObjectType[]} files
+   * @param {import("./migrator/types.js").ImportFullpathCallbackType} importCallback
+   */
   async migrateFiles(files, importCallback) {
     await this.configuration.ensureConnections(async () => {
       for (const migration of files) {
         await this.runMigrationFile({
           migration,
           requireMigration: async () => {
+            if (!migration.fullPath) throw new Error(`Migration didn't have a fullPath key: ${Object.keys(migration).join(", ")}`)
+
             const migrationImport = await importCallback(migration.fullPath)
 
             if (!migrationImport) {
@@ -94,46 +106,47 @@ export default class VelociousDatabaseMigrator {
   }
 
   /**
-   * @param {*} requireContext
+   * @param {import("./migrator/types.js").RequireMigrationContextType} requireContext
    * @returns {Promise<void>}
    */
   async migrateFilesFromRequireContext(requireContext) {
-    const files = requireContext
-      .keys()
-      .map((file) => {
-        // "13,14" because somes "require-context"-npm-module deletes first character!?
-        const match = file.match(/(\d{13,14})-(.+)\.js$/)
+    /** @type {import("./migrator/types.js").MigrationObjectType[]} */
+    let files = []
 
-        if (!match) return null
+    for (const file of requireContext.keys()) {
+      // "13,14" because somes "require-context"-npm-module deletes first character!?
+      const match = file.match(/(\d{13,14})-(.+)\.js$/)
 
-        // Fix require-context-npm-module deletes first character
-        let fileName = file
-        let dateNumber = match[1]
+      if (!match) continue
 
-        if (dateNumber.length == 13) {
-          dateNumber = `2${dateNumber}`
-          fileName = `2${fileName}`
-        }
+      // Fix require-context-npm-module deletes first character
+      let fileName = file
+      let dateNumber = match[1]
 
-        // Parse regex
-        const date = parseInt(dateNumber)
-        const migrationName = match[2]
-        const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
+      if (dateNumber.length == 13) {
+        dateNumber = `2${dateNumber}`
+        fileName = `2${fileName}`
+      }
 
-        return {
-          file: fileName,
-          date,
-          migrationClassName
-        }
+      // Parse regex
+      const date = parseInt(dateNumber)
+      const migrationName = match[2]
+      const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
+
+      files.push({
+        file: fileName,
+        date,
+        migrationClassName
       })
-      .filter((migration) => Boolean(migration))
-      .sort((migration1, migration2) => migration1.date - migration2.date)
+    }
+
+    files = files.sort((migration1, migration2) => migration1.date - migration2.date)
 
     await this.configuration.ensureConnections(async () => {
       for (const migration of files) {
         await this.runMigrationFile({
           migration,
-          requireMigration: () => requireContext(migration.file).default
+          requireMigration: async () => requireContext(migration.file).default
         })
       }
     })
@@ -174,6 +187,7 @@ export default class VelociousDatabaseMigrator {
   }
 
   /**
+   * @param {import("./drivers/base.js").default} db
    * @returns {Promise<boolean>}
    */
   async migrationsTableExist(db) {
@@ -185,34 +199,39 @@ export default class VelociousDatabaseMigrator {
   }
 
   /**
+   * @param {import("./migrator/types.js").RequireMigrationContextType} requireContext
    * @returns {Promise<void>}
    */
   async executeRequireContext(requireContext) {
     const migrationFiles = requireContext.keys()
-    const files = migrationFiles
-      .map((file) => {
-        const match = file.match(/^(\d{14})-(.+)\.js$/)
 
-        if (!match) return null
+    /** @type {import("./migrator/types.js").MigrationObjectType[]} */
+    let files = []
 
-        const date = parseInt(match[1])
-        const migrationName = match[2]
-        const migrationClassName = inflection.camelize(migrationName)
+    for (const file of migrationFiles) {
+      const match = file.match(/^(\d{14})-(.+)\.js$/)
 
-        return {
-          file,
-          fullPath: `${migrationsPath}/${file}`, // eslint-disable-line no-undef
-          date,
-          migrationClassName
-        }
+      if (!match) continue
+
+      const date = parseInt(match[1])
+      const migrationName = match[2]
+      const migrationClassName = inflection.camelize(migrationName)
+
+      const migrationObject = /** @type {import("./migrator/types.js").MigrationObjectType} */ ({
+        file,
+        date,
+        migrationClassName
       })
-      .filter((migration) => Boolean(migration))
-      .sort((migration1, migration2) => migration1.date - migration2.date)
+
+      files.push(migrationObject)
+    }
+
+    files = files.sort((migration1, migration2) => migration1.date - migration2.date)
 
     for (const migration of files) {
       await this.runMigrationFile({
         migration,
-        require: () => requireContext(migration.file).default
+        requireMigration: async () => requireContext(migration.file).default
       })
     }
   }
@@ -257,8 +276,8 @@ export default class VelociousDatabaseMigrator {
   }
 
   /**
-   * @param {{date: number}[]} files
-   * @param {function(string) : void} importCallback Function to import a file
+   * @param {import("./migrator/types.js").MigrationObjectType[]} files
+   * @param {import("./migrator/types.js").ImportFullpathCallbackType} importCallback Function to import a file
    * @returns {Promise<void>}
    */
   async rollback(files, importCallback) {
@@ -277,17 +296,22 @@ export default class VelociousDatabaseMigrator {
 
     await this.runMigrationFile({
       migration,
-      requireMigration: async () => await importCallback(migration.fullPath),
+      requireMigration: async () => {
+        if (!migration.fullPath) throw new Error(`Migration didn't have a fullPath key: ${Object.keys(migration).join(", ")}`)
+
+        return await importCallback(migration.fullPath)
+      },
       direction: "down"
     })
   }
 
   /**
-   * @returns {Promise<string | null>} The latest migration version
+   * @returns {Promise<string | undefined>} The latest migration version
    */
   async _latestMigrationVersion() {
     if (!this.migrationsVersions) await this.loadMigrationsVersions()
 
+    /** @type {string | undefined} */
     let highestVersion
 
     for (const dbIdentifier in this.migrationsVersions) {
@@ -303,9 +327,9 @@ export default class VelociousDatabaseMigrator {
 
   /**
    * @param {object} args
-   * @param {object} args.migration
-   * @param {function() : void} args.requireMigration
-   * @param {string} args.direction
+   * @param {import("./migrator/types.js").MigrationObjectType} args.migration
+   * @param {import("./migrator/types.js").RequireMigrationType} args.requireMigration
+   * @param {string} [args.direction]
    */
   async runMigrationFile({migration, requireMigration, direction = "up"}) {
     if (!this.configuration) throw new Error("No configuration set")
@@ -354,17 +378,28 @@ export default class VelociousDatabaseMigrator {
       const MigrationClass = migrationClass
       const migrationInstance = new MigrationClass({
         configuration: this.configuration,
+        databaseIdentifier: dbIdentifier,
         db
       })
       const dateString = `${digg(migration, "date")}`
 
       if (direction == "up") {
-        if (migrationInstance.change) {
+        try {
           await migrationInstance.change()
-        } else if (migrationInstance.up) {
-          await migrationInstance.up()
-        } else {
-          throw new Error(`'change' or 'up' didn't exist on migration: ${migration.file}`)
+        } catch (changeError) {
+          if (changeError instanceof NotImplementedError) {
+            try {
+              await migrationInstance.up()
+            } catch (upError) {
+              if (upError instanceof NotImplementedError) {
+                throw new Error(`'change' or 'up' didn't exist on migration: ${migration.file}`)
+              } else {
+                throw upError
+              }
+            }
+          } else {
+            throw changeError
+          }
         }
 
         const existingSchemaMigrations = await db.newQuery()
@@ -376,10 +411,14 @@ export default class VelociousDatabaseMigrator {
           await db.insert({tableName: "schema_migrations", data: {version: dateString}})
         }
       } else if (direction == "down") {
-        if (migrationInstance.down) {
+        try {
           await migrationInstance.down()
-        } else {
-          throw new Error(`'down' didn't exist on migration: ${migration.file}`)
+        } catch (downError) {
+          if (downError instanceof NotImplementedError) {
+            throw new Error(`'down' didn't exist on migration: ${migration.file} or migrating down with a change method isn't currently supported`)
+          } else {
+            throw downError
+          }
         }
 
         await db.delete({tableName: "schema_migrations", conditions: {version: dateString}})

package/src/database/pool/async-tracked-multi-connection.js

@@ -1,18 +1,38 @@
+// @ts-check
+
 import {AsyncLocalStorage} from "async_hooks"
 import BasePool from "./base.js"
 
 export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends BasePool {
-  constructor(args = {}) {
-    super(args)
-    this.connections = []
-    this.connectionsInUse = {}
-    this.asyncLocalStorage = new AsyncLocalStorage()
-    this.idSeq = 0
+  asyncLocalStorage = new AsyncLocalStorage()
+
+  /** @type {import("../drivers/base.js").default[]} */
+  connections = []
+
+  /** @type {Record<number, import("../drivers/base.js").default>} */
+  connectionsInUse = {}
+
+  idSeq = 0
+
+  /**
+   * @param {object} args
+   * @param {import("../../configuration.js").default} args.configuration
+   * @param {string} args.identifier
+   */
+  constructor({configuration, identifier}) {
+    super({configuration, identifier})
   }
 
+  /**
+   * @param {import("../drivers/base.js").default} connection
+   */
   checkin(connection) {
     const id = connection.getIdSeq()
 
+    if (typeof id !== "number") {
+      throw new Error(`idSeq on connection wasn't set? '${typeof id}' = ${id}`)
+    }
+
     if (id in this.connectionsInUse) {
       delete this.connectionsInUse[id]
     }
@@ -22,6 +42,9 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     this.connections.push(connection)
   }
 
+  /**
+   * @returns {Promise<import("../drivers/base.js").default>}
+   */
   async checkout() {
     let connection = this.connections.shift()
 
@@ -39,6 +62,9 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     return connection
   }
 
+  /**
+   * @param {function(import("../drivers/base.js").default) : void} callback
+   */
   async withConnection(callback) {
     const connection = await this.checkout()
     const id = connection.getIdSeq()
@@ -52,6 +78,9 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     })
   }
 
+  /**
+   * @returns {import("../drivers/base.js").default}
+   */
   getCurrentConnection() {
     const id = this.asyncLocalStorage.getStore()
 
@@ -63,6 +92,12 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
       throw new Error(`Connection ${id} doesn't exist any more - has it been checked in again?`)
     }
 
-    return this.connectionsInUse[id]
+    const currentConnection = this.connectionsInUse[id]
+
+    if (!currentConnection) {
+      throw new Error(`Couldn't get current connection from that ID: ${id}`)
+    }
+
+    return currentConnection
   }
 }

package/src/database/pool/base-methods-forward.js

@@ -0,0 +1,37 @@
+/**
+ * @param {typeof import("./base.js").default} PoolBase
+ */
+export default function baseMethodsForward(PoolBase) {
+  const forwardMethods = [
+    "alterTable",
+    "alterTableSql",
+    "createIndex",
+    "createIndexSql",
+    "createTable",
+    "createTableSql",
+    "delete",
+    "deleteSql",
+    "getTables",
+    "insert",
+    "insertSql",
+    "primaryKeyType",
+    "query",
+    "quote",
+    "quoteColumn",
+    "quoteTable",
+    "select",
+    "update",
+    "updateSql"
+  ]
+
+  for (const forwardMethod of forwardMethods) {
+    PoolBase.prototype[forwardMethod] = function(...args) {
+      const connection = this.getCurrentConnection()
+      const connectionMethod = connection[forwardMethod]
+
+      if (!connectionMethod) throw new Error(`${forwardMethod} isn't defined on driver`)
+
+      return connection[forwardMethod](...args)
+    }
+  }
+}

package/src/database/pool/base.js

@@ -1,46 +1,96 @@
+// @ts-check
+
 import Configuration from "../../configuration.js"
 import {digg} from "diggerize"
 import {Logger} from "../../logger.js"
+import baseMethodsForward from "./base-methods-forward.js"
 
-if (!globalThis.velociousDatabasePoolBase) {
-  globalThis.velociousDatabasePoolBase = {
-    current: null
-  }
+/** @type {{currentPool: VelociousDatabasePoolBase | null}} */
+const shared = {
+  currentPool: null
 }
 
 class VelociousDatabasePoolBase {
+  /**
+   * @returns {VelociousDatabasePoolBase}
+   */
   static current() {
-    if (!globalThis.velociousDatabasePoolBase.current) {
-      globalThis.velociousDatabasePoolBase.current = new this()
-    }
+    if (!shared.currentPool) throw new Error("A database pool hasn't been set")
 
-    return globalThis.velociousDatabasePoolBase.current
+    return shared.currentPool
   }
 
-  constructor(args = {}) {
-    this.configuration = args.configuration || Configuration.current()
+  /**
+   * @param {object} args
+   * @param {Configuration} args.configuration
+   * @param {string} args.identifier
+   */
+  constructor({configuration, identifier}) {
+    this.configuration = configuration || Configuration.current()
 
     if (!this.configuration) throw new Error("No configuration given")
-    if (!args.identifier) throw new Error("No identifier was given")
+    if (!identifier) throw new Error("No identifier was given")
 
-    this.connections = []
-    this.connectionsInUse = {}
-    this.identifier = args.identifier
+    this.identifier = identifier
     this.logger = new Logger(this)
   }
 
+  /**
+   * @interface
+   * @param {import("../drivers/base.js").default} _connection
+   */
+  checkin(_connection) { // eslint-disable-line no-unused-vars
+    throw new Error("'checkin' not implemented")
+  }
+
+  /**
+   * @interface
+   * @returns {Promise<import("../drivers/base.js").default>}
+   */
+  checkout() {
+    throw new Error("'checkout' not implemented")
+  }
+
+  /**
+   * @interface
+   * @returns {import("../drivers/base.js").default}
+   */
+  getCurrentConnection() {
+    throw new Error("'getCurrentConnection' not implemented")
+  }
+
+  /**
+   * @returns {{driver: typeof import("../drivers/base.js").default, type: string}}
+   */
   getConfiguration() {
     return digg(this.configuration.getDatabaseConfiguration(), this.identifier)
   }
 
+  /**
+   * @interface
+   * @returns {string}
+   */
+  primaryKeyType() {
+    throw new Error("'primaryKeyType' not implemented")
+  }
+
+  /**
+   * @returns {void}
+   */
   setCurrent() {
-    globalThis.velociousDatabasePoolBase.current = this
+    shared.currentPool = this
   }
 
+  /**
+   * @param {typeof import("../drivers/base.js").default} driverClass
+   */
   setDriverClass(driverClass) {
     this.driverClass = driverClass
   }
 
+  /**
+   * @returns {Promise<import("../drivers/base.js").default>}
+   */
   async spawnConnection() {
     const databaseConfig = this.getConfiguration()
 
@@ -51,6 +101,11 @@ class VelociousDatabasePoolBase {
     return connection
   }
 
+  /**
+   * @param {object} config
+   * @param {typeof import("../drivers/base.js").default} config.driver
+   * @returns {Promise<import("../drivers/base.js").default>}
+   */
   async spawnConnectionWithConfiguration(config) {
     const DriverClass = config.driver || this.driverClass
 
@@ -62,39 +117,17 @@ class VelociousDatabasePoolBase {
 
     return connection
   }
-}
 
-const forwardMethods = [
-  "alterTable",
-  "alterTableSql",
-  "createIndex",
-  "createIndexSql",
-  "createTable",
-  "createTableSql",
-  "delete",
-  "deleteSql",
-  "getTables",
-  "insert",
-  "insertSql",
-  "primaryKeyType",
-  "query",
-  "quote",
-  "quoteColumn",
-  "quoteTable",
-  "select",
-  "update",
-  "updateSql"
-]
-
-for (const forwardMethod of forwardMethods) {
-  VelociousDatabasePoolBase.prototype[forwardMethod] = function(...args) {
-    const connection = this.getCurrentConnection()
-    const connectionMethod = connection[forwardMethod]
-
-    if (!connectionMethod) throw new Error(`${forwardMethod} isn't defined on driver`)
-
-    return connection[forwardMethod](...args)
+  /**
+   * @interface
+   * @param {function(import("../drivers/base.js").default) : void} _callback
+   * @returns {Promise<void>}
+   */
+  withConnection(_callback) { // eslint-disable-line no-unused-vars
+    throw new Error("'withConnection' not implemented")
   }
 }
 
+baseMethodsForward(VelociousDatabasePoolBase)
+
 export default VelociousDatabasePoolBase

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

@@ -1,10 +1,18 @@
+// @ts-check
+
 import BasePool from "./base.js"
 
 export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
-  checkin(connection) { // eslint-disable-line no-unused-vars
+  /**
+   * @param {import("../drivers/base.js").default} _connection
+   */
+  checkin(_connection) { // eslint-disable-line no-unused-vars
     // Do nothing
   }
 
+  /**
+   * @returns {Promise<import("../drivers/base.js").default>}
+   */
   async checkout() {
     if (!this.connection) {
       this.connection = await this.spawnConnection()
@@ -13,11 +21,18 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
     return this.connection
   }
 
+  /**
+   * @param {function(import("../drivers/base.js").default) : void} callback
+   */
   async withConnection(callback) {
-    await this.checkout() // Ensure a connection is present
-    await callback(this.connection)
+    const connection = await this.checkout()
+
+    await callback(connection)
   }
 
+  /**
+   * @returns {import("../drivers/base.js").default}
+   */
   getCurrentConnection() {
     if (!this.connection) {
       throw new Error("A connection hasn't been made yet")

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

@@ -1,4 +1,5 @@
-import {digs} from "diggerize"
+// @ts-check
+
 import QueryBase from "./base.js"
 import restArgsError from "../../utils/rest-args-error.js"
 import TableData from "../table-data/index.js"
@@ -6,8 +7,7 @@ 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 {import("../drivers/base.js").default} args.driver
    * @param {TableData} args.tableData
    */
   constructor({driver, tableData, ...restArgs}) {
@@ -25,7 +25,7 @@ export default class VelociousDatabaseQueryAlterTableBase extends QueryBase {
   toSqls() {
     const databaseType = this.getDriver().getType()
     const sqls = []
-    const {tableData} = digs(this, "tableData")
+    const {tableData} = this
     const options = this.getOptions()
 
     let sql = `ALTER TABLE ${options.quoteTableName(tableData.getName())} `