Automatically cache and revalidate data in Cloudflare Workers. Using the Cache API and Execution Context.
Example:
import { createQuery } from 'cf-workers-query';
const { data, error, invalidate } = await createQuery({
queryKey: ['user', userId],
queryFn: async () => {
const user = await fetchUser(userId);
return user;
},
gcTime: 60 * 1000,
});import { createQuery } from 'cf-workers-query';
export default {
async fetch(request, env, ctx) {
const { data } = await createQuery({
queryKey: ['user', userId],
queryFn: async () => {
const user = await fetchUser(userId);
return user;
},
staleTime: 30 * 1000,
gcTime: 60 * 1000,
executionCtx: ctx,
});
return new Response(JSON.stringify(data), {
headers: {
'content-type': 'application/json',
},
});
},
};To have revalidation automatically when the stale time is reached, you need to provide the executionCtx to the createQuery function.
You can also use the defineCFExecutionContext function to define a custom execution context for the query. Can be useful if you are using a something like hono or remix.
Example using defineCFExecutionContext:
In this case you don't need to use defineCFExecutionContext as the execution context is provided automatically.
import { cache } from 'cf-workers-query/hono';
app.get('/user/:id', cache({
handler: async (ctx, next) => {
const user = await fetchUser(ctx.req.param('id'));
return ctx.json(user)
},
cacheKey: (ctx) => ['user', ctx.req.param('id')],
cacheTime: 60 * 60,
staleTime: 60
}));Type: QueryKey | null
Description: An optional key that uniquely identifies the query. This can be used to cache and retrieve query results more effectively. If set to null, the query may not be cached.
Type: () => Promise
Description: A function that returns a promise resolving with the data for the query. It is the primary function that runs to fetch the data.
Type: number
Description: Optional. The amount of time in milliseconds before the query data is considered stale. Default is 0.
Type: number
Description: Optional. The amount of time in milliseconds to keep unused data in the cache before garbage collection.
Type: boolean
Description: Optional. If true, the query will directly revalidate data.
Type: default | probabilistic
Description: Optional. If probabilistic if data is stale will use a probabilistic function to maybe revalidate data. Based on https://blog.cloudflare.com/sometimes-i-cache
Type: number | ((failureCount: number, error: Error) => boolean)
Description: Optional. Specifies the number of retry attempts in case of a query failure. Alternatively, a function that receives the failure count and error and returns a boolean indicating whether to retry the query.
Type: RetryDelay
Description: Optional. Specifies the delay between retry attempts. This can be a number indicating milliseconds or a function returning the delay based on the failure count and error.
Type: ExecutionContext
Description: Optional. The execution context to use.
Type: string
Description: Optional. The name of the cache to use. Default is cf-workers-query-cache.
Inspired by tanstack query but for Cloudflare Workers.