@zudojs/http 0.1.0 → 1.1.0

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

package/dist/httpRouter/dispatch/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * HTTP route dispatching.
+ */
+export { RouteDispatcher, dispatchRoute } from "./httpRoute.dispatcher.js";
+export { RouteStack, composeRouteStack } from "./httpRoute.stack.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/dispatch/index.js

@@ -0,0 +1,6 @@
+/**
+ * HTTP route dispatching.
+ */
+export { RouteDispatcher, dispatchRoute } from "./httpRoute.dispatcher.js";
+export { RouteStack, composeRouteStack } from "./httpRoute.stack.js";
+//# sourceMappingURL=index.js.map

package/dist/httpRouter/httpRouter.context.d.ts

@@ -0,0 +1,67 @@
+import type { HttpRequestContext as RequestContext } from "../httpRequest/httpRequest.context.js";
+import { type HttpResponseContext as ResponseContext } from "../httpResponse/httpResponse.context.js";
+import type { MatchedRoute, HttpRouterContext } from "./core/types/httpRouter.type.js";
+export type RouterContextState = Map<string, unknown>;
+export interface RouterContextInit {
+    readonly request: RequestContext;
+    readonly route: MatchedRoute;
+    readonly params?: Readonly<Record<string, string>>;
+    readonly query?: Readonly<Record<string, string | string[]>>;
+    readonly state?: RouterContextState;
+    readonly signal?: AbortSignal;
+}
+export interface RouterContextOptions {
+    readonly state?: RouterContextState;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Runtime context passed through the Zudojs HTTP router.
+ *
+ * The context is intentionally small and request-scoped.
+ * It provides handlers with access to the request, route parameters,
+ * query values, shared state, and cancellation signal.
+ */
+export declare class RouterContext implements HttpRouterContext {
+    readonly request: RequestContext;
+    readonly params: Readonly<Record<string, string>>;
+    readonly query: Readonly<Record<string, string | string[]>>;
+    readonly route: MatchedRoute;
+    readonly state: RouterContextState;
+    readonly middleware: HttpRouterContext["middleware"];
+    readonly signal: AbortSignal;
+    constructor(init: RouterContextInit);
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): this;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    method(): string;
+    url(): string;
+    path(): string;
+    routeName(): string | undefined;
+    routeId(): string;
+    metadata<T = unknown>(key: string): T | undefined;
+    param(name: string): string | undefined;
+    requiredParam(name: string): string;
+    allParams(): Readonly<Record<string, string>>;
+    queryParam(name: string): string | string[] | undefined;
+    queryString(name: string): string | undefined;
+    queryArray(name: string): readonly string[];
+    allQuery(): Readonly<Record<string, string | string[]>>;
+    aborted(): boolean;
+    throwIfAborted(): void;
+    toJSON(): Record<string, unknown>;
+}
+export declare function createRouterContext(init: RouterContextInit): RouterContext;
+export declare function isRouterContext(value: unknown): value is RouterContext;
+export declare function toRouterContext(context: HttpRouterContext): RouterContext;
+export declare function cloneRouterContext(context: HttpRouterContext, options?: RouterContextOptions): RouterContext;
+/**
+ * Builds the middleware context handed to route middleware.
+ *
+ * The middleware state is backed by the router context's own state map so
+ * middleware and handlers observe the same values.
+ */
+export declare function createRouterMiddlewareContext(request: RequestContext, signal: AbortSignal, state?: RouterContextState, metadata?: Readonly<Record<string, unknown>>): HttpRouterContext["middleware"];
+export declare function isResponseContext(value: unknown): value is ResponseContext;
+//# sourceMappingURL=httpRouter.context.d.ts.map

package/dist/httpRouter/httpRouter.context.js

@@ -0,0 +1,239 @@
+import { HttpResponseContext, } from "../httpResponse/httpResponse.context.js";
+import { RouterMiddlewareState } from "./httpRouter.state.js";
+/* -------------------------------------------------------------------------- */
+/* Router Context                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * Runtime context passed through the Zudojs HTTP router.
+ *
+ * The context is intentionally small and request-scoped.
+ * It provides handlers with access to the request, route parameters,
+ * query values, shared state, and cancellation signal.
+ */
+export class RouterContext {
+    request;
+    params;
+    query;
+    route;
+    state;
+    middleware;
+    signal;
+    constructor(init) {
+        this.request = init.request;
+        this.params = Object.freeze({
+            ...(init.params ?? {}),
+        });
+        this.query = Object.freeze({
+            ...(init.query ?? {}),
+        });
+        this.route = init.route;
+        this.state = init.state ?? new Map();
+        this.signal =
+            init.signal ??
+                getRequestSignal(init.request) ??
+                new AbortController().signal;
+        this.middleware = createRouterMiddlewareContext(this.request, this.signal, this.state, this.route.metadata);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* State                                                                     */
+    /* ------------------------------------------------------------------------ */
+    get(key) {
+        return this.state.get(key);
+    }
+    set(key, value) {
+        this.state.set(key, value);
+        return this;
+    }
+    has(key) {
+        return this.state.has(key);
+    }
+    delete(key) {
+        return this.state.delete(key);
+    }
+    clear() {
+        this.state.clear();
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Request Information                                                       */
+    /* ------------------------------------------------------------------------ */
+    method() {
+        return getRequestMethod(this.request);
+    }
+    url() {
+        return getRequestUrl(this.request);
+    }
+    path() {
+        return this.route.path;
+    }
+    routeName() {
+        return this.route.name;
+    }
+    routeId() {
+        return this.route.id;
+    }
+    metadata(key) {
+        return this.route.metadata[key];
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Parameters                                                                */
+    /* ------------------------------------------------------------------------ */
+    param(name) {
+        return this.params[name];
+    }
+    requiredParam(name) {
+        const value = this.param(name);
+        if (value === undefined) {
+            throw new Error(`Missing required route parameter "${name}".`);
+        }
+        return value;
+    }
+    allParams() {
+        return this.params;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Query                                                                     */
+    /* ------------------------------------------------------------------------ */
+    queryParam(name) {
+        return this.query[name];
+    }
+    queryString(name) {
+        const value = this.queryParam(name);
+        if (Array.isArray(value)) {
+            return value[0];
+        }
+        return value;
+    }
+    queryArray(name) {
+        const value = this.queryParam(name);
+        if (value === undefined) {
+            return [];
+        }
+        return Array.isArray(value) ? value : [value];
+    }
+    allQuery() {
+        return this.query;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Cancellation                                                              */
+    /* ------------------------------------------------------------------------ */
+    aborted() {
+        return this.signal.aborted;
+    }
+    throwIfAborted() {
+        if (this.signal.aborted) {
+            throw createAbortError(this.signal.reason);
+        }
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Conversion                                                                */
+    /* ------------------------------------------------------------------------ */
+    toJSON() {
+        return {
+            method: this.method(),
+            url: this.url(),
+            path: this.path(),
+            route: this.routeName(),
+            params: {
+                ...this.params,
+            },
+            query: {
+                ...this.query,
+            },
+        };
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+export function createRouterContext(init) {
+    return new RouterContext(init);
+}
+/* -------------------------------------------------------------------------- */
+/* Context Conversion                                                         */
+/* -------------------------------------------------------------------------- */
+export function isRouterContext(value) {
+    return value instanceof RouterContext;
+}
+export function toRouterContext(context) {
+    if (context instanceof RouterContext) {
+        return context;
+    }
+    return new RouterContext({
+        request: context.request,
+        route: context.route,
+        params: context.params,
+        query: context.query,
+        state: context.state,
+        signal: context.signal,
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Context Cloning                                                            */
+/* -------------------------------------------------------------------------- */
+export function cloneRouterContext(context, options = {}) {
+    const source = toRouterContext(context);
+    return new RouterContext({
+        request: source.request,
+        route: source.route,
+        params: source.params,
+        query: source.query,
+        state: options.state ?? new Map(source.state),
+        signal: options.signal ?? source.signal,
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Middleware Context                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Builds the middleware context handed to route middleware.
+ *
+ * The middleware state is backed by the router context's own state map so
+ * middleware and handlers observe the same values.
+ */
+export function createRouterMiddlewareContext(request, signal, state = new Map(), metadata = {}) {
+    return {
+        request,
+        response: new HttpResponseContext(),
+        state: new RouterMiddlewareState(state),
+        signal,
+        metadata,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Request Helpers                                                            */
+/* -------------------------------------------------------------------------- */
+function getRequestMethod(request) {
+    const value = request.method;
+    return (value ?? "GET").toUpperCase();
+}
+function getRequestUrl(request) {
+    const value = request.url;
+    if (value instanceof URL) {
+        return value.toString();
+    }
+    return value ?? "/";
+}
+function getRequestSignal(request) {
+    return request.signal;
+}
+/* -------------------------------------------------------------------------- */
+/* Abort Helpers                                                              */
+/* -------------------------------------------------------------------------- */
+function createAbortError(reason) {
+    if (reason instanceof Error) {
+        return reason;
+    }
+    if (typeof DOMException !== "undefined") {
+        return new DOMException(reason ? String(reason) : "The operation was aborted.", "AbortError");
+    }
+    const error = new Error(reason ? String(reason) : "The operation was aborted.");
+    error.name = "AbortError";
+    return error;
+}
+/* -------------------------------------------------------------------------- */
+/* Response Helpers                                                           */
+/* -------------------------------------------------------------------------- */
+export function isResponseContext(value) {
+    return value instanceof HttpResponseContext;
+}
+//# sourceMappingURL=httpRouter.context.js.map

package/dist/httpRouter/httpRouter.state.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Router-backed middleware state.
+ *
+ * Adapts the router context's state map to the `HttpMiddlewareState`
+ * interface so middleware and route handlers share a single store.
+ */
+import type { HttpMiddlewareState } from "../httpMiddleware/httpMiddleware.type.js";
+export declare class RouterMiddlewareState implements HttpMiddlewareState {
+    private readonly store;
+    constructor(store?: Map<string, unknown>);
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    entries(): IterableIterator<readonly [string, unknown]>;
+}
+//# sourceMappingURL=httpRouter.state.d.ts.map

package/dist/httpRouter/httpRouter.state.js

@@ -0,0 +1,31 @@
+/**
+ * Router-backed middleware state.
+ *
+ * Adapts the router context's state map to the `HttpMiddlewareState`
+ * interface so middleware and route handlers share a single store.
+ */
+export class RouterMiddlewareState {
+    store;
+    constructor(store = new Map()) {
+        this.store = store;
+    }
+    get(key) {
+        return this.store.get(key);
+    }
+    set(key, value) {
+        this.store.set(key, value);
+    }
+    has(key) {
+        return this.store.has(key);
+    }
+    delete(key) {
+        return this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+    entries() {
+        return this.store.entries();
+    }
+}
+//# sourceMappingURL=httpRouter.state.js.map

package/dist/httpRouter/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @zudojs/http/httpRouter
+ *
+ * HTTP routing system including patterns, matching, and dispatching.
+ */
+export * from "./core/index.js";
+export * from "./pattern/index.js";
+export * from "./matching/index.js";
+export * from "./tree/index.js";
+export * from "./dispatch/index.js";
+export * from "./result/index.js";
+export * from "./httpRouter.context.js";
+//# sourceMappingURL=index.d.ts.map