@zudojs/http 0.1.0 → 1.1.0

package/dist/httpRouter/core/factory/httpRoute.factory.base.js

@@ -0,0 +1,186 @@
+/**
+ * HTTP route factory base helpers.
+ *
+ * Internal normalization, validation, execution, and response utilities for
+ * route creation and dispatch.
+ */
+import { HttpRouterError } from "../error/httpRouter.error.js";
+import { formatAllowHeader } from "../../../httpMethods/http.methods.js";
+import { matchCompiledRoute } from "../../matching/httpRoute.matcher.core.js";
+import { HttpResponseContext, } from "../../../httpResponse/httpResponse.context.js";
+/* -------------------------------------------------------------------------- */
+/* Method Helpers                                                             */
+/* -------------------------------------------------------------------------- */
+export function normalizeMethod(method) {
+    const normalized = method.toUpperCase();
+    if (normalized === "*") {
+        return "*";
+    }
+    if (!isHttpMethod(normalized)) {
+        throw new HttpRouterError(`Unsupported HTTP method "${method}".`);
+    }
+    return normalized;
+}
+export function normalizeMethods(method) {
+    const methods = typeof method === "string" ? [method] : method;
+    return methods.map(normalizeMethod);
+}
+export function isHttpMethod(value) {
+    return (value === "GET" ||
+        value === "HEAD" ||
+        value === "POST" ||
+        value === "PUT" ||
+        value === "PATCH" ||
+        value === "DELETE" ||
+        value === "OPTIONS" ||
+        value === "CONNECT" ||
+        value === "TRACE");
+}
+export function collectAllowedMethods(routes, path) {
+    const methods = new Set();
+    for (const route of routes) {
+        if (!matchCompiledRoute(route, path, false)) {
+            continue;
+        }
+        if (isHttpMethod(route.definition.method)) {
+            methods.add(route.definition.method);
+        }
+    }
+    if (methods.has("GET") && !methods.has("HEAD")) {
+        methods.add("HEAD");
+    }
+    return [...methods];
+}
+/* -------------------------------------------------------------------------- */
+/* Route Identity                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * Extracts the monotonic registration sequence from a generated route id.
+ *
+ * Route ids are shaped `route:<sequence>`; ids that do not follow that shape
+ * sort last, preserving a stable order.
+ */
+export function extractRouteSequence(id) {
+    const match = /^route:(\d+)$/.exec(id);
+    const sequence = match?.[1];
+    if (sequence === undefined) {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    return Number.parseInt(sequence, 10);
+}
+/**
+ * Builds a placeholder route used when no route matched a request.
+ */
+export function createFallbackRoute(path, method) {
+    const fallback = {
+        id: "route:unmatched",
+        method: isHttpMethod(method.toUpperCase()) ? normalizeMethod(method) : "*",
+        path,
+        name: undefined,
+        params: Object.freeze({}),
+        metadata: Object.freeze({}),
+        handler: () => undefined,
+        middleware: Object.freeze([]),
+    };
+    return Object.freeze(fallback);
+}
+/* -------------------------------------------------------------------------- */
+/* Response Helpers                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * Coerces a handler result into a response context.
+ */
+export async function normalizeResponse(value) {
+    if (value instanceof HttpResponseContext) {
+        return value;
+    }
+    if (typeof Response !== "undefined" && value instanceof Response) {
+        const body = value.body === null
+            ? undefined
+            : new Uint8Array(await value.arrayBuffer());
+        return new HttpResponseContext({
+            status: value.status,
+            statusText: value.statusText,
+            headers: Object.fromEntries(value.headers.entries()),
+            body,
+        });
+    }
+    return new HttpResponseContext({ status: 204 });
+}
+/**
+ * Builds the automatic `OPTIONS` response for a matched path.
+ */
+export function createOptionsResponse(allowedMethods) {
+    return new HttpResponseContext({
+        status: 204,
+        headers: {
+            allow: formatAllowHeader(allowedMethods),
+        },
+    });
+}
+/**
+ * Default handler used when no route matches a request.
+ */
+export function defaultNotFoundHandler(context) {
+    return new HttpResponseContext({
+        status: 404,
+        headers: { "content-type": "application/json; charset=utf-8" },
+        body: {
+            error: "Not Found",
+            method: context.method,
+            path: context.path,
+        },
+    });
+}
+/**
+ * Default handler used when a path matches but the method does not.
+ */
+export function defaultMethodNotAllowedHandler(context, allowedMethods) {
+    return new HttpResponseContext({
+        status: 405,
+        headers: {
+            allow: formatAllowHeader(allowedMethods),
+            "content-type": "application/json; charset=utf-8",
+        },
+        body: {
+            error: "Method Not Allowed",
+            method: context.method,
+            path: context.path,
+            allowed: [...allowedMethods],
+        },
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Route Execution                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Runs a matched route's middleware chain followed by its handler.
+ */
+export async function executeRoute(route, context) {
+    const layers = route.middleware;
+    let invoked = -1;
+    const run = async (index) => {
+        if (index <= invoked) {
+            throw new HttpRouterError("Route middleware called next() more than once.");
+        }
+        invoked = index;
+        const layer = layers[index];
+        if (layer === undefined) {
+            return normalizeResponse(await route.handler(context));
+        }
+        let downstream;
+        const result = await layer(context.middleware, async () => {
+            downstream = await run(index + 1);
+            return downstream;
+        });
+        if (result instanceof HttpResponseContext) {
+            return result;
+        }
+        if (typeof Response !== "undefined" && result instanceof Response) {
+            return normalizeResponse(result);
+        }
+        return downstream ?? context.middleware.response;
+    };
+    return run(0);
+}
+//# sourceMappingURL=httpRoute.factory.base.js.map

package/dist/httpRouter/core/factory/httpRoute.factory.d.ts

@@ -0,0 +1,36 @@
+/**
+ * HTTP router factory functions and type guards.
+ */
+import type { RouteDefinition, RouterOptions } from "../types/httpRouter.type.js";
+import { HttpRouter } from "../register/httpRouter.register.js";
+import { HttpRouterGroup } from "../group/httpRouterGroup.core.js";
+import { RouteConflictError, InvalidRoutePatternError } from "../error/httpRouter.error.js";
+/**
+ * Creates a new HTTP router instance.
+ */
+export declare function createRouter(options?: RouterOptions): HttpRouter;
+/**
+ * Creates a normalized route definition.
+ */
+export declare function createRoute(definition: RouteDefinition): RouteDefinition;
+/**
+ * Builds a route path from a pattern and parameters.
+ */
+export declare function buildRoutePath(pattern: string, params?: Readonly<Record<string, string | number>>): string;
+/**
+ * Type guard for HttpRouter instances.
+ */
+export declare function isHttpRouter(value: unknown): value is HttpRouter;
+/**
+ * Type guard for HttpRouterGroup instances.
+ */
+export declare function isHttpRouterGroup(value: unknown): value is HttpRouterGroup;
+/**
+ * Type guard for RouteConflictError instances.
+ */
+export declare function isRouteConflictError(value: unknown): value is RouteConflictError;
+/**
+ * Type guard for InvalidRoutePatternError instances.
+ */
+export declare function isInvalidRoutePatternError(value: unknown): value is InvalidRoutePatternError;
+//# sourceMappingURL=httpRoute.factory.d.ts.map

package/dist/httpRouter/core/factory/httpRoute.factory.js

@@ -0,0 +1,67 @@
+/**
+ * HTTP router factory functions and type guards.
+ */
+import { HttpRouter } from "../register/httpRouter.register.js";
+import { HttpRouterGroup } from "../group/httpRouterGroup.core.js";
+import { RouteConflictError, InvalidRoutePatternError, } from "../error/httpRouter.error.js";
+import { normalizePath } from "../util/httpRoute.util.js";
+/**
+ * Creates a new HTTP router instance.
+ */
+export function createRouter(options = {}) {
+    return new HttpRouter(options);
+}
+/**
+ * Creates a normalized route definition.
+ */
+export function createRoute(definition) {
+    return {
+        ...definition,
+        path: normalizePath(definition.path),
+        middleware: Object.freeze([...(definition.middleware ?? [])]),
+        metadata: Object.freeze({ ...(definition.metadata ?? {}) }),
+    };
+}
+/**
+ * Builds a route path from a pattern and parameters.
+ */
+export function buildRoutePath(pattern, params = {}) {
+    const normalized = normalizePath(pattern);
+    return normalized
+        .replace(/:([a-zA-Z_][a-zA-Z0-9_-]*)(\?)?/g, (_match, name, optional) => {
+        const value = params[name];
+        if (value === undefined || value === null) {
+            if (optional) {
+                return "";
+            }
+            throw new Error(`Missing route parameter "${name}".`);
+        }
+        return encodeURIComponent(String(value));
+    })
+        .replace(/\/+/g, "/");
+}
+/**
+ * Type guard for HttpRouter instances.
+ */
+export function isHttpRouter(value) {
+    return value instanceof HttpRouter;
+}
+/**
+ * Type guard for HttpRouterGroup instances.
+ */
+export function isHttpRouterGroup(value) {
+    return value instanceof HttpRouterGroup;
+}
+/**
+ * Type guard for RouteConflictError instances.
+ */
+export function isRouteConflictError(value) {
+    return value instanceof RouteConflictError;
+}
+/**
+ * Type guard for InvalidRoutePatternError instances.
+ */
+export function isInvalidRoutePatternError(value) {
+    return value instanceof InvalidRoutePatternError;
+}
+//# sourceMappingURL=httpRoute.factory.js.map

package/dist/httpRouter/core/factory/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @zudojs/http/httpRouter/core/factory
+ *
+ * HTTP route factory utilities.
+ */
+export * from "./httpRoute.factory.js";
+export * from "./httpRoute.factory.base.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/core/factory/index.js

@@ -0,0 +1,8 @@
+/**
+ * @zudojs/http/httpRouter/core/factory
+ *
+ * HTTP route factory utilities.
+ */
+export * from "./httpRoute.factory.js";
+export * from "./httpRoute.factory.base.js";
+//# sourceMappingURL=index.js.map

package/dist/httpRouter/core/group/httpRouterGroup.core.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HTTP router group.
+ *
+ * Registers routes against a parent router under a shared path prefix and a
+ * shared set of default route options.
+ */
+import type { HttpMethod, RouteOptions, RouterHandler } from "../types/httpRouter.type.js";
+import type { HttpRouter } from "../register/httpRouter.register.js";
+export declare class HttpRouterGroup {
+    private readonly router;
+    private readonly prefix;
+    private readonly defaults;
+    constructor(router: HttpRouter, prefix: string, defaults?: RouteOptions);
+    on(method: HttpMethod | "*", path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    get(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    head(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    post(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    put(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    patch(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    delete(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    options(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    all(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    group(prefix: string, configure: (group: HttpRouterGroup) => void, options?: RouteOptions): void;
+    private resolve;
+    private mergeOptions;
+}
+//# sourceMappingURL=httpRouterGroup.core.d.ts.map

package/dist/httpRouter/core/group/httpRouterGroup.core.js

@@ -0,0 +1,68 @@
+/**
+ * HTTP router group.
+ *
+ * Registers routes against a parent router under a shared path prefix and a
+ * shared set of default route options.
+ */
+export class HttpRouterGroup {
+    router;
+    prefix;
+    defaults;
+    constructor(router, prefix, defaults = {}) {
+        this.router = router;
+        this.prefix = prefix;
+        this.defaults = defaults;
+    }
+    on(method, path, handler, options = {}) {
+        return this.router.on(method, this.resolve(path), handler, this.mergeOptions(options));
+    }
+    get(path, handler, options = {}) {
+        return this.on("GET", path, handler, options);
+    }
+    head(path, handler, options = {}) {
+        return this.on("HEAD", path, handler, options);
+    }
+    post(path, handler, options = {}) {
+        return this.on("POST", path, handler, options);
+    }
+    put(path, handler, options = {}) {
+        return this.on("PUT", path, handler, options);
+    }
+    patch(path, handler, options = {}) {
+        return this.on("PATCH", path, handler, options);
+    }
+    delete(path, handler, options = {}) {
+        return this.on("DELETE", path, handler, options);
+    }
+    options(path, handler, options = {}) {
+        return this.on("OPTIONS", path, handler, options);
+    }
+    all(path, handler, options = {}) {
+        return this.on("*", path, handler, options);
+    }
+    group(prefix, configure, options = {}) {
+        this.router.group(this.resolve(prefix), (group) => {
+            configure(group);
+        }, this.mergeOptions(options));
+    }
+    resolve(path) {
+        const left = this.prefix === "/" ? "" : this.prefix.replace(/\/+$/, "");
+        const right = path === "/" ? "" : path.replace(/^\/+/, "");
+        return `${left}/${right}` || "/";
+    }
+    mergeOptions(options) {
+        return {
+            name: options.name ?? this.defaults.name,
+            middleware: [
+                ...(this.defaults.middleware ?? []),
+                ...(options.middleware ?? []),
+            ],
+            metadata: {
+                ...(this.defaults.metadata ?? {}),
+                ...(options.metadata ?? {}),
+            },
+            strictTrailingSlash: options.strictTrailingSlash ?? this.defaults.strictTrailingSlash,
+        };
+    }
+}
+//# sourceMappingURL=httpRouterGroup.core.js.map

package/dist/httpRouter/core/group/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @zudojs/http/httpRouter/core/group
+ *
+ * HTTP router group utilities.
+ */
+export * from "./httpRouterGroup.core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/core/group/index.js

@@ -0,0 +1,7 @@
+/**
+ * @zudojs/http/httpRouter/core/group
+ *
+ * HTTP router group utilities.
+ */
+export * from "./httpRouterGroup.core.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * @zudojs/http/httpRouter/core
+ *
+ * HTTP router core module.
+ */
+export * from "./types/index.js";
+export * from "./factory/index.js";
+export * from "./registry/index.js";
+export * from "./error/index.js";
+export * from "./group/index.js";
+export * from "./register/index.js";
+export * from "./util/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/core/index.js

@@ -0,0 +1,13 @@
+/**
+ * @zudojs/http/httpRouter/core
+ *
+ * HTTP router core module.
+ */
+export * from "./types/index.js";
+export * from "./factory/index.js";
+export * from "./registry/index.js";
+export * from "./error/index.js";
+export * from "./group/index.js";
+export * from "./register/index.js";
+export * from "./util/index.js";
+//# sourceMappingURL=index.js.map

package/dist/httpRouter/core/register/httpRouter.register.d.ts

@@ -0,0 +1,45 @@
+/**
+ * HTTP router registration, matching, and dispatch.
+ */
+import type { HttpMethod, MatchedRoute, CompiledRoute, RouteDefinition, RouteOptions, RouterHandler, RouterMatch, RouterOptions, RouterResult } from "../types/httpRouter.type.js";
+import type { HttpRequestContext as RequestContext } from "../../../httpRequest/httpRequest.context.js";
+import { HttpRouterGroup } from "../group/httpRouterGroup.core.js";
+export declare class HttpRouter {
+    private readonly routes;
+    private readonly routerOptions;
+    private readonly notFoundHandler;
+    private readonly methodNotAllowedHandler;
+    private sequence;
+    constructor(options?: RouterOptions);
+    add(definition: RouteDefinition): () => void;
+    on(method: HttpMethod | "*", path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    get(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    head(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    post(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    put(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    patch(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    delete(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    options(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    connect(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    trace(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    all(path: string, handler: RouterHandler, options?: RouteOptions): () => void;
+    group(prefix: string, configure: (group: HttpRouterGroup) => void, options?: RouteOptions): void;
+    remove(method: HttpMethod | "*", path: string): boolean;
+    clear(): void;
+    count(): number;
+    list(): readonly MatchedRoute[];
+    /**
+     * Returns the registered routes with their compiled segments, most
+     * specific first.
+     */
+    compiled(): readonly CompiledRoute[];
+    find(id: string): MatchedRoute | undefined;
+    match(method: string, path: string): RouterMatch;
+    dispatch(request: RequestContext, options?: {
+        readonly signal?: AbortSignal;
+        readonly state?: Map<string, unknown>;
+    }): Promise<RouterResult>;
+    private register;
+    private sortedRoutes;
+}
+//# sourceMappingURL=httpRouter.register.d.ts.map