velocious 1.0.470 → 1.0.471

package/build/environment-handlers/node.js

@@ -32,10 +32,11 @@ import path from "path"
 import {AsyncLocalStorage as NodeAsyncLocalStorage} from "node:async_hooks"
 import {timingSafeEqual} from "node:crypto"
 import toImportSpecifier from "../utils/to-import-specifier.js"
+import {validateTimeZone} from "../time-zone.js"
 
 /**
  * Defines this typedef.
- * @typedef {{ability?: import("../authorization/ability.js").default, offsetMinutes: number, requestTiming?: import("../http-server/client/request-timing.js").default, tenant?: ?}} TimezoneStore */
+ * @typedef {{ability?: import("../authorization/ability.js").default, offsetMinutes: number, requestTiming?: import("../http-server/client/request-timing.js").default, tenant?: ?, timeZone?: string}} TimezoneStore */
 
 /**
  * Runs path within allowed prefixes.
@@ -217,7 +218,30 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       ability: existingStore?.ability,
       offsetMinutes,
       requestTiming: existingStore?.requestTiming,
-      tenant: existingStore?.tenant
+      tenant: existingStore?.tenant,
+      timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
+    }, callback)
+  }
+
+  /**
+   * Runs run with timezone.
+   * @param {string} timeZone - IANA timezone identifier.
+   * @param {() => Promise<?>} callback - Callback to run.
+   * @returns {Promise<?>} - Result of the callback.
+   */
+  async runWithTimezone(timeZone, callback) {
+    if (!this._timezoneAsyncLocalStorage) {
+      return await super.runWithTimezone(timeZone, callback)
+    }
+
+    const existingStore = this._timezoneAsyncLocalStorage.getStore()
+
+    return await this._timezoneAsyncLocalStorage.run({
+      ability: existingStore?.ability,
+      offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
+      requestTiming: existingStore?.requestTiming,
+      tenant: existingStore?.tenant,
+      timeZone: validateTimeZone(timeZone, "timeZone")
     }, callback)
   }
 
@@ -240,7 +264,37 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         ability: existingStore?.ability,
         offsetMinutes,
         requestTiming: existingStore?.requestTiming,
-        tenant: existingStore?.tenant
+        tenant: existingStore?.tenant,
+        timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
+      })
+    }
+  }
+
+  /**
+   * Runs set timezone.
+   * @param {string} timeZone - IANA timezone identifier.
+   * @returns {void} - No return value.
+   */
+  setTimezone(timeZone) {
+    if (!this._timezoneAsyncLocalStorage) {
+      super.setTimezone(timeZone)
+      return
+    }
+
+    const normalizedTimeZone = validateTimeZone(timeZone, "timeZone")
+    const store = this._timezoneAsyncLocalStorage.getStore()
+
+    if (store) {
+      store.timeZone = normalizedTimeZone
+    } else {
+      const existingStore = this._timezoneAsyncLocalStorage.getStore()
+
+      this._timezoneAsyncLocalStorage.enterWith({
+        ability: existingStore?.ability,
+        offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
+        requestTiming: existingStore?.requestTiming,
+        tenant: existingStore?.tenant,
+        timeZone: normalizedTimeZone
       })
     }
   }
@@ -262,6 +316,23 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     return super.getTimezoneOffsetMinutes(configuration)
   }
 
+  /**
+   * Runs get timezone.
+   * @param {import("../configuration.js").default | undefined} configuration - Configuration instance.
+   * @returns {string | undefined} - Timezone identifier.
+   */
+  getTimeZone(configuration) {
+    if (this._timezoneAsyncLocalStorage) {
+      const store = this._timezoneAsyncLocalStorage.getStore()
+
+      if (store && typeof store.timeZone === "string") {
+        return store.timeZone
+      }
+    }
+
+    return super.getTimeZone(configuration)
+  }
+
   /**
    * Runs run with ability.
    * @param {import("../authorization/ability.js").default | undefined} ability - Ability to set for callback scope.
@@ -279,7 +350,8 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       ability,
       offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
       requestTiming: existingStore?.requestTiming,
-      tenant: existingStore?.tenant
+      tenant: existingStore?.tenant,
+      timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
     }, callback)
   }
 
@@ -303,7 +375,8 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         ability,
         offsetMinutes: this.getTimezoneOffsetMinutes(this.getConfiguration()),
         requestTiming: undefined,
-        tenant: undefined
+        tenant: undefined,
+        timeZone: this.getTimeZone(this.getConfiguration())
       })
     }
   }
@@ -337,7 +410,8 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       ability: existingStore?.ability,
       offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
       requestTiming,
-      tenant: existingStore?.tenant
+      tenant: existingStore?.tenant,
+      timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
     }, callback)
   }
 
@@ -370,7 +444,8 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       ability: existingStore?.ability,
       offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
       requestTiming: existingStore?.requestTiming,
-      tenant
+      tenant,
+      timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
     }, callback)
   }
 
@@ -394,7 +469,8 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         ability: undefined,
         offsetMinutes: this.getTimezoneOffsetMinutes(this.getConfiguration()),
         requestTiming: undefined,
-        tenant
+        tenant,
+        timeZone: this.getTimeZone(this.getConfiguration())
       })
     }
   }

package/build/frontend-model-controller.js

@@ -2315,7 +2315,7 @@ export default class FrontendModelController extends Controller {
       const isDateTimeColumn = typeof columnType === "string" && ["date", "datetime", "timestamp"].some((type) => columnType.includes(type))
 
       if (isDateTimeColumn) {
-        const parsedDate = normalizeDateStringForWrite(value)
+        const parsedDate = normalizeDateStringForWrite(value, {timeZone: this.getConfiguration().getEnvironmentHandler().getTimeZone(this.getConfiguration())})
 
         if (isDate(parsedDate)) {
           return parsedDate
@@ -3042,7 +3042,7 @@ export default class FrontendModelController extends Controller {
       json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
         errorMessage: frontendModelClientSafeErrorMessage,
         status: "error"
-      }))
+      }, this.transportSerializationOptions()))
     })
   }
 
@@ -3203,7 +3203,7 @@ export default class FrontendModelController extends Controller {
       if (!responsePayload) return
 
       await this.render({
-        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(responsePayload))
+        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(responsePayload, this.transportSerializationOptions()))
       })
     } catch (error) {
       const errorContext = this.frontendModelEndpointErrorContext({action, commandType: action, error})
@@ -3211,7 +3211,7 @@ export default class FrontendModelController extends Controller {
       await this.frontendModelLogEndpointError({action, commandType: action, error, model: errorContext.model})
 
       await this.render({
-        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext)))
+        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext), this.transportSerializationOptions()))
       })
     }
   }
@@ -3529,7 +3529,7 @@ export default class FrontendModelController extends Controller {
       json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
         responses,
         status: "success"
-      }))
+      }, this.transportSerializationOptions()))
     })
   }
 
@@ -3736,7 +3736,7 @@ export default class FrontendModelController extends Controller {
       const responsePayload = await this.frontendModelCustomCommandPayload()
 
       await this.render({
-        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(responsePayload))
+        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(responsePayload, this.transportSerializationOptions()))
       })
     } catch (error) {
       const errorContext = this.frontendModelEndpointErrorContext({action: "frontendCustomCommand", commandType: "custom-command", error})
@@ -3744,7 +3744,7 @@ export default class FrontendModelController extends Controller {
       await this.frontendModelLogEndpointError({action: errorContext.action, commandType: errorContext.commandType, error, model: errorContext.model})
 
       await this.render({
-        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext)))
+        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext), this.transportSerializationOptions()))
       })
     }
   }

package/build/frontend-models/base.js

@@ -5,10 +5,11 @@ import timeout from "awaitery/build/timeout.js"
 import wait from "awaitery/build/wait.js"
 import FrontendModelQuery, {frontendModelEventOptionsPayload} from "./query.js"
 import FrontendModelPreloader from "./preloader.js"
-import { normalizeDateStringForWrite } from "../database/datetime-storage.js"
+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 {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"
 import {defineModelScope} from "../utils/model-scope.js"
@@ -102,6 +103,7 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * @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 {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 {{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.
  */
 /**
  * FrontendModelIdleWaitArgs type.
@@ -1590,16 +1592,69 @@ function frontendModelTransportPath(url) {
   }
 }
 
+/**
+ * Resolves the browser runtime timezone when available.
+ * @returns {string | undefined} - Browser runtime timezone when available.
+ */
+function defaultFrontendModelTimeZone() {
+  if (typeof window === "undefined") return undefined
+
+  const intl = globalThis.Intl
+
+  if (!intl) {
+    throw new Error("Expected Intl to be available for browser timezone detection")
+  }
+
+  if (typeof intl.DateTimeFormat !== "function") {
+    throw new Error("Expected Intl.DateTimeFormat to be available as a function")
+  }
+
+  const timeZone = intl.DateTimeFormat().resolvedOptions().timeZone
+
+  if (typeof timeZone !== "string" || timeZone.trim().length < 1) {
+    throw new Error("Expected Intl.DateTimeFormat to resolve a browser timezone string")
+  }
+
+  return validateTimeZone(timeZone, "browser timeZone")
+}
+
+/**
+ * Resolves the configured frontend-model request timezone.
+ * @returns {string | undefined} - Configured frontend-model timezone.
+ */
+function frontendModelTransportTimeZone() {
+  if (!Object.prototype.hasOwnProperty.call(frontendModelTransportConfig, "timeZone")) {
+    return defaultFrontendModelTimeZone()
+  }
+
+  const timeZone = typeof frontendModelTransportConfig.timeZone === "function"
+    ? frontendModelTransportConfig.timeZone()
+    : frontendModelTransportConfig.timeZone
+
+  if (timeZone === undefined || timeZone === null) {
+    throw new Error("Frontend model transport timeZone did not resolve to a timezone string")
+  }
+
+  return validateTimeZone(timeZone, "frontend model transport timeZone")
+}
+
 /**
  * Runs frontend model request headers.
+ * @param {string | undefined} [timeZone] - Pre-resolved timezone for this request.
  * @returns {Record<string, string>} - Headers for frontend-model HTTP requests.
  */
-function frontendModelRequestHeaders() {
+function frontendModelRequestHeaders(timeZone = frontendModelTransportTimeZone()) {
   const dynamicHeaders = typeof frontendModelTransportConfig.requestHeaders === "function"
     ? (frontendModelTransportConfig.requestHeaders() || {})
     : (frontendModelTransportConfig.requestHeaders || {})
+  /** @type {Record<string, string>} */
+  const headers = {"Content-Type": "application/json", ...dynamicHeaders}
+
+  if (timeZone) {
+    headers[REQUEST_TIME_ZONE_HEADER] = timeZone
+  }
 
-  return {"Content-Type": "application/json", ...dynamicHeaders}
+  return headers
 }
 
 /**
@@ -1608,10 +1663,11 @@ function frontendModelRequestHeaders() {
  * @returns {Promise<Record<string, ?>>} - Decoded shared frontend-model API response.
  */
 async function performSharedFrontendModelApiRequest(requestPayload) {
-  const serializedRequestPayload = serializeFrontendModelTransportValue(requestPayload)
+  const timeZone = frontendModelTransportTimeZone()
+  const serializedRequestPayload = serializeFrontendModelTransportValue(requestPayload, {timeZone})
   const websocketClient = frontendModelTransportConfig.websocketClient
   const url = frontendModelApiUrl()
-  const mergedHeaders = frontendModelRequestHeaders()
+  const mergedHeaders = frontendModelRequestHeaders(timeZone)
 
   if (websocketClient) {
     const response = await websocketClient.post(frontendModelTransportPath(url), serializedRequestPayload, {
@@ -2710,6 +2766,14 @@ export default class FrontendModelBase {
       frontendModelTransportConfig.requestHeaders = config.requestHeaders
     }
 
+    if (Object.prototype.hasOwnProperty.call(config, "timeZone")) {
+      if (config.timeZone === undefined) {
+        delete frontendModelTransportConfig.timeZone
+      } else {
+        frontendModelTransportConfig.timeZone = config.timeZone
+      }
+    }
+
     if (Object.prototype.hasOwnProperty.call(config, "sessionStore")) {
       frontendModelTransportConfig.sessionStore = config.sessionStore
       // Reset cached internal client so the new sessionStore is picked up.
@@ -3706,7 +3770,7 @@ export default class FrontendModelBase {
    */
   static findByPrimitiveValuesMatch(actualValue, expectedValue) {
     if (actualValue instanceof Date && typeof expectedValue === "string") {
-      const normalizedExpectedValue = normalizeDateStringForWrite(expectedValue)
+      const normalizedExpectedValue = normalizeDateStringForWrite(expectedValue, {timeZone: frontendModelTransportTimeZone()})
 
       if (normalizedExpectedValue instanceof Date) {
         return actualValue.toISOString() === normalizedExpectedValue.toISOString()
@@ -4183,7 +4247,8 @@ export default class FrontendModelBase {
    */
   static async executeCommand(commandType, payload) {
     const commandName = this.commandName(commandType)
-    const serializedPayload = /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload))
+    const timeZone = frontendModelTransportTimeZone()
+    const serializedPayload = /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload, {timeZone}))
     const resourcePath = this.resourcePath()
     const containsAttachmentUpload = frontendModelPayloadContainsAttachmentUpload(serializedPayload)
     const useSharedTransport = !containsAttachmentUpload
@@ -4219,7 +4284,7 @@ export default class FrontendModelBase {
       const directResponse = await fetch(url, {
         body: JSON.stringify(serializedPayload),
         credentials: "include",
-        headers: frontendModelRequestHeaders(),
+        headers: frontendModelRequestHeaders(timeZone),
         method: "POST"
       })
 
@@ -4257,7 +4322,8 @@ export default class FrontendModelBase {
    * @returns {Promise<Record<string, FrontendModelAttributeValue>>} - Decoded response payload.
    */
   static async executeCustomCommand({commandName, commandType, memberId = null, payload, resourcePath}) {
-    const serializedPayload = /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload))
+    const timeZone = frontendModelTransportTimeZone()
+    const serializedPayload = /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload, {timeZone}))
     const customPath = frontendModelCustomCommandPath({
       commandName,
       memberId,

package/build/frontend-models/transport-serialization.js

@@ -2,6 +2,7 @@
 
 import {resolveFrontendModelClass} from "./model-registry.js"
 import isPlainObject from "../utils/plain-object.js"
+import {formatDateInTimeZone, validateTimeZone} from "../time-zone.js"
 
 const TYPE_KEY = "__velocious_type"
 const TYPE_DATE = "date"
@@ -14,6 +15,18 @@ const NUMBER_POSITIVE_INFINITY = "Infinity"
 const NUMBER_NEGATIVE_INFINITY = "-Infinity"
 const PRELOADED_RELATIONSHIPS_KEY = "__preloadedRelationships"
 
+/**
+ * Frontend model transport serialization options.
+ * @typedef {object} FrontendModelTransportSerializationOptions
+ * @property {string | undefined} [timeZone] - IANA timezone used when serializing Date instants.
+ */
+
+/**
+ * Normalized frontend model transport serialization options.
+ * @typedef {object} NormalizedFrontendModelTransportSerializationOptions
+ * @property {string | undefined} timeZone - Validated IANA timezone used when serializing Date instants.
+ */
+
 /**
  * Assign a key to a plain object without triggering the `__proto__` setter.
  * Uses `Object.defineProperty` so that keys like `__proto__` are stored as
@@ -150,9 +163,10 @@ export function isBackendModelInstance(value) {
  * Runs serialize frontend model transport value internal.
  * @param {?} value - Value to serialize.
  * @param {WeakSet<object>} seenModels - Models already visited in the current recursion path.
+ * @param {NormalizedFrontendModelTransportSerializationOptions} options - Serialization options.
  * @returns {?} - Serialized value with transport markers.
  */
-function serializeFrontendModelTransportValueInternal(value, seenModels) {
+function serializeFrontendModelTransportValueInternal(value, seenModels, options) {
   if (value === undefined) {
     return {[TYPE_KEY]: TYPE_UNDEFINED}
   }
@@ -160,7 +174,7 @@ function serializeFrontendModelTransportValueInternal(value, seenModels) {
   if (value instanceof Date) {
     return {
       [TYPE_KEY]: TYPE_DATE,
-      value: value.toISOString()
+      value: options.timeZone ? formatDateInTimeZone(value, options.timeZone) : value.toISOString()
     }
   }
 
@@ -183,7 +197,7 @@ function serializeFrontendModelTransportValueInternal(value, seenModels) {
   }
 
   if (Array.isArray(value)) {
-    return value.map((entry) => serializeFrontendModelTransportValueInternal(entry, seenModels))
+    return value.map((entry) => serializeFrontendModelTransportValueInternal(entry, seenModels, options))
   }
 
   if (isBackendModelInstance(value)) {
@@ -195,7 +209,7 @@ function serializeFrontendModelTransportValueInternal(value, seenModels) {
      * @type {Record<string, ?>} */
     const serializedModel = {
       [TYPE_KEY]: TYPE_FRONTEND_MODEL,
-      attributes: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValueInternal(modelAttributes, seenModels)),
+      attributes: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValueInternal(modelAttributes, seenModels, options)),
       modelName
     }
 
@@ -220,7 +234,8 @@ function serializeFrontendModelTransportValueInternal(value, seenModels) {
 
       assignSafeProperty(preloadedRelationships, relationshipName, serializeFrontendModelTransportValueInternal(
         loadedRelationship == undefined ? null : loadedRelationship,
-        seenModels
+        seenModels,
+        options
       ))
     }
 
@@ -240,7 +255,7 @@ function serializeFrontendModelTransportValueInternal(value, seenModels) {
     const serialized = {}
 
     for (const [key, nestedValue] of Object.entries(value)) {
-      assignSafeProperty(serialized, key, serializeFrontendModelTransportValueInternal(nestedValue, seenModels))
+      assignSafeProperty(serialized, key, serializeFrontendModelTransportValueInternal(nestedValue, seenModels, options))
     }
 
     return serialized
@@ -249,6 +264,19 @@ function serializeFrontendModelTransportValueInternal(value, seenModels) {
   return value
 }
 
+/**
+ * Normalizes serializer options once per top-level serialization.
+ * @param {FrontendModelTransportSerializationOptions} options - Serialization options.
+ * @returns {NormalizedFrontendModelTransportSerializationOptions} - Normalized options.
+ */
+function normalizeFrontendModelTransportSerializationOptions(options) {
+  return {
+    timeZone: options.timeZone === undefined
+      ? undefined
+      : validateTimeZone(options.timeZone, "transport serialization timeZone")
+  }
+}
+
 /**
  * Runs deserialize frontend model marker.
  * @param {{attributes: Record<string, ?>, modelName: string, preloadedRelationships?: Record<string, ?>}} marker - Encoded frontend-model marker.
@@ -292,10 +320,15 @@ function deserializeFrontendModelMarker(marker) {
 /**
  * Runs the serializeFrontendModelTransportValue helper.
  * @param {?} value - Value to serialize.
+ * @param {FrontendModelTransportSerializationOptions} [options] - Serialization options.
  * @returns {?} - Serialized value with transport markers.
  */
-export function serializeFrontendModelTransportValue(value) {
-  return serializeFrontendModelTransportValueInternal(value, new WeakSet())
+export function serializeFrontendModelTransportValue(value, options = {}) {
+  return serializeFrontendModelTransportValueInternal(
+    value,
+    new WeakSet(),
+    normalizeFrontendModelTransportSerializationOptions(options)
+  )
 }
 
 /**

package/build/frontend-models/websocket-channel.js

@@ -10,6 +10,17 @@ const EVENT_FILTER_KEYS = new Set(["joins", "key", "searches", "where"])
 // to avoid the configuration → logger → websocket-publishers import cycle.
 const FRONTEND_MODELS_CHANNEL_NAME = "frontend-models"
 
+/**
+ * Runs transport serialization options for a configuration.
+ * @param {import("../configuration.js").default} configuration - Configuration instance.
+ * @returns {import("./transport-serialization.js").FrontendModelTransportSerializationOptions} - Serialization options.
+ */
+function transportSerializationOptionsForConfiguration(configuration) {
+  return {
+    timeZone: configuration.getEnvironmentHandler().getTimeZone(configuration)
+  }
+}
+
 /**
  * Defines this typedef.
  * @typedef {{action?: string, id?: string | number, matchedEventFilterKeys?: string[], record?: import("./query.js").FrontendModelTransportValue, [key: string]: import("./query.js").FrontendModelTransportValue | string[] | undefined}} FrontendModelLifecycleBroadcastBody
@@ -164,9 +175,15 @@ export default class FrontendModelWebsocketChannel extends VelociousWebsocketCha
         return
       }
 
+      const configuration = this.session.configuration
+
+      if (!configuration) {
+        throw new Error("Frontend model websocket channel has no configuration for transport serialization")
+      }
+
       deliverBody = {
         ...deliverBody,
-        record: /** @type {import("./query.js").FrontendModelTransportValue} */ (serializeFrontendModelTransportValue(projectedRecord))
+        record: /** @type {import("./query.js").FrontendModelTransportValue} */ (serializeFrontendModelTransportValue(projectedRecord, transportSerializationOptionsForConfiguration(configuration)))
       }
     }
 

package/build/frontend-models/websocket-publishers.js

@@ -11,6 +11,17 @@ const channelClassRegisteredConfigurations = new WeakSet()
 /** Shared channel name for all frontend-model lifecycle subscriptions. */
 export const FRONTEND_MODELS_CHANNEL_NAME = "frontend-models"
 
+/**
+ * Runs transport serialization options for a configuration.
+ * @param {import("../configuration.js").default} configuration - Configuration instance.
+ * @returns {import("./transport-serialization.js").FrontendModelTransportSerializationOptions} - Serialization options.
+ */
+function transportSerializationOptionsForConfiguration(configuration) {
+  return {
+    timeZone: configuration.getEnvironmentHandler().getTimeZone(configuration)
+  }
+}
+
 /**
  * Runs the frontendModelBroadcastChannelName helper.
  * @param {string} modelName - Model class name.
@@ -169,7 +180,7 @@ function broadcastFrontendModelEvent(configuration, modelName, event) {
     action: event.action,
     id: event.id,
     model: modelName,
-    ...(event.record ? {record: serializeFrontendModelTransportValue(event.record)} : {})
+    ...(event.record ? {record: serializeFrontendModelTransportValue(event.record, transportSerializationOptionsForConfiguration(configuration))} : {})
   }
 
   configuration.broadcastToChannel(FRONTEND_MODELS_CHANNEL_NAME, {model: modelName}, body)

package/build/http-server/client/request-runner.js

@@ -7,6 +7,7 @@ import Logger from "../../logger.js"
 import RequestTiming from "./request-timing.js"
 import Response from "./response.js"
 import RoutesResolver from "../../routes/resolver.js"
+import {REQUEST_TIME_ZONE_HEADER} from "../../time-zone.js"
 
 /**
  * Runs stack frame line.
@@ -223,9 +224,10 @@ export default class VelociousHttpServerClientRequestRunner {
 
         setRequestTimeoutSeconds(configuration.getRequestTimeoutMs?.())
 
+        /** @type {Promise<void> | undefined} */
         let resolvePromise
 
-        try {
+        const runResolvedRequest = async () => {
           resolvePromise = routesResolver.resolve()
           // Keep Promise.race here to allow dynamic timeout updates.
           await Promise.race([resolvePromise, timeoutPromise])
@@ -236,6 +238,16 @@ export default class VelociousHttpServerClientRequestRunner {
             hasFilePath: Boolean(response.getFilePath()),
             bodyType: responseBodyTypeForLog(response)
           }])
+        }
+
+        try {
+          const requestTimeZone = request.header(REQUEST_TIME_ZONE_HEADER)
+
+          if (requestTimeZone !== undefined && requestTimeZone !== null) {
+            await configuration.runWithTimezone(requestTimeZone, runResolvedRequest)
+          } else {
+            await runResolvedRequest()
+          }
         } catch (error) {
           if (timedOut && resolvePromise) {
             void resolvePromise.catch((resolveError) => {

package/build/src/configuration-types.d.ts

@@ -415,6 +415,7 @@
  * @property {TenantDatabaseResolverType} [tenantDatabaseResolver] - Resolver for deriving tenant-specific database config overrides.
  * @property {Record<string, TenantDatabaseProviderType>} [tenantDatabaseProviders] - Tenant database lifecycle providers keyed by database identifier.
  * @property {string} [testing] - Path to the testing configuration file.
+ * @property {string | (() => string | undefined)} [timeZone] - Default timezone for timezone-less datetime strings.
  * @property {number | (() => number)} [timezoneOffsetMinutes] - Default timezone offset in minutes.
  * @property {string | string[]} [trustedProxies] - Trusted reverse proxy address ranges used to resolve request remote addresses from forwarding headers.
  * @property {number | (() => number)} [requestTimeoutMs] - Timeout in seconds for completing a HTTP request.
@@ -1538,6 +1539,10 @@ export type ConfigurationArgsType = {
      * - Path to the testing configuration file.
      */
     testing?: string | undefined;
+    /**
+     * - Default timezone for timezone-less datetime strings.
+     */
+    timeZone?: string | (() => string | undefined) | undefined;
     /**
      * - Default timezone offset in minutes.
      */