feat: add softPurge helper

fix #46

Author: Xiphe

readme.md

@@ -375,11 +375,11 @@ be migrated on read like this:
 ```ts
 import type { CacheEntry } from 'cachified';
 import LRUCache from 'lru-cache';
-import { cachified } from 'cachified';
+import { cachified, createCacheEntry } from 'cachified';
 
-const lru = new LRUCache<string, CacheEntry<string>>({ max: 1000 });
+const lru = new LRUCache<string, CacheEntry<string | { email: string }>>({ max: 1000 });
 /* Let's assume we've previously only stored emails not user objects */
-lru.set('user-1', { value: '[email protected]', metadata: { createdAt: Date.now() } });
+lru.set('user-1', createCacheEntry('[email protected]'));
 
 function getUserById(userId: string) {
  return cachified({
@@ -403,6 +403,40 @@ function getUserById(userId: string) {
 - **Second Call `getUserById('1')`**:  
   Cache is filled an valid. `getFreshValue` is not invoked, cached value is returned
 
+### soft-purging entries
+
+Soft-purging values has the benefit of not immediately putting pressure on the app
+to update all cached values at once and instead allows to get them updated over time.
+
+More details: [Soft vs. hard purge](https://developer.fastly.com/reference/api/purging/#soft-vs-hard-purge)
+
+```ts
+import type { CacheEntry } from 'cachified';
+import LRUCache from 'lru-cache';
+import { softPurge, createCacheEntry } from 'cachified';
+
+const lru = new LRUCache<string, CacheEntry<string>>({ max: 1000 });
+lru.set('user-1', createCacheEntry('[email protected]', { ttl: 300_000 }));
+
+// This effectively sets the ttl to 0 and stale while revalidate to 300_000
+await softPurge({
+  cache: lru,
+  key: 'user-1',
+});
+
+
+// It's also possible to manually set a new time when the entry should not be served stale
+await softPurge({
+  cache: lru,
+  key: 'user-1',
+  // for one minute serve stale and refresh in background, afterwards get fresh value directly
+  staleWhileRevalidate: 60_000
+});
+```
+
+> ℹ️ In case we need to fully purge the value, we delete the key directly from our cache
+
+
 ### Fine-tuning cache metadata based on fresh values
 
 There are scenarios where we want to change the cache time based on the fresh

src/getCachedValue.ts

@@ -8,7 +8,7 @@ import { checkValue } from './checkValue';
 
 export const CACHE_EMPTY = Symbol();
 export async function getCacheEntry<Value>(
-  { key, cache }: Context<Value>,
+  { key, cache }: Pick<Context<Value>, 'key' | 'cache'>,
   report: Reporter<Value>,
 ): Promise<CacheEntry<unknown> | typeof CACHE_EMPTY> {
   report({ name: 'getCachedValueStart' });

src/softPurge.spec.ts

@@ -0,0 +1,106 @@
+import { createCacheEntry } from './common';
+import { softPurge } from './softPurge';
+
+let currentTime = 0;
+beforeEach(() => {
+  currentTime = 0;
+  jest.spyOn(Date, 'now').mockImplementation(() => currentTime);
+});
+
+describe('softPurge', () => {
+  it('does not update entry when cache is outdated already', async () => {
+    const cache = new Map();
+
+    cache.set('key', createCacheEntry('value', { ttl: 5 }));
+    currentTime = 10;
+    jest.spyOn(cache, 'set');
+
+    await softPurge({ cache, key: 'key' });
+
+    expect(cache.set).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when cache is empty', async () => {
+    const cache = new Map();
+
+    await softPurge({ cache, key: 'key' });
+  });
+
+  it('throws when entry is invalid', async () => {
+    const cache = new Map();
+
+    cache.set('key', '???');
+
+    await expect(
+      softPurge({ cache, key: 'key' }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"Cache entry for key is not a cache entry object, it's a string"`,
+    );
+  });
+
+  it('sets ttl to 0 and swr to previous ttl', async () => {
+    const cache = new Map();
+
+    cache.set('key', createCacheEntry('value', { ttl: 1000 }));
+
+    await softPurge({ cache, key: 'key' });
+
+    expect(cache.get('key')).toEqual(
+      createCacheEntry('value', { ttl: 0, swr: 1000 }),
+    );
+  });
+
+  it('sets ttl to 0 and swr to previous ttl + previous swr', async () => {
+    const cache = new Map();
+
+    cache.set('key', createCacheEntry('value', { ttl: 1000, swr: 50 }));
+
+    await softPurge({ cache, key: 'key' });
+
+    expect(cache.get('key')).toEqual(
+      createCacheEntry('value', { ttl: 0, swr: 1050 }),
+    );
+  });
+
+  it('sets ttl to 0 and swr to infinity when ttl was infinity', async () => {
+    const cache = new Map();
+
+    cache.set('key', createCacheEntry('value', { ttl: Infinity }));
+
+    await softPurge({ cache, key: 'key' });
+
+    expect(cache.get('key')).toEqual(
+      createCacheEntry('value', { ttl: 0, swr: Infinity }),
+    );
+  });
+
+  it('allows to set a custom stale while revalidate value', async () => {
+    const cache = new Map();
+    currentTime = 30;
+
+    cache.set('key', createCacheEntry('value', { ttl: Infinity }));
+
+    currentTime = 40;
+
+    await softPurge({ cache, key: 'key', staleWhileRevalidate: 50 });
+
+    expect(cache.get('key')).toEqual(
+      createCacheEntry('value', { ttl: 0, swr: 60, createdTime: 30 }),
+    );
+  });
+
+  it('supports swr alias', async () => {
+    const cache = new Map();
+    currentTime = 30;
+
+    cache.set('key', createCacheEntry('value', { ttl: Infinity }));
+
+    currentTime = 55;
+
+    await softPurge({ cache, key: 'key', swr: 10 });
+
+    expect(cache.get('key')).toEqual(
+      createCacheEntry('value', { ttl: 0, swr: 35, createdTime: 30 }),
+    );
+  });
+});

src/softPurge.ts

@@ -0,0 +1,42 @@
+import { Cache, createCacheEntry, staleWhileRevalidate } from './common';
+import { CACHE_EMPTY, getCacheEntry } from './getCachedValue';
+import { shouldRefresh } from './shouldRefresh';
+
+interface SoftPurgeOpts {
+  cache: Cache;
+  key: string;
+  /**
+   * Force the entry to outdate after ms
+   */
+  staleWhileRevalidate?: number;
+  /**
+   * Force the entry to outdate after ms
+   */
+  swr?: number;
+}
+
+export async function softPurge({
+  cache,
+  key,
+  ...swrOverwrites
+}: SoftPurgeOpts) {
+  const swrOverwrite = swrOverwrites.swr ?? swrOverwrites.staleWhileRevalidate;
+  const entry = await getCacheEntry({ cache, key }, () => {});
+
+  if (entry === CACHE_EMPTY || shouldRefresh(entry.metadata)) {
+    return;
+  }
+
+  const ttl = entry.metadata.ttl || Infinity;
+  const swr = staleWhileRevalidate(entry.metadata) || 0;
+  const lt = Date.now() - entry.metadata.createdTime;
+
+  await cache.set(
+    key,
+    createCacheEntry(entry.value, {
+      ttl: 0,
+      swr: swrOverwrite === undefined ? ttl + swr : swrOverwrite + lt,
+      createdTime: entry.metadata.createdTime,
+    }),
+  );
+}