zibri 2.3.0 → 2.4.1

package/src/caching/cache/read-through/write-through-read-through.cache.ts

@@ -0,0 +1,77 @@
+import { AlsUtilities } from '../../../context/als.utilities';
+import { CacheContext } from '../../../context/cache/cache.context';
+import { CacheOperation } from '../cache-operation.enum';
+import { ResultCacheKeyProvider, CacheWrapWriteOptionsWithResult, CacheSetDirectOptions } from '../cache-options.model';
+import { CacheInterface } from '../cache.interface';
+import { ReadThroughCache } from './read-through.cache';
+
+/**
+ * A write-through read-through cache.
+ */
+export abstract class WriteThroughReadThroughCache<K, V, N extends string, CacheTag extends string = string>
+    extends ReadThroughCache<K, V, CacheTag, true, N>
+    implements CacheInterface<K, V, CacheTag, true, N> {
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly _writeResultAvailable: true = true;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    wrapWrite<TArgs extends unknown[]>(
+        fn: (...args: TArgs) => V | Promise<V>,
+        keyFn: ResultCacheKeyProvider<K, V, TArgs>,
+        options?: CacheWrapWriteOptionsWithResult<V, TArgs, CacheTag>
+    ): (...args: TArgs) => Promise<V> {
+        return async (...args) => {
+            const cacheCtx: CacheContext = { cache: this.name, operation: CacheOperation.WRITE };
+
+            return AlsUtilities.runWithCacheContext(cacheCtx, async () => {
+                const sourceStart: number = performance.now();
+                const value: V = await fn(...args);
+                const sourceDuration: number = performance.now() - sourceStart;
+                cacheCtx.durationInMs = sourceDuration;
+                this.metrics.sourceDuration.observe({ cache: this.name, operation: CacheOperation.WRITE }, sourceDuration);
+
+                await this.safeInvalidateTags(options?.invalidatesTags, value, args);
+
+                try {
+                    const key: K = await keyFn(value, ...args);
+                    cacheCtx.key = key;
+                    const [tags, ttl] = await Promise.all([
+                        this.resolveResultTags(options?.tags, value, args),
+                        this.resolveResultTtl(options?.ttl, value, args)
+                    ]);
+
+                    const storeStart: number = performance.now();
+                    await this.store.set(key, this.createCachedValue(value, tags, ttl));
+                    this.metrics.storeDuration.observe({ cache: this.name, operation: 'set' }, performance.now() - storeStart);
+                    this.metrics.writes.increase({ cache: this.name });
+                    await this.updateSizeGauge();
+                }
+                catch (error) {
+                    this.metrics.errors.increase({ cache: this.name, operation: 'set' });
+                    await this.logger.warn(
+                        'Cache store failed after successful source write, source write was not rolled back',
+                        { error }
+                    );
+                }
+
+                return value;
+            });
+        };
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async setDirect(key: K, value: V, options?: CacheSetDirectOptions<CacheTag>): Promise<void> {
+        try {
+            const ttl: number | undefined = options?.ttl ?? await this.resolveResultTtl(undefined, value, []);
+            const tags: CacheTag[] = options?.tags ?? [];
+            await this.store.set(key, this.createCachedValue(value, tags, ttl));
+            this.metrics.writes.increase({ cache: this.name });
+            await this.updateSizeGauge();
+        }
+        catch (error) {
+            this.metrics.errors.increase({ cache: this.name, operation: 'set' });
+            await this.logger.warn('Cache store failed in setDirect', { error });
+        }
+    }
+}

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

@@ -0,0 +1,57 @@
+import { CounterInterface } from '../metrics/counter.interface';
+import { GaugeInterface } from '../metrics/gauge.interface';
+import { HistogramInterface } from '../metrics/histogram.interface';
+
+/**
+ * Metrics regarding caching.
+ */
+export type CacheMetrics = {
+    /**
+     * How many times caches have been hit.
+     */
+    hits: CounterInterface,
+    /**
+     * How many times caches have been missed.
+     */
+    misses: CounterInterface,
+    /**
+     * How many times values have been written to caches.
+     */
+    writes: CounterInterface,
+    /**
+     * How many times values have been deleted from caches.
+     */
+    deletes: CounterInterface,
+    /**
+     * How many times cache invalidations have happened.
+     */
+    invalidations: CounterInterface,
+    /**
+     * How many times cache invalidations have failed.
+     */
+    invalidationFailures: CounterInterface,
+    /**
+     * How many times cached values have expired.
+     */
+    expiredEvictions: CounterInterface,
+    /**
+     * How many times errors occurred during caching.
+     */
+    errors: CounterInterface,
+    /**
+     * The current amount of inFlight cache operations.
+     */
+    inFlight: GaugeInterface,
+    /**
+     * The amount of cached values.
+     */
+    size: GaugeInterface,
+    /**
+     * The duration of the original functions.
+     */
+    sourceDuration: HistogramInterface,
+    /**
+     * The duration of cache operations.
+     */
+    storeDuration: HistogramInterface
+};

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

@@ -0,0 +1,15 @@
+import { AnyCache } from './cache/cache.interface';
+
+/**
+ * Interface for a cache service.
+ */
+export interface CacheServiceInterface {
+    /**
+     * All caches that have been registered.
+     */
+    readonly caches: AnyCache[],
+    /**
+     * Invalidates the given tags through all caches.
+     */
+    invalidateTags: (tags: string[]) => void | Promise<void>
+}

package/src/caching/cache-tag-matchers.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it, jest } from '@jest/globals';
+
+import { CacheTagMatcher, matchesAnyTag, matchesTag } from './cache-tag-matchers';
+
+describe('matchesTag', () => {
+    it('matches exact string tags', () => {
+        expect(matchesTag('user:1', 'user:1')).toBe(true);
+        expect(matchesTag('user:1', 'user:2')).toBe(false);
+    });
+
+    it('matches regex tags', () => {
+        expect(matchesTag(/^user:\d+$/, 'user:1')).toBe(true);
+        expect(matchesTag(/^user:\d+$/, 'profile:1')).toBe(false);
+    });
+
+    it('matches predicate tags', () => {
+        const matcher: CacheTagMatcher = (tag: string): boolean => tag.startsWith('user:');
+        expect(matchesTag(matcher, 'user:1')).toBe(true);
+        expect(matchesTag(matcher, 'profile:1')).toBe(false);
+    });
+
+    it('supports broad regex matches', () => {
+        expect(matchesTag(/.*/, 'anything')).toBe(true);
+    });
+
+    it('regex matching is case sensitive by default', () => {
+        expect(matchesTag(/^user$/, 'User')).toBe(false);
+    });
+
+    it('predicate matchers receive the exact tag string', () => {
+        const matcher: CacheTagMatcher = jest.fn((tag: string): boolean => tag === 'abc');
+        expect(matchesTag(matcher, 'abc')).toBe(true);
+        expect(matcher).toHaveBeenCalledTimes(1);
+        expect(matcher).toHaveBeenCalledWith('abc');
+    });
+});
+
+describe('matchesAnyTag', () => {
+    it('returns true when at least one matcher matches at least one tag', () => {
+        const matchers: CacheTagMatcher[] = ['foo', /^bar$/, (tag: string): boolean => tag === 'baz'] as const;
+        const tags: string[] = ['nope', 'baz'];
+
+        expect(matchesAnyTag(matchers, tags)).toBe(true);
+    });
+
+    it('returns false when no matcher matches any tag', () => {
+        const matchers: CacheTagMatcher[] = ['foo', /^bar$/, (tag: string): boolean => tag === 'baz'] as const;
+        const tags: string[] = ['nope', 'also-nope'];
+
+        expect(matchesAnyTag(matchers, tags)).toBe(false);
+    });
+
+    it('returns true for a single string match', () => {
+        expect(matchesAnyTag(['user:1'], ['x', 'user:1', 'y'])).toBe(true);
+    });
+
+    it('returns true for a single regex match', () => {
+        expect(matchesAnyTag([/^user:\d+$/], ['profile:1', 'user:42'])).toBe(true);
+    });
+
+    it('returns true for a single predicate match', () => {
+        expect(matchesAnyTag([(tag: string): boolean => tag.endsWith(':write')], ['cache:read', 'cache:write'])).toBe(true);
+    });
+
+    it('returns false for empty matcher list', () => {
+        expect(matchesAnyTag([], ['a', 'b'])).toBe(false);
+    });
+
+    it('returns false for empty tag list', () => {
+        expect(matchesAnyTag(['a', /b/, (tag: string): boolean => tag === 'c'], [])).toBe(false);
+    });
+
+    it('short-circuits once a match is found', () => {
+        const matcher1: CacheTagMatcher = jest.fn((tag: string): boolean => tag === 'match');
+        const matcher2: CacheTagMatcher = jest.fn((): boolean => true);
+
+        expect(matchesAnyTag([matcher1, matcher2], ['match'])).toBe(true);
+        expect(matcher1).toHaveBeenCalledTimes(1);
+        expect(matcher2).not.toHaveBeenCalled();
+    });
+
+    it('checks tags against all matchers until one succeeds', () => {
+        const matcher1: CacheTagMatcher = jest.fn((tag: string): boolean => tag === 'nope');
+        const matcher2: CacheTagMatcher = jest.fn((tag: string): boolean => tag === 'match');
+
+        expect(matchesAnyTag([matcher1, matcher2], ['a', 'match'])).toBe(true);
+        expect(matcher1).toHaveBeenCalled();
+        expect(matcher2).toHaveBeenCalled();
+    });
+
+    it('handles duplicate tags without issue', () => {
+        expect(matchesAnyTag(['x'], ['a', 'x', 'x'])).toBe(true);
+    });
+
+    it('handles duplicate matchers without issue', () => {
+        const matcher: CacheTagMatcher = jest.fn((tag: string): boolean => tag === 'x');
+
+        expect(matchesAnyTag([matcher, matcher], ['x'])).toBe(true);
+        expect(matcher).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not mutate matchers or tags', () => {
+        const matchers: CacheTagMatcher[] = ['x', /y/];
+        const tags: string[] = ['x', 'y'];
+
+        const matchersBefore: CacheTagMatcher[] = [...matchers];
+        const tagsBefore: string[] = [...tags];
+
+        matchesAnyTag(matchers, tags);
+
+        expect(matchers).toEqual(matchersBefore);
+        expect(tags).toEqual(tagsBefore);
+    });
+});

package/src/caching/cache-tag-matchers.ts

@@ -0,0 +1,31 @@
+
+/**
+ * Matcher for a tag.
+ */
+export type CacheTagMatcher = | string | RegExp | ((tag: string) => boolean);
+
+/**
+ * Checks whether the given matchers match any of the given tags.
+ * @param matchers - The matchers used for the check.
+ * @param tags - The tags to check.
+ * @returns True if any of the tags are matched by at least one of the matchers, false otherwise.
+ */
+export function matchesAnyTag(matchers: readonly CacheTagMatcher[], tags: string[]): boolean {
+    return matchers.some(matcher => tags.some(tag => matchesTag(matcher, tag)));
+}
+
+/**
+ * Checks whether or not the given matcher matches the given tag.
+ * @param matcher - The matcher used for the check.
+ * @param tag - The tag to check.
+ * @returns True if the matcher matches the tag, false otherwise.
+ */
+export function matchesTag(matcher: CacheTagMatcher, tag: string): boolean {
+    if (typeof matcher === 'string') {
+        return matcher === tag;
+    }
+    if (matcher instanceof RegExp) {
+        return matcher.test(tag);
+    }
+    return matcher(tag);
+}

package/src/caching/cache.service.test.ts

@@ -0,0 +1,211 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, jest } from '@jest/globals';
+
+import { type CacheServiceInterface } from './cache-service.interface';
+import { CacheService } from './cache.service';
+import { Cache } from './decorators/cache.decorator';
+import { CachedValue } from './store/cached-value.model';
+import { InMemoryCacheStore } from './store/in-memory.cache-store';
+import { StartedTestServer, startTestServer } from '../__testing__/test-server/start-test-server.function';
+import { Inject } from '../di/decorators/inject.decorator';
+import { ZIBRI_DI_TOKENS } from '../di/default/zibri-di-tokens.default';
+import { inject } from '../di/inject.function';
+import { type LoggerInterface } from '../logging/logger.interface';
+import { type MetricsServiceInterface } from '../metrics/metrics-service.interface';
+import { WriteThroughReadThroughCache } from './cache/read-through/write-through-read-through.cache';
+
+@Cache()
+class UserTagCache extends WriteThroughReadThroughCache<string, string, 'User Tag Cache'> {
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER) protected readonly logger: LoggerInterface,
+        @Inject(ZIBRI_DI_TOKENS.METRICS_SERVICE) protected readonly metricsService: MetricsServiceInterface,
+        @Inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) protected readonly cacheService: CacheServiceInterface
+    ) {
+        super('User Tag Cache', new InMemoryCacheStore(), ['user']);
+    }
+}
+
+@Cache()
+class PostTagCache extends WriteThroughReadThroughCache<string, string, 'Post Tag Cache'> {
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER) protected readonly logger: LoggerInterface,
+        @Inject(ZIBRI_DI_TOKENS.METRICS_SERVICE) protected readonly metricsService: MetricsServiceInterface,
+        @Inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) protected readonly cacheService: CacheServiceInterface
+    ) {
+        super('Post Tag Cache', new InMemoryCacheStore(), ['post']);
+    }
+}
+
+@Cache()
+class UserRegexCache extends WriteThroughReadThroughCache<string, string, 'User Regex Cache'> {
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER) protected readonly logger: LoggerInterface,
+        @Inject(ZIBRI_DI_TOKENS.METRICS_SERVICE) protected readonly metricsService: MetricsServiceInterface,
+        @Inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) protected readonly cacheService: CacheServiceInterface
+    ) {
+        super('User Regex Cache', new InMemoryCacheStore(), [/^user:/]);
+    }
+}
+
+@Cache()
+class PostRegexCache extends WriteThroughReadThroughCache<string, string, 'Post Regex Cache'> {
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER) protected readonly logger: LoggerInterface,
+        @Inject(ZIBRI_DI_TOKENS.METRICS_SERVICE) protected readonly metricsService: MetricsServiceInterface,
+        @Inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) protected readonly cacheService: CacheServiceInterface
+    ) {
+        super('Post Regex Cache', new InMemoryCacheStore(), [/^post:/]);
+    }
+}
+
+@Cache()
+class UserPredicateCache extends WriteThroughReadThroughCache<string, string, 'User Predicate Cache'> {
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER) protected readonly logger: LoggerInterface,
+        @Inject(ZIBRI_DI_TOKENS.METRICS_SERVICE) protected readonly metricsService: MetricsServiceInterface,
+        @Inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) protected readonly cacheService: CacheServiceInterface
+    ) {
+        super('User Predicate Cache', new InMemoryCacheStore(), [(tag: string) => tag.startsWith('user:')]);
+    }
+}
+
+@Cache()
+class OtherPredicateCache extends WriteThroughReadThroughCache<string, string, 'Other Predicate Cache'> {
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER) protected readonly logger: LoggerInterface,
+        @Inject(ZIBRI_DI_TOKENS.METRICS_SERVICE) protected readonly metricsService: MetricsServiceInterface,
+        @Inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) protected readonly cacheService: CacheServiceInterface
+    ) {
+        super('Other Predicate Cache', new InMemoryCacheStore(), [(tag: string) => tag.startsWith('other:')]);
+    }
+}
+
+@Cache()
+class AllTagsCache extends WriteThroughReadThroughCache<string, string, 'All Tags Cache'> {
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER) protected readonly logger: LoggerInterface,
+        @Inject(ZIBRI_DI_TOKENS.METRICS_SERVICE) protected readonly metricsService: MetricsServiceInterface,
+        @Inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) protected readonly cacheService: CacheServiceInterface
+    ) {
+        super('All Tags Cache', new InMemoryCacheStore(), 'all');
+    }
+}
+
+@Cache()
+class UnrelatedTagCache extends WriteThroughReadThroughCache<string, string, 'Unrelated Tag Cache'> {
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER) protected readonly logger: LoggerInterface,
+        @Inject(ZIBRI_DI_TOKENS.METRICS_SERVICE) protected readonly metricsService: MetricsServiceInterface,
+        @Inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) protected readonly cacheService: CacheServiceInterface
+    ) {
+        super('Unrelated Tag Cache', new InMemoryCacheStore(), ['unrelated']);
+    }
+}
+
+function createCachedValue<V>(value: V, tags: string[]): CachedValue<V> {
+    return { value, tags, createdAt: new Date() };
+}
+
+describe('CacheService', () => {
+    let server: StartedTestServer;
+    let cacheService: CacheService;
+
+    beforeAll(async () => {
+        server = await startTestServer();
+        cacheService = inject(ZIBRI_DI_TOKENS.CACHE_SERVICE) as CacheService;
+    }, 15000);
+
+    afterAll(async () => {
+        await server?.shutdown();
+    });
+
+    beforeEach(async () => {
+        cacheService.caches.length = 0;
+        await inject(UserTagCache).store.clear();
+        await inject(PostTagCache).store.clear();
+        await inject(UserRegexCache).store.clear();
+        await inject(PostRegexCache).store.clear();
+        await inject(UserPredicateCache).store.clear();
+        await inject(OtherPredicateCache).store.clear();
+        await inject(AllTagsCache).store.clear();
+        await inject(UnrelatedTagCache).store.clear();
+    });
+
+    it('invalidates only caches whose declared tags match', async () => {
+        const userCache: UserTagCache = inject(UserTagCache);
+        const postCache: PostTagCache = inject(PostTagCache);
+
+        cacheService.caches.push(userCache, postCache);
+
+        await userCache.store.set('u1', createCachedValue('user-value', ['user']));
+        await postCache.store.set('p1', createCachedValue('post-value', ['post']));
+
+        await cacheService.invalidateTags(['user']);
+
+        expect(await userCache.store.get('u1')).toBeUndefined();
+        expect((await postCache.store.get('p1'))?.value).toBe('post-value');
+    });
+
+    it('invalidates caches with tag matchers based on regex', async () => {
+        const userCache: UserRegexCache = inject(UserRegexCache);
+        const postCache: PostRegexCache = inject(PostRegexCache);
+
+        cacheService.caches.push(userCache, postCache);
+
+        await userCache.store.set('u1', createCachedValue('user-value', ['user:1']));
+        await postCache.store.set('p1', createCachedValue('post-value', ['post:1']));
+
+        await cacheService.invalidateTags(['user:1']);
+
+        expect(await userCache.store.get('u1')).toBeUndefined();
+        expect((await postCache.store.get('p1'))?.value).toBe('post-value');
+    });
+
+    it('invalidates caches with tag matchers based on predicate functions', async () => {
+        const userCache: UserPredicateCache = inject(UserPredicateCache);
+        const otherCache: OtherPredicateCache = inject(OtherPredicateCache);
+
+        cacheService.caches.push(userCache, otherCache);
+
+        await userCache.store.set('u1', createCachedValue('user-value', ['user:1']));
+        await otherCache.store.set('o1', createCachedValue('other-value', ['other:1']));
+
+        await cacheService.invalidateTags(['user:1']);
+
+        expect(await userCache.store.get('u1')).toBeUndefined();
+        expect((await otherCache.store.get('o1'))?.value).toBe('other-value');
+    });
+
+    it('treats tag matchers as an optimization and only calls invalidateTags on affected caches', async () => {
+        const allCache: AllTagsCache = inject(AllTagsCache);
+        const postCache: PostTagCache = inject(PostTagCache);
+
+        cacheService.caches.push(allCache, postCache);
+
+        await allCache.store.set('a', createCachedValue('all-value', ['keep-me']));
+        await postCache.store.set('p', createCachedValue('post-value', ['post']));
+
+        // eslint-disable-next-line typescript/typedef
+        const allInvalidateSpy = jest.spyOn(allCache.store, 'invalidateTags');
+        // eslint-disable-next-line typescript/typedef
+        const postInvalidateSpy = jest.spyOn(postCache.store, 'invalidateTags');
+
+        await cacheService.invalidateTags(['user']);
+
+        expect(allInvalidateSpy).toHaveBeenCalledTimes(1);
+        expect(postInvalidateSpy).not.toHaveBeenCalled();
+
+        expect((await allCache.store.get('a'))?.value).toBe('all-value');
+        expect((await postCache.store.get('p'))?.value).toBe('post-value');
+    });
+
+    it('does nothing when no cache declares matching tags', async () => {
+        const cache: UnrelatedTagCache = inject(UnrelatedTagCache);
+
+        cacheService.caches.push(cache);
+        await cache.store.set('x', createCachedValue('value', ['x']));
+
+        await cacheService.invalidateTags(['different']);
+
+        expect((await cache.store.get('x'))?.value).toBe('value');
+    });
+});

package/src/caching/cache.service.ts

@@ -0,0 +1,69 @@
+import { AnyCache, isCache } from './cache/cache.interface';
+import { CacheServiceInterface } from './cache-service.interface';
+import { matchesAnyTag } from './cache-tag-matchers';
+import { Inject } from '../di/decorators/inject.decorator';
+import { Injectable } from '../di/decorators/injectable.decorator';
+import { ZIBRI_DI_TOKENS } from '../di/default/zibri-di-tokens.default';
+import { inject } from '../di/inject.function';
+import { GlobalRegistry } from '../global/global-registry';
+import { OnAppInit } from '../global/on-app-init.interface';
+import { type LoggerInterface } from '../logging/logger.interface';
+import { MultiTierCache } from './cache/multi-tier.cache';
+
+/**
+ * Default implementation of the cache service.
+ */
+@Injectable({ register: 'onUse' })
+export class CacheService implements CacheServiceInterface, OnAppInit {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly caches: AnyCache[] = [];
+
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER)
+        private readonly logger: LoggerInterface
+    ) {}
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async onAppInit(): Promise<void> {
+        if (GlobalRegistry.cacheClasses.length) {
+            // eslint-disable-next-line stylistic/max-len
+            await this.logger.info(`configures ${GlobalRegistry.cacheClasses.length} ${GlobalRegistry.cacheClasses.length > 1 ? 'caches' : 'cache'}:`);
+        }
+
+        for (const cacheClass of GlobalRegistry.cacheClasses) {
+            const cache: AnyCache = inject(cacheClass);
+            this.caches.push(cache);
+            if (!isCache(cache)) {
+                throw new Error(`Invalid class marked with @Cache: ${cacheClass.name} needs to implement CacheInterface`);
+            }
+            await this.logger.info(`  - ${cache.name}`);
+        }
+
+        for (const cacheInjectable of GlobalRegistry.injectables.map(i => inject(i.token)).filter(i => isCache(i))) {
+            if (!this.caches.find(c => c.name === cacheInjectable.name)) {
+                throw new Error(`The class "${cacheInjectable.constructor}" seems to be a cache but has not been decorated with @Cache()`);
+            }
+        }
+
+        const duplicateCacheNames: AnyCache[] = this.caches.filter(
+            c => this.caches.filter(internalC => internalC.name === c.name).length > 1
+        );
+        if (duplicateCacheNames.length) {
+            throw new Error(
+                [
+                    'There are duplicate cache names:',
+                    [...new Set(duplicateCacheNames)].map(s => `- ${s.name}`)
+                ].join('\n')
+            );
+        }
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async invalidateTags(tags: string[]): Promise<void> {
+        // Only hit caches that actually declared these tags
+        const affectedCaches: AnyCache[] = this.caches.filter(
+            c => !(c instanceof MultiTierCache) && (c.tags === 'all' || matchesAnyTag(c.tags, tags))
+        );
+        await Promise.all(affectedCaches.map(c => c instanceof MultiTierCache ? undefined : c.store.invalidateTags(tags)));
+    }
+}

package/src/caching/decorators/cache-delete.decorator.ts

@@ -0,0 +1,46 @@
+import { inject } from '../../di/inject.function';
+import { DiToken } from '../../di/models/di-token.model';
+import { CacheKeyProvider, CacheWrapDeleteOptions } from '../cache/cache-options.model';
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Marks the method to delete a cached value under the resolved key using the provided cache.
+ * @param cacheToken - The token of the cache to use.
+ * @param keyFn - How to resolve the key that should be deleted from the cache.
+ * @param options - Additional options like tags to invalidate.
+ */
+export function CacheDelete<
+    // eslint-disable-next-line jsdoc/require-jsdoc, typescript/no-explicit-any
+    C extends { wrapDelete: (...args: any[]) => any },
+    K,
+    CacheTag extends string,
+    TReturn,
+    TArgs extends unknown[]
+>(
+    cacheToken: DiToken<C>,
+    keyFn: CacheKeyProvider<K, TArgs>,
+    options?: CacheWrapDeleteOptions<TArgs, CacheTag>
+) {
+    return (
+        target: object,
+        propertyKey: string | symbol,
+        descriptor: TypedPropertyDescriptor<(...args: TArgs) => Promise<TReturn>>
+    ): TypedPropertyDescriptor<(...args: TArgs) => Promise<TReturn>> => {
+        // eslint-disable-next-line typescript/no-non-null-assertion
+        const original: (...args: TArgs) => Promise<TReturn> = descriptor.value!;
+        const wrappedFns: WeakMap<object, (...args: TArgs) => Promise<TReturn>> = new WeakMap();
+
+        descriptor.value = async function(this: object, ...args: TArgs): Promise<TReturn> {
+            if (!wrappedFns.has(this)) {
+                // eslint-disable-next-line typescript/typedef
+                const cache = inject(cacheToken);
+                // eslint-disable-next-line typescript/no-unsafe-argument
+                wrappedFns.set(this, cache.wrapDelete(original.bind(this), keyFn, options));
+            }
+            // eslint-disable-next-line typescript/no-non-null-assertion
+            return await wrappedFns.get(this)!(...args);
+        };
+
+        return descriptor;
+    };
+}

package/src/caching/decorators/cache-invalidate.decorator.ts

@@ -0,0 +1,43 @@
+import { inject } from '../../di/inject.function';
+import { DiToken } from '../../di/models/di-token.model';
+import { CacheWrapInvalidateOptions } from '../cache/cache-options.model';
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Marks the method to invalidate some cached values resolved by the provided options using the provided cache.
+ * @param cacheToken - The token of the cache to use.
+ * @param options - Additional options, including tags to invalidate.
+ */
+export function CacheInvalidate<
+    // eslint-disable-next-line jsdoc/require-jsdoc, typescript/no-explicit-any
+    C extends { wrapInvalidate: (...args: any[]) => any },
+    CacheTag extends string,
+    TReturn,
+    TArgs extends unknown[]
+>(
+    cacheToken: DiToken<C>,
+    options: CacheWrapInvalidateOptions<TArgs, CacheTag>
+) {
+    return (
+        target: object,
+        propertyKey: string | symbol,
+        descriptor: TypedPropertyDescriptor<(...args: TArgs) => Promise<TReturn>>
+    ): TypedPropertyDescriptor<(...args: TArgs) => Promise<TReturn>> => {
+        // eslint-disable-next-line typescript/no-non-null-assertion
+        const original: (...args: TArgs) => Promise<TReturn> = descriptor.value!;
+        const wrappedFns: WeakMap<object, (...args: TArgs) => Promise<TReturn>> = new WeakMap();
+
+        descriptor.value = async function(this: object, ...args: TArgs): Promise<TReturn> {
+            if (!wrappedFns.has(this)) {
+                // eslint-disable-next-line typescript/typedef
+                const cache = inject(cacheToken);
+                // eslint-disable-next-line typescript/no-unsafe-argument
+                wrappedFns.set(this, cache.wrapInvalidate(original.bind(this), options));
+            }
+            // eslint-disable-next-line typescript/no-non-null-assertion
+            return wrappedFns.get(this)!(...args);
+        };
+
+        return descriptor;
+    };
+}