Automatically cache and revalidate data in Cloudflare Workers. Using the Cache API and Execution Context.
MIT License
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: 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.