@cqrs-ddd/core 0.2.0

package/dist/application/base.command.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Base class for application CQRS commands.
+ *
+ * Encapsulates non-enumerable session/authentication metadata and reports which
+ * of a declared set of fields this command actually carries, via
+ * {@link getUpdateFields}.
+ */
+export declare abstract class BaseCommand<TSessionPrincipal = any> {
+    readonly sessionPrincipal?: TSessionPrincipal;
+    readonly sessionUser?: TSessionPrincipal;
+    constructor(sessionPrincipal?: TSessionPrincipal);
+    /**
+     * Serializes enumerable command payload fields to a plain object.
+     *
+     * Non-enumerable metadata such as `sessionPrincipal` and `sessionUser` is excluded, and fields whose
+     * value is `undefined` are omitted. This makes the result suitable for stable
+     * cache/idempotency fingerprinting.
+     *
+     * @returns The command payload without pipeline/session metadata.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Returns the declared updatable fields that are actually present on this command.
+     *
+     * A field counts as present when its value is not `undefined`. `null`
+     * therefore counts as an intentional mutation, which is important for nullable
+     * fields such as clearing a department.
+     *
+     * Use this with field-level authorization so the authorization surface is an
+     * explicit list owned by the command type.
+     *
+     * @param updatableFields - Allowed updatable field names for this command.
+     * @returns Only fields present in the current command payload.
+     *
+     * @example
+     * ```ts
+     * // updatableFields: the fields this command type declares updatable.
+     * const fields = command.getUpdateFields(updatableFields);
+     * authorizer.authorize('update', user, fields);
+     * ```
+     */
+    getUpdateFields(updatableFields: readonly string[]): string[];
+}
+//# sourceMappingURL=base.command.d.ts.map

package/dist/application/base.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.command.d.ts","sourceRoot":"","sources":["../../application/base.command.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,8BAAsB,WAAW,CAAC,iBAAiB,GAAG,GAAG;IACvD,SAAwB,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IAC7D,SAAwB,WAAW,CAAC,EAAE,iBAAiB,CAAC;gBAE5C,gBAAgB,CAAC,EAAE,iBAAiB;IAOhD;;;;;;;;OAQG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE;CAK9D"}

package/dist/application/base.command.js

@@ -0,0 +1,58 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseCommand = void 0;
+const request_fields_helper_1 = require("./request-fields.helper");
+/**
+ * Base class for application CQRS commands.
+ *
+ * Encapsulates non-enumerable session/authentication metadata and reports which
+ * of a declared set of fields this command actually carries, via
+ * {@link getUpdateFields}.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: generic session principal default
+class BaseCommand {
+    constructor(sessionPrincipal) {
+        if (sessionPrincipal !== undefined) {
+            (0, request_fields_helper_1.defineHidden)(this, 'sessionPrincipal', sessionPrincipal);
+            (0, request_fields_helper_1.defineHidden)(this, 'sessionUser', sessionPrincipal);
+        }
+    }
+    /**
+     * Serializes enumerable command payload fields to a plain object.
+     *
+     * Non-enumerable metadata such as `sessionPrincipal` and `sessionUser` is excluded, and fields whose
+     * value is `undefined` are omitted. This makes the result suitable for stable
+     * cache/idempotency fingerprinting.
+     *
+     * @returns The command payload without pipeline/session metadata.
+     */
+    toJSON() {
+        return (0, request_fields_helper_1.definedFields)(this);
+    }
+    /**
+     * Returns the declared updatable fields that are actually present on this command.
+     *
+     * A field counts as present when its value is not `undefined`. `null`
+     * therefore counts as an intentional mutation, which is important for nullable
+     * fields such as clearing a department.
+     *
+     * Use this with field-level authorization so the authorization surface is an
+     * explicit list owned by the command type.
+     *
+     * @param updatableFields - Allowed updatable field names for this command.
+     * @returns Only fields present in the current command payload.
+     *
+     * @example
+     * ```ts
+     * // updatableFields: the fields this command type declares updatable.
+     * const fields = command.getUpdateFields(updatableFields);
+     * authorizer.authorize('update', user, fields);
+     * ```
+     */
+    getUpdateFields(updatableFields) {
+        return updatableFields.filter((field) => this[field] !== undefined);
+    }
+}
+exports.BaseCommand = BaseCommand;
+//# sourceMappingURL=base.command.js.map

package/dist/application/base.command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.command.js","sourceRoot":"","sources":["../../application/base.command.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE,mEAAsE;AAEtE;;;;;;GAMG;AACH,gFAAgF;AAChF,MAAsB,WAAW;IAI/B,YAAY,gBAAoC;QAC9C,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACnC,IAAA,oCAAY,EAAC,IAAI,EAAE,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;YACzD,IAAA,oCAAY,EAAC,IAAI,EAAE,aAAa,EAAE,gBAAgB,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM;QACJ,OAAO,IAAA,qCAAa,EAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,eAAkC;QAChD,OAAO,eAAe,CAAC,MAAM,CAC3B,CAAC,KAAK,EAAE,EAAE,CAAE,IAAgC,CAAC,KAAK,CAAC,KAAK,SAAS,CAClE,CAAC;IACJ,CAAC;CACF;AAjDD,kCAiDC"}

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

@@ -0,0 +1,42 @@
+import type { IQueryOptions } from './query.options';
+/**
+ * Base class for application CQRS queries.
+ *
+ * Query options and authentication context are pipeline metadata rather than request
+ * payload. They are stored as non-enumerable properties so Zod validation and
+ * cache-key serialization operate only on the query payload.
+ *
+ * @typeParam TSessionUser - Application-specific principal/session metadata type.
+ *
+ * @example
+ * ```ts
+ * export class GetUserQuery extends BaseQuery<SessionUser> {
+ *   constructor(
+ *     public readonly id: string,
+ *     options?: Partial<IQueryOptions>,
+ *     sessionUser?: SessionUser,
+ *   ) {
+ *     super(options, sessionUser);
+ *   }
+ * }
+ *
+ * const query = new GetUserQuery(userId, { hydrate: true }, sessionUser);
+ * ```
+ */
+export declare abstract class BaseQuery<TSessionPrincipal = unknown> implements IQueryOptions {
+    readonly hydrate?: boolean;
+    readonly refresh?: boolean;
+    readonly sessionPrincipal?: TSessionPrincipal;
+    readonly sessionUser?: TSessionPrincipal;
+    constructor(options?: Partial<IQueryOptions>, sessionPrincipal?: TSessionPrincipal);
+    /**
+     * Serializes enumerable query payload fields to a plain object.
+     *
+     * `hydrate`, `refresh`, `sessionPrincipal` and `sessionUser` are non-enumerable metadata and stay
+     * out of the payload.
+     *
+     * @returns The query payload with `undefined` fields omitted.
+     */
+    toJSON(): Record<string, unknown>;
+}
+//# sourceMappingURL=base.query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base.query.d.ts","sourceRoot":"","sources":["../../application/base.query.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,SAAS,CAAC,iBAAiB,GAAG,OAAO,CACzD,YAAW,aAAa;IAExB,SAAwB,OAAO,CAAC,EAAE,OAAO,CAAC;IAC1C,SAAwB,OAAO,CAAC,EAAE,OAAO,CAAC;IAC1C,SAAwB,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IAC7D,SAAwB,WAAW,CAAC,EAAE,iBAAiB,CAAC;gBAGtD,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,EAChC,gBAAgB,CAAC,EAAE,iBAAiB;IAUtC;;;;;;;OAOG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGlC"}

package/dist/application/base.query.js

@@ -0,0 +1,52 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseQuery = void 0;
+const request_fields_helper_1 = require("./request-fields.helper");
+/**
+ * Base class for application CQRS queries.
+ *
+ * Query options and authentication context are pipeline metadata rather than request
+ * payload. They are stored as non-enumerable properties so Zod validation and
+ * cache-key serialization operate only on the query payload.
+ *
+ * @typeParam TSessionUser - Application-specific principal/session metadata type.
+ *
+ * @example
+ * ```ts
+ * export class GetUserQuery extends BaseQuery<SessionUser> {
+ *   constructor(
+ *     public readonly id: string,
+ *     options?: Partial<IQueryOptions>,
+ *     sessionUser?: SessionUser,
+ *   ) {
+ *     super(options, sessionUser);
+ *   }
+ * }
+ *
+ * const query = new GetUserQuery(userId, { hydrate: true }, sessionUser);
+ * ```
+ */
+class BaseQuery {
+    constructor(options, sessionPrincipal) {
+        (0, request_fields_helper_1.defineHidden)(this, 'hydrate', options?.hydrate ?? false);
+        (0, request_fields_helper_1.defineHidden)(this, 'refresh', options?.refresh ?? false);
+        if (sessionPrincipal !== undefined) {
+            (0, request_fields_helper_1.defineHidden)(this, 'sessionPrincipal', sessionPrincipal);
+            (0, request_fields_helper_1.defineHidden)(this, 'sessionUser', sessionPrincipal);
+        }
+    }
+    /**
+     * Serializes enumerable query payload fields to a plain object.
+     *
+     * `hydrate`, `refresh`, `sessionPrincipal` and `sessionUser` are non-enumerable metadata and stay
+     * out of the payload.
+     *
+     * @returns The query payload with `undefined` fields omitted.
+     */
+    toJSON() {
+        return (0, request_fields_helper_1.definedFields)(this);
+    }
+}
+exports.BaseQuery = BaseQuery;
+//# sourceMappingURL=base.query.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base.query.js","sourceRoot":"","sources":["../../application/base.query.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAGtE,mEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAsB,SAAS;IAQ7B,YACE,OAAgC,EAChC,gBAAoC;QAEpC,IAAA,oCAAY,EAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC,CAAC;QACzD,IAAA,oCAAY,EAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC,CAAC;QACzD,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACnC,IAAA,oCAAY,EAAC,IAAI,EAAE,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;YACzD,IAAA,oCAAY,EAAC,IAAI,EAAE,aAAa,EAAE,gBAAgB,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,MAAM;QACJ,OAAO,IAAA,qCAAa,EAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;CACF;AA/BD,8BA+BC"}

package/dist/application/command-base.handler.d.ts

@@ -0,0 +1,106 @@
+import { AggregateRoot } from '../domain/models/aggregate-root';
+import type { IDomainEventPublisher } from './ports/domain-event-publisher.port';
+/**
+ * Result shapes that allow `CommandBaseHandler` to publish buffered aggregate events.
+ * Return either the aggregate itself or an application result with an `aggregate` field.
+ */
+export type AggregateBearingResult = AggregateRoot | {
+    readonly aggregate: AggregateRoot;
+};
+/**
+ * Base class for all CQRS command handlers.
+ *
+ * Wraps every concrete command handler with shared lifecycle behavior:
+ * 1. Executes command logic via the abstract {@link handle} method.
+ * 2. If the result is an {@link AggregateRoot} (or an object containing `aggregate: AggregateRoot`),
+ *    its buffered uncommitted domain events are automatically published through the
+ *    {@link IDomainEventPublisher} and cleared after publication.
+ *
+ * It is framework-neutral. With NestJS CQRS, decorate the subclass with
+ * `@CommandHandler` and pass the injected `EventBus`, which satisfies
+ * {@link IDomainEventPublisher}; Nest calls {@link execute} as the handler entry point.
+ *
+ * @typeParam TCommand - The concrete command type this handler processes.
+ * @typeParam TResult - The handler's return type (e.g. aggregate entity or result carrying aggregate).
+ *
+ * @example Returning aggregate root directly (auto-published)
+ * ```typescript
+ * @CommandHandler(CreateUserCommand)
+ * export class CreateUserHandler extends CommandBaseHandler<CreateUserCommand, User> {
+ *   constructor(
+ *     @Inject(COMMAND_REPOSITORY.createUser)
+ *     private readonly commandRepository: ICommandRepository<User, UserSnapshot>,
+ *     protected readonly eventBus: EventBus,
+ *   ) {
+ *     super(eventBus);
+ *   }
+ *
+ *   async handle(command: CreateUserCommand): Promise<User> {
+ *     const user = User.create(command.username, command.email);
+ *     await this.commandRepository.save(user);
+ *     return user; // execute() automatically publishes user.getUncommittedEvents()
+ *   }
+ * }
+ * ```
+ *
+ * @example Returning an application result carrying an AggregateRoot (auto-published)
+ * ```typescript
+ * @CommandHandler(CreateAuthCommand)
+ * export class CreateAuthHandler extends CommandBaseHandler<CreateAuthCommand, CreateAuthResult> {
+ *   constructor(
+ *     @Inject(COMMAND_REPOSITORY.createAuth)
+ *     private readonly commandRepository: ICommandRepository<Auth, null>,
+ *     protected readonly eventBus: EventBus,
+ *   ) {
+ *     super(eventBus);
+ *   }
+ *
+ *   async handle(command: CreateAuthCommand): Promise<CreateAuthResult> {
+ *     const auth = Auth.create(userId, token);
+ *     await this.commandRepository.save(auth);
+ *     return {
+ *       aggregate: auth, // execute() automatically detects aggregate and publishes events
+ *       id: userId,
+ *       tenant: tenant,
+ *       token,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class CommandBaseHandler<TCommand = unknown, TResult extends AggregateBearingResult = AggregateBearingResult> {
+    protected readonly eventBus: IDomainEventPublisher;
+    /**
+     * Constructs the handler with the publisher of domain events.
+     *
+     * @param eventBus - The publisher used to dispatch domain events, such as the
+     *   NestJS CQRS `EventBus`.
+     */
+    protected constructor(eventBus: IDomainEventPublisher);
+    /**
+     * Executes the business logic for the command.
+     *
+     * Concrete handlers must implement this method instead of `execute()`.
+     * If the returned result is an {@link AggregateRoot} (or contains an `aggregate` property),
+     * any uncommitted domain events recorded on it will be published automatically.
+     *
+     * @param command - The typed command to process.
+     * @returns The result of the command execution.
+     */
+    abstract handle(command: TCommand): Promise<TResult>;
+    /**
+     * Handler entry point, invoked by the command bus (for example the NestJS CQRS
+     * `CommandBus`).
+     *
+     * Delegates to {@link handle} and automatically publishes any uncommitted domain
+     * events if the result is an {@link AggregateRoot} (or an object containing `aggregate: AggregateRoot`).
+     *
+     * Persistence and in-memory event publication are not atomic. A crash after
+     * persistence can lose events; durable delivery requires an explicit outbox.
+     *
+     * @param command - The command dispatched through the command bus.
+     * @returns The result produced by {@link handle}.
+     */
+    execute(command: TCommand): Promise<TResult>;
+}
+//# sourceMappingURL=command-base.handler.d.ts.map

package/dist/application/command-base.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-base.handler.d.ts","sourceRoot":"","sources":["../../application/command-base.handler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAEjF;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAC9B,aAAa,GACb;IAAE,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;CAAE,CAAC;AAY1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,8BAAsB,kBAAkB,CACtC,QAAQ,GAAG,OAAO,EAClB,OAAO,SAAS,sBAAsB,GAAG,sBAAsB;IAQzC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB;IANxE;;;;;OAKG;IACH,SAAS,aAAgC,QAAQ,EAAE,qBAAqB;IAExE;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpD;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;CAsBnD"}

package/dist/application/command-base.handler.js

@@ -0,0 +1,119 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandBaseHandler = void 0;
+const aggregate_root_1 = require("../domain/models/aggregate-root");
+function isAggregate(obj) {
+    return (obj instanceof aggregate_root_1.AggregateRoot ||
+        (typeof obj === 'object' &&
+            obj !== null &&
+            typeof obj.getUncommittedEvents === 'function' &&
+            typeof obj.uncommit === 'function'));
+}
+/**
+ * Base class for all CQRS command handlers.
+ *
+ * Wraps every concrete command handler with shared lifecycle behavior:
+ * 1. Executes command logic via the abstract {@link handle} method.
+ * 2. If the result is an {@link AggregateRoot} (or an object containing `aggregate: AggregateRoot`),
+ *    its buffered uncommitted domain events are automatically published through the
+ *    {@link IDomainEventPublisher} and cleared after publication.
+ *
+ * It is framework-neutral. With NestJS CQRS, decorate the subclass with
+ * `@CommandHandler` and pass the injected `EventBus`, which satisfies
+ * {@link IDomainEventPublisher}; Nest calls {@link execute} as the handler entry point.
+ *
+ * @typeParam TCommand - The concrete command type this handler processes.
+ * @typeParam TResult - The handler's return type (e.g. aggregate entity or result carrying aggregate).
+ *
+ * @example Returning aggregate root directly (auto-published)
+ * ```typescript
+ * @CommandHandler(CreateUserCommand)
+ * export class CreateUserHandler extends CommandBaseHandler<CreateUserCommand, User> {
+ *   constructor(
+ *     @Inject(COMMAND_REPOSITORY.createUser)
+ *     private readonly commandRepository: ICommandRepository<User, UserSnapshot>,
+ *     protected readonly eventBus: EventBus,
+ *   ) {
+ *     super(eventBus);
+ *   }
+ *
+ *   async handle(command: CreateUserCommand): Promise<User> {
+ *     const user = User.create(command.username, command.email);
+ *     await this.commandRepository.save(user);
+ *     return user; // execute() automatically publishes user.getUncommittedEvents()
+ *   }
+ * }
+ * ```
+ *
+ * @example Returning an application result carrying an AggregateRoot (auto-published)
+ * ```typescript
+ * @CommandHandler(CreateAuthCommand)
+ * export class CreateAuthHandler extends CommandBaseHandler<CreateAuthCommand, CreateAuthResult> {
+ *   constructor(
+ *     @Inject(COMMAND_REPOSITORY.createAuth)
+ *     private readonly commandRepository: ICommandRepository<Auth, null>,
+ *     protected readonly eventBus: EventBus,
+ *   ) {
+ *     super(eventBus);
+ *   }
+ *
+ *   async handle(command: CreateAuthCommand): Promise<CreateAuthResult> {
+ *     const auth = Auth.create(userId, token);
+ *     await this.commandRepository.save(auth);
+ *     return {
+ *       aggregate: auth, // execute() automatically detects aggregate and publishes events
+ *       id: userId,
+ *       tenant: tenant,
+ *       token,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+class CommandBaseHandler {
+    eventBus;
+    /**
+     * Constructs the handler with the publisher of domain events.
+     *
+     * @param eventBus - The publisher used to dispatch domain events, such as the
+     *   NestJS CQRS `EventBus`.
+     */
+    constructor(eventBus) {
+        this.eventBus = eventBus;
+    }
+    /**
+     * Handler entry point, invoked by the command bus (for example the NestJS CQRS
+     * `CommandBus`).
+     *
+     * Delegates to {@link handle} and automatically publishes any uncommitted domain
+     * events if the result is an {@link AggregateRoot} (or an object containing `aggregate: AggregateRoot`).
+     *
+     * Persistence and in-memory event publication are not atomic. A crash after
+     * persistence can lose events; durable delivery requires an explicit outbox.
+     *
+     * @param command - The command dispatched through the command bus.
+     * @returns The result produced by {@link handle}.
+     */
+    async execute(command) {
+        const commandResult = await this.handle(command);
+        const aggregate = isAggregate(commandResult)
+            ? commandResult
+            : commandResult &&
+                typeof commandResult === 'object' &&
+                'aggregate' in commandResult &&
+                isAggregate(commandResult.aggregate)
+                ? commandResult.aggregate
+                : undefined;
+        if (aggregate) {
+            const events = [...aggregate.getUncommittedEvents()];
+            if (events.length > 0) {
+                this.eventBus.publishAll(events);
+                aggregate.uncommit();
+            }
+        }
+        return commandResult;
+    }
+}
+exports.CommandBaseHandler = CommandBaseHandler;
+//# sourceMappingURL=command-base.handler.js.map

package/dist/application/command-base.handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-base.handler.js","sourceRoot":"","sources":["../../application/command-base.handler.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE,oEAAgE;AAWhE,SAAS,WAAW,CAAC,GAAY;IAC/B,OAAO,CACL,GAAG,YAAY,8BAAa;QAC5B,CAAC,OAAO,GAAG,KAAK,QAAQ;YACtB,GAAG,KAAK,IAAI;YACZ,OAAQ,GAAqB,CAAC,oBAAoB,KAAK,UAAU;YACjE,OAAQ,GAAqB,CAAC,QAAQ,KAAK,UAAU,CAAC,CACzD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAsB,kBAAkB;IAUG;IANzC;;;;;OAKG;IACH,YAAyC,QAA+B;QAA/B,aAAQ,GAAR,QAAQ,CAAuB;IAAG,CAAC;IAc5E;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,OAAO,CAAC,OAAiB;QAC7B,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAEjD,MAAM,SAAS,GAAG,WAAW,CAAC,aAAa,CAAC;YAC1C,CAAC,CAAC,aAAa;YACf,CAAC,CAAC,aAAa;gBACX,OAAO,aAAa,KAAK,QAAQ;gBACjC,WAAW,IAAI,aAAa;gBAC5B,WAAW,CAAC,aAAa,CAAC,SAAS,CAAC;gBACtC,CAAC,CAAC,aAAa,CAAC,SAAS;gBACzB,CAAC,CAAC,SAAS,CAAC;QAEhB,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC,oBAAoB,EAAE,CAAC,CAAC;YACrD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;gBACjC,SAAS,CAAC,QAAQ,EAAE,CAAC;YACvB,CAAC;QACH,CAAC;QAED,OAAO,aAAa,CAAC;IACvB,CAAC;CACF;AA3DD,gDA2DC"}

package/dist/application/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Application-layer primitives and the ports handlers depend on. The ports, in
+ * `ports/`, are the contracts a CQRS handler depends on; their adapters stay
+ * behind `@cqrs-ddd/core/persistence` or in an adapter package.
+ */
+export * from './base.command';
+export * from './base.query';
+export * from './command-base.handler';
+export * from './ports/cache.port';
+export * from './ports/command-repository.port';
+export * from './ports/domain-event-publisher.port';
+export * from './ports/query-repository.port';
+export * from './ports/write-side-aggregate-repository.port';
+export * from './query.options';
+export * from './tenant-resolver';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../application/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8CAA8C,CAAC;AAC7D,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/application/index.js

@@ -0,0 +1,33 @@
+"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 });
+/**
+ * Application-layer primitives and the ports handlers depend on. The ports, in
+ * `ports/`, are the contracts a CQRS handler depends on; their adapters stay
+ * behind `@cqrs-ddd/core/persistence` or in an adapter package.
+ */
+__exportStar(require("./base.command"), exports);
+__exportStar(require("./base.query"), exports);
+__exportStar(require("./command-base.handler"), exports);
+__exportStar(require("./ports/cache.port"), exports);
+__exportStar(require("./ports/command-repository.port"), exports);
+__exportStar(require("./ports/domain-event-publisher.port"), exports);
+__exportStar(require("./ports/query-repository.port"), exports);
+__exportStar(require("./ports/write-side-aggregate-repository.port"), exports);
+__exportStar(require("./query.options"), exports);
+__exportStar(require("./tenant-resolver"), exports);
+//# sourceMappingURL=index.js.map

package/dist/application/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../application/index.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;;;;;;;;;;;;;;AAEtE;;;;GAIG;AAEH,iDAA+B;AAC/B,+CAA6B;AAC7B,yDAAuC;AACvC,qDAAmC;AACnC,kEAAgD;AAChD,sEAAoD;AACpD,gEAA8C;AAC9C,+EAA6D;AAC7D,kDAAgC;AAChC,oDAAkC"}

package/dist/application/ports/cache.port.d.ts

@@ -0,0 +1,104 @@
+/** Options applied to one cache write. */
+export interface CacheSetOptions {
+    /** Entry lifetime in milliseconds. Adapter-specific semantics apply when omitted. */
+    ttl?: number;
+    /**
+     * Atomic stale-write guard. When the adapter can compare an existing value
+     * with the incoming value, returning `true` means the cached value is newer
+     * and must not be overwritten.
+     *
+     * {@link isCacheNewer} is the standard comparator for versioned snapshots.
+     */
+    isNewer?: (cached: unknown, incoming: unknown) => boolean;
+}
+/**
+ * Minimal cache port used by DDD repository decorators.
+ *
+ * Implementations must store detached/serializable snapshots rather than live
+ * domain aggregates. `set()` may additionally implement compare-and-set
+ * semantics through {@link CacheSetOptions.isNewer}.
+ *
+ * @typeParam T - Value shape stored by this cache adapter.
+ *
+ * @example
+ * ```ts
+ * const cached = await cache.get(userKey);
+ * await cache.set(userKey, user.toJSON(), {
+ *   ttl: 30_000,
+ *   isNewer: isCacheNewer,
+ * });
+ * await cache.delete(userKey);
+ * ```
+ */
+export interface ICache<T = unknown> {
+    /** Returns the cached value, or `undefined` when the key is absent. */
+    get(key: string): Promise<T | undefined>;
+    /** Writes a value under `key`, optionally with TTL/CAS semantics. */
+    set(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /** Removes `key` when present. */
+    delete(key: string): Promise<void>;
+}
+/** Cache entry observation state. */
+export type CacheStateStatus = 'hit' | 'miss' | 'expired';
+/**
+ * Observed state of a cache key including opaque revision fencing.
+ *
+ * @typeParam T - Value shape stored by this cache adapter.
+ */
+export interface CacheStateEntry<T = unknown> {
+    /**
+     * Status of the cache entry:
+     * - `'hit'`: Value is present and unexpired.
+     * - `'miss'`: Key is absent or was invalidated.
+     * - `'expired'`: Entry existed but its TTL has elapsed.
+     */
+    readonly status: CacheStateStatus;
+    /** The cached value when status is `'hit'`, otherwise `undefined`. */
+    readonly value?: T;
+    /**
+     * Opaque revision token associated with the key at the moment of inspection.
+     * Advances on every write or invalidation, and is preserved on payload expiry
+     * to eliminate ABA races during fill attempts.
+     */
+    readonly revision: string;
+}
+/**
+ * Options for revision-fenced cache fill attempts.
+ */
+export interface CacheFillOptions {
+    /** Entry lifetime in milliseconds. */
+    ttl?: number;
+}
+/**
+ * Extended cache port providing atomic revision-fenced state operations.
+ *
+ * Guarantees per-key ordering: a fill started before an observed invalidation
+ * cannot repopulate its key afterwards.
+ *
+ * @typeParam T - Value shape stored by this cache adapter.
+ */
+export interface IVersionedCache<T = unknown> extends ICache<T> {
+    readonly isVersioned: true;
+    /**
+     * Observes current key state and opaque revision token.
+     */
+    readState(key: string): Promise<CacheStateEntry<T>>;
+    /**
+     * Atomically advances the key revision and evicts the value.
+     *
+     * @returns The newly advanced revision.
+     */
+    invalidate(key: string): Promise<string>;
+    /**
+     * Atomically checks that current revision matches `observedRevision`, writes
+     * value, and advances revision on match.
+     *
+     * @returns `true` if write committed; `false` if rejected due to revision mismatch.
+     */
+    tryFill(key: string, observedRevision: string, value: T, options?: CacheFillOptions): Promise<boolean>;
+}
+/**
+ * Capability guard verifying whether an adapter supports versioned coordination.
+ */
+export declare function isVersionedCache<T = unknown>(cache: unknown): cache is IVersionedCache<T>;
+//# sourceMappingURL=cache.port.d.ts.map

package/dist/application/ports/cache.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.port.d.ts","sourceRoot":"","sources":["../../../application/ports/cache.port.ts"],"names":[],"mappings":"AAEA,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,MAAM,CAAC,CAAC,GAAG,OAAO;IACjC,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAEzC,qEAAqE;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE,kCAAkC;IAClC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,qCAAqC;AACrC,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,MAAM,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAE3B;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpD;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzC;;;;;OAKG;IACH,OAAO,CACL,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,eAAe,CAAC,CAAC,CAAC,CAU7B"}

package/dist/application/ports/cache.port.js

@@ -0,0 +1,17 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isVersionedCache = isVersionedCache;
+/**
+ * Capability guard verifying whether an adapter supports versioned coordination.
+ */
+function isVersionedCache(cache) {
+    return (typeof cache === 'object' &&
+        cache !== null &&
+        (('isVersioned' in cache &&
+            cache.isVersioned === true) ||
+            (typeof cache.readState === 'function' &&
+                typeof cache.invalidate === 'function' &&
+                typeof cache.tryFill === 'function')));
+}
+//# sourceMappingURL=cache.port.js.map

package/dist/application/ports/cache.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.port.js","sourceRoot":"","sources":["../../../application/ports/cache.port.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AA2HtE,4CAYC;AAfD;;GAEG;AACH,SAAgB,gBAAgB,CAC9B,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,CAAC,aAAa,IAAI,KAAK;YACrB,KAA4B,CAAC,WAAW,KAAK,IAAI,CAAC;YACnD,CAAC,OAAQ,KAA4B,CAAC,SAAS,KAAK,UAAU;gBAC5D,OAAQ,KAA4B,CAAC,UAAU,KAAK,UAAU;gBAC9D,OAAQ,KAA4B,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAClE,CAAC;AACJ,CAAC"}