@isaacs/ttlcache 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+The ISC License
+
+Copyright (c) 2022 - Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @isaacs/ttlcache
+
+The time-based use-recency-unaware cousin of
+[`lru-cache`](http://npm.im/lru-cache)
+
+## Usage
+
+Essentially, this is the same API as
+[`lru-cache`](http://npm.im/lru-cache), but it does not do LRU tracking,
+and is bound primarily by time, rather than space.  Since entries are not
+purged based on recency of use, it can save a lot of extra work managing
+linked lists, mapping keys to pointers, and so on.
+
+TTLs are millisecond granularity.
+
+If a capacity limit is set, then the soonest-expiring items are purged
+first, to bring it down to the size limit.
+
+Iteration is in order from soonest expiring until latest expiring.
+
+If multiple items are expiring in the same ms, then the soonest-added
+items are considered "older" for purposes of iterating and purging down to
+capacity.
+
+A TTL _must_ be set for every entry, which can be defaulted in the
+constructor.
+
+Custom size calculation is not supported.  Max capacity is simply the count
+of items in the cache.
+
+```js
+const TTLCache = require('ttlcache')
+const cache = new TTLCache({ max: 10000, ttl: 1000 })
+
+// set some value
+cache.set(1, 2)
+
+// 999 ms later
+cache.has(1) // returns true
+cache.get(1) // returns 2
+
+// 1000 ms later
+cache.get(1) // returns undefined
+cache.has(1) // returns false
+```
+
+## API
+
+### `const TTLCache = require('@isaacs/ttlcache')` or `import TTLCache from '@isaacs/ttlcache'
+
+Default export is the `TTLCache` class.
+
+### `new TTLCache({ ttl, max = Infinty, updateAgeOnGet = false, noUpdateTTL = false })`
+
+Create a new `TTLCache` object.
+
+* `max` The max number of items to keep in the cache.
+* `ttl` The max time in ms to store items.  Overridable on the `set()`
+  method.
+* `updateAgeOnGet` Should the age of an item be updated when it is
+  retrieved?  Defaults to `false`.  Overridable on the `get()` method.
+* `noUpdateTTL` Should setting a new value for an existing key leave the
+  TTL unchanged?  Defaults to `false`.  Overridable on the `set()` method.
+* `dispose` Method called with `(value, key, reason)` when an item is
+  removed from the cache.  Called once item is fully removed from cache.
+  It is safe to re-add at this point, but note that adding when `reason` is
+  `'set'` can result in infinite recursion if `noDisponseOnSet` is not
+  specified.
+* `noDisposeOnSet` Do not call `dispose()` method when overwriting a key
+  with a new value.  Defaults to `false`.  Overridable on `set()` method.
+
+When used as an iterator, like `for (const [key, value] of cache)` or
+`[...cache]`, the cache yields the same results as the `entries()` method.
+
+### `cache.size`
+
+The number of items in the cache.
+
+### `cache.set(key, value, { ttl, noUpdateTTL, noDisposeOnSet } = {})`
+
+Store a value in the cache for the specified time.
+
+`ttl` and `noUpdateTTL` optionally override defaults on the constructor.
+
+Returns the cache object.
+
+### `cache.get(key, {updateAgeOnGet, ttl} = {})`
+
+Get an item stored in the cache.  Returns `undefined` if the item is not in
+the cache (including if it has expired and been purged).
+
+If `updateAgeOnGet` is `true`, then re-add the item into the cache with the
+updated `ttl` value.  Both options default to the settings on the
+constructor.
+
+### `cache.getRemainingTTL(key)`
+
+Return the remaining time before an item expires.  Returns `0` if the item
+is not found in the cache or is already expired.
+
+### `cache.has(key)`
+
+Return true if the item is in the cache.
+
+### `cache.delete(key)`
+
+Remove an item from the cache.
+
+### `cache.clear()`
+
+Delete all items from the cache.
+
+### `cache.entries()`
+
+Return an iterator that walks through each `[key, value]` from soonest
+expiring to latest expiring.
+
+Default iteration method for the cache object.
+
+### `cache.keys()`
+
+Return an iterator that walks through each `key` from soonest expiring to
+latest expiring.
+
+### `cache.values()`
+
+Return an iterator that walks through each `value` from soonest expiring to
+latest expiring.
+
+## Internal Methods
+
+You should not ever call these, they are managed automatically.
+
+### `purgeStale`
+
+**Internal**
+
+Removes items which have expired.  Called automatically.
+
+### `purgeToCapacity`
+
+**Internal**
+
+Removes soonest-expiring items when the capacity limit is reached.  Called
+automatically.
+
+### `dispose`
+
+**Internal**
+
+Called when an item is removed from the cache and should be disposed.  Set
+this on the constructor options.

package/index.js

@@ -0,0 +1,197 @@
+// A simple TTL cache with max capacity option, ms resolution,
+// autopurge, and reasonably optimized performance
+// Relies on the fact that integer Object keys are kept sorted,
+// and managed very efficiently by V8.
+
+const maybeReqPerfHooks = (fallback) => {
+  try {
+    return require('perf_hooks').performance
+  } catch (e) {
+    return fallback
+  }
+}
+const {now} = maybeReqPerfHooks(Date)
+const isPosInt = n => n && n === Math.floor(n) && n > 0 && isFinite(n)
+
+class TTLCache {
+  constructor ({ max = Infinity, ttl, updateAgeOnGet = false, noUpdateTTL = false, dispose }) {
+    // {[expirationTime]: [keys]}
+    this.expirations = Object.create(null)
+    // {key=>val}
+    this.data = new Map()
+    // {key=>expiration}
+    this.expirationMap = new Map()
+    if (ttl !== undefined && !isPosInt(ttl)) {
+      throw new TypeError('ttl must be positive integer if set')
+    }
+    if (!isPosInt(max) && max !== Infinity) {
+      throw new TypeError('max must be positive integer or Infinity')
+    }
+    this.ttl = ttl
+    this.max = max
+    if (dispose !== undefined) {
+      if (typeof dispose !== 'function') {
+        throw new TypeError('dispose must be function if set')
+      }
+      this.dispose = dispose
+    }
+  }
+
+  clear () {
+    const entries = this.dispose !== TTLCache.prototype.dispose ? [...this] : []
+    this.data.clear()
+    this.expirationMap.clear()
+    this.expirations = Object.create(null)
+    for (const [key, val] of entries) {
+      this.dispose(val, key, 'delete')
+    }
+  }
+
+  set (key, val, { ttl = this.ttl, noUpdateTTL = this.noUpdateTTL, noDisposeOnSet = this.noDisposeOnSet } = {}) {
+    if (!isPosInt(ttl)) {
+      throw new TypeError('ttl must be positive integer')
+    }
+    const current = this.expirationMap.get(key)
+    if (current !== undefined) {
+      const oldValue = this.data.get(key)
+      if (noUpdateTTL) {
+        if (oldValue !== val) {
+          this.data.set(key, val)
+          if (!noDisposeOnSet) {
+            this.dispose(oldValue, key, 'set')
+          }
+        }
+        return this
+      } else {
+        this.delete(key, {
+          reason: 'set',
+          noDispose: noDisposeOnSet || oldValue === val,
+        })
+      }
+    }
+    const expiration = Math.ceil(now() + ttl)
+    this.expirationMap.set(key, expiration)
+    this.data.set(key, val)
+    if (!this.expirations[expiration]) {
+      const t = setTimeout(() => this.purgeStale(), ttl)
+      /* istanbul ignore else - affordance for non-node envs */
+      if (t.unref) t.unref()
+      this.expirations[expiration] = []
+    }
+    this.expirations[expiration].push(key)
+    while (this.size > this.max) {
+      this.purgeToCapacity()
+    }
+    return this
+  }
+
+  has (key) {
+    return this.data.has(key)
+  }
+
+  getRemainingTTL (key) {
+    const expiration = this.expirationMap.get(key)
+    return expiration !== undefined ? Math.max(0, expiration - now()) : 0
+  }
+
+  get (key, { updateAgeOnGet = this.updateAgeOnGet, ttl = this.ttl } = {}) {
+    const val = this.data.get(key)
+    if (updateAgeOnGet) {
+      this.set(key, val, { noUpdateTTL: false, noDisposeOnSet: true, ttl })
+    }
+    return val
+  }
+
+  dispose (value, key) {}
+
+  delete (key, { reason = 'delete', noDispose = false } = {}) {
+    const current = this.expirationMap.get(key)
+    if (current !== undefined) {
+      const value = this.data.get(key)
+      this.data.delete(key)
+      this.expirationMap.delete(key)
+      const exp = this.expirations[current]
+      if (exp.length === 1) {
+        delete this.expirations[current]
+      } else {
+        this.expirations[current] = exp.filter(k => k !== key)
+      }
+      if (!noDispose) {
+        this.dispose(value, key, reason)
+      }
+      return true
+    }
+    return false
+  }
+
+  purgeToCapacity () {
+    for (const exp in this.expirations) {
+      const keys = this.expirations[exp]
+      if (this.size - keys.length >= this.max) {
+        for (const key of keys) {
+          const val = this.data.get(key)
+          this.data.delete(key)
+          this.expirationMap.delete(key)
+          this.dispose(val, key, 'evict')
+        }
+        delete this.expirations[exp]
+      } else {
+        const s = this.size - this.max
+        for (const key of keys.splice(0, s)) {
+          const val = this.data.get(key)
+          this.data.delete(key)
+          this.expirationMap.delete(key)
+          this.dispose(val, key, 'evict')
+        }
+      }
+      return
+    }
+  }
+
+  get size () {
+    return this.data.size
+  }
+
+  purgeStale () {
+    const n = now()
+    for (const exp in this.expirations) {
+      if (exp > n) {
+        return
+      }
+      for (const key of this.expirations[exp]) {
+        const val = this.data.get(key)
+        this.data.delete(key)
+        this.expirationMap.delete(key)
+        this.dispose(val, key, 'stale')
+      }
+      delete this.expirations[exp]
+    }
+  }
+
+  *entries () {
+    for (const exp in this.expirations) {
+      for (const key of this.expirations[exp]) {
+        yield [key, this.data.get(key)]
+      }
+    }
+  }
+  *keys () {
+    for (const exp in this.expirations) {
+      for (const key of this.expirations[exp]) {
+        yield key
+      }
+    }
+  }
+  *values () {
+    for (const exp in this.expirations) {
+      for (const key of this.expirations[exp]) {
+        yield this.data.get(key)
+      }
+    }
+  }
+  [Symbol.iterator] () {
+    return this.entries()
+  }
+}
+
+module.exports = TTLCache

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@isaacs/ttlcache",
+  "version": "1.0.0",
+  "files": [
+    "index.js"
+  ],
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "description": "The time-based use-recency-unaware cousin of [`lru-cache`](http://npm.im/lru-cache)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isaacs/ttlcache"
+  },
+  "author": "Isaac Z. Schlueter <i@izs.me> (https://izs.me)",
+  "license": "ISC",
+  "scripts": {
+    "test": "tap",
+    "snap": "tap",
+    "preversion": "npm test",
+    "postversion": "npm publish",
+    "prepublishOnly": "git push origin --follow-tags"
+  },
+  "devDependencies": {
+    "clock-mock": "^1.0.4",
+    "tap": "^16.0.1"
+  },
+  "engines": {
+    "node": ">=12"
+  }
+}