feat(tanstack-query): support defaults factory

[lyzno1]

Fixes #1569.

This lets experimental_defaults take a function in addition to the existing object form:

createTanstackQueryUtils(client, {
  experimental_defaults: utils => ({
    planet: {
      create: {
        mutationOptions: {
          onSuccess: (_, __, ___, ctx) => {
            ctx.client.invalidateQueries({
              queryKey: utils.planet.key(),
            })
          },
        },
      },
    },
  }),
})

The goal is to keep procedure-level server-state defaults close to the router while avoiding a self-reference to the outer orpc variable. The object form keeps working, and defaults still use the existing shallow merge behavior.

Summary by CodeRabbit

• New Features

  • experimental_defaults parameter now accepts either an object or a factory function for dynamic configuration.

• Documentation

  • Updated integration guide with expanded guidance on using defaults with mutation side effects, including examples using generated query keys. Added clarification on shallow merge behavior and callback override semantics.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f6536068-c1f7-4742-a629-143f044361cb

📥 Commits

Reviewing files that changed from the base of the PR and between 81b6cfe and 3bdfe9a.

📒 Files selected for processing (4)

• apps/content/docs/integrations/tanstack-query.md
• packages/tanstack-query/src/router-utils.test-d.ts
• packages/tanstack-query/src/router-utils.test.ts
• packages/tanstack-query/src/router-utils.ts

---

📝 Walkthrough

Walkthrough

This PR extends the TanStack Query integration to support function-based experimental_defaults, enabling defaults factories to receive a utils parameter with typed query/mutation key generators. This eliminates awkward self-references when configuring mutation side effects like query invalidation. The feature adds a union type, resolves factories up-front, updates nested utils derivation, and includes type and runtime tests plus documentation.

Changes

Function-based experimental_defaults

Layer / File(s)	Summary
Type contract and implementation packages/tanstack-query/src/router-utils.ts	experimental_RouterUtilsDefaultsOption<T> union type accepts object or function; createRouterUtils resolves factories up-front by calling them with the new utils instance, and passes resolved defaults into createProcedureUtils and nested utils derivation via get().
Type-level test validation packages/tanstack-query/src/router-utils.test-d.ts	Test factory-typed defaults with correct/incorrect input validation for utils.nested.ping.key, callback parameter type checking for mutationOptions.onSuccess, and return type verification.
Runtime test validation packages/tanstack-query/src/router-utils.test.ts	Test that factory is called once, produces planetDefaults forwarded into nested utils with correct path, and planetUtils mutation key matches expected behavior.
Documentation and examples apps/content/docs/integrations/tanstack-query.md	Show functional experimental_defaults form using utils => ... to reference generated keys; explain shallow merge semantics and callback override behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• middleapi/orpc#1260: Prior PR modified experimental_defaults propagation in createRouterUtils and nested utils; this extends that wiring to support factory functions.

Suggested labels

size:XL, javascript

Suggested reviewers

• dinwwwh

Poem

🐰 A factory of defaults springs to life,
No self-reference, no recursive strife!
Typed keys flow through the utils' hand,
Mutations invalid with grace so grand.
Shallow spreads and overrides true,
Your TanStack Query dreams come through! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(tanstack-query): support defaults factory' clearly and concisely summarizes the main change: adding factory function support for experimental_defaults in tanstack-query.
Linked Issues check	✅ Passed	The pull request fully implements the feature requested in issue #1569: supporting a function form for experimental_defaults that receives typed utils, while maintaining backward compatibility with the object form.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the defaults factory feature: documentation updates, type tests, runtime tests, and core implementation in router-utils.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a function form for experimental_defaults in createRouterUtils, allowing default configurations to dynamically reference generated query or mutation keys without self-reference issues. It updates the documentation to explain this new capability, adds corresponding type and unit tests, and refactors createRouterUtils to evaluate the defaults factory function when provided. There are no review comments, and I have no feedback to provide.

[coderabbitai]

Actionable comments posted: 0

[pullfrog]

Reviewed changes — Adds a factory-function form for experimental_defaults in createTanstackQueryUtils, allowing cache-invalidation patterns that reference generated keys without a self-referencing outer variable. The object form remains fully supported and defaults still shallow-merge as before.

• experimental_RouterUtilsDefaultsOption<T> — new union type exported from router-utils.ts.
• createRouterUtils runtime — resolves factory once at top level, then passes the resolved defaults object into createProcedureUtils and into recursive child calls.
• Tests — runtime test verifies the factory is called once and defaults propagate; type test verifies typed access to utils inside the factory.
• Docs — updated TanStack Query docs page with function-form example and a note about shallow-merge override behavior.

---

Note: 1 inline comment(s) dropped because they did not anchor to lines inside the PR diff:

• packages/tanstack-query/src/index.ts:4 (RIGHT) — file not in PR diff

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 ｜ 𝕏}

[pullfrog]

Reviewed changes — Adds a factory-function form for experimental_defaults in createTanstackQueryUtils, allowing cache-invalidation patterns that reference generated keys without a self-referencing outer variable. The object form remains fully supported and defaults still shallow-merge as before.

• experimental_RouterUtilsDefaultsOption<T> — new union type exported from router-utils.ts.
• createRouterUtils runtime — resolves factory once at top level, then passes the resolved defaults object into createProcedureUtils and into recursive child calls.
• Tests — runtime test verifies the factory is called once and defaults propagate; type test verifies typed access to utils inside the factory.
• Docs — updated TanStack Query docs page with function-form example and a note about shallow-merge override behavior.

---

Note: 1 inline comment(s) dropped because they did not anchor to lines inside the PR diff:

• packages/tanstack-query/src/index.ts:4 (RIGHT) — file not in PR diff

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 ｜ 𝕏}