@cqrs-ddd/core
Δομικά στοιχεία ανεξάρτητα από framework για domain-driven design σε TypeScript: aggregates με εκδοχοποιημένα mutations (versioned mutations), αποσυνδεδεμένα domain events (detached events), ένας command handler που δημοσιεύει αυτά τα events, repository contracts, decorators κύκλου ζωής persistence, ένα revision-fenced repository cache, cache keys διαχωρισμένα ανά tenant και αντιστοίχιση HTTP status για τα domain errors.
Δεν εξαρτάται από κανένα framework και κανένα ORM. Οι adapters για το MikroORM βρίσκονται στο
@cqrs-ddd/mikro-orm.
Περιεχόμενα
Ενότητα με τίτλο «Περιεχόμενα»- Εγκατάσταση
- Entry points
- Aggregates
- Κανόνες τιμών (Value rules)
- Domain events
- Commands και δημοσίευση events
- Write-side repositories
- Read-side repositories
- Το repository cache
- Cache keys διαχωρισμένα ανά tenant
- Αντιστοίχιση HTTP status
- Γνωστοί περιορισμοί
- Άδεια χρήσης
Εγκατάσταση
Ενότητα με τίτλο «Εγκατάσταση»Απαιτεί 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().
Entry points
Ενότητα με τίτλο «Entry points»Κάντε import από το entry point που αντιστοιχεί στο layer που υλοποιείτε. Κάθε ένα φορτώνει αποκλειστικά ό,τι χρειάζεται.
| Entry point | Περιεχόμενο |
|---|---|
@cqrs-ddd/core/domain |
AggregateRoot, IAggregateRoot, ApplyEventOptions, RootEntity, RootEntitySnapshot, @Mutable, getMutableFields, @ApplyMutation, IEvent, DomainEvent, RootDomainEvent, deepCloneAndFreeze, textRule, numberRule, ValueViolation, και τα errors 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 |
@cqrs-ddd/core/persistence |
οι lifecycle decorators (@PersistedWrite, @Cache, @AcknowledgePersisted, @MapPersistenceErrors, @FromCache), QueryRepository, CommandRepository, MemoryCache και το injection token CACHE_TOKEN, cacheKey, cacheKeyTemplate, isCacheNewer, toCacheSnapshot, τα mutation-barrier helpers, consoleCacheLogger, safeWarn, και το persistence dialect contract (IPersistenceDialect, setPersistenceDialect, persistenceDialect) |
@cqrs-ddd/core/http |
domainErrorHttpStatus |
@cqrs-ddd/core |
όλα τα παραπάνω, συν τον τύπο Method |
Κανένα entry point δεν φορτώνει ORM ή framework.
Aggregates
Ενότητα με τίτλο «Aggregates»Ένα aggregate επεκτείνει το RootEntity<TSnapshot>. Αποκτά αυτόματα UUIDv7 id, createdAt και updatedAt, version για optimistic concurrency, και ένα event buffer. Οι αλλαγές κατάστασης πραγματοποιούνται μέσω domain μεθόδων διακοσμημένων με @ApplyMutation, οι οποίες τροποποιούν αποκλειστικά τα πεδία που έχουν δηλωθεί ως @Mutable:
Χρήση του aggregate:
- Το
@Mutableκαταχωρεί ένα πεδίο για τοapplyPatchυπό το όνομα του property χωρίς το αρχικό underscore (το_usernameενημερώνεται ωςusername). Τοas: 'name'ορίζει διαφορετικό κλειδί, ενώ τοnormalizeεπικυρώνει και μετατρέπει κάθε τιμή. - Το
applyPatch(patch)επικυρώνει και κανονικοποιεί κάθε παρεχόμενο πεδίο πριν γράψει οποιοδήποτε από αυτά, και αγνοεί τιμέςundefined. Ένα άγνωστο κλειδί ρίχνειUnknownMutableFieldError. - Μετά από επιτυχή μέθοδο, το
@ApplyMutationπροωθεί ταversionκαιupdatedAtκαι καταγράφει το event. Μια μέθοδος που ρίχνει σφάλμα δεν καταγράφει τίποτα. - Επικυρώστε πριν την εφαρμογή του patch: μια αποτυχία αφού γραφτούν τα πεδία δεν πραγματοποιεί rollback. Απορρίψτε ή επαναφορτώστε το instance.
- Το
RootEntity.from(value)επαναφέρει ένα instance, snapshot ή nullish αποτέλεσμα βάσης δεδομένων, και ρίχνειTypeErrorγια ασύμβατο aggregate. - Τα
id,createdAtκαιupdatedAtδιαθέτουν public getters και private setters. Το ORM τα αρχικοποιεί μέσω των setters. Ο κώδικας εφαρμογής αλλάζει κατάσταση μόνο μέσω domain μεθόδων και factories. - Το
versionείναι η in-memory έκδοση. ΤοgetExpectedVersion()είναι η έκδοση που διαβάστηκε ή γράφτηκε τελευταία στη βάση, την οποία συγκρίνει μια εγγραφή με condition. ΤοacknowledgePersisted()την προωθεί μετά από επιτυχή εγγραφή (το@PersistedWriteτο καλεί αυτόματα).
Κανόνες τιμών (Value rules)
Ενότητα με τίτλο «Κανόνες τιμών (Value rules)»Τα textRule(options) και numberRule(options) ορίζουν τον κανόνα για ένα πεδίο μία φορά. Το aggregate χρησιμοποιεί το parse(value) του κανόνα για την κανονικοποίηση, και τα υπόλοιπα layers διαβάζουν τα όρια του κανόνα ώστε το schema αιτήματος να μην αποκλίνει από το domain:
Το parse(value) επιστρέφει την κανονικοποιημένη τιμή ή ρίχνει το σφάλμα του κανόνα. Είναι ανεξάρτητη συνάρτηση και ο κανόνας είναι παγωμένος (frozen).
Επιλογή textRule |
Αποτέλεσμα |
|---|---|
field |
Όνομα που αναφέρεται στην παραβίαση και στο προεπιλεγμένο μήνυμα |
required |
Με false κανονικοποιεί τα null, undefined και κενό κείμενο σε null. Εξ ορισμού απορρίπτονται |
minLength, maxLength |
Μήκος μετά την κανονικοποίηση, σε UTF-16 code units |
pattern |
Regular expression στο οποίο πρέπει να ταιριάζει το κείμενο (flags g ή y απορρίπτονται) |
multiline |
Με true δέχεται tab, line feed και carriage return μέσα στο κείμενο |
error |
Κατασκευάζει το error για την παραβίαση (προεπιλογή: InvalidValueException) |
Το κείμενο ελέγχεται ως προς τον τύπο και τα μη ζευγαρωμένα surrogates, μετατρέπεται σε μορφή Unicode NFC και αφαιρούνται τα κενά στα άκρα (trimmed). Χαρακτήρες ελέγχου απορρίπτονται πάντοτε.
Επιλογή numberRule |
Αποτέλεσμα |
|---|---|
field, required, error |
Όπως στο textRule (required: false δέχεται null και undefined) |
integer |
Δέχεται μόνο ασφαλείς ακέραιους (safe integers) |
min, max |
Συμπεριληπτικά όρια εύρους (inclusive bounds) |
Ένας αριθμός πρέπει να είναι τύπου number και πεπερασμένος (finite). Αριθμητικά strings απορρίπτονται. Μια παραβίαση κανόνα ρίχνει error(violation). Το violation είναι ένα παγωμένο ValueViolation: { field, rule }, συν limit για κανόνες μήκους/εύρους και expected για κανόνες τύπου.
Domain events
Ενότητα με τίτλο «Domain events»Ένα domain event επεκτείνει το RootDomainEvent<TEntity, TPayload>. Φέρει UUIDv7 id, τα aggregateId και aggregateVersion κατά τον χρόνο του συμβάντος, και το payload: ένα βαθύ αντίγραφο (deep clone) του toJSON() του aggregate, αναδρομικά παγωμένο (recursively frozen).
- Αποσυνδεδεμένο (Detached): Μεταγενέστερες αλλαγές στο aggregate δεν επηρεάζουν ποτέ το
payload. - Read-only για συνήθη χρήση: Τα ίδια properties είναι frozen, και οι μεταλλάσσουσες μέθοδοι των κλωνοποιημένων
Date,MapκαιSetτιμών ρίχνουν σφάλμα. - Όχι όριο ασφαλείας: Το
Object.freezeδεν καλύπτει εσωτερική κατάσταση native αντικειμένων, και όλοι οι καταναλωτές ενός event μοιράζονται το ίδιοpayload. Τοevent.clonePayload()επιστρέφει ένα νέο αντίγραφο ανά κλήση όταν ένας consumer χρειάζεται αυτόνομο αντίγραφο. - Όχι transport format: Για διαμοιρασμό μέσω δικτύου, στείλτε ένα ρητό, serializable μήνυμα κατασκευασμένο από τα απαραίτητα πεδία.
Η συνάρτηση deepCloneAndFreeze(value) υποστηρίζει αντικείμενα, πίνακες, Date, Map, Set, RegExp και κυκλικές αναφορές.
Commands και δημοσίευση events
Ενότητα με τίτλο «Commands και δημοσίευση events»Τα BaseCommand και BaseQuery είναι βασικές κλάσεις για αντικείμενα command και query. Το BaseCommand διατηρεί ένα προαιρετικό sessionPrincipal εκτός enumeration και toJSON(). Το getUpdateFields(fields) επιστρέφει τα πεδία που περιλαμβάνει το command για field-level authorization.
Το CommandBaseHandler εκτελεί ένα command και δημοσιεύει τα events του aggregate που επιστρέφει:
- Το
handle()επιστρέφει το aggregate, ή αποτέλεσμα που το περιέχει ωςaggregate. Τοexecute()το καλεί, δημοσιεύει τα buffered events μία φορά με τοeventBus.publishAll(events, aggregate), καθαρίζει το buffer και επιστρέφει το αποτέλεσμα αναλλοίωτο. - Ένα αποτυχημένο
handle()δεν δημοσιεύει τίποτα. Αν τοpublishAll()αποτύχει, το σφάλμα διαδίδεται και τα events παραμένουν στο buffer. - Αν το
publishAll()επιστρέφει promise, τοexecute()το αναμένει αφού καθαρίσει το buffer. - Οποιοδήποτε αντικείμενο με μέθοδο
publishAll(events)ικανοποιεί τοIDomainEventPublisher.
Το AggregateRoot.commit() δεν δημοσιεύει τίποτα εξ ορισμού. Αφήστε το CommandBaseHandler να δημοσιεύσει, ή διαβάστε το getUncommittedEvents() και καλέστε το uncommit() χειροκίνητα.
Write-side repositories
Ενότητα με τίτλο «Write-side repositories»Ένας command handler φορτώνει το έγκυρο aggregate μέσω του IWriteSideAggregateRepository<TEntity>.findById(id): οφείλει να διαβάζει την πρωτεύουσα αποθήκευση και ποτέ cache. Το AggregateRepository του @cqrs-ddd/mikro-orm το υλοποιεί για το MikroORM.
Η μέθοδος save() δηλώνει τον κύκλο ζωής της με το @PersistedWrite:
Το @PersistedWrite συνδυάζει τρεις decorators με αυστηρή σειρά:
@Cache(options): Μετά από επιτυχή εγγραφή, γράφει το snapshot μέσω CAS (isCacheNewer) και τοποθετεί barriers για ταinvalidateKeys. Όταν τοsave()επιστρέφειnullήundefined, τοποθετεί barriers για ταdeleteKeys.@AcknowledgePersisted: Προωθεί το persisted version του επιλεγμένου aggregate μόνο μετά από επιτυχή εγγραφή.@MapPersistenceErrors: Μεταφράζει παραβιάσεις μοναδικότητας (unique constraints) σε domain σφάλματα μέσω του ενεργού persistence dialect.
Για διαγραφές (deletes), χρησιμοποιούνται μόνο τα @Cache και @MapPersistenceErrors:
Read-side repositories
Ενότητα με τίτλο «Read-side repositories»Ένα query repository επεκτείνει το QueryRepository και διακοσμεί το find() με το @FromCache:
- Κάθε hit επαναϋδατώνεται (rehydrated) μέσω του hydrator, διασφαλίζοντας ότι hit και miss επιστρέφουν τον ίδιο τύπο.
- Χωρίς hydrator αποθηκεύονται μόνο plain data.
- Αποθηκεύονται μόνο μη-nullish αποτελέσματα. Ένα barrier ή αποθηκευμένο
nullμετρά ως miss. - Ένα query με
refresh: trueπαρακάμπτει την cache.
Το repository cache
Ενότητα με τίτλο «Το repository cache»Το @Cache λειτουργεί με οποιοδήποτε ICache (get, set, delete). Το @FromCache απαιτεί IVersionedCache, το οποίο προσθέτει revision fence:
| Μέθοδος | Συμβόλαιο |
|---|---|
readState(key) |
η κατάσταση της εγγραφής (hit, miss, expired), η τιμή και το revision |
invalidate(key) |
ακυρώνει την τιμή και προωθεί το revision |
tryFill(key, observedRevision, value, options?) |
γράφει μόνο αν το revision παραμένει observedRevision, αλλιώς false |
Το @FromCache καταγράφει το revision πριν την ανάγνωση από τη βάση και γεμίζει την cache με tryFill, αποτρέποντας την εγγραφή παρωχημένου snapshot όταν μια ανάγνωση συναγωνίστηκε με invalidation ή διαγραφή. Ένας adapter που υλοποιεί μόνο ICache παρακάμπτεται από το @FromCache τόσο για αναγνώσεις όσο και για fills, καταγράφοντας σχετική προειδοποίηση.
Υλοποιήσεις του IVersionedCache:
MemoryCache({ defaultTtlMs = 60_000, maxEntries = 10_000 }): in-process cache με JSON κλωνοποίηση, ιδανική για tests.MikroOrmCacheστο@cqrs-ddd/mikro-orm: μία γραμμή βάσης ανά κλειδί, με compare-and-set σε δικό του transaction.
Τα mutation barriers (CacheMutationBarrier) σηματοδοτούν ένα διαγραμμένο ή ακυρωμένο κλειδί για διάστημα barrierTtl (60 δευτερόλεπτα εξ ορισμού).
Cache keys διαχωρισμένα ανά tenant
Ενότητα με τίτλο «Cache keys διαχωρισμένα ανά tenant»Τα cacheKey(resource, conditions, tenant?) και cacheKeyTemplate(template, tenant?) οργανώνουν κάθε κλειδί ανά tenant. Το tenant προέρχεται κατά σειρά από:
- Το ρητό όρισμα
tenant(string ή αντικείμενο μεtenantId), - Για το
cacheKeyTemplate, τοtenantIdτης πηγής context, - Τον resolver που καταχωρεί η εφαρμογή στην εκκίνηση με το
setTenantResolver(fn), - Αλλιώς, ρίχνεται
MissingTenantContextError.
Δεν υπάρχει κοινόχρηστο namespace: ένα ελλείπον tenant ρίχνει σφάλμα. Η ίδια επίλυση είναι διαθέσιμη μέσω του requireTenant(purpose, source?):
Αντιστοίχιση HTTP status
Ενότητα με τίτλο «Αντιστοίχιση HTTP status»Η συνάρτηση domainErrorHttpStatus(error) από το /http αντιστοιχίζει τα σφάλματα αυτού του πακέτου σε τιμές { statusCode, error, message }:
| Σφάλμα (Error) | Status |
|---|---|
ConcurrencyConflictError |
409 |
EntityNotFoundException |
404 |
MissingTenantContextError |
500, με γενικό μήνυμα (αίτημα χωρίς tenant είναι server fault) |
οποιοδήποτε άλλο DomainException, συμπεριλαμβανομένου του InvalidValueException |
400 |
Επιστρέφει undefined για οτιδήποτε άλλο.
Γνωστοί περιορισμοί
Ενότητα με τίτλο «Γνωστοί περιορισμοί»- Η διατήρηση στη βάση και η δημοσίευση events δεν είναι ατομικές ενέργειες. Μια διακοπή μεταξύ της εγγραφής και του
publishAll()χάνει τα events. Η αξιόπιστη παράδοση απαιτεί transactional outbox. - Η συντήρηση της cache μετά το commit είναι best-effort. Αν ένα invalidation αποτύχει, η προηγούμενη εγγραφή παραμένει μέχρι να λήξει.
- Ένα mutation barrier προστατεύει μόνο για τη διάρκεια του
barrierTtl. - Οι persistence helpers απορρίπτουν εξωτερικά transactions. Μια εγγραφή που πρέπει να γίνει commit μαζί με το aggregate δεν μπορεί να μοιραστεί το transaction του.
- Το
@MapPersistenceErrorsαντιστοιχίζει μοναδικά σφάλματα στον βαθμό που το υποστηρίζει το δηλωμένο dialect (τοMikroOrmDialectκαλύπτει PostgreSQL και SQLite). - Ο tenant resolver είναι process-wide.
Άδεια χρήσης
Ενότητα με τίτλο «Άδεια χρήσης»Διπλή άδεια υπό AGPL-3.0-or-later ή Commercial License. Δείτε τα
LICENSE και COMMERCIAL_LICENSE.txt
στη ρίζα του repository.