orpc-nuxt 0.2.0 → 0.3.0

package/README.md

@@ -432,66 +432,77 @@ const orpc = createORPCNuxtClient(client, { prefix: "blog" })
 
 ### Component tests
 
-Component tests need the Nuxt environment of `@nuxt/test-utils`:
+Configure the Nuxt test environment and load a shared setup file:
 
 ```ts
 // vitest.config.ts
 import { defineVitestConfig } from "@nuxt/test-utils/config"
 
-export default defineVitestConfig({})
+export default defineVitestConfig({
+  test: {
+    setupFiles: ["test/nuxt/setup.ts"],
+  },
+})
 ```
 
 That configuration runs every test under `test/nuxt/` or `tests/nuxt/`, and every test named `*.nuxt.test.ts` or `*.nuxt.spec.ts`, against your application.
-Replace `useOrpc()` with a client that returns fixed data, then mount the component with `mountSuspended()` so its awaited queries resolve before the assertions.
-The replacement can be any nested object of async functions; only the procedures the component calls have to exist.
+Use `createTestORPCClient()` from `orpc-nuxt/testing` to replace `useOrpc()` with an isolated fake client.
+`client` includes the regular composables and oRPC utilities.
+Each procedure leaf in `procedures` has a `.handle()` method that registers a typed handler and returns a Vitest mock.
 
 ```ts
-// test/nuxt/post-list.spec.ts
-import { mockNuxtImport, mountSuspended } from "@nuxt/test-utils/runtime"
+// test/nuxt/setup.ts
+import { mockNuxtImport } from "@nuxt/test-utils/runtime"
+import type { RouterClient } from "@orpc/server"
 import { QueryClient } from "@tanstack/vue-query"
-import { createORPCNuxtClient } from "orpc-nuxt/client"
-import { afterEach, expect, test } from "vitest"
+import { createTestORPCClient } from "orpc-nuxt/testing"
+import { afterEach } from "vitest"
 
-import PostList from "~/components/post-list.vue"
+import type { router } from "~~/server/rpc/router"
 
 const queryClient = new QueryClient({
   // Report a failing procedure instead of retrying it until the test times out.
   defaultOptions: { queries: { retry: false } },
 })
 
-const orpc = createORPCNuxtClient(
-  {
-    blog: {
-      posts: {
-        list: async () => [{ id: 1, title: "First post" }],
-      },
-    },
-  },
-  { queryClient },
-)
+export const { client, procedures, reset } = createTestORPCClient<RouterClient<typeof router>>({
+  queryClient,
+})
 
-// Vitest runs this factory before the file body, so it must return the composable without calling it.
-mockNuxtImport("useOrpc", () => () => orpc)
+// Return the composable itself; Vitest hoists this factory before the setup file runs.
+mockNuxtImport("useOrpc", () => () => client)
 
 afterEach(() => {
-  // Start every test from an empty cache, so an earlier response cannot satisfy a later query.
-  queryClient.clear()
+  reset() // Remove registered handlers.
+  queryClient.clear() // Remove cached responses.
 })
+```
+
+`orpc-nuxt/testing` does not import `nuxt/app`, so the hoisted `mockNuxtImport()` factory can load it safely.
+The explicit QueryClient keeps the test cache isolated and lets the setup clear it after each test.
+To use the application's QueryClient instead, omit the option and configure its defaults through `orpc.queryClient`.
+In that mode, import `useOrpcQueryClient()` only from a module that the hoisted factory cannot reach.
+
+Register the required handlers before mounting; `mountSuspended()` waits for awaited queries before assertions:
+
+```ts
+// test/nuxt/post-list.spec.ts
+import { mountSuspended } from "@nuxt/test-utils/runtime"
+import { expect, test } from "vitest"
+
+import PostList from "~/components/post-list.vue"
+
+import { procedures } from "./setup"
 
 test("renders the posts", async () => {
+  const list = procedures.blog.posts.list.handle(() => [{ id: 1, title: "First post" }])
   const component = await mountSuspended(PostList)
+
   expect(component.text()).toContain("First post")
+  expect(list).toHaveBeenCalledOnce()
 })
 ```
 
-Passing an explicit `queryClient` gives the tests their own cache:
-
-- The application's cache never carries data from one test into the next.
-- Test defaults such as `retry: false` stay in the test file instead of the module options.
-
-Omit it to test against the cache the module installs.
-Read that one with `useOrpcQueryClient()`, and set its defaults through the `orpc.queryClient` module options.
-
 ### 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.2.0",
+  "version": "0.3.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/runtime/testing.d.ts

@@ -0,0 +1,34 @@
+import type { AnyNestedClient, Client } from "@orpc/client";
+import type { Mock } from "vitest";
+import type { ORPCNuxtClient, ORPCNuxtClientOptions } from "./types.js";
+type MaybePromise<T> = T | Promise<T>;
+/** 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. */
+export interface TestORPCProcedure<TProcedure> {
+    /** Register the implementation used by subsequent calls and return its Vitest mock. */
+    handle(handler: TestORPCHandler<TProcedure>): Mock<TestORPCHandler<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>> : {
+    [Key in keyof T]: T[Key] extends AnyNestedClient ? TestORPCProcedures<T[Key]> : never;
+};
+/** The isolated client, procedure registry and cleanup function created for a test suite. */
+export interface TestORPCClient<T extends AnyNestedClient> {
+    /** The decorated client to return from a mocked `useOrpc()`. */
+    client: ORPCNuxtClient<T>;
+    /** Register typed implementations and receive Vitest mocks for call assertions. */
+    procedures: TestORPCProcedures<T>;
+    /** Remove every registered procedure implementation. */
+    reset: () => void;
+}
+/**
+ * Create an isolated fake oRPC client for Nuxt component tests.
+ * The entrypoint has no Nuxt runtime dependency.
+ * A shared setup file can therefore import it when Vitest hoists `mockNuxtImport()`.
+ *
+ * @param options - Cache key prefix and an optional test-owned QueryClient.
+ * @returns A decorated client, its typed registration tree and a registration reset function.
+ */
+export declare function createTestORPCClient<T extends AnyNestedClient>(options?: ORPCNuxtClientOptions): TestORPCClient<T>;
+export {};

package/dist/runtime/testing.js

@@ -0,0 +1,60 @@
+import { createORPCClient } from "@orpc/client";
+import { vi } from "vitest";
+import { createORPCNuxtClient } from "./client/create.js";
+export function createTestORPCClient(options = {}) {
+  const registrations = /* @__PURE__ */ new Map();
+  function registerHandler(path, handler) {
+    const mock = vi.fn(handler);
+    registrations.set(path, mock);
+    return mock;
+  }
+  async function callHandler(path, input) {
+    const handler = registrations.get(path);
+    if (!handler) {
+      throw new Error(`No test handler is registered for oRPC procedure "${path}"`);
+    }
+    return await handler(input);
+  }
+  const link = {
+    async call(path, input) {
+      return await callHandler(path.join("."), input);
+    }
+  };
+  const client = createORPCNuxtClient(createORPCClient(link), options);
+  const procedures = createRecursiveProxy([], (path, args) => {
+    if (path.at(-1) !== "handle") {
+      throw new Error(`Unknown test procedure call: ${path.join(".")}`);
+    }
+    const handler = args[0];
+    if (typeof handler !== "function") {
+      throw new TypeError(
+        `A test handler must be a function for oRPC procedure "${path.slice(0, -1).join(".")}"`
+      );
+    }
+    return registerHandler(path.slice(0, -1).join("."), handler);
+  });
+  return {
+    client,
+    procedures,
+    reset: () => registrations.clear()
+  };
+}
+function createRecursiveProxy(path, call) {
+  const target = () => {
+  };
+  const children = /* @__PURE__ */ new Map();
+  return new Proxy(target, {
+    get(_, property, receiver) {
+      if (typeof property !== "string" || property === "then") {
+        return Reflect.get(target, property, receiver);
+      }
+      if (children.has(property)) return children.get(property);
+      const child = createRecursiveProxy([...path, property], call);
+      children.set(property, child);
+      return child;
+    },
+    apply(_, __, args) {
+      return call(path, args);
+    }
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orpc-nuxt",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -33,6 +33,10 @@
       "types": "./dist/runtime/plugin.d.ts",
       "import": "./dist/runtime/plugin.js"
     },
+    "./testing": {
+      "types": "./dist/runtime/testing.d.ts",
+      "import": "./dist/runtime/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -81,7 +85,13 @@
     "@orpc/tanstack-query": "^2.0.0-beta.35",
     "@tanstack/vue-query": "^5.102.8",
     "nuxt": "^3.14.1592 || ^4.0.1",
+    "vitest": "^4.0.0 || ^5.0.0",
     "vue": "^3.5.0"
   },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "packageManager": "bun@1.3.14"
 }