zibri 2.3.0 → 2.4.1

package/src/caching/cache/base-cache.model.ts

@@ -0,0 +1,333 @@
+import { AlsUtilities } from '../../context/als.utilities';
+import { CacheContext } from '../../context/cache/cache.context';
+import { LoggerInterface } from '../../logging/logger.interface';
+import { MetricsServiceInterface } from '../../metrics/metrics-service.interface';
+import { OmitStrict } from '../../types/omit-strict.type';
+import { CacheMetrics } from '../cache-metrics.model';
+import { CacheServiceInterface } from '../cache-service.interface';
+import { CacheTagMatcher } from '../cache-tag-matchers';
+import { CacheOperation } from './cache-operation.enum';
+import { CacheKeyProvider, CacheSetDirectOptions, CacheTagsProvider, CacheTtlProvider, CacheWrapDeleteOptions, CacheWrapInvalidateOptions, OnInvalidationFailure, ResultCacheTagsProvider, ResultCacheTtlProvider } from './cache-options.model';
+import { CacheInterface } from './cache.interface';
+import { CacheStoreInterface } from '../store/cache-store.interface';
+import { CachedValue } from '../store/cached-value.model';
+
+/**
+ * Shared base class of all caches.
+ */
+export abstract class BaseCache<K, V, CacheTag extends string, WriteResultAvailable extends boolean, N extends string>
+implements OmitStrict<CacheInterface<K, V, CacheTag, WriteResultAvailable, N>, 'wrap' | 'wrapWrite'> {
+
+    private readonly inFlight: Map<K, Promise<V>> = new Map();
+
+    private _metrics: CacheMetrics | undefined;
+
+    protected abstract cacheService: CacheServiceInterface;
+
+    protected abstract logger: LoggerInterface;
+
+    protected abstract metricsService: MetricsServiceInterface;
+
+    abstract readonly _writeResultAvailable: WriteResultAvailable;
+
+    // eslint-disable-next-line jsdoc/require-returns
+    /**
+     * The cache metrics.
+     */
+    protected get metrics(): CacheMetrics {
+        this._metrics ??= this.initMetrics();
+        return this._metrics;
+    }
+
+    constructor(
+        readonly name: N,
+        readonly store: CacheStoreInterface<K, V>,
+        readonly tags: 'all' | readonly CacheTagMatcher[],
+        readonly defaultTtl?: number | (() => number | Promise<number>),
+        readonly onInvalidationFailure?: OnInvalidationFailure
+    ) {}
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    wrapDelete<TReturn, TArgs extends unknown[]>(
+        fn: (...args: TArgs) => TReturn | Promise<TReturn>,
+        keyFn: CacheKeyProvider<K, TArgs>,
+        options?: CacheWrapDeleteOptions<TArgs, CacheTag>
+    ): (...args: TArgs) => Promise<TReturn> {
+        return async (...args) => {
+            const cacheCtx: CacheContext = { cache: this.name, operation: CacheOperation.DELETE };
+
+            return AlsUtilities.runWithCacheContext(cacheCtx, async () => {
+                const sourceStart: number = performance.now();
+                const res: TReturn = await fn(...args);
+                cacheCtx.durationInMs = performance.now() - sourceStart;
+                this.metrics.sourceDuration.observe({ cache: this.name, operation: CacheOperation.DELETE }, cacheCtx.durationInMs);
+
+                await Promise.all([
+                    Promise.resolve()
+                        .then(async () => {
+                            const key: K = await keyFn(...args);
+                            cacheCtx.key = key;
+
+                            const storeStart: number = performance.now();
+                            await this.store.delete(key);
+                            this.metrics.storeDuration.observe({ cache: this.name, operation: 'delete' }, performance.now() - storeStart);
+                            this.metrics.deletes.increase({ cache: this.name });
+                            await this.updateSizeGauge();
+                        })
+                        .catch(async (error) => {
+                            this.metrics.errors.increase({ cache: this.name, operation: 'delete' });
+                            await this.logger.warn(
+                                'Cache deletion failed after successful source delete',
+                                { error }
+                            );
+                        }),
+                    this.safeInvalidateTags(options?.invalidatesTags, args)
+                ]);
+
+                return res;
+            });
+        };
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    wrapInvalidate<TReturn, TArgs extends unknown[]>(
+        fn: (...args: TArgs) => TReturn | Promise<TReturn>,
+        options: CacheWrapInvalidateOptions<TArgs, CacheTag>
+    ): (...args: TArgs) => Promise<TReturn> {
+        return async (...args) => {
+            const cacheCtx: CacheContext = { cache: this.name, operation: CacheOperation.INVALIDATE };
+
+            return AlsUtilities.runWithCacheContext(cacheCtx, async () => {
+                const sourceStart: number = performance.now();
+                const result: TReturn = await fn(...args);
+                cacheCtx.durationInMs = performance.now() - sourceStart;
+                this.metrics.sourceDuration.observe({ cache: this.name, operation: CacheOperation.INVALIDATE }, cacheCtx.durationInMs);
+
+                await this.safeInvalidateTags(options.invalidatesTags, args);
+
+                return result;
+            });
+        };
+    }
+
+    abstract setDirect(key: K, value: V, options?: CacheSetDirectOptions<CacheTag>): Promise<void>;
+
+    private initMetrics(): CacheMetrics {
+        const label: string[] = ['cache'];
+        const labelWithOp: string[] = ['cache', 'operation'];
+
+        return {
+            hits: this.metricsService.getCounter('cache_hits_total', label),
+            misses: this.metricsService.getCounter('cache_misses_total', label),
+            writes: this.metricsService.getCounter('cache_writes_total', label),
+            deletes: this.metricsService.getCounter('cache_deletes_total', label),
+            invalidations: this.metricsService.getCounter('cache_invalidations_total', label),
+            invalidationFailures: this.metricsService.getCounter('cache_invalidation_failures_total', label),
+            expiredEvictions: this.metricsService.getCounter('cache_expired_evictions_total', label),
+            errors: this.metricsService.getCounter('cache_errors_total', labelWithOp),
+            inFlight: this.metricsService.getGauge('cache_in_flight', label),
+            size: this.metricsService.getGauge('cache_size', label),
+            sourceDuration: this.metricsService.getHistogram(
+                'cache_source_duration_ms',
+                labelWithOp,
+                [1, 5, 10, 25, 50, 100, 250, 500, 1000]
+            ),
+            storeDuration: this.metricsService.getHistogram('cache_store_duration_ms', labelWithOp, [1, 5, 10, 25, 50, 100, 250, 500])
+        };
+    }
+
+    /**
+     * Updates the size gauge metric.
+     */
+    protected async updateSizeGauge(): Promise<void> {
+        try {
+            this.metrics.size.set({ cache: this.name }, await this.store.size());
+        }
+        catch {
+            // not critical — never surface gauge update failures
+        }
+    }
+
+    /**
+     * Runs the given factory under the given key in single flight.
+     * @param key - The key to check if a operation is already ongoing.
+     * @param factory - The operation to run.
+     * @returns The resolving promise.
+     */
+    protected async runSingleFlight(key: K, factory: () => Promise<V>): Promise<V> {
+        const existing: Promise<V> | undefined = this.inFlight.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const promise: Promise<V> = (async () => {
+            try {
+                return await factory();
+            }
+            finally {
+                this.inFlight.delete(key);
+                this.metrics.inFlight.set({ cache: this.name }, this.inFlight.size);
+            }
+        })();
+
+        this.inFlight.set(key, promise);
+        this.metrics.inFlight.set({ cache: this.name }, this.inFlight.size);
+        return promise;
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    protected async safeInvalidateTags<TArgs extends unknown[]>(
+        provider: CacheTagsProvider<TArgs, CacheTag> | undefined,
+        args: TArgs
+    ): Promise<void>;
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    protected async safeInvalidateTags<TArgs extends unknown[]>(
+        provider: ResultCacheTagsProvider<V, TArgs, CacheTag> | undefined,
+        result: V,
+        args: TArgs
+    ): Promise<void>;
+    /**
+     * Safely invalidates tags.
+     * @param provider - The provider for the tags to invalidate.
+     * @param resultOrArgs - Either the result or The method arguments, depending on whether the result is available.
+     * @param maybeArgs - The method arguments if a result is available, undefined otherwise.
+     */
+    protected async safeInvalidateTags<TArgs extends unknown[]>(
+        provider: CacheTagsProvider<TArgs, CacheTag> | ResultCacheTagsProvider<V, TArgs, CacheTag> | undefined,
+        resultOrArgs: V | TArgs,
+        maybeArgs?: TArgs
+    ): Promise<void> {
+        try {
+            const tags: CacheTag[] = maybeArgs !== undefined
+                ? await this.resolveResultTags(provider as ResultCacheTagsProvider<V, TArgs, CacheTag>, resultOrArgs as V, maybeArgs)
+                : await this.resolveArgTags(provider as CacheTagsProvider<TArgs, CacheTag>, resultOrArgs as TArgs);
+
+            if (!tags.length) {
+                return;
+            }
+
+            await this.cacheService.invalidateTags(tags);
+            this.metrics.invalidations.increase({ cache: this.name });
+            // size may have changed as other caches invalidated entries
+            await this.updateSizeGauge();
+
+        }
+        catch (error) {
+            this.metrics.invalidationFailures.increase({ cache: this.name });
+            if (this.onInvalidationFailure === 'throw') {
+                throw error;
+            }
+            else {
+                await this.logger.warn(
+                    'Cache invalidation failed, stale data may be served',
+                    { error }
+                );
+            }
+        }
+    }
+
+    /**
+     * Resolves tags from a result provider.
+     * @param provider - The provider to resolve the tags from.
+     * @param result - The result.
+     * @param args - Additional arguments.
+     * @returns All resolved CacheTags.
+     */
+    protected async resolveResultTags<TArgs extends unknown[]>(
+        provider: ResultCacheTagsProvider<V, TArgs, CacheTag> | undefined,
+        result: V,
+        args: TArgs
+    ): Promise<CacheTag[]> {
+        if (!provider) {
+            return [];
+        }
+        if (typeof provider === 'function') {
+            return await provider(result, ...args);
+        }
+        return provider;
+    }
+
+    /**
+     * Resolves tags from a provider.
+     * @param provider - The provider to resolve the tags from.
+     * @param args - The arguments.
+     * @returns All resolved CacheTags.
+     */
+    protected async resolveArgTags<TArgs extends unknown[]>(
+        provider: CacheTagsProvider<TArgs, CacheTag> | undefined,
+        args: TArgs
+    ): Promise<CacheTag[]> {
+        if (!provider) {
+            return [];
+        }
+        if (typeof provider === 'function') {
+            return await provider(...args);
+        }
+        return provider;
+    }
+
+    /**
+     * Resolves ttl from a result provider.
+     * @param provider - The provider to resolve the ttl from.
+     * @param result - The result.
+     * @param args - The arguments.
+     * @returns The resolved time to live or undefined if values should be kept in cache without time limit.
+     */
+    protected async resolveResultTtl<TArgs extends unknown[]>(
+        provider: ResultCacheTtlProvider<V, TArgs> | undefined,
+        result: V,
+        args: TArgs
+    ): Promise<number | undefined> {
+        if (provider == undefined) {
+            if (typeof this.defaultTtl === 'function') {
+                return await this.defaultTtl();
+            }
+            return this.defaultTtl;
+        }
+        if (typeof provider === 'function') {
+            return await provider(result, ...args);
+        }
+        return provider;
+    }
+
+    /**
+     * Resolves ttl from a provider.
+     * @param provider - The provider to resolve the ttl from.
+     * @param args - The arguments.
+     * @returns The resolved time to live or undefined if values should be kept in cache without time limit.
+     */
+    protected async resolveArgsTtl<TArgs extends unknown[]>(
+        provider: CacheTtlProvider<TArgs> | undefined,
+        args: TArgs
+    ): Promise<number | undefined> {
+        if (provider == undefined) {
+            if (typeof this.defaultTtl === 'function') {
+                return await this.defaultTtl();
+            }
+            return this.defaultTtl;
+        }
+        if (typeof provider === 'function') {
+            return await provider(...args);
+        }
+        return provider;
+    }
+
+    /**
+     * Creates a cached value from the given input.
+     * @param value - The value of the value to cache.
+     * @param tags - The tags that should mark this cache entry.
+     * @param ttl - The time that this cache entry should be valid.
+     * @returns A cached value definition.
+     */
+    protected createCachedValue(value: V, tags: CacheTag[], ttl: number | undefined): CachedValue<V> {
+        const createdAt: Date = new Date();
+        const expiresAt: Date | undefined = ttl != undefined ? new Date(createdAt.getTime() + ttl) : undefined;
+
+        return {
+            createdAt,
+            expiresAt,
+            value,
+            tags
+        };
+    }
+}

package/src/caching/cache/cache-operation.enum.ts

@@ -0,0 +1,9 @@
+/**
+ * The different operations of a cache.
+ */
+export enum CacheOperation {
+    WRAP = 'WRAP',
+    WRITE = 'WRITE',
+    DELETE = 'DELETE',
+    INVALIDATE = 'INVALIDATE'
+}

package/src/caching/cache/cache-options.model.ts

@@ -0,0 +1,121 @@
+/**
+ * Provider for a time to live value.
+ */
+export type CacheTtlProvider<TArgs extends unknown[]> = number | ((...args: TArgs) => (number | undefined) | Promise<number | undefined>);
+
+/**
+ * Provider for a time to live value where the result of the original function is available.
+ */
+export type ResultCacheTtlProvider<TResult, TArgs extends unknown[]> = number
+    | ((result: TResult, ...args: TArgs) => (number | undefined) | Promise<number | undefined>);
+
+/**
+ * Tags derived from args only (no result available) — wrapDelete, wrapInvalidate.
+ */
+export type CacheTagsProvider<TArgs extends unknown[], CacheTag extends string> = CacheTag[]
+    | ((...args: TArgs) => CacheTag[] | Promise<CacheTag[]>);
+
+/**
+ * Tags derived from result + args — wrap, wrapWrite.
+ */
+export type ResultCacheTagsProvider<TResult, TArgs extends unknown[], CacheTag extends string> = CacheTag[]
+    | ((result: TResult, ...args: TArgs) => CacheTag[] | Promise<CacheTag[]>);
+
+/**
+ * Provider for a cache key.
+ */
+export type CacheKeyProvider<K, TArgs extends unknown[]> = (...args: TArgs) => K | Promise<K>;
+
+/**
+ * Provider for a cache key where the result of the original function is available.
+ */
+export type ResultCacheKeyProvider<K, TResult, TArgs extends unknown[]> = (result: TResult, ...args: TArgs) => K | Promise<K>;
+
+/**
+ * The options on how to handle invalidation failures.
+ */
+export type OnInvalidationFailure = 'bestEffort' | 'throw';
+
+/**
+ * Options for manually setting a value to the cache.
+ */
+export type CacheSetDirectOptions<CacheTag extends string> = {
+    /**
+     * The time to live value.
+     */
+    ttl?: number,
+    /**
+     * Additional tags to set.
+     */
+    tags?: CacheTag[]
+};
+
+/**
+ * Options for the wrap method of a cache.
+ */
+export type CacheWrapOptions<V, TArgs extends unknown[], CacheTag extends string> = {
+    /**
+     * A provider for the time to live value.
+     */
+    ttl?: ResultCacheTtlProvider<V, TArgs>,
+    /**
+     * A provider for the tags to set.
+     */
+    tags?: ResultCacheTagsProvider<V, TArgs, CacheTag>
+};
+
+/**
+ * Options for the wrapWrite method of a cache when the result of the original function is available.
+ */
+export type CacheWrapWriteOptionsWithResult<V, TArgs extends unknown[], CacheTag extends string> = {
+    /**
+     * A provider for the time to live value.
+     */
+    ttl?: ResultCacheTtlProvider<V, TArgs>,
+    /**
+     * A provider for the tags to set.
+     */
+    tags?: ResultCacheTagsProvider<V, TArgs, CacheTag>,
+    /**
+     * A provider for the tags to invalidate.
+     */
+    invalidatesTags?: ResultCacheTagsProvider<V, TArgs, CacheTag>
+};
+
+/**
+ * Options for the wrapWrite method of a cache when the result of the original function is NOT available.
+ */
+export type CacheWrapWriteOptionsArgsOnly<TArgs extends unknown[], CacheTag extends string> = {
+    /**
+     * A provider for the time to live value.
+     */
+    ttl?: CacheTtlProvider<TArgs>,
+    /**
+     * A provider for the tags to set.
+     */
+    tags?: CacheTagsProvider<TArgs, CacheTag>,
+    /**
+     * A provider for the tags to invalidate.
+     */
+    invalidatesTags?: CacheTagsProvider<TArgs, CacheTag>
+};
+
+/**
+ * Options for the wrapDelete method of a cache.
+ */
+export type CacheWrapDeleteOptions<TArgs extends unknown[], CacheTag extends string> = {
+    /**
+     * A provider for the tags to invalidate.
+     */
+    invalidatesTags?: CacheTagsProvider<TArgs, CacheTag>
+};
+
+/**
+ * Options for the wrapInvalidate method of a cache.
+ */
+export type CacheWrapInvalidateOptions<TArgs extends unknown[], CacheTag extends string> = {
+    /**
+     * A provider for the tags to invalidate.
+     */
+    invalidatesTags: CacheTagsProvider<TArgs, CacheTag>
+};

package/src/caching/cache/cache.interface.ts

@@ -0,0 +1,133 @@
+import { type CacheTagMatcher } from '../cache-tag-matchers';
+import { CacheKeyProvider, CacheSetDirectOptions, CacheWrapDeleteOptions, CacheWrapInvalidateOptions, CacheWrapOptions, CacheWrapWriteOptionsArgsOnly, CacheWrapWriteOptionsWithResult, OnInvalidationFailure, ResultCacheKeyProvider } from './cache-options.model';
+import { MultiTierCache } from './multi-tier.cache';
+import { ExcludeStrict } from '../../types/exclude-strict.type';
+import { type CacheStoreInterface } from '../store/cache-store.interface';
+
+/**
+ * Definition for a cache.
+ */
+export interface CacheInterface<K, V, CacheTag extends string, WriteResultAvailable extends boolean, N extends string> {
+    /**
+     * Phantom carrier, only for type inference.
+     */
+    readonly _writeResultAvailable: WriteResultAvailable,
+    /**
+     * The name of the cache. Should be unique.
+     */
+    readonly name: N,
+    /**
+     * The tags that any values inside of this cache might have.
+     *
+     * This is used for performance improvements, to skip caches for invalidateTags if the given tag will never be inside any of the cached values.
+     * Can be set to 'all' to check every time.
+     */
+    readonly tags: 'all' | readonly CacheTagMatcher[],
+    /**
+     * The default time to live for a cached value.
+     */
+    readonly defaultTtl?: number | (() => number | Promise<number>),
+    /**
+     * Whether to throw when invalidation fails or to just log and ignore.
+     */
+    readonly onInvalidationFailure?: OnInvalidationFailure,
+    /**
+     * The store used by this cache.
+     */
+    readonly store: CacheStoreInterface<K, V>,
+
+    /**
+     * Returns a cached value if present; otherwise calls fn.
+     * The exact caching behavior (whether the result is stored) depends on the concrete strategy.
+     */
+    wrap: <TArgs extends unknown[]>(
+        fn: (...args: TArgs) => V | Promise<V>,
+        keyFn: CacheKeyProvider<K, TArgs>,
+        options?: CacheWrapOptions<V, TArgs, CacheTag>
+    ) => (...args: TArgs) => Promise<V>,
+
+    /**
+     * Returns a wrapped version of fn that writes its result into the cache.
+     * Key is derived from the *result*, not the args — handles the
+     * create-with-generated-id case cleanly.
+     */
+    wrapWrite: <TArgs extends unknown[]>(
+        fn: (...args: TArgs) => V | Promise<V>,
+        keyFn: WriteResultAvailable extends true
+            ? ResultCacheKeyProvider<K, V, TArgs>
+            : CacheKeyProvider<K, TArgs>,
+        options?: WriteResultAvailable extends true
+            ? CacheWrapWriteOptionsWithResult<V, TArgs, CacheTag>
+            : CacheWrapWriteOptionsArgsOnly<TArgs, CacheTag>
+    ) => (...args: TArgs) => Promise<V>,
+
+    /**
+     * Returns a wrapped version of fn that invalidates a cache entry after call.
+     */
+    wrapDelete: <TReturn, TArgs extends unknown[]>(
+        fn: (...args: TArgs) => TReturn | Promise<TReturn>,
+        keyFn: CacheKeyProvider<K, TArgs>,
+        options?: CacheWrapDeleteOptions<TArgs, CacheTag>
+    ) => (...args: TArgs) => Promise<TReturn>,
+
+    /**
+     * Calls fn → Invalidates tags → Returns the fn result.
+     * For operations that affect cached data but produce no cacheable result,
+     * e.g. CreateAll/updateAll on a collection cache where no filter key
+     * can be derived from the output.
+     */
+    wrapInvalidate: <TReturn, TArgs extends unknown[]>(
+        fn: (...args: TArgs) => TReturn | Promise<TReturn>,
+        options: CacheWrapInvalidateOptions<TArgs, CacheTag> // required — this method exists solely to invalidate
+    ) => (...args: TArgs) => Promise<TReturn>,
+    /**
+     * Directly write a value into this cache, following its configured
+     * write strategy.
+     *
+     * Use this instead of `wrapWrite` when the source function has already
+     * been called and you only need to propagate the result.
+     */
+    setDirect: (key: K, value: V, options?: CacheSetDirectOptions<CacheTag>) => Promise<void>
+}
+
+/**
+ * The type for any unspecified cache.
+ */
+// eslint-disable-next-line typescript/no-explicit-any, stylistic/max-len
+export type AnyCache = MultiTierCache<any, any, any> | CacheInterface<any, any, string, true, any> | CacheInterface<any, any, string, false, any>;
+
+/**
+ * Checks whether or not the given value is a cache.
+ * @param value - The value to check.
+ * @returns True if the value has all the keys of a cache, false otherwise.
+ */
+export function isCache(value: unknown): value is AnyCache {
+
+    if (value instanceof MultiTierCache) {
+        return true;
+    }
+    // eslint-disable-next-line typescript/no-explicit-any
+    const keys: (keyof ExcludeStrict<AnyCache, MultiTierCache<any, any, any>>)[] = [
+        'defaultTtl',
+        'name',
+        'onInvalidationFailure',
+        'store',
+        'tags',
+        'wrap',
+        'wrapDelete',
+        'wrapInvalidate',
+        'wrapWrite'
+    ];
+
+    if (value == undefined || typeof value !== 'object') {
+        return false;
+    }
+
+    for (const key of keys) {
+        if (!(key in value)) {
+            return false;
+        }
+    }
+
+    return true;
+}