cf-workers-query

library0.11.5jsnpmunverified

A lightweight caching and revalidation library for Cloudflare Workers, using the Cache API and waitUntil for background revalidation. Version 0.11.5 is the latest stable release, with monthly updates. Key differentiators: stale-while-revalidate pattern, deduplication via Cache API markers, optional Durable Objects for guaranteed single-flight, and built-in Hono integration. Unlike TanStack Query, it is purpose-built for Workers with no external dependencies except Hono (v4+). Supports probabilistic stampede prevention and fine-grained retry logic.

database

npm install cf-workers-query

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CF-WORKERS-QUERY

cf-workers-query

databasejavascriptv0.11.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createQuery

✓ import { createQuery } from 'cf-workers-query'

✗ const { createQuery } = require('cf-workers-query')

ESM-only; do not use require().

cache (Hono middleware)

✓ import { cache } from 'cf-workers-query/hono'

✗ import { cache } from 'cf-workers-query'

The hono middleware is exported from a subpath, not the main entry.

QueryDeduper (Durable Object class)

✓ export { QueryDeduper } from 'cf-workers-query/durable-object'

✗ import { QueryDeduper } from 'cf-workers-query'

Must be re-exported from your worker entry, and bound in wrangler.toml.

Basic usage of createQuery to fetch, cache and revalidate user data in a Cloudflare Worker.

import { createQuery } from 'cf-workers-query'; export default { async fetch(request, env, ctx) { const { data, error, invalidate } = await createQuery({ queryKey: ['user', '123'], queryFn: async () => { const resp = await fetch('https://api.example.com/user/123'); return resp.json(); }, staleTime: 30, gcTime: 60, }); if (error) { return new Response('Error: ' + error.message, { status: 500 }); } return new Response(JSON.stringify(data), { headers: { 'content-type': 'application/json' }, }); }, };

Debug

Known issues

gotchagcTime maps to Cache-Control: max-age seconds. If set to 0 or falsy, caching is skipped entirely. Do not expect a cached response if gcTime is 0.

fix

Set gcTime to a positive integer (in seconds) to enable caching.

affects: >=0.0.0

gotchastaleTime and gcTime are in seconds, but retryDelay is in milliseconds. Mixing units can cause unexpected behavior.

fix

Always use seconds for staleTime and gcTime, milliseconds for retryDelay.

affects: >=0.0.0

gotchaThe deduplication via Cache API markers is best-effort; under high concurrency, up to 3 fetches may run. For guaranteed single-flight, you must use Durable Objects (opt-in).

fix

Add optional Durable Object binding and import the QueryDeduper class.

affects: >=0.0.0

gotchaqueryKey set to null disables caching entirely. This behavior is unexpected if you intended a default key.

fix

Do not set queryKey to null; omit it or provide an array.

affects: >=0.0.0

deprecatedrevalidateMode: 'probabilistic' uses internal probability logic that may change in future versions. Prefer default mode.

fix

Omit revalidateMode or set to 'default'.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'cf-workers-query'

Package not installed or npm install failed.

fix

Run `npm install cf-workers-query` in your project directory.

SyntaxError: The requested module 'cf-workers-query' does not provide an export named 'createQuery'

Using CommonJS require() instead of ESM import; cf-workers-query is ESM-only.

fix

Change to `import { createQuery } from 'cf-workers-query'` and ensure your package.json has "type": "module".

Error: No Durable Object binding found for 'QUERY_DEDUPER'

Attempting to use the Durable Object deduper without configuring wrangler.toml.

fix

Add [[durable_objects.bindings]] with name and class_name in wrangler.toml, and declare the DO class in your worker.

Upgrade

Version history

0.11.5latest on npm

Audit

Dependencies

honooptionalRequired only for the hono/cache middleware export; not needed for core createQuery usage.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/anymaniax/cf-workers-query ↗

packagecf-workers-query ↗

homepagehttps://github.com/anymaniax/cf-workers-query#readme ↗