feat(core): a computed field declares the relations it needs (ADR-0025) by borisno2 · Pull Request #857 · OpenSaasAU/stack

borisno2 · 2026-08-01T05:49:59Z

Summary

Implements ADR-0025 / issue #850 — the declared-dependency follow-up to ADR-0024 (#848).

Since ADR-0024, a bare read (no caller include) returns a row's own columns only, so a virtual field's resolveOutput reading a relation off item (item.lineItems, item.posts?.length, …) silently computed over undefined unless a caller happened to include that relation. This adds a needs declaration to the base field config so a computed field can name the immediate relations its hook depends on, and have the read fetch exactly those — without widening what the caller receives.

Order: list({
  fields: {
    lineItems: relationship({ ref: 'LineItem.order', many: true }),
    total: virtual({
      type: 'number',
      needs: ['lineItems'],
      hooks: {
        resolveOutput: ({ item }) =>
          item.lineItems.reduce((sum, li) => sum + li.price * li.quantity, 0),
      },
    }),
  },
})

Fold + strip, not a widened include. foldDeclaredDependencies (new access/declared-dependencies.ts) merges declared relations into whatever include a read is already building — bare, caller-supplied, or fragment-derived — before it reaches the existing buildIncludeWithAccessControl / mergeIncludeWithAccessControl pipeline, so a declared relation is scoped exactly like a caller-named one. filterReadableFields (field-visibility.ts) then strips the declaration-only keys from the result after resolveOutput has run, at every nesting level.
Session-relative, never withheld. A dependency the session can't query isn't fetched, and the hook sees nothing in its place — the field still computes and is present in the result, never withheld.
Cycle safety reuses the existing guard. A two-list declaration cycle (Order.total needs lineItems, LineItem.x needs order) terminates via the visitedLists cycle guard already in buildIncludeWithAccessControl, rather than a new mechanism — matching the note in ADR-0026 that this guard's remaining job is defending exactly this fold.
Compile-time constraint. needs is typed as RelationshipFieldKeys<TTypeInfo['fields']>[], so a misspelled or non-relation entry is a compile error — verified against the real generated Lists.<List>.TypeInfo (requires the list to be annotated with it, the documented list<Lists.X.TypeInfo>({...}) pattern every example already uses).
Generate-time validation (new validation/needs-closure.ts, wired into opensaas generate) rejects an invalid needs entry and any declaration closure that can't fit within the read-include depth cap from any starting point (or that cycles), naming the offending field/chain rather than silently truncating at runtime.

Test plan

New suite packages/core/tests/needs-declared-dependencies.test.ts (12 tests): bare-read fetch + strip, caller-include unchanged, nested explicit-include fold + strip, Access Filter scoping (session-relative value), fully-denied and field-denied dependencies still compute, fragment query reads, two-list declaration cycle termination, generate-time validation (invalid relation, cyclic closure, too-deep closure, valid config).
New tests in packages/cli/src/commands/generate.test.ts for validateNeedsDeclarations / validateNeedsClosureDepth / formatNeedsClosureErrors.
Full existing regression suites for Explicit include bypasses relation-level access filtering on reads — caller include REPLACES the access-controlled include #566/Access control fails OPEN past include depth 5: caller includes pass through unscoped and nested rows skip field-read filtering #830/0.33.0: reads inside resolveOutput recurse without bound — server OOMs on any access-scoped read #844/Reads with no include auto-include every relation to depth 5 — Prisma returns scalars only, and this default is the root cause behind #566 / #830 / #844 #848 pass unmodified (935/935 core tests, 326/326 CLI tests).
pnpm lint, pnpm manypkg fix, pnpm format clean.
opensaas generate re-verified end-to-end against examples/blog.
Changeset added (@opensaas/stack-core + @opensaas/stack-cli, minor).

Closes #850

Generated by Claude Code

…DR-0025) Adds `needs?: string[]` to the base field config so a computed field's resolveOutput hook can declare the immediate sibling relations it cannot compute without. The read pipeline folds each declaration into the include (scoped through the Access Filter exactly like a caller-named relation) wherever that field is computed — root or nested — and strips the relation from the result afterward unless the caller named it too, for both `include` reads and fragment `query` reads. A field whose declared dependency is partially or fully denied still computes, on whatever it can see, rather than being withheld. A declaration cycle across lists terminates via the existing relationship-graph cycle guard in buildIncludeWithAccessControl. Adds generate-time validation rejecting an invalid `needs` entry or a declaration closure that can't fit the read-include depth cap from any starting point. Closes #850 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018qmK8PtjUFSEDHbcUn8bWu

changeset-bot · 2026-08-01T05:50:03Z

🦋 Changeset detected

Latest commit: 2a32775

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@opensaas/stack-core	Minor
@opensaas/stack-cli	Minor
@opensaas/stack-auth	Minor
@opensaas/stack-rag	Minor
@opensaas/stack-storage	Minor
@opensaas/stack-tiptap	Minor
@opensaas/stack-ui	Minor
@opensaas/stack-storage-s3	Minor
@opensaas/stack-storage-vercel	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-08-01T05:50:07Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stack-docs	Ready	Preview	Aug 1, 2026 8:05am

…uilds RelationshipFieldKeys<TTypeInfo['fields']> broke assignability for any non-generic field builder (e.g. @opensaas/stack-tiptap's richText(), written per the documented third-party field pattern with no TTypeInfo parameter of its own) whenever it was used in a list annotated with its generated TypeInfo: the field's own needs?: string[] no longer matched the list's narrower per-list expected type, regardless of whether that field used needs at all. This broke examples/tiptap-demo's build in CI. needs is now a plain string[] on BaseFieldConfig. An invalid entry (misspelled or non-relation) is still caught at `pnpm generate` time via validateNeedsDeclarations, just not at compile time. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018qmK8PtjUFSEDHbcUn8bWu

Add coverage for validateNeedsDeclarations/validateNeedsClosureDepth's edge paths: a list with no fields, a needs entry whose ref doesn't resolve to any list, one naming a non-relationship field, one naming a field that doesn't exist at all, and two needs entries with equal closure depth (so the second doesn't overwrite the first's recorded chain). Brings src/validation/needs-closure.ts to 100%/97.36% (was 90.19%/78.94%), above the src/validation/** threshold (92%/83%) that failed CI. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018qmK8PtjUFSEDHbcUn8bWu

github-actions · 2026-08-01T08:11:00Z