@fy-tools/rpc-server-expressjs 0.0.119-alpha.10387 → 0.0.119-alpha.10389

package/README.md

@@ -1,7 +1,149 @@
-# rpc-server-express
+# @fy-tools/rpc-server-expressjs
 
-This library was generated with [Nx](https://nx.dev).
+Express adapter for `@fy-tools/rpc-server`. Pass your app schema and an Express instance — routes are registered automatically, request validation is handled for you, and handler context is fully typed.
 
-## Building
+## Installation
 
-Run `nx build rpc-server-express` to build the library.
+```bash
+npm install @fy-tools/rpc-server-expressjs express
+```
+
+## 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
+
+Add any Express middleware before passing the app to `App` — JSON parsing is required for body validation to work.
+
+```ts
+import { App } from '@fy-tools/rpc-server-expressjs';
+import express from 'express';
+import { Schema } from './schema';
+
+const expressApp = express();
+expressApp.use(express.json());
+
+const server = new App(expressApp, Schema);
+```
+
+### 3. 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() };
+});
+
+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);
+});
+```
+
+### 4. Start the server
+
+```ts
+server._app.listen(3000);
+```
+
+---
+
+## Handler context
+
+The context passed to each handler contains:
+
+| Property | Type | Description |
+|---|---|---|
+| `body` | Inferred from schema | Validated and parsed request body |
+| `params` | Inferred from schema | Validated URL path parameters |
+| `query` | Inferred from schema | Validated query string parameters |
+| `req` | `express.Request` | Raw Express request object |
+| `res` | `express.Response` | Raw Express response object |
+
+Validation runs automatically before the handler is called. If body, params, or query fail their schema, the route responds with `400` and a validation error — the handler is not invoked.
+
+The return value of the handler is automatically sent as JSON. If you need to send a custom response (e.g. set headers, stream a file), call `res` directly and return anything — the adapter skips auto-send if headers have already been sent.
+
+---
+
+## API reference
+
+### `App`
+
+```ts
+new App(app: Application, schema: AnyApp)
+```
+
+Registers all controllers from the schema onto the Express instance.
+
+| Member | Description |
+|---|---|
+| `.C` | Typed proxy of all controllers, keyed by encoded path |
+| `.build(fn)` | Transforms the Express app and returns a new `App` |
+| `._app` | The underlying Express instance — call `.listen()` on this |
+
+### `Controller`
+
+Instantiated automatically by `App`. Creates an Express `Router` and mounts it at the controller's base path.
+
+| Member | Description |
+|---|---|
+| `.R` | Typed proxy of all routes in the controller, keyed by encoded method + path |
+| `.build(fn)` | Transforms the Express app and returns a new `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)` | Transforms the Express router and returns a new `Route` |

package/dist/lib/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/lib/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,qBAAa,GAAG,CAAC,UAAU,SAAS,WAAW,GAAG,WAAW,EAAE,MAAM,SAAS,MAAM,GAAG,MAAM;IAYxE,IAAI,EAAE,UAAU;IAAS,OAAO,EAAE,MAAM;IAX3D;;;SAGK;IACE,CAAC,EAAS,GACd,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CACrE,UAAU,EACV,oBAAoB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAC1D,GACF,CAAC;gBAEiB,IAAI,EAAE,UAAU,EAAS,OAAO,EAAE,MAAM;IAS3D,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,CAAC;CAGxD"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/lib/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,qBAAa,GAAG,CAAC,UAAU,SAAS,WAAW,GAAG,WAAW,EAAE,MAAM,SAAS,MAAM,GAAG,MAAM;IAYxE,IAAI,EAAE,UAAU;IAAS,OAAO,EAAE,MAAM;IAX3D;;;SAGK;IACE,CAAC,EAAS,GACd,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CACrE,UAAU,EACV,oBAAoB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAC1D,GACF,CAAC;gBAEiB,IAAI,EAAE,UAAU,EAAS,OAAO,EAAE,MAAM;IAY3D,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,CAAC;CAGxD"}

package/dist/lib/app.js

@@ -14,7 +14,9 @@ class App {
         this._app = _app;
         this._schema = _schema;
         for (const i in _schema._controllers_map) {
-            this.C[i] = new controller_1.Controller(this._app, _schema._controllers[_schema._controllers_map[i]]);
+            const controller = new controller_1.Controller(this._app, _schema._controllers[_schema._controllers_map[i]]);
+            this._app = controller._app;
+            this.C[i] = controller;
         }
     }
     build(fn) {

package/dist/lib/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/lib/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,aAAa,EACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,qBAAa,UAAU,CACrB,GAAG,SAAS,WAAW,GAAG,WAAW,EACrC,MAAM,SAAS,aAAa,GAAG,aAAa;IAQzB,IAAI,EAAE,GAAG;IAAS,OAAO,EAAE,MAAM;IANpD;;;SAGK;IACE,CAAC,KAkBD,GAAG,iHAlBD;gBAEU,IAAI,EAAE,GAAG,EAAS,OAAO,EAAE,MAAM;IA6BpD,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;CAGjD"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/lib/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,aAAa,EACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,qBAAa,UAAU,CACrB,GAAG,SAAS,WAAW,GAAG,WAAW,EACrC,MAAM,SAAS,aAAa,GAAG,aAAa;IAQzB,IAAI,EAAE,GAAG;IAAS,OAAO,EAAE,MAAM;IANpD;;;SAGK;IACE,CAAC,KAuBD,GAAG,iHAvBD;gBAEU,IAAI,EAAE,GAAG,EAAS,OAAO,EAAE,MAAM;IAkCpD,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;CAGjD"}

package/dist/lib/controller.js

@@ -17,11 +17,14 @@ class Controller {
         this._schema = _schema;
         const router = express_1.default.Router();
         const routes = {};
+        let currentRouter = router;
         for (const i in _schema._routes_map) {
-            routes[i] = new route_1.Route(router, _schema._routes[_schema._routes_map[i]]);
+            const route = new route_1.Route(currentRouter, _schema._routes[_schema._routes_map[i]]);
+            currentRouter = route._app;
+            routes[i] = route;
         }
         const basePath = this._schema._basePath ? `/${this._schema._basePath}` : '/';
-        this._app.use(basePath, router);
+        this._app.use(basePath, currentRouter);
         this.R = new Proxy(routes, {
             get(target, p) {
                 return routes[p];

package/dist/lib/route.d.ts

@@ -1,11 +1,12 @@
-import type { AnyRoute, Response } from '@fy-tools/rpc-server';
+import { AnyRoute, Response } from '@fy-tools/rpc-server';
 import type { Router } from 'express';
 import type { RouteToContext } from './types';
 export declare class Route<App extends Router = Router, Schema extends AnyRoute = AnyRoute> {
     _app: App;
     _schema: Schema;
+    private readonly _handlerRef;
     constructor(_app: App, _schema: Schema);
     build<T extends Router>(fn: (app: App) => T): Route<T, Schema>;
-    handler(fn: (ctx: RouteToContext<Schema>) => Promise<Response<Schema>>): this;
+    handler(fn: (ctx: RouteToContext<Schema>) => Promise<Response<Schema>>): void;
 }
 //# sourceMappingURL=route.d.ts.map

package/dist/lib/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/lib/route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAIV,MAAM,EACP,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,KAAK,CAChB,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,MAAM,SAAS,QAAQ,GAAG,QAAQ;IAEf,IAAI,EAAE,GAAG;IAAS,OAAO,EAAE,MAAM;gBAAjC,IAAI,EAAE,GAAG,EAAS,OAAO,EAAE,MAAM;IAEpD,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;IAI3C,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;CA0EvE"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/lib/route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAmB,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EAIV,MAAM,EACP,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,KAAK,CAChB,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,MAAM,SAAS,QAAQ,GAAG,QAAQ;IAMf,IAAI,EAAE,GAAG;IAAS,OAAO,EAAE,MAAM;IAJpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAE1B;gBAEiB,IAAI,EAAE,GAAG,EAAS,OAAO,EAAE,MAAM;IAgEpD,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;IAI3C,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;CAGvE"}

package/dist/lib/route.js

@@ -1,55 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Route = void 0;
+const rpc_server_1 = require("@fy-tools/rpc-server");
 class Route {
     _app;
     _schema;
+    _handlerRef;
     constructor(_app, _schema) {
         this._app = _app;
         this._schema = _schema;
-    }
-    build(fn) {
-        return new Route(fn(this._app), this._schema);
-    }
-    handler(fn) {
+        this._handlerRef = {
+            fn: () => {
+                throw new Error('Route handler not implemented');
+            },
+        };
+        // Capture ref object — closure reads handlerRef.fn, not this._handlerFn,
+        // so reassignment in handler() is always visible even if this-binding diverges.
+        const handlerRef = this._handlerRef;
         const path = this._schema._path ? `/${this._schema._path}` : '/';
         const method = this._schema._method;
-        this._app[method](path, async (req, res, next) => {
+        this._app = this._app[method](path, async (req, res, next) => {
             try {
                 let body = req.body;
                 let params = req.params;
                 let query = req.query;
                 if (this._schema._body) {
                     const result = await this._schema._body['~standard'].validate(req.body);
-                    if (result.issues) {
-                        res
-                            .status(400)
-                            .json({ error: 'Validation error', issues: result.issues });
-                        return;
-                    }
+                    if (result.issues)
+                        return next(new rpc_server_1.ValidationError(result.issues));
                     body = result.value;
                 }
                 if (this._schema._params) {
                     const result = await this._schema._params['~standard'].validate(req.params);
-                    if (result.issues) {
-                        res
-                            .status(400)
-                            .json({ error: 'Validation error', issues: result.issues });
-                        return;
-                    }
+                    if (result.issues)
+                        return next(new rpc_server_1.ValidationError(result.issues));
                     params = result.value;
                 }
                 if (this._schema._query) {
                     const result = await this._schema._query['~standard'].validate(req.query);
-                    if (result.issues) {
-                        res
-                            .status(400)
-                            .json({ error: 'Validation error', issues: result.issues });
-                        return;
-                    }
+                    if (result.issues)
+                        return next(new rpc_server_1.ValidationError(result.issues));
                     query = result.value;
                 }
-                const response = await fn({
+                const response = await handlerRef.fn({
                     body,
                     params,
                     query,
@@ -63,7 +56,12 @@ class Route {
                 next(err);
             }
         });
-        return this;
+    }
+    build(fn) {
+        return new Route(fn(this._app), this._schema);
+    }
+    handler(fn) {
+        this._handlerRef.fn = fn;
     }
 }
 exports.Route = Route;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fy-tools/rpc-server-expressjs",
-  "version": "0.0.119-alpha.10387",
+  "version": "0.0.119-alpha.10389",
   "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.10389",
     "express": "^4.21.2",
     "tslib": "^2.3.0"
   },