@fy-tools/rpc-server-elysia 0.0.119-alpha.10387 → 0.0.119-alpha.10388

package/README.md

@@ -1,7 +1,145 @@
-# rpc-server-elysia
+# @fy-tools/rpc-server-elysia
 
-This library was generated with [Nx](https://nx.dev).
+Elysia adapter for `@fy-tools/rpc-server`. Pass your app schema and an Elysia instance — routes and groups are registered automatically, and handlers are fully type-safe.
 
-## Building
+## Installation
 
-Run `nx build rpc-server-elysia` to build the library.
+```bash
+npm install @fy-tools/rpc-server-elysia elysia
+```
+
+## Usage
+
+### 1. Define a schema
+
+Use `@fy-tools/rpc-server` to define your API surface. See its [README](../rpc-server/README.md) for full details.
+
+```ts
+// schema.ts
+import { App, Controller, HttpMethod, Route } from '@fy-tools/rpc-server';
+import { z } from 'zod';
+
+export const Schema = new App()
+  .controller(
+    new Controller('auth')
+      .route(
+        new Route('login', HttpMethod.POST)
+          .body(z.object({ email: z.string(), password: z.string() }))
+          .response(z.object({ token: z.string() }))
+      )
+  )
+  .controller(
+    new Controller('users')
+      .route(
+        new Route('/', HttpMethod.GET)
+          .response(z.object({
+            items: z.array(z.object({ id: z.string(), email: z.string() })),
+          }))
+      )
+      .route(
+        new Route(':id', HttpMethod.GET)
+          .params(z.object({ id: z.string() }))
+          .response(z.object({ id: z.string(), email: z.string() }))
+      )
+      .route(
+        new Route(':id', HttpMethod.DELETE)
+          .params(z.object({ id: z.string() }))
+      )
+  );
+
+export type Schema = typeof Schema;
+```
+
+### 2. Create the server
+
+```ts
+import { App } from '@fy-tools/rpc-server-elysia';
+import { Elysia } from 'elysia';
+import { Schema } from './schema';
+
+const server = new App(new Elysia(), Schema);
+```
+
+### 3. Add middleware
+
+Use `.build()` to apply Elysia plugins before handlers run. The returned `App` carries the updated Elysia type, so resolved/derived values are available in every handler.
+
+```ts
+const authMiddleware = new Elysia({ name: 'auth' }).resolve(
+  { as: 'global' },
+  async ({ headers }) => {
+    const token = headers.authorization?.split(' ')[1];
+    return { userId: await verifyToken(token) };
+  }
+);
+
+const server = new App(new Elysia(), Schema)
+  .build((app) => app.use(authMiddleware));
+```
+
+### 4. Implement handlers
+
+Access controllers via `.C` and routes via `.R`. For path encoding rules, see the [rpc-server README](../rpc-server/README.md#path-encoding).
+
+```ts
+server.C.auth.R.post_login.handler(async (ctx) => {
+  const token = await authenticate(ctx.body.email, ctx.body.password);
+  return { token };
+});
+
+server.C.users.R.get_default.handler(async (ctx) => {
+  return { items: await db.users.findAll({ userId: ctx.userId }) };
+});
+
+server.C.users.R.get_$id.handler(async (ctx) => {
+  return db.users.findById(ctx.params.id);
+});
+
+server.C.users.R.delete_$id.handler(async (ctx) => {
+  await db.users.delete(ctx.params.id);
+});
+```
+
+`ctx.body`, `ctx.query`, `ctx.params` are typed from the schema. Anything added via `.build()` (e.g. `ctx.userId` above) is also fully typed.
+
+### 5. Start the server
+
+```ts
+server._app.listen(3000);
+```
+
+---
+
+## API reference
+
+### `App`
+
+```ts
+new App(app: AnyElysia, schema: AnyApp)
+```
+
+Registers all controllers from the schema onto the Elysia instance.
+
+| Member | Description |
+|---|---|
+| `.C` | Typed proxy of all controllers, keyed by encoded path |
+| `.build(fn)` | Applies middleware and returns a new `App` with the updated type |
+| `._app` | The underlying Elysia instance — call `.listen()` on this |
+
+### `Controller`
+
+Instantiated automatically by `App`. Wraps a single controller schema as an Elysia group.
+
+| Member | Description |
+|---|---|
+| `.R` | Typed proxy of all routes in the controller, keyed by encoded method + path |
+| `.build(fn)` | Applies middleware scoped to this controller |
+
+### `Route`
+
+Instantiated automatically by `Controller`. Wraps a single route schema.
+
+| Member | Description |
+|---|---|
+| `.handler(fn)` | Sets the request handler — called from `.R` on a controller |
+| `.build(fn)` | Applies middleware scoped to this route |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fy-tools/rpc-server-elysia",
-  "version": "0.0.119-alpha.10387",
+  "version": "0.0.119-alpha.10388",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/festusyuma/fy-tools.git",
@@ -22,7 +22,7 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@fy-tools/rpc-server": "0.0.119-alpha.10387",
+    "@fy-tools/rpc-server": "0.0.119-alpha.10388",
     "elysia": "^1.4.29",
     "tslib": "^2.3.0",
     "@standard-schema/spec": "^1.0.0"