@velony/domain 1.1.0 → 1.1.2

package/README.md

@@ -0,0 +1,237 @@
+# @velony/domain
+
+A TypeScript library providing core building blocks for Domain-Driven Design (DDD) applications.
+
+## Installation
+
+```bash
+npm install @velony/domain
+```
+
+## Features
+
+- **Type-safe** - Full TypeScript support with comprehensive type definitions
+- **DDD Patterns** - Implementations of core DDD tactical patterns
+- **Immutable** - Value objects and events are immutable by design
+- **Minimal dependencies** - Only depends on `uuid` for event ID generation
+
+## Core Concepts
+
+### Entity
+
+An object with a distinct identity that runs through time and different states.
+
+```typescript
+import { Entity, Id } from '@velony/domain';
+
+class UserId extends Id<string> {
+  static create(value: string): UserId {
+    return new UserId(value);
+  }
+}
+
+class User extends Entity<UserId> {
+  constructor(
+    id: UserId,
+    private name: string,
+    private email: string
+  ) {
+    super(id);
+  }
+
+  getName(): string {
+    return this.name;
+  }
+
+  getEmail(): string {
+    return this.email;
+  }
+}
+
+const userId = UserId.create('user-123');
+const user = new User(userId, 'John Doe', 'john@example.com');
+```
+
+### Value Object
+
+An immutable object defined by its attributes rather than a unique identifier.
+
+```typescript
+import { ValueObject } from '@velony/domain';
+
+class Email extends ValueObject<string> {
+  private constructor(value: string) {
+    super(value);
+  }
+
+  static create(value: string): Email {
+    if (!value.includes('@')) {
+      throw new Error('Invalid email format');
+    }
+    return new Email(value);
+  }
+
+  equals(other: Email): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}
+
+const email = Email.create('user@example.com');
+```
+
+### Primitive Value Object
+
+A convenient base class for value objects wrapping primitive types.
+
+```typescript
+import { PrimitiveValueObject } from '@velony/domain';
+
+class Age extends PrimitiveValueObject<number> {
+  private constructor(value: number) {
+    super(value);
+  }
+
+  static create(value: number): Age {
+    if (value < 0 || value > 150) {
+      throw new Error('Invalid age');
+    }
+    return new Age(value);
+  }
+}
+
+const age = Age.create(25);
+console.log(age.toString()); // "25"
+```
+
+### Aggregate Root
+
+The entry point to an aggregate that maintains consistency boundaries and manages domain events.
+
+```typescript
+import { AggregateRoot, Id, DomainEvent } from '@velony/domain';
+
+class OrderId extends Id<string> {
+  static create(value: string): OrderId {
+    return new OrderId(value);
+  }
+}
+
+class OrderPlacedEvent extends DomainEvent<{ total: number }> {
+  static readonly type = 'order.placed';
+
+  constructor(aggregateId: string, total: number) {
+    super(aggregateId, { total });
+  }
+}
+
+class Order extends AggregateRoot<OrderId> {
+  constructor(
+    id: OrderId,
+    private total: number
+  ) {
+    super(id);
+  }
+
+  place(): void {
+    this.pushDomainEvent(
+      new OrderPlacedEvent(this.id.toString(), this.total)
+    );
+  }
+}
+
+const order = new Order(OrderId.create('order-123'), 100);
+order.place();
+const events = order.pullDomainEvents();
+```
+
+### Domain Event
+
+Represents something significant that happened in the domain.
+
+```typescript
+import { DomainEvent } from '@velony/domain';
+
+interface UserRegisteredPayload {
+  email: string;
+  name: string;
+}
+
+class UserRegisteredEvent extends DomainEvent<UserRegisteredPayload> {
+  static readonly type = 'user.registered';
+
+  constructor(aggregateId: string, email: string, name: string) {
+    super(aggregateId, { email, name });
+  }
+}
+
+const event = new UserRegisteredEvent('user-123', 'john@example.com', 'John Doe');
+console.log(event.id); // UUIDv7
+console.log(event.type); // "user.registered"
+console.log(event.occurredAt); // Date
+console.log(event.payload); // { email: "john@example.com", name: "John Doe" }
+```
+
+### StoragePath
+
+A built-in value object for safe storage paths.
+
+```typescript
+import { StoragePath } from '@velony/domain';
+
+const path = StoragePath.create('uploads/images/photo.jpg');
+console.log(path.extension); // "jpg"
+console.log(path.toUrl('https://storage.example.com')); 
+// "https://storage.example.com/uploads/images/photo.jpg"
+
+// Validation prevents unsafe paths
+StoragePath.create('/etc/passwd'); // Error: Storage path should not start with /
+StoragePath.create('../secrets'); // Error: Storage path cannot contain ..
+StoragePath.create('files//data'); // Error: Storage path contains invalid double slashes
+```
+
+## API Reference
+
+### `Entity<TIdentifier>`
+- `id: TIdentifier` - The unique identifier
+- `equals(other: this): boolean` - Compare entities by identity
+
+### `ValueObject<TValue>`
+- `value: TValue` - The wrapped value
+- `equals(other: this): boolean` - Compare by value (abstract)
+- `toString(): string` - String representation (abstract)
+
+### `PrimitiveValueObject<T>`
+- Extends `ValueObject<T>` with default implementations for primitives
+- `equals(other: this): boolean` - Compares using strict equality
+- `toString(): string` - Converts value to string
+
+### `Id<T>`
+- Extends `PrimitiveValueObject<T>` for entity identifiers
+
+### `AggregateRoot<TIdentifier>`
+- Extends `Entity<TIdentifier>`
+- `pullDomainEvents(): DomainEvent<any>[]` - Retrieve and clear events
+- `pushDomainEvent(event: DomainEvent<any>): void` - Add event (protected)
+
+### `DomainEvent<TPayload>`
+- `id: string` - Unique event ID (UUIDv7)
+- `aggregateId: string` - ID of the aggregate that produced the event
+- `payload: TPayload` - Event-specific data
+- `occurredAt: Date` - Timestamp of occurrence
+- `type: string` - Event type identifier
+
+## License
+
+MIT
+
+## Repository
+
+[https://github.com/velony-ai/domain](https://github.com/velony-ai/domain)
+
+## Issues
+
+[https://github.com/velony-ai/domain/issues](https://github.com/velony-ai/domain/issues)

package/dist/aggregate-root.d.ts

@@ -2,10 +2,37 @@ import { DomainEvent } from './domain-event';
 import { Entity } from './entity';
 import { Id } from './id';
 declare const AGGREGATE_ROOT_BRAND: unique symbol;
+/**
+ * Abstract base class for aggregate roots in Domain-Driven Design.
+ * An aggregate root is the entry point to an aggregate and is responsible for
+ * maintaining the consistency of the aggregate boundary.
+ * It manages domain events that occur within the aggregate.
+ *
+ * @template TIdentifier - The type of identifier for the aggregate root, must extend Id
+ * @extends Entity
+ */
 export declare abstract class AggregateRoot<TIdentifier extends Id<string | number>> extends Entity<TIdentifier> {
     private readonly [AGGREGATE_ROOT_BRAND];
+    /**
+     * Collection of domain events that have occurred within this aggregate.
+     * @private
+     */
     private _domainEvents;
+    /**
+     * Retrieves and clears all pending domain events from the aggregate.
+     * This method is typically called by infrastructure code after persisting
+     * the aggregate to publish the events.
+     *
+     * @returns An array of domain events that occurred within the aggregate
+     */
     pullDomainEvents(): DomainEvent<any>[];
-    protected addDomainEvent(event: DomainEvent<any>): void;
+    /**
+     * Adds a domain event to the aggregate's event collection.
+     * Protected to allow only the aggregate itself to record events.
+     *
+     * @param event - The domain event to add
+     * @protected
+     */
+    protected pushDomainEvent(event: DomainEvent<any>): void;
 }
 export {};

package/dist/aggregate-root.js

@@ -2,15 +2,42 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AggregateRoot = void 0;
 const entity_1 = require("./entity");
+/**
+ * Abstract base class for aggregate roots in Domain-Driven Design.
+ * An aggregate root is the entry point to an aggregate and is responsible for
+ * maintaining the consistency of the aggregate boundary.
+ * It manages domain events that occur within the aggregate.
+ *
+ * @template TIdentifier - The type of identifier for the aggregate root, must extend Id
+ * @extends Entity
+ */
 class AggregateRoot extends entity_1.Entity {
     [AGGREGATE_ROOT_BRAND];
+    /**
+     * Collection of domain events that have occurred within this aggregate.
+     * @private
+     */
     _domainEvents = [];
+    /**
+     * Retrieves and clears all pending domain events from the aggregate.
+     * This method is typically called by infrastructure code after persisting
+     * the aggregate to publish the events.
+     *
+     * @returns An array of domain events that occurred within the aggregate
+     */
     pullDomainEvents() {
         const events = [...this._domainEvents];
         this._domainEvents = [];
         return events;
     }
-    addDomainEvent(event) {
+    /**
+     * Adds a domain event to the aggregate's event collection.
+     * Protected to allow only the aggregate itself to record events.
+     *
+     * @param event - The domain event to add
+     * @protected
+     */
+    pushDomainEvent(event) {
         this._domainEvents.push(event);
     }
 }

package/dist/aggregate-root.js.map

@@ -1 +1 @@
-{"version":3,"file":"aggregate-root.js","sourceRoot":"","sources":["../src/aggregate-root.ts"],"names":[],"mappings":";;;AACA,qCAAkC;AAKlC,MAAsB,aAEpB,SAAQ,eAAmB;IACV,CAAC,oBAAoB,CAAC,CAAO;IAEtC,aAAa,GAAuB,EAAE,CAAC;IAExC,gBAAgB;QACrB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC;IAChB,CAAC;IAES,cAAc,CAAC,KAAuB;QAC9C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;CACF;AAhBD,sCAgBC"}
+{"version":3,"file":"aggregate-root.js","sourceRoot":"","sources":["../src/aggregate-root.ts"],"names":[],"mappings":";;;AACA,qCAAkC;AAKlC;;;;;;;;GAQG;AACH,MAAsB,aAEpB,SAAQ,eAAmB;IACV,CAAC,oBAAoB,CAAC,CAAO;IAE9C;;;OAGG;IACK,aAAa,GAAuB,EAAE,CAAC;IAE/C;;;;;;OAMG;IACI,gBAAgB;QACrB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACO,eAAe,CAAC,KAAuB;QAC/C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;CACF;AAlCD,sCAkCC"}

package/dist/domain-event.d.ts

@@ -1,11 +1,50 @@
 export declare const DOMAIN_EVENT_BRAND: unique symbol;
+/**
+ * Abstract base class for domain events in Domain-Driven Design.
+ * A domain event represents something that happened in the domain that
+ * domain experts care about. Events are immutable and represent facts.
+ *
+ * @template TPayload - The type of the event payload containing event-specific data
+ */
 export declare abstract class DomainEvent<TPayload> {
     private readonly [DOMAIN_EVENT_BRAND];
+    /**
+     * Static type identifier for the event class.
+     * Should be overridden in concrete event classes.
+     */
     static readonly type: string;
+    /**
+     * Unique identifier for this event instance (UUIDv7).
+     * @readonly
+     */
     readonly id: string;
+    /**
+     * The identifier of the aggregate that produced this event.
+     * @readonly
+     */
     readonly aggregateId: string;
+    /**
+     * The data payload specific to this event.
+     * @readonly
+     */
     readonly payload: TPayload;
+    /**
+     * The timestamp when this event occurred.
+     * @readonly
+     */
     readonly occurredAt: Date;
+    /**
+     * Creates a new domain event.
+     *
+     * @param aggregateId - The ID of the aggregate that produced this event
+     * @param payload - The event-specific data
+     * @protected
+     */
     protected constructor(aggregateId: string, payload: TPayload);
+    /**
+     * Gets the type identifier for this event.
+     *
+     * @returns The event type string from the static type property
+     */
     get type(): string;
 }

package/dist/domain-event.js

@@ -2,19 +2,58 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DomainEvent = void 0;
 const uuid_1 = require("uuid");
+/**
+ * Abstract base class for domain events in Domain-Driven Design.
+ * A domain event represents something that happened in the domain that
+ * domain experts care about. Events are immutable and represent facts.
+ *
+ * @template TPayload - The type of the event payload containing event-specific data
+ */
 class DomainEvent {
     [exports.DOMAIN_EVENT_BRAND];
+    /**
+     * Static type identifier for the event class.
+     * Should be overridden in concrete event classes.
+     */
     static type;
+    /**
+     * Unique identifier for this event instance (UUIDv7).
+     * @readonly
+     */
     id;
+    /**
+     * The identifier of the aggregate that produced this event.
+     * @readonly
+     */
     aggregateId;
+    /**
+     * The data payload specific to this event.
+     * @readonly
+     */
     payload;
+    /**
+     * The timestamp when this event occurred.
+     * @readonly
+     */
     occurredAt;
+    /**
+     * Creates a new domain event.
+     *
+     * @param aggregateId - The ID of the aggregate that produced this event
+     * @param payload - The event-specific data
+     * @protected
+     */
     constructor(aggregateId, payload) {
         this.id = (0, uuid_1.v7)();
         this.aggregateId = aggregateId;
         this.occurredAt = new Date();
         this.payload = payload;
     }
+    /**
+     * Gets the type identifier for this event.
+     *
+     * @returns The event type string from the static type property
+     */
     get type() {
         return this.constructor.type;
     }

package/dist/domain-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"domain-event.js","sourceRoot":"","sources":["../src/domain-event.ts"],"names":[],"mappings":";;;AAAA,+BAAoC;AAIpC,MAAsB,WAAW;IACd,CAAC,0BAAkB,CAAC,CAAO;IAErC,MAAM,CAAU,IAAI,CAAS;IAEpB,EAAE,CAAS;IACX,WAAW,CAAS;IACpB,OAAO,CAAW;IAClB,UAAU,CAAO;IAEjC,YAAsB,WAAmB,EAAE,OAAiB;QAC1D,IAAI,CAAC,EAAE,GAAG,IAAA,SAAM,GAAE,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,IAAW,IAAI;QACb,OAAQ,IAAI,CAAC,WAA4C,CAAC,IAAI,CAAC;IACjE,CAAC;CACF;AApBD,kCAoBC"}
+{"version":3,"file":"domain-event.js","sourceRoot":"","sources":["../src/domain-event.ts"],"names":[],"mappings":";;;AAAA,+BAAoC;AAIpC;;;;;;GAMG;AACH,MAAsB,WAAW;IACd,CAAC,0BAAkB,CAAC,CAAO;IAE5C;;;OAGG;IACI,MAAM,CAAU,IAAI,CAAS;IAEpC;;;OAGG;IACa,EAAE,CAAS;IAE3B;;;OAGG;IACa,WAAW,CAAS;IAEpC;;;OAGG;IACa,OAAO,CAAW;IAElC;;;OAGG;IACa,UAAU,CAAO;IAEjC;;;;;;OAMG;IACH,YAAsB,WAAmB,EAAE,OAAiB;QAC1D,IAAI,CAAC,EAAE,GAAG,IAAA,SAAM,GAAE,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,IAAW,IAAI;QACb,OAAQ,IAAI,CAAC,WAA4C,CAAC,IAAI,CAAC;IACjE,CAAC;CACF;AAvDD,kCAuDC"}

package/dist/entity.d.ts

@@ -1,10 +1,40 @@
 import { Id } from './id';
 declare const ENTITY_BRAND: unique symbol;
+/**
+ * Abstract base class for entities in Domain-Driven Design.
+ * An entity is an object that has a distinct identity that runs through time
+ * and different states. Two entities with different identifiers are considered
+ * different even if all other attributes are the same.
+ *
+ * @template TIdentifier - The type of identifier for the entity, must extend Id
+ */
 export declare abstract class Entity<TIdentifier extends Id<string | number>> {
     private readonly [ENTITY_BRAND];
+    /**
+     * The unique identifier for this entity.
+     * @protected
+     */
     protected readonly _id: TIdentifier;
+    /**
+     * Creates a new entity with the given identifier.
+     *
+     * @param id - The unique identifier for this entity
+     * @protected
+     */
     protected constructor(id: TIdentifier);
+    /**
+     * Gets the unique identifier of this entity.
+     *
+     * @returns The entity's identifier
+     */
     get id(): TIdentifier;
+    /**
+     * Checks if this entity is equal to another entity.
+     * Two entities are equal if they have the same identifier.
+     *
+     * @param other - The entity to compare with
+     * @returns True if the entities have the same identifier, false otherwise
+     */
     equals(other: this): boolean;
 }
 export {};

package/dist/entity.js

@@ -1,15 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Entity = void 0;
+/**
+ * Abstract base class for entities in Domain-Driven Design.
+ * An entity is an object that has a distinct identity that runs through time
+ * and different states. Two entities with different identifiers are considered
+ * different even if all other attributes are the same.
+ *
+ * @template TIdentifier - The type of identifier for the entity, must extend Id
+ */
 class Entity {
     [ENTITY_BRAND];
+    /**
+     * The unique identifier for this entity.
+     * @protected
+     */
     _id;
+    /**
+     * Creates a new entity with the given identifier.
+     *
+     * @param id - The unique identifier for this entity
+     * @protected
+     */
     constructor(id) {
         this._id = id;
     }
+    /**
+     * Gets the unique identifier of this entity.
+     *
+     * @returns The entity's identifier
+     */
     get id() {
         return this._id;
     }
+    /**
+     * Checks if this entity is equal to another entity.
+     * Two entities are equal if they have the same identifier.
+     *
+     * @param other - The entity to compare with
+     * @returns True if the entities have the same identifier, false otherwise
+     */
     equals(other) {
         return this._id.equals(other._id);
     }

package/dist/entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":";;;AAIA,MAAsB,MAAM;IACT,CAAC,YAAY,CAAC,CAAO;IAEnB,GAAG,CAAc;IAEpC,YAAsB,EAAe;QACnC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;IAChB,CAAC;IAED,IAAW,EAAE;QACX,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAEM,MAAM,CAAC,KAAW;QACvB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;CACF;AAhBD,wBAgBC"}
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":";;;AAIA;;;;;;;GAOG;AACH,MAAsB,MAAM;IACT,CAAC,YAAY,CAAC,CAAO;IAEtC;;;OAGG;IACgB,GAAG,CAAc;IAEpC;;;;;OAKG;IACH,YAAsB,EAAe;QACnC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,IAAW,EAAE;QACX,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAW;QACvB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;CACF;AAtCD,wBAsCC"}

package/dist/id.d.ts

@@ -1,5 +1,13 @@
 import { PrimitiveValueObject } from './primitive-value-object.js';
 declare const ID_BRAND: unique symbol;
+/**
+ * Abstract base class for entity identifiers.
+ * Represents a unique identifier for domain entities, ensuring type safety
+ * and proper value object semantics for IDs.
+ *
+ * @template T - The primitive type of the identifier (string or number)
+ * @extends PrimitiveValueObject
+ */
 export declare abstract class Id<T extends string | number> extends PrimitiveValueObject<T> {
     private readonly [ID_BRAND];
 }

package/dist/id.js

@@ -2,6 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Id = void 0;
 const primitive_value_object_js_1 = require("./primitive-value-object.js");
+/**
+ * Abstract base class for entity identifiers.
+ * Represents a unique identifier for domain entities, ensuring type safety
+ * and proper value object semantics for IDs.
+ *
+ * @template T - The primitive type of the identifier (string or number)
+ * @extends PrimitiveValueObject
+ */
 class Id extends primitive_value_object_js_1.PrimitiveValueObject {
     [ID_BRAND];
 }

package/dist/id.js.map

@@ -1 +1 @@
-{"version":3,"file":"id.js","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":";;;AAAA,2EAAmE;AAInE,MAAsB,EAEpB,SAAQ,gDAAuB;IACd,CAAC,QAAQ,CAAC,CAAO;CACnC;AAJD,gBAIC"}
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":";;;AAAA,2EAAmE;AAInE;;;;;;;GAOG;AACH,MAAsB,EAEpB,SAAQ,gDAAuB;IACd,CAAC,QAAQ,CAAC,CAAO;CACnC;AAJD,gBAIC"}

package/dist/index.d.ts

@@ -1,3 +1,15 @@
+/**
+ * @velony/domain - Domain-Driven Design building blocks
+ *
+ * This package provides core abstractions for implementing Domain-Driven Design (DDD)
+ * patterns in TypeScript applications. It includes base classes for:
+ * - Entities: Objects with unique identities
+ * - Value Objects: Immutable objects defined by their attributes
+ * - Aggregate Roots: Entry points to aggregates that maintain consistency
+ * - Domain Events: Represent significant occurrences in the domain
+ *
+ * @packageDocumentation
+ */
 export { Entity } from './entity';
 export { Id } from './id';
 export { ValueObject } from './value-object';

package/dist/index.js

@@ -1,4 +1,16 @@
 "use strict";
+/**
+ * @velony/domain - Domain-Driven Design building blocks
+ *
+ * This package provides core abstractions for implementing Domain-Driven Design (DDD)
+ * patterns in TypeScript applications. It includes base classes for:
+ * - Entities: Objects with unique identities
+ * - Value Objects: Immutable objects defined by their attributes
+ * - Aggregate Roots: Entry points to aggregates that maintain consistency
+ * - Domain Events: Represent significant occurrences in the domain
+ *
+ * @packageDocumentation
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StoragePath = exports.DomainEvent = exports.AggregateRoot = exports.PrimitiveValueObject = exports.ValueObject = exports.Id = exports.Entity = void 0;
 var entity_1 = require("./entity");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,2BAA0B;AAAjB,wFAAA,EAAE,OAAA;AACX,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AACpB,mEAAgE;AAAvD,8HAAA,oBAAoB,OAAA;AAC7B,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AACtB,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AACpB,mEAA8D;AAArD,8GAAA,WAAW,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAEH,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,2BAA0B;AAAjB,wFAAA,EAAE,OAAA;AACX,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AACpB,mEAAgE;AAAvD,8HAAA,oBAAoB,OAAA;AAC7B,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AACtB,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AACpB,mEAA8D;AAArD,8GAAA,WAAW,OAAA"}

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

@@ -1,8 +1,29 @@
 import { ValueObject } from './value-object';
 declare const PRIMITIVE_VO_BRAND: unique symbol;
+/**
+ * Abstract base class for value objects wrapping primitive values.
+ * This class provides a convenient base for value objects that wrap
+ * primitive types (string, number, or boolean) with default implementations
+ * for equality and string conversion.
+ *
+ * @template T - The primitive type of the wrapped value (string, number, or boolean)
+ * @extends ValueObject
+ */
 export declare abstract class PrimitiveValueObject<T extends string | number | boolean> extends ValueObject<T> {
     private readonly [PRIMITIVE_VO_BRAND];
+    /**
+     * Checks if this value object is equal to another by comparing primitive values.
+     * Uses strict equality (===) for comparison.
+     *
+     * @param other - The value object to compare with
+     * @returns True if the primitive values are strictly equal, false otherwise
+     */
     equals(other: this): boolean;
+    /**
+     * Returns a string representation of the primitive value.
+     *
+     * @returns The string representation of the wrapped primitive value
+     */
     toString(): string;
 }
 export {};

package/dist/primitive-value-object.js

@@ -2,11 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PrimitiveValueObject = void 0;
 const value_object_1 = require("./value-object");
+/**
+ * Abstract base class for value objects wrapping primitive values.
+ * This class provides a convenient base for value objects that wrap
+ * primitive types (string, number, or boolean) with default implementations
+ * for equality and string conversion.
+ *
+ * @template T - The primitive type of the wrapped value (string, number, or boolean)
+ * @extends ValueObject
+ */
 class PrimitiveValueObject extends value_object_1.ValueObject {
     [PRIMITIVE_VO_BRAND];
+    /**
+     * Checks if this value object is equal to another by comparing primitive values.
+     * Uses strict equality (===) for comparison.
+     *
+     * @param other - The value object to compare with
+     * @returns True if the primitive values are strictly equal, false otherwise
+     */
     equals(other) {
-        return this._value === other.value;
+        return this._value === other._value;
     }
+    /**
+     * Returns a string representation of the primitive value.
+     *
+     * @returns The string representation of the wrapped primitive value
+     */
     toString() {
         return String(this._value);
     }

package/dist/primitive-value-object.js.map

@@ -1 +1 @@
-{"version":3,"file":"primitive-value-object.js","sourceRoot":"","sources":["../src/primitive-value-object.ts"],"names":[],"mappings":";;;AAAA,iDAA6C;AAI7C,MAAsB,oBAEpB,SAAQ,0BAAc;IACL,CAAC,kBAAkB,CAAC,CAAO;IAErC,MAAM,CAAC,KAAW;QACvB,OAAO,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,KAAK,CAAC;IACrC,CAAC;IAEM,QAAQ;QACb,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;CACF;AAZD,oDAYC"}
+{"version":3,"file":"primitive-value-object.js","sourceRoot":"","sources":["../src/primitive-value-object.ts"],"names":[],"mappings":";;;AAAA,iDAA6C;AAI7C;;;;;;;;GAQG;AACH,MAAsB,oBAEpB,SAAQ,0BAAc;IACL,CAAC,kBAAkB,CAAC,CAAO;IAE5C;;;;;;OAMG;IACI,MAAM,CAAC,KAAW;QACvB,OAAO,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACI,QAAQ;QACb,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;CACF;AAxBD,oDAwBC"}

package/dist/value-object.d.ts

@@ -1,10 +1,45 @@
 declare const VO_BRAND: unique symbol;
+/**
+ * Abstract base class for value objects in Domain-Driven Design.
+ * A value object is an immutable object that represents a descriptive aspect
+ * of the domain with no conceptual identity. Value objects are defined by
+ * their attributes rather than a unique identifier.
+ *
+ * @template TValue - The type of the wrapped value
+ */
 export declare abstract class ValueObject<TValue> {
     private readonly [VO_BRAND];
+    /**
+     * The encapsulated value.
+     * @protected
+     */
     protected readonly _value: TValue;
+    /**
+     * Creates a new value object wrapping the given value.
+     *
+     * @param value - The value to wrap
+     * @protected
+     */
     protected constructor(value: TValue);
+    /**
+     * Gets the wrapped value.
+     *
+     * @returns The encapsulated value
+     */
     get value(): TValue;
+    /**
+     * Checks if this value object is equal to another value object.
+     * Concrete implementations should define equality based on the values.
+     *
+     * @param other - The value object to compare with
+     * @returns True if the value objects are equal, false otherwise
+     */
     abstract equals(other: this): boolean;
+    /**
+     * Returns a string representation of the value object.
+     *
+     * @returns A string representation of this value object
+     */
     abstract toString(): string;
 }
 export {};

package/dist/value-object.js

@@ -1,12 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ValueObject = void 0;
+/**
+ * Abstract base class for value objects in Domain-Driven Design.
+ * A value object is an immutable object that represents a descriptive aspect
+ * of the domain with no conceptual identity. Value objects are defined by
+ * their attributes rather than a unique identifier.
+ *
+ * @template TValue - The type of the wrapped value
+ */
 class ValueObject {
     [VO_BRAND];
+    /**
+     * The encapsulated value.
+     * @protected
+     */
     _value;
+    /**
+     * Creates a new value object wrapping the given value.
+     *
+     * @param value - The value to wrap
+     * @protected
+     */
     constructor(value) {
         this._value = value;
     }
+    /**
+     * Gets the wrapped value.
+     *
+     * @returns The encapsulated value
+     */
     get value() {
         return this._value;
     }

package/dist/value-object.js.map

@@ -1 +1 @@
-{"version":3,"file":"value-object.js","sourceRoot":"","sources":["../src/value-object.ts"],"names":[],"mappings":";;;AAEA,MAAsB,WAAW;IACd,CAAC,QAAQ,CAAC,CAAO;IAEf,MAAM,CAAS;IAElC,YAAsB,KAAa;QACjC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CAKF;AAhBD,kCAgBC"}
+{"version":3,"file":"value-object.js","sourceRoot":"","sources":["../src/value-object.ts"],"names":[],"mappings":";;;AAEA;;;;;;;GAOG;AACH,MAAsB,WAAW;IACd,CAAC,QAAQ,CAAC,CAAO;IAElC;;;OAGG;IACgB,MAAM,CAAS;IAElC;;;;;OAKG;IACH,YAAsB,KAAa;QACjC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CAiBF;AA3CD,kCA2CC"}

package/dist/value-objects/storage-path.vo.d.ts

@@ -1,10 +1,50 @@
 import { PrimitiveValueObject } from '../primitive-value-object';
 declare const STORAGE_PATH_VO_BRAND: unique symbol;
+/**
+ * Value object representing a storage path with validation.
+ * Ensures paths are safe and properly formatted for storage operations.
+ * Paths must not start with '/', contain double slashes, or include '..' for security.
+ *
+ * @extends PrimitiveValueObject
+ */
 export declare class StoragePath extends PrimitiveValueObject<string> {
     private readonly [STORAGE_PATH_VO_BRAND];
+    /**
+     * Private constructor to enforce factory method usage.
+     *
+     * @param value - The validated storage path string
+     * @private
+     */
     private constructor();
+    /**
+     * Factory method to create a new StoragePath with validation.
+     *
+     * @param value - The storage path string to validate and wrap
+     * @returns A new StoragePath instance
+     * @throws {Error} If path starts with '/'
+     * @throws {Error} If path contains double slashes '//'
+     * @throws {Error} If path contains '..' (parent directory reference)
+     */
     static create(value: string): StoragePath;
+    /**
+     * Converts the storage path to a full URL by combining with a base URL.
+     * Ensures proper URL formatting by removing trailing slashes from base URL.
+     *
+     * @param baseUrl - The base URL to prepend to the storage path
+     * @returns The complete URL with the storage path appended
+     * @example
+     * const path = StoragePath.create('files/document.pdf');
+     * path.toUrl('https://storage.example.com'); // 'https://storage.example.com/files/document.pdf'
+     */
     toUrl(baseUrl: string): string;
+    /**
+     * Gets the file extension from the storage path.
+     *
+     * @returns The lowercase file extension without the dot, or empty string if no extension
+     * @example
+     * StoragePath.create('files/document.PDF').extension // 'pdf'
+     * StoragePath.create('files/readme').extension // ''
+     */
     get extension(): string;
 }
 export {};

package/dist/value-objects/storage-path.vo.js

@@ -2,11 +2,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StoragePath = void 0;
 const primitive_value_object_1 = require("../primitive-value-object");
+/**
+ * Value object representing a storage path with validation.
+ * Ensures paths are safe and properly formatted for storage operations.
+ * Paths must not start with '/', contain double slashes, or include '..' for security.
+ *
+ * @extends PrimitiveValueObject
+ */
 class StoragePath extends primitive_value_object_1.PrimitiveValueObject {
     [STORAGE_PATH_VO_BRAND];
+    /**
+     * Private constructor to enforce factory method usage.
+     *
+     * @param value - The validated storage path string
+     * @private
+     */
     constructor(value) {
         super(value);
     }
+    /**
+     * Factory method to create a new StoragePath with validation.
+     *
+     * @param value - The storage path string to validate and wrap
+     * @returns A new StoragePath instance
+     * @throws {Error} If path starts with '/'
+     * @throws {Error} If path contains double slashes '//'
+     * @throws {Error} If path contains '..' (parent directory reference)
+     */
     static create(value) {
         if (value.startsWith('/')) {
             throw new Error('Storage path should not start with /');
@@ -19,9 +41,27 @@ class StoragePath extends primitive_value_object_1.PrimitiveValueObject {
         }
         return new StoragePath(value);
     }
+    /**
+     * Converts the storage path to a full URL by combining with a base URL.
+     * Ensures proper URL formatting by removing trailing slashes from base URL.
+     *
+     * @param baseUrl - The base URL to prepend to the storage path
+     * @returns The complete URL with the storage path appended
+     * @example
+     * const path = StoragePath.create('files/document.pdf');
+     * path.toUrl('https://storage.example.com'); // 'https://storage.example.com/files/document.pdf'
+     */
     toUrl(baseUrl) {
         return `${baseUrl.replace(/\/$/, '')}/${this._value}`;
     }
+    /**
+     * Gets the file extension from the storage path.
+     *
+     * @returns The lowercase file extension without the dot, or empty string if no extension
+     * @example
+     * StoragePath.create('files/document.PDF').extension // 'pdf'
+     * StoragePath.create('files/readme').extension // ''
+     */
     get extension() {
         const parts = this._value.split('.');
         return parts.at(-1)?.toLowerCase() ?? '';

package/dist/value-objects/storage-path.vo.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage-path.vo.js","sourceRoot":"","sources":["../../src/value-objects/storage-path.vo.ts"],"names":[],"mappings":";;;AAAA,sEAAiE;AAIjE,MAAa,WAAY,SAAQ,6CAA4B;IAC1C,CAAC,qBAAqB,CAAC,CAAO;IAE/C,YAAoB,KAAa;QAC/B,KAAK,CAAC,KAAK,CAAC,CAAC;IACf,CAAC;IAEM,MAAM,CAAC,MAAM,CAAC,KAAa;QAChC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAEM,KAAK,CAAC,OAAe;QAC1B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;IACxD,CAAC;IAED,IAAW,SAAS;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC3C,CAAC;CACF;AA7BD,kCA6BC"}
+{"version":3,"file":"storage-path.vo.js","sourceRoot":"","sources":["../../src/value-objects/storage-path.vo.ts"],"names":[],"mappings":";;;AAAA,sEAAiE;AAIjE;;;;;;GAMG;AACH,MAAa,WAAY,SAAQ,6CAA4B;IAC1C,CAAC,qBAAqB,CAAC,CAAO;IAE/C;;;;;OAKG;IACH,YAAoB,KAAa;QAC/B,KAAK,CAAC,KAAK,CAAC,CAAC;IACf,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM,CAAC,MAAM,CAAC,KAAa;QAChC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;;;OASG;IACI,KAAK,CAAC,OAAe;QAC1B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;IACxD,CAAC;IAED;;;;;;;OAOG;IACH,IAAW,SAAS;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC3C,CAAC;CACF;AA9DD,kCA8DC"}

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@velony/domain",
-  "version": "1.1.0",
-  "description": "",
+  "version": "1.1.2",
+  "description": "TypeScript library providing core building blocks for Domain-Driven Design (DDD) applications",
+  "keywords": [
+    "ddd",
+    "domain-driven-design",
+    "domain",
+    "entity",
+    "value-object",
+    "aggregate",
+    "domain-event",
+    "typescript",
+    "ddd-patterns",
+    "tactical-patterns"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -11,8 +23,16 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
     "lint": "eslint src"