velocious 1.0.552 → 1.0.555

package/src/frontend-models/base.js

@@ -9,6 +9,7 @@ import {normalizeDateStringForWrite} from "../database/datetime-storage.js"
 import {registerFrontendModel, resolveFrontendModelClass} from "./model-registry.js"
 import {validateFrontendModelResourceCommandName, validateFrontendModelResourcePath} from "./resource-config-validation.js"
 import {deserializeFrontendModelTransportValue, serializeFrontendModelTransportValue} from "./transport-serialization.js"
+import runWithTransportDeadline from "./transport-deadline.js"
 import {REQUEST_TIME_ZONE_HEADER, validateTimeZone} from "../time-zone.js"
 import VelociousWebsocketClient from "../http-client/websocket-client.js"
 import {bufferOutgoingEvent, drainBufferedOutgoingEvents} from "./outgoing-event-buffer.js"
@@ -112,8 +113,10 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * @property {string | (() => string | undefined | null)} [url] - Optional frontend-model URL. This should be the shared endpoint (for example `"/frontend-models"` or `"https://example.com/frontend-models"`).
  * @property {boolean} [shared] - Deprecated shared-endpoint flag retained for compatibility. Frontend-model CRUD/custom commands use the shared frontend-model API envelope by default.
  * @property {string | (() => string | undefined | null)} [websocketUrl] - Optional websocket URL. When set, Velocious creates and manages its own websocket client internally. Subscriptions use the websocket; CRUD uses HTTP and falls back gracefully. Example: `"ws://localhost:3006/websocket"`.
- * @property {{post: (path: string, body?: ?, options?: {headers?: Record<string, string>}) => Promise<{json: () => ?}>, subscribe: (channel: string, options: {params?: Record<string, ?>}, callback: (payload: ?) => void) => (() => void), subscribeAndWait?: (channel: string, options: {params?: Record<string, ?>}, callback: (payload: ?) => void) => Promise<(() => void)>}} [websocketClient] - Optional websocket client for shared frontend-model API requests and subscriptions.
+ * @property {{post: (path: string, body?: ?, options?: {headers?: Record<string, string>, signal?: AbortSignal}) => Promise<{json: () => ?}>, subscribe: (channel: string, options: {params?: Record<string, ?>}, callback: (payload: ?) => void) => (() => void), subscribeAndWait?: (channel: string, options: {params?: Record<string, ?>}, callback: (payload: ?) => void) => Promise<(() => void)>}} [websocketClient] - Optional websocket client for shared frontend-model API requests and subscriptions. Its `post` receives the bounded-deadline `signal` and should forward it into the underlying transport so the deadline can abort the live request and its response-body read.
  * @property {Record<string, string> | (() => Record<string, string>)} [requestHeaders] - Extra HTTP/WS headers to attach to every frontend-model API request. Pass a function to compute them at request time (for example to include the current locale).
+ * @property {number | (() => number | undefined | null)} [timeout] - Bounded deadline in milliseconds covering connection, response headers, and response-body consumption for each frontend-model API request. On expiry the live fetch/adapter request is aborted (built on awaitery's `timeout`) and awaitery's `TimeoutError` is thrown, so callers can classify a timeout via `error instanceof TimeoutError`. Pass a function to resolve it per request. Falsy/absent means no deadline.
+ * @property {AbortSignal | (() => AbortSignal | undefined | null)} [signal] - Optional caller/session AbortSignal composed with the deadline. Aborting it cancels the live request (for example on session shutdown or offline transition); the resulting abort error stays distinguishable from a timeout. Pass a function to resolve the current signal per request.
  * @property {{get: () => string | null | undefined | Promise<string | null | undefined>, set: (sessionId: string) => void | Promise<void>, clear: () => void | Promise<void>}} [sessionStore] - Optional sessionId persistence hook forwarded to the internal `VelociousWebsocketClient` so WS sessions can be resumed across page reloads / app restarts.
  * @property {string | (() => string | null | undefined)} [timeZone] - IANA timezone sent with every frontend-model API request for timezone-less datetime parsing.
  * @property {{actorDeviceId: string, actorUserId: string, clientMutationId?: () => string, enabled?: boolean, mutationLog: import("../sync/local-mutation-log.js").default, now?: () => Date, offlineGrant: {id: string}}} [offlineSync] - Offline mutation queue configuration.
@@ -1753,6 +1756,34 @@ function frontendModelRequestHeaders(timeZone = frontendModelTransportTimeZone()
   return headers
 }
 
+/**
+ * Resolves the configured bounded transport deadline in milliseconds.
+ * @returns {number | undefined} - Configured deadline, or undefined when no deadline is set.
+ */
+function frontendModelTransportTimeoutMs() {
+  const configuredTimeout = typeof frontendModelTransportConfig.timeout === "function"
+    ? frontendModelTransportConfig.timeout()
+    : frontendModelTransportConfig.timeout
+
+  if (typeof configuredTimeout !== "number" || !(configuredTimeout > 0)) {
+    return undefined
+  }
+
+  return configuredTimeout
+}
+
+/**
+ * Resolves the configured caller/session AbortSignal composed with the deadline.
+ * @returns {AbortSignal | undefined} - Configured caller signal, or undefined when none is set.
+ */
+function frontendModelTransportSignal() {
+  const configuredSignal = typeof frontendModelTransportConfig.signal === "function"
+    ? frontendModelTransportConfig.signal()
+    : frontendModelTransportConfig.signal
+
+  return configuredSignal || undefined
+}
+
 /**
  * Runs perform shared frontend model api request.
  * @param {Record<string, ?>} requestPayload - Shared request payload.
@@ -1765,35 +1796,46 @@ async function performSharedFrontendModelApiRequest(requestPayload) {
   const url = frontendModelApiUrl()
   const mergedHeaders = frontendModelRequestHeaders(timeZone)
 
-  if (websocketClient) {
-    const response = await websocketClient.post(frontendModelTransportPath(url), serializedRequestPayload, {
-      headers: mergedHeaders
-    })
-    const responseJson = response.json()
+  return await runWithTransportDeadline(
+    {
+      errorMessage: "Shared frontend model API request timed out",
+      signal: frontendModelTransportSignal(),
+      timeoutMs: frontendModelTransportTimeoutMs()
+    },
+    async (signal) => {
+      if (websocketClient) {
+        const response = await websocketClient.post(frontendModelTransportPath(url), serializedRequestPayload, {
+          headers: mergedHeaders,
+          signal
+        })
+        const responseJson = response.json()
 
-    return /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(responseJson))
-  }
+        return /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(responseJson))
+      }
 
-  const response = await fetch(url, {
-    body: JSON.stringify(serializedRequestPayload),
-    credentials: "include",
-    headers: mergedHeaders,
-    method: "POST"
-  })
+      const response = await fetch(url, {
+        body: JSON.stringify(serializedRequestPayload),
+        credentials: "include",
+        headers: mergedHeaders,
+        method: "POST",
+        signal
+      })
 
-  const responseText = await response.text()
+      const responseText = await response.text()
 
-  if (!response.ok) {
-    throwFrontendModelHttpError({
-      commandLabel: "shared frontend model API",
-      response,
-      responseText
-    })
-  }
+      if (!response.ok) {
+        throwFrontendModelHttpError({
+          commandLabel: "shared frontend model API",
+          response,
+          responseText
+        })
+      }
 
-  const json = responseText.length > 0 ? JSON.parse(responseText) : {}
+      const json = responseText.length > 0 ? JSON.parse(responseText) : {}
 
-  return /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(json))
+      return /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(json))
+    }
+  )
 }
 
 /**
@@ -2862,6 +2904,14 @@ export default class FrontendModelBase {
       frontendModelTransportConfig.requestHeaders = config.requestHeaders
     }
 
+    if (Object.prototype.hasOwnProperty.call(config, "timeout")) {
+      frontendModelTransportConfig.timeout = config.timeout
+    }
+
+    if (Object.prototype.hasOwnProperty.call(config, "signal")) {
+      frontendModelTransportConfig.signal = config.signal
+    }
+
     if (Object.prototype.hasOwnProperty.call(config, "timeZone")) {
       if (config.timeZone === undefined) {
         delete frontendModelTransportConfig.timeZone
@@ -4428,34 +4478,42 @@ export default class FrontendModelBase {
       return decodedBatchResponse
     }
 
-    return await trackFrontendModelTransportRequest(async () => {
-      const directResponse = await fetch(url, {
-        body: JSON.stringify(serializedPayload),
-        credentials: "include",
-        headers: frontendModelRequestHeaders(timeZone),
-        method: "POST"
-      })
+    return await trackFrontendModelTransportRequest(async () => runWithTransportDeadline(
+      {
+        errorMessage: `${this.name}#${commandType} request timed out`,
+        signal: frontendModelTransportSignal(),
+        timeoutMs: frontendModelTransportTimeoutMs()
+      },
+      async (signal) => {
+        const directResponse = await fetch(url, {
+          body: JSON.stringify(serializedPayload),
+          credentials: "include",
+          headers: frontendModelRequestHeaders(timeZone),
+          method: "POST",
+          signal
+        })
 
-      const directResponseText = await directResponse.text()
+        const directResponseText = await directResponse.text()
 
-      if (!directResponse.ok) {
-        throwFrontendModelHttpError({
-          commandLabel: `${this.name}#${commandType}`,
-          response: directResponse,
-          responseText: directResponseText
-        })
-      }
+        if (!directResponse.ok) {
+          throwFrontendModelHttpError({
+            commandLabel: `${this.name}#${commandType}`,
+            response: directResponse,
+            responseText: directResponseText
+          })
+        }
 
-      const directJson = directResponseText.length > 0 ? JSON.parse(directResponseText) : {}
-      const decodedDirectResponse = /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(directJson))
+        const directJson = directResponseText.length > 0 ? JSON.parse(directResponseText) : {}
+        const decodedDirectResponse = /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(directJson))
 
-      this.throwOnErrorFrontendModelResponse({
-        commandType,
-        response: decodedDirectResponse
-      })
+        this.throwOnErrorFrontendModelResponse({
+          commandType,
+          response: decodedDirectResponse
+        })
 
-      return decodedDirectResponse
-    })
+        return decodedDirectResponse
+      }
+    ))
   }
 
   /**

package/src/frontend-models/transport-deadline.js

@@ -0,0 +1,66 @@
+// @ts-check
+
+import timeout from "awaitery/build/timeout.js"
+
+/**
+ * Runs an async transport operation under a bounded deadline built on awaitery's
+ * `timeout`, which owns the timer, the stable `TimeoutError`, and the timer
+ * cleanup. awaitery's deadline `AbortSignal` is handed to `operation` (composed
+ * with an optional caller/session signal) so the live request — and its
+ * response-body read — is actually aborted when the deadline expires, not merely
+ * left racing a wrapper promise.
+ *
+ * A deadline expiry rejects with awaitery's `TimeoutError`
+ * (`import {TimeoutError} from "awaitery/build/timeout.js"`), so callers can
+ * classify a timeout without parsing browser/network error text. A caller abort
+ * rejects with the caller's own reason, keeping the two distinguishable. Both the
+ * awaitery timer and the composed abort listeners are always cleaned up. With no
+ * positive `timeoutMs` the operation runs directly under the caller signal (or no
+ * signal) and no timer is armed.
+ * @template T
+ * @param {{timeoutMs?: number | null, signal?: AbortSignal | null, errorMessage?: string}} options - Deadline options.
+ * @param {(signal: AbortSignal) => Promise<T>} operation - Transport operation receiving the composed signal.
+ * @returns {Promise<T>} - The operation result.
+ */
+export default async function runWithTransportDeadline({timeoutMs, signal, errorMessage}, operation) {
+  if (!(typeof timeoutMs === "number" && timeoutMs > 0)) {
+    // No deadline: run under the caller signal if provided, else a never-aborting signal.
+    return await operation(signal || new AbortController().signal)
+  }
+
+  return await timeout({errorMessage: errorMessage || "Transport request timed out", timeout: timeoutMs}, async ({control}) => {
+    if (!signal) {
+      return await operation(control.signal)
+    }
+
+    // A caller that has already cancelled must not start a live request.
+    if (signal.aborted) {
+      throw signal.reason instanceof Error ? signal.reason : new Error("Transport request aborted")
+    }
+
+    // Compose the caller/session signal with awaitery's deadline signal: either
+    // one aborts the live operation, and the composed listeners are always removed.
+    const callerSignal = signal
+    const composed = new AbortController()
+    /**
+     * Aborts the composed operation when the deadline signal fires.
+     * @returns {void} - No return value.
+     */
+    const onDeadlineAbort = () => composed.abort(control.signal.reason)
+    /**
+     * Aborts the composed operation when the caller signal fires.
+     * @returns {void} - No return value.
+     */
+    const onCallerAbort = () => composed.abort(callerSignal.reason)
+
+    control.signal.addEventListener("abort", onDeadlineAbort)
+    callerSignal.addEventListener("abort", onCallerAbort)
+
+    try {
+      return await operation(composed.signal)
+    } finally {
+      control.signal.removeEventListener("abort", onDeadlineAbort)
+      callerSignal.removeEventListener("abort", onCallerAbort)
+    }
+  })
+}

package/src/testing/factory/association-declaration.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+import {InvalidDefinitionError} from "./errors.js"
+
+/**
+ * A declared association. It records the relationship name, the factory to run
+ * (defaulting to the relationship name), any traits/overrides passed to that
+ * factory, and an optional explicit strategy. When no strategy is given the
+ * association follows the parent strategy at evaluation time.
+ */
+export default class AssociationDeclaration {
+  /**
+   * Builds an association declaration.
+   * @param {object} args - Options.
+   * @param {string} args.name - Relationship name on the owning model.
+   * @param {string} [args.factory] - Factory name to run. Defaults to the relationship name.
+   * @param {string[]} [args.traits] - Traits passed to the association factory.
+   * @param {Record<string, ?>} [args.overrides] - Overrides passed to the association factory.
+   * @param {"build" | "create" | undefined} [args.strategy] - Explicit strategy override.
+   */
+  constructor({name, factory, traits = [], overrides = {}, strategy}) {
+    if (!name || typeof name !== "string") {
+      throw new InvalidDefinitionError(`Association name must be a non-empty string, got: ${String(name)}`)
+    }
+
+    if (strategy !== undefined && strategy !== "build" && strategy !== "create") {
+      throw new InvalidDefinitionError(`Association strategy must be "build" or "create", got: ${String(strategy)}`)
+    }
+
+    /** @type {"association"} - Discriminant. */
+    this.kind = "association"
+
+    /** @type {string} - Relationship name on the owning model. */
+    this.name = name
+
+    /** @type {string} - Factory name to run for the association. */
+    this.factory = factory || name
+
+    /** @type {string[]} - Traits passed to the association factory. */
+    this.traits = traits
+
+    /** @type {Record<string, ?>} - Overrides passed to the association factory. */
+    this.overrides = overrides
+
+    /** @type {"build" | "create" | undefined} - Explicit strategy override. */
+    this.strategy = strategy
+
+    Object.freeze(this)
+  }
+}

package/src/testing/factory/declarations.js

@@ -0,0 +1,110 @@
+// @ts-check
+
+/**
+ * A literal or lazy attribute (or transient) declaration. A function value is the
+ * lazy form and receives the evaluator context; any other value is a literal.
+ * @typedef {object} AttributeDeclaration
+ * @property {"attribute"} kind - Discriminant.
+ * @property {string} name - Attribute name.
+ * @property {boolean} isTransient - Whether the value is transient (never assigned/returned).
+ * @property {?} value - Literal value or lazy `(context) => value` function.
+ */
+
+/**
+ * A lifecycle callback declaration. The same declaration object reached through
+ * multiple trait paths runs once per record (dedup is by object identity).
+ * @typedef {object} CallbackDeclaration
+ * @property {"callback"} kind - Discriminant.
+ * @property {string} event - One of the supported callback events.
+ * @property {(args: {record: ?, context: ?, strategy: string}) => (void | Promise<void>)} fn - Callback body.
+ */
+
+/**
+ * A base-trait inclusion declaration (a trait applied by default within a factory
+ * or composed inside another trait).
+ * @typedef {object} TraitIncludeDeclaration
+ * @property {"traitInclude"} kind - Discriminant.
+ * @property {string} name - Referenced trait name.
+ */
+
+/**
+ * A custom-constructor declaration.
+ * @typedef {object} InitializeWithDeclaration
+ * @property {"initializeWith"} kind - Discriminant.
+ * @property {(args: {attributes: Record<string, ?>, context: ?, get: (name: string) => ?}) => (? | Promise<?>)} fn - Constructor body.
+ */
+
+/**
+ * A custom-persistence declaration.
+ * @typedef {object} ToCreateDeclaration
+ * @property {"toCreate"} kind - Discriminant.
+ * @property {(args: {record: ?, context: ?}) => (void | Promise<void>)} fn - Persistence body.
+ */
+
+/**
+ * A declaration that disables persistence entirely for the create strategy.
+ * @typedef {object} SkipCreateDeclaration
+ * @property {"skipCreate"} kind - Discriminant.
+ */
+
+/**
+ * Union of every declaration kind stored on a factory/trait definition. Includes
+ * association declarations imported from their own module.
+ * @typedef {AttributeDeclaration | CallbackDeclaration | TraitIncludeDeclaration | InitializeWithDeclaration | ToCreateDeclaration | SkipCreateDeclaration | import("./association-declaration.js").default} Declaration
+ */
+
+/**
+ * Creates a literal/lazy attribute declaration.
+ * @param {string} name - Attribute name.
+ * @param {?} value - Literal value or lazy function.
+ * @param {boolean} isTransient - Whether the declaration is transient.
+ * @returns {AttributeDeclaration} - The frozen declaration.
+ */
+export function attributeDeclaration(name, value, isTransient) {
+  return Object.freeze({kind: "attribute", name, isTransient, value})
+}
+
+/**
+ * Creates a lifecycle callback declaration.
+ * @param {string} event - Callback event name.
+ * @param {CallbackDeclaration["fn"]} fn - Callback body.
+ * @returns {CallbackDeclaration} - The frozen declaration.
+ */
+export function callbackDeclaration(event, fn) {
+  return Object.freeze({kind: "callback", event, fn})
+}
+
+/**
+ * Creates a base-trait inclusion declaration.
+ * @param {string} name - Referenced trait name.
+ * @returns {TraitIncludeDeclaration} - The frozen declaration.
+ */
+export function traitIncludeDeclaration(name) {
+  return Object.freeze({kind: "traitInclude", name})
+}
+
+/**
+ * Creates a custom-constructor declaration.
+ * @param {InitializeWithDeclaration["fn"]} fn - Constructor body.
+ * @returns {InitializeWithDeclaration} - The frozen declaration.
+ */
+export function initializeWithDeclaration(fn) {
+  return Object.freeze({kind: "initializeWith", fn})
+}
+
+/**
+ * Creates a custom-persistence declaration.
+ * @param {ToCreateDeclaration["fn"]} fn - Persistence body.
+ * @returns {ToCreateDeclaration} - The frozen declaration.
+ */
+export function toCreateDeclaration(fn) {
+  return Object.freeze({kind: "toCreate", fn})
+}
+
+/**
+ * Creates a skip-create declaration.
+ * @returns {SkipCreateDeclaration} - The frozen declaration.
+ */
+export function skipCreateDeclaration() {
+  return Object.freeze({kind: "skipCreate"})
+}