Types Organization in TypeScript Projects: Mercury Bot Case Study

Types are the backbone of any TypeScript project, but as the codebase grows, they can become scattered and hard to maintain. Here's a practical guide on organizing types, with a real-world example from Mercury Bot.

General Approaches to Type Organization

1. Domain-Driven Type Organization

Keep types close to their domain logic, organized by feature. This approach makes it easy to find related types and maintains a clear connection between types and their usage.

src/
├── market-ranking/
│   ├── types/
│   │   ├── state.types.ts
│   │   ├── config.types.ts
│   │   └── index.ts

2. Shared-First with Domain Specifics

Separate shared types from domain-specific ones, reducing duplication while maintaining clarity.

src/
├── types/
│   ├── common/
│   │   └── models.types.ts
│   └── domain/
│       └── market-ranking.types.ts

3. Layer-Based Type Organization

Organize types by technical layers, making it clear where each type belongs in the architecture.

src/
├── types/
│   ├── api.types.ts
│   ├── models.types.ts
│   └── services.types.ts

4. Interface-First with Implementation Types

Separate interface definitions from implementation types, ideal for dependency inversion.

src/
├── interfaces/
│   └── market-ranking.interface.ts
└── features/
    └── market-ranking/
        └── types/
            └── implementation.types.ts

5. Capability-Based Organization

Align types with system capabilities, perfect for microservices and modular architectures.

src/
├── capabilities/
│   └── market-ranking/
│       ├── types.ts
│       └── index.ts

Mercury Bot: Current State and Improvement Plan

Current State

Currently, Mercury Bot has most of its types concentrated in:

• src/market-ranking/types.ts (400+ lines)
• src/ta/types.ts
• Various smaller type definitions scattered across components

Proposed Reorganization

Here's a focused plan to split and reorganize types without overwhelming changes:

1. Market Ranking Types Split

   • Location: src/market-ranking/types/
   • New Files:
     • state.types.ts - GistState and related state interfaces
     • models.types.ts - Model enums and weights interfaces
     • comparison.types.ts - Comparison related interfaces
     • config.types.ts - Configuration interfaces
     • index.ts - Re-exports all types

2. Technical Analysis Types

   • Location: src/ta/types/
   • New Files:
     • indicators.types.ts - Indicator enums and interfaces
     • timeframes.types.ts - TimeFrame related types
     • index.ts - Re-exports

3. Shared Types

   • Location: src/common/types/
   • New File:
     • queue.types.ts - Queue related types and constants

Migration Strategy

1. Create new type files with proposed structure
2. Move types to their new locations
3. Update imports across the codebase
4. Remove old type files
5. Update documentation

Benefits

• Smaller, more focused files
• Clear organization by domain
• Easier to find related types
• Maintainable file sizes
• Clear import paths

Type Discovery Rules

1. Always start with domain directory's types/ folder
2. Check common/types/ for shared types
3. Use IDE's "Go to Definition" feature
4. Follow re-exports from index.ts files

Conclusion

Type organization doesn't have to be overwhelming. Start with a clear plan, focus on the most impactful changes, and maintain consistency. The proposed changes for Mercury Bot demonstrate how to apply these principles in practice while keeping the scope manageable.

Remember: The goal is to make the codebase more maintainable and types more discoverable, not to achieve theoretical perfection.