feat(pinia-colada): define base options and interceptors via contract meta

[dinwwwh]

Summary

Port of #1705 to @orpc/pinia-colada. Define base Pinia Colada options and interceptors directly on a procedure contract via piniaColada, and apply them automatically with the new ContractOptionsUtilsPlugin.

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

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

• piniaColada 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, any pair involving a function modifier composes, and a key explicitly set to undefined resets the value from lower layers
• getPiniaColadaMeta reads the stored options for custom integrations
• UseMutationFnContext now matches the runtime merged mutation context, so values provided by a global onMutate are typed inside mutation interceptors via UseMutationContextCommon augmentation
• Docs cover the plugin, the reference-only nature of contract types, and passing runtime values such as router utils through a global onMutate hook for optimistic updates

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
orpc	Ready	Preview, Comment	Jul 25, 2026 1:37am

[pkg-pr-new]

More templates

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

@orpc/ai-sdk

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

@orpc/arktype

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

@orpc/bun

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

@orpc/client

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

@orpc/cloudflare

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

@orpc/contract

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

@orpc/experimental-effect

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

@orpc/evlog

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

@orpc/json-schema

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

@orpc/nest

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

@orpc/next

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

@orpc/openapi

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

@orpc/opentelemetry

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

@orpc/pinia-colada

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

@orpc/pino

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

@orpc/publisher

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

@orpc/ratelimit

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

@orpc/server

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

@orpc/shared

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

@orpc/tanstack-query

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

@orpc/trpc

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

@orpc/valibot

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

@orpc/zod

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

commit: 77a5dc9

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 18 untouched benchmarks

---

_{Comparing dinwwwh:claude/pinia-colada-pr-1705-e13d5e (77a5dc9) with main (deb9e75)}

[pullfrog]

Important

isProcedureUtilsOptions incorrectly rejects function modifiers in scoped options — see inline comment. Otherwise looks solid.

Reviewed changes — ports the contract-options-via-meta pattern to @orpc/pinia-colada, allowing base options and interceptors to be defined on procedure contracts via piniaColada() and applied automatically through ContractOptionsUtilsPlugin.

• New meta.ts — piniaColada() stores procedure utils options in contract meta under ~pinia-colada, with merge-on-repeat semantics; getPiniaColadaMeta() reads stored options; ContractOptionsUtilsPlugin implements RouterUtilsPlugin.initProcedureOptions to apply meta as the base layer
• mergeProcedureUtilsOptions and mergeProcedureUtilsModifier — centralized option merging that concatenates interceptors (meta → global → scoped) and composes modifier functions (base applied first), replacing the ad-hoc inline spread-merging in createRouterUtilsInternal
• Enhanced isProcedureUtilsOptions — moved from router-utils.ts to procedure-utils.ts with stricter validation (interceptor-element function checks, modifier-key plain-object checks) and constant key arrays
• Router utils refactor — createRouterUtilsInternal now uses mergeProcedureUtilsOptions for global→scoped composition, deduplicating the merging logic
• Docs — new contract options plugin section in pinia-colada.md with a warning about contract types being reference-only

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

[pullfrog]

Reviewed changes — adds UseMutationGlobalContext to UseMutationFnContext so augmented global values are typed inside mutation interceptors, and documents the optimistic-update pattern via contract meta and global onMutate.

• UseMutationFnContext includes UseMutationGlobalContext — switched the source type from UseMutationOptions['mutation']'s context (which only carries local onMutate context, effectively any with the <any, any> generics) to UseMutationOptionsGlobal['onSuccess']'s context (which intersects UseMutationContextCommon & UseMutationGlobalContext). Module augmentations on UseMutationGlobalContext now flow through to mutation interceptor fnContext.
• Docs: optimistic updates via contract meta — new collapsible section in pinia-colada.md showing how to augment UseMutationGlobalContext, provide runtime values (router utils, query cache) through a global onMutate hook, and use them in contract-meta mutation interceptors for optimistic updates with rollback.

ℹ️ No new issues from the incremental changes. The prior finding about isProcedureUtilsOptions rejecting function modifiers is still unaddressed — see the open thread for details.

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

[pullfrog]

Reviewed changes — added a runtime test validating the optimistic-update-through-contract-meta pattern from the docs.

• New meta.test.tsx — end-to-end test mount using Vue, Pinia Colada, ContractOptionsUtilsPlugin, and a global onMutate that injects router utils and a query cache into UseMutationGlobalContext. Verifies optimistic update, rollback on error, invalidateQueries refetch, and a successful mutation sequence.

ℹ️ No new issues from the incremental changes. The test is thorough and passes. The prior finding about isProcedureUtilsOptions rejecting function modifiers is still unaddressed — see the open thread.

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

[pullfrog]

✅ No new issues found.

Reviewed changes — adds undefined reset semantics to mergeProcedureUtilsOptions, tightens the merger API, and moves composition tests to the right module.

• mergeProcedureUtilsOptions supports explicit undefined reset — a key set to undefined in the override clears the base value instead of merging. The implementation handles this cleanly by relying on the initial { ...base, ...override } spread and only applying interceptor concatenation or modifier composition when both sides have truthy values.
• mergeProcedureUtilsModifier signature tightened — both parameters are now required (not | undefined), matching the caller which only invokes when both are defined.
• Composition tests moved from meta.test.ts to procedure-utils.test.ts — tests now exercise mergeProcedureUtilsOptions directly rather than going through the meta layer, which is the right home.
• emptyInterceptors removed from router-utils tests — the new merge doesn't carry forward empty interceptor arrays, so test expectations no longer include them.

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