@wynn-dev/better-fetch-rpc 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyên
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,454 @@
+<a id="readme-top"></a>
+
+<!-- PROJECT SHIELDS -->
+
+[![NPM Version](https://img.shields.io/npm/v/better-fetch-rpc.svg?style=for-the-badge)](https://www.npmjs.com/package/better-fetch-rpc)
+[![NPM Downloads](https://img.shields.io/npm/dm/better-fetch-rpc.svg?style=for-the-badge)](https://www.npmjs.com/package/better-fetch-rpc)
+[![Contributors](https://img.shields.io/github/contributors/nbnguyen75/better-fetch-rpc.svg?style=for-the-badge)](https://github.com/nbnguyen75/better-fetch-rpc/graphs/contributors)
+[![Forks](https://img.shields.io/github/forks/nbnguyen75/better-fetch-rpc.svg?style=for-the-badge)](https://github.com/nbnguyen75/better-fetch-rpc/network/members)
+[![Stargazers](https://img.shields.io/github/stars/nbnguyen75/better-fetch-rpc.svg?style=for-the-badge)](https://github.com/nbnguyen75/better-fetch-rpc/stargazers)
+[![Issues](https://img.shields.io/github/issues/nbnguyen75/better-fetch-rpc.svg?style=for-the-badge)](https://github.com/nbnguyen75/better-fetch-rpc/issues)
+[![MIT License](https://img.shields.io/github/license/nbnguyen75/better-fetch-rpc.svg?style=for-the-badge)](https://github.com/nbnguyen75/better-fetch-rpc/blob/main/LICENSE)
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+  <h3 align="center">better-fetch-rpc</h3>
+
+  <p align="center">
+    A type-safe, RPC-style wrapper around <code>fetch</code> — call your API like a local function, with full type inference.
+    <br />
+    <a href="https://github.com/nbnguyen75/better-fetch-rpc"><strong>Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/nbnguyen75/better-fetch-rpc/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
+    ·
+    <a href="https://github.com/nbnguyen75/better-fetch-rpc/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
+  </p>
+</div>
+
+<!-- TABLE OF CONTENTS -->
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+      <ul>
+        <li><a href="#built-with">Built With</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#usage">Usage</a>
+      <ul>
+        <li><a href="#1-define-your-routes">Define your routes</a></li>
+        <li><a href="#2-create-the-client-and-call-it">Create the client and call it</a></li>
+        <li><a href="#response-shapes">Response shapes</a></li>
+        <li><a href="#typing-the-error-channel">Typing the error channel</a></li>
+        <li><a href="#reusing-endpoint-types">Reusing endpoint types</a></li>
+        <li><a href="#client-options">Client options</a></li>
+        <li><a href="#schema-compatibility">Schema compatibility</a></li>
+        <li><a href="#runtime-response-validation">Runtime response validation</a></li>
+        <li><a href="#tanstack-query">TanStack Query</a></li>
+      </ul>
+    </li>
+    <li><a href="#api-reference">API Reference</a></li>
+    <li><a href="#roadmap">Roadmap</a></li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+  </ol>
+</details>
+
+<!-- ABOUT THE PROJECT -->
+
+## About The Project
+
+**better-fetch-rpc** is a type-safe RPC-style wrapper around `fetch`. Instead of hand-writing URL strings, headers, and response parsing for every request, you define your API routes once and call them like local functions — with types inferred end-to-end.
+
+Schema types (zod, valibot, arktype, …) are understood through [Standard Schema](https://standardschema.dev) and can optionally validate responses at runtime. The package itself has zero runtime dependencies besides its `@better-fetch/fetch` peer.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+### Built With
+
+- [![TypeScript][TypeScript-badge]][TypeScript-url]
+- [![Node.js][Node-badge]][Node-url]
+- [better-fetch](https://github.com/better-auth/better-fetch) — fetch engine with native Standard Schema validation
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- GETTING STARTED -->
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js ≥ 18
+
+### Installation
+
+```sh
+npm install better-fetch-rpc
+# or
+pnpm add better-fetch-rpc
+# or
+yarn add better-fetch-rpc
+```
+
+`@better-fetch/fetch` is a peer dependency and is installed automatically by
+npm, pnpm, and yarn. Runtime response validation needs a peer of at least
+`v1.1.21` (the first version with Standard Schema `output` support). A schema
+library (zod, valibot, …) is only needed if you use runtime response
+validation.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- USAGE EXAMPLES -->
+
+## Usage
+
+### 1. Define your routes
+
+A router maps paths to HTTP methods (`$get`, `$post`, `$put`, `$patch`,
+`$delete`). Each endpoint declares its `headers`, `params`, `query`, `body`,
+and `response` — as plain TypeScript types or as schemas from any
+Standard Schema library:
+
+```ts
+import type { EnsureRouter } from 'better-fetch-rpc';
+
+import { z } from 'zod';
+
+const noteSchema = z.object({ id: z.string(), title: z.string() });
+
+type Note = z.infer<typeof noteSchema>;
+type ApiSuccessResponse<T> = { success: true; data: T };
+
+type Router = EnsureRouter<{
+  '/api/v1/notes': {
+    $get: {
+      response: ApiSuccessResponse<Note[]>;
+      query?: { limit?: number } | undefined;
+    };
+    $post: {
+      response: ApiSuccessResponse<Note>;
+      body: { title: string };
+    };
+  };
+  '/api/v1/notes/:id': {
+    $get: {
+      response: typeof noteSchema;
+      params: { id: string };
+    };
+  };
+}>;
+```
+
+Endpoints that declare nothing — or only optional fields — accept zero
+arguments; required fields must be passed.
+
+### 2. Create the client and call it
+
+Path segments become properties. `:id`-style segments are indexed with the
+literal key and filled from `params` (which better-fetch also substitutes
+into the URL):
+
+```ts
+import { createRpcClient } from 'better-fetch-rpc';
+
+const api = createRpcClient<Router>('https://api.example.com');
+
+// Fully typed request + response
+const { data, error } = await api.api.v1.notes[':id'].$get({
+  params: { id: '123' },
+});
+
+if (error) {
+  console.error(error);
+} else {
+  console.log(data); // typed from the route definition
+}
+```
+
+### Response shapes
+
+By default every call resolves to `{ data, error }` — exactly one of them is
+non-null. Pass `throw: true` to receive the response data directly and let
+transport failures reject instead:
+
+```ts
+const throwing = createRpcClient<Router>('https://api.example.com', { throw: true });
+
+const notes = await throwing.api.v1.notes.$get({ query: { limit: 10 } });
+//    ^ typed as the $get response (no envelope)
+```
+
+### Typing the error channel
+
+Pass your server's error shape as the second generic so `error` is typed:
+
+```ts
+type ApiError = { errorCode: string; message: string };
+
+const api = createRpcClient<Router, ApiError>('https://api.example.com');
+
+const { error } = await api.api.v1.notes.$get();
+if (error) {
+  console.error(error.errorCode); // string
+}
+```
+
+### Reusing endpoint types
+
+`InferRequestType` / `InferResponseType` extract an endpoint's options and
+resolved value — handy for wrapping calls in your own functions:
+
+```ts
+import type { InferRequestType, InferResponseType } from 'better-fetch-rpc';
+
+type GetNotesRequest = InferRequestType<typeof api.api.v1.notes.$get>;
+type GetNotesResponse = InferResponseType<typeof api.api.v1.notes.$get>['data'];
+
+export async function getNotes(args: GetNotesRequest): Promise<GetNotesResponse> {
+  const result = await api.api.v1.notes.$get(args);
+  if (result.error) throw new Error('Request failed');
+  return result.data;
+}
+```
+
+### Client options
+
+The second argument accepts everything
+[`@better-fetch/fetch`](https://github.com/better-auth/better-fetch) accepts
+(`auth`, `headers`, `retry`, `timeout`, …) — except `baseURL`/`body`, which
+the client owns — plus `schemas` (see below):
+
+```ts
+const api = createRpcClient<Router>('https://api.example.com', {
+  auth: { token: () => getToken(), type: 'Bearer' },
+});
+```
+
+### Schema compatibility
+
+Request/response types are inferred through [Standard Schema](https://standardschema.dev),
+so any compliant library works — no hard dependency on a specific one:
+
+- zod ≥ 3.24
+- valibot ≥ 1.0
+- arktype ≥ 2.0
+- …anything exposing `~standard`
+
+Plain TypeScript types work too — schemas are optional, not required.
+
+### Runtime response validation
+
+Types alone can't verify what the server actually sends. To validate responses
+at runtime, define routes as a const once — feeding both the router type and
+the runtime schemas — and pass it via the `schemas` option:
+
+```ts
+import { z } from 'zod';
+import { ValidationError, createRpcClient } from 'better-fetch-rpc';
+
+const noteSchema = z.object({ id: z.string(), title: z.string() });
+
+const routes = {
+  '/api/v1/notes/:id': {
+    $get: { response: noteSchema },
+  },
+} as const;
+
+type Router = EnsureRouter<typeof routes>;
+
+const api = createRpcClient<Router>('https://api.example.com', { schemas: routes });
+
+try {
+  const { data, error } = await api.api.v1.notes[':id'].$get({ params: { id: '123' } });
+  if (error) {
+    console.error('Request failed:', error);
+  } else {
+    console.log(data.title); // validated: guaranteed to match noteSchema
+  }
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Server broke the contract:', error.issues);
+  }
+  throw error;
+}
+```
+
+Rules:
+
+- Only routes with a runtime schema are validated; everything else passes
+  through untouched (inference-only, zero cost).
+- Validation failures **always throw** `ValidationError` (re-exported for
+  convenience) — in both `throw: true` and default modes, just like network
+  errors. The `{ data, error }` channel is reserved for server responses.
+- Schemas declared as bare types (no runtime instance) are inference-only;
+  only `typeof mySchema` entries paired with `schemas` can be validated.
+
+### TanStack Query
+
+The `throw: true` client pairs naturally with TanStack Query v5: transport and
+validation failures reject, so they land in Query's `error` / `onError`
+channel with no envelope unwrapping. Define `queryOptions` factories once,
+then consume them in hooks:
+
+```ts
+import { queryOptions } from '@tanstack/react-query';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+
+const throwing = createRpcClient<Router>('https://api.example.com', { throw: true });
+
+export const noteKeys = {
+  all: ['notes'] as const,
+  list: (params?: { limit?: number }) => [...noteKeys.all, 'list', params] as const,
+  detail: (id: string) => [...noteKeys.all, 'detail', id] as const,
+};
+
+export function noteDetailQueryOptions(id: string) {
+  return queryOptions({
+    queryFn: () => throwing.api.v1.notes[':id'].$get({ params: { id } }),
+    queryKey: noteKeys.detail(id),
+  });
+}
+
+export function useNote(id: string) {
+  return useQuery(noteDetailQueryOptions(id));
+}
+
+export function useCreateNote() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (title: string) => throwing.api.v1.notes.$post({ body: { title } }),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: noteKeys.all });
+    },
+  });
+}
+```
+
+`ValidationError` from a validated route surfaces the same way — as the
+query/mutation `error` — because validation failures always throw.
+
+_For more examples and the full API reference, please refer to the [Documentation](https://github.com/nbnguyen75/better-fetch-rpc)._
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- API REFERENCE -->
+
+## API Reference
+
+### Values
+
+| Export             | Description                                                                                   |
+| ------------------ | --------------------------------------------------------------------------------------------- |
+| `createRpcClient`  | `createRpcClient<Router, Error = unknown>(baseURL?, options?)` — builds the typed RPC client. |
+| `ValidationError`  | Re-exported from `@better-fetch/fetch`. Thrown on response validation failure; has `.issues`. |
+| `isStandardSchema` | Type guard for Standard Schema instances.                                                     |
+
+### Types
+
+| Export                  | Description                                                             |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `EnsureRouter<T>`       | Constrains a route map to the router shape.                             |
+| `BaseRouter`            | `Record<string, MethodMap>` — the base constraint for routers.          |
+| `EndpointDef`           | One endpoint: `headers` / `params` / `query` / `body` / `response`.     |
+| `MethodMap`             | `$get` / `$post` / `$put` / `$patch` / `$delete` endpoint map.          |
+| `ProxyTree<R, T, E>`    | The client type derived from a router.                                  |
+| `RpcResponse<D, E>`     | `{ data: D; error: null } \| { data: null; error: E }`.                 |
+| `RpcSchemas<R>`         | Runtime schemas mirror for the `schemas` option.                        |
+| `RouteSchemas`          | Per-endpoint schemas: `{ response?: StandardSchemaV1 }`.                |
+| `CreateRpcClientOption` | Client options (better-fetch options + `schemas`).                      |
+| `RequestOptions`        | Per-call options: `headers` / `params` / `query` / `body`.              |
+| `HttpMethod`            | `'DELETE' \| 'PATCH' \| 'POST' \| 'GET' \| 'PUT'`.                      |
+| `InferRequestType<F>`   | Extracts an endpoint function's options type.                           |
+| `InferResponseType<F>`  | Extracts an endpoint function's resolved value type.                    |
+| `StandardSchemaV1`      | Vendored Standard Schema interface (no dependency needed to reference). |
+| `InferStandardInput`    | Infer a schema's input type.                                            |
+| `InferStandardOutput`   | Infer a schema's output type.                                           |
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- ROADMAP -->
+
+## Roadmap
+
+- [x] Core RPC client (GET/POST/PUT/PATCH/DELETE)
+- [x] Opt-in Standard Schema runtime response validation
+- [ ] Request/response interceptors
+- [ ] Built-in retry & timeout handling
+
+See the [open issues](https://github.com/nbnguyen75/better-fetch-rpc/issues) for a full list of proposed features and known issues.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- CONTRIBUTING -->
+
+## Contributing
+
+Contributions make the open source community amazing. Any contributions you make are **greatly appreciated**.
+
+If you have a suggestion, fork the repo and open a pull request, or open an issue with the tag "enhancement". Don't forget to star the project!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+### Changesets
+
+Every PR that should trigger a release must include a changeset: run
+`pnpm changeset` and commit the generated file. The release workflow turns
+them into version bumps and `CHANGELOG.md` entries automatically.
+
+### Package managers
+
+Use **pnpm** or **bun** — never npm. After any dependency change, run both
+`pnpm install` and `bun install` so `pnpm-lock.yaml` and `bun.lock` stay in
+sync. Never mix managers in one `node_modules`: switching means deleting
+`node_modules` and reinstalling. CI runs pnpm only, and `pnpm test` is the
+source of truth (`bun run test` executes vitest under Bun, which is
+unsupported — use Bun for `bun dist/index.js` smoke runs instead).
+
+### Emergency local publish
+
+Releases normally ship from CI via OIDC trusted publishing. If CI is
+unavailable, `pnpm publish` works locally with an automation token, but the
+release will lack a provenance attestation — prefer CI.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- LICENSE -->
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- CONTACT -->
+
+## Contact
+
+Nguyên (Wynn) - [GitHub @nbnguyen75](https://github.com/nbnguyen75)
+
+Project Link: [https://github.com/nbnguyen75/better-fetch-rpc](https://github.com/nbnguyen75/better-fetch-rpc)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- MARKDOWN LINKS & IMAGES -->
+
+[TypeScript-badge]: https://img.shields.io/badge/typescript-3178C6?style=for-the-badge&logo=typescript&logoColor=white
+[TypeScript-url]: https://www.typescriptlang.org/
+[Node-badge]: https://img.shields.io/badge/node.js-339933?style=for-the-badge&logo=node.js&logoColor=white
+[Node-url]: https://nodejs.org/

package/dist/index.cjs

@@ -0,0 +1,64 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _better_fetch_fetch = require("@better-fetch/fetch");
+//#region src/standard-schema.ts
+function isStandardSchema(value) {
+	if (typeof value !== "object" || value === null || !("~standard" in value)) return false;
+	const standard = value["~standard"];
+	return typeof standard === "object" && standard !== null;
+}
+//#endregion
+//#region src/rpc.ts
+const METHOD_KEY_MAP = {
+	$delete: "DELETE",
+	$patch: "PATCH",
+	$post: "POST",
+	$get: "GET",
+	$put: "PUT"
+};
+const METHOD_TO_KEY = {
+	DELETE: "$delete",
+	GET: "$get",
+	PATCH: "$patch",
+	POST: "$post",
+	PUT: "$put"
+};
+function createProxyClient(makeRequest, segments = []) {
+	return new Proxy(() => {}, { get(_target, prop) {
+		if (prop in METHOD_KEY_MAP) {
+			const method = METHOD_KEY_MAP[prop];
+			if (!method) return void 0;
+			const path = "/" + segments.join("/");
+			return (options) => makeRequest(method, path, options);
+		}
+		return createProxyClient(makeRequest, [...segments, prop]);
+	} });
+}
+function createRpcClient(baseURL, option = {}) {
+	const { schemas, ...fetchOption } = option;
+	const $fetchBase = (0, _better_fetch_fetch.createFetch)({
+		...baseURL ? { baseURL } : {},
+		...fetchOption
+	});
+	const schemaIndex = schemas;
+	const makeRequest = (method, path, options) => {
+		const responseSchema = schemaIndex?.[path]?.[METHOD_TO_KEY[method]]?.response;
+		return $fetchBase(path, {
+			headers: options?.headers,
+			params: options?.params,
+			query: options?.query,
+			body: options?.body,
+			method,
+			...isStandardSchema(responseSchema) ? { output: responseSchema } : {}
+		});
+	};
+	return createProxyClient(makeRequest);
+}
+//#endregion
+Object.defineProperty(exports, "ValidationError", {
+	enumerable: true,
+	get: function() {
+		return _better_fetch_fetch.ValidationError;
+	}
+});
+exports.createRpcClient = createRpcClient;
+exports.isStandardSchema = isStandardSchema;

package/dist/index.d.cts

@@ -0,0 +1,100 @@
+import { CreateFetchOption, ValidationError } from "@better-fetch/fetch";
+//#region src/standard-schema.d.ts
+/**
+ * Standard Schema V1 — vendored type definitions (no runtime code).
+ *
+ * Source: https://github.com/standard-schema/standard-schema (v1 spec).
+ * Vendored so this package stays dependency-free: any schema library that
+ * implements the spec (zod ≥ 3.24, valibot ≥ 1.0, arktype ≥ 2.0, …) is
+ * structurally compatible without this package depending on it.
+ *
+ * Only the shapes needed for type inference and (future) response
+ * validation are included. Kept flat (no namespaces) to stay compatible
+ * with `erasableSyntaxOnly`.
+ */
+interface StandardSchemaPathSegment {
+  readonly key: PropertyKey;
+}
+interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | StandardSchemaPathSegment> | undefined;
+}
+interface StandardSchemaSuccessResult<Output> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+interface StandardSchemaFailureResult {
+  readonly issues: ReadonlyArray<StandardSchemaIssue>;
+}
+type StandardSchemaResult<Output> = StandardSchemaFailureResult | StandardSchemaSuccessResult<Output>;
+interface StandardSchemaTypes<Input = unknown, Output = Input> {
+  readonly input: Input;
+  readonly output: Output;
+}
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?: StandardSchemaTypes<Input, Output> | undefined;
+  };
+}
+type InferStandardInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+type InferStandardOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+//#endregion
+//#region src/rpc.d.ts
+type InferSchema<T> = T extends StandardSchemaV1 ? InferStandardOutput<T> : T;
+type EndpointDef = {
+  headers?: Record<string, string | undefined> | StandardSchemaV1;
+  query?: Record<string, unknown> | StandardSchemaV1 | undefined;
+  params?: Record<string, unknown> | StandardSchemaV1;
+  response?: unknown;
+  body?: unknown;
+};
+type MethodMap = {
+  $delete?: EndpointDef;
+  $patch?: EndpointDef;
+  $post?: EndpointDef;
+  $get?: EndpointDef;
+  $put?: EndpointDef;
+};
+type InferRequest<T extends EndpointDef> = { [K in keyof T as K extends 'body' | 'headers' | 'params' | 'query' ? T[K] extends never ? never : K : never]: InferSchema<T[K]>; };
+type RequestArgs<Endpoint extends EndpointDef> = Record<string, never> extends InferRequest<Endpoint> ? [options?: InferRequest<Endpoint>] : [options: InferRequest<Endpoint>];
+type RequestOptions = {
+  headers?: Record<string, string | undefined>;
+  params?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  body?: Record<string, unknown>;
+};
+type Split<S extends string> = S extends `${infer Head}/${infer Tail}` ? Head extends '' ? Split<Tail> : [Head, ...Split<Tail>] : S extends '' ? [] : [S];
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+type RpcResponse<Data, Error = unknown> = {
+  error: Error;
+  data: null;
+} | {
+  error: null;
+  data: Data;
+};
+type MethodClient<Methods extends MethodMap, Throw extends boolean, Error = unknown> = { [M in keyof Methods as Methods[M] extends EndpointDef ? M : never]: Methods[M] extends EndpointDef ? (...args: RequestArgs<Methods[M]>) => Promise<Throw extends true ? InferResponse<Methods[M]> : RpcResponse<InferResponse<Methods[M]>, Error>> : never; };
+type BuildBranch<Segments extends ReadonlyArray<string>, Leaf> = Segments extends readonly [infer Head extends string, ...infer Rest extends ReadonlyArray<string>] ? Rest extends readonly [] ? { [K in Head]: Leaf; } : { [K in Head]: BuildBranch<Rest, Leaf>; } : never;
+type BaseRouter = Record<string, MethodMap>;
+type ProxyTree<Router extends BaseRouter, Throw extends boolean = false, Error = unknown> = UnionToIntersection<{ [Path in keyof Router]: Path extends string ? BuildBranch<Split<Path>, MethodClient<Router[Path], Throw, Error>> : never; }[keyof Router]>;
+type HttpMethod = 'DELETE' | 'PATCH' | 'POST' | 'GET' | 'PUT';
+type InferRequestType<T extends (...args: Array<never>) => unknown> = Parameters<T>[0];
+type InferResponseType<T extends (...args: Array<never>) => unknown> = Awaited<ReturnType<T>>;
+type InferResponse<T extends EndpointDef> = InferSchema<T['response']>;
+type EnsureRouter<T extends BaseRouter> = T;
+type RouteSchemas = {
+  response?: StandardSchemaV1 | undefined;
+};
+type RpcSchemas<Router extends BaseRouter> = { [Path in keyof Router]?: { [Method in keyof Router[Path]]?: RouteSchemas | undefined; }; };
+type CreateRpcClientOption<Router extends BaseRouter = BaseRouter> = Omit<CreateFetchOption, 'baseURL' | 'body'> & {
+  schemas?: RpcSchemas<Router> | undefined;
+};
+export declare function createRpcClient<Router extends BaseRouter, Error = unknown>(baseURL: undefined | string, option: CreateRpcClientOption<Router> & {
+  throw: true;
+}): ProxyTree<Router, true, Error>;
+export declare function createRpcClient<Router extends BaseRouter, Error = unknown>(baseURL?: string, option?: CreateRpcClientOption<Router>): ProxyTree<Router, false, Error>;
+//#endregion
+export { type BaseRouter, type CreateRpcClientOption, type EndpointDef, type EnsureRouter, type HttpMethod, type InferRequestType, type InferResponseType, type InferStandardInput, type InferStandardOutput, type MethodMap, type ProxyTree, type RequestOptions, type RouteSchemas, type RpcResponse, type RpcSchemas, type StandardSchemaFailureResult, type StandardSchemaIssue, type StandardSchemaPathSegment, type StandardSchemaResult, type StandardSchemaSuccessResult, type StandardSchemaTypes, type StandardSchemaV1, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import { CreateFetchOption, ValidationError } from "@better-fetch/fetch";
+//#region src/standard-schema.d.ts
+/**
+ * Standard Schema V1 — vendored type definitions (no runtime code).
+ *
+ * Source: https://github.com/standard-schema/standard-schema (v1 spec).
+ * Vendored so this package stays dependency-free: any schema library that
+ * implements the spec (zod ≥ 3.24, valibot ≥ 1.0, arktype ≥ 2.0, …) is
+ * structurally compatible without this package depending on it.
+ *
+ * Only the shapes needed for type inference and (future) response
+ * validation are included. Kept flat (no namespaces) to stay compatible
+ * with `erasableSyntaxOnly`.
+ */
+interface StandardSchemaPathSegment {
+  readonly key: PropertyKey;
+}
+interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | StandardSchemaPathSegment> | undefined;
+}
+interface StandardSchemaSuccessResult<Output> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+interface StandardSchemaFailureResult {
+  readonly issues: ReadonlyArray<StandardSchemaIssue>;
+}
+type StandardSchemaResult<Output> = StandardSchemaFailureResult | StandardSchemaSuccessResult<Output>;
+interface StandardSchemaTypes<Input = unknown, Output = Input> {
+  readonly input: Input;
+  readonly output: Output;
+}
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?: StandardSchemaTypes<Input, Output> | undefined;
+  };
+}
+type InferStandardInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+type InferStandardOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+//#endregion
+//#region src/rpc.d.ts
+type InferSchema<T> = T extends StandardSchemaV1 ? InferStandardOutput<T> : T;
+type EndpointDef = {
+  headers?: Record<string, string | undefined> | StandardSchemaV1;
+  query?: Record<string, unknown> | StandardSchemaV1 | undefined;
+  params?: Record<string, unknown> | StandardSchemaV1;
+  response?: unknown;
+  body?: unknown;
+};
+type MethodMap = {
+  $delete?: EndpointDef;
+  $patch?: EndpointDef;
+  $post?: EndpointDef;
+  $get?: EndpointDef;
+  $put?: EndpointDef;
+};
+type InferRequest<T extends EndpointDef> = { [K in keyof T as K extends 'body' | 'headers' | 'params' | 'query' ? T[K] extends never ? never : K : never]: InferSchema<T[K]>; };
+type RequestArgs<Endpoint extends EndpointDef> = Record<string, never> extends InferRequest<Endpoint> ? [options?: InferRequest<Endpoint>] : [options: InferRequest<Endpoint>];
+type RequestOptions = {
+  headers?: Record<string, string | undefined>;
+  params?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  body?: Record<string, unknown>;
+};
+type Split<S extends string> = S extends `${infer Head}/${infer Tail}` ? Head extends '' ? Split<Tail> : [Head, ...Split<Tail>] : S extends '' ? [] : [S];
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+type RpcResponse<Data, Error = unknown> = {
+  error: Error;
+  data: null;
+} | {
+  error: null;
+  data: Data;
+};
+type MethodClient<Methods extends MethodMap, Throw extends boolean, Error = unknown> = { [M in keyof Methods as Methods[M] extends EndpointDef ? M : never]: Methods[M] extends EndpointDef ? (...args: RequestArgs<Methods[M]>) => Promise<Throw extends true ? InferResponse<Methods[M]> : RpcResponse<InferResponse<Methods[M]>, Error>> : never; };
+type BuildBranch<Segments extends ReadonlyArray<string>, Leaf> = Segments extends readonly [infer Head extends string, ...infer Rest extends ReadonlyArray<string>] ? Rest extends readonly [] ? { [K in Head]: Leaf; } : { [K in Head]: BuildBranch<Rest, Leaf>; } : never;
+type BaseRouter = Record<string, MethodMap>;
+type ProxyTree<Router extends BaseRouter, Throw extends boolean = false, Error = unknown> = UnionToIntersection<{ [Path in keyof Router]: Path extends string ? BuildBranch<Split<Path>, MethodClient<Router[Path], Throw, Error>> : never; }[keyof Router]>;
+type HttpMethod = 'DELETE' | 'PATCH' | 'POST' | 'GET' | 'PUT';
+type InferRequestType<T extends (...args: Array<never>) => unknown> = Parameters<T>[0];
+type InferResponseType<T extends (...args: Array<never>) => unknown> = Awaited<ReturnType<T>>;
+type InferResponse<T extends EndpointDef> = InferSchema<T['response']>;
+type EnsureRouter<T extends BaseRouter> = T;
+type RouteSchemas = {
+  response?: StandardSchemaV1 | undefined;
+};
+type RpcSchemas<Router extends BaseRouter> = { [Path in keyof Router]?: { [Method in keyof Router[Path]]?: RouteSchemas | undefined; }; };
+type CreateRpcClientOption<Router extends BaseRouter = BaseRouter> = Omit<CreateFetchOption, 'baseURL' | 'body'> & {
+  schemas?: RpcSchemas<Router> | undefined;
+};
+export declare function createRpcClient<Router extends BaseRouter, Error = unknown>(baseURL: undefined | string, option: CreateRpcClientOption<Router> & {
+  throw: true;
+}): ProxyTree<Router, true, Error>;
+export declare function createRpcClient<Router extends BaseRouter, Error = unknown>(baseURL?: string, option?: CreateRpcClientOption<Router>): ProxyTree<Router, false, Error>;
+//#endregion
+export { type BaseRouter, type CreateRpcClientOption, type EndpointDef, type EnsureRouter, type HttpMethod, type InferRequestType, type InferResponseType, type InferStandardInput, type InferStandardOutput, type MethodMap, type ProxyTree, type RequestOptions, type RouteSchemas, type RpcResponse, type RpcSchemas, type StandardSchemaFailureResult, type StandardSchemaIssue, type StandardSchemaPathSegment, type StandardSchemaResult, type StandardSchemaSuccessResult, type StandardSchemaTypes, type StandardSchemaV1, ValidationError };

package/dist/index.js

@@ -0,0 +1,56 @@
+import { ValidationError, createFetch } from "@better-fetch/fetch";
+//#region src/standard-schema.ts
+function isStandardSchema(value) {
+	if (typeof value !== "object" || value === null || !("~standard" in value)) return false;
+	const standard = value["~standard"];
+	return typeof standard === "object" && standard !== null;
+}
+//#endregion
+//#region src/rpc.ts
+const METHOD_KEY_MAP = {
+	$delete: "DELETE",
+	$patch: "PATCH",
+	$post: "POST",
+	$get: "GET",
+	$put: "PUT"
+};
+const METHOD_TO_KEY = {
+	DELETE: "$delete",
+	GET: "$get",
+	PATCH: "$patch",
+	POST: "$post",
+	PUT: "$put"
+};
+function createProxyClient(makeRequest, segments = []) {
+	return new Proxy(() => {}, { get(_target, prop) {
+		if (prop in METHOD_KEY_MAP) {
+			const method = METHOD_KEY_MAP[prop];
+			if (!method) return void 0;
+			const path = "/" + segments.join("/");
+			return (options) => makeRequest(method, path, options);
+		}
+		return createProxyClient(makeRequest, [...segments, prop]);
+	} });
+}
+function createRpcClient(baseURL, option = {}) {
+	const { schemas, ...fetchOption } = option;
+	const $fetchBase = createFetch({
+		...baseURL ? { baseURL } : {},
+		...fetchOption
+	});
+	const schemaIndex = schemas;
+	const makeRequest = (method, path, options) => {
+		const responseSchema = schemaIndex?.[path]?.[METHOD_TO_KEY[method]]?.response;
+		return $fetchBase(path, {
+			headers: options?.headers,
+			params: options?.params,
+			query: options?.query,
+			body: options?.body,
+			method,
+			...isStandardSchema(responseSchema) ? { output: responseSchema } : {}
+		});
+	};
+	return createProxyClient(makeRequest);
+}
+//#endregion
+export { ValidationError, createRpcClient, isStandardSchema };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@wynn-dev/better-fetch-rpc",
+  "version": "0.0.0",
+  "description": "Type-safe RPC-style client built on @better-fetch/fetch — define routes once, call them like local functions.",
+  "keywords": [
+    "better-fetch",
+    "fetch",
+    "rpc",
+    "typed-client",
+    "typescript"
+  ],
+  "homepage": "https://github.com/nbnguyen75/better-fetch-rpc#readme",
+  "bugs": {
+    "url": "https://github.com/nbnguyen75/better-fetch-rpc/issues"
+  },
+  "license": "MIT",
+  "author": "Nguyên (Wynn)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nbnguyen75/better-fetch-rpc.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt --check",
+    "format:fix": "oxfmt",
+    "test": "vitest run",
+    "release": "bumpp --commit --tag --push",
+    "prepublishOnly": "bun run test & bun run build",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@better-fetch/fetch": "^1.3.2",
+    "@changesets/cli": "^3.0.3",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.2",
+    "bumpp": "^12.3.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.6.0",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.3",
+    "valibot": "^1.1.0",
+    "vitest": "^3.2.4",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@better-fetch/fetch": "^1.1.21"
+  },
+  "lint-staged": {
+    "src/*": [
+      "oxlint --fix"
+    ]
+  }
+}