import{LRUCache}from'lru-cache';import{cachified,CacheEntry,Cache,totalTtl}from'@epic-web/cachified';/* lru cache is not part of this package but a simple non-persistent cache */constlruInstance=newLRUCache<string,CacheEntry>({max: 1000});constlru: Cache={set(key,value){constttl=totalTtl(value?.metadata);returnlruInstance.set(key,value,{ttl: ttl===Infinity ? undefined : ttl,start: value?.metadata?.createdTime,});},get(key){returnlruInstance.get(key);},delete(key){returnlruInstance.delete(key);},};functiongetUserById(userId: number){returncachified({key: `user-${userId}`,cache: lru,asyncgetFreshValue(){/* Normally we want to either use a type-safe API or `checkValue` but to keep this example simple we work with `any` */constresponse=awaitfetch(`https://jsonplaceholder.typicode.com/users/${userId}`,);returnresponse.json();},/* 5 minutes until cache gets invalid * Optional, defaults to Infinity */ttl: 300_000,});}// Let's get through some calls of `getUserById`:console.log(awaitgetUserById(1));// > logs the user with ID 1// Cache was empty, `getFreshValue` got invoked and fetched the user-data that// is now cached for 5 minutes// 2 minutes laterconsole.log(awaitgetUserById(1));// > logs the exact same user-data// Cache was filled an valid. `getFreshValue` was not invoked// 10 minutes laterconsole.log(awaitgetUserById(1));// > logs the user with ID 1 that might have updated fields// Cache timed out, `getFreshValue` got invoked to fetch a fresh copy of the user// that now replaces current cache entry and is cached for 5 minutes

interfaceCachifiedOptions<Value>{/** * Required * * The key this value is cached by * Must be unique for each value */key: string;/** * Required * * Cache implementation to use * * Must conform with signature * - set(key: string, value: object): void | Promise<void> * - get(key: string): object | Promise<object> * - delete(key: string): void | Promise<void> */cache: Cache;/** * Required * * Function that is called when no valid value is in cache for given key * Basically what we would do if we wouldn't use a cache * * Can be async and must return fresh value or throw * * receives context object as argument * - context.metadata.ttl?: number * - context.metadata.swr?: number * - context.metadata.createdTime: number * - context.background: boolean */getFreshValue: GetFreshValue<Value>;/** * Time To Live; often also referred to as max age * * Amount of milliseconds the value should stay in cache * before we get a fresh one * * Setting any negative value will disable caching * Can be infinite * * Default: `Infinity` */ttl?: number;/** * Amount of milliseconds that a value with exceeded ttl is still returned * while a fresh value is refreshed in the background * * Should be positive, can be infinite * * Default: `0` */staleWhileRevalidate?: number;/** * Alias for staleWhileRevalidate */swr?: number;/** * Validator that checks every cached and fresh value to ensure type safety * * Can be a standard schema validator or a custom validator function * @see https://github.com/standard-schema/standard-schema?tab=readme-ov-file#what-schema-libraries-implement-the-spec * * Value considered ok when: * - schema succeeds * - validator returns * - true * - migrate(newValue) * - undefined * - null * * Value considered bad when: * - schema throws * - validator: * - returns false * - returns reason as string * - throws * * A validator function receives two arguments: * 1. the value * 2. a migrate callback, see https://github.com/epicweb-dev/cachified#migrating-values * * Default: `undefined` - no validation */checkValue?: |CheckValue<Value>|StandardSchemaV1<unknown,Value>|Schema<Value,unknown>;/** * Set true to not even try reading the currently cached value * * Will write new value to cache even when cached value is * still valid. * * Default: `false` */forceFresh?: boolean;/** * Whether or not to fall back to cache when getting a forced fresh value * fails * * Can also be a positive number as the maximum age in milliseconds that a * fallback value might have * * Default: `Infinity` */fallbackToCache?: boolean|number;/** * Promises passed to `waitUntil` represent background tasks which must be * completed before the server can shutdown. e.g. swr cache revalidation * * Useful for serverless environments such as Cloudflare Workers. * * 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;}

import{cachified}from'@epic-web/cachified';constcache=newMap();functiongetUserById(userId: number){returncachified({ttl: 120_000/* Two minutes */,staleWhileRevalidate: 300_000/* Five minutes */, cache,key: `user-${userId}`,asyncgetFreshValue(){constresponse=awaitfetch(`https://jsonplaceholder.typicode.com/users/${userId}`,);returnresponse.json();},});}console.log(awaitgetUserById(1));// > logs the user with ID 1// Cache is empty, `getFreshValue` gets invoked and and its value returned and// cached for 7 minutes total. After 2 minutes the cache will start refreshing in background// 30 seconds laterconsole.log(awaitgetUserById(1));// > logs the exact same user-data// Cache is filled an valid. `getFreshValue` is not invoked, cached value is returned// 4 minutes laterconsole.log(awaitgetUserById(1));// > logs the exact same user-data// Cache timed out but stale while revalidate is not exceeded.// cached value is returned immediately, `getFreshValue` gets invoked in the// background and its value is cached for the next 7 minutes// 30 seconds laterconsole.log(awaitgetUserById(1));// > logs fresh user-data from the previous call// Cache is filled an valid. `getFreshValue` is not invoked, cached value is returned

import{cachified}from'@epic-web/cachified';constcache=newMap();functiongetUserById(userId: number,forceFresh?: boolean){returncachified({ forceFresh,/* when getting a forced fresh value fails we fall back to cached value as long as it's not older then 5 minutes */fallbackToCache: 300_000/* 5 minutes, defaults to Infinity */, cache,key: `user-${userId}`,asyncgetFreshValue(){constresponse=awaitfetch(`https://jsonplaceholder.typicode.com/users/${userId}`,);returnresponse.json();},});}console.log(awaitgetUserById(1));// > logs the user with ID 1// Cache is empty, `getFreshValue` gets invoked and and its value returnedconsole.log(awaitgetUserById(1,true));// > logs fresh user with ID 1// Cache is filled an valid. but we forced a fresh value, so `getFreshValue` is invoked

import{cachified,createCacheEntry}from'@epic-web/cachified';constcache=newMap();/* Assume something bad happened and we have an invalid cache entry... */cache.set('user-1',createCacheEntry('INVALID')asany);functiongetUserById(userId: number){returncachified({checkValue(value: unknown){if(!isRecord(value)){/* We can either throw to indicate a bad value */thrownewError(`Expected user to be object, got ${typeofvalue}`);}if(typeofvalue.email!=='string'){/* Or return a reason/message string */return`Expected user-${userId} to have an email`;}if(typeofvalue.username!=='string'){/* Or just say no... */returnfalse;}/* undefined, true or null are considered OK */}, cache,key: `user-${userId}`,asyncgetFreshValue(){constresponse=awaitfetch(`https://jsonplaceholder.typicode.com/users/${userId}`,);returnresponse.json();},});}functionisRecord(value: unknown): value is Record<string,unknown>{returntypeofvalue==='object'&&value!==null&&!Array.isArray(value);}console.log(awaitgetUserById(1));// > logs the user with ID 1// Cache was not empty but value was invalid, `getFreshValue` got invoked and// and the cache was updatedconsole.log(awaitgetUserById(1));// > logs the exact same data as above// Cache was filled an valid. `getFreshValue` was not invoked

import{cachified,createCacheEntry}from'@epic-web/cachified';importzfrom'zod';constcache=newMap();/* Assume something bad happened and we have an invalid cache entry... */cache.set('user-1',createCacheEntry('INVALID')asany);functiongetUserById(userId: number){returncachified({checkValue: z.object({email: z.string(),}), cache,key: `user-${userId}`,asyncgetFreshValue(){constresponse=awaitfetch(`https://jsonplaceholder.typicode.com/users/${userId}`,);returnresponse.json();},});}console.log(awaitgetUserById(1));// > logs the user with ID 1// Cache was not empty but value was invalid, `getFreshValue` got invoked and// and the cache was updatedconsole.log(awaitgetUserById(1));// > logs the exact same data as above// Cache was filled an valid. `getFreshValue` was not invoked

import{configure}from'@epic-web/cachified';import{LRUCache}from'lru-cache';/* lruCachified now has a default cache */constlruCachified=configure({cache: newLRUCache<string,CacheEntry>({max: 1000}),});constvalue=awaitlruCachified({key: 'user-1',getFreshValue: async()=>'ONE',});

import{createCacheEntry,assertCacheEntry,isExpired,cachified,}from'@epic-web/cachified';constcache=newMap();/* Manually set an entry to cache */cache.set('user-1',createCacheEntry('[email protected]',/* Optional CacheMetadata */{ttl: 300_000,swr: Infinity},),);/* Receive the value with cachified */constvalue: string=awaitcachified({ cache,key: 'user-1',getFreshValue(){thrownewError('This is not called since cache is set earlier');},});console.log(value);// > logs "[email protected]"/* Manually get a value from cache */constentry: unknown=cache.get('user-1');assertCacheEntry(entry);// will throw when entry is not a valid CacheEntryconsole.log(entry.value);// > logs "[email protected]"/* Manually check if an entry is expired */constexpired=isExpired(entry.metadata);console.log(expired);// > logs true, "stale" or false/* Manually remove an entry from cache */cache.delete('user-1');

import{cachified,createCacheEntry}from'@epic-web/cachified';constcache=newMap();/* Let's assume we've previously only stored emails not user objects */cache.set('user-1',createCacheEntry('[email protected]'));functiongetUserById(userId: number){returncachified({checkValue(value,migrate){if(typeofvalue==='string'){returnmigrate({email: value});}/* other validations... */},key: 'user-1', cache,getFreshValue(){thrownewError('This is never called');},});}console.log(awaitgetUserById(1));// > logs{email: 'someone@example.org' }// Cache is filled and invalid but value can be migrated from email to user-object// `getFreshValue` is not invokedconsole.log(awaitgetUserById(1));// > logs the exact same data as above// Cache is filled an valid.

import{cachified,softPurge}from'@epic-web/cachified';constcache=newMap();functiongetUserById(userId: number){returncachified({ cache,key: `user-${userId}`,ttl: 300_000,asyncgetFreshValue(){constresponse=awaitfetch(`https://jsonplaceholder.typicode.com/users/${userId}`,);returnresponse.json();},});}console.log(awaitgetUserById(1));// > logs user with ID 1// cache was empty, fresh value was requested and is cached for 5 minutesawaitsoftPurge({ cache,key: 'user-1',});// This internally sets the ttl to 0 and staleWhileRevalidate to 300_000// 10 seconds laterconsole.log(awaitgetUserById(1));// > logs the outdated, soft-purged data// cache has been soft-purged, the cached value got returned and a fresh value// is requested in the background and again cached for 5 minutes// 1 minute laterconsole.log(awaitgetUserById(1));// > logs the fresh data that got refreshed by the previous callawaitsoftPurge({ cache,key: 'user-1',// manually overwrite how long the stale data should stay in cachestaleWhileRevalidate: 60_000/* one minute from now on */,});// 2 minutes laterconsole.log(awaitgetUserById(1));// > logs completely fresh data

import{cachified}from'@epic-web/cachified';constcache=newMap();constvalue: null|string=awaitcachified({ttl: 60_000/* Default cache of one minute... */,asyncgetFreshValue(context){constresponse=awaitfetch(`https://jsonplaceholder.typicode.com/users/1`,);constdata=awaitresponse.json();if(data===null){/* On an empty result, prevent caching */context.metadata.ttl=-1;}returndata;}, cache,key: 'user-1',});

import{cachified,createBatch}from'@epic-web/cachified';constcache=newMap();asyncfunctiongetFreshValues(idsThatAreNotInCache: number[]){constres=awaitfetch(`https://example.org/api?ids=${idsThatAreNotInCache.join(',')}`,);constdata=awaitres.json();// Validate data here...returndata;}functiongetUsersWithId(ids: number[]){constbatch=createBatch(getFreshValues);returnPromise.all(ids.map((id)=>cachified({getFreshValue: batch.add(id,/* onValue callback is optional but can be used to manipulate * cache metadata based on the received value. (see section above) */({ value, ...context})=>{},), cache,key: `entry-${id}`,ttl: 60_000,}),),);}console.log(awaitgetUsersWithId([1,2]));// > logs user objects for ID 1 & ID 2// Caches is completely empty. `getFreshValues` is invoked with `[1, 2]`// and its return values cached separately// 1 minute laterconsole.log(awaitgetUsersWithId([2,3]));// > logs user objects for ID 2 & ID 3// User with ID 2 is in cache, `getFreshValues` is invoked with `[3]`// cachified returns with one value from cache and one fresh value

import{cachified,verboseReporter}from'@epic-web/cachified';constcache=newMap();awaitcachified({ cache,key: 'user-1',asyncgetFreshValue(){constresponse=awaitfetch(`https://jsonplaceholder.typicode.com/users/1`,);returnresponse.json();},},verboseReporter(),);