feat: add isExpired helper (#122)

README.md

@@ -480,6 +480,7 @@ maintenance and testing these helpers might come handy.
 import {
   createCacheEntry,
   assertCacheEntry,
+  isExpired,
   cachified,
 } from '@epic-web/cachified';
 
@@ -512,6 +513,11 @@ assertCacheEntry(entry); // will throw when entry is not a valid CacheEntry
 console.log(entry.value);
 // > logs "[email protected]"
 
+/* Manually check if an entry is expired */
+const expired = isExpired(entry.metadata);
+console.log(expired);
+// > logs true, "stale" or false
+
 /* Manually remove an entry from cache */
 cache.delete('user-1');
 ```

src/cachified.ts

@@ -9,7 +9,7 @@ import {
 import { CACHE_EMPTY, getCachedValue } from './getCachedValue';
 import { getFreshValue } from './getFreshValue';
 import { CreateReporter } from './reporter';
-import { shouldRefresh } from './shouldRefresh';
+import { isExpired } from './isExpired';
 
 // This is to prevent requesting multiple fresh values in parallel
 // while revalidating or getting first value
@@ -53,7 +53,8 @@ export async function cachified<Value>(
 
   if (pendingValues.has(key)) {
     const { value: pendingRefreshValue, metadata } = pendingValues.get(key)!;
-    if (!shouldRefresh(metadata)) {
+
+    if (!isExpired(metadata)) {
       /* Notify batch that we handled this call using pending value */
       context.getFreshValue[HANDLE]?.();
       report({ name: 'getFreshValueHookPending' });

src/getCachedValue.ts

@@ -1,7 +1,7 @@
 import { Context, CacheEntry } from './common';
 import { assertCacheEntry } from './assertCacheEntry';
 import { HANDLE } from './common';
-import { shouldRefresh } from './shouldRefresh';
+import { isExpired } from './isExpired';
 import { cachified } from './cachified';
 import { Reporter } from './reporter';
 import { checkValue } from './checkValue';
@@ -42,12 +42,12 @@ export async function getCachedValue<Value>(
       return CACHE_EMPTY;
     }
 
-    const refresh = shouldRefresh(cached.metadata);
+    const expired = isExpired(cached.metadata);
     const staleRefresh =
-      refresh === 'stale' ||
-      (refresh === 'now' && staleWhileRevalidate === Infinity);
+      expired === 'stale' ||
+      (expired === true && staleWhileRevalidate === Infinity);
 
-    if (refresh === 'now') {
+    if (expired === true) {
       report({ name: 'getCachedValueOutdated', ...cached });
     }
 
@@ -75,7 +75,7 @@ export async function getCachedValue<Value>(
       );
     }
 
-    if (!refresh || staleRefresh) {
+    if (!expired || staleRefresh) {
       const valueCheck = await checkValue(context, cached.value);
       if (valueCheck.success) {
         report({

src/getFreshValue.ts

@@ -1,6 +1,6 @@
 import { Context, CacheMetadata, createCacheEntry } from './common';
 import { getCacheEntry, CACHE_EMPTY } from './getCachedValue';
-import { shouldRefresh } from './shouldRefresh';
+import { isExpired } from './isExpired';
 import { Reporter } from './reporter';
 import { checkValue } from './checkValue';
 
@@ -59,7 +59,8 @@ export async function getFreshValue<Value>(
   }
 
   try {
-    const write = shouldRefresh(metadata) !== 'now';
+    /* Only write to cache when the value has not already fully expired while getting it */
+    const write = isExpired(metadata) !== true;
     if (write) {
       await cache.set(key, createCacheEntry(value, metadata));
     }

src/index.ts

@@ -12,7 +12,7 @@ export * from './reporter';
 export { createBatch } from './createBatch';
 export { cachified } from './cachified';
 export { cachified as default } from './cachified';
-export { shouldRefresh } from './shouldRefresh';
+export { shouldRefresh, isExpired } from './isExpired';
 export { assertCacheEntry } from './assertCacheEntry';
 export { softPurge } from './softPurge';
 export { configure } from './configure';

src/isExpired.ts

@@ -0,0 +1,47 @@
+import { CacheMetadata, staleWhileRevalidate } from './common';
+
+/**
+ * Check wether a cache entry is expired.
+ *
+ * @returns
+ *   - `true` when the cache entry is expired
+ *   - `false` when it's still valid
+ *   - `"stale"` when it's within the stale period
+ */
+export function isExpired(metadata: CacheMetadata): boolean | 'stale' {
+  /* No TTL means the cache is permanent / never expires */
+  if (metadata.ttl === null) {
+    return false;
+  }
+
+  const validUntil = metadata.createdTime + (metadata.ttl || 0);
+  const staleUntil = validUntil + (staleWhileRevalidate(metadata) || 0);
+  const now = Date.now();
+
+  /* We're still within the ttl period */
+  if (now <= validUntil) {
+    return false;
+  }
+  /* We're within the stale period */
+  if (now <= staleUntil) {
+    return 'stale';
+  }
+
+  /* Expired */
+  return true;
+}
+
+/**
+ * @deprecated prefer using `isExpired` instead
+ */
+export function shouldRefresh(
+  metadata: CacheMetadata,
+): 'now' | 'stale' | false {
+  const expired = isExpired(metadata);
+
+  if (expired === true) {
+    return 'now';
+  }
+
+  return expired;
+}

src/softPurge.ts

@@ -1,6 +1,6 @@
 import { Cache, createCacheEntry, staleWhileRevalidate } from './common';
 import { CACHE_EMPTY, getCacheEntry } from './getCachedValue';
-import { shouldRefresh } from './shouldRefresh';
+import { isExpired } from './isExpired';
 
 interface SoftPurgeOpts {
   cache: Cache;
@@ -23,7 +23,7 @@ export async function softPurge({
   const swrOverwrite = swrOverwrites.swr ?? swrOverwrites.staleWhileRevalidate;
   const entry = await getCacheEntry({ cache, key }, () => {});
 
-  if (entry === CACHE_EMPTY || shouldRefresh(entry.metadata)) {
+  if (entry === CACHE_EMPTY || isExpired(entry.metadata)) {
     return;
   }