velocious 1.0.449 → 1.0.451

package/src/background-jobs/scheduler.js

@@ -23,7 +23,7 @@ const DURATION_MULTIPLIERS = {
 }
 /**
  * DurationUnit type.
-  @typedef {keyof typeof DURATION_MULTIPLIERS} DurationUnit */
+ * @typedef {keyof typeof DURATION_MULTIPLIERS} DurationUnit */
 
 /**
  * Runs the parseScheduledDuration helper.
@@ -54,7 +54,7 @@ export function parseScheduledDuration(value, fieldName) {
   const numericValue = Number(match[1])
   const multiplier = DURATION_MULTIPLIERS[/**
                                            * Narrows the runtime value to the documented type.
-                                            @type {DurationUnit} */ (match[2])]
+                                           * @type {DurationUnit} */ (match[2])]
 
   if (!multiplier) {
     throw new Error(`Invalid scheduled background job ${fieldName}: ${value}`)
@@ -77,11 +77,11 @@ export default class BackgroundJobsScheduler {
     this.logger = new Logger(this)
     /**
      * Narrows the runtime value to the documented type.
-      @type {Array<ReturnType<typeof setInterval>>} */
+     * @type {Array<ReturnType<typeof setInterval>>} */
     this.intervalIds = []
     /**
      * Narrows the runtime value to the documented type.
-      @type {Array<ReturnType<typeof setTimeout>>} */
+     * @type {Array<ReturnType<typeof setTimeout>>} */
     this.timeoutIds = []
     /**
      * Narrows the runtime value to the documented type.
@@ -92,7 +92,7 @@ export default class BackgroundJobsScheduler {
 
   /**
    * Runs start.
-    @returns {Promise<void>} */
+   * @returns {Promise<void>} */
   async start() {
     this.stopped = false
 
@@ -115,7 +115,7 @@ export default class BackgroundJobsScheduler {
 
   /**
    * Runs stop.
-    @returns {void} */
+   * @returns {void} */
   stop() {
     this.stopped = true
 
@@ -170,7 +170,7 @@ export default class BackgroundJobsScheduler {
   scheduleEveryJob({jobConfiguration, jobKey}) {
     const everyConfig = /**
                          * Narrows the runtime value to the documented type.
-                          @type {NonNullable<typeof jobConfiguration.every>} */ (jobConfiguration.every)
+                         * @type {NonNullable<typeof jobConfiguration.every>} */ (jobConfiguration.every)
     const {everyValue, firstInValue} = this.normalizeEvery(everyConfig)
     const intervalMs = parseScheduledDuration(everyValue, `${jobKey}.every`)
     const firstInMs = firstInValue !== undefined ? parseScheduledDuration(firstInValue, `${jobKey}.first_in`) : intervalMs

package/src/background-jobs/store.js

@@ -15,7 +15,7 @@ const DEFAULT_MAX_RETRIES = 10
 const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
 /**
  * Execution modes.
-  @type {import("./types.js").BackgroundJobExecutionMode[]} */
+ * @type {import("./types.js").BackgroundJobExecutionMode[]} */
 const EXECUTION_MODES = ["inline", "forked", "spawned"]
 const DEFAULT_EXECUTION_MODE = "forked"
 
@@ -233,13 +233,13 @@ export default class BackgroundJobsStore {
 
       /**
        * Counts.
-        @type {Record<string, number>} */
+       * @type {Record<string, number>} */
       const counts = {}
 
       for (const row of rows) {
         const typedRow = /**
                           * Narrows the runtime value to the documented type.
-                           @type {Record<string, ?>} */ (row)
+                          * @type {Record<string, ?>} */ (row)
 
         counts[String(typedRow.status)] = this._normalizeNumber(typedRow.count) || 0
       }
@@ -267,7 +267,7 @@ export default class BackgroundJobsStore {
       const rows = await query.results()
       const countRow = /**
                         * Narrows the runtime value to the documented type.
-                         @type {Record<string, ?>} */ (rows[0] || {})
+                        * @type {Record<string, ?>} */ (rows[0] || {})
 
       return this._normalizeNumber(countRow.count) || 0
     })
@@ -734,7 +734,7 @@ export default class BackgroundJobsStore {
   _failureUpdate({failureMessage, markOrphaned, nextAttempt, now, scheduledAt, shouldRetry}) {
     /**
      * Update.
-      @type {Record<string, ?>} */
+     * @type {Record<string, ?>} */
     const update = {
       attempts: nextAttempt,
       handed_off_at_ms: null,
@@ -926,7 +926,7 @@ export default class BackgroundJobsStore {
     let callbackCalled = false
     /**
      * Defines result.
-      @type {T | undefined} */
+     * @type {T | undefined} */
     let result
 
     await pool.withConnection({name: "Background jobs store"}, async (db) => {
@@ -938,7 +938,7 @@ export default class BackgroundJobsStore {
       throw new Error("Background jobs store callback was not invoked")
     }
 
-    return /** Narrows the runtime value to the documented type. @type {T} */ (result)
+    return /** @type {T} */ (result)
   }
 
   /**

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

@@ -112,7 +112,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
       const counts = await this._store().countsByStatus()
       /**
        * By status.
-        @type {Record<string, number>} */
+       * @type {Record<string, number>} */
       const byStatus = {}
       let total = 0
 
@@ -224,7 +224,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
     return Object.keys(jobs).map((name) => {
       const entry = jobs[name] || /**
                                    * Narrows the runtime value to the documented type.
-                                    @type {?} */ ({})
+                                   * @type {?} */ ({})
 
       return {
         args: redactArgs ? undefined : (entry.args || []),

package/src/background-jobs/worker.js

@@ -14,7 +14,7 @@ const FORKED_CHILD_SIGKILL_GRACE_MS = 5000
 const FORKED_RUNNER_ENTRY_PATH = fileURLToPath(new URL("./forked-runner-child.js", import.meta.url))
 /**
  * Execution modes.
-  @type {import("./types.js").BackgroundJobExecutionMode[]} */
+ * @type {import("./types.js").BackgroundJobExecutionMode[]} */
 const EXECUTION_MODES = ["inline", "forked", "spawned"]
 
 export default class BackgroundJobsWorker {
@@ -31,11 +31,11 @@ export default class BackgroundJobsWorker {
   constructor({configuration, host, port, maxConcurrentForkedJobs, maxConcurrentInlineJobs, forkedChildSigkillGraceMs} = {}) {
     /**
      * Narrows the runtime value to the documented type.
-      @type {Promise<import("../configuration.js").default>} */
+     * @type {Promise<import("../configuration.js").default>} */
     this.configurationPromise = configuration ? Promise.resolve(configuration) : configurationResolver()
     /**
      * Narrows the runtime value to the documented type.
-      @type {import("../configuration.js").default | undefined} */
+     * @type {import("../configuration.js").default | undefined} */
     this.configuration = undefined
     this.host = host
     this.port = port
@@ -50,7 +50,7 @@ export default class BackgroundJobsWorker {
       : undefined
     /**
      * Narrows the runtime value to the documented type.
-      @type {number | undefined} */
+     * @type {number | undefined} */
     this.maxConcurrentForkedJobsOverride = typeof maxConcurrentForkedJobs === "number" && maxConcurrentForkedJobs >= 1
       ? maxConcurrentForkedJobs
       : undefined
@@ -62,7 +62,7 @@ export default class BackgroundJobsWorker {
     this.maxConcurrentInlineJobs = this.maxConcurrentInlineJobsOverride || 4
     /**
      * Narrows the runtime value to the documented type.
-      @type {number} */
+     * @type {number} */
     this.maxConcurrentForkedJobs = this.maxConcurrentForkedJobsOverride || 4
     /**
      * Grace period between SIGTERM and SIGKILL when reaping process runners that
@@ -76,11 +76,11 @@ export default class BackgroundJobsWorker {
     this.workerId = randomUUID()
     /**
      * Narrows the runtime value to the documented type.
-      @type {JsonSocket | undefined} */
+     * @type {JsonSocket | undefined} */
     this.jsonSocket = undefined
     /**
      * Narrows the runtime value to the documented type.
-      @type {BackgroundJobsStatusReporter | undefined} */
+     * @type {BackgroundJobsStatusReporter | undefined} */
     this.statusReporter = undefined
     /**
      * Up to `this.maxConcurrentInlineJobs` of these run in parallel. They
@@ -275,10 +275,10 @@ export default class BackgroundJobsWorker {
     if (!payload.id) throw new Error("Background job payload missing id")
     /**
      * Identified payload.
-      @type {import("./types.js").BackgroundJobPayload & {id: string}} */
+     * @type {import("./types.js").BackgroundJobPayload & {id: string}} */
     const identifiedPayload = /**
                                * Narrows the runtime value to the documented type.
-                                @type {?} */ (payload)
+                               * @type {?} */ (payload)
 
     const executionMode = this._executionModeForPayload(identifiedPayload)
 
@@ -322,7 +322,7 @@ export default class BackgroundJobsWorker {
     // regardless of success or failure.
     /**
      * Defines inflight.
-      @type {Promise<void>} */
+     * @type {Promise<void>} */
     let inflight
 
     inflight = this._runInlineJobAndReport(payload).finally(() => {
@@ -375,7 +375,7 @@ export default class BackgroundJobsWorker {
   _trackProcessJob(processJob) {
     /**
      * Defines inflight.
-      @type {Promise<void>} */
+     * @type {Promise<void>} */
     let inflight
 
     inflight = processJob.finally(() => {
@@ -464,7 +464,7 @@ export default class BackgroundJobsWorker {
     const jobInstance = new JobClass()
     /**
      * Perform.
-      @type {(...args: Array<?>) => Promise<void>} */
+     * @type {(...args: Array<?>) => Promise<void>} */
     const perform = jobInstance.perform
 
     await configuration.withConnections({name: `Background job worker inline: ${payload.jobName}`}, async () => {

package/src/beacon/client.js

@@ -55,22 +55,22 @@ export default class BeaconClient extends EventEmitter {
     this._reconnectDelayMs = this._initialReconnectDelayMs
     /**
      * Narrows the runtime value to the documented type.
-      @type {JsonSocket | undefined} */
+     * @type {JsonSocket | undefined} */
     this._jsonSocket = undefined
     /**
      * Narrows the runtime value to the documented type.
-      @type {net.Socket | undefined} */
+     * @type {net.Socket | undefined} */
     this._socket = undefined
     this._connected = false
     this._ready = false
     this._closed = false
     /**
      * Narrows the runtime value to the documented type.
-      @type {NodeJS.Timeout | undefined} */
+     * @type {NodeJS.Timeout | undefined} */
     this._reconnectTimer = undefined
     /**
      * Narrows the runtime value to the documented type.
-      @type {Promise<void> | undefined} */
+     * @type {Promise<void> | undefined} */
     this._connectPromise = undefined
     /**
      * Last socket error observed while connected, surfaced as the disconnect reason.
@@ -118,7 +118,7 @@ export default class BeaconClient extends EventEmitter {
       }
       const onError = (/**
                         * Narrows the runtime value to the documented type.
-                         @type {Error} */ error) => {
+                        * @type {Error} */ error) => {
         this.off("connect", onConnect)
         this.off("connect-error", onError)
         reject(error)
@@ -145,7 +145,10 @@ export default class BeaconClient extends EventEmitter {
   async waitForReady({timeoutMs} = {}) {
     if (this._ready) return
 
-    /** Cleanup. @type {() => void} */
+    /**
+     * Cleans up the ready listener and timeout.
+     * @type {() => void}
+     */
     let cleanup = () => {}
     const readyPromise = new Promise((resolve) => {
       const onReady = () => {
@@ -184,7 +187,7 @@ export default class BeaconClient extends EventEmitter {
 
     /**
      * Message.
-      @type {import("./types.js").BeaconBroadcastMessage} */
+     * @type {import("./types.js").BeaconBroadcastMessage} */
     const message = {
       type: "broadcast",
       channel,
@@ -270,7 +273,7 @@ export default class BeaconClient extends EventEmitter {
 
     jsonSocket.on("message", (/**
                                * Narrows the runtime value to the documented type.
-                                @type {import("./types.js").BeaconSocketMessage} */ message) => {
+                               * @type {import("./types.js").BeaconSocketMessage} */ message) => {
       if (message?.type === "hello-ack" && message.peerId === this.peerId) {
         this._ready = true
         this.emit("ready")

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

@@ -20,11 +20,11 @@
 
 /**
  * Defines this typedef.
-  @typedef {{_receiveBroadcast: (message: import("./types.js").BeaconBroadcastMessage) => void}} InProcessPeer */
+ * @typedef {{_receiveBroadcast: (message: import("./types.js").BeaconBroadcastMessage) => void}} InProcessPeer */
 
 /**
  * Peers.
-  @type {Set<InProcessPeer>} */
+ * @type {Set<InProcessPeer>} */
 const peers = new Set()
 
 /**

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

@@ -37,7 +37,7 @@ export default class InProcessBeaconClient extends EventEmitter {
     this._connected = false
     /**
      * Narrows the runtime value to the documented type.
-      @type {(() => void) | undefined} */
+     * @type {(() => void) | undefined} */
     this._unregister = undefined
   }
 
@@ -94,7 +94,7 @@ export default class InProcessBeaconClient extends EventEmitter {
 
     /**
      * Message.
-      @type {import("./types.js").BeaconBroadcastMessage} */
+     * @type {import("./types.js").BeaconBroadcastMessage} */
     const message = {
       type: "broadcast",
       channel,

package/src/beacon/server.js

@@ -31,11 +31,11 @@ export default class BeaconServer {
     this.logger = new Logger(this)
     /**
      * Narrows the runtime value to the documented type.
-      @type {Set<JsonSocket>} */
+     * @type {Set<JsonSocket>} */
     this.peers = new Set()
     /**
      * Narrows the runtime value to the documented type.
-      @type {net.Server | undefined} */
+     * @type {net.Server | undefined} */
     this.server = undefined
     /**
      * Accepted sockets, including connections that have not completed the hello handshake yet.
@@ -110,7 +110,7 @@ export default class BeaconServer {
     const jsonSocket = new JsonSocket(socket)
     /**
      * Defines peerId.
-      @type {string | undefined} */
+     * @type {string | undefined} */
     let peerId
 
     const cleanup = () => {

package/src/cli/browser-cli.js

@@ -21,7 +21,7 @@ export default class VelociousBrowserCli {
   enable() {
     /**
      * Global scope.
-      @type {typeof globalThis & {velociousCLI?: VelociousBrowserCli}} */
+     * @type {typeof globalThis & {velociousCLI?: VelociousBrowserCli}} */
     const globalScope = globalThis
 
     globalScope.velociousCLI = this

package/src/cli/commands/db/base-command.js

@@ -4,12 +4,12 @@ import {digg} from "diggerize"
 export default class DbBaseCommand extends BaseCommand {
   /**
    * Narrows the runtime value to the documented type.
-    @type {import("../../../database/drivers/base.js").default | undefined} */
+   * @type {import("../../../database/drivers/base.js").default | undefined} */
   databaseConnection
 
   /**
    * Narrows the runtime value to the documented type.
-    @type {Array<object> | undefined} */
+   * @type {Array<object> | undefined} */
   result
 
   /**

package/src/cli/index.js

@@ -88,11 +88,11 @@ export default class VelociousCli {
     const commandNames = new Set(commands.map((command) => command.name))
     /**
      * Groups.
-      @type {string[][]} */
+     * @type {string[][]} */
     const groups = []
     /**
      * Current group.
-      @type {string[]} */
+     * @type {string[]} */
     let currentGroup = []
 
     for (const processArg of processArgs) {

package/src/cli/tenant-database-command-helper.js

@@ -18,7 +18,7 @@ export default class TenantDatabaseCommandHelper {
 
   /**
    * Runs validate tenant database identifier.
-    @returns {void} */
+   * @returns {void} */
   validateTenantDatabaseIdentifier() {
     const databaseConfiguration = this.configuration.getDatabaseConfiguration()[this.identifier]
 
@@ -88,7 +88,7 @@ export default class TenantDatabaseCommandHelper {
 
     /**
      * Failures.
-      @type {Array<{error: Error, tenant: ?}>} */
+     * @type {Array<{error: Error, tenant: ?}>} */
     const failures = []
     const workers = []
     let tenantIndex = 0
@@ -186,7 +186,7 @@ export default class TenantDatabaseCommandHelper {
     if (tenant && typeof tenant === "object") {
       const tenantObject = /**
                             * Narrows the runtime value to the documented type.
-                             @type {{id?: ?, name?: ?, slug?: ?}} */ (tenant)
+                            * @type {{id?: ?, name?: ?, slug?: ?}} */ (tenant)
 
       if (tenantObject.slug) return String(tenantObject.slug)
       if (tenantObject.name) return String(tenantObject.name)

package/src/cli/use-browser-cli.js

@@ -5,7 +5,7 @@ import restArgsError from "../utils/rest-args-error.js"
 
 /**
  * Shared.
-  @type {{browserCli?: BrowserCli}} */
+ * @type {{browserCli?: BrowserCli}} */
 const shared = {}
 
 /**

package/src/configuration-types.js

@@ -263,6 +263,8 @@
  * @property {string} [columnType] - Alias for column type name.
  * @property {string} [sqlType] - Alias for column type name.
  * @property {string} [dataType] - Alias for column type name.
+ * @property {string} [jsDocType] - Exact generated JSDoc type for non-column attributes.
+ * @property {string} [name] - Attribute name when configured as an array entry.
  * @property {boolean} [null] - Whether value can be null.
  * @property {boolean} [selectedByDefault] - Whether included in default serialization. Defaults to true.
  */
@@ -274,7 +276,7 @@
 
 /**
  * @typedef {object} FrontendModelResourceConfiguration
- * @property {string[] | Record<string, FrontendModelAttributeConfiguration | import("./database/drivers/base-column.js").default | boolean>} attributes - Attributes to expose on the frontend model.
+ * @property {Array<string | FrontendModelAttributeConfiguration> | Record<string, FrontendModelAttributeConfiguration | import("./database/drivers/base-column.js").default | boolean>} attributes - Attributes to expose on the frontend model.
  * @property {string[]} [abilities] - Ability action list (camelCase action names). Defaults to `["read"]` for `find` and `index` when omitted.
  * @property {Record<string, FrontendModelAttachmentConfiguration>} [attachments] - Attachment helpers keyed by attachment name.
  * @property {string[]} [commands] - Legacy built-in command names (`index`, `find`, `create`, `update`, `destroy`, `attach`, `download`, `url`).