feat(server): support config ThrowableError (#311)

This allow config throwable-error this can helpful when you want more
strict error types - js allow throw any value but by default oRPC treat
you throw an Error instance, it's a best practice and fine in 99.5%
cases

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **Documentation**
- Introduced a new “No Throw Literal” page with best practice
guidelines.
  - Updated the sidebar navigation to include a link to the new content.

- **New Features**
- Enhanced responses with a clear success indicator, improving clarity
on operation outcomes.

- **Refactor**
- Streamlined error handling across the system, enabling more flexible
error type usage.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/.vitepress/config.ts

@@ -141,6 +141,7 @@ export default defineConfig({
           collapsed: true,
           items: [
             { text: 'Dedupe Middleware', link: '/docs/best-practices/dedupe-middleware' },
+            { text: 'No Throw Literal', link: '/docs/best-practices/no-throw-literal' },
           ],
         },
         {

apps/content/docs/best-practices/no-throw-literal.md

@@ -0,0 +1,57 @@
+---
+title: No Throw Literal
+description: Always throw `Error` instances instead of literal values.
+---
+
+# No Throw Literal
+
+In JavaScript, you can throw any value, but it's best to throw only `Error` instances.
+
+```ts
+// eslint-disable-next-line no-throw-literal
+throw 'error' // ✗ avoid
+throw new Error('error') // ✓ recommended
+```
+
+:::info
+oRPC treats thrown `Error` instances as best practice by default, as recommended by the [JavaScript Standard Style](https://standardjs.com/rules.html#throw-new-error-old-style).
+:::
+
+## Configuration
+
+Customize oRPC's behavior by setting `throwableError` in the `Registry`:
+
+```ts
+declare module '@orpc/server' { // or '@orpc/contract', or '@orpc/client'
+  interface Registry {
+    throwableError: Error // [!code highlight]
+  }
+}
+```
+
+:::info
+Avoid using `any` or `unknown` for `throwableError` because doing so prevents the client from inferring [type-safe errors](/docs/client/error-handling#using-safe-and-isdefinederror). Instead, use `null | undefined | {}` (equivalent to `unknown`) for stricter error type inference.
+:::
+
+:::tip
+If you configure `throwableError` as `null | undefined | {}`, adjust your code to check the `success` property:
+
+```ts
+const { error, data, success } = await safe(client('input'))
+
+if (!success) {
+  if (isDefinedError(error)) {
+    // handle type-safe error
+  }
+  // handle other errors
+}
+else {
+  // handle success
+}
+```
+
+:::
+
+## Bonus
+
+If you use ESLint, enable the [no-throw-literal](https://eslint.org/docs/rules/no-throw-literal) rule to enforce throwing only `Error` instances.

packages/client/src/adapters/standard/link.ts

@@ -1,4 +1,4 @@
-import type { Interceptor } from '@orpc/shared'
+import type { Interceptor, ThrowableError } from '@orpc/shared'
 import type { StandardLazyResponse, StandardRequest } from '@orpc/standard-server'
 import type { ClientContext, ClientLink, ClientOptions } from '../../types'
 import type { StandardLinkClient, StandardLinkCodec } from './types'
@@ -11,8 +11,8 @@ export interface StandardLinkPlugin<T extends ClientContext> {
 }
 
 export interface StandardLinkOptions<T extends ClientContext> {
-  interceptors?: Interceptor<{ path: readonly string[], input: unknown, options: ClientOptions<T> }, unknown, unknown>[]
-  clientInterceptors?: Interceptor<{ request: StandardRequest }, StandardLazyResponse, unknown>[]
+  interceptors?: Interceptor<{ path: readonly string[], input: unknown, options: ClientOptions<T> }, unknown, ThrowableError>[]
+  clientInterceptors?: Interceptor<{ request: StandardRequest }, StandardLazyResponse, ThrowableError>[]
   plugins?: StandardLinkPlugin<T>[]
 }
 

packages/client/src/index.ts

@@ -6,4 +6,5 @@ export * from './types'
 export * from './utils'
 
 export { onError, onFinish, onStart, onSuccess } from '@orpc/shared'
+export type { Registry, ThrowableError } from '@orpc/shared'
 export { ErrorEvent } from '@orpc/standard-server'

packages/client/src/types.ts

@@ -15,9 +15,9 @@ export type ClientRest<TClientContext extends ClientContext, TInput> = Record<ne
     : [input: TInput, options?: FriendlyClientOptions<TClientContext>]
   : [input: TInput, options: FriendlyClientOptions<TClientContext>]
 
-export type ClientPromiseResult<TOutput, TError extends Error> = PromiseWithError<TOutput, TError>
+export type ClientPromiseResult<TOutput, TError> = PromiseWithError<TOutput, TError>
 
-export interface Client<TClientContext extends ClientContext, TInput, TOutput, TError extends Error> {
+export interface Client<TClientContext extends ClientContext, TInput, TOutput, TError> {
   (...rest: ClientRest<TClientContext, TInput>): ClientPromiseResult<TOutput, TError>
 }
 

packages/client/src/utils.test-d.ts

@@ -7,9 +7,9 @@ describe('safe', async () => {
   const client = {} as Client<ClientContext, string, number, Error | ORPCError<'BAD_GATEWAY', { val: string }>>
 
   it('tuple style', async () => {
-    const [error, data, isDefined] = await safe(client('123'))
+    const [error, data, isDefined, success] = await safe(client('123'))
 
-    if (error) {
+    if (error || !success) {
       expectTypeOf(error).toEqualTypeOf<Error | ORPCError<'BAD_GATEWAY', { val: string }>>()
       expectTypeOf(data).toEqualTypeOf<undefined>()
       expectTypeOf(isDefined).toEqualTypeOf<boolean>()
@@ -33,9 +33,9 @@ describe('safe', async () => {
   })
 
   it('object style', async () => {
-    const { error, data, isDefined } = await safe(client('123'))
+    const { error, data, isDefined, success } = await safe(client('123'))
 
-    if (error) {
+    if (error || !success) {
       expectTypeOf(error).toEqualTypeOf<Error | ORPCError<'BAD_GATEWAY', { val: string }>>()
       expectTypeOf(data).toEqualTypeOf<undefined>()
       expectTypeOf(isDefined).toEqualTypeOf<boolean>()
@@ -57,4 +57,11 @@ describe('safe', async () => {
       expectTypeOf(isDefined).toEqualTypeOf<false>()
     }
   })
+
+  it('can catch Promise', async () => {
+    const { error, data } = await safe({} as Promise<number>)
+
+    expectTypeOf(error).toEqualTypeOf<Error | null>()
+    expectTypeOf(data).toEqualTypeOf<number | undefined >()
+  })
 })

packages/client/src/utils.test.ts

@@ -3,23 +3,23 @@ import { resolveFriendlyClientOptions, safe } from './utils'
 
 it('safe', async () => {
   const r1 = await safe(Promise.resolve(1))
-  expect([...r1]).toEqual([null, 1, false])
-  expect({ ...r1 }).toEqual(expect.objectContaining({ error: null, data: 1, isDefined: false }))
+  expect([...r1]).toEqual([null, 1, false, true])
+  expect({ ...r1 }).toEqual(expect.objectContaining({ error: null, data: 1, isDefined: false, success: true }))
 
   const e2 = new Error('error')
   const r2 = await safe(Promise.reject(e2))
-  expect([...r2]).toEqual([e2, undefined, false])
-  expect({ ...r2 }).toEqual(expect.objectContaining({ error: e2, data: undefined, isDefined: false }))
+  expect([...r2]).toEqual([e2, undefined, false, false])
+  expect({ ...r2 }).toEqual(expect.objectContaining({ error: e2, data: undefined, isDefined: false, success: false }))
 
   const e3 = new ORPCError('BAD_GATEWAY', { defined: true })
   const r3 = await safe(Promise.reject(e3))
-  expect([...r3]).toEqual([e3, undefined, true])
-  expect({ ...r3 }).toEqual(expect.objectContaining({ error: e3, data: undefined, isDefined: true }))
+  expect([...r3]).toEqual([e3, undefined, true, false])
+  expect({ ...r3 }).toEqual(expect.objectContaining({ error: e3, data: undefined, isDefined: true, success: false }))
 
   const e4 = new ORPCError('BAD_GATEWAY')
   const r4 = await safe(Promise.reject(e4))
-  expect([...r4]).toEqual([e4, undefined, false])
-  expect({ ...r4 }).toEqual(expect.objectContaining({ error: e4, data: undefined, isDefined: false }))
+  expect([...r4]).toEqual([e4, undefined, false, false])
+  expect({ ...r4 }).toEqual(expect.objectContaining({ error: e4, data: undefined, isDefined: false, success: false }))
 })
 
 it('resolveFriendlyClientOptions', () => {

packages/client/src/utils.ts

@@ -1,36 +1,37 @@
+import type { ThrowableError } from '@orpc/shared'
 import type { ORPCError } from './error'
 import type { ClientContext, ClientOptions, ClientPromiseResult, FriendlyClientOptions } from './types'
 import { isDefinedError } from './error'
 
-export type SafeResult<TOutput, TError extends Error> =
-  | [error: null, data: TOutput, isDefined: false]
-  & { error: null, data: TOutput, isDefined: false }
-  | [error: Exclude<TError, ORPCError<any, any>>, data: undefined, isDefined: false]
-  & { error: Exclude<TError, ORPCError<any, any>>, data: undefined, isDefined: false }
-  | [error: Extract<TError, ORPCError<any, any>>, data: undefined, isDefined: true]
-  & { error: Extract<TError, ORPCError<any, any>>, data: undefined, isDefined: true }
+export type SafeResult<TOutput, TError> =
+  | [error: null, data: TOutput, isDefined: false, success: true]
+  & { error: null, data: TOutput, isDefined: false, success: true }
+  | [error: Exclude<TError, ORPCError<any, any>>, data: undefined, isDefined: false, success: false]
+  & { error: Exclude<TError, ORPCError<any, any>>, data: undefined, isDefined: false, success: false }
+  | [error: Extract<TError, ORPCError<any, any>>, data: undefined, isDefined: true, success: false]
+  & { error: Extract<TError, ORPCError<any, any>>, data: undefined, isDefined: true, success: false }
 
-export async function safe<TOutput, TError extends Error>(promise: ClientPromiseResult<TOutput, TError>): Promise<SafeResult<TOutput, TError>> {
+export async function safe<TOutput, TError = ThrowableError>(promise: ClientPromiseResult<TOutput, TError>): Promise<SafeResult<TOutput, TError>> {
   try {
     const output = await promise
     return Object.assign(
-      [null, output, false] satisfies [null, TOutput, false],
-      { error: null, data: output, isDefined: false as const },
+      [null, output, false, true] satisfies [null, TOutput, false, true],
+      { error: null, data: output, isDefined: false as const, success: true as const },
     )
   }
   catch (e) {
     const error = e as TError
 
     if (isDefinedError(error)) {
       return Object.assign(
-        [error, undefined, true] satisfies [typeof error, undefined, true],
-        { error, data: undefined, isDefined: true as const },
+        [error, undefined, true, false] satisfies [typeof error, undefined, true, false],
+        { error, data: undefined, isDefined: true as const, success: false as const },
       )
     }
 
     return Object.assign(
-      [error as Exclude<TError, ORPCError<any, any>>, undefined, false] satisfies [Exclude<TError, ORPCError<any, any>>, undefined, false],
-      { error: error as Exclude<TError, ORPCError<any, any>>, data: undefined, isDefined: false as const },
+      [error as Exclude<TError, ORPCError<any, any>>, undefined, false, false] satisfies [Exclude<TError, ORPCError<any, any>>, undefined, false, false],
+      { error: error as Exclude<TError, ORPCError<any, any>>, data: undefined, isDefined: false as const, success: false as const },
     )
   }
 }

packages/contract/src/error.ts

@@ -1,4 +1,5 @@
 import type { ORPCError, ORPCErrorCode } from '@orpc/client'
+import type { ThrowableError } from '@orpc/shared'
 import type { AnySchema, InferSchemaOutput, Schema, SchemaIssue } from './schema'
 
 export interface ValidationErrorOptions extends ErrorOptions {
@@ -40,4 +41,4 @@ export type ORPCErrorFromErrorMap<TErrorMap extends ErrorMap> = {
     : never
 }[keyof TErrorMap]
 
-export type ErrorFromErrorMap<TErrorMap extends ErrorMap> = Error | ORPCErrorFromErrorMap<TErrorMap>
+export type ErrorFromErrorMap<TErrorMap extends ErrorMap> = ORPCErrorFromErrorMap<TErrorMap> | ThrowableError

packages/contract/src/index.ts

@@ -15,3 +15,4 @@ export * from './router-utils'
 export * from './schema'
 
 export { ORPCError } from '@orpc/client'
+export type { Registry, ThrowableError } from '@orpc/shared'