@thednp/rpc 0.0.4 → 0.0.5

package/wiki/best-practices.md

@@ -1,364 +0,0 @@
-# Best Practices
-
-## @thednp/rpc is a Transport Pipe
-
-The best thing to do **first** is to understand `@thednp/rpc` is that it only handles **transport** and **serialization**.
-
-It does not provide:
-- Caching
-- Authentication
-- Validation
-- State management
-- Request limits
-- Retry logic
-
-Use dedicated tools for these concerns.
-
-## Client-Side Caching
-
-All major frameworks have a `@tanstack/<framework>-query` made by [Tanstack](https://tanstack.com/) to cover all needs except validation and authentication.
-
-For instance the `@tanstack/react-query` is the recommended layer for React apps client-side caching, invalidation, and stale-while-revalidate:
-
-```ts
-// src/components/GreetUser.tsx
-import { useQuery, useQueryClient } from '@tanstack/react-query';
-import { sayHi } from '../api';
-
-function GreetUser({ name }: { name: string }) {
-  const { data } = useQuery({
-    queryKey: ['say-hi', name],
-    queryFn: ({ signal }) => {
-      const result = sayHi(name);
-      signal.addEventListener('abort', () => result.cancel('query cancelled'));
-      return result.data;
-    },
-  });
-  return <div>{data ?? 'Loading...'}</div>;
-}
-```
-
-## AbortSignal Best Practices
-
-Always check `signal.aborted` or call `signal.throwIfAborted()` in long-running server functions:
-
-```ts
-export const processBatch = createServerFunction(
-  'process-batch',
-  async (signal: AbortSignal, items: string[]) => {
-    const results = [];
-    const errors = [];
-    for (const item of items) {
-      signal.throwIfAborted();
-      const result = await heavyWork(item);
-      results.push(result);
-      // handle errors properly
-    }
-    return results;
-  },
-);
-```
-
-## Input Validation
-
-Always validate client-provided data before using it in server functions. Use libraries like **zod** or **valibot** to parse and validate inputs:
-
-```ts
-// src/api/server.ts
-import { z } from 'zod';
-import { createServerFunction } from '@thednp/rpc/server';
-
-const ProfileSchema = z.object({
-  name: z.string().min(1).max(100),
-  age: z.number().int().positive(),
-});
-
-export const updateProfile = createServerFunction(
-  'update-profile',
-  async (signal, raw) => {
-    const parsed = ProfileSchema.safeParse(raw);
-    if (!parsed.success) {
-      return { ok: false, errors: parsed.error.flatten().fieldErrors };
-    }
-    // parsed.data is fully typed
-    await saveToDb(parsed.data);
-    return { ok: true };
-  },
-);
-```
-
-Return validation errors as structured data — the client's `handleResponse` will surface them as an `Error`. Check [Server Functions Guide](./server-functions.md) for more detailed examples.
-
-## Authentication
-
-> Never add auth hooks inside server functions.
-
-Use authentication middleware **before** `createRPCMiddleware()`.
-
-```ts
-app.use(authMiddleware);
-app.use(createRPCMiddleware());
-```
-
-
-### Basic Authorization
-
-A typical auth middleware reads credentials from the request, validates them, and sets `req.user`:
-
-```ts
-// Express
-const authMiddleware = (req, res, next) => {
-  const token = req.headers.authorization?.replace("Bearer ", "");
-  if (!token) {
-    res.status(401).json({ error: "Unauthorized" });
-    return;
-  }
-  try {
-    req.user = verifyToken(token); // { id, role, ... }
-    next();
-  } catch {
-    res.status(401).json({ error: "Unauthorized" });
-  }
-};
-```
-
-> In your production apps, **use best solutions** provided by server of your choice. The above code is only to showcase how to wire pieces together.
-
-### Per-Function Authorization
-
-When some server functions should be public and others require authentication, use `createMiddleware` with a handler that inspects the function name:
-
-```ts
-import type { Request } from "express";
-import { createMiddleware } from "@thednp/rpc/express";
-import { loadRPCConfig } from "@thednp/rpc";
-
-const publicFns = new Set(["login", "register", "publicData"]);
-const config = await loadRPCConfig();
-
-// use a type to better describe your requests
-type UserRequest = Request & {
-  user: YourUserType
-}
-
-const rpcAuthz = createMiddleware({
-  rpcPrefix: config.rpcPrefix,
-  handler: async (req: UserRequest, res, next) => {
-    const url = new URL(req.url, "http://localhost").pathname;
-    const fnName = url.replace(config.rpcPrefix, "");
-    const user = req.user; // set by earlier auth middleware
-
-    // Allow public functions through
-    if (publicFns.has(fnName)) return next();
-
-    // Reject unauthenticated
-    if (!user) {
-      res.statusCode = 401;
-      res.setHeader("Content-Type", "application/json");
-      res.end(JSON.stringify({ error: "Unauthorized" }));
-      return;
-    }
-
-    next();
-  },
-});
-```
-
-Wire it between auth and the RPC handler:
-
-```ts
-app.use(authMiddleware);      // sets req.user
-app.use(rpcAuthz);            // per-function guard
-app.use(createRPCMiddleware());
-```
-
-For role-based access, extend with a map:
-
-```ts
-const roleAccess: Record<string, string[]> = {
-  deleteUser: ["admin"],
-  updateProfile: ["user", "admin"],
-};
-
-if (!user || !roleAccess[fnName]?.includes(user.role)) {
-  // 401 or 403
-}
-```
-
-## Body Limits
-
-In most cases you should rely on your framework's body-parser middleware:
-
-```ts
-// Express
-import express from "express";
-const app = express();
-app.use(express.json({ limit: 1024 * 1024 })); // or "1mb"
-app.use(createRPCMiddleware());
-```
-
-```ts
-// Fastify
-import Fastify from "fastify";
-
-const app = Fastify({ logger: false, bodyLimit: 1024 * 1024 }); // "1MB"
-```
-
-```ts
-// Hono
-import { Hono } from "hono";
-import { bodyLimit } from 'hono/body-limit';
-
-const app = new Hono();
-app.use('*', bodyLimit({ maxSize: 1024 * 1024 })) // 1MB
-```
-
-```ts
-// Koa
-import Koa from "koa";
-import { koaBody } from 'koa-body';
-
-const app = new Koa();
-app.use(koaBody({ jsonLimit: 1024 * 1024 })); // 1MB
-```
-
-In other cases, your custom [server app](../examples/ssr/http-express.ts) can use something like this:
-```ts
-// SSR (custom node:http server with Vite middleware mode)
-import { createMiddleware, readBody } from "@thednp/rpc/express";
-import { loadRPCConfig } from "@thednp/rpc";
-
-const config = await loadRPCConfig();
-const MAX_BODY_SIZE = 1024 * 1024;
-
-app.use(createMiddleware({
-  rpcPrefix: config.rpcPrefix,
-  handler: async (req, res, next) => {
-    const { data } = await readBody(req);
-    if (Buffer.byteLength(typeof data === "string" ? data : JSON.stringify(data)) > MAX_BODY_SIZE) {
-      res.statusCode = 413;
-      res.end("Payload Too Large");
-      return;
-    }
-    req.body = data;
-    next();
-  },
-}));
-```
-
-For SPA you can make use of the vite runtime [proxy](../examples/spa/vite.config.ts)
-```ts
-// SPA (dedicated RPC proxy server)
-import { readBody } from "@thednp/rpc/express";
-
-const MAX_BODY_SIZE = 1024 * 1024;
-
-const bodyLimit = async (req, res, next) => {
-  const { data } = await readBody(req);
-  if (Buffer.byteLength(typeof data === "string" ? data : JSON.stringify(data)) > MAX_BODY_SIZE) {
-    res.statusCode = 413;
-    res.end("Payload Too Large");
-    return;
-  }
-  req.body = data;
-  next();
-};
-```
-
-## Rate Limiting
-
-Throttle RPC endpoints like any other route — rate limiting is the host's responsibility:
-
-```ts
-// Express
-import { rateLimit } from 'express-rate-limit';
-
-app.use('/__rpc', rateLimit({
-  windowMs: 60 * 1000, // 1 minute
-  limit: 60, // 60 requests per window
-  standardHeaders: 'draft-8',
-  legacyHeaders: false,
-}));
-app.use(createRPCMiddleware());
-```
-
-```ts
-// Fastify
-import rateLimit from '@fastify/rate-limit';
-
-await app.register(rateLimit, { max: 60, timeWindow: '1 minute' });
-```
-
-```ts
-// Hono
-import { rateLimiter } from 'hono-rate-limiter';
-
-app.use('/__rpc/*', rateLimiter({ windowMs: 60_000, limit: 60 }));
-```
-
-```ts
-// Koa
-import { rateLimit } from 'koa2-ratelimit';
-
-app.use(rateLimit.middleware({ interval: { min: 1 }, max: 60 }));
-```
-
-## Origin / CSRF Protection
-
-`@thednp/rpc` performs **no origin validation by default** — like authentication, it is opt-in so the host decides.
-
-### Option A: `origin` middleware option
-
-When your RPC endpoints sit behind a reverse proxy with multiple public origins (e.g. a sibling subdomain), pass the allowed origin to `createRPCMiddleware()`:
-
-```ts
-app.use(createRPCMiddleware({
-  origin: 'https://app.example.com',
-}));
-```
-
-Requests carrying an `Origin` header that does not match are rejected with `403 Forbidden`. Requests without an `Origin` header (curl, native apps) pass through unchecked.
-
-> `SameSite=Lax` cookies already block cross-site `POST` from HTML forms; the `origin` option closes the remaining "sibling subdomain" case.
-
-### Option B: custom middleware
-
-Check `Sec-Fetch-Site` (Fetch Metadata) or `Origin` yourself before the RPC middleware:
-
-```ts
-// Express
-app.use((req, res, next) => {
-  const site = req.headers['sec-fetch-site'];
-  if (site && site !== 'same-origin' && site !== 'none') {
-    res.status(403).json({ error: 'Forbidden' });
-    return;
-  }
-  next();
-});
-app.use(createRPCMiddleware());
-```
-
-Note that strict checks rejecting requests *without* these headers (TanStack Start style) will break curl and native clients — only enforce when the header is present, or provide an opt-out.
-
-## SSR Guidance
-
-- On the **server**, `createServerFunction` runs directly (not Vite-transformed).
-- On the **client**, the plugin replaces server function calls with `fetch` based client modules.
-- Keep `src/entry-client.ts` and `src/entry-server.ts` separate for proper hydration.
-
-## File Naming
-
-Only files matching `server.ts`, `server.js`, `server.mjs`, `server.mts` in `src/api/` are scanned. Export functions individually for proper client module mapping:
-
-```ts
-// ✅ Good — individual exports
-export const sayHi = createServerFunction('say-hi', fn);
-export const add = createServerFunction('add-numbers', fn);
-
-// ❌ Avoid — default export or bundled objects
-export default { sayHi, add };
-```
-
-## Cache is Not @thednp/rpc's Job
-
-Use `react-query`, `SWR`, or your framework's data hooks for caching. `@thednp/rpc` is the **transport layer only**.

package/wiki/client-usage.md

@@ -1,66 +0,0 @@
-# Client Usage
-
-Server functions, despite their name, work in both server and client side (transformed into `fetch` based modules by our plugin), a perfect fit for isomorphic rendering.
-
-In most apps you will be working with client focused apps.
-
-## Auto-Generated Client Modules
-
-When you import from `./api` in your client code, the plugin intercepts the import and generates a client module for each server function.
-
-```ts
-import { sayHi, add } from './api';
-```
-
-Each imported function returns:
-
-```ts
-{ data: Promise<T>, cancel: (reason: string) => void }
-```
-
-- **`data`** — A promise that resolves to the server function's return value.
-- **`cancel(reason: string)`** — Aborts the underlying fetch request, causing `signal.aborted` to be set in the server function.
-
-### Example
-
-```ts
-import { sayHi } from './api';
-
-const { data, cancel } = sayHi('World');
-const result = await data; // "Hello World!"
-cancel('user cancelled'); // triggers AbortController on the client side
-```
-
-## Error Handling
-
-- **Fetch errors** (network failure, CORS) — thrown from `await data`
-- **HTTP 4xx/5xx responses** — thrown from `await data`
-- **Cancellation** — aborts the fetch and warns `"Request was cancelled"` in the console
-
-## @tanstack/react-query Integration
-
-`@thednp/rpc` is a transport pipe — it handles serialization and transport only. For client-side caching, data invalidation, and stale-while-revalidate patterns, use `@tanstack/react-query`:
-
-```ts
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { sayHi } from './api';
-
-function GreetUser({ name }: { name: string }) {
-  const queryClient = useQueryClient();
-
-  const { data } = useQuery({
-    queryKey: ['say-hi', name],
-    queryFn: ({ signal }) => {
-      const result = sayHi(name);
-      signal.addEventListener('abort', () => result.cancel('query cancelled'));
-      return result.data;
-    },
-  });
-
-  return <div>{data ?? 'Loading...'}</div>;
-}
-```
-
-Combine `cancel()` with React Query's `signal` for proper abort handling during component unmount or query invalidation.
-
-Other frameworks have a `@tanstack/<framework>-query` made by [Tanstack](https://tanstack.com/).

package/wiki/configuration.md

@@ -1,76 +0,0 @@
-# Configuration
-
-## `rpc.config.ts`
-
-Create `rpc.config.ts` in your project root for system-wide configuration:
-
-```ts
-import { defineConfig } from '@thednp/rpc';
-
-export default defineConfig({
-  rpcPrefix: '__rpc',
-  adapter: 'express',
-});
-```
-
-## `vite.config.ts`
-
-Update your `vite.config.ts` in your project root and set additional development options:
-
-```ts
-import { defineConfig } from 'vite';
-import rpc from '@thednp/rpc';
-
-export default defineConfig({
-  plugins: [rpc(/* development options */)]
-});
-
-```
-
-> **NOTE** these plugin options only apply to **development** and override the options in `rpc.config.ts`.
-
-### Options
-
-| Option       | Type     | Default     | Description                                                  |
-| --------------| ----------| -------------| --------------------------------------------------------------|
-| `rpcPrefix` | `string` | `'__rpc'`   | RPC endpoint prefix used in URL routing                      |
-| `adapter`    | `string` | `'express'` | Target adapter (`'express'`, `'fastify'`, `'hono'`, `'koa'`) |
-
-## Config File Discovery
-
-The plugin searches for config files in this order:
-
-1. `rpc.config.ts`
-2. `rpc.config.js`
-3. `rpc.config.mjs`
-4. `rpc.config.mts`
-5. `.rpcrc.ts`
-6. `.rpcrc.js`
-
-The first file found is used. If none is found, defaults are applied.
-
-## Utilities
-
-### `defineConfig`
-
-Type-safe helper for creating the config object. Provides autocomplete and type checking for all options.
-
-```ts
-import { defineConfig } from '@thednp/rpc';
-
-export default defineConfig({
-  rpcPrefix: '__rpc',
-});
-```
-
-### `loadRPCConfig`
-
-Programmatically load the RPC config, useful in custom server setups:
-
-```ts
-import { loadRPCConfig } from '@thednp/rpc';
-
-const config = await loadRPCConfig();
-console.log(config.rpcPrefix); // '__rpc'
-console.log(config.adapter);    // 'express'
-```

package/wiki/getting-started.md

@@ -1,105 +0,0 @@
-# Getting Started
-
-## Installation
-
-```bash
-// pnpm + jsr registry
-pnpm add jsr:@thednp/rpc
-```
-
-```bash
-// pnpm + npmjs registry
-pnpm add @thednp/rpc
-```
-
-```bash
-// npm + npmjs registry
-npm install @thednp/rpc
-```
-
-```bash
-// bun + npmjs registry
-bun add @thednp/rpc
-```
-
-```bash
-// deno + npmjs registry
-deno add npm:@thednp/rpc
-```
-
-```bash
-// deno + jsr registry
-deno add jsr:@thednp/rpc
-```
-
-## Quick Start
-
-For a quick understanding of a project setup check the [dedicated wiki section](./setup.md).
-
-### 1. Configure system wide configuration `rpc.config.ts`
-
-```ts
-import { defineConfig } from "@thednp/rpc";
-
-export default defineConfig({
-  rpcPrefix: "__rpc",
-  adapter: "express",
-});
-```
-
-Currently `@thednp/rpc` supports `'express'`, `'fastify'`, `'hono'` and `'koa'`. Check [adapters](./adapters.md) for more guides.
-
-Also check [configuration](./configuration.md) for more guides.
-
-
-### 2. Add the plugin to `vite.config.ts`
-
-```ts
-import rpc from '@thednp/rpc';
-
-export default {
-  plugins: [rpc()],
-};
-```
-
-Check [configuration](./configuration.md) for more guides.
-
-
-### 3. Create a server function in `src/api/server.ts`
-
-```ts
-import { createServerFunction } from '@thednp/rpc/server';
-
-export const sayHi = createServerFunction(
-  'say-hi',
-  async (signal: AbortSignal, name: string) => {
-    signal.throwIfAborted();
-    await new Promise((res) => setTimeout(res, 1500));
-    return `Hello ${name}!`;
-  },
-);
-```
-
-Expose it in `src/api/index.ts`
-
-```ts
-export * from "./server"
-```
-
-Check the [server functions guide](./server-functions.md) for details.
-
-### 4. Use it in your code
-
-```ts
-import { sayHi } from './api';
-
-const { data, cancel } = sayHi('World');
-const result = await data; // "Hello World!"
-cancel('user cancelled');
-```
-
-That's it — the plugin auto-scans `src/api/server.ts`, maps exports to client functions, and replaces `./api` imports with fetch-based client modules during the Vite transform.
-
-For a more detailed guide on client-side usage, check the [dedicated wiki section](./client-usage.md).
-
-Next you need to [connect the adapter](./adapters.md) with your server of choice.

package/wiki/index.md

@@ -1,14 +0,0 @@
-# @thednp/rpc
-
-A Vite plugin for creating server functions with automatic Remote Procedure Calls (RPC) generation. Server functions are defined in a dedicated file, auto-scanned, and transformed into client-side fetch modules — no manual API route setup required.
-
-## Table of Contents
-
-- [Getting Started](./getting-started.md) — Installation and quick start
-- [Setup Guide](./setup.md) — Project structure and configuration
-- [Configuration](./configuration.md) — Configuration reference
-- [Server Functions](./server-functions.md) — Creating server functions
-- [Client Usage](./client-usage.md) — Client-side usage
-- [Adapters](./adapters.md) — Framework adapters
-- [Security](./security.md) — Security hardening
-- [Best Practices](./best-practices.md) — Tips and best practices

package/wiki/security.md

@@ -1,76 +0,0 @@
-# Security
-
-## Prefix Boundary Check
-
-All adapters use `new RegExp(\`^/${escapeRegExp(rpcPrefix)}/\`)` instead of `startsWith` to match the RPC endpoint path. The prefix is escaped with `escapeRegExp()` before being embedded in the boundary regex, preventing ReDoS or unintended matching from metacharacters in the prefix. This prevents path-segment bypass attacks:
-
-```
-rpcPrefix = '__rpc'
-
-# Safe: matches /__rpc/foo
-// __rpc/foo  →  /__rpc/
-
-# Not matched: /__rpc-evil/foo or /foo/__rpc/bar
-```
-
-Using `startsWith` would incorrectly match paths like `/__rpc-evil/foo`, which could route to unintended handlers. The regex ensures the prefix is a standalone path segment.
-
-## Koa URL Normalization
-
-The Koa adapter parses `ctx.url` through `new URL()` before prefix checking. This strips query strings and normalizes encoding, preventing query-string injection attacks:
-
-```ts
-const url = new URL(ctx.url, 'http://localhost');
-const pathname = url.pathname; // clean, no query string
-```
-
-## Generic 404 Responses
-
-Error responses do not echo the requested function name. This prevents function enumeration — an attacker cannot discover available RPC functions by probing for non-existent endpoints.
-
-## HTTP Method Enforcement
-
-Server functions default to `POST`, and the middleware rejects any request whose HTTP method does not match the function's configured method with `405 Method Not Allowed`:
-
-```
-GET  /__rpc/do-stuff  →  405  (function defaults to POST)
-POST /__rpc/do-stuff  →  200
-```
-
-This blocks the simplest CSRF vector: an attacker page embedding `<img src="/__rpc/do-stuff">` or a form `GET` that would otherwise trigger side effects. Functions that opt into `method: "GET"` (via `createServerFunction(name, handler, { method: 'GET' })`) receive their arguments as an `?args=` JSON query parameter. Reserve `GET` for side-effect-free functions only. See [Server Functions Guide](./server-functions.md) for details.
-
-## Origin Validation
-
-`@thednp/rpc` performs no origin validation by default, but `createRPCMiddleware()` accepts an `origin` option:
-
-```ts
-app.use(createRPCMiddleware({ origin: 'https://app.example.com' }));
-```
-
-When set, any request carrying an `Origin` header that does not match the configured origin is rejected with `403 Forbidden`. Requests **without** an `Origin` header (curl, native clients) pass through — the check only rejects when the browser-provided header disagrees. This closes the "sibling subdomain" CSRF gap that `SameSite=Lax` cookies alone cannot cover. See [Best Practices Guide](./best-practices.md) for custom middleware alternatives.
-
-## Authentication via Middleware
-
-Authentication is handled by middleware registered **before** `createRPCMiddleware()`. The middleware chain composes naturally:
-
-```ts
-// Express example
-app.use(authMiddleware);             // auth first
-app.use(createRPCMiddleware());      // RPC second
-```
-
-Do not add auth hooks inside the plugin. Use your framework's standard middleware pattern. Check [Best Practices Guide](./best-practices.md) for more detailed examples.
-
-## Body Size Limits
-
-JSON body size limits are handled by your framework's body-parser middleware:
-
-- **Express**: `express.json({ limit: '1mb' })` (default **100kb**)
-- **Fastify**: `bodyLimit` option in Fastify config (default **1 MiB**)
-- **Koa**: `koa-body({ formLimit: '1mb' })`
-- **Hono**: Built-in body size limiting
-
-The `readBody` utility of each adapter reads the raw request stream and does **not** impose a built-in size limit — always register your framework's body-parser middleware (or a custom limit handler) before `createRPCMiddleware()`. Check [Best Practices Guide](./best-practices.md) for body-limit examples.
-
-## Input Validation
-Server functions receive raw, untrusted client data. Always validate before use. Check [Server Functions Guide](./server-functions.md) for more detailed examples.