@zudojs/http 0.0.6 → 1.0.0

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

@@ -0,0 +1,306 @@
+/**
+ * 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) {
+            response.status_code(result.status);
+            response.headers_obj(result.headers);
+            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

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

@@ -0,0 +1,301 @@
+/**
+ * Zudojs HTTP route stack.
+ *
+ * Maintains the ordered execution layers associated with a route.
+ * Middleware ordering is explicit and deterministic.
+ */
+/* -------------------------------------------------------------------------- */
+/* Route Stack                                                                */
+/* -------------------------------------------------------------------------- */
+export class RouteStack {
+    layers = [];
+    options;
+    sequence = 0;
+    constructor(options = {}) {
+        this.options = {
+            strictNext: options.strictNext ?? true,
+        };
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Registration                                                              */
+    /* ------------------------------------------------------------------------ */
+    use(handler, options = {}) {
+        return this.add("middleware", handler, options);
+    }
+    handler(handler, options = {}) {
+        return this.add("handler", handler, options);
+    }
+    add(type, handler, options = {}) {
+        if (typeof handler !== "function") {
+            throw new TypeError("Route stack layer must be a function.");
+        }
+        this.sequence += 1;
+        const layer = Object.freeze({
+            id: `layer:${this.sequence}`,
+            name: options.name,
+            type,
+            handler,
+            order: this.layers.length,
+            metadata: Object.freeze({
+                ...(options.metadata ?? {}),
+            }),
+        });
+        this.layers.push(layer);
+        return layer;
+    }
+    addMany(layers) {
+        const added = [];
+        for (const layer of layers) {
+            if ("id" in layer) {
+                this.insertLayer(layer);
+                added.push(layer);
+                continue;
+            }
+            added.push(this.add(layer.type, layer.handler, {
+                name: layer.name,
+                metadata: layer.metadata,
+            }));
+        }
+        return Object.freeze(added);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Ordering                                                                  */
+    /* ------------------------------------------------------------------------ */
+    before(target, handler, options = {}) {
+        const index = this.indexOf(target);
+        if (index === -1) {
+            throw new Error(`Route stack layer "${target}" was not found.`);
+        }
+        const layer = this.add("middleware", handler, options);
+        this.move(layer.id, index);
+        return layer;
+    }
+    after(target, handler, options = {}) {
+        const index = this.indexOf(target);
+        if (index === -1) {
+            throw new Error(`Route stack layer "${target}" was not found.`);
+        }
+        const layer = this.add("middleware", handler, options);
+        this.move(layer.id, index + 1);
+        return layer;
+    }
+    move(layerId, targetIndex) {
+        const sourceIndex = this.indexOf(layerId);
+        if (sourceIndex === -1) {
+            return false;
+        }
+        const boundedIndex = Math.max(0, Math.min(targetIndex, this.layers.length - 1));
+        const [layer] = this.layers.splice(sourceIndex, 1);
+        if (layer === undefined) {
+            /* `indexOf` already proved the index is in range, so this cannot fire. */
+            return false;
+        }
+        this.layers.splice(boundedIndex, 0, layer);
+        this.reindex();
+        return true;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Removal                                                                   */
+    /* ------------------------------------------------------------------------ */
+    remove(layerId) {
+        const index = this.indexOf(layerId);
+        if (index === -1) {
+            return false;
+        }
+        this.layers.splice(index, 1);
+        this.reindex();
+        return true;
+    }
+    removeByName(name) {
+        const original = this.layers.length;
+        for (let index = this.layers.length - 1; index >= 0; index -= 1) {
+            if (this.layers[index]?.name === name) {
+                this.layers.splice(index, 1);
+            }
+        }
+        this.reindex();
+        return original - this.layers.length;
+    }
+    clear() {
+        this.layers.length = 0;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Lookup                                                                    */
+    /* ------------------------------------------------------------------------ */
+    get(layerId) {
+        return this.layers.find((layer) => layer.id === layerId);
+    }
+    getByName(name) {
+        return this.layers.find((layer) => layer.name === name);
+    }
+    indexOf(layerId) {
+        return this.layers.findIndex((layer) => layer.id === layerId);
+    }
+    has(layerId) {
+        return this.indexOf(layerId) !== -1;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Inspection                                                                */
+    /* ------------------------------------------------------------------------ */
+    all() {
+        return Object.freeze([...this.layers]);
+    }
+    middleware() {
+        return Object.freeze(this.layers.filter((layer) => layer.type === "middleware"));
+    }
+    getHandler() {
+        for (let index = this.layers.length - 1; index >= 0; index -= 1) {
+            const layer = this.layers[index];
+            if (layer?.type === "handler") {
+                return layer;
+            }
+        }
+        return undefined;
+    }
+    count() {
+        return this.layers.length;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Execution                                                                 */
+    /* ------------------------------------------------------------------------ */
+    async execute(context) {
+        let index = -1;
+        let executed = 0;
+        const dispatch = async (current) => {
+            if (this.options.strictNext && current <= index) {
+                throw new Error("Route stack next() called multiple times.");
+            }
+            index = current;
+            const layer = this.layers[current];
+            if (!layer) {
+                return;
+            }
+            executed += 1;
+            if (layer.type === "handler") {
+                await layer.handler(context.request, context.response);
+                return;
+            }
+            await layer.handler(context.request, context.response, () => dispatch(current + 1));
+        };
+        try {
+            await dispatch(0);
+            return Object.freeze({
+                executed,
+                completed: true,
+                error: undefined,
+            });
+        }
+        catch (error) {
+            return Object.freeze({
+                executed,
+                completed: false,
+                error,
+            });
+        }
+    }
+    async run(request, response, route) {
+        return this.execute({
+            request,
+            response,
+            route,
+        });
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Conversion                                                                */
+    /* ------------------------------------------------------------------------ */
+    static fromRoute(route, options = {}) {
+        const stack = new RouteStack(options);
+        const middleware = normalizeMiddleware(route.middleware);
+        for (const layer of middleware) {
+            stack.use(layer);
+        }
+        stack.handler(route.handler);
+        return stack;
+    }
+    clone() {
+        const clone = new RouteStack(this.options);
+        for (const layer of this.layers) {
+            clone.insertLayer({
+                ...layer,
+                metadata: Object.freeze({
+                    ...layer.metadata,
+                }),
+            });
+        }
+        clone.sequence = this.sequence;
+        return clone;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Serialization                                                             */
+    /* ------------------------------------------------------------------------ */
+    toJSON() {
+        return Object.freeze(this.layers.map((layer) => ({
+            id: layer.id,
+            name: layer.name,
+            type: layer.type,
+            order: layer.order,
+            metadata: layer.metadata,
+        })));
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Internals                                                                 */
+    /* ------------------------------------------------------------------------ */
+    insertLayer(layer) {
+        this.layers.push(layer);
+        this.sequence = Math.max(this.sequence, extractSequence(layer.id));
+        this.reindex();
+    }
+    reindex() {
+        for (const [index, layer] of this.layers.entries()) {
+            this.layers[index] = Object.freeze({
+                ...layer,
+                order: index,
+            });
+        }
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factories                                                                  */
+/* -------------------------------------------------------------------------- */
+export function createRouteStack(options = {}) {
+    return new RouteStack(options);
+}
+export function createRouteStackFromRoute(route, options = {}) {
+    return RouteStack.fromRoute(route, options);
+}
+/* -------------------------------------------------------------------------- */
+/* Middleware Helpers                                                         */
+/* -------------------------------------------------------------------------- */
+export function composeRouteStack(layers, options = {}) {
+    const stack = new RouteStack(options);
+    for (const layer of layers) {
+        stack.use(layer);
+    }
+    return stack;
+}
+function normalizeMiddleware(middleware) {
+    if (!middleware) {
+        return [];
+    }
+    if (Array.isArray(middleware)) {
+        return middleware;
+    }
+    return [middleware];
+}
+/* -------------------------------------------------------------------------- */
+/* Utilities                                                                  */
+/* -------------------------------------------------------------------------- */
+function extractSequence(id) {
+    const match = id.match(/:(\d+)$/);
+    return match ? Number(match[1]) : 0;
+}
+export function isRouteStack(value) {
+    return value instanceof RouteStack;
+}
+export function isRouteStackLayer(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    return ("id" in value && "type" in value && "handler" in value && "order" in value);
+}
+//# sourceMappingURL=httpRoute.stack.js.map