@thermopylae/lib.cache/dist/policies/eviction/priority.d.ts

Modular cache.

import { Percentage, Seconds } from '@thermopylae/core.declarations';
import { CacheReplacementPolicy, Deleter, EntryValidity } from '../../contracts/cache-replacement-policy';
import { CacheEntry } from '../../contracts/commons';
import { IterableCacheBackend } from '../../contracts/cache-backend';
/**
 * @private
 */
declare const PRIORITY_SYM: unique symbol;
/**
 * Describes {@link CacheEntry} priority against eviction caused by lack of system memory.
 */
declare const enum CacheEntryPriority {
    /**
     * Cache items with this priority level are the most likely to be deleted from the cache.
     */
    LOW = 0,
    /**
     * Cache items with this priority level are more likely to be deleted from the cache than {@link CacheEntryPriority.NORMAL} priority.
     */
    BELOW_NORMAL = 1,
    /**
     * Cache items with this priority level are likely to be deleted from the cache
     * after those items with {@link CacheEntryPriority.LOW} or {@link CacheEntryPriority.BELOW_NORMAL} priority. <br/>
     * This is the default.
     */
    NORMAL = 2,
    /**
     * Cache items with this priority level are less likely to be deleted from cache
     * than those assigned with {@link CacheEntryPriority.NORMAL} priority.
     */
    ABOVE_NORMAL = 3,
    /**
     * Cache items with this priority level are the least likely to be deleted from the cache.
     */
    HIGH = 4,
    /**
     * The cache items with this priority level will not be automatically deleted from the cache.
     */
    NOT_REMOVABLE = 5
}
/**
 * @private
 */
interface PrioritizedCacheEntry<Key, Value> extends CacheEntry<Key, Value> {
    [PRIORITY_SYM]: CacheEntryPriority;
}
interface PriorityEvictionPolicyArgumentsBundle {
    /**
     * Priority of the key when memory is low and eviction needs to be performed.
     */
    priority?: CacheEntryPriority;
}
interface PriorityEvictionPolicyOptions<Key, Value> {
    /**
     * Iterable cache backend.
     */
    iterableCacheBackend: IterableCacheBackend<Key, Value>;
    /**
     * Interval for checking whether process is low on memory. <br/>
     * Defaults to **3600 seconds**.
     */
    checkInterval?: Seconds;
    /**
     * Percentage of the available memory which is considered to be critical. <br/>
     * When process reaches it or goes bellow, cache entries eviction kicks in on next {@link PriorityEvictionPolicyOptions.checkInterval}. <br/>
     * Percentage is calculated by the following formula: **((heapTotal - heapUsed) * 100) / heapTotal**.
     * > ⚠️ WARNING ⚠
     * > Computation of the available memory doesn't take into account garbage collection and is subject to false positive results.
     * GC is performed in a **stop the world** fashion, hence it's delayed by V8 as much as possible and performed when it's
     * really needed, i.e. when process is low on memory. <br/>
     * > Therefore, there is always a small chance that we will run our eviction handler and detect high memory usage
     * before GC will occur.
     *
     * Defaults to **20%**.
     */
    criticalAvailableMemoryPercentage?: Percentage;
    /**
     * Percentage of cache entries that needs to be evicted when {@link PriorityEvictionPolicyOptions.criticalAvailableMemoryPercentage} is reached. <br/>
     * Defaults to **20%**.
     */
    cacheEvictionPercentage?: Percentage;
}
/**
 * {@link CacheReplacementPolicy} which evicts entries when NodeJS process is low on memory. <br/>
 * Eviction is based on {@link CacheEntryPriority} and is performed in a **stop the world** way,
 * as it will iterate over cache entries to determine which ones needs to ne evicted based on their priority.
 *
 * @template Key				Type of the key.
 * @template Value				Type of the value.
 * @template ArgumentsBundle	Type of the arguments bundle.
 */
declare class PriorityEvictionPolicy<Key, Value, ArgumentsBundle extends PriorityEvictionPolicyArgumentsBundle = PriorityEvictionPolicyArgumentsBundle> implements CacheReplacementPolicy<Key, Value, ArgumentsBundle> {
    /**
     * @private
     */
    private readonly options;
    private readonly numberOfCacheEntriesByPriority;
    private checkMemoryConsumptionIntervalId;
    private deleteFromCache;
    constructor(options: PriorityEvictionPolicyOptions<Key, Value>);
    /**
     * Whether eviction timer has been started.
     */
    get idle(): boolean;
    /**
     * @inheritDoc
     */
    onHit(): EntryValidity;
    /**
     * @inheritDoc
     */
    onMiss(): void;
    /**
     * @inheritDoc
     */
    onSet(entry: PrioritizedCacheEntry<Key, Value>, options?: ArgumentsBundle): void;
    /**
     * @inheritDoc
     */
    onUpdate(entry: PrioritizedCacheEntry<Key, Value>, options?: ArgumentsBundle): void;
    /**
     * @inheritDoc
     */
    onDelete(entry: PrioritizedCacheEntry<Key, Value>): void;
    /**
     * @inheritDoc
     */
    onClear(): void;
    /**
     * @inheritDoc
     */
    setDeleter(deleter: Deleter<Key, Value>): void;
    private performEvictionOnLowMemory;
    private computeNumberOfEntriesToEvictByPriority;
    private increaseNumberOfEntries;
    private decreaseNumberOfEntries;
    private stopEvictionTimer;
    private static fillConstructorOptionsWithDefaults;
    private static fillNumberOfCacheEntriesByPriorityWithStartingValues;
}
export { PriorityEvictionPolicy, PriorityEvictionPolicyOptions, CacheEntryPriority, PrioritizedCacheEntry, PRIORITY_SYM };