velocious 1.0.460 → 1.0.462

package/README.md

@@ -2200,7 +2200,7 @@ export default new Configuration({
 })
 ```
 
-Use `configuration.runWithTenant(tenant, callback)` or `Current.tenant()` when custom model/database routing needs to read the active tenant manually.
+Use `configuration.runWithTenant(tenant, callback)` or `Current.tenant()` when custom model/database routing needs to read the active tenant manually. The tenant is an app-defined value — inputs (`runWithTenant`/`Current.setTenant`/`Current.withTenant`) accept any `object`, `Current.tenant()` returns `Record<string, unknown> | undefined`, and the `switchesTenantDatabase(...)` resolver callback receives `Record<string, unknown> | null | undefined`, so narrow before reading fields. See [tenant object typing](docs/tenant-databases.md#tenant-object-typing).
 
 Tenant-switched model classes fail closed by default: if `switchesTenantDatabase(...)` cannot resolve a tenant database identifier for the current tenant, Velocious raises `TenantDatabaseScopeError` instead of running the query against the configured fallback database. Set `enforceTenantDatabaseScopes: false` only for legacy apps that still need the old fallback behavior during migration.
 

package/build/application.js

@@ -119,9 +119,7 @@ export default class VelociousApplication {
   async startLockedHttpServer({configuration, host, httpServerConfiguration, port}) {
     try {
       if (!configuration.getWebsocketEvents()) {
-        configuration.setWebsocketEvents(/**
-                                          * Types the following value.
-                                          * @type {?} */ (websocketEventsHost))
+        configuration.setWebsocketEvents(/** @type {?} */ (websocketEventsHost))
       }
 
       await configuration.connectBeacon({peerType: "server"})

package/build/background-jobs/cron-expression.js

@@ -60,9 +60,7 @@ export function parseCronExpression(expression) {
   }
 
   const trimmed = expression.trim().toLowerCase()
-  const expanded = SHORTCUTS[/**
-                              * Narrows the runtime value to the documented type.
-                              * @type {keyof typeof SHORTCUTS} */ (trimmed)] || trimmed
+  const expanded = SHORTCUTS[/** @type {keyof typeof SHORTCUTS} */ (trimmed)] || trimmed
   const fields = expanded.split(/\s+/)
 
   if (fields.length !== 5) {

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

@@ -12,9 +12,7 @@ let finishing = false
 function isJobMessage(message) {
   if (!message || typeof message !== "object") return false
 
-  const messageRecord = /**
-                         * Narrows the runtime value to the documented type.
-                         * @type {{type?: ?, payload?: ?}} */ (message)
+  const messageRecord = /** @type {{type?: ?, payload?: ?}} */ (message)
 
   return messageRecord.type === "job" && Object.hasOwn(messageRecord, "payload")
 }

package/build/background-jobs/job.js

@@ -58,9 +58,7 @@ export default class VelociousJob {
     const isOptionsArg = lastArg && typeof lastArg === "object" && !Array.isArray(lastArg) && "jobOptions" in lastArg
 
     if (isOptionsArg) {
-      const {jobOptions} = /**
-                            * Narrows the runtime value to the documented type.
-                            * @type {{jobOptions: import("./types.js").BackgroundJobOptions}} */ (lastArg)
+      const {jobOptions} = /** @type {{jobOptions: import("./types.js").BackgroundJobOptions}} */ (lastArg)
       return {jobArgs: args.slice(0, -1), jobOptions: jobOptions || {}}
     }
 

package/build/background-jobs/scheduler.js

@@ -52,9 +52,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])]
+  const multiplier = DURATION_MULTIPLIERS[/** @type {DurationUnit} */ (match[2])]
 
   if (!multiplier) {
     throw new Error(`Invalid scheduled background job ${fieldName}: ${value}`)
@@ -168,9 +166,7 @@ export default class BackgroundJobsScheduler {
    * @returns {void}
    */
   scheduleEveryJob({jobConfiguration, jobKey}) {
-    const everyConfig = /**
-                         * Narrows the runtime value to the documented type.
-                         * @type {NonNullable<typeof jobConfiguration.every>} */ (jobConfiguration.every)
+    const everyConfig = /** @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/build/background-jobs/store.js

@@ -237,9 +237,7 @@ export default class BackgroundJobsStore {
       const counts = {}
 
       for (const row of rows) {
-        const typedRow = /**
-                          * Narrows the runtime value to the documented type.
-                          * @type {Record<string, ?>} */ (row)
+        const typedRow = /** @type {Record<string, ?>} */ (row)
 
         counts[String(typedRow.status)] = this._normalizeNumber(typedRow.count) || 0
       }
@@ -265,9 +263,7 @@ export default class BackgroundJobsStore {
       if (jobName) query = query.where({job_name: jobName})
 
       const rows = await query.results()
-      const countRow = /**
-                        * Narrows the runtime value to the documented type.
-                        * @type {Record<string, ?>} */ (rows[0] || {})
+      const countRow = /** @type {Record<string, ?>} */ (rows[0] || {})
 
       return this._normalizeNumber(countRow.count) || 0
     })

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

@@ -222,9 +222,7 @@ export default class VelociousBackgroundJobsWebController extends Controller {
     const redactArgs = Boolean(this._mountOptions().redactArgs)
 
     return Object.keys(jobs).map((name) => {
-      const entry = jobs[name] || /**
-                                   * Narrows the runtime value to the documented type.
-                                   * @type {?} */ ({})
+      const entry = jobs[name] || /** @type {?} */ ({})
 
       return {
         args: redactArgs ? undefined : (entry.args || []),

package/build/background-jobs/worker.js

@@ -276,9 +276,7 @@ export default class BackgroundJobsWorker {
     /**
      * Identified payload.
      * @type {import("./types.js").BackgroundJobPayload & {id: string}} */
-    const identifiedPayload = /**
-                               * Narrows the runtime value to the documented type.
-                               * @type {?} */ (payload)
+    const identifiedPayload = /** @type {?} */ (payload)
 
     const executionMode = this._executionModeForPayload(identifiedPayload)
 

package/build/beacon/client.js

@@ -116,9 +116,7 @@ export default class BeaconClient extends EventEmitter {
         this.off("connect-error", onError)
         resolve()
       }
-      const onError = (/**
-                        * Narrows the runtime value to the documented type.
-                        * @type {Error} */ error) => {
+      const onError = (/** @type {Error} */ error) => {
         this.off("connect", onConnect)
         this.off("connect-error", onError)
         reject(error)
@@ -271,9 +269,7 @@ export default class BeaconClient extends EventEmitter {
       this.emit("connect")
     })
 
-    jsonSocket.on("message", (/**
-                               * Narrows the runtime value to the documented type.
-                               * @type {import("./types.js").BeaconSocketMessage} */ message) => {
+    jsonSocket.on("message", (/** @type {import("./types.js").BeaconSocketMessage} */ message) => {
       if (message?.type === "hello-ack" && message.peerId === this.peerId) {
         this._ready = true
         this.emit("ready")

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

@@ -184,9 +184,7 @@ export default class TenantDatabaseCommandHelper {
    */
   tenantLabel(tenant) {
     if (tenant && typeof tenant === "object") {
-      const tenantObject = /**
-                            * Narrows the runtime value to the documented type.
-                            * @type {{id?: ?, name?: ?, slug?: ?}} */ (tenant)
+      const tenantObject = /** @type {{id?: ?, name?: ?, slug?: ?}} */ (tenant)
 
       if (tenantObject.slug) return String(tenantObject.slug)
       if (tenantObject.name) return String(tenantObject.name)

package/build/configuration.js

@@ -30,15 +30,34 @@ export {CurrentConfigurationNotSetError}
  * @returns {string | undefined} - Current working directory when the runtime exposes one.
  */
 function currentWorkingDirectory() {
-  const processObject = /**
-                         * Types the following value.
-                         * @type {{cwd?: ?} | undefined} */ (globalThis.process)
+  const processObject = /** @type {{cwd?: ?} | undefined} */ (globalThis.process)
 
   if (typeof processObject?.cwd !== "function") return undefined
 
   return processObject.cwd()
 }
 
+/**
+ * Resolves the overloaded with/ensure connections arguments.
+ * @template T
+ * @param {WithConnectionsOptionsType | WithConnectionsCallbackType<T>} optionsOrCallback - Checkout options or callback function.
+ * @param {WithConnectionsCallbackType<T> | undefined} callback - Callback function.
+ * @param {string} defaultName - Default checkout name.
+ * @returns {{name: string, callback: WithConnectionsCallbackType<T> | undefined}} Resolved checkout name and callback.
+ */
+function resolveWithConnectionsArgs(optionsOrCallback, callback, defaultName) {
+  if (typeof optionsOrCallback == "function") {
+    const actualCallback = /** @type {WithConnectionsCallbackType<T>} */ (optionsOrCallback)
+
+    return {name: defaultName, callback: actualCallback}
+  }
+
+  return {
+    name: optionsOrCallback.name || defaultName,
+    callback
+  }
+}
+
 /**
  * Runs canonical debug snapshot value.
  * @param {?} value - Snapshot value to canonicalize.
@@ -49,13 +68,9 @@ function canonicalDebugSnapshotValue(value) {
   if (Array.isArray(value)) return value.map((entry) => canonicalDebugSnapshotValue(entry))
 
   return Object.keys(value).sort().reduce((result, key) => {
-    result[key] = canonicalDebugSnapshotValue(/**
-                                               * Types the following value.
-                                               * @type {Record<string, ?>} */ (value)[key])
+    result[key] = canonicalDebugSnapshotValue(/** @type {Record<string, ?>} */ (value)[key])
     return result
-  }, /**
-      * Types the following value.
-      * @type {Record<string, ?>} */ ({}))
+  }, /** @type {Record<string, ?>} */ ({}))
 }
 
 /**
@@ -496,9 +511,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<Record<string, ?>>} - HTTP server worker diagnostics.
    */
   async _debugHttpServerSnapshot() {
-    const httpServer = /**
-                        * Types the following value.
-                        * @type {{getDebugSnapshot?: () => Promise<Record<string, ?>>} | undefined} */ (this._httpServerInstance)
+    const httpServer = /** @type {{getDebugSnapshot?: () => Promise<Record<string, ?>>} | undefined} */ (this._httpServerInstance)
 
     if (!httpServer?.getDebugSnapshot) {
       return {configured: Boolean(this.httpServer), active: false}
@@ -597,9 +610,7 @@ export default class VelociousConfiguration {
       const detailsBuckets = new Map()
 
       for (const subscription of channelSubscriptions) {
-        const details = /**
-                         * Types the following value.
-                         * @type {Record<string, ?>} */ (canonicalDebugSnapshotValue(subscription.debugSnapshot()))
+        const details = /** @type {Record<string, ?>} */ (canonicalDebugSnapshotValue(subscription.debugSnapshot()))
         const key = JSON.stringify(details)
         const existingBucket = detailsBuckets.get(key)
 
@@ -624,9 +635,7 @@ export default class VelociousConfiguration {
       const channelSubscriptionBuckets = new Map()
 
       for (const {channelType, subscription} of session._channelSubscriptions.values()) {
-        const details = /**
-                         * Types the following value.
-                         * @type {Record<string, ?>} */ (subscription.debugSnapshot())
+        const details = /** @type {Record<string, ?>} */ (subscription.debugSnapshot())
         const model = typeof details.model === "string" ? details.model : null
         const key = JSON.stringify({channelType, model})
         const existingBucket = channelSubscriptionBuckets.get(key)
@@ -2422,13 +2431,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withConnections(optionsOrCallback, callback) {
-    const name = typeof optionsOrCallback == "function" ? "Configuration.withConnections" : (optionsOrCallback.name || "Configuration.withConnections")
-    /**
-     * Actual with connections callback.
-     * @type {WithConnectionsCallbackType<T> | undefined} */
-    const actualWithConnectionsCallback = typeof optionsOrCallback == "function" ? /**
-                                                                                    * Types the following value.
-                                                                                    * @type {WithConnectionsCallbackType<T>} */ (optionsOrCallback) : callback
+    const {name, callback: actualWithConnectionsCallback} = resolveWithConnectionsArgs(optionsOrCallback, callback, "Configuration.withConnections")
 
     if (!actualWithConnectionsCallback) throw new Error("withConnections requires a callback")
 
@@ -2537,13 +2540,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async ensureConnections(optionsOrCallback, callback) {
-    const name = typeof optionsOrCallback == "function" ? "Configuration.ensureConnections" : (optionsOrCallback.name || "Configuration.ensureConnections")
-    /**
-     * Actual with connections callback.
-     * @type {WithConnectionsCallbackType<T> | undefined} */
-    const actualWithConnectionsCallback = typeof optionsOrCallback == "function" ? /**
-                                                                                    * Types the following value.
-                                                                                    * @type {WithConnectionsCallbackType<T>} */ (optionsOrCallback) : callback
+    const {name, callback: actualWithConnectionsCallback} = resolveWithConnectionsArgs(optionsOrCallback, callback, "Configuration.ensureConnections")
 
     if (!actualWithConnectionsCallback) throw new Error("ensureConnections requires a callback")
 

package/build/controller.js

@@ -141,9 +141,7 @@ export default class VelociousController {
    * @returns {typeof VelociousController} - The controller class.
    */
   _getControllerClass() {
-    const controllerClass = /**
-                             * Types the following value.
-                             * @type {typeof VelociousController} */ (this.constructor)
+    const controllerClass = /** @type {typeof VelociousController} */ (this.constructor)
 
     return controllerClass
   }
@@ -159,11 +157,7 @@ export default class VelociousController {
       const beforeActions = currentControllerClass._beforeActions
 
       if (beforeActions) {
-        const controllerPrototype = /**
-                                     * Types the following value.
-                                     * @type {Record<string, Function | undefined>} */ (/**
-                                                                                        * Types the following value.
-                                                                                        * @type {?} */ (currentControllerClass.prototype))
+        const controllerPrototype = /** @type {Record<string, Function | undefined>} */ (/** @type {?} */ (currentControllerClass.prototype))
 
         for (const beforeActionName of beforeActions) {
           const beforeAction = controllerPrototype[beforeActionName]
@@ -215,9 +209,7 @@ export default class VelociousController {
 
       return paramsToObject.toObject()
     } catch (error) {
-      const ensuredError = /**
-                            * Types the following value.
-                            * @type {Error & {velociousContext?: Record<string, ?>}} */ (error)
+      const ensuredError = /** @type {Error & {velociousContext?: Record<string, ?>}} */ (error)
 
       ensuredError.velociousContext = {
         ...(ensuredError.velociousContext || {}),
@@ -295,9 +287,7 @@ export default class VelociousController {
 
       ejs.renderFile(viewPath, actualViewParams, {}, (err, str) => {
         if (err) {
-          const renderError = /**
-                               * Types the following value.
-                               * @type {Error & {code?: string}} */ (err)
+          const renderError = /** @type {Error & {code?: string}} */ (err)
 
           if (renderError.code === "ENOENT") {
             this.logger.warn(`Missing view file: ${viewPath}`)

package/build/current.js

@@ -61,7 +61,7 @@ export default class Current {
 
   /**
    * Runs set tenant.
-   * @param {Record<string, unknown>} tenant - Tenant.
+   * @param {object} tenant - Tenant. Any caller-defined object shape; read back (and narrowed) via tenant().
    * @returns {void} - No return value.
    */
   static setTenant(tenant) {
@@ -70,7 +70,7 @@ export default class Current {
 
   /**
    * Runs with tenant.
-   * @param {Record<string, unknown>} tenant - Tenant.
+   * @param {object} tenant - Tenant. Any caller-defined object shape; read back (and narrowed) via tenant().
    * @param {() => Promise<?>} callback - Callback.
    * @returns {Promise<?>} - Callback result.
    */

package/build/database/drivers/mssql/index.js

@@ -340,9 +340,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
       const tables = []
 
       for (const row of result) {
-        const table = new Table(this, /**
-                                       * Narrows the runtime value to the documented type.
-                                       * @type {Record<string, string>} */ (row))
+        const table = new Table(this, /** @type {Record<string, string>} */ (row))
 
         tables.push(table)
       }

package/build/database/drivers/mysql/index.js

@@ -223,9 +223,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @returns {import("../base.js").RetryableDatabaseErrorResult} - Retry info.
    */
   retryableDatabaseError(error) {
-    const errorCode = /**
-                       * Narrows the runtime value to the documented type.
-                       * @type {?} */ (error).code
+    const errorCode = /** @type {?} */ (error).code
     const message = error.message || ""
     const shouldRetry = (
       errorCode == "ECONNREFUSED" ||
@@ -337,9 +335,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
       const tables = []
 
       for (const row of result) {
-        const table = new Table(this, /**
-                                       * Narrows the runtime value to the documented type.
-                                       * @type {Record<string, string>} */ (row))
+        const table = new Table(this, /** @type {Record<string, string>} */ (row))
 
         tables.push(table)
       }

package/build/database/drivers/pgsql/index.js

@@ -292,9 +292,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
       const tables = []
 
       for (const row of result) {
-        const table = new Table(this, /**
-                                       * Narrows the runtime value to the documented type.
-                                       * @type {Record<string, string>} */ (row))
+        const table = new Table(this, /** @type {Record<string, string>} */ (row))
 
         tables.push(table)
       }

package/build/database/drivers/sqlite/base.js

@@ -87,9 +87,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * @returns {Promise<string[]>} - Resolves with SQL statements.
    */
   async dropTableSQLs(tableName, args = {}) {
-    const driver = /**
-                    * Narrows the runtime value to the documented type.
-                    * @type {import("../base.js").default} */ (this)
+    const driver = /** @type {import("../base.js").default} */ (this)
     const dropArgs = Object.assign({tableName, driver}, args)
     const dropTable = new DropTable(dropArgs)
 
@@ -126,9 +124,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
       const tables = []
 
       for (const row of result) {
-        const table = new Table({driver: this, row: /**
-                                                     * Narrows the runtime value to the documented type.
-                                                     * @type {Record<string, string | number | null>} */ (row)})
+        const table = new Table({driver: this, row: /** @type {Record<string, string | number | null>} */ (row)})
 
         tables.push(table)
       }
@@ -403,9 +399,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
           if (timeoutHandle) clearTimeout(timeoutHandle)
 
           const current = state.waitersByName.get(name) || []
-          const index = current.indexOf(/**
-                                         * Narrows the runtime value to the documented type.
-                                         * @type {() => void} */ (removeAndResolve))
+          const index = current.indexOf(/** @type {() => void} */ (removeAndResolve))
 
           if (index >= 0) current.splice(index, 1)
           if (current.length === 0) state.waitersByName.delete(name)

package/build/database/drivers/sqlite/index.js

@@ -247,9 +247,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
         return true
       } catch (error) {
-        if (/**
-             * Narrows the runtime value to the documented type.
-             * @type {NodeJS.ErrnoException} */ (error)?.code !== "EEXIST") throw error
+        if (/** @type {NodeJS.ErrnoException} */ (error)?.code !== "EEXIST") throw error
 
         if (await this._isAdvisoryLockStale(lockPath)) {
           await fs.rm(lockPath, {recursive: true, force: true})
@@ -285,9 +283,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
       return true
     } catch (error) {
-      if (/**
-           * Narrows the runtime value to the documented type.
-           * @type {NodeJS.ErrnoException} */ (error)?.code !== "EEXIST") throw error
+      if (/** @type {NodeJS.ErrnoException} */ (error)?.code !== "EEXIST") throw error
 
       if (await this._isAdvisoryLockStale(lockPath)) {
         await fs.rm(lockPath, {recursive: true, force: true})
@@ -298,9 +294,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
           return true
         } catch (retryError) {
-          if (/**
-               * Narrows the runtime value to the documented type.
-               * @type {NodeJS.ErrnoException} */ (retryError)?.code === "EEXIST") return false
+          if (/** @type {NodeJS.ErrnoException} */ (retryError)?.code === "EEXIST") return false
 
           throw retryError
         }

package/build/database/drivers/sqlite/table.js

@@ -71,9 +71,7 @@ export default class VelociousDatabaseDriversSqliteTable extends BaseTable {
 
         if (!sql) throw new Error(`Could not find SQL for index ${columnsIndex.getName()}`)
 
-        const indexData = /**
-                           * Narrows the runtime value to the documented type.
-                           * @type {typeof columnsIndex.data & {columnNames?: string[]}} */ (columnsIndex.data)
+        const indexData = /** @type {typeof columnsIndex.data & {columnNames?: string[]}} */ (columnsIndex.data)
 
         indexData.columnNames = this._parseColumnsFromSQL(String(sql))
 

package/build/database/migrator.js

@@ -301,9 +301,7 @@ export default class VelociousDatabaseMigrator {
       const migrationName = match[2]
       const migrationClassName = inflection.camelize(migrationName)
 
-      const migrationObject = /**
-                               * Narrows the runtime value to the documented type.
-                               * @type {import("./migrator/types.js").MigrationObjectType} */ ({
+      const migrationObject = /** @type {import("./migrator/types.js").MigrationObjectType} */ ({
         file,
         date,
         migrationClassName