@isaacs/ttlcache 1.1.0 → 1.2.0

package/README.md

@@ -54,9 +54,14 @@ Default export is the `TTLCache` class.
 
 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 +109,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 +200,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
@@ -154,13 +155,22 @@ declare namespace TTLCache {
      * @default false
      */
     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

@@ -10,8 +10,10 @@ const maybeReqPerfHooks = fallback => {
     return fallback
   }
 }
-const { now } = maybeReqPerfHooks(Date)
+const timeProvider = maybeReqPerfHooks(Date)
+const now = () => timeProvider.now()
 const isPosInt = n => n && n === Math.floor(n) && n > 0 && isFinite(n)
+const isPosIntOrInf = n => n === Infinity || isPosInt(n)
 
 class TTLCache {
   constructor({
@@ -20,17 +22,19 @@ class TTLCache {
     updateAgeOnGet = false,
     noUpdateTTL = false,
     dispose,
-  }) {
+  } = {}) {
     // {[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
@@ -56,7 +60,7 @@ class TTLCache {
     }
   }
 
-  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 +72,19 @@ 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.purgeStale(), ttl)
+        /* istanbul ignore else - affordance for non-node envs */
+        if (t.unref) t.unref()
+        this.expirations[expiration] = []
+      }
+      this.expirations[expiration].push(key)
+    } else {
+      this.expirationMap.set(key, Infinity)
     }
-    this.expirations[expiration].push(key)
   }
 
   set(
@@ -88,8 +96,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 +129,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
   }
@@ -188,7 +198,7 @@ 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]) {

package/package.json

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