API Reference

import { defineTags } from "@tanstack-tools/query-tags";

const appTags = defineTags({
  todos: {
    list: () => ["todos"],
    byId: (id: string) => ["todo", id],
  },
  users: {
    list: () => ["users"],
    byId: (id: string) => ["user", id],
  },
});

// Leaf tags
appTags.todos.list()          // ["todos"]
appTags.todos.byId("abc")     // ["todo", "abc"]

// Group — expands all zero-arg leaves when passed to invalidateTags
appTags.todos()               // TagGroup { leaves: [["todos"]] }
appTags()                     // TagGroup { leaves: [["todos"], ["users"]] }

import { withTags } from "@tanstack-tools/query-tags";
import { useQuery } from "@tanstack/react-query";

// Form 1 — wrap existing options (canonical)
const query = useQuery(
  withTags({ queryFn: fetchTodos }, [appTags.todos.list()]),
);
// → { queryKey: ['["todos"]'], meta: { tags: [["todos"]] }, queryFn: fetchTodos }

// Form 2 — meta.tags directly (equivalent, no helper)
const query2 = useQuery({
  queryKey: ["todos"],
  queryFn: fetchTodos,
  meta: { tags: [appTags.todos.list()] },
});

import {
  matchTags,
  findQueriesByTag,
  listAllTags,
  EVERY_INVALIDATION_TAG,
} from "@tanstack-tools/query-tags";

// Which queries would be invalidated by these tags?
const hits = matchTags({ queryClient, tags: [appTags.todos.list()] });
// → [{ queryKey: ["todos"], queryHash: '["todos"]' }, …]

// Queries tagged with a single specific tag
const queries = findQueriesByTag({ queryClient, tag: appTags.todos.list() });

// All tags currently registered in the cache
const allTags = listAllTags({ queryClient });
// → ['"__every_invalidation__"', '["todos"]', '["users"]']

// Tag that matches on every invalidation event
meta: { tags: [EVERY_INVALIDATION_TAG] }

import { createTagInvalidationSystem } from "@tanstack-tools/query-tags/server";

// Minimal — defaults are sensible
const tagInvalidation = createTagInvalidationSystem();

// Full options
const tagInvalidation = createTagInvalidationSystem<MyContext>({
  batchWindow: 50,         // ms — merge rapid-fire events (default: 50)
  heartbeatInterval: 30000,// ms — keep proxies alive (default: 30 000)
  eventLogSize: 1000,      // ring-buffer per scope (default: 1 000)
  maxConnections: 10000,   // global SSE cap (default: 10 000)
  maxConnectionsPerScope: 1000, // per-scope SSE cap (default: 1 000)
  maxScopeKeyLength: 128,  // max scope key chars (default: 128)
  broadcast: myBroadcast,  // multi-instance adapter (default: in-process)
  resolveScope: (ctx) => ({ kind: "user", id: ctx.userId }),
  rateLimit: false,        // disable rate limiting (or pass tiers)
  resolveClientIp: (req) => req.headers.get("CF-Connecting-IP") ?? "",
  onDevtoolsEvent: (event) => devtoolsSink.emit(event),
});

// Invalidate from a server action
await tagInvalidation.invalidateTags({ tags: [appTags.todos.list()] });

import { TagInvalidationProvider } from "@tanstack-tools/query-tags/react";
import { createInvalidatorClient } from "@tanstack-tools/query-tags/client";

const client = createInvalidatorClient();

// Minimal (required props only)
<TagInvalidationProvider queryClient={queryClient} router={router}>
  <App />
</TagInvalidationProvider>

// With all options
<TagInvalidationProvider
  queryClient={queryClient}
  router={router}
  client={client}           // enables status/history/control hooks
  scope={{ kind: "user", id: userId }}
  eventSourceUrl="/api/invalidator/sse"
  onDisconnect="invalidate-all"   // or "silent" | { strategy, tags? }
  onError={(err, ctx) => console.error(ctx, err)}
  dedupeWindow={50}               // ms client-side dedup (default: 50)
  conditionalInvalidation={true}  // skip fresh queries (default: false)
  tabLeader={true}                // WS1 tab leader election
>
  <App />
</TagInvalidationProvider>

import {
  useTagInvalidationRuntime,
  useTagInvalidationDebugState,
  useInvalidationClient,
  useInvalidationStatus,
  useInvalidationHistory,
  useInvalidationControl,
  useInvalidationActions,
  useOptimisticInvalidation,
  useOptimisticMutation,
} from "@tanstack-tools/query-tags/react";

// Debug state — connected, paused, event log
const { isConnected, isPaused, messages } = useTagInvalidationDebugState();

// Control panel (requires client prop on provider)
const { pauseAll, resumeAll, disableTags, enableTags, isPausing } =
  useInvalidationControl();

// Polling queries (require client prop)
const { data: status } = useInvalidationStatus({ refetchInterval: 5000 });
const { data: history } = useInvalidationHistory();

// Optimistic update with rollback
const [optimisticTodos, addOptimistic] = useOptimisticInvalidation(todos);

import { createInvalidatorClient } from "@tanstack-tools/query-tags/client";

// TanStack Start — uses server functions under the hood
const client = createInvalidatorClient({ basePath: "/api/invalidator" });

// Attach to provider
<TagInvalidationProvider client={client} queryClient={queryClient} router={router}>
  <App />
</TagInvalidationProvider>

// Hono
import { createHonoHandler } from "@tanstack-tools/query-tags/adapters/hono";
app.all("/api/invalidator/*", createHonoHandler(system));

// Express
import { createExpressHandler } from "@tanstack-tools/query-tags/adapters/express";
app.all("/api/invalidator/*", createExpressHandler(system));

// Fastify
import { createFastifyHandler } from "@tanstack-tools/query-tags/adapters/fastify";
fastify.all("/api/invalidator/*", createFastifyHandler(system));

// Elysia
import { createElysiaHandler } from "@tanstack-tools/query-tags/adapters/elysia";
app.all("/api/invalidator/*", createElysiaHandler(system));

// Koa
import { createKoaHandler } from "@tanstack-tools/query-tags/adapters/koa";
router.all("/api/invalidator/(.*)", createKoaHandler(system));

// Node.js HTTP / https.createServer
import { createNodeHandler } from "@tanstack-tools/query-tags/adapters/node";
http.createServer(createNodeHandler(system));

// Fetch-standard (Bun, Deno, Cloudflare Workers)
import { createFetchHandler } from "@tanstack-tools/query-tags/adapters/fetch";
export default { fetch: createFetchHandler(system) };

// Shared options (all adapters accept these)
const handler = createHonoHandler(system, {
  basePath: "/api/invalidator",  // strip prefix from incoming URLs
  authenticate: async (req) => {
    const token = req.headers.get("Authorization");
    return token === "Bearer secret"; // false → 401, Response → forwarded
  },
});

import { createRedisBroadcast } from "@tanstack-tools/query-tags/redis";
import Redis from "ioredis";

const pub = new Redis();
const sub = new Redis();

const broadcast = createRedisBroadcast({
  channelPrefix: "query-tags:",      // default
  publish: (channel, msg) => pub.publish(channel, msg),
  subscribe: (channel, handler) => {
    sub.subscribe(channel);
    sub.on("message", (ch, msg) => ch === channel && handler(ch, msg));
    return () => sub.unsubscribe(channel);
  },
});

const system = createTagInvalidationSystem({ broadcast });

import { createTagsMiddleware } from "@tanstack-tools/query-tags/orpc";

const tagMiddleware = createTagsMiddleware({ system: tagInvalidation });

// Attach to any oRPC procedure
export const updateTodo = base
  .use(tagMiddleware)
  .handler(async ({ input, context }) => {
    const todo = await db.todos.update(input);
    context.invalidateTags([appTags.todos.byId(input.id)]);
    return todo;
  });

import { createTagsMiddleware } from "@tanstack-tools/query-tags/trpc";

const withTags = createTagsMiddleware({ system: tagInvalidation });

export const updateTodo = t.procedure
  .use(withTags)
  .mutation(async ({ input, ctx }) => {
    const todo = await db.todos.update(input);
    ctx.invalidateTags([appTags.todos.byId(input.id)]);
    return todo;
  });

import { vi } from "vitest";
import {
  createMockInvalidationSystem,
  createMockInvalidatorClient,
  createTestProvider,
  simulateInvalidation,
} from "@tanstack-tools/query-tags/testing";

// 1. Server-side assertions
const system = createMockInvalidationSystem();
await system.invalidateTags({ tags: [appTags.todos.list()] });
system.expectTagsInvalidated(['"todos"']);  // normalized string
system.expectTagsNotInvalidated(['"users"']);
system.getInvalidationCount('"todos"');     // → 1
system.reset();

// 2. Mock client for provider
const client = createMockInvalidatorClient({ vi });
client.mocks.getStatus.mockResolvedValue({ paused: true, … });

// 3. Test provider wrapper
const { TestProvider, queryClient, runtime } = createTestProvider({ client });
render(<MyComponent />, { wrapper: TestProvider });

// 4. Trigger invalidation without SSE
await simulateInvalidation(runtime, {
  tags: [appTags.todos.list()],
  scopeKey: "global",
});

import {
  QueryTagsDevtoolsPanel,
  QueryTagsDevtools,
  queryTagsPlugin,
  useDevtoolsStore,
  createDevtoolsAdapter,
} from "@tanstack-tools/query-tags/devtools";

// As a TanStack Query DevTools plugin
<TanStackQueryDevtools plugins={[queryTagsPlugin]} />

// As a standalone floating widget
<QueryTagsDevtools position="bottom-right" initialOpen={false} />

// As an embedded panel
<QueryTagsDevtoolsPanel theme="dark" />

// Access store state programmatically
const { debugState, setActiveTab, setTheme } = useDevtoolsStore();