Add LRU option for in-memory storage (#34)

- Add an `LRU` cache class
- Support using this LRU instead of the simple in-memory cache

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+### 1.3.0
+
+- Add an `LRU` cache implementation
+- Add a `maxMemoryItems` option to use an LRU instead of the simple in-memory cache
+
 ### 1.2.3
 
 - [#24] Fix Typescript typings

README.md

@@ -24,6 +24,7 @@ You can instantiate the cache with 3 configurable options: `maxAge`,
 - `maxAge`: The duration, in milliseconds, before a cached item expires
 - `maxStaleness`: (Optional) The duration, in milliseconds, in which expired cache
 items are still served. Defaults to 0, meaning never serve data past expiration. Can also be set to `Infinity`, meaning always give at least a cached version.
+- `maxMemoryItems`: (Optional) Discards the least recently used items from memory when storing items past this maximum.
 - `fsCachePath`: (Optional) file path to create a file-system based cache
 - `shouldCache`: (Optional) a function to determine whether or not you will
 cache a found item
@@ -201,9 +202,7 @@ Your new `OtherCache` will then be used *after* the built-in caches. In the
 above case a fallback for the `memory` cache: any key not found in the `memory`
 cache will then be looked up in `OtherCache`.
 
-If you instead want to entirely replace the built-in array caches, you provide
-a `caches` array to override it. In this example, we replicate the default
-implementation by overriding with a `Memory` and `File` cache
+If you instead want to entirely replace the built-in array of caches, you can provide a `caches` array to override it. In this example, we replicate the default implementation by overriding with the `Memory` and `File` cache implementations that come with `out-of-band-cache`:
 
 ```js
 const path = require('path');
@@ -223,7 +222,17 @@ const cache = new Cache({
 });
 ```
 
-Your new cache must, at a minimum match the following spec to integrate
+### Provided Cache Methods
+
+The `out-of-band-cache` library comes with three cache implementations:
+
+- `Memory`: A simple in-memory cache that stores values in an object map
+- `File`: A file-based cache that stores values in a directory on disk. It takes a config object with a `path` property that specifies the directory to use.
+- `LRU`: An in-memory cache that stores a maximum number of items, evicting the least recently used items when the cache is full. It takes a config object with a `maxItems` property that specifies the maximum number of items to store and `maxAge`.
+
+### Authoring Custom Cache Methods
+
+A custom cache must, at a minimum, match the following spec to integrate
 properly with `out-of-band-cache`:
 
 ```js

lib/index.js

@@ -1,6 +1,7 @@
 const MultiLevelCache = require('./multi-level');
 const MemoryStorage = require('./memory');
 const FSStorage = require('./fs');
+const LRUStorage = require('./lru');
 
 /**
  * @typedef {(Object|String|Number|Boolean|Date)} JSONSerializable
@@ -25,13 +26,16 @@ const FSStorage = require('./fs');
  * @param {String} [opts.fsCachePath]             - The path to use for file-system caching. Disables FS caching if omitted.
  * @param {Number} opts.maxAge                    - The duration in milliseconds before a cached item expires.
  * @param {Number} opts.maxStaleness              - The duration in milliseconds in which expired cache items are still served.
+ * @param {Number} [opts.maxMemoryItems]          - The maximum number of items to retain in memory.
  * @param {ShouldCache} [opts.shouldCache]        - Function to determine whether to not we should cache the result
  * @param {ShouldCache} [opts.fallback[Cache]]    - An array of additional caches provided by the consumer of the application
  * @returns {MultiLevelCache} a new cache object
  */
 function Cache(opts) {
   let caches = [
-    new MemoryStorage()
+    opts.maxMemoryItems
+      ? new LRUStorage({ maxItems: opts.maxMemoryItems, maxAge: opts.maxAge })
+      : new MemoryStorage()
   ];
 
   if (opts.fsCachePath) {
@@ -54,7 +58,8 @@ function Cache(opts) {
   });
 }
 
-Cache.Memory = MemoryStorage;
 Cache.File = FSStorage;
+Cache.Memory = MemoryStorage;
+Cache.LRU = LRUStorage;
 
 module.exports = Cache;

lib/lru.js

@@ -0,0 +1,68 @@
+const LRU = require('lru-cache');
+
+/**
+ * A Cache that stores items in-memory with a Least Recently Used (LRU) eviction policy
+ */
+class LRUCache {
+  /**
+  * @param {Object} [opts]          - Options for the Client instance
+  * @param {Object} [opts.items]    - Items to pre-populate in the cache
+  * @param {number} [opts.maxItems] - Maximum items to retain in the cache
+  * @param {number} [opts.maxAge]   - Age in milliseconds before an item expires
+  */
+  constructor({ items = {}, maxItems, maxAge } = {}) {
+    if (typeof maxItems !== 'number' || maxItems < 1) {
+      throw new Error('max option is required and must be a positive integer');
+    }
+
+    this._items = new LRU({ max: maxItems, maxAge });
+
+    for (const [key, value] of Object.entries(items)) {
+      this._items.set(key, value);
+    }
+  }
+
+  /**
+   * Initializes the cache
+   *
+   * @returns {Promise<void>} a Promise which resolves once initialization completes
+   */
+  async init() {
+    // We synchronously initialized the cache, so we don't have to do anything
+  }
+
+  /**
+   * Tries to retrieve a cache item
+   *
+   * @param {String} key  - The cache key
+   * @returns {Promise<JSONSerializable>} a Promise which resolves if an item was found or fails if no item exists.
+   */
+  async get(key) {
+    if (this._items.has(key)) {
+      return this._items.get(key);
+    }
+
+    throw new Error('Key not found');
+  }
+
+  /**
+   * Stores a cache item
+   *
+   * @param {String} key    - The cache key
+   * @param {JSONSerializable} value  - The JSON-serializable value to store
+   *
+   * @returns {Promise<void>} a Promise which resolves once storage completes.
+   */
+  async set(key, value) {
+    this._items.set(key, value);
+  }
+
+  /**
+   * Clears the cache
+   */
+  reset() {
+    this._items.reset();
+  }
+}
+
+module.exports = LRUCache;