velocious 1.0.470 → 1.0.471

package/README.md

@@ -378,7 +378,7 @@ export default new Configuration({
 `frontendModels` entries must be `FrontendModelBaseResource` subclasses. Built-in CRUD/find/index/serialize behavior lives in the base class, and app resources override only the pieces they actually need.
 Resource-level index customization should prefer `indexQuery()` or the pagination/search/sort hooks over replacing `records()`, so built-in pluck and aggregate count support can keep using the same query. See [`docs/frontend-model-resources.md`](docs/frontend-model-resources.md) for the resource extension points.
 
-Custom class- and instance-level commands are declared via `collectionCommands` / `memberCommands`. Each entry is a plain camelCase method name, or a `{name, args?, returnType?}` object that types the command's arguments and response — e.g. `memberCommands: ["suspend", {name: "refresh", args: [{name: "age", type: "number"}], returnType: "string"}]`. A command whose args are a single object literal with only optional fields generates an omittable parameter (`record.command()` works without passing `{}`); any required field keeps the argument mandatory. See [`docs/frontend-model-resources.md#custom-commands`](docs/frontend-model-resources.md#custom-commands).
+Custom class- and instance-level commands are declared via `collectionCommands` / `memberCommands`. Each entry is a plain camelCase method name, or a `{name, args?, returnType?}` object that types the command's arguments and response — e.g. `memberCommands: ["suspend", {name: "refresh", args: [{name: "age", type: "number"}], returnType: "string"}]`. Plain string commands derive args and return types from the backend resource method JSDoc; shared DTO `@import` types outside the backend `src` tree are preserved in generated frontend models, while backend-local helper types such as `ReturnType<typeof serializePayload>` are rejected. A command whose args are a single object literal with only optional fields generates an omittable parameter (`record.command()` works without passing `{}`); any required field keeps the argument mandatory. See [`docs/frontend-model-resources.md#custom-commands`](docs/frontend-model-resources.md#custom-commands).
 
 Resources expose the full CRUD ability set (`create`, `destroy`, `read`, `update`) by default. To restrict the API surface — for example to a read-only resource — declare an explicit subset:
 
@@ -565,13 +565,15 @@ When your frontend app calls a backend on another host/port (or under a path pre
 import FrontendModelBase from "velocious/build/src/frontend-models/base.js"
 
 FrontendModelBase.configureTransport({
-  url: "http://127.0.0.1:4501/frontend-models"
+  url: "http://127.0.0.1:4501/frontend-models",
+  timeZone: () => Intl.DateTimeFormat().resolvedOptions().timeZone
 })
 ```
 
 Available transport options:
 
 - `url` (can also be a relative path like `"/frontend-models"` on web)
+- `timeZone` (an IANA timezone string or a function returning one). Browser clients auto-detect this when it is not configured. Frontend-model datetime strings without an explicit timezone are interpreted in this request timezone and stored/queried as UTC instants.
 
 Use `await FrontendModelBase.waitForIdle()` when a test harness or app lifecycle needs to wait for queued, scheduled, and active frontend-model transport requests to finish before resetting state.
 

package/build/configuration-types.js

@@ -474,6 +474,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.

package/build/configuration.js

@@ -22,6 +22,7 @@ import {requestDetails} from "./error-reporting/request-details.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
 import PluginRoutes from "./routes/plugin-routes.js"
 import restArgsError from "./utils/rest-args-error.js"
+import {validateTimeZone} from "./time-zone.js"
 import {withTrackedStack} from "./utils/with-tracked-stack.js"
 
 export {CurrentConfigurationNotSetError}
@@ -125,7 +126,7 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, structureSql, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, structureSql, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -183,6 +184,7 @@ export default class VelociousConfiguration {
     this.locales = locales
     this._initializers = initializers
     this._testing = testing
+    this._timeZone = timeZone
     this._timezoneOffsetMinutes = timezoneOffsetMinutes
     this._trustedProxies = trustedProxies
     this._requestTimeoutMs = requestTimeoutMs
@@ -1848,6 +1850,20 @@ export default class VelociousConfiguration {
     return new Date().getTimezoneOffset()
   }
 
+  /**
+   * Runs get time zone.
+   * @returns {string | undefined} - Configured timezone identifier.
+   */
+  getTimeZone() {
+    const timeZone = typeof this._timeZone === "function"
+      ? this._timeZone()
+      : this._timeZone
+
+    if (timeZone === undefined || timeZone === null) return undefined
+
+    return validateTimeZone(timeZone, "configuration timeZone")
+  }
+
   /**
    * Runs get websocket events.
    * @returns {import("./http-server/websocket-events.js").default | undefined} - The websocket events.
@@ -2330,6 +2346,16 @@ export default class VelociousConfiguration {
     return await this.getEnvironmentHandler().runWithRequestTiming(requestTiming, callback)
   }
 
+  /**
+   * Runs run with timezone.
+   * @param {string} timeZone - IANA timezone identifier.
+   * @param {() => Promise<?>} callback - Callback.
+   * @returns {Promise<?>} - Callback result.
+   */
+  async runWithTimezone(timeZone, callback) {
+    return await this.getEnvironmentHandler().runWithTimezone(timeZone, callback)
+  }
+
   /**
    * Runs get current ability.
    * @returns {import("./authorization/ability.js").default | undefined} - Current ability from context.

package/build/controller.js

@@ -83,6 +83,18 @@ export default class VelociousController {
    */
   getRequest() { return this._request }
 
+  /**
+   * Runs transport serialization options.
+   * @returns {import("./frontend-models/transport-serialization.js").FrontendModelTransportSerializationOptions} - Serialization options.
+   */
+  transportSerializationOptions() {
+    const configuration = this.getConfiguration()
+
+    return {
+      timeZone: configuration.getEnvironmentHandler().getTimeZone(configuration)
+    }
+  }
+
   /**
    * Runs set cookie.
    * @param {string} name - Cookie name.
@@ -257,7 +269,7 @@ export default class VelociousController {
    */
   renderJsonArg(json) {
     return this._measureViewRender(() => {
-      const body = JSON.stringify(serializeFrontendModelTransportValue(json))
+      const body = JSON.stringify(serializeFrontendModelTransportValue(json, this.transportSerializationOptions()))
 
       this._response.setHeader("Content-Type", "application/json; charset=UTF-8")
       this._response.setBody(body)

package/build/database/datetime-storage.js

@@ -1,9 +1,12 @@
 // @ts-check
 
 import isDate from "../utils/is-date.js"
+import {Temporal} from "@js-temporal/polyfill"
+import {validateTimeZone} from "../time-zone.js"
 
 const dateTimeWithTimezonePattern = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:[zZ]|[+-]\d{2}:\d{2})$/
 const dateTimeWithoutTimezonePattern = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?$/
+const dateTimeWithoutTimezonePartsPattern = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?$/
 const timezoneSuffixPattern = /(?:[zZ]|[+-]\d{2}:\d{2})$/
 
 /**
@@ -85,6 +88,42 @@ function parseTimezoneLessDateTimeStringWithOffset(value, legacyLocalOffsetMinut
   return new Date(utcDate.getTime() + (legacyLocalOffsetMinutes * 60 * 1000))
 }
 
+/**
+ * Parses a timezone-less datetime string in a named timezone.
+ * @param {string} value - Datetime string.
+ * @param {string} timeZone - IANA timezone identifier.
+ * @returns {Date | string} - Parsed date or the original string when it is not a recognized datetime.
+ */
+function parseTimezoneLessDateTimeStringWithTimeZone(value, timeZone) {
+  const match = value.match(dateTimeWithoutTimezonePartsPattern)
+
+  if (!match) return value
+
+  const normalizedTimeZone = validateTimeZone(timeZone, "timeZone")
+  const fraction = (match[7] || "").padEnd(9, "0")
+
+  try {
+    const zonedDateTime = Temporal.ZonedDateTime.from({
+      day: Number(match[3]),
+      hour: Number(match[4]),
+      microsecond: Number(fraction.slice(3, 6)),
+      millisecond: Number(fraction.slice(0, 3)),
+      minute: Number(match[5]),
+      month: Number(match[2]),
+      nanosecond: Number(fraction.slice(6, 9)),
+      second: Number(match[6]),
+      timeZone: normalizedTimeZone,
+      year: Number(match[1])
+    })
+
+    return new Date(Number(zonedDateTime.epochMilliseconds))
+  } catch (error) {
+    if (error instanceof RangeError) return value
+
+    throw error
+  }
+}
+
 /**
  * Checks whether a string has a datetime timezone suffix.
  * @param {string} value - Value to check.
@@ -123,26 +162,31 @@ export function formatDateForDatabase(value, {databaseType}) {
 
 /**
  * Normalizes a record write string into a Date when it is a recognized datetime string.
- * Timezone-less strings are external input and are treated as UTC.
+ * Timezone-less strings are interpreted in the given timezone when present, otherwise UTC.
  * @param {string} value - Value to normalize.
+ * @param {object} [options] - Parse options.
+ * @param {string | undefined} [options.timeZone] - Timezone for timezone-less strings.
  * @returns {Date | string} - Normalized value.
  */
-export function normalizeDateStringForWrite(value) {
+export function normalizeDateStringForWrite(value, {timeZone} = {}) {
   if (hasDateTimeTimezone(value)) return parseTimezoneQualifiedDateTimeString(value)
+  if (timeZone !== undefined) return parseTimezoneLessDateTimeStringWithTimeZone(value, timeZone)
 
   return parseTimezoneLessDateTimeStringAsUtc(value)
 }
 
 /**
  * Normalizes a record write value into a Date when it is a recognized datetime string.
- * Timezone-less strings are external input and are treated as UTC.
+ * Timezone-less strings are interpreted in the given timezone when present, otherwise UTC.
  * @param {Date | string | null | undefined} value - Value to normalize.
+ * @param {object} [options] - Parse options.
+ * @param {string | undefined} [options.timeZone] - Timezone for timezone-less strings.
  * @returns {Date | string | null | undefined} - Normalized value.
  */
-export function normalizeDateValueForWrite(value) {
+export function normalizeDateValueForWrite(value, {timeZone} = {}) {
   if (typeof value != "string") return value
 
-  return normalizeDateStringForWrite(value)
+  return normalizeDateStringForWrite(value, {timeZone})
 }
 
 /**

package/build/database/record/index.js

@@ -1800,7 +1800,7 @@ class VelociousDatabaseRecord {
    * @returns {?} - The date value.
    */
   _normalizeDateValue(value) {
-    return normalizeDateValueForWrite(value)
+    return normalizeDateValueForWrite(value, {timeZone: this.getModelClass()._timeZoneForDateWrite()})
   }
 
   /**
@@ -2164,7 +2164,7 @@ class VelociousDatabaseRecord {
    * @returns {?} - Normalized value.
    */
   static _normalizeDateValueForInsert(value) {
-    return normalizeDateValueForWrite(value)
+    return normalizeDateValueForWrite(value, {timeZone: this._timeZoneForDateWrite()})
   }
 
   /**
@@ -2173,7 +2173,17 @@ class VelociousDatabaseRecord {
    * @returns {string | Date} - Parsed date or original string.
    */
   static _normalizeDateStringForInsert(value) {
-    return normalizeDateStringForWrite(value)
+    return normalizeDateStringForWrite(value, {timeZone: this._timeZoneForDateWrite()})
+  }
+
+  /**
+   * Runs time zone for date writes.
+   * @returns {string | undefined} - Active timezone identifier.
+   */
+  static _timeZoneForDateWrite() {
+    const configuration = this._getConfiguration()
+
+    return configuration.getEnvironmentHandler().getTimeZone(configuration)
   }
 
   /**
@@ -3923,7 +3933,7 @@ class VelociousDatabaseRecord {
 
       const value = data[columnName]
 
-      data[columnName] = normalizeDateValueForWrite(value)
+      data[columnName] = normalizeDateValueForWrite(value, {timeZone: this.getModelClass()._timeZoneForDateWrite()})
     }
   }
 

package/build/environment-handlers/base.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import {validateTimeZone} from "../time-zone.js"
+
 /**
  * CommandFileObjectType type.
  * @typedef {object} CommandFileObjectType
@@ -69,6 +71,26 @@ export default class VelociousEnvironmentHandlerBase {
     }
   }
 
+  /**
+   * 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.configuration) throw new Error("Configuration hasn't been set")
+
+    const previousTimeZone = this.configuration._timeZone
+
+    this.configuration._timeZone = validateTimeZone(timeZone, "timeZone")
+
+    try {
+      return await callback()
+    } finally {
+      this.configuration._timeZone = previousTimeZone
+    }
+  }
+
   /**
    * Runs set timezone offset.
    * @param {number} _offsetMinutes - Offset in minutes (Date#getTimezoneOffset).
@@ -83,6 +105,17 @@ export default class VelociousEnvironmentHandlerBase {
     this.configuration._timezoneOffsetMinutes = _offsetMinutes
   }
 
+  /**
+   * Runs set timezone.
+   * @param {string} timeZone - IANA timezone identifier.
+   * @returns {void} - No return value.
+   */
+  setTimezone(timeZone) {
+    if (!this.configuration) throw new Error("Configuration hasn't been set")
+
+    this.configuration._timeZone = validateTimeZone(timeZone, "timeZone")
+  }
+
   /**
    * Runs get timezone offset minutes.
    * @param {import("../configuration.js").default | undefined} configuration - Configuration instance.
@@ -100,6 +133,19 @@ export default class VelociousEnvironmentHandlerBase {
     return /** @type {number} */ (activeConfiguration.getTimezoneOffsetMinutes())
   }
 
+  /**
+   * Runs get timezone.
+   * @param {import("../configuration.js").default | undefined} configuration - Configuration instance.
+   * @returns {string | undefined} - Timezone identifier.
+   */
+  getTimeZone(configuration) {
+    const activeConfiguration = configuration || this.configuration
+
+    if (!activeConfiguration) throw new Error("Configuration hasn't been set")
+
+    return activeConfiguration.getTimeZone()
+  }
+
   /**
    * Runs run with request timing.
    * @param {import("../http-server/client/request-timing.js").default | undefined} requestTiming - Request timing collector.