Skip to main content

24. Centralized TypeScript Types

Status: Accepted Date: 2025-07-06

Context​

In a large monorepo with multiple interacting applications and libraries, many data structures and types (e.g., User, Order, TradeSignal) are shared. Defining these types independently within each project would lead to massive duplication, inconsistencies (type drift), and significant maintenance overhead. When a shared type changes, it would need to be updated in multiple places, which is highly error-prone.

Decision​

We will establish a single, authoritative source for all shared TypeScript types in the monorepo. A dedicated package, @kaido/types (located at libs/core/kaido-types), will house all type definitions, interfaces, and enums that are used by more than one project. All other projects in the monorepo that need to use these shared types must list @kaido/types as a dependency and import the types from this central package.

Consequences​

Positive:

  • Single Source of Truth: Eliminates type duplication and ensures that all projects are using the same, consistent data structures.
  • Improved Type Safety: Greatly reduces the risk of type drift and integration errors between different parts of the system.
  • Maintainability: When a shared type needs to be updated, the change only needs to be made in one place. The TypeScript compiler will then enforce the change across all consuming projects.
  • Clear Contracts: The centralized package serves as a clear, documented contract for the core data models of the entire ecosystem.

Negative:

  • Potential Bottleneck: The centralized types package can become a bottleneck if changes to it are not managed efficiently. All projects that depend on it may need to be updated when it changes.
  • Coupling: All projects become coupled to the @kaido/types package. A breaking change in this package will have a wide-ranging impact.
  • Over-centralization Risk: There is a risk of putting types in the central package that are only used by a single project, leading to unnecessary bloat.

Mitigation:

  • Clear Ownership & Process: Establish a clear ownership and contribution process for the @kaido/types package. Changes should be reviewed carefully for their impact on the entire system.
  • Semantic Versioning: Strictly adhere to semantic versioning for the @kaido/types package to clearly communicate the impact of changes.
  • Modular Structure: Organize types within the @kaido/types package into sub-modules (e.g., minerva/, mercury/) so that consumers can import only the types they need.
  • Strict Guidelines: Enforce a strict policy that only types used by more than one project should be placed in the central package. Project-specific types should remain within the project.