Repository navigation
fix: answer a bare ?include= and an empty related to-one with an included key (follow-up to #257) - #266
Merged
Conversation
…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>
This was referenced Oct 8, 2026
Closed
- `.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>
9 tasks done
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
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
includecould get a response without theincludedkey, and some missing tests.ResourceHandlers.related, to-one with empty linkage (src/ResourceHandlers.ts). The handler returned{ data: null, jsonapi }before it reachedAssemble, soGET …/polity?include=xhad noincludedkey. It also never validated the include paths, so?include=nopeanswered200. When the request carriesinclude, the handler now runsQuery.validateIncludePaths(include, { includable: config.includable ?? [], maxDepth: Assemble.MAX_INCLUDE_DEPTH })(the same defaultsAssemble.resourceuses) and returns{ data: null, included: [], jsonapi }. The return type now declaresincluded?: readonly [].Endpoint.flatRelated's to-one document withincludedalready declares the member, and I checked that{ data: null, included: [] }encodes throughRelatedDocument(target, { included }).includesignal is now presence, not emptiness. A bare?include=decodes to[].Assemble'swalkandHandlers.resolveIncludedboth treated[]as "not requested" and omitted the key. The example handlers, which testquery.include === undefined, emittedincluded: []. Both now go by presence:walkchecksoptions.include !== undefined, andresolveIncludedreturns[]for an empty path list without loading anything. That matches its documented contract (undefinedmeans nothing was requested,[]means the walk resolved to nothing). TheAssemble.test.tscase that pinnedinclude: []→ no key now expectsincluded: [].Handlers.DocumentValuealways declaresreadonly included?: ReadonlyArray<Included>. The[Included] extends [never]branch is gone. Before this,Handlers.data(r, { included: [] }).includedfailed to compile because a literal[]infersIncluded = never, even though the value carries the key. The doc comment now says onlymeta/jsonapiare conditional.resolveIncludedproperty table now cover the presence rule and the related to-one case.9f03440): the stalededupe-included-against-primary.mdchangeset (see Changeset), the undisclosedrequire-effect-concurrencysite (see Verification), exactincludedassertions in the type test, two more empty to-one tests, and a reflowedDocumentValuedoc line insrc/Handlers.ts.Tests. Each new or changed
srctest failed on the unfixed code first (6 failures acrossResourceHandlers.test.ts,Assemble.test.tsandHandlers.include.test.ts, plus 3tscerrors in the new type test):ResourceHandlers.relatedto-one with empty linkage:include: ["country"], a 3-hopinclude: ["country.capital.mayor"](the default depth limit) andinclude: []all give{ data: null, included: [], jsonapi }. Noincludegives no key. An unknown path fails withUnsupportedIncludePath(400), a 4-hop path withUnsupportedIncludeDepth, and with noincludableconfigured any path fails withUnsupportedIncludePath. Mutation checks:maxDepth: 2fails the 3-hop case, and anincludabledefault of["country"]fails the unconfigured case.Assemble.resourcewithinclude: []givesincluded: [].Assemble.collection/unpaginatedCollectionin validate-only mode (include + includable, notargets) giveincluded: [], both for a named path and forinclude: [].Handlers.resolveIncluded(article, [])gives[]with no loader calls.undefinedstill givesundefined.test/empty-included.types.ts: pins theincludedmember ofdata/collectionwithincluded: [], with no option, and with[person], asEquals<Pick<typeof doc, "included">, { readonly included?: ReadonlyArray<…> }>.Pickfails to compile when the key is absent, andEqualsfails when the member is required orany. 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 throughHttpApiTest(the client sendsinclude: []as a bare?include=).GET /repositories/1andGET /repositoriesboth answerincluded: []. In a mutation run where the handler treated[]as absent, this test failed.examples/githubandexamples/northwind: a request with noincludegets 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(ontrunkat1cb0652, which includes #259 and #262; GitHub reports it mergeable withtrunkate8396eb):pnpm install --frozen-lockfile: passvp run build: passvp check: pass (0 errors, 4365 warnings againsttrunk's 4367). Per rule againsttrunk:effect-run-in-body+1 (src/ResourceHandlers.test.ts, the file's existingEffect.runPromisetest idiom, kept to one site withEffect.all);no-length-comparison−1 andprefer-arr-match−1 (src/Assemble.ts);avoid-object-type−1 (src/Handlers.ts). No other rule changes. The previous head (96ed121) also added onerequire-effect-concurrency(theEffect.allnow passes{ concurrency: 1 }), oneno-barrel-importsand fourprefer-option-over-null(test/empty-included.types.ts, now importingeffect/Schemaand asserting withEquals); 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 onlytrunk's unused@ts-expect-errormarkers insrc/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@examplecompiled and executed): pass (224 examples)fallow audit --format json --quiet --explain --gate-marker agent: verdictpass(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 emptyincludedwhen the request carriedinclude(#232) #257'sempty-included-on-include.md, which is already ontrunk. 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): dedupeincludedagainst the primary data #225, unreleased) corrected. It said a document whoseincludedcandidates are all primary data omits the member, and thatHandlers.data(article, { included: [article] })succeeds withincludedomitted. Since bug: compound documents omitincludedwhen ?include= resolves to nothing #232 that document carriesincluded: []. It now saysHandlers.data/Handlers.collectionemitincluded: [], theAssemblebuilders do the same when the request carriedincludeand omit the key without it, and the example succeeds withincluded: []. I read all pending changesets together. The other twoincludedentries (empty-included-on-include.md,included-key-on-bare-include.md) agree with it and with 0.16.3 (whereresolveIncludedreturnedundefinedfor[]andDocumentValuedeclaredincludedonly for a non-neverelement type).Notes
include, even an empty?include=, gets theincludedkey ([]). This follows the spec's wording, "when … a client supplies anincludeparameter", and it is what the examples' handlers already did. The alternative is to treat?include=as not requested, with no key: revertwalktoinclude.length === 0andresolveIncludedtopaths.length === 0, and change the examples to testquery.include?.length.Assemble.MAX_INCLUDE_DEPTH.RelatedConfighas nodepthoption, and the resolved to-one path (Assemble.resource) uses the same default, so both cases reject the same paths.relatedendpoint is unchanged.Endpoint.flatRelateddeclaresinclude: falsethere, soincludenever reaches that handler.query.include === undefined ? undefined : …ternaries into a sharedincludedForhelper. I tried it. Measured againsttrunk, 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 oneprefer-option-over-nullwarning per example. I reverted it.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