1 | # lru cache
|
2 |
|
3 | A cache object that deletes the least-recently-used items.
|
4 |
|
5 | ## Usage:
|
6 |
|
7 | ```javascript
|
8 | var LRU = require("lru-cache")
|
9 | , options = { max: 500
|
10 | , length: function (n) { return n * 2 }
|
11 | , dispose: function (key, n) { n.close() }
|
12 | , maxAge: 1000 * 60 * 60 }
|
13 | , cache = LRU(options)
|
14 | , otherCache = LRU(50) // sets just the max size
|
15 |
|
16 | cache.set("key", "value")
|
17 | cache.get("key") // "value"
|
18 |
|
19 | cache.reset() // empty the cache
|
20 | ```
|
21 |
|
22 | If you put more stuff in it, then items will fall out.
|
23 |
|
24 | If you try to put an oversized thing in it, then it'll fall out right
|
25 | away.
|
26 |
|
27 | ## Options
|
28 |
|
29 | * `max` The maximum size of the cache, checked by applying the length
|
30 | function to all values in the cache. Not setting this is kind of
|
31 | silly, since that's the whole purpose of this lib, but it defaults
|
32 | to `Infinity`.
|
33 | * `maxAge` Maximum age in ms. Items are not pro-actively pruned out
|
34 | as they age, but if you try to get an item that is too old, it'll
|
35 | drop it and return undefined instead of giving it to you.
|
36 | * `length` Function that is used to calculate the length of stored
|
37 | items. If you're storing strings or buffers, then you probably want
|
38 | to do something like `function(n){return n.length}`. The default is
|
39 | `function(n){return 1}`, which is fine if you want to store `n`
|
40 | like-sized things.
|
41 | * `dispose` Function that is called on items when they are dropped
|
42 | from the cache. This can be handy if you want to close file
|
43 | descriptors or do other cleanup tasks when items are no longer
|
44 | accessible. Called with `key, value`. It's called *before*
|
45 | actually removing the item from the internal cache, so if you want
|
46 | to immediately put it back in, you'll have to do that in a
|
47 | `nextTick` or `setTimeout` callback or it won't do anything.
|
48 | * `stale` By default, if you set a `maxAge`, it'll only actually pull
|
49 | stale items out of the cache when you `get(key)`. (That is, it's
|
50 | not pre-emptively doing a `setTimeout` or anything.) If you set
|
51 | `stale:true`, it'll return the stale value before deleting it. If
|
52 | you don't set this, then it'll return `undefined` when you try to
|
53 | get a stale entry, as if it had already been deleted.
|
54 |
|
55 | ## API
|
56 |
|
57 | * `set(key, value, max)`
|
58 | * `get(key) => value`
|
59 |
|
60 | Both of these will update the "recently used"-ness of the key.
|
61 | They do what you think. `max` is optional and overrides the
|
62 | cache `max` option if provided.
|
63 |
|
64 | * `peek(key)`
|
65 |
|
66 | Returns the key value (or `undefined` if not found) without
|
67 | updating the "recently used"-ness of the key.
|
68 |
|
69 | (If you find yourself using this a lot, you *might* be using the
|
70 | wrong sort of data structure, but there are some use cases where
|
71 | it's handy.)
|
72 |
|
73 | * `del(key)`
|
74 |
|
75 | Deletes a key out of the cache.
|
76 |
|
77 | * `reset()`
|
78 |
|
79 | Clear the cache entirely, throwing away all values.
|
80 |
|
81 | * `has(key)`
|
82 |
|
83 | Check if a key is in the cache, without updating the recent-ness
|
84 | or deleting it for being stale.
|
85 |
|
86 | * `forEach(function(value,key,cache), [thisp])`
|
87 |
|
88 | Just like `Array.prototype.forEach`. Iterates over all the keys
|
89 | in the cache, in order of recent-ness. (Ie, more recently used
|
90 | items are iterated over first.)
|
91 |
|
92 | * `keys()`
|
93 |
|
94 | Return an array of the keys in the cache.
|
95 |
|
96 | * `values()`
|
97 |
|
98 | Return an array of the values in the cache.
|
99 |
|
100 | * `length()`
|
101 |
|
102 | Return total length of objects in cache taking into account
|
103 | `length` options function.
|
104 |
|
105 | * `itemCount()`
|
106 |
|
107 | Return total quantity of objects currently in cache. Note, that
|
108 | `stale` (see options) items are returned as part of this item
|
109 | count.
|