Danijel Martinek
e25b1f7a1c
Factory takes [[ErrorCtor, TRPC_CODE], ...] tuples and returns a tRPC middleware that translates matching domain errors to TRPCError. Discrim- inates by instanceof; preserves original error as cause; unmapped errors propagate (tRPC then wraps them as INTERNAL_SERVER_ERROR with the original error as .cause — middleware does not interfere). core-shared never enumerates feature errors — each feature passes its own constructors in via integrations/api/procedures.ts (Tasks 3-7). Also exports the `t` instance from trpc/init.ts so feature procedure files can do t.procedure.use(...). Also fixes tsconfig.json: rootDir set to "." and @/* path alias added so test files using @/ resolve correctly under tsc --noEmit. Refactor log: §1, §2, §4 Spec: R13–R17
108 lines
6.6 KiB
Markdown
108 lines
6.6 KiB
Markdown
# Refactor Changelog — Input/Output Unification + Presenter + Error Middleware + Public-Surface Cleanup
|
|
|
|
**Started:** 2026-05-06
|
|
**Spec:** [2026-05-06-input-output-unification-design.md](../specs/2026-05-06-input-output-unification-design.md)
|
|
**Plan:** [2026-05-06-plan-9-io-unification.md](../plans/2026-05-06-plan-9-io-unification.md)
|
|
**Branch:** feature/io-unification
|
|
|
|
This document captures every architectural change made during Plan 9
|
|
execution, organized by category. After the plan is merged, use the
|
|
"Doc update checklist" at the bottom to update external docs in a
|
|
single follow-up pass — combined with the still-pending Plan 8
|
|
doc-update items so docs are written once for the post-Plan-9 state.
|
|
|
|
---
|
|
|
|
## 1. Files added
|
|
|
|
- packages/core-shared/src/trpc/define-error-middleware.ts — middleware factory mapping [ErrorCtor, TRPC_CODE] tuples to TRPCError translation
|
|
- packages/core-shared/src/trpc/define-error-middleware.test.ts — 4 tests covering mapped translation, multiple codes, unmapped passthrough (verifies INTERNAL_SERVER_ERROR + cause preservation), cause preservation
|
|
|
|
## 2. Files modified
|
|
|
|
- packages/core-shared/src/trpc/init.ts — `t` instance now exported (was internal const) so feature procedures.ts can do `t.procedure.use(...)`
|
|
- packages/core-shared/package.json — added "./trpc/define-error-middleware" subpath export
|
|
- packages/core-shared/tsconfig.json — set `rootDir: "."` and added `@/*` path alias so test files using `@/` resolve correctly under `tsc --noEmit`
|
|
|
|
## 3. Pattern changes (code-level)
|
|
|
|
### 3.1 Use-case files — input + output schemas + runtime parse
|
|
(populated when use cases are migrated)
|
|
|
|
### 3.2 Controller files — presenter + unknown input + view return type
|
|
(populated when controllers are migrated)
|
|
|
|
### 3.3 tRPC integration — feature-scoped procedures, schema reuse from use cases
|
|
(populated when routers are migrated)
|
|
|
|
## 4. Error-middleware adoption
|
|
|
|
- core-shared infrastructure landed; feature routers will adopt in Tasks 3-7.
|
|
- Discriminator: `instanceof Ctor` (not error name string), so duck-typing is impossible — features pass their own class constructors.
|
|
- Cause preservation: TRPCError carries the original domain error in `.cause` for client structured-error inspection.
|
|
- Note on tRPC v11 behavior: unmapped errors still surface as `TRPCError(code: INTERNAL_SERVER_ERROR)` because tRPC's `createCaller` wraps all procedure errors. Our middleware does not interfere — the original error is preserved as `.cause` for inspection.
|
|
|
|
## 5. Public-API surface
|
|
|
|
### 5.1 ./ui subpath added per feature
|
|
(populated as features adopt the subpath)
|
|
|
|
### 5.2 Feature root index.ts cleanup
|
|
(populated as features clean up their root exports)
|
|
|
|
## 6. Test additions
|
|
|
|
### 6.1 R25 — output-validation tests (use case)
|
|
(populated when use cases gain malformed-input "repo lied" tests)
|
|
|
|
### 6.2 R26 — router error-mapping tests
|
|
(populated when feature routers gain TRPCError-translation tests)
|
|
|
|
### 6.3 R27/R28 — presenter shape tests
|
|
(populated when controllers with non-identity presenters add view-shape assertions)
|
|
|
|
## 7. Open issues / deferred decisions
|
|
|
|
(populated as encountered)
|
|
|
|
---
|
|
|
|
## Doc update checklist (deferred — combined with paused Plan 8 doc pass)
|
|
|
|
After Plan 9 lands, the still-pending Plan 8 doc-update items resume
|
|
and now also pick up Plan 9 rules. Each item below covers BOTH plans'
|
|
material so we touch every file once.
|
|
|
|
- [ ] `CLAUDE.md` — Key Conventions: append schema-in-use-case rule, presenter rule, controller `unknown` input rule, `./ui` subpath rule, schema-export-from-root rule
|
|
- [ ] `AGENTS.md` (root) — Per-Package Conventions: document `./ui` subpath, schema reachability from feature root, factory-bound use cases / controllers (carry-over from Plan 8)
|
|
- [ ] `docs/guides/adding-a-feature.md` — restructure to use the Plan-9 use-case template (with input + output schemas + parse), the Plan-9 controller template (with presenter), and the new `procedures.ts` step (per-feature error map)
|
|
- [ ] `docs/guides/tdd-workflow.md` — update mock decision tree + worked example to factory injection (Plan 8) + R25 output-validation test pattern (Plan 9) + R26 router-error-mapping test pattern (Plan 9)
|
|
- [ ] `docs/guides/testing-strategy.md` — Mocking section: direct factory injection (Plan 8); R25/R26/R27/R28 test obligations (Plan 9)
|
|
- [ ] `docs/architecture/vertical-feature-spec.md` — §6 file shape: schemas + presenter + procedures.ts; §10 testing: R25/R26/R27/R28
|
|
- [ ] `docs/architecture/overview.md` — data-flow box: add input schema, output schema, presenter, error-middleware lanes
|
|
- [ ] `docs/architecture/dependency-flow.md` — verify (no expected change beyond a `./ui` mention)
|
|
- [ ] `docs/decisions/adr-012-lazar-conformance.md` — append note that input/output unification + presenter + error middleware land in ADR-013
|
|
- [ ] `docs/decisions/adr-013-input-output-unification.md` — created in this plan's final task (Task 9); link from prior ADRs
|
|
- [ ] Per-feature `AGENTS.md` (auth/blog/media/marketing-pages/navigation) — Plan 8 file paths + Plan 9 schema/presenter/procedures patterns
|
|
- [ ] `packages/core-testing/AGENTS.md` — note R25/R26 test patterns
|
|
- [ ] `packages/core-shared/AGENTS.md` — document `defineErrorMiddleware` and the `t` re-export
|
|
- [ ] Plan 8 plan/spec — add a one-line annotation that some controller/router patterns shifted in Plan 9; link to this changelog
|
|
|
|
---
|
|
|
|
## Notes for the doc-update pass author
|
|
|
|
When updating external docs, apply these substitutions globally:
|
|
|
|
| Old reference | New reference |
|
|
|---|---|
|
|
| Use case takes `{ x }` directly typed | Use case takes `XInput` (`z.infer<typeof xInputSchema>`); schema lives in same file |
|
|
| Use case returns `Promise<Entity>` | Use case returns `Promise<XOutput>` validated by `xOutputSchema.parse(...)` |
|
|
| Controller imports `z` and defines local `inputSchema` | Controller imports `xInputSchema` from the use-case file |
|
|
| Controller input typed `Partial<z.infer<...>>` | Controller input typed `unknown` |
|
|
| Controller returns `Promise<Entity>` | Controller has `function presenter(value: XOutput)`; returns `Promise<ReturnType<typeof presenter>>` (or `Promise<void>` for void use cases) |
|
|
| Router uses `publicProcedure` from `core-shared/trpc/init` | Router uses feature's `xProcedure` from `./procedures` |
|
|
| Router redefines input schema as `z.object({...})` in `.input(...)` | Router uses `.input(xInputSchema)` imported from the use-case file |
|
|
| Domain error reaches the wire as a generic `TRPCError({ code: "INTERNAL_SERVER_ERROR" })` | Domain error mapped to specific code by `defineErrorMiddleware` in `procedures.ts` |
|
|
| Frontend imports `articleBySlugQuery` from `@repo/blog` | Frontend imports from `@repo/blog/ui` |
|