typed-service-contracts

Use the Spec and Handler pattern: define a spec.ts with Zod input schemas, error code enums, and a Result discriminated union, then implement a handler.ts class that returns typed results. This separates the contract from side-effecting implementation.

Return a Result type as a discriminated union of Success and Failure objects instead of throwing. Each failure carries an error code, message, and recoverable flag, and handlers wrap logic in try-catch to map unexpected exceptions into an UNKNOWN_ERROR result.

Parsing transforms and narrows raw input into a trusted type, while validation only checks values. The pattern favors parsing with refinements, such as rejecting path traversal strings, so downstream handlers receive guaranteed-valid DTOs.

Write contract tests that feed invalid data tables into the schema's safeParse and assert rejection, then write logic tests that mock dependencies like fs and assert the handler's returned Result object. This isolates validation rules from business flow.

Avoid it for trivial scripts or prototypes where the overhead of schemas, error unions, and split files outweighs the benefits. It is designed for CLIs, libraries, and high-reliability logic where exhaustive error handling and testability matter.