@cqrs-ddd/core 0.2.0

package/dist/persistence/decorators/cache.decorator.js

@@ -0,0 +1,200 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BARRIER_TTL_MS = void 0;
+exports.Cache = Cache;
+const cache_port_1 = require("../../application/ports/cache.port");
+const cache_logger_1 = require("../cache/cache-logger");
+const cache_barrier_helper_1 = require("../helpers/cache-barrier.helper");
+const cache_owner_helper_1 = require("../helpers/cache-owner.helper");
+const cache_snapshot_helper_1 = require("../helpers/cache-snapshot.helper");
+const cache_version_helper_1 = require("../helpers/cache-version.helper");
+const defaultLogger = (0, cache_logger_1.consoleCacheLogger)('CacheDecorator');
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Evicts one key using the strongest coordination the adapter supports.
+ *
+ * A {@link IVersionedCache} advances the key revision, which already fences any
+ * fill that started before this mutation, so no barrier value is stored: leaving
+ * one behind would make the next read hydrate a sentinel instead of a snapshot.
+ * Unversioned adapters have no revision to compare, so they receive a
+ * {@link CacheMutationBarrier} instead. {@link FromCache} bypasses such adapters,
+ * and wherever it meets a barrier it treats it as a miss, never as a snapshot.
+ */
+async function evictKey(cache, key, reason, entity, barrierTtl) {
+    if ((0, cache_port_1.isVersionedCache)(cache)) {
+        await cache.invalidate(key);
+        return;
+    }
+    const barrier = (0, cache_barrier_helper_1.createCacheMutationBarrier)(reason, entity);
+    await cache.set(key, barrier, { ttl: barrierTtl });
+}
+/**
+ * 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.
+ */
+exports.DEFAULT_BARRIER_TTL_MS = 60_000;
+/**
+ * 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> { ... }
+ * ```
+ */
+function Cache(setKeyOrOptions, deleteKeysFn, invalidateKeysFn) {
+    const options = typeof setKeyOrOptions === 'function' || setKeyOrOptions === null
+        ? {
+            setKey: setKeyOrOptions,
+            deleteKeys: deleteKeysFn,
+            invalidateKeys: invalidateKeysFn,
+        }
+        : setKeyOrOptions;
+    if (!options || typeof options !== 'object') {
+        throw new Error('@Cache decorator requires an explicit key derivation function or options object.');
+    }
+    const resolvedSetKey = options.setKey ?? null;
+    const resolvedDeleteKeys = options.deleteKeys ?? null;
+    const resolvedInvalidateKeys = options.invalidateKeys ?? null;
+    const resolvedTtl = options.ttl;
+    const resolvedBarrierTtl = options.barrierTtl ?? exports.DEFAULT_BARRIER_TTL_MS;
+    const logger = options.logger ?? defaultLogger;
+    const resolvedIsNewer = options.isNewer === null ? undefined : (options.isNewer ?? cache_version_helper_1.isCacheNewer);
+    if (!resolvedSetKey && !resolvedDeleteKeys && !resolvedInvalidateKeys) {
+        throw new Error('@Cache decorator requires at least one of setKey, deleteKeys, or invalidateKeys to be specified.');
+    }
+    return (_target, _propertyKey, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = async function (entity) {
+            // Observed before persistence so a write-through can tell whether anyone
+            // mutated the key while this write was in flight. A versioned adapter has
+            // no barrier value to outrank a late snapshot, so the revision it hands
+            // out here is what keeps a deleted aggregate from being resurrected.
+            let observedKey;
+            let observedRevision;
+            let observedValue;
+            if (this.cache && resolvedSetKey && (0, cache_port_1.isVersionedCache)(this.cache)) {
+                try {
+                    observedKey = resolvedSetKey(entity);
+                    const state = await this.cache.readState(observedKey);
+                    observedRevision = state.revision;
+                    observedValue = state.status === 'hit' ? state.value : undefined;
+                }
+                catch {
+                    observedKey = undefined;
+                    observedRevision = undefined;
+                }
+            }
+            const result = await original.call(this, entity);
+            if (!this.cache) {
+                (0, cache_owner_helper_1.reportMissingCacheProperty)(this, '@Cache', options.logger);
+                return result;
+            }
+            // Cache maintenance is best-effort: the DB write already succeeded,
+            // so a cache failure must not turn a success into an error.
+            try {
+                const deleting = result === null || result === undefined;
+                const keysFn = deleting ? resolvedDeleteKeys : resolvedInvalidateKeys;
+                if (keysFn) {
+                    let keys = [];
+                    try {
+                        keys = keysFn(entity) ?? [];
+                    }
+                    catch (err) {
+                        const keyOption = deleting ? 'deleteKeys' : 'invalidateKeys';
+                        const operation = deleting ? 'cache eviction' : 'cache maintenance';
+                        (0, cache_logger_1.safeWarn)(logger, `Failed resolving ${keyOption} during ${operation}: ${errorMessage(err)}`);
+                    }
+                    for (const key of keys) {
+                        try {
+                            await evictKey(this.cache, key, deleting ? 'deleted' : 'invalidated', entity, resolvedBarrierTtl);
+                        }
+                        catch (err) {
+                            const action = deleting ? 'evicting deletion' : 'invalidating';
+                            (0, cache_logger_1.safeWarn)(logger, `Failed ${action} key "${key}": ${errorMessage(err)}`);
+                        }
+                    }
+                }
+                if (deleting)
+                    return result;
+                if (resolvedSetKey) {
+                    let setKey;
+                    try {
+                        setKey = resolvedSetKey(entity);
+                    }
+                    catch (err) {
+                        (0, cache_logger_1.safeWarn)(logger, `Failed resolving setKey during cache maintenance: ${errorMessage(err)}`);
+                    }
+                    if (setKey) {
+                        try {
+                            const snapshot = (0, cache_snapshot_helper_1.toCacheSnapshot)(result);
+                            if ((0, cache_port_1.isVersionedCache)(this.cache)) {
+                                if (observedRevision !== undefined && setKey === observedKey) {
+                                    // Skip the write-through when the snapshot observed before
+                                    // persistence is already newer; otherwise commit it only if
+                                    // the revision still matches, so a concurrent mutation wins.
+                                    if (!resolvedIsNewer?.(observedValue, snapshot)) {
+                                        await this.cache.tryFill(setKey, observedRevision, snapshot, { ttl: resolvedTtl });
+                                    }
+                                }
+                                else {
+                                    // No revision was observed for this key before the write, so
+                                    // a fill cannot be fenced; drop the pre-write value instead.
+                                    await this.cache.invalidate(setKey);
+                                }
+                            }
+                            else {
+                                await this.cache.set(setKey, snapshot, {
+                                    ttl: resolvedTtl,
+                                    isNewer: resolvedIsNewer,
+                                });
+                            }
+                        }
+                        catch (err) {
+                            (0, cache_logger_1.safeWarn)(logger, `Failed setting cache key "${setKey}": ${errorMessage(err)}`);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                (0, cache_logger_1.safeWarn)(logger, `Unexpected error during cache maintenance: ${errorMessage(err)}`);
+            }
+            return result;
+        };
+    };
+}
+//# sourceMappingURL=cache.decorator.js.map

package/dist/persistence/decorators/cache.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.decorator.js","sourceRoot":"","sources":["../../../persistence/decorators/cache.decorator.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,65 @@
+import { IQueryOptions } from '../../application/query.options';
+import type { ICacheLogger } from '../cache/cache-logger';
+import { isCacheNewer } from '../helpers/cache-version.helper';
+export { isCacheNewer };
+/**
+ * Options for configuring read-through caching and rehydration via {@link FromCache}.
+ */
+export interface FromCacheOptions<TQuery = unknown, TResult = unknown> {
+    /**
+     * Function deriving the cache key from query options.
+     * When it returns `null`, caching is skipped for that call.
+     */
+    keyFn?: ((query: TQuery) => string | null) | null;
+    /**
+     * Function to rehydrate a raw cached snapshot back into a domain entity.
+     * When omitted, the repository's {@link QueryRepositoryHydration} applies;
+     * `null` opts this method out of it.
+     */
+    hydrateFn?: ((cached: unknown) => TResult) | null;
+    /**
+     * Optional serializer function to convert a domain entity or complex result into
+     * a pure, detached snapshot for storage in cache.
+     * If omitted, the repository's {@link QueryRepositoryHydration} serializer
+     * applies, and otherwise {@link toCacheSnapshot} extracts a snapshot via
+     * `result.toJSON()` or deep JSON cloning. `null` skips the repository default.
+     */
+    serializeFn?: ((result: TResult) => unknown) | null;
+    /**
+     * Requires `hydrateFn` at decoration time. Every hit is rehydrated whenever a
+     * hydrator applies, so this flag does not change the result.
+     */
+    alwaysHydrate?: boolean;
+    /**
+     * Optional time-to-live in milliseconds for cached entries.
+     */
+    ttl?: number;
+    /**
+     * Optional version comparator for stale-read prevention during concurrent cache population.
+     * Defaults to {@link isCacheNewer}.
+     */
+    isNewer?: (cached: unknown, incoming: unknown) => boolean;
+    /**
+     * Receives read-through warnings (unversioned adapter, uncacheable result, missing
+     * `cache` property). Defaults to `console.warn` with a `[FromCacheDecorator]`
+     * prefix. See {@link ICacheLogger}.
+     */
+    logger?: ICacheLogger;
+}
+/**
+ * Read-through cache decorator for a {@link QueryRepository} `find` method.
+ *
+ * Provides declarative read-through caching with revision-fenced coordination:
+ * - **Key derivation**: Generates a cache key via `keyFn`. If `keyFn` returns `null`, caching is skipped.
+ * - **Snapshot storage contract**: Stores strictly serializable snapshots in the cache, never live domain aggregates.
+ * - **Consistent result shape**: When a method or repository `hydrateFn` applies, every hit is rehydrated, so hits
+ *   and misses return the same type. Without a hydrator only plain-data results are cached; any other result
+ *   (a class instance, or a result reshaped by `serializeFn`) is returned uncached and reported once.
+ * - **Revision-fenced consistency**: When coordinated via {@link IVersionedCache}, cache fill attempts verify the
+ *   observed revision token atomically (`tryFill`). A fill started before an observed invalidation cannot
+ *   repopulate the key afterwards.
+ * - **Bounded retry**: Contended fills inspect current cache state and boundedly retry authoritative reads before
+ *   falling back to un-cached database results.
+ */
+export declare function FromCache<TQuery extends IQueryOptions = IQueryOptions, TResult = unknown>(keyFnOrOptions: ((query: TQuery) => string | null) | FromCacheOptions<TQuery, TResult>, hydrateFnOrOptions?: ((cached: unknown) => TResult) | FromCacheOptions<TQuery, TResult>, extraOptions?: FromCacheOptions<TQuery, TResult>): MethodDecorator;
+//# sourceMappingURL=from-cache.decorator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"from-cache.decorator.d.ts","sourceRoot":"","sources":["../../../persistence/decorators/from-cache.decorator.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAK1D,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAM/D,OAAO,EAAE,YAAY,EAAE,CAAC;AAsBxB;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACnE;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAElD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAElD;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAEpD;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1D;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AA8BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CACvB,MAAM,SAAS,aAAa,GAAG,aAAa,EAC5C,OAAO,GAAG,OAAO,EAEjB,cAAc,EACV,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC,GAClC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,kBAAkB,CAAC,EACf,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,GAC9B,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,YAAY,CAAC,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/C,eAAe,CAyIjB"}

package/dist/persistence/decorators/from-cache.decorator.js

@@ -0,0 +1,165 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCacheNewer = void 0;
+exports.FromCache = FromCache;
+const cache_port_1 = require("../../application/ports/cache.port");
+const cache_logger_1 = require("../cache/cache-logger");
+const cache_barrier_helper_1 = require("../helpers/cache-barrier.helper");
+const cache_owner_helper_1 = require("../helpers/cache-owner.helper");
+const cache_snapshot_helper_1 = require("../helpers/cache-snapshot.helper");
+const cache_version_helper_1 = require("../helpers/cache-version.helper");
+Object.defineProperty(exports, "isCacheNewer", { enumerable: true, get: function () { return cache_version_helper_1.isCacheNewer; } });
+const defaultLogger = (0, cache_logger_1.consoleCacheLogger)('FromCacheDecorator');
+const warnedUnversionedAdapters = new WeakSet();
+/**
+ * Reports an unversioned adapter once per instance: a silent loss of caching is
+ * harder to diagnose than the race the bypass avoids.
+ */
+function warnUnversionedAdapterOnce(cache, logger) {
+    if (warnedUnversionedAdapters.has(cache))
+        return;
+    warnedUnversionedAdapters.add(cache);
+    (0, cache_logger_1.safeWarn)(logger, `${cache.constructor?.name ?? 'Cache adapter'} implements only get/set/delete, ` +
+        'so @FromCache read-through is disabled for repositories using it. ' +
+        'Implement IVersionedCache (readState/invalidate/tryFill) to enable ' +
+        'revision-fenced caching.');
+}
+/**
+ * True for values whose cached JSON form equals the value itself: primitives,
+ * arrays and plain objects of such values. Class instances and `Date` are not.
+ */
+function isPlainData(value, ancestors = new WeakSet()) {
+    if (value === null || typeof value !== 'object') {
+        return typeof value !== 'function' && typeof value !== 'bigint';
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (ancestors.has(value) ||
+        (!Array.isArray(value) &&
+            prototype !== Object.prototype &&
+            prototype !== null)) {
+        return false;
+    }
+    ancestors.add(value);
+    const plain = Object.values(value).every((item) => isPlainData(item, ancestors));
+    ancestors.delete(value);
+    return plain;
+}
+/**
+ * Read-through cache decorator for a {@link QueryRepository} `find` method.
+ *
+ * Provides declarative read-through caching with revision-fenced coordination:
+ * - **Key derivation**: Generates a cache key via `keyFn`. If `keyFn` returns `null`, caching is skipped.
+ * - **Snapshot storage contract**: Stores strictly serializable snapshots in the cache, never live domain aggregates.
+ * - **Consistent result shape**: When a method or repository `hydrateFn` applies, every hit is rehydrated, so hits
+ *   and misses return the same type. Without a hydrator only plain-data results are cached; any other result
+ *   (a class instance, or a result reshaped by `serializeFn`) is returned uncached and reported once.
+ * - **Revision-fenced consistency**: When coordinated via {@link IVersionedCache}, cache fill attempts verify the
+ *   observed revision token atomically (`tryFill`). A fill started before an observed invalidation cannot
+ *   repopulate the key afterwards.
+ * - **Bounded retry**: Contended fills inspect current cache state and boundedly retry authoritative reads before
+ *   falling back to un-cached database results.
+ */
+function FromCache(keyFnOrOptions, hydrateFnOrOptions, extraOptions) {
+    const positionalKey = typeof keyFnOrOptions === 'function';
+    const positionalHydrator = positionalKey && typeof hydrateFnOrOptions === 'function';
+    let resolvedOptions = positionalKey ? hydrateFnOrOptions : keyFnOrOptions;
+    if (typeof resolvedOptions === 'function')
+        resolvedOptions = extraOptions;
+    const resolvedKeyFn = positionalKey ? keyFnOrOptions : keyFnOrOptions.keyFn;
+    const resolvedHydrateFn = positionalHydrator
+        ? hydrateFnOrOptions
+        : (resolvedOptions?.hydrateFn ?? undefined);
+    const declaresHydrateFn = positionalHydrator ||
+        (resolvedOptions !== undefined && 'hydrateFn' in resolvedOptions);
+    const declaresSerializeFn = resolvedOptions !== undefined && 'serializeFn' in resolvedOptions;
+    if (resolvedOptions?.alwaysHydrate && !resolvedHydrateFn) {
+        throw new TypeError('FromCache: alwaysHydrate requires a hydrateFn');
+    }
+    const logger = resolvedOptions?.logger ?? defaultLogger;
+    const MAX_FILL_RETRIES = 2;
+    let reportedUncacheable = false;
+    return (_target, _propertyKey, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = async function (query) {
+            if (!this.cache) {
+                (0, cache_owner_helper_1.reportMissingCacheProperty)(this, '@FromCache', resolvedOptions?.logger);
+                return original.call(this, query);
+            }
+            if (query.refresh)
+                return original.call(this, query);
+            if (!resolvedKeyFn)
+                throw new TypeError('FromCache requires a keyFn');
+            const key = resolvedKeyFn(query);
+            if (key === null) {
+                return original.call(this, query);
+            }
+            // Method-level options win; otherwise the repository policy applies,
+            // and a repository hydrator rehydrates every hit.
+            const repositoryHydration = this.hydration;
+            const hydrateFn = declaresHydrateFn
+                ? resolvedHydrateFn
+                : repositoryHydration?.hydrateFn;
+            const serializeFn = declaresSerializeFn
+                ? resolvedOptions?.serializeFn
+                : repositoryHydration?.serializeFn;
+            const hydrateCached = (cachedValue) => hydrateFn ? hydrateFn(cachedValue) : cachedValue;
+            // A revision-fenced key can still hold a barrier written by an
+            // unversioned writer against the same store; it is a sentinel, never a
+            // snapshot, so it counts as a miss rather than something to hydrate. The
+            // same holds for `null`: this decorator never fills one, so a stored null
+            // is a leftover from another writer, not a cached absence.
+            const isUsableSnapshot = (state) => state.status === 'hit' &&
+                state.value !== undefined &&
+                state.value !== null &&
+                !(0, cache_barrier_helper_1.isCacheMutationBarrier)(state.value);
+            // 1. Versioned coordination path (capable adapters)
+            if ((0, cache_port_1.isVersionedCache)(this.cache)) {
+                let observedState = await this.cache.readState(key);
+                if (isUsableSnapshot(observedState)) {
+                    return hydrateCached(observedState.value);
+                }
+                for (let attempt = 0;; attempt++) {
+                    const result = await original.call(this, query);
+                    if (result === null || result === undefined) {
+                        const postState = await this.cache.readState(key);
+                        if (isUsableSnapshot(postState)) {
+                            return hydrateCached(postState.value);
+                        }
+                        return result;
+                    }
+                    // A hit without a hydrator returns the cached data as is, so only a
+                    // result that already is that data may be cached.
+                    if (!hydrateFn && (serializeFn || !isPlainData(result))) {
+                        if (!reportedUncacheable) {
+                            reportedUncacheable = true;
+                            (0, cache_logger_1.safeWarn)(logger, `${this.constructor.name} caches a result that a hit could not reproduce without a hydrateFn; ` +
+                                'the result is returned uncached. Configure a hydrateFn or return plain data.');
+                        }
+                        return result;
+                    }
+                    const snapshot = (0, cache_snapshot_helper_1.toCacheSnapshot)(result, serializeFn);
+                    const committed = await this.cache.tryFill(key, observedState.revision, snapshot, { ttl: resolvedOptions?.ttl });
+                    if (committed) {
+                        return result;
+                    }
+                    const currentState = await this.cache.readState(key);
+                    if (isUsableSnapshot(currentState)) {
+                        const newerCheck = resolvedOptions?.isNewer ?? cache_version_helper_1.isCacheNewer;
+                        if (newerCheck(currentState.value, snapshot)) {
+                            return hydrateCached(currentState.value);
+                        }
+                    }
+                    if (attempt === MAX_FILL_RETRIES)
+                        return result;
+                    observedState = currentState;
+                }
+            }
+            // 2. Unversioned adapter: with no revision to fence a fill against a
+            // concurrent invalidation, the cache is bypassed for both reads and fills.
+            warnUnversionedAdapterOnce(this.cache, logger);
+            return original.call(this, query);
+        };
+    };
+}
+//# sourceMappingURL=from-cache.decorator.js.map

package/dist/persistence/decorators/from-cache.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-cache.decorator.js","sourceRoot":"","sources":["../../../persistence/decorators/from-cache.decorator.ts"],"names":[],"mappings":"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"}

package/dist/persistence/decorators/map-persistence-errors.decorator.d.ts

@@ -0,0 +1,88 @@
+import { type IPersistenceDialect } from '../persistence-dialect';
+/**
+ * Domain errors per violated unique constraint, keyed by the entity property the
+ * constraint covers. A multi-column constraint has no single property: key it by
+ * its declared name, passed as `TConstraint` from a constant declared beside the
+ * ORM mapping. No database name or column string appears in a repository.
+ */
+export type UniqueErrors<TEntity, TConstraint extends string = never> = {
+    readonly [K in Extract<keyof TEntity, string> | TConstraint]?: (entity: TEntity) => Error;
+};
+/**
+ * Method decorator that intercepts persistence failures from the wrapped method and
+ * translates identifiable database unique constraint violations into domain exceptions.
+ *
+ * ### Error Matching Mechanics
+ * - **Unique violations**: the persistence dialect ({@link IPersistenceDialect}) names the
+ *   violated constraint by the entity property it covers; `unique[key]` builds the
+ *   domain error. The dialect comes from `options.dialect`, else from
+ *   {@link setPersistenceDialect}. A method that declares `unique` with no dialect
+ *   available throws a `TypeError` before it runs, so a violation never escapes as a
+ *   raw driver error.
+ * - **Residual translation**: Any error not matching a configured constraint is passed to the
+ *   optional `otherwise` translator, which is the declarative place to convert driver/network
+ *   failures into the neutral {@link TransientOperationError} retry signal.
+ * - **Passthrough**: Without `otherwise` — or when `otherwise` returns the error unchanged — the
+ *   error is rethrown with its original identity, class, and stack trace completely preserved.
+ *
+ * Use `otherwise` for application-level translation of unmatched driver or
+ * network failures. Keep persistence translation in this decorator so the
+ * lifecycle order relative to `@AcknowledgePersisted` and `@Cache` remains
+ * explicit in the decorator stack.
+ *
+ * ### 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.
+ *
+ * @param options The `entity` extractor, the `unique` errors, an optional `dialect`
+ *   overriding the registered one (for a repository on another store), and an
+ *   optional `otherwise` translator.
+ *
+ * @example Mapping unique constraints in a create repository
+ * ```typescript
+ * @Injectable()
+ * export class CreateUserCommandRepository extends CommandRepository<User, UserSnapshot> {
+ *   @Cache<User, UserSnapshot>((u) => `users:${u.id}`, null, (u) => [`users:email:${u.email}`])
+ *   @AcknowledgePersisted<[User]>({ entity: ([user]) => user })
+ *   @MapPersistenceErrors<[User], User>({
+ *     entity: ([user]) => user,
+ *     unique: { email: (user) => new UniqueEmailException(user) },
+ *   })
+ *   async save(user: User): Promise<UserSnapshot> {
+ *     const created = this.store.em.create(User, user);
+ *     this.store.em.persist(created);
+ *     await this.store.em.flush();
+ *     return created.toJSON();
+ *   }
+ * }
+ * ```
+ */
+export declare function MapPersistenceErrors<TArgs extends unknown[], TEntity, TConstraint extends string = never, TThis = unknown>(options: {
+    entity: (args: TArgs) => TEntity;
+    unique?: UniqueErrors<TEntity, TConstraint>;
+    dialect?: IPersistenceDialect;
+    /**
+     * Optional translator applied to any error that did not match a unique constraint
+     * mapping. Return the error unchanged to preserve its identity, or return a
+     * replacement to express it in application terms.
+     *
+     * The canonical use is transient-failure classification with
+     * {@link mapPersistenceError}, so that retry policies consume
+     * `TransientOperationError` rather than driver codes:
+     *
+     * ```typescript
+     * otherwise: (error, user) => mapPersistenceError(error, `deleting User ${user.id}`),
+     * ```
+     *
+     * Deliberate domain errors thrown inside the method (`ConcurrencyConflictError`,
+     * `EntityNotFoundException`) also pass through this hook. `mapPersistenceError`
+     * returns non-transient errors unchanged, so no explicit re-throw guard is needed.
+     *
+     * Written as a method, it runs with `this` bound to the repository instance
+     * (typed by `TThis`), for a message that names instance state.
+     */
+    otherwise?: (this: TThis, error: unknown, entity: TEntity) => unknown;
+}): <TResult>(_target: object, _key: string | symbol, descriptor: TypedPropertyDescriptor<(...args: TArgs) => Promise<TResult>>) => void;
+//# sourceMappingURL=map-persistence-errors.decorator.d.ts.map

package/dist/persistence/decorators/map-persistence-errors.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-persistence-errors.decorator.d.ts","sourceRoot":"","sources":["../../../persistence/decorators/map-persistence-errors.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,OAAO,EAAE,WAAW,SAAS,MAAM,GAAG,KAAK,IAAI;IACtE,QAAQ,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,OAAO,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,CAC7D,MAAM,EAAE,OAAO,KACZ,KAAK;CACX,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,SAAS,OAAO,EAAE,EACvB,OAAO,EACP,WAAW,SAAS,MAAM,GAAG,KAAK,EAClC,KAAK,GAAG,OAAO,EACf,OAAO,EAAE;IACT,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC;IACjC,MAAM,CAAC,EAAE,YAAY,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;CACvE,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,CA+BR"}

package/dist/persistence/decorators/map-persistence-errors.decorator.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapPersistenceErrors = MapPersistenceErrors;
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+const persistence_dialect_1 = require("../persistence-dialect");
+/**
+ * Method decorator that intercepts persistence failures from the wrapped method and
+ * translates identifiable database unique constraint violations into domain exceptions.
+ *
+ * ### Error Matching Mechanics
+ * - **Unique violations**: the persistence dialect ({@link IPersistenceDialect}) names the
+ *   violated constraint by the entity property it covers; `unique[key]` builds the
+ *   domain error. The dialect comes from `options.dialect`, else from
+ *   {@link setPersistenceDialect}. A method that declares `unique` with no dialect
+ *   available throws a `TypeError` before it runs, so a violation never escapes as a
+ *   raw driver error.
+ * - **Residual translation**: Any error not matching a configured constraint is passed to the
+ *   optional `otherwise` translator, which is the declarative place to convert driver/network
+ *   failures into the neutral {@link TransientOperationError} retry signal.
+ * - **Passthrough**: Without `otherwise` — or when `otherwise` returns the error unchanged — the
+ *   error is rethrown with its original identity, class, and stack trace completely preserved.
+ *
+ * Use `otherwise` for application-level translation of unmatched driver or
+ * network failures. Keep persistence translation in this decorator so the
+ * lifecycle order relative to `@AcknowledgePersisted` and `@Cache` remains
+ * explicit in the decorator stack.
+ *
+ * ### 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.
+ *
+ * @param options The `entity` extractor, the `unique` errors, an optional `dialect`
+ *   overriding the registered one (for a repository on another store), and an
+ *   optional `otherwise` translator.
+ *
+ * @example Mapping unique constraints in a create repository
+ * ```typescript
+ * @Injectable()
+ * export class CreateUserCommandRepository extends CommandRepository<User, UserSnapshot> {
+ *   @Cache<User, UserSnapshot>((u) => `users:${u.id}`, null, (u) => [`users:email:${u.email}`])
+ *   @AcknowledgePersisted<[User]>({ entity: ([user]) => user })
+ *   @MapPersistenceErrors<[User], User>({
+ *     entity: ([user]) => user,
+ *     unique: { email: (user) => new UniqueEmailException(user) },
+ *   })
+ *   async save(user: User): Promise<UserSnapshot> {
+ *     const created = this.store.em.create(User, user);
+ *     this.store.em.persist(created);
+ *     await this.store.em.flush();
+ *     return created.toJSON();
+ *   }
+ * }
+ * ```
+ */
+function MapPersistenceErrors(options) {
+    return (_target, _key, descriptor) => {
+        const original = descriptor.value;
+        if (typeof original !== 'function')
+            throw new TypeError('Persistence decorators require a method.');
+        const unique = options.unique ?? {};
+        const hasUnique = Object.keys(unique).length > 0;
+        descriptor.value = async function (...args) {
+            const dialect = options.dialect ?? (0, persistence_dialect_1.persistenceDialect)();
+            if (hasUnique && !dialect) {
+                throw new TypeError('Unique-constraint mapping needs a persistence dialect: call setPersistenceDialect() or pass { dialect }.');
+            }
+            try {
+                return await original.apply(this, args);
+            }
+            catch (error) {
+                const entity = options.entity(args);
+                const key = hasUnique
+                    ? dialect?.uniqueViolation(error, entity)
+                    : undefined;
+                const toError = key === undefined
+                    ? undefined
+                    : unique[key];
+                if (toError)
+                    throw toError(entity);
+                if (options.otherwise)
+                    throw options.otherwise.call(this, error, entity);
+                throw error;
+            }
+        };
+    };
+}
+//# sourceMappingURL=map-persistence-errors.decorator.js.map

package/dist/persistence/decorators/map-persistence-errors.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-persistence-errors.decorator.js","sourceRoot":"","sources":["../../../persistence/decorators/map-persistence-errors.decorator.ts"],"names":[],"mappings":";;AAqEA,oDAkEC;AAvID,sEAAsE;AACtE,gEAGgC;AAchC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,SAAgB,oBAAoB,CAKlC,OAyBD;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,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QACjD,UAAU,CAAC,KAAK,GAAG,KAAK,WAAW,GAAG,IAAW;YAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAA,wCAAkB,GAAE,CAAC;YACxD,IAAI,SAAS,IAAI,CAAC,OAAO,EAAE,CAAC;gBAC1B,MAAM,IAAI,SAAS,CACjB,0GAA0G,CAC3G,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC1C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACpC,MAAM,GAAG,GAAG,SAAS;oBACnB,CAAC,CAAC,OAAO,EAAE,eAAe,CAAC,KAAK,EAAE,MAAgB,CAAC;oBACnD,CAAC,CAAC,SAAS,CAAC;gBACd,MAAM,OAAO,GACX,GAAG,KAAK,SAAS;oBACf,CAAC,CAAC,SAAS;oBACX,CAAC,CAAE,MAAqD,CAAC,GAAG,CAAC,CAAC;gBAClE,IAAI,OAAO;oBAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;gBACnC,IAAI,OAAO,CAAC,SAAS;oBACnB,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,IAAa,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;gBAC7D,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}