velocious 1.0.577 → 1.0.579

package/src/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) {
@@ -786,9 +786,9 @@ export default class BackgroundJobsMain {
         options: message.options || {}
       })
 
-      jsonSocket.send({type: "schedule-replaced", ...result})
       this._notifyEnqueued()
       await this._drain()
+      jsonSocket.send({type: "schedule-replaced", ...result})
     } catch (error) {
       this._handleClientMutationError({
         context: {jobName: message.jobName, scheduleKey: message.scheduleKey, stage: "background-job-replace-scheduled"},
@@ -812,9 +812,9 @@ export default class BackgroundJobsMain {
     try {
       const result = await this.store.cancelScheduled(message.scheduleKey)
 
-      jsonSocket.send({type: "schedule-cancelled", ...result})
       this._notifyEnqueued()
       await this._drain()
+      jsonSocket.send({type: "schedule-cancelled", ...result})
     } catch (error) {
       this._handleClientMutationError({
         context: {scheduleKey: message.scheduleKey, stage: "background-job-cancel-scheduled"},
@@ -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/src/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/src/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/src/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/src/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/src/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/src/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
  */

package/src/background-jobs/web/controller.js

@@ -180,7 +180,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
   /**
    * Runs serialize job.
    * @param {import("../types.js").BackgroundJobRow} job - Job row.
-   * @returns {Record<string, ?>} - Serialized job for the API.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Serialized job for the API.
    */
   _serializeJob(job) {
     const redactArgs = Boolean(this._mountOptions().redactArgs)
@@ -209,7 +209,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
   /**
    * Runs serialize schedule.
    * @param {import("../../configuration-types.js").ScheduledBackgroundJobsConfiguration | undefined} scheduled - Scheduled jobs config.
-   * @returns {Array<Record<string, ?>>} - Serialized recurring jobs.
+   * @returns {Array<Record<string, ReturnType<typeof JSON.parse>>>} - Serialized recurring jobs.
    */
   _serializeSchedule(scheduled) {
     const jobs = scheduled?.jobs
@@ -219,7 +219,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
     const redactArgs = Boolean(this._mountOptions().redactArgs)
 
     return Object.keys(jobs).map((name) => {
-      const entry = jobs[name] || /** @type {?} */ ({})
+      const entry = jobs[name] || /** @type {ReturnType<typeof JSON.parse>} */ ({})
 
       return {
         args: redactArgs ? undefined : (entry.args || []),
@@ -235,7 +235,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
 
   /**
    * Runs sanitize status.
-   * @param {?} value - Raw status param.
+   * @param {ReturnType<typeof JSON.parse>} value - Raw status param.
    * @returns {string | undefined} - Valid status or undefined.
    */
   _sanitizeStatus(value) {
@@ -244,7 +244,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
 
   /**
    * Runs sanitize sort.
-   * @param {?} value - Raw sort param (e.g. "createdAtMs" or "-failedAtMs").
+   * @param {ReturnType<typeof JSON.parse>} value - Raw sort param (e.g. "createdAtMs" or "-failedAtMs").
    * @returns {{sortColumn: string, sortDirection: "ASC" | "DESC"}} - Normalized sort.
    */
   _sanitizeSort(value) {
@@ -261,7 +261,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
 
   /**
    * Runs positive int.
-   * @param {?} value - Raw numeric param.
+   * @param {ReturnType<typeof JSON.parse>} value - Raw numeric param.
    * @param {number} fallback - Fallback when invalid.
    * @returns {number} - Positive integer.
    */

package/src/background-jobs/web/counts-channel.js

@@ -55,7 +55,7 @@ export default class BackgroundJobCountsChannel extends VelociousWebsocketChanne
   matches(broadcastParams) {
     if (!broadcastParams || typeof broadcastParams !== "object" || Array.isArray(broadcastParams)) return false
 
-    return String(/** @type {Record<string, ?>} */ (broadcastParams).databaseIdentifier) === this.databaseIdentifier
+    return String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (broadcastParams).databaseIdentifier) === this.databaseIdentifier
   }
 
   /**

package/src/background-jobs/worker.js

@@ -434,7 +434,7 @@ export default class BackgroundJobsWorker {
     /**
      * Identified payload.
      * @type {import("./types.js").BackgroundJobPayload & {id: string}} */
-    const identifiedPayload = /** @type {?} */ (payload)
+    const identifiedPayload = /** @type {ReturnType<typeof JSON.parse>} */ (payload)
 
     const executionMode = this._executionModeForPayload(identifiedPayload)
 
@@ -795,12 +795,12 @@ export default class BackgroundJobsWorker {
    * runs jobs concurrently and reports one `job-outcome` per job id.
    * @param {object} args - Message details.
    * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
-   * @param {?} args.message - IPC message.
+   * @param {ReturnType<typeof JSON.parse>} args.message - IPC message.
    * @returns {void}
    */
   _handlePooledChildMessage({child, message}) {
     if (!message || typeof message !== "object") return
-    const record = /** @type {{type?: ?, jobId?: ?, acknowledged?: ?, rssBytes?: ?, error?: ?}} */ (message)
+    const record = /** @type {{type?: ReturnType<typeof JSON.parse>, jobId?: ReturnType<typeof JSON.parse>, acknowledged?: ReturnType<typeof JSON.parse>, rssBytes?: ReturnType<typeof JSON.parse>, error?: ReturnType<typeof JSON.parse>}} */ (message)
     const state = this.pooledChildStates.get(child)
     if (record.type !== "job-outcome" || !state || state.settling || typeof record.jobId !== "string") return
     const entry = state.inflight.get(record.jobId)
@@ -885,7 +885,7 @@ export default class BackgroundJobsWorker {
    * loop when a child crashes on startup.
    * @param {object} args - Failure details.
    * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
-   * @param {?} args.error - Failure.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Failure.
    * @returns {Promise<void>}
    */
   async _handlePooledChildFailure({child, error}) {
@@ -935,7 +935,7 @@ export default class BackgroundJobsWorker {
     const jobInstance = new JobClass()
     /**
      * Perform.
-     * @type {(...args: Array<?>) => Promise<void>} */
+     * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} */
     const perform = jobInstance.perform
 
     await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job worker inline: ${payload.jobName}`}, async () => {
@@ -1170,7 +1170,7 @@ export default class BackgroundJobsWorker {
    * Runs report forked child failure.
    * @param {object} args - Options.
    * @param {import("./types.js").BackgroundJobPayload & {id: string}} args.payload - Payload.
-   * @param {?} args.error - Error.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Error.
    * @returns {void}
    */
   _reportForkedChildFailure({payload, error}) {
@@ -1234,7 +1234,7 @@ export default class BackgroundJobsWorker {
    * @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.
@@ -1261,7 +1261,7 @@ export default class BackgroundJobsWorker {
    * @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/src/beacon/client.js

@@ -9,7 +9,7 @@ import EventEmitter from "../utils/event-emitter.js"
 
 /**
  * BeaconBroadcastHandler type.
- * @typedef {function(import("./types.js").BeaconBroadcastMessage): void} BeaconBroadcastHandler
+ * @typedef {(arg: import("./types.js").BeaconBroadcastMessage) => void} BeaconBroadcastHandler
  */
 const DEFAULT_RECONNECT_DELAY_MS = 1000
 const MAX_RECONNECT_DELAY_MS = 30_000
@@ -178,8 +178,8 @@ export default class BeaconClient extends EventEmitter {
    * unless the daemon is restarted mid-publish).
    * @param {object} args - Broadcast args.
    * @param {string} args.channel - Channel name.
-   * @param {Record<string, ?>} args.broadcastParams - Routing params.
-   * @param {?} args.body - Message body.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.broadcastParams - Routing params.
+   * @param {ReturnType<typeof JSON.parse>} args.body - Message body.
    * @returns {boolean} - True if the publish was written to the socket. False if the client is currently disconnected.
    */
   publish({channel, broadcastParams, body}) {

package/src/beacon/in-process-client.js

@@ -7,7 +7,7 @@ import {publishToInProcessPeers, registerInProcessPeer} from "./in-process-broke
 
 /**
  * BeaconBroadcastHandler type.
- * @typedef {function(import("./types.js").BeaconBroadcastMessage): void} BeaconBroadcastHandler
+ * @typedef {(arg: import("./types.js").BeaconBroadcastMessage) => void} BeaconBroadcastHandler
  */
 
 /**
@@ -85,8 +85,8 @@ export default class InProcessBeaconClient extends EventEmitter {
    * `BeaconClient` semantics.
    * @param {object} args - Broadcast args.
    * @param {string} args.channel - Channel name.
-   * @param {Record<string, ?>} args.broadcastParams - Routing params.
-   * @param {?} args.body - Message body.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.broadcastParams - Routing params.
+   * @param {ReturnType<typeof JSON.parse>} args.body - Message body.
    * @returns {boolean} - True when the broadcast was queued.
    */
   publish({channel, broadcastParams, body}) {

package/src/beacon/types.js

@@ -37,7 +37,7 @@
  */
 
 /**
- * @typedef {{type: "broadcast", channel: string, broadcastParams: Record<string, ?>, body: ?, originPeerId?: string}} BeaconBroadcastMessage
+ * @typedef {{type: "broadcast", channel: string, broadcastParams: Record<string, ReturnType<typeof JSON.parse>>, body: ReturnType<typeof JSON.parse>, originPeerId?: string}} BeaconBroadcastMessage
  *
  * `channel`, `broadcastParams`, and `body` mirror the
  * `configuration.broadcastToChannel(channel, broadcastParams, body)`

package/src/cli/base-command.js

@@ -37,7 +37,7 @@ export default class VelociousCliBaseCommand {
   /**
    * Runs execute.
    * @abstract
-   * @returns {Promise<?>} - Resolves with the execute.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the execute.
    */
   execute() {
     throw new Error("execute not implemented")

package/src/cli/commands/console.js

@@ -4,7 +4,7 @@ import BaseCommand from "../base-command.js"
 export default class VelociousCliCommandsConsole extends BaseCommand{
   /**
    * Runs execute.
-   * @returns {Promise<?>} - Resolves with the command result.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the command result.
    */
   async execute() {
     return await this.getConfiguration().getEnvironmentHandler().cliCommandsConsole(this)

package/src/cli/commands/db/schema/dump.js

@@ -4,7 +4,7 @@ import BaseCommand from "../../../base-command.js"
 export default class DbSchemaDump extends BaseCommand {
   /**
    * Runs execute.
-   * @returns {Promise<?>} - Resolves with the command result.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the command result.
    */
   async execute() {
     return await this.getConfiguration().getEnvironmentHandler().cliCommandsDbSchemaDump(this)

package/src/cli/commands/db/schema/load.js

@@ -4,7 +4,7 @@ import BaseCommand from "../../../base-command.js"
 export default class DbSchemaLoad extends BaseCommand {
   /**
    * Runs execute.
-   * @returns {Promise<?>} - Resolves with the command result.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the command result.
    */
   async execute() {
     return await this.getConfiguration().getEnvironmentHandler().cliCommandsDbSchemaLoad(this)