orpc-nuxt 0.6.0 → 0.7.0

package/README.md

@@ -173,15 +173,10 @@ const post = await orpc.blog.posts.get.call({ id: 1 })
 
 ### Declared errors
 
-Treat an expected rejection as an application outcome only when the procedure declares it with `.errors()`.
-Let every other error propagate to the application's error handler, including an `ORPCError` whose code was not declared by that procedure.
-
-Use `catchORPCError()` from the client entrypoint to handle selected declared errors while preserving their code and data types:
+Use `.callCatching()` to call a procedure and handle errors it declares with `.errors()`, with their code and data types:
 
 ```ts
-import { catchORPCError } from "orpc-nuxt/client"
-
-const post = await catchORPCError(orpc.blog.posts.update.call(input), {
+const post = await orpc.blog.posts.update.callCatching(input, {
   CONFLICT: (error) => {
     message.value = error.message
     conflictingField.value = error.data.field
@@ -195,16 +190,26 @@ Undeclared errors and declared codes without a handler are rethrown unchanged.
 
 When one declared error simply means there is no result, map it to `undefined` or `null` directly:
 
+```ts
+const post = await orpc.blog.posts.get.callCatching({ id }, { NOT_FOUND: null })
+// post is the procedure output or null.
+```
+
+Pass call options such as `context` or `signal` as the third argument.
+Pass `undefined` as input for procedures without input.
+
+`.callCatching()` is built on `catchORPCError()`, which handles errors of a promise returned directly by any typed oRPC client call.
+Import it from the client entrypoint when you do not call the procedure through this package's client:
+
 ```ts
 import { catchORPCError } from "orpc-nuxt/client"
 
-const post = await catchORPCError(orpc.blog.posts.get.call({ id }), {
-  NOT_FOUND: null,
-})
-// post is the procedure output or null.
+const post = await catchORPCError(client.blog.posts.get({ id }), { NOT_FOUND: null })
 ```
 
-The client also exposes oRPC's utilities:
+### oRPC utilities
+
+The client also exposes oRPC's TanStack Query utilities:
 
 - `.key()` builds a cache key prefix for a procedure or router branch.
 - `.queryKey()` builds a query key for a specific input.

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.14.1592 || ^4.0.1"
   },
-  "version": "0.6.0",
+  "version": "0.7.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/client/create.js

@@ -4,6 +4,7 @@ import { useORPCMutation } from "../vue-query/mutation.js";
 import { useORPCQuery } from "../vue-query/query.js";
 import { resolveQueryClient } from "../vue-query/query-client.js";
 import { decorateClient } from "./decorate.js";
+import { catchDefinedErrors } from "./error.js";
 export function createORPCNuxtClient(client, options = {}) {
   const utils = createTanstackQueryUtils(client, { prefix: options.prefix });
   let queryClient = options.queryClient ?? resolveQueryClient();
@@ -18,6 +19,10 @@ export function createORPCNuxtClient(client, options = {}) {
       useMutation(mutationOptions) {
         return useORPCMutation(target, mutationOptions, getQueryClient());
       },
+      callCatching(input, handlers, callOptions) {
+        const utils2 = target;
+        return catchDefinedErrors(utils2.call(input, callOptions), handlers);
+      },
       invalidate() {
         const utils2 = target;
         return getQueryClient().invalidateQueries({ queryKey: utils2.key() });

package/dist/runtime/client/error.d.ts

@@ -4,17 +4,20 @@ type ErrorOf<TPromise extends Promise<unknown>> = TPromise extends {
         type: infer Error;
     };
 } ? Error : never;
-type DefinedError<TPromise extends Promise<unknown>> = Extract<ErrorOf<TPromise>, AnyORPCError>;
-type DefinedErrorCode<TPromise extends Promise<unknown>> = DefinedError<TPromise>["code"] & string;
+type DefinedError<TError> = Extract<TError, AnyORPCError>;
+/** Error codes declared by a procedure whose client error union is `TError`. */
+export type DefinedErrorCode<TError> = DefinedError<TError>["code"] & string;
 type ErrorResultValue = string | number | boolean | bigint | symbol | null | undefined | readonly unknown[] | {
     readonly [key: string]: unknown;
 };
-type DefinedErrorHandlers<TPromise extends Promise<unknown>> = Partial<{
-    [Code in DefinedErrorCode<TPromise>]: ((error: Extract<DefinedError<TPromise>, {
+/** Handlers or result values keyed by the codes declared in the client error union `TError`. */
+export type DefinedErrorHandlers<TError> = Partial<{
+    [Code in DefinedErrorCode<TError>]: ((error: Extract<DefinedError<TError>, {
         code: Code;
     }>) => unknown) | ErrorResultValue;
 }>;
-type HandledResult<Handlers> = {
+/** The awaited result of any handler or value in `Handlers`. */
+export type HandledResult<Handlers> = {
     [Code in keyof Handlers]: Handlers[Code] extends (...args: never[]) => infer Result ? Awaited<Result> : Awaited<Handlers[Code]>;
 }[keyof Handlers];
 /**
@@ -28,5 +31,13 @@ type HandledResult<Handlers> = {
  * @param handlers - Handlers keyed by declared error code.
  * @returns The procedure output or the result of the matching handler.
  */
-export declare function catchORPCError<TPromise extends Promise<unknown>, Handlers extends object & DefinedErrorHandlers<NoInfer<TPromise>>>(promise: TPromise, handlers: "__error" extends keyof TPromise ? Handlers & Record<Exclude<keyof Handlers, DefinedErrorCode<NoInfer<TPromise>>>, never> : never): Promise<Awaited<TPromise> | HandledResult<Handlers>>;
+export declare function catchORPCError<TPromise extends Promise<unknown>, Handlers extends object & DefinedErrorHandlers<ErrorOf<NoInfer<TPromise>>>>(promise: TPromise, handlers: "__error" extends keyof TPromise ? Handlers & Record<Exclude<keyof Handlers, DefinedErrorCode<ErrorOf<NoInfer<TPromise>>>>, never> : never): Promise<Awaited<TPromise> | HandledResult<Handlers>>;
+/**
+ * Untyped runtime of `catchORPCError()` for callers that enforce handler types themselves.
+ *
+ * @param promise - A procedure call result.
+ * @param handlers - Handlers or result values keyed by declared error code.
+ * @returns The procedure output or the result of the matching handler.
+ */
+export declare function catchDefinedErrors(promise: Promise<unknown>, handlers: Record<string, unknown>): Promise<unknown>;
 export {};

package/dist/runtime/client/error.js

@@ -1,5 +1,8 @@
 import { isDefinedError } from "@orpc/client";
 export function catchORPCError(promise, handlers) {
+  return catchDefinedErrors(promise, handlers);
+}
+export function catchDefinedErrors(promise, handlers) {
   return promise.catch((error) => {
     const orpcError = error;
     if (!isDefinedError(orpcError)) throw error;

package/dist/runtime/types.d.ts

@@ -1,7 +1,8 @@
-import type { AnyNestedClient, Client, ClientContext } from "@orpc/client";
+import type { AnyNestedClient, Client, ClientContext, FriendlyClientOptions } from "@orpc/client";
 import type { RouterUtils } from "@orpc/tanstack-query";
 import type { QueryClient, SkipToken, UseMutationOptions, UseMutationReturnType, UseQueryOptions, UseQueryReturnType } from "@tanstack/vue-query";
 import type { ComputedRef, DeepReadonly, MaybeRefOrGetter, Ref, WritableComputedRef } from "vue";
+import type { DefinedErrorCode, DefinedErrorHandlers, HandledResult } from "./client/error.js";
 /** Configure cache ownership and key namespacing when wrapping an application-owned client. */
 export interface ORPCNuxtClientOptions {
     /** Separate the cache keys of clients whose procedure paths overlap. */
@@ -11,7 +12,8 @@ export interface ORPCNuxtClientOptions {
 }
 /**
  * An oRPC client decorated with Vue composables and the official TanStack Query utilities.
- * Router branches retain their names; finite procedures gain query and mutation composables.
+ * Router branches retain their names; finite procedures gain query and mutation composables
+ * and `callCatching()`.
  * Procedures whose output includes an async iterable retain only the upstream utilities.
  */
 export type ORPCNuxtClient<T extends AnyNestedClient> = RouterUtils<T> & {
@@ -85,5 +87,10 @@ interface ProcedureHooks<C extends ClientContext, I, O, E> {
     }>>): AwaitableQuery<ORPCQueryResult<O, E>>;
     /** Create a mutation observer; call mutate or mutateAsync to execute the procedure. */
     useMutation<M = unknown>(...args: object extends C ? [options?: MaybeRefOrGetter<ORPCMutationOptions<C, I, O, E, M>>] : [options: MaybeRefOrGetter<ORPCMutationOptions<C, I, O, E, M>>]): UseMutationReturnType<O, E, I, M>;
+    /**
+     * Call the procedure and handle selected declared errors like `catchORPCError()`.
+     * Pass `undefined` as input for procedures without input.
+     */
+    callCatching<Handlers extends object & DefinedErrorHandlers<E>>(input: I, handlers: Handlers & Record<Exclude<keyof Handlers, DefinedErrorCode<E>>, never>, ...rest: object extends C ? [options?: FriendlyClientOptions<C>] : [options: FriendlyClientOptions<C>]): Promise<O | HandledResult<Handlers>>;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orpc-nuxt",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "oRPC integration for Nuxt with TanStack Vue Query composables.",
   "homepage": "https://github.com/IlyaSemenov/orpc-nuxt#readme",
   "bugs": "https://github.com/IlyaSemenov/orpc-nuxt/issues",