@isaacs/ttlcache 1.2.2 → 1.4.0

package/README.md

@@ -53,9 +53,9 @@ 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.
+You may call `cache.cancelTimer()` to clear the timeout and
+allow the process to exit normally. Be advised that canceling the
+timer in this way will of course prevent anything from expiring.
 
 ## API
 
@@ -63,7 +63,7 @@ timeouts and allow the process to exit normally.
 
 Default export is the `TTLCache` class.
 
-### `new TTLCache({ ttl, max = Infinty, updateAgeOnGet = false, noUpdateTTL = false, noDisposeOnSet = false })`
+### `new TTLCache({ ttl, max = Infinty, updateAgeOnGet = false, checkAgeOnGet = false, noUpdateTTL = false, noDisposeOnSet = false })`
 
 Create a new `TTLCache` object.
 
@@ -77,6 +77,11 @@ Create a new `TTLCache` object.
   call.
 * `updateAgeOnGet` Should the age of an item be updated when it is
   retrieved?  Defaults to `false`.  Overridable on the `get()` method.
+* `checkAgeOnGet` Check the TTL whenever an item is retrieved
+  with `get()`. If the item is past its ttl, but the timer has
+  not yet fired, then delete it and return undefined. By default,
+  the cache will return a value if it has one, even if it is
+  technically beyond its TTL.
 * `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
@@ -113,14 +118,18 @@ Store a value in the cache for the specified time.
 
 Returns the cache object.
 
-### `cache.get(key, {updateAgeOnGet, ttl} = {})`
+### `cache.get(key, {updateAgeOnGet, checkAgeOnGet, 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.
+If `updateAgeOnGet` is `true`, then re-add the item into the
+cache with the updated `ttl` value.  All options default to the
+settings on the constructor.
+
+If `checkAgeOnGet`, then an item will be deleted if it is found
+to be beyond its TTL, which can happen if the setTimeout timer
+has not yet fired to trigger its expiration.
 
 Note that using `updateAgeOnGet` _can_ effectively simulate a
 "least-recently-used" type of algorithm, by repeatedly updating
@@ -164,6 +173,14 @@ latest expiring.
 Return an iterator that walks through each `value` from soonest expiring to
 latest expiring.
 
+### `cache.cancelTimer()`
+
+Clear the internal timer, and stop automatically expiring items
+when their TTL expires.
+
+This allows the process to exit normally on Deno and other
+platforms that lack Node's `Timer.unref()` method.
+
 ## Internal Methods
 
 You should not ever call these, they are managed automatically.
@@ -188,6 +205,13 @@ automatically.
 Called when an item is removed from the cache and should be disposed.  Set
 this on the constructor options.
 
+### `setTimer`
+
+**Internal**
+
+Called when an with a ttl is added. This ensures that only one timer
+is setup at once. Called automatically.
+
 ## Algorithm
 
 The cache uses two `Map` objects.  The first maps item keys to their

package/index.d.ts

@@ -6,6 +6,13 @@
 declare class TTLCache<K, V> implements Iterable<[K, V]> {
   constructor(options?: TTLCache.Options<K, V>)
 
+  ttl: number
+  max: number
+  updateAgeOnGet: boolean
+  checkAgeOnGet: boolean
+  noUpdateTTL: boolean
+  noDisposeOnSet: boolean
+
   /**
    * The total number of items held in the cache at the current moment.
    */
@@ -86,6 +93,13 @@ declare class TTLCache<K, V> implements Iterable<[K, V]> {
    * `cache.entries()`
    */
   public [Symbol.iterator](): Iterator<[K, V]>
+
+  /**
+   * Cancel the timer and stop automatically expiring entries.
+   * This allows the process to gracefully exit where Timer.unref()
+   * is not available.
+   */
+  public cancelTimer(): void
 }
 
 declare namespace TTLCache {
@@ -135,6 +149,19 @@ declare namespace TTLCache {
      */
     updateAgeOnGet?: boolean
 
+    /**
+     * In the event that an item's expiration timer hasn't yet fired,
+     * and an attempt is made to get() it, then return undefined and
+     * delete it, rather than returning the cached value.
+     *
+     * By default, items are only expired when their timer fires, so there's
+     * a bit of a "best effort" expiration, and the cache will return a value
+     * if it has one, even if it's technically stale.
+     *
+     * @default false
+     */
+    checkAgeOnGet?: boolean
+
     /**
      * Do not call dispose() function when overwriting a key with a new value
      *
@@ -175,10 +202,25 @@ declare namespace TTLCache {
 
   type GetOptions = {
     /**
-     * Update the age of item being retrieved.
+     * Update the age of items on cache.get(), renewing their TTL
+     *
+     * @default false
      */
     updateAgeOnGet?: boolean
 
+    /**
+     * In the event that an item's expiration timer hasn't yet fired,
+     * and an attempt is made to get() it, then return undefined and
+     * delete it, rather than returning the cached value.
+     *
+     * By default, items are only expired when their timer fires, so there's
+     * a bit of a "best effort" expiration, and the cache will return a value
+     * if it has one, even if it's technically stale.
+     *
+     * @default false
+     */
+    checkAgeOnGet?: boolean
+
     /**
      * Set new TTL, applied only when `updateAgeOnGet` is true
      */

package/index.js

@@ -20,6 +20,7 @@ class TTLCache {
     max = Infinity,
     ttl,
     updateAgeOnGet = false,
+    checkAgeOnGet = false,
     noUpdateTTL = false,
     dispose,
     noDisposeOnSet = false,
@@ -40,9 +41,10 @@ class TTLCache {
     }
     this.ttl = ttl
     this.max = max
-    this.updateAgeOnGet = updateAgeOnGet
-    this.noUpdateTTL = noUpdateTTL
-    this.noDisposeOnSet = noDisposeOnSet
+    this.updateAgeOnGet = !!updateAgeOnGet
+    this.checkAgeOnGet = !!checkAgeOnGet
+    this.noUpdateTTL = !!noUpdateTTL
+    this.noDisposeOnSet = !!noDisposeOnSet
     if (dispose !== undefined) {
       if (typeof dispose !== 'function') {
         throw new TypeError('dispose must be function if set')
@@ -50,19 +52,56 @@ class TTLCache {
       this.dispose = dispose
     }
 
-    this.timers = new Set()
+    this.timer = undefined
+    this.timerExpiration = undefined
+  }
+
+  setTimer(expiration, ttl) {
+    if (this.timerExpiration < expiration) {
+      return
+    }
+
+    if (this.timer) {
+      clearTimeout(this.timer)
+    }
+
+    const t = setTimeout(() => {
+      this.timer = undefined
+      this.timerExpiration = undefined
+      this.purgeStale()
+      for (const exp in this.expirations) {
+        this.setTimer(exp, exp - now())
+        break
+      }
+    }, ttl)
+
+    /* istanbul ignore else - affordance for non-node envs */
+    if (t.unref) t.unref()
+
+    this.timerExpiration = expiration
+    this.timer = t
   }
 
   // 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)
+  cancelTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timerExpiration = undefined
+      this.timer = undefined
     }
   }
 
+  /* istanbul ignore next */
+  cancelTimers() {
+    process.emitWarning(
+      'TTLCache.cancelTimers has been renamed to ' +
+        'TTLCache.cancelTimer (no "s"), and will be removed in the next ' +
+        'major version update'
+    )
+    return this.cancelTimer()
+  }
 
   clear() {
     const entries =
@@ -70,7 +109,7 @@ class TTLCache {
     this.data.clear()
     this.expirationMap.clear()
     // no need for any purging now
-    this.cancelTimers()
+    this.cancelTimer()
     this.expirations = Object.create(null)
     for (const [key, val] of entries) {
       this.dispose(val, key, 'delete')
@@ -93,14 +132,8 @@ class TTLCache {
       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.setTimer(expiration, ttl)
       }
       this.expirations[expiration].push(key)
     } else {
@@ -159,9 +192,17 @@ class TTLCache {
 
   get(
     key,
-    { updateAgeOnGet = this.updateAgeOnGet, ttl = this.ttl } = {}
+    {
+      updateAgeOnGet = this.updateAgeOnGet,
+      ttl = this.ttl,
+      checkAgeOnGet = this.checkAgeOnGet,
+    } = {}
   ) {
     const val = this.data.get(key)
+    if (checkAgeOnGet && this.getRemainingTTL(key) === 0) {
+      this.delete(key)
+      return undefined
+    }
     if (updateAgeOnGet) {
       this.setTTL(key, ttl)
     }
@@ -186,7 +227,7 @@ class TTLCache {
       }
       this.dispose(value, key, 'delete')
       if (this.size === 0) {
-        this.cancelTimers()
+        this.cancelTimer()
       }
       return true
     }
@@ -246,7 +287,7 @@ class TTLCache {
       }
     }
     if (this.size === 0) {
-      this.cancelTimers()
+      this.cancelTimer()
     }
   }
 

package/package.json

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