Repository navigation
fix: keep an empty included when the request carried include (#232) - #257
Merged
Merged
Conversation
JSON:API 1.1 §Fetching Includes requires a response to a request carrying `include` to have an `included` key, "even if that `included` key holds an empty array". The builders dropped an empty one. - `Handlers.data` / `Handlers.collection` emit any `included` array, including one that is empty or that the dedupe against the primary data empties, and omit the member only for `undefined`. This makes `resolveIncluded`'s documented `[]` vs `undefined` distinction hold on the wire. - `Assemble.*` emit `included: []` whenever the request carried `include`, including in validate-only mode (no `targets`). Without `include` they still omit the key unless the caller's own members survive the dedupe. - The examples pass `undefined` when `query.include` is absent, so their responses to requests without `include` stay unchanged. Part of #232; the conformance-kit rule is #256. Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc Co-Authored-By: Claude <noreply@anthropic.com>
8 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Part of #232. The conformance-kit rule the issue suggests is split out to #256, because the kit,
docs/conformance.mdand the examples'conformance.test.tswere being edited in parallel.JSON:API 1.1 §Fetching Includes says a response to a request carrying
include"MUST be a compound document with anincludedkey — even if thatincludedkey holds an empty array". The builders dropped an emptyincluded. After #225,GET /search?include=author, where every author is also a hit, lost the key entirely.Handlers.data/Handlers.collection(buildinsrc/Handlers.ts) now emit anyincludedarray: one that was empty, and one the dedupe against the primary data empties. They omit the member only when givenundefined.resolveIncluded's documented distinction (undefined= nothing requested,[]= the walk resolved to nothing) now holds on the wire. The full-linkage check and the dedupe both run as before on an empty array. They have nothing to check and return[].Assemble.resource/collection/unpaginatedCollectionemitincluded: []whenever the request carriedinclude(options.includenon-empty). That covers a walk that resolved nothing, a set of candidates that were all primary data, and validate-only mode with notargets. Withoutincludethey still omit the key. If the caller's ownincludedmembers are all primary data, the dedupe empties the array, and that empty array is stripped (withoutEmptyIncluded), so a response to a request withoutincludeis unchanged on the wire.examples/*/handlers.ts) passundefinedwhenquery.includeis absent instead of[]. Without this, every response to a request withoutincludewould have gainedincluded: []. The doc examples insrc/Handlers.ts(module doc anddata) now use the same pattern.includedasSchema.optionalKey(Schema.Array(...)), so[]encodes and decodes. The new blog end-to-end test confirms this throughHttpApiTest.resolveIncludedproperty table and the assembler paragraph now describe the key.Tests (each new or changed one failed on unfixed trunk code first: 10 failures across
Handlers.test.ts,Handlers.include.test.tsandAssemble.test.ts, plus the blog search test; the "no include → no key" example assertion failed with the library fixed and the old example handlers):Handlers:included: []emitted fordata/collection/data(null),undefinedomits it, all candidates deduped against primary →included: [](bothHandlers.buildIncludeddedupesincludedagainst itself but not against the primary data, so one document can carry the same(type, id)twice #147 cases updated), theonResourcesingle-run case, andresolveIncluded→[]→included: [].Assemble:resourcewith include + no targets and with include + unresolvable ref →[],resourcewithout include (orinclude: []) → no key.collectioninclude + nothing resolves (and an empty page) →[], include + all deduped (Handlers.buildIncludeddedupesincludedagainst itself but not against the primary data, so one document can carry the same(type, id)twice #147 case) →[], no include +included: []or all-primary members → no key.unpaginatedCollectioninclude + nothing resolves →[], include + all deduped →[], no include +included: []→ no key.examples/blog:GET /search?filter[q]=d&include=author(the author is a hit) →included: [], the same request withoutincludehas no key, andGET /articles/1without include has no key.Verification
pnpm install --frozen-lockfile: passvp run build: passvp check: pass (0 errors; no new warnings in the changed files, counted per file against trunk)vp run check(sources, type-level tests, examples, emitted declarations): passvp run -r test:unit: pass (root 2062, github 39, northwind 42, blog 53; the examples' conformance suites included)vp run docgen(every JSDoc@examplecompiled and executed): pass (222 examples)fallow audit --format json --quiet --explain --gate-marker agent: verdictwarn, notfailfallow audit --base origin/trunk: no dead code. Complexity and duplication findings are warnings, almost all inherited inexamples/*/handlers.ts.Changeset
.changeset/empty-included-on-include.md: patch, following the pre-1.0 convention for fixes. Flagged: the change is visible on the wire. A handler that passes[]for a request withoutinclude(thequery.include?.includes("author") ? [author] : []pattern the old doc examples showed) now emitsincluded: []there. That is still a valid document, but the bytes differ. The changeset says how to keep the old output: passundefined. If you would rather call this a minor bump, it is a one-word change.Notes
Assemble's validate-only mode (includegiven, notargets) used to keepincludedabsent, and its option doc said so. It now emitsincluded: [], plus whatever the caller resolved itself for the collections, because the request carriedincludeand the spec requires the key. The alternative is to keep validate-only mode keyless and treat the caller as responsible for the key.AssemblevsHandlersrule:Handlerscannot see the request, so the caller decides with array vsundefined.Assemblecan see it (options.include), so it decides by the request. A caller'sincluded: []withoutincludestays keyless there, as before.Handlers.DocumentValuestill infersIncluded = neverfrom a literalincluded: [], so the static type has noincludedmember while the value hasincluded: []. That is harmless structurally and left unchanged.src/internal/conformance/*,src/Conformance*.ts,docs/conformance.md,examples/*/test/conformance.test.ts.🤖 Generated with Claude Code
https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Generated by Claude Code