@isaacs/ttlcache 1.4.1 → 2.0.0

package/index.d.ts

@@ -1,231 +0,0 @@
-// 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>)
-
-  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.
-   */
-  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]>
-
-  /**
-   * Cancel the timer and stop automatically expiring entries.
-   * This allows the process to gracefully exit where Timer.unref()
-   * is not available.
-   */
-  public cancelTimer(): void
-}
-
-declare namespace TTLCache {
-  type DisposeReason = 'evict' | 'set' | 'delete' | 'stale'
-
-  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
-
-    /**
-     * 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
-     *
-     * @default false
-     */
-    noDisposeOnSet?: 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 = {
-    /**
-     * Do not call dispose() function when overwriting a key with a new value
-     * Overrides the value set in the constructor.
-     */
-    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 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
-     */
-    ttl?: number
-  }
-}
-
-export = TTLCache

package/index.js

@@ -1,324 +0,0 @@
-// A simple TTL cache with max capacity option, ms resolution,
-// autopurge, and reasonably optimized performance
-// Relies on the fact that integer Object keys are kept sorted,
-// and managed very efficiently by V8.
-
-/* istanbul ignore next */
-const perf =
-  typeof performance === 'object' &&
-  performance &&
-  typeof performance.now === 'function'
-    ? performance
-    : Date
-
-const now = () => perf.now()
-const isPosInt = n => n && n === Math.floor(n) && n > 0 && isFinite(n)
-const isPosIntOrInf = n => n === Infinity || isPosInt(n)
-
-class TTLCache {
-  constructor({
-    max = Infinity,
-    ttl,
-    updateAgeOnGet = false,
-    checkAgeOnGet = false,
-    noUpdateTTL = false,
-    dispose,
-    noDisposeOnSet = false,
-  } = {}) {
-    // {[expirationTime]: [keys]}
-    this.expirations = Object.create(null)
-    // {key=>val}
-    this.data = new Map()
-    // {key=>expiration}
-    this.expirationMap = new Map()
-    if (ttl !== undefined && !isPosIntOrInf(ttl)) {
-      throw new TypeError(
-        'ttl must be positive integer or Infinity if set'
-      )
-    }
-    if (!isPosIntOrInf(max)) {
-      throw new TypeError('max must be positive integer or Infinity')
-    }
-    this.ttl = ttl
-    this.max = max
-    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')
-      }
-      this.dispose = dispose
-    }
-
-    this.timer = undefined
-    this.timerExpiration = undefined
-  }
-
-  setTimer(expiration, ttl) {
-    if (this.timerExpiration < expiration) {
-      return
-    }
-
-    if (this.timer) {
-      clearTimeout(this.timer)
-    }
-
-    const t = setTimeout(() => {
-      this.timer = undefined
-      this.timerExpiration = undefined
-      this.purgeStale()
-      for (const exp in this.expirations) {
-        this.setTimer(exp, exp - now())
-        break
-      }
-    }, ttl)
-
-    /* istanbul ignore else - affordance for non-node envs */
-    if (t.unref) t.unref()
-
-    this.timerExpiration = expiration
-    this.timer = t
-  }
-
-  // hang onto the timer so we can clearTimeout if all items
-  // are deleted.  Deno doesn't have Timer.unref(), so it
-  // hangs otherwise.
-  cancelTimer() {
-    if (this.timer) {
-      clearTimeout(this.timer)
-      this.timerExpiration = undefined
-      this.timer = undefined
-    }
-  }
-
-  /* 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'
-    )
-    return this.cancelTimer()
-  }
-
-  clear() {
-    const entries =
-      this.dispose !== TTLCache.prototype.dispose ? [...this] : []
-    this.data.clear()
-    this.expirationMap.clear()
-    // no need for any purging now
-    this.cancelTimer()
-    this.expirations = Object.create(null)
-    for (const [key, val] of entries) {
-      this.dispose(val, key, 'delete')
-    }
-  }
-
-  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]) {
-        this.expirations[expiration] = []
-        this.setTimer(expiration, ttl)
-      }
-      this.expirations[expiration].push(key)
-    } else {
-      this.expirationMap.set(key, Infinity)
-    }
-  }
-
-  set(
-    key,
-    val,
-    {
-      ttl = this.ttl,
-      noUpdateTTL = this.noUpdateTTL,
-      noDisposeOnSet = this.noDisposeOnSet,
-    } = {}
-  ) {
-    if (!isPosIntOrInf(ttl)) {
-      throw new TypeError('ttl must be positive integer or Infinity')
-    }
-    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()
-    }
-
-    return this
-  }
-
-  has(key) {
-    return this.data.has(key)
-  }
-
-  getRemainingTTL(key) {
-    const expiration = this.expirationMap.get(key)
-    return expiration === Infinity
-      ? expiration
-      : expiration !== undefined
-      ? Math.max(0, Math.ceil(expiration - now()))
-      : 0
-  }
-
-  get(
-    key,
-    {
-      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)
-    }
-    return val
-  }
-
-  dispose(_, __) {}
-
-  delete(key) {
-    const current = this.expirationMap.get(key)
-    if (current !== undefined) {
-      const value = this.data.get(key)
-      this.data.delete(key)
-      this.expirationMap.delete(key)
-      const exp = this.expirations[current]
-      if (exp) {
-        if (exp.length <= 1) {
-          delete this.expirations[current]
-        } else {
-          this.expirations[current] = exp.filter(k => k !== key)
-        }
-      }
-      this.dispose(value, key, 'delete')
-      if (this.size === 0) {
-        this.cancelTimer()
-      }
-      return true
-    }
-    return false
-  }
-
-  purgeToCapacity() {
-    for (const exp in this.expirations) {
-      const keys = this.expirations[exp]
-      if (this.size - keys.length >= this.max) {
-        delete this.expirations[exp]
-        const entries = []
-        for (const key of keys) {
-          entries.push([key, this.data.get(key)])
-          this.data.delete(key)
-          this.expirationMap.delete(key)
-        }
-        for (const [key, val] of entries) {
-          this.dispose(val, key, 'evict')
-        }
-      } else {
-        const s = this.size - this.max
-        const entries = []
-        for (const key of keys.splice(0, s)) {
-          entries.push([key, this.data.get(key)])
-          this.data.delete(key)
-          this.expirationMap.delete(key)
-        }
-        for (const [key, val] of entries) {
-          this.dispose(val, key, 'evict')
-        }
-        return
-      }
-    }
-  }
-
-  get size() {
-    return this.data.size
-  }
-
-  purgeStale() {
-    const n = Math.ceil(now())
-    for (const exp in this.expirations) {
-      if (exp === 'Infinity' || exp > n) {
-        return
-      }
-
-      /* istanbul ignore next
-       * mysterious need for a guard here?
-       * https://github.com/isaacs/ttlcache/issues/26 */
-      const keys = [...(this.expirations[exp] || [])]
-      const entries = []
-      delete this.expirations[exp]
-      for (const key of keys) {
-        entries.push([key, this.data.get(key)])
-        this.data.delete(key)
-        this.expirationMap.delete(key)
-      }
-      for (const [key, val] of entries) {
-        this.dispose(val, key, 'stale')
-      }
-    }
-    if (this.size === 0) {
-      this.cancelTimer()
-    }
-  }
-
-  *entries() {
-    for (const exp in this.expirations) {
-      for (const key of this.expirations[exp]) {
-        yield [key, this.data.get(key)]
-      }
-    }
-  }
-  *keys() {
-    for (const exp in this.expirations) {
-      for (const key of this.expirations[exp]) {
-        yield key
-      }
-    }
-  }
-  *values() {
-    for (const exp in this.expirations) {
-      for (const key of this.expirations[exp]) {
-        yield this.data.get(key)
-      }
-    }
-  }
-  [Symbol.iterator]() {
-    return this.entries()
-  }
-}
-
-module.exports = TTLCache