@isaacs/ttlcache 1.0.3 → 1.1.0

package/index.d.ts

@@ -0,0 +1,174 @@
+// 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, defaults to 0, which means "no TTL"
+     */
+    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
+    noUpdateTTL?: boolean
+    ttl?: number
+  }
+
+  type GetOptions = {
+    /**
+     * Update the age of items
+     */
+    updateAgeOnGet?: boolean
+
+    /**
+     * Set new TTL, applied only when `updateAgeOnGet` is true
+     */
+    ttl?: number
+  }
+}
+
+export = TTLCache

package/index.js

@@ -3,18 +3,24 @@
 // Relies on the fact that integer Object keys are kept sorted,
 // and managed very efficiently by V8.
 
-const maybeReqPerfHooks = (fallback) => {
+const maybeReqPerfHooks = fallback => {
   try {
     return require('perf_hooks').performance
   } catch (e) {
     return fallback
   }
 }
-const {now} = maybeReqPerfHooks(Date)
+const { now } = maybeReqPerfHooks(Date)
 const isPosInt = n => n && n === Math.floor(n) && n > 0 && isFinite(n)
 
 class TTLCache {
-  constructor ({ max = Infinity, ttl, updateAgeOnGet = false, noUpdateTTL = false, dispose }) {
+  constructor({
+    max = Infinity,
+    ttl,
+    updateAgeOnGet = false,
+    noUpdateTTL = false,
+    dispose,
+  }) {
     // {[expirationTime]: [keys]}
     this.expirations = Object.create(null)
     // {key=>val}
@@ -29,8 +35,8 @@ class TTLCache {
     }
     this.ttl = ttl
     this.max = max
-    this.updateAgeOnGet = updateAgeOnGet;
-    this.noUpdateTTL = noUpdateTTL;
+    this.updateAgeOnGet = updateAgeOnGet
+    this.noUpdateTTL = noUpdateTTL
     if (dispose !== undefined) {
       if (typeof dispose !== 'function') {
         throw new TypeError('dispose must be function if set')
@@ -39,8 +45,9 @@ class TTLCache {
     }
   }
 
-  clear () {
-    const entries = this.dispose !== TTLCache.prototype.dispose ? [...this] : []
+  clear() {
+    const entries =
+      this.dispose !== TTLCache.prototype.dispose ? [...this] : []
     this.data.clear()
     this.expirationMap.clear()
     this.expirations = Object.create(null)
@@ -49,37 +56,20 @@ class TTLCache {
     }
   }
 
-  set (key, val, { ttl = this.ttl, noUpdateTTL = this.noUpdateTTL, noDisposeOnSet = this.noDisposeOnSet } = {}) {
-    if (!isPosInt(ttl)) {
-      throw new TypeError('ttl must be positive integer')
-    }
+  setTTL (key, ttl = this.ttl) {
     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
+      // 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 {
-        // 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)
-        }
+        this.expirations[current] = exp.filter(k => k !== key)
       }
     }
-    const expiration = Math.ceil(time + ttl)
+
+    const expiration = Math.floor(now() + 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 */
@@ -87,37 +77,69 @@ class TTLCache {
       this.expirations[expiration] = []
     }
     this.expirations[expiration].push(key)
+  }
+
+  set(
+    key,
+    val,
+    {
+      ttl = this.ttl,
+      noUpdateTTL = this.noUpdateTTL,
+      noDisposeOnSet = this.noDisposeOnSet,
+    } = {}
+  ) {
+    if (!isPosInt(ttl)) {
+      throw new TypeError('ttl must be positive integer')
+    }
+    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)
+    }
 
     while (this.size > this.max) {
       this.purgeToCapacity()
     }
 
-    if (!noDisposeOnSet && current && oldValue !== val) {
-      this.dispose(oldValue, key, 'set')
-    }
     return this
   }
 
-  has (key) {
+  has(key) {
     return this.data.has(key)
   }
 
-  getRemainingTTL (key) {
+  getRemainingTTL(key) {
     const expiration = this.expirationMap.get(key)
-    return expiration !== undefined ? Math.max(0, expiration - now()) : 0
+    return expiration !== undefined
+      ? Math.max(0, Math.ceil(expiration - now()))
+      : 0
   }
 
-  get (key, { updateAgeOnGet = this.updateAgeOnGet, ttl = this.ttl } = {}) {
+  get(
+    key,
+    { updateAgeOnGet = this.updateAgeOnGet, ttl = this.ttl } = {}
+  ) {
     const val = this.data.get(key)
     if (updateAgeOnGet) {
-      this.set(key, val, { noUpdateTTL: false, noDisposeOnSet: true, ttl })
+      this.setTTL(key, ttl)
     }
     return val
   }
 
-  dispose (value, key) {}
+  dispose(_, __) {}
 
-  delete (key) {
+  delete(key) {
     const current = this.expirationMap.get(key)
     if (current !== undefined) {
       const value = this.data.get(key)
@@ -135,7 +157,7 @@ class TTLCache {
     return false
   }
 
-  purgeToCapacity () {
+  purgeToCapacity() {
     for (const exp in this.expirations) {
       const keys = this.expirations[exp]
       if (this.size - keys.length >= this.max) {
@@ -159,12 +181,12 @@ class TTLCache {
     }
   }
 
-  get size () {
+  get size() {
     return this.data.size
   }
 
-  purgeStale () {
-    const n = now()
+  purgeStale() {
+    const n = Math.ceil(now())
     for (const exp in this.expirations) {
       if (exp > n) {
         return
@@ -179,28 +201,28 @@ class TTLCache {
     }
   }
 
-  *entries () {
+  *entries() {
     for (const exp in this.expirations) {
       for (const key of this.expirations[exp]) {
         yield [key, this.data.get(key)]
       }
     }
   }
-  *keys () {
+  *keys() {
     for (const exp in this.expirations) {
       for (const key of this.expirations[exp]) {
         yield key
       }
     }
   }
-  *values () {
+  *values() {
     for (const exp in this.expirations) {
       for (const key of this.expirations[exp]) {
         yield this.data.get(key)
       }
     }
   }
-  [Symbol.iterator] () {
+  [Symbol.iterator]() {
     return this.entries()
   }
 }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@isaacs/ttlcache",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "files": [
-    "index.js"
+    "index.js",
+    "index.d.ts"
   ],
   "main": "index.js",
   "exports": {
@@ -23,10 +24,36 @@
     "prepublishOnly": "git push origin --follow-tags"
   },
   "devDependencies": {
-    "clock-mock": "^1.0.4",
-    "tap": "^16.0.1"
+    "@types/node": "^17.0.42",
+    "@types/tap": "^15.0.7",
+    "clock-mock": "^1.0.6",
+    "prettier": "^2.7.0",
+    "tap": "^16.0.1",
+    "ts-node": "^10.8.1",
+    "typescript": "^4.7.3"
   },
   "engines": {
     "node": ">=12"
+  },
+  "tap": {
+    "nyc-arg": [
+      "--include=index.js"
+    ],
+    "node-arg": [
+      "--require",
+      "ts-node/register"
+    ],
+    "ts": false
+  },
+  "prettier": {
+    "semi": false,
+    "printWidth": 70,
+    "tabWidth": 2,
+    "useTabs": false,
+    "singleQuote": true,
+    "jsxSingleQuote": false,
+    "bracketSameLine": true,
+    "arrowParens": "avoid",
+    "endOfLine": "lf"
   }
 }