velocious 1.0.473 → 1.0.475

package/src/configuration-types.js

@@ -240,7 +240,7 @@
  */
 
 /**
- * @typedef {Record<string, unknown> & {configuration?: import("./configuration.js").default, currentUser?: unknown, params?: VelociousParams, request?: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default}} VelociousLooseObject
+ * @typedef {Record<string, unknown> & {configuration?: import("./configuration.js").default, currentDevice?: unknown, currentUser?: unknown, modelRegistry?: Record<string, unknown> | {model: (name: string) => unknown}, now?: Date | (() => Date), offlineGrant?: unknown, params?: VelociousParams, request?: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default, resourceRuntime?: "backend" | "frontend" | "offline"}} VelociousLooseObject
  */
 
 /**
@@ -309,16 +309,18 @@
 /**
  * @typedef {object} FrontendModelResourceConfiguration
  * @property {Array<string | FrontendModelAttributeConfiguration> | Record<string, FrontendModelAttributeConfiguration | import("./database/drivers/base-column.js").default | boolean>} attributes - Attributes to expose on the frontend model.
- * @property {string[]} [abilities] - Ability action list (camelCase action names). Defaults to `["read"]` for `find` and `index` when omitted.
+ * @property {string[]} [abilities] - Additional camelCase ability action names to expose for per-record `record.can(action)` reads. Base CRUD actions (`read`, `create`, `update`, `destroy`) are always included and must not be listed here.
  * @property {Record<string, FrontendModelAttachmentConfiguration>} [attachments] - Attachment helpers keyed by attachment name.
  * @property {string[]} [commands] - Legacy built-in command names (`index`, `find`, `create`, `update`, `destroy`, `attach`, `download`, `url`).
  * @property {Array<FrontendModelResourceCustomCommand>} [collectionCommands] - Custom collection commands. Each entry is a camelCase method name, or a `{name, args?, returnType?}` object declaring typed arguments and/or a response type. The runtime derives the kebab-case command slug from the name.
  * @property {Array<FrontendModelResourceCustomCommand>} [memberCommands] - Custom member commands. Each entry is a camelCase method name, or a `{name, args?, returnType?}` object declaring typed arguments and/or a response type. The runtime derives the kebab-case command slug from the name.
  * @property {string[]} [builtInCollectionCommands] - Built-in collection command names (`index`, `create`).
  * @property {string[]} [builtInMemberCommands] - Built-in member command names (`find`, `update`, `destroy`, `attach`, `download`, `url`).
+ * @property {string} [modelName] - Frontend model name override.
  * @property {string[]} [relationships] - Relationship names to expose in frontend models. Type and target model are inferred from the backend model's registered relationships.
  * @property {string} [primaryKey] - Primary key attribute name.
  * @property {FrontendModelResourceServerConfiguration} [server] - Optional legacy backend behavior overrides for built-in frontend actions.
+ * @property {FrontendModelResourceSyncConfiguration | boolean} [sync] - Optional safe local/offline sync policy metadata. `policy` participates in the hash but is not exposed to generated frontend config/manifest.
  */
 
 /**
@@ -337,13 +339,48 @@
  */
 
 /**
- * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands"> & {
+ * JSON value accepted by sync policy metadata/hash inputs.
+ * @typedef {null | string | number | boolean | unknown[] | Record<string, unknown>} FrontendModelSyncJsonValue
+ */
+
+/**
+ * Frontend-model local/offline sync policy config. `metadata` is exposed to
+ * frontends and peers; `policy` is hashed but intentionally omitted from
+ * frontend-safe manifests.
+ * @typedef {object} FrontendModelResourceSyncConfiguration
+ * @property {boolean} [enabled] - Whether the resource is sync-enabled. Defaults to true when `sync` is configured.
+ * @property {string[]} [operations] - Sync operation names such as `index`, `find`, `create`, `update`, custom domain commands, etc.
+ * @property {string | number} [policyVersion] - App-controlled policy version used as a stable change signal.
+ * @property {Record<string, FrontendModelSyncJsonValue>} [metadata] - Safe frontend-visible metadata.
+ * @property {Record<string, FrontendModelSyncJsonValue>} [policy] - Deterministic non-secret policy inputs included in the policy hash only.
+ */
+
+/**
+ * Velocious sync configuration.
+ * @typedef {object} VelociousSyncConfiguration
+ * @property {Array<import("./sync/offline-grant.js").OfflineGrantSigningKey>} offlineGrantSigningKeys - Signing keys used to issue and verify offline grants. Secrets must never be exposed to clients.
+ * @property {number} [offlineGrantTtlMs] - Default offline grant TTL in milliseconds. Defaults to 24 hours.
+ */
+
+/**
+ * Frontend-safe normalized sync metadata.
+ * @typedef {object} NormalizedFrontendModelResourceSyncConfiguration
+ * @property {boolean} enabled - Whether the resource is sync-enabled.
+ * @property {string[]} operations - Sorted, duplicate-free sync operation names.
+ * @property {string | null} policyVersion - App-controlled policy version, or null.
+ * @property {string} policyHash - Deterministic sha256 hash of safe policy inputs.
+ * @property {Record<string, FrontendModelSyncJsonValue>} [metadata] - Safe frontend-visible metadata.
+ */
+
+/**
+ * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "sync"> & {
  *   abilities: FrontendModelResourceAbilitiesConfiguration
  *   builtInCollectionCommands: Record<string, string>
  *   builtInMemberCommands: Record<string, string>
  *   collectionCommands: Record<string, string>
  *   commandMetadata: Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>
  *   memberCommands: Record<string, string>
+ *   sync?: NormalizedFrontendModelResourceSyncConfiguration
  * }} NormalizedFrontendModelResourceConfiguration
  */
 
@@ -470,6 +507,7 @@
  * @property {string[]} locales - Supported locales.
  * @property {LocaleFallbacksType} localeFallbacks - Locale fallback map.
  * @property {StructureSqlConfiguration} [structureSql] - Structure SQL generation configuration.
+ * @property {VelociousSyncConfiguration} [sync] - Local/offline sync framework configuration.
  * @property {TenantResolverType} [tenantResolver] - Resolver for creating request-scoped tenant context objects.
  * @property {TenantDatabaseResolverType} [tenantDatabaseResolver] - Resolver for deriving tenant-specific database config overrides.
  * @property {Record<string, TenantDatabaseProviderType>} [tenantDatabaseProviders] - Tenant database lifecycle providers keyed by database identifier.

package/src/configuration.js

@@ -20,6 +20,7 @@ import VelociousWebsocketChannelSubscribers from "./http-server/websocket-channe
 import {CurrentConfigurationNotSetError, currentConfiguration, setCurrentConfiguration} from "./current-configuration.js"
 import {requestDetails} from "./error-reporting/request-details.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
+import {currentOfflineGrantSigningKey, normalizeOfflineGrantSigningKey} from "./sync/offline-grant.js"
 import PluginRoutes from "./routes/plugin-routes.js"
 import restArgsError from "./utils/rest-args-error.js"
 import {validateTimeZone} from "./time-zone.js"
@@ -126,7 +127,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, timeZone, 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, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -189,6 +190,7 @@ export default class VelociousConfiguration {
     this._trustedProxies = trustedProxies
     this._requestTimeoutMs = requestTimeoutMs
     this._structureSql = structureSql
+    this._sync = this._normalizeSyncConfiguration(sync)
     this._tenantDatabaseProviders = tenantDatabaseProviders || {}
     this._tenantDatabaseResolver = tenantDatabaseResolver
     this._tenantResolver = tenantResolver
@@ -380,6 +382,44 @@ export default class VelociousConfiguration {
     return this._cookieSecret
   }
 
+  /**
+   * Runs get sync configuration.
+   * @returns {import("./configuration-types.js").VelociousSyncConfiguration} - Sync configuration.
+   */
+  getSyncConfiguration() {
+    return this._sync
+  }
+
+  /**
+   * Runs current offline grant signing key.
+   * @returns {import("./sync/offline-grant.js").OfflineGrantSigningKey} - Current signing key.
+   */
+  currentOfflineGrantSigningKey() {
+    const signingKeys = this.getSyncConfiguration().offlineGrantSigningKeys
+
+    return currentOfflineGrantSigningKey(signingKeys)
+  }
+
+  /**
+   * Normalizes sync configuration.
+   * @param {import("./configuration-types.js").VelociousSyncConfiguration | undefined} sync - Sync configuration.
+   * @returns {import("./configuration-types.js").VelociousSyncConfiguration} - Normalized sync configuration.
+   */
+  _normalizeSyncConfiguration(sync) {
+    const offlineGrantSigningKeys = sync?.offlineGrantSigningKeys || []
+    const offlineGrantTtlMs = sync?.offlineGrantTtlMs
+
+    if (!Array.isArray(offlineGrantSigningKeys)) throw new Error("sync.offlineGrantSigningKeys must be an array")
+    if (offlineGrantTtlMs !== undefined && (!Number.isInteger(offlineGrantTtlMs) || offlineGrantTtlMs <= 0)) {
+      throw new Error("sync.offlineGrantTtlMs must be a positive integer number of milliseconds")
+    }
+
+    return {
+      offlineGrantSigningKeys: offlineGrantSigningKeys.map((key) => normalizeOfflineGrantSigningKey(key)),
+      offlineGrantTtlMs: offlineGrantTtlMs || 24 * 60 * 60 * 1000
+    }
+  }
+
   /**
    * Runs get database configuration.
    * @returns {Record<string, import("./configuration-types.js").DatabaseConfigurationType>} - The database configuration.

package/src/database/drivers/base.js

@@ -50,6 +50,7 @@
  * @property {string} [logName] - Query log subject.
  * @property {boolean} [logQuery] - Whether to log the query.
  * @property {boolean} [processListComment] - Whether to add process-list comments to the query.
+ * @property {boolean} [sessionTimeZone] - Whether to ensure the configured database session time zone before the query.
  * @property {string} [sourceStack] - Stack captured at the caller boundary.
  */
 
@@ -237,6 +238,14 @@ export default class VelociousDatabaseDriversBase {
     // No-op by default
   }
 
+  /**
+   * Flushes pending writes that the driver delayed for persistence.
+   * @returns {Promise<void>} - Resolves when pending writes are durable.
+   */
+  async flushPendingWrites() {
+    // No-op by default
+  }
+
   /**
    * Runs set connection checkout name.
    * @param {string | undefined} name - Human-readable name for this active checkout.
@@ -1041,12 +1050,14 @@ export default class VelociousDatabaseDriversBase {
     let result
 
     try {
+      const runQueryActualWithHooks = async () => await this._queryActualWithHooks(querySql, options)
+
       if (requestTiming && tries === 1) {
-        result = await requestTiming.measureDbQuery(async () => await this._queryActual(querySql))
+        result = await requestTiming.measureDbQuery(runQueryActualWithHooks)
       } else if (requestTiming) {
-        result = await requestTiming.measure("db", async () => await this._queryActual(querySql))
+        result = await requestTiming.measure("db", runQueryActualWithHooks)
       } else {
-        result = await this._queryActual(querySql)
+        result = await runQueryActualWithHooks()
       }
     } finally {
       this._activeQuery = previousActiveQuery
@@ -1070,6 +1081,42 @@ export default class VelociousDatabaseDriversBase {
     return result
   }
 
+  /**
+   * Runs query actual with before/after hooks.
+   * @param {string} sql - SQL string.
+   * @param {QueryOptions} options - Query options.
+   * @returns {Promise<QueryResultType>} - Resolves with the query.
+   */
+  async _queryActualWithHooks(sql, options) {
+    await this.beforeQuery(sql, options)
+
+    try {
+      return await this._queryActual(sql)
+    } finally {
+      await this.afterQuery(sql, options)
+    }
+  }
+
+  /**
+   * Hook that runs immediately before a SQL query is sent to the driver.
+   * @param {string} _sql - SQL string.
+   * @param {QueryOptions} _options - Query options.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async beforeQuery(_sql, _options) {
+    // No-op by default
+  }
+
+  /**
+   * Hook that runs immediately after a SQL query has completed or failed.
+   * @param {string} _sql - SQL string.
+   * @param {QueryOptions} _options - Query options.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async afterQuery(_sql, _options) {
+    // No-op by default
+  }
+
   /**
    * Runs get debug snapshot.
    * @returns {DatabaseConnectionDebugSnapshot} - Diagnostic snapshot for this connection.
@@ -1504,6 +1551,7 @@ export default class VelociousDatabaseDriversBase {
         }
       }
     })
+    await this.flushPendingWrites()
   }
 
   /**

package/src/database/drivers/mysql/index.js

@@ -30,15 +30,20 @@ import Update from "./sql/update.js"
 const MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS = 60 * 60 * 24 * 365
 
 export default class VelociousDatabaseDriversMysql extends Base{
+  /** @type {string | null} */
+  _desiredSessionTimeZone = "+00:00"
+
+  /** @type {string | null} */
+  _currentSessionTimeZone = null
+
   /**
    * Runs connect.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async connect() {
+    this.resetCurrentSessionTimeZone()
     this.pool = mysql.createPool(Object.assign({connectionLimit: 1}, this.connectArgs()))
     this.pool.on("error", this.onPoolError)
-
-    await this.setSessionTimezoneToUtc()
   }
 
   /**
@@ -56,6 +61,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
   async close() {
     await this.pool?.end()
     this.pool = undefined
+    this.resetCurrentSessionTimeZone()
   }
 
   /**
@@ -64,7 +70,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @returns {Promise<void>} - Resolves when complete.
    */
   async setConnectionCheckoutName(name) {
-    await this.query(`SET @velocious_connection_checkout_name = ${name === undefined ? "NULL" : this.quote(name)}`, {logName: "Set Connection Checkout Name", processListComment: false})
+    await this.query(`SET @velocious_connection_checkout_name = ${name === undefined ? "NULL" : this.quote(name)}`, {logName: "Set Connection Checkout Name", processListComment: false, sessionTimeZone: false})
     await super.setConnectionCheckoutName(name)
   }
 
@@ -73,16 +79,77 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @returns {Promise<void>} - Resolves when complete.
    */
   async clearConnectionCheckoutName() {
-    await this.query("SET @velocious_connection_checkout_name = NULL", {logName: "Clear Connection Checkout Name", processListComment: false})
+    await this.query("SET @velocious_connection_checkout_name = NULL", {logName: "Clear Connection Checkout Name", processListComment: false, sessionTimeZone: false})
     await super.clearConnectionCheckoutName()
   }
 
   /**
-   * Sets the database session timezone to UTC so bare timestamp literals store UTC instants.
+   * Hook before every query.
+   * @param {string} _sql - SQL string.
+   * @param {import("../base.js").QueryOptions} options - Query options.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async setSessionTimezoneToUtc() {
-    await this.query("SET time_zone = '+00:00'", {logName: "Set Session Time Zone", processListComment: false})
+  async beforeQuery(_sql, options) {
+    if (options.sessionTimeZone !== false) await this.ensureSessionTimeZone()
+  }
+
+  /**
+   * Gets the desired database session time zone for this connection context.
+   * @returns {string | null} - Desired session time zone.
+   */
+  getDesiredSessionTimeZone() {
+    return this._desiredSessionTimeZone
+  }
+
+  /**
+   * Sets the desired database session time zone without querying MySQL immediately.
+   * @param {string | null} timeZone - Desired session time zone.
+   */
+  setDesiredSessionTimeZone(timeZone) {
+    this._desiredSessionTimeZone = timeZone
+  }
+
+  /**
+   * Gets the database session time zone last confirmed through SET time_zone.
+   * @returns {string | null} - Current known session time zone.
+   */
+  getCurrentSessionTimeZone() {
+    return this._currentSessionTimeZone
+  }
+
+  /**
+   * Clears the current known database session time zone when the physical connection changes.
+   */
+  resetCurrentSessionTimeZone() {
+    this._currentSessionTimeZone = null
+  }
+
+  /**
+   * Ensures MySQL has the desired session time zone before user SQL runs.
+   * @returns {Promise<boolean>} - True when SET time_zone was executed.
+   */
+  async ensureSessionTimeZone() {
+    const desiredSessionTimeZone = this.getDesiredSessionTimeZone()
+
+    if (desiredSessionTimeZone === null || this.getCurrentSessionTimeZone() === desiredSessionTimeZone) return false
+
+    await this.setSessionTimeZone(desiredSessionTimeZone)
+
+    return true
+  }
+
+  /**
+   * Sets the database session time zone if it changed from the last confirmed value.
+   * @param {string} timeZone - Session time zone value accepted by MySQL.
+   * @returns {Promise<boolean>} - True when SET time_zone was executed.
+   */
+  async setSessionTimeZone(timeZone) {
+    if (this.getCurrentSessionTimeZone() === timeZone) return false
+
+    await this._queryActual(`SET time_zone = ${this.quote(timeZone)}`)
+    this._currentSessionTimeZone = timeZone
+
+    return true
   }
 
   /**

package/src/database/drivers/sqlite/connection-sql-js.js

@@ -8,16 +8,28 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
    * Runs constructor.
    * @param {import("../base.js").default} driver - Database driver instance.
    * @param {import("sql.js").Database} connection - Connection.
+   * @param {import("./web-persistence.js").SqliteWebPersistence} persistence - Database persistence adapter.
    */
-  constructor(driver, connection) {
+  constructor(driver, connection, persistence) {
     this.connection = connection
     this.driver = driver
+    this.persistence = persistence
   }
 
   async close() {
-    await this.saveDatabase()
+    await this.flushDatabaseSave()
     await this.connection.close()
   }
+
+  /**
+   * Flushes any debounced database save and waits until persistence is complete.
+   * @returns {Promise<void>} - Resolves when the current database bytes are stored.
+   */
+  async flushDatabaseSave() {
+    this.saveDatabaseDebounce.clear()
+    await this.saveDatabase()
+  }
+
   /**
    * Runs query.
    * @param {string} sql - SQL string.
@@ -36,10 +48,9 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
   }
 
   saveDatabase = async () => {
-    const localStorageContent = this.connection.export()
+    const databaseContent = this.connection.export()
 
-    // @ts-expect-error
-    await this.driver.betterLocalStorage.set(this.driver.localStorageName(), localStorageContent)
+    await this.persistence.save(databaseContent)
   }
 
   saveDatabaseDebounce = debounce(this.saveDatabase, 500)

package/src/database/drivers/sqlite/index.web.js

@@ -1,8 +1,8 @@
 // @ts-check
 
-import BetterLocalStorage from "better-localstorage"
 import ConnectionSqlJs from "./connection-sql-js.js"
 import initSqlJs from "sql.js"
+import {createSqliteWebPersistence, deleteSqliteWebPersistences, sqliteWebPersistenceKey} from "./web-persistence.js"
 
 import Base from "./base.js"
 
@@ -12,10 +12,6 @@ import Base from "./base.js"
  */
 
 export default class VelociousDatabaseDriversSqliteWeb extends Base {
-  /**
-   * Better local storage.
-   * @type {BetterLocalStorage | undefined} */
-  betterLocalStorage = undefined
   /**
    * Connection.
    * @type {ConnectionSqlJs | undefined} */
@@ -39,16 +35,14 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
     this.args = this.getArgs()
 
     if (!this.args.getConnection) {
-      this.betterLocalStorage ||= new BetterLocalStorage()
-
       if (this.args.reset) {
-        await this.betterLocalStorage.delete(this.localStorageName())
+        await deleteSqliteWebPersistences({databaseName: this.databaseName()})
       }
 
+      const persistence = await createSqliteWebPersistence({databaseName: this.databaseName()})
       const SQL = await initSqlJs({locateFile: this.sqlJsLocateFile()})
-
-      const databaseContent = await this.betterLocalStorage.get(this.localStorageName())
-      const connectionSqlJs = new ConnectionSqlJs(this, new SQL.Database(databaseContent))
+      const databaseContent = await persistence.load()
+      const connectionSqlJs = new ConnectionSqlJs(this, new SQL.Database(databaseContent), persistence)
 
       this._connection = connectionSqlJs
     }
@@ -58,6 +52,18 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
     await this.getConnection().close()
   }
 
+  /**
+   * Flushes pending SQL.js local persistence writes.
+   * @returns {Promise<void>} - Resolves when pending writes are durable.
+   */
+  async flushPendingWrites() {
+    if (!this.args?.getConnection) {
+      if (!this._connection) throw new Error("SQLite web connection has not been initialized")
+
+      await this._connection.flushDatabaseSave()
+    }
+  }
+
   /**
    * Runs get connection.
    * @returns {ConnectionSqlJs | SqliteWebConnection} - The connection.
@@ -72,11 +78,19 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
   }
 
   localStorageName() {
-    if (!this.args?.name) {
-      throw new Error("No name given in arguments for SQLite Web database")
-    }
+    return sqliteWebPersistenceKey(this.databaseName())
+  }
+
+  /**
+   * Returns the configured database name.
+   * @returns {string} - Database name.
+   */
+  databaseName() {
+    const name = this.args?.name
+
+    if (typeof name !== "string" || name.length < 1) throw new Error("No name given in arguments for SQLite Web database")
 
-    return `VelociousDatabaseDriversSqliteWeb---${this.args?.name}`
+    return name
   }
 
   /**