@tackpay/ddd

Domain Driven Design (DDD) library for TypeScript. It provides a small set of building blocks (Entity, Aggregate, ValueObject, ID, events) with strict typing and modern tooling.

Prerequisites

| Tool | Version | | ------- | ---------- | | Node.js | >= 22.12.0 | | pnpm | >= 10.17.1 |

Getting Started

# Install dependencies
pnpm install

# Run the check suite (types, lint, format, spelling, etc.)
# Note: it includes `lint-staged` checks and may require staged files.
pnpm run check

# Build the project
pnpm run build

# Run tests
pnpm test

Installation (as a dependency)

pnpm add @tackpay/ddd

# or
npm i @tackpay/ddd

# or
yarn add @tackpay/ddd

Usage

import { Aggregate, Entity, ID, ValueObject } from '@tackpay/ddd'
import { Utils, Validator } from '@tackpay/ddd/common'

// Use the exported primitives to model your domain.
// (See `src/` and `test/` for more examples.)

Scripts

| Command | Description | | ------------------------ | ------------------------------------------------------------------------------- | | pnpm run build | Clean dist/, compile with tsup, copy package files | | pnpm run check | Run all checks in parallel (includes lint-staged, which expects staged files) | | pnpm run fix | Auto-fix lint, format, and markdown issues | | pnpm test | Run Jest test suite | | pnpm run test:coverage | Run tests with coverage report | | pnpm run commit | Create a conventional commit via Commitizen | | pnpm run version | Bump version and generate changelog with standard-version | | pnpm run update-deps | Check and update dependencies |

Project Structure

src/
├── index.ts          # Public API
├── types.ts          # Shared types
├── common/           # Shared utilities (subpath export: @tackpay/ddd/common)
├── core/             # DDD building blocks (Entity, Aggregate, ValueObject, events, etc.)
└── utils/            # Internal utilities
test/
├── jest.setup.ts     # Test setup (reflect-metadata)
└── *.pkg.ts          # Package-level tests
.github/              # CI/CD workflows and templates

Tooling

• Build — tsup (powered by esbuild)
• Lint — Biome
• Format — Prettier + Biome
• Test — Jest with ts-jest
• Spell check — cspell
• Git hooks — Husky + lint-staged
• Commits — Commitizen + commitlint (conventional commits)
• Versioning — standard-version

TypeScript Configuration

The project uses two TypeScript configs:

• tsconfig.json — Full config with strict checks, used by the IDE and tsc --noEmit
• tsconfig.build.json — Extends the base config, used by tsup for production builds (excludes tests)

Decorators and emitDecoratorMetadata are enabled for decorator-based patterns (DI, ORM, etc.).

License

ISC