add context to status/tracing objects

Author: isaacs

src/index.ts

@@ -267,6 +267,18 @@ export namespace LRUCache {
      */
     memo?: 'hit' | 'miss'
 
+    /**
+     * The `context` option provided to a memo or fetch operation
+     *
+     * In practice, of course, this will be the same type as the `FC`
+     * fetch context param used to instantiate the LRUCache, but the
+     * convolutions of threading that through would get quite complicated,
+     * and preclude forcing/forbidding the passing of a `context` param
+     * where it is/isn't expected, which is more valuable for error
+     * prevention.
+     */
+    context?: unknown
+
     /**
      * the ttl stored for the item, or undefined if ttls are not used.
      */
@@ -2679,6 +2691,9 @@ export class LRUCache<K extends {}, V extends {}, FC = unknown> {
     const ths = tracing.hasSubscribers
     const { status = hasSubscribers() ? {} : undefined } = fetchOptions
     fetchOptions.status = status
+    if (status && fetchOptions.context) {
+      status.context = fetchOptions.context
+    }
     const p = this.#fetch(k, fetchOptions)
     if (status && hasSubscribers()) {
       if (ths) {
@@ -2825,6 +2840,9 @@ export class LRUCache<K extends {}, V extends {}, FC = unknown> {
     const ths = tracing.hasSubscribers
     const { status = hasSubscribers() ? {} : undefined } = fetchOptions
     fetchOptions.status = status
+    if (status && fetchOptions.context) {
+      status.context = fetchOptions.context
+    }
     const p = this.#forceFetch(k, fetchOptions)
     if (status && hasSubscribers()) {
       if (ths) {
@@ -2885,6 +2903,9 @@ export class LRUCache<K extends {}, V extends {}, FC = unknown> {
     if (status) {
       status.op = 'memo'
       status.key = k
+      if (memoOptions.context) {
+        status.context = memoOptions.context
+      }
     }
     const result = this.#memo(k, memoOptions)
     if (status) status.value = result

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

@@ -316,6 +316,7 @@ Array [
     "op": "fetch",
   },
   Object {
+    "context": true,
     "fetch": "refresh",
     "fetchDispatched": true,
     "fetchResolved": true,

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

@@ -1005,6 +1005,7 @@ Array [
     "trace": true,
   },
   Object {
+    "context": true,
     "fetch": "refresh",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -1234,6 +1235,7 @@ Array [
 exports[`test/tracing.ts > TAP > test/tracing.ts > TAP > abort, but then keep on fetching anyway traces 1`] = `
 Map {
   Object {
+    "context": true,
     "fetch": "miss",
     "fetchAborted": true,
     "fetchAbortIgnored": true,
@@ -1253,6 +1255,7 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": true,
     "fetch": "miss",
     "fetchAborted": true,
     "fetchAbortIgnored": true,
@@ -1269,6 +1272,7 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": true,
     "fetch": "miss",
     "fetchAborted": true,
     "fetchAbortIgnored": true,
@@ -1285,6 +1289,7 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": true,
     "fetch": "miss",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -1299,6 +1304,7 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": true,
     "error": Error: fetch() returned undefined {
       "name": "Error",
     },
@@ -3832,6 +3838,9 @@ Array []
 exports[`test/tracing.ts > TAP > test/tracing.ts > TAP > fetch context required if set in ctor type traces 1`] = `
 Map {
   Object {
+    "context": Object {
+      "a": 1,
+    },
     "fetch": "miss",
     "fetchDispatched": true,
     "key": "x",
@@ -3852,6 +3861,9 @@ Map {
     "end",
   ],
   Object {
+    "context": Object {
+      "x": 1,
+    },
     "fetch": "miss",
     "fetchDispatched": true,
     "key": "z",
@@ -3862,6 +3874,9 @@ Map {
     "end",
   ],
   Object {
+    "context": Object {
+      "a": 1,
+    },
     "fetch": "miss",
     "fetchDispatched": true,
     "key": "x",
@@ -3891,6 +3906,9 @@ Map {
     "end",
   ],
   Object {
+    "context": Object {
+      "x": 1,
+    },
     "fetch": "miss",
     "fetchDispatched": true,
     "key": "z",
@@ -3906,6 +3924,7 @@ Map {
 exports[`test/tracing.ts > TAP > test/tracing.ts > TAP > fetch context traces 1`] = `
 Map {
   Object {
+    "context": "overridden",
     "fetch": "miss",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -3933,6 +3952,7 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": "first context",
     "fetch": "miss",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -3960,6 +3980,7 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": "ignored",
     "fetch": "hit",
     "key": "x",
     "now": 1092,
@@ -4596,12 +4617,14 @@ Array [
     "value": 10,
   },
   Object {
+    "context": 8,
     "key": "10",
     "memo": "hit",
     "op": "memo",
     "value": 10,
   },
   Object {
+    "context": 8,
     "forceRefresh": true,
     "key": "10",
     "memo": "miss",
@@ -4660,6 +4683,7 @@ Map {}
 exports[`test/tracing.ts > TAP > test/tracing.ts > TAP > forceRefresh traces 2`] = `
 Map {
   Object {
+    "context": true,
     "fetch": "hit",
     "key": 1,
     "now": 1092,
@@ -4773,6 +4797,7 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": true,
     "fetch": "refresh",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -4842,6 +4867,9 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": Object {
+      "a": 1,
+    },
     "fetch": "miss",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -4872,6 +4900,9 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": Object {
+      "x": 1,
+    },
     "fetch": "miss",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -4887,6 +4918,9 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": Object {
+      "a": 1,
+    },
     "fetch": "miss",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -4927,6 +4961,9 @@ Map {
     "asyncEnd",
   ],
   Object {
+    "context": Object {
+      "x": 1,
+    },
     "fetch": "miss",
     "fetchDispatched": true,
     "fetchResolved": true,
@@ -10367,12 +10404,14 @@ Map {
 exports[`test/tracing.ts > TAP > test/tracing.ts > TAP > with context metrics 1`] = `
 Array [
   Object {
+    "context": true,
     "key": 1,
     "memo": "miss",
     "op": "memo",
     "value": 1,
   },
   Object {
+    "context": true,
     "key": 1,
     "memo": "hit",
     "op": "memo",
@@ -10391,6 +10430,7 @@ Array [
     "value": 4,
   },
   Object {
+    "context": true,
     "key": 2,
     "memo": "hit",
     "op": "memo",

test/fetch.ts

@@ -395,7 +395,7 @@ t.test('forceRefresh', async t => {
     return status
   }
 
-  const cache = new LRU<number, number>({
+  const cache = new LRU<number, number, boolean>({
     max: 10,
     allowStale: true,
     ttl: 100,
@@ -413,33 +413,52 @@ t.test('forceRefresh', async t => {
   // put in some values that don't match what fetchMethod returns
   cache.set(1, 100)
   cache.set(2, 200)
-  t.equal(await cache.fetch(1), 100)
+  t.equal(await cache.fetch(1, { context: true }), 100)
   // still there, because we're allowing stale, and it's not stale
   const status: LRUCache.Status<number, number> = {}
   t.equal(
     await cache.fetch(2, {
       forceRefresh: true,
       allowStale: false,
       status,
+      context: false,
     }),
     2,
   )
   t.equal(status.fetch, 'refresh', 'status reflects forced refresh')
-  t.equal(await cache.fetch(1, { forceRefresh: true }), 100)
+  t.equal(
+    await cache.fetch(1, { forceRefresh: true, context: false }),
+    100,
+  )
   clock.advance(100)
-  t.equal(await cache.fetch(2, { forceRefresh: true, status: s() }), 2)
+  t.equal(
+    await cache.fetch(2, {
+      forceRefresh: true,
+      status: s(),
+      context: false,
+    }),
+    2,
+  )
   t.equal(cache.peek(1), 100)
   // if we don't allow stale though, then that means that we wait
   // for the background fetch to complete, so we get the updated value.
-  t.equal(await cache.fetch(1, { allowStale: false, status: s() }), 1)
+  t.equal(
+    await cache.fetch(1, {
+      allowStale: false,
+      context: false,
+      status: s(),
+    }),
+    1,
+  )
 
   cache.set(1, 100)
-  t.equal(await cache.fetch(1, { allowStale: false }), 100)
+  t.equal(await cache.fetch(1, { allowStale: false, context: false }), 100)
   t.equal(
     await cache.fetch(1, {
       forceRefresh: true,
       allowStale: false,
       status: s(),
+      context: true,
     }),
     1,
   )
@@ -599,7 +618,7 @@ t.test('abort, but then keep on fetching anyway', async t => {
   let aborted: Error | undefined = undefined
   let resolved: boolean = false
   let returnUndefined: boolean = false
-  const cache = new LRU<number, number>({
+  const cache = new LRU<number, number, boolean>({
     max: 10,
     ignoreFetchAbort: true,
     fetchMethod: async (k, _, { signal, options }) => {
@@ -618,7 +637,7 @@ t.test('abort, but then keep on fetching anyway', async t => {
   })
   const ac = new AbortController()
   const status: LRUCache.Status<number, number> = {}
-  const p = cache.fetch(1, { signal: ac.signal, status })
+  const p = cache.fetch(1, { signal: ac.signal, status, context: true })
   const er = new Error('ignored abort signal')
   ac.abort(er)
   clock.advance(100)
@@ -632,7 +651,7 @@ t.test('abort, but then keep on fetching anyway', async t => {
   t.equal(ac.signal.reason, er)
   t.equal(cache.get(1), 1)
 
-  const p2 = cache.forceFetch(2)
+  const p2 = cache.forceFetch(2, { context: true })
   t.equal(cache.get(2), undefined)
   cache.delete(2)
   t.equal(cache.get(2), undefined)
@@ -641,7 +660,7 @@ t.test('abort, but then keep on fetching anyway', async t => {
   t.equal(cache.get(2), undefined)
 
   // if aborted for cause, we don't save the fetched value
-  const p3 = cache.fetch(3)
+  const p3 = cache.fetch(3, { context: true })
   t.equal(cache.get(3), undefined)
   cache.set(3, 33)
   t.equal(cache.get(3), 33)
@@ -652,10 +671,10 @@ t.test('abort, but then keep on fetching anyway', async t => {
   const e = expose(cache)
   returnUndefined = true
   const before = e.valList.slice()
-  const p4 = cache.fetch(4)
+  const p4 = cache.fetch(4, { context: true })
   clock.advance(100)
   t.equal(await p4, undefined)
-  const p5 = cache.forceFetch(4)
+  const p5 = cache.forceFetch(4, { context: true })
   clock.advance(100)
   await t.rejects(p5, { message: 'fetch() returned undefined' })
   t.same(e.valList, before, 'did not update values with undefined')