orpc-nuxt 0.4.0 → 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.
@@ -524,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.
@@ -553,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.4.0",
+  "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/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.4.0",
+  "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"
+  }
 }