@morojs/moro 1.8.11 → 1.8.13

package/dist/core/routing/unified-router.d.ts

@@ -20,7 +20,8 @@ export interface MiddlewarePhases {
 export interface RouteSchema {
     method: HttpMethod;
     path: string;
-    handler: RouteHandler;
+    /** A function, or the response body itself (see StaticBody) */
+    handler: RouteHandler | StaticBody | ParamEcho;
     validation?: ValidationConfig;
     auth?: AuthConfig;
     rateLimit?: RateLimitConfig;
@@ -33,6 +34,18 @@ export interface RouteSchema {
      *  calling into JS; every other server runs `handler`, which sends the
      *  same bytes. */
     static?: StaticResponse;
+    /** The engine shape of a param(name) handler on a bare route with exactly
+     *  that one parameter: the path segment between prefix and suffix is the
+     *  body. MoroEngineServer on @morojs/engine >= 1.1.9 (paramRoutes) answers
+     *  it without calling into JS; every other server runs `handler`. */
+    paramEcho?: ParamRouteReply;
+}
+export interface ParamRouteReply {
+    name: string;
+    prefix: string;
+    suffix: string;
+    status: number;
+    headers: string[] | null;
 }
 /** The reply a literal handler sends, in the engine's shape. */
 export interface StaticResponse {
@@ -43,14 +56,40 @@ export interface StaticResponse {
 }
 /** What .handler() accepts in place of a function: the response body itself. */
 export type StaticBody = string | Buffer;
+export declare const PARAM_ECHO: unique symbol;
+/** The marker param(name) produces: "answer with this path parameter as the
+ *  body". `.handler(param('id'))` on `/user/:id` answers `GET /user/42` with
+ *  `42`, as `res.end(req.params.id)` would - and on Moro's native engine, on
+ *  a route with nothing else configured, without entering JS at all. */
+export interface ParamEcho {
+    readonly [PARAM_ECHO]: true;
+    readonly name: string;
+}
+export declare function param(name: string): ParamEcho;
+export declare function isParamEcho(value: unknown): value is ParamEcho;
+/**
+ * param(name) in place of a handler: the route answers with that path
+ * parameter as the body, as res.end(req.params[name]) would. When `:name` is
+ * a whole segment of the path, the only parameter in it, and nothing else is
+ * configured, the schema also carries `paramEcho` - prefix and suffix around
+ * the segment - so a server that can answer it natively does so without
+ * calling into JS. The engine echoes the segment as it is on the wire,
+ * undecoded (as uWS does); a parameter that needs decoding stays a function
+ * handler.
+ */
+export declare function compileParamRoute(schema: Partial<RouteSchema>, echo: ParamEcho): RouteSchema;
 /**
  * A literal body in place of a handler: the route answers with exactly that
- * body, as res.send(body) would (status 200, the implied content-type). When
- * nothing else is configured on the route - no auth, validation, rate limit,
- * cache or middleware, and a literal path - the schema also carries `static`,
- * so a server that can answer it natively does so without calling into JS.
- * Anything configured keeps the route on the normal pipeline, where the
- * handler sends the same bytes after that configuration has run.
+ * body. A non-empty body goes out as res.send(body) would (status 200, the
+ * implied content-type). An empty body has nothing a content-type could
+ * describe, so it goes out as res.end() would: status and Content-Length: 0,
+ * no header block - 38 bytes less per response, and byte-identical to the
+ * engine's own static reply with no headers. When nothing else is configured
+ * on the route - no auth, validation, rate limit, cache or middleware, and a
+ * literal path - the schema also carries `static`, so a server that can
+ * answer it natively does so without calling into JS. Anything configured
+ * keeps the route on the normal pipeline, where the handler sends the same
+ * bytes after that configuration has run.
  */
 export declare function compileStaticRoute(schema: Partial<RouteSchema>, body: StaticBody): RouteSchema;
 export declare class RouteBuilder {
@@ -71,7 +110,7 @@ export declare class RouteBuilder {
     use(...middleware: Middleware[]): this;
     describe(description: string): this;
     tag(...tags: string[]): this;
-    handler<T>(handler: RouteHandler<T> | StaticBody): void;
+    handler<T>(handler: RouteHandler<T> | StaticBody | ParamEcho): void;
 }
 export declare class UnifiedRouter {
     private static instance;
@@ -129,7 +168,7 @@ export declare class UnifiedRouter {
     /**
      * Direct API (for backward compatibility)
      */
-    addRoute(method: HttpMethod, path: string, handler: RouteHandler, middleware?: Middleware[]): void;
+    addRoute(method: HttpMethod, path: string, handler: RouteHandler | StaticBody, middleware?: Middleware[]): void;
     /**
      * Find a matching route for the request - HYBRID OPTIMIZED
      * Returns boolean (sync) for fast-path routes, Promise<boolean> for others

package/dist/core/routing/unified-router.js

@@ -13,6 +13,74 @@ const logger = createFrameworkLogger('UnifiedRouter');
 const rateLimitCore = new RateLimitCore();
 const cacheCore = new CacheCore();
 const validationCore = new ValidationCore();
+export const PARAM_ECHO = Symbol.for('moro.paramEcho');
+export function param(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new Error('param(name) needs the parameter name, e.g. param("id") for "/user/:id"');
+    }
+    return Object.freeze({ [PARAM_ECHO]: true, name });
+}
+export function isParamEcho(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[PARAM_ECHO] === true);
+}
+// Nothing configured that a reply answered inside the engine would skip:
+// no auth, validation, rate limit, cache or middleware. (Static replies also
+// need a literal path; parameter echoes need exactly one parameter.)
+function isBareRoute(schema) {
+    const mw = schema.middleware;
+    const hasMiddleware = Array.isArray(mw)
+        ? mw.length > 0
+        : mw !== undefined &&
+            Object.keys(mw).some(phase => {
+                const list = mw[phase];
+                return Array.isArray(list) && list.length > 0;
+            });
+    return !schema.auth && !schema.validation && !schema.rateLimit && !schema.cache && !hasMiddleware;
+}
+/**
+ * param(name) in place of a handler: the route answers with that path
+ * parameter as the body, as res.end(req.params[name]) would. When `:name` is
+ * a whole segment of the path, the only parameter in it, and nothing else is
+ * configured, the schema also carries `paramEcho` - prefix and suffix around
+ * the segment - so a server that can answer it natively does so without
+ * calling into JS. The engine echoes the segment as it is on the wire,
+ * undecoded (as uWS does); a parameter that needs decoding stays a function
+ * handler.
+ */
+export function compileParamRoute(schema, echo) {
+    const name = echo.name;
+    schema.handler = (req, res) => {
+        const value = req.params?.[name];
+        res.end(value === undefined ? undefined : String(value));
+    };
+    const path = schema.path ?? '';
+    const segments = path.split('/');
+    const marker = `:${name}`;
+    const at = segments.indexOf(marker);
+    if (at === -1) {
+        // The router names a parameter after its whole segment, so ":name.json"
+        // is a parameter called "name.json" and param('name') would never see it.
+        // (":names" is a different parameter, not a misuse; it gets no echo.)
+        const partial = segments.some(seg => seg.startsWith(marker) && /^[^A-Za-z0-9_$]/.test(seg.slice(marker.length)));
+        if (partial) {
+            throw new Error(`param('${name}') needs '${marker}' as a whole segment of the route path; ` +
+                `'${path}' has it inside a segment`);
+        }
+        return schema;
+    }
+    const rest = segments.slice(at + 1);
+    const plainShape = !segments.some((seg, i) => i !== at && seg.startsWith(':')) &&
+        !path.includes('*') &&
+        !rest.includes(''); // no trailing or doubled slash after the parameter
+    if (plainShape && isBareRoute(schema)) {
+        const prefix = segments.slice(0, at).join('/') + '/';
+        const suffix = rest.length > 0 ? '/' + rest.join('/') : '';
+        schema.paramEcho = { name, prefix, suffix, status: 200, headers: null };
+    }
+    return schema;
+}
 // The content-type res.send() implies for a body it was given no header for:
 // the same three cases MoroEngineServer's send() picks a template by, spelled
 // out here so an engine-answered reply carries the bytes send() would have.
@@ -26,35 +94,34 @@ function impliedContentType(body) {
 }
 /**
  * A literal body in place of a handler: the route answers with exactly that
- * body, as res.send(body) would (status 200, the implied content-type). When
- * nothing else is configured on the route - no auth, validation, rate limit,
- * cache or middleware, and a literal path - the schema also carries `static`,
- * so a server that can answer it natively does so without calling into JS.
- * Anything configured keeps the route on the normal pipeline, where the
- * handler sends the same bytes after that configuration has run.
+ * body. A non-empty body goes out as res.send(body) would (status 200, the
+ * implied content-type). An empty body has nothing a content-type could
+ * describe, so it goes out as res.end() would: status and Content-Length: 0,
+ * no header block - 38 bytes less per response, and byte-identical to the
+ * engine's own static reply with no headers. When nothing else is configured
+ * on the route - no auth, validation, rate limit, cache or middleware, and a
+ * literal path - the schema also carries `static`, so a server that can
+ * answer it natively does so without calling into JS. Anything configured
+ * keeps the route on the normal pipeline, where the handler sends the same
+ * bytes after that configuration has run.
  */
 export function compileStaticRoute(schema, body) {
-    schema.handler = (_req, res) => {
-        res.send(body);
-    };
+    const empty = body.length === 0;
+    schema.handler = empty
+        ? (_req, res) => {
+            res.end();
+        }
+        : (_req, res) => {
+            res.send(body);
+        };
     const path = schema.path ?? '';
-    const mw = schema.middleware;
-    const hasMiddleware = Array.isArray(mw)
-        ? mw.length > 0
-        : mw !== undefined &&
-            Object.keys(mw).some(phase => {
-                const list = mw[phase];
-                return Array.isArray(list) && list.length > 0;
-            });
-    const bare = !path.includes(':') &&
-        !path.includes('*') &&
-        !schema.auth &&
-        !schema.validation &&
-        !schema.rateLimit &&
-        !schema.cache &&
-        !hasMiddleware;
+    const bare = !path.includes(':') && !path.includes('*') && isBareRoute(schema);
     if (bare) {
-        schema.static = { status: 200, headers: ['content-type', impliedContentType(body)], body };
+        schema.static = {
+            status: 200,
+            headers: empty ? null : ['content-type', impliedContentType(body)],
+            body,
+        };
     }
     return schema;
 }
@@ -188,8 +255,8 @@ export class RouteBuilder {
         }
         return this;
     }
-    // Terminal method: a function, or the response body itself (see
-    // compileStaticRoute for what a literal body means).
+    // Terminal method: a function, the response body itself (see
+    // compileStaticRoute), or param(name) (see compileParamRoute).
     handler(handler) {
         if (typeof handler === 'function') {
             // Avoid spread operator - add handler directly
@@ -201,7 +268,11 @@ export class RouteBuilder {
             this.router.registerRoute(compileStaticRoute(this.schema, handler));
             return;
         }
-        throw new Error('Handler is required: a function, or the response body as a string or Buffer');
+        if (isParamEcho(handler)) {
+            this.router.registerRoute(compileParamRoute(this.schema, handler));
+            return;
+        }
+        throw new Error('Handler is required: a function, the response body as a string or Buffer, or param(name)');
     }
 }
 // ===== Unified Router =====
@@ -334,13 +405,20 @@ export class UnifiedRouter {
         // - so this is where the body becomes a handler and, on a bare route, a
         // reply the native engine can answer itself.
         if (typeof schema.handler !== 'function') {
-            const body = schema.handler;
-            if (typeof body !== 'string' && !Buffer.isBuffer(body)) {
+            const given = schema.handler;
+            if (isParamEcho(given)) {
+                compileParamRoute(schema, given);
+            }
+            else if (typeof given === 'string' || Buffer.isBuffer(given)) {
+                compileStaticRoute(schema, given);
+            }
+            else {
                 throw new Error(`Handler for ${schema.method} ${schema.path} must be a function, ` +
-                    'or the response body as a string or Buffer');
+                    'the response body as a string or Buffer, or param(name)');
             }
-            compileStaticRoute(schema, body);
         }
+        // From here on the handler is a function, whichever form was registered.
+        const registered = schema;
         // OPTIMIZATION: Skip PathMatcher.compile for better performance
         // Determine if static route (optimized check)
         const pathLen = schema.path.length;
@@ -359,9 +437,9 @@ export class UnifiedRouter {
         // OPTIMIZATION: Lazy auth middleware creation (only create when needed, not during registration)
         // This speeds up route registration significantly
         const route = {
-            schema,
+            schema: registered,
             compiledPath: null, // Will be set lazily if needed
-            handler: schema.handler,
+            handler: registered.handler,
             isFastPath,
             executionOrder,
             rateLimitConfig: schema.rateLimit,