org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/lru-cache/README.md

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