velocious 1.0.474 → 1.0.475

package/src/frontend-model-controller.js

@@ -5,7 +5,8 @@ import Controller from "./controller.js"
 import FrontendModelBaseResource from "./frontend-model-resource/base-resource.js"
 import Response from "./http-server/client/response.js"
 import {frontendModelResourcesWithBuiltInsForBackendProject} from "./frontend-models/built-in-resources.js"
-import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcePath, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
+import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcePath, frontendModelResourcesForBackendProject, frontendModelSyncManifestForBackendProjects} from "./frontend-models/resource-definition.js"
+import {createOfflineGrantFromBootstrap} from "./sync/offline-grant.js"
 import {FrontendModelQueryError, normalizeGroup as normalizeQueryGroup, normalizeJoins as normalizeQueryJoins, normalizePluck as normalizeQueryPluck, normalizePreload as normalizeQueryPreload, normalizeSearchOperator as normalizeQuerySearchOperator, normalizeSort as normalizeQuerySort} from "./frontend-models/query.js"
 import {assignSafeProperty, deserializeFrontendModelTransportValue, isBackendModelInstance, serializeFrontendModelTransportValue} from "./frontend-models/transport-serialization.js"
 import {requestDetails} from "./error-reporting/request-details.js"
@@ -25,7 +26,11 @@ import {RansackQueryError, normalizeRansackGroup, parseRansackSort} from "./util
 function normalizeFrontendModelPreload(preload) {
   if (!preload) return null
 
-  return normalizeQueryPreload(preload)
+  try {
+    return normalizeQueryPreload(preload)
+  } catch (error) {
+    throwFrontendModelQueryErrorForParserError(error)
+  }
 }
 
 /**
@@ -863,13 +868,31 @@ export default class FrontendModelController extends Controller {
     for (const [relationshipName, relationshipPreload] of Object.entries(preload)) {
       if (relationshipPreload === false) continue
 
-      const relationship = modelClass.getRelationshipByName(relationshipName)
+      const relationship = modelClass.getRelationshipsMap()[relationshipName]
+      if (!relationship) {
+        throw frontendModelQueryError(`Unknown preload relationship "${relationshipName}" for ${modelClass.name}`)
+      }
+
       const targetModelClass = await this.ensureFrontendModelRelationshipTargetClassInitialized({
         backendProject,
         relationship
       })
 
-      if (!targetModelClass || !isPlainObject(relationshipPreload)) continue
+      if (!targetModelClass) {
+        if (isPlainObject(relationshipPreload) && Object.keys(relationshipPreload).length > 0) {
+          let message = `Cannot preload nested relationships through relationship "${relationshipName}" for ${modelClass.name} because its target model class could not be resolved`
+
+          if (relationship.getPolymorphic() && relationship.getType() === "belongsTo") {
+            message = `Cannot preload nested relationships through polymorphic relationship "${relationshipName}" for ${modelClass.name}`
+          }
+
+          throw frontendModelQueryError(message)
+        }
+
+        continue
+      }
+
+      if (!isPlainObject(relationshipPreload)) continue
 
       await this.ensureFrontendModelPreloadClassesInitialized({
         backendProject,
@@ -3438,6 +3461,106 @@ export default class FrontendModelController extends Controller {
     return {status: "success"}
   }
 
+  /**
+   * Runs frontend sync bootstrap.
+   * @returns {Promise<void>} - Sync bootstrap response with manifest and signed offline grant.
+   */
+  async frontendSyncBootstrap() {
+    if (this.request().httpMethod() === "OPTIONS") {
+      await this.render({status: 204, json: {}})
+      return
+    }
+
+    const params = /** @type {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} */ (deserializeFrontendModelTransportValue(this.params()))
+    const configuration = this.getConfiguration()
+    const syncManifest = frontendModelSyncManifestForBackendProjects(configuration.getBackendProjects())
+    const offlineGrant = await createOfflineGrantFromBootstrap({
+      deviceId: this.frontendSyncBootstrapDeviceId(params),
+      grantId: this.frontendSyncBootstrapGrantId(params),
+      grantTtlMs: configuration.getSyncConfiguration().offlineGrantTtlMs,
+      now: this.frontendSyncBootstrapNow(params),
+      resources: syncManifest,
+      scopes: this.frontendSyncBootstrapScopes(params),
+      signingKey: configuration.currentOfflineGrantSigningKey(),
+      userId: this.frontendSyncBootstrapUserId()
+    })
+
+    await this.render({
+      json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
+        offlineGrant,
+        status: "success",
+        syncManifest
+      }, this.transportSerializationOptions()))
+    })
+  }
+
+  /**
+   * Resolves device id for sync bootstrap.
+   * @param {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} params - Request params.
+   * @returns {string} - Device id.
+   */
+  frontendSyncBootstrapDeviceId(params) {
+    if (typeof params.deviceId === "string" && params.deviceId.length > 0) return params.deviceId
+
+    throw new Error("Expected sync bootstrap deviceId")
+  }
+
+  /**
+   * Resolves grant id for sync bootstrap.
+   * @param {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} params - Request params.
+   * @returns {string | undefined} - Deterministic grant id for tests, generated id otherwise.
+   */
+  frontendSyncBootstrapGrantId(params) {
+    if (this.getConfiguration().getEnvironment() === "test" && typeof params.grantId === "string") return params.grantId
+
+    return undefined
+  }
+
+  /**
+   * Resolves bootstrap issue time.
+   * @param {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} params - Request params.
+   * @returns {Date} - Issue time.
+   */
+  frontendSyncBootstrapNow(params) {
+    if (this.getConfiguration().getEnvironment() === "test" && typeof params.now === "string") return new Date(params.now)
+
+    return new Date()
+  }
+
+  /**
+   * Resolves sync bootstrap scopes.
+   * @param {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} params - Request params.
+   * @returns {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue>} - Grant scopes.
+   */
+  frontendSyncBootstrapScopes(params) {
+    const scopes = params.scopes
+
+    if (scopes && typeof scopes === "object" && !Array.isArray(scopes)) {
+      return /** @type {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue>} */ (scopes)
+    }
+
+    return {}
+  }
+
+  /**
+   * Resolves current user id for sync bootstrap.
+   * @returns {string} - User id.
+   */
+  frontendSyncBootstrapUserId() {
+    const ability = this.currentAbility()
+    const currentUser = ability?.currentUser()
+
+    if (typeof currentUser === "string" || typeof currentUser === "number") return String(currentUser)
+    if (currentUser && typeof currentUser === "object") {
+      const userRecord = /** @type {{id?: string | number | (() => string | number)}} */ (currentUser)
+      const idValue = typeof userRecord.id === "function" ? userRecord.id() : userRecord.id
+
+      if (typeof idValue === "string" || typeof idValue === "number") return String(idValue)
+    }
+
+    throw new Error("Expected sync bootstrap current user")
+  }
+
   /**
    * Runs frontend api.
    * @returns {Promise<void>} - Shared frontend model API action with batch support.

package/src/frontend-model-resource/base-resource.js

@@ -165,6 +165,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   static primaryKey = undefined
   /** @type {import("../configuration-types.js").FrontendModelResourceServerConfiguration | undefined} */
   static server = undefined
+  /** @type {import("../configuration-types.js").FrontendModelResourceSyncConfiguration | boolean | undefined} */
+  static sync = undefined
   /** @type {string[] | undefined} */
   static translatedAttributes = undefined
   /** @type {?} */
@@ -204,7 +206,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Reads a static resource config value from the environment resource first,
    * then from the shared resource.
-   * @param {"abilities" | "attachments" | "attributes" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "modelName" | "primaryKey" | "relationships" | "server" | "translatedAttributes"} name - Static config property name.
+   * @param {"abilities" | "attachments" | "attributes" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "modelName" | "primaryKey" | "relationships" | "server" | "sync" | "translatedAttributes"} name - Static config property name.
    * @returns {?} - Resolved config value.
    */
   static sharedResourceStaticValue(name) {
@@ -359,6 +361,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     const primaryKey = this.sharedResourceStaticValue("primaryKey")
     const relationships = this.sharedResourceStaticValue("relationships")
     const server = this.sharedResourceStaticValue("server")
+    const sync = this.sharedResourceStaticValue("sync")
     /** @type {import("../configuration-types.js").FrontendModelResourceConfiguration} */
     const config = {
       attributes: /** @type {Record<string, ?> | string[]} */ (attributes || [])
@@ -375,6 +378,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     if (primaryKey) config.primaryKey = /** @type {string} */ (primaryKey)
     if (relationships) config.relationships = /** @type {string[]} */ (relationships)
     if (server) config.server = /** @type {import("../configuration-types.js").FrontendModelResourceServerConfiguration} */ (server)
+    if (sync !== undefined) config.sync = /** @type {import("../configuration-types.js").FrontendModelResourceSyncConfiguration | boolean} */ (sync)
 
     return config
   }

package/src/frontend-models/base.js

@@ -58,7 +58,15 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  */
 /**
  * Defines this typedef.
- * @typedef {{attributes?: Array<string | FrontendModelAttributeDefinition> | Record<string, FrontendModelAttributeDefinition>, builtInCollectionCommands?: string[], builtInMemberCommands?: string[], collectionCommands?: string[], commands?: string[], memberCommands?: string[], attachments?: Record<string, FrontendModelAttachmentDefinition>, modelName?: string, nestedAttributes?: Record<string, {allowDestroy?: boolean, limit?: number}>, primaryKey?: string, relationships?: string[]}} FrontendModelResourceConfig
+ * @typedef {Record<string, FrontendModelTransportValue>} FrontendModelSyncMetadata
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{enabled: boolean, operations: string[], policyHash: string, policyVersion: string | null, metadata?: FrontendModelSyncMetadata}} FrontendModelSyncConfig
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{attributes?: Array<string | FrontendModelAttributeDefinition> | Record<string, FrontendModelAttributeDefinition>, builtInCollectionCommands?: string[], builtInMemberCommands?: string[], collectionCommands?: string[], commands?: string[], memberCommands?: string[], attachments?: Record<string, FrontendModelAttachmentDefinition>, modelName?: string, nestedAttributes?: Record<string, {allowDestroy?: boolean, limit?: number}>, primaryKey?: string, relationships?: string[], sync?: FrontendModelSyncConfig}} FrontendModelResourceConfig
  */
 /**
  * Frontend model constructor type.
@@ -104,6 +112,7 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * @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.
+ * @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.
  */
 /**
  * FrontendModelIdleWaitArgs type.
@@ -777,6 +786,89 @@ function frontendModelClassFor(model) {
   return /** @type {FrontendModelClass} */ (constructorValue)
 }
 
+/**
+ * Whether the configured offline queue should handle a model operation.
+ * @param {FrontendModelClass} ModelClass - Model class.
+ * @param {"create" | "update" | "destroy"} operation - Sync operation.
+ * @returns {boolean} - Whether to queue locally.
+ */
+function shouldQueueFrontendModelOperationOffline(ModelClass, operation) {
+  const offlineSync = frontendModelTransportConfig.offlineSync
+
+  if (!offlineSync?.enabled) return false
+
+  const syncConfig = ModelClass.resourceConfig().sync
+
+  if (!syncConfig?.enabled) return false
+  if (!syncConfig.operations.includes(operation)) throw new Error(`Offline sync for ${ModelClass.getModelName()} does not allow ${operation}`)
+
+  return true
+}
+
+/**
+ * Queues an offline sync mutation.
+ * @param {object} args - Arguments.
+ * @param {Record<string, FrontendModelAttributeValue>} args.attributes - Mutation attributes.
+ * @param {string} [args.clientMutationId] - Pre-generated mutation id.
+ * @param {FrontendModelClass} args.ModelClass - Model class.
+ * @param {"create" | "update" | "destroy"} args.operation - Sync operation.
+ * @returns {Promise<string>} - Client mutation id.
+ */
+async function queueFrontendModelMutationOffline({attributes, clientMutationId: providedClientMutationId, ModelClass, operation}) {
+  const offlineSync = frontendModelTransportConfig.offlineSync
+
+  if (!offlineSync) throw new Error("Offline sync is not configured")
+
+  const syncConfig = ModelClass.resourceConfig().sync
+  if (!syncConfig?.enabled) throw new Error(`Offline sync is not enabled for ${ModelClass.getModelName()}`)
+
+  const now = offlineSync.now ? offlineSync.now() : new Date()
+  if (!(now instanceof Date) || Number.isNaN(now.getTime())) throw new Error("offlineSync.now must return a valid Date")
+
+  const clientMutationId = providedClientMutationId || (offlineSync.clientMutationId ? offlineSync.clientMutationId() : frontendModelOfflineMutationId())
+  if (typeof clientMutationId !== "string" || clientMutationId.length < 1) throw new Error("offlineSync.clientMutationId must return a non-empty string")
+
+  await offlineSync.mutationLog.append({
+    mutation: {
+      actorDeviceId: offlineSync.actorDeviceId,
+      actorUserId: offlineSync.actorUserId,
+      attributes: frontendModelSyncJsonObject(attributes),
+      baseVersion: null,
+      clientMutationId,
+      model: ModelClass.getModelName(),
+      occurredAt: now.toISOString(),
+      offlineGrantId: offlineSync.offlineGrant.id,
+      operation,
+      policyHash: syncConfig.policyHash
+    }
+  })
+
+  return clientMutationId
+}
+
+/**
+ * Generates a frontend-model offline mutation id.
+ * @returns {string} - Local mutation id.
+ */
+function frontendModelOfflineMutationId() {
+  if (globalThis.crypto && typeof globalThis.crypto.randomUUID === "function") return globalThis.crypto.randomUUID()
+
+  return `frontend-mutation-${Date.now()}-${Math.random().toString(16).slice(2)}`
+}
+
+/**
+ * Converts model attributes to sync-safe JSON payload values.
+ * @param {Record<string, FrontendModelAttributeValue>} attributes - Frontend model attributes.
+ * @returns {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} - Sync-safe attributes.
+ */
+function frontendModelSyncJsonObject(attributes) {
+  const serialized = JSON.parse(JSON.stringify(attributes))
+
+  if (!serialized || typeof serialized !== "object" || Array.isArray(serialized)) throw new Error("Expected sync mutation attributes object")
+
+  return /** @type {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} */ (serialized)
+}
+
 /**
  * Runs normalize frontend attachment input.
  * @param {?} input - Attachment input.
@@ -2779,6 +2871,10 @@ export default class FrontendModelBase {
       // Reset cached internal client so the new sessionStore is picked up.
       internalWebsocketClient = null
     }
+
+    if (Object.prototype.hasOwnProperty.call(config, "offlineSync")) {
+      frontendModelTransportConfig.offlineSync = config.offlineSync
+    }
   }
 
   /**
@@ -3892,6 +3988,43 @@ export default class FrontendModelBase {
       payload.attachments = attachments
     }
 
+    if (shouldQueueFrontendModelOperationOffline(ModelClass, commandType)) {
+      const offlineAttributes = {...payload.attributes}
+      let clientMutationId
+
+      if (isNew) {
+        const primaryKey = ModelClass.primaryKey()
+        const currentPrimaryKey = this.readAttribute(primaryKey)
+
+        if (currentPrimaryKey === undefined || currentPrimaryKey === null) {
+          clientMutationId = frontendModelTransportConfig.offlineSync?.clientMutationId
+            ? frontendModelTransportConfig.offlineSync.clientMutationId()
+            : frontendModelOfflineMutationId()
+          this.setAttribute(primaryKey, clientMutationId)
+          offlineAttributes[primaryKey] = clientMutationId
+        }
+      } else {
+        offlineAttributes[ModelClass.primaryKey()] = payload.id
+      }
+
+      if (payload.nestedAttributes !== undefined || payload.attachments !== undefined) {
+        throw new Error(`Offline sync for ${ModelClass.name} does not support nested attributes or attachments yet`)
+      }
+
+      await queueFrontendModelMutationOffline({
+        attributes: offlineAttributes,
+        clientMutationId,
+        ModelClass,
+        operation: commandType
+      })
+      this.setIsNewRecord(false)
+      this._persistedAttributes = cloneFrontendModelAttributes(this.attributes())
+      this._pendingNestedAttributes = {}
+      this._clearPendingAttachments()
+
+      return this
+    }
+
     const response = await ModelClass.executeCommand(commandType, payload)
 
     this.assignAttributes(ModelClass.attributesFromResponse(response))
@@ -3944,9 +4077,20 @@ export default class FrontendModelBase {
    */
   async destroy() {
     const ModelClass = frontendModelClassFor(this)
+    const id = this.primaryKeyValue()
+
+    if (shouldQueueFrontendModelOperationOffline(ModelClass, "destroy")) {
+      await queueFrontendModelMutationOffline({
+        attributes: {[ModelClass.primaryKey()]: id},
+        ModelClass,
+        operation: "destroy"
+      })
+
+      return
+    }
 
     await ModelClass.executeCommand("destroy", {
-      id: this.primaryKeyValue()
+      id
     })
   }
 

package/src/frontend-models/query.js

@@ -129,14 +129,14 @@ export function normalizePreload(preload) {
         continue
       }
 
-      throw new Error(`Invalid preload entry type: ${typeof entry}`)
+      throw frontendModelQueryError(`Invalid preload entry type: ${typeof entry}`)
     }
 
     return normalized
   }
 
   if (!isPlainObject(preload)) {
-    throw new Error(`Invalid preload type: ${typeof preload}`)
+    throw frontendModelQueryError(`Invalid preload type: ${typeof preload}`)
   }
 
   /**
@@ -155,7 +155,7 @@ export function normalizePreload(preload) {
       continue
     }
 
-    throw new Error(`Invalid preload value for ${relationshipName}: ${typeof relationshipPreload}`)
+    throw frontendModelQueryError(`Invalid preload value for ${relationshipName}: ${typeof relationshipPreload}`)
   }
 
   return normalized