corrade-nucleus-nucleons – Blame information for rev 20
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
20 | office | 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 | * `rforEach(function(value,key,cache), [thisp])` |
||
100 | |||
101 | The same as `cache.forEach(...)` but items are iterated over in |
||
102 | reverse order. (ie, less recently used items are iterated over |
||
103 | first.) |
||
104 | |||
105 | * `keys()` |
||
106 | |||
107 | Return an array of the keys in the cache. |
||
108 | |||
109 | * `values()` |
||
110 | |||
111 | Return an array of the values in the cache. |
||
112 | |||
113 | * `length()` |
||
114 | |||
115 | Return total length of objects in cache taking into account |
||
116 | `length` options function. |
||
117 | |||
118 | * `itemCount` |
||
119 | |||
120 | Return total quantity of objects currently in cache. Note, that |
||
121 | `stale` (see options) items are returned as part of this item |
||
122 | count. |
||
123 | |||
124 | * `dump()` |
||
125 | |||
126 | Return an array of the cache entries ready for serialization and usage |
||
127 | with 'destinationCache.load(arr)`. |
||
128 | |||
129 | * `load(cacheEntriesArray)` |
||
130 | |||
131 | Loads another cache entries array, obtained with `sourceCache.dump()`, |
||
132 | into the cache. The destination cache is reset before loading new entries |