Repository navigation
Description
Found by the conformance kit (#120) running against all three of examples/.
What's wrong
src/Handlers.ts — buildIncluded seeds its dedup set from included only:
// Dedupe by (type, id)
const seen = new Set<string>()
const deduped: Array<Included> = []
for (const resource of included) {
const k = key(resource)
if (seen.has(k)) continue
seen.add(k)
deduped.push(resource)
}primary is passed in — and is used, two blocks down, for the full-linkage check — but it never seeds seen. So a resource that appears in the primary data and is handed to included is emitted in both slots.
JSON:API §Compound Documents:
A compound document MUST NOT include more than one resource object for each
typeandidpair.
The constraint is document-wide, not included-wide.
Repro
Any heterogeneous collection endpoint where an include path targets a type that is also primary data. All three examples have one — the /search endpoint:
GET /search?include=author
examples/blog:
people:9 at /data/1 and /included/0
examples/github (GET /search?include=owner):
users:1 at /data/6 and /included/0; users:2 at /data/7 and /included/1
examples/northwind (GET /search?include=category,supplier):
suppliers:1 at /data/8 and /included/1; suppliers:2 at /data/9 and /included/4; suppliers:3 at /data/10 and /included/5
The kit's finding:
FAIL spec/document/no-duplicate-resources
MUST NOT · Compound Documents
A compound document MUST NOT include more than one resource object for each `type` and
`id` pair.
https://jsonapi.org/format/1.1/#document-compound-documents
· /search?include=author answered the same (type, id) more than once
GET /search?include=author [accept: application/vnd.api+json]
expected: one resource object per (type, id)
observed: people:9 at /data/1 and /included/0
Why it's the library's, not the examples'
The three handlers do the ordinary thing — resolve the include paths, hand the targets to Handlers.collection as included — and the builder's documented contract is that it dedupes. Its module header says so:
includedresources are deduplicated by(type, id)
A caller reading that has no reason to dedupe against primary data itself, and no ergonomic way to: the primary set is the builder's own argument.
It bites hardest exactly where it is hardest to notice — a heterogeneous collection, where whether a given resource lands in data or included depends on the query.
Expected
buildIncluded seeds seen with the primary data's keys, so a resource already present as primary data is dropped from included rather than repeated:
const seen = new Set(primary.map(key))That is also the reading that makes the existing full-linkage check coherent — it already treats [...primary, ...deduped] as one document.
Acceptance criteria
-
buildIncludedexcludes resources already present in the primary data. - A test covering the heterogeneous-collection case: same
(type, id)as primary data and as anincludetarget, emitted once. -
spec/document/no-duplicate-resourcescomes off theKNOWN_FAILURESlist in all threeexamples/*/test/conformance.test.ts.
Activity
Merge main into the conformance kit
test(Assemble): say what the #147 page-member case exercises
fix(Handlers): dedupe `included` against the primary data
test(Assemble): say what the #147 page-member case exercises