refactor!: stop exporting internal-only APIs before v2 stable by dinwwwh · Pull Request #2326 · middleapi/orpc

dinwwwh · 2026-10-24T06:30:49Z

Removes internal-only helpers from the package entry points, so they can change freely after v2 is stable. Each removed symbol was checked to have no use in another workspace package, the docs, playgrounds, tests/ or benches/.

Removed exports (36)

Entry point	Removed
`@orpc/server`	`augmentRouter`, `AugmentRouterOptions` (type), `augmentImplementedRouter`, `AugmentImplementedRouterOptions` (type), `createRouterImplementer`, `decorateMiddleware`, `createGuardedProcedureLazy`, `createContractProcedure`, `withHiddenRouterContract`, `getHiddenRouterContract`, `cloneORPCError`, `reconcileORPCError`
`@orpc/server/standard`	`CompositeStandardHandlerPlugin`, `TracingHandlerPlugin`
`@orpc/client`	`resolveFriendlyClientOptions`
`@orpc/client/standard`	`CompositeStandardLinkPlugin`
`@orpc/contract`	`augmentContractRouter`, `HIDDEN_META_PLUGINS_SYMBOL`, `getAsyncIteratorObjectSchemaDetails`, `AsyncIteratorObjectSchemaDetails` (type)
`@orpc/openapi`	`isBodylessMethod`, `DEFAULT_OPENAPI_SUCCESS_DESCRIPTION`, `DEFAULT_OPENAPI_INPUT_STRUCTURE`, `DEFAULT_OPENAPI_OUTPUT_STRUCTURE`
`@orpc/openapi/standard`	`serializeHeaders`
`@orpc/tanstack-query`	`generateOperationKey`, `isProcedureUtilsOptions`, `CompositeRouterUtilsPlugin`, `serializableStreamedQuery`
`@orpc/pinia-colada`	`generateOperationKey`, `isProcedureUtilsOptions`, `CompositeRouterUtilsPlugin`, `serializableStreamedQuery`, `liveQuery`
`@orpc/swr`	`generateOperationKey`, `isSubsetOf`

cloneORPCError and reconcileORPCError are only dropped from @orpc/server's re-exports. Other packages import them from @orpc/client and @orpc/contract, so they stay exported there. Nothing new is exported, and no export changed between value and type-only. @orpc/shared is unchanged.

How it's done

Modules that mix public and internal symbols are now re-exported with explicit name lists in index.ts instead of export *. A new export added to one of these modules has to be added to its index.ts list to become public:
- @orpc/server: implementer-router, middleware-decorated, procedure-utils, router-utils
- @orpc/server/standard, @orpc/client/standard: plugin
- @orpc/client: utils
- @orpc/contract: router-utils, schema-built-in
- @orpc/openapi: constants, utils
- @orpc/tanstack-query, @orpc/pinia-colada: key, plugin, procedure-utils, shared-utils, stream-query
- @orpc/swr: key, procedure-utils, shared-utils
- @orpc/msw: http-procedure-utils
These modules are no longer re-exported at all: router-hidden (server), utils (@orpc/openapi/standard and @orpc/swr), live-query (pinia-colada).
TracingHandlerPlugin, HIDDEN_META_PLUGINS_SYMBOL, AugmentRouterOptions and AugmentImplementedRouterOptions are only used in their own file, so they lost the export keyword there.
The OpenAPI matcher test builds its contract-first router with implement(contract).router() instead of importing withHiddenRouterContract.
The @orpc/effect index test no longer asserts that internal helpers are not exported.

Kept on purpose

Adapter building blocks: StandardHandler, RPCMatcher, createStandardPeerRequestHandler, WebSocketHandler, WebSocketLinkTransport, …
The @orpc/json-schema utilities and the meta readers (getMcpToolMeta, getTanstackQueryMeta, …).
mergeProcedureUtilsOptions, for RouterUtilsPlugin authors.
Unique-symbol context keys that appear in public types.
Deprecated aliases.
Classes whose type is public, such as SharedRouterImplementer, ProcedureUtils/SharedUtils and HTTPProcedureUtils, stay value exports. The bundled .d.mts declares them as values even when the source says export type, so a type-only export would type-check and then crash at load.

Breaking changes

The 36 symbols above can no longer be imported from the listed entry points.

Verification

Up to date with main (72feedb, which includes feat(effect)!: promote to stable as @orpc/effect #2321 and fix!: only accept jsonified client factories in createContractJsonifiedUtilsFactory #2328).
Repo checks pass on the merged head: pnpm lint, pnpm type:check (including @orpc/nest), the root pnpm vitest run, the @orpc/cloudflare and @orpc/bun test suites, and pnpm docs:validate.
The export diff against main is exactly the 36 removals, with nothing added and no export switched between value and type-only.
Declaration portability, checked like fix: re-export helper types that appear in inferred types #2308 by packing every package from this branch and from its base at the time (23fc494):
- About 90 consumer projects, in 10 groups covering every package, each install only what a real user of that integration would. They use composite: true and exercise documented patterns, including values passed between entry points.
- Each compiles with TS 6 (bundler and NodeNext) and TS 5.9, and the emitted .d.ts is re-checked with skipLibCheck: false.
- Result: no new diagnostic of any code (TS2345 and TS2742/TS2883 included), and the emitted .d.ts/.js are byte-identical to that base.
Static checks on the built .d.mts, re-run after merging main at b3945c9:
- No type referenced by a package's public declarations became unnameable for a consumer that installs only that package.
- No class is declared in more than one .d.mts file of a package.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U63hBfpeESmJiHXznRFzjN

Helpers that only exist to support each package's own implementation are no longer exported from its entry points, so they can change freely after v2 is stable. Each symbol was checked to have no use in other workspace packages, docs, playgrounds, e2e tests or benches. Removed exports: - @orpc/server: augmentRouter, augmentImplementedRouter (+ options types), createRouterImplementer, decorateMiddleware, createGuardedProcedureLazy, createContractProcedure, withHiddenRouterContract, getHiddenRouterContract, and the cloneORPCError / reconcileORPCError re-exports - @orpc/server/standard: CompositeStandardHandlerPlugin, TracingHandlerPlugin - @orpc/client: resolveFriendlyClientOptions - @orpc/client/standard: CompositeStandardLinkPlugin - @orpc/contract: augmentContractRouter, HIDDEN_META_PLUGINS_SYMBOL, getAsyncIteratorObjectSchemaDetails (+ AsyncIteratorObjectSchemaDetails) - @orpc/shared: AsyncIdQueue, startSpan, setSpanAttributeIfDefined, runInSpanContext - @orpc/openapi: isBodylessMethod, DEFAULT_OPENAPI_SUCCESS_DESCRIPTION, DEFAULT_OPENAPI_INPUT_STRUCTURE, DEFAULT_OPENAPI_OUTPUT_STRUCTURE - @orpc/openapi/standard: serializeHeaders - @orpc/tanstack-query, @orpc/pinia-colada: generateOperationKey, isProcedureUtilsOptions, CompositeRouterUtilsPlugin, serializableStreamedQuery (and liveQuery in Pinia Colada) - @orpc/swr: generateOperationKey, isSubsetOf Now type-only exports, because they appear in public inferred types but are only constructed internally: SharedRouterImplementer (@orpc/server), ProcedureUtils and SharedUtils (TanStack Query, Pinia Colada, SWR), and HTTPProcedureUtils (@orpc/msw). Kept on purpose: adapter building blocks (StandardHandler, RPCMatcher, createStandardPeerRequestHandler, WebSocketHandler, ...), the @orpc/json-schema toolkit, meta readers (getMcpToolMeta, ...), mergeProcedureUtilsOptions for RouterUtilsPlugin authors, unique-symbol context keys that appear in public types, and deprecated aliases. Index tests now assert the internals are not exported. The OpenAPI matcher test builds its contract-first router with implement(contract).router() instead of withHiddenRouterContract. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U63hBfpeESmJiHXznRFzjN

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U63hBfpeESmJiHXznRFzjN

SharedRouterImplementer, ProcedureUtils, SharedUtils and HTTPProcedureUtils were switched to `export type`, but the bundled .d.mts drops the type-only modifier and still lists them as values. A consumer could import them without `type` (or use them with instanceof) and pass type-checking, then fail at load time because the runtime module no longer exports them. Export them as values again, as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U63hBfpeESmJiHXznRFzjN

Restore `export * from './queue'` and `export * from './tracing'` so AsyncIdQueue, AsyncIdQueueCloseOptions, startSpan, setSpanAttributeIfDefined and runInSpanContext stay exported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U63hBfpeESmJiHXznRFzjN

cloudflare-workers-and-pages · 2026-10-24T06:31:03Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	orpc	`613df85`	Commit Preview URL Branch Preview URL	Oct 24 2026, 01:49 PM

macroscopeapp · 2026-10-24T06:32:32Z

Approvability

Verdict: Needs Human Approval

Macroscope's review found this PR requires human approval — This PR removes 36 previously importable symbols from multiple package entrypoints before v2 stability; while production request behavior is unchanged, external consumers may face compile-time or runtime import breaks. The breadth and explicitly breaking API surface warrants human review.

No code changes detected at 613df85. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

pkg-pr-new · 2026-10-24T06:33:22Z

More templates

@orpc/ai-sdk

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

@orpc/arktype

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

@orpc/bun

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

@orpc/client

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

@orpc/cloudflare

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

@orpc/contract

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

@orpc/effect

npm i https://pkg.pr.new/@orpc/effect@2326

@orpc/evlog

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

@orpc/hibernation

npm i https://pkg.pr.new/@orpc/hibernation@2326

@orpc/json-schema

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

@orpc/experimental-lock

npm i https://pkg.pr.new/@orpc/experimental-lock@2326

@orpc/mcp

npm i https://pkg.pr.new/@orpc/mcp@2326

@orpc/msw

npm i https://pkg.pr.new/@orpc/msw@2326

@orpc/nest

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

@orpc/next

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

@orpc/node

npm i https://pkg.pr.new/@orpc/node@2326

@orpc/openapi

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

@orpc/opentelemetry

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

@orpc/pinia-colada

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

@orpc/pino

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

@orpc/publisher

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

@orpc/ratelimit

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

@orpc/server

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

@orpc/shared

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

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@2326

@orpc/tanstack-query

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

@orpc/trpc

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

@orpc/valibot

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

@orpc/zod

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

commit: 613df85

codspeed · 2026-10-24T06:33:39Z

Merging this PR will not alter performance

1 warning

⚠️ 5 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

✅ 28 untouched benchmarks
⏩ 2 skipped benchmarks¹

_{Comparing claude/admiring-wozniak-0r22e7 (613df85) with main (72feedb)}

2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

codecov · 2026-10-24T06:33:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

pullfrog

ℹ️ No critical issues — one minor suggestion inline.

Reviewed changes

Removed 36 internal-only exports from @orpc/server, @orpc/server/standard, @orpc/client, @orpc/client/standard, @orpc/contract, @orpc/openapi, @orpc/openapi/standard, @orpc/tanstack-query, @orpc/pinia-colada, and @orpc/swr.
Explicit export {}/export type {} lists replace export * in the many modules that mixed public and internal symbols, so a new internal helper no longer becomes public by default.
Dropped barrels entirely for router-hidden (server), utils (openapi/standard, swr), and live-query (pinia-colada).
Public-typed classes stay value exports (SharedRouterImplementer, ProcedureUtils, SharedUtils, HTTPProcedureUtils).
Test updates drop assertions for now-removed symbols; the OpenAPI matcher test now builds its contract-first router via implement(contract).router(...).

I traced each new explicit list back to its module and confirmed every retained symbol was previously reachable through the old export * (no accidental additions), that every removed symbol is still exported by its defining module for the intra-package relative imports that use it (@orpc/mcp keeps working because the plural getAsyncIteratorObjectSchemasDetails stays public), and that no cross-package import of a removed symbol exists. The only runtime files touched merely drop an export keyword, so there is no behavior change, and the OpenAPI matcher test refactor is semantically equivalent to the old withHiddenRouterContract call.

^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

…ak-0r22e7

claude added 4 commits October 23, 2026 14:37

test: drop assertions that internal helpers are not exported

7e0ef6a

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U63hBfpeESmJiHXznRFzjN

pullfrog Bot reviewed Oct 24, 2026

View reviewed changes

Comment thread packages/effect/src/index.test.ts

claude added 2 commits October 24, 2026 08:28

Merge remote-tracking branch 'origin/main' into claude/admiring-wozni…

e9e8a6e

…ak-0r22e7

Merge remote-tracking branch 'origin/main' into claude/admiring-wozni…

613df85

…ak-0r22e7

dinwwwh merged commit 5dc334e into main Oct 24, 2026
14 checks passed

Navigation Menu

Repository navigation

refactor!: stop exporting internal-only APIs before v2 stable - #2326

refactor!: stop exporting internal-only APIs before v2 stable#2326
dinwwwh merged 6 commits into
mainfrom
claude/admiring-wozniak-0r22e7

dinwwwh commented Oct 24, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

macroscopeapp Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

codspeed Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Oct 24, 2026

Uh oh!

pullfrog Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Removed exports (36)

How it's done

Kept on purpose

Breaking changes

Verification

Uh oh!

cloudflare-workers-and-pages Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

macroscopeapp Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approvability

Uh oh!

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

Uh oh!

Uh oh!

codspeed Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

codecov Bot commented Oct 24, 2026

Codecov Report

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dinwwwh commented Oct 24, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Oct 24, 2026 •

edited

Loading

macroscopeapp Bot commented Oct 24, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 24, 2026 •

edited

Loading

codspeed Bot commented Oct 24, 2026 •

edited

Loading