zibri 2.2.1 → 2.4.0

package/src/backup/backup.service.ts

@@ -1,17 +1,20 @@
 import { Readable } from 'node:stream';
 
-import { BehaviorSubject } from 'rxjs';
+import { BehaviorSubject, first, firstValueFrom } from 'rxjs';
 
 import { BackupEntity, BackupEntityCreateData } from './backup-entity.model';
 import { BackupResourceEntity, BackupResourceEntityCreateData } from './backup-resource-entity.model';
 import { BackupResourceInterface } from './backup-resource.interface';
 import { BackupCreateData, BackupServiceInterface } from './backup-service.interface';
+import { ZibriApplication } from '../application';
 import { PostgresDataSource } from '../data-source/data-sources/postgres-data-source.model';
 import { repositoryTokenFor } from '../di/decorators/inject-repository.decorator';
+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 { LoggerInterface } from '../logging/logger.interface';
+import { type LoggerInterface } from '../logging/logger.interface';
 import { Newable } from '../types/newable.type';
 import { MetadataUtilities } from '../utilities/metadata.utilities';
 import { PromiseUtilities } from '../utilities/promise.utilities';
@@ -19,12 +22,16 @@ import { validateEntitiesRegistered } from '../utilities/validate-entities-regis
 import { BackupResourceMetadata } from './decorators/backup-resource-metadata.model';
 import { BackupTransportInterface } from './transports/backup-transport.interface';
 import { Repository } from '../data-source/repository';
+import { OnAppInit } from '../global/on-app-init.interface';
+import { OnAppShutdown } from '../global/on-app-shutdown.interface';
+import { JsonUtilities } from '../utilities/json.utilities';
+import { Ms } from '../utilities/ms';
 
 /**
  * Default implementation of the backup service.
  */
-export class BackupService implements BackupServiceInterface {
-    private readonly logger: LoggerInterface;
+@Injectable({ register: 'onUse' })
+export class BackupService implements BackupServiceInterface, OnAppInit, OnAppShutdown {
     private readonly backupResources: Newable<BackupResourceInterface>[] = [];
 
     private get backupRepository(): Repository<BackupEntity, BackupEntityCreateData> {
@@ -37,16 +44,20 @@ export class BackupService implements BackupServiceInterface {
     // eslint-disable-next-line jsdoc/require-jsdoc
     readonly isRestoringBackup: BehaviorSubject<boolean> = new BehaviorSubject(false);
 
-    constructor() {
-        this.logger = inject(ZIBRI_DI_TOKENS.LOGGER);
-    }
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly shutdownTimeoutInMs: number = Ms.MINUTE * 15;
+
+    constructor(
+        @Inject(ZIBRI_DI_TOKENS.LOGGER)
+        private readonly logger: LoggerInterface
+    ) {}
 
     // eslint-disable-next-line jsdoc/require-jsdoc
-    async init(): Promise<void> {
+    async onAppInit(app: ZibriApplication): Promise<void> {
         if (GlobalRegistry.backupResources.length) {
             // eslint-disable-next-line stylistic/max-len
             await this.logger.info(`configures ${GlobalRegistry.backupResources.length} ${GlobalRegistry.backupResources.length > 1 ? 'resources' : 'resource'} to be backed up:`);
-            validateEntitiesRegistered(BackupService.name, BackupResourceEntity, BackupEntity);
+            validateEntitiesRegistered(BackupService.name, app, BackupResourceEntity, BackupEntity);
         }
 
         for (const resourceClass of GlobalRegistry.backupResources) {
@@ -67,6 +78,14 @@ export class BackupService implements BackupServiceInterface {
         await this.syncBackupEntities();
     }
 
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async onAppShutdown(): Promise<void> {
+        await Promise.all([
+            firstValueFrom(this.isCreatingBackup.pipe(first(v => !v))),
+            firstValueFrom(this.isRestoringBackup.pipe(first(v => !v)))
+        ]);
+    }
+
     // eslint-disable-next-line jsdoc/require-jsdoc
     async syncBackupEntities(): Promise<void> {
         if (!this.backupResources.length) {
@@ -248,12 +267,12 @@ export class BackupService implements BackupServiceInterface {
                     [
                         `Could not resolve backup data for resource "${resource.name}" from transport: ${transport.name}.`,
                         'Cause:',
-                        error instanceof Error ? error.message : JSON.stringify(error)
+                        error instanceof Error ? error.message : JsonUtilities.stringify(error)
                     ].join('\n')
                 );
             }
         }
 
-        throw new Error('Could not resolve data for');
+        throw new Error(`Could not resolve backup data for resource "${resource.name}".`);
     }
 }

package/src/backup/transports/fs.backup-transport.ts

@@ -6,7 +6,8 @@ import { BackupTransportInterface } from './backup-transport.interface';
 import { ZIBRI_DI_TOKENS } from '../../di/default/zibri-di-tokens.default';
 import { inject } from '../../di/inject.function';
 import { LoggerInterface } from '../../logging/logger.interface';
-import { FsUtilities, Path } from '../../utilities/fs.utilities';
+import { FsUtilities, FsPath } from '../../utilities/fs.utilities';
+import { JsonUtilities } from '../../utilities/json.utilities';
 import { BackupEntity } from '../backup-entity.model';
 import { BackupResourceEntity } from '../backup-resource-entity.model';
 
@@ -21,7 +22,7 @@ export class FsBackupTransport implements BackupTransportInterface {
         return inject(ZIBRI_DI_TOKENS.LOGGER);
     }
 
-    constructor(readonly name: string, protected readonly backupBasePath: Path) {}
+    constructor(readonly name: string, protected readonly backupBasePath: FsPath) {}
 
     // eslint-disable-next-line jsdoc/require-jsdoc
     async resolveBackups(existingEntities: BackupEntity[]): Promise<BackupEntity[]> {
@@ -37,22 +38,22 @@ export class FsBackupTransport implements BackupTransportInterface {
             if (existingEntities.map(e => e.name).includes(node.name)) {
                 return;
             }
-            const p: Path = FsUtilities.getPath(node.parentPath, node.name, METADATA_FILENAME);
+            const p: FsPath = FsUtilities.getPath(node.parentPath, node.name, METADATA_FILENAME);
             if (!await FsUtilities.exists(p)) {
                 await this.logger.warn(`Could not find the metadata file needed to resolve a backup: "${p}"`);
                 return;
             }
             const json: string = await FsUtilities.readFile(p);
-            return JSON.parse(json) as BackupEntity;
+            return JsonUtilities.parse<BackupEntity>(json);
         }))).filter(b => b != undefined);
         return res;
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc
     async storeData(data: Readable, backup: BackupEntity, resource: BackupResourceEntity): Promise<void> {
-        const p: Path = this.getResourcePath(backup, resource);
+        const p: FsPath = this.getResourcePath(backup, resource);
         await FsUtilities.mkdir(this.getBackupPath(backup));
-        await FsUtilities.createFile(this.getBackupMetadataPath(backup), JSON.stringify(backup));
+        await FsUtilities.createFile(this.getBackupMetadataPath(backup), JsonUtilities.stringify(backup));
 
         await pipeline(
             data,
@@ -62,25 +63,25 @@ export class FsBackupTransport implements BackupTransportInterface {
 
     // eslint-disable-next-line jsdoc/require-jsdoc
     retrieveData(backup: BackupEntity, resource: BackupResourceEntity): Readable | Promise<Readable> {
-        const p: Path = this.getResourcePath(backup, resource);
+        const p: FsPath = this.getResourcePath(backup, resource);
         return FsUtilities.createReadStream(p);
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc
     async deleteData(backup: BackupEntity, resource: BackupResourceEntity): Promise<void> {
-        const p: Path = this.getResourcePath(backup, resource);
+        const p: FsPath = this.getResourcePath(backup, resource);
         await FsUtilities.rm(p);
     }
 
-    private getResourcePath(backup: BackupEntity, resource: BackupResourceEntity): Path {
+    private getResourcePath(backup: BackupEntity, resource: BackupResourceEntity): FsPath {
         return FsUtilities.getPath(this.getBackupPath(backup), resource.name);
     }
 
-    private getBackupPath(backup: BackupEntity): Path {
+    private getBackupPath(backup: BackupEntity): FsPath {
         return FsUtilities.getPath(this.backupBasePath, backup.name);
     }
 
-    private getBackupMetadataPath(backup: BackupEntity): Path {
+    private getBackupMetadataPath(backup: BackupEntity): FsPath {
         return FsUtilities.getPath(this.getBackupPath(backup), METADATA_FILENAME);
     }
 }

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

@@ -0,0 +1,333 @@
+import { AlsUtilities } from '../../context/als.utilities';
+import { LogCacheContext } from '../../logging/log-context.model';
+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: LogCacheContext = { 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: LogCacheContext = { 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>
+};