velocious 1.0.461 → 1.0.463

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

@@ -99,9 +99,12 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    */
   constructor({configuration, identifier}) {
     super({configuration, identifier})
-    this._withoutCurrentConnectionContext = /**
-                                             * Narrows the runtime value to the documented type.
-                                             * @type {(callback: () => ?) => ?} */ ((callback) => this.asyncLocalStorage.run(undefined, callback))
+    /**
+     * Runs a callback without the inherited current connection context.
+     * @type {(callback: () => ?) => ?}
+     */
+    const withoutCurrentConnectionContext = (callback) => this.asyncLocalStorage.run(undefined, callback)
+    this._withoutCurrentConnectionContext = withoutCurrentConnectionContext
   }
 
   /**
@@ -111,9 +114,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    */
   async checkin(connection) {
     const id = connection.getIdSeq()
-    const trackedConnection = /**
-                               * Narrows the runtime value to the documented type.
-                               * @type {import("../drivers/base.js").default & {[CLOSED_CONNECTION]?: boolean, [CONNECTION_CHECKED_OUT_AT]?: number, [IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
+    const trackedConnection = /** @type {import("../drivers/base.js").default & {[CLOSED_CONNECTION]?: boolean, [CONNECTION_CHECKED_OUT_AT]?: number, [IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
 
     if (trackedConnection[CLOSED_CONNECTION]) {
       this.untrackConnectionInUse(connection, id)
@@ -243,9 +244,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {boolean} - Whether the connection matches the reuse key.
    */
   connectionMatchesReuseKey(connection, reuseKey) {
-    const connectionWithPoolKey = /**
-                                   * Narrows the runtime value to the documented type.
-                                   * @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
+    const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
 
     return connectionWithPoolKey[POOL_CONFIGURATION_KEY] === reuseKey
   }
@@ -261,9 +260,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
     const id = this.idSeq++
 
-    const trackedConnection = /**
-                               * Narrows the runtime value to the documented type.
-                               * @type {import("../drivers/base.js").default & {[CONNECTION_CHECKED_OUT_AT]?: number, [IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
+    const trackedConnection = /** @type {import("../drivers/base.js").default & {[CONNECTION_CHECKED_OUT_AT]?: number, [IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
     delete trackedConnection[IDLE_CONNECTION_CHECKED_IN_AT]
     trackedConnection[CONNECTION_CHECKED_OUT_AT] = Date.now()
 
@@ -362,9 +359,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
     try {
       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)
+      const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
 
       connectionWithPoolKey[POOL_CONFIGURATION_KEY] = reuseKey
       connection.setSchemaCacheInvalidator(() => {
@@ -528,8 +523,65 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    */
   pendingCheckoutTimeoutError(checkout) {
     const checkoutName = checkout.options.name ? ` Checkout name: ${JSON.stringify(checkout.options.name)}.` : ""
+    const diagnostics = this.pendingCheckoutTimeoutDiagnostics(checkout)
+
+    return new Error(`Timed out after ${checkout.timeoutMillis}ms waiting for database connection checkout from pool "${this.identifier}".${checkoutName} ${diagnostics}`)
+  }
+
+  /**
+   * Builds sanitized diagnostics for a checkout timeout.
+   * @param {PendingCheckout} checkout - Timed-out checkout.
+   * @returns {string} - Pool state summary.
+   */
+  pendingCheckoutTimeoutDiagnostics(checkout) {
+    const snapshot = this.getDebugSnapshot()
+    const connectionSummaries = snapshot.connections
+      .map((connection) => this.pendingCheckoutTimeoutConnectionSummary(connection))
+      .join(", ")
+    const pendingSummaries = (snapshot.pendingCheckouts || [])
+      .map((pendingCheckout) => this.pendingCheckoutTimeoutPendingSummary(pendingCheckout))
+      .join(", ")
+    const waitedForMs = Math.max(0, Date.now() - checkout.enqueuedAt)
 
-    return new Error(`Timed out after ${checkout.timeoutMillis}ms waiting for database connection checkout from pool "${this.identifier}".${checkoutName}`)
+    return `Pool state: max=${this.maxConnections() ?? "unbounded"}, inUse=${snapshot.inUseCount}, idle=${snapshot.idleCount}, pending=${snapshot.pendingCheckoutCount}, spawning=${snapshot.connectionsBeingSpawned}, timedOutWaitingForMs=${waitedForMs}, holders=[${connectionSummaries}], waiting=[${pendingSummaries}].`
+  }
+
+  /**
+   * Builds a sanitized connection summary for checkout timeout diagnostics.
+   * @param {Record<string, ?>} connection - Connection debug snapshot.
+   * @returns {string} - Sanitized connection state.
+   */
+  pendingCheckoutTimeoutConnectionSummary(connection) {
+    const parts = [`state=${connection.state}`]
+
+    if (connection.checkoutName) parts.push(`checkout=${JSON.stringify(connection.checkoutName)}`)
+    if (typeof connection.checkedOutForMs === "number") parts.push(`checkedOutForMs=${connection.checkedOutForMs}`)
+    if (typeof connection.idleForMs === "number") parts.push(`idleForMs=${connection.idleForMs}`)
+    if (typeof connection.openTransactions === "number") parts.push(`openTransactions=${connection.openTransactions}`)
+
+    const activeQuery = connection.activeQuery
+
+    if (activeQuery && typeof activeQuery === "object" && !Array.isArray(activeQuery)) {
+      const runningMs = (/** @type {Record<string, ?>} */ (activeQuery)).runningMs
+
+      if (typeof runningMs === "number") parts.push(`activeQueryMs=${runningMs}`)
+    }
+
+    return `{${parts.join(" ")}}`
+  }
+
+  /**
+   * Builds a sanitized pending checkout summary for checkout timeout diagnostics.
+   * @param {import("./base.js").DatabasePoolPendingCheckoutDebugSnapshot} pendingCheckout - Waiting checkout snapshot.
+   * @returns {string} - Sanitized pending checkout state.
+   */
+  pendingCheckoutTimeoutPendingSummary(pendingCheckout) {
+    const parts = [`index=${pendingCheckout.index}`, `waitingForMs=${pendingCheckout.waitingForMs}`]
+
+    if (pendingCheckout.checkoutName) parts.push(`checkout=${JSON.stringify(pendingCheckout.checkoutName)}`)
+    if (pendingCheckout.remainingTimeoutMs !== null) parts.push(`remainingTimeoutMs=${pendingCheckout.remainingTimeoutMs}`)
+
+    return `{${parts.join(" ")}}`
   }
 
   /**
@@ -709,9 +761,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {void} - No return value.
    */
   setGlobalConnection(connection) {
-    const klass = /**
-                   * Narrows the runtime value to the documented type.
-                   * @type {typeof VelociousDatabasePoolAsyncTrackedMultiConnection} */ (this.constructor)
+    const klass = /** @type {typeof VelociousDatabasePoolAsyncTrackedMultiConnection} */ (this.constructor)
     let mapForConfiguration = klass.globalConnections.get(this.configuration)
 
     if (!mapForConfiguration) {
@@ -770,6 +820,14 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     return this.getCurrentConnection()
   }
 
+  /**
+   * Returns whether this pool has a real async context for the current connection.
+   * @returns {boolean} - Whether nested code can reuse the current connection context.
+   */
+  hasCurrentConnectionContext() {
+    return this.asyncLocalStorage.getStore() !== undefined
+  }
+
   /**
    * Runs get debug snapshot.
    * @returns {import("./base.js").DatabasePoolDebugSnapshot} - Diagnostic snapshot for this pool.
@@ -816,9 +874,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    */
   addInUseDebugConnectionSnapshots({connections, now, seenConnections}) {
     for (const [id, connection] of Object.entries(this.connectionsInUse)) {
-      const trackedConnection = /**
-                                 * Narrows the runtime value to the documented type.
-                                 * @type {import("../drivers/base.js").default & {[CONNECTION_CHECKED_OUT_AT]?: number}} */ (connection)
+      const trackedConnection = /** @type {import("../drivers/base.js").default & {[CONNECTION_CHECKED_OUT_AT]?: number}} */ (connection)
       const checkedOutAt = trackedConnection[CONNECTION_CHECKED_OUT_AT]
       const checkedOutForMs = typeof checkedOutAt === "number" ? Math.max(0, now - checkedOutAt) : undefined
 
@@ -838,9 +894,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
       seenConnections.add(connection)
 
-      const trackedConnection = /**
-                                 * Narrows the runtime value to the documented type.
-                                 * @type {import("../drivers/base.js").default & {[IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
+      const trackedConnection = /** @type {import("../drivers/base.js").default & {[IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
       const checkedInAt = trackedConnection[IDLE_CONNECTION_CHECKED_IN_AT]
       const idleForMs = typeof checkedInAt === "number" ? Math.max(0, now - checkedInAt) : undefined
 
@@ -906,9 +960,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {import("../drivers/base.js").default | undefined} - The global connection for this pool identifier.
    */
   getGlobalConnectionForIdentifier() {
-    const klass = /**
-                   * Narrows the runtime value to the documented type.
-                   * @type {typeof VelociousDatabasePoolAsyncTrackedMultiConnection} */ (this.constructor)
+    const klass = /** @type {typeof VelociousDatabasePoolAsyncTrackedMultiConnection} */ (this.constructor)
     const mapForConfiguration = klass.globalConnections.get(this.configuration)
 
     return mapForConfiguration?.[this.identifier]
@@ -919,9 +971,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {void} - No return value.
    */
   clearGlobalConnectionForIdentifier() {
-    const klass = /**
-                   * Narrows the runtime value to the documented type.
-                   * @type {typeof VelociousDatabasePoolAsyncTrackedMultiConnection} */ (this.constructor)
+    const klass = /** @type {typeof VelociousDatabasePoolAsyncTrackedMultiConnection} */ (this.constructor)
     const mapForConfiguration = klass.globalConnections.get(this.configuration)
 
     if (!mapForConfiguration) return
@@ -975,9 +1025,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     if (this.idleConnectionReaperTimer) return
     if (!this.hasIdleConnectionsToReap()) return
 
-    const delay = this.nextIdleConnectionReapDelay(/**
-                                                    * Narrows the runtime value to the documented type.
-                                                    * @type {number} */ (this.idleTimeoutMillis()))
+    const delay = this.nextIdleConnectionReapDelay(/** @type {number} */ (this.idleTimeoutMillis()))
 
     this.idleConnectionReaperTimer = setTimeout(() => {
       this.idleConnectionReaperTimer = undefined
@@ -1011,9 +1059,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     for (const connection of this.connections) {
       if (this.connectionHasOpenTransaction(connection)) continue
 
-      const trackedConnection = /**
-                                 * Narrows the runtime value to the documented type.
-                                 * @type {import("../drivers/base.js").default & {[IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
+      const trackedConnection = /** @type {import("../drivers/base.js").default & {[IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
       const checkedInAt = trackedConnection[IDLE_CONNECTION_CHECKED_IN_AT]
 
       if (typeof checkedInAt !== "number") continue
@@ -1109,9 +1155,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {boolean} - Whether the connection is marked closed.
    */
   connectionIsClosed(connection) {
-    const trackedConnection = /**
-                               * Narrows the runtime value to the documented type.
-                               * @type {import("../drivers/base.js").default & {[CLOSED_CONNECTION]?: boolean}} */ (connection)
+    const trackedConnection = /** @type {import("../drivers/base.js").default & {[CLOSED_CONNECTION]?: boolean}} */ (connection)
 
     return Boolean(trackedConnection[CLOSED_CONNECTION])
   }
@@ -1122,9 +1166,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {boolean} - Whether the idle connection expired.
    */
   idleConnectionExpired({connection, idleTimeoutMillis, now}) {
-    const trackedConnection = /**
-                               * Narrows the runtime value to the documented type.
-                               * @type {import("../drivers/base.js").default & {[IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
+    const trackedConnection = /** @type {import("../drivers/base.js").default & {[IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
     const checkedInAt = trackedConnection[IDLE_CONNECTION_CHECKED_IN_AT]
 
     return typeof checkedInAt === "number" && now - checkedInAt >= idleTimeoutMillis
@@ -1174,9 +1216,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
       return await existingClose
     }
 
-    const trackedConnection = /**
-                               * Narrows the runtime value to the documented type.
-                               * @type {import("../drivers/base.js").default & {[CLOSED_CONNECTION]?: boolean, [CONNECTION_CHECKED_OUT_AT]?: number, [IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
+    const trackedConnection = /** @type {import("../drivers/base.js").default & {[CLOSED_CONNECTION]?: boolean, [CONNECTION_CHECKED_OUT_AT]?: number, [IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
 
     trackedConnection[CLOSED_CONNECTION] = true
     delete trackedConnection[CONNECTION_CHECKED_OUT_AT]

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

@@ -28,20 +28,12 @@ export default function baseMethodsForward(PoolBase) {
     "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))
+  const prototype = /** @type {Record<string, (...args: Array<?>) => ?>} */ (/** @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 connectionRecord = /** @type {Record<string, (...args: Array<?>) => ?>} */ (/** @type {?} */ (connection))
       const connectionMethod = connectionRecord[forwardMethod]
 
       if (!connectionMethod) throw new Error(`${forwardMethod} isn't defined on driver`)

package/src/database/pool/base.js

@@ -58,13 +58,9 @@ function stableStringify(value) {
 
   if (value && typeof value === "object") {
     const entries = Object
-      .keys(/**
-             * Narrows the runtime value to the documented type.
-             * @type {Record<string, ?>} */ (value))
+      .keys(/** @type {Record<string, ?>} */ (value))
       .sort()
-      .map((key) => `${JSON.stringify(key)}:${stableStringify(/**
-                                                               * Narrows the runtime value to the documented type.
-                                                               * @type {Record<string, ?>} */ (value)[key])}`)
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(/** @type {Record<string, ?>} */ (value)[key])}`)
 
     return `{${entries.join(",")}}`
   }
@@ -148,6 +144,14 @@ class VelociousDatabasePoolBase {
     return this.getCurrentConnection()
   }
 
+  /**
+   * Returns whether the current connection is pinned to an execution context.
+   * @returns {boolean} - Whether the current connection can be reused by nested code.
+   */
+  hasCurrentConnectionContext() {
+    return true
+  }
+
   /**
    * Runs without current connection context.
    * @template T
@@ -195,9 +199,7 @@ class VelociousDatabasePoolBase {
    * @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)
+    const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
 
     return connectionWithPoolKey[POOL_CONFIGURATION_KEY] === this.getConfigurationReuseKey()
   }
@@ -256,9 +258,7 @@ class VelociousDatabasePoolBase {
 
     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)
+    const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
     connectionWithPoolKey[POOL_CONFIGURATION_KEY] = this.getConfigurationReuseKey()
     connection.setSchemaCacheInvalidator(() => {
       this.clearSchemaCache()
@@ -371,9 +371,7 @@ class VelociousDatabasePoolBase {
    * @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)
+    const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
 
     return {
       ...connection.getDebugSnapshot(),

package/src/database/query/index.js

@@ -188,9 +188,7 @@ export default class VelociousDatabaseQuery {
      * @type {import("./where-base.js").default[]} */
     this._wheres = wheres
 
-    const boundWhere = /**
-                        * Narrows the runtime value to the documented type.
-                        * @type {?} */ (this.where.bind(this))
+    const boundWhere = /** @type {?} */ (this.where.bind(this))
     boundWhere.not = this.whereNot.bind(this)
     this.where = boundWhere
   }
@@ -200,9 +198,7 @@ export default class VelociousDatabaseQuery {
    * @returns {this} - The clone.
    */
   clone() {
-    const QueryClass = /**
-                        * Narrows the runtime value to the documented type.
-                        * @type {new (args: QueryArgsType) => this} */ (this.constructor)
+    const QueryClass = /** @type {new (args: QueryArgsType) => this} */ (this.constructor)
     const newQuery = new QueryClass({
       driver: this._driverFn,
       froms: [...this._froms],
@@ -494,9 +490,7 @@ export default class VelociousDatabaseQuery {
     if (typeof where == "string") {
       this._wheres.push(new WherePlain(this, where))
     } else if (typeof where == "object" && (where.constructor.name == "object" || where.constructor.name == "Object")) {
-      this._wheres.push(new WhereHash(this, /**
-                                             * Narrows the runtime value to the documented type.
-                                             * @type {import("./where-hash.js").WhereHash} */ (where)))
+      this._wheres.push(new WhereHash(this, /** @type {import("./where-hash.js").WhereHash} */ (where)))
     } else {
       throw new Error(`Invalid type of where: ${typeof where} (${where.constructor.name})`)
     }
@@ -513,9 +507,7 @@ export default class VelociousDatabaseQuery {
     if (typeof where == "string") {
       this._wheres.push(new WhereNot(new WherePlain(this, where)))
     } else if (typeof where == "object" && (where.constructor.name == "object" || where.constructor.name == "Object")) {
-      this._wheres.push(new WhereNot(new WhereHash(this, /**
-                                                          * Narrows the runtime value to the documented type.
-                                                          * @type {import("./where-hash.js").WhereHash} */ (where))))
+      this._wheres.push(new WhereNot(new WhereHash(this, /** @type {import("./where-hash.js").WhereHash} */ (where))))
     } else {
       throw new Error(`Invalid type of where: ${typeof where} (${where.constructor.name})`)
     }

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

@@ -29,12 +29,8 @@ export default class VelociousDatabaseQueryJoinObject extends JoinBase {
       throw new Error(`Query has to be a ModelClassQuery but was a ${query.constructor.name}`)
     }
 
-    const modelQuery = /**
-                        * Narrows the runtime value to the documented type.
-                        * @type {import("./model-class-query.js").default} */ (query)
-    const ModelClass = /**
-                        * Narrows the runtime value to the documented type.
-                        * @type {typeof import("../record/index.js").default} */ (
+    const modelQuery = /** @type {import("./model-class-query.js").default} */ (query)
+    const ModelClass = /** @type {typeof import("../record/index.js").default} */ (
       this.basePath.length > 0 ? modelQuery._resolveModelClassForJoinPath(this.basePath) : modelQuery.modelClass
     )
 
@@ -53,9 +49,7 @@ export default class VelociousDatabaseQueryJoinObject extends JoinBase {
   joinObject(join, modelClass, sql, joinsCount, path) {
     const pretty = this.pretty
     const conn = this.getQuery().driver
-    const query = /**
-                   * Narrows the runtime value to the documented type.
-                   * @type {import("./model-class-query.js").default} */ (this.getQuery())
+    const query = /** @type {import("./model-class-query.js").default} */ (this.getQuery())
 
     for (const joinKey in join) {
       const joinValue = join[joinKey]

package/src/database/query/model-class-query.js

@@ -216,9 +216,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
    * @returns {this} - The clone.
    */
   clone() {
-    const newQuery = /**
-                      * Narrows the runtime value to the documented type.
-                      * @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (new VelociousDatabaseQueryModelClassQuery({
+    const newQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (new VelociousDatabaseQueryModelClassQuery({
       driver: this._driverFn,
       froms: [...this._froms],
       handler: this.handler.clone(),
@@ -338,9 +336,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     countQuery._selects = []
     countQuery.select(sql)
 
-    const results = /**
-                     * Narrows the runtime value to the documented type.
-                     * @type {{count: number}[]} */ (await countQuery._executeQuery({
+    const results = /** @type {{count: number}[]} */ (await countQuery._executeQuery({
       logName: countQuery.queryLogName("Count")
     }))
 
@@ -374,9 +370,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       `SELECT ${countSql} AS ${this.driver.quoteColumn("count")}`,
       `FROM (${countQuery.toSql()}) AS ${this.driver.quoteTable("paginated_count_rows")}`
     ].join(" ")
-    const results = /**
-                     * Narrows the runtime value to the documented type.
-                     * @type {{count: number}[]} */ (await this.driver.query(
+    const results = /** @type {{count: number}[]} */ (await this.driver.query(
       sql,
       {logName: this.queryLogName("Count")}
     ))
@@ -470,18 +464,12 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     const froms = this.getFroms()
     const lastFrom = froms[froms.length - 1]
 
-    if (lastFrom && typeof /**
-                            * Narrows the runtime value to the documented type.
-                            * @type {?} */ (lastFrom).tableName === "string") {
+    if (lastFrom && typeof /** @type {?} */ (lastFrom).tableName === "string") {
       return /** @type {?} */ (lastFrom).tableName
     }
 
-    if (lastFrom && typeof /**
-                            * Narrows the runtime value to the documented type.
-                            * @type {?} */ (lastFrom).plain === "string") {
-      const parsedReference = parseFromPlainTableReference(/**
-                                                            * Narrows the runtime value to the documented type.
-                                                            * @type {?} */ (lastFrom).plain)
+    if (lastFrom && typeof /** @type {?} */ (lastFrom).plain === "string") {
+      const parsedReference = parseFromPlainTableReference(/** @type {?} */ (lastFrom).plain)
 
       if (parsedReference) return parsedReference
     }
@@ -539,9 +527,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
    * @returns {VelociousDatabaseQueryModelClassQuery<MC>} - The scoped query.
    */
   withJoinPath(joinBasePath) {
-    const scopedQuery = /**
-                         * Narrows the runtime value to the documented type.
-                         * @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (this.clone())
+    const scopedQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (this.clone())
 
     scopedQuery._joinBasePath = joinBasePath
     scopedQuery._joinTracker = this._joinTracker
@@ -638,9 +624,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     }
 
     return this._applyJoinPathScope({
-      joinPath: normalizeScopePath(/**
-                                    * Narrows the runtime value to the documented type.
-                                    * @type {string | string[]} */ (pathOrScopeDescriptor)),
+      joinPath: normalizeScopePath(/** @type {string | string[]} */ (pathOrScopeDescriptor)),
       scopeDescriptor: maybeScopeDescriptor
     })
   }
@@ -659,9 +643,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       throw new Error(`Cannot apply ${scopeDescriptor.modelClass.name} scope to ${this.getModelClass().name} query`)
     }
 
-    const scopedQuery = /**
-                         * Narrows the runtime value to the documented type.
-                         * @type {this | void} */ (scopeDescriptor.callback({
+    const scopedQuery = /** @type {this | void} */ (scopeDescriptor.callback({
       driver: this.driver,
       modelClass: this.getModelClass(),
       query: this,
@@ -693,9 +675,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     const scopedQuery = this.buildJoinScopeQuery(targetModelClass, fullJoinPath)
     const originalJoinCount = scopedQuery._joins.length
     const originalWhereCount = scopedQuery._wheres.length
-    const appliedQuery = /**
-                          * Narrows the runtime value to the documented type.
-                          * @type {typeof scopedQuery | void} */ (scopeDescriptor.callback({
+    const appliedQuery = /** @type {typeof scopedQuery | void} */ (scopeDescriptor.callback({
       driver: scopedQuery.driver,
       modelClass: targetModelClass,
       path: [...fullJoinPath],
@@ -742,9 +722,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
    * @returns {VelociousDatabaseQueryModelClassQuery<MC>} - The scoped join query.
    */
   buildJoinScopeQuery(targetModelClass, joinPath) {
-    const scopedQuery = /**
-                         * Narrows the runtime value to the documented type.
-                         * @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (targetModelClass._newQuery())
+    const scopedQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (targetModelClass._newQuery())
 
     scopedQuery._joinTracker = this._joinTracker
     scopedQuery._joinBasePath = joinPath
@@ -817,9 +795,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
     conditions[this.getModelClass().primaryKey()] = recordId
 
-    const newQuery = /**
-                      * Narrows the runtime value to the documented type.
-                      * @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (this.clone())
+    const newQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (this.clone())
 
     newQuery.where(conditions)
 
@@ -838,9 +814,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
    * @returns {Promise<InstanceType<MC> | null>} - Resolves with the by.
    */
   async findBy(conditions) {
-    const newQuery = /**
-                      * Narrows the runtime value to the documented type.
-                      * @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (this.clone())
+    const newQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (this.clone())
 
     newQuery.where(conditions)
 
@@ -890,9 +864,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     if (record) return record
 
     const ModelClass = this.getModelClass()
-    const newRecord = /**
-                       * Narrows the runtime value to the documented type.
-                       * @type {InstanceType<MC>} */ (new ModelClass(conditions))
+    const newRecord = /** @type {InstanceType<MC>} */ (new ModelClass(conditions))
 
     if (callback) {
       callback(newRecord)
@@ -945,9 +917,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
     for (const result of results) {
       const ModelClass = this.getModelClass()
-      const model = /**
-                     * Narrows the runtime value to the documented type.
-                     * @type {InstanceType<MC>} */ (new ModelClass())
+      const model = /** @type {InstanceType<MC>} */ (new ModelClass())
 
       model.loadExistingRecord(result)
       models.push(model)
@@ -1013,9 +983,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     const attributeMap = modelClass.getAttributeNameToColumnNameMap()
     const columnNames = flatColumns.map((column) => attributeMap[column] || column)
 
-    const query = /**
-                   * Narrows the runtime value to the documented type.
-                   * @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (this.clone())
+    const query = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (this.clone())
 
     query._preload = {}
     query._selects = []
@@ -1030,15 +998,11 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
     if (columnNames.length === 1) {
       const [columnName] = columnNames
-      return rows.map((row) => /**
-                                * Narrows the runtime value to the documented type.
-                                * @type {Record<string, ?>} */ (row)[columnName])
+      return rows.map((row) => /** @type {Record<string, ?>} */ (row)[columnName])
     }
 
     return rows.map((row) => {
-      const rowHash = /**
-                       * Narrows the runtime value to the documented type.
-                       * @type {Record<string, ?>} */ (row)
+      const rowHash = /** @type {Record<string, ?>} */ (row)
 
       return columnNames.map((columnName) => rowHash[columnName])
     })
@@ -1496,9 +1460,7 @@ function normalizeRelationshipWhereOperator(operator) {
   }
 
   return /** @type {"eq" | "notEq" | "gt" | "gteq" | "lt" | "lteq" | "like"} */ (
-    operatorAliases[/**
-                     * Narrows the runtime value to the documented type.
-                     * @type {"<" | "<=" | ">" | ">="} */ (operator)] || operator
+    operatorAliases[/** @type {"<" | "<=" | ">" | ">="} */ (operator)] || operator
   )
 }
 
@@ -1537,9 +1499,7 @@ function normalizeRelationshipWhereOperatorTuples(value) {
      */
     const addCondition = (conditionValue) => {
       if (isRelationshipWhereOperatorTuple(conditionValue)) {
-        const tuple = /**
-                       * Narrows the runtime value to the documented type.
-                       * @type {[string, "eq" | "notEq" | "gt" | "gteq" | "lt" | "lteq" | "like" | ">" | ">=" | "<" | "<=", unknown, ...Array<unknown>]} */ (conditionValue)
+        const tuple = /** @type {[string, "eq" | "notEq" | "gt" | "gteq" | "lt" | "lteq" | "like" | ">" | ">=" | "<" | "<=", unknown, ...Array<unknown>]} */ (conditionValue)
         const normalizedOperator = normalizeRelationshipWhereOperator(tuple[1])
 
         normalized.push([
@@ -1561,9 +1521,7 @@ function normalizeRelationshipWhereOperatorTuples(value) {
       throw new Error("Relationship where conditions must be tuples")
     }
 
-    /**
-     * Narrows the runtime value to the documented type.
-     * @type {Array<?>} */ (conditionValue).forEach((nestedConditionValue) => {
+    /** @type {Array<?>} */ (conditionValue).forEach((nestedConditionValue) => {
       addCondition(nestedConditionValue)
     })
   }