feat(tanstack-query): prefix option to avoid key conflicts

[dinwwwh]

Summary

Prefer prefix over path to avoiding conflict keys in @orpc/tanstack-query

const userORPC = createTanstackQueryUtils(userClient, {
  prefix: 'user'
})

const postORPC = createTanstackQueryUtils(postClient, {
  prefix: 'post'
})

userORPC.planet.find.queryKey({ input: { id: 1 } })
// ['user', ['planet', 'find'], { type: 'query', input: { id: 1 } }]

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
orpc	Ready	Preview, Comment	Jul 20, 2026 3:35am

[codspeed-hq]

Merging this PR will not alter performance

✅ 18 untouched benchmarks

---

_{Comparing dinwwwh:claude/pinia-colada-path-to-prefix-bdae9a (c65dc84) with main (652a5e8)}

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/arktype

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

@orpc/bun

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

@orpc/client

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

@orpc/cloudflare

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

@orpc/contract

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

@orpc/experimental-effect

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

@orpc/evlog

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

@orpc/json-schema

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

@orpc/nest

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

@orpc/next

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

@orpc/openapi

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

@orpc/opentelemetry

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

@orpc/pinia-colada

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

@orpc/pino

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

@orpc/publisher

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

@orpc/ratelimit

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

@orpc/server

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

@orpc/shared

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

@orpc/tanstack-query

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

@orpc/trpc

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

@orpc/valibot

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

@orpc/zod

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

commit: c65dc84

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pullfrog]

✅ No new issues found.

Reviewed changes — the replacement of path with prefix in @orpc/tanstack-query, aligning key generation with @orpc/pinia-colada.

• RouterUtilsOptions.path is replaced by prefix?: string via OperationKeyPrefixOptions.
• generateOperationKey now prepends the prefix as a separate tuple element.
• ProcedureUtilsOptions carries the prefix and every key method passes it through.
• createRouterUtils gains an optional positional path parameter used internally by contract utils to keep procedure meta.path rooting.
• Tests and docs are updated; vitest and tsc pass for @orpc/tanstack-query.

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

[pullfrog]

Caution

The latest commit hides the internal base-path parameter from the public createRouterUtils signature, but two call sites still rely on passing it. This produces a TypeScript error and a failing test, and at runtime contract utils would be rooted at the wrong path.

Reviewed changes — since the prior review, the public createRouterUtils signature was trimmed to hide the internal base-path parameter, and key-related types were relocated from types.ts to key.ts.

• Hid the base-path parameter from createRouterUtils by moving routing recursion through an internal createRouterUtilsInternal helper.
• Moved OperationKey* types from types.ts into key.ts and updated imports across procedure-utils.ts, router-utils.ts, and contract-utils.ts.
• Updated tests and docs to reflect the new prefix-only public API.

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

[pullfrog]

Caution

The latest commit removes the public base-path tests, but the underlying TS2554 type error and runtime path bug it exposed are still present.

Reviewed changes — latest commit removed the now-invalid public base-path test and the @ts-expect-error case for the removed path option.

• Removed the roots utils at the given base path unit test and the path: ['base'] type-test case.

🚨 Contract utils still pass a base path that createRouterUtils no longer accepts

Removing the failing tests is correct for the public API, but packages/tanstack-query/src/contract-utils.ts still passes the procedure's meta.path as the third argument to createRouterUtils. That exported signature only accepts (client, options), so pnpm --filter @orpc/tanstack-query type:check still reports src/contract-utils.ts(63,8): error TS2554: Expected 1-2 arguments, but got 3.

At runtime the extra argument is ignored, so contract utils are rooted at [] instead of the procedure path. This still needs an internal helper that can carry the base path without exposing it publicly.

Technical details

# Contract utils still pass a base path that `createRouterUtils` no longer accepts

## Affected sites
- `packages/tanstack-query/src/contract-utils.ts:60-63` — passes `path` as the third argument; produces the typecheck error and a runtime root mismatch.

## Required outcome
- `contract-utils.ts` (and any other internal caller) must be able to supply a base path to the router-utils recursion without making it part of the public `createRouterUtils` signature.

## Suggested approach
- Export a package-private helper from `router-utils.ts` (for example, `createRouterUtilsWithPath`) that accepts the base path and delegates to `createRouterUtilsInternal`, or have `contract-utils.ts` import and call `createRouterUtilsInternal` directly.
- Keep the public `createRouterUtils` signature as `(client, options)`.

## Open questions for the human
- None — the fix is mechanical.

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

[pullfrog]

✅ No new issues found.

Reviewed changes — the latest commit resolves the contract-utils base-path routing issue flagged in the prior review by passing the procedure's meta.path inside the RouterUtilsOptions object and merging it with any existing base path.

• createContractUtilsFactory now combines options.path with the procedure's meta.path and passes the merged path to createRouterUtils, so contract utils are rooted at the correct base path.
• The contract-utils unit tests were updated to include a base path and assert the merged path flows into createRouterUtils.
• createRouterUtils retains the base path as an @internal option while keeping its public signature as (client, options).

pnpm vitest run packages/tanstack-query/src/ and pnpm --filter @orpc/tanstack-query type:check pass.

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