CHANGELOG.md

@@ -89,6 +89,9 @@ well.
 * `max` and `maxSize` are now two separate options.  (Previously, they were
   a single `max` option, which would be based on either count or computed
   size.)
+* The function assigned to the `dispose` option is now expected to have signature
+  `(value, key, reason)` rather than `(key, value)`, reversing the order of
+  `value` and `key`.
 
 ## v6 - 2020-07
 

README.md

@@ -67,7 +67,7 @@ const options = {
 
   // async method to use for cache.fetch(), for
   // stale-while-revalidate type of behavior
-  fetch: async (key, staleValue, { options, signal }) => {}
+  fetchMethod: async (key, staleValue, { options, signal }) => {}
 }
 
 const cache = new LRU(options)
@@ -391,15 +391,19 @@ moment.
 
 The total size of items in cache when using size tracking.
 
-### `set(key, value, [{ size, sizeCalculation, ttl,
-noDisposeOnSet }])`
+### `set(key, value, [{ size, sizeCalculation, ttl, noDisposeOnSet, start }])`
 
 Add a value to the cache.
 
 Optional options object may contain `ttl` and `sizeCalculation`
 as described above, which default to the settings on the cache
 object.
 
+If `start` is provided, then that will set the effective start
+time for the TTL calculation.  Note that this must be a previous
+value of `performance.now()` if supported, or a previous value of
+`Date.now()` if not.
+
 Options object my also include `size`, which will prevent calling
 the `sizeCalculation` function and just use the specified number
 if it is a positive integer, and `noDisposeOnSet` which will
@@ -518,6 +522,12 @@ the item found.
 Return an array of `[key, entry]` objects which can be passed to
 `cache.load()`
 
+The `start` fields are calculated relative to a portable
+`Date.now()` timestamp, even if `performance.now()` is available.
+
+Stale entries are always included in the `dump`, even if
+`allowStale` is false.
+
 Note: this returns an actual array, not a generator, so it can be
 more easily passed around.
 
@@ -527,6 +537,10 @@ Reset the cache and load in the items in `entries` in the order
 listed.  Note that the shape of the resulting cache may be
 different if the same options are not used in both caches.
 
+The `start` fields are assumed to be calculated relative to a
+portable `Date.now()` timestamp, even if `performance.now()` is
+available.
+
 ### `purgeStale()`
 
 Delete any stale entries.  Returns `true` if anything was

index.d.ts

@@ -500,6 +500,7 @@ declare namespace LRUCache {
     size?: number
     sizeCalculation?: SizeCalculator<K, V>
     ttl?: number
+    start?: number
     noDisposeOnSet?: boolean
     noUpdateTTL?: boolean
   }
@@ -555,6 +556,7 @@ declare namespace LRUCache {
     value: V
     ttl?: number
     size?: number
+    start?: number
   }
 }
 

index.js

@@ -285,8 +285,8 @@ class LRUCache {
     this.ttls = new ZeroArray(this.max)
     this.starts = new ZeroArray(this.max)
 
-    this.setItemTTL = (index, ttl) => {
-      this.starts[index] = ttl !== 0 ? perf.now() : 0
+    this.setItemTTL = (index, ttl, start = perf.now()) => {
+      this.starts[index] = ttl !== 0 ? start : 0
       this.ttls[index] = ttl
       if (ttl !== 0 && this.ttlAutopurge) {
         const t = setTimeout(() => {
@@ -346,7 +346,7 @@ class LRUCache {
     }
   }
   updateItemAge(index) {}
-  setItemTTL(index, ttl) {}
+  setItemTTL(index, ttl, start) {}
   isStale(index) {
     return false
   }
@@ -510,12 +510,17 @@ class LRUCache {
 
   dump() {
     const arr = []
-    for (const i of this.indexes()) {
+    for (const i of this.indexes({ allowStale: true })) {
       const key = this.keyList[i]
-      const value = this.valList[i]
+      const v = this.valList[i]
+      const value = this.isBackgroundFetch(v) ? v.__staleWhileFetching : v
       const entry = { value }
       if (this.ttls) {
         entry.ttl = this.ttls[i]
+        // always dump the start relative to a portable timestamp
+        // it's ok for this to be a bit slow, it's a rare operation.
+        const age = perf.now() - this.starts[i]
+        entry.start = Math.floor(Date.now() - age)
       }
       if (this.sizes) {
         entry.size = this.sizes[i]
@@ -528,6 +533,13 @@ class LRUCache {
   load(arr) {
     this.clear()
     for (const [key, entry] of arr) {
+      if (entry.start) {
+        // entry.start is a portable timestamp, but we may be using
+        // node's performance.now(), so calculate the offset.
+        // it's ok for this to be a bit slow, it's a rare operation.
+        const age = Date.now() - entry.start
+        entry.start = perf.now() - age
+      }
       this.set(key, entry.value, entry)
     }
   }
@@ -539,6 +551,7 @@ class LRUCache {
     v,
     {
       ttl = this.ttl,
+      start,
       noDisposeOnSet = this.noDisposeOnSet,
       size = 0,
       sizeCalculation = this.sizeCalculation,
@@ -583,7 +596,7 @@ class LRUCache {
       this.initializeTTLTracking()
     }
     if (!noUpdateTTL) {
-      this.setItemTTL(index, ttl)
+      this.setItemTTL(index, ttl, start)
     }
     if (this.disposeAfter) {
       while (this.disposed.length) {

package.json

@@ -1,7 +1,7 @@
 {
   "name": "lru-cache",
   "description": "A cache object that deletes the least-recently-used items.",
-  "version": "7.10.2",
+  "version": "7.10.3",
   "author": "Isaac Z. Schlueter <i@izs.me>",
   "keywords": [
     "mru",

tap-snapshots/test/fetch.ts.test.cjs

@@ -0,0 +1,10 @@
+/* IMPORTANT
+ * This snapshot file is auto-generated, but designed for humans.
+ * It should be checked into source control and tracked carefully.
+ * Re-generate by setting TAP_SNAPSHOT=1 and running tests.
+ * Make sure to inspect the output below.  Do not ignore changes!
+ */
+'use strict'
+exports[`test/fetch.ts TAP asynchronous fetching > safe to stringify dump 1`] = `
+[["key",{"value":1,"ttl":5,"start":11}]]
+`

tap-snapshots/test/map-like.ts.test.cjs

@@ -51,6 +51,7 @@ Array [
     3,
     Object {
       "size": 1,
+      "start": 0,
       "ttl": 0,
       "value": "3",
     },
@@ -59,6 +60,7 @@ Array [
     5,
     Object {
       "size": 1,
+      "start": 0,
       "ttl": 0,
       "value": "5",
     },
@@ -67,6 +69,7 @@ Array [
     6,
     Object {
       "size": 1,
+      "start": 0,
       "ttl": 0,
       "value": "6",
     },
@@ -75,10 +78,20 @@ Array [
     4,
     Object {
       "size": 1,
+      "start": 0,
       "ttl": 0,
       "value": "new value 4",
     },
   ],
+  Array [
+    7,
+    Object {
+      "size": 1,
+      "start": -10000,
+      "ttl": 1,
+      "value": "stale",
+    },
+  ],
 ]
 `
 

tap-snapshots/test/ttl.ts.test.cjs

@@ -0,0 +1,48 @@
+/* IMPORTANT
+ * This snapshot file is auto-generated, but designed for humans.
+ * It should be checked into source control and tracked carefully.
+ * Re-generate by setting TAP_SNAPSHOT=1 and running tests.
+ * Make sure to inspect the output below.  Do not ignore changes!
+ */
+'use strict'
+exports[`test/ttl.ts TAP tests using Date.now() set item pre-stale > dump with stale values 1`] = `
+Array [
+  Array [
+    1,
+    Object {
+      "start": 3010,
+      "ttl": 10,
+      "value": 1,
+    },
+  ],
+  Array [
+    2,
+    Object {
+      "start": 2999,
+      "ttl": 10,
+      "value": 2,
+    },
+  ],
+]
+`
+
+exports[`test/ttl.ts TAP tests with perf_hooks.performance.now() set item pre-stale > dump with stale values 1`] = `
+Array [
+  Array [
+    1,
+    Object {
+      "start": 1505,
+      "ttl": 10,
+      "value": 1,
+    },
+  ],
+  Array [
+    2,
+    Object {
+      "start": 1494,
+      "ttl": 10,
+      "value": 2,
+    },
+  ],
+]
+`

test/fetch.ts

@@ -59,6 +59,14 @@ t.test('asynchronous fetching', async t => {
   )
   const e = expose(c)
   const v = e.valList[0]
+
+  // should not have any promises or cycles in the dump
+  const dump = c.dump()
+  for (const [_, entry] of dump) {
+    t.type(entry.value, 'number')
+  }
+  t.matchSnapshot(JSON.stringify(dump), 'safe to stringify dump')
+
   t.equal(e.isBackgroundFetch(v), true)
   t.equal(e.backgroundFetch('key', 0), v)
   await v

test/map-like.ts

@@ -1,7 +1,15 @@
-if (typeof performance === 'undefined') {
+if (typeof global.performance === 'undefined') {
   global.performance = require('perf_hooks').performance
 }
 import t from 'tap'
+const Clock = require('clock-mock')
+const clock = new Clock()
+const { performance, Date } = global
+// @ts-ignore
+t.teardown(() => Object.assign(global, { performance, Date }))
+global.Date = clock.Date
+global.performance = clock
+
 import LRU from '../'
 import { expose } from './fixtures/expose'
 
@@ -40,7 +48,7 @@ t.matchSnapshot(c.dump(), 'dump, new value 4')
 c.set(7, 'stale', { ttl: 1, size: 1 })
 const e = expose(c)
 const idx = e.keyMap.get(7)
-e.starts[idx as number] = performance.now() - 10000
+e.starts[idx as number] = clock.now() - 10000
 const seen: number[] = []
 for (const i of e.indexes()) {
   seen[i] = seen[i] || 0

test/ttl.ts

@@ -398,13 +398,38 @@ const runTests = (LRU: typeof LRUCache, t: Tap.Test) => {
     t.end()
   })
 
+  t.test('set item pre-stale', t => {
+    const c = new LRU({
+      max: 3,
+      ttl: 10,
+      allowStale: true,
+    })
+    c.set(1, 1)
+    t.equal(c.has(1), true)
+    t.equal(c.get(1), 1)
+    c.set(2, 2, { start: clock.now() - 11 })
+    t.equal(c.has(2), false)
+    t.equal(c.get(2), 2)
+    t.equal(c.get(2), undefined)
+    c.set(2, 2, { start: clock.now() - 11 })
+    const dump = c.dump()
+    t.matchSnapshot(dump, 'dump with stale values')
+    const d = new LRU({ max: 3, ttl: 10, allowStale: true })
+    d.load(dump)
+    t.equal(d.has(2), false)
+    t.equal(d.get(2), 2)
+    t.equal(d.get(2), undefined)
+    t.end()
+  })
+
   t.end()
 }
 
 t.test('tests with perf_hooks.performance.now()', t => {
-  const { performance } = global
+  const { performance, Date } = global
   // @ts-ignore
-  t.teardown(() => (global.performance = performance))
+  t.teardown(() => Object.assign(global, { performance, Date }))
+  global.Date = clock.Date
   global.performance = clock
   const LRU = t.mock('../', {})
   runTests(LRU, t)