diff --git a/.changeset/empty-included-on-include.md b/.changeset/empty-included-on-include.md new file mode 100644 index 00000000..cddcd021 --- /dev/null +++ b/.changeset/empty-included-on-include.md @@ -0,0 +1,5 @@ +--- +"@thomasfosterau/effect-jsonapi": patch +--- + +A response to a request carrying `include` now keeps its `included` key when nothing is left to include, as JSON:API 1.1 §Fetching Includes requires ("even if that `included` key holds an empty array"). `Handlers.data` / `Handlers.collection` emit any `included` array they are given — empty, or emptied by the dedupe against the primary data (so `GET /search?include=author` where every author is also a hit answers `included: []`) — and omit the member only for `undefined`; before, an empty result was omitted too. A handler that passes `[]` for a request with no `include` (`query.include?.includes("author") ? [author] : []`) now emits `included: []` there as well: pass `undefined` instead when `query.include` is `undefined`. `Assemble.resource` / `Assemble.collection` / `Assemble.unpaginatedCollection` emit `included: []` whenever the request carried `include` — including when no `targets` registry is wired — and still omit it without `include` unless the caller's own members survive the dedupe. diff --git a/README.md b/README.md index 304d3d0a..5ed39d73 100644 --- a/README.md +++ b/README.md @@ -1145,7 +1145,7 @@ const ArticlesLive = HttpApiBuilder.group(Api, "articles", (handlers) => ) ``` -The document builders (`Handlers.data` / `Handlers.collection`) enforce the compound-document rules at runtime: `included` is **deduplicated** by `(type, id)` — against itself and against the primary `data`, so a resource that is both a hit and an include target is emitted once, as primary data — and checked for **full linkage** (every included resource must be reachable from the primary data through resource linkage). Their `onResource` option applies per-resource processing — sparse fieldsets, computed `meta` — uniformly across the whole document ([below](#the-per-resource-transform-pass-onresource)). +The document builders (`Handlers.data` / `Handlers.collection`) enforce the compound-document rules at runtime: `included` is **deduplicated** by `(type, id)` — against itself and against the primary `data`, so a resource that is both a hit and an include target is emitted once, as primary data — and checked for **full linkage** (every included resource must be reachable from the primary data through resource linkage). Any `included` array is emitted, even an empty one or one the dedupe empties — a response to a request carrying `include` MUST have an `included` key, "even if that `included` key holds an empty array" ([§Fetching Includes](https://jsonapi.org/format/1.1/#fetching-includes)) — so pass an array whenever the request carried `include`, and `undefined` when it did not, which omits the member. Their `onResource` option applies per-resource processing — sparse fieldsets, computed `meta` — uniformly across the whole document ([below](#the-per-resource-transform-pass-onresource)). ### Resolving `included` — one batch per level @@ -1174,7 +1174,7 @@ What it guarantees, and why each one matters: | **Cycles terminate** | A graph that loops (`articles → comments → articles`) revisits resources the document already holds, which are never re-loaded | | **Depth-capped** | `depth` (default `3`, the deepest path `Query.Include` legalises) bounds the number of hops. §7.1 leaves the bound implementation-defined and each hop is another round of loader calls, so this is a denial-of-service boundary, not just an ergonomic one | | **Unresolvable refs dropped** | A type with no target, an id the batch didn't return, a row this viewer may not see: all normal outcomes, simply absent from `included`. A loader's own failure propagates and fails the document | -| **`undefined` when unasked** | So the caller omits the member. `[]` is the different statement "your walk resolved to nothing" | +| **`undefined` when unasked** | So the builders omit the member. `[]` is the different statement "your walk resolved to nothing", which they emit as `included: []` | Because every resource is reached _through_ a document resource's linkage, full linkage holds by construction **for the array the resolver returns**: handed unchanged to `Handlers.data` / `Handlers.collection` with the same primary data, the builders' check is a guard over the resolver's own output rather than a live constraint. It is live again when anything between the walk and the document changes linkage, because the check runs on the resources the document actually emits: @@ -1517,7 +1517,7 @@ The refusal applies only when no range of any media type carries `q > 0`; anothe ### The assembler, the handlers and the registry -`Assemble.resource` / `Assemble.collection` are the seam a handler's document returns go through: capability `meta` (`canEdit` / `canDelete`, computed per resource by a hook — `roleCapabilities`, `ownedCapabilities`, or your own), links stringified, fieldsets projected, the `include` walk validated and resolved batched through a `Handlers.IncludeTargets` registry, the `jsonapi` member set. +`Assemble.resource` / `Assemble.collection` are the seam a handler's document returns go through: capability `meta` (`canEdit` / `canDelete`, computed per resource by a hook — `roleCapabilities`, `ownedCapabilities`, or your own), links stringified, fieldsets projected, the `include` walk validated and resolved batched through a `Handlers.IncludeTargets` registry, the `jsonapi` member set. A request carrying `include` always gets the `included` key — `[]` when nothing resolved or every candidate was already primary data; without `include` the key is absent unless members the caller resolved itself survive the dedupe. `Assemble.collection(resources, pagination, options?)` surfaces the page math — `meta.totalCount` and the five offset pagination links, carrying the request's other query pairs. A collection served whole (a small fixed list, or a to-many related collection that is never paged) uses `Assemble.unpaginatedCollection(resources, options?)` instead: the same stamping, projection, `include` walk, `included` handling and `jsonapi` member, with no pagination `links` (and no `links` member at all unless `self` is given) and no `meta` (unless `meta` is given) — and its `UnpaginatedCollectionDocument` type has no page math and no pagination links, so no `meta.totalCount` and no `next` / `last` link the endpoint doesn't honour is advertised: diff --git a/examples/blog/handlers.ts b/examples/blog/handlers.ts index f9081208..ede72195 100644 --- a/examples/blog/handlers.ts +++ b/examples/blog/handlers.ts @@ -154,7 +154,8 @@ export const ArticlesLive = HttpApiBuilder.group(Api, "articles", (handlers) => loadArticle(params.id).pipe( Effect.map((article) => Handlers.data(article, { - included: resolveIncluded(article, query.include), + included: + query.include === undefined ? undefined : resolveIncluded(article, query.include), self: `/articles/${article.id}`, }), ), @@ -187,7 +188,10 @@ export const ArticlesLive = HttpApiBuilder.group(Api, "articles", (handlers) => return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((article) => resolveIncluded(article, query.include)), + included: + query.include === undefined + ? undefined + : page.flatMap((article) => resolveIncluded(article, query.include)), meta: { total }, links: Handlers.offsetPaginationLinks("/articles", { offset, limit }, total), }), @@ -264,12 +268,15 @@ export const ArticlesLive = HttpApiBuilder.group(Api, "articles", (handlers) => const page = all.slice(offset, offset + limit); const path = Handlers.relatedLink("articles", article.id, "comments"); return Handlers.collection(page, { - included: query.include?.includes("author") - ? page.flatMap((comment) => { - const author = store.people.get(comment.relationships!.author.data.id); - return author === undefined ? [] : [author]; - }) - : [], + included: + query.include === undefined + ? undefined + : query.include.includes("author") + ? page.flatMap((comment) => { + const author = store.people.get(comment.relationships!.author.data.id); + return author === undefined ? [] : [author]; + }) + : [], meta: { total }, links: Handlers.offsetPaginationLinks(path, { offset, limit }, total), }); @@ -368,7 +375,7 @@ export const SearchLive = HttpApiBuilder.group(Api, "search", (handlers) => Handlers.collection(page, { included: query.include === undefined - ? [] + ? undefined : page.flatMap((result) => result.type === "articles" ? resolveIncluded(result, query.include) : [], ), diff --git a/examples/blog/test/blog.test.ts b/examples/blog/test/blog.test.ts index d65db7f9..d75dc6a0 100644 --- a/examples/blog/test/blog.test.ts +++ b/examples/blog/test/blog.test.ts @@ -65,6 +65,8 @@ describe("blog example: fetching", () => { expect(document.links?.self).toBe("/articles/1"); // dates decode through the wire format expect(document.data?.attributes.createdAt).toBeInstanceOf(Date); + // no `?include=`, no compound document: the member is absent, not `[]` + expect(document).not.toHaveProperty("included"); }); it("serves compound documents for ?include=author,tags", async () => { @@ -510,6 +512,34 @@ describe("blog example: heterogeneous search", () => { expect(document.included?.map((resource) => resource.type)).toEqual(["people"]); }); + it("keeps an empty `included` when every included author is already a hit (#232)", async () => { + // "d" hits the article and its author, Dan: the author is primary data, so + // the dedupe leaves nothing to include — but the request carried + // `include`, and §Fetching Includes requires the key, even empty. + const document = await run( + Effect.gen(function* () { + const client = yield* buildClient; + return yield* client.search.search({ + query: { filter: { q: "d" }, include: ["author"] }, + }); + }), + ); + + // the article and its author are both hits + expect(document.data.map((result) => `${result.type}:${result.id}`)).toEqual( + expect.arrayContaining(["articles:1", `people:${sampleAuthor.id}`]), + ); + expect(document.included).toEqual([]); + // …and without `include` the member is absent + const plain = await run( + Effect.gen(function* () { + const client = yield* buildClient; + return yield* client.search.search({ query: { filter: { q: "d" } } }); + }), + ); + expect(plain).not.toHaveProperty("included"); + }); + it("documents the search endpoint in OpenAPI", () => { const spec = OpenApi.fromApi(Api); expect(spec.paths["/search"]?.get).toBeDefined(); diff --git a/examples/github/handlers.ts b/examples/github/handlers.ts index e826c68a..eb521471 100644 --- a/examples/github/handlers.ts +++ b/examples/github/handlers.ts @@ -458,7 +458,10 @@ export const RepositoriesLive = HttpApiBuilder.group(Api, "repositories", (handl loadRepository(params.id).pipe( Effect.map((repository) => Handlers.data(repository, { - included: resolveRepositoryIncluded(repository, query.include), + included: + query.include === undefined + ? undefined + : resolveRepositoryIncluded(repository, query.include), self: `/repositories/${repository.id}`, }), ), @@ -494,9 +497,10 @@ export const RepositoriesLive = HttpApiBuilder.group(Api, "repositories", (handl return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((repository) => - resolveRepositoryIncluded(repository, query.include), - ), + included: + query.include === undefined + ? undefined + : page.flatMap((repository) => resolveRepositoryIncluded(repository, query.include)), meta: { total }, links: Handlers.numberPaginationLinks("/repositories", { number, size }, total), }), @@ -571,7 +575,8 @@ export const IssuesLive = HttpApiBuilder.group(Api, "issues", (handlers) => loadIssue(params.id).pipe( Effect.map((issue) => Handlers.data(issue, { - included: resolveIssueIncluded(issue, query.include), + included: + query.include === undefined ? undefined : resolveIssueIncluded(issue, query.include), self: `/issues/${issue.id}`, }), ), @@ -601,7 +606,10 @@ export const IssuesLive = HttpApiBuilder.group(Api, "issues", (handlers) => return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((issue) => resolveIssueIncluded(issue, query.include)), + included: + query.include === undefined + ? undefined + : page.flatMap((issue) => resolveIssueIncluded(issue, query.include)), meta: { total }, links: Handlers.numberPaginationLinks("/issues", { number, size }, total), }), @@ -660,12 +668,15 @@ export const IssuesLive = HttpApiBuilder.group(Api, "issues", (handlers) => const { number, page, size, total } = paginate(all, query.page); const path = Handlers.relatedLink("issues", issue.id, "comments"); return Handlers.collection(page, { - included: query.include?.includes("author") - ? page.flatMap((comment) => { - const author = store.users.get(comment.relationships!.author.data.id); - return author === undefined ? [] : [author]; - }) - : [], + included: + query.include === undefined + ? undefined + : query.include.includes("author") + ? page.flatMap((comment) => { + const author = store.users.get(comment.relationships!.author.data.id); + return author === undefined ? [] : [author]; + }) + : [], meta: { total }, links: Handlers.numberPaginationLinks(path, { number, size }, total), }); @@ -768,7 +779,8 @@ export const PullsLive = HttpApiBuilder.group(Api, "pulls", (handlers) => loadPull(params.id).pipe( Effect.map((pull) => Handlers.data(pull, { - included: resolvePullIncluded(pull, query.include), + included: + query.include === undefined ? undefined : resolvePullIncluded(pull, query.include), self: `/pulls/${pull.id}`, }), ), @@ -791,7 +803,10 @@ export const PullsLive = HttpApiBuilder.group(Api, "pulls", (handlers) => return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((pull) => resolvePullIncluded(pull, query.include)), + included: + query.include === undefined + ? undefined + : page.flatMap((pull) => resolvePullIncluded(pull, query.include)), meta: { total }, links: Handlers.numberPaginationLinks("/pulls", { number, size }, total), }), @@ -831,13 +846,16 @@ export const SearchLive = HttpApiBuilder.group(Api, "search", (handlers) => return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((result) => - result.type === "repositories" - ? resolveRepositoryIncluded(result, query.include) - : result.type === "issues" - ? resolveIssueIncluded(result, query.include) - : [], - ), + included: + query.include === undefined + ? undefined + : page.flatMap((result) => + result.type === "repositories" + ? resolveRepositoryIncluded(result, query.include) + : result.type === "issues" + ? resolveIssueIncluded(result, query.include) + : [], + ), meta: { total }, links: Handlers.offsetPaginationLinks("/search", { offset, limit }, total), }), diff --git a/examples/northwind/handlers.ts b/examples/northwind/handlers.ts index bb423f16..e9fe6651 100644 --- a/examples/northwind/handlers.ts +++ b/examples/northwind/handlers.ts @@ -674,7 +674,10 @@ export const ProductsLive = HttpApiBuilder.group(Api, "products", (handlers) => loadProduct(params.id).pipe( Effect.map((product) => Handlers.data(product, { - included: resolveProductIncluded(product, query.include), + included: + query.include === undefined + ? undefined + : resolveProductIncluded(product, query.include), self: `/products/${product.id}`, }), ), @@ -719,7 +722,10 @@ export const ProductsLive = HttpApiBuilder.group(Api, "products", (handlers) => return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((product) => resolveProductIncluded(product, query.include)), + included: + query.include === undefined + ? undefined + : page.flatMap((product) => resolveProductIncluded(product, query.include)), meta: { total }, links: Handlers.offsetPaginationLinks("/products", { offset, limit }, total), }), @@ -829,7 +835,10 @@ export const EmployeesLive = HttpApiBuilder.group(Api, "employees", (handlers) = loadEmployee(params.id).pipe( Effect.map((employee) => Handlers.data(employee, { - included: resolveEmployeeIncluded(employee, query.include), + included: + query.include === undefined + ? undefined + : resolveEmployeeIncluded(employee, query.include), self: `/employees/${employee.id}`, }), ), @@ -846,7 +855,10 @@ export const EmployeesLive = HttpApiBuilder.group(Api, "employees", (handlers) = const { limit, offset, page, total } = paginate(employees, query.page); return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((employee) => resolveEmployeeIncluded(employee, query.include)), + included: + query.include === undefined + ? undefined + : page.flatMap((employee) => resolveEmployeeIncluded(employee, query.include)), meta: { total }, links: Handlers.offsetPaginationLinks("/employees", { offset, limit }, total), }), @@ -940,7 +952,8 @@ export const OrdersLive = HttpApiBuilder.group(Api, "orders", (handlers) => loadOrder(params.id).pipe( Effect.map((order) => Handlers.data(order, { - included: resolveOrderIncluded(order, query.include), + included: + query.include === undefined ? undefined : resolveOrderIncluded(order, query.include), self: `/orders/${order.id}`, }), ), @@ -977,7 +990,10 @@ export const OrdersLive = HttpApiBuilder.group(Api, "orders", (handlers) => return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((order) => resolveOrderIncluded(order, query.include)), + included: + query.include === undefined + ? undefined + : page.flatMap((order) => resolveOrderIncluded(order, query.include)), meta: { total }, links: Handlers.offsetPaginationLinks("/orders", { offset, limit }, total), }), @@ -1034,7 +1050,10 @@ export const OrdersLive = HttpApiBuilder.group(Api, "orders", (handlers) => const { limit, offset, page, total } = paginate(all, query.page); const path = Handlers.relatedLink("orders", order.id, "lineItems"); return Handlers.collection(page, { - included: page.flatMap((item) => resolveOrderItemIncluded(item, query.include)), + included: + query.include === undefined + ? undefined + : page.flatMap((item) => resolveOrderItemIncluded(item, query.include)), meta: { total }, links: Handlers.offsetPaginationLinks(path, { offset, limit }, total), }); @@ -1099,9 +1118,12 @@ export const SearchLive = HttpApiBuilder.group(Api, "search", (handlers) => return Effect.succeed( Handlers.collection(page, { - included: page.flatMap((result) => - result.type === "products" ? resolveProductIncluded(result, query.include) : [], - ), + included: + query.include === undefined + ? undefined + : page.flatMap((result) => + result.type === "products" ? resolveProductIncluded(result, query.include) : [], + ), meta: { total }, links: Handlers.offsetPaginationLinks("/search", { offset, limit }, total), }), diff --git a/src/Assemble.test.ts b/src/Assemble.test.ts index 8d50cf81..5d55cc4d 100644 --- a/src/Assemble.test.ts +++ b/src/Assemble.test.ts @@ -238,14 +238,33 @@ describe("Assemble.resource", () => { ]); }); - it("emits no `included` when no include is requested, or no registry is wired", async () => { + it("emits no `included` when no include is requested", async () => { expect( - (await run(Assemble.resource(person("p1"), { includable: ["birthPlace"] }))).included, - ).toBeUndefined(); + await run(Assemble.resource(person("p1"), { includable: ["birthPlace"] })), + ).not.toHaveProperty("included"); + expect( + await run(Assemble.resource(person("p1"), { include: [], includable: ["birthPlace"] })), + ).not.toHaveProperty("included"); + }); + + it("emits `included: []` when include was requested and nothing resolved (#232)", async () => { + // §Fetching Includes: a response to a request carrying `include` MUST be a + // compound document with an `included` key, even an empty one. const validatedOnly = await run( Assemble.resource(person("p1"), { include: ["birthPlace"], includable: ["birthPlace"] }), ); - expect(validatedOnly.included).toBeUndefined(); + expect(validatedOnly.included).toEqual([]); + // A registry that cannot resolve the ref: the walk answers `[]`. + const { calls, targets } = registry([party("party-1")]); + const unresolved = await run( + Assemble.resource(person("p1"), { + include: ["birthPlace"], + includable: ["birthPlace"], + targets, + }), + ); + expect(calls).toEqual([]); + expect(unresolved.included).toEqual([]); }); it("rejects an include path outside the whitelist, naming the allowed paths", async () => { @@ -367,7 +386,7 @@ describe("Assemble.collection", () => { } }); - it("emits pre-resolved included members, link-coerced, and omits the member when empty", async () => { + it("emits pre-resolved included members, link-coerced, and omits the member when empty and unrequested", async () => { const withIncluded = await run( Assemble.collection( page, @@ -391,6 +410,17 @@ describe("Assemble.collection", () => { ) ).included, ).toBeUndefined(); + // Members that are all primary data, with no `include` on the request: + // the dedupe leaves nothing, and there is no request to answer with `[]`. + expect( + await run( + Assemble.collection( + [person("a"), place], + { totalCount: 2, offset: 0, limit: 10, baseUrl }, + { included: [place] }, + ), + ), + ).not.toHaveProperty("included"); }); it("does not repeat a page member in `included` (#147)", async () => { @@ -409,7 +439,34 @@ describe("Assemble.collection", () => { ); expect(calls).toEqual([]); expect(ids(document.data)).toEqual(["people:a", "places:place-1"]); - expect(document.included).toBeUndefined(); + // Every candidate was a hit, but the request carried `include`, so the + // compound document keeps its `included` key, empty (#232). + expect(document.included).toEqual([]); + }); + + it("emits `included: []` when include was requested and nothing resolved (#232)", async () => { + const { calls, targets } = registry([]); + const document = await run( + Assemble.collection( + page, + { totalCount: 3, offset: 0, limit: 10, baseUrl }, + { include: ["birthPlace"], includable: ["birthPlace"], targets }, + ), + ); + expect(calls).toEqual([]); + expect(document.included).toEqual([]); + // An empty page answers the same way. + expect( + ( + await run( + Assemble.collection( + [], + { totalCount: 0, offset: 0, limit: 10, baseUrl }, + { include: ["birthPlace"], includable: ["birthPlace"], targets }, + ), + ) + ).included, + ).toEqual([]); }); it("resolves the page's include walk in one batch per target type, deduplicated", async () => { @@ -532,9 +589,34 @@ describe("Assemble.unpaginatedCollection", () => { expect(calls).toEqual([]); expect(ids(deduped.data)).toEqual(["contests:x", "elections:election-1"]); expect(ids(deduped.included)).toEqual(["candidates:c-1"]); - expect( - (await run(Assemble.unpaginatedCollection(whole, { included: [] }))).included, - ).toBeUndefined(); + expect(await run(Assemble.unpaginatedCollection(whole, { included: [] }))).not.toHaveProperty( + "included", + ); + }); + + it("emits `included: []` when include was requested and nothing remains (#232)", async () => { + const { calls, targets } = registry([]); + const unresolved = await run( + Assemble.unpaginatedCollection(whole, { + include: ["birthPlace"], + includable: ["birthPlace"], + targets, + }), + ); + expect(calls).toEqual([]); + expect(unresolved.included).toEqual([]); + // Every candidate is already primary data: the dedupe leaves nothing, and + // the key stays. + const deduped = await run( + Assemble.unpaginatedCollection([contest("x"), election], { + included: [election], + include: ["election"], + includable: ["election"], + targets, + }), + ); + expect(ids(deduped.data)).toEqual(["contests:x", "elections:election-1"]); + expect(deduped.included).toEqual([]); }); it("assembles what `collection` does, less its links and meta", async () => { diff --git a/src/Assemble.ts b/src/Assemble.ts index 1c8fb8b1..efdcc2c2 100644 --- a/src/Assemble.ts +++ b/src/Assemble.ts @@ -24,6 +24,12 @@ * disagree about what a ref resolves to and a page's walk is never N round * trips. * + * A request carrying `include` always answers a compound document: the + * `included` key is present, `[]` when nothing resolved or every candidate was + * already primary data (JSON:API 1.1 §Fetching Includes). Without `include` + * the key is absent unless members the caller resolved itself survive the + * dedupe against the primary data. + * * ## Capabilities * * `meta.canEdit` / `meta.canDelete` advertise what the viewer may do to a @@ -363,7 +369,9 @@ export interface Options(options: Options) => const asValue = (resource: ResourceLike): Handlers.ResourceValue => resource as unknown as Handlers.ResourceValue; -/** Validates the requested paths, then walks them — or answers nothing when no walk was asked for. */ +/** + * Validates the requested paths, then walks them. `undefined` means the + * request carried no `include`, and only that: a request that did gets an + * array, `[]` when there is no registry to walk through, so the document + * keeps its `included` key (§Fetching Includes, #232). + */ const walk = ( primary: ReadonlyArray, options: Options, @@ -695,7 +708,7 @@ const walk = ( }).pipe( Effect.flatMap(() => options.targets === undefined - ? Effect.succeed(undefined) + ? Effect.succeed([]) : Handlers.resolveIncluded(primary.map(asValue), include, options.targets, { depth, concurrency: options.concurrency, @@ -768,7 +781,8 @@ export const resource = < Effect.map((included) => { const built = Handlers.data(asValue(wired), { ...(wired.links?.self === undefined ? {} : { self: wired.links.self }), - ...(included === undefined || included.length === 0 + // An empty walk keeps the key: the request carried `include` (#232). + ...(included === undefined ? {} : { included: included.map((r) => asValue(stringifyLinks(r))) }), onResource: onResourceFor(options), @@ -778,6 +792,18 @@ export const resource = < ); }; +// A document answering a request that carried no `include` keeps `included` +// only when something is in it: the caller may have resolved no members of +// its own, or only members that are primary data, which the builders' dedupe +// then drops, leaving their empty array. +const withoutEmptyIncluded = }>( + document: T, +): T => { + if (document.included === undefined || document.included.length > 0) return document; + const { included: _included, ...rest } = document; + return rest as T; +}; + /** * The shared body of {@link collection} and {@link unpaginatedCollection}: * link coercion, the batched walk, the caller's pre-resolved `included`, the @@ -803,19 +829,24 @@ const assembleCollection = ( const wired = resources.map(stringifyLinks); return walk(wired, options).pipe( Effect.map((resolved) => { + // `resolved` is an array exactly when the request carried `include`. + const requested = resolved !== undefined; const included = [...(options.included ?? []), ...(resolved ?? [])]; const built = Handlers.collection(wired.map(asValue), { ...top, - ...(included.length === 0 - ? {} - : { included: included.map((r) => asValue(stringifyLinks(r))) }), + included: included.map((r) => asValue(stringifyLinks(r))), onResource: onResourceFor(options), }); // SAFETY: `Handlers.collection` types its value over the builders' loose // `ResourceValue`; the value is `D` by construction — the wired, stamped - // resources, `included` only when non-empty, exactly the `top` members - // the caller's `D` declares, and the `jsonapi` member. - return { ...built, jsonapi: JSONAPI_MEMBER } as unknown as D; + // resources, `included` when the request carried `include` (empty if + // nothing remains, #232) or when members survive the dedupe against + // the primary data, exactly the `top` members the caller's `D` + // declares, and the `jsonapi` member. + return { + ...(requested ? built : withoutEmptyIncluded(built)), + jsonapi: JSONAPI_MEMBER, + } as unknown as D; }), ); }; diff --git a/src/Handlers.include.test.ts b/src/Handlers.include.test.ts index 48f6e798..1541ef94 100644 --- a/src/Handlers.include.test.ts +++ b/src/Handlers.include.test.ts @@ -711,6 +711,19 @@ describe("Handlers.resolveIncluded — composing a document", () => { expect(document).toEqual({ data: article1 }); expect("included" in document).toBe(false); }); + + it("keeps an empty `included` when the walk resolved to nothing (#232)", async () => { + // §Fetching Includes: a request carrying `include` gets a compound + // document with an `included` key, even an empty one. `[]` from the walk + // reaches the wire as `included: []`, not as an omitted member. + const db = store(graph); + const document = await run( + Handlers.resolveIncluded(article1, ["editor"], db.targets("people")).pipe( + Effect.map((included) => Handlers.data(article1, { included })), + ), + ); + expect(document).toEqual({ data: article1, included: [] }); + }); }); describe("Handlers.resolveIncluded — types", () => { diff --git a/src/Handlers.test.ts b/src/Handlers.test.ts index 120621f4..e4e0ace6 100644 --- a/src/Handlers.test.ts +++ b/src/Handlers.test.ts @@ -90,8 +90,26 @@ describe("Handlers.data", () => { expect(Handlers.data(selfLinked, { included: [selfLinked, author] }).included).toEqual([ author, ]); - // …and when it was the only candidate, there is no `included` member at all. - expect(Handlers.data(selfLinked, { included: [selfLinked] })).toEqual({ data: selfLinked }); + // …and when it was the only candidate, `included` is still there, empty: + // the caller asked for a compound document (#232). + expect(Handlers.data(selfLinked, { included: [selfLinked] })).toEqual({ + data: selfLinked, + included: [], + }); + }); + + it("emits `included: []` when the caller passed an empty array (#232)", () => { + // JSON:API 1.1 §Fetching Includes: a response to a request carrying + // `include` MUST be a compound document with an `included` key, even if it + // holds an empty array. An array — however empty — is the caller saying so. + expect(Handlers.data(article, { included: [] })).toEqual({ data: article, included: [] }); + expect(Handlers.data(null, { included: [] })).toEqual({ data: null, included: [] }); + }); + + it("omits `included` when the caller passed `undefined` (#232)", () => { + // `undefined` is "no include was requested": the document stays bare. + expect(Handlers.data(article, { included: undefined })).toEqual({ data: article }); + expect("included" in Handlers.data(article, { included: undefined })).toBe(false); }); }); @@ -123,10 +141,23 @@ describe("Handlers.collection", () => { expect(doc.included).toEqual([comment]); }); - it("omits `included` when every candidate is already primary data (#147)", () => { + it("keeps an empty `included` when every candidate is already primary data (#147, #232)", () => { + // `/search?include=author` where every author is also a hit: the dedupe + // against primary data leaves nothing, and the request still carried + // `include`, so the compound document keeps its (empty) `included` key. expect(Handlers.collection([article, author], { included: [author, author] })).toEqual({ data: [article, author], + included: [], + }); + }); + + it("emits `included: []` for an empty array and omits it for `undefined` (#232)", () => { + expect(Handlers.collection([article], { included: [] })).toEqual({ + data: [article], + included: [], }); + expect(Handlers.collection([], { included: [] })).toEqual({ data: [], included: [] }); + expect(Handlers.collection([article], { included: undefined })).toEqual({ data: [article] }); }); it("appends the request's canonical query to the self link", () => { @@ -441,7 +472,7 @@ describe("the per-resource transform pass", () => { }, }); expect(runs).toBe(1); - expect(document.included).toBeUndefined(); + expect(document.included).toEqual([]); }); it("runs before the full-linkage check — a transform that breaks linkage is caught", () => { diff --git a/src/Handlers.ts b/src/Handlers.ts index cd89ff6f..3118b7d8 100644 --- a/src/Handlers.ts +++ b/src/Handlers.ts @@ -12,6 +12,13 @@ * primary data by following resource linkage — the primary data's * relationships, then other included resources' relationships * + * `included` keeps the request's shape: an array — even one that is empty, or + * that dedup against the primary data empties — emits the member, because 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" + * (JSON:API 1.1 §Fetching Includes). Pass `undefined` when the request carried + * no `include`, and the member is omitted. + * * They also take an `onResource` hook — a per-resource transform run **once * per resource, in every slot**: the primary `data`, every deduplicated * `included` member, and the identifiers of a linkage document. That is what @@ -23,7 +30,8 @@ * handlers.handle("fetch", ({ params, query }) => * loadArticle(params.id).pipe(Effect.map((article) => * data(article, { - * included: query.include?.includes("author") ? [author] : [], + * // `undefined` without `?include=`; `[]` when it names nothing to load + * included: query.include === undefined ? undefined : query.include.includes("author") ? [author] : [], * self: `/articles/${article.id}` * }) * )) @@ -987,8 +995,11 @@ const resolve = ( * target, an id the batch didn't return, a row the viewer may not see: all * are normal outcomes, and simply absent from `included`. A loader's own * failure propagates and fails the document. - * - **`undefined` when nothing was requested**, so the caller omits the member. - * An empty array is the different statement "your walk resolved to nothing". + * - **`undefined` when nothing was requested**, so the builders omit the + * member. An empty array is the different statement "your walk resolved to + * nothing", and {@link data} / {@link collection} emit it as `included: []` + * — §Fetching Includes requires the key in every response to a request + * carrying `include`. * * **Full linkage holds by construction — for the array this returns.** Every * member is reached *through* the linkage of the primary data the walk started @@ -1202,16 +1213,18 @@ const build = ( onResource: ResourceTransform | undefined, ) => { const links = options === undefined ? undefined : buildLinks(options); - // Omitted, not `[]`, when nothing survives dedup against the primary data — - // the same shape as a document that was handed no `included` at all. - const members = + // An array — however empty, and however empty dedup against the primary + // data leaves it — is a compound document, and keeps its `included` key: + // §Fetching Includes requires one in every response to a request carrying + // `include`, "even if that `included` key holds an empty array" (#232). + // Only `undefined` (nothing was requested) omits the member. + const included = options?.included === undefined - ? [] + ? undefined : buildIncluded(primary, options.included, { checkLinkage: options.checkLinkage, onResource, }); - const included = Arr.isReadonlyArrayNonEmpty(members) ? members : undefined; return { data, ...(included !== undefined ? { included } : {}), @@ -1225,7 +1238,10 @@ const build = ( * Builds a single-resource document value: `{ data, included?, links?, meta?, jsonapi? }`. * * Included resources are deduplicated — against each other and against the - * primary data — and checked for full linkage. + * primary data — and checked for full linkage. Any `included` array, empty + * or emptied by that dedup, is emitted (`included: []`): pass one whenever the + * request carried `include`, and `undefined` when it did not, so the member + * is omitted (JSON:API 1.1 §Fetching Includes). * * Pass `jsonapi` to stamp the top-level `jsonapi` object — `Document.v1_1` to * advertise JSON:API 1.1, or `Atomic.jsonapi` for the atomic-operations @@ -1280,7 +1296,10 @@ const build = ( * loadArticle(params.id).pipe( * Effect.map((article) => * Handlers.data(article, { - * included: query.include?.includes("author") ? [author] : [], + * // `undefined` without `?include=` (no `included` member); `[]` + * // when it named nothing that resolved (`included: []`) + * included: + * query.include === undefined ? undefined : query.include.includes("author") ? [author] : [], * jsonapi: Document.v1_1, * self: `/articles/${article.id}` * }) @@ -1333,6 +1352,11 @@ export const data = < >( resource: R, options?: { + /** + * The compound document's members. An array — even `[]` — emits + * `included`; `undefined` omits it. Pass an array whenever the request + * carried `include` (JSON:API 1.1 §Fetching Includes). + */ readonly included?: ReadonlyArray | undefined; readonly meta?: M; /** The top-level `jsonapi` object, e.g. `Document.v1_1`. Omitted by default. */ @@ -1377,7 +1401,10 @@ export const data = < * Builds a collection document value: `{ data: [...], included?, links?, meta?, jsonapi? }`. * * Included resources are deduplicated — against each other and against the - * primary data — and checked for full linkage. + * primary data — and checked for full linkage. As with {@link data}, any + * `included` array is emitted, even empty — a heterogeneous collection whose + * every include candidate is already a hit answers `included: []` — and + * `undefined` omits the member. * * JSON:API 1.1 requires a collection's `self` link to carry the query * parameters the client provided. Pass `query` — the request's canonical @@ -1449,6 +1476,11 @@ export const collection = < >( resources: ReadonlyArray, options?: { + /** + * The compound document's members. An array — even `[]` — emits + * `included`; `undefined` omits it. Pass an array whenever the request + * carried `include` (JSON:API 1.1 §Fetching Includes). + */ readonly included?: ReadonlyArray | undefined; readonly meta?: M; /** The top-level `jsonapi` object, e.g. `Document.v1_1`. Omitted by default. */