@isaacs/ttlcache 1.1.0 → 1.2.1

package/README.md

@@ -29,7 +29,7 @@ Custom size calculation is not supported.  Max capacity is simply the count
 of items in the cache.
 
 ```js
-const TTLCache = require('ttlcache')
+const TTLCache = require('@isaacs/ttlcache')
 const cache = new TTLCache({ max: 10000, ttl: 1000 })
 
 // set some value
@@ -44,19 +44,37 @@ cache.get(1) // returns undefined
 cache.has(1) // returns false
 ```
 
+## Caveat Regarding Timers and Graceful Exits
+
+On Node.js, this module uses the `Timeout.unref()` method to
+prevent its internal `setTimeout` calls from keeping the process
+running indefinitely.  However, on other systems such as Deno,
+where the `setTimeout` method does not return an object with an
+`unref()` method, the process will stay open as long as any
+unexpired entry exists in the cache.
+
+You may delete all entries (by using `cache.clear()` or
+`cache.delete(key)` with every key) in order to clear the
+timeouts and allow the process to exit normally.
+
 ## 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 })`
+### `new TTLCache({ ttl, max = Infinty, updateAgeOnGet = false, noUpdateTTL = false, noDisposeOnSet = false })`
 
 Create a new `TTLCache` object.
 
-* `max` The max number of items to keep in the cache.
+* `max` The max number of items to keep in the cache.  Must be
+  positive integer or `Infinity`, defaults to `Infinity` (ie,
+  limited only by TTL, not by item count).
 * `ttl` The max time in ms to store items.  Overridable on the `set()`
-  method.
+  method.  Must be a positive integer or `Infinity` (see note
+  below about immortality hazards).  If `undefined` in
+  constructor, then a TTL _must_ be provided in each `set()`
+  call.
 * `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
@@ -104,6 +122,13 @@ 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.
 
+Note that using `updateAgeOnGet` _can_ effectively simulate a
+"least-recently-used" type of algorithm, by repeatedly updating
+the TTL of items as they are used.  However, if you find yourself
+doing this, consider using
+[`lru-cache`](http://npm.im/lru-cache), as it is much more
+optimized for an LRU use case.
+
 ### `cache.getRemainingTTL(key)`
 
 Return the remaining time before an item expires.  Returns `0` if the item
@@ -188,3 +213,17 @@ 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.
+
+## Immortality Hazards
+
+It is possible to set a TTL of `Infinity`, in which case an item
+will never expire.  As it does not expire, its TTL is not
+tracked, and `getRemainingTTL()` will return `Infinity` for that
+key.
+
+If you do this, then the item will never be purged.  Create
+enough immortal values, and the cache will grow to consume all
+available memory.  If find yourself doing this, it's _probably_
+better to use a different data structure, such as a `Map` or
+plain old object to store values, as it will have better
+performance and the hazards will be more obvious.

package/index.d.ts

@@ -4,7 +4,7 @@
 // https://github.com/isaacs/node-lru-cache/blob/v7.10.1/index.d.ts
 
 declare class TTLCache<K, V> implements Iterable<[K, V]> {
-  constructor(options: TTLCache.Options<K, V>)
+  constructor(options?: TTLCache.Options<K, V>)
 
   /**
    * The total number of items held in the cache at the current moment.
@@ -104,9 +104,10 @@ declare namespace TTLCache {
      * by default, and MAY live in the cache, contributing to max,
      * long after they have expired.
      *
-     * Must be an integer number of ms, defaults to 0, which means "no TTL"
+     * Must be an integer number of ms, or Infinity.  Defaults to `undefined`,
+     * meaning that a TTL must be set explicitly for each set()
      */
-    ttl: number
+    ttl?: number
 
     /**
      * Boolean flag to tell the cache to not update the TTL when
@@ -134,6 +135,13 @@ declare namespace TTLCache {
      */
     updateAgeOnGet?: boolean
 
+    /**
+     * Do not call dispose() function when overwriting a key with a new value
+     *
+     * @default false
+     */
+    noDisposeOnSet?: boolean
+
     /**
      * Function that is called on items when they are dropped from the cache.
      * This can be handy if you want to close file descriptors or do other
@@ -148,19 +156,26 @@ declare namespace TTLCache {
 
   type SetOptions = {
     /**
-     * Set to true to suppress calling the dispose() function if the entry
-     * key is still accessible within the cache.
-     *
-     * @default false
+     * Do not call dispose() function when overwriting a key with a new value
+     * Overrides the value set in the constructor.
      */
     noDisposeOnSet?: boolean
+
+    /**
+     * Do not update the TTL when overwriting an existing item.
+     */
     noUpdateTTL?: boolean
+
+    /**
+     * Override the default TTL for this one set() operation.
+     * Required if a TTL was not set in the constructor options.
+     */
     ttl?: number
   }
 
   type GetOptions = {
     /**
-     * Update the age of items
+     * Update the age of item being retrieved.
      */
     updateAgeOnGet?: boolean
 

package/index.js

@@ -3,15 +3,15 @@
 // 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 perf =
+  typeof performance === 'object' &&
+  performance &&
+  typeof performance.now === 'function'
+    ? performance
+    : Date
+const now = () => perf.now()
 const isPosInt = n => n && n === Math.floor(n) && n > 0 && isFinite(n)
+const isPosIntOrInf = n => n === Infinity || isPosInt(n)
 
 class TTLCache {
   constructor({
@@ -20,43 +20,62 @@ class TTLCache {
     updateAgeOnGet = false,
     noUpdateTTL = false,
     dispose,
-  }) {
+    noDisposeOnSet = false,
+  } = {}) {
     // {[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 (ttl !== undefined && !isPosIntOrInf(ttl)) {
+      throw new TypeError(
+        'ttl must be positive integer or Infinity if set'
+      )
     }
-    if (!isPosInt(max) && max !== Infinity) {
+    if (!isPosIntOrInf(max)) {
       throw new TypeError('max must be positive integer or Infinity')
     }
     this.ttl = ttl
     this.max = max
     this.updateAgeOnGet = updateAgeOnGet
     this.noUpdateTTL = noUpdateTTL
+    this.noDisposeOnSet = noDisposeOnSet
     if (dispose !== undefined) {
       if (typeof dispose !== 'function') {
         throw new TypeError('dispose must be function if set')
       }
       this.dispose = dispose
     }
+
+    this.timers = new Set()
+  }
+
+  // hang onto the timer so we can clearTimeout if all items
+  // are deleted.  Deno doesn't have Timer.unref(), so it
+  // hangs otherwise.
+  cancelTimers() {
+    for (const t of this.timers) {
+      clearTimeout(t)
+      this.timers.delete(t)
+    }
   }
 
+
   clear() {
     const entries =
       this.dispose !== TTLCache.prototype.dispose ? [...this] : []
     this.data.clear()
     this.expirationMap.clear()
+    // no need for any purging now
+    this.cancelTimers()
     this.expirations = Object.create(null)
     for (const [key, val] of entries) {
       this.dispose(val, key, 'delete')
     }
   }
 
-  setTTL (key, ttl = this.ttl) {
+  setTTL(key, ttl = this.ttl) {
     const current = this.expirationMap.get(key)
     if (current !== undefined) {
       // remove from the expirations list, so it isn't purged
@@ -68,15 +87,23 @@ class TTLCache {
       }
     }
 
-    const expiration = Math.floor(now() + ttl)
-    this.expirationMap.set(key, expiration)
-    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] = []
+    if (ttl !== Infinity) {
+      const expiration = Math.floor(now() + ttl)
+      this.expirationMap.set(key, expiration)
+      if (!this.expirations[expiration]) {
+        const t = setTimeout(() => {
+          this.timers.delete(t)
+          this.purgeStale()
+        }, ttl)
+        /* istanbul ignore else - affordance for non-node envs */
+        if (t.unref) t.unref()
+        this.timers.add(t)
+        this.expirations[expiration] = []
+      }
+      this.expirations[expiration].push(key)
+    } else {
+      this.expirationMap.set(key, Infinity)
     }
-    this.expirations[expiration].push(key)
   }
 
   set(
@@ -88,8 +115,8 @@ class TTLCache {
       noDisposeOnSet = this.noDisposeOnSet,
     } = {}
   ) {
-    if (!isPosInt(ttl)) {
-      throw new TypeError('ttl must be positive integer')
+    if (!isPosIntOrInf(ttl)) {
+      throw new TypeError('ttl must be positive integer or Infinity')
     }
     if (this.expirationMap.has(key)) {
       if (!noUpdateTTL) {
@@ -121,7 +148,9 @@ class TTLCache {
 
   getRemainingTTL(key) {
     const expiration = this.expirationMap.get(key)
-    return expiration !== undefined
+    return expiration === Infinity
+      ? expiration
+      : expiration !== undefined
       ? Math.max(0, Math.ceil(expiration - now()))
       : 0
   }
@@ -146,12 +175,17 @@ class TTLCache {
       this.data.delete(key)
       this.expirationMap.delete(key)
       const exp = this.expirations[current]
-      if (exp && exp.length <= 1) {
-        delete this.expirations[current]
-      } else {
-        this.expirations[current] = exp.filter(k => k !== key)
+      if (exp) {
+        if (exp.length <= 1) {
+          delete this.expirations[current]
+        } else {
+          this.expirations[current] = exp.filter(k => k !== key)
+        }
       }
       this.dispose(value, key, 'delete')
+      if (this.size === 0) {
+        this.cancelTimers()
+      }
       return true
     }
     return false
@@ -161,23 +195,29 @@ class TTLCache {
     for (const exp in this.expirations) {
       const keys = this.expirations[exp]
       if (this.size - keys.length >= this.max) {
+        delete this.expirations[exp]
+        const entries = []
         for (const key of keys) {
-          const val = this.data.get(key)
+          entries.push([key, this.data.get(key)])
           this.data.delete(key)
           this.expirationMap.delete(key)
+        }
+        for (const [key, val] of entries) {
           this.dispose(val, key, 'evict')
         }
-        delete this.expirations[exp]
       } else {
         const s = this.size - this.max
+        const entries = []
         for (const key of keys.splice(0, s)) {
-          const val = this.data.get(key)
+          entries.push([key, this.data.get(key)])
           this.data.delete(key)
           this.expirationMap.delete(key)
+        }
+        for (const [key, val] of entries) {
           this.dispose(val, key, 'evict')
         }
+        return
       }
-      return
     }
   }
 
@@ -188,16 +228,23 @@ class TTLCache {
   purgeStale() {
     const n = Math.ceil(now())
     for (const exp in this.expirations) {
-      if (exp > n) {
+      if (exp === 'Infinity' || exp > n) {
         return
       }
-      for (const key of this.expirations[exp]) {
-        const val = this.data.get(key)
+      const keys = [...this.expirations[exp]]
+      const entries = []
+      delete this.expirations[exp]
+      for (const key of keys) {
+        entries.push([key, this.data.get(key)])
         this.data.delete(key)
         this.expirationMap.delete(key)
+      }
+      for (const [key, val] of entries) {
         this.dispose(val, key, 'stale')
       }
-      delete this.expirations[exp]
+    }
+    if (this.size === 0) {
+      this.cancelTimers()
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isaacs/ttlcache",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "files": [
     "index.js",
     "index.d.ts"