Skip to content

fix: keep an empty included when the request carried include (#232) - #257

Merged
thomasfosterau merged 1 commit into
trunkfrom
issue-232-empty-included
Oct 8, 2026
Merged

thomasfosterau merged 1 commit into
trunkfrom
issue-232-empty-included

Conversation

@thomasfosterau

Copy link
Copy Markdown
Owner

Summary

Part of #232. The conformance-kit rule the issue suggests is split out to #256, because the kit, docs/conformance.md and the examples' conformance.test.ts were being edited in parallel.

JSON:API 1.1 §Fetching Includes says a response to a request carrying include "MUST be a compound document with an included key — even if that included key holds an empty array". The builders dropped an empty included. After #225, GET /search?include=author, where every author is also a hit, lost the key entirely.

  • Handlers.data / Handlers.collection (build in src/Handlers.ts) now emit any included array: one that was empty, and one the dedupe against the primary data empties. They omit the member only when given undefined. 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 / unpaginatedCollection emit included: [] whenever the request carried include (options.include non-empty). That covers a walk that resolved nothing, a set of candidates that were all primary data, and validate-only mode with no targets. Without include they still omit the key. If the caller's own included members are all primary data, the dedupe empties the array, and that empty array is stripped (withoutEmptyIncluded), so a response to a request without include is unchanged on the wire.
  • Examples (examples/*/handlers.ts) pass undefined when query.include is absent instead of []. Without this, every response to a request without include would have gained included: []. The doc examples in src/Handlers.ts (module doc and data) now use the same pattern.
  • Schema encoding: every document schema declares included as Schema.optionalKey(Schema.Array(...)), so [] encodes and decodes. The new blog end-to-end test confirms this through HttpApiTest.
  • README: the builders paragraph, the resolveIncluded property 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.ts and Assemble.test.ts, plus the blog search test; the "no include → no key" example assertion failed with the library fixed and the old example handlers):

Verification

  • pnpm install --frozen-lockfile: pass
  • vp run build: pass
  • vp 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): pass
  • vp run -r test:unit: pass (root 2062, github 39, northwind 42, blog 53; the examples' conformance suites included)
  • vp run docgen (every JSDoc @example compiled and executed): pass (222 examples)
  • fallow audit --format json --quiet --explain --gate-marker agent: verdict warn, not fail
  • fallow audit --base origin/trunk: no dead code. Complexity and duplication findings are warnings, almost all inherited in examples/*/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 without include (the query.include?.includes("author") ? [author] : [] pattern the old doc examples showed) now emits included: [] there. That is still a valid document, but the bytes differ. The changeset says how to keep the old output: pass undefined. If you would rather call this a minor bump, it is a one-word change.

Notes

  • Decision for the owner (proposed default implemented): Assemble's validate-only mode (include given, no targets) used to keep included absent, and its option doc said so. It now emits included: [], plus whatever the caller resolved itself for the collections, because the request carried include and the spec requires the key. The alternative is to keep validate-only mode keyless and treat the caller as responsible for the key.
  • Assemble vs Handlers rule: Handlers cannot see the request, so the caller decides with array vs undefined. Assemble can see it (options.include), so it decides by the request. A caller's included: [] without include stays keyless there, as before.
  • Handlers.DocumentValue still infers Included = never from a literal included: [], so the static type has no included member while the value has included: []. That is harmless structurally and left unchanged.
  • Not touched: 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

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants