TS Ddd Use Case

TypeScript DDD Use Case

MANDATORY — READ ENTIRE FILE: Before any implementation step, read references/use-case-pattern.md completely. Do NOT load other DDD skills (entity, repository, dto, controller) unless explicitly requested.

A use case orchestrates one application intent. It is the only layer allowed to talk to repository ports, domain entities, and other application services in the same bounded context. It never throws for expected failures, never maps to HTTP, never validates VO invariants itself.

Before You Start

Answer these before touching code:

• Is this an IN→OUT verb (create-*, publish-*, add-*, list-*)? → application/usecases/<verb>-<noun>.usecase.ts implementing UseCase<IN, OUT>.
• Is this a reusable orchestrator without a clean IN→OUT shape (allocator, coordinator, resolver)? → application/services/<name>.service.ts exposing one or more domain methods, no UseCase interface. See SlugAllocator for the canonical pattern.
• Command or query? Write/mutation → repository port + domain entity. Read/projection → query port (or repo.listByX when the read still returns entities).
• What fails? Which pre-conditions must hold? What does each await return on isFailure?
• Update or create? Update requires loading current state first (findBySlug/findById) and mutating via a named domain method (publish, addSection, cloneWith). Never merge raw input blind.
• Does the input carry a discriminator/status/kind? Type it with the enum-typed union from contracts (CelebrationKind), never string. Pass enum members (CelebrationStatusEnum.DRAFT), never literals.

Dependency Decision Table

Core Rules

• Implement UseCase<IN, OUT> from @acme/shared: execute(input: IN): Promise<Result<OUT>>.
• Decorate the class with @Injectable() from @nestjs/common. Use cases are providers, registered in the BC module.
• Inject repository ports via @Inject(<TOKEN>) using the symbol token from @<bc>/domain/repositories (e.g. CELEBRATION_REPOSITORY). Never inject the concrete adapter class.
• Type the constructor field with the port interface (CelebrationRepository), not the Firestore/InMemory class.
• Fail early: every await is followed by if (X.isFailure) return X.withFail;. Domain error codes go through Result.fail("CODE").
• Delegate every invariant to the entity: call Entity.tryCreate(...), entity.publish(), entity.addSection(...), etc. The use case checks isFailure and forwards; it does not re-validate VOs.
• For enum-backed fields (status / kind / palette / layout / provider) pass enum members from contracts. Literal strings are a bug even when they match — they break refactors and silent renames.
• Imports use workspace aliases: @acme/shared, @acme/<bc>-contracts, @<bc>/domain/..., @<bc>/application/.... No relative paths across layers.
• The barrel apps/api/src/<bc>/application/usecases/index.ts re-exports every use case; update it the moment a new file lands.
• Class name drops the UseCase suffix (CreateCelebration, not CreateCelebrationUseCase). The file extension .usecase.ts already encodes the role; doubling it in the class name is noise. Constructor injection sites read better as private readonly create: CreateCelebration.

NEVER

• NEVER throw inside execute for expected failures. Return Result.fail(...) or result.withFail. Throwing breaks result-to-http mapping and lets unhandled exceptions reach NestJS.
• NEVER map errors to HTTP status codes here. That is the controller's job (presentation/<bc>.controller.ts via result-to-http).
• NEVER import from @nestjs/common other than Inject + Injectable. No HttpException, no Logger (use injected logger if needed). No Firebase, no Zod, no DTO classes — those live in presentation/ and infra/.
• NEVER re-implement VO validation (slug shape, kind whitelist, palette lookup). Call Celebration.tryCreate / Section.tryCreate; propagate withFail.
• NEVER inject the concrete repository (FirestoreCelebrationRepository, InMemoryCelebrationRepository). Only the symbol token + port interface.
• NEVER type a status/kind field as string. Use CelebrationKind / CelebrationStatus from contracts. Never write status: "draft"; write status: CelebrationStatusEnum.DRAFT.
• NEVER update without loading the aggregate first (findBySlug). Partial merges destroy existing props.
• NEVER put cross-cutting orchestration that doesn't fit IN→OUT into a use case. Promote it to application/services/<name>.service.ts (e.g. SlugAllocator).

Result API — project-specific bits

• result.withFail — getter that re-wraps a failed Result<A> as Result<B> without recomputing. Use it for every if (x.isFailure) return x.withFail; step. Not the generic Result API — this is our shortcut.
• Domain error codes are SCREAMING_SNAKE_CASE and catalogued in apps/api/src/shared/http/error-codes.ts. Add new codes there before using them in a use case.

References

See references/use-case-pattern.md for: real file layout, the canonical create / state-transition / nested-mutation / list snippets, the application/services/ exception, the test strategy with InMemoryCelebrationRepository, enum-fixture rules, and the implementation checklist.

See examples/create-greeting.usecase.example.ts for a self-contained use case + fake repo + Jest test using enum members.