@cqrs-ddd/core 0.2.0

package/dist/domain/exceptions/invalid-value.exception.js

@@ -0,0 +1,67 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidValueException = void 0;
+const domain_exception_1 = require("./domain.exception");
+function describeViolation(violation) {
+    const { field } = violation;
+    switch (violation.rule) {
+        case 'required':
+            return `${field} is required.`;
+        case 'type':
+            return `${field} must be a ${violation.expected}.`;
+        case 'characters':
+            return `${field} must not contain control characters or unpaired surrogates.`;
+        case 'minLength':
+            return `${field} must be at least ${violation.limit} characters.`;
+        case 'maxLength':
+            return `${field} must be at most ${violation.limit} characters.`;
+        case 'pattern':
+            return `${field} does not match the required format.`;
+        case 'finite':
+            return `${field} must be a finite number.`;
+        case 'integer':
+            return `${field} must be a safe integer.`;
+        case 'min':
+            return `${field} must be at least ${violation.limit}.`;
+        case 'max':
+            return `${field} must be at most ${violation.limit}.`;
+    }
+}
+/**
+ * A value broke a rule of a {@link textRule} or {@link numberRule}.
+ *
+ * It is the error both rules throw by default, and the base class for an
+ * application's own exceptions, which then share its message format and its
+ * `violation`. `domainErrorHttpStatus()` answers 400 for it, like any other
+ * `DomainException`.
+ *
+ * The rejected value is not kept, so logging the exception cannot leak it.
+ *
+ * @example
+ * ```ts
+ * export class InvalidUsernameException extends InvalidValueException {}
+ *
+ * const username = textRule({
+ *   field: 'username',
+ *   minLength: 3,
+ *   error: (violation) => new InvalidUsernameException(violation),
+ * });
+ *
+ * username.normalize('ab');
+ * // throws InvalidUsernameException: "username must be at least 3 characters."
+ * ```
+ */
+class InvalidValueException extends domain_exception_1.DomainException {
+    violation;
+    /**
+     * @param violation - The broken rule.
+     * @param message - Replaces the default message built from `violation`.
+     */
+    constructor(violation, message) {
+        super(message ?? describeViolation(violation));
+        this.violation = violation;
+    }
+}
+exports.InvalidValueException = InvalidValueException;
+//# sourceMappingURL=invalid-value.exception.js.map

package/dist/domain/exceptions/invalid-value.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-value.exception.js","sourceRoot":"","sources":["../../../domain/exceptions/invalid-value.exception.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAGtE,yDAAqD;AAErD,SAAS,iBAAiB,CAAC,SAAyB;IAClD,MAAM,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IAC5B,QAAQ,SAAS,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,UAAU;YACb,OAAO,GAAG,KAAK,eAAe,CAAC;QACjC,KAAK,MAAM;YACT,OAAO,GAAG,KAAK,cAAc,SAAS,CAAC,QAAQ,GAAG,CAAC;QACrD,KAAK,YAAY;YACf,OAAO,GAAG,KAAK,8DAA8D,CAAC;QAChF,KAAK,WAAW;YACd,OAAO,GAAG,KAAK,qBAAqB,SAAS,CAAC,KAAK,cAAc,CAAC;QACpE,KAAK,WAAW;YACd,OAAO,GAAG,KAAK,oBAAoB,SAAS,CAAC,KAAK,cAAc,CAAC;QACnE,KAAK,SAAS;YACZ,OAAO,GAAG,KAAK,sCAAsC,CAAC;QACxD,KAAK,QAAQ;YACX,OAAO,GAAG,KAAK,2BAA2B,CAAC;QAC7C,KAAK,SAAS;YACZ,OAAO,GAAG,KAAK,0BAA0B,CAAC;QAC5C,KAAK,KAAK;YACR,OAAO,GAAG,KAAK,qBAAqB,SAAS,CAAC,KAAK,GAAG,CAAC;QACzD,KAAK,KAAK;YACR,OAAO,GAAG,KAAK,oBAAoB,SAAS,CAAC,KAAK,GAAG,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,qBAAsB,SAAQ,kCAAe;IAC/C,SAAS,CAAiB;IAEnC;;;OAGG;IACH,YAAY,SAAyB,EAAE,OAAgB;QACrD,KAAK,CAAC,OAAO,IAAI,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAXD,sDAWC"}

package/dist/domain/exceptions/missing-tenant-context.exception.d.ts

@@ -0,0 +1,24 @@
+import { DomainException } from './domain.exception';
+/**
+ * Framework-neutral signal that an operation requiring tenant isolation was
+ * attempted without a resolvable tenant identity.
+ *
+ * Tenant-scoped operations fail closed here. A missing tenant must never be
+ * collapsed into a shared or default tenant: every caller whose tenant could not
+ * be resolved would then read and write the same cache entries or database,
+ * which is a cross-tenant data leak that produces no error and no log line.
+ *
+ * Deployments that are genuinely single-tenant make that explicit rather than
+ * implicit: pass a fixed tenant id to the key helper, or register
+ * `setTenantResolver(() => 'single')`, so the decision is visible in code.
+ *
+ * @example
+ * ```ts
+ * if (!tenantId) throw new MissingTenantContextError('users.create idempotency key');
+ * ```
+ */
+export declare class MissingTenantContextError extends DomainException {
+    readonly operation: string;
+    constructor(operation: string);
+}
+//# sourceMappingURL=missing-tenant-context.exception.d.ts.map

package/dist/domain/exceptions/missing-tenant-context.exception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-tenant-context.exception.d.ts","sourceRoot":"","sources":["../../../domain/exceptions/missing-tenant-context.exception.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,yBAA0B,SAAQ,eAAe;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAMvC"}

package/dist/domain/exceptions/missing-tenant-context.exception.js

@@ -0,0 +1,33 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingTenantContextError = void 0;
+const domain_exception_1 = require("./domain.exception");
+/**
+ * Framework-neutral signal that an operation requiring tenant isolation was
+ * attempted without a resolvable tenant identity.
+ *
+ * Tenant-scoped operations fail closed here. A missing tenant must never be
+ * collapsed into a shared or default tenant: every caller whose tenant could not
+ * be resolved would then read and write the same cache entries or database,
+ * which is a cross-tenant data leak that produces no error and no log line.
+ *
+ * Deployments that are genuinely single-tenant make that explicit rather than
+ * implicit: pass a fixed tenant id to the key helper, or register
+ * `setTenantResolver(() => 'single')`, so the decision is visible in code.
+ *
+ * @example
+ * ```ts
+ * if (!tenantId) throw new MissingTenantContextError('users.create idempotency key');
+ * ```
+ */
+class MissingTenantContextError extends domain_exception_1.DomainException {
+    operation;
+    constructor(operation) {
+        super(`Missing tenant context for ${operation}. Run it inside a tenant scope or pass ` +
+            'the tenant explicitly; it never falls back to a shared or default tenant.');
+        this.operation = operation;
+    }
+}
+exports.MissingTenantContextError = MissingTenantContextError;
+//# sourceMappingURL=missing-tenant-context.exception.js.map

package/dist/domain/exceptions/missing-tenant-context.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-tenant-context.exception.js","sourceRoot":"","sources":["../../../domain/exceptions/missing-tenant-context.exception.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE,yDAAqD;AAErD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,yBAA0B,SAAQ,kCAAe;IACvC;IAArB,YAAqB,SAAiB;QACpC,KAAK,CACH,8BAA8B,SAAS,yCAAyC;YAC9E,2EAA2E,CAC9E,CAAC;QAJiB,cAAS,GAAT,SAAS,CAAQ;IAKtC,CAAC;CACF;AAPD,8DAOC"}

package/dist/domain/exceptions/transient-operation.error.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Framework- and infrastructure-neutral signal that an application operation
+ * failed for a reason the configured resilience policy may retry.
+ *
+ * Infrastructure adapters are responsible for translating their own transient
+ * failures into this error. Application handlers do not inspect database,
+ * driver, network, or transport-specific error codes.
+ */
+export declare class TransientOperationError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** True when `error` is a TransientOperationError. */
+export declare function isTransientOperationError(error: unknown): error is TransientOperationError;
+//# sourceMappingURL=transient-operation.error.d.ts.map

package/dist/domain/exceptions/transient-operation.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient-operation.error.d.ts","sourceRoot":"","sources":["../../../domain/exceptions/transient-operation.error.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAK3D;AAED,sDAAsD;AACtD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,uBAAuB,CAElC"}

package/dist/domain/exceptions/transient-operation.error.js

@@ -0,0 +1,27 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransientOperationError = void 0;
+exports.isTransientOperationError = isTransientOperationError;
+/**
+ * Framework- and infrastructure-neutral signal that an application operation
+ * failed for a reason the configured resilience policy may retry.
+ *
+ * Infrastructure adapters are responsible for translating their own transient
+ * failures into this error. Application handlers do not inspect database,
+ * driver, network, or transport-specific error codes.
+ */
+class TransientOperationError extends Error {
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = TransientOperationError.name;
+        this.cause = options?.cause;
+    }
+}
+exports.TransientOperationError = TransientOperationError;
+/** True when `error` is a TransientOperationError. */
+function isTransientOperationError(error) {
+    return error instanceof TransientOperationError;
+}
+//# sourceMappingURL=transient-operation.error.js.map

package/dist/domain/exceptions/transient-operation.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient-operation.error.js","sourceRoot":"","sources":["../../../domain/exceptions/transient-operation.error.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAqBtE,8DAIC;AAvBD;;;;;;;GAOG;AACH,MAAa,uBAAwB,SAAQ,KAAK;IACvC,KAAK,CAAW;IAEzB,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC,IAAI,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;IAC9B,CAAC;CACF;AARD,0DAQC;AAED,sDAAsD;AACtD,SAAgB,yBAAyB,CACvC,KAAc;IAEd,OAAO,KAAK,YAAY,uBAAuB,CAAC;AAClD,CAAC"}

package/dist/domain/exceptions/unknown-mutable-field.error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Raised when `applyPatch()` receives a patch key that the aggregate has
+ * not declared with `@Mutable()`.
+ *
+ * This is a wiring defect, not a domain rule violation: the mutation names a
+ * field the aggregate does not expose for mutation, so nothing is written, no
+ * version is advanced and no event is recorded.
+ */
+export declare class UnknownMutableFieldError extends Error {
+    readonly aggregate: string;
+    readonly field: string;
+    constructor(aggregate: string, field: string, known: readonly string[]);
+}
+//# sourceMappingURL=unknown-mutable-field.error.d.ts.map

package/dist/domain/exceptions/unknown-mutable-field.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-mutable-field.error.d.ts","sourceRoot":"","sources":["../../../domain/exceptions/unknown-mutable-field.error.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE;CAUvE"}

package/dist/domain/exceptions/unknown-mutable-field.error.js

@@ -0,0 +1,24 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownMutableFieldError = void 0;
+/**
+ * Raised when `applyPatch()` receives a patch key that the aggregate has
+ * not declared with `@Mutable()`.
+ *
+ * This is a wiring defect, not a domain rule violation: the mutation names a
+ * field the aggregate does not expose for mutation, so nothing is written, no
+ * version is advanced and no event is recorded.
+ */
+class UnknownMutableFieldError extends Error {
+    aggregate;
+    field;
+    constructor(aggregate, field, known) {
+        super(`${aggregate} does not declare '${field}' as a mutable field. Declare it with @Mutable() or remove it from the mutation patch. Known mutable fields: ${known.length > 0 ? known.join(', ') : '(none)'}.`);
+        this.name = UnknownMutableFieldError.name;
+        this.aggregate = aggregate;
+        this.field = field;
+    }
+}
+exports.UnknownMutableFieldError = UnknownMutableFieldError;
+//# sourceMappingURL=unknown-mutable-field.error.js.map

package/dist/domain/exceptions/unknown-mutable-field.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-mutable-field.error.js","sourceRoot":"","sources":["../../../domain/exceptions/unknown-mutable-field.error.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE;;;;;;;GAOG;AACH,MAAa,wBAAyB,SAAQ,KAAK;IACxC,SAAS,CAAS;IAClB,KAAK,CAAS;IAEvB,YAAY,SAAiB,EAAE,KAAa,EAAE,KAAwB;QACpE,KAAK,CACH,GAAG,SAAS,sBAAsB,KAAK,gHACrC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QACxC,GAAG,CACJ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC,IAAI,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAdD,4DAcC"}

package/dist/domain/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Domain primitives. Free of ORM and persistence dependencies.
+ *
+ * Import from here — `@cqrs-ddd/core/domain` — in domain code, so a
+ * file that only needs `DomainException` does not pull the persistence layer in
+ * behind it.
+ */
+export * from './decorators/apply-mutation.decorator';
+export * from './decorators/mutable.decorator';
+export * from './events/domain.event';
+export * from './events/event.interface';
+export * from './events/root-domain.event';
+export * from './exceptions/concurrency-conflict.error';
+export * from './exceptions/domain.exception';
+export * from './exceptions/entity-not-found.exception';
+export * from './exceptions/invalid-value.exception';
+export * from './exceptions/missing-tenant-context.exception';
+export * from './exceptions/transient-operation.error';
+export * from './exceptions/unknown-mutable-field.error';
+export * from './interfaces/root-entity-snapshot.interface';
+export * from './models/aggregate-root';
+export * from './models/root.entity';
+export * from './rules/number.rule';
+export * from './rules/text.rule';
+export * from './rules/value-violation';
+//# sourceMappingURL=index.d.ts.map

package/dist/domain/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../domain/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,cAAc,uCAAuC,CAAC;AACtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yCAAyC,CAAC;AACxD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,sCAAsC,CAAC;AACrD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC"}

package/dist/domain/index.js

@@ -0,0 +1,43 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+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 });
+/**
+ * Domain primitives. Free of ORM and persistence dependencies.
+ *
+ * Import from here — `@cqrs-ddd/core/domain` — in domain code, so a
+ * file that only needs `DomainException` does not pull the persistence layer in
+ * behind it.
+ */
+__exportStar(require("./decorators/apply-mutation.decorator"), exports);
+__exportStar(require("./decorators/mutable.decorator"), exports);
+__exportStar(require("./events/domain.event"), exports);
+__exportStar(require("./events/event.interface"), exports);
+__exportStar(require("./events/root-domain.event"), exports);
+__exportStar(require("./exceptions/concurrency-conflict.error"), exports);
+__exportStar(require("./exceptions/domain.exception"), exports);
+__exportStar(require("./exceptions/entity-not-found.exception"), exports);
+__exportStar(require("./exceptions/invalid-value.exception"), exports);
+__exportStar(require("./exceptions/missing-tenant-context.exception"), exports);
+__exportStar(require("./exceptions/transient-operation.error"), exports);
+__exportStar(require("./exceptions/unknown-mutable-field.error"), exports);
+__exportStar(require("./interfaces/root-entity-snapshot.interface"), exports);
+__exportStar(require("./models/aggregate-root"), exports);
+__exportStar(require("./models/root.entity"), exports);
+__exportStar(require("./rules/number.rule"), exports);
+__exportStar(require("./rules/text.rule"), exports);
+__exportStar(require("./rules/value-violation"), exports);
+//# sourceMappingURL=index.js.map

package/dist/domain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../domain/index.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;;;;;;;;;;;;;;AAEtE;;;;;;GAMG;AAEH,wEAAsD;AACtD,iEAA+C;AAC/C,wDAAsC;AACtC,2DAAyC;AACzC,6DAA2C;AAC3C,0EAAwD;AACxD,gEAA8C;AAC9C,0EAAwD;AACxD,uEAAqD;AACrD,gFAA8D;AAC9D,yEAAuD;AACvD,2EAAyD;AACzD,8EAA4D;AAC5D,0DAAwC;AACxC,uDAAqC;AACrC,sDAAoC;AACpC,oDAAkC;AAClC,0DAAwC"}

package/dist/domain/interfaces/root-entity-snapshot.interface.d.ts

@@ -0,0 +1,7 @@
+export interface RootEntitySnapshot {
+    readonly id: string;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    readonly version?: number;
+}
+//# sourceMappingURL=root-entity-snapshot.interface.d.ts.map

package/dist/domain/interfaces/root-entity-snapshot.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-entity-snapshot.interface.d.ts","sourceRoot":"","sources":["../../../domain/interfaces/root-entity-snapshot.interface.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/domain/interfaces/root-entity-snapshot.interface.js

@@ -0,0 +1,4 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=root-entity-snapshot.interface.js.map

package/dist/domain/interfaces/root-entity-snapshot.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-entity-snapshot.interface.js","sourceRoot":"","sources":["../../../domain/interfaces/root-entity-snapshot.interface.ts"],"names":[],"mappings":";AAAA,sEAAsE"}

package/dist/domain/models/aggregate-root.d.ts

@@ -0,0 +1,87 @@
+import { IEvent } from '../events/event.interface';
+declare const INTERNAL_EVENTS: unique symbol;
+declare const IS_AUTO_COMMIT_ENABLED: unique symbol;
+/**
+ * Options for applying an event to an aggregate root.
+ */
+export interface ApplyEventOptions {
+    /**
+     * Whether the event originates from historical rehydration.
+     * If true, the event will not be buffered into uncommitted events.
+     */
+    readonly fromHistory?: boolean;
+    /**
+     * Whether to skip calling the corresponding `on<EventName>` handler.
+     */
+    readonly skipHandler?: boolean;
+}
+/**
+ * Abstract base class representing a Domain-Driven Design (DDD) aggregate root.
+ *
+ * Provides a framework-neutral event buffering lifecycle:
+ * - Records uncommitted domain events via {@link apply}.
+ * - Dispatches events to optional `on<EventName>` instance handlers for internal state updates.
+ * - Supports state rehydration via {@link loadFromHistory}.
+ * - Exposes buffered events via {@link getUncommittedEvents} for out-of-band application dispatch.
+ * - Clears buffered events via {@link uncommit} once reliably persisted or published.
+ *
+ * @template EventBase The base event type, defaults to {@link IEvent}.
+ */
+export declare abstract class AggregateRoot<EventBase extends IEvent = IEvent> {
+    private [IS_AUTO_COMMIT_ENABLED];
+    private readonly [INTERNAL_EVENTS];
+    /**
+     * Sets whether the aggregate root should automatically commit and publish events upon application.
+     */
+    set autoCommit(value: boolean);
+    /**
+     * Gets whether the aggregate root automatically commits and publishes events upon application.
+     */
+    get autoCommit(): boolean;
+    /**
+     * Called by apply() for each event while autoCommit is enabled; a no-op unless overridden.
+     */
+    publish<T extends EventBase = EventBase>(_event: T): void;
+    /**
+     * Called by commit() with a copy of the buffered events; a no-op unless overridden.
+     */
+    publishAll<T extends EventBase = EventBase>(_events: T[]): void;
+    /**
+     * Commits all uncommitted events by publishing them via {@link publishAll} and clearing the buffer.
+     */
+    commit(): void;
+    /**
+     * Clears all uncommitted events without publishing.
+     */
+    uncommit(): void;
+    /**
+     * Returns all uncommitted events currently buffered on this aggregate.
+     */
+    getUncommittedEvents(): EventBase[];
+    /**
+     * Loads domain events from history to rehydrate the aggregate's internal state.
+     * Historical events invoke event handlers without being re-buffered.
+     */
+    loadFromHistory(history: EventBase[]): void;
+    /**
+     * Applies an event to the aggregate root.
+     *
+     * If `fromHistory` is false and `autoCommit` is disabled, the event is appended to
+     * the uncommitted events buffer. If `autoCommit` is enabled, the event is published
+     * immediately. Unless `skipHandler` is true, routes to `on<EventName>(event)` if present.
+     *
+     * @param event The domain event to apply.
+     * @param optionsOrIsFromHistory Boolean indicating historical event or options object.
+     */
+    apply<T extends EventBase = EventBase>(event: T, optionsOrIsFromHistory?: boolean | ApplyEventOptions): void;
+    /**
+     * Resolves the method handler corresponding to the applied event name (`on<EventName>`).
+     */
+    protected getEventHandler<T extends EventBase = EventBase>(event: T): ((event: T) => void) | undefined;
+    /**
+     * Resolves the constructor name of the event.
+     */
+    protected getEventName(event: unknown): string;
+}
+export {};
+//# sourceMappingURL=aggregate-root.d.ts.map

package/dist/domain/models/aggregate-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-root.d.ts","sourceRoot":"","sources":["../../../domain/models/aggregate-root.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAEnD,QAAA,MAAM,eAAe,eAA4B,CAAC;AAClD,QAAA,MAAM,sBAAsB,eAAmC,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;GAWG;AACH,8BAAsB,aAAa,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IACnE,OAAO,CAAC,CAAC,sBAAsB,CAAC,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,CAAmB;IAErD;;OAEG;IACH,IAAI,UAAU,CAAC,KAAK,EAAE,OAAO,EAE5B;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;IACH,OAAO,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI;IAEzD;;OAEG;IACH,UAAU,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI;IAE/D;;OAEG;IACH,MAAM,IAAI,IAAI;IAKd;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACH,oBAAoB,IAAI,SAAS,EAAE;IAInC;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI;IAM3C;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EACnC,KAAK,EAAE,CAAC,EACR,sBAAsB,GAAE,OAAO,GAAG,iBAAsB,GACvD,IAAI;IA2BP;;OAEG;IACH,SAAS,CAAC,eAAe,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EACvD,KAAK,EAAE,CAAC,GACP,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS;IAQnC;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;CAI/C"}

package/dist/domain/models/aggregate-root.js

@@ -0,0 +1,122 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license.
+ * Derived from and compatible with NestJS CQRS AggregateRoot (MIT License).
+ * Copyright (c) 2017-2026 Kamil Mysliwiec (https://kamilmysliwiec.com)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AggregateRoot = void 0;
+const INTERNAL_EVENTS = Symbol('INTERNAL_EVENTS');
+const IS_AUTO_COMMIT_ENABLED = Symbol('IS_AUTO_COMMIT_ENABLED');
+/**
+ * Abstract base class representing a Domain-Driven Design (DDD) aggregate root.
+ *
+ * Provides a framework-neutral event buffering lifecycle:
+ * - Records uncommitted domain events via {@link apply}.
+ * - Dispatches events to optional `on<EventName>` instance handlers for internal state updates.
+ * - Supports state rehydration via {@link loadFromHistory}.
+ * - Exposes buffered events via {@link getUncommittedEvents} for out-of-band application dispatch.
+ * - Clears buffered events via {@link uncommit} once reliably persisted or published.
+ *
+ * @template EventBase The base event type, defaults to {@link IEvent}.
+ */
+class AggregateRoot {
+    [IS_AUTO_COMMIT_ENABLED] = false;
+    [INTERNAL_EVENTS] = [];
+    /**
+     * Sets whether the aggregate root should automatically commit and publish events upon application.
+     */
+    set autoCommit(value) {
+        this[IS_AUTO_COMMIT_ENABLED] = value;
+    }
+    /**
+     * Gets whether the aggregate root automatically commits and publishes events upon application.
+     */
+    get autoCommit() {
+        return this[IS_AUTO_COMMIT_ENABLED];
+    }
+    /**
+     * Called by apply() for each event while autoCommit is enabled; a no-op unless overridden.
+     */
+    publish(_event) { }
+    /**
+     * Called by commit() with a copy of the buffered events; a no-op unless overridden.
+     */
+    publishAll(_events) { }
+    /**
+     * Commits all uncommitted events by publishing them via {@link publishAll} and clearing the buffer.
+     */
+    commit() {
+        this.publishAll([...this[INTERNAL_EVENTS]]);
+        this[INTERNAL_EVENTS].length = 0;
+    }
+    /**
+     * Clears all uncommitted events without publishing.
+     */
+    uncommit() {
+        this[INTERNAL_EVENTS].length = 0;
+    }
+    /**
+     * Returns all uncommitted events currently buffered on this aggregate.
+     */
+    getUncommittedEvents() {
+        return this[INTERNAL_EVENTS];
+    }
+    /**
+     * Loads domain events from history to rehydrate the aggregate's internal state.
+     * Historical events invoke event handlers without being re-buffered.
+     */
+    loadFromHistory(history) {
+        for (const event of history) {
+            this.apply(event, true);
+        }
+    }
+    /**
+     * Applies an event to the aggregate root.
+     *
+     * If `fromHistory` is false and `autoCommit` is disabled, the event is appended to
+     * the uncommitted events buffer. If `autoCommit` is enabled, the event is published
+     * immediately. Unless `skipHandler` is true, routes to `on<EventName>(event)` if present.
+     *
+     * @param event The domain event to apply.
+     * @param optionsOrIsFromHistory Boolean indicating historical event or options object.
+     */
+    apply(event, optionsOrIsFromHistory = {}) {
+        const isFromHistory = (typeof optionsOrIsFromHistory === 'boolean'
+            ? optionsOrIsFromHistory
+            : optionsOrIsFromHistory.fromHistory) ?? false;
+        const skipHandler = (typeof optionsOrIsFromHistory === 'boolean'
+            ? false
+            : optionsOrIsFromHistory.skipHandler) ?? false;
+        if (!isFromHistory && !this.autoCommit) {
+            this[INTERNAL_EVENTS].push(event);
+        }
+        if (this.autoCommit) {
+            this.publish(event);
+        }
+        if (!skipHandler) {
+            const handler = this.getEventHandler(event);
+            if (handler) {
+                handler.call(this, event);
+            }
+        }
+    }
+    /**
+     * Resolves the method handler corresponding to the applied event name (`on<EventName>`).
+     */
+    getEventHandler(event) {
+        const handler = `on${this.getEventName(event)}`;
+        const method = this[handler];
+        return typeof method === 'function'
+            ? method
+            : undefined;
+    }
+    /**
+     * Resolves the constructor name of the event.
+     */
+    getEventName(event) {
+        const proto = Object.getPrototypeOf(event);
+        return proto?.constructor?.name ?? 'Event';
+    }
+}
+exports.AggregateRoot = AggregateRoot;
+//# sourceMappingURL=aggregate-root.js.map

package/dist/domain/models/aggregate-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-root.js","sourceRoot":"","sources":["../../../domain/models/aggregate-root.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAIH,MAAM,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAClD,MAAM,sBAAsB,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAkBhE;;;;;;;;;;;GAWG;AACH,MAAsB,aAAa;IACzB,CAAC,sBAAsB,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC,eAAe,CAAC,GAAgB,EAAE,CAAC;IAErD;;OAEG;IACH,IAAI,UAAU,CAAC,KAAc;QAC3B,IAAI,CAAC,sBAAsB,CAAC,GAAG,KAAK,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,OAAO,CAAkC,MAAS,IAAS,CAAC;IAE5D;;OAEG;IACH,UAAU,CAAkC,OAAY,IAAS,CAAC;IAElE;;OAEG;IACH,MAAM;QACJ,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QAC5C,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,oBAAoB;QAClB,OAAO,IAAI,CAAC,eAAe,CAAC,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,OAAoB;QAClC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CACH,KAAQ,EACR,yBAAsD,EAAE;QAExD,MAAM,aAAa,GACjB,CAAC,OAAO,sBAAsB,KAAK,SAAS;YAC1C,CAAC,CAAC,sBAAsB;YACxB,CAAC,CAAC,sBAAsB,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;QAEnD,MAAM,WAAW,GACf,CAAC,OAAO,sBAAsB,KAAK,SAAS;YAC1C,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,sBAAsB,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;QAEnD,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;YAC5C,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACO,eAAe,CACvB,KAAQ;QAER,MAAM,OAAO,GAAG,KAAK,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,MAAM,GAAI,IAAgC,CAAC,OAAO,CAAC,CAAC;QAC1D,OAAO,OAAO,MAAM,KAAK,UAAU;YACjC,CAAC,CAAE,MAA6B;YAChC,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAED;;OAEG;IACO,YAAY,CAAC,KAAc;QACnC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,IAAI,OAAO,CAAC;IAC7C,CAAC;CACF;AAxHD,sCAwHC"}