@thednp/rpc 0.0.1 → 0.0.5

package/wiki/server-functions.md

@@ -1,93 +0,0 @@
-# Server Functions
-
-## `createServerFunction(name, handler, options?)`
-
-The core API for defining server-side functions.
-
-### Signature
-
-```ts
-function createServerFunction<T>(
-  name: string,
-  handler: (signal: AbortSignal, ...args: JsonArray) => Promise<T>,
-  options?: { contentType: 'application/json' | 'text/plain'}
-): ServerFunction<T>;
-```
-
-### Parameters
-
-- **`name`** (`string`) — The registered name used in RPC routing. Must match the name used when calling the function on the client.
-- **`handler`** (`(signal: AbortSignal, ...args: JsonArray) => Promise<T>`) — The actual implementation. The first argument is always an `AbortSignal`; remaining arguments come from the client. The return value must be JSON-serializable.
-- **`options`** (`{ contentType?: 'application/json' | 'text/plain' }`) — Optional serialization strategy. Defaults to `'application/json'`.
-
-### AbortSignal
-
-The first argument to every server function is an `AbortSignal`. This allows the client to cancel a request:
-
-```ts
-export const longTask = createServerFunction(
-  'long-task',
-  async (signal: AbortSignal, id: string) => {
-    signal.throwIfAborted(); // throws if client cancelled
-    // ... do work ...
-    signal.throwIfAborted(); // check again after each step
-    return result;
-  },
-);
-```
-
-Use `signal.aborted` or `signal.throwIfAborted()` in long-running functions to respond to cancellation promptly.
-
-### Registration
-
-When `createServerFunction` is called, it registers the function in a server-side map keyed by `name`. This map is used by the RPC middleware to route incoming requests to the correct implementation.
-
-### Return Type
-
-The return value of `handler` is serialized to JSON and sent as the HTTP response body. Ensure your return type is JSON-serializable.
-
-## Input Validation
-
-Server functions receive raw, untrusted client data. Always validate before use.
-
-**zod:**
-
-```ts
-import { z } from 'zod';
-import { createServerFunction } from '@thednp/rpc/server';
-
-const AddSchema = z.object({
-  a: z.number(),
-  b: z.number(),
-});
-
-export const add = createServerFunction('add', async (signal, raw) => {
-  const parsed = AddSchema.safeParse(raw);
-  if (!parsed.success) {
-    return { error: parsed.error.flatten() };
-  }
-  return parsed.data.a + parsed.data.b;
-});
-```
-
-**valibot:**
-
-```ts
-import * as v from 'valibot';
-import { createServerFunction } from '@thednp/rpc/server';
-
-const AddSchema = v.object({
-  a: v.number(),
-  b: v.number(),
-});
-
-export const add = createServerFunction('add', async (signal, raw) => {
-  const parsed = v.safeParse(AddSchema, raw);
-  if (parsed.issues) {
-    return { error: v.flatten(parsed.issues).nested };
-  }
-  return parsed.output.a + parsed.output.b;
-});
-```
-
-Validation errors return structured data instead of throwing — the client's auto-generated `handleResponse` receives `{ error: ... }` and surfaces it as an `Error`.

package/wiki/setup.md

@@ -1,77 +0,0 @@
-# Setup
-
-## Required Project Structure
-
-```
-project/
-├── src/
-│   ├── api/
-│   │   └── server.ts        # Auto-scanned server functions
-│   ├── entry-client.ts      # Client entry (SSR projects)
-│   └── entry-server.ts      # Server entry (SSR projects)
-├── vite.config.ts           # Add rpc() plugin here
-├── rpc.config.ts            # Optional config
-└── package.json
-```
-
-## Server Files
-
-The plugin looks in `src/api/` for files matching these names:
-
-- `server.ts`
-- `server.js`
-- `server.mjs`
-- `server.mts`
-
-Each matched file is loaded with `vite.ssrLoadModule`, and all named exports are mapped to client functions. Export each function individually for proper mapping.
-
-## How Auto-Scanning Works
-
-1. During `resolveId`, the plugin intercepts imports from `./api` (or paths under `src/api/`).
-2. It scans `src/api/` for the server files listed above and loads them via `vite.ssrLoadModule`.
-3. It builds a map of export names to their `createServerFunction` registration names.
-4. During `transform`, it replaces the import with generated client modules that use `fetch` API under the hood.
-
-## SSR vs SPA
-
-### SSR Projects
-
-Create both `src/entry-client.ts` and `src/entry-server.ts`. The client bundle imports from `./api`, which gets transformed by the plugin. On the server, `createServerFunction` runs directly (not transformed).
-
-### SPA Projects
-
-Import directly from `./api` in your client code. No server entry is needed.
-
-## Production Adapters
-
-Use the appropriate adapter for your framework:
-
-```ts
-// Express
-import { attachRPC, attachVite } from '@thednp/rpc/express';
-await attachRPC(app);  // production
-attachVite(app, vite); // development
-```
-
-```ts
-// Fastify
-import { attachRPC, attachVite } from '@thednp/rpc/fastify';
-await attachRPC(app);  // production
-attachVite(app, vite); // development
-```
-
-```ts
-// Hono
-import { attachRPC, attachVite } from '@thednp/rpc/hono';
-await attachRPC(app);  // production
-attachVite(app, vite); // development
-```
-
-```ts
-// Koa
-import { attachRPC, attachVite } from '@thednp/rpc/koa';
-await attachRPC(app);  // production
-attachVite(app, vite); // development
-```
-
-See [Adapters](adapters.md) for full server setup examples.