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
2 changes: 1 addition & 1 deletion .changeset/dedupe-included-against-primary.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
"@thomasfosterau/effect-jsonapi": patch
---

`Handlers.data`, `Handlers.collection`, `Handlers.buildIncluded` and the `Assemble` builders that route through them no longer emit a resource in `included` when it is already present as primary data. A compound document now carries one resource object per `(type, id)` pair, as JSON:API requires — previously a heterogeneous collection whose include target was also one of the hits (e.g. `/search?include=author`) repeated that resource in `included`. When every `included` candidate is already primary data, the `included` member is omitted, as it is when none is passed — so a call that passes a primary resource in `included` with nothing referencing it (e.g. `Handlers.data(article, { included: [article] })`), which used to fail the full-linkage check, now succeeds with `included` omitted.
`Handlers.data`, `Handlers.collection`, `Handlers.buildIncluded` and the `Assemble` builders that route through them no longer emit a resource in `included` when it is already present as primary data. A compound document now carries one resource object per `(type, id)` pair, as JSON:API requires — previously a heterogeneous collection whose include target was also one of the hits (e.g. `/search?include=author`) repeated that resource in `included`. When every `included` candidate is already primary data, `Handlers.data` and `Handlers.collection` emit `included: []`, as they do any `included` array they are given, and the `Assemble` builders do the same when the request carried `include` (without `include` they omit the key) — so a call that passes a primary resource in `included` with nothing referencing it (e.g. `Handlers.data(article, { included: [article] })`), which used to fail the full-linkage check, now succeeds with `included: []`.
5 changes: 5 additions & 0 deletions .changeset/included-key-on-bare-include.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@thomasfosterau/effect-jsonapi": patch
---

Presence of `include` now decides the `included` key everywhere. A bare `?include=` decodes to `[]`; `Assemble.resource` / `Assemble.collection` / `Assemble.unpaginatedCollection` used to treat that as no `include` and omit the key, and now answer it with `included: []`, as does `Handlers.resolveIncluded`, which returns `[]` for an empty path list instead of `undefined`. `ResourceHandlers.related` answers a to-one with empty linkage `{ data: null, included: [] }` when the request carried `include`, and validates those paths first, so an unsupported path is a `400` there as it is for a resolved to-one (it used to answer `200` with no `included`). `Handlers.DocumentValue` now always declares an optional `included`, so `Handlers.data(r, { included: [] }).included` type-checks.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1175,7 +1175,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 builders omit the member. `[]` is the different statement "your walk resolved to nothing", which they emit as `included: []` |
| **`undefined` when unasked** | So the builders omit the member. `[]` is the different statement "your walk resolved to nothing" (a bare `?include=`, an empty path list, answers it too), 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 @@ -1536,7 +1536,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. 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.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. Presence is the signal: a bare `?include=` decodes to `[]` and is a request carrying `include` too. Without `include` the key is absent unless members the caller resolved itself survive the dedupe. `ResourceHandlers.related` answers an empty to-one the same way: `{ data: null, included: [] }` when the request carried `include`, its paths validated (`400` for one outside the whitelist) though there is nothing to walk from.

`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
35 changes: 35 additions & 0 deletions examples/github/test/github.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,41 @@ describe("github example: fetching", () => {
expect(document.included?.map((resource) => resource.type)).toEqual(["users"]);
});

it("omits `included` when the request carries no `include` (#232)", async () => {
const { list, one } = await run(
Effect.gen(function* () {
const client = yield* buildClient;
const one = yield* client.repositories.get({
params: { id: Repository.Id.make("1") },
query: {},
});
const list = yield* client.repositories.list({ query: {} });
return { list, one };
}),
);
expect(one).not.toHaveProperty("included");
expect(list).not.toHaveProperty("included");
});

it("answers `?include=` with no paths with an empty `included` (#232)", async () => {
// `include: []` goes on the wire as a bare `?include=`, which decodes to
// `[]`: the request carried `include`, so the compound document keeps its
// key (§Fetching Includes), empty because no path names anything to load.
const { list, one } = await run(
Effect.gen(function* () {
const client = yield* buildClient;
const one = yield* client.repositories.get({
params: { id: Repository.Id.make("1") },
query: { include: [] },
});
const list = yield* client.repositories.list({ query: { include: [] } });
return { list, one };
}),
);
expect(one.included).toEqual([]);
expect(list.included).toEqual([]);
});

it("resolves 2-hop include paths: issue → repository → owner", async () => {
const document = await run(
Effect.gen(function* () {
Expand Down
13 changes: 13 additions & 0 deletions examples/northwind/test/northwind.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,19 @@ describe("northwind example: fetching", () => {
]);
});

it("omits `included` when the request carries no `include` (#232)", async () => {
const { list, one } = await run(
Effect.gen(function* () {
const client = yield* buildClient;
const one = yield* client.products.get({ params: { id: Product.Id.make("1") }, query: {} });
const list = yield* client.products.list({ query: {} });
return { list, one };
}),
);
expect(one).not.toHaveProperty("included");
expect(list).not.toHaveProperty("included");
});

it("narrows `included` to the requested include paths on the client", async () => {
const include = ["category"] as const;
const document = await run(
Expand Down
44 changes: 42 additions & 2 deletions src/Assemble.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -242,9 +242,15 @@ describe("Assemble.resource", () => {
expect(
await run(Assemble.resource(person("p1"), { includable: ["birthPlace"] })),
).not.toHaveProperty("included");
});

it("emits `included: []` for `?include=` with no paths: the request carried `include` (#232)", async () => {
// Presence is the signal: `?include=` decodes to `[]`, and a client that
// supplied `include`, even empty, gets the compound document's key.
expect(
await run(Assemble.resource(person("p1"), { include: [], includable: ["birthPlace"] })),
).not.toHaveProperty("included");
(await run(Assemble.resource(person("p1"), { include: [], includable: ["birthPlace"] })))
.included,
).toEqual([]);
});

it("emits `included: []` when include was requested and nothing resolved (#232)", async () => {
Expand Down Expand Up @@ -469,6 +475,24 @@ describe("Assemble.collection", () => {
).toEqual([]);
});

it("emits `included: []` in validate-only mode: include, no registry (#232)", async () => {
const pagination = { totalCount: 3, offset: 0, limit: 10, baseUrl };
expect(
(
await run(
Assemble.collection(page, pagination, {
include: ["birthPlace"],
includable: ["birthPlace"],
}),
)
).included,
).toEqual([]);
// `?include=` with no paths is still a request that carried `include`.
expect(
(await run(Assemble.collection(page, pagination, { include: [], includable: [] }))).included,
).toEqual([]);
});

it("resolves the page's include walk in one batch per target type, deduplicated", async () => {
const { calls, targets } = registry([place]);
const document = await run(
Expand Down Expand Up @@ -619,6 +643,22 @@ describe("Assemble.unpaginatedCollection", () => {
expect(deduped.included).toEqual([]);
});

it("emits `included: []` in validate-only mode: include, no registry (#232)", async () => {
expect(
(
await run(
Assemble.unpaginatedCollection(whole, {
include: ["birthPlace"],
includable: ["birthPlace"],
}),
)
).included,
).toEqual([]);
expect(
(await run(Assemble.unpaginatedCollection(whole, { include: [], includable: [] }))).included,
).toEqual([]);
});

it("assembles what `collection` does, less its links and meta", async () => {
const options = {
viewer: NON_ADMIN,
Expand Down
18 changes: 12 additions & 6 deletions src/Assemble.ts
Original file line number Diff line number Diff line change
Expand Up @@ -358,7 +358,12 @@ export interface Options<V = unknown, Targets extends Handlers.IncludeTargets =
* caller wants. Empty / missing means the full resource.
*/
readonly fields?: Handlers.Fields | undefined;
/** The requested `?include=` paths (JSON:API §7.1 dot paths). */
/**
* The requested `?include=` paths (JSON:API §7.1 dot paths), or `undefined`
* when the request carried no `include`. Presence is the signal: any array,
* even the `[]` a bare `?include=` decodes to, answers with the `included`
* key.
*/
readonly include?: ReadonlyArray<string> | undefined;
/**
* The legal include paths — anything else fails
Expand Down Expand Up @@ -685,9 +690,10 @@ const asValue = (resource: ResourceLike): Handlers.ResourceValue =>

/**
* 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).
* request carried no `include`, and only that: a request that did — even a
* bare `?include=`, which decodes to `[]` — gets an array, `[]` when there is
* no registry to walk through or no path to walk, so the document keeps its
* `included` key (§Fetching Includes, #232).
*/
const walk = <Targets extends Handlers.IncludeTargets>(
primary: ReadonlyArray<ResourceLike>,
Expand All @@ -699,8 +705,8 @@ const walk = <Targets extends Handlers.IncludeTargets>(
| Handlers.IncludeTargetError<Targets>,
Handlers.IncludeTargetServices<Targets>
> => {
const include = options.include ?? [];
if (include.length === 0) return Effect.succeed(undefined);
const include = options.include;
if (include === undefined) return Effect.succeed(undefined);
const depth = options.depth ?? MAX_INCLUDE_DEPTH;
return Query.validateIncludePaths(include, {
includable: options.includable ?? [],
Expand Down
10 changes: 8 additions & 2 deletions src/Handlers.include.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -97,16 +97,22 @@ const graph: ReadonlyArray<Handlers.ResourceValue> = [
const run = <A, E>(effect: Effect.Effect<A, E>) => Effect.runPromise(effect);

describe("Handlers.resolveIncluded — nothing requested", () => {
it("resolves to undefined when no paths were requested, so the member is omitted", async () => {
it("resolves to undefined when no `include` was requested, so the member is omitted", async () => {
const db = store(graph);
expect(
await run(Handlers.resolveIncluded(article1, undefined, db.targets("people"))),
).toBeUndefined();
expect(await run(Handlers.resolveIncluded(article1, [], db.targets("people")))).toBeUndefined();
// and nothing was loaded to find that out
expect(db.calls).toEqual([]);
});

it("resolves to [] for `?include=` with no paths: the request carried `include` (#232)", async () => {
const db = store(graph);
expect(await run(Handlers.resolveIncluded(article1, [], db.targets("people")))).toEqual([]);
// nothing to walk, so nothing loaded
expect(db.calls).toEqual([]);
});

it("resolves to [] — not undefined — when the walk ran and came back empty", async () => {
const db = store(graph);
const empty: Handlers.ResourceValue = { type: "articles", id: "7" };
Expand Down
54 changes: 30 additions & 24 deletions src/Handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -995,11 +995,12 @@ 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 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`.
* - **`undefined` when nothing was requested** (`paths` is `undefined`), so
* the builders omit the member. An empty array is the different statement
* "your walk resolved to nothing" — including for an empty `paths`, which is
* a bare `?include=`: the request carried `include` — and {@link data} /
* {@link collection} emit it as `included: []`, because §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
Expand Down Expand Up @@ -1106,15 +1107,17 @@ export const resolveIncluded = <Targets extends IncludeTargets>(
IncludeTargetError<Targets>,
IncludeTargetServices<Targets>
> =>
(paths === undefined || paths.length === 0
(paths === undefined
? Effect.succeed(undefined)
: resolve(
primary === null ? [] : Array.isArray(primary) ? primary : [primary as ResourceValue],
paths,
targets,
options?.concurrency ?? "unbounded",
options?.depth ?? 3,
)) as Effect.Effect<
: paths.length === 0
? Effect.succeed([])
: resolve(
primary === null ? [] : Array.isArray(primary) ? primary : [primary as ResourceValue],
paths,
targets,
options?.concurrency ?? "unbounded",
options?.depth ?? 3,
)) as Effect.Effect<
ReadonlyArray<IncludeTargetResource<Targets>> | undefined,
IncludeTargetError<Targets>,
IncludeTargetServices<Targets>
Expand All @@ -1125,17 +1128,19 @@ export const resolveIncluded = <Targets extends IncludeTargets>(
* {@link collection} return, named so consumers can annotate their own
* document-assembling functions instead of hand-rolling the envelope type.
*
* The `jsonapi` member is *conditional* on `J`, the same way `included` is
* conditional on `Included` and `meta` on `M`: it is present (and required,
* not optional — a builder that infers `J` from an argument has one to put
* there) only when a caller actually passed the `jsonapi` option, so the
* return type of `Handlers.data(article, { jsonapi: Document.v1_1 })` carries
* The `jsonapi` member is *conditional* on `J`, the same way `meta` is
* conditional on `M`: it is present (and required, not optional — a builder
* that infers `J` from an argument has one to put there) only when a caller
* actually passed the `jsonapi` option, so the return type of
* `Handlers.data(article, { jsonapi: Document.v1_1 })` carries
* `jsonapi: Document.JsonApiObjectValue` and the return type of
* `Handlers.data(article)` has no `jsonapi` member at all — no cast needed
* either way.
* either way. `included` is always declared, optional: a builder emits any
* array it is given, so `Handlers.data(article, { included: [] })` — whose
* literal `[]` infers `Included = never` — still reads back `included: []`.
*
* The type stays *conditional* on its generics so TypeScript only infers
* `Included` / `M` / `J` from arguments — never from the expected (contextual)
* `M` / `J` from arguments — never from the expected (contextual)
* return type of a handler, which breaks down inside `pipe(Effect.map(...))`
* chains.
*
Expand All @@ -1148,10 +1153,11 @@ export type DocumentValue<
M extends MetaValue = never,
J extends JsonApiObjectValue = never,
> = Simplify<
{ readonly data: Data; readonly links?: LinksValue } & ([Included] extends [never]
? {}
: { readonly included?: ReadonlyArray<Included> }) &
([M] extends [never] ? {} : { readonly meta?: M }) &
{
readonly data: Data;
readonly included?: ReadonlyArray<Included>;
readonly links?: LinksValue;
} & ([M] extends [never] ? {} : { readonly meta?: M }) &
([J] extends [never] ? {} : { readonly jsonapi: J })
>;

Expand Down
Loading
Loading