Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/empty-included-on-include.md
Original file line number Diff line number Diff line change
@@ -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.
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down
25 changes: 16 additions & 9 deletions examples/blog/handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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}`,
}),
),
Expand Down Expand Up @@ -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),
}),
Expand Down Expand Up @@ -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),
});
Expand Down Expand Up @@ -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) : [],
),
Expand Down
30 changes: 30 additions & 0 deletions examples/blog/test/blog.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 () => {
Expand Down Expand Up @@ -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();
Expand Down
60 changes: 39 additions & 21 deletions examples/github/handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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}`,
}),
),
Expand Down Expand Up @@ -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),
}),
Expand Down Expand Up @@ -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}`,
}),
),
Expand Down Expand Up @@ -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),
}),
Expand Down Expand Up @@ -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),
});
Expand Down Expand Up @@ -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}`,
}),
),
Expand All @@ -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),
}),
Expand Down Expand Up @@ -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),
}),
Expand Down
Loading
Loading