typescript-coding-standards

Return typed error values such as Result<T, E>, Effect, or better-result for expected failures like parsing, validation, and I/O errors. Reserve throw and rejected promises for unrecoverable defects like violated invariants or startup misconfiguration.

Parse-don't-validate means converting unknown input into branded domain types at the system boundary rather than passing raw DTOs through core logic. Use schema libraries like Zod or Effect Schema at edges, then work with refined types like EmailAddress internally.

Avoid vi.mock and jest.mock module mocks for new behavior. Instead inject dependencies through constructors, use in-memory fakes or local adapters, and assert observable behavior like returned values, persisted state, or recorded sent messages.

Audit existing adapters first: reuse one through a narrow dependency interface, or extend it only if the method fits its cohesive capability. Create a new adapter only when reuse would cause bad coupling, and record meaningful new services in an ADR.

Parse all config at startup into typed configuration with branded and Redacted-wrapped secret values, failing fast with useful context when values are missing. Never read process.env scattered through application code or use non-null assertions on secrets.

Do not use them to rewrite an entire codebase during an unrelated change. Follow local conventions first, improve only the touched code, and translate typed errors to existing framework exception behavior at boundaries instead of forcing broad migrations.