From b4b58a0fb91db35d777fccb90966ba920423054a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 02:36:52 +0000 Subject: [PATCH 1/2] feat(Assemble): capabilitiesOnIncluded to stamp primary data only (#567) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Y5G6PMempKsgjiV1NDcCJY --- .changeset/capabilities-on-included.md | 5 ++ src/Assemble.test.ts | 70 ++++++++++++++++++++++++++ src/Assemble.ts | 41 ++++++++++++--- src/ResourceHandlers.test.ts | 19 ++++++- src/ResourceHandlers.ts | 16 ++++-- 5 files changed, 139 insertions(+), 12 deletions(-) create mode 100644 .changeset/capabilities-on-included.md diff --git a/.changeset/capabilities-on-included.md b/.changeset/capabilities-on-included.md new file mode 100644 index 00000000..1526cc21 --- /dev/null +++ b/.changeset/capabilities-on-included.md @@ -0,0 +1,5 @@ +--- +"@thomasfosterau/effect-jsonapi": minor +--- + +Add `capabilitiesOnIncluded` to `Assemble.Options` (and `Assemble.RelationshipInput`, and the `ResourceHandlers` read-only, writable and related configs): `false` stamps the `capabilities` hook's result on primary data only, leaving `included` members without capability `meta`. It defaults to `true`, today's behaviour, so existing callers are unchanged. From gardeneria#1263 O5. diff --git a/src/Assemble.test.ts b/src/Assemble.test.ts index e25f3709..24628e2d 100644 --- a/src/Assemble.test.ts +++ b/src/Assemble.test.ts @@ -237,6 +237,35 @@ describe("Assemble.resource", () => { }), ); + it.effect("stamps included members unless `capabilitiesOnIncluded` is false", () => + Effect.gen(function* () { + const stamped = { canEdit: true, canDelete: true }; + const { targets } = registry([place]); + const options = { + viewer: ADMIN, + capabilities: familyCapabilities, + include: ["birthPlace"], + includable: ["birthPlace"], + targets, + }; + const both = yield* Assemble.resource(person("p1"), options); + expect(both.data.meta).toEqual(stamped); + expect(both.included?.[0]?.meta).toEqual(stamped); + const explicit = yield* Assemble.resource(person("p1"), { + ...options, + capabilitiesOnIncluded: true, + }); + expect(explicit.included?.[0]?.meta).toEqual(stamped); + const primaryOnly = yield* Assemble.resource(person("p1"), { + ...options, + capabilitiesOnIncluded: false, + }); + expect(primaryOnly.data.meta).toEqual(stamped); + expect(primaryOnly.included).toHaveLength(1); + expect(primaryOnly.included?.[0]).not.toHaveProperty("meta"); + }), + ); + it.effect("resolves a to-many include in one loader call per level", () => Effect.gen(function* () { const { calls, targets } = registry([candidate("c-1"), candidate("c-2")]); @@ -575,6 +604,28 @@ describe("Assemble.collection", () => { expect(document.included?.[0]?.meta).toEqual({ canEdit: false, canDelete: false }); }), ); + + it.effect("stamps the page only when `capabilitiesOnIncluded` is false", () => + Effect.gen(function* () { + const stamped = { canEdit: true, canDelete: true }; + const { targets } = registry([place]); + const document = yield* Assemble.collection( + page, + { totalCount: 3, offset: 0, limit: 10, baseUrl }, + { + viewer: ADMIN, + capabilities: familyCapabilities, + capabilitiesOnIncluded: false, + include: ["birthPlace"], + includable: ["birthPlace"], + targets, + }, + ); + expect(document.data.map((resource) => resource.meta)).toEqual(page.map(() => stamped)); + expect(document.included?.map((r) => r.id)).toEqual(["place-1"]); + expect(document.included?.[0]).not.toHaveProperty("meta"); + }), + ); }); describe("Assemble.unpaginatedCollection", () => { @@ -627,6 +678,25 @@ describe("Assemble.unpaginatedCollection", () => { }), ); + it.effect("leaves included members unstamped when `capabilitiesOnIncluded` is false", () => + Effect.gen(function* () { + const { targets } = registry([place]); + const document = yield* Assemble.unpaginatedCollection(whole, { + viewer: ADMIN, + capabilities: familyCapabilities, + capabilitiesOnIncluded: false, + include: ["birthPlace"], + includable: ["birthPlace"], + targets, + }); + expect(document.data.map((resource) => resource.meta)).toEqual( + whole.map(() => ({ canEdit: true, canDelete: true })), + ); + expect(ids(document.included)).toEqual(["places:place-1"]); + expect(document.included?.[0]).not.toHaveProperty("meta"); + }), + ); + it.effect("walks a nested path level by level", () => Effect.gen(function* () { const { targets } = registry([election, event]); diff --git a/src/Assemble.ts b/src/Assemble.ts index db1020b8..24c17867 100644 --- a/src/Assemble.ts +++ b/src/Assemble.ts @@ -40,12 +40,14 @@ * rung comparison), {@link ownedCapabilities} (the owner, or a moderator * acting for them) and {@link noCapabilities} (a family with no write * surface). No hook means no stamp: a family that publishes the pair passes - * one. + * one. Members of `included` are stamped too; pass + * `capabilitiesOnIncluded: false` to stamp the primary data only. * * @since 0.16.0 */ import * as Arr from "effect/Array"; import * as Effect from "effect/Effect"; +import * as HashSet from "effect/HashSet"; import * as P from "effect/Predicate"; import type * as ApiError from "./ApiError.js"; import type * as Document from "./Document.js"; @@ -395,6 +397,17 @@ export interface Options | undefined; + /** + * Whether `included` members are stamped with the {@link capabilities} + * rule too. Defaults to `true` — every emitted resource, primary and + * included alike. `false` stamps the primary data only; `included` members + * carry no capability `meta`. A relationship document's primary data is + * linkage, which carries no `meta`, so there `false` stamps nothing. + * + * @since 0.22.0 + * @category models + */ + readonly capabilitiesOnIncluded?: boolean; } /** @@ -733,10 +746,21 @@ export const toWireSafeResource = (resource: R): R => // --------------------------------------------------------------------------- /** The resource-level transform every emitted resource goes through. */ -const onResourceFor = (options: Options) => - Handlers.compose( +const onResourceFor = ( + options: Pick, "capabilities" | "capabilitiesOnIncluded" | "viewer" | "fields">, + primary: ReadonlyArray, +) => { + // With `capabilitiesOnIncluded: false` only the primary data is stamped. The + // one transform shapes both slots, so primary membership is by `(type, id)`; + // a resource that is both is shaped once, for the primary slot (#567). + const primaryKeys = + options.capabilitiesOnIncluded === false + ? HashSet.fromIterable(primary.map((r) => `${r.type}\0${r.id}`)) + : undefined; + return Handlers.compose( Handlers.withMeta((resource) => - options.capabilities === undefined + options.capabilities === undefined || + (primaryKeys !== undefined && !HashSet.has(primaryKeys, `${resource.type}\0${resource.id}`)) ? undefined : // The viewer is handed to the hook exactly as it was given: an // omitted option is `undefined`, which is then what `V` is. @@ -744,6 +768,7 @@ const onResourceFor = (options: Options) => ), Handlers.project(options.fields), ); +}; // `ResourceLike`'s `relationships` values widen to `unknown`, which the // builders' stricter `ResourceValue` rejects; the builders only read @@ -855,7 +880,7 @@ export const resource = < "included", included === undefined ? undefined : included.map((r) => asValue(stringifyLinks(r))), ), - onResource: onResourceFor(options), + onResource: onResourceFor(options, [wired]), }); return { ...built, jsonapi: JSONAPI_MEMBER } as unknown as ResourceDocument; }), @@ -906,7 +931,7 @@ const assembleCollection = ( const built = Handlers.collection(wired.map(asValue), { ...top, included: included.map((r) => asValue(stringifyLinks(r))), - onResource: onResourceFor(options), + onResource: onResourceFor(options, wired), }); // SAFETY: `Handlers.collection` types its value over the builders' loose // `ResourceValue`; the value is `D` by construction — the wired, stamped @@ -1123,6 +1148,8 @@ export interface RelationshipInput | undefined; + /** As {@link Options.capabilitiesOnIncluded}: `false` leaves `included` unstamped. */ + readonly capabilitiesOnIncluded?: boolean; /** * Resources to carry in `included`, typically the related resources the * linkage names. Full linkage applies, and is checked: each must be @@ -1210,7 +1237,7 @@ export const relationship = asValue(stringifyLinks(r))), - { onResource: onResourceFor(input) }, + { onResource: onResourceFor(input, []) }, ); const rel = readRelationship(input.parent, input.key); const related = rel?.links?.related === undefined ? undefined : toLinkString(rel.links.related); diff --git a/src/ResourceHandlers.test.ts b/src/ResourceHandlers.test.ts index 6346ca8e..fc4add62 100644 --- a/src/ResourceHandlers.test.ts +++ b/src/ResourceHandlers.test.ts @@ -218,7 +218,10 @@ const seeded = () => // SAFETY: the stub ops read the same members the family's list query decodes. const listQuery = peopleListQuery as ResourceHandlers.ListQuery; -const handlersFor = (ops: ReturnType["ops"]) => { +const handlersFor = ( + ops: ReturnType["ops"], + extra: { readonly capabilitiesOnIncluded?: boolean } = {}, +) => { const { cache, store: cacheStore, state } = makeCache(); const { transact, opened } = makeTransact(); const handlers = ResourceHandlers.make({ @@ -231,6 +234,7 @@ const handlersFor = (ops: ReturnType["ops"]) => { cache, transact, include: { includable: PERSON_INCLUDE.paths, targets }, + ...extra, }); return { handlers, cacheStore, state, opened }; }; @@ -879,6 +883,19 @@ describe("list", () => { }), ); + it("stamps the page only when `capabilitiesOnIncluded` is false", async () => { + const { ops } = seeded(); + const { handlers } = handlersFor(ops, { capabilitiesOnIncluded: false }); + const document = await success( + handlers + .list({ query: { include: ["birthPlace"] } }) + .pipe(Effect.provide(as(Option.some(ADMIN)))), + ); + expect(document.data[0]?.meta).toEqual({ canEdit: true, canDelete: true }); + expect(document.included?.map((r) => r.id)).toEqual([PLACE]); + expect(document.included?.[0]).not.toHaveProperty("meta"); + }); + /** * One test per axis the links have to carry, each asserting the parameter * reaches all five links: a client paginates by `next` / `prev`, and diff --git a/src/ResourceHandlers.ts b/src/ResourceHandlers.ts index d4c40b37..cde39772 100644 --- a/src/ResourceHandlers.ts +++ b/src/ResourceHandlers.ts @@ -223,6 +223,8 @@ export interface ReadOnlyConfig< readonly viewer?: Effect.Effect | undefined; /** The capability rule every emitted resource is stamped with. Omit for no stamp. */ readonly capabilities?: Assemble.CapabilitiesHook | undefined; + /** `false` stamps the primary data only, leaving `included` members unstamped. Defaults to `true`. */ + readonly capabilitiesOnIncluded?: boolean; /** Read-through on `get`; write-through and eviction on the writes. */ readonly cache?: Cache | undefined; /** The `?include=` walk on `get` and `list`. */ @@ -521,7 +523,7 @@ export const readOnly = < >( config: ReadOnlyConfig, ): ReadOnlyHandlers => { - const { ops, segment, cache, include, capabilities } = config; + const { ops, segment, cache, include, capabilities, capabilitiesOnIncluded } = config; const maxPageLimit = config.maxPageLimit ?? 100; const viewer = (config.viewer ?? none) as Effect.Effect; // Built once per family: `Query.canonicalPairs` returns the encoder-bound @@ -529,6 +531,7 @@ export const readOnly = < const linkPairs = Query.canonicalPairs(config.listQuery); const assemble = { ...definedMember("capabilities", capabilities), + ...definedMember("capabilitiesOnIncluded", capabilitiesOnIncluded), ...definedMember("includable", include?.includable), ...definedMember("targets", include?.targets), ...definedMember("depth", include?.depth), @@ -689,7 +692,7 @@ export const make = < RT, Committed, TId> > => { - const { ops, segment, cache, capabilities } = config; + const { ops, segment, cache, capabilities, capabilitiesOnIncluded } = config; const viewer = (config.viewer ?? none) as Effect.Effect; const transact = (config.transact ?? identityTransact) as Transact; const hidden = config.hiddenWrite; @@ -745,6 +748,7 @@ export const make = < if (cache !== undefined) yield* cache.set(result.id, reread.value); return yield* Assemble.resource(reread.value, { ...definedMember("capabilities", capabilities), + ...definedMember("capabilitiesOnIncluded", capabilitiesOnIncluded), viewer: yield* viewer, }); }), @@ -890,6 +894,8 @@ export interface RelatedConfig< readonly linkBase: Effect.Effect; readonly viewer?: Effect.Effect | undefined; readonly capabilities?: Assemble.CapabilitiesHook | undefined; + /** `false` stamps the primary data only, leaving `included` members unstamped. Defaults to `true`. */ + readonly capabilitiesOnIncluded?: boolean; /** The to-many page size when the caller names none. Defaults to `50`. */ readonly defaultPageLimit?: number | undefined; /** The most related rows one page may resolve. Defaults to `100`. */ @@ -992,8 +998,10 @@ export const related = < R | RV | RL | Handlers.IncludeTargetServices >) => { const viewer = (config.viewer ?? none) as Effect.Effect; - const capabilities = - config.capabilities === undefined ? {} : { capabilities: config.capabilities }; + const capabilities = { + ...definedMember("capabilities", config.capabilities), + ...definedMember("capabilitiesOnIncluded", config.capabilitiesOnIncluded), + }; const concurrency = config.concurrency ?? 6; const linkPairs = config.listQuery === undefined ? undefined : Query.canonicalPairs(config.listQuery); From ecfe336cc1b4b387799344160848e3beaf544c2d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 04:45:09 +0000 Subject: [PATCH 2/2] test(ResourceHandlers): use it.effect for the capabilitiesOnIncluded test (#567) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Y5G6PMempKsgjiV1NDcCJY --- src/ResourceHandlers.test.ts | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/ResourceHandlers.test.ts b/src/ResourceHandlers.test.ts index fc4add62..d1b34352 100644 --- a/src/ResourceHandlers.test.ts +++ b/src/ResourceHandlers.test.ts @@ -883,18 +883,18 @@ describe("list", () => { }), ); - it("stamps the page only when `capabilitiesOnIncluded` is false", async () => { - const { ops } = seeded(); - const { handlers } = handlersFor(ops, { capabilitiesOnIncluded: false }); - const document = await success( - handlers + it.effect("stamps the page only when `capabilitiesOnIncluded` is false", () => + Effect.gen(function* () { + const { ops } = seeded(); + const { handlers } = handlersFor(ops, { capabilitiesOnIncluded: false }); + const document = yield* handlers .list({ query: { include: ["birthPlace"] } }) - .pipe(Effect.provide(as(Option.some(ADMIN)))), - ); - expect(document.data[0]?.meta).toEqual({ canEdit: true, canDelete: true }); - expect(document.included?.map((r) => r.id)).toEqual([PLACE]); - expect(document.included?.[0]).not.toHaveProperty("meta"); - }); + .pipe(Effect.provide(as(Option.some(ADMIN)))); + expect(document.data[0]?.meta).toEqual({ canEdit: true, canDelete: true }); + expect(document.included?.map((r) => r.id)).toEqual([PLACE]); + expect(document.included?.[0]).not.toHaveProperty("meta"); + }), + ); /** * One test per axis the links have to carry, each asserting the parameter