velocious 1.0.431 → 1.0.433

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

@@ -0,0 +1,52 @@
+// @ts-check
+
+/**
+ * Runs base methods forward.
+ * @param {typeof import("./base.js").default} PoolBase - Pool base.
+ * @returns {void} - No return value.
+ */
+export default function baseMethodsForward(PoolBase) {
+  const forwardMethods = [
+    "alterTable",
+    "alterTableSQLs",
+    "createIndex",
+    "createIndexSQLs",
+    "createTable",
+    "createTableSql",
+    "delete",
+    "deleteSql",
+    "getTables",
+    "insert",
+    "insertSql",
+    "primaryKeyType",
+    "query",
+    "quote",
+    "quoteColumn",
+    "quoteTable",
+    "select",
+    "update",
+    "updateSql"
+  ]
+
+  const prototype = /**
+                     * Narrows the runtime value to the documented type.
+                      @type {Record<string, (...args: Array<?>) => ?>} */ (/**
+                                                                            * Narrows the runtime value to the documented type.
+                                                                             @type {?} */ (PoolBase.prototype))
+
+  for (const forwardMethod of forwardMethods) {
+    prototype[forwardMethod] = function(...args) {
+      const connection = this.getCurrentConnection()
+      const connectionRecord = /**
+                                * Narrows the runtime value to the documented type.
+                                 @type {Record<string, (...args: Array<?>) => ?>} */ (/**
+                                                                                       * Narrows the runtime value to the documented type.
+                                                                                        @type {?} */ (connection))
+      const connectionMethod = connectionRecord[forwardMethod]
+
+      if (!connectionMethod) throw new Error(`${forwardMethod} isn't defined on driver`)
+
+      return connectionMethod.apply(connection, args)
+    }
+  }
+}

package/build/database/pool/base.js

@@ -0,0 +1,380 @@
+// @ts-check
+
+import Configuration from "../../configuration.js"
+import Logger from "../../logger.js"
+import baseMethodsForward from "./base-methods-forward.js"
+
+export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
+
+/**
+ * ConnectionCheckoutOptions type.
+ * @typedef {object} ConnectionCheckoutOptions
+ * @property {string} [name] - Human-readable name for the checked-out connection.
+ */
+
+/**
+ * DatabasePoolDebugSnapshot type.
+ * @typedef {object} DatabasePoolDebugSnapshot
+ * @property {Record<string, ?>} configuration - Sanitized resolved database configuration.
+ * @property {Array<Record<string, ?>>} connections - Live connection snapshots.
+ * @property {number} connectionsBeingSpawned - Number of in-progress connection spawns.
+ * @property {number} idleCount - Number of idle connections.
+ * @property {string} identifier - Database identifier.
+ * @property {number} inUseCount - Number of checked-out connections.
+ * @property {Array<Record<string, ?>>} [pendingCheckouts] - Waiting checkout snapshots.
+ * @property {number} pendingCheckoutCount - Number of queued checkout requests.
+ * @property {string} poolClass - Pool class name.
+ */
+
+/**
+ * Shared.
+  @type {{currentPool: VelociousDatabasePoolBase | null}} */
+const shared = {
+  currentPool: null
+}
+
+/**
+ * Runs stable stringify.
+ * @param {?} value - Value to stringify.
+ * @returns {string} - Stable JSON string.
+ */
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`
+  }
+
+  if (value && typeof value === "object") {
+    const entries = Object
+      .keys(/**
+             * Narrows the runtime value to the documented type.
+              @type {Record<string, ?>} */ (value))
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(/**
+                                                               * Narrows the runtime value to the documented type.
+                                                                @type {Record<string, ?>} */ (value)[key])}`)
+
+    return `{${entries.join(",")}}`
+  }
+
+  return JSON.stringify(value)
+}
+
+class VelociousDatabasePoolBase {
+  /**
+   * Without current connection context.
+    @type {undefined | ((callback: () => ?) => ?)} */
+  _withoutCurrentConnectionContext = undefined
+
+  /**
+   * Runs current.
+   * @returns {VelociousDatabasePoolBase} - The current.
+   */
+  static current() {
+    if (!shared.currentPool) throw new Error("A database pool hasn't been set")
+
+    return shared.currentPool
+  }
+
+  /**
+   * Clears any global connections for the given configuration.
+   * @returns {void} - No return value.
+   */
+  static clearGlobalConnections() {}
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {Configuration} args.configuration - Configuration instance.
+   * @param {string} args.identifier - Identifier.
+   */
+  constructor({configuration, identifier}) {
+    this.configuration = configuration || Configuration.current()
+
+    if (!this.configuration) throw new Error("No configuration given")
+    if (!identifier) throw new Error("No identifier was given")
+
+    this.identifier = identifier
+    this.logger = new Logger(this)
+  }
+
+  /**
+   * Runs checkin.
+   * @abstract
+   * @param {import("../drivers/base.js").default} _connection - Connection.
+   */
+  checkin(_connection) {
+    throw new Error("'checkin' not implemented")
+  }
+
+  /**
+   * Runs checkout.
+   * @abstract
+   * @param {ConnectionCheckoutOptions} [_options] - Checkout options.
+   * @returns {Promise<import("../drivers/base.js").default>} - Resolves with the checkout.
+   */
+  checkout(_options) {
+    throw new Error("'checkout' not implemented")
+  }
+
+  /**
+   * Runs get current connection.
+   * @abstract
+   * @returns {import("../drivers/base.js").default} - The current connection.
+   */
+  getCurrentConnection() {
+    throw new Error("'getCurrentConnection' not implemented")
+  }
+
+  /**
+   * Returns the connection pinned to the current context, if any.
+   * Default implementation defers to `getCurrentConnection`.
+   * @returns {import("../drivers/base.js").default | undefined} - The current context connection.
+   */
+  getCurrentContextConnection() {
+    return this.getCurrentConnection()
+  }
+
+  /**
+   * Runs without current connection context.
+   * @template T
+   * @param {() => T} callback - Callback to run without ? current connection context.
+   * @returns {T} - Callback result.
+   */
+  withoutCurrentConnectionContext(callback) {
+    if (this._withoutCurrentConnectionContext) return /** Narrows the runtime value to the documented type. @type {T} */ (this._withoutCurrentConnectionContext(callback))
+
+    return callback()
+  }
+
+  /**
+   * Runs get configuration.
+   * @returns {import("../../configuration-types.js").DatabaseConfigurationType} - Resolved database configuration for the pool identifier.
+   */
+  getConfiguration() {
+    return this.configuration.resolveDatabaseConfiguration(this.identifier)
+  }
+
+  /**
+   * Runs get configuration reuse key.
+   * @returns {string} - Reuse key for the currently resolved database configuration.
+   */
+  getConfigurationReuseKey() {
+    const databaseConfiguration = this.getConfiguration()
+
+    return stableStringify({
+      database: databaseConfiguration.database,
+      host: databaseConfiguration.host,
+      name: databaseConfiguration.name,
+      port: databaseConfiguration.port,
+      schema: databaseConfiguration.schema,
+      schemaCache: databaseConfiguration.schemaCache,
+      sqlConfig: databaseConfiguration.sqlConfig,
+      type: databaseConfiguration.type,
+      useDatabase: databaseConfiguration.useDatabase,
+      username: databaseConfiguration.username
+    })
+  }
+
+  /**
+   * Runs connection matches current configuration.
+   * @param {import("../drivers/base.js").default} connection - Connection.
+   * @returns {boolean} - Whether connection matches current resolved configuration.
+   */
+  connectionMatchesCurrentConfiguration(connection) {
+    const connectionWithPoolKey = /**
+                                   * Narrows the runtime value to the documented type.
+                                    @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
+
+    return connectionWithPoolKey[POOL_CONFIGURATION_KEY] === this.getConfigurationReuseKey()
+  }
+
+  /**
+   * Clears schema metadata cached by this pool's current connection.
+   * Pools that keep multiple connections alive should override this to clear every live connection.
+   * @returns {void} - No return value.
+   */
+  clearSchemaCache() {
+    this._clearConnectionSchemaCache(this.getCurrentConnection())
+  }
+
+  /**
+   * Runs clear connection schema cache.
+   * @param {import("../drivers/base.js").default} connection - Connection whose local schema cache should be cleared.
+   * @returns {void} - No return value.
+   */
+  _clearConnectionSchemaCache(connection) {
+    connection._clearLocalSchemaCache()
+  }
+
+  /**
+   * Runs primary key type.
+   * @abstract
+   * @returns {string} - The primary key type.
+   */
+  primaryKeyType() {
+    throw new Error("'primaryKeyType' not implemented")
+  }
+
+  /**
+   * Runs set current.
+   * @returns {void} - No return value.
+   */
+  setCurrent() {
+    shared.currentPool = this
+  }
+
+  /**
+   * Runs set driver class.
+   * @param {typeof import("../drivers/base.js").default} driverClass - Driver class.
+   */
+  setDriverClass(driverClass) {
+    this.driverClass = driverClass
+  }
+
+  /**
+   * Runs spawn connection.
+   * @returns {Promise<import("../drivers/base.js").default>} - Resolves with the spawn connection.
+   */
+  async spawnConnection() {
+    const databaseConfig = this.getConfiguration()
+
+    this.logger.debug("spawnConnection", {identifier: this.identifier, databaseConfig})
+
+    const connection = await this.spawnConnectionWithConfiguration(databaseConfig)
+
+    const connectionWithPoolKey = /**
+                                   * Narrows the runtime value to the documented type.
+                                    @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
+    connectionWithPoolKey[POOL_CONFIGURATION_KEY] = this.getConfigurationReuseKey()
+    connection.setSchemaCacheInvalidator(() => {
+      this.clearSchemaCache()
+      this.configuration.clearSchemaCachesForReuseKey(this.getConfigurationReuseKey())
+    })
+
+    return connection
+  }
+
+  /**
+   * Runs spawn connection with configuration.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} config - Configuration object.
+   * @returns {Promise<import("../drivers/base.js").default>} - Resolves with the spawn connection with configuration.
+   */
+  async spawnConnectionWithConfiguration(config) {
+    const DriverClass = config.driver || this.driverClass
+
+    if (!DriverClass) throw new Error("No driver class set in database pool or in given config")
+
+    const connection = new DriverClass(config, this.configuration)
+
+    try {
+      await connection.connect()
+    } catch (error) {
+      await this.closeConnectionAfterFailedConnect(connection)
+      throw error
+    }
+
+    return connection
+  }
+
+  /**
+   * Runs close connection after failed connect.
+   * @param {import("../drivers/base.js").default} connection - Connection to close.
+   * @returns {Promise<void>} - Resolves when cleanup has been attempted.
+   */
+  async closeConnectionAfterFailedConnect(connection) {
+    try {
+      await connection.close()
+    } catch (error) {
+      this.logger.warn("Failed to close database connection after connect failed", {error})
+    }
+  }
+
+  /**
+   * Runs with connection.
+   * @template T
+   * @abstract
+   * @param {ConnectionCheckoutOptions | function(import("../drivers/base.js").default) : Promise<T>} _optionsOrCallback - Checkout options or callback function.
+   * @param {function(import("../drivers/base.js").default) : Promise<T>} [_callback] - Callback function.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  withConnection(_optionsOrCallback, _callback) {
+    throw new Error("'withConnection' not implemented")
+  }
+
+  /**
+   * Ensures a reusable connection exists for contexts where AsyncLocalStorage isn't set.
+   * Default implementation just checks out a connection.
+   * @returns {Promise<import("../drivers/base.js").default>} - Resolves with the global connection.
+   */
+  async ensureGlobalConnection() {
+    return await this.checkout()
+  }
+
+  /**
+   * Runs get debug snapshot.
+   * @returns {DatabasePoolDebugSnapshot} - Diagnostic snapshot for this pool.
+   */
+  getDebugSnapshot() {
+    return {
+      configuration: this.debugConfigurationSnapshot(),
+      connections: [],
+      connectionsBeingSpawned: 0,
+      identifier: this.identifier,
+      idleCount: 0,
+      inUseCount: 0,
+      pendingCheckoutCount: 0,
+      poolClass: this.constructor.name
+    }
+  }
+
+  /**
+   * Runs debug configuration snapshot.
+   * @returns {Record<string, ?>} - Sanitized resolved database configuration.
+   */
+  debugConfigurationSnapshot() {
+    const databaseConfig = this.getConfiguration()
+    const poolConfig = databaseConfig.pool
+
+    return {
+      database: databaseConfig.database,
+      driver: databaseConfig.driver?.name,
+      host: databaseConfig.host,
+      migrations: databaseConfig.migrations,
+      name: databaseConfig.name,
+      pool: poolConfig ? {idleTimeoutMillis: poolConfig.idleTimeoutMillis, max: poolConfig.max} : undefined,
+      port: databaseConfig.port,
+      schema: databaseConfig.schema,
+      type: databaseConfig.type,
+      useDatabase: databaseConfig.useDatabase,
+      username: databaseConfig.username
+    }
+  }
+
+  /**
+   * Runs debug connection snapshot.
+   * @param {import("../drivers/base.js").default} connection - Database connection.
+   * @param {Record<string, ?>} details - Extra diagnostic fields.
+   * @returns {Record<string, ?>} - Connection diagnostic snapshot.
+   */
+  debugConnectionSnapshot(connection, details = {}) {
+    const connectionWithPoolKey = /**
+                                   * Narrows the runtime value to the documented type.
+                                    @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
+
+    return {
+      ...connection.getDebugSnapshot(),
+      ...details,
+      reuseKey: connectionWithPoolKey[POOL_CONFIGURATION_KEY]
+    }
+  }
+
+  /**
+   * Closes all connections for this pool.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async closeAll() {}
+}
+
+baseMethodsForward(VelociousDatabasePoolBase)
+
+export default VelociousDatabasePoolBase

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

@@ -0,0 +1,118 @@
+// @ts-check
+
+import BasePool from "./base.js"
+
+export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
+  /**
+   * Runs checkin.
+   * @param {import("../drivers/base.js").default} connection - Connection.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async checkin(connection) {
+    await connection.clearConnectionCheckoutName()
+  }
+
+  /**
+   * Runs checkout.
+   * @param {import("./base.js").ConnectionCheckoutOptions} [options] - Checkout options.
+   * @returns {Promise<import("../drivers/base.js").default>} - Resolves with the checkout.
+   */
+  async checkout(options = {}) {
+    if (this.connection && !this.connectionMatchesCurrentConfiguration(this.connection)) {
+      const previousConnection = this.connection
+
+      this.connection = undefined
+
+      await previousConnection.close()
+    }
+
+    if (!this.connection) {
+      this.connection = await this.spawnConnection()
+    }
+
+    await this.connection.setConnectionCheckoutName(options.name)
+
+    return this.connection
+  }
+
+  /**
+   * Runs with connection.
+   * @template T
+   * @param {import("./base.js").ConnectionCheckoutOptions | function(import("../drivers/base.js").default) : Promise<T>} optionsOrCallback - Checkout options or callback function.
+   * @param {function(import("../drivers/base.js").default) : Promise<T>} [callback] - Callback function.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withConnection(optionsOrCallback, callback) {
+    const options = typeof optionsOrCallback == "function" ? {} : optionsOrCallback
+
+    const connection = await this.checkout(options)
+
+    try {
+      if (typeof optionsOrCallback == "function") return await optionsOrCallback(connection)
+
+      if (!callback) throw new Error("withConnection requires a callback")
+
+      return await callback(connection)
+    } finally {
+      await this.checkin(connection)
+    }
+  }
+
+  /**
+   * Clears schema metadata cached by the reusable connection if it exists.
+   * @returns {void} - No return value.
+   */
+  clearSchemaCache() {
+    if (this.connection) this._clearConnectionSchemaCache(this.connection)
+  }
+
+  /**
+   * Closes the cached connection if it exists.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async closeAll() {
+    if (!this.connection) return
+
+    const connection = this.connection
+
+    this.connection = undefined
+
+    await connection.close()
+  }
+
+  /**
+   * Runs get current connection.
+   * @returns {import("../drivers/base.js").default} - The current connection.
+   */
+  getCurrentConnection() {
+    if (!this.connection) {
+      throw new Error("A connection hasn't been made yet")
+    }
+
+    return this.connection
+  }
+
+  /**
+   * Runs get current context connection.
+   * @returns {import("../drivers/base.js").default | undefined} - The current context connection.
+   */
+  getCurrentContextConnection() {
+    return this.connection
+  }
+
+  /**
+   * Runs get debug snapshot.
+   * @returns {import("./base.js").DatabasePoolDebugSnapshot} - Diagnostic snapshot for this pool.
+   */
+  getDebugSnapshot() {
+    const connections = this.connection
+      ? [this.debugConnectionSnapshot(this.connection, {state: "shared"})]
+      : []
+
+    return {
+      ...super.getDebugSnapshot(),
+      connections,
+      idleCount: this.connection ? 1 : 0
+    }
+  }
+}

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

@@ -0,0 +1,104 @@
+// @ts-check
+
+import QueryBase from "./base.js"
+import restArgsError from "../../utils/rest-args-error.js"
+import TableData from "../table-data/index.js"
+
+export default class VelociousDatabaseQueryAlterTableBase extends QueryBase {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../drivers/base.js").default} args.driver - Database driver instance.
+   * @param {TableData} args.tableData - Table data.
+   */
+  constructor({driver, tableData, ...restArgs}) {
+    restArgsError(restArgs)
+
+    if (!(tableData instanceof TableData)) throw new Error("Invalid table data was given")
+
+    super({driver})
+    this.tableData = tableData
+  }
+
+  /**
+   * Runs to sqls.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async toSQLs() {
+    const databaseType = this.getDriver().getType()
+    const sqls = []
+    const {tableData} = this
+    const options = this.getOptions()
+
+    let sql = `ALTER TABLE ${options.quoteTableName(tableData.getName())} `
+    let actionCount = 0
+
+    for (const column of tableData.getColumns()) {
+      if (actionCount > 0) sql += ", "
+
+      if (column.isNewColumn()) {
+        sql += databaseType == "mssql" ? "ADD " : "ADD COLUMN "
+        sql += column.getSQL({driver: this.getDriver(), forAlterTable: false})
+      } else if (column.getNewName()) {
+        const newColumnName = column.getNewName()
+
+        if (!newColumnName) throw new Error(`Expected new column name for ${column.getName()}`)
+
+        sql += `RENAME COLUMN ${options.quoteColumnName(column.getName())} TO ${options.quoteColumnName(newColumnName)}`
+      } else if (column.getDropColumn()) {
+        sql += `DROP COLUMN ${options.quoteColumnName(column.getName())}`
+      } else {
+        if (databaseType == "mssql" || databaseType == "pgsql") {
+          sql += "ALTER COLUMN "
+        } else {
+          sql += "MODIFY "
+        }
+
+        sql += column.getSQL({driver: this.getDriver(), forAlterTable: true})
+      }
+
+
+      actionCount++
+    }
+
+    // SQLite's ALTER TABLE does not support adding constraints; the SQLite driver overrides
+    // alterTableSQLs entirely (via TableRebuilder) so this base path is never invoked there.
+    for (const foreignKey of tableData.getForeignKeys()) {
+      if (!foreignKey.getIsNewForeignKey()) continue
+
+      if (actionCount > 0) sql += ", "
+
+      sql += "ADD"
+
+      if (foreignKey.getName()) {
+        sql += ` CONSTRAINT ${options.quoteIndexName(foreignKey.getName())}`
+      }
+
+      sql += ` FOREIGN KEY (${options.quoteColumnName(foreignKey.getColumnName())})`
+      sql += ` REFERENCES ${options.quoteTableName(foreignKey.getReferencedTableName())} (${options.quoteColumnName(foreignKey.getReferencedColumnName())})`
+
+      actionCount++
+    }
+
+    if (actionCount > 0) {
+      sqls.push(sql)
+    }
+
+    if (databaseType == "pgsql") {
+      for (const column of tableData.getColumns()) {
+      if (!column.isNewColumn() || column.getDropColumn()) continue
+
+      const notes = column.getNotesForDatabase(databaseType)
+      const actualName = column.getActualName()
+
+      if (!notes || !actualName) continue
+
+      sqls.push(
+        `COMMENT ON COLUMN ${options.quoteTableName(tableData.getName())}.${options.quoteColumnName(actualName)} IS ${options.quote(notes)}`
+      )
+      }
+    }
+
+    return sqls
+  }
+}

package/build/database/query/base.js

@@ -0,0 +1,49 @@
+// @ts-check
+
+import restArgsError from "../../utils/rest-args-error.js"
+
+export default class VelociousDatabaseQueryBase {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../drivers/base.js").default} args.driver - Database driver instance.
+   * @param {import("../query-parser/options.js").default} [args.options] - Options object.
+   */
+  constructor({driver, options, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this._driver = driver
+    this._options = options || driver.options()
+
+    if (!this._options) throw new Error("No database options was given or could be gotten from driver")
+  }
+
+  getConfiguration() {
+    return this.getDriver().getConfiguration()
+  }
+
+  getDriver() {
+    return this._driver
+  }
+
+  /**
+   * Runs get options.
+   * @returns {import("../query-parser/options.js").default} - The options options.
+   */
+  getOptions() {
+    return this._options
+  }
+
+  getDatabaseType() {
+    return this.getDriver().getType()
+  }
+
+  /**
+   * Runs to sqls.
+   * @abstract
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async toSQLs() {
+    throw new Error("'toSQLs' wasn't implemented")
+  }
+}