velocious 1.0.515 → 1.0.516

package/build/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) {

package/build/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/build/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/build/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/build/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/build/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/build/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/build/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)

package/build/database/record/auditing.js

@@ -74,7 +74,12 @@ let globalEventConnections = {}
 
 /** @type {AuditEventsType} */
 const AuditEvents = {
-  /** Fire all registered callbacks for a model type + action. @param {string} type @param {string} action @param {AuditEventPayload} args */
+  /**
+   * Fire all registered callbacks for a model type and action.
+   * @param {string} type - Audited model type whose listeners should fire.
+   * @param {string} action - Audit action whose listeners should fire.
+   * @param {AuditEventPayload} args - Audit event delivered to matching listeners.
+   */
   call(type, action, args) {
     const actions = globalEventConnections[type] || {}
     const callbacks = actions[action] || []
@@ -84,7 +89,13 @@ const AuditEvents = {
     }
   },
 
-  /** Register a callback for a model type + action. Returns an unsubscribe function. @param {string} type @param {string} action @param {(args: AuditEventPayload) => void} callback @returns {() => void} */
+  /**
+   * Register a callback for a model type and action.
+   * @param {string} type - Audited model type to observe.
+   * @param {string} action - Audit action to observe.
+   * @param {(args: AuditEventPayload) => void} callback - Listener invoked for matching audit events.
+   * @returns {() => void} - Callback that removes the registration.
+   */
   connect(type, action, callback) {
     if (!globalEventConnections[type]) {
       globalEventConnections[type] = {}
@@ -109,7 +120,7 @@ const AuditEvents = {
     }
   },
 
-  /** Clear all registered callbacks. @returns {void} */
+  /** Clear all registered callbacks. */
   reset() {
     globalEventConnections = {}
   }
@@ -244,7 +255,10 @@ function sharedAuditClass(modelClass) {
    * Framework-owned Audit model for the shared `audits` table.
    */
   class Audit extends dbRecordClass {
-    /** Returns the backing table name. @returns {string} */
+    /**
+     * Returns the backing table name.
+     * @returns {string} - Shared `audits` table name.
+     */
     static tableName() {
       return "audits"
     }
@@ -291,7 +305,10 @@ function dedicatedAuditClass(modelClass, tableName) {
    * Framework-owned per-model Audit class.
    */
   class ModelAudit extends dbRecordClass {
-    /** Returns the backing table name. @returns {string} */
+    /**
+     * Returns the backing table name.
+     * @returns {string} - Dedicated audit table supplied for this model class.
+     */
     static tableName() {
       return tableName
     }
@@ -906,7 +923,7 @@ function normalizeAction(action) {
  * Creates the shared audit tables migration up/down callbacks for use inside
  * a Migration class. The `table` parameter is a Migration instance.
  * @param {{id?: {type: string}}} [options] - ID column options.
- * @returns {{down: (table: import("../migration/index.js").default) => Promise<void>, up: (table: import("../migration/index.js").default) => Promise<void>}}
+ * @returns {{down: (table: import("../migration/index.js").default) => Promise<void>, up: (table: import("../migration/index.js").default) => Promise<void>}} - Up/down callbacks for the shared audit tables.
  */
 function createSharedAuditTablesMigration(options = {}) {
   const opts = /** @type {{id?: {type: string}}} */ (options)

package/build/database/record/index.js

@@ -2688,7 +2688,7 @@ class VelociousDatabaseRecord {
    * @param {string} name - Lock name (for the error message).
    * @param {() => Promise<T>} callback - Callback holding the lock.
    * @param {number | null} [holdTimeoutMs] - Max hold time; falsy disables the timeout.
-   * @returns {Promise<T>}
+   * @returns {Promise<T>} - Callback result after the lock-protected operation.
    */
   static async runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs) {
     return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs)
@@ -3816,7 +3816,7 @@ class VelociousDatabaseRecord {
    * column of the same name. Returns the attached number, or 0 when
    * `.withCount(...)` wasn't requested for this attribute.
    * @param {string} attributeName - Attribute name, e.g. `"tasksCount"` or a custom `"activeMembersCount"` from `.withCount({activeMembersCount: {...}})`.
-   * @returns {number}
+   * @returns {number} - Attached association count, or zero when absent.
    */
   readCount(attributeName) {
     return readPayloadAssociationCount(/** @type {import("../../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), attributeName)
@@ -3837,7 +3837,7 @@ class VelociousDatabaseRecord {
    * All attached association counts as a plain object. Used by the
    * frontend-model serializer to ship counts alongside the record
    * attributes on the wire.
-   * @returns {Record<string, number>}
+   * @returns {Record<string, number>} - Association counts keyed by attribute name.
    */
   associationCounts() {
     /**
@@ -3864,7 +3864,7 @@ class VelociousDatabaseRecord {
    * registered fn for this record (e.g. no child rows matched the
    * aggregate).
    * @param {string} name - queryData attribute name (matches a SELECT alias from the registered fn).
-   * @returns {?}
+   * @returns {?} - Attached query-data value.
    */
   queryData(name) {
     return readPayloadQueryData(/** @type {import("../../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), name)
@@ -3886,7 +3886,7 @@ class VelociousDatabaseRecord {
    * All attached queryData values as a plain object. Used by the
    * frontend-model serializer to ship queryData alongside the record
    * attributes on the wire.
-   * @returns {Record<string, ?>}
+   * @returns {Record<string, ?>} - Query-data values keyed by name.
    */
   queryDataValues() {
     /**
@@ -3914,7 +3914,7 @@ class VelociousDatabaseRecord {
    * `record.can("update")` without first checking whether the ability
    * was loaded.
    * @param {string} action - Ability action name, e.g. `"update"`.
-   * @returns {boolean}
+   * @returns {boolean} - Whether the requested ability is allowed.
    */
   can(action) {
     return readPayloadComputedAbility(/** @type {import("../../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), action)
@@ -3936,7 +3936,7 @@ class VelociousDatabaseRecord {
    * All attached per-record ability results as a plain object. Used
    * by the frontend-model serializer to ship results alongside the
    * record attributes on the wire.
-   * @returns {Record<string, boolean>}
+   * @returns {Record<string, boolean>} - Ability results keyed by action.
    */
   computedAbilities() {
     /**