velocious 1.0.447 → 1.0.449

package/README.md

@@ -22,7 +22,7 @@
 * EJS-backed mailers with delivery, queueing, and payload rendering support (see [docs/mailers.md](docs/mailers.md))
 * Trusted reverse proxy handling for `request.remoteAddress()` (see [docs/trusted-proxies.md](docs/trusted-proxies.md))
 * In-process driver schema metadata caching (see [docs/schema-metadata-cache.md](docs/schema-metadata-cache.md))
-* Named database connection checkouts for debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
+* Named database connection checkouts, bounded pool waits, and debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
 
 # Setup

package/build/configuration-types.js

@@ -47,12 +47,14 @@
  * @property {number | null} [pool.max] - Maximum number of connections. Set null to disable the cap.
  * @property {number} [pool.min] - Minimum number of connections.
  * @property {number} [pool.idleTimeoutMillis] - Idle timeout before releasing a connection.
+ * @property {number | null} [pool.checkoutTimeoutMillis] - Timeout while waiting for an available connection after the max connection cap is reached. Set null to wait indefinitely.
  * @property {string} [server] - SQL server hostname.
  * @property {string} [user] - SQL username.
  */
 
 /**
  * @typedef {object} DatabasePoolConfiguration
+ * @property {number | null} [checkoutTimeoutMillis] - Timeout while a checkout waits for an available async-tracked connection after the max live connection cap is reached. Set null to wait indefinitely. Default: 10000.
  * @property {number | null} [idleTimeoutMillis] - Idle timeout before closing a checked-in async-tracked connection. Set null to disable idle reaping. Default: 5000.
  * @property {number | null} [max] - Maximum live async-tracked connections for this pool. Defaults to 10. Extra checkouts wait until a matching connection is checked in or capacity is freed. Set null to disable the cap.
  */

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

@@ -8,6 +8,7 @@ const IDLE_CONNECTION_CHECKED_IN_AT = Symbol("velociousIdleConnectionCheckedInAt
 const CONNECTION_CHECKED_OUT_AT = Symbol("velociousConnectionCheckedOutAt")
 const DEFAULT_MAX_CONNECTIONS = 10
 const DEFAULT_IDLE_TIMEOUT_MILLIS = 5000
+const DEFAULT_CHECKOUT_TIMEOUT_MILLIS = 10000
 
 /**
  * PendingCheckout type.
@@ -18,6 +19,9 @@ const DEFAULT_IDLE_TIMEOUT_MILLIS = 5000
  * @property {string} reuseKey - Database configuration reuse key needed by the checkout.
  * @property {(connection: import("../drivers/base.js").default) => void} resolve - Resolves with an activated connection.
  * @property {(error: Error) => void} reject - Rejects when checkout cannot complete.
+ * @property {number | null} timeoutAt - Timestamp when the checkout will time out, or null when disabled.
+ * @property {number | null} timeoutMillis - Milliseconds to wait before rejecting, or null when disabled.
+ * @property {ReturnType<typeof setTimeout> | undefined} timeoutTimer - Timer that rejects the pending checkout.
  */
 
 export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends BasePool {
@@ -281,17 +285,39 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs max connections.
-   * @returns {number | undefined} - Configured max live connections.
+   * @returns {number | null} - Configured max live connections.
    */
   maxConnections() {
     const value = this.getConfiguration().pool?.max
 
-    if (value === null) return
+    if (value === null) return null
     if (this.validMaxConnections(value)) return value
 
     return DEFAULT_MAX_CONNECTIONS
   }
 
+  /**
+   * Runs checkout timeout millis.
+   * @returns {number | null} - Pending checkout timeout in milliseconds, or null when disabled.
+   */
+  checkoutTimeoutMillis() {
+    const value = this.getConfiguration().pool?.checkoutTimeoutMillis
+
+    if (value === null) return null
+    if (this.validCheckoutTimeoutMillis(value)) return value
+
+    return DEFAULT_CHECKOUT_TIMEOUT_MILLIS
+  }
+
+  /**
+   * Runs valid checkout timeout millis.
+   * @param {?} value - Candidate checkout timeout.
+   * @returns {value is number} - Whether the value is a valid timeout.
+   */
+  validCheckoutTimeoutMillis(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+  }
+
   /**
    * Runs valid max connections.
    * @param {?} value - Candidate max connection count.
@@ -322,7 +348,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   canSpawnConnection() {
     const maxConnections = this.maxConnections()
 
-    return maxConnections === undefined || this.liveConnectionCount() < maxConnections
+    return maxConnections === null || this.liveConnectionCount() < maxConnections
   }
 
   /**
@@ -361,7 +387,23 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    */
   async waitForCheckout(databaseConfig, reuseKey, options = {}) {
     return await new Promise((resolve, reject) => {
-      this.pendingCheckouts.push({databaseConfig, enqueuedAt: Date.now(), options, reject, resolve, reuseKey})
+      const enqueuedAt = Date.now()
+      const timeoutMillis = this.checkoutTimeoutMillis()
+      /** @type {PendingCheckout} */
+      const checkout = {
+        databaseConfig,
+        enqueuedAt,
+        options,
+        reject,
+        resolve,
+        reuseKey,
+        timeoutAt: timeoutMillis === null ? null : enqueuedAt + timeoutMillis,
+        timeoutMillis,
+        timeoutTimer: undefined
+      }
+
+      checkout.timeoutTimer = this.startPendingCheckoutTimeout(checkout)
+      this.pendingCheckouts.push(checkout)
       void this.drainPendingCheckouts().catch((error) => {
         const checkoutError = error instanceof Error ? error : new Error("Failed to drain pending database connection checkouts.", {cause: error})
 
@@ -400,17 +442,19 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
       const checkout = this.pendingCheckouts[0]
 
       if (await this.closeIdleConnectionForPendingCheckoutCapacity(checkout)) continue
+      if (!this.pendingCheckouts.includes(checkout)) continue
       if (this.canSpawnConnection()) {
-        this.pendingCheckouts.shift()
+        this.removePendingCheckoutAt(0)
         await this.spawnAndResolvePendingCheckout(checkout)
         continue
       }
 
       const reapedConnection = await this.idleConnectionForPendingCheckout(checkout)
 
+      if (!this.pendingCheckouts.includes(checkout)) continue
       if (!reapedConnection) return
 
-      this.pendingCheckouts.shift()
+      this.removePendingCheckoutAt(0)
       await this.resolvePendingCheckout(checkout, reapedConnection)
     }
   }
@@ -426,7 +470,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
       if (!connection) continue
 
-      this.pendingCheckouts.splice(index, 1)
+      this.removePendingCheckoutAt(index)
       await this.resolvePendingCheckout(checkout, connection)
 
       return true
@@ -435,6 +479,71 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     return false
   }
 
+  /**
+   * Runs remove pending checkout at.
+   * @param {number} index - Pending checkout index.
+   * @returns {PendingCheckout} - Removed checkout.
+   */
+  removePendingCheckoutAt(index) {
+    const checkout = this.pendingCheckouts.splice(index, 1)[0]
+
+    this.clearPendingCheckoutTimeout(checkout)
+
+    return checkout
+  }
+
+  /**
+   * Runs start pending checkout timeout.
+   * @param {PendingCheckout} checkout - Pending checkout to time out.
+   * @returns {ReturnType<typeof setTimeout> | undefined} - Timer, if timeout is enabled.
+   */
+  startPendingCheckoutTimeout(checkout) {
+    if (checkout.timeoutMillis === null) return undefined
+
+    const timer = setTimeout(() => {
+      this.timeoutPendingCheckout(checkout)
+    }, checkout.timeoutMillis)
+
+    return timer
+  }
+
+  /**
+   * Runs timeout pending checkout.
+   * @param {PendingCheckout} checkout - Pending checkout to reject.
+   * @returns {void}
+   */
+  timeoutPendingCheckout(checkout) {
+    const index = this.pendingCheckouts.indexOf(checkout)
+
+    if (index === -1) return
+
+    this.removePendingCheckoutAt(index)
+    checkout.reject(this.pendingCheckoutTimeoutError(checkout))
+  }
+
+  /**
+   * Runs pending checkout timeout error.
+   * @param {PendingCheckout} checkout - Timed-out checkout.
+   * @returns {Error} - Timeout error.
+   */
+  pendingCheckoutTimeoutError(checkout) {
+    const checkoutName = checkout.options.name ? ` Checkout name: ${JSON.stringify(checkout.options.name)}.` : ""
+
+    return new Error(`Timed out after ${checkout.timeoutMillis}ms waiting for database connection checkout from pool "${this.identifier}".${checkoutName}`)
+  }
+
+  /**
+   * Runs clear pending checkout timeout.
+   * @param {PendingCheckout} checkout - Pending checkout.
+   * @returns {void}
+   */
+  clearPendingCheckoutTimeout(checkout) {
+    if (!checkout.timeoutTimer) return
+
+    clearTimeout(checkout.timeoutTimer)
+    checkout.timeoutTimer = undefined
+  }
+
   /**
    * Runs close idle connection for pending checkout capacity.
    * @param {PendingCheckout} checkout - Checkout waiting for a connection.
@@ -472,6 +581,8 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     if (connection) return connection
 
     await this.reapIdleConnections()
+    if (!this.pendingCheckouts.includes(checkout)) return
+
     connection = this.takeIdleConnectionForReuseKey(checkout.reuseKey, {includeOpenTransactions: false})
 
     return connection
@@ -762,14 +873,17 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   /**
    * Runs pending checkout debug snapshots.
    * @param {number} now - Current timestamp.
-   * @returns {Array<Record<string, ?>>} - Pending checkout snapshots.
+   * @returns {import("./base.js").DatabasePoolPendingCheckoutDebugSnapshot[]} - Pending checkout snapshots.
    */
   pendingCheckoutDebugSnapshots(now) {
     return this.pendingCheckouts.map((checkout, index) => ({
       checkoutName: checkout.options.name,
       enqueuedAt: checkout.enqueuedAt,
       index,
+      remainingTimeoutMs: checkout.timeoutAt === null ? null : Math.max(0, checkout.timeoutAt - now),
       reuseKey: checkout.reuseKey,
+      timeoutAt: checkout.timeoutAt,
+      timeoutMillis: checkout.timeoutMillis,
       waitingForMs: Math.max(0, now - checkout.enqueuedAt)
     }))
   }
@@ -1131,6 +1245,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     this.pendingCheckouts = []
 
     for (const checkout of pendingCheckouts) {
+      this.clearPendingCheckoutTimeout(checkout)
       checkout.reject(error)
     }
   }

package/build/database/pool/base.js

@@ -12,6 +12,19 @@ export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
  * @property {string} [name] - Human-readable name for the checked-out connection.
  */
 
+/**
+ * DatabasePoolPendingCheckoutDebugSnapshot type.
+ * @typedef {object} DatabasePoolPendingCheckoutDebugSnapshot
+ * @property {string | undefined} checkoutName - Human-readable checkout name.
+ * @property {number} enqueuedAt - Timestamp when the checkout started waiting.
+ * @property {number} index - Pending checkout queue index.
+ * @property {number | null} remainingTimeoutMs - Milliseconds before the checkout times out, or null when disabled.
+ * @property {string} reuseKey - Database configuration reuse key needed by the checkout.
+ * @property {number | null} timeoutAt - Timestamp when the checkout will time out, or null when disabled.
+ * @property {number | null} timeoutMillis - Timeout configured for the checkout, or null when disabled.
+ * @property {number} waitingForMs - Milliseconds already spent waiting.
+ */
+
 /**
  * DatabasePoolDebugSnapshot type.
  * @typedef {object} DatabasePoolDebugSnapshot
@@ -21,7 +34,7 @@ export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
  * @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 {Array<DatabasePoolPendingCheckoutDebugSnapshot>} [pendingCheckouts] - Waiting checkout snapshots.
  * @property {number} pendingCheckoutCount - Number of queued checkout requests.
  * @property {string} poolClass - Pool class name.
  */

package/build/database/record/index.js

@@ -222,6 +222,10 @@ class TenantDatabaseScopeError extends Error {
   }
 }
 
+/**
+ * Base database record.
+ * @template {Record<string, ?>} [WriteAttributes=Record<string, ?>]
+ */
 class VelociousDatabaseRecord {
   /**
    * Narrows the runtime value to the documented type.
@@ -1150,17 +1154,18 @@ class VelociousDatabaseRecord {
 
   /**
    * Runs create.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {Record<string, ?>} [attributes] - Attributes.
-   * @returns {Promise<InstanceType<MC>>} - Resolves with the create.
+   * @template {Record<string, ?>} CreateAttributes
+   * @template {VelociousDatabaseRecord<CreateAttributes>} Model
+   * @this {{new (changes?: CreateAttributes): Model} & typeof VelociousDatabaseRecord}
+   * @param {CreateAttributes} [attributes] - Attributes.
+   * @returns {Promise<Model>} - Resolves with the create.
    */
   static async create(attributes) {
     await this.ensureInitialized()
 
     const record = /**
                     * Narrows the runtime value to the documented type.
-                     @type {InstanceType<MC>} */ (new this(attributes))
+                     @type {Model} */ (new this(attributes))
 
     await record.save()
 
@@ -3353,9 +3358,9 @@ class VelociousDatabaseRecord {
 
   /**
    * Runs constructor.
-   * @param {Record<string, ?>} changes - Changes.
+   * @param {WriteAttributes} changes - Changes.
    */
-  constructor(changes = {}) {
+  constructor(changes = /** @type {WriteAttributes} */ ({})) {
     this.getModelClass()._assertHasBeenInitialized()
     this._attributes = {}
     this._changes = {}
@@ -4256,7 +4261,7 @@ class VelociousDatabaseRecord {
 
   /**
    * Assigns the attributes to the record and saves it.
-   * @param {object} attributesToAssign - The attributes to assign to the record.
+   * @param {WriteAttributes} attributesToAssign - The attributes to assign to the record.
    */
   async update(attributesToAssign) {
     if (attributesToAssign) this.assign(attributesToAssign)

package/build/environment-handlers/node/cli/commands/generate/base-models.js

@@ -139,24 +139,9 @@ export default class DbGenerateModel extends BaseCommand {
 
         const hasManyRelationFilePath = `${velociousPath}/database/record/instance-relationships/has-many.js`
 
+        fileContent += `/** @augments {DatabaseRecord<${writeAttributeTypeName}>} */\n`
         fileContent += `export default class ${modelNameCamelized}Base extends DatabaseRecord {\n`
 
-        fileContent += "  /**\n"
-        fileContent += `   * Creates a ${modelNameCamelized} record.\n`
-        fileContent += `   * @template {typeof ${modelNameCamelized}Base} T\n`
-        fileContent += "   * @this {T}\n"
-        fileContent += `   * @param {${writeAttributeTypeName}} [attributes] - Attributes for the new record.\n`
-        fileContent += "   * @returns {Promise<InstanceType<T>>} - Persisted record.\n"
-        fileContent += "   */\n"
-        fileContent += "  static async create(attributes) { return /** @type {Promise<InstanceType<T>>} */ (super.create(attributes)) }\n\n"
-
-        fileContent += "  /**\n"
-        fileContent += `   * Updates this ${modelNameCamelized} record.\n`
-        fileContent += `   * @param {${writeAttributeTypeName}} attributes - Attributes to assign before saving.\n`
-        fileContent += "   * @returns {Promise<void>} - Resolves when the record is saved.\n"
-        fileContent += "   */\n"
-        fileContent += "  async update(attributes) { return await super.update(attributes) }\n\n"
-
       // --- getModelClass() override (fixes polymorphic typing in JS/JSDoc) ---
       if (await fileExists(sourceModelFullFilePath)) {
         // Model file exists (e.g. src/models/ticket.js) → return typeof Ticket