velocious 1.0.577 → 1.0.579

package/build/configuration.js

@@ -3,7 +3,7 @@
 /**
  * WithConnectionsCallbackType type.
  * @template T
- * @typedef {function(Record<string, import("./database/drivers/base.js").default>) : Promise<T>} WithConnectionsCallbackType
+ * @typedef {(arg: Record<string, import("./database/drivers/base.js").default>) => Promise<T>} WithConnectionsCallbackType
  */
 /**
  * WithConnectionsOptionsType type.
@@ -37,7 +37,7 @@ export {CurrentConfigurationNotSetError}
  * @returns {string | undefined} - Current working directory when the runtime exposes one.
  */
 function currentWorkingDirectory() {
-  const processObject = /** @type {{cwd?: ?} | undefined} */ (globalThis.process)
+  const processObject = /** @type {{cwd?: ReturnType<typeof JSON.parse>} | undefined} */ (globalThis.process)
 
   if (typeof processObject?.cwd !== "function") return undefined
 
@@ -68,17 +68,17 @@ function resolveWithConnectionsArgs(optionsOrCallback, callback, defaultName) {
 
 /**
  * Runs canonical debug snapshot value.
- * @param {?} value - Snapshot value to canonicalize.
- * @returns {?} Snapshot value with object keys sorted recursively.
+ * @param {ReturnType<typeof JSON.parse>} value - Snapshot value to canonicalize.
+ * @returns {ReturnType<typeof JSON.parse>} Snapshot value with object keys sorted recursively.
  */
 function canonicalDebugSnapshotValue(value) {
   if (!value || typeof value !== "object") return value
   if (Array.isArray(value)) return value.map((entry) => canonicalDebugSnapshotValue(entry))
 
   return Object.keys(value).sort().reduce((result, key) => {
-    result[key] = canonicalDebugSnapshotValue(/** @type {Record<string, ?>} */ (value)[key])
+    result[key] = canonicalDebugSnapshotValue(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (value)[key])
     return result
-  }, /** @type {Record<string, ?>} */ ({}))
+  }, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ ({}))
 }
 
 /**
@@ -106,7 +106,7 @@ function mergeDatabaseConfiguration(databaseConfiguration, overrideConfiguration
 
 /**
  * Resolves the grace window (ms) before a sustained beacon outage is reported.
- * @param {?} value - Configured `unreachableReportMs`, if any.
+ * @param {ReturnType<typeof JSON.parse>} value - Configured `unreachableReportMs`, if any.
  * @returns {number} - The configured value when it's a finite number, otherwise the 30s default.
  */
 function resolveBeaconUnreachableReportMs(value) {
@@ -126,7 +126,7 @@ const DEFAULT_COMPRESSION_GZIP_LEVEL = 6
 
 /**
  * Validates a positive safe integer configuration value.
- * @param {?} value - Configured positive safe integer.
+ * @param {ReturnType<typeof JSON.parse>} value - Configured positive safe integer.
  * @param {string} name - Configuration key.
  * @param {number} defaultValue - Default value.
  * @returns {number} - Validated configured or default value.
@@ -142,7 +142,7 @@ function positiveSafeInteger(value, name, defaultValue) {
 
 /**
  * Validates an integer configuration value inside an inclusive range.
- * @param {?} value - Configured integer.
+ * @param {ReturnType<typeof JSON.parse>} value - Configured integer.
  * @param {string} name - Configuration key.
  * @param {number} min - Minimum accepted value (inclusive).
  * @param {number} max - Maximum accepted value (inclusive).
@@ -286,6 +286,19 @@ export default class VelociousConfiguration {
     }
 
     this._isInitialized = false
+    this._modelsInitialized = false
+    /**
+     * Invalidates model phases that started before database connections closed.
+     * @type {number}
+     */
+    this._modelInitializationGeneration = 0
+    /**
+     * In-progress `initializeModels()` promise. Model initialization is an
+     * atomic bootstrap phase: concurrent callers share it, and a rejection
+     * leaves the phase eligible for a later complete attempt.
+     * @type {Promise<void> | undefined}
+     */
+    this._initializeModelsPromise = undefined
     /**
      * In-progress `initialize()` promise, memoized so concurrent callers await
      * the same bootstrap. Reset to undefined if initialization fails.
@@ -309,7 +322,7 @@ export default class VelociousConfiguration {
     }
     /**
      * Stores the http server instance value.
-     * @type {{getDebugSnapshot: () => Promise<Record<string, ?>>} | undefined} */
+     * @type {{getDebugSnapshot: () => Promise<Record<string, ReturnType<typeof JSON.parse>>>} | undefined} */
     this._httpServerInstance = undefined
     this.locale = locale
     this.localeFallbacks = localeFallbacks
@@ -382,7 +395,7 @@ export default class VelociousConfiguration {
 
     /**
      * Stores the websocket session identity resolver value.
-     * @type {((session: import("./http-server/client/websocket-session.js").default) => ? | Promise<?>) | null} */
+     * @type {((session: import("./http-server/client/websocket-session.js").default) => ReturnType<typeof JSON.parse> | Promise<ReturnType<typeof JSON.parse>>) | null} */
     this._websocketSessionIdentityResolver = null
     this._logging = logging
     this._mailerBackend = mailerBackend
@@ -729,7 +742,7 @@ export default class VelociousConfiguration {
   /**
    * Runs resolve database configuration.
    * @param {string} identifier - Identifier.
-   * @param {?} [tenant] - Tenant override.
+   * @param {ReturnType<typeof JSON.parse>} [tenant] - Tenant override.
    * @returns {import("./configuration-types.js").DatabaseConfigurationType} - Resolved database configuration for the identifier.
    */
   resolveDatabaseConfiguration(identifier, tenant = this.getCurrentTenant()) {
@@ -779,7 +792,7 @@ export default class VelociousConfiguration {
   /**
    * Runs is database identifier active.
    * @param {string} identifier - Database identifier.
-   * @param {?} [tenant] - Tenant override.
+   * @param {ReturnType<typeof JSON.parse>} [tenant] - Tenant override.
    * @returns {boolean} - Whether this database identifier is active in the current tenant context.
    */
   isDatabaseIdentifierActive(identifier, tenant = this.getCurrentTenant()) {
@@ -815,7 +828,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get debug snapshot.
-   * @returns {Promise<Record<string, ?>>} - Human-readable server diagnostics.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - Human-readable server diagnostics.
    */
   async getDebugSnapshot() {
     const localSnapshot = this.getLocalDebugSnapshot()
@@ -828,7 +841,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get local debug snapshot.
-   * @returns {Record<string, ?>} - Human-readable diagnostics for this process only.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Human-readable diagnostics for this process only.
    */
   getLocalDebugSnapshot() {
     return {
@@ -843,10 +856,10 @@ export default class VelociousConfiguration {
 
   /**
    * Runs debug http server snapshot.
-   * @returns {Promise<Record<string, ?>>} - HTTP server worker diagnostics.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - HTTP server worker diagnostics.
    */
   async _debugHttpServerSnapshot() {
-    const httpServer = /** @type {{getDebugSnapshot?: () => Promise<Record<string, ?>>} | undefined} */ (this._httpServerInstance)
+    const httpServer = /** @type {{getDebugSnapshot?: () => Promise<Record<string, ReturnType<typeof JSON.parse>>>} | undefined} */ (this._httpServerInstance)
 
     if (!httpServer?.getDebugSnapshot) {
       return {configured: Boolean(this.httpServer), active: false}
@@ -857,7 +870,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs debug server snapshot.
-   * @returns {Record<string, ?>} - Server runtime diagnostics.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Server runtime diagnostics.
    */
   _debugServerSnapshot() {
     const nodeProcess = typeof process === "undefined" ? undefined : process
@@ -874,7 +887,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs debug configuration snapshot.
-   * @returns {Record<string, ?>} - Configuration diagnostics.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Configuration diagnostics.
    */
   _debugConfigurationSnapshot() {
     return {
@@ -894,7 +907,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs debug background jobs snapshot.
-   * @returns {Record<string, ?>} - Background job diagnostics.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Background job diagnostics.
    */
   _debugBackgroundJobsSnapshot() {
     return {
@@ -905,7 +918,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs debug database snapshot.
-   * @returns {Record<string, ?>} - Database diagnostics.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Database diagnostics.
    */
   _debugDatabaseSnapshot() {
     /**
@@ -928,7 +941,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs debug websocket snapshot.
-   * @returns {Record<string, ?>} - WebSocket diagnostics.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - WebSocket diagnostics.
    */
   _debugWebsocketSnapshot() {
     /**
@@ -942,11 +955,11 @@ export default class VelociousConfiguration {
     const subscriptions = Array.from(this._websocketChannelSubscriptions.entries()).map(([channel, channelSubscriptions]) => {
       /**
        * Details buckets.
-       * @type {Map<string, {count: number, details: Record<string, ?>}>} */
+       * @type {Map<string, {count: number, details: Record<string, ReturnType<typeof JSON.parse>>}>} */
       const detailsBuckets = new Map()
 
       for (const subscription of channelSubscriptions) {
-        const details = /** @type {Record<string, ?>} */ (canonicalDebugSnapshotValue(subscription.debugSnapshot()))
+        const details = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (canonicalDebugSnapshotValue(subscription.debugSnapshot()))
         const key = JSON.stringify(details)
         const existingBucket = detailsBuckets.get(key)
 
@@ -971,7 +984,7 @@ export default class VelociousConfiguration {
       const channelSubscriptionBuckets = new Map()
 
       for (const {channelType, subscription} of session._channelSubscriptions.values()) {
-        const details = /** @type {Record<string, ?>} */ (subscription.debugSnapshot())
+        const details = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (subscription.debugSnapshot())
         const model = typeof details.model === "string" ? details.model : null
         const key = JSON.stringify({channelType, model})
         const existingBucket = channelSubscriptionBuckets.get(key)
@@ -1791,7 +1804,7 @@ export default class VelociousConfiguration {
   _deliverBroadcastFromBeacon(message) {
     /**
      * Websocket events.
-     * @type {?} */
+     * @type {ReturnType<typeof JSON.parse>} */
     const websocketEvents = this._websocketEvents
 
     if (websocketEvents && typeof websocketEvents.broadcastV2 === "function") {
@@ -2020,25 +2033,39 @@ export default class VelociousConfiguration {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async initializeModels(args = {type: "server"}) {
-    if (!this._modelsInitialized) {
-      this._modelsInitialized = true
+    if (this._modelsInitialized) return
+    if (this._initializeModelsPromise) return await this._initializeModelsPromise
 
+    const modelInitializationGeneration = this._modelInitializationGeneration
+    const initializeModelsPromise = (async () => {
       const shouldSkipDummyModelInitialization = process.env.VELOCIOUS_SKIP_DUMMY_MODEL_INITIALIZATION === "1"
         && process.env.VELOCIOUS_BROWSER_TESTS === "true"
         && this.getEnvironment() === "test"
 
-      if (shouldSkipDummyModelInitialization) {
-        return
+      if (!shouldSkipDummyModelInitialization) {
+        if (this._initializeModels) {
+          await this._initializeModels({configuration: this, type: args.type})
+        }
+
+        await this.getEnvironmentHandler().initializePackageModels(this)
+        await initializeAuditedModelRelationships(this)
+
+        await this.getEnvironmentHandler().initializeFrontendModelWebsocketPublishers(this)
       }
 
-      if (this._initializeModels) {
-        await this._initializeModels({configuration: this, type: args.type})
+      if (this._modelInitializationGeneration === modelInitializationGeneration) {
+        this._modelsInitialized = true
       }
+    })()
 
-      await this.getEnvironmentHandler().initializePackageModels(this)
-      await initializeAuditedModelRelationships(this)
+    this._initializeModelsPromise = initializeModelsPromise
 
-      await this.getEnvironmentHandler().initializeFrontendModelWebsocketPublishers(this)
+    try {
+      await initializeModelsPromise
+    } finally {
+      if (this._initializeModelsPromise === initializeModelsPromise) {
+        this._initializeModelsPromise = undefined
+      }
     }
   }
 
@@ -2073,6 +2100,12 @@ export default class VelociousConfiguration {
 
     this._initializePromise = (async () => {
       await this.initializeModels({type})
+
+      // Model initialization can be invalidated by a concurrent connection close.
+      // If models are not ready, stop without marking the configuration initialized
+      // so the next caller retries a full bootstrap.
+      if (!this._modelsInitialized) return
+
       await this.getEnvironmentHandler().autoDiscoverResources(this)
       this._mergeDiscoveredAbilityResources()
       this._validateResourceRelationshipsOnModels()
@@ -2104,6 +2137,13 @@ export default class VelociousConfiguration {
       this._initializePromise = undefined
       throw error
     }
+
+    // If the inner IIFE returned without marking the configuration initialized
+    // (e.g. because models were invalidated mid-bootstrap), clear the promise so
+    // a later call retries a full bootstrap.
+    if (!this._isInitialized) {
+      this._initializePromise = undefined
+    }
   }
 
   /**
@@ -2210,7 +2250,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs set translator.
-   * @param {function(string, Record<string, ?> | undefined) : string} callback - Translator callback.
+   * @param {(arg1: string, arg2: Record<string, ReturnType<typeof JSON.parse>> | undefined) => string} callback - Translator callback.
    * @returns {void} - No return value.
    */
   setTranslator(callback) { this._translator = callback }
@@ -2218,7 +2258,7 @@ export default class VelociousConfiguration {
   /**
    * Runs default translator.
    * @param {string} msgID - Msg id.
-   * @param {Record<string, ?>} [args] - Translator options and variables.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args] - Translator options and variables.
    * @returns {string} - The default translator.
    */
   _defaultTranslator(msgID, args) {
@@ -2246,7 +2286,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get translator.
-   * @returns {(msgID: string, args?: Record<string, ?>) => string} - The configured translator.
+   * @returns {(msgID: string, args?: Record<string, ReturnType<typeof JSON.parse>>) => string} - The configured translator.
    */
   getTranslator() {
     if (this._translator) return this._translator
@@ -2432,8 +2472,8 @@ export default class VelociousConfiguration {
    * `canSubscribe()` continue to receive broadcasts until they
    * unsubscribe or the session ends.
    * @param {string} name
-   * @param {Record<string, ?>} broadcastParams
-   * @param {?} body
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} broadcastParams
+   * @param {ReturnType<typeof JSON.parse>} body
    * @returns {void}
    */
   /**
@@ -2527,7 +2567,7 @@ export default class VelociousConfiguration {
    *
    * Return `null`/`undefined` to mean "no identity" — resumes still
    * succeed if pause and resume both resolve to a nullish value.
-   * @param {((session: import("./http-server/client/websocket-session.js").default) => ? | Promise<?>) | null} resolver - Authenticated-caller identity resolver, or null to disable identity checks.
+   * @param {((session: import("./http-server/client/websocket-session.js").default) => ReturnType<typeof JSON.parse> | Promise<ReturnType<typeof JSON.parse>>) | null} resolver - Authenticated-caller identity resolver, or null to disable identity checks.
    * @returns {void}
    */
   setWebsocketSessionIdentityResolver(resolver) {
@@ -2536,7 +2576,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get websocket session identity resolver.
-   * @returns {((session: import("./http-server/client/websocket-session.js").default) => ? | Promise<?>) | null} - The configured identity resolver.
+   * @returns {((session: import("./http-server/client/websocket-session.js").default) => ReturnType<typeof JSON.parse> | Promise<ReturnType<typeof JSON.parse>>) | null} - The configured identity resolver.
    */
   getWebsocketSessionIdentityResolver() {
     return this._websocketSessionIdentityResolver
@@ -2635,8 +2675,8 @@ export default class VelociousConfiguration {
   /**
    * Runs broadcast to channel.
    * @param {string} name - Channel type receiving the broadcast.
-   * @param {Record<string, ?>} broadcastParams - Values used to match eligible subscriptions.
-   * @param {?} body - Broadcast payload delivered to matching subscriptions.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} broadcastParams - Values used to match eligible subscriptions.
+   * @param {ReturnType<typeof JSON.parse>} body - Broadcast payload delivered to matching subscriptions.
    * @returns {void}
    */
   broadcastToChannel(name, broadcastParams, body) {
@@ -2665,7 +2705,7 @@ export default class VelociousConfiguration {
     // so fall through to the local dispatch.
     /**
      * Websocket events.
-     * @type {?} */
+     * @type {ReturnType<typeof JSON.parse>} */
     const websocketEvents = this._websocketEvents
 
     if (websocketEvents && typeof websocketEvents.broadcastV2 === "function") {
@@ -2691,7 +2731,7 @@ export default class VelociousConfiguration {
   async awaitPendingBroadcasts() {
     /**
      * Websocket events.
-     * @type {?} */
+     * @type {ReturnType<typeof JSON.parse>} */
     const websocketEvents = this._websocketEvents
 
     if (websocketEvents && typeof websocketEvents.awaitPendingBroadcasts === "function") {
@@ -2704,8 +2744,8 @@ export default class VelociousConfiguration {
    * directly (in-process mode) or by the worker thread after the
    * main-process fan-out.
    * @param {string} name - Channel name.
-   * @param {Record<string, ?>} broadcastParams - Params passed to each subscription's `matches()`.
-   * @param {?} body - Message body delivered via `sendMessage()`.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} broadcastParams - Params passed to each subscription's `matches()`.
+   * @param {ReturnType<typeof JSON.parse>} body - Message body delivered via `sendMessage()`.
    * @param {{eventId?: string}} [meta] - Optional event metadata for replay tracking.
    * @returns {void}
    */
@@ -2785,7 +2825,7 @@ export default class VelociousConfiguration {
   /**
    * Runs resolve ability.
    * @param {object} args - Ability resolver args.
-   * @param {Record<string, ?>} args.params - Request params.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.params - Request params.
    * @param {import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default} [args.request] - Request object. Absent for websocket channel subscriptions resolved from subscribe params.
    * @param {import("./http-server/client/response.js").default} [args.response] - Response object. Absent outside HTTP request handling.
    * @returns {Promise<import("./authorization/ability.js").default | undefined>} - Resolved ability.
@@ -2812,8 +2852,8 @@ export default class VelociousConfiguration {
   /**
    * Runs run with ability.
    * @param {import("./authorization/ability.js").default | undefined} ability - Ability instance.
-   * @param {() => Promise<?>} callback - Callback.
-   * @returns {Promise<?>} - Callback result.
+   * @param {() => Promise<ReturnType<typeof JSON.parse>>} callback - Callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Callback result.
    */
   async runWithAbility(ability, callback) {
     return await this.getEnvironmentHandler().runWithAbility(ability, callback)
@@ -2822,8 +2862,8 @@ export default class VelociousConfiguration {
   /**
    * Runs run with request timing.
    * @param {import("./http-server/client/request-timing.js").default | undefined} requestTiming - Request timing collector.
-   * @param {() => Promise<?>} callback - Callback.
-   * @returns {Promise<?>} - Callback result.
+   * @param {() => Promise<ReturnType<typeof JSON.parse>>} callback - Callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Callback result.
    */
   async runWithRequestTiming(requestTiming, callback) {
     return await this.getEnvironmentHandler().runWithRequestTiming(requestTiming, callback)
@@ -2832,8 +2872,8 @@ export default class VelociousConfiguration {
   /**
    * Runs run with timezone.
    * @param {string} timeZone - IANA timezone identifier.
-   * @param {() => Promise<?>} callback - Callback.
-   * @returns {Promise<?>} - Callback result.
+   * @param {() => Promise<ReturnType<typeof JSON.parse>>} callback - Callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Callback result.
    */
   async runWithTimezone(timeZone, callback) {
     return await this.getEnvironmentHandler().runWithTimezone(timeZone, callback)
@@ -2857,7 +2897,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get current tenant.
-   * @returns {?} - Current tenant from context.
+   * @returns {ReturnType<typeof JSON.parse>} - Current tenant from context.
    */
   getCurrentTenant() {
     return this.getEnvironmentHandler().getCurrentTenant()
@@ -2865,9 +2905,9 @@ export default class VelociousConfiguration {
 
   /**
    * Runs run with tenant.
-   * @param {?} tenant - Tenant.
-   * @param {() => Promise<?>} callback - Callback.
-   * @returns {Promise<?>} - Callback result.
+   * @param {ReturnType<typeof JSON.parse>} tenant - Tenant.
+   * @param {() => Promise<ReturnType<typeof JSON.parse>>} callback - Callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Callback result.
    */
   async runWithTenant(tenant, callback) {
     return await this.getEnvironmentHandler().runWithTenant(tenant, callback)
@@ -2876,11 +2916,11 @@ export default class VelociousConfiguration {
   /**
    * Runs resolve tenant.
    * @param {object} args - Tenant resolver args.
-   * @param {Record<string, ?>} args.params - Request params.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.params - Request params.
    * @param {import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default | undefined} args.request - Request object.
    * @param {import("./http-server/client/response.js").default | undefined} args.response - Response object.
-   * @param {{channel: string, params?: Record<string, ?>}} [args.subscription] - Subscription metadata.
-   * @returns {Promise<?>} - Resolved tenant.
+   * @param {{channel: string, params?: Record<string, ReturnType<typeof JSON.parse>>}} [args.subscription] - Subscription metadata.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolved tenant.
    */
   async resolveTenant({params, request, response, subscription}) {
     const resolver = this.getTenantResolver()
@@ -2983,15 +3023,19 @@ export default class VelociousConfiguration {
       throw new Error(`Unknown or inactive database identifier: ${databaseIdentifier}`)
     }
 
+    const tenant = this.getCurrentTenant()
+    const databaseConfiguration = this.resolveDatabaseConfiguration(databaseIdentifier, tenant)
     const pool = this.getDatabasePool(databaseIdentifier)
 
     return await pool.withOperationConnection({name}, async (connection, owner) => {
       const operation = new DatabaseOperation({
         configuration: this,
+        databaseConfiguration,
         configurationReuseKey: pool.getConnectionConfigurationReuseKey(connection),
         connection,
         databaseIdentifier,
-        owner
+        owner,
+        tenant
       })
 
       try {
@@ -3002,6 +3046,45 @@ export default class VelociousConfiguration {
     })
   }
 
+  /**
+   * Runs explicit model work on one connection selected from a captured physical
+   * database configuration. No ambient tenant value is read during checkout or
+   * execution.
+   * @template T
+   * @param {{databaseConfiguration: import("./configuration-types.js").DatabaseConfigurationType, databaseIdentifier: string, name?: string, tenant?: object}} options - Captured operation options.
+   * @param {(operation: DatabaseOperation) => Promise<T>} callback - Operation callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async withDatabaseOperation({databaseConfiguration, databaseIdentifier, name = "Configuration.withDatabaseOperation", tenant, ...restArgs}, callback) {
+    restArgsError(restArgs)
+
+    if (!databaseIdentifier) throw new Error("Configuration.withDatabaseOperation requires a databaseIdentifier")
+    if (!databaseConfiguration) throw new Error("Configuration.withDatabaseOperation requires a databaseConfiguration")
+    if (typeof callback != "function") throw new Error("Configuration.withDatabaseOperation requires a callback")
+
+    const pool = this.getDatabasePool(databaseIdentifier)
+    const configurationReuseKey = pool.getConfigurationReuseKey(databaseConfiguration)
+
+    return await pool.withCapturedOperationConnection({databaseConfiguration, name}, async (connection, owner) => {
+      const operation = new DatabaseOperation({
+        configuration: this,
+        databaseConfiguration,
+        configurationReuseKey,
+        connection,
+        databaseIdentifier,
+        enforceCurrentTenantReuseKey: false,
+        owner,
+        tenant
+      })
+
+      try {
+        return await callback(operation)
+      } finally {
+        operation.complete()
+      }
+    })
+  }
+
   /**
    * Runs callback with database connections for the requested identifiers.
    * @template T
@@ -3113,7 +3196,7 @@ export default class VelociousConfiguration {
 
   /**
    * Runs is missing current connection error.
-   * @param {?} error - Error thrown while looking up the current connection.
+   * @param {ReturnType<typeof JSON.parse>} error - Error thrown while looking up the current connection.
    * @returns {boolean} - Whether the error means no current connection is available.
    */
   isMissingCurrentConnectionError(error) {
@@ -3244,8 +3327,10 @@ export default class VelociousConfiguration {
           PoolClass.clearGlobalConnections(this)
         }
 
-        // Allow models to be re-initialized after connections are closed.
+        // Allow full re-initialization after connections are closed.
+        this._modelInitializationGeneration += 1
         this._modelsInitialized = false
+        this._isInitialized = false
       }
     })()
 

package/build/controller.js

@@ -12,6 +12,9 @@ import querystring from "querystring"
 import {serializeFrontendModelTransportValue} from "./frontend-models/transport-serialization.js"
 
 export default class VelociousController {
+  /** @type {Array<string> | undefined} */
+  static _beforeActions = undefined
+
   /**
    * Runs before action.
    * @param {string} methodName - Method name.
@@ -34,7 +37,7 @@ export default class VelociousController {
    * @param {string} args.action - Action.
    * @param {import("./configuration.js").default} args.configuration - Configuration instance.
    * @param {string} args.controller - Controller.
-   * @param {Record<string, ?>} args.params - Parameters object.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.params - Parameters object.
    * @param {import("./http-server/client/request.js").default} args.request - Request object.
    * @param {import("./http-server/client/response.js").default} args.response - Response object.
    * @param {string} args.viewPath - View path.
@@ -73,7 +76,7 @@ export default class VelociousController {
 
   /**
    * Runs get params.
-   * @returns {Record<string, ?>} - The params.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - The params.
    */
   getParams() { return this._params }
 
@@ -98,7 +101,7 @@ export default class VelociousController {
   /**
    * Runs set cookie.
    * @param {string} name - Cookie name.
-   * @param {?} value - Cookie value.
+   * @param {ReturnType<typeof JSON.parse>} value - Cookie value.
    * @param {object} [args] - Options object.
    * @param {string} [args.domain] - Domain.
    * @param {Date} [args.expires] - Expires date.
@@ -169,7 +172,7 @@ export default class VelociousController {
       const beforeActions = currentControllerClass._beforeActions
 
       if (beforeActions) {
-        const controllerPrototype = /** @type {Record<string, ((...args: Array<?>) => ?) | undefined>} */ (/** @type {?} */ (currentControllerClass.prototype))
+        const controllerPrototype = /** @type {Record<string, ((...args: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>) | undefined>} */ (/** @type {ReturnType<typeof JSON.parse>} */ (currentControllerClass.prototype))
 
         for (const beforeActionName of beforeActions) {
           const beforeAction = controllerPrototype[beforeActionName]
@@ -192,7 +195,7 @@ export default class VelociousController {
 
   /**
    * Runs params.
-   * @returns {Record<string, ?>} - The params.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - The params.
    */
   params() {
     // Merge query parameters so controllers can read them via params()
@@ -205,7 +208,7 @@ export default class VelociousController {
 
   /**
    * Runs query parameters.
-   * @returns {Record<string, ?>} - The query parameters.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - The query parameters.
    */
   queryParameters() {
     const query = this._request.path().split("?")[1]
@@ -215,13 +218,13 @@ export default class VelociousController {
     try {
       /**
        * Unparsed params.
-       * @type {Record<string, ?>} */
+       * @type {Record<string, ReturnType<typeof JSON.parse>>} */
       const unparsedParams = querystring.parse(query)
       const paramsToObject = new ParamsToObject(unparsedParams)
 
       return paramsToObject.toObject()
     } catch (error) {
-      const ensuredError = /** @type {Error & {velociousContext?: Record<string, ?>}} */ (error)
+      const ensuredError = /** @type {Error & {velociousContext?: Record<string, ReturnType<typeof JSON.parse>>}} */ (error)
 
       ensuredError.velociousContext = {
         ...(ensuredError.velociousContext || {}),

package/build/current.js

@@ -38,8 +38,8 @@ export default class Current {
   /**
    * Runs with ability.
    * @param {import("./authorization/ability.js").default | undefined} ability - Ability.
-   * @param {() => Promise<?>} callback - Callback.
-   * @returns {Promise<?>} - Callback result.
+   * @param {() => Promise<ReturnType<typeof JSON.parse>>} callback - Callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Callback result.
    */
   static async withAbility(ability, callback) {
     return await this.configuration().runWithAbility(ability, callback)

package/build/database/annotations-async-hooks.js

@@ -9,7 +9,7 @@ let asyncLocalStorage
 
 /**
  * Database annotations global.
- * @type {typeof globalThis & {velociousDatabaseAnnotations?: {getDatabaseAnnotations: () => string[], withDatabaseAnnotation: (annotation: string, callback: () => Promise<?>) => Promise<?>}}} */
+ * @type {typeof globalThis & {velociousDatabaseAnnotations?: {getDatabaseAnnotations: () => string[], withDatabaseAnnotation: (annotation: string, callback: () => Promise<ReturnType<typeof JSON.parse>>) => Promise<ReturnType<typeof JSON.parse>>}}} */
 const databaseAnnotationsGlobal = globalThis
 
 if (AsyncLocalStorage) {
@@ -27,8 +27,8 @@ function getDatabaseAnnotations() {
 /**
  * Runs the callback with an annotation that is appended to database query comments.
  * @param {string} annotation - Human-readable annotation for queries executed inside the callback.
- * @param {() => Promise<?>} callback - Callback to execute inside the annotation context.
- * @returns {Promise<?>} - Resolves with the callback result.
+ * @param {() => Promise<ReturnType<typeof JSON.parse>>} callback - Callback to execute inside the annotation context.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the callback result.
  */
 async function withDatabaseAnnotation(annotation, callback) {
   if (!asyncLocalStorage) return await callback()