Brunobkr/llama.cpp_AlgMor24_github

1/**2 * @module LRUCache3 */4import type { Perf } from './perf.js';5export type { Perf } from './perf.js';6declare const TYPE: unique symbol;7export type PosInt = number & {8    [TYPE]: 'Positive Integer';9};10export type Index = number & {11    [TYPE]: 'LRUCache Index';12};13export type UintArray = Uint8Array | Uint16Array | Uint32Array;14export type NumberArray = UintArray | number[];15declare class ZeroArray extends Array<number> {16    constructor(size: number);17}18export type { ZeroArray };19export type { Stack };20export type StackLike = Stack | Index[];21declare class Stack {22    #private;23    heap: NumberArray;24    length: number;25    static create(max: number): StackLike;26    constructor(max: number, HeapCls: {27        new (n: number): NumberArray;28    });29    push(n: Index): void;30    pop(): Index;31}32/**33 * Promise representing an in-progress {@link LRUCache#fetch} call34 */35export type BackgroundFetch<V> = Promise<V | undefined> & {36    __returned: BackgroundFetch<V> | undefined;37    __abortController: AbortController;38    __staleWhileFetching: V | undefined;39};40export type DisposeTask<K, V> = [41    value: V,42    key: K,43    reason: LRUCache.DisposeReason44];45export declare namespace LRUCache {46    /**47     * An integer greater than 0, reflecting the calculated size of items48     */49    type Size = number;50    /**51     * Integer greater than 0, representing some number of milliseconds, or the52     * time at which a TTL started counting from.53     */54    type Milliseconds = number;55    /**56     * An integer greater than 0, reflecting a number of items57     */58    type Count = number;59    /**60     * The reason why an item was removed from the cache, passed61     * to the {@link Disposer} methods.62     *63     * - `evict`: The item was evicted because it is the least recently used,64     *   and the cache is full.65     * - `set`: A new value was set, overwriting the old value being disposed.66     * - `delete`: The item was explicitly deleted, either by calling67     *   {@link LRUCache#delete}, {@link LRUCache#clear}, or68     *   {@link LRUCache#set} with an undefined value.69     * - `expire`: The item was removed due to exceeding its TTL.70     * - `fetch`: A {@link OptionsBase#fetchMethod} operation returned71     *   `undefined` or was aborted, causing the item to be deleted.72     */73    type DisposeReason = 'evict' | 'set' | 'delete' | 'expire' | 'fetch';74    /**75     * A method called upon item removal, passed as the76     * {@link OptionsBase.dispose} and/or77     * {@link OptionsBase.disposeAfter} options.78     */79    type Disposer<K, V> = (value: V, key: K, reason: DisposeReason) => void;80    /**81     * The reason why an item was added to the cache, passed82     * to the {@link Inserter} methods.83     *84     * - `add`: the item was not found in the cache, and was added85     * - `update`: the item was in the cache, with the same value provided86     * - `replace`: the item was in the cache, and replaced87     */88    type InsertReason = 'add' | 'update' | 'replace';89    /**90     * A method called upon item insertion, passed as the91     * {@link OptionsBase.insert}92     */93    type Inserter<K, V> = (value: V, key: K, reason: InsertReason) => void;94    /**95     * A function that returns the effective calculated size96     * of an entry in the cache.97     */98    type SizeCalculator<K, V> = (value: V, key: K) => Size;99    /**100     * Options provided to the101     * {@link OptionsBase.fetchMethod} function.102     */103    interface FetcherOptions<K, V, FC = unknown> {104        signal: AbortSignal;105        options: FetcherFetchOptions<K, V, FC>;106        /**107         * Object provided in the {@link FetchOptions.context} option to108         * {@link LRUCache#fetch}109         */110        context: FC;111    }112    /**113     * Occasionally, it may be useful to track the internal behavior of the114     * cache, particularly for logging, debugging, or for behavior within the115     * `fetchMethod`. To do this, you can pass a `status` object to the116     * {@link LRUCache#fetch}, {@link LRUCache#get}, {@link LRUCache#set},117     * {@link LRUCache#memo}, and {@link LRUCache#has} methods.118     *119     * The `status` option should be a plain JavaScript object. The following120     * fields will be set on it appropriately, depending on the situation.121     *122     * These objects are also the context objects passed to listeners on the123     * `lru-cache:metrics` diagnostic channel, and the `lru-cache` tracing124     * channels, in platforms that support them.125     */126    interface Status<K, V, FC = unknown> {127        /**128         * The operation being performed129         */130        op?: 'get' | 'set' | 'memo' | 'fetch' | 'delete' | 'has' | 'peek';131        /**132         * The status of a set() operation.133         *134         * - add: the item was not found in the cache, and was added135         * - update: the item was in the cache, with the same value provided136         * - replace: the item was in the cache, and replaced137         * - miss: the item was not added to the cache for some reason138         */139        set?: 'add' | 'update' | 'replace' | 'miss' | 'deleted';140        /**141         * The status of a delete() operation.142         */143        delete?: LRUCache.DisposeReason;144        /**145         * The result of a peek() operation146         *147         * - hit: the item was found and returned148         * - stale: the item is in the cache, but past its ttl and not returned149         * - miss: item not in the cache150         */151        peek?: 'hit' | 'miss' | 'stale';152        /**153         * The status of a memo() operation.154         *155         * - 'hit': the item was found in the cache and returned156         * - 'miss': the `memoMethod` function was called157         */158        memo?: 'hit' | 'miss';159        /**160         * The `context` option provided to a memo or fetch operation161         *162         * In practice, of course, this will be the same type as the `FC`163         * fetch context param used to instantiate the LRUCache, but the164         * convolutions of threading that through would get quite complicated,165         * and preclude forcing/forbidding the passing of a `context` param166         * where it is/isn't expected, which is more valuable for error167         * prevention.168         */169        context?: unknown;170        /**171         * the ttl stored for the item, or undefined if ttls are not used.172         */173        ttl?: Milliseconds;174        /**175         * the start time for the item, or undefined if ttls are not used.176         */177        start?: Milliseconds;178        /**179         * The timestamp used for TTL calculation180         */181        now?: Milliseconds;182        /**183         * the remaining ttl for the item, or undefined if ttls are not used.184         */185        remainingTTL?: Milliseconds;186        /**187         * The calculated size for the item, if sizes are used.188         */189        entrySize?: Size;190        /**191         * The total calculated size of the cache, if sizes are used.192         */193        totalCalculatedSize?: Size;194        /**195         * A flag indicating that the item was not stored, due to exceeding the196         * {@link OptionsBase.maxEntrySize}197         */198        maxEntrySizeExceeded?: true;199        /**200         * The key that was set or retrieved201         */202        key?: K;203        /**204         * The value that was set205         */206        value?: V;207        /**208         * The old value, specified in the case of `set:'replace'`209         */210        oldValue?: V;211        /**212         * The results of a {@link LRUCache#has} operation213         *214         * - hit: the item was found in the cache215         * - stale: the item was found in the cache, but is stale216         * - miss: the item was not found in the cache217         */218        has?: 'hit' | 'stale' | 'miss';219        /**220         * The status of a {@link LRUCache#fetch} operation.221         * Note that this can change as the underlying fetch() moves through222         * various states.223         *224         * - inflight: there is another fetch() for this key which is in process225         * - get: there is no {@link OptionsBase.fetchMethod}, so226         *   {@link LRUCache#get} was called.227         * - miss: the item is not in cache, and will be fetched.228         * - hit: the item is in the cache, and was resolved immediately.229         * - stale: the item is in the cache, but stale.230         * - refresh: the item is in the cache, and not stale, but231         *   {@link FetchOptions.forceRefresh} was specified.232         */233        fetch?: 'get' | 'inflight' | 'miss' | 'hit' | 'stale' | 'refresh';234        /**235         * `forceRefresh` option was used for either a fetch or memo operation236         */237        forceRefresh?: boolean;238        /**239         * The {@link OptionsBase.fetchMethod} was called240         */241        fetchDispatched?: true;242        /**243         * The cached value was updated after a successful call to244         * {@link OptionsBase.fetchMethod}245         */246        fetchUpdated?: true;247        /**248         * The reason for a fetch() rejection.  Either the error raised by the249         * {@link OptionsBase.fetchMethod}, or the reason for an250         * AbortSignal.251         */252        fetchError?: Error;253        /**254         * The fetch received an abort signal255         */256        fetchAborted?: true;257        /**258         * The abort signal received was ignored, and the fetch was allowed to259         * continue in the background.260         */261        fetchAbortIgnored?: true;262        /**263         * The fetchMethod promise resolved successfully264         */265        fetchResolved?: true;266        /**267         * The fetchMethod promise was rejected268         */269        fetchRejected?: true;270        /**271         * The status of a {@link LRUCache#get} operation.272         *273         * - fetching: The item is currently being fetched.  If a previous value274         *   is present and allowed, that will be returned.275         * - stale: The item is in the cache, and is stale. If it was returned,276         *   then the `returnedStale` flag will be set.277         * - stale-fetching: The value is being fetched in the background, but is278         *   currently stale. If the stale value was returned, then the279         *   `returnedStale` flag will be set.280         * - hit: the item is in the cache281         * - miss: the item is not in the cache282         */283        get?: 'stale' | 'hit' | 'miss' | 'fetching' | 'stale-fetching';284        /**285         * A fetch or get operation returned a stale value.286         */287        returnedStale?: true;288        /**289         * A tracingChannel trace was started for this operation290         */291        trace?: boolean;292        /**293         * A reference to the cache instance associated with this operation294         */295        cache?: LRUCache<K & {}, V & {}, FC>;296    }297    /**298     * options which override the options set in the LRUCache constructor299     * when calling {@link LRUCache#fetch}.300     *301     * This is the union of {@link GetOptions} and {@link SetOptions}, plus302     * {@link OptionsBase.noDeleteOnFetchRejection},303     * {@link OptionsBase.allowStaleOnFetchRejection},304     * {@link FetchOptions.forceRefresh}, and305     * {@link FetcherOptions.context}306     *307     * Any of these may be modified in the {@link OptionsBase.fetchMethod}308     * function, but the {@link GetOptions} fields will of course have no309     * effect, as the {@link LRUCache#get} call already happened by the time310     * the fetchMethod is called.311     */312    interface FetcherFetchOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {313        status?: Status<K, V, FC>;314        size?: Size;315    }316    /**317     * Options that may be passed to the {@link LRUCache#fetch} method.318     */319    interface FetchOptions<K, V, FC> extends FetcherFetchOptions<K, V, FC> {320        /**321         * Set to true to force a re-load of the existing data, even if it322         * is not yet stale.323         */324        forceRefresh?: boolean;325        /**326         * Context provided to the {@link OptionsBase.fetchMethod} as327         * the {@link FetcherOptions.context} param.328         *329         * If the FC type is specified as unknown (the default),330         * undefined or void, then this is optional.  Otherwise, it will331         * be required.332         */333        context?: FC;334        signal?: AbortSignal;335        status?: Status<K, V, FC>;336    }337    /**338     * Options provided to {@link LRUCache#fetch} when the FC type is something339     * other than `unknown`, `undefined`, or `void`340     */341    interface FetchOptionsWithContext<K, V, FC> extends FetchOptions<K, V, FC> {342        context: FC;343    }344    /**345     * Options provided to {@link LRUCache#fetch} when the FC type is346     * `undefined` or `void`347     */348    interface FetchOptionsNoContext<K, V, FC extends undefined | void = undefined> extends FetchOptions<K, V, FC> {349        context?: FC;350    }351    interface MemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {352        /**353         * Set to true to force a re-load of the existing data, even if it354         * is not yet stale.355         */356        forceRefresh?: boolean;357        /**358         * Context provided to the {@link OptionsBase.memoMethod} as359         * the {@link MemoizerOptions.context} param.360         *361         * If the FC type is specified as unknown (the default),362         * undefined or void, then this is optional.  Otherwise, it will363         * be required.364         */365        context?: FC;366        status?: Status<K, V, FC>;367    }368    /**369     * Options provided to {@link LRUCache#memo} when the FC type is something370     * other than `unknown`, `undefined`, or `void`371     */372    interface MemoOptionsWithContext<K, V, FC> extends MemoOptions<K, V, FC> {373        context: FC;374    }375    /**376     * Options provided to {@link LRUCache#memo} when the FC type is377     * `undefined` or `void`378     */379    interface MemoOptionsNoContext<K, V, FC extends undefined | void = undefined> extends MemoOptions<K, V, FC> {380        context?: FC;381    }382    /**383     * Options provided to the384     * {@link OptionsBase.memoMethod} function.385     */386    interface MemoizerOptions<K, V, FC = unknown> {387        options: MemoizerMemoOptions<K, V, FC>;388        /**389         * Object provided in the {@link MemoOptions.context} option to390         * {@link LRUCache#memo}391         */392        context: FC;393    }394    /**395     * options which override the options set in the LRUCache constructor396     * when calling {@link LRUCache#memo}.397     *398     * This is the union of {@link GetOptions} and {@link SetOptions}, plus399     * {@link MemoOptions.forceRefresh}, and400     * {@link MemoOptions.context}401     *402     * Any of these may be modified in the {@link OptionsBase.memoMethod}403     * function, but the {@link GetOptions} fields will of course have no404     * effect, as the {@link LRUCache#get} call already happened by the time405     * the memoMethod is called.406     */407    interface MemoizerMemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL'> {408        status?: Status<K, V, FC>;409        size?: Size;410        start?: Milliseconds;411    }412    /**413     * Options that may be passed to the {@link LRUCache#has} method.414     */415    interface HasOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'updateAgeOnHas'> {416        status?: Status<K, V, FC>;417    }418    /**419     * Options that may be passed to the {@link LRUCache#get} method.420     */421    interface GetOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet'> {422        status?: Status<K, V, FC>;423    }424    /**425     * Options that may be passed to the {@link LRUCache#peek} method.426     */427    interface PeekOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'allowStale'> {428        status?: Status<K, V, FC>;429    }430    /**431     * Options that may be passed to the {@link LRUCache#set} method.432     */433    interface SetOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL'> {434        /**435         * If size tracking is enabled, then setting an explicit size436         * in the {@link LRUCache#set} call will prevent calling the437         * {@link OptionsBase.sizeCalculation} function.438         */439        size?: Size;440        /**441         * If TTL tracking is enabled, then setting an explicit start442         * time in the {@link LRUCache#set} call will override the443         * default time from `performance.now()` or `Date.now()`.444         *445         * Note that it must be a valid value for whichever time-tracking446         * method is in use.447         */448        start?: Milliseconds;449        status?: Status<K, V, FC>;450    }451    /**452     * The type signature for the {@link OptionsBase.fetchMethod} option.453     */454    type Fetcher<K, V, FC = unknown> = (key: K, staleValue: V | undefined, options: FetcherOptions<K, V, FC>) => Promise<V | undefined | void> | V | undefined | void;455    /**456     * the type signature for the {@link OptionsBase.memoMethod} option.457     */458    type Memoizer<K, V, FC = unknown> = (key: K, staleValue: V | undefined, options: MemoizerOptions<K, V, FC>) => V;459    /**460     * Options which may be passed to the {@link LRUCache} constructor.461     *462     * Most of these may be overridden in the various options that use463     * them.464     *465     * Despite all being technically optional, the constructor requires that466     * a cache is at minimum limited by one or more of {@link OptionsBase.max},467     * {@link OptionsBase.ttl}, or {@link OptionsBase.maxSize}.468     *469     * If {@link OptionsBase.ttl} is used alone, then it is strongly advised470     * (and in fact required by the type definitions here) that the cache471     * also set {@link OptionsBase.ttlAutopurge}, to prevent potentially472     * unbounded storage.473     *474     * All options are also available on the {@link LRUCache} instance, making475     * it safe to pass an LRUCache instance as the options argumemnt to476     * make another empty cache of the same type.477     *478     * Some options are marked as read-only, because changing them after479     * instantiation is not safe. Changing any of the other options will of480     * course only have an effect on subsequent method calls.481     */482    interface OptionsBase<K, V, FC> {483        /**484         * The maximum number of items to store in the cache before evicting485         * old entries. This is read-only on the {@link LRUCache} instance,486         * and may not be overridden.487         *488         * If set, then storage space will be pre-allocated at construction489         * time, and the cache will perform significantly faster.490         *491         * Note that significantly fewer items may be stored, if492         * {@link OptionsBase.maxSize} and/or {@link OptionsBase.ttl} are also493         * set.494         *495         * **It is strongly recommended to set a `max` to prevent unbounded growth496         * of the cache.**497         */498        max?: Count;499        /**500         * Max time in milliseconds for items to live in cache before they are501         * considered stale.  Note that stale items are NOT preemptively removed by502         * default, and MAY live in the cache, contributing to its LRU max, long503         * after they have expired, unless {@link OptionsBase.ttlAutopurge} is504         * set.505         *506         * If set to `0` (the default value), then that means "do not track507         * TTL", not "expire immediately".508         *509         * Also, as this cache is optimized for LRU/MRU operations, some of510         * the staleness/TTL checks will reduce performance, as they will incur511         * overhead by deleting items.512         *513         * This is not primarily a TTL cache, and does not make strong TTL514         * guarantees. There is no pre-emptive pruning of expired items, but you515         * _may_ set a TTL on the cache, and it will treat expired items as missing516         * when they are fetched, and delete them.517         *518         * Optional, but must be a non-negative integer in ms if specified.519         *520         * This may be overridden by passing an options object to `cache.set()`.521         *522         * At least one of `max`, `maxSize`, or `TTL` is required. This must be a523         * positive integer if set.524         *525         * Even if ttl tracking is enabled, **it is strongly recommended to set a526         * `max` to prevent unbounded growth of the cache.**527         *528         * If ttl tracking is enabled, and `max` and `maxSize` are not set,529         * and `ttlAutopurge` is not set, then a warning will be emitted530         * cautioning about the potential for unbounded memory consumption.531         * (The TypeScript definitions will also discourage this.)532         */533        ttl?: Milliseconds;534        /**535         * Minimum amount of time in ms in which to check for staleness.536         * Defaults to 1, which means that the current time is checked537         * at most once per millisecond.538         *539         * Set to 0 to check the current time every time staleness is tested.540         * (This reduces performance, and is theoretically unnecessary.)541         *542         * Setting this to a higher value will improve performance somewhat543         * while using ttl tracking, albeit at the expense of keeping stale544         * items around a bit longer than their TTLs would indicate.545         *546         * @default 1547         */548        ttlResolution?: Milliseconds;549        /**550         * Preemptively remove stale items from the cache.551         *552         * Note that this may *significantly* degrade performance, especially if553         * the cache is storing a large number of items. It is almost always best554         * to just leave the stale items in the cache, and let them fall out as new555         * items are added.556         *557         * Note that this means that {@link OptionsBase.allowStale} is a bit558         * pointless, as stale items will be deleted almost as soon as they559         * expire.560         *561         * Use with caution!562         */563        ttlAutopurge?: boolean;564        /**565         * When using time-expiring entries with `ttl`, setting this to `true` will566         * make each item's age reset to 0 whenever it is retrieved from cache with567         * {@link LRUCache#get}, causing it to not expire. (It can still fall out568         * of cache based on recency of use, of course.)569         *570         * Has no effect if {@link OptionsBase.ttl} is not set.571         *572         * This may be overridden by passing an options object to `cache.get()`.573         */574        updateAgeOnGet?: boolean;575        /**576         * When using time-expiring entries with `ttl`, setting this to `true` will577         * make each item's age reset to 0 whenever its presence in the cache is578         * checked with {@link LRUCache#has}, causing it to not expire. (It can579         * still fall out of cache based on recency of use, of course.)580         *581         * Has no effect if {@link OptionsBase.ttl} is not set.582         */583        updateAgeOnHas?: boolean;584        /**585         * Allow {@link LRUCache#get} and {@link LRUCache#fetch} calls to return586         * stale data, if available.587         *588         * By default, if you set `ttl`, stale items will only be deleted from the589         * cache when you `get(key)`. That is, it's not preemptively pruning items,590         * unless {@link OptionsBase.ttlAutopurge} is set.591         *592         * If you set `allowStale:true`, it'll return the stale value *as well as*593         * deleting it. If you don't set this, then it'll return `undefined` when594         * you try to get a stale entry.595         *596         * Note that when a stale entry is fetched, _even if it is returned due to597         * `allowStale` being set_, it is removed from the cache immediately. You598         * can suppress this behavior by setting599         * {@link OptionsBase.noDeleteOnStaleGet}, either in the constructor, or in600         * the options provided to {@link LRUCache#get}.601         *602         * This may be overridden by passing an options object to `cache.get()`.603         * The `cache.has()` method will always return `false` for stale items.604         *605         * Only relevant if a ttl is set.606         */607        allowStale?: boolean;608        /**609         * Function that is called on items when they are dropped from the610         * cache, as `dispose(value, key, reason)`.611         *612         * This can be handy if you want to close file descriptors or do613         * other cleanup tasks when items are no longer stored in the cache.614         *615         * **NOTE**: It is called _before_ the item has been fully removed616         * from the cache, so if you want to put it right back in, you need617         * to wait until the next tick. If you try to add it back in during618         * the `dispose()` function call, it will break things in subtle and619         * weird ways.620         *621         * Unlike several other options, this may _not_ be overridden by622         * passing an option to `set()`, for performance reasons.623         *624         * The `reason` will be one of the following strings, corresponding625         * to the reason for the item's deletion:626         *627         * - `evict` Item was evicted to make space for a new addition628         * - `set` Item was overwritten by a new value629         * - `expire` Item expired its TTL630         * - `fetch` Item was deleted due to a failed or aborted fetch, or a631         *   fetchMethod returning `undefined.632         * - `delete` Item was removed by explicit `cache.delete(key)`,633         *   `cache.clear()`, or `cache.set(key, undefined)`.634         */635        dispose?: Disposer<K, V>;636        /**637         * Function that is called when new items are inserted into the cache,638         * as `onInsert(value, key, reason)`.639         *640         * This can be useful if you need to perform actions when an item is641         * added, such as logging or tracking insertions.642         *643         * Unlike some other options, this may _not_ be overridden by passing644         * an option to `set()`, for performance and consistency reasons.645         */646        onInsert?: Inserter<K, V>;647        /**648         * The same as {@link OptionsBase.dispose}, but called *after* the entry649         * is completely removed and the cache is once again in a clean state.650         *651         * It is safe to add an item right back into the cache at this point.652         * However, note that it is *very* easy to inadvertently create infinite653         * recursion this way.654         */655        disposeAfter?: Disposer<K, V>;656        /**657         * Set to true to suppress calling the658         * {@link OptionsBase.dispose} function if the entry key is659         * still accessible within the cache.660         *661         * This may be overridden by passing an options object to662         * {@link LRUCache#set}.663         *664         * Only relevant if `dispose` or `disposeAfter` are set.665         */666        noDisposeOnSet?: boolean;667        /**668         * Boolean flag to tell the cache to not update the TTL when setting a new669         * value for an existing key (ie, when updating a value rather than670         * inserting a new value).  Note that the TTL value is _always_ set (if671         * provided) when adding a new entry into the cache.672         *673         * Has no effect if a {@link OptionsBase.ttl} is not set.674         *675         * May be passed as an option to {@link LRUCache#set}.676         */677        noUpdateTTL?: boolean;678        /**679         * Set to a positive integer to track the sizes of items added to the680         * cache, and automatically evict items in order to stay below this size.681         * Note that this may result in fewer than `max` items being stored.682         *683         * Attempting to add an item to the cache whose calculated size is greater684         * that this amount will be a no-op. The item will not be cached, and no685         * other items will be evicted.686         *687         * Optional, must be a positive integer if provided.688         *689         * Sets `maxEntrySize` to the same value, unless a different value is690         * provided for `maxEntrySize`.691         *692         * At least one of `max`, `maxSize`, or `TTL` is required. This must be a693         * positive integer if set.694         *695         * Even if size tracking is enabled, **it is strongly recommended to set a696         * `max` to prevent unbounded growth of the cache.**697         *698         * Note also that size tracking can negatively impact performance,699         * though for most cases, only minimally.700         */701        maxSize?: Size;702        /**703         * The effective size for background fetch promises.704         *705         * This has no effect unless `maxSize` and `sizeCalculation` are used,706         * and a {@link LRUCache.OptionsBase.fetchMethod} is provided to707         * support {@link LRUCache#fetch}.708         *709         * If a stale value is present in the cache, then the effective size of710         * the background fetch is the size of the stale item it will eventually711         * replace. If not, then this value is used as its effective size.712         *713         * @default 1714         */715        backgroundFetchSize?: number;716        /**717         * The maximum allowed size for any single item in the cache.718         *719         * If a larger item is passed to {@link LRUCache#set} or returned by a720         * {@link OptionsBase.fetchMethod} or {@link OptionsBase.memoMethod}, then721         * it will not be stored in the cache.722         *723         * Attempting to add an item whose calculated size is greater than724         * this amount will not cache the item or evict any old items, but725         * WILL delete an existing value if one is already present.726         *727         * Optional, must be a positive integer if provided. Defaults to728         * the value of `maxSize` if provided.729         */730        maxEntrySize?: Size;731        /**732         * A function that returns a number indicating the item's size.733         *734         * Requires {@link OptionsBase.maxSize} to be set.735         *736         * If not provided, and {@link OptionsBase.maxSize} or737         * {@link OptionsBase.maxEntrySize} are set, then all738         * {@link LRUCache#set} calls **must** provide an explicit739         * {@link SetOptions.size} or sizeCalculation param.740         */741        sizeCalculation?: SizeCalculator<K, V>;742        /**743         * Method that provides the implementation for {@link LRUCache#fetch}744         *745         * ```ts746         * fetchMethod(key, staleValue, { signal, options, context })747         * ```748         *749         * If `fetchMethod` is not provided, then `cache.fetch(key)` is equivalent750         * to `Promise.resolve(cache.get(key))`.751         *752         * If at any time, `signal.aborted` is set to `true`, or if the753         * `signal.onabort` method is called, or if it emits an `'abort'` event754         * which you can listen to with `addEventListener`, then that means that755         * the fetch should be abandoned. This may be passed along to async756         * functions aware of AbortController/AbortSignal behavior.757         *758         * The `fetchMethod` should **only** return `undefined` or a Promise759         * resolving to `undefined` if the AbortController signaled an `abort`760         * event. In all other cases, it should return or resolve to a value761         * suitable for adding to the cache.762         *763         * The `options` object is a union of the options that may be provided to764         * `set()` and `get()`. If they are modified, then that will result in765         * modifying the settings to `cache.set()` when the value is resolved, and766         * in the case of767         * {@link OptionsBase.noDeleteOnFetchRejection} and768         * {@link OptionsBase.allowStaleOnFetchRejection}, the handling of769         * `fetchMethod` failures.770         *771         * For example, a DNS cache may update the TTL based on the value returned772         * from a remote DNS server by changing `options.ttl` in the `fetchMethod`.773         */774        fetchMethod?: Fetcher<K, V, FC>;775        /**776         * Method that provides the implementation for {@link LRUCache#memo}777         */778        memoMethod?: Memoizer<K, V, FC>;779        /**780         * Set to true to suppress the deletion of stale data when a781         * {@link OptionsBase.fetchMethod} returns a rejected promise.782         */783        noDeleteOnFetchRejection?: boolean;784        /**785         * Do not delete stale items when they are retrieved with786         * {@link LRUCache#get}.787         *788         * Note that the `get` return value will still be `undefined`789         * unless {@link OptionsBase.allowStale} is true.790         *791         * When using time-expiring entries with `ttl`, by default stale792         * items will be removed from the cache when the key is accessed793         * with `cache.get()`.794         *795         * Setting this option will cause stale items to remain in the cache, until796         * they are explicitly deleted with `cache.delete(key)`, or retrieved with797         * `noDeleteOnStaleGet` set to `false`.798         *799         * This may be overridden by passing an options object to `cache.get()`.800         *801         * Only relevant if a ttl is used.802         */803        noDeleteOnStaleGet?: boolean;804        /**805         * Set to true to allow returning stale data when a806         * {@link OptionsBase.fetchMethod} throws an error or returns a rejected807         * promise.808         *809         * This differs from using {@link OptionsBase.allowStale} in that stale810         * data will ONLY be returned in the case that the {@link LRUCache#fetch}811         * fails, not any other times.812         *813         * If a `fetchMethod` fails, and there is no stale value available, the814         * `fetch()` will resolve to `undefined`. Ie, all `fetchMethod` errors are815         * suppressed.816         *817         * Implies `noDeleteOnFetchRejection`.818         *819         * This may be set in calls to `fetch()`, or defaulted on the constructor,820         * or overridden by modifying the options object in the `fetchMethod`.821         */822        allowStaleOnFetchRejection?: boolean;823        /**824         * Set to true to return a stale value from the cache when the825         * `AbortSignal` passed to the {@link OptionsBase.fetchMethod} dispatches826         * an `'abort'` event, whether user-triggered, or due to internal cache827         * behavior.828         *829         * Unless {@link OptionsBase.ignoreFetchAbort} is also set, the underlying830         * {@link OptionsBase.fetchMethod} will still be considered canceled, and831         * any value it returns will be ignored and not cached.832         *833         * Caveat: since fetches are aborted when a new value is explicitly834         * set in the cache, this can lead to fetch returning a stale value,835         * since that was the fallback value _at the moment the `fetch()` was836         * initiated_, even though the new updated value is now present in837         * the cache.838         *839         * For example:840         *841         * ```ts842         * const cache = new LRUCache<string, any>({843         *   ttl: 100,844         *   fetchMethod: async (url, oldValue, { signal }) =>  {845         *     const res = await fetch(url, { signal })846         *     return await res.json()847         *   }848         * })849         * cache.set('https://example.com/', { some: 'data' })850         * // 100ms go by...851         * const result = cache.fetch('https://example.com/')852         * cache.set('https://example.com/', { other: 'thing' })853         * console.log(await result) // { some: 'data' }854         * console.log(cache.get('https://example.com/')) // { other: 'thing' }855         * ```856         */857        allowStaleOnFetchAbort?: boolean;858        /**859         * Set to true to ignore the `abort` event emitted by the `AbortSignal`860         * object passed to {@link OptionsBase.fetchMethod}, and still cache the861         * resulting resolution value, as long as it is not `undefined`.862         *863         * When used on its own, this means aborted {@link LRUCache#fetch} calls864         * are not immediately resolved or rejected when they are aborted, and865         * instead take the full time to await.866         *867         * When used with {@link OptionsBase.allowStaleOnFetchAbort}, aborted868         * {@link LRUCache#fetch} calls will resolve immediately to their stale869         * cached value or `undefined`, and will continue to process and eventually870         * update the cache when they resolve, as long as the resulting value is871         * not `undefined`, thus supporting a "return stale on timeout while872         * refreshing" mechanism by passing `AbortSignal.timeout(n)` as the signal.873         *874         * For example:875         *876         * ```ts877         * const c = new LRUCache({878         *   ttl: 100,879         *   ignoreFetchAbort: true,880         *   allowStaleOnFetchAbort: true,881         *   fetchMethod: async (key, oldValue, { signal }) => {882         *     // note: do NOT pass the signal to fetch()!883         *     // let's say this fetch can take a long time.884         *     const res = await fetch(`https://slow-backend-server/${key}`)885         *     return await res.json()886         *   },887         * })888         *889         * // this will return the stale value after 100ms, while still890         * // updating in the background for next time.891         * const val = await c.fetch('key', { signal: AbortSignal.timeout(100) })892         * ```893         *894         * **Note**: regardless of this setting, an `abort` event _is still895         * emitted on the `AbortSignal` object_, so may result in invalid results896         * when passed to other underlying APIs that use AbortSignals.897         *898         * This may be overridden in the {@link OptionsBase.fetchMethod} or the899         * call to {@link LRUCache#fetch}.900         */901        ignoreFetchAbort?: boolean;902        /**903         * In some cases, you may want to swap out the performance/Date object904         * used for TTL tracking. This should almost certainly NOT be done in905         * production environments!906         *907         * This value defaults to `global.performance` if it has a `now()` method,908         * or the `global.Date` object otherwise.909         */910        perf?: Perf;911    }912    interface OptionsMaxLimit<K, V, FC> extends OptionsBase<K, V, FC> {913        max: Count;914    }915    interface OptionsTTLLimit<K, V, FC> extends OptionsBase<K, V, FC> {916        ttl: Milliseconds;917        ttlAutopurge: boolean;918    }919    interface OptionsSizeLimit<K, V, FC> extends OptionsBase<K, V, FC> {920        maxSize: Size;921    }922    /**923     * The valid safe options for the {@link LRUCache} constructor924     */925    type Options<K, V, FC> = OptionsMaxLimit<K, V, FC> | OptionsSizeLimit<K, V, FC> | OptionsTTLLimit<K, V, FC>;926    /**927     * Entry objects used by {@link LRUCache#load} and {@link LRUCache#dump},928     * and returned by {@link LRUCache#info}.929     */930    interface Entry<V> {931        value: V;932        ttl?: Milliseconds;933        size?: Size;934        start?: Milliseconds;935    }936}937/**938 * Default export, the thing you're using this module to get.939 *940 * The `K` and `V` types define the key and value types, respectively. The941 * optional `FC` type defines the type of the `context` object passed to942 * `cache.fetch()` and `cache.memo()`.943 *944 * Keys and values **must not** be `null` or `undefined`.945 *946 * All properties from the options object (with the exception of `max`,947 * `maxSize`, `fetchMethod`, `memoMethod`, `dispose` and `disposeAfter`) are948 * added as normal public members. (The listed options are read-only getters.)949 *950 * Changing any of these will alter the defaults for subsequent method calls.951 */952export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {953    #private;954    /**955     * {@link LRUCache.OptionsBase.perf}956     */957    get perf(): Perf;958    /**959     * {@link LRUCache.OptionsBase.ttl}960     */961    ttl: LRUCache.Milliseconds;962    /**963     * {@link LRUCache.OptionsBase.ttlResolution}964     */965    ttlResolution: LRUCache.Milliseconds;966    /**967     * {@link LRUCache.OptionsBase.ttlAutopurge}968     */969    ttlAutopurge: boolean;970    /**971     * {@link LRUCache.OptionsBase.updateAgeOnGet}972     */973    updateAgeOnGet: boolean;974    /**975     * {@link LRUCache.OptionsBase.updateAgeOnHas}976     */977    updateAgeOnHas: boolean;978    /**979     * {@link LRUCache.OptionsBase.allowStale}980     */981    allowStale: boolean;982    /**983     * {@link LRUCache.OptionsBase.noDisposeOnSet}984     */985    noDisposeOnSet: boolean;986    /**987     * {@link LRUCache.OptionsBase.noUpdateTTL}988     */989    noUpdateTTL: boolean;990    /**991     * {@link LRUCache.OptionsBase.maxEntrySize}992     */993    maxEntrySize: LRUCache.Size;994    /**995     * {@link LRUCache.OptionsBase.sizeCalculation}996     */997    sizeCalculation?: LRUCache.SizeCalculator<K, V>;998    /**999     * {@link LRUCache.OptionsBase.noDeleteOnFetchRejection}1000     */1001    noDeleteOnFetchRejection: boolean;1002    /**1003     * {@link LRUCache.OptionsBase.noDeleteOnStaleGet}1004     */1005    noDeleteOnStaleGet: boolean;1006    /**1007     * {@link LRUCache.OptionsBase.allowStaleOnFetchAbort}1008     */1009    allowStaleOnFetchAbort: boolean;1010    /**1011     * {@link LRUCache.OptionsBase.allowStaleOnFetchRejection}1012     */1013    allowStaleOnFetchRejection: boolean;1014    /**1015     * {@link LRUCache.OptionsBase.ignoreFetchAbort}1016     */1017    ignoreFetchAbort: boolean;1018    /** {@link LRUCache.OptionsBase.backgroundFetchSize} */1019    backgroundFetchSize: number;1020    /**1021     * Do not call this method unless you need to inspect the1022     * inner workings of the cache.  If anything returned by this1023     * object is modified in any way, strange breakage may occur.1024     *1025     * These fields are private for a reason!1026     *1027     * @internal1028     */1029    static unsafeExposeInternals<K extends {}, V extends {}, FC extends unknown = unknown>(c: LRUCache<K, V, FC>): {1030        starts: ZeroArray | undefined;1031        ttls: ZeroArray | undefined;1032        autopurgeTimers: (NodeJS.Timeout | undefined)[] | undefined;1033        sizes: ZeroArray | undefined;1034        keyMap: Map<K, number>;1035        keyList: (K | undefined)[];1036        valList: (V | BackgroundFetch<V> | undefined)[];1037        next: NumberArray;1038        prev: NumberArray;1039        readonly head: Index;1040        readonly tail: Index;1041        free: StackLike;1042        isBackgroundFetch: (p: unknown) => p is BackgroundFetch<V>;1043        backgroundFetch: (k: K, index: number | undefined, options: LRUCache.FetchOptions<K, V, FC>, context: unknown) => BackgroundFetch<V>;1044        moveToTail: (index: number) => void;1045        indexes: (options?: {1046            allowStale: boolean;1047        }) => Generator<Index, void, unknown>;1048        rindexes: (options?: {1049            allowStale: boolean;1050        }) => Generator<Index, void, unknown>;1051        isStale: (index: number | undefined) => boolean;1052    };1053    /**1054     * {@link LRUCache.OptionsBase.max} (read-only)1055     */1056    get max(): LRUCache.Count;1057    /**1058     * {@link LRUCache.OptionsBase.maxSize} (read-only)1059     */1060    get maxSize(): LRUCache.Count;1061    /**1062     * The total computed size of items in the cache (read-only)1063     */1064    get calculatedSize(): LRUCache.Size;1065    /**1066     * The number of items stored in the cache (read-only)1067     */1068    get size(): LRUCache.Count;1069    /**1070     * {@link LRUCache.OptionsBase.fetchMethod} (read-only)1071     */1072    get fetchMethod(): LRUCache.Fetcher<K, V, FC> | undefined;1073    get memoMethod(): LRUCache.Memoizer<K, V, FC> | undefined;1074    /**1075     * {@link LRUCache.OptionsBase.dispose} (read-only)1076     */1077    get dispose(): LRUCache.Disposer<K, V> | undefined;1078    /**1079     * {@link LRUCache.OptionsBase.onInsert} (read-only)1080     */1081    get onInsert(): LRUCache.Inserter<K, V> | undefined;1082    /**1083     * {@link LRUCache.OptionsBase.disposeAfter} (read-only)1084     */1085    get disposeAfter(): LRUCache.Disposer<K, V> | undefined;1086    constructor(options: LRUCache.Options<K, V, FC> | LRUCache<K, V, FC>);1087    /**1088     * Return the number of ms left in the item's TTL. If item is not in cache,1089     * returns `0`. Returns `Infinity` if item is in cache without a defined TTL.1090     */1091    getRemainingTTL(key: K): number;1092    /**1093     * Return a generator yielding `[key, value]` pairs,1094     * in order from most recently used to least recently used.1095     */1096    entries(): Generator<[K, V], void, unknown>;1097    /**1098     * Inverse order version of {@link LRUCache.entries}1099     *1100     * Return a generator yielding `[key, value]` pairs,1101     * in order from least recently used to most recently used.1102     */1103    rentries(): Generator<(K | V)[], void, unknown>;1104    /**1105     * Return a generator yielding the keys in the cache,1106     * in order from most recently used to least recently used.1107     */1108    keys(): Generator<K, void, unknown>;1109    /**1110     * Inverse order version of {@link LRUCache.keys}1111     *1112     * Return a generator yielding the keys in the cache,1113     * in order from least recently used to most recently used.1114     */1115    rkeys(): Generator<K, void, unknown>;1116    /**1117     * Return a generator yielding the values in the cache,1118     * in order from most recently used to least recently used.1119     */1120    values(): Generator<V, void, unknown>;1121    /**1122     * Inverse order version of {@link LRUCache.values}1123     *1124     * Return a generator yielding the values in the cache,1125     * in order from least recently used to most recently used.1126     */1127    rvalues(): Generator<V | undefined, void, unknown>;1128    /**1129     * Iterating over the cache itself yields the same results as1130     * {@link LRUCache.entries}1131     */1132    [Symbol.iterator](): Generator<[K, V], void, unknown>;1133    /**1134     * A String value that is used in the creation of the default string1135     * description of an object. Called by the built-in method1136     * `Object.prototype.toString`.1137     */1138    [Symbol.toStringTag]: string;1139    /**1140     * Find a value for which the supplied fn method returns a truthy value,1141     * similar to `Array.find()`. fn is called as `fn(value, key, cache)`.1142     */1143    find(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => boolean, getOptions?: LRUCache.GetOptions<K, V, FC>): V | undefined;1144    /**1145     * Call the supplied function on each item in the cache, in order from most1146     * recently used to least recently used.1147     *1148     * `fn` is called as `fn(value, key, cache)`.1149     *1150     * If `thisp` is provided, function will be called in the `this`-context of1151     * the provided object, or the cache if no `thisp` object is provided.1152     *1153     * Does not update age or recenty of use, or iterate over stale values.1154     */1155    forEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => unknown, thisp?: unknown): void;1156    /**1157     * The same as {@link LRUCache.forEach} but items are iterated over in1158     * reverse order.  (ie, less recently used items are iterated over first.)1159     */1160    rforEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => unknown, thisp?: unknown): void;1161    /**1162     * Delete any stale entries. Returns true if anything was removed,1163     * false otherwise.1164     */1165    purgeStale(): boolean;1166    /**1167     * Get the extended info about a given entry, to get its value, size, and1168     * TTL info simultaneously. Returns `undefined` if the key is not present.1169     *1170     * Unlike {@link LRUCache#dump}, which is designed to be portable and survive1171     * serialization, the `start` value is always the current timestamp, and the1172     * `ttl` is a calculated remaining time to live (negative if expired).1173     *1174     * Always returns stale values, if their info is found in the cache, so be1175     * sure to check for expirations (ie, a negative {@link LRUCache.Entry#ttl})1176     * if relevant.1177     */1178    info(key: K): LRUCache.Entry<V> | undefined;1179    /**1180     * Return an array of [key, {@link LRUCache.Entry}] tuples which can be1181     * passed to {@link LRUCache#load}.1182     *1183     * The `start` fields are calculated relative to a portable `Date.now()`1184     * timestamp, even if `performance.now()` is available.1185     *1186     * Stale entries are always included in the `dump`, even if1187     * {@link LRUCache.OptionsBase.allowStale} is false.1188     *1189     * Note: this returns an actual array, not a generator, so it can be more1190     * easily passed around.1191     */1192    dump(): [K, LRUCache.Entry<V>][];1193    /**1194     * Reset the cache and load in the items in entries in the order listed.1195     *1196     * The shape of the resulting cache may be different if the same options are1197     * not used in both caches.1198     *1199     * The `start` fields are assumed to be calculated relative to a portable1200     * `Date.now()` timestamp, even if `performance.now()` is available.

Showing the first 1,200 of 1400 lines. Download the file for the rest.