@tanstack/query-core 5.90.20: dehydrate

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 dehydrate in pkg:npm/%40tanstack/query-core@5.90.20
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40tanstack/query-core@5.90.20
Demonstrate these symbols/APIs:
  - dehydrate

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:af455faa8bb771458962adddaa9edf0d2e25e6f65110032ebde52bb88a8e5f56","contract":["dehydrate extracts successful queries from QueryClient into DehydratedState","defaultShouldDehydrateQuery excludes pending and failed queries by default","shouldDehydrateQuery option enables custom filtering of queries during dehydration","serializeData option transforms query data before storing in dehydrated state","dehydrate includes paused mutations and omits active mutations by default","hydrate restores dehydrated queries and data into a target QueryClient","dehydrate preserves query meta on dehydrated query records"],"goal":"verify dehydrate in pkg:npm/%40tanstack/query-core@5.90.20","kind":"HOW","packages":["pkg:npm/%40tanstack/query-core@5.90.20"],"schemaVersion":1,"symbols":["dehydrate"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","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.90.20"],"schemaVersion":1,"subject":"pkg:npm/%40tanstack/query-core@5.90.20","symbols":["dehydrate"],"verifierAdapter":"node-typescript@1"}

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

{
  "name": "sample-query-core-dehydrate",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@tanstack/query-core": "5.90.20"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify dehydrate in pkg:npm/%40tanstack/query-core@5.90.20",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40tanstack/query-core@5.90.20"
  ],
  "symbols": [
    "dehydrate"
  ]
}

import {
  QueryClient,
  dehydrate,
  hydrate,
  defaultShouldDehydrateQuery,
  defaultShouldDehydrateMutation,
} from '@tanstack/query-core';

/**
 * Creates a QueryClient preconfigured for server-side dehydration.
 * @param {object} [defaultOptions] Default query options.
 * @returns {QueryClient}
 */
export function createServerQueryClient(defaultOptions = {}) {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 1000 * 60,
        ...defaultOptions.queries,
      },
      ...defaultOptions,
    },
  });
}

/**
 * Dehydrates the state of a QueryClient with optional custom filters or serializers.
 * @param {QueryClient} client
 * @param {object} [options]
 * @returns {object} Dehydrated state containing queries and mutations
 */
export function dehydrateClient(client, options) {
  return dehydrate(client, options);
}

/**
 * Restores dehydrated state into a target QueryClient.
 * @param {QueryClient} client
 * @param {object} dehydratedState
 * @param {object} [options]
 */
export function hydrateClient(client, dehydratedState, options) {
  hydrate(client, dehydratedState, options);
}

export {
  QueryClient,
  dehydrate,
  hydrate,
  defaultShouldDehydrateQuery,
  defaultShouldDehydrateMutation,
};

export default dehydrate;

import assert from 'node:assert/strict';
import {
  QueryClient,
  dehydrate,
  hydrate,
  defaultShouldDehydrateQuery,
  defaultShouldDehydrateMutation,
} from '@tanstack/query-core';
import {
  createServerQueryClient,
  dehydrateClient,
  hydrateClient,
} from '../src/index.mjs';

// 1. dehydrate extracts successful queries from QueryClient into DehydratedState
{
  const client = new QueryClient();
  client.setQueryData(['items', 1], { id: 1, title: 'Sample Item' });

  const dehydrated = dehydrate(client);
  assert.ok(Array.isArray(dehydrated.queries), 'queries should be an array');
  assert.ok(Array.isArray(dehydrated.mutations), 'mutations should be an array');
  assert.equal(dehydrated.queries.length, 1);

  const query = dehydrated.queries[0];
  assert.deepEqual(query.queryKey, ['items', 1]);
  assert.deepEqual(query.state.data, { id: 1, title: 'Sample Item' });
  assert.equal(typeof query.queryHash, 'string');
  assert.equal(typeof query.dehydratedAt, 'number');

  // Also test helper function dehydrateClient
  const helperDehydrated = dehydrateClient(client);
  assert.equal(helperDehydrated.queries.length, 1);
  assert.deepEqual(helperDehydrated.queries[0].queryKey, ['items', 1]);
}

// 2. defaultShouldDehydrateQuery excludes pending and failed queries by default
{
  const client = createServerQueryClient();
  client.setQueryData(['success-item'], 'valid payload');

  await client.prefetchQuery({
    queryKey: ['error-item'],
    queryFn: () => Promise.reject(new Error('simulated network error')),
    retry: false,
  }).catch(() => {});

  let resolvePending;
  const pendingPromise = new Promise((res) => { resolvePending = res; });
  client.prefetchQuery({
    queryKey: ['pending-item'],
    queryFn: () => pendingPromise,
    retry: false,
  });

  const cache = client.getQueryCache();
  const successQuery = cache.find({ queryKey: ['success-item'] });
  const errorQuery = cache.find({ queryKey: ['error-item'] });
  const pendingQuery = cache.find({ queryKey: ['pending-item'] });

  assert.equal(defaultShouldDehydrateQuery(successQuery), true);
  assert.equal(defaultShouldDehydrateQuery(errorQuery), false);
  assert.equal(defaultShouldDehydrateQuery(pendingQuery), false);

  const dehydrated = dehydrate(client);
  assert.equal(dehydrated.queries.length, 1);
  assert.deepEqual(dehydrated.queries[0].queryKey, ['success-item']);

  resolvePending('resolved');
}

// 3. shouldDehydrateQuery option enables custom filtering of queries during dehydration
{
  const client = new QueryClient();
  client.setQueryData(['public', 'settings'], { theme: 'dark' });
  client.setQueryData(['private', 'session'], { token: 'secret-token' });

  const dehydrated = dehydrate(client, {
    shouldDehydrateQuery: (query) => query.queryKey[0] === 'public',
  });

  assert.equal(dehydrated.queries.length, 1);
  assert.deepEqual(dehydrated.queries[0].queryKey, ['public', 'settings']);
  assert.deepEqual(dehydrated.queries[0].state.data, { theme: 'dark' });
}

// 4. serializeData option transforms query data before storing in dehydrated state
{
  const client = new QueryClient();
  const timestamp = new Date('2026-09-03T00:00:00.000Z');
  client.setQueryData(['timestamp-entry'], { recordedAt: timestamp });

  const dehydrated = dehydrate(client, {
    serializeData: (data) => {
      if (data && data.recordedAt instanceof Date) {
        return { recordedAt: data.recordedAt.toISOString() };
      }
      return data;
    },
  });

  assert.equal(dehydrated.queries.length, 1);
  assert.deepEqual(dehydrated.queries[0].state.data, {
    recordedAt: '2026-09-03T00:00:00.000Z',
  });
}

// 5. dehydrate includes paused mutations and omits active mutations by default
{
  const client = new QueryClient();

  // Paused mutation (e.g. offline mutation waiting to sync)
  const pausedMutation = client.getMutationCache().build(client, {
    mutationKey: ['sync-post', 1],
  }, {
    context: undefined,
    data: undefined,
    error: null,
    failureCount: 0,
    failureReason: null,
    isPaused: true,
    status: 'pending',
    variables: { title: 'Draft Post' },
    submittedAt: Date.now(),
  });

  // Active mutation
  const activeMutation = client.getMutationCache().build(client, {
    mutationKey: ['sync-post', 2],
  }, {
    context: undefined,
    data: undefined,
    error: null,
    failureCount: 0,
    failureReason: null,
    isPaused: false,
    status: 'pending',
    variables: { title: 'Active Post' },
    submittedAt: Date.now(),
  });

  assert.equal(defaultShouldDehydrateMutation(pausedMutation), true);
  assert.equal(defaultShouldDehydrateMutation(activeMutation), false);

  const dehydrated = dehydrate(client);
  assert.equal(dehydrated.mutations.length, 1);
  assert.deepEqual(dehydrated.mutations[0].mutationKey, ['sync-post', 1]);
}

// 6. hydrate restores dehydrated queries and data into a target QueryClient
{
  const sourceClient = new QueryClient();
  sourceClient.setQueryData(['items', 'list'], [10, 20, 30]);

  const dehydrated = dehydrate(sourceClient);

  const targetClient = new QueryClient();
  hydrateClient(targetClient, dehydrated);

  const restoredData = targetClient.getQueryData(['items', 'list']);
  assert.deepEqual(restoredData, [10, 20, 30]);

  const restoredQuery = targetClient.getQueryCache().find({ queryKey: ['items', 'list'] });
  assert.ok(restoredQuery, 'query should exist in target cache');
  assert.equal(restoredQuery.state.status, 'success');
  assert.equal(restoredQuery.state.fetchStatus, 'idle');
}

// 7. dehydrate preserves query meta on dehydrated query records
{
  const client = new QueryClient();
  await client.prefetchQuery({
    queryKey: ['meta-sample'],
    queryFn: () => ({ status: 'ready' }),
    meta: { scope: 'public', version: 2 },
  });

  const dehydrated = dehydrate(client);
  assert.equal(dehydrated.queries.length, 1);
  assert.deepEqual(dehydrated.queries[0].meta, { scope: 'public', version: 2 });
}

console.log('Contract tests passed successfully.');