typed-service-contracts

Define a spec.ts containing Zod input and output schemas, a discriminated union of error codes, and an interface. Then implement a handler.ts class that parses inputs, performs side effects, and returns Success or Failure result objects instead of throwing.

It is a vertical slice architecture where the spec defines the contract (schemas, error types, interface) and the handler implements the logic. The handler catches all exceptions and maps them to typed Result values, separating validation from business logic.

Write data-driven contract tests that call safeParse with invalid inputs and assert rejection, then write handler tests that mock dependencies like fs and assert the returned Result object's error codes and success states.

The Result pattern makes every failure mode explicit in the type system as a discriminated union, forcing callers to handle errors exhaustively. Handlers catch unknown runtime errors and map them to an UNKNOWN_ERROR code, preventing unhandled exceptions.

Avoid it for trivial scripts or prototypes where schema definitions and interface boilerplate outweigh the benefits. It is designed for CLIs, libraries, and high-reliability logic where input parsing and exhaustive error handling justify the structure.