orpc-nuxt 0.5.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.
@@ -557,19 +562,20 @@ test("renders the posts", async () => {
 })
 ```
 
-Use `createORPCError()` when a fake procedure must reproduce a declared rejection:
+The second handler argument provides typed error constructors derived from that procedure's `.errors()` map:
 
 ```ts
-import { createORPCError } from "orpc-nuxt/testing"
-
-procedures.blog.posts.update.handle(() => {
-  throw createORPCError("CONFLICT", "Already exists", { field: "title" })
+procedures.blog.posts.update.handle((input, { errors }) => {
+  if (input.title === "taken") {
+    throw errors.CONFLICT({
+      message: "Already exists",
+      data: { field: "title" },
+    })
+  }
+  return { id: 1, ...input }
 })
 ```
 
-Because this helper is standalone, it cannot infer which fake procedure will throw the error.
-Its code and data are therefore not checked against that procedure's `.errors()` map.
-
 ### Outside Vue components
 
 You can call `.useQuery()` and `.useMutation()` outside a component, for example in a script or in a test that never mounts one.

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.14.1592 || ^4.0.1"
   },
-  "version": "0.5.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/testing.d.ts

@@ -1,33 +1,35 @@
-import type { AnyNestedClient, Client, ORPCError, ORPCErrorCode } from "@orpc/client";
+import type { AnyORPCError, AnyNestedClient, Client } from "@orpc/client";
+import { ORPCError } from "@orpc/client";
 import { QueryClient } from "@tanstack/vue-query";
 import type { Mock } from "vitest";
 import type { ORPCNuxtClient, ORPCNuxtClientOptions } from "./types.js";
 type MaybePromise<T> = T | Promise<T>;
-/**
- * Create an oRPC error marked as declared for a fake client procedure.
- * The standalone helper cannot infer a specific procedure, so its code is not limited to that procedure's `.errors()` map.
- *
- * @param code - The error code exposed to the client.
- * @param message - The human-readable error message.
- * @returns An error that `isDefinedError()` and `catchORPCError()` recognize as declared.
- */
-export declare function createORPCError<Code extends ORPCErrorCode>(code: Code, message: string): ORPCError<Code, undefined>;
-/**
- * Create an oRPC error with typed data marked as declared for a fake client procedure.
- * The standalone helper cannot infer a specific procedure, so its code and data are not checked against that procedure's `.errors()` map.
- *
- * @param code - The error code exposed to the client.
- * @param message - The human-readable error message.
- * @param data - Error data exposed to the client.
- * @returns An error that `isDefinedError()` and `catchORPCError()` recognize as declared.
- */
-export declare function createORPCError<Code extends ORPCErrorCode, Data>(code: Code, message: string, data: Data): ORPCError<Code, Data>;
+type ProcedureError<TProcedure> = TProcedure extends Client<any, any, any, infer Error> ? Extract<Error, AnyORPCError> : never;
+type ErrorConstructorOptions<Data> = ErrorOptions & {
+    message?: string;
+} & (undefined extends Data ? {
+    data?: Data;
+} : {
+    data: Data;
+});
+type ErrorConstructor<ErrorType extends AnyORPCError> = ErrorType extends ORPCError<infer _Code, infer Data> ? (...args: undefined extends Data ? [options?: ErrorConstructorOptions<Data>] : [options: ErrorConstructorOptions<Data>]) => ErrorType : never;
+type TestORPCErrors<TProcedure> = {
+    [Code in ProcedureError<TProcedure>["code"] & string]: ErrorConstructor<Extract<ProcedureError<TProcedure>, {
+        code: Code;
+    }>>;
+};
+/** Error constructors derived from the procedure's declared error union. */
+export interface TestORPCHandlerOptions<TProcedure> {
+    /** Construct an error declared by this procedure, with its corresponding data type. */
+    errors: TestORPCErrors<TProcedure>;
+}
 /** A procedure implementation registered for a test client. */
-export type TestORPCHandler<TProcedure> = TProcedure extends Client<infer _Context, infer Input, infer Output, infer _Error> ? (input: Input) => MaybePromise<Awaited<Output>> : never;
+export type TestORPCHandler<TProcedure> = TProcedure extends Client<infer _Context, infer Input, infer Output, infer _Error> ? (input: Input, options: TestORPCHandlerOptions<TProcedure>) => MaybePromise<Awaited<Output>> : never;
+type TestORPCMockHandler<TProcedure> = TProcedure extends Client<infer _Context, infer Input, infer Output, infer _Error> ? (input: Input) => MaybePromise<Awaited<Output>> : never;
 /** Registration methods for one procedure in a test client. */
 export interface TestORPCProcedure<TProcedure> {
     /** Register the implementation used by subsequent calls and return its Vitest mock. */
-    handle(handler: TestORPCHandler<TProcedure>): Mock<TestORPCHandler<TProcedure>>;
+    handle(handler: TestORPCHandler<TProcedure>): Mock<TestORPCMockHandler<TProcedure>>;
 }
 /** A router-shaped tree whose procedure leaves register test implementations. */
 export type TestORPCProcedures<T extends AnyNestedClient> = T extends Client<infer Context, infer Input, infer Output, infer Error> ? TestORPCProcedure<Client<Context, Input, Output, Error>> : {

package/dist/runtime/testing.js

@@ -1,10 +1,7 @@
-import { createORPCClient, createORPCErrorFromJson } from "@orpc/client";
+import { createORPCClient, createORPCErrorFromJson, ORPCError } from "@orpc/client";
 import { QueryClient } from "@tanstack/vue-query";
 import { vi } from "vitest";
 import { createORPCNuxtClient } from "./client/create.js";
-export function createORPCError(code, message, data) {
-  return createORPCErrorFromJson({ defined: true, code, message, data });
-}
 export function createTestORPCClient(options = {}) {
   const registrations = /* @__PURE__ */ new Map();
   const queryClient = options.queryClient ?? new QueryClient({
@@ -14,7 +11,8 @@ export function createTestORPCClient(options = {}) {
     }
   });
   function registerHandler(path, handler) {
-    const mock = vi.fn(handler);
+    const options2 = { errors: createErrorConstructors() };
+    const mock = vi.fn((input) => handler(input, options2));
     registrations.set(path, mock);
     return mock;
   }
@@ -53,6 +51,22 @@ export function createTestORPCClient(options = {}) {
     }
   };
 }
+function createErrorConstructors() {
+  const constructors = /* @__PURE__ */ new Map();
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(target, property, receiver) {
+      if (typeof property !== "string") return Reflect.get(target, property, receiver);
+      const cached = constructors.get(property);
+      if (cached) return cached;
+      const constructor = (options) => {
+        const error = new ORPCError(property, options);
+        return createORPCErrorFromJson({ ...error.toJSON(), defined: true }, { cause: error.cause });
+      };
+      constructors.set(property, constructor);
+      return constructor;
+    }
+  });
+}
 function createRecursiveProxy(path, call) {
   const target = () => {
   };

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.5.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",