UNPKG

6.64 kBTypeScriptView Raw
1// Type definitions for lru-cache 5.1
2// Project: https://github.com/isaacs/node-lru-cache
3// Definitions by: Bart van der Schoor <https://github.com/Bartvds>
4// BendingBender <https://github.com/BendingBender>
5// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
6// TypeScript Version: 2.3
7
8declare class LRUCache<K, V> {
9 constructor(options?: LRUCache.Options<K, V>);
10 constructor(max: number);
11
12 /**
13 * Return total length of objects in cache taking into account `length` options function.
14 */
15 readonly length: number;
16
17 /**
18 * Return total quantity of objects currently in cache. Note,
19 * that `stale` (see options) items are returned as part of this item count.
20 */
21 readonly itemCount: number;
22
23 /**
24 * Same as Options.allowStale.
25 */
26 allowStale: boolean;
27
28 /**
29 * Same as Options.length.
30 */
31 lengthCalculator(value: V): number;
32
33 /**
34 * Same as Options.max. Resizes the cache when the `max` changes.
35 */
36 max: number;
37
38 /**
39 * Same as Options.maxAge. Resizes the cache when the `maxAge` changes.
40 */
41 maxAge: number;
42
43 /**
44 * Will update the "recently used"-ness of the key. They do what you think.
45 * `maxAge` is optional and overrides the cache `maxAge` option if provided.
46 */
47 set(key: K, value: V, maxAge?: number): boolean;
48
49 /**
50 * Will update the "recently used"-ness of the key. They do what you think.
51 * `maxAge` is optional and overrides the cache `maxAge` option if provided.
52 *
53 * If the key is not found, will return `undefined`.
54 */
55 get(key: K): V | undefined;
56
57 /**
58 * Returns the key value (or `undefined` if not found) without updating
59 * the "recently used"-ness of the key.
60 *
61 * (If you find yourself using this a lot, you might be using the wrong
62 * sort of data structure, but there are some use cases where it's handy.)
63 */
64 peek(key: K): V | undefined;
65
66 /**
67 * Check if a key is in the cache, without updating the recent-ness
68 * or deleting it for being stale.
69 */
70 has(key: K): boolean;
71
72 /**
73 * Deletes a key out of the cache.
74 */
75 del(key: K): void;
76
77 /**
78 * Clear the cache entirely, throwing away all values.
79 */
80 reset(): void;
81
82 /**
83 * Manually iterates over the entire cache proactively pruning old entries.
84 */
85 prune(): void;
86
87 /**
88 * Just like `Array.prototype.forEach`. Iterates over all the keys in the cache,
89 * in order of recent-ness. (Ie, more recently used items are iterated over first.)
90 */
91 forEach<T = this>(callbackFn: (this: T, value: V, key: K, cache: this) => void, thisArg?: T): void;
92
93 /**
94 * The same as `cache.forEach(...)` but items are iterated over in reverse order.
95 * (ie, less recently used items are iterated over first.)
96 */
97 rforEach<T = this>(callbackFn: (this: T, value: V, key: K, cache: this) => void, thisArg?: T): void;
98
99 /**
100 * Return an array of the keys in the cache.
101 */
102 keys(): K[];
103
104 /**
105 * Return an array of the values in the cache.
106 */
107 values(): V[];
108
109 /**
110 * Return an array of the cache entries ready for serialization and usage with `destinationCache.load(arr)`.
111 */
112 dump(): Array<LRUCache.Entry<K, V>>;
113
114 /**
115 * Loads another cache entries array, obtained with `sourceCache.dump()`,
116 * into the cache. The destination cache is reset before loading new entries
117 *
118 * @param cacheEntries Obtained from `sourceCache.dump()`
119 */
120 load(cacheEntries: ReadonlyArray<LRUCache.Entry<K, V>>): void;
121}
122
123declare namespace LRUCache {
124 interface Options<K, V> {
125 /**
126 * The maximum size of the cache, checked by applying the length
127 * function to all values in the cache. Not setting this is kind of silly,
128 * since that's the whole purpose of this lib, but it defaults to `Infinity`.
129 */
130 max?: number;
131
132 /**
133 * Maximum age in ms. Items are not pro-actively pruned out as they age,
134 * but if you try to get an item that is too old, it'll drop it and return
135 * undefined instead of giving it to you.
136 */
137 maxAge?: number;
138
139 /**
140 * Function that is used to calculate the length of stored items.
141 * If you're storing strings or buffers, then you probably want to do
142 * something like `function(n, key){return n.length}`. The default
143 * is `function(){return 1}`, which is fine if you want to store
144 * `max` like-sized things. The item is passed as the first argument,
145 * and the key is passed as the second argument.
146 */
147 length?(value: V, key?: K): number;
148
149 /**
150 * Function that is called on items when they are dropped from the cache.
151 * This can be handy if you want to close file descriptors or do other
152 * cleanup tasks when items are no longer accessible. Called with `key, value`.
153 * It's called before actually removing the item from the internal cache,
154 * so if you want to immediately put it back in, you'll have to do that in
155 * a `nextTick` or `setTimeout` callback or it won't do anything.
156 */
157 dispose?(key: K, value: V): void;
158
159 /**
160 * By default, if you set a `maxAge`, it'll only actually pull stale items
161 * out of the cache when you `get(key)`. (That is, it's not pre-emptively
162 * doing a `setTimeout` or anything.) If you set `stale:true`, it'll return
163 * the stale value before deleting it. If you don't set this, then it'll
164 * return `undefined` when you try to get a stale entry,
165 * as if it had already been deleted.
166 */
167 stale?: boolean;
168
169 /**
170 * By default, if you set a `dispose()` method, then it'll be called whenever
171 * a `set()` operation overwrites an existing key. If you set this option,
172 * `dispose()` will only be called when a key falls out of the cache,
173 * not when it is overwritten.
174 */
175 noDisposeOnSet?: boolean;
176
177 /**
178 * When using time-expiring entries with `maxAge`, setting this to `true` will make each
179 * item's effective time update to the current time whenever it is retrieved from cache,
180 * causing it to not expire. (It can still fall out of cache based on recency of use, of
181 * course.)
182 */
183 updateAgeOnGet?: boolean;
184 }
185
186 interface Entry<K, V> {
187 k: K;
188 v: V;
189 e: number;
190 }
191}
192
193export = LRUCache;