feat(result): typed, translatable error handling (@carbon/result)

[sidgaikwad]

Summary

Service operations used to fail in an untyped way: services returned raw Supabase { data, error } or threw generic Errors, and the user-facing message was hardcoded English authored at the route. Despite 11 supported locales, every error toast was English — and several services passed the raw PostgrestError straight through, so a raw duplicate key value violates unique constraint … could land in a user's toast.

This introduces @carbon/result: service functions return a typed Result<T, E> whose failure side is a tagged error carrying a Lingui message descriptor. The error is translated at the action boundary into the requester's locale and shown through the existing flash/toast machinery. Developers get exhaustive, typed failure handling; users get messages in their own language; raw database errors never reach them.

Design is recorded in docs/adr/0001, the PRD in docs/prd, and the glossary in CONTEXT.md.

Architecture

graph TD
  R["@carbon/result<br/>Result&lt;T,E&gt; · CarbonError base · 6 core errors"]
  D["@carbon/database<br/>fromQuery / fromTransaction adapters"]
  S["Service layer (*.service.ts)<br/>returns Result · raises errors · domain errors live here"]
  A["Action / loader (conversion boundary)<br/>match → errorFlash(error, i18n)"]
  F["@carbon/auth<br/>FlashResult · flash() · getRequestI18n()"]
  T["Toast — already translated, requester's locale"]
  EB["Route ErrorBoundary"]

  R --> D
  R --> S
  D --> S
  S -->|Result flows up| A
  A --> F
  F --> T
  S -.->|defects: Panic / raw throw| EB

Loading

The error is translated once, at write time, in the requester's locale — not at creation (no presentation concerns in service signatures) and not on the client.

sequenceDiagram
  participant U as User
  participant Act as Action
  participant Svc as approveRequest()
  participant DB as Kysely/Supabase
  U->>Act: POST approve / reject decision
  Act->>Svc: approveRequest(db, id, userId)
  Svc->>DB: pre-flight select
  DB-->>Svc: row missing / not "Pending"
  Svc-->>Act: Result.err(NotFoundError | ConflictError)
  Note over Act: result.isErr()
  Act->>Act: i18n = getRequestI18n(request)
  Act->>Act: errorFlash(error, i18n) → FlashResult (translated)
  Act-->>U: redirect + flash cookie → translated toast

Loading

What's in the box

Package	Change
@carbon/result (new)	Re-exports better-result; a Lingui-aware CarbonError base (class-level default + call-site override, serializable interpolation values, yieldable in Result.gen) and the six closed-set core errors: NotFoundError, ValidationError, ConflictError, BusinessRuleError, DatabaseError, ExternalServiceError.
@carbon/auth	Renamed the old Result type → FlashResult (frees the name for the typed Result). Added errorFlash / successFlash boundary converters that resolve the descriptor via the request i18n and log the raw cause for on-call debugging.
@carbon/database	fromQuery(query, { entity, id }) maps PostgrestError → DatabaseError and no-rows → NotFoundError; fromTransaction(db, fn) maps thrown exceptions → DatabaseError (raw error preserved). Keeps @carbon/result free of Supabase/Kysely types.
apps erp / mes	getRequestI18n(request) builds a request-scoped i18n for the boundary.
Approvals pilot	approveRequest / rejectRequest / cancelApprovalRequest return Result; the purchase-order, supplier and quality-document routes match → errorFlash; the MCP direct-executor is now Result-aware so a typed failure isn't reported as success.
i18n / docs	packages/result/src added to both Lingui catalogs (the pre-commit hook extracted the new ids). Greenfield Rule documented in AGENTS.md.

Conflict vs. BusinessRule

Per the glossary: Conflict = the operation is valid but the current state already blocks/satisfies it (e.g. "already clocked in"); BusinessRule = the operation itself violates an invariant (e.g. "insufficient quantity"). There is no PermissionError — auth and RLS enforce permissions upstream.

See it yourself

pnpm --filter @carbon/result demo

Prints every error and its translations (English = expected, plus Spanish & German) resolved through the exact errorFlash path. Expected output and manual in-app verification steps are in docs/result-error-demo.md.

Tests

Suite	Covers
packages/result/src/errors.test.ts	core error tags, default/override descriptors, serializable values, Result.gen
packages/database/src/result.test.ts	adapter ok / error-shape / no-rows / transaction-throw paths
packages/auth/src/utils/result.test.ts	translation + interpolation + override at the boundary; cause logging
apps/erp/.../shared.service.test.ts	approvals pilot NotFound + Conflict
packages/result/src/demo.test.ts	all errors × locales

35 new tests; @carbon/result, @carbon/database, erp, jobs, mes typecheck clean.

Adoption (Greenfield Rule)

New and materially-modified service functions return Result; untouched legacy code keeps its current style. No big-bang rewrite. The approvals module is the reference example.

Follow-ups (out of scope here)

• Run pnpm translate to LLM-translate the newly-extracted message ids for all 11 locales (this PR extracts them; the strings ship untranslated, falling back to English).
• An independent app-local Result type still exists in apps/erp/app/types/index.ts (a FlashResult-shaped sibling); renaming it for full unambiguity is a separate mechanical change.
• Converting the remaining ~19 service files follows the Greenfield Rule over time.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
academy	Ready	Preview, Comment	Jun 25, 2026 3:20pm
carbon	Ready	Preview, Comment	Jun 25, 2026 3:20pm
docs	Ready	Preview, Comment	Jun 25, 2026 3:20pm
mes	Ready	Preview, Comment	Jun 25, 2026 3:20pm