feat(client): safe client

[Copilot]

This PR implements the createSafeClient feature requested in #703, which provides automatic safe error handling for oRPC client calls without requiring manual wrapping.

Problem

Previously, users had to manually wrap each client call with the safe function:

const { error, data, isDefined } = await safe(client.doSomething({ id: '123' }))

This became repetitive when you wanted all calls to use safe error handling.

Solution

Added createSafeClient function that wraps an entire client to automatically apply safe error handling:

const safeClient = createSafeClient(client)
const { error, data, isDefined } = await safeClient.doSomething({ id: '123' })

Implementation Details

• Proxy-based interception: Uses JavaScript Proxy to intercept both property access (for nested clients) and function calls (for procedure execution)
• Type safety: Added SafeClient<T> type that transforms client methods to return Promise<SafeResult<...>> instead of ClientPromiseResult<...>
• Full compatibility: Supports all existing client features including nested procedures, client options (signal, context), and both object/tuple destructuring
• Zero breaking changes: Purely additive feature that doesn't modify existing APIs

Features

✅ Automatic error handling - All procedure calls return safe results
✅ Nested procedure support - Works with safeClient.user.profile.get()
✅ Client options - Supports signals, context, and other options
✅ Type safety - Full TypeScript support with proper inference
✅ Destructuring - Both { error, data } and [error, data] styles

Examples

Basic Usage

import { createSafeClient } from '@orpc/client'

const safeClient = createSafeClient(client)

// Object destructuring
const { error, data, isDefined, isSuccess } = await safeClient.getUser({ id: '123' })

// Tuple destructuring  
const [error, data, isDefined, isSuccess] = await safeClient.getUser({ id: '123' })

Error Handling

const { error, data, isDefined } = await safeClient.getUser({ id: 'invalid' })

if (error) {
  if (isDefined) {
    // Defined ORPC error with structured data
    console.log('Error code:', error.code)
  } else {
    // Regular error
    console.log('Error:', error.message)  
  }
} else {
  console.log('Success:', data)
}

Nested Procedures

// All levels automatically wrapped
const result = await safeClient.admin.users.list({ page: 1 })

Testing

• Added 5 comprehensive unit tests covering success/error cases, nested calls, and client options
• Added 4 integration tests demonstrating real-world usage patterns
• Added TypeScript type tests to ensure proper type inference
• All 534 existing tests continue to pass
• Verified build, linting, and type checking

Fixes #703.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
orpc	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 11, 2025 9:36am

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

📢 Thoughts on this report? Let us know!

[pkg-pr-new]

More templates

• @orpc/astro-playground
• @orpc/browser-extension-playground
• @orpc/cloudflare-worker-playground
• @orpc/contract-first-playground
• @orpc/electron-playground
• @orpc/nest-playground
• @orpc/next-playground
• @orpc/nuxt-playground
• @orpc/solid-start-playground
• @orpc/svelte-kit-playground
• @orpc/tanstack-start-playground

@orpc/arktype

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

@orpc/client

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

@orpc/contract

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

@orpc/experimental-durable-event-iterator

npm i https://pkg.pr.new/@orpc/experimental-durable-event-iterator@751

@orpc/hey-api

npm i https://pkg.pr.new/@orpc/hey-api@751

@orpc/json-schema

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

@orpc/nest

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

@orpc/openapi

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

@orpc/openapi-client

npm i https://pkg.pr.new/@orpc/openapi-client@751

@orpc/react

npm i https://pkg.pr.new/@orpc/react@751

@orpc/react-query

npm i https://pkg.pr.new/@orpc/react-query@751

@orpc/server

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

@orpc/shared

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

@orpc/solid-query

npm i https://pkg.pr.new/@orpc/solid-query@751

@orpc/standard-server

npm i https://pkg.pr.new/@orpc/standard-server@751

@orpc/standard-server-aws-lambda

npm i https://pkg.pr.new/@orpc/standard-server-aws-lambda@751

@orpc/standard-server-fetch

npm i https://pkg.pr.new/@orpc/standard-server-fetch@751

@orpc/standard-server-node

npm i https://pkg.pr.new/@orpc/standard-server-node@751

@orpc/standard-server-peer

npm i https://pkg.pr.new/@orpc/standard-server-peer@751

@orpc/svelte-query

npm i https://pkg.pr.new/@orpc/svelte-query@751

@orpc/tanstack-query

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

@orpc/trpc

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

@orpc/valibot

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

@orpc/vue-colada

npm i https://pkg.pr.new/@orpc/vue-colada@751

@orpc/vue-query

npm i https://pkg.pr.new/@orpc/vue-query@751

@orpc/zod

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

commit: 86dbc63

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Join our Discord community for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.