feat: add support for traceIds

Author: Xiphe

README.md

@@ -233,6 +233,11 @@ interface CachifiedOptions<Value> {
    * Default: `undefined`
    */
   waitUntil?: (promise: Promise<unknown>) => void;
+  /**
+   * Trace ID for debugging, is stored along cache metadata and can be accessed
+   * in `getFreshValue` and reporter
+   */
+  traceId?: any;
 }
 ```
 

src/cachified.spec.ts

@@ -35,6 +35,10 @@ function ignoreNode14<T>(callback: () => T) {
   return callback();
 }
 
+const anyMetadata = expect.objectContaining({
+  createdTime: expect.any(Number),
+} satisfies CacheMetadata);
+
 let currentTime = 0;
 beforeEach(() => {
   currentTime = 0;
@@ -1423,7 +1427,7 @@ describe('cachified', () => {
 
     expect(values).toEqual(['value-1', 'YOLO!', 'value-3']);
     expect(getValues).toHaveBeenCalledTimes(1);
-    expect(getValues).toHaveBeenCalledWith([1, 3]);
+    expect(getValues).toHaveBeenCalledWith([1, 3], [anyMetadata, anyMetadata]);
   });
 
   it('rejects all values when batch get fails', async () => {
@@ -1469,7 +1473,10 @@ describe('cachified', () => {
 
     expect(await valuesP).toEqual(['value-1', 'value-seven']);
     expect(getValues).toHaveBeenCalledTimes(1);
-    expect(getValues).toHaveBeenCalledWith([1, 'seven']);
+    expect(getValues).toHaveBeenCalledWith(
+      [1, 'seven'],
+      [anyMetadata, anyMetadata],
+    );
   });
 
   it('can edit metadata for single batch values', async () => {
@@ -1670,6 +1677,65 @@ describe('cachified', () => {
 
     expect(value).toBe('ONE');
   });
+
+  it('supports trace ids', async () => {
+    expect.assertions(6);
+
+    const cache = new Map<string, CacheEntry>();
+    const traceId1 = Symbol();
+    const d = new Deferred<string>();
+
+    const value = cachified({
+      cache,
+      key: 'test-1',
+      ttl: 200,
+      traceId: traceId1,
+      async getFreshValue({ metadata: { traceId } }) {
+        // in getFreshValue
+        expect(traceId).toBe(traceId1);
+        return d.promise;
+      },
+    });
+    await delay(0);
+
+    d.resolve('ONE');
+    expect(await value).toBe('ONE');
+
+    // on cache entry
+    expect(cache.get('test-1')?.metadata.traceId).toBe(traceId1);
+
+    const traceId2 = 'some-string-id';
+
+    // in batch getFreshValues
+    const batch = createBatch((freshIndexes, metadata) => {
+      expect(metadata[0].traceId).toBe(traceId2);
+      return freshIndexes.map((i) => `value-${i}`);
+    });
+
+    const createReporter = jest.fn(() => () => {});
+
+    await cachified(
+      {
+        cache,
+        key: 'test-2',
+        ttl: 200,
+        traceId: traceId2,
+        getFreshValue: batch.add(1),
+      },
+      createReporter,
+    );
+
+    expect(cache.get('test-2')?.metadata.traceId).toBe(traceId2);
+
+    expect(createReporter).toHaveBeenCalledWith(
+      expect.objectContaining({
+        traceId: traceId2,
+        metadata: expect.objectContaining({
+          traceId: traceId2,
+        }),
+      }),
+    );
+  });
 });
 
 function createReporter() {

src/cachified.ts

@@ -2,7 +2,6 @@ import {
   CachifiedOptions,
   CachifiedOptionsWithSchema,
   Cache,
-  CacheEntry,
   createContext,
   HANDLE,
 } from './common';
@@ -16,6 +15,16 @@ import { isExpired } from './isExpired';
 // Keys are unique per cache but may be used by multiple caches
 const pendingValuesByCache = new WeakMap<Cache, Map<string, any>>();
 
+/**
+ * Get the internal pending values cache for a given cache
+ */
+function getPendingValuesCache(cache: Cache) {
+  if (!pendingValuesByCache.has(cache)) {
+    pendingValuesByCache.set(cache, new Map());
+  }
+  return pendingValuesByCache.get(cache)!;
+}
+
 export async function cachified<Value, InternalValue>(
   options: CachifiedOptionsWithSchema<Value, InternalValue>,
   reporter?: CreateReporter<Value>,
@@ -30,15 +39,7 @@ export async function cachified<Value>(
 ): Promise<Value> {
   const context = createContext(options, reporter);
   const { key, cache, forceFresh, report, metadata } = context;
-
-  // Register this cache
-  if (!pendingValuesByCache.has(cache)) {
-    pendingValuesByCache.set(cache, new Map());
-  }
-  const pendingValues: Map<
-    string,
-    CacheEntry<Promise<Value>> & { resolve: (value: Value) => void }
-  > = pendingValuesByCache.get(cache)!;
+  const pendingValues = getPendingValuesCache(cache);
 
   const hasPendingValue = () => {
     return pendingValues.has(key);

src/common.ts

@@ -5,6 +5,7 @@ export interface CacheMetadata {
   createdTime: number;
   ttl?: number | null;
   swr?: number | null;
+  traceId?: any;
   /** @deprecated use swr instead */
   readonly swv?: number | null;
 }
@@ -201,6 +202,11 @@ export interface CachifiedOptions<Value> {
    * Default: `undefined`
    */
   waitUntil?: (promise: Promise<unknown>) => void;
+  /**
+   * Trace ID for debugging, is stored along cache metadata and can be accessed
+   * in `getFreshValue` and reporter
+   */
+  traceId?: any;
 }
 
 /* When using a schema validator, a strongly typed getFreshValue is not required
@@ -216,12 +222,13 @@ export type CachifiedOptionsWithSchema<Value, InternalValue> = Omit<
 export interface Context<Value>
   extends Omit<
     Required<CachifiedOptions<Value>>,
-    'fallbackToCache' | 'reporter' | 'checkValue' | 'swr'
+    'fallbackToCache' | 'reporter' | 'checkValue' | 'swr' | 'traceId'
   > {
   checkValue: CheckValue<Value>;
   report: Reporter<Value>;
   fallbackToCache: number;
   metadata: CacheMetadata;
+  traceId?: any;
 }
 
 function validateWithSchema<Value>(
@@ -277,7 +284,11 @@ export function createContext<Value>(
     staleRefreshTimeout: 0,
     forceFresh: false,
     ...options,
-    metadata: createCacheMetaData({ ttl, swr: staleWhileRevalidate }),
+    metadata: createCacheMetaData({
+      ttl,
+      swr: staleWhileRevalidate,
+      traceId: options.traceId,
+    }),
     waitUntil: options.waitUntil ?? (() => {}),
   };
 
@@ -313,11 +324,13 @@ export function createCacheMetaData({
   ttl = null,
   swr = 0,
   createdTime = Date.now(),
+  traceId,
 }: Partial<Omit<CacheMetadata, 'swv'>> = {}) {
   return {
     ttl: ttl === Infinity ? null : ttl,
     swr: swr === Infinity ? null : swr,
     createdTime,
+    ...(traceId ? { traceId } : {}),
   };
 }
 

src/createBatch.ts

@@ -1,4 +1,8 @@
-import type { GetFreshValue, GetFreshValueContext } from './common';
+import type {
+  CacheMetadata,
+  GetFreshValue,
+  GetFreshValueContext,
+} from './common';
 import { HANDLE } from './common';
 
 type OnValueCallback<Value> = (
@@ -12,20 +16,25 @@ export type AddFn<Value, Param> = (
   onValue?: OnValueCallback<Value>,
 ) => GetFreshValue<Value>;
 
+export type GetFreshValues<Value, Param> = (
+  params: Param[],
+  metadata: CacheMetadata[],
+) => Value[] | Promise<Value[]>;
+
 export function createBatch<Value, Param>(
-  getFreshValues: (params: Param[]) => Value[] | Promise<Value[]>,
+  getFreshValues: GetFreshValues<Value, Param>,
   autoSubmit: false,
 ): {
   submit: () => Promise<void>;
   add: AddFn<Value, Param>;
 };
 export function createBatch<Value, Param>(
-  getFreshValues: (params: Param[]) => Value[] | Promise<Value[]>,
+  getFreshValues: GetFreshValues<Value, Param>,
 ): {
   add: AddFn<Value, Param>;
 };
 export function createBatch<Value, Param>(
-  getFreshValues: (params: Param[]) => Value[] | Promise<Value[]>,
+  getFreshValues: GetFreshValues<Value, Param>,
   autoSubmit: boolean = true,
 ): {
   submit?: () => Promise<void>;
@@ -35,6 +44,7 @@ export function createBatch<Value, Param>(
     param: Param,
     res: (value: Value) => void,
     rej: (reason: unknown) => void,
+    metadata: CacheMetadata,
   ][] = [];
 
   let count = 0;
@@ -62,7 +72,10 @@ export function createBatch<Value, Param>(
 
     try {
       const results = await Promise.resolve(
-        getFreshValues(requests.map(([param]) => param)),
+        getFreshValues(
+          requests.map(([param]) => param),
+          requests.map((args) => args[3]),
+        ),
       );
       results.forEach((value, index) => requests[index][1](value));
       submission.resolve();
@@ -97,6 +110,7 @@ export function createBatch<Value, Param>(
                 res(value);
               },
               rej,
+              context.metadata,
             ]);
             if (!handled) {
               handled = true;