Skip to content

feat: cap the error objects a 400 reports for undeclared body members #308

Closed

Description

@thomasfosterau

Problem

A 400 for undeclared attributes / relationships members reports every undeclared key of the member, each as its own JSON:API error object. The errors parse option doesn't change this: the key check in closedStruct (src/internal/schemaExt.ts) builds one UnexpectedKey issue per key and returns them together, so HttpApi's default errors: "first" still gets all of them.

The response grows with the request, about 15× in bytes. Measured on current trunk over the real middleware stack (Middleware.layer, POST /notes on a resource that declares one attribute):

Undeclared keys Request 400 response Time
20 201 B 2.9 KB 4 ms
10,000 99 KB 1.45 MB 140 ms
50,000 539 KB 7.3 MB 332 ms

The post-merge review of #304 measured the same sizes (529 ms for 50,000 keys on its machine). Before #304 this applied only to a member that declares no fields (#281). #304 extends it to every write body member on every resource, so any create or update endpoint can be asked for a response about 15 times the size of the request.

For comparison, effect's own onExcessProperty: "error" with errors: "first" stops at the first undeclared key (SchemaAST.js, "handle excess properties") and reports every key only with errors: "all".

Proposal

Cap the issues the key check reports. Two options:

  1. The first N keys, plus one summary. Report the first 20 undeclared keys, each at its own pointer as today. If there are more, add one summary error at the member, e.g. detail "…and 9,980 more undeclared members". The client still sees several mistakes at once, and the response size is bounded.
  2. Follow the errors option. Report one key under errors: "first" (the HttpApi default), and every key under errors: "all", as effect's onExcessProperty: "error" does.

Option 1 keeps the most useful behaviour for a client with a few typos. Option 2 matches effect, but the HTTP default would then report one key per request.

This needs an owner decision. Either option changes #281's test "reports every undeclared member, each at its own pointer" (src/Resource.undeclared.test.ts), and the #292 test beside it, which pin the current uncapped behaviour. The README's Undeclared body members paragraph and the pending changesets (.changeset/reject-undeclared-body-members.md, .changeset/reject-undeclared-members-everywhere.md) say every undeclared member is reported, so they would change too.

Done when

  • The owner has chosen a cap (option 1, option 2, or another).
  • The number of error objects a 400 carries for undeclared members is bounded on every write body member (createPayload, updatePayload, createInput, updateInput, atomic add / update), with a test that sends 10,000 keys and asserts the bound.
  • Encoding (Client) and decoding apply the same cap.
  • The README, the closedStruct comment and a changeset describe the cap.

Found in the post-merge review of #304. Refs #281, #292.


Generated by Claude Code

Activity

  1. thomasfosterau commented on Oct 9, 2026

    @thomasfosterau
    OwnerAuthor

    Owner decision (2026-10-09): cap at the first 12 undeclared keys plus one summary error, and make the cap configurable.

    • The first 12 undeclared keys are each reported at their own pointer, as today.
    • If there are more, one summary error is added at the member, e.g. "…and 9,988 more undeclared members".
    • The cap is configurable, with a default of 12. The implementer will propose where the option lives, for example a parse annotation or a Resource.make / Middleware option, choosing whichever reaches every write body member and both encode and decode. The proposal will be explained in the PR.

    An implementer is being dispatched.


    Generated by Claude Code

  2. thomasfosterau commented on Oct 10, 2026

    @thomasfosterau
    OwnerAuthor

    Owner decision (2026-10-10): rename both before 0.17.0.

    • The option undeclaredMemberCap becomes maxUndeclaredMemberErrors, since it caps the reported errors and not the accepted members.
    • The summary detail becomes self-contained with plain digits: "9988 more undeclared members not listed" (singular: "1 more undeclared member not listed").

    Both are unreleased, so no deprecation is needed. This rides in the #324 follow-up PR, along with the post-merge review fixes.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions