@tanstack/query-core 5.67.1: QueryClient

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @tanstack/query-core.QueryClient in pkg:npm/%40tanstack/query-core@5.67.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40tanstack/query-core@5.67.1
Demonstrate these symbols/APIs:
  - @tanstack/query-core.QueryClient
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:d16319c85f0ed281d96617ea775c033f7e06d0da228ccd890eaf1dbf39b162e3","constraints":{"executionContext":"node"},"contract":["assert QueryClient ensureQueryData returns cached data without calling queryFn when data exists, or executes queryFn when missing","assert QueryClient setQueryData treats an updater function returning undefined as a no-op bailout","assert QueryClient cancelQueries aborts in-flight query execution via AbortSignal","assert QueryClient getQueriesData and setQueriesData batch inspect and update matching cached queries","assert QueryClient setQueryDefaults and getQueryDefaults manage defaults by prefix and return empty object for unmatched keys","assert QueryClient resetQueries restores matching queries to pending status and clears cached data"],"goal":"verify @tanstack/query-core.QueryClient in pkg:npm/%40tanstack/query-core@5.67.1","kind":"HOW","packages":["pkg:npm/%40tanstack/query-core@5.67.1"],"schemaVersion":1,"symbols":["@tanstack/query-core.QueryClient"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40tanstack/query-core@5.67.1"],"schemaVersion":1,"subject":"pkg:npm/%40tanstack/query-core@5.67.1","symbols":["@tanstack/query-core.QueryClient"],"verifierAdapter":"node-typescript@1"}

import { QueryClient } from '@tanstack/query-core';

/**
 * Creates and configures a QueryClient instance.
 * @param {object} [options]
 * @returns {QueryClient}
 */
export function createQueryClient(options) {
  return new QueryClient(options);
}

/**
 * Ensures query data exists in cache by returning cached data or executing queryFn.
 * @param {QueryClient} client
 * @param {object} options
 * @returns {Promise<any>}
 */
export async function ensureQueryData(client, options) {
  return client.ensureQueryData(options);
}

/**
 * Sets query data in cache with support for functional updater and bailout.
 * @param {QueryClient} client
 * @param {Array<any>} queryKey
 * @param {any} updater
 * @returns {any}
 */
export function setQueryData(client, queryKey, updater) {
  return client.setQueryData(queryKey, updater);
}

/**
 * Cancels in-flight queries matching queryKey filter.
 * @param {QueryClient} client
 * @param {object} [filters]
 * @returns {Promise<void>}
 */
export async function cancelQueries(client, filters) {
  return client.cancelQueries(filters);
}

/**
 * Retrieves all cached query key-value pairs matching a filter prefix.
 * @param {QueryClient} client
 * @param {object} [filters]
 * @returns {Array<[Array<any>, any]>}
 */
export function getQueriesData(client, filters) {
  return client.getQueriesData(filters);
}

/**
 * Batch updates cached query values matching a filter prefix.
 * @param {QueryClient} client
 * @param {object} filters
 * @param {Function} updater
 * @returns {Array<[Array<any>, any]>}
 */
export function setQueriesData(client, filters, updater) {
  return client.setQueriesData(filters, updater);
}

/**
 * Sets default options for queries matching a key prefix.
 * @param {QueryClient} client
 * @param {Array<any>} queryKey
 * @param {object} options
 * @returns {void}
 */
export function setQueryDefaults(client, queryKey, options) {
  return client.setQueryDefaults(queryKey, options);
}

/**
 * Gets configured default options matching a query key.
 * @param {QueryClient} client
 * @param {Array<any>} queryKey
 * @returns {object}
 */
export function getQueryDefaults(client, queryKey) {
  return client.getQueryDefaults(queryKey);
}

/**
 * Resets matching query state in cache.
 * @param {QueryClient} client
 * @param {object} [filters]
 * @returns {Promise<void>}
 */
export async function resetQueries(client, filters) {
  return client.resetQueries(filters);
}

export { QueryClient };
export default QueryClient;

{
  "name": "sample-query-core-queryclient",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-query-core-queryclient",
      "version": "1.0.0",
      "dependencies": {
        "@tanstack/query-core": "5.67.1"
      }
    },
    "node_modules/@tanstack/query-core": {
      "version": "5.67.1",
      "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.67.1.tgz",
      "integrity": "sha512-AkFmuukVejyqVIjEQoFhLb3q+xHl7JG8G9cANWTMe3s8iKzD9j1VBSYXgCjy6vm6xM8cUCR9zP2yqWxY9pTWOA==",
      "license": "MIT",
      "funding": {
        "type": "github",
        "url": "https://github.com/sponsors/tannerlinsley"
      }
    }
  }
}

{
  "name": "sample-query-core-queryclient",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@tanstack/query-core": "5.67.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @tanstack/query-core.QueryClient in pkg:npm/%40tanstack/query-core@5.67.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40tanstack/query-core@5.67.1"
  ],
  "symbols": [
    "@tanstack/query-core.QueryClient"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert/strict';
import {
  QueryClient,
  createQueryClient,
  ensureQueryData,
  setQueryData,
  cancelQueries,
  getQueriesData,
  setQueriesData,
  setQueryDefaults,
  getQueryDefaults,
  resetQueries,
} from '../index.mjs';

// Contract 1: QueryClient ensureQueryData returns cached data without calling queryFn when data exists, or executes queryFn when missing
{
  const client = createQueryClient();
  let fnCalls = 0;
  const options = {
    queryKey: ['item', 1],
    queryFn: async () => {
      fnCalls++;
      return { id: 1, name: 'First' };
    },
  };

  // Missing in cache -> runs queryFn and caches result
  const result1 = await ensureQueryData(client, options);
  assert.deepStrictEqual(result1, { id: 1, name: 'First' });
  assert.strictEqual(fnCalls, 1);

  // Invalidate query to mark it stale
  await client.invalidateQueries({ queryKey: ['item', 1] });
  const query = client.getQueryCache().find({ queryKey: ['item', 1] });
  assert.strictEqual(query.isStale(), true);

  // Cached data exists (even if stale) -> returns cached data, queryFn is not invoked again
  const result2 = await ensureQueryData(client, options);
  assert.deepStrictEqual(result2, { id: 1, name: 'First' });
  assert.strictEqual(fnCalls, 1);
}

// Contract 2: QueryClient setQueryData treats an updater function returning undefined as a no-op bailout
{
  const client = createQueryClient();
  setQueryData(client, ['config'], { theme: 'dark' });
  assert.deepStrictEqual(client.getQueryData(['config']), { theme: 'dark' });

  // Updater returning undefined acts as a no-op bailout
  setQueryData(client, ['config'], () => undefined);
  assert.deepStrictEqual(client.getQueryData(['config']), { theme: 'dark' });

  // Normal updater modifies the cached value
  setQueryData(client, ['config'], (prev) => ({ ...prev, theme: 'light' }));
  assert.deepStrictEqual(client.getQueryData(['config']), { theme: 'light' });
}

// Contract 3: QueryClient cancelQueries aborts in-flight query execution via AbortSignal
{
  const client = createQueryClient();
  let aborted = false;
  let signalReceived = false;

  const fetchPromise = client.fetchQuery({
    queryKey: ['task'],
    queryFn: async ({ signal }) => {
      signalReceived = !!signal;
      signal.addEventListener('abort', () => {
        aborted = true;
      });
      await new Promise((resolve) => setTimeout(resolve, 300));
      return 'done';
    },
  }).catch(() => 'cancelled');

  await new Promise((resolve) => setTimeout(resolve, 30));
  assert.strictEqual(client.isFetching({ queryKey: ['task'] }), 1);

  await cancelQueries(client, { queryKey: ['task'] });
  assert.strictEqual(signalReceived, true);
  assert.strictEqual(aborted, true);
  await fetchPromise;
}

// Contract 4: QueryClient getQueriesData and setQueriesData batch inspect and update matching cached queries
{
  const client = createQueryClient();
  setQueryData(client, ['todos', 1], { text: 'read docs', done: false });
  setQueryData(client, ['todos', 2], { text: 'write test', done: false });
  setQueryData(client, ['posts', 1], { title: 'intro', done: false });

  const todos = getQueriesData(client, { queryKey: ['todos'] });
  assert.strictEqual(todos.length, 2);
  assert.deepStrictEqual(todos.map(([k]) => k), [['todos', 1], ['todos', 2]]);

  setQueriesData(client, { queryKey: ['todos'] }, (old) => (old ? { ...old, done: true } : old));
  assert.strictEqual(client.getQueryData(['todos', 1]).done, true);
  assert.strictEqual(client.getQueryData(['todos', 2]).done, true);
  assert.strictEqual(client.getQueryData(['posts', 1]).done, false);
}

// Contract 5: QueryClient setQueryDefaults and getQueryDefaults manage defaults by prefix and return empty object for unmatched keys
{
  const client = createQueryClient();
  setQueryDefaults(client, ['users'], { staleTime: 60000, gcTime: 120000 });

  const defaults = getQueryDefaults(client, ['users', 42]);
  assert.strictEqual(defaults.staleTime, 60000);
  assert.strictEqual(defaults.gcTime, 120000);

  const unmatched = getQueryDefaults(client, ['other', 1]);
  assert.deepStrictEqual(unmatched, {});
}

// Contract 6: QueryClient resetQueries restores matching queries to pending status and clears cached data
{
  const client = createQueryClient();
  let fetchCount = 0;
  const options = {
    queryKey: ['counter'],
    queryFn: async () => {
      fetchCount++;
      return { count: fetchCount };
    },
  };

  await client.fetchQuery(options);
  assert.strictEqual(client.getQueryData(['counter']).count, 1);

  await resetQueries(client, { queryKey: ['counter'] });
  const state = client.getQueryState(['counter']);
  assert.strictEqual(state.data, undefined);
  assert.strictEqual(state.status, 'pending');
}

console.log('All QueryClient contract assertions passed.');