Skip to content

fix: answer a bare ?include= and an empty related to-one with an included key (follow-up to #257) - #266

Merged
thomasfosterau merged 2 commits into
trunkfrom
issue-232-empty-included-followup
Oct 8, 2026
Merged

thomasfosterau merged 2 commits into
trunkfrom
issue-232-empty-included-followup

Conversation

@thomasfosterau

@thomasfosterau thomasfosterau commented Oct 8, 2026 •

Copy link
Copy Markdown
Owner

Summary

Follow-up to #257. Part of #232. #257 merged before this round of review fixes landed, so they come as a new PR off trunk.

The review of #257 found three remaining places where a request carrying include could get a response without the included key, and some missing tests.

  • ResourceHandlers.related, to-one with empty linkage (src/ResourceHandlers.ts). The handler returned { data: null, jsonapi } before it reached Assemble, so GET …/polity?include=x had no included key. It also never validated the include paths, so ?include=nope answered 200. When the request carries include, the handler now runs Query.validateIncludePaths(include, { includable: config.includable ?? [], maxDepth: Assemble.MAX_INCLUDE_DEPTH }) (the same defaults Assemble.resource uses) and returns { data: null, included: [], jsonapi }. The return type now declares included?: readonly []. Endpoint.flatRelated's to-one document with included already declares the member, and I checked that { data: null, included: [] } encodes through RelatedDocument(target, { included }).
  • The include signal is now presence, not emptiness. A bare ?include= decodes to []. Assemble's walk and Handlers.resolveIncluded both treated [] as "not requested" and omitted the key. The example handlers, which test query.include === undefined, emitted included: []. Both now go by presence: walk checks options.include !== undefined, and resolveIncluded returns [] for an empty path list without loading anything. That matches its documented contract (undefined means nothing was requested, [] means the walk resolved to nothing). The Assemble.test.ts case that pinned include: [] → no key now expects included: [].
  • Handlers.DocumentValue always declares readonly included?: ReadonlyArray<Included>. The [Included] extends [never] branch is gone. Before this, Handlers.data(r, { included: [] }).included failed to compile because a literal [] infers Included = never, even though the value carries the key. The doc comment now says only meta / jsonapi are conditional.
  • README: the assembler paragraph and the resolveIncluded property table now cover the presence rule and the related to-one case.
  • Review fixes (second commit, 9f03440): the stale dedupe-included-against-primary.md changeset (see Changeset), the undisclosed require-effect-concurrency site (see Verification), exact included assertions in the type test, two more empty to-one tests, and a reflowed DocumentValue doc line in src/Handlers.ts.

Tests. Each new or changed src test failed on the unfixed code first (6 failures across ResourceHandlers.test.ts, Assemble.test.ts and Handlers.include.test.ts, plus 3 tsc errors in the new type test):

  • ResourceHandlers.related to-one with empty linkage: include: ["country"], a 3-hop include: ["country.capital.mayor"] (the default depth limit) and include: [] all give { data: null, included: [], jsonapi }. No include gives no key. An unknown path fails with UnsupportedIncludePath (400), a 4-hop path with UnsupportedIncludeDepth, and with no includable configured any path fails with UnsupportedIncludePath. Mutation checks: maxDepth: 2 fails the 3-hop case, and an includable default of ["country"] fails the unconfigured case.
  • Assemble.resource with include: [] gives included: []. Assemble.collection / unpaginatedCollection in validate-only mode (include + includable, no targets) give included: [], both for a named path and for include: [].
  • Handlers.resolveIncluded(article, []) gives [] with no loader calls. undefined still gives undefined.
  • test/empty-included.types.ts: pins the included member of data / collection with included: [], with no option, and with [person], as Equals<Pick<typeof doc, "included">, { readonly included?: ReadonlyArray<…> }>. Pick fails to compile when the key is absent, and Equals fails when the member is required or any. A negative control asserts it is not the required form. Mutation checks: making the member required, ReadonlyArray<any>, or restoring the [Included] extends [never] conditional each fails the file.
  • examples/github: ?include= with no paths, end to end through HttpApiTest (the client sends include: [] as a bare ?include=). GET /repositories/1 and GET /repositories both answer included: []. In a mutation run where the handler treated [] as absent, this test failed.
  • examples/github and examples/northwind: a request with no include gets no key, for both get and list. In a mutation run where the handler always passed an array, this test failed.

Verification

All run in order on 9f03440 (on trunk at 1cb0652, which includes #259 and #262; GitHub reports it mergeable with trunk at e8396eb):

  • pnpm install --frozen-lockfile: pass
  • vp run build: pass
  • vp check: pass (0 errors, 4365 warnings against trunk's 4367). Per rule against trunk: effect-run-in-body +1 (src/ResourceHandlers.test.ts, the file's existing Effect.runPromise test idiom, kept to one site with Effect.all); no-length-comparison −1 and prefer-arr-match −1 (src/Assemble.ts); avoid-object-type −1 (src/Handlers.ts). No other rule changes. The previous head (96ed121) also added one require-effect-concurrency (the Effect.all now passes { concurrency: 1 }), one no-barrel-imports and four prefer-option-over-null (test/empty-included.types.ts, now importing effect/Schema and asserting with Equals); this body did not disclose them, and all six are gone.
  • vp run check (sources, type-level tests, examples, emitted declarations): pass. TS6 (tsc6 -p tsconfig.json --noEmit) shows only trunk's unused @ts-expect-error markers in src/Endpoint.ts.
  • vp run -r test:unit: pass (root 2095, github 44, northwind 40, blog 53; the new cases extend existing tests)
  • vp run docgen (every JSDoc @example compiled and executed): pass (224 examples)
  • fallow audit --format json --quiet --explain --gate-marker agent: verdict pass (0 introduced findings)
  • fallow audit --base origin/trunk: pass, "No issues in 12 changed files". The 5 complexity warnings are inherited.

Changeset

  • .changeset/included-key-on-bare-include.md: patch (a fix, before 1.0). It is a new file, not an edit to fix: keep an empty included when the request carried include (#232) #257's empty-included-on-include.md, which is already on trunk. A separate file stays valid if the release PR consumes the first one before this merges.
  • .changeset/dedupe-included-against-primary.md (from fix(Handlers): dedupe included against the primary data #225, unreleased) corrected. It said a document whose included candidates are all primary data omits the member, and that Handlers.data(article, { included: [article] }) succeeds with included omitted. Since bug: compound documents omit included when ?include= resolves to nothing #232 that document carries included: []. It now says Handlers.data / Handlers.collection emit included: [], the Assemble builders do the same when the request carried include and omit the key without it, and the example succeeds with included: []. I read all pending changesets together. The other two included entries (empty-included-on-include.md, included-key-on-bare-include.md) agree with it and with 0.16.3 (where resolveIncluded returned undefined for [] and DocumentValue declared included only for a non-never element type).

Notes

  • Interpretation for the owner (implemented): a client that supplies include, even an empty ?include=, gets the included key ([]). This follows the spec's wording, "when … a client supplies an include parameter", and it is what the examples' handlers already did. The alternative is to treat ?include= as not requested, with no key: revert walk to include.length === 0 and resolveIncluded to paths.length === 0, and change the examples to test query.include?.length.
  • The empty to-one now validates include paths at depth Assemble.MAX_INCLUDE_DEPTH. RelatedConfig has no depth option, and the resolved to-one path (Assemble.resource) uses the same default, so both cases reject the same paths.
  • The to-many related endpoint is unchanged. Endpoint.flatRelated declares include: false there, so include never reaches that handler.
  • Not done (optional review nit): folding the examples' query.include === undefined ? undefined : … ternaries into a shared includedFor helper. I tried it. Measured against trunk, fallow found no duplication in the current ternaries. The helper itself is identical in three independent example packages, so it added 3 new clone groups, and it added one prefer-option-over-null warning per example. I reverted it.
  • Not touched: src/internal/codecs.ts, src/internal/conformance/*, src/Conformance*.ts, src/Middleware.ts, docs/conformance.md, examples/*/test/conformance.test.ts.

🤖 Generated with Claude Code


Generated by Claude Code

…232)

Follow-up to #257's review.

- `ResourceHandlers.related`: a to-one with empty linkage validated no
  include paths and answered `{ data: null }` without `included`. It now
  validates the request's paths (400 for one outside the whitelist or too
  deep) and answers `{ data: null, included: [] }` when the request carried
  `include`.
- Presence of `include` is the signal everywhere: `Assemble`'s walk and
  `Handlers.resolveIncluded` treated the `[]` a bare `?include=` decodes to
  as "not requested"; both now answer it with `[]`, so the document keeps
  its `included` key.
- `Handlers.DocumentValue` always declares `included?`, so
  `Handlers.data(r, { included: [] }).included` type-checks.
- Tests: the related to-one cases, `?include=` with no paths through
  `Assemble` / `resolveIncluded` and end to end in the github example,
  validate-only `collection` / `unpaginatedCollection`, "no include, no
  key" regressions in the github and northwind examples, and a type test.

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
- `.changeset/dedupe-included-against-primary.md`: a document whose
  `included` candidates are all primary data now carries `included: []`
  (the presence rule from #232), not an omitted member; say so, and that
  the `Assemble` builders omit it only without `include`.
- `src/ResourceHandlers.test.ts`: give the empty to-one test's
  `Effect.all` an explicit `{ concurrency: 1 }`
  (`require-effect-concurrency`), accept a 3-hop path at the default
  depth limit, and reject a path when no `includable` is configured.
- `test/empty-included.types.ts`: pin the `included` member exactly with
  `Equals<Pick<…, "included">, …>`, which fails when the key is absent,
  required or `any`; import `Schema` from `effect/Schema`.
- `src/Handlers.ts`: reflow an overlong `DocumentValue` doc line.

Part of #232.

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
@thomasfosterau
thomasfosterau merged commit 306eb47 into trunk Oct 8, 2026
1 check passed
@thomasfosterau
thomasfosterau deleted the issue-232-empty-included-followup branch October 8, 2026 07:39
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