@zudojs/http 0.1.0 → 1.1.0

package/dist/httpRouter/dispatch/httpRoute.dispatcher.js

@@ -0,0 +1,317 @@
+/**
+ * Zudojs HTTP route dispatcher.
+ *
+ * Responsible for taking a matched route and executing its middleware and
+ * handler pipeline. Route registration and route matching remain separate
+ * concerns.
+ */
+import { HttpResponseContext } from "../../httpResponse/httpResponse.context.js";
+import { createRouterContext } from "../httpRouter.context.js";
+import { RouterMiddlewareState } from "../httpRouter.state.js";
+import { getRequestSignal } from "../core/util/httpRoute.util.js";
+/* -------------------------------------------------------------------------- */
+/* Route Dispatcher                                                           */
+/* -------------------------------------------------------------------------- */
+export class RouteDispatcher {
+    matcher;
+    options;
+    dispatchCount = 0;
+    handledCount = 0;
+    unmatchedCount = 0;
+    errorCount = 0;
+    constructor(matcher, options = {}) {
+        this.matcher = matcher;
+        this.options = options;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Dispatch                                                                  */
+    /* ------------------------------------------------------------------------ */
+    async dispatch(request, response) {
+        this.dispatchCount += 1;
+        const match = this.matcher.match({
+            method: getRequestMethod(request),
+            path: getRequestPath(request),
+        });
+        if (!match) {
+            this.unmatchedCount += 1;
+            return Object.freeze({
+                matched: false,
+                handled: false,
+                route: undefined,
+                error: undefined,
+                context: undefined,
+            });
+        }
+        const context = createDispatchContext(request, response, match);
+        try {
+            await this.execute(context);
+            this.handledCount += 1;
+            await this.options.onComplete?.(context);
+            return Object.freeze({
+                matched: true,
+                handled: true,
+                route: match.route,
+                error: undefined,
+                context,
+            });
+        }
+        catch (error) {
+            this.errorCount += 1;
+            if (this.options.onError) {
+                await this.options.onError(error, context);
+            }
+            return Object.freeze({
+                matched: true,
+                handled: false,
+                route: match.route,
+                error,
+                context,
+            });
+        }
+    }
+    async dispatchMatch(match, request, response) {
+        this.dispatchCount += 1;
+        const context = createDispatchContext(request, response, match);
+        try {
+            await this.execute(context);
+            this.handledCount += 1;
+            await this.options.onComplete?.(context);
+            return Object.freeze({
+                matched: true,
+                handled: true,
+                route: match.route,
+                error: undefined,
+                context,
+            });
+        }
+        catch (error) {
+            this.errorCount += 1;
+            if (this.options.onError) {
+                await this.options.onError(error, context);
+            }
+            return Object.freeze({
+                matched: true,
+                handled: false,
+                route: match.route,
+                error,
+                context,
+            });
+        }
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Execution                                                                 */
+    /* ------------------------------------------------------------------------ */
+    async execute(context) {
+        const state = new RouterMiddlewareState();
+        const middleware = context.route.middleware.map((layer) => toRouteMiddleware(layer, context.route, state));
+        const handler = toDispatchHandler(context.route.handler, context);
+        let index = -1;
+        const dispatchNext = async (current) => {
+            if (current <= index) {
+                throw new Error("Route middleware called next() more than once.");
+            }
+            index = current;
+            const layer = middleware[current];
+            if (layer !== undefined) {
+                await layer(context.request, context.response, () => dispatchNext(current + 1));
+                return;
+            }
+            await handler(context.request, context.response);
+        };
+        await dispatchNext(0);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Handler Execution                                                         */
+    /* ------------------------------------------------------------------------ */
+    async executeHandler(handler, context) {
+        const normalized = normalizeHandler(handler);
+        await normalized(context.request, context.response);
+    }
+    async executeMiddleware(middleware, context) {
+        const layers = normalizeMiddleware(middleware);
+        let index = -1;
+        const next = async (current) => {
+            if (current <= index) {
+                throw new Error("Route middleware called next() more than once.");
+            }
+            index = current;
+            const layer = layers[current];
+            if (layer === undefined) {
+                return;
+            }
+            await layer(context.request, context.response, () => next(current + 1));
+        };
+        await next(0);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Introspection                                                             */
+    /* ------------------------------------------------------------------------ */
+    stats() {
+        return Object.freeze({
+            dispatches: this.dispatchCount,
+            handled: this.handledCount,
+            unmatched: this.unmatchedCount,
+            errors: this.errorCount,
+        });
+    }
+    resetStats() {
+        this.dispatchCount = 0;
+        this.handledCount = 0;
+        this.unmatchedCount = 0;
+        this.errorCount = 0;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+export function createRouteDispatcher(matcher, options = {}) {
+    return new RouteDispatcher(matcher, options);
+}
+/* -------------------------------------------------------------------------- */
+/* Standalone Dispatch                                                        */
+/* -------------------------------------------------------------------------- */
+export async function dispatchRoute(dispatcher, request, response) {
+    return dispatcher.dispatch(request, response);
+}
+/* -------------------------------------------------------------------------- */
+/* Context Creation                                                           */
+/* -------------------------------------------------------------------------- */
+function createDispatchContext(request, response, match) {
+    return Object.freeze({
+        request,
+        response,
+        route: match.route,
+        params: Object.freeze({
+            ...match.params,
+        }),
+        method: match.method,
+        path: match.path,
+        match,
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Request Access                                                             */
+/* -------------------------------------------------------------------------- */
+function getRequestMethod(request) {
+    const candidate = request;
+    return candidate.method ?? candidate.request?.method ?? "GET";
+}
+function getRequestPath(request) {
+    const candidate = request;
+    return (candidate.path ??
+        candidate.url ??
+        candidate.request?.path ??
+        candidate.request?.url ??
+        "/");
+}
+/* -------------------------------------------------------------------------- */
+/* Handler Normalization                                                      */
+/* -------------------------------------------------------------------------- */
+function normalizeHandler(handler) {
+    if (typeof handler !== "function") {
+        throw new TypeError("Route handler must be a function.");
+    }
+    return handler;
+}
+/**
+ * Adapts a router handler, which receives a router context, to the
+ * dispatcher's (request, response) calling convention.
+ *
+ * A response context returned by the handler is merged into the dispatch
+ * response so the dispatcher's response object stays authoritative.
+ */
+function toDispatchHandler(handler, context) {
+    return async (request, response) => {
+        const result = await handler(createRouterContext({
+            request,
+            route: context.route,
+            params: context.params,
+            signal: getRequestSignal(request),
+        }));
+        if (result instanceof HttpResponseContext && result !== response) {
+            /*
+             * Everything the handler put on its response must survive the merge.
+             * Copying only status, headers and body dropped every cookie the
+             * handler set, its custom status text and its metadata.
+             */
+            response.setStatus(result.status, result.statusText);
+            response.headers_obj(result.headers);
+            for (const cookie of result.cookies) {
+                response.setCookie(cookie);
+            }
+            for (const [key, value] of Object.entries(result.metadata)) {
+                response.setMetadata(key, value);
+            }
+            response.setBody(result.body);
+        }
+    };
+}
+/**
+ * Adapts an `HttpMiddleware`, which receives a middleware context, to the
+ * dispatcher's (request, response, next) calling convention.
+ */
+function toRouteMiddleware(middleware, route, state) {
+    return async (request, response, next) => {
+        await middleware({
+            request,
+            response,
+            state,
+            signal: getRequestSignal(request) ?? new AbortController().signal,
+            metadata: route.metadata,
+        }, async () => {
+            await next();
+            return response;
+        });
+    };
+}
+function normalizeMiddleware(middleware) {
+    if (!middleware) {
+        return [];
+    }
+    const layers = Array.isArray(middleware) ? middleware : [middleware];
+    for (const layer of layers) {
+        if (typeof layer !== "function") {
+            throw new TypeError("Route middleware must be functions.");
+        }
+    }
+    return layers;
+}
+/* -------------------------------------------------------------------------- */
+/* Utilities                                                                  */
+/* -------------------------------------------------------------------------- */
+export function composeRouteMiddleware(middleware) {
+    const layers = normalizeMiddleware(middleware);
+    return async (request, response, next) => {
+        let index = -1;
+        const dispatch = async (current) => {
+            if (current <= index) {
+                throw new Error("Composed middleware called next() more than once.");
+            }
+            index = current;
+            const layer = layers[current];
+            if (layer === undefined) {
+                await next();
+                return;
+            }
+            await layer(request, response, () => dispatch(current + 1));
+        };
+        await dispatch(0);
+    };
+}
+export function createRouteHandler(handler) {
+    return async (context) => {
+        const response = new HttpResponseContext();
+        await handler(context.request, response);
+        return response;
+    };
+}
+export function isRouteDispatcher(value) {
+    return value instanceof RouteDispatcher;
+}
+export function isRouteDispatchResult(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    return "matched" in value && "handled" in value;
+}
+//# sourceMappingURL=httpRoute.dispatcher.js.map

package/dist/httpRouter/dispatch/httpRoute.stack.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Zudojs HTTP route stack.
+ *
+ * Maintains the ordered execution layers associated with a route.
+ * Middleware ordering is explicit and deterministic.
+ */
+import type { MatchedRoute, RouterHandler } from "../core/types/httpRouter.type.js";
+import type { HttpRequestContext as RequestContext } from "../../httpRequest/httpRequest.context.js";
+import type { HttpResponseContext as ResponseContext } from "../../httpResponse/httpResponse.context.js";
+export type RouteStackNext = () => void | Promise<void>;
+export type RouteStackHandler = (request: RequestContext, response: ResponseContext, next?: RouteStackNext) => void | Promise<void>;
+export type RouteStackLayerType = "middleware" | "handler";
+export interface RouteStackLayer {
+    readonly id: string;
+    readonly name: string | undefined;
+    readonly type: RouteStackLayerType;
+    readonly handler: RouteStackHandler;
+    readonly order: number;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface RouteStackOptions {
+    readonly strictNext?: boolean;
+}
+export interface RouteStackExecutionContext {
+    readonly request: RequestContext;
+    readonly response: ResponseContext;
+    readonly route: MatchedRoute | undefined;
+}
+export interface RouteStackExecutionResult {
+    readonly executed: number;
+    readonly completed: boolean;
+    readonly error: unknown | undefined;
+}
+export declare class RouteStack {
+    private readonly layers;
+    private readonly options;
+    private sequence;
+    constructor(options?: RouteStackOptions);
+    use(handler: RouteStackHandler, options?: {
+        readonly name?: string;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }): RouteStackLayer;
+    handler(handler: RouteStackHandler | RouterHandler, options?: {
+        readonly name?: string;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }): RouteStackLayer;
+    add(type: RouteStackLayerType, handler: RouteStackHandler, options?: {
+        readonly name?: string;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }): RouteStackLayer;
+    addMany(layers: readonly (RouteStackLayer | {
+        readonly type: RouteStackLayerType;
+        readonly handler: RouteStackHandler;
+        readonly name?: string;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    })[]): readonly RouteStackLayer[];
+    before(target: string, handler: RouteStackHandler, options?: {
+        readonly name?: string;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }): RouteStackLayer;
+    after(target: string, handler: RouteStackHandler, options?: {
+        readonly name?: string;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }): RouteStackLayer;
+    move(layerId: string, targetIndex: number): boolean;
+    remove(layerId: string): boolean;
+    removeByName(name: string): number;
+    clear(): void;
+    get(layerId: string): RouteStackLayer | undefined;
+    getByName(name: string): RouteStackLayer | undefined;
+    indexOf(layerId: string): number;
+    has(layerId: string): boolean;
+    all(): readonly RouteStackLayer[];
+    middleware(): readonly RouteStackLayer[];
+    getHandler(): RouteStackLayer | undefined;
+    count(): number;
+    execute(context: RouteStackExecutionContext): Promise<RouteStackExecutionResult>;
+    run(request: RequestContext, response: ResponseContext, route?: MatchedRoute): Promise<RouteStackExecutionResult>;
+    static fromRoute(route: MatchedRoute, options?: RouteStackOptions): RouteStack;
+    clone(): RouteStack;
+    toJSON(): readonly Record<string, unknown>[];
+    private insertLayer;
+    private reindex;
+}
+export declare function createRouteStack(options?: RouteStackOptions): RouteStack;
+export declare function createRouteStackFromRoute(route: MatchedRoute, options?: RouteStackOptions): RouteStack;
+export declare function composeRouteStack(layers: readonly RouteStackHandler[], options?: RouteStackOptions): RouteStack;
+export declare function isRouteStack(value: unknown): value is RouteStack;
+export declare function isRouteStackLayer(value: unknown): value is RouteStackLayer;
+//# sourceMappingURL=httpRoute.stack.d.ts.map