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