@cqrs-ddd/core 0.2.0

package/dist/application/ports/command-repository.port.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Contract for write-side command repositories.
+ *
+ * Persists an entity or aggregate state into persistence storage.
+ *
+ * @typeParam TEntity - The aggregate entity or payload being persisted.
+ * @typeParam TResult - The result type returned after persistence (or null on deletion).
+ *
+ * @example
+ * ```ts
+ * constructor(
+ *   @Inject(COMMAND_REPOSITORY.createUser)
+ *   private readonly users: ICommandRepository<User, UserSnapshot>,
+ * ) {}
+ *
+ * await this.users.save(user);
+ * ```
+ */
+export interface ICommandRepository<TEntity = unknown, TResult = unknown> {
+    /**
+     * Persists the aggregate/payload.
+     *
+     * Returning `null` is the conventional deletion result used by the DDD cache
+     * decorator to trigger eviction/barrier behavior.
+     */
+    save(entity: TEntity): Promise<TResult | null>;
+}
+//# sourceMappingURL=command-repository.port.d.ts.map

package/dist/application/ports/command-repository.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-repository.port.d.ts","sourceRoot":"","sources":["../../../application/ports/command-repository.port.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACtE;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAChD"}

package/dist/application/ports/command-repository.port.js

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

package/dist/application/ports/command-repository.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-repository.port.js","sourceRoot":"","sources":["../../../application/ports/command-repository.port.ts"],"names":[],"mappings":";AAAA,sEAAsE"}

package/dist/application/ports/domain-event-publisher.port.d.ts

@@ -0,0 +1,18 @@
+import type { IEvent } from '../../domain/events/event.interface';
+/**
+ * Publishes the buffered domain events of an aggregate after a command succeeds.
+ *
+ * Any bus with a `publishAll(events)` method fits, including the NestJS CQRS
+ * `EventBus`, so a Nest handler passes its injected `EventBus` unchanged.
+ *
+ * @example
+ * ```ts
+ * const publisher: IDomainEventPublisher = {
+ *   publishAll: (events) => events.forEach((event) => emitter.emit('event', event)),
+ * };
+ * ```
+ */
+export interface IDomainEventPublisher {
+    publishAll(events: IEvent[]): unknown;
+}
+//# sourceMappingURL=domain-event-publisher.port.d.ts.map

package/dist/application/ports/domain-event-publisher.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-event-publisher.port.d.ts","sourceRoot":"","sources":["../../../application/ports/domain-event-publisher.port.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;CACvC"}

package/dist/application/ports/domain-event-publisher.port.js

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

package/dist/application/ports/domain-event-publisher.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-event-publisher.port.js","sourceRoot":"","sources":["../../../application/ports/domain-event-publisher.port.ts"],"names":[],"mappings":";AAAA,sEAAsE"}

package/dist/application/ports/query-repository.port.d.ts

@@ -0,0 +1,26 @@
+import { IQueryOptions } from '../query.options';
+/**
+ * Application-facing read repository contract.
+ *
+ * Query handlers depend on this interface rather than ORM/query-builder
+ * implementations. Repository adapters may use {@link FromCache} internally,
+ * but callers receive only the declared `TResult`.
+ *
+ * @typeParam TQuery - Query object accepted by {@link find}.
+ * @typeParam TResult - Domain/read result returned to the application layer.
+ *
+ * @example
+ * ```ts
+ * constructor(
+ *   @Inject(QUERY_REPOSITORY.getUser)
+ *   private readonly users: IQueryRepository<GetUserQuery, User | null>,
+ * ) {}
+ *
+ * const user = await this.users.find(query);
+ * ```
+ */
+export interface IQueryRepository<TQuery = IQueryOptions, TResult = unknown> {
+    /** Resolves one application query. */
+    find(query: TQuery): Promise<TResult>;
+}
+//# sourceMappingURL=query-repository.port.d.ts.map

package/dist/application/ports/query-repository.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-repository.port.d.ts","sourceRoot":"","sources":["../../../application/ports/query-repository.port.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB,CAAC,MAAM,GAAG,aAAa,EAAE,OAAO,GAAG,OAAO;IACzE,sCAAsC;IACtC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvC"}

package/dist/application/ports/query-repository.port.js

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

package/dist/application/ports/query-repository.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-repository.port.js","sourceRoot":"","sources":["../../../application/ports/query-repository.port.ts"],"names":[],"mappings":";AAAA,sEAAsE"}

package/dist/application/ports/write-side-aggregate-repository.port.d.ts

@@ -0,0 +1,33 @@
+import type { ICommandRepository } from './command-repository.port';
+/**
+ * Write-side repository contract for commands that mutate an existing aggregate.
+ *
+ * `findById()` must read authoritative persistence and must not use a read-side
+ * result cache. Adapters backed by an ORM identity map should force a refresh so
+ * optimistic-concurrency checks are based on current persisted state.
+ *
+ * Use this contract in update/delete command handlers that must authorize and
+ * mutate the real aggregate before saving it.
+ *
+ * @typeParam TEntity - Rehydrated aggregate type.
+ * @typeParam TId - Aggregate identifier type.
+ *
+ * @example
+ * ```ts
+ * const user = await repository.findById(command.id);
+ * if (!user) throw new EntityNotFoundException('User', command.id);
+ * authorizer.authorize('update', user);
+ * user.update({ department: command.department });
+ * await repository.save(user);
+ * ```
+ */
+export interface IWriteSideAggregateRepository<TEntity, TId = string> extends ICommandRepository<TEntity, unknown> {
+    /**
+     * Loads the current authoritative aggregate for a mutating command.
+     *
+     * @param id - Aggregate identifier.
+     * @returns The rehydrated aggregate, or `null` when it does not exist.
+     */
+    findById(id: TId): Promise<TEntity | null>;
+}
+//# sourceMappingURL=write-side-aggregate-repository.port.d.ts.map

package/dist/application/ports/write-side-aggregate-repository.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-side-aggregate-repository.port.d.ts","sourceRoot":"","sources":["../../../application/ports/write-side-aggregate-repository.port.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,6BAA6B,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM,CAClE,SAAQ,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC5C"}

package/dist/application/ports/write-side-aggregate-repository.port.js

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

package/dist/application/ports/write-side-aggregate-repository.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-side-aggregate-repository.port.js","sourceRoot":"","sources":["../../../application/ports/write-side-aggregate-repository.port.ts"],"names":[],"mappings":";AAAA,sEAAsE"}

package/dist/application/query.options.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Metadata understood by DDD query repositories and read-through cache helpers.
+ *
+ * Query implementations normally inherit this through {@link BaseQuery}.
+ */
+export interface IQueryOptions {
+    /**
+     * Query metadata for repositories that read it. {@link FromCache} does not:
+     * it rehydrates every hit whenever a hydrator applies.
+     *
+     * @default false
+     */
+    hydrate?: boolean;
+    /**
+     * Bypass read-through cache lookup and fill, forcing an authoritative read
+     * directly from underlying persistence.
+     *
+     * @default false
+     */
+    refresh?: boolean;
+}
+//# sourceMappingURL=query.options.d.ts.map

package/dist/application/query.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.options.d.ts","sourceRoot":"","sources":["../../application/query.options.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/application/query.options.js

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

package/dist/application/query.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.options.js","sourceRoot":"","sources":["../../application/query.options.ts"],"names":[],"mappings":";AAAA,sEAAsE"}

package/dist/application/request-fields.helper.d.ts

@@ -0,0 +1,5 @@
+/** Defines a non-enumerable property, excluded from `toJSON()` and payload spreads. */
+export declare function defineHidden(target: object, key: string, value: unknown): void;
+/** Returns the enumerable own fields of a request whose value is not `undefined`. */
+export declare function definedFields(request: object): Record<string, unknown>;
+//# sourceMappingURL=request-fields.helper.d.ts.map

package/dist/application/request-fields.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-fields.helper.d.ts","sourceRoot":"","sources":["../../application/request-fields.helper.ts"],"names":[],"mappings":"AAEA,uFAAuF;AACvF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACb,IAAI,CAEN;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQtE"}

package/dist/application/request-fields.helper.js

@@ -0,0 +1,20 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineHidden = defineHidden;
+exports.definedFields = definedFields;
+/** Defines a non-enumerable property, excluded from `toJSON()` and payload spreads. */
+function defineHidden(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: false });
+}
+/** Returns the enumerable own fields of a request whose value is not `undefined`. */
+function definedFields(request) {
+    const json = {};
+    for (const [key, value] of Object.entries(request)) {
+        if (value !== undefined) {
+            json[key] = value;
+        }
+    }
+    return json;
+}
+//# sourceMappingURL=request-fields.helper.js.map

package/dist/application/request-fields.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-fields.helper.js","sourceRoot":"","sources":["../../application/request-fields.helper.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AAGtE,oCAMC;AAGD,sCAQC;AAlBD,uFAAuF;AACvF,SAAgB,YAAY,CAC1B,MAAc,EACd,GAAW,EACX,KAAc;IAEd,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,qFAAqF;AACrF,SAAgB,aAAa,CAAC,OAAe;IAC3C,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/application/tenant-resolver.d.ts

@@ -0,0 +1,56 @@
+/**
+ * An explicit tenant: a tenant id string, or an object carrying `tenantId`, such
+ * as a request or job context.
+ */
+export type TenantSource = string | {
+    readonly tenantId?: string | undefined;
+};
+/**
+ * Returns the tenant of the running unit of work, or `undefined` when there is
+ * none.
+ */
+export type TenantResolver = () => string | undefined;
+/**
+ * Registers where tenant-scoped helpers such as `cacheKey` and
+ * `cacheKeyTemplate` find the tenant when none is passed to them, typically the
+ * request or job context the application already keeps.
+ *
+ * Register it once at startup; a later call replaces it, and `undefined` removes
+ * it. When the resolver returns nothing, or none is registered, those helpers
+ * fail closed with {@link MissingTenantContextError}.
+ *
+ * @param resolver - Returns the current tenant, or `undefined` for none.
+ *
+ * @example
+ * ```ts
+ * const requestTenant = new AsyncLocalStorage<string>();
+ * setTenantResolver(() => requestTenant.getStore());
+ *
+ * // Per request or job:
+ * requestTenant.run(tenantId, () => handle(request));
+ * ```
+ */
+export declare function setTenantResolver(resolver: TenantResolver | undefined): void;
+/**
+ * Returns the tenant for a security-sensitive operation, or fails closed.
+ *
+ * An explicit string always wins, even an empty one. An object uses its
+ * `tenantId`; without one, or when `source` is omitted, the tenant of the
+ * registered {@link setTenantResolver} resolver applies. Nothing resolved, or an
+ * empty tenant, throws {@link MissingTenantContextError}: keys for caches,
+ * idempotency and rate limits must never collapse several tenants into one
+ * shared namespace.
+ *
+ * @param source - The explicit tenant, or `undefined` to use the resolver.
+ * @param purpose - What the tenant is for, named in the error.
+ * @returns The non-empty tenant id.
+ * @throws {MissingTenantContextError} When no tenant can be resolved.
+ *
+ * @example
+ * ```ts
+ * // A key factory that receives a request or job context:
+ * const tenantId = requireTenantId(ctx, 'users.create idempotency key');
+ * ```
+ */
+export declare function requireTenantId(source: TenantSource | undefined, purpose: string): string;
+//# sourceMappingURL=tenant-resolver.d.ts.map

package/dist/application/tenant-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-resolver.d.ts","sourceRoot":"","sources":["../../application/tenant-resolver.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAItD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAE5E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,OAAO,EAAE,MAAM,GACd,MAAM,CAOR"}

package/dist/application/tenant-resolver.js

@@ -0,0 +1,60 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setTenantResolver = setTenantResolver;
+exports.requireTenantId = requireTenantId;
+const missing_tenant_context_exception_1 = require("../domain/exceptions/missing-tenant-context.exception");
+let tenantResolver;
+/**
+ * Registers where tenant-scoped helpers such as `cacheKey` and
+ * `cacheKeyTemplate` find the tenant when none is passed to them, typically the
+ * request or job context the application already keeps.
+ *
+ * Register it once at startup; a later call replaces it, and `undefined` removes
+ * it. When the resolver returns nothing, or none is registered, those helpers
+ * fail closed with {@link MissingTenantContextError}.
+ *
+ * @param resolver - Returns the current tenant, or `undefined` for none.
+ *
+ * @example
+ * ```ts
+ * const requestTenant = new AsyncLocalStorage<string>();
+ * setTenantResolver(() => requestTenant.getStore());
+ *
+ * // Per request or job:
+ * requestTenant.run(tenantId, () => handle(request));
+ * ```
+ */
+function setTenantResolver(resolver) {
+    tenantResolver = resolver;
+}
+/**
+ * Returns the tenant for a security-sensitive operation, or fails closed.
+ *
+ * An explicit string always wins, even an empty one. An object uses its
+ * `tenantId`; without one, or when `source` is omitted, the tenant of the
+ * registered {@link setTenantResolver} resolver applies. Nothing resolved, or an
+ * empty tenant, throws {@link MissingTenantContextError}: keys for caches,
+ * idempotency and rate limits must never collapse several tenants into one
+ * shared namespace.
+ *
+ * @param source - The explicit tenant, or `undefined` to use the resolver.
+ * @param purpose - What the tenant is for, named in the error.
+ * @returns The non-empty tenant id.
+ * @throws {MissingTenantContextError} When no tenant can be resolved.
+ *
+ * @example
+ * ```ts
+ * // A key factory that receives a request or job context:
+ * const tenantId = requireTenantId(ctx, 'users.create idempotency key');
+ * ```
+ */
+function requireTenantId(source, purpose) {
+    const tenantId = typeof source === 'string'
+        ? source
+        : (source?.tenantId ?? tenantResolver?.());
+    if (!tenantId)
+        throw new missing_tenant_context_exception_1.MissingTenantContextError(purpose);
+    return tenantId;
+}
+//# sourceMappingURL=tenant-resolver.js.map

package/dist/application/tenant-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-resolver.js","sourceRoot":"","sources":["../../application/tenant-resolver.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AAsCtE,8CAEC;AAuBD,0CAUC;AAvED,4GAAkG;AAclG,IAAI,cAA0C,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,iBAAiB,CAAC,QAAoC;IACpE,cAAc,GAAG,QAAQ,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,eAAe,CAC7B,MAAgC,EAChC,OAAe;IAEf,MAAM,QAAQ,GACZ,OAAO,MAAM,KAAK,QAAQ;QACxB,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,IAAI,cAAc,EAAE,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,4DAAyB,CAAC,OAAO,CAAC,CAAC;IAC5D,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/domain/decorators/apply-mutation.decorator.d.ts

@@ -0,0 +1,64 @@
+import { IEvent } from '../events/event.interface';
+/**
+ * The state change a domain method describes: mutable field keys mapped to
+ * their new values for `RootEntity.applyPatch()`. Undefined values are ignored.
+ * An absent patch leaves fields unchanged.
+ *
+ * @typeParam TEntity - The aggregate the patch applies to.
+ */
+export type MutationPatch<TEntity> = Partial<TEntity> | void;
+/** A non-empty array of domain events. */
+export type NonEmptyEventArray = readonly [IEvent, ...IEvent[]] | [IEvent, ...IEvent[]];
+export type SingleEvent = IEvent & {
+    length?: never;
+};
+/**
+ * Configuration for a declarative aggregate mutation and domain event application.
+ *
+ * @typeParam TEntity - The aggregate the decorated method belongs to.
+ */
+export interface ApplyMutationOptions<TEntity> {
+    /**
+     * Factory for the domain event(s) recorded once the mutation has completed.
+     * It receives the aggregate **after** the patch, `onUpdate()` and the
+     * version/timestamp advance, ensuring event payload and metadata snapshot
+     * the post-mutation version and `updatedAt`.
+     *
+     * Must return a single domain event object or a non-empty array of domain events.
+     */
+    readonly event: (entity: TEntity) => SingleEvent | NonEmptyEventArray;
+}
+/**
+ * Completes a successful domain mutation by advancing `onUpdate()` once and
+ * recording events from the resulting state. Preserves the method's return value,
+ * including an entity returned by an asynchronous method.
+ *
+ * Domain methods validate inputs, call `this.applyPatch(...)` for mutable fields,
+ * and return `this`. They must not apply events or advance lifecycle state directly.
+ * Lifecycle operations are checked before invoking the method.
+ *
+ * Patch validation and normalization finish before that patch writes any fields.
+ * Failures after a successful patch (including later method code, lifecycle hooks,
+ * or event construction/application) do not roll back state: discard or reload
+ * the aggregate. Rejected methods do not run the completion lifecycle.
+ *
+ * @typeParam TEntity - The aggregate the decorated method belongs to.
+ * @param options - The domain event(s) factory to record for this mutation.
+ * @returns A method decorator that performs the full mutation lifecycle.
+ *
+ * @example
+ * ```ts
+ * export class User extends RootEntity<UserSnapshot> {
+ *   @Mutable<string>({ normalize: (value) => User.normalizeUsername(value) })
+ *   private _username: string;
+ *
+ *   @ApplyMutation<User>({ event: (user) => new UserRenamedEvent(user) })
+ *   rename(name: string): this {
+ *     this.applyPatch({ username: name });
+ *     return this;
+ *   }
+ * }
+ * ```
+ */
+export declare function ApplyMutation<TEntity = unknown>(options: ApplyMutationOptions<TEntity>): MethodDecorator;
+//# sourceMappingURL=apply-mutation.decorator.d.ts.map

package/dist/domain/decorators/apply-mutation.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-mutation.decorator.d.ts","sourceRoot":"","sources":["../../../domain/decorators/apply-mutation.decorator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAEnD;;;;;;GAMG;AAEH,MAAM,MAAM,aAAa,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB,GAC1B,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GAC9B,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAE1B,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,OAAO;IAC3C;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,WAAW,GAAG,kBAAkB,CAAC;CACvE;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAG,OAAO,EAC7C,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,GACrC,eAAe,CA8BjB"}

package/dist/domain/decorators/apply-mutation.decorator.js

@@ -0,0 +1,86 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApplyMutation = ApplyMutation;
+function assertLifecycleOperations(entity) {
+    for (const method of ['onUpdate', 'apply']) {
+        if (typeof entity?.[method] !== 'function') {
+            throw new TypeError(`@ApplyMutation requires target instance to implement callable ${method}() method.`);
+        }
+    }
+}
+function completeMutation(entity, result, options) {
+    entity.onUpdate();
+    const eventOrEvents = options.event(entity);
+    if (!Array.isArray(eventOrEvents)) {
+        if (eventOrEvents === null || typeof eventOrEvents !== 'object') {
+            throw new TypeError(`@ApplyMutation event factory must return a domain event object or non-empty array of events, received: ${String(eventOrEvents)}.`);
+        }
+        entity.apply(eventOrEvents);
+        return result;
+    }
+    if (eventOrEvents.length === 0) {
+        throw new TypeError('@ApplyMutation event factory must return at least one domain event.');
+    }
+    for (let i = 0; i < eventOrEvents.length; i++) {
+        const evt = eventOrEvents[i];
+        if (evt === null || typeof evt !== 'object') {
+            throw new TypeError(`@ApplyMutation event factory returned an invalid event at index ${i}. Expected an event object, received: ${String(evt)}.`);
+        }
+    }
+    for (const evt of eventOrEvents) {
+        entity.apply(evt);
+    }
+    return result;
+}
+/**
+ * Completes a successful domain mutation by advancing `onUpdate()` once and
+ * recording events from the resulting state. Preserves the method's return value,
+ * including an entity returned by an asynchronous method.
+ *
+ * Domain methods validate inputs, call `this.applyPatch(...)` for mutable fields,
+ * and return `this`. They must not apply events or advance lifecycle state directly.
+ * Lifecycle operations are checked before invoking the method.
+ *
+ * Patch validation and normalization finish before that patch writes any fields.
+ * Failures after a successful patch (including later method code, lifecycle hooks,
+ * or event construction/application) do not roll back state: discard or reload
+ * the aggregate. Rejected methods do not run the completion lifecycle.
+ *
+ * @typeParam TEntity - The aggregate the decorated method belongs to.
+ * @param options - The domain event(s) factory to record for this mutation.
+ * @returns A method decorator that performs the full mutation lifecycle.
+ *
+ * @example
+ * ```ts
+ * export class User extends RootEntity<UserSnapshot> {
+ *   @Mutable<string>({ normalize: (value) => User.normalizeUsername(value) })
+ *   private _username: string;
+ *
+ *   @ApplyMutation<User>({ event: (user) => new UserRenamedEvent(user) })
+ *   rename(name: string): this {
+ *     this.applyPatch({ username: name });
+ *     return this;
+ *   }
+ * }
+ * ```
+ */
+function ApplyMutation(options) {
+    if (!options || typeof options.event !== 'function') {
+        throw new TypeError('@ApplyMutation requires an event factory option: @ApplyMutation({ event: (entity) => ... }).');
+    }
+    return (_target, _propertyKey, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = function (...args) {
+            assertLifecycleOperations(this);
+            const entity = this;
+            const result = original.apply(this, args);
+            if (result && typeof result.then === 'function') {
+                return result.then((value) => completeMutation(entity, value, options));
+            }
+            return completeMutation(entity, result, options);
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=apply-mutation.decorator.js.map

package/dist/domain/decorators/apply-mutation.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-mutation.decorator.js","sourceRoot":"","sources":["../../../domain/decorators/apply-mutation.decorator.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AAiItE,sCAgCC;AArHD,SAAS,yBAAyB,CAChC,MAAe;IAEf,KAAK,MAAM,MAAM,IAAI,CAAC,UAAU,EAAE,OAAO,CAAU,EAAE,CAAC;QACpD,IACE,OAAQ,MAAwC,EAAE,CAAC,MAAM,CAAC,KAAK,UAAU,EACzE,CAAC;YACD,MAAM,IAAI,SAAS,CACjB,iEAAiE,MAAM,YAAY,CACpF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CACvB,MAAqB,EACrB,MAAe,EACf,OAAsC;IAEtC,MAAM,CAAC,QAAQ,EAAE,CAAC;IAElB,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,MAAiB,CAAC,CAAC;IAEvD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,IAAI,aAAa,KAAK,IAAI,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;YAChE,MAAM,IAAI,SAAS,CACjB,0GAA0G,MAAM,CAAC,aAAa,CAAC,GAAG,CACnI,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CACjB,qEAAqE,CACtE,CAAC;IACJ,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5C,MAAM,IAAI,SAAS,CACjB,mEAAmE,CAAC,yCAAyC,MAAM,CAAC,GAAG,CAAC,GAAG,CAC5H,CAAC;QACJ,CAAC;IACH,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,aAAa,CAC3B,OAAsC;IAEtC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CACjB,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IAED,OAAO,CACL,OAAe,EACf,YAA6B,EAC7B,UAA8B,EAC9B,EAAE;QACF,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAe,CAAC;QAE5C,UAAU,CAAC,KAAK,GAAG,UAAU,GAAG,IAAe;YAC7C,yBAAyB,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,MAAM,GAAG,IAAqB,CAAC;YACrC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAE1C,IAAI,MAAM,IAAI,OAAQ,MAA2B,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBACtE,OAAQ,MAA2B,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CACjD,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CACzC,CAAC;YACJ,CAAC;YAED,OAAO,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACnD,CAAC,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/domain/decorators/mutable.decorator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Registration options for a mutable aggregate field.
+ *
+ * @typeParam TValue - The value type stored in the backing property.
+ */
+export interface MutableOptions<TValue = unknown> {
+    /**
+     * Public patch key a domain method uses for this field. Defaults to the
+     * decorated property name with a single leading underscore removed
+     * (`_username` becomes `username`).
+     */
+    readonly as?: string;
+    /**
+     * Invariant check and coercion applied before the value reaches the backing
+     * property. Throw a domain exception here to reject the mutation; the
+     * aggregate is then left untouched, no version is advanced and no event is
+     * recorded.
+     */
+    readonly normalize?: (value: TValue) => TValue;
+}
+/** A registered mutable field: its backing property and its normalizer. */
+export interface MutableFieldDefinition {
+    readonly propertyKey: string;
+    readonly patchKey: string;
+    readonly normalize?: (value: unknown) => unknown;
+}
+/**
+ * Declares an aggregate property as mutable through domain methods.
+ *
+ * `RootEntity.applyPatch()` writes only to fields registered here, so the set of properties a
+ * mutation may touch is declared once on the field itself instead of being
+ * restated in every method that changes it.
+ *
+ * @param options - Patch key override and the field's normalizer.
+ * @returns A property decorator registering the field on the owning class.
+ *
+ * @example
+ * ```ts
+ * export class User extends RootEntity<UserSnapshot> {
+ *   @Mutable<string>({ normalize: (value) => User.normalizeUsername(value) })
+ *   private _username: string;
+ * }
+ * ```
+ */
+export declare function Mutable<TValue = unknown>(options?: MutableOptions<TValue>): PropertyDecorator;
+/**
+ * Resolves every mutable field visible on an instance, including fields
+ * declared by base classes.
+ *
+ * @param instance - The aggregate to inspect.
+ * @returns Patch key to field definition, nearest declaration winning.
+ */
+export declare function getMutableFields(instance: object): ReadonlyMap<string, MutableFieldDefinition>;
+//# sourceMappingURL=mutable.decorator.d.ts.map

package/dist/domain/decorators/mutable.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutable.decorator.d.ts","sourceRoot":"","sources":["../../../domain/decorators/mutable.decorator.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAChD;AAED,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAClD;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,MAAM,GAAG,OAAO,EACtC,OAAO,GAAE,cAAc,CAAC,MAAM,CAAM,GACnC,iBAAiB,CA2BnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GACf,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAwB7C"}