{"id":44552,"library":"cf-workers-query","title":"cf-workers-query","description":"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.","status":"active","version":"0.11.5","language":"javascript","source_language":"en","source_url":"https://github.com/anymaniax/cf-workers-query","tags":["javascript","rest","cloudflare workers","query","cache","cloudflare","workers","typescript"],"install":[{"cmd":"npm install cf-workers-query","lang":"bash","label":"npm"},{"cmd":"yarn add cf-workers-query","lang":"bash","label":"yarn"},{"cmd":"pnpm add cf-workers-query","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required only for the hono/cache middleware export; not needed for core createQuery usage.","package":"hono","optional":true}],"imports":[{"note":"ESM-only; do not use require().","wrong":"const { createQuery } = require('cf-workers-query')","symbol":"createQuery","correct":"import { createQuery } from 'cf-workers-query'"},{"note":"The hono middleware is exported from a subpath, not the main entry.","wrong":"import { cache } from 'cf-workers-query'","symbol":"cache (Hono middleware)","correct":"import { cache } from 'cf-workers-query/hono'"},{"note":"Must be re-exported from your worker entry, and bound in wrangler.toml.","wrong":"import { QueryDeduper } from 'cf-workers-query'","symbol":"QueryDeduper (Durable Object class)","correct":"export { QueryDeduper } from 'cf-workers-query/durable-object'"}],"quickstart":{"code":"import { createQuery } from 'cf-workers-query';\n\nexport default {\n  async fetch(request, env, ctx) {\n    const { data, error, invalidate } = await createQuery({\n      queryKey: ['user', '123'],\n      queryFn: async () => {\n        const resp = await fetch('https://api.example.com/user/123');\n        return resp.json();\n      },\n      staleTime: 30,\n      gcTime: 60,\n    });\n\n    if (error) {\n      return new Response('Error: ' + error.message, { status: 500 });\n    }\n\n    return new Response(JSON.stringify(data), {\n      headers: { 'content-type': 'application/json' },\n    });\n  },\n};\n","lang":"typescript","description":"Basic usage of createQuery to fetch, cache and revalidate user data in a Cloudflare Worker."},"warnings":[{"fix":"Set gcTime to a positive integer (in seconds) to enable caching.","message":"gcTime 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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Always use seconds for staleTime and gcTime, milliseconds for retryDelay.","message":"staleTime and gcTime are in seconds, but retryDelay is in milliseconds. Mixing units can cause unexpected behavior.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add optional Durable Object binding and import the QueryDeduper class.","message":"The 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).","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Do not set queryKey to null; omit it or provide an array.","message":"queryKey set to null disables caching entirely. This behavior is unexpected if you intended a default key.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Omit revalidateMode or set to 'default'.","message":"revalidateMode: 'probabilistic' uses internal probability logic that may change in future versions. Prefer default mode.","severity":"deprecated","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'0.11.5':24 'api':17,43 'background':21 'built':55,66 'built-in':54 'cach':7,16,42,91 'cf':2 'cf-workers-queri':1 'cloudflar':12,88,92 'dedupl':40 'depend':72 'differenti':34 'durabl':46 'except':73 'extern':71 'fine':82 'fine-grain':81 'flight':52 'grain':83 'guarante':49 'hono':57,74 'integr':58 'javascript':86 'key':33 'latest':27 'librari':10 'lightweight':6 'logic':85 'marker':44 'month':31 'object':47 'option':45 'pattern':39 'prevent':79 'probabilist':77 'purpos':65 'purpose-built':64 'queri':4,61,90 'releas':29 'rest':87 'retri':84 'revalid':9,22,38 'singl':51 'single-flight':50 'stabl':28 'stale':36 'stale-while-revalid':35 'stamped':78 'support':76 'tanstack':60 'typescript':94 'unlik':59 'updat':32 'use':14 'v4':75 'version':23 'via':41 'waituntil':19 'worker':3,13,68,89,93","created_at":"2026-06-07T12:50:42.324433+00:00","updated_at":"2026-06-07T12:50:42.324433+00:00","problems":[{"fix":"Run `npm install cf-workers-query` in your project directory.","cause":"Package not installed or npm install failed.","error":"Error: Cannot find module 'cf-workers-query'"},{"fix":"Change to `import { createQuery } from 'cf-workers-query'` and ensure your package.json has \"type\": \"module\".","cause":"Using CommonJS require() instead of ESM import; cf-workers-query is ESM-only.","error":"SyntaxError: The requested module 'cf-workers-query' does not provide an export named 'createQuery'"},{"fix":"Add [[durable_objects.bindings]] with name and class_name in wrangler.toml, and declare the DO class in your worker.","cause":"Attempting to use the Durable Object deduper without configuring wrangler.toml.","error":"Error: No Durable Object binding found for 'QUERY_DEDUPER'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/anymaniax/cf-workers-query#readme","github":"https://github.com/anymaniax/cf-workers-query","docs":null,"changelog":null,"pypi":null,"npm":"cf-workers-query","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}