@isaacs/ttlcache - npm Package Compare versions

Comparing version 1.3.0 to 1.4.0

index.d.ts

@@ -9,2 +9,9 @@ // Type definitions for ttlcache 1.0.0
 
+  ttl: number
+  max: number
+  updateAgeOnGet: boolean
+  checkAgeOnGet: boolean
+  noUpdateTTL: boolean
+  noDisposeOnSet: boolean
+
   /**
@@ -147,2 +154,15 @@ * The total number of items held in the cache at the current moment.
     /**
+     * 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
@@ -187,3 +207,5 @@ *
     /**
-     * Update the age of item being retrieved.
+     * Update the age of items on cache.get(), renewing their TTL
+     *
+     * @default false
      */
@@ -193,2 +215,15 @@ 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
@@ -195,0 +230,0 @@ */

index.js

@@ -23,2 +23,3 @@ // A simple TTL cache with max capacity option, ms resolution,
     updateAgeOnGet = false,
+    checkAgeOnGet = false,
     noUpdateTTL = false,
@@ -44,5 +45,6 @@ dispose,
     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) {
@@ -59,3 +61,3 @@ if (typeof dispose !== 'function') {
 
-  setTimer (expiration, ttl) {
+  setTimer(expiration, ttl) {
     if (this.timerExpiration < expiration) {
@@ -99,5 +101,7 @@ return
   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()
@@ -195,5 +199,13 @@ }
     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) {
@@ -200,0 +212,0 @@ this.setTTL(key, ttl)

package.json

 {
   "name": "@isaacs/ttlcache",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "files": [
@@ -5,0 +5,0 @@ "index.js",

README.md

@@ -66,3 +66,3 @@ # @isaacs/ttlcache
 
-### `new TTLCache({ ttl, max = Infinty, updateAgeOnGet = false, noUpdateTTL = false, noDisposeOnSet = false })`
+### `new TTLCache({ ttl, max = Infinty, updateAgeOnGet = false, checkAgeOnGet = false, noUpdateTTL = false, noDisposeOnSet = false })`
 
@@ -81,2 +81,7 @@ Create a new `TTLCache` object.
   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
@@ -118,3 +123,3 @@ TTL unchanged?  Defaults to `false`.  Overridable on the `set()` method.
 
-### `cache.get(key, {updateAgeOnGet, ttl} = {})`
+### `cache.get(key, {updateAgeOnGet, checkAgeOnGet, ttl} = {})`
 
@@ -124,6 +129,10 @@ Get an item stored in the cache.  Returns `undefined` if the item is not in
 
-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
@@ -130,0 +139,0 @@ "least-recently-used" type of algorithm, by repeatedly updating

No alert changes

Improved metrics

Total package byte prevSize

25057

increased by8.22%

Lines of code

492

increased by9.82%

Number of lines in readme file

254

increased by3.67%

No dependency changes