feat(tanstack-query): define base options and interceptors via contract meta by dinwwwh · Pull Request #1705 · middleapi/orpc

dinwwwh · 2026-07-21T11:20:26Z

Summary

Define base TanStack Query options and interceptors directly on a procedure contract via tanstackQuery, and apply them automatically with the new ContractOptionsUtilsPlugin.

export const contract = {
  planet: {
    find: oc
      .input(z.object({ id: z.number() }))
      .meta(tanstackQuery({
        queryOptions: {
          staleTime: 60 * 1000,
        },
      })),
  },
}

const orpc = createTanstackQueryUtils(client, {
  plugins: [new ContractOptionsUtilsPlugin(contract)],
})

tanstackQuery infers input, output, and error types from the contract, supports all procedure utils options (keys, options, interceptors), and merges when applied multiple times
ContractOptionsUtilsPlugin applies meta options as the base layer: utils level options override them and utils interceptors run after meta interceptors
Merging is consistent across all layers: interceptors concatenate, plain option objects spread-merge, and function modifiers compose
getTanstackQueryMeta reads the stored options for custom integrations
Docs cover the plugin, the reference-only nature of contract types, and passing runtime values such as router utils through mutation meta

vercel · 2026-07-21T11:20:32Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
orpc	Ready	Preview, Comment	Jul 23, 2026 2:56pm

pkg-pr-new · 2026-07-21T11:22:41Z

More templates

@orpc/ai-sdk

npm i https://pkg.pr.new/middleapi/orpc/@orpc/ai-sdk@1705

@orpc/arktype

npm i https://pkg.pr.new/middleapi/orpc/@orpc/arktype@1705

@orpc/bun

npm i https://pkg.pr.new/middleapi/orpc/@orpc/bun@1705

@orpc/client

npm i https://pkg.pr.new/middleapi/orpc/@orpc/client@1705

@orpc/cloudflare

npm i https://pkg.pr.new/middleapi/orpc/@orpc/cloudflare@1705

@orpc/contract

npm i https://pkg.pr.new/middleapi/orpc/@orpc/contract@1705

@orpc/experimental-effect

npm i https://pkg.pr.new/middleapi/orpc/@orpc/experimental-effect@1705

@orpc/evlog

npm i https://pkg.pr.new/middleapi/orpc/@orpc/evlog@1705

@orpc/json-schema

npm i https://pkg.pr.new/middleapi/orpc/@orpc/json-schema@1705

@orpc/nest

npm i https://pkg.pr.new/middleapi/orpc/@orpc/nest@1705

@orpc/next

npm i https://pkg.pr.new/middleapi/orpc/@orpc/next@1705

@orpc/openapi

npm i https://pkg.pr.new/middleapi/orpc/@orpc/openapi@1705

@orpc/opentelemetry

npm i https://pkg.pr.new/middleapi/orpc/@orpc/opentelemetry@1705

@orpc/pinia-colada

npm i https://pkg.pr.new/middleapi/orpc/@orpc/pinia-colada@1705

@orpc/pino

npm i https://pkg.pr.new/middleapi/orpc/@orpc/pino@1705

@orpc/publisher

npm i https://pkg.pr.new/middleapi/orpc/@orpc/publisher@1705

@orpc/ratelimit

npm i https://pkg.pr.new/middleapi/orpc/@orpc/ratelimit@1705

@orpc/server

npm i https://pkg.pr.new/middleapi/orpc/@orpc/server@1705

@orpc/shared

npm i https://pkg.pr.new/middleapi/orpc/@orpc/shared@1705

@orpc/tanstack-query

npm i https://pkg.pr.new/middleapi/orpc/@orpc/tanstack-query@1705

@orpc/trpc

npm i https://pkg.pr.new/middleapi/orpc/@orpc/trpc@1705

@orpc/valibot

npm i https://pkg.pr.new/middleapi/orpc/@orpc/valibot@1705

@orpc/zod

npm i https://pkg.pr.new/middleapi/orpc/@orpc/zod@1705

commit: 4f0bbc8

codecov · 2026-07-21T11:24:30Z

Codecov Report

❌ Patch coverage is 96.66667% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/tanstack-query/src/procedure-utils.ts	90.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

codspeed-hq · 2026-07-21T11:25:40Z

Merging this PR will not alter performance

✅ 18 untouched benchmarks

_{Comparing dinwwwh:claude/tanstack-query-meta-plugin-edfe5e (4f0bbc8) with main (fb2b8d2)}

pullfrog

ℹ️ No critical issues — one minor API-surface note inline.

Reviewed changes — added tanstackQueryMeta, getTanstackQueryMeta, and ContractMetaPlugin so base TanStack Query options and interceptors can be defined on a procedure contract and applied automatically as the default layer under utils options.

packages/tanstack-query/src/meta.ts — introduces the tanstackQueryMeta contract meta plugin, getTanstackQueryMeta reader, and ContractMetaPlugin router utils plugin.
packages/tanstack-query/src/procedure-utils.ts — adds mergeProcedureUtilsOptions/mergeProcedureUtilsModifier so option modifiers spread-merge and interceptors concatenate across layers.
packages/tanstack-query/src/router-utils.ts — switches global/scoped per-procedure option merging to mergeProcedureUtilsOptions to keep semantics consistent.
packages/tanstack-query/src/index.ts — exports the new ./meta module and now also exports ./plugin.
Tests and docs — adds meta.test.ts/meta.test-d.ts, updates the router-utils.test.ts mock, and documents the contract meta plugin.

^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

pullfrog · 2026-07-21T11:31:52Z

Heads-up: the inline suggestion in my review on packages/tanstack-query/src/index.ts was malformed — the suggested replacement included extra lines by mistake. Please ignore that suggestion entirely.

The actual feedback is just a nit: export * from './plugin' now also makes CompositeRouterUtilsPlugin public. If that class is meant to stay internal, consider scoping the export to RouterUtilsPlugin only or marking CompositeRouterUtilsPlugin as @internal. Everything else looks good to merge.

^{｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

…ilsPlugin

…ptionsUtilsPlugin

…ion meta

…example

…ptions

…ery-meta-plugin-edfe5e # Conflicts: # packages/tanstack-query/src/procedure-utils.ts # packages/tanstack-query/src/router-utils.test.ts # packages/tanstack-query/src/router-utils.ts

pullfrog

ℹ️ One minor suggestion inline.

Reviewed changes — adds tanstackQuery for defining base TanStack Query options/interceptors on procedure contracts, and ContractOptionsUtilsPlugin for applying them automatically via the plugin system. Also refactors router-utils.ts to use a shared mergeProcedureUtilsOptions helper with consistent spread-merge composition semantics.

Add tanstackQuery contract meta plugin — stores ProcedureUtilsOptions under ~tanstack-query in procedure meta, supports multi-layer merging with interceptor concatenation and modifier composition.
Add ContractOptionsUtilsPlugin — walks the contract by path via getRouterContract and merges stored meta as the base layer under scoped/global utils options.
Refactor interceptor merging — extract mergeProcedureUtilsOptions and mergeProcedureUtilsModifier in procedure-utils.ts, use them in both tanstackQuery accumulation and router-utils.ts scoped-options merge.
Export RouterUtilsPlugin interface — ./plugin module is now part of the public API, enabling custom plugin implementations.
Tests and type tests — unit tests for storage, merging, function composition, router propagation, and end-to-end createRouterUtils flow. Type tests verify contract type inference.

^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

pullfrog · 2026-07-23T15:00:35Z

 export * from './contract-utils'
 export * from './key'
+export * from './meta'
+export * from './plugin'


ℹ️ export * from './plugin' now makes CompositeRouterUtilsPlugin part of the public API. It's an internal composition primitive that users shouldn't need to construct directly — they pass plain plugin arrays to createTanstackQueryUtils. Consider exporting only RouterUtilsPlugin explicitly or marking CompositeRouterUtilsPlugin with @internal in its JSDoc.

feat(tanstack-query): contract meta for base query/mutation options

b1f8615

vercel Bot deployed to Preview July 21, 2026 11:22 View deployment

pullfrog Bot reviewed Jul 21, 2026

View reviewed changes

Comment thread packages/tanstack-query/src/index.ts

dinwwwh marked this pull request as draft July 21, 2026 12:07

refactor(tanstack-query): rename tanstackQueryMeta to tanstackQuery

93e0cca

vercel Bot deployed to Preview July 23, 2026 12:16 View deployment

refactor(tanstack-query): rename ContractMetaPlugin to ContractMetaUt…

6ffba85

…ilsPlugin

vercel Bot deployed to Preview July 23, 2026 13:12 View deployment

refactor(tanstack-query): rename ContractMetaUtilsPlugin to ContractO…

4f2cb5b

…ptionsUtilsPlugin

vercel Bot deployed to Preview July 23, 2026 13:19 View deployment

dinwwwh added 2 commits July 23, 2026 20:23

docs(tanstack-query): note contract meta types are reference only

9eba6d6

docs(tanstack-query): avoid em dash in contract options warning

0f6dc8f

vercel Bot deployed to Preview July 23, 2026 13:27 View deployment

docs(tanstack-query): advanced example passing router utils via mutat…

90c85ba

…ion meta

vercel Bot deployed to Preview July 23, 2026 13:33 View deployment

docs(tanstack-query): generalize contract meta runtime values example

6bc8639

vercel Bot deployed to Preview July 23, 2026 13:36 View deployment

docs(tanstack-query): demonstrate optimistic update in contract meta …

fa9ee24

…example

vercel Bot deployed to Preview July 23, 2026 13:39 View deployment

feat(tanstack-query): compose function modifiers when merging utils o…

0783c2f

…ptions

vercel Bot deployed to Preview July 23, 2026 14:01 View deployment

docs(tanstack-query): remove merging behavior info block

3b1f5ca

vercel Bot deployed to Preview July 23, 2026 14:03 View deployment

Merge remote-tracking branch 'middleapi/main' into claude/tanstack-qu…

4f0bbc8

…ery-meta-plugin-edfe5e # Conflicts: # packages/tanstack-query/src/procedure-utils.ts # packages/tanstack-query/src/router-utils.test.ts # packages/tanstack-query/src/router-utils.ts

dinwwwh changed the title ~~feat(tanstack-query): contract meta for base query/mutation options~~ feat(tanstack-query): define base options and interceptors via contract meta Jul 23, 2026

dinwwwh marked this pull request as ready for review July 23, 2026 14:56

vercel Bot deployed to Preview July 23, 2026 14:56 View deployment

pullfrog Bot reviewed Jul 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(tanstack-query): define base options and interceptors via contract meta#1705

feat(tanstack-query): define base options and interceptors via contract meta#1705
dinwwwh wants to merge 12 commits into
middleapi:mainfrom
dinwwwh:claude/tanstack-query-meta-plugin-edfe5e

dinwwwh commented Jul 21, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

codspeed-hq Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

pullfrog Bot left a comment

Uh oh!

Uh oh!

pullfrog Bot commented Jul 21, 2026

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

dinwwwh commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

vercel Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codspeed-hq Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pullfrog Bot commented Jul 21, 2026

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

pullfrog Bot Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dinwwwh commented Jul 21, 2026 •

edited

Loading

vercel Bot commented Jul 21, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 21, 2026 •

edited

Loading

codecov Bot commented Jul 21, 2026 •

edited

Loading

codspeed-hq Bot commented Jul 21, 2026 •

edited

Loading