@toreda/cache/dist/cache.d.ts

Time-based object cache in TypeScript.

/**
 *	MIT License
 *
 *	Copyright (c) 2019 - 2022 Toreda, Inc.
 *
 *	Permission is hereby granted, free of charge, to any person obtaining a copy
 *	of this software and associated documentation files (the "Software"), to deal
 *	in the Software without restriction, including without limitation the rights
 *	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 *	copies of the Software, and to permit persons to whom the Software is
 *	furnished to do so, subject to the following conditions:

 * 	The above copyright notice and this permission notice shall be included in all
 * 	copies or substantial portions of the Software.
 *
 * 	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 *	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 *	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * 	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 *	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 *	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * 	SOFTWARE.
 *
 */
import { CacheItem } from './cache/item';
import type { CacheItemId } from './cache/item/id';
import type { Cacheable } from './cacheable';
import type { CfgData } from './cfg/data';
import { Log } from '@toreda/log';
import type { Time } from '@toreda/time';
import type { UInt } from '@toreda/strong-types';
/**
 * Time based object cache for TypeScript generics.
 *
 * @category Cache
 */
export declare class Cache<ItemT extends Cacheable> {
    /** Global log instance. */
    readonly log: Log;
    /** Map of ItemId  */
    readonly items: Map<CacheItemId, CacheItem<ItemT>>;
    /** Validates objects before they're added to the cache. */
    readonly itemValidator: (item?: ItemT | null) => boolean;
    /** Max number of items that can be cached at any one time. */
    readonly capacityMax: UInt;
    /** Minimum number of seconds between prune calls. `prune()` execution aborts automatically when called
     *  more frequently than delay allows. */
    readonly pruneDelay: Time;
    /** Timestamp of the last successful prune operation. */
    readonly lastPrune: Time;
    constructor(cfg?: CfgData<ItemT>);
    /**
     * Helper that guarantees a Log instance is set during init. Check optional `log` arg and return it if
     * it's a valid `Log` instance. Otherwise creates & returns a new `Log` instance.
     * @param baseLog
     * @returns
     */
    private makeLog;
    /**
     * Get current cached item count.
     * @returns
     */
    size(): number;
    /**
     * Check unexpired item with target id exists in cache. Returns false when target item expires
     * but still exists in cache.
     * @param id		Unique ID of item in cache.
     * @returns
     */
    has(id: string): boolean;
    /**
     * Get item from cache matching `id` if one exists.
     * @param id		Globally unique item identifier.
     * @returns			Item of type `ItemT` if it exists, otherwise `null`.
     */
    get(id: string): ItemT | null;
    /**
     * Add item to cache if it does not exist. When ite
     * @param item			Item to cache.
     * @param overwrite		`true`	-	Overwrite existing item with same ID.
     *						`false`	-	(default) Do not overwrite existing item. add call fails.
     * @returns
     */
    add(item: ItemT, overwrite?: boolean): boolean;
    /**
     * The default validator used to check items before they're cached. Only used when no cache
     *  cfg option is provided for `itemValidator`.
     * @param item
     * @returns
     */
    defaultItemValidator(item?: ItemT | null): boolean;
    /**
     * Clear cached & volatile data that can be easily recreated. The system received a memory
     * warning, indicating performance issues.
     * @returns		`true` when handler executes, `false` when handler does not execute.
     */
    onMemoryWarning(): Promise<boolean>;
    /**
     * Iterate over all items and check for expiration.
     * @returns
     */
    prune(): Promise<number>;
    /**
     * Reset cache to inital state.
     * @returns		void
     */
    reset(): void;
}