Μετάβαση στο περιεχόμενο
Από την έκδοση 0.5.0 τα πακέτα συνεχίζουν ως @cqrs-ddd, με τεκμηρίωση στο aristoteliss.github.io/ddd-cqrs· οι εφαρμογές NestJS προσθέτουν το @cqrs-ddd/nestjs. Αυτός ο ιστότοπος τεκμηριώνει τη σειρά 0.4.x.

@cqrs-ddd/core

Από την έκδοση 0.5.0 το @cqrs-ddd/core αναπτύσσεται και δημοσιεύεται από το ddd-cqrs, με τεκμηρίωση στο aristoteliss.github.io/ddd-cqrs. Αυτός ο ιστότοπος τεκμηριώνει τη σειρά 0.4.x· οι εκδόσεις 0.1 έως 0.4 παραμένουν στο npm αμετάβλητες.

npm version License

Δομικά στοιχεία ανεξάρτητα από framework για domain-driven design σε TypeScript: aggregates με versioned mutations, αποσυνδεδεμένα domain events, ένας command handler που δημοσιεύει αυτά τα συμβάντα, συμβόλαια repository, decorators κύκλου ζωής persistence, ένα revision-fenced repository cache, κλειδιά cache με tenant scope και αντιστοίχιση καταστάσεων HTTP για τα σφάλματά του.

Δεν εξαρτάται από κανένα framework και κανένα ORM. Οι adapters για το MikroORM βρίσκονται στο @cqrs-ddd/mikro-orm. Λειτουργεί σε μια απλή υπηρεσία Node, καθώς και σε μια εφαρμογή NestJS μέσω δομικής συμβατότητας: δείτε Χρήση από το NestJS.

Terminal window
pnpm add @cqrs-ddd/core
# or
npm install @cqrs-ddd/core

Απαιτεί Node.js 22.12 ή νεότερο. Εγκαθιστά τα @cqrs-ddd/uuidv7 και @cqrs-ddd/safe-stringify, τα οποία δεν έχουν εξαρτήσεις. Για persistence με το MikroORM, προσθέστε τα @cqrs-ddd/mikro-orm και @mikro-orm/core 7.

Δημοσιεύεται ως ES module· μια εφαρμογή CommonJS το φορτώνει με require(). Εάν προέρχεστε από την έκδοση 0.3.x, δείτε Αναβάθμιση από 0.3.x.

Εισαγάγετε από το entry point που αντιστοιχεί στο επίπεδο (layer) που γράφετε. Κάθε ένα φορτώνει μόνο ό,τι χρειάζεται.

Entry point Περιέχει
@cqrs-ddd/core/domain AggregateRoot, IAggregateRoot, ApplyEventOptions, RootEntity, RootEntitySnapshot, @Mutable, getMutableFields, @ApplyMutation, IEvent, DomainEvent, RootDomainEvent, deepCloneAndFreeze, textRule, numberRule, ValueViolation, και τα σφάλματα DomainException, InvalidValueException, EntityNotFoundException, ConcurrencyConflictError, TransientOperationError (με isTransientOperationError), MissingTenantContextError, UnknownMutableFieldError
@cqrs-ddd/core/application BaseCommand, BaseQuery, IQueryOptions, CommandBaseHandler, τα ports (IDomainEventPublisher, ICommandRepository, IQueryRepository, IWriteSideAggregateRepository, ICache, IVersionedCache, isVersionedCache), requireTenant, setTenantResolver, και το deprecated requireTenantId
@cqrs-ddd/core/persistence τους decorators κύκλου ζωής (@PersistedWrite, @Cache, @AcknowledgePersisted, @MapPersistenceErrors, @FromCache), QueryRepository, CommandRepository, MemoryCache και το injection token του CACHE_TOKEN, cacheKey, cacheKeyTemplate, isCacheNewer, toCacheSnapshot, τα βοηθητικά mutation-barrier, consoleCacheLogger, safeWarn, και το συμβόλαιο persistence dialect (IPersistenceDialect, setPersistenceDialect, persistenceDialect)
@cqrs-ddd/core/http domainErrorHttpStatus
@cqrs-ddd/core όλα τα παραπάνω, καθώς και τον τύπο Method

Κανένα entry point δεν φορτώνει κάποιο ORM ή το NestJS.

Ένα aggregate επεκτείνει το RootEntity<TSnapshot>. Αποκτά ένα UUIDv7 id, createdAt και updatedAt, ένα version για optimistic concurrency, και ένα buffer συμβάντων. Οι αλλαγές κατάστασης γίνονται μέσω domain μεθόδων διακοσμημένων με @ApplyMutation, οι οποίες γράφουν μόνο τα πεδία που έχουν δηλωθεί ως @Mutable:

import {
ApplyMutation,
DomainException,
InvalidValueException,
Mutable,
RootEntity,
type RootEntitySnapshot,
textRule,
} from '@cqrs-ddd/core/domain';
export class InvalidUsernameException extends InvalidValueException {}
export class InvalidDepartmentException extends InvalidValueException {}
export class EmptyUserUpdateException extends DomainException {
constructor() {
super('A user update needs at least one field.');
}
}
export interface UserSnapshot extends Partial<RootEntitySnapshot> {
readonly username: string;
readonly email: string;
readonly department?: string | null;
}
export class User extends RootEntity<UserSnapshot> {
static readonly aggregateName = 'user';
static readonly rules = {
username: textRule({
field: 'username',
minLength: 3,
maxLength: 255,
error: (violation) => new InvalidUsernameException(violation),
}),
department: textRule({
field: 'department',
required: false,
maxLength: 255,
error: (violation) => new InvalidDepartmentException(violation),
}),
} as const;
@Mutable<string>({ normalize: (value) => User.rules.username.parse(value) })
private _username: string;
@Mutable<string | null>({ normalize: (value) => User.rules.department.parse(value) })
private _department: string | null;
readonly email: string;
private constructor(snapshot: UserSnapshot) {
super(snapshot);
this._username = User.rules.username.parse(snapshot.username);
this._department = User.rules.department.parse(snapshot.department);
this.email = snapshot.email;
}
static create(username: string, email: string, department?: string | null): User {
const user = new User({ username, email, department });
user.apply(new UserCreatedEvent(user));
return user;
}
static fromJSON(snapshot: UserSnapshot): User {
return new User(snapshot);
}
get username(): string {
return this._username;
}
private set username(value: string) {
this._username = User.rules.username.parse(value);
}
get department(): string | null {
return this._department;
}
private set department(value: string | null) {
this._department = User.rules.department.parse(value);
}
@ApplyMutation<User>({ event: (user) => new UserUpdatedEvent(user) })
update(fields: { username?: string; department?: string | null }): this {
if (fields.username === undefined && fields.department === undefined) {
throw new EmptyUserUpdateException();
}
this.applyPatch({ username: fields.username, department: fields.department });
return this;
}
@ApplyMutation<User>({ event: (user) => new UserDeletedEvent(user) })
delete(): this {
return this;
}
toJSON(): UserSnapshot & RootEntitySnapshot {
return this.freezeState({
id: this.id,
username: this._username,
department: this._department,
email: this.email,
createdAt: this.createdAt,
updatedAt: this.updatedAt,
version: this.version,
});
}
}

Τα συμβάντα δηλώνονται στα Domain events. Χρήση του aggregate:

const user = User.create('alice', 'alice@example.test');
user.version; // 1
user.getUncommittedEvents(); // [UserCreatedEvent]
user.update({ department: 'Research' });
user.version; // 2
user.getExpectedVersion(); // 1: the version the next write must find in storage
user.update({}); // throws EmptyUserUpdateException; nothing is recorded
user.update({ username: 'a' }); // throws InvalidUsernameException before any field is written
  • Το @Mutable καταχωρίζει ένα πεδίο για το applyPatch υπό το όνομα της ιδιότητάς του χωρίς το αρχικό underscore (το _username ενημερώνεται ως username)· το as: 'name' ορίζει άλλο κλειδί, και το normalize επικυρώνει και μετατρέπει κάθε τιμή.
  • Το applyPatch(patch) επικυρώνει και κανονικοποιεί (normalizes) κάθε παρεχόμενο πεδίο πριν γράψει οποιοδήποτε από αυτά, και αγνοεί τις τιμές undefined. Ένα άγνωστο κλειδί πετά UnknownMutableFieldError.
  • Μετά από μια επιτυχημένη μέθοδο, το @ApplyMutation προωθεί τα version και updatedAt και καταγράφει το event. Μια μέθοδος που πετά σφάλμα δεν καταγράφει τίποτα.
  • Επικυρώστε πριν από το patching: μια αποτυχία αφού γραφτούν τα πεδία (μεταγενέστερος κώδικας μεθόδου, lifecycle hook, δημιουργία συμβάντος) δεν τα επαναφέρει (rollback). Απορρίψτε ή επαναφορτώστε το instance.
  • Το RootEntity.from(value) επαναενυδατώνει (rehydrates) ένα instance, ένα snapshot ή ένα nullish αποτέλεσμα βάσης δεδομένων, και πετά TypeError για μη συμβατό aggregate.
  • Τα id, createdAt και updatedAt έχουν δημόσιους getters και ιδιωτικούς (private) setters. Το ORM εκτελεί hydration μέσω των setters (δείτε παρακάτω)· ο κώδικας της εφαρμογής δεν μπορεί να τους αναθέσει τιμές και αλλάζει την κατάσταση μέσω domain μεθόδων και factories. Ορίστε επίσης ιδιωτικούς setters για τα persisted πεδία μιας υποκλάσης, όπως τα username και department παραπάνω.
  • Το version είναι η έκδοση στη μνήμη· το getExpectedVersion() είναι η έκδοση που διαβάστηκε τελευταία φορά από ή γράφτηκε στο storage, με την οποία συγκρίνεται μια version-conditioned εγγραφή. Το acknowledgePersisted() το προωθεί μετά από επιτυχή εγγραφή· το @PersistedWrite το καλεί αυτόματα για εσάς.

Τα textRule(options) και numberRule(options) ορίζουν τον κανόνα για ένα πεδίο μία φορά. Το aggregate χρησιμοποιεί το parse(value) του κανόνα για να κανονικοποιήσει την τιμή, και άλλα επίπεδα διαβάζουν τα όρια του κανόνα, ώστε το schema ενός request να μην αποκλίνει από το domain:

z.string().trim().min(User.rules.username.minLength).max(User.rules.username.maxLength);

Το parse(value) επιστρέφει την κανονικοποιημένη τιμή ή πετά το σφάλμα του κανόνα. Είναι μια αυτόνομη συνάρτηση, και ο κανόνας είναι παγωμένος (frozen).

Επιλογή textRule Αποτέλεσμα
field Όνομα που αναφέρεται στην παραβίαση και στο προεπιλεγμένο μήνυμα
required Με false κανονικοποιεί τα null, undefined και κενό κείμενο σε null· από προεπιλογή απορρίπτονται
minLength, maxLength Μήκος μετά την κανονικοποίηση, σε UTF-16 code units όπως τα .min() και .max() του Zod
pattern Κανονική έκφραση (regex) με την οποία πρέπει να ταιριάζει το κείμενο· τα flags g ή y απορρίπτονται
multiline Με true δέχεται tab, line feed και carriage return εντός του κειμένου
error Κατασκευάζει το σφάλμα για μια παραβίαση· προεπιλογή το InvalidValueException

Το κείμενο ελέγχεται ως προς τον τύπο και για μη συζευγμένα surrogates, στη συνέχεια μετατρέπεται σε μορφή Unicode NFC και αφαιρούνται τα κενά (trimmed). Οι χαρακτήρες ελέγχου (control characters) απορρίπτονται πάντα, όπως και τα tabs και οι αλλαγές γραμμής εκτός αν έχει οριστεί το multiline.

Επιλογή numberRule Αποτέλεσμα
field, required, error Όπως και στο textRule (το required: false δέχεται null και undefined)
integer Δέχεται μόνο ασφαλείς ακέραιους (safe integers)
min, max Συμπεριληπτικά όρια (inclusive bounds)

Ένας αριθμός πρέπει να είναι τύπου number και πεπερασμένος· μια αριθμητική συμβολοσειρά απορρίπτεται, δεν μετατρέπεται. Μια μη έγκυρη επιλογή, όπως minLength μεγαλύτερο από το maxLength, πετά TypeError κατά τον ορισμό του κανόνα.

Ένας παραβιασμένος κανόνας πετά error(violation). Το violation είναι ένα παγωμένο (frozen) ValueViolation: { field, rule }, συν το limit για κανόνα μήκους ή εύρους και το expected για κανόνα τύπου. Το InvalidValueException το μεταφέρει, κατασκευάζει το μήνυμα (username must be at least 3 characters.), και δεν διατηρεί την απορριφθείσα τιμή. Επεκτείνετέ το για τις δικές σας εξαιρέσεις, όπως στο παραπάνω παράδειγμα, ώστε όλες να μοιράζονται αυτή τη δομή.

Ένα domain event επεκτείνει το RootDomainEvent<TEntity, TPayload>. Φέρει ένα UUIDv7 id, τα aggregateId και aggregateVersion κατά τον χρόνο του συμβάντος, και το payload: έναν βαθύ κλώνο (deep clone) του toJSON() του aggregate, αναδρομικά παγωμένο (frozen).

import { RootDomainEvent } from '@cqrs-ddd/core/domain';
export class UserCreatedEvent extends RootDomainEvent<User, UserSnapshot> {
constructor(user: User) {
super(user);
}
}

Τα UserUpdatedEvent και UserDeletedEvent δηλώνονται με τον ίδιο τρόπο.

  • Αποσυνδεδεμένο (Detached): μετέπειτα αλλαγές στο aggregate δεν φτάνουν ποτέ στο payload.
  • Μόνο για ανάγνωση σε συνήθη πρόσβαση: οι ίδιες οι ιδιότητες είναι παγωμένες, και οι μέθοδοι μετάλλαξης (mutating methods) των κλωνοποιημένων τιμών Date, Map και Set πετούν σφάλμα.
  • Όχι όριο ασφαλείας: Το Object.freeze δεν καλύπτει την ενσωματωμένη εσωτερική κατάσταση, επομένως το Date.prototype.setTime.call(payload.at, 0) εξακολουθεί να την αλλάζει, και κάθε καταναλωτής ενός συμβάντος μοιράζεται το ίδιο payload. Το event.clonePayload() επιστρέφει ένα νέο παγωμένο αντίγραφο ανά κλήση όταν ένας καταναλωτής χρειάζεται το δικό του.
  • Όχι μορφή μεταφοράς (transport format): στείλτε ένα ρητό, serializable μήνυμα κατασκευασμένο από τα πεδία που χρειάζεστε.

Το deepCloneAndFreeze(value) είναι η συνάρτηση πίσω από το payload, χρησιμοποιήσιμη και αυτόνομα. Διαχειρίζεται αντικείμενα, πίνακες, Date, Map, Set, RegExp και κυκλικές αναφορές.

Τα BaseCommand και BaseQuery είναι απλές βασικές κλάσεις για αντικείμενα command και query. Το BaseCommand διατηρεί ένα προαιρετικό sessionPrincipal (ή sessionUser) εκτός απαρίθμησης και toJSON(), ώστε να μην φτάνει ποτέ σε αποτύπωμα (fingerprint) ή log. Το getUpdateFields(fields) επιστρέφει τα αναφερόμενα πεδία που φέρει το command (το null υπολογίζεται, το undefined όχι), για εξουσιοδότηση σε επίπεδο πεδίου.

Το CommandBaseHandler εκτελεί ένα command και δημοσιεύει τα συμβάντα του aggregate που επιστρέφει:

import {
BaseCommand,
CommandBaseHandler,
type IDomainEventPublisher,
type IWriteSideAggregateRepository,
} from '@cqrs-ddd/core/application';
import { EntityNotFoundException } from '@cqrs-ddd/core/domain';
export class UpdateUserCommand extends BaseCommand {
constructor(
readonly id: string,
readonly username?: string,
readonly department?: string | null,
) {
super();
}
}
export class UpdateUserHandler extends CommandBaseHandler<UpdateUserCommand, User> {
constructor(
private readonly users: IWriteSideAggregateRepository<User>,
eventBus: IDomainEventPublisher,
) {
super(eventBus);
}
async handle(command: UpdateUserCommand): Promise<User> {
const user = await this.users.findById(command.id);
if (!user) throw new EntityNotFoundException('User', command.id);
user.update({ username: command.username, department: command.department });
await this.users.save(user);
return user;
}
}
const handler = new UpdateUserHandler(users, {
publishAll: async (events) => events.forEach((event) => emitter.emit('event', event)),
});
await handler.execute(new UpdateUserCommand(id, 'bob'));
  • Το handle() επιστρέφει το aggregate, ή ένα αποτέλεσμα που το περιέχει ως aggregate· οποιοδήποτε IAggregateRoot είναι αποδεκτό. Το execute() το καλεί, δημοσιεύει τα αποθηκευμένα στο buffer συμβάντα μία φορά με eventBus.publishAll(events, aggregate) (το aggregate αποτελεί το dispatcher context), εκκαθαρίζει το buffer και επιστρέφει το αποτέλεσμα αμετάβλητο.
  • Ένα απορριφθέν handle() δεν δημοσιεύει τίποτα. Εάν το publishAll() πετάξει σφάλμα, το σφάλμα διαδίδεται και τα συμβάντα παραμένουν στο buffer.
  • Εάν το publishAll() επιστρέφει υπόσχεση (promise), το execute() την περιμένει (awaits) μετά την εκκαθάριση του buffer. Η απόρριψή της απορρίπτει το command, παρόλο που το aggregate έχει ήδη αποθηκευτεί στο persistence storage· τα συμβάντα δεν δημοσιεύονται δεύτερη φορά.
  • Οποιοδήποτε αντικείμενο με publishAll(events) αποτελεί IDomainEventPublisher.

Το AggregateRoot.commit() δεν δημοσιεύει τίποτα από προεπιλογή. Παραδίδει ένα αντίγραφο του buffer στο hook publishAll του ίδιου του aggregate (το apply() καλεί το publish όσο το autoCommit είναι ενεργό), το οποίο δεν κάνει τίποτα μέχρι να συνδεθεί ένας publisher, και στη συνέχεια εκκαθαρίζει το buffer. Συνεπώς, η κλήση του commit() χωρίς συνδεδεμένο publisher απορρίπτει τα συμβάντα· το ίδιο ισχύει και για το autoCommit. Αφήστε το CommandBaseHandler να δημοσιεύσει, ή διαβάστε το getUncommittedEvents() και καλέστε το uncommit() εσείς οι ίδιοι.

Το commit(dispatcherContext?) περνά το context, όπως { transaction }, στο publishAll και επιστρέφει αυτό που εκείνο επιστρέφει. Το buffer εκκαθαρίζεται μόλις επιστρέψει το publishAll, πριν διευθετηθεί ένας ασύγχρονος publisher, επομένως το await aggregate.commit() περιμένει τον publisher και λαμβάνει το σφάλμα του χωρίς κίνδυνο δεύτερης δημοσίευσης· εάν το publishAll πετάξει σφάλμα, τα συμβάντα παραμένουν στο buffer.

Ένας command handler φορτώνει το αυθεντικό aggregate μέσω του IWriteSideAggregateRepository<TEntity>.findById(id): πρέπει να διαβάζει το πρωτεύον storage, ποτέ cache. Το AggregateRepository του @cqrs-ddd/mikro-orm το υλοποιεί για το MikroORM.

Το save() δηλώνει τον κύκλο ζωής του με το @PersistedWrite. Με το @cqrs-ddd/mikro-orm, όπου το AggregateRepository παρέχει το findById() και το this.store:

import type { ICache } from '@cqrs-ddd/core/application';
import { DomainException } from '@cqrs-ddd/core/domain';
import { cacheKey, PersistedWrite } from '@cqrs-ddd/core/persistence';
import {
AggregateRepository,
type IEntityManagerSource,
mapPersistenceError,
optimisticUpdate,
} from '@cqrs-ddd/mikro-orm';
export class UniqueEmailException extends DomainException {
constructor(readonly user: User) {
super('This email is already registered.');
}
}
export class UpdateUserRepository extends AggregateRepository<UserSnapshot, User, UserSnapshot> {
constructor(cache: ICache<UserSnapshot>, store: IEntityManagerSource) {
super(cache, store, User, User.aggregateName, User.fromJSON);
}
@PersistedWrite<User>({
cache: {
setKey: (user) => cacheKey(User.aggregateName, { id: user.id }),
invalidateKeys: (user) => [cacheKey(User.aggregateName, { email: user.email })],
},
unique: { email: (user) => new UniqueEmailException(user) },
otherwise: (error, user) => mapPersistenceError(error, `updating User ${user.id}`),
})
async save(user: User): Promise<UserSnapshot> {
const snapshot = user.toJSON();
await optimisticUpdate(
this.store.em,
User,
user,
{
username: snapshot.username,
department: snapshot.department ?? null,
updatedAt: snapshot.updatedAt,
},
'User',
);
return snapshot;
}
}

Το optimisticUpdate προσθέτει το version στα εγγεγραμμένα πεδία· κάθε άλλη τροποποιημένη στήλη, συμπεριλαμβανομένου του updatedAt, αναφέρεται ρητά.

Το @PersistedWrite εφαρμόζει τρεις decorators. Όταν τοποθετούνται χειροκίνητα σε στοίβα, η σειρά είναι σταθερή, από τον εξωτερικό προς τον εσωτερικό:

  1. @Cache(options): μετά από επιτυχή εγγραφή, γράφει το επιστρεφόμενο snapshot μέσω compare-and-set (isCacheNewer εκτός αν το isNewer ορίζει διαφορετικά), και εγκαθιστά barriers για τα invalidateKeys. Όταν το save() επιλύεται σε null ή undefined, εγκαθιστά barriers για τα deleteKeys. Τα σφάλματα cache καταγράφονται στα logs και ποτέ δεν μετατρέπουν μια επιβεβαιωμένη (committed) εγγραφή σε αποτυχία.
  2. @AcknowledgePersisted({ entity: ([aggregate]) => aggregate }): προωθεί την persisted έκδοση του επιλεγμένου aggregate μόνο αφού επιτύχει η εγγραφή.
  3. @MapPersistenceErrors({ entity, unique, dialect, otherwise }): μεταφράζει μια παραβίαση μοναδικότητας (unique violation) στο δικό σας domain error. Το unique έχει ως κλειδί την ιδιότητα του entity που καλύπτει ο περιορισμός ({ email: ... }), ή το δηλωμένο όνομα ενός περιορισμού πολλαπλών στηλών (MapPersistenceErrors<Args, Entity, typeof NAME>), ώστε ένα repository να μην κατονομάζει ποτέ περιορισμό ή στήλη βάσης δεδομένων. Το ποιον περιορισμό παραβίασε ένα σφάλμα αναγιγνώσκεται από το persistence dialect: options.dialect, διαφορετικά αυτό που καταχωρίστηκε με το setPersistenceDialect() στο composition root. Το core δεν γνωρίζει καμία βάση δεδομένων· ένας adapter όπως το MikroOrmDialect του @cqrs-ddd/mikro-orm υλοποιεί το IPersistenceDialect. Μια μέθοδος που δηλώνει unique χωρίς διαθέσιμο dialect πετά TypeError πριν εκτελεστεί. Το otherwise μεταφράζει τα υπόλοιπα, για παράδειγμα με το mapPersistenceError του @cqrs-ddd/mikro-orm, το οποίο μετατρέπει αποτυχίες οδηγού (driver) και δικτύου που επιδέχονται επανάληψη σε TransientOperationError και διατηρεί κάθε άλλο σφάλμα αμετάβλητο.

Οι διαγραφές δεν πραγματοποιούν acknowledgment, επομένως στοιβάζουν μόνο τα @Cache και @MapPersistenceErrors, και επιλύονται σε null ώστε το @Cache να εγκαταστήσει barriers για τα deleteKeys:

import { Cache, cacheKey, MapPersistenceErrors } from '@cqrs-ddd/core/persistence';
import { mapPersistenceError, optimisticDelete } from '@cqrs-ddd/mikro-orm';
export class DeleteUserRepository extends AggregateRepository<UserSnapshot, User, null> {
constructor(cache: ICache<UserSnapshot>, store: IEntityManagerSource) {
super(cache, store, User, User.aggregateName, User.fromJSON);
}
@Cache<User, null>({
deleteKeys: (user) => [
cacheKey(User.aggregateName, { id: user.id }),
cacheKey(User.aggregateName, { email: user.email }),
],
})
@MapPersistenceErrors<[User], User>({
entity: ([user]) => user,
otherwise: (error, user) => mapPersistenceError(error, `deleting User ${user.id}`),
})
async save(user: User): Promise<null> {
await optimisticDelete(this.store.em, User, user, 'User');
return null;
}
}

Η ίδια η εγγραφή πρέπει να εξαρτάται από την έκδοση (WHERE id = ? AND version = expected) και δεν πρέπει να εκτελείται εντός εξωτερικού transaction, του οποίου η επιτυχία δεν θα σήμαινε ανθεκτικό (durable) persistence. Το @cqrs-ddd/mikro-orm παρέχει τα optimisticUpdate και optimisticDelete για αυτόν τον σκοπό.

Ένα query repository επεκτείνει το QueryRepository και διακοσμεί το find() με το @FromCache. Ο constructor δέχεται το cache (οποιοδήποτε ICache· δείτε Το repository cache για το γιατί το @FromCache χρειάζεται ένα IVersionedCache) και την προεπιλεγμένη ενυδάτωση (hydration) του repository:

import { BaseQuery, type ICache, type IQueryOptions } from '@cqrs-ddd/core/application';
import { cacheKey, FromCache, QueryRepository } from '@cqrs-ddd/core/persistence';
import type { IEntityManagerSource } from '@cqrs-ddd/mikro-orm';
export class GetUserQuery extends BaseQuery {
constructor(
readonly id: string,
options?: IQueryOptions,
) {
super(options);
}
}
export class GetUserRepository extends QueryRepository<GetUserQuery, User | null> {
constructor(
cache: ICache<UserSnapshot>,
private readonly store: IEntityManagerSource,
) {
super(cache, { hydrateFn: (cached) => User.fromJSON(cached as UserSnapshot) });
}
@FromCache<GetUserQuery, User | null>({
keyFn: (query) => cacheKey(User.aggregateName, { id: query.id }),
})
async find(query: GetUserQuery): Promise<User | null> {
return this.store.em.findOne(User, { id: query.id }, query.refresh ? { refresh: true } : undefined);
}
}
await users.find(new GetUserQuery(id)); // may be served from the cache
await users.find(new GetUserQuery(id, { refresh: true })); // always reads the database

Επιλογές @FromCache: keyFn (επιστρέψτε null για παράκαμψη του cache στη συγκεκριμένη κλήση), hydrateFn, serializeFn, ttl σε χιλιοστά του δευτερολέπτου (ms), isNewer και logger.

  • Κάθε επιτυχία (hit) επανενυδατώνεται όποτε εφαρμόζεται hydrator, ώστε ένα hit και ένα miss να επιστρέφουν τον ίδιο τύπο. Το hydrateFn της ίδιας της μεθόδου (ή hydrateFn: null) υπερισχύει αυτού του repository· το serializeFn ακολουθεί τον ίδιο κανόνα.
  • Χωρίς hydrator, αποθηκεύονται στο cache μόνο απλά δεδομένα (plain data)· ένα instance κλάσης επιστρέφεται χωρίς caching.
  • Αποθηκεύονται μόνο μη-nullish αποτελέσματα. Ένα barrier ή ένα αποθηκευμένο null υπολογίζεται ως miss.
  • Ένα query με refresh: true παρακάμπτει το cache.
  • Τα σφάλματα cache διαδίδονται από τις αναγνώσεις: ένα query αποτυγχάνει αντί να κάνει εικασίες.

Το @Cache λειτουργεί με οποιοδήποτε ICache (get, set, delete). Το @FromCache απαιτεί ένα IVersionedCache, το οποίο προσθέτει ένα φράγμα αναθεώρησης (revision fence):

Μέθοδος Συμβόλαιο
readState(key) η κατάσταση της εγγραφής (hit, miss, expired), η τιμή και η αδιαφανής αναθεώρηση (opaque revision)
invalidate(key) αποβάλλει την τιμή και προωθεί την αναθεώρηση
tryFill(key, observedRevision, value, options?) γράφει μόνο αν η αναθεώρηση παραμένει observedRevision· false διαφορετικά

Το @FromCache παρατηρεί την αναθεώρηση πριν από την ανάγνωση της βάσης δεδομένων και συμπληρώνει με το tryFill, ώστε μια ανάγνωση που ήρθε σε race condition με μια ακύρωση ή διαγραφή να μην μπορεί να επανεγγράψει ένα παλιό snapshot. Ένα απορριφθέν fill ξαναδιαβάζει το κλειδί, επιστρέφει ένα αυστηρά νεότερο snapshot εάν υπάρχει, και σε αντίθετη περίπτωση επαναλαμβάνει για περιορισμένο αριθμό φορών πριν επιστρέψει το αποτέλεσμα της βάσης χωρίς caching. Ένας adapter που υλοποιεί μόνο το ICache παρακάμπτεται από το @FromCache τόσο για αναγνώσεις όσο και για fills, με μία προειδοποίηση να καταγράφεται στα logs: δεν μπορεί να διασφαλίσει fencing σε ένα fill.

Δύο adapters υλοποιούν το IVersionedCache:

  • MemoryCache({ defaultTtlMs = 60_000, maxEntries = 10_000 }): εντός της διεργασίας, εγγραφές κλωνοποιημένες μέσω JSON κατά την εγγραφή και ανάγνωση, για δοκιμές και μεμονωμένη διεργασία.
  • MikroOrmCache, στο @cqrs-ddd/mikro-orm: μία γραμμή βάσης δεδομένων ανά κλειδί, κάθε εγγραφή συνιστά compare-and-set στο δικό της transaction.

Το CacheSetOptions.isNewer(cached, incoming) επιστρέφει true όταν η cached τιμή είναι νεότερη και δεν πρέπει να αντικατασταθεί· το isCacheNewer συγκρίνει το version, έπειτα το __gen, και μετά το updatedAt. Το toCacheSnapshot μετατρέπει ένα αποτέλεσμα σε αποσυνδεδεμένο (detached) snapshot: το cache δεν αποθηκεύει ποτέ ζωντανό aggregate.

Τα mutation barriers (CacheMutationBarrier) επισημαίνουν ένα διαγραμμένο ή ακυρωμένο κλειδί για διάστημα barrierTtl, 60 δευτερόλεπτα από προεπιλογή. Επιλέξτε μέγεθος μεγαλύτερο από τη μεγαλύτερη σε διάρκεια ανάγνωση σε εξέλιξη.

Η επιλογή logger. Τα @Cache και @FromCache δέχονται logger: { warn(message) } για τις λειτουργικές προειδοποιήσεις τους, όπως μια αποτυχημένη εγγραφή cache, έναν παρακαμφθέντα adapter ή ένα λάθος συνδεδεμένο repository. Ένας NestJS Logger ή το console ταιριάζουν άριστα. Χωρίς αυτόν, οι προειδοποιήσεις κατευθύνονται στο console.warn. Ένας logger που πετά σφάλμα δεν αλλάζει ποτέ ένα αποτέλεσμα. Ένας adapter αναφέρει τις δικές του προειδοποιήσεις με τον ίδιο τρόπο μέσω των consoleCacheLogger(context) και safeWarn(logger, message).

Τα cacheKey(resource, conditions, tenant?) και cacheKeyTemplate(template, tenant?) θέτουν namespace σε κάθε κλειδί βάσει tenant. Το tenant προέρχεται, κατά σειρά προτεραιότητας, από:

  1. το ρητό όρισμα tenant: string με το tenant id, ή αντικείμενο που φέρει tenantId, όπως το context ενός αιτήματος·
  2. για το cacheKeyTemplate, το tenantId μιας πηγής context·
  3. τον resolver που καταχωρίζει η εφαρμογή μία φορά κατά την εκκίνηση με το setTenantResolver(fn), μια συνάρτηση που επιστρέφει το tenant του τρέχοντος request ή job·
  4. διαφορετικά, MissingTenantContextError.
import { AsyncLocalStorage } from 'node:async_hooks';
import { setTenantResolver } from '@cqrs-ddd/core/application';
const requestTenant = new AsyncLocalStorage<string>();
setTenantResolver(() => requestTenant.getStore());
// Per request or job:
requestTenant.run(tenantId, () => handle(request));

Δεν υπάρχει κοινόχρηστο namespace: ένα ελλείπον ή κενό tenant, ή ένας resolver που δεν επιστρέφει τίποτα, πετά σφάλμα. Μια single-tenant εγκατάσταση περνά ένα σταθερό id ή καταχωρίζει setTenantResolver(() => 'single'). Η ίδια επίλυση είναι δημόσια διαθέσιμη ως requireTenant(purpose, source?), για οποιοδήποτε άλλο κλειδί πρέπει να διαχωρίζεται ανά tenant, όπως ένα κλειδί idempotency ή rate-limit, και για οποιονδήποτε κώδικα χρειάζεται το τρέχον tenant και πρέπει να αποτυγχάνει όταν δεν υπάρχει κανένα:

import { requireTenant } from '@cqrs-ddd/core/application';
requireTenant('access token issuance'); // the resolver's tenant
requireTenant('users.create idempotency key', ctx); // ctx.tenantId, else the resolver's

Το requireTenantId(source, purpose) είναι deprecated: δέχεται τα ίδια ορίσματα με αντίστροφη σειρά και καλεί το requireTenant.

Τα κλειδιά cacheKey έχουν τη μορφή ${tenant}:${resource}:v1:${sha256}, υπολογισμένα με hash επί μιας key-sorted σειριοποίησης του [tenant, resource, conditions]. Η μορφή είναι παγωμένη (frozen), ώστε οι αποθηκευμένες εγγραφές να παραμένουν προσπελάσιμες μεταξύ διαφορετικών εκδόσεων.

Το domainErrorHttpStatus(error) από το /http αντιστοιχίζει τα σφάλματα αυτού του πακέτου σε απλές τιμές { statusCode, error, message }, για οποιοδήποτε HTTP framework:

Σφάλμα Status
ConcurrencyConflictError 409
EntityNotFoundException 404
MissingTenantContextError 500, με γενικό μήνυμα: ένα αίτημα χωρίς tenant συνιστά σφάλμα server
οποιοδήποτε άλλο DomainException, συμπεριλαμβανομένου του InvalidValueException 400

Επιστρέφει undefined για οτιδήποτε άλλο. Αντιστοιχίστε πρώτα τις δικές σας εξαιρέσεις, και στη συνέχεια περάστε τα υπόλοιπα σε αυτό.

Τίποτα σε αυτό το πακέτο δεν εισάγει το NestJS· η ενσωμάτωση είναι δομική (structural).

  • Το EventBus του NestJS CQRS διαθέτει publishAll(events, dispatcherContext), επομένως αποτελεί IDomainEventPublisher: ένας handler περνά το injected bus του στο super(eventBus), και το bus παραδίδει το aggregate στον ρυθμισμένο publisher του ως dispatcher context.
  • Το AggregateRoot ικανοποιεί το IAggregateRoot του NestJS, και ένα AggregateRoot του NestJS ικανοποιεί το IAggregateRoot αυτού του πακέτου. Το EventPublisher.mergeObjectContext(aggregate) συνδέει ένα aggregate με το EventBus: το commit() στη συνέχεια δημοσιεύει με το aggregate ως context, το commit({ transaction }) με αυτό το context, και τα δύο επιστρέφουν το αποτέλεσμα του bus.
  • Το CommandBaseHandler.execute(command) είναι η μέθοδος που καλεί το command bus του NestJS, επομένως μια κλάση διακοσμημένη με @CommandHandler το επεκτείνει απευθείας.
  • Τα BaseCommand, BaseQuery και τα domain events είναι απλές κλάσεις τις οποίες το NestJS αποστέλλει όπως κάθε άλλη.
@CommandHandler(UpdateUserCommand)
export class UpdateUserHandler extends CommandBaseHandler<UpdateUserCommand, User> {
constructor(
@Inject(USER_WRITE_REPOSITORY) private readonly users: IWriteSideAggregateRepository<User>,
eventBus: EventBus,
) {
super(eventBus);
}
// handle() as above
}

Η εφαρμογή γράφει την υπόλοιπη διασύνδεση (glue):

  • providers για τα repositories και το cache, για παράδειγμα ένας useFactory provider που κατασκευάζει ένα MikroOrmCache από το @cqrs-ddd/mikro-orm υπό το token CACHE_TOKEN:

    { provide: CACHE_TOKEN, useValue: new MemoryCache({ defaultTtlMs: 30_000 }) }
  • τον tenant resolver, καταχωρισμένο μία φορά πριν οποιοδήποτε lifecycle hook μπορέσει να ξεκινήσει εργασία που τον διαβάζει, για παράδειγμα στον constructor ενός module·

  • ένα exception filter που αντιστοιχίζει τα δικά του σφάλματα και στη συνέχεια καλεί το domainErrorHttpStatus·

  • έναν logger για τους decorators cache, όπως new Logger('UserCache').

Το μη δημοσιευμένο πακέτο workspace @nestjs-pipeline/ddd-core (φάκελος ddd/core) αντιστοιχίζεται σε αυτό το πακέτο ως εξής. Εξαρτιόταν από το NestJS και το MikroORM· αυτό το πακέτο δεν εξαρτάται από κανένα από τα δύο, και τα μέρη του MikroORM βρίσκονται στο @cqrs-ddd/mikro-orm.

ddd/core @cqrs-ddd/core
import { … } from '@nestjs-pipeline/ddd-core' τα entry points επιπέδων: @cqrs-ddd/core/domain, /application, /persistence, /http
@Mutate() σε μέθοδο μετάλλαξης, η οποία καλούσε το onUpdate() @ApplyMutation({ event }), το οποίο καταγράφει επίσης το event, καθώς και πεδία @Mutable γραμμένα μέσω του applyPatch()
DomainOutcome, RootDomainOutcome που επιστρέφονταν από το handle() το handle() επιστρέφει το aggregate, ή αποτέλεσμα με ιδιότητα aggregate· τα καταγεγραμμένα συμβάντα του δημοσιεύονται
CommandBaseHandler(eventBus: EventBus) από το @nestjs/cqrs CommandBaseHandler(eventBus: IDomainEventPublisher)· ένα NestJS EventBus εξακολουθεί να ταιριάζει
CacheableEntity, ICacheKey, entity.cacheKey (prefix + id) RootEntity με στατικό aggregateName, κλειδιά κατασκευασμένα με cacheKey(User.aggregateName, { id }), πάντα με tenant scope
CacheableEntity.fromStringify(data, fromJSON) RootEntity.from(value) ή το fromJSON του ίδιου του aggregate
ICommandRepository.save(domainOutcome) ICommandRepository.save(entity), και IWriteSideAggregateRepository.findById(id) για φόρτωση
@Cache(setKeyFn, deleteKeysFn) @Cache({ setKey, deleteKeys, invalidateKeys, ttl, isNewer, barrierTtl, logger }), συνήθως μέσω του @PersistedWrite
@FromCache(keyFn, hydrateFn), ενυδάτωση όταν ορίζεται το query.hydrate @FromCache({ keyFn, hydrateFn, … }) με ένα IVersionedCache· τα hits επανενυδατώνονται πάντα όταν εφαρμόζεται hydrator
QueryRepository(cache) QueryRepository(cache, { hydrateFn, serializeFn? })
ICache στο persistence/cache.interface ICache και IVersionedCache στο @cqrs-ddd/core/application
UnixTimestampType UnixTimestampType στο @cqrs-ddd/mikro-orm
RootEntity με αφηρημένο (abstract) afterUpdate() το afterUpdate() είναι προαιρετικό hook· το RootEntity επεκτείνει το AggregateRoot και προσθέτει version, getExpectedVersion(), το buffer συμβάντων και ιδιωτικούς hydration setters

Τα παλιά imports και τα νέα δίπλα-δίπλα:

ddd/core
import { CacheableEntity, CommandBaseHandler, Mutate, RootDomainOutcome } from '@nestjs-pipeline/ddd-core';
// @cqrs-ddd/core
import { ApplyMutation, Mutable, RootEntity } from '@cqrs-ddd/core/domain';
import { CommandBaseHandler } from '@cqrs-ddd/core/application';
import { cacheKey, PersistedWrite } from '@cqrs-ddd/core/persistence';
import { AggregateRepository, optimisticUpdate, UnixTimestampType } from '@cqrs-ddd/mikro-orm';
  • Το persistence και η δημοσίευση συμβάντων δεν είναι ατομικά (atomic). Μια κατάρρευση μεταξύ της εγγραφής και του publishAll() χάνει τα συμβάντα· η ανθεκτική παράδοση απαιτεί transactional outbox.
  • Η συντήρηση του cache μετά από commit γίνεται με προσπάθεια βέλτιστης απόδοσης (best-effort). Εάν μια ακύρωση αποτύχει, η προηγούμενη εγγραφή παραμένει μέχρι να λήξει: το revision fence συντονίζει το cache με τον εαυτό του, όχι με τη βάση δεδομένων. Διαβάστε με { refresh: true } όπου μια απόφαση δεν πρέπει να βασίζεται σε cached τιμή.
  • Ένα mutation barrier προστατεύει μόνο για διάστημα barrierTtl. Αποτελεί ένα περιορισμένο παράθυρο ανταγωνισμού (race window), όχι tombstone.
  • Τα βοηθητικά εργαλεία persistence απορρίπτουν εξωτερικά transactions· οι decorators δεν μπορούν να καταστήσουν πολλαπλές εγγραφές ατομικές. Μια γραμμή που πρέπει να γίνει commit μαζί με το aggregate, όπως μια εγγραφή audit ή ένα μήνυμα outbox, συνεπώς δεν μπορεί να μοιραστεί το transaction του ακόμη: αυτό απαιτεί commit hooks που εκτελούν acknowledgment και εργασίες cache μετά το commit.
  • Το @MapPersistenceErrors αντιστοιχίζει μια παραβίαση μοναδικότητας μόνο στον βαθμό που το καταχωρισμένο persistence dialect τη διαβάζει· το MikroOrmDialect διαβάζει σφάλματα PostgreSQL και SQLite.
  • Ο tenant resolver λειτουργεί σε επίπεδο διεργασίας: ένας ανά διεργασία, για κάθε εγκατεστημένο αντίγραφο αυτού του πακέτου.
  • Τα payloads συμβάντων είναι παγωμένα μόνο για συνήθη πρόσβαση· δείτε Domain events.

Διπλή άδεια υπό AGPL-3.0-or-later ή Commercial License. Δείτε τα LICENSE και COMMERCIAL_LICENSE.txt στη ρίζα του repository.