feat(client)!: update safe utility (#174)

unnoq · web-flow · commit 553adec9ad20 · 2025-02-27T16:35:18.000+07:00
* feat!: update `safe` utility

* sync

* improve

* avoid as any
diff --git a/apps/content/docs/client/error-handling.md b/apps/content/docs/client/error-handling.md
@@ -29,9 +29,10 @@ const doSomething = os
   })
   .callable()
 
-const [data, error] = await safe(doSomething({ id: '123' }))
+const [error, data, isDefined] = await safe(doSomething({ id: '123' }))
+// or const { error, data, isDefined } = await safe(doSomething({ id: '123' }))
 
-if (isDefinedError(error)) {
+if (isDefinedError(error)) { // or isDefined
   // handle known error
   console.log(error.data.retryAfter)
 }
@@ -47,5 +48,8 @@ else {
 :::info
 
 - `safe` works like `try/catch`, but can infer error types.
+- `safe` supports both tuple `[error, data, isDefined]` and object `{ error, data, isDefined }` styles.
 - `isDefinedError` checks if an error originates from `.errors`.
-  :::
+- `isDefined` can replace `isDefinedError`
+
+:::
diff --git a/packages/client/src/utils.test-d.ts b/packages/client/src/utils.test-d.ts
@@ -3,24 +3,58 @@ import type { Client, ClientContext } from './types'
 import { isDefinedError } from './error'
 import { safe } from './utils'
 
-it('safe', async () => {
+describe('safe', async () => {
   const client = {} as Client<ClientContext, string, number, Error | ORPCError<'BAD_GATEWAY', { val: string }>>
 
-  const [output, error, isDefined] = await safe(client('123'))
+  it('tuple style', async () => {
+    const [error, data, isDefined] = await safe(client('123'))
 
-  if (!error) {
-    expectTypeOf(output).toEqualTypeOf<number>()
-  }
+    if (error) {
+      expectTypeOf(error).toEqualTypeOf<Error | ORPCError<'BAD_GATEWAY', { val: string }>>()
+      expectTypeOf(data).toEqualTypeOf<undefined>()
+      expectTypeOf(isDefined).toEqualTypeOf<boolean>()
 
-  if (isDefined) {
-    expectTypeOf(error).toEqualTypeOf<ORPCError<'BAD_GATEWAY', { val: string }>>()
-  }
+      if (isDefinedError(error)) {
+        expectTypeOf(error).toEqualTypeOf<ORPCError<'BAD_GATEWAY', { val: string }>>()
+      }
 
-  if (error) {
-    expectTypeOf(error).toEqualTypeOf<Error | ORPCError<'BAD_GATEWAY', { val: string }>>()
+      if (isDefined) {
+        expectTypeOf(error).toEqualTypeOf<ORPCError<'BAD_GATEWAY', { val: string }>>()
+      }
+      else {
+        expectTypeOf(error).toEqualTypeOf<Error>()
+      }
+    }
+    else {
+      expectTypeOf(error).toEqualTypeOf<null>()
+      expectTypeOf(data).toEqualTypeOf<number>()
+      expectTypeOf(isDefined).toEqualTypeOf<false>()
+    }
+  })
+
+  it('object style', async () => {
+    const { error, data, isDefined } = await safe(client('123'))
 
-    if (isDefinedError(error)) {
-      expectTypeOf(error).toEqualTypeOf<ORPCError<'BAD_GATEWAY', { val: string }>>()
+    if (error) {
+      expectTypeOf(error).toEqualTypeOf<Error | ORPCError<'BAD_GATEWAY', { val: string }>>()
+      expectTypeOf(data).toEqualTypeOf<undefined>()
+      expectTypeOf(isDefined).toEqualTypeOf<boolean>()
+
+      if (isDefinedError(error)) {
+        expectTypeOf(error).toEqualTypeOf<ORPCError<'BAD_GATEWAY', { val: string }>>()
+      }
+
+      if (isDefined) {
+        expectTypeOf(error).toEqualTypeOf<ORPCError<'BAD_GATEWAY', { val: string }>>()
+      }
+      else {
+        expectTypeOf(error).toEqualTypeOf<Error>()
+      }
+    }
+    else {
+      expectTypeOf(error).toEqualTypeOf<null>()
+      expectTypeOf(data).toEqualTypeOf<number>()
+      expectTypeOf(isDefined).toEqualTypeOf<false>()
     }
-  }
+  })
 })
diff --git a/packages/client/src/utils.test.ts b/packages/client/src/utils.test.ts
@@ -3,17 +3,21 @@ import { safe } from './utils'
 
 it('safe', async () => {
   const r1 = await safe(Promise.resolve(1))
-  expect(r1).toEqual([1, undefined, false])
+  expect([...r1]).toEqual([null, 1, false])
+  expect({ ...r1 }).toEqual(expect.objectContaining({ error: null, data: 1, isDefined: false }))
 
   const e2 = new Error('error')
   const r2 = await safe(Promise.reject(e2))
-  expect(r2).toEqual([undefined, e2, false])
+  expect([...r2]).toEqual([e2, undefined, false])
+  expect({ ...r2 }).toEqual(expect.objectContaining({ error: e2, data: undefined, isDefined: false }))
 
   const e3 = new ORPCError('BAD_GATEWAY', { defined: true })
   const r3 = await safe(Promise.reject(e3))
-  expect(r3).toEqual([undefined, e3, true])
+  expect([...r3]).toEqual([e3, undefined, true])
+  expect({ ...r3 }).toEqual(expect.objectContaining({ error: e3, data: undefined, isDefined: true }))
 
   const e4 = new ORPCError('BAD_GATEWAY')
   const r4 = await safe(Promise.reject(e4))
-  expect(r4).toEqual([undefined, e4, false])
+  expect([...r4]).toEqual([e4, undefined, false])
+  expect({ ...r4 }).toEqual(expect.objectContaining({ error: e4, data: undefined, isDefined: false }))
 })
diff --git a/packages/client/src/utils.ts b/packages/client/src/utils.ts
@@ -3,22 +3,34 @@ import type { ClientPromiseResult } from './types'
 import { isDefinedError } from './error'
 
 export type SafeResult<TOutput, TError extends Error> =
-  | [output: TOutput, error: undefined, isDefinedError: false]
-  | [output: undefined, error: TError, isDefinedError: false]
-  | [output: undefined, error: Extract<TError, ORPCError<any, any>>, isDefinedError: true]
+  | [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 async function safe<TOutput, TError extends Error>(promise: ClientPromiseResult<TOutput, TError>): Promise<SafeResult<TOutput, TError>> {
   try {
     const output = await promise
-    return [output, undefined, false]
+    return Object.assign(
+      [null, output, false] satisfies [null, TOutput, false],
+      { error: null, data: output, isDefined: false as const },
+    )
   }
   catch (e) {
     const error = e as TError
 
     if (isDefinedError(error)) {
-      return [undefined, error, true]
+      return Object.assign(
+        [error, undefined, true] satisfies [typeof error, undefined, true],
+        { error, data: undefined, isDefined: true as const },
+      )
     }
 
-    return [undefined, error, false]
+    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 },
+    )
   }
 }
diff --git a/packages/client/tests/e2e.test-d.ts b/packages/client/tests/e2e.test-d.ts
@@ -23,18 +23,18 @@ describe('e2e', () => {
   })
 
   it('infer errors', async () => {
-    const [,error] = await safe(orpc.post.find({ id: '123' }))
+    const [error] = await safe(orpc.post.find({ id: '123' }))
 
     expectTypeOf(error).toEqualTypeOf<
-      | undefined
+      | null
       | Error
       | ORPCError<'NOT_FOUND', { id: string }>
     >()
 
-    const [, error2] = await safe(orpc.post.create({ title: 'title' }))
+    const [error2] = await safe(orpc.post.create({ title: 'title' }))
 
     expectTypeOf(error2).toEqualTypeOf<
-      | undefined
+      | null
       | Error
       | ORPCError<'CONFLICT', { title: string, thumbnail?: File }>
       | ORPCError<'FORBIDDEN', { title: string, thumbnail?: File }>
diff --git a/packages/client/tests/e2e.test.ts b/packages/client/tests/e2e.test.ts
@@ -14,20 +14,20 @@ describe('e2e', () => {
   })
 
   it('on error', async () => {
-    const [, error, isDefined] = await safe(orpc.post.find({ id: 'NOT_FOUND' }))
+    const [error,, isDefined] = await safe(orpc.post.find({ id: 'NOT_FOUND' }))
 
     expect(isDefined).toBe(true)
     expect(error).toBeInstanceOf(ORPCError)
     expect((error as any).data).toEqual({ id: 'NOT_FOUND' })
 
-    const [, error2, isDefined2] = await safe(orpc.post.create({ title: 'CONFLICT' }))
+    const [error2,, isDefined2] = await safe(orpc.post.create({ title: 'CONFLICT' }))
 
     expect(isDefined2).toBe(true)
     expect(error2).toBeInstanceOf(ORPCError)
     expect((error2 as any).data).toEqual({ title: 'CONFLICT' })
 
     // @ts-expect-error - invalid input
-    const [, error3, isDefined3] = await safe(orpc.post.create({ }))
+    const [error3,, isDefined3] = await safe(orpc.post.create({ }))
 
     expect(isDefined3).toBe(false)
     expect(error3).toBeInstanceOf(ORPCError)
diff --git a/packages/server/src/procedure-client.test-d.ts b/packages/server/src/procedure-client.test-d.ts
@@ -29,10 +29,10 @@ describe('ProcedureClient', () => {
   })
 
   it('works', async () => {
-    const [output, error, isDefined] = await safe(client({ input: 123 }, { context: { cache: true } }))
+    const [error, data, isDefined] = await safe(client({ input: 123 }, { context: { cache: true } }))
 
     if (!error) {
-      expectTypeOf(output).toEqualTypeOf<{ output: string }>()
+      expectTypeOf(data).toEqualTypeOf<{ output: string }>()
     }
 
     if (isDefined) {
diff --git a/packages/server/src/procedure-utils.test-d.ts b/packages/server/src/procedure-utils.test-d.ts
@@ -4,10 +4,10 @@ import { ping, pong } from '../tests/shared'
 import { call } from './procedure-utils'
 
 it('call', async () => {
-  const [output, error, isDefined] = await safe(call(ping, { input: 123 }, { context: { db: 'postgres' } }))
+  const [error, data, isDefined] = await safe(call(ping, { input: 123 }, { context: { db: 'postgres' } }))
 
   if (!error) {
-    expectTypeOf(output).toEqualTypeOf<{ output: string }>()
+    expectTypeOf(data).toEqualTypeOf<{ output: string }>()
   }
 
   if (isDefined) {
