@thednp/rpc 0.0.1 → 0.0.5

package/wiki/adapters.md

@@ -1,143 +0,0 @@
-# Adapters
-
-`@thednp/rpc` provides adapters for ExpressJS, Fastify, Hono, and Koa. Each adapter exports `attachRPC` for production and `attachVite` for development.
-
-## Common Pattern
-
-All adapters share the same two-function API:
-
-```ts
-import { attachRPC, attachVite } from '@thednp/rpc/<adapter>';
-
-// Production: mount RPC middleware
-await attachRPC(app);
-
-// Development: mount RPC + Vite middleware
-attachVite(app, vite);
-```
-
-## Express
-
-### Installation
-
-```bash
-pnpm add @thednp/rpc express
-```
-
-### Usage
-
-```ts
-// server.ts
-import express from 'express';
-import { attachRPC, attachVite } from '@thednp/rpc/express';
-import { createServer } from 'vite';
-
-const app = express();
-const isDev = process.env.NODE_ENV !== 'production';
-
-if (isDev) {
-  const vite = await createServer({ server: { middlewareMode: true } });
-  attachVite(app, vite);
-} else {
-  await attachRPC(app);
-  app.use(express.static('dist'));
-}
-
-app.listen(3000);
-```
-
-## Fastify
-
-### Installation
-
-```bash
-pnpm add @thednp/rpc fastify
-```
-
-### Usage
-
-```ts
-// server.ts
-import Fastify from 'fastify';
-import { attachRPC, attachVite } from '@thednp/rpc/fastify';
-import { createServer } from 'vite';
-
-const fastify = Fastify({ logger: true });
-const isDev = process.env.NODE_ENV !== 'production';
-
-if (isDev) {
-  const vite = await createServer({ server: { middlewareMode: true } });
-  attachVite(fastify, vite);
-} else {
-  await attachRPC(fastify);
-  fastify.register(require('@fastify/static'), { root: 'dist' });
-}
-
-fastify.listen({ port: 3000 });
-```
-
-## Hono
-
-### Installation
-
-```bash
-pnpm add @thednp/rpc hono
-```
-
-### Usage
-
-```ts
-// server.ts
-import { Hono } from 'hono';
-import { attachRPC, attachVite } from '@thednp/rpc/hono';
-import { createServer } from 'vite';
-
-const app = new Hono();
-const isDev = process.env.NODE_ENV !== 'production';
-
-if (isDev) {
-  const vite = await createServer({ server: { middlewareMode: true } });
-  attachVite(app, vite);
-} else {
-  await attachRPC(app);
-  app.use('*', serveStatic({ root: './dist' }));
-}
-
-export default app;
-```
-
-## Koa
-
-### Installation
-
-```bash
-pnpm add @thednp/rpc koa koa-body
-```
-
-### Usage
-
-Body parser must be registered before the RPC middleware:
-
-```ts
-// server.ts
-import Koa from 'koa';
-import { koaBody } from 'koa-body';
-import { attachRPC, attachVite } from '@thednp/rpc/koa';
-import { createServer } from 'vite';
-
-const app = new Koa();
-const isDev = process.env.NODE_ENV !== 'production';
-
-// Body parser must come before RPC middleware
-app.use(koaBody({ jsonLimit: 1024 * 1024 }));
-
-if (isDev) {
-  const vite = await createServer({ server: { middlewareMode: true } });
-  attachVite(app, vite);
-} else {
-  await attachRPC(app);
-  app.use(require('koa-static')('dist'));
-}
-
-app.listen(3000);
-```

package/wiki/best-practices.md

@@ -1,201 +0,0 @@
-# Best Practices
-
-## @thednp/rpc is a Transport Pipe
-
-`@thednp/rpc` handles serialization and **transport only**. It does not provide:
-
-- Caching
-- Authentication
-- Validation
-- State management
-- 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`.
-
-## Authentication
-
-Use middleware before `createRPCMiddleware()`:
-
-```ts
-// Express
-app.use(authMiddleware);
-app.use(createRPCMiddleware());
-```
-
-> Never add auth hooks inside the plugin.
-
-## Body Limits
-
-In most cases you can 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
-```
-
-```ts
-// SSR (custom 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({
-  rpcPreffix: config.rpcPreffix,
-  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();
-  },
-}));
-```
-
-```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();
-};
-```
-
-## 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,62 +0,0 @@
-# Client Usage
-
-## 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)`** — 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** — returns `"Request cancelled by user"` from `await data`
-
-## @tanstack/react-query Integration
-
-`@thednp/rpc` is a dumb pipe — it handles serialization and transport only. For client-side caching, 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,77 +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({
-  rpcPreffix: '__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                                                  |
-| --------------| ----------| -------------| --------------------------------------------------------------|
-| `rpcPreffix` | `string` | `'__rpc'`   | RPC endpoint prefix used in URL routing                      |
-| `adapter`    | `string` | `'express'` | Target adapter (`'express'`, `'fastify'`, `'hono'`, `'koa'`) |
-
-## Config File Discovery
-
-When `configFile` is not specified, 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({
-  rpcPreffix: '__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.rpcPreffix); // '__rpc'
-console.log(config.adapter);    // 'express'
-```

package/wiki/getting-started.md

@@ -1,76 +0,0 @@
-# Getting Started
-
-## Installation
-
-```bash
-pnpm add @thednp/rpc@latest
-```
-
-```bash
-npm install @thednp/rpc@latest
-```
-
-```bash
-bun add @thednp/rpc@latest
-```
-
-```bash
-deno add npm:@thednp/rpc@latest
-```
-
-## Quick Start
-
-### 1. Configure system wide configuration `rpc.config.ts`
-
-```ts
-import { defineConfig } from "@thednp/rpc";
-
-export default defineConfig({
-  rpcPreffix: "__server",
-  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}!`;
-  },
-);
-```
-
-### 4. Use it on the client
-
-```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.

package/wiki/index.md

@@ -1,26 +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.
-
-## Features
-
-- File-level server code isolation without directives like `'use server'`
-- System-wide configuration via `rpc.config.ts`
-- Automatic RPC generation for server functions
-- `AbortController` support for request cancellation
-- Adapters for Express, Fastify, Hono, and Koa with unified API
-- Framework-agnostic core
-- TypeScript support
-- Path-segment prefix matching prevents URL boundary bypass
-- @tanstack/react-query integration for client-side caching and invalidation
-
-## 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,54 +0,0 @@
-# Security
-
-## Prefix Boundary Check
-
-All adapters use `new RegExp(\`^/${rpcPreffix}/\`)` instead of `startsWith` to match the RPC endpoint path. This prevents path-segment bypass attacks:
-
-```
-rpcPreffix = '__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.
-
-## 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.
-
-## 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
-
-Since the RPC framework's `readBody` also accepts `text/plain` requests (not parsed by the JSON body parser), the raw stream path in the Express and Koa adapters has a built-in safety net — a `maxBodySize` parameter that defaults to **1 MiB**. Pass a custom value to `readBody(req, signal, myLimit)` to override.
-
-Register body parsing middleware before `createRPCMiddleware()`.