@hmpsn/ts-ddd 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Hampson <thomas@hmpsn.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# ts-ddd
+
+[![npm version](https://badge.fury.io/js/ts-ddd.svg)](https://www.npmjs.com/package/ts-ddd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Base classes for implementing Domain-Driven Design (DDD) applications in TypeScript.
+
+## Installation
+
+```bash
+npm install ts-ddd
+```
+
+## Features
+
+This package provides the following DDD building blocks:
+
+- **Entity**: Base class for entities with unique identifiers
+- **ValueObject**: Base class for immutable value objects
+- **AggregateRoot**: Base class for aggregate roots with domain event support
+- **DomainEvent**: Base class for domain events
+- **Repository**: Interface for repository pattern
+- **UniqueEntityID**: Utility class for generating unique identifiers
+
+## Usage
+
+### Entity
+
+Entities are objects that have a unique identity that runs through time and different representations.
+
+```typescript
+import { Entity } from 'ts-ddd';
+
+interface UserProps {
+  name: string;
+  email: string;
+}
+
+class User extends Entity<string> {
+  get name(): string {
+    return this.props.name;
+  }
+
+  get email(): string {
+    return this.props.email;
+  }
+
+  public updateEmail(newEmail: string): void {
+    this.props.email = newEmail;
+  }
+}
+
+// Create a new user
+const user = new User('user-123', { name: 'John Doe', email: 'john@example.com' });
+console.log(user.id); // 'user-123'
+console.log(user.name); // 'John Doe'
+```
+
+### ValueObject
+
+Value Objects are immutable objects that are defined by their attributes rather than a unique identity.
+
+```typescript
+import { ValueObject } from 'ts-ddd';
+
+interface AddressProps {
+  street: string;
+  city: string;
+  zipCode: string;
+}
+
+class Address extends ValueObject<AddressProps> {
+  get street(): string {
+    return this.props.street;
+  }
+
+  get city(): string {
+    return this.props.city;
+  }
+
+  get zipCode(): string {
+    return this.props.zipCode;
+  }
+}
+
+// Create addresses
+const address1 = new Address({ street: '123 Main St', city: 'Springfield', zipCode: '12345' });
+const address2 = new Address({ street: '123 Main St', city: 'Springfield', zipCode: '12345' });
+
+// Value objects with same properties are equal
+console.log(address1.equals(address2)); // true
+```
+
+### AggregateRoot
+
+An Aggregate Root is an entity that is the root of an aggregate, which is a cluster of domain objects that can be treated as a single unit.
+
+```typescript
+import { AggregateRoot, DomainEvent, UniqueEntityID } from 'ts-ddd';
+
+class OrderPlacedEvent extends DomainEvent {
+  constructor(aggregateId: UniqueEntityID, public readonly total: number) {
+    super(aggregateId);
+  }
+}
+
+interface OrderProps {
+  total: number;
+  status: string;
+}
+
+class Order extends AggregateRoot<string> {
+  get total(): number {
+    return this.props.total;
+  }
+
+  get status(): string {
+    return this.props.status;
+  }
+
+  public placeOrder(): void {
+    this.props.status = 'placed';
+    const event = new OrderPlacedEvent(new UniqueEntityID(this.id), this.total);
+    this.addDomainEvent(event);
+  }
+}
+
+// Create and place an order
+const order = new Order({ total: 100, status: 'pending' }, 'order-123');
+order.placeOrder();
+
+// Access domain events
+console.log(order.domainEvents.length); // 1
+console.log(order.domainEvents[0] instanceof OrderPlacedEvent); // true
+
+// Clear events after dispatching
+order.clearEvents();
+```
+
+### Repository Interface
+
+The Repository interface provides a contract for data access objects.
+
+```typescript
+import { IRepository } from 'ts-ddd';
+
+class UserRepository implements IRepository<User> {
+  async findById(id: string): Promise<User | null> {
+    // Implementation
+    return null;
+  }
+
+  async save(entity: User): Promise<void> {
+    // Implementation
+  }
+
+  async delete(entity: User): Promise<void> {
+    // Implementation
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT

package/dist/aggregate-root.d.ts

@@ -0,0 +1,22 @@
+import { Entity } from './entity';
+import { DomainEvent } from './domain-event';
+/**
+ * Base class for Aggregate Roots in DDD.
+ * An Aggregate Root is an entity that is the root of an aggregate,
+ * which is a cluster of domain objects that can be treated as a single unit.
+ */
+export declare abstract class AggregateRoot<TId, TProps = Record<string, unknown>> extends Entity<TId, TProps> {
+    private _events;
+    /**
+     * Gets the domain events for this aggregate.
+     */
+    get events(): DomainEvent[];
+    /**
+     * Adds a domain event to be dispatched.
+     */
+    protected publishEvent(event: DomainEvent): void;
+    /**
+     * Clears all domain events.
+     */
+    clearEvents(): void;
+}

package/dist/aggregate-root.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AggregateRoot = void 0;
+const entity_1 = require("./entity");
+/**
+ * Base class for Aggregate Roots in DDD.
+ * An Aggregate Root is an entity that is the root of an aggregate,
+ * which is a cluster of domain objects that can be treated as a single unit.
+ */
+class AggregateRoot extends entity_1.Entity {
+    constructor() {
+        super(...arguments);
+        this._events = [];
+    }
+    /**
+     * Gets the domain events for this aggregate.
+     */
+    get events() {
+        return this._events;
+    }
+    /**
+     * Adds a domain event to be dispatched.
+     */
+    publishEvent(event) {
+        this._events.push(event);
+    }
+    /**
+     * Clears all domain events.
+     */
+    clearEvents() {
+        this._events = [];
+    }
+}
+exports.AggregateRoot = AggregateRoot;

package/dist/domain-event.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Unique identifier for domain events.
+ */
+export declare class UniqueEntityID {
+    private value;
+    constructor(id?: string);
+    private generateId;
+    toString(): string;
+    toValue(): string;
+    equals(id?: UniqueEntityID): boolean;
+}
+/**
+ * Interface for domain events.
+ */
+export interface IDomainEvent {
+    dateTimeOccurred: Date;
+    getAggregateId(): UniqueEntityID;
+}
+/**
+ * Base class for Domain Events in DDD.
+ * Domain Events represent something that happened in the domain that domain experts care about.
+ */
+export declare abstract class DomainEvent implements IDomainEvent {
+    dateTimeOccurred: Date;
+    private aggregateId;
+    constructor(aggregateId: UniqueEntityID);
+    getAggregateId(): UniqueEntityID;
+}

package/dist/domain-event.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DomainEvent = exports.UniqueEntityID = void 0;
+/**
+ * Unique identifier for domain events.
+ */
+class UniqueEntityID {
+    constructor(id) {
+        this.value = id || this.generateId();
+    }
+    generateId() {
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+    toString() {
+        return this.value;
+    }
+    toValue() {
+        return this.value;
+    }
+    equals(id) {
+        if (id === null || id === undefined) {
+            return false;
+        }
+        if (!(id instanceof UniqueEntityID)) {
+            return false;
+        }
+        return id.toValue() === this.value;
+    }
+}
+exports.UniqueEntityID = UniqueEntityID;
+/**
+ * Base class for Domain Events in DDD.
+ * Domain Events represent something that happened in the domain that domain experts care about.
+ */
+class DomainEvent {
+    constructor(aggregateId) {
+        this.dateTimeOccurred = new Date();
+        this.aggregateId = aggregateId;
+    }
+    getAggregateId() {
+        return this.aggregateId;
+    }
+}
+exports.DomainEvent = DomainEvent;

package/dist/entity.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Interface for entities that have a unique identifier.
+ */
+export interface IEntity<TId, TProps> {
+    equals(object?: Entity<TId, TProps>): boolean;
+}
+/**
+ * Base class for Entities in DDD.
+ * Entities are objects that have a unique identity that runs through time and different representations.
+ */
+export declare abstract class Entity<TId, TProps = Record<string, unknown>> implements IEntity<TId, TProps> {
+    readonly id: TId;
+    readonly props: TProps;
+    constructor(id: TId, props: TProps);
+    /**
+     * Checks equality between entities based on their identity.
+     */
+    equals(object?: Entity<TId, TProps>): boolean;
+}

package/dist/entity.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Entity = void 0;
+/**
+ * Base class for Entities in DDD.
+ * Entities are objects that have a unique identity that runs through time and different representations.
+ */
+class Entity {
+    constructor(id, props) {
+        this.id = id;
+        this.props = props;
+    }
+    /**
+     * Checks equality between entities based on their identity.
+     */
+    equals(object) {
+        if (object == null || object == undefined) {
+            return false;
+        }
+        if (this === object) {
+            return true;
+        }
+        if (!(object instanceof Entity)) {
+            return false;
+        }
+        return this.id === object.id;
+    }
+}
+exports.Entity = Entity;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ts-ddd - Base classes for implementing Domain-Driven Design (DDD) applications in TypeScript
+ * Copyright (c) 2026 Thomas Hampson <thomas@hmpsn.me>
+ * Licensed under the MIT License - see LICENSE.md for details
+ */
+export { ValueObject } from './value-object';
+export { Entity, IEntity } from './entity';
+export { AggregateRoot } from './aggregate-root';
+export { DomainEvent, IDomainEvent, UniqueEntityID } from './domain-event';
+export { IRepository } from './repository';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * ts-ddd - Base classes for implementing Domain-Driven Design (DDD) applications in TypeScript
+ * Copyright (c) 2026 Thomas Hampson <thomas@hmpsn.me>
+ * Licensed under the MIT License - see LICENSE.md for details
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UniqueEntityID = exports.DomainEvent = exports.AggregateRoot = exports.Entity = exports.ValueObject = void 0;
+var value_object_1 = require("./value-object");
+Object.defineProperty(exports, "ValueObject", { enumerable: true, get: function () { return value_object_1.ValueObject; } });
+var entity_1 = require("./entity");
+Object.defineProperty(exports, "Entity", { enumerable: true, get: function () { return entity_1.Entity; } });
+var aggregate_root_1 = require("./aggregate-root");
+Object.defineProperty(exports, "AggregateRoot", { enumerable: true, get: function () { return aggregate_root_1.AggregateRoot; } });
+var domain_event_1 = require("./domain-event");
+Object.defineProperty(exports, "DomainEvent", { enumerable: true, get: function () { return domain_event_1.DomainEvent; } });
+Object.defineProperty(exports, "UniqueEntityID", { enumerable: true, get: function () { return domain_event_1.UniqueEntityID; } });

package/dist/repository.d.ts

@@ -0,0 +1,19 @@
+import { Entity } from './entity';
+/**
+ * Generic repository interface for DDD.
+ * Repositories provide the illusion of an in-memory collection of all objects of a certain type.
+ */
+export interface IRepository<T extends Entity<unknown, unknown>> {
+    /**
+     * Finds an entity by its unique identifier.
+     */
+    findById(id: T['id']): Promise<T | null>;
+    /**
+     * Saves an entity to the repository.
+     */
+    save(entity: T): Promise<void>;
+    /**
+     * Removes an entity from the repository.
+     */
+    delete(entity: T): Promise<void>;
+}

package/dist/repository.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/value-object.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Base class for Value Objects in DDD.
+ * Value Objects are immutable objects that are defined by their attributes rather than a unique identity.
+ */
+export declare abstract class ValueObject<T> {
+    protected readonly props: T;
+    constructor(props: T);
+    /**
+     * Checks equality between value objects based on their properties.
+     * Uses deep comparison of properties.
+     */
+    equals(vo?: ValueObject<T>): boolean;
+    /**
+     * Deep equality comparison for objects.
+     */
+    private deepEquals;
+}

package/dist/value-object.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValueObject = void 0;
+/**
+ * Base class for Value Objects in DDD.
+ * Value Objects are immutable objects that are defined by their attributes rather than a unique identity.
+ */
+class ValueObject {
+    constructor(props) {
+        this.props = Object.freeze(props);
+    }
+    /**
+     * Checks equality between value objects based on their properties.
+     * Uses deep comparison of properties.
+     */
+    equals(vo) {
+        if (vo === null || vo === undefined) {
+            return false;
+        }
+        if (vo.props === undefined) {
+            return false;
+        }
+        return this.deepEquals(this.props, vo.props);
+    }
+    /**
+     * Deep equality comparison for objects.
+     */
+    deepEquals(a, b) {
+        if (a === b)
+            return true;
+        if (a === null || b === null || a === undefined || b === undefined) {
+            return false;
+        }
+        if (typeof a !== typeof b)
+            return false;
+        if (typeof a !== 'object')
+            return a === b;
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length)
+            return false;
+        for (const key of keysA) {
+            if (!keysB.includes(key))
+                return false;
+            if (!this.deepEquals(a[key], b[key]))
+                return false;
+        }
+        return true;
+    }
+}
+exports.ValueObject = ValueObject;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hmpsn/ts-ddd",
+  "version": "1.0.0",
+  "description": "Base classes for implementing Domain-Driven Design (DDD) applications in TypeScript",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ddd",
+    "domain-driven-design",
+    "typescript",
+    "entity",
+    "value-object",
+    "aggregate-root",
+    "domain-event"
+  ],
+  "author": "Thomas Hampson <thomas@hmpsn.me>",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrhammo/ts-ddd.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.10",
+    "@typescript-eslint/eslint-plugin": "^8.53.1",
+    "@typescript-eslint/parser": "^8.53.1",
+    "eslint": "^9.39.2",
+    "jest": "^30.2.0",
+    "prettier": "^3.8.1",
+    "semantic-release": "^24.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  }
+}