@isaacs/ttlcache 1.0.1 → 1.0.4

package/README.md

@@ -61,11 +61,22 @@ Create a new `TTLCache` object.
   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.
+  (Note that TTL is _always_ updated if the item is expired, since that is
+  treated as a new `set()` and the old item is no longer relevant.)
 * `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.
+
+    Disposal reasons:
+
+    * `'stale'` TTL expired.
+    * `'set'` Overwritten with a new different value.
+    * `'evict'` Removed from the cache to stay within capacity limit.
+    * `'delete'` Explicitly deleted with `cache.delete()` or
+      `cache.clear()`
+
 * `noDisposeOnSet` Do not call `dispose()` method when overwriting a key
   with a new value.  Defaults to `false`.  Overridable on `set()` method.
 
@@ -113,7 +124,8 @@ Delete all items from the cache.
 ### `cache.entries()`
 
 Return an iterator that walks through each `[key, value]` from soonest
-expiring to latest expiring.
+expiring to latest expiring.  (Items expiring at the same time are walked
+in insertion order.)
 
 Default iteration method for the cache object.
 
@@ -150,3 +162,29 @@ automatically.
 
 Called when an item is removed from the cache and should be disposed.  Set
 this on the constructor options.
+
+## Algorithm
+
+The cache uses two `Map` objects.  The first maps item keys to their
+expiration time, and the second maps item keys to their values.  Then, a
+null-prototype object uses the expiration time as keys, with the value
+being an array of all the keys expiring at that time.
+
+This leverages a few important features of modern JavaScript engines for
+fairly good performance:
+
+- `Map` objects are highly optimized for referring to arbitrary values by
+  arbitrary keys.
+- Objects with solely integer-numeric keys are iterated in sorted numeric
+  order rather than insertion order, and insertions in the middle of the
+  key ordering are still very fast.  This is true of all modern JS engines
+  tested at the time of this module's creation, but most particularly V8
+  (the engine in Node.js).
+
+When it is time to prune, we can always walk the null-prototype object in
+iteration order, deleting items until we come to the first key greater than
+the current time.
+
+Thus, the `start` time doesn't need to be tracked, only the expiration
+time.  When an item age is updated (either explicitly on `get()`, or by
+setting to a new value), it is deleted and re-inserted.

package/index.js

@@ -3,18 +3,24 @@
 // Relies on the fact that integer Object keys are kept sorted,
 // and managed very efficiently by V8.
 
-const maybeReqPerfHooks = (fallback) => {
+const maybeReqPerfHooks = fallback => {
   try {
     return require('perf_hooks').performance
   } catch (e) {
     return fallback
   }
 }
-const {now} = maybeReqPerfHooks(Date)
+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 }) {
+  constructor({
+    max = Infinity,
+    ttl,
+    updateAgeOnGet = false,
+    noUpdateTTL = false,
+    dispose,
+  }) {
     // {[expirationTime]: [keys]}
     this.expirations = Object.create(null)
     // {key=>val}
@@ -29,6 +35,8 @@ class TTLCache {
     }
     this.ttl = ttl
     this.max = max
+    this.updateAgeOnGet = updateAgeOnGet
+    this.noUpdateTTL = noUpdateTTL
     if (dispose !== undefined) {
       if (typeof dispose !== 'function') {
         throw new TypeError('dispose must be function if set')
@@ -37,8 +45,9 @@ class TTLCache {
     }
   }
 
-  clear () {
-    const entries = this.dispose !== TTLCache.prototype.dispose ? [...this] : []
+  clear() {
+    const entries =
+      this.dispose !== TTLCache.prototype.dispose ? [...this] : []
     this.data.clear()
     this.expirationMap.clear()
     this.expirations = Object.create(null)
@@ -47,14 +56,25 @@ class TTLCache {
     }
   }
 
-  set (key, val, { ttl = this.ttl, noUpdateTTL = this.noUpdateTTL, noDisposeOnSet = this.noDisposeOnSet } = {}) {
+  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)
+    const time = now()
+    const oldValue =
+      current === undefined ? undefined : this.data.get(key)
     if (current !== undefined) {
-      const oldValue = this.data.get(key)
-      if (noUpdateTTL) {
+      // we aren't updating the ttl, so just set the data
+      if (noUpdateTTL && current > time) {
         if (oldValue !== val) {
           this.data.set(key, val)
           if (!noDisposeOnSet) {
@@ -63,13 +83,17 @@ class TTLCache {
         }
         return this
       } else {
-        this.delete(key, {
-          reason: 'set',
-          noDispose: noDisposeOnSet || oldValue === val,
-        })
+        // just delete from expirations list, since we're about to
+        // add to data and expirationsMap anyway
+        const exp = this.expirations[current]
+        if (!exp || exp.length <= 1) {
+          delete this.expirations[current]
+        } else {
+          this.expirations[current] = exp.filter(k => k !== key)
+        }
       }
     }
-    const expiration = Math.ceil(now() + ttl)
+    const expiration = Math.ceil(time + ttl)
     this.expirationMap.set(key, expiration)
     this.data.set(key, val)
     if (!this.expirations[expiration]) {
@@ -79,52 +103,64 @@ class TTLCache {
       this.expirations[expiration] = []
     }
     this.expirations[expiration].push(key)
+
     while (this.size > this.max) {
       this.purgeToCapacity()
     }
+
+    if (!noDisposeOnSet && current && oldValue !== val) {
+      this.dispose(oldValue, key, 'set')
+    }
     return this
   }
 
-  has (key) {
+  has(key) {
     return this.data.has(key)
   }
 
-  getRemainingTTL (key) {
+  getRemainingTTL(key) {
     const expiration = this.expirationMap.get(key)
-    return expiration !== undefined ? Math.max(0, expiration - now()) : 0
+    return expiration !== undefined
+      ? Math.max(0, expiration - now())
+      : 0
   }
 
-  get (key, { updateAgeOnGet = this.updateAgeOnGet, ttl = this.ttl } = {}) {
+  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 })
+      this.set(key, val, {
+        noUpdateTTL: false,
+        noDisposeOnSet: true,
+        ttl,
+      })
     }
     return val
   }
 
-  dispose (value, key) {}
+  dispose(_, __) {}
 
-  delete (key, { reason = 'delete', noDispose = false } = {}) {
+  delete(key) {
     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) {
+      if (exp && exp.length <= 1) {
         delete this.expirations[current]
       } else {
         this.expirations[current] = exp.filter(k => k !== key)
       }
-      if (!noDispose) {
-        this.dispose(value, key, reason)
-      }
+      this.dispose(value, key, 'delete')
       return true
     }
     return false
   }
 
-  purgeToCapacity () {
+  purgeToCapacity() {
     for (const exp in this.expirations) {
       const keys = this.expirations[exp]
       if (this.size - keys.length >= this.max) {
@@ -148,11 +184,11 @@ class TTLCache {
     }
   }
 
-  get size () {
+  get size() {
     return this.data.size
   }
 
-  purgeStale () {
+  purgeStale() {
     const n = now()
     for (const exp in this.expirations) {
       if (exp > n) {
@@ -168,28 +204,28 @@ class TTLCache {
     }
   }
 
-  *entries () {
+  *entries() {
     for (const exp in this.expirations) {
       for (const key of this.expirations[exp]) {
         yield [key, this.data.get(key)]
       }
     }
   }
-  *keys () {
+  *keys() {
     for (const exp in this.expirations) {
       for (const key of this.expirations[exp]) {
         yield key
       }
     }
   }
-  *values () {
+  *values() {
     for (const exp in this.expirations) {
       for (const key of this.expirations[exp]) {
         yield this.data.get(key)
       }
     }
   }
-  [Symbol.iterator] () {
+  [Symbol.iterator]() {
     return this.entries()
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isaacs/ttlcache",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "files": [
     "index.js"
   ],
@@ -23,10 +23,35 @@
     "prepublishOnly": "git push origin --follow-tags"
   },
   "devDependencies": {
-    "clock-mock": "^1.0.4",
-    "tap": "^16.0.1"
+    "@types/node": "^17.0.42",
+    "@types/tap": "^15.0.7",
+    "clock-mock": "^1.0.6",
+    "prettier": "^2.7.0",
+    "tap": "^16.0.1",
+    "ts-node": "^10.8.1"
   },
   "engines": {
     "node": ">=12"
+  },
+  "tap": {
+    "nyc-arg": [
+      "--include=index.js"
+    ],
+    "node-arg": [
+      "--require",
+      "ts-node/register"
+    ],
+    "ts": false
+  },
+  "prettier": {
+    "semi": false,
+    "printWidth": 70,
+    "tabWidth": 2,
+    "useTabs": false,
+    "singleQuote": true,
+    "jsxSingleQuote": false,
+    "bracketSameLine": true,
+    "arrowParens": "avoid",
+    "endOfLine": "lf"
   }
 }