velocious 1.0.473 → 1.0.475

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

@@ -148,6 +148,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /** @type {Record<string, ?> | undefined} */
   static attachments = undefined
   /** @type {string[] | undefined} */
+  static commands = undefined
+  /** @type {string[] | undefined} */
   static collectionCommands = undefined
   /** @type {string[] | undefined} */
   static builtInCollectionCommands = undefined
@@ -157,8 +159,18 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   static builtInMemberCommands = undefined
   /** @type {string[] | undefined} */
   static relationships = undefined
+  /** @type {string | undefined} */
+  static modelName = undefined
+  /** @type {string | undefined} */
+  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 {?} */
+  static SharedResource = undefined
 
   /**
    * Runs constructor.
@@ -179,6 +191,149 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     this.modelNameValue = "modelName" in args ? args.modelName : this.modelClass().getModelName()
     this.paramsValue = "params" in args ? args.params : undefined
     this.resourceConfigurationValue = "resourceConfiguration" in args ? args.resourceConfiguration : defaultResourceConfiguration
+    /** @type {FrontendModelBaseResource | null | undefined} */
+    this.sharedResourceInstanceValue = undefined
+  }
+
+  /**
+   * Returns the configured shared resource class.
+   * @returns {?} - Shared resource class.
+   */
+  static sharedResourceClass() {
+    return this.SharedResource
+  }
+
+  /**
+   * 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" | "sync" | "translatedAttributes"} name - Static config property name.
+   * @returns {?} - Resolved config value.
+   */
+  static sharedResourceStaticValue(name) {
+    if (this[name] !== undefined) return this[name]
+
+    const SharedResource = /** @type {typeof FrontendModelBaseResource | undefined} */ (this.sharedResourceClass())
+
+    if (!SharedResource) return undefined
+    if (SharedResource[name] !== undefined) return SharedResource[name]
+
+    return undefined
+  }
+
+  /**
+   * Resolves translated attributes from environment and shared resources.
+   * @returns {string[] | undefined} - Translated attribute names.
+   */
+  static translatedAttributesConfig() {
+    return /** @type {string[] | undefined} */ (this.sharedResourceStaticValue("translatedAttributes"))
+  }
+
+  /**
+   * Builds a resource instance for shared-resource fallback calls.
+   * @returns {FrontendModelBaseResource | null} - Shared resource instance when configured.
+   */
+  sharedResourceInstance() {
+    if (this.sharedResourceInstanceValue !== undefined) return this.sharedResourceInstanceValue
+
+    const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (this.constructor)
+    const SharedResource = /** @type {typeof FrontendModelBaseResource | undefined} */ (ResourceClass.sharedResourceClass())
+
+    if (!SharedResource) {
+      this.sharedResourceInstanceValue = null
+      return this.sharedResourceInstanceValue
+    }
+
+    if (SharedResource === ResourceClass) {
+      throw new Error(`${ResourceClass.name}.SharedResource cannot point to itself.`)
+    }
+
+    this.sharedResourceInstanceValue = new SharedResource({
+      ability: this.ability,
+      controller: this.controller,
+      context: this.context,
+      locals: this.locals,
+      modelClass: this.modelClass(),
+      modelName: this.modelName(),
+      params: this.params(),
+      resourceConfiguration: this.resourceConfiguration()
+    })
+
+    return this.sharedResourceInstanceValue
+  }
+
+  /**
+   * Calls a shared-resource method only when the shared resource overrides the framework default.
+   * @param {string} methodName - Method name to resolve.
+   * @param {unknown[]} args - Method args.
+   * @returns {{called: boolean, result: unknown}} - Shared method call result.
+   */
+  callSharedResourceMethod(methodName, args) {
+    const sharedResource = this.sharedResourceInstance()
+
+    if (!sharedResource) return {called: false, result: undefined}
+
+    const methodOwner = prototypeOwnerForMethod(sharedResource, methodName)
+
+    if (!methodOwner || methodOwner === FrontendModelBaseResource.prototype || methodOwner === AuthorizationBaseResource.prototype) {
+      return {called: false, result: undefined}
+    }
+
+    const method = /** @type {Record<string, (...methodArgs: unknown[]) => unknown>} */ (/** @type {unknown} */ (sharedResource))[methodName]
+
+    return {called: true, result: method.apply(sharedResource, args)}
+  }
+
+  /**
+   * Runs shared method result or a fallback callback.
+   * @template Result
+   * @param {string} methodName - Shared method name.
+   * @param {unknown[]} args - Shared method args.
+   * @param {() => Result} fallback - Fallback callback.
+   * @returns {Result} - Shared or fallback result.
+   */
+  sharedResourceMethodOr(methodName, args, fallback) {
+    const sharedResult = this.callSharedResourceMethod(methodName, args)
+
+    if (sharedResult.called) return /** @type {Result} */ (sharedResult.result)
+
+    return fallback()
+  }
+
+  /**
+   * Resolves a method on this resource or its shared fallback.
+   * @param {string} methodName - Method name.
+   * @returns {{method: (...methodArgs: unknown[]) => unknown, resource: FrontendModelBaseResource} | null} - Resolved method and receiver.
+   */
+  resourceMethod(methodName) {
+    const ownMethod = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (this))[methodName]
+
+    if (typeof ownMethod === "function") {
+      return {
+        method: /** @type {(...methodArgs: unknown[]) => unknown} */ (ownMethod),
+        resource: this
+      }
+    }
+
+    const sharedResource = this.sharedResourceInstance()
+
+    if (!sharedResource) return null
+
+    const sharedMethod = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (sharedResource))[methodName]
+
+    if (typeof sharedMethod !== "function") return null
+
+    return {
+      method: /** @type {(...methodArgs: unknown[]) => unknown} */ (sharedMethod),
+      resource: sharedResource
+    }
+  }
+
+  /**
+   * Runs abilities.
+   * @returns {void} - No return value.
+   */
+  abilities() {
+    this.sharedResourceMethodOr("abilities", [], () => undefined)
   }
 
   /**
@@ -194,18 +349,36 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {import("../configuration-types.js").FrontendModelResourceConfiguration} - Static resource config (raw user input shape; consumers normalize).
    */
   static resourceConfig() {
+    const attributes = this.sharedResourceStaticValue("attributes")
+    const abilities = this.sharedResourceStaticValue("abilities")
+    const attachments = this.sharedResourceStaticValue("attachments")
+    const commands = this.sharedResourceStaticValue("commands")
+    const builtInCollectionCommands = this.sharedResourceStaticValue("builtInCollectionCommands")
+    const builtInMemberCommands = this.sharedResourceStaticValue("builtInMemberCommands")
+    const collectionCommands = this.sharedResourceStaticValue("collectionCommands")
+    const memberCommands = this.sharedResourceStaticValue("memberCommands")
+    const modelName = this.sharedResourceStaticValue("modelName")
+    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: this.attributes || []
+      attributes: /** @type {Record<string, ?> | string[]} */ (attributes || [])
     }
 
-    if (this.abilities) config.abilities = this.abilities
-    if (this.attachments) config.attachments = this.attachments
-    if (this.builtInCollectionCommands) config.builtInCollectionCommands = this.builtInCollectionCommands
-    if (this.builtInMemberCommands) config.builtInMemberCommands = this.builtInMemberCommands
-    if (this.collectionCommands) config.collectionCommands = this.collectionCommands
-    if (this.memberCommands) config.memberCommands = this.memberCommands
-    if (this.relationships) config.relationships = this.relationships
+    if (abilities) config.abilities = /** @type {string[]} */ (abilities)
+    if (attachments) config.attachments = /** @type {Record<string, ?>} */ (attachments)
+    if (commands) config.commands = /** @type {string[]} */ (commands)
+    if (builtInCollectionCommands) config.builtInCollectionCommands = /** @type {string[]} */ (builtInCollectionCommands)
+    if (builtInMemberCommands) config.builtInMemberCommands = /** @type {string[]} */ (builtInMemberCommands)
+    if (collectionCommands) config.collectionCommands = /** @type {string[]} */ (collectionCommands)
+    if (memberCommands) config.memberCommands = /** @type {string[]} */ (memberCommands)
+    if (modelName) config.modelName = /** @type {string} */ (modelName)
+    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
   }
@@ -242,6 +415,14 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     return /** @type {TModelClass} */ (this.modelClassValue)
   }
 
+  /**
+   * Runs required model class for authorization helpers.
+   * @returns {TModelClass} - Backing model class.
+   */
+  requiredModelClass() {
+    return this.modelClass()
+  }
+
   /**
    * Runs model name.
    * @returns {string} - Model name.
@@ -307,9 +488,11 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {Array<string | Record<string, ?>>} - Permit spec.
    */
   permittedParams(arg) {
-    void arg
+    return this.sharedResourceMethodOr("permittedParams", [arg], () => {
+      void arg
 
-    return []
+      return []
+    })
   }
 
   /**
@@ -319,9 +502,11 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {FrontendModelResourceAttributePayload | Promise<FrontendModelResourceAttributePayload>} - Normalized attributes.
    */
   normalizeCreateAttributes(attributes, options) {
-    void options
+    return this.sharedResourceMethodOr("normalizeCreateAttributes", [attributes, options], () => {
+      void options
 
-    return attributes
+      return attributes
+    })
   }
 
   /**
@@ -332,10 +517,12 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {FrontendModelResourceAttributePayload | Promise<FrontendModelResourceAttributePayload>} - Normalized attributes.
    */
   normalizeUpdateAttributes(model, attributes, options) {
-    void model
-    void options
+    return this.sharedResourceMethodOr("normalizeUpdateAttributes", [model, attributes, options], () => {
+      void model
+      void options
 
-    return attributes
+      return attributes
+    })
   }
 
   /**
@@ -346,9 +533,11 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {void | Promise<void>} - Resolves when the hook finishes.
    */
   beforeCreate(model, attributes, options) {
-    void model
-    void attributes
-    void options
+    return this.sharedResourceMethodOr("beforeCreate", [model, attributes, options], () => {
+      void model
+      void attributes
+      void options
+    })
   }
 
   /**
@@ -359,9 +548,11 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {void | Promise<void>} - Resolves when the hook finishes.
    */
   afterCreate(model, attributes, options) {
-    void model
-    void attributes
-    void options
+    return this.sharedResourceMethodOr("afterCreate", [model, attributes, options], () => {
+      void model
+      void attributes
+      void options
+    })
   }
 
   /**
@@ -372,9 +563,11 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {void | Promise<void>} - Resolves when the hook finishes.
    */
   beforeUpdate(model, attributes, options) {
-    void model
-    void attributes
-    void options
+    return this.sharedResourceMethodOr("beforeUpdate", [model, attributes, options], () => {
+      void model
+      void attributes
+      void options
+    })
   }
 
   /**
@@ -385,9 +578,11 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {void | Promise<void>} - Resolves when the hook finishes.
    */
   afterUpdate(model, attributes, options) {
-    void model
-    void attributes
-    void options
+    return this.sharedResourceMethodOr("afterUpdate", [model, attributes, options], () => {
+      void model
+      void attributes
+      void options
+    })
   }
 
   /**
@@ -396,7 +591,9 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {void | Promise<void>} - Resolves when the hook finishes.
    */
   beforeDestroy(model) {
-    void model
+    return this.sharedResourceMethodOr("beforeDestroy", [model], () => {
+      void model
+    })
   }
 
   /**
@@ -405,7 +602,9 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {void | Promise<void>} - Resolves when the hook finishes.
    */
   afterDestroy(model) {
-    void model
+    return this.sharedResourceMethodOr("afterDestroy", [model], () => {
+      void model
+    })
   }
 
   /**
@@ -418,10 +617,12 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {Promise<Result>} - Callback result.
    */
   async runMutationTransaction({action, model, callback}) {
-    void action
-    void model
+    return await this.sharedResourceMethodOr("runMutationTransaction", [{action, model, callback}], async () => {
+      void action
+      void model
 
-    return await callback()
+      return await callback()
+    })
   }
 
   /**
@@ -517,9 +718,11 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {boolean | void | Promise<boolean | void>} - Continue processing unless false.
    */
   beforeAction(action) {
-    void action
+    return this.sharedResourceMethodOr("beforeAction", [action], () => {
+      void action
 
-    // No-op by default.
+      // No-op by default.
+    })
   }
 
   /**
@@ -663,14 +866,14 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     /** @type {Record<string, ?>} */
     const directAttributes = {}
     const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (this.constructor)
-    const translatedSet = new Set(ResourceClass.translatedAttributes || [])
+    const translatedSet = new Set(ResourceClass.translatedAttributesConfig() || [])
 
     for (const [name, value] of Object.entries(attributes)) {
       const resourceSetterName = `set${inflection.camelize(name)}Attribute`
-      const resourceSetter = virtualSetterLookup(this)[resourceSetterName]
+      const resourceSetter = this.resourceMethod(resourceSetterName)
 
-      if (typeof resourceSetter === "function") {
-        await resourceSetter.call(this, model, value)
+      if (resourceSetter) {
+        await resourceSetter.method.call(resourceSetter.resource, model, value)
       } else if (translatedSet.has(name)) {
         await this._setTranslatedAttributeOnModel(model, name, value)
       } else {
@@ -1527,12 +1730,21 @@ function parsePermittedParams(permitSpec) {
 }
 
 /**
- * Narrows a resource to its dynamic virtual setter lookup surface.
- * @param {FrontendModelBaseResource} resource - Resource instance.
- * @returns {Record<string, FrontendModelResourceVirtualSetter>} Dynamic virtual setter lookup.
+ * Locates which prototype owns a method implementation.
+ * @param {object} instance - Instance receiving the method.
+ * @param {string} methodName - Method name.
+ * @returns {object | null} - Prototype that owns the method.
  */
-function virtualSetterLookup(resource) {
-  return /** @type {Record<string, FrontendModelResourceVirtualSetter>} */ (/** @type {unknown} */ (resource))
+function prototypeOwnerForMethod(instance, methodName) {
+  let prototype = Object.getPrototypeOf(instance)
+
+  while (prototype) {
+    if (Object.prototype.hasOwnProperty.call(prototype, methodName)) return prototype
+
+    prototype = Object.getPrototypeOf(prototype)
+  }
+
+  return null
 }
 
 /**
@@ -1567,7 +1779,7 @@ function filterWritableFrontendModelAttributes(
   if (resource) {
     const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (resource.constructor)
 
-    translatedAttributes = ResourceClass.translatedAttributes || []
+    translatedAttributes = ResourceClass.translatedAttributesConfig() || []
   }
 
   const translatedSet = new Set(translatedAttributes)
@@ -1582,11 +1794,11 @@ function filterWritableFrontendModelAttributes(
     const requestedSetterName = `set${inflection.camelize(resolvedAttributeName)}`
     const setterName = receiverClass.findMemberNameInsensitive(receiver, requestedSetterName) || requestedSetterName
     const resourceSetterName = `set${inflection.camelize(attributeName)}Attribute`
-    const resourceSetter = resource ? virtualSetterLookup(resource)[resourceSetterName] : undefined
+    const resourceSetter = resource?.resourceMethod(resourceSetterName)
 
     if (setterName in receiver) {
       writableAttributes[attributeName] = value
-    } else if (typeof resourceSetter === "function") {
+    } else if (resourceSetter) {
       writableAttributes[attributeName] = value
     } else if (translatedSet.has(attributeName)) {
       writableAttributes[attributeName] = value

package/src/frontend-model-resource/velocious-attachment-resource.js

@@ -26,9 +26,6 @@ export default class VelociousAttachmentResource extends FrontendModelBaseResour
     updatedAt: {type: "datetime"}
   }
 
-  /** @type {string[]} */
-  static abilities = ["read"]
-
   /** @type {string[]} */
   static builtInCollectionCommands = ["index"]
 

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
     })
   }