fix(core-shared): match domain errors by name across module graphs
Some checks failed
CodeQL / Analyze (javascript-typescript) (push) Has been cancelled
CI / typecheck + lint + boundaries + test + build (push) Has been cancelled
Coverage snapshot / snapshot (push) Has been cancelled
Release Please / release-please (push) Has been cancelled
Sentry PII guard (R31) / pii-guard (push) Has been cancelled
CI / Storybook smoke tests + visual regression (push) Has been cancelled
CI / Playwright e2e (push) Has been cancelled
Mutation testing (nightly) / mutate (push) Has been cancelled
Library trace revalidation (weekly) / revalidate (push) Has been cancelled

defineErrorMiddleware matched by instanceof only; the custom server's
tsx-bound DI graph and the Next-compiled route handler each load their
own copy of every error class, so mapped domain errors (e.g.
UnauthenticatedError -> UNAUTHORIZED) fell through and surfaced as raw
500s — hit in production by a downstream app built from this template.
Match on the canonical error name (probed from the constructor's
string-literal this.name) with instanceof as the fast path; nameless
classes stay identity-only so plain Errors never translate. ADR-027
records the decision and the now-load-bearing this.name convention.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-31 18:25:38 +02:00
parent 3d52f2de85
commit ed59b4348f
4 changed files with 165 additions and 3 deletions

View File

@@ -106,7 +106,7 @@ See `docs/guides/coverage.md` for the cookbook and ADR-020 for the full rational
- **Tests inject mocks directly** Construct `MockXRepository` and pass into the factory: `signInUseCase(mockUsers, mockAuth)(input)`. No container rebinding in unit tests
- **Schemas in the use-case file** Every use case exports `xInputSchema` (a `z.ZodObject` with `.strict()`; `z.object({}).strict()` for void inputs) and, for non-void use cases, `xOutputSchema`. Types: `XInput = z.infer<typeof xInputSchema>` and `XOutput`. Use case body ends with `xOutputSchema.parse(result)` before returning (runtime guarantee against malformed repository data)
- **Controllers receive `unknown` + presenter** Controllers `safeParse(xInputSchema)` from the use-case file and throw `InputParseError` on failure. Non-void controllers define a top-level `function presenter(value: XOutput)` and return `Promise<ReturnType<typeof presenter>>` (identity is fine `return value`); void controllers return `Promise<void>` with no presenter
- **Feature-scoped tRPC error mapping** Each feature has `integrations/api/procedures.ts` exporting `xProcedure = t.procedure.use(defineErrorMiddleware([[Ctor, "TRPC_CODE"], ...]))` from `@repo/core-shared/trpc/define-error-middleware`. Routers use `xProcedure.input(xInputSchema)` schemas are imported from the use-case file, never redefined inline. `core-shared` never enumerates feature error classes
- **Feature-scoped tRPC error mapping** Each feature has `integrations/api/procedures.ts` exporting `xProcedure = t.procedure.use(defineErrorMiddleware([[Ctor, "TRPC_CODE"], ...]))` from `@repo/core-shared/trpc/define-error-middleware`. Routers use `xProcedure.input(xInputSchema)` schemas are imported from the use-case file, never redefined inline. `core-shared` never enumerates feature error classes. Matching is by **canonical error name**, not class identity (ADR-027): every domain error class MUST set `this.name = "<ClassName>"` from a string literal in its constructor (side-effect-free, callable with one message arg) `instanceof` fails across module graphs (tsx DI vs webpack bundle) and would mask mapped errors as 500s
- **Public surface split** Feature root (`.`) exports contracts only: types, errors, schemas, IUseCase / IController aliases, router type, constants. UI artifacts (hooks, components, query builders) live behind `./ui` (`src/ui/index.ts`). Apps import hooks/components from `@repo/<feature>/ui`, schemas/types from `@repo/<feature>`
- **Feature UI owns its data fetching** Each feature's `src/ui/hooks/` contains `"use client"` hooks that wrap `useTRPC` + `useSuspenseQuery`. Connected components in `src/ui/components/` call these hooks. App pages prefetch via `appRouter.createCaller({})` and hydrate via `HydrationBoundary` + `dehydrate` + `setQueryData`. See `docs/guides/building-feature-ui.md`
- **Payload repositories via constructor** Feature packages receive Payload config at constructor time, not as a direct dependency