velocious 1.0.641 → 1.0.643

package/src/database/record/index.js

@@ -71,6 +71,8 @@ import UUID from "pure-uuid"
  * AttachmentDriverConstructor type.
  * @typedef {import("../../configuration-types.js").AttachmentDriverConstructor} AttachmentDriverConstructor
  */
+/** @typedef {import("../../configuration-types.js").AttachmentSyncConfiguration} AttachmentSyncConfiguration */
+/** @typedef {import("../../configuration-types.js").RecordAttachmentConfiguration} RecordAttachmentConfiguration */
 
 /** Stored values that a declared `"boolean"` cast reads back as `true`. */
 const declaredBooleanTruthyValues = new Set([1, true, "1"])
@@ -238,7 +240,7 @@ class VelociousDatabaseRecord {
   static _lifecycleCallbacks = undefined
   /** @type {Record<string, typeof import("./validators/base.js").default> | undefined} */
   static _validatorTypes = undefined
-  /** @type {Record<string, {driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}> | undefined} */
+  /** @type {Record<string, RecordAttachmentConfiguration> | undefined} */
   static _attachmentsMap = undefined
   /** @type {Record<string, import("./relationships/base.js").default> | undefined} */
   static _relationships = undefined
@@ -494,13 +496,13 @@ class VelociousDatabaseRecord {
 
   /**
    * Runs get attachments map.
-   * @returns {Record<string, {driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}>} - Attachment definitions keyed by name.
+   * @returns {Record<string, RecordAttachmentConfiguration>} - Attachment definitions keyed by name.
    */
   static getAttachmentsMap() {
     if (!this._attachmentsMap) {
       /**
        * Narrows the runtime value to the documented type.
-       * @type {Record<string, {driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}>} */
+       * @type {Record<string, RecordAttachmentConfiguration>} */
       this._attachmentsMap = {}
     }
 
@@ -1165,16 +1167,25 @@ class VelociousDatabaseRecord {
 
   /**
    * Runs get attachments.
-   * @returns {Record<string, {driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}>} - Attachment definitions.
+   * @returns {Record<string, RecordAttachmentConfiguration>} - Attachment definitions.
    */
   static getAttachments() {
     return this.getAttachmentsMap()
   }
 
+  /**
+   * Returns attachment definitions through the model contract shared with
+   * frontend model classes.
+   * @returns {Record<string, RecordAttachmentConfiguration>} - Attachment definitions.
+   */
+  static attachmentDefinitions() {
+    return this.getAttachmentsMap()
+  }
+
   /**
    * Runs get attachment by name.
    * @param {string} attachmentName - Attachment name.
-   * @returns {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}} - Attachment definition.
+   * @returns {RecordAttachmentConfiguration} - Attachment definition.
    */
   static getAttachmentByName(attachmentName) {
     const definition = this.getAttachmentsMap()[attachmentName]
@@ -1443,14 +1454,34 @@ class VelociousDatabaseRecord {
    * @param {string} attachmentName - Attachment name.
    * @param {object} args - Attachment args.
    * @param {string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>} [args.driver] - Attachment driver name, class, or instance.
+   * @param {AttachmentSyncConfiguration} [args.sync] - Client-safe synchronized asset policy.
    * @param {"hasOne" | "hasMany"} args.type - Attachment type.
    * @returns {void} - No return value.
    */
-  static _defineAttachment(attachmentName, {driver, type}) {
+  static _defineAttachment(attachmentName, {driver, sync, type}) {
     if (!attachmentName || typeof attachmentName !== "string") throw new Error(`Invalid attachment name: ${attachmentName}`)
     if (attachmentName in this.getAttachmentsMap()) throw new Error(`Attachment ${attachmentName} already exists`)
 
-    this.getAttachmentsMap()[attachmentName] = {driver, type}
+    if (sync) {
+      const {fetch, offlineRequirement, retention, ...restSync} = sync
+
+      restArgsError(restSync)
+
+      if (fetch !== "eager" && fetch !== "on-demand") {
+        throw new Error(`Attachment ${attachmentName} sync fetch must be eager or on-demand`)
+      }
+      if (offlineRequirement !== "optional" && offlineRequirement !== "required") {
+        throw new Error(`Attachment ${attachmentName} offline requirement must be optional or required`)
+      }
+      if (retention !== "durable" && retention !== "evictable") {
+        throw new Error(`Attachment ${attachmentName} sync retention must be durable or evictable`)
+      }
+      if (offlineRequirement === "required" && retention !== "durable") {
+        throw new Error(`Attachment ${attachmentName} required offline assets must use durable retention`)
+      }
+    }
+
+    this.getAttachmentsMap()[attachmentName] = {driver, sync, type}
 
     const prototype = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (/** @type {ReturnType<typeof JSON.parse>} */ (this.prototype))
 
@@ -1467,21 +1498,21 @@ class VelociousDatabaseRecord {
   /**
    * Adds a single attachment helper to the model.
    * @param {string} attachmentName - Attachment name.
-   * @param {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>}} [args] - Attachment options.
+   * @param {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, sync?: AttachmentSyncConfiguration}} [args] - Attachment options.
    * @returns {void} - No return value.
    */
   static hasOneAttachment(attachmentName, args = {}) {
-    this._defineAttachment(attachmentName, {driver: args.driver, type: "hasOne"})
+    this._defineAttachment(attachmentName, {driver: args.driver, sync: args.sync, type: "hasOne"})
   }
 
   /**
    * Adds a collection attachment helper to the model.
    * @param {string} attachmentName - Attachment name.
-   * @param {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>}} [args] - Attachment options.
+   * @param {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, sync?: AttachmentSyncConfiguration}} [args] - Attachment options.
    * @returns {void} - No return value.
    */
   static hasManyAttachments(attachmentName, args = {}) {
-    this._defineAttachment(attachmentName, {driver: args.driver, type: "hasMany"})
+    this._defineAttachment(attachmentName, {driver: args.driver, sync: args.sync, type: "hasMany"})
   }
 
   /**

package/src/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -5,6 +5,7 @@ import path from "node:path"
 import * as inflection from "inflection"
 import {frontendModelResourceIsBuiltIn, frontendModelResourcesWithBuiltInsForBackendProject} from "../../../../../frontend-models/built-in-resources.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition} from "../../../../../frontend-models/resource-definition.js"
+import {frontendModelResourceInternalConstructor} from "../../../../../frontend-model-resource/base-resource.js"
 
 /**
  * Attribute metadata used for generated frontend-model JSDoc.
@@ -381,7 +382,18 @@ export default class DbGenerateFrontendModels extends BaseCommand {
           ? "hasMany"
           : "hasOne"
 
-        fileContent += `        ${attachmentName}: {type: ${JSON.stringify(attachmentType)}},\n`
+        if (attachmentConfig.sync) {
+          fileContent += `        ${attachmentName}: {\n`
+          fileContent += "          sync: {\n"
+          fileContent += `            fetch: ${JSON.stringify(attachmentConfig.sync.fetch)},\n`
+          fileContent += `            offlineRequirement: ${JSON.stringify(attachmentConfig.sync.offlineRequirement)},\n`
+          fileContent += `            retention: ${JSON.stringify(attachmentConfig.sync.retention)},\n`
+          fileContent += "          },\n"
+          fileContent += `          type: ${JSON.stringify(attachmentType)}\n`
+          fileContent += "        },\n"
+        } else {
+          fileContent += `        ${attachmentName}: {type: ${JSON.stringify(attachmentType)}},\n`
+        }
       }
       fileContent += "      },\n"
     }
@@ -857,7 +869,8 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     try {
       const modelClass = resourceClass.modelClass()
 
-      const instance = new resourceClass({
+      const ResourceClass = frontendModelResourceInternalConstructor(resourceClass)
+      const instance = new ResourceClass({
         ability: undefined,
         context: {},
         locals: {},
@@ -894,7 +907,8 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     try {
       const modelClass = resourceClass.modelClass()
 
-      const instance = new resourceClass({
+      const ResourceClass = frontendModelResourceInternalConstructor(resourceClass)
+      const instance = new ResourceClass({
         ability: undefined,
         context: {},
         locals: {},

package/src/frontend-model-controller.js

@@ -3,7 +3,7 @@
 import {randomUUID} from "node:crypto"
 import * as inflection from "inflection"
 import Controller from "./controller.js"
-import FrontendModelBaseResource from "./frontend-model-resource/base-resource.js"
+import FrontendModelBaseResource, {frontendModelResourceInternalConstructor} 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, frontendModelSyncManifestForBackendProjects} from "./frontend-models/resource-definition.js"
@@ -70,7 +70,7 @@ import {RansackQueryError, normalizeRansackGroup, parseRansackSort} from "./util
  * @typedef {object} FrontendModelIndexQueryOptions
  * @property {boolean} [includePagination] - Whether frontend-model pagination params should be applied.
  * @property {boolean} [includeSort] - Whether frontend-model sort params should be applied.
- * @property {import("./frontend-model-resource/base-resource.js").default} [resource] - Resource providing query hooks.
+ * @property {Pick<import("./frontend-model-resource/base-resource.js").default<import("./frontend-model-resource/base-resource.js").FrontendModelResourceModelClass>, "applyFrontendModelIndexPagination" | "applyFrontendModelIndexSearch" | "applyFrontendModelIndexSort">} [resource] - Resource providing query hooks.
  */
 /** @typedef {import("./database/query/model-class-query.js").default & Record<symbol, Set<string> | undefined>} FrontendModelQueryMetadata */
 /**
@@ -1040,7 +1040,9 @@ export default class FrontendModelController extends Controller {
       resourceConfiguration: frontendModelResource.resourceConfiguration
     }
 
-    return new frontendModelResource.resourceClass(resourceArgs)
+    const ResourceClass = frontendModelResourceInternalConstructor(frontendModelResource.resourceClass)
+
+    return new ResourceClass(resourceArgs)
   }
 
   /**
@@ -2908,7 +2910,9 @@ export default class FrontendModelController extends Controller {
         const resourceClass = resourceDefinition ? frontendModelResourceClassFromDefinition(resourceDefinition) : null
 
         if (resourceClass) {
-          resource = new resourceClass({
+          const ResourceClass = frontendModelResourceInternalConstructor(resourceClass)
+
+          resource = new ResourceClass({
             ability: this.currentAbility(),
             // Propagate the controller so a related/preloaded model's serialization
             // resource can use request context (e.g. `requestBaseUrl()` for signed
@@ -3985,7 +3989,8 @@ export default class FrontendModelController extends Controller {
 
     if (!frontendModelResource) throw frontendSyncReplaySafeError(`Sync replay model is not enabled: ${mutation.model}`)
 
-    const resource = new frontendModelResource.resourceClass({
+    const ResourceClass = frontendModelResourceInternalConstructor(frontendModelResource.resourceClass)
+    const resource = new ResourceClass({
       ability: this.currentAbility(),
       controller: this,
       context: {

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

@@ -5,6 +5,11 @@ import * as inflection from "inflection"
 import isPlainObject from "../utils/plain-object.js"
 import VelociousError from "../velocious-error.js"
 
+/**
+ * Backend or frontend model class bound to a frontend-model resource.
+ * @typedef {import("../authorization/base-resource.js").AuthorizationResourceModelClass & {attachmentDefinitions: () => Record<string, import("../configuration-types.js").FrontendModelAttachmentConfiguration>, primaryKey: () => string}} FrontendModelResourceModelClass
+ */
+
 /**
  * Built-in frontend-model resource action.
  * @typedef {"index" | "find" | "create" | "update" | "destroy" | "attach" | "attachmentList" | "download" | "url"} FrontendModelResourceAction
@@ -20,7 +25,7 @@ import VelociousError from "../velocious-error.js"
  *   frontendModelAbilityAction: (action: FrontendModelResourceAction) => string,
  *   frontendModelAbilityAuthorizedQuery: (action: FrontendModelResourceAction) => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
  *   frontendModelAuthorizedQuery: (action: FrontendModelResourceAction) => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
- *   frontendModelIndexQuery: (options?: FrontendModelResourceIndexQueryOptions & {resource?: FrontendModelBaseResource}) => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
+ *   frontendModelIndexQuery: (options?: FrontendModelResourceIndexQueryOptions & {resource?: Pick<FrontendModelBaseResource<FrontendModelResourceModelClass>, "applyFrontendModelIndexPagination" | "applyFrontendModelIndexSearch" | "applyFrontendModelIndexSort">}) => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
  *   frontendModelParams: () => import("../configuration-types.js").VelociousParams,
  *   frontendModelPreload: () => import("../database/query/index.js").NestedPreloadRecord | null,
  *   frontendModelResourceConfigurationForModelClass: (modelClass: typeof import("../database/record/index.js").default) => FrontendModelResolvedResourceConfiguration | null,
@@ -68,9 +73,10 @@ import VelociousError from "../velocious-error.js"
 
 /**
  * FrontendModelResourceControllerArgs type.
+ * @template {typeof import("../database/record/index.js").default} [TDatabaseModelClass=typeof import("../database/record/index.js").default]
  * @typedef {object} FrontendModelResourceControllerArgs
  * @property {FrontendModelResourceController} controller - Frontend-model controller instance.
- * @property {typeof import("../database/record/index.js").default} modelClass - Backing model class.
+ * @property {TDatabaseModelClass} modelClass - Backing model class.
  * @property {string} modelName - Model name.
  * @property {import("../configuration-types.js").VelociousParams} params - Request params.
  * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | import("../configuration-types.js").FrontendModelResourceConfiguration} resourceConfiguration - Normalized resource configuration (or raw input shape during early bootstrap).
@@ -78,17 +84,26 @@ import VelociousError from "../velocious-error.js"
 
 /**
  * FrontendModelResourceAbilityArgs type.
+ * @template {FrontendModelResourceModelClass} [TModelClass=FrontendModelResourceModelClass]
  * @typedef {object} FrontendModelResourceAbilityArgs
  * @property {import("../authorization/ability.js").default} [ability] - Ability instance when the resource is used directly for authorization.
  * @property {import("../configuration.js").default} [configuration] - Velocious configuration for controller-less construction (for example the sync websocket channel); the controller path derives it from the controller instead.
  * @property {import("../configuration-types.js").VelociousLooseObject} [context] - Ability context.
  * @property {import("../configuration-types.js").VelociousLooseObject} [locals] - Ability locals.
- * @property {typeof import("../database/record/index.js").default} [modelClass] - Optional backing model class override.
+ * @property {TModelClass} [modelClass] - Optional backing model class override.
  * @property {string} [modelName] - Optional model name override.
  * @property {import("../configuration-types.js").VelociousParams} [params] - Optional params override.
  * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | import("../configuration-types.js").FrontendModelResourceConfiguration} [resourceConfiguration] - Optional normalized resource configuration.
  */
 
+/**
+ * Internal constructor contract used when a resource instantiates its shared
+ * counterpart across the frontend/backend model boundary.
+ * @template {FrontendModelResourceModelClass} TModelClass
+ * @template {typeof import("../database/record/index.js").default} TDatabaseModelClass
+ * @typedef {{new (args: FrontendModelResourceAbilityArgs<FrontendModelResourceModelClass> | FrontendModelResourceControllerArgs): FrontendModelBaseResource<TModelClass, TDatabaseModelClass>}} FrontendModelResourceInternalConstructor
+ */
+
 /**
  * Normalized sync replay mutation passed to the resource sync hooks.
  * @typedef {import("../sync/sync-envelope-replay-service.js").SyncReplayMutation} FrontendModelSyncMutation
@@ -163,19 +178,30 @@ import VelociousError from "../velocious-error.js"
  * @typedef {FrontendModelResourceAttributePayload & {id?: string | number, _destroy?: boolean, attributes?: FrontendModelResourceAttributePayload, attachments?: FrontendModelResourceAttributePayload, nestedAttributes?: FrontendModelResourceAttributePayload}} FrontendModelResourceNestedEntry
  */
 
+/**
+ * Narrows an unbound resource registry entry at framework-owned construction
+ * sites where the backing database model has already been resolved.
+ * @param {import("../configuration-types.js").FrontendModelResourceClassType} ResourceClass - Unbound resource class.
+ * @returns {FrontendModelResourceInternalConstructor<typeof import("../database/record/index.js").default, typeof import("../database/record/index.js").default>} Runtime constructor.
+ */
+export function frontendModelResourceInternalConstructor(ResourceClass) {
+  return /** @type {FrontendModelResourceInternalConstructor<typeof import("../database/record/index.js").default, typeof import("../database/record/index.js").default>} */ (/** @type {unknown} */ (ResourceClass))
+}
+
 /**
  * Base class for backend frontend-model resources.
- * @template {typeof import("../database/record/index.js").default} [TModelClass=typeof import("../database/record/index.js").default]
+ * @template {FrontendModelResourceModelClass} [TModelClass=typeof import("../database/record/index.js").default]
+ * @template {typeof import("../database/record/index.js").default} [TDatabaseModelClass=Extract<TModelClass, typeof import("../database/record/index.js").default>]
  */
 export default class FrontendModelBaseResource extends AuthorizationBaseResource {
-  /** @type {typeof import("../database/record/index.js").default | undefined} */
+  /** @type {FrontendModelResourceModelClass | undefined} */
   static ModelClass = undefined
 
   /** @type {Record<string, ReturnType<typeof JSON.parse>> | string[] | undefined} */
   static attributes = undefined
   /** @type {string[] | undefined} */
   static abilities = undefined
-  /** @type {Record<string, ReturnType<typeof JSON.parse>> | undefined} */
+  /** @type {Record<string, import("../configuration-types.js").FrontendModelAttachmentConfiguration> | undefined} */
   static attachments = undefined
   /** @type {string[] | undefined} */
   static commands = undefined
@@ -214,7 +240,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
 
   /**
    * Runs constructor.
-   * @param {FrontendModelResourceAbilityArgs | FrontendModelResourceControllerArgs} args - Resource args.
+   * @param {FrontendModelResourceAbilityArgs<TModelClass> | FrontendModelResourceControllerArgs<TDatabaseModelClass>} args - Resource args.
    */
   constructor(args) {
     super({
@@ -223,16 +249,18 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       locals: "locals" in args ? args.locals || {} : {}
     })
 
-    const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (this.constructor)
+    // Narrows the subclass static side to the model class carried by this resource generic.
+    const ResourceClass = /** @type {typeof FrontendModelBaseResource & {ModelClass: TModelClass | undefined, modelClass: () => TModelClass}} */ (this.constructor)
     const defaultResourceConfiguration = /** @type {import("../configuration-types.js").FrontendModelResourceConfiguration} */ ({attributes: []})
 
     this.controller = "controller" in args ? args.controller : undefined
     this.configurationValue = "configuration" in args ? args.configuration : undefined
-    this.modelClassValue = "modelClass" in args ? args.modelClass : ResourceClass.modelClass()
+    // Narrows the internal controller/shared-resource construction path to the resource's declared model generic.
+    this.modelClassValue = /** @type {TModelClass} */ ("modelClass" in args ? args.modelClass : ResourceClass.modelClass())
     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} */
+    /** @type {FrontendModelBaseResource<TModelClass, TDatabaseModelClass> | null | undefined} */
     this.sharedResourceInstanceValue = undefined
   }
 
@@ -269,15 +297,37 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     return /** @type {string[] | undefined} */ (this.sharedResourceStaticValue("translatedAttributes"))
   }
 
+  /**
+   * Resolves frontend-safe attachment declarations from the backing model.
+   * Resource-level declarations remain as a fallback for frontend-only resources.
+   * @returns {Record<string, import("../configuration-types.js").FrontendModelAttachmentConfiguration>} - Client attachment configuration keyed by name.
+   */
+  static attachmentConfigurations() {
+    const configuredAttachments = /** @type {Record<string, import("../configuration-types.js").FrontendModelAttachmentConfiguration> | undefined} */ (this.sharedResourceStaticValue("attachments"))
+    const attachments = configuredAttachments ? {...configuredAttachments} : {}
+
+    if (!this.ModelClass) return attachments
+
+    for (const [attachmentName, definition] of Object.entries(this.ModelClass.attachmentDefinitions())) {
+      const attachmentConfig = /** @type {import("../configuration-types.js").FrontendModelAttachmentConfiguration} */ ({type: definition.type})
+
+      if (definition.sync) attachmentConfig.sync = {...definition.sync}
+
+      attachments[attachmentName] = attachmentConfig
+    }
+
+    return attachments
+  }
+
   /**
    * Builds a resource instance for shared-resource fallback calls.
-   * @returns {FrontendModelBaseResource | null} - Shared resource instance when configured.
+   * @returns {FrontendModelBaseResource<TModelClass, TDatabaseModelClass> | 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())
+    const ResourceClass = /** @type {import("../configuration-types.js").FrontendModelResourceClassType<TModelClass, TDatabaseModelClass>} */ (this.constructor)
+    const SharedResource = /** @type {import("../configuration-types.js").FrontendModelResourceClassType<TModelClass, TDatabaseModelClass> | undefined} */ (ResourceClass.sharedResourceClass())
 
     if (!SharedResource) {
       this.sharedResourceInstanceValue = null
@@ -288,7 +338,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       throw new Error(`${ResourceClass.name}.SharedResource cannot point to itself.`)
     }
 
-    this.sharedResourceInstanceValue = new SharedResource({
+    const SharedResourceConstructor = /** @type {FrontendModelResourceInternalConstructor<TModelClass, TDatabaseModelClass>} */ (/** @type {unknown} */ (SharedResource))
+    const sharedResource = new SharedResourceConstructor({
       ability: this.ability,
       controller: this.controller,
       context: this.context,
@@ -298,8 +349,9 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       params: this.params(),
       resourceConfiguration: this.resourceConfiguration()
     })
+    this.sharedResourceInstanceValue = sharedResource
 
-    return this.sharedResourceInstanceValue
+    return sharedResource
   }
 
   /**
@@ -343,7 +395,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * 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.
+   * @returns {{method: (...methodArgs: unknown[]) => unknown, resource: FrontendModelBaseResource<TModelClass, TDatabaseModelClass>} | null} - Resolved method and receiver.
    */
   resourceMethod(methodName) {
     const ownMethod = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (this))[methodName]
@@ -392,7 +444,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   static resourceConfig() {
     const attributes = this.sharedResourceStaticValue("attributes")
     const abilities = this.sharedResourceStaticValue("abilities")
-    const attachments = this.sharedResourceStaticValue("attachments")
+    const attachments = this.attachmentConfigurations()
     const commands = this.sharedResourceStaticValue("commands")
     const builtInCollectionCommands = this.sharedResourceStaticValue("builtInCollectionCommands")
     const builtInMemberCommands = this.sharedResourceStaticValue("builtInMemberCommands")
@@ -409,7 +461,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     }
 
     if (abilities) config.abilities = /** @type {string[]} */ (abilities)
-    if (attachments) config.attachments = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (attachments)
+    if (Object.keys(attachments).length > 0) config.attachments = attachments
     if (commands) config.commands = /** @type {string[]} */ (commands)
     if (builtInCollectionCommands) config.builtInCollectionCommands = /** @type {string[]} */ (builtInCollectionCommands)
     if (builtInMemberCommands) config.builtInMemberCommands = /** @type {string[]} */ (builtInMemberCommands)
@@ -424,16 +476,6 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     return config
   }
 
-  /**
-   * Runs static model class.
-   * @returns {typeof import("../database/record/index.js").default} - Backing model class.
-   */
-  static modelClass() {
-    if (!this.ModelClass) throw new Error(`${this.name} requires a static ModelClass.`)
-
-    return this.ModelClass
-  }
-
   /**
    * Runs controller instance.
    * @returns {import("../controller.js").default} - Controller instance.
@@ -466,7 +508,16 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       throw new Error(`${this.constructor.name} requires a model class.`)
     }
 
-    return /** @type {TModelClass} */ (this.modelClassValue)
+    return this.modelClassValue
+  }
+
+  /**
+   * Returns the database model class used by server-only resource operations.
+   * @returns {TDatabaseModelClass} - Database model class.
+   */
+  databaseModelClass() {
+    // Narrows the portable resource generic at the explicit backend-operation boundary.
+    return /** @type {TDatabaseModelClass} */ (/** @type {unknown} */ (this.modelClass()))
   }
 
   /**
@@ -619,7 +670,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {Promise<import("../database/record/index.js").default | null>} Existing record or null.
    */
   async findSyncRecord({ability = this.ability, forDelete = false, mutation}) {
-    const ModelClass = this.modelClass()
+    const ModelClass = this.databaseModelClass()
     const primaryKey = ModelClass.primaryKey()
     const query = ability
       ? ModelClass.accessibleFor(this.syncAbilityAction(forDelete ? "destroy" : "update"), ability)
@@ -819,20 +870,20 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Runs authorized query.
    * @param {FrontendModelResourceAction} action - Ability action.
-   * @returns {import("../database/query/model-class-query.js").default<TModelClass>} - Authorized query.
+   * @returns {import("../database/query/model-class-query.js").default<TDatabaseModelClass>} - Authorized query.
    */
   authorizedQuery(action) {
     // Narrows the controller query to this resource's model class.
-    return /** @type {import("../database/query/model-class-query.js").default<TModelClass>} */ (this.typedControllerInstance().frontendModelAbilityAuthorizedQuery(action))
+    return /** @type {import("../database/query/model-class-query.js").default<TDatabaseModelClass>} */ (this.typedControllerInstance().frontendModelAbilityAuthorizedQuery(action))
   }
 
   /**
    * Runs index query.
    * @param {FrontendModelResourceIndexQueryOptions} [options] - Query options.
-   * @returns {import("../database/query/model-class-query.js").default<TModelClass>} - Frontend-model index query.
+   * @returns {import("../database/query/model-class-query.js").default<TDatabaseModelClass>} - Frontend-model index query.
    */
   indexQuery(options = {}) {
-    return /** @type {import("../database/query/model-class-query.js").default<TModelClass>} */ (this.typedControllerInstance().frontendModelIndexQuery({
+    return /** @type {import("../database/query/model-class-query.js").default<TDatabaseModelClass>} */ (this.typedControllerInstance().frontendModelIndexQuery({
       ...options,
       resource: this
     }))
@@ -961,8 +1012,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     const normalizedAttributes = await this.normalizeCreateAttributes(attributes, options)
     const attachmentSplit = this._extractAttachmentAttributes(normalizedAttributes, options.attachments ?? null)
     const permit = parsePermittedParams(this.permittedParams({action: "create", ability: this.ability, locals: this.locals, params: normalizedAttributes}))
-    const ModelClass = this.modelClass()
-    const filtered = filterWritableFrontendModelAttributes(this.modelClass().prototype, ModelClass, attachmentSplit.attributes, this, permit.attributes)
+    const ModelClass = this.databaseModelClass()
+    const filtered = filterWritableFrontendModelAttributes(ModelClass.prototype, ModelClass, attachmentSplit.attributes, this, permit.attributes)
     const model = new ModelClass()
 
     return await this.runMutationTransaction({
@@ -1021,7 +1072,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {Promise<import("../database/record/index.js").default>} - Saved model.
    */
   async _saveWithNestedAttributes({filtered, model, options, permit}) {
-    await this.modelClass().transaction(async () => {
+    await this.databaseModelClass().transaction(async () => {
       await this._assignWithVirtualSetters(model, filtered)
       this._assignAttachments(model, options.attachments ?? null, permit.attributes)
 
@@ -1079,7 +1130,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {{attributes: Record<string, ReturnType<typeof JSON.parse>>, attachments: Record<string, ReturnType<typeof JSON.parse>> | null}} Attributes with attachment keys removed and merged attachment payload.
    */
   _extractAttachmentAttributes(attributes, attachments) {
-    const attachmentDefinitions = this.modelClass().getAttachmentsMap()
+    const attachmentDefinitions = this.modelClass().attachmentDefinitions()
     const attachmentNames = new Set(Object.keys(attachmentDefinitions))
 
     if (attachmentNames.size === 0) return {attributes, attachments}
@@ -1272,7 +1323,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       throw new Error(`No frontend-model resource registered for child model '${targetModelClass.getModelName()}' under relationship '${relationshipName}'.`)
     }
 
-    const childResource = new childResourceConfig.resourceClass({
+    const ChildResource = frontendModelResourceInternalConstructor(childResourceConfig.resourceClass)
+    const childResource = new ChildResource({
       ability: this.ability,
       controller,
       context: this.context || {},
@@ -1934,10 +1986,12 @@ function prototypeOwnerForMethod(instance, methodName) {
 
 /**
  * Runs filter writable frontend model attributes.
+ * @template {FrontendModelResourceModelClass} ResourceModelClass
+ * @template {typeof import("../database/record/index.js").default} ResourceDatabaseModelClass
  * @param {Record<string, ReturnType<typeof JSON.parse>>} receiver - Model instance or prototype.
  * @param {WritableAttributeReceiverClass} receiverClass - Static helper owner for the receiver.
  * @param {Record<string, ReturnType<typeof JSON.parse>>} attributes - Incoming frontend-model attributes.
- * @param {FrontendModelBaseResource | null} [resource] - Resource instance for virtual-setter detection.
+ * @param {FrontendModelBaseResource<ResourceModelClass, ResourceDatabaseModelClass> | null} [resource] - Resource instance for virtual-setter detection.
  * @param {string[] | null} [permittedAttributeNames] - Optional explicit permit list. `null` falls back to setter-existence checks only.
  * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Writable attributes only.
  */
@@ -1945,7 +1999,7 @@ function filterWritableFrontendModelAttributes(
   receiver,
   receiverClass,
   attributes,
-  resource = /** @type {FrontendModelBaseResource | null} */ (null),
+  resource = /** @type {FrontendModelBaseResource<ResourceModelClass, ResourceDatabaseModelClass> | null} */ (null),
   permittedAttributeNames = null
 ) {
   // Frontend-model writes should fail fast when callers submit read-only or unknown attrs.

package/src/frontend-models/base.js

@@ -66,7 +66,7 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  */
 /**
  * Defines this typedef.
- * @typedef {{type: "hasOne" | "hasMany"}} FrontendModelAttachmentDefinition
+ * @typedef {{sync?: import("../configuration-types.js").AttachmentSyncConfiguration, type: "hasOne" | "hasMany"}} FrontendModelAttachmentDefinition
  */
 /**
  * Defines frontend-model attribute metadata.

package/src/sync/sync-api-controller.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import Controller from "../controller.js"
-import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
+import FrontendModelBaseResource, {frontendModelResourceInternalConstructor} from "../frontend-model-resource/base-resource.js"
 
 /** Configurations whose sync.api routes have already been mounted. */
 const mountedConfigurations = new WeakSet()
@@ -41,9 +41,10 @@ export default class SyncApiController extends Controller {
    */
   syncResource(params) {
     const ResourceClass = this.syncResourceClass()
+    const ResourceConstructor = frontendModelResourceInternalConstructor(ResourceClass)
     const ability = this.currentAbility()
 
-    return new ResourceClass({
+    return new ResourceConstructor({
       ability,
       controller: /** @type {import("../frontend-model-resource/base-resource.js").FrontendModelResourceController} */ (/** @type {unknown} */ (this)),
       context: {
@@ -137,7 +138,7 @@ export default class SyncApiController extends Controller {
    * @returns {import("../configuration-types.js").FrontendModelResourceClassType} Sync resource class.
    */
   missingSyncResourceClass() {
-    return /** @type {typeof FrontendModelBaseResource} */ (/** @type {unknown} */ (this.raiseMissingSyncResourceClass()))
+    return /** @type {import("../configuration-types.js").FrontendModelResourceClassType} */ (/** @type {unknown} */ (this.raiseMissingSyncResourceClass()))
   }
 
   /** Raises a configuration error for subclasses that do not provide a resource. */
@@ -155,7 +156,7 @@ export default class SyncApiController extends Controller {
 
     if (!modelClass) throw new Error("Sync resource class must define static ModelClass")
 
-    return modelClass
+    return /** @type {typeof import("../database/record/index.js").default} */ (/** @type {unknown} */ (modelClass))
   }
 
   /**
@@ -178,4 +179,3 @@ export default class SyncApiController extends Controller {
     })
   }
 }
-

package/src/sync/sync-envelope-replay-service.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import {deliverDeclaredBroadcasts, upsertSyncRow} from "./sync-change-fanout.js"
+import {frontendModelResourceInternalConstructor} from "../frontend-model-resource/base-resource.js"
 import {markServerApply} from "./sync-publish-suppression.js"
 import {resolveFrontendModelResourceClass} from "../frontend-models/resource-definition.js"
 import {resolveSyncConflict} from "./conflict-strategy.js"
@@ -567,7 +568,7 @@ export default class SyncEnvelopeReplayService {
    * @returns {Promise<import("../frontend-model-resource/base-resource.js").default>} Routed resource instance.
    */
   async buildReplayResource({actor, context, mutation, registration}) {
-    const ResourceClass = registration.resourceClass
+    const ResourceClass = frontendModelResourceInternalConstructor(registration.resourceClass)
     const {ability, abilityContext} = await this.replayAbilityFor({actor, context})
 
     return new ResourceClass({