@rest-rpc/next 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rest-rpc
+
+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,45 @@
+# rest-rpc
+
+REST-shaped APIs with function-shaped TypeScript.
+
+`rest-rpc` lets you define HTTP routes in a shared TypeScript contract, then use
+that contract to derive typed server handlers, typed fetch clients, TanStack Query
+options, and OpenAPI documents.
+
+The API stays REST-shaped. Everyday application code can feel like function
+calls.
+
+```ts
+const todo = await api.todos.get.fetch({ id: "todo_1" });
+```
+
+That call is still a normal HTTP request:
+
+```http
+GET /todos/todo_1
+```
+
+## Packages
+
+- `@rest-rpc/core`: contracts, fetch client, OpenAPI generation, core helpers.
+- `@rest-rpc/express`: Express server adapter.
+- `@rest-rpc/hono`: Hono server adapter.
+- `@rest-rpc/fastify`: Fastify server adapter.
+- `@rest-rpc/web`: Web `Request`/`Response` HTTP handler adapter.
+- `@rest-rpc/next`: Next.js server/client adapter.
+- `@rest-rpc/tanstack-query`: TanStack Query options and key helpers.
+
+`@rest-rpc/server` contains shared adapter infrastructure and is mainly useful
+for adapter authors.
+
+## Design
+
+- REST routes remain explicit in the contract.
+- Handler and client calls use flattened request input.
+- Responses are keyed by HTTP status.
+- Server adapters are thin integrations with existing frameworks.
+- Schema libraries, OpenAPI UI, middleware, auth, and app structure stay your choice.
+
+## Documentation
+
+Full documentation will live at [rest-rpc.dev](https://rest-rpc.dev).

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import type { ApiClientFor, ApiClientOptions, Contract } from "@rest-rpc/core";
+import type { HttpRouteDeclaration } from "@rest-rpc/core/contract";
+type NextFetchOptions = RequestInit & {
+    next?: {
+        tags?: string[];
+        [key: string]: unknown;
+    };
+};
+export type NextClientFetchOptions = Omit<NextFetchOptions, "method" | "body" | "headers" | "signal">;
+export type NextClientOptions = Omit<ApiClientOptions, "fetchOptions"> & {
+    automaticFetchTags?: {
+        enabled: boolean;
+        tagPrefix?: string;
+    };
+    fetchOptions?: NextClientFetchOptions;
+};
+export declare const initNextClient: <TContract extends Contract>(contract: TContract, options: NextClientOptions) => ApiClientFor<TContract>;
+export declare const getGeneratedTagsForRoute: (route: HttpRouteDeclaration, options?: {
+    request?: Record<string, unknown>;
+    tagPrefix?: string;
+}) => string[];
+export {};

package/dist/client.js

@@ -0,0 +1,41 @@
+import { getRouteCacheTags, initClient } from "@rest-rpc/core";
+const createRouteCacheTagsForUrl = (url, prefix) => {
+    const parsed = new URL(url instanceof Request ? url.url : String(url));
+    return Array.from(new Set([
+        `${prefix ?? "rest-rpc"}:${parsed.pathname}${parsed.search}`,
+        `${prefix ?? "rest-rpc"}:${parsed.pathname}`,
+    ]));
+};
+const fetchWithTags = (fetchImpl, tagPrefix) => {
+    return (url, init) => {
+        if (init?.method !== "GET")
+            return fetchImpl(url, init);
+        const nextInit = init;
+        const taggedInit = {
+            ...nextInit,
+            next: {
+                ...nextInit.next,
+                tags: [
+                    ...(nextInit.next?.tags ?? []),
+                    ...createRouteCacheTagsForUrl(url, tagPrefix),
+                ],
+            },
+        };
+        return fetchImpl(url, taggedInit);
+    };
+};
+export const initNextClient = (contract, options) => {
+    const { automaticFetchTags, fetch, ...clientOptions } = options;
+    if (!automaticFetchTags?.enabled) {
+        return initClient(contract, options);
+    }
+    const fetchImpl = fetch ?? ((url, init) => globalThis.fetch(url, init));
+    return initClient(contract, {
+        ...clientOptions,
+        fetch: fetchWithTags(fetchImpl, automaticFetchTags.tagPrefix),
+    });
+};
+export const getGeneratedTagsForRoute = (route, options) => getRouteCacheTags(route, {
+    request: options?.request,
+    prefix: options?.tagPrefix,
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ContractResponseError } from "@rest-rpc/web";
+export type { NextClientOptions } from "./client.ts";
+export { getGeneratedTagsForRoute, initNextClient, } from "./client.ts";
+export { type CreateRouteHandlerOptions, createRouteHandler, createRouterHandler, type NextRouteHandlerContext, type NextRouteParseBody, type NextRouteParseBodyInput, type RouteHandler, type RouteRequest, type RouteResponse, } from "./server.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ContractResponseError } from "@rest-rpc/web";
+export { getGeneratedTagsForRoute, initNextClient, } from "./client.js";
+export { createRouteHandler, createRouterHandler, } from "./server.js";

package/dist/server.d.ts

@@ -0,0 +1,30 @@
+import type { HttpMethod, HttpRouteDeclaration, RequestBodySchema } from "@rest-rpc/core/contract";
+import { type CreateWebHandlerOptions, type RouteHandler as WebRouteHandler, type WebRouteParseBodyInput, type RouteRequest as WebRouteRequest, type RouteResponse as WebRouteResponse } from "@rest-rpc/web";
+type WebContract = HttpRouteDeclaration | {
+    [key: string]: WebContract;
+};
+type WebRequestHandler = (request: Request) => Promise<Response>;
+type WebRouterHandlers<TContract extends WebContract> = TContract extends HttpRouteDeclaration ? RouteHandler<TContract> : {
+    [K in keyof TContract]: TContract[K] extends WebContract ? WebRouterHandlers<TContract[K]> : never;
+};
+type RouteHandlerMap<E extends HttpRouteDeclaration> = {
+    [K in E["method"]]: WebRequestHandler;
+};
+type RouterHandlerMap = {
+    [K in HttpMethod]: WebRequestHandler;
+};
+export type NextRouteHandlerContext = {
+    request: Request;
+};
+export type RouteRequest<E extends HttpRouteDeclaration> = WebRouteRequest<E, NextRouteHandlerContext>;
+export type RouteResponse<E extends HttpRouteDeclaration> = WebRouteResponse<E>;
+export type RouteHandler<E extends HttpRouteDeclaration> = WebRouteHandler<E, NextRouteHandlerContext>;
+export type NextRouteParseBodyInput = WebRouteParseBodyInput;
+export type NextRouteParseBody = (input: NextRouteParseBodyInput) => unknown | Promise<unknown>;
+export type CreateRouteHandlerOptions = {
+    errorHandlers?: CreateWebHandlerOptions<NextRouteHandlerContext>["errorHandlers"];
+    parseBody?: NextRouteParseBody;
+};
+export declare function createRouteHandler<E extends HttpRouteDeclaration>(route: E, handler: RouteHandler<E>, options?: CreateRouteHandlerOptions): RouteHandlerMap<E>;
+export declare const createRouterHandler: <const TContract extends WebContract>(contract: TContract, handlers: WebRouterHandlers<TContract>, options?: CreateRouteHandlerOptions) => RouterHandlerMap;
+export type { RequestBodySchema };

package/dist/server.js

@@ -0,0 +1,26 @@
+import { initWeb, } from "@rest-rpc/web";
+export function createRouteHandler(route, handler, options) {
+    const web = initWeb();
+    const handle = web.createHandler(web.route(route, handler), {
+        errorHandlers: options?.errorHandlers,
+        parseBody: options?.parseBody,
+    });
+    return {
+        [route.method]: (request) => handle(request, { request }),
+    };
+}
+export const createRouterHandler = (contract, handlers, options) => {
+    const web = initWeb();
+    const handle = web.createHandler(web.router(contract, handlers), {
+        errorHandlers: options?.errorHandlers,
+        parseBody: options?.parseBody,
+    });
+    const nextHandler = (request) => handle(request, { request });
+    return {
+        DELETE: nextHandler,
+        GET: nextHandler,
+        PATCH: nextHandler,
+        POST: nextHandler,
+        PUT: nextHandler,
+    };
+};

package/dist/tags.d.ts

@@ -0,0 +1,4 @@
+import type { HttpRouteDeclaration } from "@rest-rpc/core/contract";
+export declare const getUrlTag: (url: string) => string;
+export declare const getRouteTags: (route: HttpRouteDeclaration, request?: Record<string, unknown>) => string[];
+//# sourceMappingURL=tags.d.ts.map

package/dist/tags.js

@@ -0,0 +1,11 @@
+import { constructBaseRequest } from "@rest-rpc/core";
+const tagPrefix = "rest-rpc";
+export const getUrlTag = (url) => {
+    const parsed = new URL(url, "http://rest-rpc.local");
+    return `${tagPrefix}:${parsed.pathname}${parsed.search}`;
+};
+export const getRouteTags = (route, request) => {
+    const { url } = constructBaseRequest("", route, request, "strip");
+    return [getUrlTag(url)];
+};
+//# sourceMappingURL=tags.js.map

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@rest-rpc/next",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@rest-rpc/core": "^0.1.0-beta.0",
+    "@rest-rpc/web": "^0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test src/*.test.ts src/**/*.test.ts",
+    "typecheck": "pnpm run build && tsc -p tsconfig.json"
+  }
+}