@isaacs/ttlcache 1.0.4 → 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

@@ -0,0 +1,184 @@
+// Type definitions for ttlcache 1.0.0
+// Project: https://github.com/isaacs/ttlcache
+// Loosely based on @isaacs/lru-cache
+// 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>)
+
+  /**
+   * The total number of items held in the cache at the current moment.
+   */
+  public readonly size: number
+
+  /**
+   * Add a value to the cache.
+   */
+  public set(key: K, value: V, options?: TTLCache.SetOptions): this
+
+  /**
+   * Return a value from the cache.
+   * If the key is not found, `get()` will return `undefined`.
+   * This can be confusing when setting values specifically to `undefined`,
+   * as in `cache.set(key, undefined)`. Use `cache.has()` to determine
+   * whether a key is present in the cache at all.
+   */
+  public get<T = V>(
+    key: K,
+    options?: TTLCache.GetOptions
+  ): T | undefined
+
+  /**
+   * Check if a key is in the cache.
+   * Will return false if the item is stale, even though it is technically
+   * in the cache.
+   */
+  public has(key: K): boolean
+
+  /**
+   * Deletes a key out of the cache.
+   * Returns true if the key was deleted, false otherwise.
+   */
+  public delete(key: K): boolean
+
+  /**
+   * Clear the cache entirely, throwing away all values.
+   */
+  public clear(): void
+
+  /**
+   * Delete any stale entries. Returns true if anything was removed, false
+   * otherwise.
+   */
+  public purgeStale(): boolean
+
+  /**
+   * Return the remaining time before an item expires.
+   * Returns 0 if the item is not found in the cache or is already expired.
+   */
+  public getRemainingTTL(key: K): number
+
+  /**
+   * Set the ttl explicitly to a value, defaulting to the TTL set on the ctor
+   */
+  public setTTL(key: K, ttl?: number): void
+
+  /**
+   * Return a generator yielding `[key, value]` pairs, from soonest expiring
+   * to latest expiring. (Items expiring at the same time are walked in insertion order.)
+   */
+  public entries(): Generator<[K, V]>
+
+  /**
+   * Return a generator yielding the keys in the cache,
+   * from soonest expiring to latest expiring.
+   */
+  public keys(): Generator<K>
+
+  /**
+   * Return a generator yielding the values in the cache,
+   * from soonest expiring to latest expiring.
+   */
+  public values(): Generator<V>
+
+  /**
+   * Iterating over the cache itself yields the same results as
+   * `cache.entries()`
+   */
+  public [Symbol.iterator](): Iterator<[K, V]>
+}
+
+declare namespace TTLCache {
+  type DisposeReason = 'evict' | 'set' | 'delete'
+
+  type Disposer<K, V> = (
+    value: V,
+    key: K,
+    reason: DisposeReason
+  ) => void
+
+  type TTLOptions = {
+    /**
+     * Max time in milliseconds for items to live in cache before they are
+     * considered stale.  Note that stale items are NOT preemptively removed
+     * by default, and MAY live in the cache, contributing to max,
+     * long after they have expired.
+     *
+     * 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
+
+    /**
+     * Boolean flag to tell the cache to not update the TTL when
+     * setting a new value for an existing key (ie, when updating a value
+     * rather than inserting a new value).  Note that the TTL value is
+     * _always_ set when adding a new entry into the cache.
+     *
+     * @default false
+     */
+    noUpdateTTL?: boolean
+  }
+
+  type Options<K, V> = {
+    /**
+     * The number of items to keep.
+     *
+     * @default Infinity
+     */
+    max?: number
+
+    /**
+     * Update the age of items on cache.get(), renewing their TTL
+     *
+     * @default false
+     */
+    updateAgeOnGet?: 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
+     * cleanup tasks when items are no longer accessible. Called with `key,
+     * value`.  It's called before actually removing the item from the
+     * internal cache, so it is *NOT* safe to re-add them.
+     * Use `disposeAfter` if you wish to dispose items after they have been
+     * full removed, when it is safe to add them back to the cache.
+     */
+    dispose?: Disposer<K, V>
+  } & TTLOptions
+
+  type SetOptions = {
+    /**
+     * Set to true to suppress calling the dispose() function if the entry
+     * key is still accessible within the cache.
+     *
+     * @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 item being retrieved.
+     */
+    updateAgeOnGet?: boolean
+
+    /**
+     * Set new TTL, applied only when `updateAgeOnGet` is true
+     */
+    ttl?: number
+  }
+}
+
+export = TTLCache

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,6 +60,33 @@ class TTLCache {
     }
   }
 
+  setTTL(key, ttl = this.ttl) {
+    const current = this.expirationMap.get(key)
+    if (current !== undefined) {
+      // remove from the expirations list, so it isn't purged
+      const exp = this.expirations[current]
+      if (!exp || exp.length <= 1) {
+        delete this.expirations[current]
+      } else {
+        this.expirations[current] = exp.filter(k => k !== key)
+      }
+    }
+
+    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)
+    }
+  }
+
   set(
     key,
     val,
@@ -65,52 +96,30 @@ 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')
     }
-    const current = this.expirationMap.get(key)
-    const time = now()
-    const oldValue =
-      current === undefined ? undefined : this.data.get(key)
-    if (current !== undefined) {
-      // we aren't updating the ttl, so just set the data
-      if (noUpdateTTL && current > time) {
-        if (oldValue !== val) {
-          this.data.set(key, val)
-          if (!noDisposeOnSet) {
-            this.dispose(oldValue, key, 'set')
-          }
-        }
-        return this
-      } else {
-        // just delete from expirations list, since we're about to
-        // add to data and expirationsMap anyway
-        const exp = this.expirations[current]
-        if (!exp || exp.length <= 1) {
-          delete this.expirations[current]
-        } else {
-          this.expirations[current] = exp.filter(k => k !== key)
+    if (this.expirationMap.has(key)) {
+      if (!noUpdateTTL) {
+        this.setTTL(key, ttl)
+      }
+      // has old value
+      const oldValue = this.data.get(key)
+      if (oldValue !== val) {
+        this.data.set(key, val)
+        if (!noDisposeOnSet) {
+          this.dispose(oldValue, key, 'set')
         }
       }
+    } else {
+      this.setTTL(key, ttl)
+      this.data.set(key, val)
     }
-    const expiration = Math.ceil(time + ttl)
-    this.expirationMap.set(key, expiration)
-    this.data.set(key, val)
-    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)
 
     while (this.size > this.max) {
       this.purgeToCapacity()
     }
 
-    if (!noDisposeOnSet && current && oldValue !== val) {
-      this.dispose(oldValue, key, 'set')
-    }
     return this
   }
 
@@ -120,8 +129,10 @@ class TTLCache {
 
   getRemainingTTL(key) {
     const expiration = this.expirationMap.get(key)
-    return expiration !== undefined
-      ? Math.max(0, expiration - now())
+    return expiration === Infinity
+      ? expiration
+      : expiration !== undefined
+      ? Math.max(0, Math.ceil(expiration - now()))
       : 0
   }
 
@@ -131,11 +142,7 @@ class TTLCache {
   ) {
     const val = this.data.get(key)
     if (updateAgeOnGet) {
-      this.set(key, val, {
-        noUpdateTTL: false,
-        noDisposeOnSet: true,
-        ttl,
-      })
+      this.setTTL(key, ttl)
     }
     return val
   }
@@ -189,9 +196,9 @@ class TTLCache {
   }
 
   purgeStale() {
-    const n = now()
+    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,8 +1,9 @@
 {
   "name": "@isaacs/ttlcache",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "files": [
-    "index.js"
+    "index.js",
+    "index.d.ts"
   ],
   "main": "index.js",
   "exports": {
@@ -28,7 +29,8 @@
     "clock-mock": "^1.0.6",
     "prettier": "^2.7.0",
     "tap": "^16.0.1",
-    "ts-node": "^10.8.1"
+    "ts-node": "^10.8.1",
+    "typescript": "^4.7.3"
   },
   "engines": {
     "node": ">=12"