@libs-for-dev/nestjs-ddd-library 1.0.0

package/README.md

@@ -0,0 +1,154 @@
+# NestJS DDD Library
+
+A comprehensive library providing Domain-Driven Design (DDD) building blocks for NestJS applications. This library helps you implement DDD patterns such as Value Objects, Entities, and Aggregates in your NestJS projects with TypeScript.
+
+## Features
+
+- **Entities**: Objects that have a distinct identity that runs through time and different states
+- **Aggregates**: Cluster of domain objects that can be treated as a single unit
+- **Result types**: Using oxide.ts for type-safe error handling
+- **Value Objects**: Immutable objects that contain attributes but have no conceptual identity with examples:
+  - **UUID**: Built-in UUID v7 generation and validation
+  - **Email**: Email value object with validation
+
+## Installation
+
+```bash
+# Using npm
+npm install @libs-for-dev/nestjs-ddd-library
+
+# Using yarn
+yarn add @libs-for-dev/nestjs-ddd-library
+
+# Using pnpm
+pnpm add @libs-for-dev/nestjs-ddd-library
+```
+
+### Peer Dependencies
+
+This library requires the following peer dependencies:
+
+```bash
+yarn add @nestjs/cqrs class-validator fast-equals oxide.ts ui7
+```
+
+## Usage Examples
+
+### Value Objects
+
+#### UUID
+
+```typescript
+import { Uuid } from '@libs-for-dev/nestjs-ddd-library';
+
+// Generate a new UUID (v7)
+const uuid = Uuid.generate();
+console.log(uuid.value); // Generated UUID v7 string
+
+// Create from existing UUID string
+const uuidResult = Uuid.create('de49eb8d-9199-4046-a784-d015148f95a7');
+
+if (uuidResult.isOk()) {
+  const uuid = uuidResult.unwrap();
+  console.log(uuid.value); // de49eb8d-9199-4046-a784-d015148f95a7
+} else {
+  // Handle error
+  console.error(uuidResult.unwrapErr());
+}
+```
+
+#### Email
+
+```typescript
+import { Email } from '@libs-for-dev/nestjs-ddd-library';
+
+// Create an Email value object
+const emailResult = Email.create('user@example.com');
+
+if (emailResult.isOk()) {
+  const email = emailResult.unwrap();
+  console.log(email.value); // user@example.com
+} else {
+  // Handle error
+  console.error(emailResult.unwrapErr());
+}
+```
+
+### Entities
+
+```typescript
+import { AbstractEntity, Uuid } from '@libs-for-dev/nestjs-ddd-library';
+
+// Define entity properties
+interface UserProps {
+  email: string;
+  name: string;
+}
+
+// Create an entity class
+class User extends AbstractEntity<Uuid, UserProps> {
+  public static create(id: Uuid, props: UserProps): User {
+    return new User(id, props);
+  }
+
+  // Add domain methods here
+  public updateName(name: string): void {
+    this.propsData = {
+      props: {
+        ...this.props,
+        name
+      }
+    };
+  }
+}
+
+// Usage
+const userId = Uuid.generate();
+const user = User.create(userId, {
+  email: 'user@example.com',
+  name: 'John Doe'
+});
+
+// Access properties
+console.log(user.id.value); // UUID
+console.log(user.props.name); // John Doe
+
+// Update properties using domain methods
+user.updateName('Jane Doe');
+console.log(user.props.name); // Jane Doe
+```
+
+## Domain Events
+
+The library integrates with NestJS CQRS to support domain events:
+
+```typescript
+import { AbstractEntity, Uuid } from '@libs-for-dev/nestjs-ddd-library';
+import { IEvent } from '@nestjs/cqrs';
+
+// Define a domain event
+class UserCreatedEvent implements IEvent {
+  constructor(public readonly userId: string, public readonly email: string) {}
+}
+
+// Entity with domain events
+class User extends AbstractEntity<Uuid, UserProps> {
+  public static create(id: Uuid, props: UserProps): User {
+    const user = new User(id, props);
+    user.apply(new UserCreatedEvent(id.value, props.email));
+    return user;
+  }
+}
+
+// In your NestJS application
+@EventsHandler(UserCreatedEvent)
+export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+  handle(event: UserCreatedEvent) {
+    console.log(`User created: ${event.userId} with email ${event.email}`);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/abstract-entity.d.ts

@@ -0,0 +1,12 @@
+import type { IEvent } from '@nestjs/cqrs';
+import { AggregateRoot } from '@nestjs/cqrs';
+export interface EntityPropsInterface<T> {
+    props: T;
+}
+export declare abstract class AbstractEntity<Id, Props, Event extends IEvent = IEvent> extends AggregateRoot<Event> {
+    readonly id: Id;
+    get props(): Props;
+    protected propsData: EntityPropsInterface<Props>;
+    protected constructor(id: Id, props: Props);
+    equals(object: AbstractEntity<Id, Props>): boolean;
+}

package/dist/abstract-entity.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractEntity = void 0;
+const cqrs_1 = require("@nestjs/cqrs");
+class AbstractEntity extends cqrs_1.AggregateRoot {
+    id;
+    get props() {
+        return Object.freeze(this.propsData.props);
+    }
+    propsData;
+    constructor(id, props) {
+        super();
+        this.id = id;
+        this.propsData = { props };
+    }
+    equals(object) {
+        if (this.constructor.name !== object.constructor.name) {
+            return false;
+        }
+        return this.id === object.id;
+    }
+}
+exports.AbstractEntity = AbstractEntity;

package/dist/abstract-value-object.d.ts

@@ -0,0 +1,11 @@
+export interface PrimitiveInterface<T extends Date | Primitives> {
+    value: T;
+}
+export type Primitives = boolean | null | number | string;
+type ValueObjectProps<T> = T extends Date | Primitives ? PrimitiveInterface<T> : T;
+export declare abstract class AbstractValueObject<T> {
+    readonly props: Readonly<ValueObjectProps<T>>;
+    protected constructor(props: Readonly<ValueObjectProps<T>>);
+    equals(valueObject: AbstractValueObject<T>): boolean;
+}
+export {};

package/dist/abstract-value-object.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractValueObject = void 0;
+const fast_equals_1 = require("fast-equals");
+class AbstractValueObject {
+    props;
+    constructor(props) {
+        this.props = props;
+    }
+    equals(valueObject) {
+        if (this.constructor.name !== valueObject.constructor.name) {
+            return false;
+        }
+        return (0, fast_equals_1.deepEqual)(valueObject.props, this.props);
+    }
+}
+exports.AbstractValueObject = AbstractValueObject;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './value-objects';
+export * from './abstract-entity';
+export * from './abstract-value-object';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./value-objects"), exports);
+__exportStar(require("./abstract-entity"), exports);
+__exportStar(require("./abstract-value-object"), exports);

package/dist/value-objects/email.d.ts

@@ -0,0 +1,7 @@
+import type { Result } from 'oxide.ts';
+import { AbstractValueObject } from '../abstract-value-object';
+export declare class Email extends AbstractValueObject<string> {
+    get value(): string;
+    static create(email: string): Result<Email, Error>;
+    private static isValid;
+}

package/dist/value-objects/email.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Email = void 0;
+const class_validator_1 = require("class-validator");
+const oxide_ts_1 = require("oxide.ts");
+const abstract_value_object_1 = require("../abstract-value-object");
+const not_an_email_error_1 = require("../value-objects/errors/not-an-email.error");
+class Email extends abstract_value_object_1.AbstractValueObject {
+    get value() {
+        return this.props.value;
+    }
+    static create(email) {
+        if (!this.isValid(email)) {
+            return (0, oxide_ts_1.Err)(new not_an_email_error_1.NotAnEmailError(email));
+        }
+        return (0, oxide_ts_1.Ok)(new Email({ value: email }));
+    }
+    static isValid(email) {
+        return (0, class_validator_1.isEmail)(email);
+    }
+}
+exports.Email = Email;

package/dist/value-objects/errors/index.d.ts

@@ -0,0 +1,2 @@
+export * from './not-an-email.error';
+export * from './not-an-uuid.error';

package/dist/value-objects/errors/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./not-an-email.error"), exports);
+__exportStar(require("./not-an-uuid.error"), exports);

package/dist/value-objects/errors/not-an-email.error.d.ts

@@ -0,0 +1,4 @@
+export declare class NotAnEmailError extends Error {
+    static readonly name = "NotAnEmailError";
+    constructor(email: string);
+}

package/dist/value-objects/errors/not-an-email.error.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotAnEmailError = void 0;
+class NotAnEmailError extends Error {
+    static name = 'NotAnEmailError';
+    constructor(email) {
+        super(`${email} is not a valid email`);
+    }
+}
+exports.NotAnEmailError = NotAnEmailError;

package/dist/value-objects/errors/not-an-uuid.error.d.ts

@@ -0,0 +1,4 @@
+export declare class NotAnUuidError extends Error {
+    static readonly name = "NotAnUuidError";
+    constructor(uuid: string);
+}

package/dist/value-objects/errors/not-an-uuid.error.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotAnUuidError = void 0;
+class NotAnUuidError extends Error {
+    static name = 'NotAnUuidError';
+    constructor(uuid) {
+        super(`${uuid} is not a valid UUID`);
+    }
+}
+exports.NotAnUuidError = NotAnUuidError;

package/dist/value-objects/index.d.ts

@@ -0,0 +1,3 @@
+export * from './errors';
+export * from './email';
+export * from './uuid';

package/dist/value-objects/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./errors"), exports);
+__exportStar(require("./email"), exports);
+__exportStar(require("./uuid"), exports);

package/dist/value-objects/uuid.d.ts

@@ -0,0 +1,7 @@
+import type { Result } from 'oxide.ts';
+import { AbstractValueObject } from '../abstract-value-object';
+export declare class Uuid extends AbstractValueObject<string> {
+    get value(): string;
+    static create(uuid: string): Result<Uuid, Error>;
+    static generate(): Uuid;
+}

package/dist/value-objects/uuid.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Uuid = void 0;
+const class_validator_1 = require("class-validator");
+const oxide_ts_1 = require("oxide.ts");
+const ui7_1 = require("ui7");
+const abstract_value_object_1 = require("../abstract-value-object");
+const not_an_uuid_error_1 = require("../value-objects/errors/not-an-uuid.error");
+class Uuid extends abstract_value_object_1.AbstractValueObject {
+    get value() {
+        return this.props.value;
+    }
+    static create(uuid) {
+        if (!(0, class_validator_1.isUUID)(uuid)) {
+            return (0, oxide_ts_1.Err)(new not_an_uuid_error_1.NotAnUuidError(uuid));
+        }
+        return (0, oxide_ts_1.Ok)(new Uuid({ value: uuid }));
+    }
+    static generate() {
+        return new Uuid({ value: (0, ui7_1.v7)() });
+    }
+}
+exports.Uuid = Uuid;

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@libs-for-dev/nestjs-ddd-library",
+  "version": "1.0.0",
+  "description": "NestJS DDD library",
+  "keywords": [
+    "ddd-library",
+    "nestjs"
+  ],
+  "repository": "https://gitlab.com/libs-for-dev/nestjs/nestjs-ddd-library",
+  "license": "MIT",
+  "author": {
+    "name": "libs-for-dev"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf ./dist && cti create ./src && tsc --project tsconfig.build.json && tsc-alias --project tsconfig.build.json && cti clean ./src",
+    "dev:quality": "yarn concurrently --timings --kill-others-on-fail 'yarn lint' 'yarn test'",
+    "dev:test:watch": "vitest",
+    "lint": "yarn concurrently --timings 'yarn:lint:*'",
+    "lint:audit": "yarn npm audit",
+    "lint:depcheck": "depcheck",
+    "lint:eslint": "eslint --cache --cache-location /tmp .",
+    "lint:scriptlint": "scriptlint",
+    "lint:tsc": "tsc --noEmit --pretty --project .",
+    "test": "yarn concurrently --timings 'npm:test:*'",
+    "test:mutation": "yarn stryker run",
+    "test:unit": "vitest run"
+  },
+  "devDependencies": {
+    "@libs-for-dev/eslint-rules": "2.3.3",
+    "@nestjs/common": "^11.1.0",
+    "@nestjs/core": "^11.1.0",
+    "@nestjs/cqrs": "^11.0.3",
+    "@stryker-mutator/core": "^8.7.1",
+    "@stryker-mutator/vitest-runner": "^8.7.1",
+    "@types/node": "^22.15.3",
+    "@vitest/coverage-v8": "^3.1.2",
+    "class-validator": "^0.14.1",
+    "concurrently": "^9.1.2",
+    "create-ts-index": "^1.14.0",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.25.1",
+    "fast-equals": "^5.2.2",
+    "jiti": "^2.4.2",
+    "oxide.ts": "^1.1.0",
+    "reflect-metadata": "^0.2.2",
+    "scriptlint": "^3.0.0",
+    "tsc-alias": "^1.8.15",
+    "typescript": "^5.8.3",
+    "ui7": "^0.2.3",
+    "vitest": "^3.1.2",
+    "yarn-audit-fix": "^10.1.1"
+  },
+  "peerDependencies": {
+    "@nestjs/cqrs": ">=9.0.0 <12.0.0",
+    "class-validator": ">=0.12.0 <0.15.0",
+    "fast-equals": ">=5.0.0 <6.0.0",
+    "oxide.ts": ">=1.0.0 <2.0.0",
+    "ui7": ">=0.2.0 <0.3.0"
+  },
+  "packageManager": "yarn@4.9.1",
+  "engines": {
+    "node": "^23.11.0"
+  }
+}