zibri 2.3.0 → 2.4.0

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

@@ -0,0 +1,60 @@
+import { ExtractCacheWriteResultAvailable } from './decorator-types';
+import { inject } from '../../di/inject.function';
+import { DiToken } from '../../di/models/di-token.model';
+import { CacheKeyProvider, CacheWrapWriteOptionsArgsOnly, CacheWrapWriteOptionsWithResult, ResultCacheKeyProvider } from '../cache/cache-options.model';
+import { CacheInterface } from '../cache/cache.interface';
+import { MultiTierCache, MultiWrapWriteOptions } from '../cache/multi-tier.cache';
+
+/** Extract the wrapWrite options type for a given cache and TArgs. */
+type ExtractWrapWriteOptions<C, TArgs extends unknown[]>
+    // eslint-disable-next-line typescript/no-explicit-any
+    = C extends MultiTierCache<any, infer V, infer Tiers, infer CacheTag>
+        ? MultiWrapWriteOptions<V, TArgs, CacheTag, Tiers>
+        // eslint-disable-next-line typescript/no-explicit-any
+        : C extends Pick<CacheInterface<any, infer V, infer CacheTag, infer WR, any>, 'wrapWrite'>
+            ? (WR extends true
+                ? CacheWrapWriteOptionsWithResult<V, TArgs, CacheTag>
+                : CacheWrapWriteOptionsArgsOnly<TArgs, CacheTag>)
+            : never;
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Marks the method to write the result to the cache using the provided cache.
+ * @param cacheToken - The token of the cache to use.
+ * @param keyFn - How to resolve the key under which results should be cached.
+ * @param options - Additional options like ttl or tags.
+ */
+// eslint-disable-next-line jsdoc/require-jsdoc, typescript/no-explicit-any
+export function CacheWrite<C extends { wrapWrite: (...args: any[]) => any }, K, V, TArgs extends unknown[]>(
+    cacheToken: DiToken<C>,
+    keyFn: ExtractCacheWriteResultAvailable<C> extends true
+        ? ResultCacheKeyProvider<K, V, TArgs>
+        : CacheKeyProvider<K, TArgs>,
+    options?: ExtractWrapWriteOptions<C, TArgs>
+) {
+    return function decorator(
+        target: object,
+        propertyKey: string | symbol,
+        descriptor: TypedPropertyDescriptor<(...args: TArgs) => Promise<V>>
+    ): TypedPropertyDescriptor<(...args: TArgs) => Promise<V>> {
+        // eslint-disable-next-line typescript/no-non-null-assertion
+        const original: (...args: TArgs) => Promise<V> = descriptor.value!;
+        const wrappedFns: WeakMap<object, (...args: TArgs) => Promise<V>> = new WeakMap();
+
+        descriptor.value = async function(this: object, ...args: TArgs): Promise<V> {
+            if (!wrappedFns.has(this)) {
+                // eslint-disable-next-line typescript/typedef
+                const cache = inject(cacheToken);
+                wrappedFns.set(
+                    this,
+                    // eslint-disable-next-line typescript/no-unsafe-argument
+                    cache.wrapWrite(original.bind(this), keyFn, options)
+                );
+            }
+            // eslint-disable-next-line typescript/no-non-null-assertion
+            return wrappedFns.get(this)!(...args);
+        };
+
+        return descriptor;
+    };
+}

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

@@ -0,0 +1,20 @@
+import { GlobalRegistry } from '../../global/global-registry';
+import { Newable } from '../../types/newable.type';
+import { MetadataUtilities } from '../../utilities/metadata.utilities';
+import { AnyCache } from '../cache/cache.interface';
+
+/**
+ * Marks a class that should be used as a cache.
+ */
+export function Cache(): ClassDecorator {
+    return target => {
+        // eslint-disable-next-line unicorn/error-message
+        const stack: string = new Error().stack ?? '';
+        MetadataUtilities.setFilePath(target, stack);
+        GlobalRegistry.injectables.push({
+            token: target as unknown as Newable<unknown>,
+            useClass: target as unknown as Newable<unknown>
+        });
+        GlobalRegistry.cacheClasses.push(target as unknown as Newable<AnyCache>);
+    };
+}

package/src/caching/decorators/cached.decorator.ts

@@ -0,0 +1,52 @@
+import { inject } from '../../di/inject.function';
+import { DiToken } from '../../di/models/di-token.model';
+import { CacheKeyProvider, CacheWrapOptions } from '../cache/cache-options.model';
+import { CacheInterface } from '../cache/cache.interface';
+import { MultiTierCache, MultiWrapOptions } from '../cache/multi-tier.cache';
+
+// eslint-disable-next-line jsdoc/require-jsdoc
+type ExtractWrapOptions<C, TArgs extends unknown[]>
+    // eslint-disable-next-line typescript/no-explicit-any
+    = C extends MultiTierCache<any, infer V, infer Tiers, infer CacheTag>
+        ? MultiWrapOptions<V, TArgs, CacheTag, Tiers>
+        // eslint-disable-next-line typescript/no-explicit-any
+        : C extends Pick<CacheInterface<any, infer V, infer CacheTag, any, any>, 'wrap'>
+            ? CacheWrapOptions<V, TArgs, CacheTag>
+            : never;
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Marks the method for caching via the given cache token.
+ * @param cacheToken - The token of the cache to use.
+ * @param keyFn - How to resolve the key under which results are cached.
+ * @param options - Additional options like ttl or tags.
+ */
+// eslint-disable-next-line jsdoc/require-jsdoc, typescript/no-explicit-any
+export function Cached<C extends { wrap: (...args: any[]) => any }, K, V, TArgs extends unknown[]>(
+    cacheToken: DiToken<C>,
+    keyFn: CacheKeyProvider<K, TArgs>,
+    options?: ExtractWrapOptions<C, TArgs>
+) {
+    return (
+        target: object,
+        propertyKey: string | symbol,
+        descriptor: TypedPropertyDescriptor<(...args: TArgs) => Promise<V>>
+    ): TypedPropertyDescriptor<(...args: TArgs) => Promise<V>> => {
+        // eslint-disable-next-line typescript/no-non-null-assertion
+        const original: (...args: TArgs) => V | Promise<V> = descriptor.value!;
+        const wrappedFns: WeakMap<object, (...args: TArgs) => Promise<V>> = new WeakMap();
+
+        descriptor.value = async function(this: object, ...args: TArgs): Promise<V> {
+            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.wrap(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/decorator-types.ts

@@ -0,0 +1,20 @@
+import { CacheInterface } from '../cache/cache.interface';
+import { MultiTierCache } from '../cache/multi-tier.cache';
+
+/**
+ * Extracts the key type `K` from a cache-like type.
+ */
+export type ExtractCacheKey<C>
+    // eslint-disable-next-line typescript/no-explicit-any
+    = C extends MultiTierCache<infer K, any, any, any>
+        ? K
+        // eslint-disable-next-line typescript/no-explicit-any
+        : C extends CacheInterface<infer K, any, any, any, any>
+            ? K
+            : never;
+
+/** Extract the WriteResultAvailable flag from a cache-like type. */
+// eslint-disable-next-line jsdoc/require-jsdoc
+export type ExtractCacheWriteResultAvailable<C> = C extends { _writeResultAvailable: infer WR }
+    ? (WR extends boolean ? WR : never)
+    : never;

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

@@ -0,0 +1,59 @@
+import { CachedValue } from './cached-value.model';
+
+/**
+ * The different strategies on how to handle cache overflows.
+ */
+export type RemoveOnOverflowStrategy = 'leastRecentlyUsed' | 'mostRecentlyUsed' | 'leastFrequentlyUsed' | 'firstInFirstOut';
+
+/**
+ * Configuration of a cache store.
+ */
+export type CacheStoreConfig = {
+    /**
+     * The maximum amount of entries that the store can hold.
+     */
+    readonly maxEntries: number,
+    /**
+     * The maximum amount of bytes that this store can hold.
+     * Checks are done usually done using estimations, not exact numbers.
+     */
+    readonly maxBytes: number,
+    /**
+     * How to handle caches that exceed their maxEntries or maxBytes.
+     */
+    readonly removeOnOverflow: RemoveOnOverflowStrategy
+};
+
+/**
+ * Interface for an cache store.
+ */
+export interface CacheStoreInterface<K, V> {
+    /**
+     * The configuration for the store.
+     */
+    readonly config: CacheStoreConfig,
+    /**
+     * Gets the cached value stored under the given key.
+     */
+    get: (key: K) => CachedValue<V> | undefined | Promise<CachedValue<V> | undefined>,
+    /**
+     * Stores a new cached value under the given key.
+     */
+    set: (key: K, value: CachedValue<V>) => void | Promise<void>,
+    /**
+     * Deletes the cached value stored under the given key.
+     */
+    delete: (key: K) => void | Promise<void>,
+    /**
+     * Completely clears all values from the cache.
+     */
+    clear: () => void | Promise<void>,
+    /**
+     * Invalidates all cached values that have one of the given tags.
+     */
+    invalidateTags: (tags: string[]) => void | Promise<void>,
+    /**
+     * The number of elements in the store.
+     */
+    size: () => number | Promise<number>
+}

package/src/caching/store/cached-value.model.ts

@@ -0,0 +1,27 @@
+import { Property } from '../../entity/decorators/property.decorator';
+
+/**
+ * Definition for a cached value.
+ */
+export class CachedValue<V> {
+    /**
+     * The timestamp at which the value has been cached.
+     */
+    @Property.date({ default: () => new Date() })
+    createdAt!: Date;
+    /**
+     * The timestamp at which this cached value expires.
+     */
+    @Property.date({ required: false })
+    expiresAt?: Date;
+    /**
+     * The actual value that has been cached.
+     */
+    @Property.unknown({ required: false })
+    value!: V;
+    /**
+     * Optional tags that the value can have and can be invalidated by.
+     */
+    @Property.array({ items: { type: 'string' } })
+    tags!: string[];
+}

package/src/caching/store/in-memory.cache-store.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { CachedValue } from './cached-value.model';
+import { InMemoryCacheStore } from './in-memory.cache-store';
+
+function createCachedValue<V>(value: V, tags: string[]): CachedValue<V> {
+    return {
+        value,
+        tags,
+        createdAt: new Date()
+    };
+}
+
+describe('InMemoryCacheStore', () => {
+    it('returns undefined for missing keys', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        expect(store.get('missing')).toBeUndefined();
+        expect(store.has('missing')).toBe(false);
+    });
+
+    it('stores and retrieves values', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        store.set('a', createCachedValue(1, ['tag-a']));
+
+        expect(store.get('a')?.value).toBe(1);
+        expect(store.get('a')?.tags).toEqual(['tag-a']);
+        expect(store.has('a')).toBe(true);
+    });
+
+    it('overwrites existing values for the same key', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        store.set('a', createCachedValue(1, ['tag-a']));
+        store.set('a', createCachedValue(2, ['tag-b']));
+
+        expect(store.get('a')?.value).toBe(2);
+        expect(store.get('a')?.tags).toEqual(['tag-b']);
+        expect(store.has('a')).toBe(true);
+    });
+
+    it('deletes values by key', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        store.set('a', createCachedValue(1, ['tag-a']));
+        store.delete('a');
+
+        expect(store.get('a')).toBeUndefined();
+        expect(store.has('a')).toBe(false);
+    });
+
+    it('clears all values', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        store.set('a', createCachedValue(1, ['tag-a']));
+        store.set('b', createCachedValue(2, ['tag-b']));
+
+        store.clear();
+
+        expect(store.get('a')).toBeUndefined();
+        expect(store.get('b')).toBeUndefined();
+        expect(store.has('a')).toBe(false);
+        expect(store.has('b')).toBe(false);
+    });
+
+    it('invalidates only entries with matching tags', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        store.set('a', createCachedValue(1, ['tag-a', 'tag-common']));
+        store.set('b', createCachedValue(2, ['tag-b']));
+        store.set('c', createCachedValue(3, ['tag-common']));
+
+        store.invalidateTags(['tag-common']);
+
+        expect(store.get('a')).toBeUndefined();
+        expect(store.get('b')?.value).toBe(2);
+        expect(store.get('c')).toBeUndefined();
+    });
+
+    it('invalidates entries matching any provided tag', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        store.set('a', createCachedValue(1, ['tag-a']));
+        store.set('b', createCachedValue(2, ['tag-b']));
+        store.set('c', createCachedValue(3, ['tag-c']));
+
+        store.invalidateTags(['tag-b', 'tag-c']);
+
+        expect(store.get('a')?.value).toBe(1);
+        expect(store.get('b')).toBeUndefined();
+        expect(store.get('c')).toBeUndefined();
+    });
+
+    it('does nothing when invalidateTags receives no matching tags', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        store.set('a', createCachedValue(1, ['tag-a']));
+
+        store.invalidateTags(['tag-x']);
+
+        expect(store.get('a')?.value).toBe(1);
+    });
+
+    it('can handle invalidating an empty cache', () => {
+        const store: InMemoryCacheStore<string, number> = new InMemoryCacheStore();
+
+        expect(() => store.invalidateTags(['tag-a'])).not.toThrow();
+    });
+
+    it('keeps stored object references intact', () => {
+        type Value = { name: string, nested: { id: number } };
+        const store: InMemoryCacheStore<string, Value> = new InMemoryCacheStore();
+        const value: Value = { name: 'x', nested: { id: 1 } };
+
+        store.set('a', createCachedValue(value, ['tag-a']));
+
+        expect(store.get('a')?.value).toBe(value);
+    });
+});

package/src/caching/store/in-memory.cache-store.ts

@@ -0,0 +1,272 @@
+import { CacheStoreConfig, CacheStoreInterface } from './cache-store.interface';
+import { CachedValue } from './cached-value.model';
+import { Bytes } from '../../utilities/bytes';
+import { DoublyLinkedList, LinkedListNode } from '../../utilities/doubly-linked-list';
+import { JsonUtilities } from '../../utilities/json.utilities';
+import { NumberUtilities } from '../../utilities/number.utilities';
+
+/**
+ * Internal linked list node.
+ */
+interface CacheEntry<K, V> {
+    /** The node inside the order list (holds the key). */
+    orderNode: LinkedListNode<K>,
+    /** The actual cached value. */
+    value: CachedValue<V>,
+    /** Estimated size in bytes (for byte‑based eviction). */
+    byteSize: number,
+    /** Frequency counter (used only by LFU). */
+    frequency: number
+}
+
+/**
+ * A simple in‑memory cache store.
+ *
+ * Supports LRU, MRU, FIFO and LFU eviction when maxEntries or maxBytes
+ * are exceeded.  The implementation uses a generic {@link DoublyLinkedList}
+ * to keep O(1) access, removal and reordering.
+ */
+export class InMemoryCacheStore<K, V> implements CacheStoreInterface<K, V> {
+    private readonly entries: Map<K, CacheEntry<K, V>> = new Map();
+
+    /** Order list – used by LRU, MRU, FIFO.  For LFU it’s still maintained but not used for eviction. */
+    private readonly orderList: DoublyLinkedList<K> = new DoublyLinkedList();
+
+    private currentBytes: number = 0;
+
+    // LFU helpers
+    private readonly frequencyMap: Map<number, Set<K>> = new Map();
+    private minFrequency: number = 0;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly config: CacheStoreConfig;
+
+    constructor(configInput?: Partial<CacheStoreConfig>) {
+        this.config = {
+            maxEntries: 500,
+            maxBytes: Bytes.KB * 750,
+            removeOnOverflow: 'leastRecentlyUsed',
+            ...configInput
+        };
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    get(key: K): CachedValue<V> | undefined {
+        const entry: CacheEntry<K, V> | undefined = this.entries.get(key);
+        if (!entry) {
+            return undefined;
+        }
+
+        this.recordAccess(entry);
+        return entry.value;
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    set(key: K, value: CachedValue<V>): void {
+        const existing: CacheEntry<K, V> | undefined = this.entries.get(key);
+
+        if (existing) {
+            this.currentBytes = NumberUtilities.subtract(this.currentBytes, existing.byteSize).toNumber();
+            existing.value = value;
+            existing.byteSize = this.estimateBytes(key, value);
+            this.currentBytes = NumberUtilities.add(this.currentBytes, existing.byteSize).toNumber();
+            this.recordAccess(existing);
+            return;
+        }
+
+        const byteSize: number = this.estimateBytes(key, value);
+
+        // Evict until there is enough space
+        while (
+            this.size() >= this.config.maxEntries
+            || NumberUtilities.add(this.currentBytes, byteSize).comparedTo(this.config.maxBytes) === 1
+        ) {
+            if (this.entries.size <= 0) {
+                // a single entry exceeds the cache, skip caching for it
+                return;
+            }
+            this.evictOne();
+        }
+
+        const orderNode: LinkedListNode<K> = this.orderList.addLast(key);
+
+        const entry: CacheEntry<K, V> = {
+            orderNode,
+            value,
+            byteSize,
+            frequency: 1
+        };
+        this.entries.set(key, entry);
+        this.currentBytes = NumberUtilities.add(this.currentBytes, byteSize).toNumber();
+
+        // LFU initialization
+        if (this.config.removeOnOverflow === 'leastFrequentlyUsed') {
+            this.increaseFrequency(entry);
+        }
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    delete(key: K): void {
+        const entry: CacheEntry<K, V> | undefined = this.entries.get(key);
+        if (!entry) {
+            return;
+        }
+
+        // Remove from order list
+        this.orderList.remove(entry.orderNode);
+
+        // Subtract bytes
+        this.currentBytes = NumberUtilities.subtract(this.currentBytes, entry.byteSize).toNumber();
+
+        // LFU cleanup
+        if (this.config.removeOnOverflow === 'leastFrequentlyUsed') {
+            this.decreaseFrequency(entry);
+        }
+
+        this.entries.delete(key);
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    has(key: K): boolean {
+        return this.entries.has(key);
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    clear(): void {
+        this.entries.clear();
+        this.orderList.clear();
+        this.frequencyMap.clear();
+        this.currentBytes = 0;
+        this.minFrequency = 0;
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    size(): number {
+        return this.entries.size;
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    invalidateTags(tags: string[]): void {
+        // Safe iteration – we delete while iterating
+        for (const [key, entry] of this.entries.entries()) {
+            if (entry.value.tags.some(t => tags.includes(t))) {
+                this.delete(key);
+            }
+        }
+    }
+
+    private evictOne(): void {
+        switch (this.config.removeOnOverflow) {
+            case 'leastRecentlyUsed':
+            case 'firstInFirstOut': {
+                // Both evict the head of the order list
+                if (this.orderList.head) {
+                    this.delete(this.orderList.head.value);
+                }
+                break;
+            }
+            case 'mostRecentlyUsed': {
+                // Evict the tail (most recently used)
+                if (this.orderList.tail) {
+                    this.delete(this.orderList.tail.value);
+                }
+                break;
+            }
+            case 'leastFrequentlyUsed': {
+                // Remove any key from the current minimum‑frequency bucket
+                const minSet: Set<K> | undefined = this.frequencyMap.get(this.minFrequency);
+                if (minSet && minSet.size > 0) {
+                    // eslint-disable-next-line typescript/no-non-null-assertion
+                    const keyToEvict: K = minSet.values().next().value!;
+                    this.delete(keyToEvict);
+                    return;
+                }
+                if (this.orderList.head) {
+                    this.delete(this.orderList.head.value);
+                }
+                break;
+            }
+        }
+    }
+
+    private recordAccess(entry: CacheEntry<K, V>): void {
+        switch (this.config.removeOnOverflow) {
+            case 'leastRecentlyUsed':
+            case 'mostRecentlyUsed': {
+                // Move to tail (mark as most recent)
+                this.orderList.moveToTail(entry.orderNode);
+                break;
+            }
+            case 'firstInFirstOut': {
+                // Do not change order – keep insertion order intact
+                break;
+            }
+            case 'leastFrequentlyUsed': {
+                // Increase frequency
+                this.increaseFrequency(entry);
+                break;
+            }
+        }
+    }
+
+    private increaseFrequency(entry: CacheEntry<K, V>): void {
+        const oldFrequency: number = entry.frequency;
+        const newFrequency: number = oldFrequency + 1;
+        entry.frequency = newFrequency;
+
+        // remove from old frequency set
+        const oldSet: Set<K> | undefined = this.frequencyMap.get(oldFrequency);
+        if (oldSet) {
+            oldSet.delete(entry.orderNode.value);
+            if (oldSet.size === 0) {
+                this.frequencyMap.delete(oldFrequency);
+                if (oldFrequency === this.minFrequency) {
+                    // find the next min frequency
+                    this.minFrequency = Math.min(...this.frequencyMap.keys());
+                    if (!Number.isFinite(this.minFrequency)) {
+                        this.minFrequency = 0;
+                    }
+                }
+            }
+        }
+
+        // add to new frequency set
+        if (!this.frequencyMap.has(newFrequency)) {
+            this.frequencyMap.set(newFrequency, new Set());
+        }
+        // eslint-disable-next-line typescript/no-non-null-assertion
+        this.frequencyMap.get(newFrequency)!.add(entry.orderNode.value);
+        if (newFrequency < this.minFrequency || this.minFrequency === 0) {
+            this.minFrequency = newFrequency;
+        }
+    }
+
+    private decreaseFrequency(entry: CacheEntry<K, V>): void {
+        // Called when a node is removed – just clean up the frequency sets.
+        const frequency: number = entry.frequency;
+        const set: Set<K> | undefined = this.frequencyMap.get(frequency);
+        if (!set) {
+            return;
+        }
+
+        set.delete(entry.orderNode.value);
+        if (set.size === 0) {
+            this.frequencyMap.delete(frequency);
+            if (frequency === this.minFrequency) {
+                this.minFrequency = Math.min(...this.frequencyMap.keys());
+                if (!Number.isFinite(this.minFrequency)) {
+                    this.minFrequency = 0;
+                }
+            }
+        }
+    }
+
+    private estimateBytes(key: K, value: CachedValue<V>): number {
+        try {
+            return Buffer.byteLength(JsonUtilities.stringify({ key, value }), 'utf8');
+        }
+        catch {
+            return 1024;
+        }
+    }
+}