velocious 1.0.578 → 1.0.579

package/README.md

@@ -2579,7 +2579,7 @@ Tenant lifecycle commands print start and final counts, report each completed te
 
 `afterMigrateTenant` hooks run inside the active default and tenant database connection scope for the tenant being migrated.
 
-At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a tenant context, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. `Tenant.with` and `Tenant.each` run their callbacks inside `ensureConnections`, so switching into a tenant establishes its database connections (global + tenant), initializes registered tenant-switched models whose tables exist, and passes the connections to the callback — the tenant is immediately queryable without caller-owned connection or model initialization (already-open connections and in-progress model initialization promises are reused). Models for absent optional tables stay deferred. `Tenant.with` is generic over its callback's return type, so a value returned from inside the tenant context comes back to the caller with its type preserved (no cast needed). `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
+At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a Node async context, `Tenant.handle(tenant)` to deeply capture immutable application and physical database identity for overlapping browser/native work, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. `Tenant.handle(...).databaseOperation(...)` and `.transaction(...)` use bounded pool-owned checkouts and pin model/query/write/association/preload/audit/attachment/raw work to the captured database even if a later UI project switch changes ambient tenant state. `Model.usingTenant(tenant)` uses the same safe core and adds eager helpers plus general `databaseOperation`/`transaction` model callbacks; eager records preserve legacy ambient Node follow-up semantics, while browser/native follow-up database work belongs inside the callback APIs. Inactive identifiers, mixed physical tenants, unsupported/cyclic descriptors, and expired operations fail closed. `Tenant.with` and `Tenant.each` retain their connection-establishing and model-initializing ambient behavior for Node request/job flows. `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
 
 `SchemaCloner` adds a missing auto-increment column and its separate source unique index in one schema alteration, including on MySQL/MariaDB where an auto-increment column must be keyed when it is created.
 

package/build/application.js

@@ -83,7 +83,7 @@ export default class VelociousApplication {
 
   /**
    * Runs run.
-   * @param {function() : void} callback - Callback function.
+   * @param {() => void} callback - Callback function.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async run(callback) {
@@ -119,14 +119,14 @@ export default class VelociousApplication {
    * @param {object} args - HTTP server startup arguments.
    * @param {import("./configuration.js").default} args.configuration - Configuration instance.
    * @param {string} [args.host] - HTTP server host.
-   * @param {Record<string, ?>} args.httpServerConfiguration - Merged HTTP server configuration.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.httpServerConfiguration - Merged HTTP server configuration.
    * @param {number} args.port - HTTP server port.
    * @returns {Promise<void>} - Resolves after the HTTP server has started.
    */
   async startLockedHttpServer({configuration, host, httpServerConfiguration, port}) {
     try {
       if (!configuration.getWebsocketEvents()) {
-        configuration.setWebsocketEvents(/** @type {?} */ (websocketEventsHost))
+        configuration.setWebsocketEvents(/** @type {ReturnType<typeof JSON.parse>} */ (websocketEventsHost))
       }
 
       await configuration.connectBeacon({peerType: "server"})

package/build/authorization/ability.js

@@ -3,7 +3,7 @@
 /**
  * Defines this typedef.
  * @template {typeof import("../database/record/index.js").default} [MC=typeof import("../database/record/index.js").default]
- * @typedef {Record<string, ?> | string | ((query: import("../database/query/model-class-query.js").default<MC>, args: {ability: VelociousAuthorizationAbility, action: string, modelClass: MC}) => void | import("../database/query/model-class-query.js").default<MC>)} AbilityConditionsType
+ * @typedef {Record<string, ReturnType<typeof JSON.parse>> | string | ((query: import("../database/query/model-class-query.js").default<MC>, args: {ability: VelociousAuthorizationAbility, action: string, modelClass: MC}) => void | import("../database/query/model-class-query.js").default<MC>)} AbilityConditionsType
  */
 
 /**
@@ -45,8 +45,8 @@ export default class VelociousAuthorizationAbility {
   /**
    * Runs constructor.
    * @param {object} args - Ability args.
-   * @param {Record<string, ?>} [args.context] - Ability context.
-   * @param {Record<string, ?>} [args.locals] - Ability locals.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.context] - Ability context.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.locals] - Ability locals.
    * @param {Array<typeof import("./base-resource.js").default>} [args.resources] - Resource classes.
    */
   constructor({context = {}, locals = {}, resources} = {}) {
@@ -97,7 +97,7 @@ export default class VelociousAuthorizationAbility {
 
   /**
    * Runs get context.
-   * @returns {Record<string, ?>} - Context.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Context.
    */
   getContext() {
     return this.context
@@ -105,7 +105,7 @@ export default class VelociousAuthorizationAbility {
 
   /**
    * Runs get locals.
-   * @returns {Record<string, ?>} - Locals.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Locals.
    */
   getLocals() {
     return this.locals
@@ -113,7 +113,7 @@ export default class VelociousAuthorizationAbility {
 
   /**
    * Runs current user.
-   * @returns {?} - Current user from context.
+   * @returns {ReturnType<typeof JSON.parse>} - Current user from context.
    */
   currentUser() {
     return this.context.currentUser

package/build/authorization/base-resource.js

@@ -81,7 +81,7 @@ export default class AuthorizationBaseResource {
   /**
    * Runs assert resource conditions signature.
    * @param {object} args - Signature args.
-   * @param {?} args.conditions - Conditions value.
+   * @param {ReturnType<typeof JSON.parse>} args.conditions - Conditions value.
    * @param {"can" | "cannot"} args.methodName - Method name.
    * @returns {void}
    */

package/build/background-jobs/client.js

@@ -28,7 +28,7 @@ export default class BackgroundJobsClient {
    * Runs enqueue.
    * @param {object} args - Options.
    * @param {string} args.jobName - Job name.
-   * @param {Array<?>} args.args - Job args.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {Promise<string>} - Job id.
    */
@@ -62,7 +62,7 @@ export default class BackgroundJobsClient {
    * @param {object} args - Options.
    * @param {string} args.scheduleKey - Stable logical schedule key.
    * @param {string} args.jobName - Job name.
-   * @param {Array<?>} args.args - Job args.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
    */

package/build/background-jobs/forked-runner-child.js

@@ -31,13 +31,13 @@ async function shutdownRunner(exitCode) {
 
 /**
  * Runs is job message.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {message is {type: "job", payload: import("./types.js").BackgroundJobPayload}} - Whether this is a job message.
  */
 function isJobMessage(message) {
   if (!message || typeof message !== "object") return false
 
-  const messageRecord = /** @type {{type?: ?, payload?: ?}} */ (message)
+  const messageRecord = /** @type {{type?: ReturnType<typeof JSON.parse>, payload?: ReturnType<typeof JSON.parse>}} */ (message)
 
   return messageRecord.type === "job" && Object.hasOwn(messageRecord, "payload")
 }
@@ -68,7 +68,7 @@ function reportJobFinished() {
 
 /**
  * Runs run job message.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {Promise<void>} - Resolves after the payload has run.
  */
 async function runJobMessage(message) {
@@ -84,7 +84,7 @@ async function runJobMessage(message) {
 
 /**
  * Runs handle job message.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {Promise<void>} - Resolves after completion is reported.
  */
 async function handleJobMessage(message) {

package/build/background-jobs/job-runner.js

@@ -20,7 +20,7 @@ export class BackgroundJobPerformedFailure extends Error {
 /**
  * Runs report beacon ready error.
  * @param {import("../configuration.js").default} configuration - Configuration.
- * @param {?} error - Beacon readiness error.
+ * @param {ReturnType<typeof JSON.parse>} error - Beacon readiness error.
  * @returns {void}
  */
 function reportBeaconReadyError(configuration, error) {
@@ -94,7 +94,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
   const jobInstance = new JobClass()
   /**
    * Perform.
-   * @type {(...args: Array<?>) => Promise<void>} */
+   * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} */
   const perform = jobInstance.perform
 
   // Name the process after the job it is running so `ps`/`top` show what each

package/build/background-jobs/job.js

@@ -10,7 +10,7 @@ import BackgroundJobsClient from "./client.js"
  * `class RunBuildJob extends VelociousJob<[string]>` with `async perform(buildId)`.
  * The default empty tuple keeps argument-less jobs (`extends VelociousJob`,
  * `async perform()`) working unchanged.
- * @template {Array<?>} [TArgs=[]]
+ * @template {Array<ReturnType<typeof JSON.parse>>} [TArgs=[]]
  */
 export default class VelociousJob {
   /**
@@ -69,7 +69,7 @@ export default class VelociousJob {
 
   /**
    * Runs perform later.
-   * @param {...?} args - Job args.
+   * @param {...ReturnType<typeof JSON.parse>} args - Job args.
    * @returns {Promise<string>} - Job id.
    */
   static async performLater(...args) {
@@ -86,7 +86,7 @@ export default class VelociousJob {
   /**
    * Runs perform later with options.
    * @param {object} args - Options.
-   * @param {Array<?>} args.args - Job args.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {Promise<string>} - Job id.
    */
@@ -104,7 +104,7 @@ export default class VelociousJob {
    * Atomically replaces this job class's queued owner for a stable schedule key.
    * @param {object} args - Options.
    * @param {string} args.scheduleKey - Stable logical schedule key.
-   * @param {Array<?>} args.args - Job args.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
    */
@@ -132,8 +132,8 @@ export default class VelociousJob {
 
   /**
    * Runs split args and options.
-   * @param {Array<?>} args - Job args.
-   * @returns {{jobArgs: Array<?>, jobOptions: import("./types.js").BackgroundJobOptions}} - Split args and options.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Job args.
+   * @returns {{jobArgs: Array<ReturnType<typeof JSON.parse>>, jobOptions: import("./types.js").BackgroundJobOptions}} - Split args and options.
    */
   static _splitArgsAndOptions(args) {
     if (args.length === 0) {

package/build/background-jobs/json-socket.js

@@ -92,7 +92,7 @@ export default class JsonSocket extends EventEmitter {
 
   /**
    * Runs send.
-   * @param {?} message - Message to send.
+   * @param {ReturnType<typeof JSON.parse>} message - Message to send.
    * @returns {void}
    */
   send(message) {

package/build/background-jobs/main.js

@@ -136,7 +136,7 @@ export default class BackgroundJobsMain {
     this._unsubscribeBeacon = undefined
     /**
      * Narrows the runtime value to the documented type.
-     * @type {((...args: Array<?>) => void) | undefined} */
+     * @type {((...args: Array<ReturnType<typeof JSON.parse>>) => void) | undefined} */
     this._beaconConnectHandler = undefined
     /**
      * Narrows the runtime value to the documented type.
@@ -710,7 +710,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Reports an unexpected lease-release failure on framework error channels.
-   * @param {?} error - Release failure.
+   * @param {ReturnType<typeof JSON.parse>} error - Release failure.
    * @returns {void}
    */
   _reportHandoffReleaseError(error) {
@@ -727,7 +727,7 @@ export default class BackgroundJobsMain {
    * Reports an unexpected worker-handoff adoption failure on framework error
    * channels. A failed adoption is not fatal (the worker's jobs remain and are
    * reclaimed by the orphan sweep), but must surface rather than be swallowed.
-   * @param {?} error - Adoption failure.
+   * @param {ReturnType<typeof JSON.parse>} error - Adoption failure.
    * @returns {void}
    */
   _reportHandoffAdoptError(error) {
@@ -830,8 +830,8 @@ export default class BackgroundJobsMain {
   /**
    * Returns safe validation failures and reports unexpected client mutations.
    * @param {object} args - Options.
-   * @param {Record<string, ?>} args.context - Framework-error context.
-   * @param {?} args.error - Mutation failure.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.context - Framework-error context.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Mutation failure.
    * @param {string} args.fallbackMessage - Client-safe fallback message.
    * @param {JsonSocket} args.jsonSocket - JSON socket.
    * @param {string} args.logMessage - Error log prefix.
@@ -922,7 +922,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs emit background job failed.
-   * @param {{error: ?, handoffId?: string, handedOffAtMs?: number, job: import("./types.js").BackgroundJobRow, workerId?: string}} args - Failure event data.
+   * @param {{error: ReturnType<typeof JSON.parse>, handoffId?: string, handedOffAtMs?: number, job: import("./types.js").BackgroundJobRow, workerId?: string}} args - Failure event data.
    * @returns {void}
    */
   _emitBackgroundJobFailed({error, handoffId, handedOffAtMs, job, workerId}) {
@@ -983,7 +983,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs normalize failure error.
-   * @param {?} error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} error - Reported failure value.
    * @returns {Error} Normalized error.
    */
   _normalizeFailureError(error) {
@@ -994,7 +994,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs error from unknown failure.
-   * @param {?} error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} error - Reported failure value.
    * @returns {Error} Normalized error.
    */
   _errorFromUnknownFailure(error) {
@@ -1008,7 +1008,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs message from unknown failure.
-   * @param {?} error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} error - Reported failure value.
    * @returns {string} Error message.
    */
   _messageFromUnknownFailure(error) {
@@ -1019,7 +1019,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs has string failure.
-   * @param {?} error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} error - Reported failure value.
    * @returns {error is string} Whether the value is a non-empty string.
    */
   _hasStringFailure(error) {
@@ -1029,7 +1029,7 @@ export default class BackgroundJobsMain {
   /**
    * Runs copy string failure stack.
    * @param {object} args - Options.
-   * @param {?} args.error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Reported failure value.
    * @param {Error} args.normalizedError - Normalized error.
    * @returns {void}
    */

package/build/background-jobs/normalize-error.js

@@ -2,7 +2,7 @@
 
 /**
  * Runs normalize background job error.
- * @param {?} error - Error input.
+ * @param {ReturnType<typeof JSON.parse>} error - Error input.
  * @returns {string} - Normalized error string.
  */
 export default function normalizeBackgroundJobError(error) {
@@ -14,7 +14,7 @@ export default function normalizeBackgroundJobError(error) {
 
 /**
  * Runs stringify unknown error.
- * @param {?} error - Error input.
+ * @param {ReturnType<typeof JSON.parse>} error - Error input.
  * @returns {string} - Stringified error.
  */
 function stringifyUnknownError(error) {

package/build/background-jobs/pooled-runner-child.js

@@ -50,12 +50,12 @@ function updateProcessTitle() {
 
 /**
  * Checks whether an IPC value is a runnable pooled job message.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {message is {type: "job", payload: import("./types.js").BackgroundJobPayload & {id: string}}} - Whether this is a valid job message.
  */
 function isJobMessage(message) {
   if (!message || typeof message !== "object") return false
-  const record = /** @type {{type?: ?, payload?: ?}} */ (message)
+  const record = /** @type {{type?: ReturnType<typeof JSON.parse>, payload?: ReturnType<typeof JSON.parse>}} */ (message)
 
   return record.type === "job" && !!record.payload && typeof record.payload === "object" && typeof record.payload.id === "string"
 }
@@ -117,7 +117,7 @@ async function runJob(payload) {
 
 /**
  * Handles a job message, starting it alongside any concurrent siblings.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {void}
  */
 function handleMessage(message) {

package/build/background-jobs/scheduler.js

@@ -67,7 +67,7 @@ export default class BackgroundJobsScheduler {
    * Runs constructor.
    * @param {object} args - Options.
    * @param {import("../configuration.js").default} args.configuration - Configuration.
-   * @param {function({args: Array<?>, jobClass: typeof import("./job.js").default, jobKey: string, options: import("./types.js").BackgroundJobOptions}) : Promise<void>} args.enqueueJob - Enqueue callback.
+   * @param {(args: {args: Array<ReturnType<typeof JSON.parse>>, jobClass: typeof import("./job.js").default, jobKey: string, options: import("./types.js").BackgroundJobOptions}) => Promise<void>} args.enqueueJob - Enqueue callback.
    */
   constructor({configuration, enqueueJob}) {
     this.configuration = configuration

package/build/background-jobs/status-reporter.js

@@ -37,7 +37,7 @@ export default class BackgroundJobsStatusReporter {
    * @param {object} args - Options.
    * @param {string} args.jobId - Job id.
    * @param {"completed" | "failed"} args.status - Status.
-   * @param {?} [args.error] - Error.
+   * @param {ReturnType<typeof JSON.parse>} [args.error] - Error.
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
    * @param {string} [args.workerId] - Worker id.
@@ -84,7 +84,7 @@ export default class BackgroundJobsStatusReporter {
    * @param {object} args - Options.
    * @param {string} args.jobId - Job id.
    * @param {"completed" | "failed"} args.status - Status.
-   * @param {?} [args.error] - Error.
+   * @param {ReturnType<typeof JSON.parse>} [args.error] - Error.
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
    * @param {string} [args.workerId] - Worker id.

package/build/background-jobs/store.js

@@ -162,7 +162,7 @@ export default class BackgroundJobsStore {
    * Runs enqueue.
    * @param {object} args - Options.
    * @param {string} args.jobName - Job name.
-   * @param {Array<?>} args.args - Arguments.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Arguments.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Options.
    * @returns {Promise<string>} - Job id.
    */
@@ -190,7 +190,7 @@ export default class BackgroundJobsStore {
           .results()
 
         if (existing[0]) {
-          resultJobId = String(/** @type {Record<string, ?>} */ (existing[0]).id)
+          resultJobId = String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (existing[0]).id)
 
           return
         }
@@ -209,7 +209,7 @@ export default class BackgroundJobsStore {
    * @param {object} args - Options.
    * @param {string} args.scheduleKey - Stable logical schedule key.
    * @param {string} args.jobName - Job name.
-   * @param {Array<?>} args.args - Arguments.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Arguments.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Options.
    * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
    */
@@ -233,7 +233,7 @@ export default class BackgroundJobsStore {
             .where({schedule_key: normalizedScheduleKey})
             .limit(1)
             .results()
-          const ownerJobId = ownerRows[0] ? String(/** @type {Record<string, ?>} */ (ownerRows[0]).job_id) : null
+          const ownerJobId = ownerRows[0] ? String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (ownerRows[0]).job_id) : null
           const ownerJob = ownerJobId ? await this._getJobRowById(db, ownerJobId) : null
           /** @type {import("./types.js").BackgroundJobReplacementPreviousStatus} */
           let previousStatus = null
@@ -308,7 +308,7 @@ export default class BackgroundJobsStore {
 
           if (!ownerRows[0]) return {jobId: null, outcome: "not_found"}
 
-          const jobId = String(/** @type {Record<string, ?>} */ (ownerRows[0]).job_id)
+          const jobId = String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (ownerRows[0]).job_id)
           const job = await this._getJobRowById(db, jobId)
 
           if (job?.status === "queued") {
@@ -502,7 +502,7 @@ export default class BackgroundJobsStore {
       const counts = {}
 
       for (const row of rows) {
-        const typedRow = /** @type {Record<string, ?>} */ (row)
+        const typedRow = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)
 
         counts[String(typedRow.status)] = this._normalizeNumber(typedRow.count) || 0
       }
@@ -542,7 +542,7 @@ export default class BackgroundJobsStore {
       if (jobName) query = query.where({job_name: jobName})
 
       const rows = await query.results()
-      const countRow = /** @type {Record<string, ?>} */ (rows[0] || {})
+      const countRow = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (rows[0] || {})
 
       return this._normalizeNumber(countRow.count) || 0
     })
@@ -723,7 +723,7 @@ export default class BackgroundJobsStore {
    * Runs mark failed.
    * @param {object} args - Options.
    * @param {string} args.jobId - Job id.
-   * @param {?} args.error - Error.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Error.
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {string} [args.workerId] - Worker id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
@@ -865,7 +865,7 @@ export default class BackgroundJobsStore {
 
         if (rows.length === 0) return 0
 
-        const ids = rows.map((/** @type {Record<string, ?>} */ row) => db.quote(String(row.id))).join(", ")
+        const ids = rows.map((/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ row) => db.quote(String(row.id))).join(", ")
 
         const removed = await db.affectedRows(
           `DELETE FROM ${db.quoteTable(JOBS_TABLE)} WHERE ${db.quoteColumn("id")} IN (${ids})`
@@ -940,7 +940,7 @@ export default class BackgroundJobsStore {
   /**
    * Normalizes one new job before entering its persistence transaction.
    * @param {object} args - Job input.
-   * @param {Array<?>} args.args - Job arguments.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job arguments.
    * @param {string} args.jobName - Job name.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {PreparedBackgroundJob} - Prepared job.
@@ -1546,9 +1546,9 @@ export default class BackgroundJobsStore {
    * @param {object} args - Options.
    * @param {import("../database/drivers/base.js").default} args.db - Database connection.
    * @param {import("./types.js").BackgroundJobRow} args.job - Job row.
-   * @param {?} args.error - Error.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Error.
    * @param {boolean} args.markOrphaned - Whether marking orphaned.
-   * @param {Record<string, ?>} [args.conditions] - Update fencing conditions. Defaults to the active-handoff lease match; the time-based orphan sweep overrides this with an id/status match so it can reclaim rows whose `handoff_id` is null (e.g. handed off by an older velocious before handoff-id fencing existed).
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.conditions] - Update fencing conditions. Defaults to the active-handoff lease match; the time-based orphan sweep overrides this with an id/status match so it can reclaim rows whose `handoff_id` is null (e.g. handed off by an older velocious before handoff-id fencing existed).
    * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Updated job row when the lease transition won.
    */
   async _applyFailure({db, job, error, markOrphaned, conditions}) {
@@ -1613,12 +1613,12 @@ export default class BackgroundJobsStore {
    * @param {number} args.now - Current timestamp.
    * @param {number | null} args.scheduledAt - Next scheduled timestamp.
    * @param {boolean} args.shouldRetry - Whether the job should retry.
-   * @returns {Record<string, ?>} - Database update data.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Database update data.
    */
   _failureUpdate({failureMessage, markOrphaned, nextAttempt, now, scheduledAt, shouldRetry}) {
     /**
      * Update.
-     * @type {Record<string, ?>} */
+     * @type {Record<string, ReturnType<typeof JSON.parse>>} */
     const update = {
       attempts: nextAttempt,
       handed_off_at_ms: null,
@@ -1637,7 +1637,7 @@ export default class BackgroundJobsStore {
    * @param {object} args - Options.
    * @param {boolean} args.markOrphaned - Whether marking orphaned.
    * @param {number} args.now - Current timestamp.
-   * @param {Record<string, ?>} args.update - Database update data.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.update - Database update data.
    * @returns {void}
    */
   _applyOrphanedFailureUpdate({markOrphaned, now, update}) {
@@ -1651,7 +1651,7 @@ export default class BackgroundJobsStore {
    * @param {number} args.now - Current timestamp.
    * @param {number | null} args.scheduledAt - Next scheduled timestamp.
    * @param {boolean} args.shouldRetry - Whether the job should retry.
-   * @param {Record<string, ?>} args.update - Database update data.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.update - Database update data.
    * @returns {void}
    */
   _applyFailureStatusUpdate({markOrphaned, now, scheduledAt, shouldRetry, update}) {
@@ -1672,7 +1672,7 @@ export default class BackgroundJobsStore {
 
   /**
    * Runs normalize job row.
-   * @param {Record<string, ?>} row - Raw database row.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} row - Raw database row.
    * @returns {import("./types.js").BackgroundJobRow} - Normalized job row.
    */
   _normalizeJobRow(row) {
@@ -1944,7 +1944,7 @@ export default class BackgroundJobsStore {
    */
   async _countRevision(db) {
     const rows = await db.newQuery().from(COUNTS_REVISION_TABLE).select("revision").where({key: COUNTS_REVISION_KEY}).limit(1).results()
-    const revision = this._normalizeNumber(/** @type {Record<string, ?>} */ (rows[0] || {}).revision)
+    const revision = this._normalizeNumber(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (rows[0] || {}).revision)
 
     if (revision === null || !Number.isSafeInteger(revision) || revision < 0) {
       throw new Error(`Invalid background job count revision: ${revision}`)
@@ -2001,7 +2001,7 @@ export default class BackgroundJobsStore {
     let total = 0
 
     for (const row of rows) {
-      const typedRow = /** @type {Record<string, ?>} */ (row)
+      const typedRow = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)
       const status = String(typedRow.status)
       const count = this._normalizeNumber(typedRow.count) || 0
 
@@ -2158,7 +2158,7 @@ export default class BackgroundJobsStore {
     const concurrencyRows = await db.newQuery().from(CONCURRENCY_TABLE).select("concurrency_key").results()
 
     for (const row of concurrencyRows) {
-      const concurrencyKey = String(/** @type {Record<string, ?>} */ (row).concurrency_key)
+      const concurrencyKey = String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row).concurrency_key)
 
       if (!concurrencyKey.startsWith(QUEUE_CONCURRENCY_KEY_PREFIX)) continue
       if (cappedQueues.has(concurrencyKey.slice(QUEUE_CONCURRENCY_KEY_PREFIX.length))) continue
@@ -2174,7 +2174,7 @@ export default class BackgroundJobsStore {
 
   /**
    * Runs normalize number.
-   * @param {?} value - Input value.
+   * @param {ReturnType<typeof JSON.parse>} value - Input value.
    * @returns {number | null} - Normalized number.
    */
   _normalizeNumber(value) {
@@ -2242,8 +2242,8 @@ export default class BackgroundJobsStore {
 
   /**
    * Runs parse args.
-   * @param {?} value - Input value.
-   * @returns {Array<?>} - Parsed args.
+   * @param {ReturnType<typeof JSON.parse>} value - Input value.
+   * @returns {Array<ReturnType<typeof JSON.parse>>} - Parsed args.
    */
   _parseArgs(value) {
     if (!value) return []

package/build/background-jobs/types.js

@@ -22,7 +22,7 @@
  * @typedef {object} BackgroundJobPayload
  * @property {string} [id] - Job id.
  * @property {string} jobName - Job class name.
- * @property {Array<?>} [args] - Serialized job arguments.
+ * @property {Array<ReturnType<typeof JSON.parse>>} [args] - Serialized job arguments.
  * @property {string} [handoffId] - Unique handoff lease id.
  * @property {string} [workerId] - Worker id handling the job.
  * @property {number} [handedOffAtMs] - Time handed to a worker in ms.
@@ -32,7 +32,7 @@
  * @typedef {object} BackgroundJobRow
  * @property {string} id - Job id.
  * @property {string} jobName - Job class name.
- * @property {Array<?>} args - Serialized job arguments.
+ * @property {Array<ReturnType<typeof JSON.parse>>} args - Serialized job arguments.
  * @property {BackgroundJobExecutionMode} executionMode - How the job should run.
  * @property {string} queue - Queue name (defaults to `"default"`).
  * @property {string | null} scheduleKey - Stable logical schedule key retained for history.
@@ -71,7 +71,7 @@
 /**
  * @typedef {object} BackgroundJobFailureEvent
  * @property {BackgroundJobRow} job - Updated job row after failure handling.
- * @property {?} error - Failure error.
+ * @property {ReturnType<typeof JSON.parse>} error - Failure error.
  * @property {number | null} attempts - Updated failure attempts count.
  * @property {boolean} terminal - Whether this failure ended the job.
  * @property {boolean} willRetry - Whether the job was returned to the queue.
@@ -87,10 +87,10 @@
  * @typedef {{type: "ready", acceptsForked?: boolean, acceptsInline?: boolean, acceptsPooled?: boolean, acceptsSpawned?: boolean}} BackgroundJobReadyMessage
  * @typedef {{type: "draining"}} BackgroundJobDrainingMessage
  * @typedef {{type: "heartbeat", workerId?: string}} BackgroundJobHeartbeatMessage
- * @typedef {{type: "enqueue", jobName: string, args?: Array<?>, options?: BackgroundJobOptions}} BackgroundJobEnqueueMessage
+ * @typedef {{type: "enqueue", jobName: string, args?: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}} BackgroundJobEnqueueMessage
  * @typedef {{type: "enqueued", jobId: string}} BackgroundJobEnqueuedMessage
  * @typedef {{type: "enqueue-error", error?: string}} BackgroundJobEnqueueErrorMessage
- * @typedef {{type: "replace-scheduled", scheduleKey: string, jobName: string, args?: Array<?>, options?: BackgroundJobOptions}} BackgroundJobReplaceScheduledMessage
+ * @typedef {{type: "replace-scheduled", scheduleKey: string, jobName: string, args?: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}} BackgroundJobReplaceScheduledMessage
  * @typedef {{type: "schedule-replaced", jobId: string, previousJobId: string | null, previousStatus: BackgroundJobReplacementPreviousStatus}} BackgroundJobScheduleReplacedMessage
  * @typedef {{type: "replace-scheduled-error", error?: string}} BackgroundJobReplaceScheduledErrorMessage
  * @typedef {{type: "cancel-scheduled", scheduleKey: string}} BackgroundJobCancelScheduledMessage
@@ -98,7 +98,7 @@
  * @typedef {{type: "cancel-scheduled-error", error?: string}} BackgroundJobCancelScheduledErrorMessage
  * @typedef {{type: "job", payload: BackgroundJobPayload}} BackgroundJobJobMessage
  * @typedef {{type: "job-complete", jobId: string, handoffId?: string, workerId?: string, handedOffAtMs?: number}} BackgroundJobCompleteMessage
- * @typedef {{type: "job-failed", jobId: string, error?: ?, handoffId?: string, workerId?: string, handedOffAtMs?: number}} BackgroundJobFailedMessage
+ * @typedef {{type: "job-failed", jobId: string, error?: ReturnType<typeof JSON.parse>, handoffId?: string, workerId?: string, handedOffAtMs?: number}} BackgroundJobFailedMessage
  * @typedef {{type: "job-updated", jobId: string}} BackgroundJobUpdatedMessage
  * @typedef {{type: "job-update-error", jobId: string, error?: string}} BackgroundJobUpdateErrorMessage
  */