@isaacs/ttlcache 1.3.0 → 1.4.0

package/README.md

@@ -63,7 +63,7 @@ timer in this way will of course prevent anything from expiring.
 
 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

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.
    */
@@ -142,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
      *
@@ -182,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')
@@ -54,7 +56,7 @@ class TTLCache {
     this.timerExpiration = undefined
   }
 
-  setTimer (expiration, ttl) {
+  setTimer(expiration, ttl) {
     if (this.timerExpiration < expiration) {
       return
     }
@@ -93,9 +95,11 @@ class TTLCache {
 
   /* 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')
+    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()
   }
 
@@ -188,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)
     }

package/package.json

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