@cqrs-ddd/core 0.2.0

package/dist/persistence/cache/memory.cache.d.ts

@@ -0,0 +1,72 @@
+import type { CacheFillOptions, CacheSetOptions, CacheStateEntry, IVersionedCache } from '../../application/ports/cache.port';
+export declare const CACHE_TOKEN: unique symbol;
+export type MemoryCacheSetOptions = CacheSetOptions;
+/**
+ * Upper bound on retained keys, including revision-only entries.
+ */
+export declare const DEFAULT_MAX_ENTRIES = 10000;
+/**
+ * In-memory implementation of {@link IVersionedCache} maintaining deep detachment parity
+ * with database/network caches via JSON cloning on both `set()` and `get()`.
+ *
+ * Implements revision-fenced coordination:
+ * - Every write and invalidation takes the next value of one cache-wide counter.
+ * - Retains coordination metadata on payload expiry to prevent ABA stale fills.
+ * - An absent key reports the absence revision, which advances to the counter
+ *   whenever an entry is evicted or the cache is cleared, so dropping a key's
+ *   metadata never returns it to a revision a reader observed before the drop.
+ */
+export declare class MemoryCache<T> implements IVersionedCache<T> {
+    readonly isVersioned: true;
+    private store;
+    private lastRevision;
+    private absentRevision;
+    private readonly defaultTtlMs;
+    private readonly maxEntries;
+    constructor(options?: {
+        defaultTtlMs?: number;
+        maxEntries?: number;
+    });
+    private nextRevision;
+    /**
+     * Drops expired entries, then the oldest surviving ones until the store fits.
+     */
+    private evict;
+    /**
+     * Observes current key state and opaque revision token.
+     */
+    readState(key: string): Promise<CacheStateEntry<T>>;
+    /**
+     * Atomically advances the key revision and removes the value.
+     */
+    invalidate(key: string): Promise<string>;
+    /**
+     * Atomically checks that current revision matches `observedRevision`, writes
+     * value, and advances revision on match.
+     */
+    tryFill(key: string, observedRevision: string, value: T, options?: CacheFillOptions): Promise<boolean>;
+    /**
+     * Stores a value in memory, cloning it via JSON round-trip to guarantee detachment.
+     * Enforces TTL expiration and optional atomic CAS stale-write protection (`isNewer`).
+     */
+    set(key: string, value: T, options?: MemoryCacheSetOptions): Promise<void>;
+    private write;
+    /**
+     * Retrieves a cached value, checking TTL and returning a detached clone.
+     */
+    get(key: string): Promise<T | undefined>;
+    /**
+     * Removes the value and advances the key's revision, as invalidate() does.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Purges all keys from the in-memory cache. Every revision observed before
+     * the purge, including an observed absence, is rejected by a later `tryFill`.
+     */
+    clear(): Promise<void>;
+    /**
+     * Current number of keys in the in-memory cache.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=memory.cache.d.ts.map

package/dist/persistence/cache/memory.cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.cache.d.ts","sourceRoot":"","sources":["../../../persistence/cache/memory.cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAE5C,eAAO,MAAM,WAAW,eAAwB,CAAC;AAEjD,MAAM,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AA6B1C;;;;;;;;;;GAUG;AACH,qBAAa,WAAW,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,WAAW,EAAG,IAAI,CAAU;IAErC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,cAAc,CAAM;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,CAAC,EAAE;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;IAKD,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,KAAK;IAmBb;;OAEG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAoBzD;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAc9C;;;OAGG;IACG,OAAO,CACX,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC;IAcnB;;;OAGG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC;IAahB,OAAO,CAAC,KAAK;IAoBb;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAU9C;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/persistence/cache/memory.cache.js

@@ -0,0 +1,183 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCache = exports.DEFAULT_MAX_ENTRIES = exports.CACHE_TOKEN = void 0;
+exports.CACHE_TOKEN = Symbol('MemoryCache');
+/**
+ * Upper bound on retained keys, including revision-only entries.
+ */
+exports.DEFAULT_MAX_ENTRIES = 10_000;
+function detach(value) {
+    if (value === undefined || value === null || typeof value !== 'object') {
+        return value;
+    }
+    return JSON.parse(JSON.stringify(value));
+}
+function isExpired(entry, now = Date.now()) {
+    return entry.expiresAt !== undefined && now > entry.expiresAt;
+}
+function clearValue(entry) {
+    entry.hasValue = false;
+    entry.value = undefined;
+    entry.expiresAt = undefined;
+}
+/**
+ * In-memory implementation of {@link IVersionedCache} maintaining deep detachment parity
+ * with database/network caches via JSON cloning on both `set()` and `get()`.
+ *
+ * Implements revision-fenced coordination:
+ * - Every write and invalidation takes the next value of one cache-wide counter.
+ * - Retains coordination metadata on payload expiry to prevent ABA stale fills.
+ * - An absent key reports the absence revision, which advances to the counter
+ *   whenever an entry is evicted or the cache is cleared, so dropping a key's
+ *   metadata never returns it to a revision a reader observed before the drop.
+ */
+class MemoryCache {
+    isVersioned = true;
+    store = new Map();
+    lastRevision = 0n;
+    absentRevision = 0n;
+    defaultTtlMs;
+    maxEntries;
+    constructor(options) {
+        this.defaultTtlMs = options?.defaultTtlMs ?? 60_000;
+        this.maxEntries = options?.maxEntries ?? exports.DEFAULT_MAX_ENTRIES;
+    }
+    nextRevision() {
+        this.lastRevision += 1n;
+        return this.lastRevision;
+    }
+    /**
+     * Drops expired entries, then the oldest surviving ones until the store fits.
+     */
+    evict() {
+        if (this.store.size <= this.maxEntries)
+            return;
+        // Invalidate every token observed before the drop, including absences
+        this.absentRevision = this.lastRevision;
+        const now = Date.now();
+        for (const [key, entry] of this.store) {
+            if (isExpired(entry, now)) {
+                this.store.delete(key);
+            }
+        }
+        for (const key of this.store.keys()) {
+            if (this.store.size <= this.maxEntries)
+                break;
+            this.store.delete(key);
+        }
+    }
+    /**
+     * Observes current key state and opaque revision token.
+     */
+    async readState(key) {
+        const entry = this.store.get(key);
+        if (!entry) {
+            return { status: 'miss', revision: this.absentRevision.toString() };
+        }
+        if (entry.hasValue) {
+            if (isExpired(entry)) {
+                return { status: 'expired', revision: entry.revision.toString() };
+            }
+            return {
+                status: 'hit',
+                value: detach(entry.value),
+                revision: entry.revision.toString(),
+            };
+        }
+        return { status: 'miss', revision: entry.revision.toString() };
+    }
+    /**
+     * Atomically advances the key revision and removes the value.
+     */
+    async invalidate(key) {
+        const existing = this.store.get(key);
+        const revision = this.nextRevision();
+        if (existing) {
+            existing.revision = revision;
+            clearValue(existing);
+            return revision.toString();
+        }
+        this.store.set(key, { revision, hasValue: false });
+        this.evict();
+        return revision.toString();
+    }
+    /**
+     * Atomically checks that current revision matches `observedRevision`, writes
+     * value, and advances revision on match.
+     */
+    async tryFill(key, observedRevision, value, options) {
+        const existing = this.store.get(key);
+        const currentRevision = (existing ? existing.revision : this.absentRevision).toString();
+        if (currentRevision !== observedRevision) {
+            return false;
+        }
+        this.write(key, value, options, existing);
+        return true;
+    }
+    /**
+     * Stores a value in memory, cloning it via JSON round-trip to guarantee detachment.
+     * Enforces TTL expiration and optional atomic CAS stale-write protection (`isNewer`).
+     */
+    async set(key, value, options) {
+        const existing = this.store.get(key);
+        if (existing?.hasValue) {
+            if (isExpired(existing)) {
+                clearValue(existing);
+            }
+            else if (options?.isNewer?.(existing.value, value)) {
+                return;
+            }
+        }
+        this.write(key, value, options, existing);
+    }
+    write(key, value, options, existing) {
+        const ttl = options?.ttl ?? this.defaultTtlMs;
+        const entry = {
+            revision: this.nextRevision(),
+            value: detach(value),
+            expiresAt: ttl > 0 ? Date.now() + ttl : undefined,
+            hasValue: true,
+        };
+        if (existing)
+            Object.assign(existing, entry);
+        else
+            this.store.set(key, entry);
+        this.evict();
+    }
+    /**
+     * Retrieves a cached value, checking TTL and returning a detached clone.
+     */
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry?.hasValue)
+            return undefined;
+        if (isExpired(entry)) {
+            clearValue(entry);
+            return undefined;
+        }
+        return detach(entry.value);
+    }
+    /**
+     * Removes the value and advances the key's revision, as invalidate() does.
+     */
+    async delete(key) {
+        await this.invalidate(key);
+    }
+    /**
+     * Purges all keys from the in-memory cache. Every revision observed before
+     * the purge, including an observed absence, is rejected by a later `tryFill`.
+     */
+    async clear() {
+        this.absentRevision = this.nextRevision();
+        this.store.clear();
+    }
+    /**
+     * Current number of keys in the in-memory cache.
+     */
+    get size() {
+        return this.store.size;
+    }
+}
+exports.MemoryCache = MemoryCache;
+//# sourceMappingURL=memory.cache.js.map

package/dist/persistence/cache/memory.cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.cache.js","sourceRoot":"","sources":["../../../persistence/cache/memory.cache.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AASzD,QAAA,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;AAIjD;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC;AAE1C,SAAS,MAAM,CAAI,KAAQ;IACzB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAM,CAAC;AAChD,CAAC;AASD,SAAS,SAAS,CAChB,KAAgC,EAChC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAEhB,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC;AAChE,CAAC;AAED,SAAS,UAAU,CAAC,KAAgC;IAClD,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;IACxB,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAa,WAAW;IACb,WAAW,GAAG,IAAa,CAAC;IAE7B,KAAK,GAAqC,IAAI,GAAG,EAAE,CAAC;IACpD,YAAY,GAAG,EAAE,CAAC;IAClB,cAAc,GAAG,EAAE,CAAC;IACX,YAAY,CAAS;IACrB,UAAU,CAAS;IAEpC,YAAY,OAGX;QACC,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,MAAM,CAAC;QACpD,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,2BAAmB,CAAC;IAC/D,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED;;OAEG;IACK,KAAK;QACX,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAE/C,sEAAsE;QACtE,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,YAAY,CAAC;QAExC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU;gBAAE,MAAM;YAC9C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,GAAW;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,CAAC;QACtE,CAAC;QAED,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;YACpE,CAAC;YACD,OAAO;gBACL,MAAM,EAAE,KAAK;gBACb,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;gBAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE;aACpC,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;IACjE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,GAAW;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QACrC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAC7B,UAAU,CAAC,QAAQ,CAAC,CAAC;YACrB,OAAO,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC7B,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CACX,GAAW,EACX,gBAAwB,EACxB,KAAQ,EACR,OAA0B;QAE1B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,eAAe,GAAG,CACtB,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CACnD,CAAC,QAAQ,EAAE,CAAC;QAEb,IAAI,eAAe,KAAK,gBAAgB,EAAE,CAAC;YACzC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CACP,GAAW,EACX,KAAQ,EACR,OAA+B;QAE/B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,QAAQ,EAAE,QAAQ,EAAE,CAAC;YACvB,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxB,UAAU,CAAC,QAAQ,CAAC,CAAC;YACvB,CAAC;iBAAM,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;gBACrD,OAAO;YACT,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAEO,KAAK,CACX,GAAW,EACX,KAAQ,EACR,OAAqC,EACrC,QAAyC;QAEzC,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC;QAC9C,MAAM,KAAK,GAAwB;YACjC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE;YAC7B,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;YACpB,SAAS,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS;YACjD,QAAQ,EAAE,IAAI;SACf,CAAC;QAEF,IAAI,QAAQ;YAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;;YACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAEhC,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,QAAQ;YAAE,OAAO,SAAS,CAAC;QACvC,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,UAAU,CAAC,KAAK,CAAC,CAAC;YAClB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAvLD,kCAuLC"}

package/dist/persistence/command-repository.abstract.d.ts

@@ -0,0 +1,39 @@
+import { ICache } from '../application/ports/cache.port';
+import { ICommandRepository } from '../application/ports/command-repository.port';
+/**
+ * Base class for write-side (command) repositories.
+ *
+ * Persists an entity or aggregate state via the abstract {@link save} method and receives an
+ * {@link ICache} instance. Subclasses annotate `save()` with the `@Cache` decorator
+ * to perform automatic write-through caching or cache eviction upon mutation.
+ *
+ * @typeParam TEntity - The aggregate entity type accepted by {@link save}.
+ * @typeParam TResult - The persisted result type returned by {@link save}.
+ *
+ * @example Creating a command repository with @Cache
+ * ```typescript
+ * @Injectable()
+ * export class CreateUserCommandRepository extends CommandRepository<User, UserSnapshot> {
+ *   constructor(
+ *     @Inject(CACHE_TOKEN) protected readonly cache: ICache<UserSnapshot>,
+ *     @Inject(MIKRO_ORM_CLIENT) private readonly store: MikroOrmStore,
+ *   ) {
+ *     super(cache);
+ *   }
+ *
+ *   @Cache<User, UserSnapshot>(
+ *     (user) => cacheKey(User.aggregateName, { id: user.id }),
+ *   )
+ *   async save(user: User): Promise<UserSnapshot> {
+ *     const created = await this.store.em.upsert(User, user);
+ *     return created.toJSON();
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class CommandRepository<TEntity = unknown, TResult = unknown | null, TCache = unknown> implements ICommandRepository<TEntity, TResult> {
+    protected readonly cache: ICache<TCache>;
+    constructor(cache: ICache<TCache>);
+    abstract save(entity: TEntity): Promise<TResult | null>;
+}
+//# sourceMappingURL=command-repository.abstract.d.ts.map

package/dist/persistence/command-repository.abstract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-repository.abstract.d.ts","sourceRoot":"","sources":["../../persistence/command-repository.abstract.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,8BAAsB,iBAAiB,CACrC,OAAO,GAAG,OAAO,EACjB,OAAO,GAAG,OAAO,GAAG,IAAI,EACxB,MAAM,GAAG,OAAO,CAChB,YAAW,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC;IAEnC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;gBAArB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;IAEpD,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;CACxD"}

package/dist/persistence/command-repository.abstract.js

@@ -0,0 +1,43 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandRepository = void 0;
+/**
+ * Base class for write-side (command) repositories.
+ *
+ * Persists an entity or aggregate state via the abstract {@link save} method and receives an
+ * {@link ICache} instance. Subclasses annotate `save()` with the `@Cache` decorator
+ * to perform automatic write-through caching or cache eviction upon mutation.
+ *
+ * @typeParam TEntity - The aggregate entity type accepted by {@link save}.
+ * @typeParam TResult - The persisted result type returned by {@link save}.
+ *
+ * @example Creating a command repository with @Cache
+ * ```typescript
+ * @Injectable()
+ * export class CreateUserCommandRepository extends CommandRepository<User, UserSnapshot> {
+ *   constructor(
+ *     @Inject(CACHE_TOKEN) protected readonly cache: ICache<UserSnapshot>,
+ *     @Inject(MIKRO_ORM_CLIENT) private readonly store: MikroOrmStore,
+ *   ) {
+ *     super(cache);
+ *   }
+ *
+ *   @Cache<User, UserSnapshot>(
+ *     (user) => cacheKey(User.aggregateName, { id: user.id }),
+ *   )
+ *   async save(user: User): Promise<UserSnapshot> {
+ *     const created = await this.store.em.upsert(User, user);
+ *     return created.toJSON();
+ *   }
+ * }
+ * ```
+ */
+class CommandRepository {
+    cache;
+    constructor(cache) {
+        this.cache = cache;
+    }
+}
+exports.CommandRepository = CommandRepository;
+//# sourceMappingURL=command-repository.abstract.js.map

package/dist/persistence/command-repository.abstract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-repository.abstract.js","sourceRoot":"","sources":["../../persistence/command-repository.abstract.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAKtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAsB,iBAAiB;IAMN;IAA/B,YAA+B,KAAqB;QAArB,UAAK,GAAL,KAAK,CAAgB;IAAG,CAAC;CAGzD;AATD,8CASC"}

package/dist/persistence/decorators/acknowledge-persisted.decorator.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Contract required for aggregates to participate in persistence version acknowledgment.
+ *
+ * Implemented automatically by {@link RootEntity}.
+ */
+export interface PersistedAggregate {
+    /** The current in-memory aggregate version. */
+    readonly version?: number;
+    /**
+     * Advances the persisted version baseline (`_persistedVersion`) to match
+     * the durable version written to persistent storage.
+     */
+    acknowledgePersisted(version?: number): void;
+}
+/**
+ * Method decorator that guarantees an aggregate's persisted version baseline is updated
+ * upon successful completion of a repository write operation.
+ *
+ * ### Lifecycle Semantics
+ * 1. **Argument Selection**: Extracts the aggregate from method arguments via `options.entity(args)`.
+ *    Argument positions are never hardcoded or assumed.
+ * 2. **Version Capture**: Captures `const version = entity.version` before awaiting the method.
+ * 3. **Execution**: Invokes the wrapped persistence method (e.g. `save(entity)`).
+ * 4. **Acknowledgment on Success**: If the promise resolves, invokes `entity.acknowledgePersisted(version)`
+ *    to align `_persistedVersion` with the newly written durable version.
+ * 5. **Preserved Baseline on Failure**: If the promise rejects (due to concurrency conflict, unique constraint,
+ *    or connection error), `acknowledgePersisted()` is skipped, leaving `getExpectedVersion()` at its previous baseline.
+ *
+ * ### Canonical Decorator Ordering
+ * Always stack decorators in this outermost-to-innermost order:
+ * 1. `@Cache(...)` — Best-effort cache synchronization after acknowledgment.
+ * 2. `@AcknowledgePersisted(...)` — Acknowledges version baseline on successful write.
+ * 3. `@MapPersistenceErrors(...)` — Translates low-level DB driver errors to domain exceptions.
+ *
+ * > [!IMPORTANT]
+ * > This decorator assumes an autocommitted persistence operation where promise resolution means
+ * > durable storage commit. Externally managed transactions require transaction commit-hook contracts,
+ * > not method decorators.
+ *
+ * @param options Configuration object with an `entity` extractor function over the method's argument tuple.
+ *
+ * @example Usage in an update command repository
+ * ```typescript
+ * @Injectable()
+ * export class UpdateRoleCommandRepository extends CommandRepository<Role, RoleSnapshot> {
+ *   @Cache<Role, RoleSnapshot>((role) => `roles:${role.id}`)
+ *   @AcknowledgePersisted<[Role]>({ entity: ([role]) => role })
+ *   @MapPersistenceErrors<[Role], Role>({
+ *     entity: ([role]) => role,
+ *     unique: [{ constraint: 'roles_name_unique', columns: 'roles.name', error: (r) => new UniqueRoleNameException(r) }],
+ *   })
+ *   async save(role: Role): Promise<RoleSnapshot> {
+ *     const snapshot = role.toJSON();
+ *     await optimisticUpdate(this.store.em, Role, role, { name: snapshot.name }, 'Role');
+ *     return snapshot;
+ *   }
+ * }
+ * ```
+ *
+ * @example Usage in a create command repository
+ * ```typescript
+ * @Injectable()
+ * export class CreateRoleCommandRepository extends CommandRepository<Role, RoleSnapshot> {
+ *   @Cache<Role, RoleSnapshot>((role) => `roles:${role.id}`)
+ *   @AcknowledgePersisted<[Role]>({ entity: ([role]) => role })
+ *   @MapPersistenceErrors<[Role], Role>({
+ *     entity: ([role]) => role,
+ *     unique: [{ constraint: 'roles_name_unique', columns: 'roles.name', error: (r) => new UniqueRoleNameException(r) }],
+ *   })
+ *   async save(role: Role): Promise<RoleSnapshot> {
+ *     const created = this.store.em.create(Role, role);
+ *     this.store.em.persist(created);
+ *     await this.store.em.flush();
+ *     return created.toJSON();
+ *   }
+ * }
+ * ```
+ */
+export declare function AcknowledgePersisted<TArgs extends unknown[]>(options: {
+    entity: (args: TArgs) => PersistedAggregate;
+}): <TResult>(_target: object, _key: string | symbol, descriptor: TypedPropertyDescriptor<(...args: TArgs) => Promise<TResult>>) => void;
+//# sourceMappingURL=acknowledge-persisted.decorator.d.ts.map

package/dist/persistence/decorators/acknowledge-persisted.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acknowledge-persisted.decorator.d.ts","sourceRoot":"","sources":["../../../persistence/decorators/acknowledge-persisted.decorator.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,oBAAoB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAAE;IACrE,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,kBAAkB,CAAC;CAC7C,IACS,OAAO,EACb,SAAS,MAAM,EACf,MAAM,MAAM,GAAG,MAAM,EACrB,YAAY,uBAAuB,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,KACxE,IAAI,CAYR"}

package/dist/persistence/decorators/acknowledge-persisted.decorator.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AcknowledgePersisted = AcknowledgePersisted;
+/**
+ * Method decorator that guarantees an aggregate's persisted version baseline is updated
+ * upon successful completion of a repository write operation.
+ *
+ * ### Lifecycle Semantics
+ * 1. **Argument Selection**: Extracts the aggregate from method arguments via `options.entity(args)`.
+ *    Argument positions are never hardcoded or assumed.
+ * 2. **Version Capture**: Captures `const version = entity.version` before awaiting the method.
+ * 3. **Execution**: Invokes the wrapped persistence method (e.g. `save(entity)`).
+ * 4. **Acknowledgment on Success**: If the promise resolves, invokes `entity.acknowledgePersisted(version)`
+ *    to align `_persistedVersion` with the newly written durable version.
+ * 5. **Preserved Baseline on Failure**: If the promise rejects (due to concurrency conflict, unique constraint,
+ *    or connection error), `acknowledgePersisted()` is skipped, leaving `getExpectedVersion()` at its previous baseline.
+ *
+ * ### Canonical Decorator Ordering
+ * Always stack decorators in this outermost-to-innermost order:
+ * 1. `@Cache(...)` — Best-effort cache synchronization after acknowledgment.
+ * 2. `@AcknowledgePersisted(...)` — Acknowledges version baseline on successful write.
+ * 3. `@MapPersistenceErrors(...)` — Translates low-level DB driver errors to domain exceptions.
+ *
+ * > [!IMPORTANT]
+ * > This decorator assumes an autocommitted persistence operation where promise resolution means
+ * > durable storage commit. Externally managed transactions require transaction commit-hook contracts,
+ * > not method decorators.
+ *
+ * @param options Configuration object with an `entity` extractor function over the method's argument tuple.
+ *
+ * @example Usage in an update command repository
+ * ```typescript
+ * @Injectable()
+ * export class UpdateRoleCommandRepository extends CommandRepository<Role, RoleSnapshot> {
+ *   @Cache<Role, RoleSnapshot>((role) => `roles:${role.id}`)
+ *   @AcknowledgePersisted<[Role]>({ entity: ([role]) => role })
+ *   @MapPersistenceErrors<[Role], Role>({
+ *     entity: ([role]) => role,
+ *     unique: [{ constraint: 'roles_name_unique', columns: 'roles.name', error: (r) => new UniqueRoleNameException(r) }],
+ *   })
+ *   async save(role: Role): Promise<RoleSnapshot> {
+ *     const snapshot = role.toJSON();
+ *     await optimisticUpdate(this.store.em, Role, role, { name: snapshot.name }, 'Role');
+ *     return snapshot;
+ *   }
+ * }
+ * ```
+ *
+ * @example Usage in a create command repository
+ * ```typescript
+ * @Injectable()
+ * export class CreateRoleCommandRepository extends CommandRepository<Role, RoleSnapshot> {
+ *   @Cache<Role, RoleSnapshot>((role) => `roles:${role.id}`)
+ *   @AcknowledgePersisted<[Role]>({ entity: ([role]) => role })
+ *   @MapPersistenceErrors<[Role], Role>({
+ *     entity: ([role]) => role,
+ *     unique: [{ constraint: 'roles_name_unique', columns: 'roles.name', error: (r) => new UniqueRoleNameException(r) }],
+ *   })
+ *   async save(role: Role): Promise<RoleSnapshot> {
+ *     const created = this.store.em.create(Role, role);
+ *     this.store.em.persist(created);
+ *     await this.store.em.flush();
+ *     return created.toJSON();
+ *   }
+ * }
+ * ```
+ */
+function AcknowledgePersisted(options) {
+    return (_target, _key, descriptor) => {
+        const original = descriptor.value;
+        if (typeof original !== 'function')
+            throw new TypeError('Persistence decorators require a method.');
+        descriptor.value = async function (...args) {
+            const entity = options.entity(args);
+            const version = entity.version;
+            const result = await original.apply(this, args);
+            entity.acknowledgePersisted(version);
+            return result;
+        };
+    };
+}
+//# sourceMappingURL=acknowledge-persisted.decorator.js.map

package/dist/persistence/decorators/acknowledge-persisted.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acknowledge-persisted.decorator.js","sourceRoot":"","sources":["../../../persistence/decorators/acknowledge-persisted.decorator.ts"],"names":[],"mappings":";;AAgFA,oDAmBC;AAnFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,SAAgB,oBAAoB,CAA0B,OAE7D;IACC,OAAO,CACL,OAAe,EACf,IAAqB,EACrB,UAAyE,EACnE,EAAE;QACR,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;QAClC,IAAI,OAAO,QAAQ,KAAK,UAAU;YAChC,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;QAClE,UAAU,CAAC,KAAK,GAAG,KAAK,WAAW,GAAG,IAAW;YAC/C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;YAC/B,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAChD,MAAM,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;YACrC,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/persistence/decorators/cache.decorator.d.ts

@@ -0,0 +1,93 @@
+import type { ICacheLogger } from '../cache/cache-logger';
+/**
+ * Options for configuring write-through and eviction caching via {@link Cache}.
+ */
+export interface CacheOptions<TEntity = unknown> {
+    /**
+     * Function deriving the cache key to write on success.
+     * Pass `null` or omit to skip write-through caching.
+     */
+    setKey?: ((entity: TEntity) => string) | null;
+    /**
+     * Function deriving keys to evict when `save()` returns `null` or `undefined` (e.g. deletion).
+     */
+    deleteKeys?: ((entity: TEntity) => string[]) | null;
+    /**
+     * Optional secondary keys to evict on every successful save before writing the new entry.
+     */
+    invalidateKeys?: ((entity: TEntity) => string[]) | null;
+    /**
+     * Optional time-to-live in milliseconds for the write-through cache entry.
+     */
+    ttl?: number;
+    /**
+     * Optional version comparison function for CAS-safe write-through caching.
+     * If omitted, defaults to {@link isCacheNewer} which compares `version`, `__gen`, or `updatedAt`.
+     * Pass `null` to skip the isNewer comparison.
+     */
+    isNewer?: ((cached: unknown, incoming: unknown) => boolean) | null;
+    /**
+     * Lifetime in milliseconds of the {@link CacheMutationBarrier} written on
+     * deletions and secondary invalidations.
+     *
+     * A barrier only has to outlive the in-flight reads/writes it guards against,
+     * so configure this above the expected maximum repository operation latency.
+     * Ignored by {@link IVersionedCache} adapters, which fence concurrent fills by
+     * revision instead of by barrier.
+     *
+     * @default {@link DEFAULT_BARRIER_TTL_MS}
+     */
+    barrierTtl?: number;
+    /**
+     * Receives cache-maintenance warnings. Defaults to `console.warn` with a
+     * `[CacheDecorator]` prefix. See {@link ICacheLogger}.
+     */
+    logger?: ICacheLogger;
+}
+/**
+ * Default barrier lifetime: long enough to outlive an in-flight read or write
+ * that started before the mutation, short enough that deleted aggregates do not
+ * accumulate keys indefinitely.
+ */
+export declare const DEFAULT_BARRIER_TTL_MS = 60000;
+/**
+ * Write-through cache decorator for a {@link CommandRepository} `save` method.
+ *
+ * Provides declarative cache synchronization on mutating database operations:
+ * - **Write-through update**: When `save()` resolves with a non-nullish result, the result is cached
+ *   under the key generated by `setKey` (after invalidating any secondary keys via `invalidateKeys`).
+ * - **Cache eviction on delete**: When `save()` resolves with `null` or `undefined` (e.g. entity deletion),
+ *   all keys returned by `deleteKeys` are evicted from the cache.
+ * - **Best-effort safety**: Cache write and eviction operations swallow errors internally so that an
+ *   already-committed database transaction is never converted into an application error.
+ * - **Explicit keys**: Requires at least one of `setKey`, `deleteKeys` or `invalidateKeys`;
+ *   scoping the key (for example with `cacheKey`) is the key function's job.
+ *
+ * @example Positional syntax on creation / update
+ * ```typescript
+ * @Cache<User, UserSnapshot>(
+ *   (user) => cacheKey(User.aggregateName, { id: user.id }),
+ *   null,
+ *   (user) => [cacheKey(User.aggregateName, { email: user.email })],
+ * )
+ * async save(user: User): Promise<UserSnapshot> { ... }
+ * ```
+ *
+ * Cache maintenance runs only after the wrapped persistence method succeeds and
+ * is best-effort: cache failures are logged rather than converting an already
+ * durable write into an application failure. Pair this decorator with
+ * `@AcknowledgePersisted` and `@MapPersistenceErrors` in the canonical order.
+ *
+ * @example Options object syntax on eviction / delete
+ * ```typescript
+ * @Cache<User, null>({
+ *   deleteKeys: (user) => [
+ *     cacheKey(User.aggregateName, { id: user.id }),
+ *     cacheKey(User.aggregateName, { email: user.email }),
+ *   ],
+ * })
+ * async save(user: User): Promise<null> { ... }
+ * ```
+ */
+export declare function Cache<TEntity = unknown, TResult = unknown | null>(setKeyOrOptions: ((entity: TEntity) => string) | CacheOptions<TEntity> | null, deleteKeysFn?: ((entity: TEntity) => string[]) | null, invalidateKeysFn?: ((entity: TEntity) => string[]) | null): MethodDecorator;
+//# sourceMappingURL=cache.decorator.d.ts.map

package/dist/persistence/decorators/cache.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.decorator.d.ts","sourceRoot":"","sources":["../../../persistence/decorators/cache.decorator.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AA2C1D;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,OAAO,GAAG,OAAO;IAC7C;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,GAAG,IAAI,CAAC;IAE9C;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAEpD;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAExD;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAEnE;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,EAC/D,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,EAC7E,YAAY,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,EAAE,CAAC,GAAG,IAAI,EACrD,gBAAgB,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,EAAE,CAAC,GAAG,IAAI,GACxD,eAAe,CAmKjB"}