velocious 1.0.577 → 1.0.579

package/build/utils/ransack.js

@@ -28,7 +28,7 @@ import {resolveFrontendModelClass} from "../frontend-models/model-registry.js"
  * @property {RansackAttribute[]} attributes - Resolved attributes to test.
  * @property {RansackCombinator} combinator - How multiple attributes are combined.
  * @property {RansackPredicate} predicate - Parsed Ransack predicate.
- * @property {?} value - Normalized value.
+ * @property {ReturnType<typeof JSON.parse>} value - Normalized value.
  */
 /**
  * RansackGroup type.
@@ -83,7 +83,7 @@ const supportedPredicates = [
 /**
  * Runs the normalizeRansackParams helper.
  * @param {RansackModelClass} modelClass - Model class.
- * @param {Record<string, ?>} params - Ransack-style params hash.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Ransack-style params hash.
  * @returns {RansackCondition[]} - Normalized conditions.
  */
 export function normalizeRansackParams(modelClass, params) {
@@ -93,7 +93,7 @@ export function normalizeRansackParams(modelClass, params) {
 /**
  * Runs the normalizeRansackGroup helper.
  * @param {RansackModelClass} modelClass - Model class.
- * @param {Record<string, ?>} params - Ransack-style params hash.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Ransack-style params hash.
  * @returns {RansackGroup} - Normalized group.
  */
 export function normalizeRansackGroup(modelClass, params) {
@@ -139,7 +139,7 @@ const SKIP_RANSACK_CONDITION = Symbol("skip-ransack-condition")
  * @param {object} args - Options.
  * @param {string} args.key - Simple Ransack key.
  * @param {RansackModelClass} args.modelClass - Model class.
- * @param {?} args.rawValue - Raw condition value.
+ * @param {ReturnType<typeof JSON.parse>} args.rawValue - Raw condition value.
  * @returns {RansackCondition | null} - Normalized condition, or null when skipped.
  */
 function normalizeSimpleRansackCondition({key, modelClass, rawValue}) {
@@ -170,7 +170,7 @@ function normalizeSimpleRansackCondition({key, modelClass, rawValue}) {
  * Runs normalize advanced ransack conditions.
  * @param {object} args - Options.
  * @param {RansackModelClass} args.modelClass - Model class.
- * @param {?} args.value - Advanced conditions collection.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Advanced conditions collection.
  * @returns {RansackCondition[]} - Normalized conditions.
  */
 function normalizeAdvancedRansackConditions({modelClass, value}) {
@@ -217,7 +217,7 @@ function normalizeAdvancedRansackConditions({modelClass, value}) {
  * Runs normalize advanced ransack groups.
  * @param {object} args - Options.
  * @param {RansackModelClass} args.modelClass - Model class.
- * @param {?} args.value - Advanced groups collection.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Advanced groups collection.
  * @returns {RansackGroup[]} - Normalized groups.
  */
 function normalizeAdvancedRansackGroups({modelClass, value}) {
@@ -239,7 +239,7 @@ function normalizeAdvancedRansackGroups({modelClass, value}) {
 
 /**
  * Runs normalize ransack combinator.
- * @param {?} value - Candidate combinator.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate combinator.
  * @param {RansackCombinator} defaultValue - Default combinator.
  * @returns {RansackCombinator} - Normalized combinator.
  */
@@ -252,9 +252,9 @@ function normalizeRansackCombinator(value, defaultValue) {
 
 /**
  * Runs normalize ransack collection.
- * @param {?} value - Candidate collection.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate collection.
  * @param {string} name - Collection name for errors.
- * @returns {Array<?>} - Collection values in stable order.
+ * @returns {Array<ReturnType<typeof JSON.parse>>} - Collection values in stable order.
  */
 function normalizeRansackCollection(value, name) {
   if (value === undefined || value === null || value === "") return []
@@ -282,8 +282,8 @@ function normalizeRansackCollection(value, name) {
  * Runs advanced ransack condition value.
  * @param {object} args - Options.
  * @param {RansackPredicate} args.predicate - Parsed predicate.
- * @param {?} args.value - Advanced condition value.
- * @returns {?} - Value passed to predicate normalization.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Advanced condition value.
+ * @returns {ReturnType<typeof JSON.parse>} - Value passed to predicate normalization.
  */
 function advancedRansackConditionValue({predicate, value}) {
   if (predicate === "in" || predicate === "not_in") return value
@@ -299,7 +299,7 @@ function advancedRansackConditionValue({predicate, value}) {
  * Runs resolve ransack attributes from advanced value.
  * @param {object} args - Options.
  * @param {RansackModelClass} args.modelClass - Model class.
- * @param {?} args.value - Advanced attribute value.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Advanced attribute value.
  * @returns {RansackAttribute[]} - Resolved attributes.
  */
 function resolveRansackAttributesFromAdvancedValue({modelClass, value}) {
@@ -322,7 +322,7 @@ function resolveRansackAttributesFromAdvancedValue({modelClass, value}) {
 
 /**
  * Runs normalize advanced attribute values.
- * @param {?} value - Advanced attribute value.
+ * @param {ReturnType<typeof JSON.parse>} value - Advanced attribute value.
  * @returns {string[]} - Attribute path strings.
  */
 function normalizeAdvancedAttributeValues(value) {
@@ -341,7 +341,7 @@ function normalizeAdvancedAttributeValues(value) {
 
 /**
  * Runs normalize advanced attribute value.
- * @param {?} value - Advanced attribute entry.
+ * @param {ReturnType<typeof JSON.parse>} value - Advanced attribute entry.
  * @returns {string} - Attribute path string.
  */
 function normalizeAdvancedAttributeValue(value) {
@@ -543,12 +543,12 @@ function resolveAttributeName({modelClass, value}) {
  * @returns {Record<string, {targetModelClass: RansackModelClass}>} - Relationship entries keyed by name.
  */
 function relationshipEntries(modelClass) {
-  if (typeof /** @type {?} */ (modelClass).getRelationshipsMap === "function") {
+  if (typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).getRelationshipsMap === "function") {
     return backendRelationshipEntries(modelClass)
   }
 
-  if (typeof /** @type {?} */ (modelClass).relationshipDefinitions === "function" &&
-    typeof /** @type {?} */ (modelClass).relationshipModelClasses === "function") {
+  if (typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).relationshipDefinitions === "function" &&
+    typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).relationshipModelClasses === "function") {
     return frontendRelationshipEntries(modelClass)
   }
 
@@ -565,7 +565,7 @@ function backendRelationshipEntries(modelClass) {
    * Entries.
    * @type {Record<string, {targetModelClass: RansackModelClass}>} */
   const entries = {}
-  const relationshipsMap = /** @type {?} */ (modelClass).getRelationshipsMap()
+  const relationshipsMap = /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).getRelationshipsMap()
 
   for (const relationshipName of Object.keys(relationshipsMap)) {
     const relationship = relationshipsMap[relationshipName]
@@ -592,8 +592,8 @@ function frontendRelationshipEntries(modelClass) {
    * Entries.
    * @type {Record<string, {targetModelClass: RansackModelClass}>} */
   const entries = {}
-  const definitions = /** @type {?} */ (modelClass).relationshipDefinitions()
-  const relationshipModelClasses = /** @type {?} */ (modelClass).relationshipModelClasses()
+  const definitions = /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).relationshipDefinitions()
+  const relationshipModelClasses = /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).relationshipModelClasses()
 
   for (const relationshipName of Object.keys(definitions)) {
     const targetModelClass = resolveFrontendModelClass(relationshipModelClasses[relationshipName])
@@ -612,12 +612,12 @@ function frontendRelationshipEntries(modelClass) {
  * @returns {Record<string, string>} - Attribute-to-column entries keyed by attribute name.
  */
 function attributeEntries(modelClass) {
-  if (typeof /** @type {?} */ (modelClass).getAttributeNameToColumnNameMap === "function") {
-    return /** @type {Record<string, string>} */ ((/** @type {?} */ (modelClass).getAttributeNameToColumnNameMap()))
+  if (typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).getAttributeNameToColumnNameMap === "function") {
+    return /** @type {Record<string, string>} */ ((/** @type {ReturnType<typeof JSON.parse>} */ (modelClass).getAttributeNameToColumnNameMap()))
   }
 
-  const resourceConfig = typeof /** @type {?} */ (modelClass).resourceConfig === "function"
-    ? /** @type {?} */ (modelClass).resourceConfig()
+  const resourceConfig = typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).resourceConfig === "function"
+    ? /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).resourceConfig()
     : {}
   const attributes = resourceConfig.attributes
   /**
@@ -714,8 +714,8 @@ function snakeToCamelSuffix(value) {
  * Runs normalize ransack value.
  * @param {object} args - Options.
  * @param {RansackPredicate} args.predicate - Parsed predicate.
- * @param {?} args.value - Raw value.
- * @returns {?} - Normalized value.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Raw value.
+ * @returns {ReturnType<typeof JSON.parse>} - Normalized value.
  */
 function normalizeRansackValue({predicate, value}) {
   if (predicate === "null") {
@@ -733,7 +733,7 @@ function normalizeRansackValue({predicate, value}) {
 
 /**
  * Runs normalize ransack null value.
- * @param {?} value - Candidate null predicate value.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate null predicate value.
  * @returns {boolean | typeof SKIP_RANSACK_CONDITION} - Normalized value.
  */
 function normalizeRansackNullValue(value) {
@@ -744,8 +744,8 @@ function normalizeRansackNullValue(value) {
 
 /**
  * Runs normalize ransack list value.
- * @param {?} value - Candidate list predicate value.
- * @returns {Array<?> | typeof SKIP_RANSACK_CONDITION} - Normalized value.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate list predicate value.
+ * @returns {Array<ReturnType<typeof JSON.parse>> | typeof SKIP_RANSACK_CONDITION} - Normalized value.
  */
 function normalizeRansackListValue(value) {
   const normalizedArray = normalizeRansackArray(value)
@@ -755,16 +755,16 @@ function normalizeRansackListValue(value) {
 
 /**
  * Ransack true values.
- * @type {Set<?>} */
+ * @type {Set<ReturnType<typeof JSON.parse>>} */
 const ransackTrueValues = new Set([true, 1, "1", "true"])
 /**
  * Ransack false values.
- * @type {Set<?>} */
+ * @type {Set<ReturnType<typeof JSON.parse>>} */
 const ransackFalseValues = new Set([false, 0, "0", "false"])
 
 /**
  * Runs normalize ransack boolean.
- * @param {?} value - Candidate boolean.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate boolean.
  * @returns {boolean | null} - Normalized boolean or null when blank.
  */
 function normalizeRansackBoolean(value) {
@@ -777,7 +777,7 @@ function normalizeRansackBoolean(value) {
 
 /**
  * Runs ransack value is blank.
- * @param {?} value - Candidate value.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate value.
  * @returns {boolean} - Whether value should be ignored as blank.
  */
 function ransackValueIsBlank(value) {
@@ -786,8 +786,8 @@ function ransackValueIsBlank(value) {
 
 /**
  * Runs normalize ransack array.
- * @param {?} value - Candidate array-ish value.
- * @returns {Array<?>} - Normalized array values.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate array-ish value.
+ * @returns {Array<ReturnType<typeof JSON.parse>>} - Normalized array values.
  */
 function normalizeRansackArray(value) {
   if (Array.isArray(value)) {

package/build/utils/with-tracked-stack-async-hooks.js

@@ -9,8 +9,8 @@ let asyncLocalStorage
 
 /**
  * Tracked stack global.
- * @type {{withTrackedStack?: {addTrackedStackToError: (error: Error) => void, withTrackedStack: (arg1: string | (() => Promise<?>), arg2?: (() => Promise<?>) | Error) => Promise<?>}}} */
-const trackedStackGlobal = /** @type {?} */ (globalThis)
+ * @type {{withTrackedStack?: {addTrackedStackToError: (error: Error) => void, withTrackedStack: (arg1: string | (() => Promise<ReturnType<typeof JSON.parse>>), arg2?: (() => Promise<ReturnType<typeof JSON.parse>>) | Error) => Promise<ReturnType<typeof JSON.parse>>}}} */
+const trackedStackGlobal = /** @type {ReturnType<typeof JSON.parse>} */ (globalThis)
 
 if (AsyncLocalStorage) {
   asyncLocalStorage = new AsyncLocalStorage()
@@ -39,14 +39,14 @@ function addTrackedStackToError(error) {
 
 /**
  * Runs with tracked stack.
- * @param {(() => Promise<?>) | string} arg1 - Arg1.
- * @param {(() => Promise<?>) | Error} [arg2] - Arg2.
- * @returns {Promise<?>} - Resolves with the callback result.
+ * @param {(() => Promise<ReturnType<typeof JSON.parse>>) | string} arg1 - Arg1.
+ * @param {(() => Promise<ReturnType<typeof JSON.parse>>) | Error} [arg2] - Arg2.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the callback result.
  */
 async function withTrackedStack(arg1, arg2) {
   /**
    * Defines callback.
-   * @type {() => Promise<?>} */
+   * @type {() => Promise<ReturnType<typeof JSON.parse>>} */
   let callback
 
   /**
@@ -55,10 +55,10 @@ async function withTrackedStack(arg1, arg2) {
   let stack
 
   if (typeof arg2 == "function" && typeof arg1 == "string") {
-    callback = /** @type {() => Promise<?>} */ (arg2)
+    callback = /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ (arg2)
     stack = arg1
   } else {
-    callback = /** @type {() => Promise<?>} */ (arg1)
+    callback = /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ (arg1)
     stack = Error().stack || ""
   }
 

package/build/utils/with-tracked-stack.js

@@ -2,8 +2,8 @@
 
 /**
  * Tracked stack global.
- * @type {{withTrackedStack?: {withTrackedStack?: (stack: string | undefined, fn: () => Promise<?>) => Promise<?>, addTrackedStackToError?: (error: Error) => void}}} */
-const trackedStackGlobal = /** @type {?} */ (globalThis)
+ * @type {{withTrackedStack?: {withTrackedStack?: (stack: string | undefined, fn: () => Promise<ReturnType<typeof JSON.parse>>) => Promise<ReturnType<typeof JSON.parse>>, addTrackedStackToError?: (error: Error) => void}}} */
+const trackedStackGlobal = /** @type {ReturnType<typeof JSON.parse>} */ (globalThis)
 
 /**
  * Runs add tracked stack to error.
@@ -15,13 +15,13 @@ function addTrackedStackToError(error) {
 
 /**
  * Runs with tracked stack.
- * @param {string | (() => Promise<?>)} stackOrCallback - Stack string or callback.
- * @param {(() => Promise<?>)} [callback] - Callback to execute.
- * @returns {Promise<?>} - Resolves with value.
+ * @param {string | (() => Promise<ReturnType<typeof JSON.parse>>)} stackOrCallback - Stack string or callback.
+ * @param {(() => Promise<ReturnType<typeof JSON.parse>>)} [callback] - Callback to execute.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with value.
  */
 async function withTrackedStack(stackOrCallback, callback) {
   const tracked = trackedStackGlobal.withTrackedStack?.withTrackedStack
-  const resolvedCallback = callback ?? /** @type {() => Promise<?>} */ (stackOrCallback)
+  const resolvedCallback = callback ?? /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ (stackOrCallback)
   const stack = typeof stackOrCallback == "string" ? stackOrCallback : undefined
 
   if (tracked) {

package/build/velocious-error.js

@@ -6,17 +6,21 @@ export default class VelociousError extends Error {
    * Runs constructor.
    * @param {string} message - Error message.
    * @param {object} [args] - Options.
-   * @param {?} [args.cause] - Error cause.
+   * @param {ReturnType<typeof JSON.parse>} [args.cause] - Error cause.
    * @param {string} [args.code] - Optional error code.
+   * @param {import("./configuration-types.js").ClientErrorPayloadReporterPayload} [args.details] - Structured client-safe error details.
+   * @param {"application_error" | "authorization_error" | "record_not_found" | "validation_error"} [args.errorType] - Stable client-facing error category.
    * @param {boolean} [args.safeToExpose] - Whether the message is safe to return to clients.
    */
   constructor(message, args = {}) {
-    const {cause, code, safeToExpose = false} = args
+    const {cause, code, details, errorType, safeToExpose = false} = args
 
     super(message, {cause})
 
     this.name = "VelociousError"
     this.code = code
+    this.details = details
+    this.errorType = errorType
     this.safeToExpose = safeToExpose
   }
 
@@ -24,8 +28,10 @@ export default class VelociousError extends Error {
    * Runs safe.
    * @param {string} message - Error message.
    * @param {object} [args] - Options.
-   * @param {?} [args.cause] - Error cause.
+   * @param {ReturnType<typeof JSON.parse>} [args.cause] - Error cause.
    * @param {string} [args.code] - Optional error code.
+   * @param {import("./configuration-types.js").ClientErrorPayloadReporterPayload} [args.details] - Structured client-safe error details.
+   * @param {"application_error" | "authorization_error" | "record_not_found" | "validation_error"} [args.errorType] - Stable client-facing error category.
    * @returns {VelociousError} - Client-safe error instance.
    */
   static safe(message, args = {}) {

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.577",
+  "version": "1.0.579",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [
@@ -111,7 +111,7 @@
     "eslint-plugin-jsdoc": "^63.0.0",
     "eslint-plugin-jsdoc-inline-type-casts": "https://github.com/kaspernj/eslint-plugin-jsdoc-inline-type-casts/archive/refs/heads/master.tar.gz",
     "eslint-plugin-jsdoc-tag-lines": "^1.0.1",
-    "fallow": "3.10.0",
+    "fallow": "3.11.0",
     "globals": "^17.0.0",
     "mssql": "^12.0.0",
     "mysql": "^2.18.1",
@@ -126,7 +126,7 @@
     "sqlite3": "^6.0.1",
     "system-testing": "^1.0.108",
     "tedious": "^20.0.0",
-    "typescript": "^6.0.2",
+    "typescript": "^7.0.2",
     "uniqunize": "^1.0.3"
   }
 }

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