cf-workers-query

Cf-Workers-Query

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,
});

Stale revalidation

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:

Hono example

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
}));

API Reference

queryKey

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.

queryFn

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.

staleTime

Type: number

Description: Optional. The amount of time in milliseconds before the query data is considered stale. Default is 0.

gcTime

Type: number

Description: Optional. The amount of time in milliseconds to keep unused data in the cache before garbage collection.

revalidate

Type: boolean

Description: Optional. If true, the query will directly revalidate data.

revalidateMode

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

retry

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.

retryDelay

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.

executionCtx

Type: ExecutionContext

Description: Optional. The execution context to use.

cacheName

Type: string

Description: Optional. The name of the cache to use. Default is cf-workers-query-cache.

Credits

Inspired by tanstack query but for Cloudflare Workers.

Changelog

0.8.2 (2025-01-22)

🩹 Fixes

• create-query: return cache properly (5a87607)

❤️ Thank You

• Victor Bury