---
description: TypeScript coding practices and style guide for DDD-oriented applications
---
# TypeScript Coding Practices and Style Guide for DDD-Oriented Applications

## General Principles
- Object-oriented programming is the primary paradigm.
- Always prefer the simplest and clearest solution.
- Keep the codebase clean, organized, and easily readable.
- Consider design patterns when writing code.
- Domain should be the core of the application — business logic is the heart and should remain independent of frameworks and technical details.
- Use ubiquitous language: class, method, and variable names must reflect the business domain precisely.

## Typing
- Keep all type definitions separate from implementation code.
- Categorize type definitions into:
  - **DTOs:** Data Transfer Objects between layers.
  - **Entity:** Represents core business objects with identity and behavior.
  - **Value Object:** Defined by its attributes, not by identity.
  - **Aggregate Root:** Entry point to a group of related entities, enforces invariants.
  - **Domain Event:** Describes something important that happened in the domain.
  - **Domain Service:** Encapsulates business logic that doesn't naturally belong to an entity.
  - **Application Service:** Coordinates use cases and business rules execution.
  - **Repository:** Interface for persisting and retrieving domain objects.
  - **Router:** Defines routes and connects them to controllers.
  - **Controller:** Handles input from external sources and maps it to application services.
  - **Mapper:** Converts between DTOs and domain objects.
  - **Container:** Registers dependencies (dependency injection).
  - **Schema Validate:** Validation schemas for user input (e.g., Zod).
  - **Symbols:** Centralized tokens for dependency injection.
  - **Interfaces / Types:** Contracts or utility types not classified above.
- Use suffixes: `.dto.ts`, `.entity.ts`, `.value-object.ts`, `.aggregate.ts`, `.domain-event.ts`, `.domain-service.ts`, `.application-service.ts`, `.repository.ts`, `.controller.ts`, `.mapper.ts`, `.container.ts`, `.router.ts`, `.schema-validate.ts`, `.symbols.ts`, `.interface.ts`, `.type.ts`.

## File Structure & Organization
- One class per file.
- Keep files small; refactor when exceeding 200-300 lines.
- Use lowercase `kebab-case` for file and folder names.
- Organize code into **bounded contexts** when applicable, each with its own layers.
- Regularly remove unused files to keep the codebase lean.

## Application Layering
- Follow DDD Layered Architecture:
  - **Domain Layer:** Entities, value objects, domain services, domain events.
  - **Application Layer:** Use case coordination, application services, commands.
  - **Infrastructure Layer:** Implementations for repositories, external APIs, DB access.
  - **Interface Layer:** Controllers, routers, DTOs, adapters.
- Avoid cross-layer dependencies and maintain separation of concerns.

## Code Style & Best Practices
- Use functional programming principles like immutability where appropriate.
- Avoid `forEach`; prefer `map`, `reduce`, etc.
- Favor early returns for readability and maintainability.
- Centralize error handling; avoid duplicated try/catch blocks.
- Domain code must be highly testable — write unit tests for entities and domain services.

## Imports
- Organize imports in this order:
  1. NodeJS built-in modules
  2. 3rd-party modules
  3. Internal application modules
- Use **path aliases by bounded context** to avoid tight coupling across domains.
- Remove unused imports to maintain cleanliness.

## Linting & Formatting
- Use ESLint for linting and formatting.
- Follow rules strictly as defined in `.eslintrc.ts` and `tsconfig.eslint.json`.