velocious 1.0.577 → 1.0.579

package/build/http-server/client/websocket-session.js

@@ -15,7 +15,7 @@ import WebsocketRequest from "./websocket-request.js"
 
 /**
  * Defines this typedef.
- * @typedef {{type: "subscribe", channel: string, lastEventId?: string, params?: Record<string, ?>} | {type: "metadata", data?: Record<string, ?>} | {type?: "request", body?: ?, headers?: Record<string, ?>, id?: string | number | null, method: string, path: string} | Record<string, ?>} WebsocketSessionMessage
+ * @typedef {{type: "subscribe", channel: string, lastEventId?: string, params?: Record<string, ReturnType<typeof JSON.parse>>} | {type: "metadata", data?: Record<string, ReturnType<typeof JSON.parse>>} | {type?: "request", body?: ReturnType<typeof JSON.parse>, headers?: Record<string, ReturnType<typeof JSON.parse>>, id?: string | number | null, method: string, path: string} | Record<string, ReturnType<typeof JSON.parse>>} WebsocketSessionMessage
  */
 
 /**
@@ -60,23 +60,23 @@ const WEBSOCKET_MAX_FRAGMENTED_MESSAGE_FRAGMENTS = 1024
 /**
  * Runs subscribe message.
  * @param {WebsocketSessionMessage} message - Raw websocket message.
- * @returns {{type: "subscribe", channel: string, lastEventId?: string, params?: Record<string, ?>} | null} - Subscribe message when matched.
+ * @returns {{type: "subscribe", channel: string, lastEventId?: string, params?: Record<string, ReturnType<typeof JSON.parse>>} | null} - Subscribe message when matched.
  */
 function subscribeMessage(message) {
   return message.type === "subscribe"
-    ? /** @type {{type: "subscribe", channel: string, lastEventId?: string, params?: Record<string, ?>}} */ (message)
+    ? /** @type {{type: "subscribe", channel: string, lastEventId?: string, params?: Record<string, ReturnType<typeof JSON.parse>>}} */ (message)
     : null
 }
 
 /**
  * Runs request message.
  * @param {WebsocketSessionMessage} message - Raw websocket message.
- * @returns {{type?: "request", body?: ?, headers?: Record<string, ?>, id?: string | number | null, method: string, path: string} | null} - Request message when matched.
+ * @returns {{type?: "request", body?: ReturnType<typeof JSON.parse>, headers?: Record<string, ReturnType<typeof JSON.parse>>, id?: string | number | null, method: string, path: string} | null} - Request message when matched.
  */
 function requestMessage(message) {
   if (message.type && message.type !== "request") return null
 
-  return /** @type {{type?: "request", body?: ?, headers?: Record<string, ?>, id?: string | number | null, method: string, path: string}} */ (message)
+  return /** @type {{type?: "request", body?: ReturnType<typeof JSON.parse>, headers?: Record<string, ReturnType<typeof JSON.parse>>, id?: string | number | null, method: string, path: string}} */ (message)
 }
 
 /**
@@ -84,8 +84,8 @@ function requestMessage(message) {
  * Nullish values compare equal to each other but not to a real identity.
  * Plain objects are compared via JSON round-trip so apps can return a
  * `{userId, tenantId}`-style object without building their own equality.
- * @param {?} a - Paused-time identity.
- * @param {?} b - Resume-time identity.
+ * @param {ReturnType<typeof JSON.parse>} a - Paused-time identity.
+ * @param {ReturnType<typeof JSON.parse>} b - Resume-time identity.
  * @returns {boolean} - True when the two identities are considered the same caller.
  */
 function identitiesMatch(a, b) {
@@ -148,14 +148,14 @@ export default class VelociousHttpServerClientWebsocketSession {
 
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Record<string, ?>} */
+     * @type {Record<string, ReturnType<typeof JSON.parse>>} */
     this._metadata = {}
 
     /**
      * Long-lived per-session state bag. Stable across reconnects once
      * grace-period resumption lands in Phase 2; today it just lives
      * for the duration of the underlying socket.
-     * @type {Record<string, ?>}
+     * @type {Record<string, ReturnType<typeof JSON.parse>>}
      */
     this.data = {}
 
@@ -186,7 +186,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Array<?>} - frames produced while paused; flushed on resume.
+     * @type {Array<ReturnType<typeof JSON.parse>>} - frames produced while paused; flushed on resume.
      */
     this._outboundQueue = []
 
@@ -210,7 +210,7 @@ export default class VelociousHttpServerClientWebsocketSession {
      * time by `getWebsocketSessionIdentityResolver`. Awaited at resume
      * time to compare against the fresh caller's identity. Undefined
      * on a live (non-paused) session.
-     * @type {Promise<?> | undefined}
+     * @type {Promise<ReturnType<typeof JSON.parse>> | undefined}
      */
     this._resumeIdentityPromise = undefined
 
@@ -288,7 +288,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
   /**
    * Runs get metadata.
-   * @returns {Record<string, ?>} - Client-provided metadata (defensive copy).
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Client-provided metadata (defensive copy).
    */
   getMetadata() {
     return {...this._metadata}
@@ -354,7 +354,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   /**
    * Runs send event.
    * @param {string} channel - Channel name.
-   * @param {?} payload - Payload data.
+   * @param {ReturnType<typeof JSON.parse>} payload - Payload data.
    * @param {{createdAt?: string, eventId?: string, replayed?: boolean, sequence?: number}} [options] - Event metadata.
    * @returns {Promise<void>} - Resolves when complete.
    */
@@ -492,7 +492,7 @@ export default class VelociousHttpServerClientWebsocketSession {
     if (error instanceof ValidationError) return true
     if (error instanceof VelociousError && error.safeToExpose) return true
 
-    const annotatedError = /** @type {Error & {errorType?: string, velocious?: Record<string, ?>}} */ (error)
+    const annotatedError = /** @type {Error & {errorType?: string, velocious?: Record<string, ReturnType<typeof JSON.parse>>}} */ (error)
 
     if (isPlainObject(annotatedError.velocious)) return true
 
@@ -501,8 +501,8 @@ export default class VelociousHttpServerClientWebsocketSession {
 
   /**
    * Reports one unexpected WebSocket dispatch failure and returns its normalized Error.
-   * @param {?} caughtError - Caught dispatch failure.
-   * @param {Record<string, ?>} context - Structured dispatch context.
+   * @param {ReturnType<typeof JSON.parse>} caughtError - Caught dispatch failure.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} context - Structured dispatch context.
    * @returns {Error} - Normalized error for existing logs and client responses.
    */
   _reportUnexpectedDispatchError(caughtError, context) {
@@ -627,7 +627,7 @@ export default class VelociousHttpServerClientWebsocketSession {
     }
 
     if (message.type === "metadata") {
-      const metadataPayload = /** @type {{data?: Record<string, ?>}} */ (message)
+      const metadataPayload = /** @type {{data?: Record<string, ReturnType<typeof JSON.parse>>}} */ (message)
 
       this._metadata = metadataPayload.data && typeof metadataPayload.data === "object" ? {...metadataPayload.data} : {}
 
@@ -1253,7 +1253,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   /**
    * Runs subscribe to channel.
    * @param {string} channel - Channel name.
-   * @param {{acknowledge?: boolean, channelHandler?: import("../websocket-channel.js").default, lastEventId?: string, params?: Record<string, ?>, subscriptionChannel?: string}} [options] - Subscribe options.
+   * @param {{acknowledge?: boolean, channelHandler?: import("../websocket-channel.js").default, lastEventId?: string, params?: Record<string, ReturnType<typeof JSON.parse>>, subscriptionChannel?: string}} [options] - Subscribe options.
    * @returns {Promise<boolean>} - Whether the subscription was added.
    */
   async subscribeToChannel(channel, {acknowledge = true, channelHandler, lastEventId, params, subscriptionChannel} = {}) {
@@ -1368,7 +1368,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * The returned promise is stored at pause time and awaited at
    * resume time so we can reject resume attempts from a different
    * authenticated caller (signed out, swapped user, expired cookie).
-   * @returns {Promise<?>} - Captured authenticated identity for resume validation.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Captured authenticated identity for resume validation.
    */
   async _captureResumeIdentity() {
     const resolver = this.configuration.getWebsocketSessionIdentityResolver?.()
@@ -1447,7 +1447,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * created one whose socket just connected) transfers state from
    * the paused session and instructs the client via
    * `session-resumed` or `session-gone`.
-   * @param {Record<string, ?>} message - Session-resume frame containing the paused session identifier.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} message - Session-resume frame containing the paused session identifier.
    * @returns {Promise<void>}
    */
   async _handleSessionResume(message) {
@@ -1564,7 +1564,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * registered connection class, stores it on `_connections`, and
    * fires `onConnect()`. Sends `connection-opened` on success or
    * `connection-error` on failure.
-   * @param {Record<string, ?>} message - Connection-open frame naming the connection type and identifier.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} message - Connection-open frame naming the connection type and identifier.
    * @returns {Promise<void>}
    */
   async _handleConnectionOpen(message) {
@@ -1619,7 +1619,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
   /**
    * Handles a `{type: "connection-message"}` from the client.
-   * @param {Record<string, ?>} message - Connection-message frame containing the target identifier and body.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} message - Connection-message frame containing the target identifier and body.
    * @returns {Promise<void>}
    */
   async _handleConnectionMessage(message) {
@@ -1650,7 +1650,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   /**
    * Handles a `{type: "connection-close"}` from the client — fires
    * `onClose("client_close")` and confirms with `connection-closed`.
-   * @param {Record<string, ?>} message - Connection-close frame containing the target identifier.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} message - Connection-close frame containing the target identifier.
    * @returns {Promise<void>}
    */
   async _handleConnectionClose(message) {
@@ -1684,7 +1684,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * Handles `{type: "channel-subscribe"}` — runs `canSubscribe()`,
    * registers with the Configuration's global routing registry on
    * success, and sends `channel-subscribed` or `channel-error`.
-   * @param {Record<string, ?>} message - Channel-subscribe frame describing the requested subscription.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} message - Channel-subscribe frame describing the requested subscription.
    * @returns {Promise<void>}
    */
   async _handleChannelSubscribe(message) {
@@ -1817,7 +1817,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   /**
    * Handles `{type: "channel-unsubscribe"}` from the client — calls
    * `unsubscribed()` and sends `channel-unsubscribed`.
-   * @param {Record<string, ?>} message - Channel-unsubscribe frame containing the subscription identifier.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} message - Channel-unsubscribe frame containing the subscription identifier.
    * @returns {Promise<void>}
    */
   async _handleChannelUnsubscribe(message) {
@@ -1956,7 +1956,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
   /**
    * Runs handle channel subscription.
-   * @param {{channel: string, lastEventId?: string, params?: Record<string, ?>}} args - Subscription args.
+   * @param {{channel: string, lastEventId?: string, params?: Record<string, ReturnType<typeof JSON.parse>>}} args - Subscription args.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async _handleChannelSubscription({channel, lastEventId, params}) {
@@ -2020,7 +2020,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * @param {string} args.channel - Internal channel name.
    * @param {string | undefined} args.lastEventId - Last received event id.
    * @param {string} args.subscriptionChannel - Client-facing channel name.
-   * @param {Record<string, ?> | undefined} args.subscriptionParams - Client-facing params.
+   * @param {Record<string, ReturnType<typeof JSON.parse>> | undefined} args.subscriptionParams - Client-facing params.
    * @returns {Promise<false | {buffered: boolean, ceilingSequence: number, checkpointSequence: number, replaying: boolean} | null>} - Replay state.
    */
   async _prepareReplayState({channel, lastEventId, subscriptionChannel, subscriptionParams}) {
@@ -2097,7 +2097,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
   /**
    * Runs resolve tenant.
-   * @param {{channel?: string, params?: Record<string, ?>}} args - Tenant resolution args.
+   * @param {{channel?: string, params?: Record<string, ReturnType<typeof JSON.parse>>}} args - Tenant resolution args.
    * @returns {Promise<string | null | undefined>} - Resolved tenant.
    */
   async _resolveTenant({channel, params}) {

package/build/http-server/cookie.js

@@ -125,7 +125,7 @@ export default class Cookie {
 
   /**
    * Runs encrypt value.
-   * @param {?} value - Value to encrypt.
+   * @param {ReturnType<typeof JSON.parse>} value - Value to encrypt.
    * @param {string} secret - Encryption secret.
    * @returns {string} - Encrypted value.
    */
@@ -174,7 +174,7 @@ export default class Cookie {
 
   /**
    * Runs serialize encrypted value.
-   * @param {?} value - Value to serialize.
+   * @param {ReturnType<typeof JSON.parse>} value - Value to serialize.
    * @returns {{payload: string, type: string}} - Serialized payload.
    */
   static _serializeEncryptedValue(value) {

package/build/http-server/development-reloader.js

@@ -22,7 +22,7 @@ export default class VelociousHttpServerDevelopmentReloader {
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {import("../configuration.js").default} args.configuration - Configuration instance.
-   * @param {function({changedPath: string}) : Promise<void>} args.onReload - Reload callback.
+   * @param {(args: {changedPath: string}) => Promise<void>} args.onReload - Reload callback.
    * @param {number} [args.debounceMs] - Debounce window for grouped changes.
    * @param {typeof fsWatch} [args.watchFactory] - File watch factory.
    * @param {typeof fs.readdir} [args.readdir] - Directory reader.

package/build/http-server/index.js

@@ -14,7 +14,7 @@ import WorkerHandler from "./worker-handler/index.js"
  * @typedef {{start: () => Promise<void>, stop: () => Promise<void>}} DevelopmentReloaderLike */
 /**
  * Defines this typedef.
- * @typedef {function({configuration: import("../configuration.js").default, workerCount: number}) : (WorkerHandler | InProcessHandler)} WorkerHandlerFactory */
+ * @typedef {(args: {configuration: import("../configuration.js").default, workerCount: number}) => (WorkerHandler | InProcessHandler)} WorkerHandlerFactory */
 
 /**
  * Runs normalize worker count.
@@ -84,7 +84,7 @@ export default class VelociousHttpServer {
    * @param {number} [args.port] - Port.
    * @param {number} [args.maxWorkers] - Max workers.
    * @param {number} [args.workers] - Worker handlers to start.
-   * @param {function({configuration: import("../configuration.js").default, onReload: function({changedPath: string}) : Promise<void>}) : {start: () => Promise<void>, stop: () => Promise<void>}} [args.developmentReloaderFactory] - Development reloader factory.
+   * @param {(args: {configuration: import("../configuration.js").default, onReload: (args: {changedPath: string}) => Promise<void>}) => {start: () => Promise<void>, stop: () => Promise<void>}} [args.developmentReloaderFactory] - Development reloader factory.
    * @param {WorkerHandlerFactory} [args.workerHandlerFactory] - Worker handler factory.
    */
   constructor({configuration, developmentReloaderFactory, host, inProcess, maxWorkers, port, workerHandlerFactory, workers}) {
@@ -224,7 +224,7 @@ export default class VelociousHttpServer {
 
   /**
    * Runs get debug snapshot.
-   * @returns {Promise<Record<string, ?>>} - HTTP server worker diagnostics.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - HTTP server worker diagnostics.
    */
   async getDebugSnapshot() {
     return {
@@ -241,7 +241,7 @@ export default class VelociousHttpServer {
   /**
    * Runs worker debug snapshot.
    * @param {WorkerHandler | InProcessHandler} workerHandler - Worker handler to inspect.
-   * @returns {Promise<Record<string, ?>>} Worker debug snapshot.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} Worker debug snapshot.
    */
   async workerDebugSnapshot(workerHandler) {
     if (workerHandler instanceof WorkerHandler) return await workerHandler.getDebugSnapshot()
@@ -253,7 +253,7 @@ export default class VelociousHttpServer {
   /**
    * Runs in process worker debug snapshot.
    * @param {InProcessHandler} workerHandler - In-process worker handler to inspect.
-   * @returns {Record<string, ?>} Worker debug snapshot.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Worker debug snapshot.
    */
   inProcessWorkerDebugSnapshot(workerHandler) {
     return {

package/build/http-server/remote-address.js

@@ -63,7 +63,7 @@ export default function resolveRemoteAddress({configuration, headers, socketRemo
 
   if (!trust) return socketRemoteAddress
 
-  const proxyRequest = /** @type {Parameters<typeof proxyaddr>[0]} */ (/** @type {?} */ ({
+  const proxyRequest = /** @type {Parameters<typeof proxyaddr>[0]} */ (/** @type {ReturnType<typeof JSON.parse>} */ ({
     connection: {remoteAddress: socketRemoteAddress},
     headers: nodeStyleHeaders(headers),
     socket: {remoteAddress: socketRemoteAddress}

package/build/http-server/server-lock.js

@@ -108,7 +108,7 @@ export default class VelociousHttpServerLock {
 
   /**
    * Runs is local process owner.
-   * @param {Record<string, ?> | null} owner - Existing lock owner metadata.
+   * @param {Record<string, ReturnType<typeof JSON.parse>> | null} owner - Existing lock owner metadata.
    * @returns {boolean} - Whether owner metadata names a local process.
    */
   isLocalProcessOwner(owner) {
@@ -120,7 +120,7 @@ export default class VelociousHttpServerLock {
 
   /**
    * Runs owner hostname matches.
-   * @param {Record<string, ?>} owner - Existing lock owner metadata.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} owner - Existing lock owner metadata.
    * @returns {boolean} - Whether the owner hostname is local or absent.
    */
   ownerHostnameMatches(owner) {
@@ -147,13 +147,13 @@ export default class VelociousHttpServerLock {
 
   /**
    * Reads owner metadata from an existing server lock directory.
-   * @returns {Promise<Record<string, ?> | null>} - Parsed owner metadata, when readable.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>> | null>} - Parsed owner metadata, when readable.
    */
   async readOwnerMetadata() {
     try {
       const rawOwner = await fs.readFile(path.join(this.lockPath, "owner.json"), "utf8")
 
-      return /** @type {Record<string, ?>} */ (JSON.parse(rawOwner))
+      return /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (JSON.parse(rawOwner))
     } catch {
       return null
     }

package/build/http-server/websocket-channel-subscribers.js

@@ -13,14 +13,14 @@ export default class VelociousWebsocketChannelSubscribers {
   constructor() {
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Map<string, Set<(payload: ?, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>>>} */
+     * @type {Map<string, Set<(payload: ReturnType<typeof JSON.parse>, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>>>} */
     this._subscribers = new Map()
   }
 
   /**
    * Runs subscribe.
    * @param {string} channel - Channel name to subscribe to.
-   * @param {(payload: ?, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>} callback - Callback invoked for each event on the channel.
+   * @param {(payload: ReturnType<typeof JSON.parse>, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>} callback - Callback invoked for each event on the channel.
    * @returns {() => void} - Unsubscribe function.
    */
   subscribe(channel, callback) {
@@ -42,7 +42,7 @@ export default class VelociousWebsocketChannelSubscribers {
   /**
    * Runs unsubscribe.
    * @param {string} channel - Channel name.
-   * @param {(payload: ?, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>} callback - Previously registered callback.
+   * @param {(payload: ReturnType<typeof JSON.parse>, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>} callback - Previously registered callback.
    * @returns {void}
    */
   unsubscribe(channel, callback) {
@@ -72,7 +72,7 @@ export default class VelociousWebsocketChannelSubscribers {
    * Dispatch an event to all subscribers of the channel.
    * @param {object} args - Event args.
    * @param {string} args.channel - Channel name.
-   * @param {?} args.payload - Event payload.
+   * @param {ReturnType<typeof JSON.parse>} args.payload - Event payload.
    * @param {string} [args.createdAt] - Event creation time.
    * @param {string} [args.eventId] - Event identifier.
    * @returns {Promise<void>} - Resolves when all subscribers have completed.

package/build/http-server/websocket-channel.js

@@ -93,7 +93,7 @@ export default class VelociousWebsocketChannel {
   /**
    * Returns sanitized diagnostics for debug snapshots.
    * Subclasses can override to expose non-sensitive routing details.
-   * @returns {Record<string, ?>} Debug-safe subscription details.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Debug-safe subscription details.
    */
   debugSnapshot() { return {} }
 

package/build/http-server/websocket-connection.js

@@ -14,7 +14,7 @@ export default class VelociousWebsocketConnection {
    * Runs constructor.
    * @param {object} args - Owning session, connection parameters, and client identifier.
    * @param {string} args.connectionId - Client-assigned id, unique within the session.
-   * @param {Record<string, ?>} args.params - Opaque params from the `connection-open` message.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.params - Opaque params from the `connection-open` message.
    * @param {import("./client/websocket-session.js").default} args.session - Owning session.
    */
   constructor({connectionId, params, session}) {
@@ -36,7 +36,7 @@ export default class VelociousWebsocketConnection {
    * Called for each `connection-message` the client sends to this
    * specific connection. Messages arriving before `onConnect` has
    * resolved are queued and delivered in order once it finishes.
-   * @param {?} body - Client-sent payload for this connection.
+   * @param {ReturnType<typeof JSON.parse>} body - Client-sent payload for this connection.
    * @returns {void | Promise<void>} - Completes after message handling.
    */
   onMessage(body) { void body }
@@ -72,7 +72,7 @@ export default class VelociousWebsocketConnection {
   /**
    * Sends a `connection-message` frame to the client side of this
    * connection. Throws if the connection has already been closed.
-   * @param {?} body - Connection payload to send to the client.
+   * @param {ReturnType<typeof JSON.parse>} body - Connection payload to send to the client.
    * @returns {void}
    */
   sendMessage(body) {

package/build/http-server/websocket-event-log-store.js

@@ -112,8 +112,8 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * Runs append event.
    * @param {object} args - Options.
    * @param {string} args.channel - Channel name.
-   * @param {?} args.payload - Event payload.
-   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ?}>} - Persisted event row.
+   * @param {ReturnType<typeof JSON.parse>} args.payload - Event payload.
+   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>}>} - Persisted event row.
    */
   async appendEvent({channel, payload}) {
     await this.ensureReady()
@@ -197,7 +197,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * @param {object} args - Options.
    * @param {string} args.channel - Channel name.
    * @param {string} args.id - Event id.
-   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ?, sequence: number} | null>} - Event row or null.
+   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>, sequence: number} | null>} - Event row or null.
    */
   async getEventById({channel, id}) {
     await this.ensureReady()
@@ -223,7 +223,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
         .order("sequence DESC")
         .limit(1)
         .results()
-      const row = /** @type {Record<string, ?> | undefined} */ (rows[0])
+      const row = /** @type {Record<string, ReturnType<typeof JSON.parse>> | undefined} */ (rows[0])
 
       if (!row) return null
 
@@ -237,7 +237,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * @param {string} args.channel - Channel name.
    * @param {number} args.sequence - Lower bound sequence.
    * @param {number | null | undefined} [args.upToSequence] - Inclusive ceiling sequence.
-   * @returns {Promise<Array<{channel: string, createdAt: string, id: string, payload: ?, sequence: number}>>} - Ordered events.
+   * @returns {Promise<Array<{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>, sequence: number}>>} - Ordered events.
    */
   async getEventsAfter({channel, sequence, upToSequence}) {
     await this.ensureReady()
@@ -352,7 +352,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * @param {string} args.channel - Channel name.
    * @param {import("../database/drivers/base.js").default} args.db - Database connection.
    * @param {string} args.id - Event id.
-   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ?, sequence: number} | null>} - Event row or null.
+   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>, sequence: number} | null>} - Event row or null.
    */
   async _getEventById({channel, db, id}) {
     const rows = /** @type {WebsocketEventRow[]} */ (await db
@@ -370,7 +370,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
   /**
    * Runs normalize event row.
    * @param {WebsocketEventRow} row - Raw row.
-   * @returns {{channel: string, createdAt: string, id: string, payload: ?, sequence: number}} - Normalized row.
+   * @returns {{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>, sequence: number}} - Normalized row.
    */
   _normalizeEventRow(row) {
     const createdAtValue = row.created_at
@@ -406,8 +406,8 @@ export default class VelociousHttpServerWebsocketEventLogStore {
 
   /**
    * Runs with db.
-   * @param {(db: import("../database/drivers/base.js").default) => Promise<?>} callback - Callback.
-   * @returns {Promise<?>} - Callback result.
+   * @param {(db: import("../database/drivers/base.js").default) => Promise<ReturnType<typeof JSON.parse>>} callback - Callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Callback result.
    */
   async _withDb(callback) {
     return await this.configuration.ensureConnections({databaseIdentifiers: [this.databaseIdentifier], name: "Websocket event log store"}, async (dbs) => {

package/build/http-server/websocket-events-host.js

@@ -69,13 +69,13 @@ export class VelociousHttpServerWebsocketEventsHost {
   /**
    * Runs publish.
    * @param {object | string} channelOrArgs - Channel name or options object.
-   * @param {?} [payloadArg] - Payload data when channel is passed separately.
+   * @param {ReturnType<typeof JSON.parse>} [payloadArg] - Payload data when channel is passed separately.
    * @returns {void} - No return value.
    */
   publish(channelOrArgs, payloadArg) {
     const publishArgs = typeof channelOrArgs === "string"
       ? {channel: channelOrArgs, payload: payloadArg}
-      : /** @type {{channel: string, payload: ?}} */ (channelOrArgs)
+      : /** @type {{channel: string, payload: ReturnType<typeof JSON.parse>}} */ (channelOrArgs)
     const channel = publishArgs.channel
     const payload = publishArgs.payload
 
@@ -103,8 +103,8 @@ export class VelociousHttpServerWebsocketEventsHost {
    * interested) so clients can resume from a `lastEventId` checkpoint.
    * @param {object} args - Options object.
    * @param {string} args.channel - Channel name.
-   * @param {Record<string, ?>} args.broadcastParams - Routing filter params.
-   * @param {?} args.body - Message body.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.broadcastParams - Routing filter params.
+   * @param {ReturnType<typeof JSON.parse>} args.body - Message body.
    * @param {import("../configuration.js").default} args.configuration - Originating configuration.
    * @returns {void}
    */
@@ -188,7 +188,7 @@ export class VelociousHttpServerWebsocketEventsHost {
   /**
    * Runs persist v2 event if needed.
    * @param {object} args - Options.
-   * @param {?} args.body - Event body.
+   * @param {ReturnType<typeof JSON.parse>} args.body - Event body.
    * @param {string} args.channel - Channel name.
    * @param {import("../configuration.js").default} args.configuration - Originating configuration.
    * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata when storage is enabled.
@@ -201,7 +201,7 @@ export class VelociousHttpServerWebsocketEventsHost {
    * Runs persist event if needed.
    * @param {object} args - Options object.
    * @param {string} args.channel - Channel name.
-   * @param {?} args.payload - Payload data.
+   * @param {ReturnType<typeof JSON.parse>} args.payload - Payload data.
    * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata.
    */
   async _persistEventIfNeeded({channel, payload}) {
@@ -212,7 +212,7 @@ export class VelociousHttpServerWebsocketEventsHost {
    * Runs persist channel event if needed.
    * @param {object} args - Options object.
    * @param {string} args.channel - Channel name.
-   * @param {?} args.payload - Payload data.
+   * @param {ReturnType<typeof JSON.parse>} args.payload - Payload data.
    * @param {import("../configuration.js").default} [args.configuration] - Configuration owning the event store.
    * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata.
    */

package/build/http-server/websocket-events.js

@@ -4,7 +4,7 @@ export default class VelociousHttpServerWebsocketEvents {
   /**
    * Runs constructor.
    * @param {object} args - Options object.
-   * @param {import("worker_threads").parentPort} args.parentPort - Parent port.
+   * @param {import("node:worker_threads").MessagePort | null} args.parentPort - Parent port.
    * @param {number} args.workerCount - Worker count.
    */
   constructor({parentPort, workerCount}) {
@@ -15,7 +15,7 @@ export default class VelociousHttpServerWebsocketEvents {
   /**
    * Runs publish.
    * @param {string} channel - Channel name.
-   * @param {?} payload - Payload data.
+   * @param {ReturnType<typeof JSON.parse>} payload - Payload data.
    * @returns {void} - No return value.
    */
   publish(channel, payload) {
@@ -31,8 +31,8 @@ export default class VelociousHttpServerWebsocketEvents {
    * every worker so subscribers on any worker receive the broadcast.
    * @param {object} args - Options object.
    * @param {string} args.channel - Channel name.
-   * @param {Record<string, ?>} args.broadcastParams - Filter params forwarded to `matches()`.
-   * @param {?} args.body - Message body delivered via `sendMessage()`.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.broadcastParams - Filter params forwarded to `matches()`.
+   * @param {ReturnType<typeof JSON.parse>} args.body - Message body delivered via `sendMessage()`.
    * @returns {void}
    */
   publishV2Broadcast({channel, broadcastParams, body}) {

package/build/http-server/worker-handler/channel-subscriber-dispatch.js

@@ -8,7 +8,7 @@
  * @param {string | undefined} args.eventId - Event identifier.
  * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
  * @param {import("../../logger.js").default} args.logger - Logger for isolated subscriber failures.
- * @param {?} args.payload - Broadcast payload.
+ * @param {ReturnType<typeof JSON.parse>} args.payload - Broadcast payload.
  * @returns {Promise<void>} Resolves after subscribers have been attempted.
  */
 export default async function dispatchChannelSubscribers({channel, configuration, createdAt, eventId, logger, payload}) {

package/build/http-server/worker-handler/in-process.js

@@ -32,7 +32,7 @@ export default class VelociousHttpServerInProcessHandler {
 
     this.logger = new Logger(this)
     this.workerCount = workerCount
-    this.unregisterFromEventsHost = websocketEventsHost.register(/** @type {?} */ (this))
+    this.unregisterFromEventsHost = websocketEventsHost.register(/** @type {ReturnType<typeof JSON.parse>} */ (this))
     this._stopping = false
   }
 
@@ -117,7 +117,7 @@ export default class VelociousHttpServerInProcessHandler {
 
     // Create a message-port shim so ServerClient.onSocketData can route data
     // to the in-process HTTP Client without needing a real worker thread.
-    const messagePortShim = /** @type {import("worker_threads").Worker} */ (/** @type {?} */ ({
+    const messagePortShim = /** @type {import("worker_threads").Worker} */ (/** @type {ReturnType<typeof JSON.parse>} */ ({
       postMessage: (/** @type {{command: string, chunk?: Buffer | Uint8Array | string, clientCount?: number}} */ data) => {
         if (data.command === "clientWrite" && data.chunk) {
           const chunk = typeof data.chunk === "string" ? Buffer.from(data.chunk) : Buffer.from(data.chunk)
@@ -178,8 +178,8 @@ export default class VelociousHttpServerInProcessHandler {
    * subscriptions on the shared configuration.
    * @param {object} args - Options object.
    * @param {string} args.channel - Channel name.
-   * @param {Record<string, ?>} args.broadcastParams - Routing filter params.
-   * @param {?} args.body - Message body.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.broadcastParams - Routing filter params.
+   * @param {ReturnType<typeof JSON.parse>} args.body - Message body.
    * @param {string} [args.eventId] - Persisted event id for replay.
    * @returns {void}
    */
@@ -203,7 +203,7 @@ export default class VelociousHttpServerInProcessHandler {
    * @param {string} args.channel - Channel name.
    * @param {string} [args.createdAt] - Event creation time.
    * @param {string} [args.eventId] - Event identifier.
-   * @param {?} args.payload - Payload data.
+   * @param {ReturnType<typeof JSON.parse>} args.payload - Payload data.
    * @returns {void}
    */
   dispatchWebsocketEvent({channel, createdAt, eventId, payload}) {