@daiso-tech/core/dist/cache/contracts/cache.contract.d.ts

The library offers flexible, framework-agnostic solutions for modern web applications, built on adaptable components that integrate seamlessly with popular frameworks like Next Js.

/**
 * @module Cache
 */
import { type CacheEventMap } from "../../cache/contracts/cache.events.js";
import { type IEventListenable } from "../../event-bus/contracts/_module.js";
import { type ITask } from "../../task/contracts/_module.js";
import { type ITimeSpan } from "../../time-span/contracts/_module.js";
import { type AsyncLazyable, type NoneFunc } from "../../utilities/_module.js";
/**
 * The `ICacheListenable` contract defines a way for listening {@link ICache | `ICache`} operation events.
 *
 * IMPORT_PATH: `"@daiso-tech/core/cache/contracts"`
 * @group Contracts
 */
export type ICacheListenable<TType = unknown> = IEventListenable<CacheEventMap<TType>>;
/**
 * IMPORT_PATH: `"@daiso-tech/core/cache/contracts"`
 * @group Contracts
 */
export type CacheWriteSettings = {
    ttl?: ITimeSpan | null;
    jitter?: number;
    /**
     * Used internally for testin.
     *
     * @internal
     */
    _mathRandom?: () => number;
};
/**
 * The `ICacheBase` contract defines a way for as key-value pairs independent of data storage.
 *
 * IMPORT_PATH: `"@daiso-tech/core/cache/contracts"`
 * @group Contracts
 */
export type ICacheBase<TType = unknown> = {
    /**
     * The `exists` method returns true when `key` is found otherwise false will be returned.
     */
    exists(key: string): ITask<boolean>;
    /**
     * The `missing` method returns true when `key` is not found otherwise false will be returned.
     */
    missing(key: string): ITask<boolean>;
    /**
     * The `get` method returns the value when `key` is found otherwise null will be returned.
     */
    get(key: string): ITask<TType | null>;
    /**
     * The `getOrFail` method returns the value when `key` is found otherwise an error will be thrown.
     *
     * @throws {KeyNotFoundCacheError} {@link KeyNotFoundCacheError}
     */
    getOrFail(key: string): ITask<TType>;
    /**
     * The `getAndRemove` method returns the value when `key` is found otherwise null will be returned.
     * The key will be removed after it is returned.
     */
    getAndRemove(key: string): ITask<TType | null>;
    /**
     * The `getOr` method will retrieve the given `key` if found otherwise `defaultValue` will be returned.
     *
     * @param defaultValue - can be regular value, sync or async {@link Invokable | `Invokable`} value and {@link ITask | `ITask`} value.
     */
    getOr(key: string, defaultValue: AsyncLazyable<NoneFunc<TType>>): ITask<TType>;
    /**
     * The `getOrAdd` method will retrieve the given `key` if found otherwise `valueToAdd` will be added and returned.
     *
     * @param valueToAdd - can be regular value, sync or async {@link Invokable | `Invokable`} value and {@link ITask | `ITask`} value.
     */
    getOrAdd(key: string, valueToAdd: AsyncLazyable<NoneFunc<TType>>, settings?: CacheWriteSettings): ITask<TType>;
    /**
     * The `add` method adds a `key` with given `value` when key doesn't exists.
     *
     * @param ttl - If null is passed, the item will not expire.
     *
     * @returns Returns true when key doesn't exists otherwise false will be returned.
     */
    add(key: string, value: TType, settings?: CacheWriteSettings): ITask<boolean>;
    /**
     * The `addOrFail` method adds a `key` with given `value` when key doesn't exists.
     * Throws an error if the `key` exists.
     *
     * @throws {KeyExistsCacheError} {@link KeyExistsCacheError}
     */
    addOrFail(key: string, value: TType, settings?: CacheWriteSettings): ITask<void>;
    /**
     * The `put` method replaces th given `key` with the given `value` and `ttl` if the `key` exists
     * othwerwise it will add the given `value` with the given `ttl`.
     *
     * @param ttl - If null is passed, the item will not expire.
     *
     * @returns Returns true if the `key` where replaced otherwise false is returned.
     */
    put(key: string, value: TType, settings?: CacheWriteSettings): ITask<boolean>;
    /**
     * The `update` method updates the given `key` with given `value`.
     *
     * @returns Returns true if the `key` where updated otherwise false will be returned.
     */
    update(key: string, value: TType): ITask<boolean>;
    /**
     * The `updateOrFail` method updates the given `key` with given `value`.
     * Thorws error if the `key` is not found.
     *
     * @throws {KeyNotFoundCacheError} {@link KeyNotFoundCacheError}
     */
    updateOrFail(key: string, value: TType): ITask<void>;
    /**
     * The `increment` method increments the given `key` with given `value`.
     * An error will thrown if the value is not a number.
     *
     * @param value - If not defined then it will be defaulted to 1.
     *
     * @returns Returns true if the `key` where incremented otherwise false will be returned.
     *
     * @throws {TypeError} {@link TypeError}
     */
    increment(key: string, value?: Extract<TType, number>): ITask<boolean>;
    /**
     * The `incrementOrFail` method increments the given `key` with given `value`.
     * An error will thrown if the value is not a number or if the key is not found.
     *
     * @param value - If not defined then it will be defaulted to 1.
     *
     * @throws {KeyNotFoundCacheError} {@link KeyNotFoundCacheError}
     * @throws {TypeError} {@link TypeError}
     */
    incrementOrFail(key: string, value?: Extract<TType, number>): ITask<void>;
    /**
     * The `decrement` method decrements the given `key` with given `value`.
     * An error will thrown if the value is not a number.
     *
     * @param value - If not defined then it will be defaulted to 1.
     *
     * @returns Returns true if the `key` where decremented otherwise false will be returned.
     *
     * @throws {TypeError} {@link TypeError}
     */
    decrement(key: string, value?: Extract<TType, number>): ITask<boolean>;
    /**
     * The `decrementOrFail` method decrements the given `key` with given `value`.
     * An error will thrown if the value is not a number or if the key is not found.
     *
     * @param value - If not defined then it will be defaulted to 1.
     *
     * @throws {KeyNotFoundCacheError} {@link KeyNotFoundCacheError}
     * @throws {TypeError} {@link TypeError}
     */
    decrementOrFail(key: string, value?: Extract<TType, number>): ITask<void>;
    /**
     * The `remove` method removes the given `key`.
     *
     * @returns Returns true if the key is found otherwise false is returned.
     */
    remove(key: string): ITask<boolean>;
    /**
     * The `removeOrFail` method removes the given `key`.
     * Throws an error if the key is not found.
     *
     * @throws {KeyNotFoundCacheError} {@link KeyNotFoundCacheError}
     */
    removeOrFail(key: string): ITask<void>;
    /**
     * The `removeMany` method removes many keys.
     *
     * @param keys - The param items can be a string or an `Iterable` of strings.
     * If the param items are an `Iterable`, it will be joined into a single string.
     * Think of an `Iterable` as representing a path.
     *
     * @returns Returns true if one of the keys where deleted otherwise false is returned.
     */
    removeMany(keys: Iterable<string>): ITask<boolean>;
    /**
     * The `clear` method removes all the keys in the cache. If a cache is in a group then only the keys part of the group will be removed.
     */
    clear(): ITask<void>;
};
/**
 * The `ICache` contract defines a way for as key-value pairs independent of data storage and listening to operation events.
 *
 * IMPORT_PATH: `"@daiso-tech/core/cache/contracts"`
 * @group Contracts
 */
export type ICache<TType = unknown> = ICacheListenable<TType> & ICacheBase<TType>;