next-zero-rpc 0.1.6 → 0.1.8

package/README.md

@@ -38,32 +38,46 @@ if (err) {
 }
 ```
 
-### How it compares
-
-| Feature                   | next-zero-rpc        | tRPC        | raw fetch |
-| ------------------------- | -------------------- | ----------- | --------- |
-| Type-safe paths           | ✅                   | ✅          | ❌        |
-| Type-safe responses       | ✅                   | ✅          | ❌        |
-| Type-safe methods         | ✅                   | N/A         | ❌        |
-| **Error type narrowing**  | ✅                   | ❌          | ❌        |
-| Zero runtime cost         | ✅ (1.8 KB minified) | ❌ (~14 KB) | ✅        |
-| Zero config               | ✅                   | ❌          | ✅        |
-| Standard API routes       | ✅                   | ❌          | ✅        |
-| Dynamic params `[id]`     | ✅                   | ✅          | N/A       |
-| Catch-all `[...slug]`     | ✅                   | ✅          | N/A       |
-| Go-style error handling   | ✅                   | ❌          | ❌        |
-| Exhaustive error checking | ✅                   | ❌          | ❌        |
-| Server action helpers     | ✅                   | ❌          | N/A       |
-| Dependencies              | 0                    | 5+          | 0         |
+### The 2026 Ecosystem Comparison
+
+| Feature                     | next-zero-rpc                          | tRPC                              | ts-rest                         | raw fetch         |
+| --------------------------- | -------------------------------------- | --------------------------------- | ------------------------------- | ----------------- |
+| Primary Philosophy          | Invisible type bridge                  | End-to-end framework              | Contract-first API              | Platform standard |
+| Source of Truth             | Next.js Route Handlers                 | tRPC Routers / Procedures         | Shared contract.ts file         | None              |
+| Type-safe paths & responses | ✅                                     | ✅                                | ✅                              | ❌                |
+| Per-route error narrowing   | ✅ (via TypeScript generics)           | ❌ (Global error shapes)          | ❌ (Standardized HTTP errors)   | ❌                |
+| Next.js App Router Native   | ✅ (Zero changes to standard handlers) | ❌ (Requires tRPC adapters)       | ❌ (Requires ts-rest adapters)  | ✅                |
+| Input Validation            | Bring-your-own                         | Built-in (Zod heavily favored)    | Built-in (Zod favored)          | Bring-your-own    |
+| OpenAPI Generation          | ❌                                     | ❌ (Requires third-party plugins) | ✅ (First-class citizen)        | ❌                |
+| Client Runtime Size         | ~1.8 KB                                | ~15 KB                            | ~3-5 KB                         | 0 KB              |
+| Server Actions Integration  | ✅ (Tuple-based Go-style returns)      | ✅ (Excellent RSC/Action support) | Partial (Focus remains on REST) | N/A               |
+| Non-TS Client Support       | ❌                                     | ❌                                | ✅ (Via standard REST/OpenAPI)  | ✅                |
+| Ecosystem & Community       | Niche / Lightweight                    | Massive / Enterprise-grade        | Very Strong / Standardized      | Ubiquitous        |
+
+#### Architectural Breakdown: Which to Choose?
+
+##### 1. next-zero-rpc (The Minimalist Bridge)
+
+- **Best for:** Teams deeply invested in the Next.js App Router who want type safety without adopting a new framework paradigm.
+- **The draw:** You write standard \`export async function GET(req)\` handlers. The library just quietly infers what you wrote. If you ever decide to remove the library, your backend code doesn't have to change at all.
+- **The trade-off:** You give up the robust middleware pipelines, batched requests, and automatic OpenAPI generation that larger ecosystems provide.
+
+## When to use this
+
+**Use `next-zero-rpc` when:**
+
+- You're already writing plain Next.js App Router route handlers and want type-safe `fetch` calls _without restructuring your backend_ into tRPC procedures or ts-rest contracts
+- Per-route error code narrowing matters to you — this is genuinely not available in tRPC or ts-rest out of the box
+- You want a tiny client footprint (~1.8 KB) and zero ongoing npm dependencies
 
 ## Philosophy
 
 **You own the code, not the library.** `next-zero-rpc` is not a locked-in framework—it's a philosophy, a paradigm, and a set of methods for doing things. When you run `init`, we give you four files. From that moment on, they are _yours_ to modify, extend, or delete.
 
-- **Zero vendor lock-in** — There is no black-box `node_modules` dependency dictating your architecture. You own the fetch client, the error codes, and the registry generator.
+- **Zero vendor lock-in** — There is no black-box `node_modules` dependency dictating your architecture. You own the fetch client, the error codes, and the registry generator. If the maintainer disappears tomorrow, you're not blocked.
 - **Zero boilerplate** — You write standard Next.js API route handlers using simple response helpers — no decorators, no schema registrations, no complex abstractions. The codegen reads what already exists and builds the type bridge automatically.
 - **Not a framework** — It's a type bridge. It infers what your route handlers return and gives your client code full type safety over those responses.
-- **Validation is yours** — Input validation (Zod, Valibot, Arktype, manual checks) stays inside your route handler where it belongs. This library doesn't impose a validation layer — that's a feature, not a gap.
+- **Validation is yours** — Input validation (Zod, Valibot, Arktype, manual checks) stays inside your route handler where it belongs. This library doesn't impose a validation layer — that's a deliberate design choice.
 - **Non-invasive** — Unlike tRPC or ts-rest, you don't adopt a new API definition pattern. Your routes are regular Next.js routes. The library is invisible.
 
 ## Setup
@@ -177,7 +191,7 @@ This works because:
 
 1. `createApiError` is generic: `createApiError<C extends ErrorCode>(code: C, ...) → NextResponse<ApiErrorPayload<C>>`
 2. TypeScript infers the literal `C` from each call site in your handler
-3. `InferErrorApiResponse` extracts the union of all `ApiErrorPayload<C>` types from the handler's return type
+3. `UnwrapNextResponse` extracts the union of all `ApiErrorPayload<C>` types from the handler's return type
 4. The client sees only those specific error codes
 
 ### Go-Style Tuple Returns
@@ -241,6 +255,18 @@ const [data, err] = await apiFetch("/api/extreme/org1/projects/proj1/tasks/a/b/c
 const [data, err] = await apiFetch("/api/users/123?include=profile", { method: "GET" });
 ```
 
+### Static vs Dynamic Route Precedence
+
+If you have overlapping static and dynamic routes (e.g., `/api/users/active` and `/api/users/[userId]`), `next-zero-rpc` correctly gives **exact static matches precedence** over dynamic segments at compile time.
+
+```typescript
+// Safely infers the type of the `active` route, completely ignoring the `[userId]` route
+const [activeUsers] = await apiFetch("/api/users/active", { method: "GET" });
+
+// Safely infers the type of the `[userId]` route
+const [singleUser] = await apiFetch("/api/users/123", { method: "GET" });
+```
+
 ### Route Groups Support
 
 Next.js route groups like `(groupName)` are natively supported. They are automatically ignored in the URL path mapping and the generated TypeScript types, perfectly matching Next.js behavior:
@@ -369,15 +395,15 @@ HTTP_STATUS_ERROR.GATEWAY_TIMEOUT; // 504
 
 #### Functions
 
-| Function                  | Signature                                                                      | Description                           |
-| ------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- |
-| `createApiError<C>`       | `(code: C, statusCode, options?) → NextResponse<ApiErrorPayload<C>>`           | Create a typed API error response     |
-| `createApiSuccess<T>`     | `(data: T, statusCode?) → NextResponse<T>`                                     | Create a typed API success response   |
-| `createApiSuccess`        | `(undefined, NO_CONTENT) → NextResponse<undefined>`                            | Overload for 204 No Content           |
-| `isApiErrorPayload`       | `(payload: unknown) → payload is ApiErrorPayload<ErrorCode>`                   | Runtime type guard for error payloads |
-| `createServiceError`      | `(code, options?) → [null, ServiceError]`                                      | Go-style error for server actions     |
-| `createServiceSuccess<T>` | `(data?: T) → [T \| undefined, null]`                                          | Go-style success for server actions   |
-| `assertNever`             | `(value: never) → never`                                                       | Compile-time exhaustiveness guard     |
+| Function                  | Signature                                                            | Description                           |
+| ------------------------- | -------------------------------------------------------------------- | ------------------------------------- |
+| `createApiError<C>`       | `(code: C, statusCode, options?) → NextResponse<ApiErrorPayload<C>>` | Create a typed API error response     |
+| `createApiSuccess<T>`     | `(data: T, statusCode?) → NextResponse<T>`                           | Create a typed API success response   |
+| `createApiSuccess`        | `(undefined, NO_CONTENT) → NextResponse<undefined>`                  | Overload for 204 No Content           |
+| `isApiErrorPayload`       | `(payload: unknown) → payload is ApiErrorPayload<ErrorCode>`         | Runtime type guard for error payloads |
+| `createServiceError`      | `(code, options?) → [null, ServiceError]`                            | Go-style error for server actions     |
+| `createServiceSuccess<T>` | `(data?: T) → [T \| undefined, null]`                                | Go-style success for server actions   |
+| `assertNever`             | `(value: never) → never`                                             | Compile-time exhaustiveness guard     |
 
 ### `apiClient.ts`
 
@@ -515,7 +541,7 @@ Since you own all the source files, you can customize anything:
 
 [![Open in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/github/caocchinh/next-zero-rpc/tree/main/examples/minimal)
 
-Opens [`examples/minimal`](https://github.com/caocchinh/next-zero-rpc/tree/main/examples/minimal) — a self-contained Next.js app with a working `apiFetch` client and two example API routes.
+Opens [`examples/minimal`](./examples/minimal) — a self-contained Next.js app with a working `apiFetch` client and two example API routes.
 
 ### Run locally
 
@@ -538,11 +564,11 @@ npx next-zero-rpc --help       # Show help
 
 ## Requirements
 
-| Requirement | Minimum Version | Reason |
-| ----------- | --------------- | ------ |
-| Next.js | **14.0** | App Router (stable since 14.0) |
-| TypeScript | **4.9** | `satisfies` keyword used in `responses.ts` |
-| Node.js | **18** | Native `fetch` API required by `apiFetch` |
+| Requirement | Minimum Version | Reason                                     |
+| ----------- | --------------- | ------------------------------------------ |
+| Next.js     | **14.0**        | App Router (stable since 14.0)             |
+| TypeScript  | **4.9**         | `satisfies` keyword used in `responses.ts` |
+| Node.js     | **18**          | Native `fetch` API required by `apiFetch`  |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-zero-rpc",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Type-safe fetch for Next.js — zero runtime, zero config, zero dependencies.",
   "keywords": [
     "nextjs",

package/templates/apiClient.ts

@@ -18,8 +18,8 @@ type UnwrapNextResponse<T> = T extends (...args: never[]) => infer R
 type ResolveRoute<Path extends string> =
   FindMatchingRoute<Path> extends keyof KnownRoutes ? FindMatchingRoute<Path> : never;
 
-type RouteHandler<Path extends string, M extends HttpMethod> =
-  KnownRoutes[ResolveRoute<Path>][M & keyof KnownRoutes[ResolveRoute<Path>]];
+type RouteHandler<Path extends string, M extends HttpMethod> = KnownRoutes[ResolveRoute<Path>][M &
+  keyof KnownRoutes[ResolveRoute<Path>]];
 
 type RouteMethods<Path extends string> = Extract<keyof KnownRoutes[ResolveRoute<Path>], HttpMethod>;
 
@@ -56,7 +56,7 @@ export async function apiFetch(
 
     let payload;
     // An empty HTTP body resolves to an empty string "" (falsy).
-    // Valid JSON primitives like `0`, `null`, `false`, or `""` serialize to 
+    // Valid JSON primitives like `0`, `null`, `false`, or `""` serialize to
     // length > 0 strings (e.g. `"0"`, `"null"`, `'""'`), which are all truthy.
     // This perfectly catches empty responses (like 204) while preserving valid JSON.
     if (!text) {

package/templates/apiRegistry.ts

@@ -37,11 +37,16 @@ type MatchSegments<P extends string[], K extends string[]> = K extends []
 
 type StripQuery<Path extends string> = Path extends `${infer Base}?${string}` ? Base : Path;
 
-export type FindMatchingRoute<Path extends string> = {
-  [K in keyof KnownRoutes & string]: MatchSegments<Split<StripQuery<Path>>, Split<K>> extends true
-    ? K
-    : never;
-}[keyof KnownRoutes & string];
+export type FindMatchingRoute<Path extends string> = Path extends keyof KnownRoutes
+  ? Path
+  : {
+      [K in keyof KnownRoutes & string]: MatchSegments<
+        Split<StripQuery<Path>>,
+        Split<K>
+      > extends true
+        ? K
+        : never;
+    }[keyof KnownRoutes & string];
 
 export type CheckPath<Path extends string> = Path extends ""
   ? keyof KnownRoutes