velocious 1.0.514 → 1.0.516

package/src/configuration.js

@@ -2056,7 +2056,8 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get translator.
-   * @returns {(msgID: string, args?: Record<string, ?>) => string} */
+   * @returns {(msgID: string, args?: Record<string, ?>) => string} - The configured translator.
+   */
   getTranslator() {
     if (this._translator) return this._translator
 
@@ -2156,8 +2157,8 @@ export default class VelociousConfiguration {
    * Registers a `VelociousWebsocketConnection` subclass under a name.
    * Clients that send `{type: "connection-open", connectionType: name}`
    * will have this class instantiated for their connection.
-   * @param {string} name
-   * @param {typeof import("./http-server/websocket-connection.js").default} ConnectionClass
+   * @param {string} name - Client-facing connection type name.
+   * @param {typeof import("./http-server/websocket-connection.js").default} ConnectionClass - Websocket connection class.
    * @returns {void}
    */
   registerWebsocketConnection(name, ConnectionClass) {
@@ -2168,8 +2169,8 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get websocket connection class.
-   * @param {string} name
-   * @returns {typeof import("./http-server/websocket-connection.js").default | undefined}
+   * @param {string} name - Connection type name to look up.
+   * @returns {typeof import("./http-server/websocket-connection.js").default | undefined} - Registered websocket connection class.
    */
   getWebsocketConnectionClass(name) {
     return this._websocketConnectionClasses.get(name)
@@ -2178,8 +2179,8 @@ export default class VelociousConfiguration {
   /**
    * Registers a `VelociousWebsocketChannel` subclass under a name.
    * Clients subscribe via `{type: "channel-subscribe", channelType: name, ...}`.
-   * @param {string} name
-   * @param {typeof import("./http-server/websocket-channel.js").default} ChannelClass
+   * @param {string} name - Client-facing channel type name.
+   * @param {typeof import("./http-server/websocket-channel.js").default} ChannelClass - Websocket channel class.
    * @returns {void}
    */
   registerWebsocketChannel(name, ChannelClass) {
@@ -2190,8 +2191,8 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get websocket channel class.
-   * @param {string} name
-   * @returns {typeof import("./http-server/websocket-channel.js").default | undefined}
+   * @param {string} name - Channel type name to look up.
+   * @returns {typeof import("./http-server/websocket-channel.js").default | undefined} - Registered websocket channel class.
    */
   getWebsocketChannelClass(name) {
     return this._websocketChannelClasses.get(name)
@@ -2201,8 +2202,8 @@ export default class VelociousConfiguration {
    * Tracks a live channel subscription in the global routing registry.
    * Called by the session when `canSubscribe()` resolves truthy; the
    * session calls `_unregisterWebsocketChannelSubscription` on unsubscribe.
-   * @param {string} name
-   * @param {import("./http-server/websocket-channel.js").default} subscription
+   * @param {string} name - Channel type used as the routing key.
+   * @param {import("./http-server/websocket-channel.js").default} subscription - Live channel subscription to register.
    * @returns {void}
    */
   _registerWebsocketChannelSubscription(name, subscription) {
@@ -2218,8 +2219,8 @@ export default class VelociousConfiguration {
 
   /**
    * Runs unregister websocket channel subscription.
-   * @param {string} name
-   * @param {import("./http-server/websocket-channel.js").default} subscription
+   * @param {string} name - Channel type used as the routing key.
+   * @param {import("./http-server/websocket-channel.js").default} subscription - Live channel subscription to remove.
    * @returns {void}
    */
   _unregisterWebsocketChannelSubscription(name, subscription) {
@@ -2262,7 +2263,7 @@ export default class VelociousConfiguration {
    * connection message / channel dispatch. The wrapper receives the
    * session and a `next` callback; it must call `next()` to run the
    * handler. Use it to set up AsyncLocalStorage per request.
-   * @param {((session: import("./http-server/client/websocket-session.js").default, next: () => Promise<void>) => Promise<void>) | null} wrapper
+   * @param {((session: import("./http-server/client/websocket-session.js").default, next: () => Promise<void>) => Promise<void>) | null} wrapper - Per-message session-context wrapper, or null to disable it.
    * @returns {void}
    */
   setWebsocketAroundRequest(wrapper) {
@@ -2271,7 +2272,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get websocket around request.
-   * @returns {((session: import("./http-server/client/websocket-session.js").default, next: () => Promise<void>) => Promise<void>) | null}
+   * @returns {((session: import("./http-server/client/websocket-session.js").default, next: () => Promise<void>) => Promise<void>) | null} - Websocket session wrapper.
    */
   getWebsocketAroundRequest() {
     return this._websocketAroundRequest
@@ -2282,7 +2283,7 @@ export default class VelociousConfiguration {
    * HTTP and WS-borne. Receives `{request, response, next}` and must
    * call `next()` to run the action. Use it for per-request context
    * like AsyncLocalStorage-scoped locale or tracing.
-   * @param {((context: {request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default, response: import("./http-server/client/response.js").default, next: () => Promise<void>}) => Promise<void>) | null} wrapper
+   * @param {((context: {request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default, response: import("./http-server/client/response.js").default, next: () => Promise<void>}) => Promise<void>) | null} wrapper - Per-action request-context wrapper, or null to disable it.
    * @returns {void}
    */
   setAroundAction(wrapper) {
@@ -2291,7 +2292,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get around action.
-   * @returns {((context: {request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default, response: import("./http-server/client/response.js").default, next: () => Promise<void>}) => Promise<void>) | null}
+   * @returns {((context: {request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default, response: import("./http-server/client/response.js").default, next: () => Promise<void>}) => Promise<void>) | null} - HTTP request wrapper.
    */
   getAroundAction() {
     return this._aroundAction
@@ -2310,7 +2311,7 @@ export default class VelociousConfiguration {
    *
    * Return `null`/`undefined` to mean "no identity" — resumes still
    * succeed if pause and resume both resolve to a nullish value.
-   * @param {((session: import("./http-server/client/websocket-session.js").default) => ? | Promise<?>) | null} resolver
+   * @param {((session: import("./http-server/client/websocket-session.js").default) => ? | Promise<?>) | null} resolver - Authenticated-caller identity resolver, or null to disable identity checks.
    * @returns {void}
    */
   setWebsocketSessionIdentityResolver(resolver) {
@@ -2319,14 +2320,15 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get websocket session identity resolver.
-   * @returns {((session: import("./http-server/client/websocket-session.js").default) => ? | Promise<?>) | null} */
+   * @returns {((session: import("./http-server/client/websocket-session.js").default) => ? | Promise<?>) | null} - The configured identity resolver.
+   */
   getWebsocketSessionIdentityResolver() {
     return this._websocketSessionIdentityResolver
   }
 
   /**
    * Runs set websocket session grace seconds.
-   * @param {number} seconds
+   * @param {number} seconds - Grace period before a paused session expires.
    * @returns {void}
    */
   setWebsocketSessionGraceSeconds(seconds) {
@@ -2336,7 +2338,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs set websocket session heartbeat seconds.
-   * @param {number} seconds
+   * @param {number} seconds - Heartbeat interval, with zero disabling reaping.
    * @returns {void}
    */
   setWebsocketSessionHeartbeatSeconds(seconds) {
@@ -2349,7 +2351,7 @@ export default class VelociousConfiguration {
    * timer. When the timer fires, the session's permanent teardown
    * hook is invoked. Called by the session itself from `_handleClose`
    * when there is resumable state (live Connections / Channel subs).
-   * @param {import("./http-server/client/websocket-session.js").default} session
+   * @param {import("./http-server/client/websocket-session.js").default} session - Resumable session to retain during its grace period.
    * @returns {void}
    */
   _pauseWebsocketSession(session) {
@@ -2372,8 +2374,8 @@ export default class VelociousConfiguration {
   /**
    * Looks up a paused session by id (does NOT remove it — caller is
    * expected to call `_resumeWebsocketSession` to complete the handoff).
-   * @param {string} sessionId
-   * @returns {import("./http-server/client/websocket-session.js").default | null}
+   * @param {string} sessionId - Paused session identifier to look up.
+   * @returns {import("./http-server/client/websocket-session.js").default | null} - Paused session with the requested identifier, if present.
    */
   _findPausedWebsocketSession(sessionId) {
     return this._pausedWebsocketSessions.get(sessionId)?.session || null
@@ -2383,7 +2385,7 @@ export default class VelociousConfiguration {
    * Removes a paused session from the registry and cancels its grace
    * timer. Called on successful resume handoff and on explicit
    * expiry.
-   * @param {string} sessionId
+   * @param {string} sessionId - Paused session identifier to remove and cancel.
    * @returns {void}
    */
   _clearPausedWebsocketSession(sessionId) {
@@ -2398,7 +2400,7 @@ export default class VelociousConfiguration {
   /**
    * Grace-timer callback. Calls the session's permanent-teardown
    * hook and drops it from the registry.
-   * @param {string} sessionId
+   * @param {string} sessionId - Paused session identifier whose grace period expired.
    * @returns {void}
    */
   _expireWebsocketSession(sessionId) {
@@ -2416,9 +2418,9 @@ export default class VelociousConfiguration {
 
   /**
    * Runs broadcast to channel.
-   * @param {string} name
-   * @param {Record<string, ?>} broadcastParams
-   * @param {?} body
+   * @param {string} name - Channel type receiving the broadcast.
+   * @param {Record<string, ?>} broadcastParams - Values used to match eligible subscriptions.
+   * @param {?} body - Broadcast payload delivered to matching subscriptions.
    * @returns {void}
    */
   broadcastToChannel(name, broadcastParams, body) {
@@ -2830,6 +2832,29 @@ export default class VelociousConfiguration {
     return runCallback()
   }
 
+  /**
+   * Runs a callback inside every pool's test shared connection context (a no-op for
+   * pools without one). In-process request handling is wrapped in this so a request
+   * runs on the same connection — and open transaction — as the test that issued it,
+   * letting request specs clean up by rolling back instead of truncating. Outside
+   * tests no shared connection is set, so this just runs the callback.
+   * @template T
+   * @param {() => T} callback - Callback to run inside the shared connection contexts.
+   * @returns {T} - Callback result.
+   */
+  runWithTestSharedConnectionContexts(callback) {
+    let runCallback = callback
+
+    for (const pool of Object.values(this.databasePools)) {
+      if (!pool) continue
+      const previousRunCallback = runCallback
+
+      runCallback = () => pool.runWithTestSharedConnection(previousRunCallback)
+    }
+
+    return runCallback()
+  }
+
   /**
    * Runs is missing current connection error.
    * @param {?} error - Error thrown while looking up the current connection.

package/src/controller.js

@@ -169,7 +169,7 @@ export default class VelociousController {
       const beforeActions = currentControllerClass._beforeActions
 
       if (beforeActions) {
-        const controllerPrototype = /** @type {Record<string, Function | undefined>} */ (/** @type {?} */ (currentControllerClass.prototype))
+        const controllerPrototype = /** @type {Record<string, ((...args: Array<?>) => ?) | undefined>} */ (/** @type {?} */ (currentControllerClass.prototype))
 
         for (const beforeActionName of beforeActions) {
           const beforeAction = controllerPrototype[beforeActionName]
@@ -266,6 +266,7 @@ export default class VelociousController {
   /**
    * Runs render json arg.
    * @param {object} json - JSON payload.
+   * @returns {void} - Sets the response JSON payload.
    */
   renderJsonArg(json) {
     return this._measureViewRender(() => {
@@ -339,11 +340,12 @@ export default class VelociousController {
    * @param {object} [args] - Options object.
    * @param {string} [args.contentType] - Content type.
    * @param {number | string} [args.status] - Status.
+   * @param {(result: "completed" | "aborted") => void | Promise<void>} [args.onFinished] - Called once after file delivery completes or aborts.
    * @returns {void} - No return value.
    */
   sendFile(filePath, args = {}) {
     this._measureViewRender(() => {
-      const {contentType, status, ...restArgs} = args
+      const {contentType, onFinished, status, ...restArgs} = args
 
       restArgsError(restArgs)
 
@@ -351,6 +353,10 @@ export default class VelociousController {
         throw new Error(`Expected file path to be a non-empty string, got: ${String(filePath)}`)
       }
 
+      if (onFinished !== undefined && typeof onFinished !== "function") {
+        throw new Error(`Expected onFinished to be a function, got: ${typeof onFinished}`)
+      }
+
       const detectedContentType = contentType || this.sendFileContentType(filePath)
 
       if (detectedContentType) {
@@ -361,7 +367,7 @@ export default class VelociousController {
         this._response.setStatus(status)
       }
 
-      this._response.setFilePath(filePath)
+      this._response.setFilePath(filePath, onFinished || null)
     })
   }
 

package/src/database/drivers/sqlite/base.js

@@ -401,7 +401,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
         const waiters = state.waitersByName.get(name) || []
         /**
          * Timeout handle.
-         * @type {NodeJS.Timeout | null} */
+         * @type {ReturnType<typeof setTimeout> | null} */
         let timeoutHandle = null
         /**
          * Remove and resolve.

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

@@ -93,7 +93,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * (create and remove) per critical section.
    * @param {string} name - Lock name.
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the advisory lock was acquired.
    */
   async acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const deadline = typeof timeoutMs === "number" && timeoutMs >= 0 ? Date.now() + timeoutMs : null
@@ -121,7 +121,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
   /**
    * Runs try acquire advisory lock.
    * @param {string} name - Lock name.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the advisory lock was acquired immediately.
    */
   async tryAcquireAdvisoryLock(name) {
     const inProcessAcquired = await super.tryAcquireAdvisoryLock(name)
@@ -151,7 +151,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * and the filesystem state is left alone so we never delete somebody
    * else's lock directory.
    * @param {string} name - Lock name.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the advisory lock was released.
    */
   async releaseAdvisoryLock(name) {
     const inProcessReleased = await super.releaseAdvisoryLock(name)
@@ -166,7 +166,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
   /**
    * Runs is advisory lock held.
    * @param {string} name - Lock name.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the advisory lock is held.
    */
   async isAdvisoryLockHeld(name) {
     if (await super.isAdvisoryLockHeld(name)) return true
@@ -176,7 +176,8 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
   /**
    * Runs resolve advisory lock directory.
-   * @returns {string} */
+   * @returns {string} - The advisory-lock directory.
+   */
   _resolveAdvisoryLockDirectory() {
     if (!this._advisoryLockDirectory) {
       // Fall back to deriving the directory for callers that invoked
@@ -192,7 +193,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
   /**
    * Runs advisory lock path.
    * @param {string} name - Lock name.
-   * @returns {string}
+   * @returns {string} - Filesystem path for the advisory lock.
    */
   _advisoryLockPath(name) {
     const hash = createHash("sha256").update(name).digest("hex").slice(0, 16)
@@ -228,7 +229,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * Runs acquire advisory lock file.
    * @param {string} name - Lock name.
    * @param {{timeoutMs?: number | null}} args - Timeout args.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the advisory-lock file was acquired.
    */
   async _acquireAdvisoryLockFile(name, {timeoutMs}) {
     await this._ensureAdvisoryLockDirectory()
@@ -247,7 +248,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
         return true
       } catch (error) {
-        if (/** @type {NodeJS.ErrnoException} */ (error)?.code !== "EEXIST") throw error
+        if (/** @type {Error & {code?: string}} */ (error)?.code !== "EEXIST") throw error
 
         if (await this._isAdvisoryLockStale(lockPath)) {
           await fs.rm(lockPath, {recursive: true, force: true})
@@ -270,7 +271,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
   /**
    * Runs try acquire advisory lock file.
    * @param {string} name - Lock name.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the advisory-lock file was acquired immediately.
    */
   async _tryAcquireAdvisoryLockFile(name) {
     await this._ensureAdvisoryLockDirectory()
@@ -283,7 +284,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
       return true
     } catch (error) {
-      if (/** @type {NodeJS.ErrnoException} */ (error)?.code !== "EEXIST") throw error
+      if (/** @type {Error & {code?: string}} */ (error)?.code !== "EEXIST") throw error
 
       if (await this._isAdvisoryLockStale(lockPath)) {
         await fs.rm(lockPath, {recursive: true, force: true})
@@ -294,7 +295,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
           return true
         } catch (retryError) {
-          if (/** @type {NodeJS.ErrnoException} */ (retryError)?.code === "EEXIST") return false
+          if (/** @type {Error & {code?: string}} */ (retryError)?.code === "EEXIST") return false
 
           throw retryError
         }
@@ -324,7 +325,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
   /**
    * Runs is advisory lock file held.
    * @param {string} name - Lock name.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the advisory-lock file exists and is active.
    */
   async _isAdvisoryLockFileHeld(name) {
     const lockPath = this._advisoryLockPath(name)
@@ -345,7 +346,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * probe a PID on another machine; operators in that situation should
    * remove stale lock directories by hand if they linger.
    * @param {string} lockPath - Absolute path of the lock directory.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the advisory-lock file is stale.
    */
   async _isAdvisoryLockStale(lockPath) {
     /**
@@ -382,7 +383,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
       return false
     } catch (error) {
-      return /** @type {NodeJS.ErrnoException} */ (error)?.code === "ESRCH"
+      return /** @type {Error & {code?: string}} */ (error)?.code === "ESRCH"
     }
   }
 }

package/src/database/migrations-ledger.js

@@ -18,7 +18,7 @@ const TABLE_NAME = "schema_migrations"
 export default class MigrationsLedger {
   /**
    * The ledger table name.
-   * @returns {string}
+   * @returns {string} - Ledger table name.
    */
   static tableName() {
     return TABLE_NAME
@@ -26,8 +26,8 @@ export default class MigrationsLedger {
 
   /**
    * Whether the ledger table exists on the given database.
-   * @param {import("./drivers/base.js").default} db
-   * @returns {Promise<boolean>}
+   * @param {import("./drivers/base.js").default} db - Database whose migration ledger is inspected.
+   * @returns {Promise<boolean>} - Whether the ledger table exists.
    */
   static async tableExists(db) {
     const table = await db.getTableByName(TABLE_NAME, {throwError: false})
@@ -38,7 +38,7 @@ export default class MigrationsLedger {
   /**
    * Creates the ledger table if it does not exist. This is the single definition of
    * the `schema_migrations` table shape.
-   * @param {import("./drivers/base.js").default} db
+   * @param {import("./drivers/base.js").default} db - Database that should contain the ledger table.
    * @returns {Promise<void>}
    */
   static async ensureTable(db) {
@@ -57,8 +57,8 @@ export default class MigrationsLedger {
 
   /**
    * Every applied migration version recorded in the ledger.
-   * @param {import("./drivers/base.js").default} db
-   * @returns {Promise<string[]>}
+   * @param {import("./drivers/base.js").default} db - Database whose applied versions are loaded.
+   * @returns {Promise<string[]>} - Applied migration versions.
    */
   static async appliedVersions(db) {
     const rows = await db.select(TABLE_NAME)
@@ -68,9 +68,9 @@ export default class MigrationsLedger {
 
   /**
    * Whether the given version is recorded as applied.
-   * @param {import("./drivers/base.js").default} db
-   * @param {string} version
-   * @returns {Promise<boolean>}
+   * @param {import("./drivers/base.js").default} db - Database whose ledger is queried.
+   * @param {string} version - Migration version to look up.
+   * @returns {Promise<boolean>} - Whether the migration version is applied.
    */
   static async hasVersion(db, version) {
     const rows = await db.newQuery()
@@ -84,8 +84,8 @@ export default class MigrationsLedger {
   /**
    * Records a single version as applied. The targeted existence check keeps the
    * migrator's per-migration hot path cheap (no full-table load per migration).
-   * @param {import("./drivers/base.js").default} db
-   * @param {string} version
+   * @param {import("./drivers/base.js").default} db - Database whose ledger receives the version.
+   * @param {string} version - Migration version to record as applied.
    * @returns {Promise<void>}
    */
   static async recordVersion(db, version) {
@@ -96,8 +96,8 @@ export default class MigrationsLedger {
 
   /**
    * Removes a version from the ledger (used when migrating down).
-   * @param {import("./drivers/base.js").default} db
-   * @param {string} version
+   * @param {import("./drivers/base.js").default} db - Database whose ledger loses the version.
+   * @param {string} version - Migration version to mark as unapplied.
    * @returns {Promise<void>}
    */
   static async removeVersion(db, version) {
@@ -108,8 +108,8 @@ export default class MigrationsLedger {
    * Baselines a database's ledger: records each version as applied without running
    * its migration. Idempotent — already-recorded versions are skipped. Ensures the
    * ledger table exists first, then loads the existing set once for the whole batch.
-   * @param {import("./drivers/base.js").default} db
-   * @param {string[]} versions
+   * @param {import("./drivers/base.js").default} db - Database whose ledger should be baselined.
+   * @param {string[]} versions - Migration versions to record without running them.
    * @returns {Promise<string[]>} The versions that were newly recorded.
    */
   static async markApplied(db, versions) {
@@ -136,7 +136,7 @@ export default class MigrationsLedger {
    * provisioning path advanced `targetDb`'s schema to match `sourceDb` out of band
    * (e.g. cloning table structure between databases): the migrations are, by
    * construction, already applied on the target, so record them without re-running.
-   * @param {{sourceDb: import("./drivers/base.js").default, targetDb: import("./drivers/base.js").default}} args
+   * @param {{sourceDb: import("./drivers/base.js").default, targetDb: import("./drivers/base.js").default}} args - Source ledger and target database to baseline.
    * @returns {Promise<string[]>} The versions that were newly recorded on the target.
    */
   static async baselineFromDatabase({sourceDb, targetDb}) {

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

@@ -809,6 +809,22 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     this._testSharedConnection = undefined
   }
 
+  /**
+   * Runs a callback inside the test shared connection's async context, so nested
+   * `getCurrentConnection`/`ensureConnections` reuse it (with a real context) rather
+   * than checking out a fresh pooled connection. Used to run an in-process request
+   * handler on the same connection — and open transaction — as the test body. No-op
+   * (runs the callback as-is) when no shared connection is set.
+   * @template T
+   * @param {() => T} callback - Callback to run in the shared connection's context.
+   * @returns {T} - Callback result.
+   */
+  runWithTestSharedConnection(callback) {
+    if (!this._testSharedConnection) return callback()
+
+    return this.asyncLocalStorage.run(this._testSharedConnection.getIdSeq(), callback)
+  }
+
   /**
    * Returns the connection tied to the current async context, if any.
    * Falls back to the test shared connection when no async context exists.

package/src/database/pool/base.js

@@ -144,6 +144,32 @@ class VelociousDatabasePoolBase {
     return this.getCurrentConnection()
   }
 
+  /**
+   * Pins a connection to be returned to callers that run without a connection-context
+   * pin (used by the test runner to share one connection with in-process HTTP handlers).
+   * Base pools that do not track async context ignore it; async-context pools override.
+   * @param {import("../drivers/base.js").default} _connection - Shared connection.
+   * @returns {void}
+   */
+  setTestSharedConnection(_connection) {}
+
+  /**
+   * Clears the shared connection set by {@link setTestSharedConnection}. No-op by default.
+   * @returns {void}
+   */
+  clearTestSharedConnection() {}
+
+  /**
+   * Runs a callback inside the test shared connection's context. Base pools that do not
+   * track async context just run the callback as-is; async-context pools override.
+   * @template T
+   * @param {() => T} callback - Callback to run.
+   * @returns {T} - Callback result.
+   */
+  runWithTestSharedConnection(callback) {
+    return callback()
+  }
+
   /**
    * Returns whether the current connection is pinned to an execution context.
    * @returns {boolean} - Whether the current connection can be reused by nested code.

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

@@ -316,6 +316,7 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
     /**
      * Normalize.
      * @param {?} entry - Value to normalize.
+     * @returns {?} - SQLite predicate value with booleans encoded as 1 or 0.
      */
     const normalize = (entry) => {
       if (entry === true) return 1
@@ -353,6 +354,7 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
     /**
      * Normalize.
      * @param {?} entry - Value to normalize.
+     * @returns {?} - Column-compatible predicate value, or the no-match sentinel for numeric UUIDs.
      */
     const normalize = (entry) => {
       if (isUuidType && typeof entry === "number") return NO_MATCH

package/src/database/query/with-count.js

@@ -85,7 +85,7 @@ export function normalizeWithCount(spec) {
 /**
  * Runs entry from name.
  * @param {string} name - Relationship name (attribute name is derived by appending "Count").
- * @returns {WithCountEntry}
+ * @returns {WithCountEntry} - Normalized association-count entry.
  */
 function entryFromName(name) {
   return {

package/src/database/record/acts-as-list.js

@@ -21,7 +21,7 @@ function setShiftingFlag(record, value) {
 /**
  * Runs is shifting.
  * @param {import("./index.js").default} record - Model instance.
- * @returns {boolean}
+ * @returns {boolean} - Whether list positions are currently shifting.
  */
 function isShifting(record) {
   // @ts-ignore - Symbol indexing on Record instances
@@ -341,7 +341,7 @@ async function highestPositionInScope({record, positionColumn, scope, scopeValue
  * _belongsToChanges.
  * @param {import("./index.js").default} record - Model instance.
  * @param {string} scope - camelCase scope attribute name (e.g. "projectId").
- * @returns {string | number | null}
+ * @returns {string | number | null} - Current list position value.
  */
 function resolveScopeValue(record, scope) {
   const attrValue = record.readAttribute(scope)