velocious 1.0.448 → 1.0.450

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

@@ -4,10 +4,29 @@ import AuthorizationBaseResource from "../authorization/base-resource.js"
 import * as inflection from "inflection"
 import isPlainObject from "../utils/plain-object.js"
 
+/**
+ * Built-in frontend-model resource action.
+ * @typedef {"index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url"} FrontendModelResourceAction
+ */
+
+/**
+ * Frontend-model controller methods used by resources.
+ * @typedef {import("../controller.js").default & {
+ *   currentAbility: () => import("../authorization/ability.js").default | undefined,
+ *   frontendModelAbilityAction: (action: FrontendModelResourceAction) => string,
+ *   frontendModelAuthorizedQuery: (action: FrontendModelResourceAction) => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
+ *   frontendModelIndexQuery: () => 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,
+ *   serializeFrontendModel: (model: import("../database/record/index.js").default) => Promise<Record<string, object | string | number | boolean | null>>
+ * }} FrontendModelResourceController
+ */
+
 /**
  * FrontendModelResourceControllerArgs type.
  * @typedef {object} FrontendModelResourceControllerArgs
- * @property {import("../controller.js").default} controller - Frontend-model controller instance.
+ * @property {FrontendModelResourceController} controller - Frontend-model controller instance.
  * @property {typeof import("../database/record/index.js").default} modelClass - Backing model class.
  * @property {string} modelName - Model name.
  * @property {import("../configuration-types.js").VelociousParams} params - Request params.
@@ -35,51 +54,68 @@ import isPlainObject from "../utils/plain-object.js"
  * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration} resourceConfiguration - Normalized resource configuration.
  */
 
+/**
+ * Transport-safe value accepted in frontend-model resource mutation payloads.
+ * Nested object/array values are intentionally opaque because TypeScript rejects
+ * recursive JSDoc typedefs for this transport payload contract.
+ * @typedef {import("../frontend-models/base.js").FrontendModelTransportValue | import("../database/record/index.js").default | Record<string, unknown> | Array<unknown>} FrontendModelResourcePayloadValue
+ */
+
+/**
+ * Attribute payload accepted by frontend-model resource mutations.
+ * @typedef {Record<string, FrontendModelResourcePayloadValue>} FrontendModelResourceAttributePayload
+ */
+
+/**
+ * Virtual setter method on a frontend-model resource.
+ * @typedef {function(import("../database/record/index.js").default, FrontendModelResourcePayloadValue): (void | Promise<void>)} FrontendModelResourceVirtualSetter
+ */
+
+/**
+ * Static helpers used when checking whether a model-like receiver accepts an attribute.
+ * @typedef {object} WritableAttributeReceiverClass
+ * @property {function(string): string} [resolveAttributeName] - Resolves aliases to canonical attribute names.
+ * @property {function(Record<string, ?>, string): string} [findMemberNameInsensitive] - Locates a setter method on the receiver.
+ */
+
+/**
+ * Options passed while saving frontend-model resource mutations.
+ * @typedef {object} FrontendModelResourceSaveOptions
+ * @property {FrontendModelResourceAttributePayload | null} [attachments] - Uploaded attachment attributes.
+ * @property {FrontendModelResourceController | null} [controller] - Controller handling the mutation.
+ * @property {FrontendModelResourceAttributePayload | null} [nestedAttributes] - Nested attributes payload.
+ */
+
+/**
+ * Normalized nested attributes entry.
+ * @typedef {FrontendModelResourceAttributePayload & {id?: string | number, _destroy?: boolean, attributes?: FrontendModelResourceAttributePayload, attachments?: FrontendModelResourceAttributePayload, nestedAttributes?: FrontendModelResourceAttributePayload}} FrontendModelResourceNestedEntry
+ */
+
 /**
  * Base class for backend frontend-model resources.
  * @template {typeof import("../database/record/index.js").default} [TModelClass=typeof import("../database/record/index.js").default]
  */
 export default class FrontendModelBaseResource extends AuthorizationBaseResource {
-  /**
-   * Backing model class.
-    @type {typeof import("../database/record/index.js").default | undefined} */
+  /** @type {typeof import("../database/record/index.js").default | undefined} */
   static ModelClass = undefined
 
-  /**
-   * Attributes.
-    @type {Record<string, ?> | string[] | undefined} */
+  /** @type {Record<string, ?> | string[] | undefined} */
   static attributes = undefined
-  /**
-   * Abilities.
-    @type {string[] | undefined} */
+  /** @type {string[] | undefined} */
   static abilities = undefined
-  /**
-   * Attachments.
-    @type {Record<string, ?> | undefined} */
+  /** @type {Record<string, ?> | undefined} */
   static attachments = undefined
-  /**
-   * Collection commands.
-    @type {string[] | undefined} */
+  /** @type {string[] | undefined} */
   static collectionCommands = undefined
-  /**
-   * Built in collection commands.
-    @type {string[] | undefined} */
+  /** @type {string[] | undefined} */
   static builtInCollectionCommands = undefined
-  /**
-   * Member commands.
-    @type {string[] | undefined} */
+  /** @type {string[] | undefined} */
   static memberCommands = undefined
-  /**
-   * Built in member commands.
-    @type {string[] | undefined} */
+  /** @type {string[] | undefined} */
   static builtInMemberCommands = undefined
-  /**
-   * Relationships.
-    @type {string[] | undefined} */
+  /** @type {string[] | undefined} */
   static relationships = undefined
-  /**
-   * Translated attributes.
-    @type {string[] | undefined} */
+  /** @type {string[] | undefined} */
   static translatedAttributes = undefined
 
   /**
@@ -93,32 +129,22 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       locals: "locals" in args ? args.locals || {} : {}
     })
 
+    const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (this.constructor)
+    const defaultResourceConfiguration = /** @type {import("../configuration-types.js").FrontendModelResourceConfiguration} */ ({attributes: []})
+
     this.controller = "controller" in args ? args.controller : undefined
-    this.modelClassValue = "modelClass" in args ? args.modelClass : /**
-                                                                     * Narrows the runtime value to the documented type.
-                                                                      @type {typeof import("../database/record/index.js").default | undefined} */ (/**
-                                                                                                                                                    * Narrows the runtime value to the documented type.
-                                                                                                                                                     @type {typeof FrontendModelBaseResource} */ (this.constructor).modelClass())
+    this.modelClassValue = "modelClass" in args ? args.modelClass : ResourceClass.modelClass()
     this.modelNameValue = "modelName" in args ? args.modelName : (this.modelClassValue?.getModelName ? this.modelClassValue.getModelName() : this.modelClassValue?.name || "")
     this.paramsValue = "params" in args ? args.params : undefined
-    this.resourceConfigurationValue = "resourceConfiguration" in args ? args.resourceConfiguration : /**
-                                                                                                      * Narrows the runtime value to the documented type.
-                                                                                                       @type {import("../configuration-types.js").FrontendModelResourceConfiguration} */ ({attributes: []})
+    this.resourceConfigurationValue = "resourceConfiguration" in args ? args.resourceConfiguration : defaultResourceConfiguration
   }
 
   /**
    * Runs typed controller instance.
-   * @returns {import("../controller.js").default & {
-   *   frontendModelAuthorizedQuery: (action: "index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url") => import("../database/query/model-class-query.js").default<TModelClass>,
-   *   frontendModelAbilityAction: (action: string) => string,
-   *   currentAbility: () => import("../authorization/ability.js").default | undefined,
-   *   frontendModelIndexQuery: () => import("../database/query/model-class-query.js").default<TModelClass>,
-   *   frontendModelPreload: () => import("../database/query/index.js").NestedPreloadRecord | null,
-   *   serializeFrontendModel: (model: import("../database/record/index.js").default) => Promise<Record<string, unknown>>
-   * }} - Controller instance with frontend-model helpers.
+   * @returns {FrontendModelResourceController} - Controller instance with frontend-model helpers.
    */
   typedControllerInstance() {
-    return /** Narrows the runtime value to the documented type. @type {?} */ (this.controller)
+    return /** @type {FrontendModelResourceController} */ (this.controller)
   }
 
   /**
@@ -126,9 +152,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {import("../configuration-types.js").FrontendModelResourceConfiguration} - Static resource config (raw user input shape; consumers normalize).
    */
   static resourceConfig() {
-    /**
-     * Config.
-      @type {import("../configuration-types.js").FrontendModelResourceConfiguration} */
+    /** @type {import("../configuration-types.js").FrontendModelResourceConfiguration} */
     const config = {
       attributes: this.attributes || []
     }
@@ -244,6 +268,118 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     return []
   }
 
+  /**
+   * Normalizes create attributes before permission filtering and saving.
+   * @param {FrontendModelResourceAttributePayload} attributes - Incoming create attributes.
+   * @param {FrontendModelResourceSaveOptions} options - Save options.
+   * @returns {FrontendModelResourceAttributePayload | Promise<FrontendModelResourceAttributePayload>} - Normalized attributes.
+   */
+  normalizeCreateAttributes(attributes, options) {
+    void options
+
+    return attributes
+  }
+
+  /**
+   * Normalizes update attributes before permission filtering and saving.
+   * @param {import("../database/record/index.js").default} model - Existing model.
+   * @param {FrontendModelResourceAttributePayload} attributes - Incoming update attributes.
+   * @param {FrontendModelResourceSaveOptions} options - Save options.
+   * @returns {FrontendModelResourceAttributePayload | Promise<FrontendModelResourceAttributePayload>} - Normalized attributes.
+   */
+  normalizeUpdateAttributes(model, attributes, options) {
+    void model
+    void options
+
+    return attributes
+  }
+
+  /**
+   * Runs before create.
+   * @param {import("../database/record/index.js").default} model - New model before assignment/save.
+   * @param {FrontendModelResourceAttributePayload} attributes - Normalized create attributes.
+   * @param {FrontendModelResourceSaveOptions} options - Save options.
+   * @returns {void | Promise<void>} - Resolves when the hook finishes.
+   */
+  beforeCreate(model, attributes, options) {
+    void model
+    void attributes
+    void options
+  }
+
+  /**
+   * Runs after create.
+   * @param {import("../database/record/index.js").default} model - Created model.
+   * @param {FrontendModelResourceAttributePayload} attributes - Normalized create attributes.
+   * @param {FrontendModelResourceSaveOptions} options - Save options.
+   * @returns {void | Promise<void>} - Resolves when the hook finishes.
+   */
+  afterCreate(model, attributes, options) {
+    void model
+    void attributes
+    void options
+  }
+
+  /**
+   * Runs before update.
+   * @param {import("../database/record/index.js").default} model - Existing model before assignment/save.
+   * @param {FrontendModelResourceAttributePayload} attributes - Normalized update attributes.
+   * @param {FrontendModelResourceSaveOptions} options - Save options.
+   * @returns {void | Promise<void>} - Resolves when the hook finishes.
+   */
+  beforeUpdate(model, attributes, options) {
+    void model
+    void attributes
+    void options
+  }
+
+  /**
+   * Runs after update.
+   * @param {import("../database/record/index.js").default} model - Updated model.
+   * @param {FrontendModelResourceAttributePayload} attributes - Normalized update attributes.
+   * @param {FrontendModelResourceSaveOptions} options - Save options.
+   * @returns {void | Promise<void>} - Resolves when the hook finishes.
+   */
+  afterUpdate(model, attributes, options) {
+    void model
+    void attributes
+    void options
+  }
+
+  /**
+   * Runs before destroy.
+   * @param {import("../database/record/index.js").default} model - Model before destroy.
+   * @returns {void | Promise<void>} - Resolves when the hook finishes.
+   */
+  beforeDestroy(model) {
+    void model
+  }
+
+  /**
+   * Runs after destroy.
+   * @param {import("../database/record/index.js").default} model - Destroyed model.
+   * @returns {void | Promise<void>} - Resolves when the hook finishes.
+   */
+  afterDestroy(model) {
+    void model
+  }
+
+  /**
+   * Wraps create/update/destroy resource mutations.
+   * @template Result
+   * @param {object} args - Transaction args.
+   * @param {"create" | "update" | "destroy"} args.action - Mutation action.
+   * @param {import("../database/record/index.js").default} args.model - Mutated model.
+   * @param {() => Promise<Result>} args.callback - Mutation callback.
+   * @returns {Promise<Result>} - Callback result.
+   */
+  async runMutationTransaction({action, model, callback}) {
+    void action
+    void model
+
+    return await callback()
+  }
+
   /**
    * Runs primary key.
    * @returns {string} - Primary key.
@@ -252,11 +388,12 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
 
   /**
    * Runs authorized query.
-   * @param {"index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url"} action - Ability action.
+   * @param {FrontendModelResourceAction} action - Ability action.
    * @returns {import("../database/query/model-class-query.js").default<TModelClass>} - Authorized query.
    */
   authorizedQuery(action) {
-    return this.typedControllerInstance().frontendModelAuthorizedQuery(action)
+    // Narrows the controller query to this resource's model class.
+    return /** @type {import("../database/query/model-class-query.js").default<TModelClass>} */ (this.typedControllerInstance().frontendModelAuthorizedQuery(action))
   }
 
 
@@ -329,18 +466,30 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
 
   /**
    * Runs create.
-   * @param {Record<string, ?>} attributes - Create attributes.
-   * @param {{attachments?: Record<string, ?> | null, controller?: ?, nestedAttributes?: Record<string, ?> | null}} [options] - Save options.
+   * @param {FrontendModelResourceAttributePayload} attributes - Create attributes.
+   * @param {FrontendModelResourceSaveOptions} [options] - Save options.
    * @returns {Promise<import("../database/record/index.js").default>} - Created model.
    */
   async create(attributes, options = {}) {
-    const attachmentSplit = this._extractAttachmentAttributes(attributes, options.attachments ?? null)
-    const permit = parsePermittedParams(this.permittedParams({action: "create", ability: this.ability, locals: this.locals, params: attributes}))
+    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 filtered = filterWritableFrontendModelAttributes(this.modelClass().prototype, attachmentSplit.attributes, this, permit.attributes)
     const ModelClass = this.modelClass()
     const model = new ModelClass()
 
-    return await this._saveWithNestedAttributes({filtered, model, options: {...options, attachments: attachmentSplit.attachments}, permit})
+    return await this.runMutationTransaction({
+      action: "create",
+      model,
+      callback: async () => {
+        await this.beforeCreate(model, normalizedAttributes, options)
+        const savedModel = await this._saveWithNestedAttributes({filtered, model, options: {...options, attachments: attachmentSplit.attachments}, permit})
+
+        await this.afterCreate(savedModel, normalizedAttributes, options)
+
+        return savedModel
+      }
+    })
   }
 
   /**
@@ -355,21 +504,33 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Runs update.
    * @param {import("../database/record/index.js").default} model - Existing model.
-   * @param {Record<string, ?>} attributes - Update attributes.
-   * @param {{attachments?: Record<string, ?> | null, controller?: ?, nestedAttributes?: Record<string, ?> | null}} [options] - Save options.
+   * @param {FrontendModelResourceAttributePayload} attributes - Update attributes.
+   * @param {FrontendModelResourceSaveOptions} [options] - Save options.
    * @returns {Promise<import("../database/record/index.js").default>} - Updated model.
    */
   async update(model, attributes, options = {}) {
-    const attachmentSplit = this._extractAttachmentAttributes(attributes, options.attachments ?? null)
-    const permit = parsePermittedParams(this.permittedParams({action: "update", ability: this.ability, locals: this.locals, params: attributes}))
+    const normalizedAttributes = await this.normalizeUpdateAttributes(model, attributes, options)
+    const attachmentSplit = this._extractAttachmentAttributes(normalizedAttributes, options.attachments ?? null)
+    const permit = parsePermittedParams(this.permittedParams({action: "update", ability: this.ability, locals: this.locals, params: normalizedAttributes}))
     const filtered = filterWritableFrontendModelAttributes(model, attachmentSplit.attributes, this, permit.attributes)
 
-    return await this._saveWithNestedAttributes({filtered, model, options: {...options, attachments: attachmentSplit.attachments}, permit})
+    return await this.runMutationTransaction({
+      action: "update",
+      model,
+      callback: async () => {
+        await this.beforeUpdate(model, normalizedAttributes, options)
+        const savedModel = await this._saveWithNestedAttributes({filtered, model, options: {...options, attachments: attachmentSplit.attachments}, permit})
+
+        await this.afterUpdate(savedModel, normalizedAttributes, options)
+
+        return savedModel
+      }
+    })
   }
 
   /**
    * Saves a model and applies nested attributes in one transaction.
-   * @param {{filtered: Record<string, ?>, model: import("../database/record/index.js").default, options: {attachments?: Record<string, ?> | null, controller?: ?, nestedAttributes?: Record<string, ?> | null}, permit: {attributes: string[], nested: Record<string, ?>}}} args - Save arguments.
+   * @param {{filtered: Record<string, ?>, model: import("../database/record/index.js").default, options: FrontendModelResourceSaveOptions, permit: {attributes: string[], nested: Record<string, ?>}}} args - Save arguments.
    * @returns {Promise<import("../database/record/index.js").default>} - Saved model.
    */
   async _saveWithNestedAttributes({filtered, model, options, permit}) {
@@ -400,27 +561,17 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {Promise<void>}
    */
   async _assignWithVirtualSetters(model, attributes) {
-    /**
-     * Direct attributes.
-      @type {Record<string, ?>} */
+    /** @type {Record<string, ?>} */
     const directAttributes = {}
-    const translatedSet = new Set(/**
-                                   * Narrows the runtime value to the documented type.
-                                    @type {typeof FrontendModelBaseResource} */ (this.constructor).translatedAttributes || [])
+    const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (this.constructor)
+    const translatedSet = new Set(ResourceClass.translatedAttributes || [])
 
     for (const [name, value] of Object.entries(attributes)) {
       const resourceSetterName = `set${inflection.camelize(name)}Attribute`
+      const resourceSetter = virtualSetterLookup(this)[resourceSetterName]
 
-      if (typeof /**
-                  * Narrows the runtime value to the documented type.
-                   @type {Record<string, ?>} */ (/**
-                                                  * Narrows the runtime value to the documented type.
-                                                   @type {?} */ (this))[resourceSetterName] === "function") {
-        await /**
-               * Narrows the runtime value to the documented type.
-                @type {Record<string, ?>} */ (/**
-                                               * Narrows the runtime value to the documented type.
-                                                @type {?} */ (this))[resourceSetterName](model, value)
+      if (typeof resourceSetter === "function") {
+        await resourceSetter.call(this, model, value)
       } else if (translatedSet.has(name)) {
         await this._setTranslatedAttributeOnModel(model, name, value)
       } else {
@@ -516,25 +667,21 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * Sets a translated attribute on a model via the translations relationship.
    * @param {import("../database/record/index.js").default} model - Model instance.
    * @param {string} name - Attribute name.
-   * @param {?} value - Attribute value.
+   * @param {FrontendModelResourcePayloadValue} value - Attribute value.
    * @returns {Promise<void>}
    */
   async _setTranslatedAttributeOnModel(model, name, value) {
     const locale = this.context?.configuration?.getLocale?.() || "en"
     const instanceRelationship = model.getRelationshipByName("translations")
 
-    /**
-     * Defines translation.
-      @type {import("../database/record/index.js").default | undefined} */
+    /** @type {import("../database/record/index.js").default | undefined} */
     let translation
 
     if (model.isNewRecord()) {
       const loaded = instanceRelationship.loaded()
 
       if (Array.isArray(loaded)) {
-        translation = loaded.find((/**
-                                    * Narrows the runtime value to the documented type.
-                                     @type {Record<string, ?>} */ t) => t.locale() === locale)
+        translation = loaded.find((t) => /** @type {Record<string, ?>} */ (t).locale() === locale)
       }
     } else {
       if (!instanceRelationship.getPreloaded()) {
@@ -544,9 +691,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       const loaded = instanceRelationship.loaded()
 
       if (Array.isArray(loaded)) {
-        translation = loaded.find((/**
-                                    * Narrows the runtime value to the documented type.
-                                     @type {Record<string, ?>} */ t) => t.locale() === locale)
+        translation = loaded.find((t) => /** @type {Record<string, ?>} */ (t).locale() === locale)
       }
     }
 
@@ -554,9 +699,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       translation = instanceRelationship.build({locale})
     }
 
-    /**
-     * Assignments.
-      @type {Record<string, ?>} */
+    /** @type {Record<string, ?>} */
     const assignments = {}
 
     assignments[name] = value
@@ -569,7 +712,15 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {Promise<void>} - No return value.
    */
   async destroy(model) {
-    await model.destroy()
+    await this.runMutationTransaction({
+      action: "destroy",
+      model,
+      callback: async () => {
+        await this.beforeDestroy(model)
+        await model.destroy()
+        await this.afterDestroy(model)
+      }
+    })
   }
 
   /**
@@ -589,10 +740,10 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @param {object} args - Nested relationship inputs.
    * @param {import("../database/record/index.js").default} args.parent - Parent model instance.
    * @param {string} args.relationshipName - Relationship receiving nested attributes.
-   * @param {?} args.rawEntries - Raw nested entries from the request payload.
+   * @param {FrontendModelResourcePayloadValue} args.rawEntries - Raw nested entries from the request payload.
    * @param {{attributes: string[], nested: Record<string, ?>}} args.childPermit - Parsed child permit.
-   * @param {?} args.controller - Controller instance for child resource lookup.
-   * @returns {{ability: import("../authorization/ability.js").default | undefined, childResource: FrontendModelBaseResource, childResourceConfig: FrontendModelResolvedResourceConfiguration, childWritableAttributes: string[], destroyPermitted: boolean, entries: Array<Record<string, ?>>, relationship: import("../database/record/relationships/base.js").default, targetModelClass: typeof import("../database/record/index.js").default}} Nested relationship context.
+   * @param {FrontendModelResourceController | null | undefined} args.controller - Controller instance for child resource lookup.
+   * @returns {{ability: import("../authorization/ability.js").default | undefined, childResource: FrontendModelBaseResource, childResourceConfig: FrontendModelResolvedResourceConfiguration, childWritableAttributes: string[], destroyPermitted: boolean, entries: Array<FrontendModelResourceNestedEntry>, relationship: import("../database/record/relationships/base.js").default, targetModelClass: typeof import("../database/record/index.js").default}} Nested relationship context.
    */
   _nestedRelationshipContext({parent, relationshipName, rawEntries, childPermit, controller}) {
     const parentModelClass = parent.getModelClass()
@@ -631,7 +782,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
 
     const childResource = new childResourceConfig.resourceClass({
       ability: this.ability,
-      controller,
+      controller: controller || undefined,
       context: this.context || {},
       locals: this.locals || {},
       modelClass: targetModelClass,
@@ -663,10 +814,10 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Normalizes nested entries for collection and singular relationships.
    * @param {object} args - Nested entries inputs.
-   * @param {?} args.rawEntries - Raw nested entries value.
+   * @param {FrontendModelResourcePayloadValue} args.rawEntries - Raw nested entries value.
    * @param {string} args.relationshipName - Relationship name.
    * @param {string} args.relationshipType - Relationship type.
-   * @returns {Array<Record<string, ?>>} Normalized nested entry objects.
+   * @returns {Array<FrontendModelResourceNestedEntry>} Normalized nested entry objects.
    */
   _nestedRelationshipEntries({rawEntries, relationshipName, relationshipType}) {
     if (relationshipType === "hasMany") {
@@ -677,7 +828,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       return rawEntries.map((entry) => {
         if (!isPlainObject(entry)) throw new Error(`nestedAttributes['${relationshipName}'] entries must be objects.`)
 
-        return entry
+        // Narrows the plain-object payload to a normalized nested-entry object.
+        return /** @type {FrontendModelResourceNestedEntry} */ (entry)
       })
     }
 
@@ -686,14 +838,16 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       return rawEntries.map((entry) => {
         if (!isPlainObject(entry)) throw new Error(`nestedAttributes['${relationshipName}'] entries must be objects.`)
 
-        return entry
+        // Narrows the plain-object payload to a normalized nested-entry object.
+        return /** @type {FrontendModelResourceNestedEntry} */ (entry)
       })
     }
     if (!isPlainObject(rawEntries)) {
       throw new Error(`Expected object for nestedAttributes['${relationshipName}'] but got: ${typeof rawEntries}`)
     }
 
-    return [rawEntries]
+    // Narrows the plain-object payload to a normalized nested-entry object.
+    return [/** @type {FrontendModelResourceNestedEntry} */ (rawEntries)]
   }
 
   /**
@@ -702,25 +856,38 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * fields (`{name, file, commentsAttributes}`).
    * @param {object} args - Normalization inputs.
    * @param {{attributes: string[], nested: Record<string, ?>}} args.childPermit - Parsed child permit spec.
-   * @param {Record<string, ?>} args.entry - Raw nested entry.
+   * @param {FrontendModelResourceNestedEntry} args.entry - Raw nested entry.
    * @param {string} args.relationshipName - Relationship name for error messages.
    * @param {typeof import("../database/record/index.js").default} args.targetModelClass - Child model class.
-   * @returns {Record<string, ?>} Normalized nested entry.
+   * @returns {FrontendModelResourceNestedEntry} Normalized nested entry.
    */
   _normalizeNestedRelationshipEntry({childPermit, entry, relationshipName, targetModelClass}) {
-    /** @type {Record<string, ?>} */
+    /** @type {FrontendModelResourceAttributePayload} */
     const attributes = {}
-    /** @type {Record<string, ?>} */
+    /** @type {FrontendModelResourceAttributePayload} */
     const attachments = {}
-    /** @type {Record<string, ?>} */
+    /** @type {FrontendModelResourceAttributePayload} */
     const nestedAttributes = {}
-    /** @type {Record<string, ?>} */
+    /** @type {FrontendModelResourceNestedEntry} */
     const normalized = {}
     const attachmentDefinitions = targetModelClass.getAttachmentsMap?.() || {}
 
     for (const [attributeName, value] of Object.entries(entry)) {
-      if (attributeName === "id" || attributeName === "_destroy") {
-        normalized[attributeName] = value
+      if (attributeName === "id") {
+        if (typeof value !== "string" && typeof value !== "number") {
+          throw new Error(`nestedAttributes['${relationshipName}'] entry id must be a string or number.`)
+        }
+
+        normalized.id = value
+        continue
+      }
+
+      if (attributeName === "_destroy") {
+        if (typeof value !== "boolean") {
+          throw new Error(`nestedAttributes['${relationshipName}'] entry _destroy must be a boolean.`)
+        }
+
+        normalized._destroy = value
         continue
       }
 
@@ -771,8 +938,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Applies belongs-to nested attributes before the parent save so the parent FK can be set.
    * @param {import("../database/record/index.js").default} parent - Parent model instance.
-   * @param {Record<string, ?>} nestedAttributes - Nested-attribute payload keyed by relationship name.
-   * @param {?} controller - Controller instance for resource resolution and authorization.
+   * @param {FrontendModelResourceAttributePayload} nestedAttributes - Nested-attribute payload keyed by relationship name.
+   * @param {FrontendModelResourceController | null | undefined} controller - Controller instance for resource resolution and authorization.
    * @param {{attributes: string[], nested: Record<string, ?>} | null} [parentPermit] - Parsed parent permit spec.
    * @returns {Promise<void>}
    */
@@ -802,13 +969,15 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
           if (!context.destroyPermitted) {
             throw new Error(`nestedAttributes['${relationshipName}'] entry requested _destroy but "_destroy" is not in the permit for this relationship.`)
           }
-          if (!entry.id) throw new Error(`nestedAttributes['${relationshipName}'] _destroy entry is missing an id.`)
+          const id = entry.id
+
+          if (id == undefined) throw new Error(`nestedAttributes['${relationshipName}'] _destroy entry is missing an id.`)
 
           const existing = await this._findNestedRecord({
             ability: context.ability,
             action: "destroy",
             childResourceConfiguration: context.childResourceConfig.resourceConfiguration,
-            id: entry.id,
+            id,
             relationshipName,
             targetModelClass: context.targetModelClass
           })
@@ -818,12 +987,13 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
           continue
         }
 
-        const child = entry.id
+        const id = entry.id
+        const child = id != undefined
           ? await this._findNestedRecord({
             ability: context.ability,
             action: "update",
             childResourceConfiguration: context.childResourceConfig.resourceConfiguration,
-            id: entry.id,
+            id,
             relationshipName,
             targetModelClass: context.targetModelClass
           })
@@ -837,7 +1007,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
         await context.childResource._applyBelongsToNestedAttributes(child, entry.nestedAttributes || {}, controller, childPermit)
         await child.save()
 
-        if (!entry.id) {
+        if (id == undefined) {
           await this._authorizeCreatedChild({
             ability: context.ability,
             child,
@@ -869,8 +1039,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * (allowDestroy, limit, rejectIf) come from the MODEL's
    * `acceptedNestedAttributesFor(name)` declaration.
    * @param {import("../database/record/index.js").default} parent - Parent model instance.
-   * @param {Record<string, ?>} nestedAttributes - Nested-attribute payload keyed by relationship name.
-   * @param {?} controller - Controller instance for resource resolution and authorization.
+   * @param {FrontendModelResourceAttributePayload} nestedAttributes - Nested-attribute payload keyed by relationship name.
+   * @param {FrontendModelResourceController | null | undefined} controller - Controller instance for resource resolution and authorization.
    * @param {{attributes: string[], nested: Record<string, ?>} | null} [parentPermit] - Parsed parent permit spec.
    * @returns {Promise<void>}
    */
@@ -922,11 +1092,17 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       }
 
       for (const entry of destroyEntries) {
+        const id = entry.id
+
+        if (id == undefined) {
+          throw new Error(`nestedAttributes['${relationshipName}'] _destroy entry is missing an id.`)
+        }
+
         const existing = await this._findScopedChild({
           ability: context.ability,
           action: "destroy",
           childResourceConfiguration: context.childResourceConfig.resourceConfiguration,
-          id: entry.id,
+          id,
           parent,
           parentLinkAttributes,
           relationshipName,
@@ -937,11 +1113,17 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       }
 
       for (const entry of updateEntries) {
+        const id = entry.id
+
+        if (id == undefined) {
+          throw new Error(`nestedAttributes['${relationshipName}'] update entry is missing an id.`)
+        }
+
         const existing = await this._findScopedChild({
           ability: context.ability,
           action: "update",
           childResourceConfiguration: context.childResourceConfig.resourceConfiguration,
-          id: entry.id,
+          id,
           parent,
           parentLinkAttributes,
           relationshipName,
@@ -1098,9 +1280,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
       throw new Error(`Nested child resource must define an 'abilities' object to authorize nested ${action}.`)
     }
 
-    const abilityAction = /**
-                           * Narrows the runtime value to the documented type.
-                            @type {Record<string, string>} */ (abilities)[action]
+    const abilityAction = /** @type {Record<string, string>} */ (abilities)[action]
 
     if (typeof abilityAction !== "string" || abilityAction.length < 1) {
       throw new Error(`Nested child resource must define abilities.${action}.`)
@@ -1130,12 +1310,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     const primaryKey = targetModelClass.primaryKey()
     const lookup = {[primaryKey]: id, ...parentLinkAttributes}
     const query = ability
-      ? /**
-         * Narrows the runtime value to the documented type.
-          @type {?} */ (targetModelClass).accessibleFor(this._resolveChildAbilityAction(childResourceConfiguration, action), ability)
-      : /**
-         * Narrows the runtime value to the documented type.
-          @type {?} */ (targetModelClass).where({})
+      ? targetModelClass.accessibleFor(this._resolveChildAbilityAction(childResourceConfiguration, action), ability)
+      : targetModelClass.where({})
 
     const existing = await query.findBy(lookup)
 
@@ -1163,9 +1339,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
 
     const abilityAction = this._resolveChildAbilityAction(childResourceConfiguration, "create")
     const primaryKey = targetModelClass.primaryKey()
-    const authorizedIds = await /**
-                                 * Narrows the runtime value to the documented type.
-                                  @type {?} */ (targetModelClass)
+    const authorizedIds = await targetModelClass
       .accessibleFor(abilityAction, ability)
       .where({[primaryKey]: child.readAttribute(primaryKey)})
       .pluck(primaryKey)
@@ -1189,12 +1363,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     if (relationshipNames.length === 0) return
 
     for (const relationshipName of relationshipNames) {
-      if (typeof /**
-                  * Narrows the runtime value to the documented type.
-                   @type {?} */ (model).loadRelationship === "function") {
-        await /**
-               * Narrows the runtime value to the documented type.
-                @type {?} */ (model).loadRelationship(relationshipName)
+      if (typeof model.loadRelationship === "function") {
+        await model.loadRelationship(relationshipName)
       }
     }
   }
@@ -1220,13 +1390,9 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
  * @returns {{attributes: string[], nested: Record<string, {attributes: string[], nested: Record<string, ?>}>}} - Parsed structure.
  */
 function parsePermittedParams(permitSpec) {
-  /**
-   * Attributes.
-    @type {string[]} */
+  /** @type {string[]} */
   const attributes = []
-  /**
-   * Nested.
-    @type {Record<string, {attributes: string[], nested: Record<string, ?>}>} */
+  /** @type {Record<string, {attributes: string[], nested: Record<string, ?>}>} */
   const nested = {}
 
   if (!Array.isArray(permitSpec)) return {attributes, nested}
@@ -1258,6 +1424,15 @@ function parsePermittedParams(permitSpec) {
   return {attributes, nested}
 }
 
+/**
+ * Narrows a resource to its dynamic virtual setter lookup surface.
+ * @param {FrontendModelBaseResource} resource - Resource instance.
+ * @returns {Record<string, FrontendModelResourceVirtualSetter>} Dynamic virtual setter lookup.
+ */
+function virtualSetterLookup(resource) {
+  return /** @type {Record<string, FrontendModelResourceVirtualSetter>} */ (/** @type {unknown} */ (resource))
+}
+
 /**
  * Runs filter writable frontend model attributes.
  * @param {Record<string, ?>} receiver - Model instance or prototype.
@@ -1266,28 +1441,32 @@ function parsePermittedParams(permitSpec) {
  * @param {string[] | null} [permittedAttributeNames] - Optional explicit permit list. `null` falls back to setter-existence checks only.
  * @returns {Record<string, ?>} - Writable attributes only.
  */
-function filterWritableFrontendModelAttributes(receiver, attributes, resource = /**
-                                                                                 * Narrows the runtime value to the documented type.
-                                                                                  @type {FrontendModelBaseResource | null} */ (null), permittedAttributeNames = null) {
+function filterWritableFrontendModelAttributes(
+  receiver,
+  attributes,
+  resource = /** @type {FrontendModelBaseResource | null} */ (null),
+  permittedAttributeNames = null
+) {
   // Frontend-model writes should fail fast when callers submit read-only or unknown attrs.
   // Silent drops hide contract mistakes in generated models and app-side wrapper code.
-  /**
-   * Writable attributes.
-    @type {Record<string, ?>} */
+  /** @type {Record<string, ?>} */
   const writableAttributes = {}
-  /**
-   * Invalid attributes.
-    @type {string[]} */
+  /** @type {string[]} */
   const invalidAttributes = []
-  /**
-   * Not permitted attributes.
-    @type {string[]} */
+  /** @type {string[]} */
   const notPermittedAttributes = []
 
   const permitSet = Array.isArray(permittedAttributeNames) ? new Set(permittedAttributeNames) : null
-  const translatedSet = resource ? new Set(/**
-                                            * Narrows the runtime value to the documented type.
-                                             @type {typeof FrontendModelBaseResource} */ (resource.constructor).translatedAttributes || []) : new Set()
+  /** @type {string[]} */
+  let translatedAttributes = []
+
+  if (resource) {
+    const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (resource.constructor)
+
+    translatedAttributes = ResourceClass.translatedAttributes || []
+  }
+
+  const translatedSet = new Set(translatedAttributes)
 
   for (const [attributeName, value] of Object.entries(attributes)) {
     if (permitSet && !permitSet.has(attributeName)) {
@@ -1295,19 +1474,16 @@ function filterWritableFrontendModelAttributes(receiver, attributes, resource =
       continue
     }
 
-    const modelClass = /** Narrows the runtime value to the documented type. @type {?} */ (receiver).constructor
+    const modelClass = /** @type {WritableAttributeReceiverClass} */ (receiver.constructor)
     const resolvedAttributeName = (modelClass && typeof modelClass.resolveAttributeName === "function" && modelClass.resolveAttributeName(attributeName)) || attributeName
     const requestedSetterName = `set${inflection.camelize(resolvedAttributeName)}`
     const setterName = (modelClass && typeof modelClass.findMemberNameInsensitive === "function" && modelClass.findMemberNameInsensitive(receiver, requestedSetterName)) || requestedSetterName
     const resourceSetterName = `set${inflection.camelize(attributeName)}Attribute`
+    const resourceSetter = resource ? virtualSetterLookup(resource)[resourceSetterName] : undefined
 
     if (setterName in receiver) {
       writableAttributes[attributeName] = value
-    } else if (resource && typeof /**
-                                   * Narrows the runtime value to the documented type.
-                                    @type {Record<string, ?>} */ (/**
-                                                                   * Narrows the runtime value to the documented type.
-                                                                    @type {?} */ (resource))[resourceSetterName] === "function") {
+    } else if (typeof resourceSetter === "function") {
       writableAttributes[attributeName] = value
     } else if (translatedSet.has(attributeName)) {
       writableAttributes[attributeName] = value