feat(requests-result): 🔥 Add ttl to updateRequestsCache (#477)

Add a ttl parameter to the updateRequestsCache function, allowing users
to set an expiration time for each cache record when updating multiple
keys. If a ttl value isn't provided, the cache record doesn't expire.

✅ Closes: 471

docs/docs/features/requests/requests-cache.mdx

@@ -200,8 +200,15 @@ store.update(
 );
 
 store.update(updateRequestsCache(['keyOne', 'keyTwo'], { value: 'partial' }));
+
+store.update(
+  updateRequestsCache(['keyOne', 'keyTwo'], { value: 'partial', ttl: 1000 })
+);
 ```
 
+If you pass `ttl` (time to live) when updating a cache record, that represents the time (in milliseconds) that key will
+have the value that was set (afterward, it reverts to 'none'). This parameter can be used to set individual `ttl` values for each key when updating multiple keys at once. If a `ttl` is not passed for a key, the value for that key does not expire.
+
 ### `clearRequestsCache`
 
 ```ts

packages/requests/src/lib/requests-cache.spec.ts

@@ -209,3 +209,33 @@ test('updateRequestsCache', () => {
 
   expect(store.getValue()).toMatchSnapshot();
 });
+
+test('updateRequestsCache with ttl', () => {
+  const { state, config } = createState(
+    withRequestsCache<'foo' | 'bar' | 'baz'>()
+  );
+
+  const store = new Store({ state, config, name: 'users' });
+
+  jest.useFakeTimers();
+
+  store.update(
+    updateRequestsCache(['foo', 'bar'], { value: 'partial', ttl: 1000 })
+  );
+
+  expect(
+    store.query(isRequestCached('foo', { value: 'partial' }))
+  ).toBeTruthy();
+
+  expect(
+    store.query(isRequestCached('bar', { value: 'partial' }))
+  ).toBeTruthy();
+
+  jest.advanceTimersByTime(2000);
+
+  expect(store.query(isRequestCached('foo', { value: 'partial' }))).toBeFalsy();
+
+  expect(store.query(isRequestCached('bar', { value: 'partial' }))).toBeFalsy();
+
+  jest.useRealTimers();
+});

packages/requests/src/lib/requests-cache.ts

@@ -54,10 +54,15 @@ export function selectRequestCache<S extends RequestsCacheState>(
 
 export function updateRequestsCache<S extends RequestsCacheState>(
   keys: Array<CacheRecordKeys<S>>,
-  value: CacheState
+  value: CacheState | { value: CacheState['value']; ttl?: number }
 ): Reducer<S>;
 export function updateRequestsCache<S extends RequestsCacheState>(
-  requests: Partial<Record<CacheRecordKeys<S>, CacheState>>
+  requests: Partial<
+    Record<
+      CacheRecordKeys<S>,
+      CacheState | { value: CacheState['value']; ttl?: number }
+    >
+  >
 ): Reducer<S>;
 export function updateRequestsCache<S extends RequestsCacheState>(
   requestsOrKeys: any,
@@ -67,7 +72,15 @@ export function updateRequestsCache<S extends RequestsCacheState>(
 
   if (value) {
     normalized = requestsOrKeys.reduce((acc: any, key: string) => {
-      acc[key] = value;
+      const data = {
+        value: value.value ?? 'full',
+      } as CacheState;
+
+      if (value.ttl) {
+        data.timestamp = Date.now() + value.ttl;
+      }
+
+      acc[key] = data;
 
       return acc;
     }, {});