orpc-nuxt 0.3.1 → 0.5.0

package/README.md

@@ -171,6 +171,39 @@ Use `.call()` when you just need a procedure's response, without query state or
 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:
+
+```ts
+import { catchORPCError } from "orpc-nuxt/client"
+
+const post = await catchORPCError(orpc.blog.posts.update.call(input), {
+  CONFLICT: (error) => {
+    message.value = error.message
+    conflictingField.value = error.data.field
+  },
+  NOT_FOUND: () => navigateTo("/posts"),
+})
+```
+
+The successful output, matching handler's awaited result, or matching non-function value becomes the call result.
+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
+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.
+```
+
 The client also exposes oRPC's utilities:
 
 - `.key()` builds a cache key prefix for a procedure or router branch.
@@ -289,9 +322,42 @@ Relative URLs resolve against the current request URL during SSR.
 Only headers listed in `forwardHeaders` are forwarded from the incoming SSR request.
 `credentials: "include"` allows browser cookies on cross-origin requests.
 
+### Custom link
+
+Return a custom `link` when the server needs a request-scoped transport while the browser should keep a regular HTTP transport:
+
+```ts
+// app/plugins/orpc.ts
+import { RPCLink } from "@orpc/client/fetch"
+import type { RouterClient } from "@orpc/server"
+import { getRequestURL } from "h3"
+import { defineNuxtPlugin } from "orpc-nuxt/plugin"
+import type { router } from "~~/server/rpc/router"
+
+export default defineNuxtPlugin<RouterClient<typeof router>>(() => ({
+  link: ({ event }) => {
+    if (!event) return new RPCLink({ url: "/api/rpc" })
+
+    const requestFetch = event.context.nuxtMultiApp.createFetch("web")
+    const endpoint = new URL("/api/rpc", getRequestURL(event))
+
+    return new RPCLink({
+      origin: endpoint.origin,
+      url: endpoint.pathname as `/${string}`,
+      fetch: requestFetch,
+    })
+  },
+}))
+```
+
+The link factory receives `{ nuxtApp, event }`, where `event` is the current H3 event during SSR and `undefined` in the browser.
+It runs once per Nuxt application, so every SSR request gets its own link.
+The plugin setup callback has the same lifecycle: once per SSR request and once when the browser app starts.
+`orpc-nuxt` still creates the typed client, decorates it with Vue Query composables, and provides `$orpc`.
+
 ### Manual client setup
 
-Use `createORPCNuxtClient` when you need a custom transport or want SSR to call the router directly.
+Use `createORPCNuxtClient` when you want SSR to call the router directly or need to own the complete client setup.
 Instead of the shared HTTP plugin above, add a browser plugin and a server plugin.
 
 Keep `orpc-nuxt` in `modules`: manual setup replaces that plugin, not the module that installs the QueryClient and the composables.
@@ -491,6 +557,19 @@ test("renders the posts", async () => {
 })
 ```
 
+Use `createORPCError()` when a fake procedure must reproduce a declared rejection:
+
+```ts
+import { createORPCError } from "orpc-nuxt/testing"
+
+procedures.blog.posts.update.handle(() => {
+  throw createORPCError("CONFLICT", "Already exists", { field: "title" })
+})
+```
+
+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.
@@ -520,14 +599,16 @@ try {
 
 ## Development
 
-Install dependencies with `bun install`, then run `bun run build`, `bun run types`, and `bun run test`.
+Install dependencies from the repository root with `bun install`.
+Run `bun run build`, `bun run types`, and `bun run test` from this package's directory.
 
 Run `bun run test:component` to check the documented component-test recipe in the fixture application; it uses the built package, so build first.
 
 To try the package in a Nuxt app, build it and run `bunx nuxt dev tests/fixtures/nuxt`.
 The example app uses the built package, so rebuild after changing its source.
 
-Run `bunx playwright install chromium-headless-shell`, then `bun run test:nuxt` to check the packed npm archive with the Nuxt version installed in the workspace.
+From the repository root, install the shared test browser with `bunx playwright install chromium-headless-shell`.
+Then run `bun run test:nuxt` from this package's directory to check the packed npm archive with the Nuxt version installed in the workspace.
 It is checked with both module-managed and app-managed QueryClients, including types, SSR, and hydration in development and production.
 
 To check other Nuxt versions by hand, pass them explicitly: `bun run test:nuxt 3.14.1592 4.0.1`.

package/dist/module.d.mts

@@ -1,4 +1,4 @@
-import * as _nuxt_schema from '@nuxt/schema';
+import * as nuxt_schema from 'nuxt/schema';
 import { StaticQueryClientConfig } from '../dist/runtime/nuxt/query-config.js';
 export { StaticQueryClientConfig } from '../dist/runtime/nuxt/query-config.js';
 export { ORPCRuntimeHooks as ModuleRuntimeHooks } from '../dist/runtime/nuxt/hooks.js';
@@ -8,7 +8,7 @@ interface ModuleOptions {
     /** Set static query defaults, or use false when another plugin owns Vue Query and hydration. */
     queryClient?: boolean | StaticQueryClientConfig;
 }
-declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+declare const _default: nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
 export type { ModuleOptions };

package/dist/module.json

@@ -4,9 +4,9 @@
   "compatibility": {
     "nuxt": "^3.14.1592 || ^4.0.1"
   },
-  "version": "0.3.1",
+  "version": "0.5.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
-    "unbuild": "3.6.1"
+    "unbuild": "unknown"
   }
 }

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

@@ -0,0 +1,32 @@
+import { type AnyORPCError } from "@orpc/client";
+type ErrorOf<TPromise extends Promise<unknown>> = TPromise extends {
+    __error?: {
+        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 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>, {
+        code: Code;
+    }>) => unknown) | ErrorResultValue;
+}>;
+type HandledResult<Handlers> = {
+    [Code in keyof Handlers]: Handlers[Code] extends (...args: never[]) => infer Result ? Awaited<Result> : Awaited<Handlers[Code]>;
+}[keyof Handlers];
+/**
+ * Handle selected errors declared by an oRPC procedure and rethrow every other rejection.
+ * The promise must come directly from a typed client call so its declared error union is preserved.
+ * Each handler receives the declared error branch narrowed to its own code.
+ * A non-function value is returned directly when its error code matches.
+ * Synchronous and asynchronous handler results are included in the returned promise type.
+ *
+ * @param promise - The `PromiseWithError` returned by an oRPC client procedure.
+ * @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 {};

package/dist/runtime/client/error.js

@@ -0,0 +1,10 @@
+import { isDefinedError } from "@orpc/client";
+export function catchORPCError(promise, handlers) {
+  return promise.catch((error) => {
+    const orpcError = error;
+    if (!isDefinedError(orpcError)) throw error;
+    if (!Object.hasOwn(handlers, orpcError.code)) throw error;
+    const handler = handlers[orpcError.code];
+    return typeof handler === "function" ? handler(orpcError) : handler;
+  });
+}

package/dist/runtime/client.d.ts

@@ -1,2 +1,3 @@
 export { createORPCNuxtClient } from "./client/create.js";
+export { catchORPCError } from "./client/error.js";
 export type { AwaitableQuery, ORPCMutationOptions, ORPCNuxtClient, ORPCNuxtClientOptions, ORPCQueryOptions, ORPCQueryResult, ORPCSelectedQueryResult, } from "./types.js";

package/dist/runtime/client.js

@@ -1 +1,2 @@
 export { createORPCNuxtClient } from "./client/create.js";
+export { catchORPCError } from "./client/error.js";

package/dist/runtime/nuxt/define-plugin.d.ts

@@ -1,8 +1,23 @@
-import { type AnyNestedClient } from "@orpc/client";
+import { type AnyNestedClient, type ClientLink, type InferClientContext } from "@orpc/client";
 import { type NuxtApp, type Plugin } from "nuxt/app";
 import type { ORPCNuxtClient, ORPCNuxtClientOptions } from "../types.js";
-/** Configure the HTTP transport and cache used by a Nuxt app's injected oRPC client. */
-export interface OrpcPluginOptions extends ORPCNuxtClientOptions {
+/** Nuxt state available while creating one app's custom oRPC link. */
+export interface OrpcLinkContext {
+    /** The Nuxt application that will own the client. */
+    nuxtApp: NuxtApp;
+    /** The current H3 request event during SSR, or undefined in the browser. */
+    event: NonNullable<NuxtApp["ssrContext"]>["event"] | undefined;
+}
+/** Configure the transport and cache used by a Nuxt app's injected oRPC client. */
+export type OrpcPluginOptions<T extends AnyNestedClient = AnyNestedClient> = ORPCNuxtClientOptions & ({
+    /** Use an application-owned link or create one for each Nuxt application. */
+    link: ClientLink<InferClientContext<T>> | ((context: OrpcLinkContext) => ClientLink<InferClientContext<T>>);
+    url?: never;
+    serverUrl?: never;
+    credentials?: never;
+    forwardHeaders?: never;
+} | {
+    link?: never;
     /** RPC handler URL, including its path; relative URLs resolve against the current page URL. */
     url: string;
     /** Optional SSR handler URL; an absent or empty value falls back to url. */
@@ -11,13 +26,14 @@ export interface OrpcPluginOptions extends ORPCNuxtClientOptions {
     credentials?: RequestCredentials;
     /** Incoming headers to forward during SSR; only explicitly listed headers are forwarded. */
     forwardHeaders?: readonly string[];
-}
+});
 /**
- * Create an HTTP client per Nuxt app and provide it as $orpc with inferred router types.
+ * Create an oRPC client per Nuxt app and provide it as $orpc with inferred router types.
  * The setup callback runs once per SSR request and once when the browser app starts.
+ * A custom link factory also runs once per app and receives its Nuxt app and H3 event.
  * Install Vue Query before this plugin, or return an explicit queryClient from setup.
  * Its QueryClient is captured immediately, so invalidate works before any composable runs.
  */
-export declare function defineNuxtPlugin<T extends AnyNestedClient>(setup: (nuxtApp: NuxtApp) => OrpcPluginOptions): Plugin<{
+export declare function defineNuxtPlugin<T extends AnyNestedClient>(setup: (nuxtApp: NuxtApp) => OrpcPluginOptions<T>): Plugin<{
     orpc: ORPCNuxtClient<T>;
 }>;

package/dist/runtime/nuxt/define-plugin.js

@@ -1,4 +1,6 @@
-import { createORPCClient } from "@orpc/client";
+import {
+  createORPCClient
+} from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
 import {
   defineNuxtPlugin as createNuxtPlugin,
@@ -16,25 +18,7 @@ export function defineNuxtPlugin(setup) {
         "orpc-nuxt: install Vue Query before the oRPC plugin. Enable the module's QueryClient, use enforce: 'pre' in your Vue Query plugin, or pass queryClient explicitly."
       );
     }
-    const url = import.meta.server ? options.serverUrl || options.url : options.url;
-    const endpoint = new URL(url, useRequestURL());
-    if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
-      throw new Error("orpc-nuxt: the RPC handler URL must use HTTP or HTTPS.");
-    }
-    const link = new RPCLink({
-      // oRPC v2 accepts the origin separately from the handler path and query string.
-      origin: endpoint.origin,
-      // HTTP URL.pathname always starts with the slash required by StandardUrl.
-      url: `${endpoint.pathname}${endpoint.search}`,
-      // An explicit empty list is essential: undefined would forward every incoming header.
-      headers: useRequestHeaders([...options.forwardHeaders ?? []]),
-      fetch(url2, init) {
-        return globalThis.fetch(url2, {
-          ...init,
-          credentials: options.credentials
-        });
-      }
-    });
+    const link = typeof options.link === "function" ? options.link({ nuxtApp, event: nuxtApp.ssrContext?.event }) : options.link ?? createHTTPLink(options);
     const client = createORPCClient(link);
     const orpc = createORPCNuxtClient(client, {
       prefix: options.prefix,
@@ -45,3 +29,24 @@ export function defineNuxtPlugin(setup) {
     };
   });
 }
+function createHTTPLink(options) {
+  const url = import.meta.server ? options.serverUrl || options.url : options.url;
+  const endpoint = new URL(url, useRequestURL());
+  if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
+    throw new Error("orpc-nuxt: the RPC handler URL must use HTTP or HTTPS.");
+  }
+  return new RPCLink({
+    // oRPC v2 accepts the origin separately from the handler path and query string.
+    origin: endpoint.origin,
+    // HTTP URL.pathname always starts with the slash required by StandardUrl.
+    url: `${endpoint.pathname}${endpoint.search}`,
+    // An explicit empty list is essential: undefined would forward every incoming header.
+    headers: useRequestHeaders([...options.forwardHeaders ?? []]),
+    fetch(url2, init) {
+      return globalThis.fetch(url2, {
+        ...init,
+        credentials: options.credentials
+      });
+    }
+  });
+}

package/dist/runtime/plugin.d.ts

@@ -1,2 +1,2 @@
 export { defineNuxtPlugin } from "./nuxt/define-plugin.js";
-export type { OrpcPluginOptions } from "./nuxt/define-plugin.js";
+export type { OrpcLinkContext, OrpcPluginOptions } from "./nuxt/define-plugin.js";

package/dist/runtime/testing.d.ts

@@ -1,8 +1,27 @@
-import type { AnyNestedClient, Client } from "@orpc/client";
+import type { AnyNestedClient, Client, ORPCError, ORPCErrorCode } 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>;
 /** 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;
 /** Registration methods for one procedure in a test client. */

package/dist/runtime/testing.js

@@ -1,7 +1,10 @@
-import { createORPCClient } from "@orpc/client";
+import { createORPCClient, createORPCErrorFromJson } 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({

package/dist/runtime/vue-query/mutation.d.ts

@@ -8,4 +8,4 @@ import { type QueryClient } from "@tanstack/vue-query";
  * @param options - Mutation options, optionally wrapped in a ref or getter.
  * @param queryClient - An explicit cache owner; otherwise Vue Query uses the injected client.
  */
-export declare function useORPCMutation(target: object, options: unknown, queryClient?: QueryClient): import("@tanstack/vue-query").UseMutationReturnType<unknown, Error, unknown, unknown, Omit<import("@tanstack/query-core").MutationObserverIdleResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/query-core").MutationObserverLoadingResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/query-core").MutationObserverErrorResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/query-core").MutationObserverSuccessResult<unknown, Error, unknown, unknown>, "mutate" | "reset">>;
+export declare function useORPCMutation(target: object, options: unknown, queryClient?: QueryClient): import("@tanstack/vue-query").UseMutationReturnType<unknown, Error, unknown, unknown, Omit<import("@tanstack/vue-query").MutationObserverIdleResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/vue-query").MutationObserverLoadingResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/vue-query").MutationObserverErrorResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/vue-query").MutationObserverSuccessResult<unknown, Error, unknown, unknown>, "mutate" | "reset">>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orpc-nuxt",
-  "version": "0.3.1",
+  "version": "0.5.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",
@@ -8,7 +8,8 @@
   "author": "Ilya Semenov",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/IlyaSemenov/orpc-nuxt.git"
+    "url": "git+https://github.com/IlyaSemenov/orpc-nuxt.git",
+    "directory": "packages/orpc-nuxt"
   },
   "files": [
     "README.md",
@@ -45,14 +46,11 @@
   },
   "scripts": {
     "build": "nuxt-module-build build && publint",
-    "lint": "oxlint --fix && oxfmt",
-    "lint:check": "oxlint && oxfmt --check",
-    "prepare": "lefthook install",
-    "prepublishOnly": "bun run build",
     "test": "bun test src tests/runtime",
     "test:component": "vitest run --root tests/fixtures/nuxt",
     "test:nuxt": "bun tests/nuxt/run.ts",
-    "types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json && nuxt typecheck tests/fixtures/nuxt"
+    "types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json && nuxt typecheck tests/fixtures/nuxt",
+    "prepublishOnly": "bun run build"
   },
   "dependencies": {
     "@nuxt/kit": "^3.14.1592 || ^4.0.1",
@@ -60,23 +58,23 @@
     "es-toolkit": "^1.52.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.31.1",
     "@nuxt/cli": "^3.37.0",
     "@nuxt/module-builder": "^1.0.3",
     "@nuxt/test-utils": "^4.3.2",
+    "@orpc/client": "^2.0.0-beta.35",
     "@orpc/server": "2.0.0-beta.35",
-    "@playwright/test": "1.58.2",
+    "@orpc/tanstack-query": "^2.0.0-beta.35",
+    "@tanstack/vue-query": "^5.102.8",
     "@tsconfig/bun": "^1.0.10",
     "@types/bun": "^1.3.14",
     "@vue/server-renderer": "^3.5.0",
     "@vue/test-utils": "^2.5.0",
     "happy-dom": "^20.14.3",
     "nuxt": "^4.5.2",
-    "oxfmt": "^0.67.0",
-    "oxlint": "^1.82.0",
     "publint": "^0.3.22",
     "typescript": "^5.9.3",
     "vitest": "^5.0.0",
+    "vue": "^3.5.0",
     "vue-tsc": "^3.3.11",
     "zod": "^4.3.6"
   },
@@ -92,6 +90,5 @@
     "vitest": {
       "optional": true
     }
-  },
-  "packageManager": "bun@1.3.14"
+  }
 }