Document API

README.md

@@ -1,7 +1,92 @@
 # Rache
 
-A random-eviction cache which facilitates a global cache-size limit on a collection of sub caches.
+A random-eviction cache which imposes a global cache-size limit on all the caches derived from it.
 
-It randomly evicts an entry when it is full.
+Useful when you have many caches and want to limit their memory usage as a whole, instead of per cache.
 
-eviction and `get` and `set` operations take constant time.
+The `get` and `set` operations as well as `delete` (and cache eviction) take constant time.
+
+## Install
+
+```
+npm i rache
+```
+
+## Usage
+
+```
+const Rache = require('rache')
+
+const cache = new Rache({ maxSize: 3 })
+const cache2 = cache.sub()
+const cache3 = cache.sub()
+
+cache.set('key', 'value')
+cache2.set('key', 'otherValue')
+cache3.set('some', 'thing')
+
+// cache 1 is a separate cache from cache2 and cache3
+console.log('cached:', cache.get('key')) // 'value'
+
+// But they share the same global size
+console.log(cache.globalSize, 'of', cache.globalSize) // 3 of 3
+
+cache.set('key2', 'another value')
+// The cache was full, so one of the existing 3 entries got evicted
+
+console.log(cache.globalSize, 'of', cache.globalSize) // 3 of 3
+```
+
+## API
+
+#### `const cache = new Rache({ maxSize=65536 })`
+
+Creates a new cache.
+
+`maxSize` is the maximum amount of entries globally, across this cache and all derived caches (derived with `cache.sub()`).
+
+#### `const subCache = cache.sub()`
+
+Creates a new cache which shares the global memory limit with the original cache.
+
+#### `cache.globalSize`
+
+The amount of entries across all caches
+
+#### `cache.size`
+
+The amount of entries in this specific cache
+
+#### `cache.set(key, value)`
+
+Set the key to the given value.
+
+If the global cache size was at the limit, a random old entry is evicted from the cache.
+
+#### `cache.delete(key)`
+
+Delete the entry corresponding to `key`, if any.
+
+Returns `true` if an entry was deleted, `false` otherwise.
+
+#### `cache.get(key)`
+
+Returns the value corresponding to the given key, or `undefined` if there is none.
+
+#### `cache.keys()`
+
+Returns an iterator over the keys of this particular cache.
+
+#### `cache.values()`
+
+Returns an iterator over the values of this particular cache.
+
+#### `cache.clear()`
+
+Clear all entries from this particular cache.
+
+After clearing, new entries can again be added to the cache.
+
+#### `cache.destroy()`
+
+Destroys the cache. The cache should no longer be used after it has been destroyed.

example.js

@@ -1,15 +1,20 @@
-const GlobalCache = require('./index')
+const Rache = require('.')
 
-function main () {
-  const cache = new GlobalCache()
+const cache = new Rache({ maxSize: 3 })
+const cache2 = cache.sub()
+const cache3 = cache.sub()
 
-  for (let i = 0; i < 100_000; i++) {
-    cache.set(i, `value-${i}`)
-  }
+cache.set('key', 'value')
+cache2.set('key', 'otherValue')
+cache3.set('some', 'thing')
 
-  for (let i = 0; i < 100; i++) {
-    console.log('cache', i, cache.get(i))
-  }
-}
+// cache 1 is a separate cache from cache2 and cache3
+console.log('cached:', cache.get('key')) // 'value'
 
-main()
+// But they share the same global size
+console.log(cache.globalSize, 'of', cache.globalSize) // 3 of 3
+
+cache.set('key2', 'another value')
+// The cache was full, so one of the existing 3 entries got evicted
+
+console.log(cache.globalSize, 'of', cache.globalSize) // 3 of 3