@zudojs/http 0.1.0 → 1.1.0

package/dist/httpRouter/index.js

@@ -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.js.map

package/dist/httpRouter/matching/httpRoute.matcher.core.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compiled-route matching.
+ *
+ * Matches a request path against a route's compiled segments, honouring
+ * case sensitivity, optional parameters, per-parameter regular expression
+ * constraints, and trailing wildcards.
+ */
+import type { CompiledRoute } from "../core/types/httpRouter.type.js";
+export declare function matchCompiledRoute(route: CompiledRoute, path: string, caseSensitive: boolean): Readonly<Record<string, string>> | undefined;
+//# sourceMappingURL=httpRoute.matcher.core.d.ts.map

package/dist/httpRouter/matching/httpRoute.matcher.core.js

@@ -0,0 +1,72 @@
+/**
+ * Compiled-route matching.
+ *
+ * Matches a request path against a route's compiled segments, honouring
+ * case sensitivity, optional parameters, per-parameter regular expression
+ * constraints, and trailing wildcards.
+ */
+import { decodeRouteSegment, normalizePath, splitPath, } from "../core/util/httpRoute.util.js";
+export function matchCompiledRoute(route, path, caseSensitive) {
+    const routePath = normalizePath(path);
+    const inputSegments = splitPath(routePath);
+    const output = {};
+    const routeSegments = route.segments;
+    let inputIndex = 0;
+    for (const segment of routeSegments) {
+        if (segment.type === "wildcard") {
+            /*
+             * Decode each segment separately and re-join. Decoding the joined tail
+             * in one go would turn an encoded `%2f` into a real separator and let a
+             * `%2e%2e` segment become `..`, so the tail a handler receives could
+             * escape the prefix the wildcard was anchored to.
+             */
+            const decodedTail = [];
+            for (const raw of inputSegments.slice(inputIndex)) {
+                const decoded = decodeRouteSegment(raw);
+                if (decoded === undefined) {
+                    return undefined;
+                }
+                decodedTail.push(decoded);
+            }
+            output[segment.name] = decodedTail.join("/");
+            inputIndex = inputSegments.length;
+            break;
+        }
+        const input = inputSegments[inputIndex];
+        if (input === undefined &&
+            segment.type === "parameter" &&
+            segment.optional) {
+            continue;
+        }
+        if (input === undefined) {
+            return undefined;
+        }
+        if (segment.type === "literal") {
+            const expected = caseSensitive
+                ? segment.value
+                : segment.value.toLowerCase();
+            const actual = caseSensitive ? input : input.toLowerCase();
+            if (expected !== actual) {
+                return undefined;
+            }
+            inputIndex += 1;
+            continue;
+        }
+        if (segment.type === "parameter") {
+            const decoded = decodeRouteSegment(input);
+            if (decoded === undefined) {
+                return undefined;
+            }
+            if (segment.pattern && !segment.pattern.test(decoded)) {
+                return undefined;
+            }
+            output[segment.name] = decoded;
+            inputIndex += 1;
+        }
+    }
+    if (inputIndex !== inputSegments.length) {
+        return undefined;
+    }
+    return Object.freeze(output);
+}
+//# sourceMappingURL=httpRoute.matcher.core.js.map

package/dist/httpRouter/matching/httpRoute.matcher.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Zudojs HTTP route matcher.
+ *
+ * Selects and matches registered routes against an incoming HTTP method and
+ * pathname. Route registration lives in the router core; per-route segment
+ * matching lives in `httpRoute.matcher.core.ts`.
+ */
+import type { HttpMethod, MatchedRoute } from "../core/types/httpRouter.type.js";
+import type { HttpRouter } from "../core/register/httpRouter.register.js";
+export interface RouteMatcherOptions {
+    readonly caseSensitive?: boolean;
+    readonly allowHeadFallback?: boolean;
+    readonly allowOptionsFallback?: boolean;
+}
+export interface RouteMatchRequest {
+    readonly method: string;
+    readonly path: string;
+}
+export interface RouteMatcherResult {
+    readonly route: MatchedRoute;
+    readonly params: Readonly<Record<string, string>>;
+    readonly method: HttpMethod | "*";
+    readonly path: string;
+    readonly score: number;
+    readonly matchedBy: "exact" | "head-fallback" | "options-fallback" | "wildcard";
+}
+export interface RouteMethodResult {
+    readonly allowed: boolean;
+    readonly methods: readonly (HttpMethod | "*")[];
+    readonly allowHeader: string;
+}
+export interface RouteMatcherStats {
+    readonly routes: number;
+    readonly requests: number;
+    readonly matches: number;
+    readonly misses: number;
+}
+export declare class RouteMatcher {
+    private readonly router;
+    private readonly matcherOptions;
+    private requests;
+    private matches;
+    private misses;
+    constructor(router: HttpRouter, options?: RouteMatcherOptions);
+    match(request: RouteMatchRequest): RouteMatcherResult | undefined;
+    matchMethod(method: string | HttpMethod | "*", path: string): RouteMatcherResult | undefined;
+    matchAll(request: RouteMatchRequest): readonly RouteMatcherResult[];
+    matchPath(path: string): readonly RouteMatcherResult[];
+    allowedMethods(path: string): RouteMethodResult;
+    isAllowed(method: string, path: string): boolean;
+    stats(): RouteMatcherStats;
+    resetStats(): void;
+    private collect;
+    private matchFirstAllowed;
+}
+export declare function createRouteMatcher(router: HttpRouter, options?: RouteMatcherOptions): RouteMatcher;
+export declare function matchRoute(matcher: RouteMatcher, method: string, path: string): RouteMatcherResult | undefined;
+export declare function matchRoutePath(matcher: RouteMatcher, path: string): readonly RouteMatcherResult[];
+export declare function getAllowedMethods(matcher: RouteMatcher, path: string): RouteMethodResult;
+export declare function normalizeRequestPath(path: string): string;
+export declare function isRouteMatcher(value: unknown): value is RouteMatcher;
+export declare function isRouteMatcherResult(value: unknown): value is RouteMatcherResult;
+//# sourceMappingURL=httpRoute.matcher.d.ts.map

package/dist/httpRouter/matching/httpRoute.matcher.js

@@ -0,0 +1,274 @@
+/**
+ * Zudojs HTTP route matcher.
+ *
+ * Selects and matches registered routes against an incoming HTTP method and
+ * pathname. Route registration lives in the router core; per-route segment
+ * matching lives in `httpRoute.matcher.core.ts`.
+ */
+import { normalizeMethod } from "../core/factory/httpRoute.factory.base.js";
+import { formatAllowHeader } from "../../httpMethods/http.methods.js";
+import { matchCompiledRoute } from "./httpRoute.matcher.core.js";
+/* -------------------------------------------------------------------------- */
+/* Route Matcher                                                              */
+/* -------------------------------------------------------------------------- */
+export class RouteMatcher {
+    router;
+    matcherOptions;
+    requests = 0;
+    matches = 0;
+    misses = 0;
+    constructor(router, options = {}) {
+        this.router = router;
+        this.matcherOptions = {
+            caseSensitive: options.caseSensitive ?? false,
+            allowHeadFallback: options.allowHeadFallback ?? true,
+            allowOptionsFallback: options.allowOptionsFallback ?? true,
+        };
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Primary Matching                                                         */
+    /* ------------------------------------------------------------------------ */
+    match(request) {
+        this.requests += 1;
+        const method = normalizeMethod(request.method);
+        const path = normalizeRequestPath(request.path);
+        const direct = this.matchMethod(method, path);
+        if (direct) {
+            this.matches += 1;
+            return direct;
+        }
+        if (method === "HEAD" && this.matcherOptions.allowHeadFallback) {
+            const fallback = this.matchMethod("GET", path);
+            if (fallback) {
+                this.matches += 1;
+                return {
+                    ...fallback,
+                    matchedBy: "head-fallback",
+                };
+            }
+        }
+        if (method === "OPTIONS" && this.matcherOptions.allowOptionsFallback) {
+            const first = this.matchFirstAllowed(this.allowedMethods(path).methods, path);
+            if (first) {
+                this.matches += 1;
+                return {
+                    ...first,
+                    matchedBy: "options-fallback",
+                };
+            }
+        }
+        this.misses += 1;
+        return undefined;
+    }
+    matchMethod(method, path) {
+        const normalizedMethod = normalizeMethod(method);
+        const normalizedPath = normalizeRequestPath(path);
+        for (const route of this.router.compiled()) {
+            if (!methodApplies(route.definition.method, normalizedMethod)) {
+                continue;
+            }
+            const params = matchCompiledRoute(route, normalizedPath, this.matcherOptions.caseSensitive);
+            if (!params) {
+                continue;
+            }
+            return createResult(route, params, normalizedMethod, normalizedPath);
+        }
+        return undefined;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* All Matches                                                              */
+    /* ------------------------------------------------------------------------ */
+    matchAll(request) {
+        const method = normalizeMethod(request.method);
+        const path = normalizeRequestPath(request.path);
+        return this.collect(method, path);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Path Matching                                                            */
+    /* ------------------------------------------------------------------------ */
+    matchPath(path) {
+        return this.collect("*", normalizeRequestPath(path));
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Allowed Methods                                                          */
+    /* ------------------------------------------------------------------------ */
+    allowedMethods(path) {
+        const normalizedPath = normalizeRequestPath(path);
+        const methods = new Set();
+        for (const route of this.router.compiled()) {
+            const params = matchCompiledRoute(route, normalizedPath, this.matcherOptions.caseSensitive);
+            if (params) {
+                methods.add(route.definition.method);
+            }
+        }
+        const ordered = orderMethods(methods);
+        return Object.freeze({
+            allowed: ordered.length > 0,
+            methods: Object.freeze(ordered),
+            allowHeader: formatAllowHeader(ordered),
+        });
+    }
+    isAllowed(method, path) {
+        const normalizedMethod = normalizeMethod(method);
+        const allowed = this.allowedMethods(path);
+        if (allowed.methods.includes("*")) {
+            return true;
+        }
+        if (allowed.methods.includes(normalizedMethod)) {
+            return true;
+        }
+        return normalizedMethod === "HEAD" && allowed.methods.includes("GET");
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Statistics                                                               */
+    /* ------------------------------------------------------------------------ */
+    stats() {
+        return Object.freeze({
+            routes: this.router.count(),
+            requests: this.requests,
+            matches: this.matches,
+            misses: this.misses,
+        });
+    }
+    resetStats() {
+        this.requests = 0;
+        this.matches = 0;
+        this.misses = 0;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Internals                                                                */
+    /* ------------------------------------------------------------------------ */
+    collect(method, path) {
+        const results = [];
+        const seen = new Set();
+        for (const route of this.router.compiled()) {
+            if (!methodApplies(route.definition.method, method)) {
+                continue;
+            }
+            const params = matchCompiledRoute(route, path, this.matcherOptions.caseSensitive);
+            if (!params || seen.has(route.definition.id)) {
+                continue;
+            }
+            seen.add(route.definition.id);
+            results.push(createResult(route, params, method, path));
+        }
+        return Object.freeze(results);
+    }
+    matchFirstAllowed(methods, path) {
+        for (const method of methods) {
+            const result = this.matchMethod(method, path);
+            if (result) {
+                return result;
+            }
+        }
+        return undefined;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+export function createRouteMatcher(router, options = {}) {
+    return new RouteMatcher(router, options);
+}
+/* -------------------------------------------------------------------------- */
+/* Standalone Helpers                                                         */
+/* -------------------------------------------------------------------------- */
+export function matchRoute(matcher, method, path) {
+    return matcher.match({
+        method,
+        path,
+    });
+}
+export function matchRoutePath(matcher, path) {
+    return matcher.matchPath(path);
+}
+export function getAllowedMethods(matcher, path) {
+    return matcher.allowedMethods(path);
+}
+/* -------------------------------------------------------------------------- */
+/* Result Creation                                                            */
+/* -------------------------------------------------------------------------- */
+function createResult(route, params, method, path) {
+    return Object.freeze({
+        route: route.definition,
+        params: Object.freeze({
+            ...params,
+        }),
+        method,
+        path,
+        score: route.score,
+        matchedBy: route.definition.method === "*" ? "wildcard" : "exact",
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Method Utilities                                                           */
+/* -------------------------------------------------------------------------- */
+function methodApplies(routeMethod, requestMethod) {
+    return (routeMethod === "*" ||
+        requestMethod === "*" ||
+        routeMethod === requestMethod);
+}
+function orderMethods(methods) {
+    const preferred = [
+        "OPTIONS",
+        "GET",
+        "HEAD",
+        "POST",
+        "PUT",
+        "PATCH",
+        "DELETE",
+        "CONNECT",
+        "TRACE",
+        "*",
+    ];
+    return preferred.filter((method) => methods.has(method));
+}
+/* -------------------------------------------------------------------------- */
+/* Path Utilities                                                             */
+/* -------------------------------------------------------------------------- */
+export function normalizeRequestPath(path) {
+    if (!path) {
+        return "/";
+    }
+    let normalized = path.trim();
+    if (normalized.startsWith("http://") || normalized.startsWith("https://")) {
+        try {
+            normalized = new URL(normalized).pathname;
+        }
+        catch {
+            // Keep the original value if it is not a valid absolute URL.
+        }
+    }
+    const queryIndex = normalized.indexOf("?");
+    if (queryIndex !== -1) {
+        normalized = normalized.slice(0, queryIndex);
+    }
+    const hashIndex = normalized.indexOf("#");
+    if (hashIndex !== -1) {
+        normalized = normalized.slice(0, hashIndex);
+    }
+    if (!normalized.startsWith("/")) {
+        normalized = `/${normalized}`;
+    }
+    normalized = normalized.replace(/\/{2,}/g, "/");
+    if (normalized.length > 1 && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized || "/";
+}
+/* -------------------------------------------------------------------------- */
+/* Type Guards                                                                */
+/* -------------------------------------------------------------------------- */
+export function isRouteMatcher(value) {
+    return value instanceof RouteMatcher;
+}
+export function isRouteMatcherResult(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    return ("route" in value &&
+        "params" in value &&
+        "method" in value &&
+        "path" in value);
+}
+//# sourceMappingURL=httpRoute.matcher.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * HTTP route matching.
+ */
+export { matchCompiledRoute } from "./httpRoute.matcher.core.js";
+export { RouteMatcher, createRouteMatcher, matchRoute, matchRoutePath, getAllowedMethods, normalizeRequestPath, isRouteMatcher, isRouteMatcherResult, } from "./httpRoute.matcher.js";
+export type { RouteMatcherOptions, RouteMatchRequest, RouteMatcherResult, RouteMethodResult, RouteMatcherStats, } from "./httpRoute.matcher.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/matching/index.js

@@ -0,0 +1,6 @@
+/**
+ * HTTP route matching.
+ */
+export { matchCompiledRoute } from "./httpRoute.matcher.core.js";
+export { RouteMatcher, createRouteMatcher, matchRoute, matchRoutePath, getAllowedMethods, normalizeRequestPath, isRouteMatcher, isRouteMatcherResult, } from "./httpRoute.matcher.js";
+//# sourceMappingURL=index.js.map

package/dist/httpRouter/pattern/core/httpPattern.compilation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Route pattern compilation.
+ *
+ * @module httpRoute/pattern/compilation
+ */
+import type { RoutePatternOptions, CompiledRoutePattern } from "./httpPattern.type.js";
+/**
+ * Compiles a route pattern string into a CompiledRoutePattern.
+ */
+export declare function compileRoutePattern(pattern: string, options?: RoutePatternOptions): CompiledRoutePattern;
+//# sourceMappingURL=httpPattern.compilation.d.ts.map

package/dist/httpRouter/pattern/core/httpPattern.compilation.js

@@ -0,0 +1,44 @@
+/**
+ * Route pattern compilation.
+ *
+ * @module httpRoute/pattern/compilation
+ */
+import { RoutePatternError, DuplicateRouteParameterError, } from "./httpPattern.type.js";
+import { parseSegments } from "./httpPattern.segmentParsing.js";
+import { buildRegex } from "./httpPattern.regexBuilding.js";
+/**
+ * Compiles a route pattern string into a CompiledRoutePattern.
+ */
+export function compileRoutePattern(pattern, options = {}) {
+    if (!pattern) {
+        throw new RoutePatternError("Pattern cannot be empty", { pattern });
+    }
+    const segments = parseSegments(pattern);
+    const paramNames = extractParamNames(segments);
+    validateNoDuplicateParams(paramNames, pattern);
+    const regex = buildRegex(segments, options);
+    return {
+        original: pattern,
+        segments,
+        regex,
+        paramNames,
+        options,
+    };
+}
+function extractParamNames(segments) {
+    return segments
+        .filter((s) => s.type === "parameter" || s.type === "wildcard")
+        .map((s) => s.name);
+}
+function validateNoDuplicateParams(paramNames, pattern) {
+    const seen = new Set();
+    for (const name of paramNames) {
+        if (name === "*")
+            continue;
+        if (seen.has(name)) {
+            throw new DuplicateRouteParameterError(pattern, name);
+        }
+        seen.add(name);
+    }
+}
+//# sourceMappingURL=httpPattern.compilation.js.map

package/dist/httpRouter/pattern/core/httpPattern.matching.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Route pattern matching.
+ *
+ * @module httpRoute/pattern/matching
+ */
+import type { CompiledRoutePattern, RouteMatch } from "./httpPattern.type.js";
+/**
+ * Tests if a path matches a compiled route pattern.
+ */
+export declare function testRoutePattern(pattern: CompiledRoutePattern, path: string): boolean;
+/**
+ * Matches a path against a compiled route pattern.
+ */
+export declare function matchRoutePattern(pattern: CompiledRoutePattern, path: string): RouteMatch | undefined;
+/**
+ * Matches a path against multiple compiled route patterns.
+ */
+export declare function matchRoutePatterns(patterns: readonly CompiledRoutePattern[], path: string): RouteMatch | undefined;
+/**
+ * Tests if a path matches any of the compiled route patterns.
+ */
+export declare function testRoutePatterns(patterns: readonly CompiledRoutePattern[], path: string): boolean;
+//# sourceMappingURL=httpPattern.matching.d.ts.map

package/dist/httpRouter/pattern/core/httpPattern.matching.js

@@ -0,0 +1,93 @@
+/**
+ * Route pattern matching.
+ *
+ * @module httpRoute/pattern/matching
+ */
+const TRAVERSAL_CHARS = /[\\\u0000]/;
+/**
+ * Decodes a captured pattern group.
+ *
+ * Matching happens against the still-encoded path, so `%2e%2e%2f` satisfies a
+ * `[^/]+` parameter and only becomes `../` afterwards. Anything that decodes
+ * into a traversal payload, or that is not valid percent-encoding at all,
+ * fails the match rather than reaching a handler.
+ */
+function decodeCapture(value, kind) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (TRAVERSAL_CHARS.test(decoded)) {
+        return undefined;
+    }
+    const parts = kind === "wildcard" ? decoded.split("/") : [decoded];
+    for (const part of parts) {
+        if (part === "." || part === "..") {
+            return undefined;
+        }
+        if (kind !== "wildcard" && part.includes("/")) {
+            return undefined;
+        }
+    }
+    return decoded;
+}
+/**
+ * Tests if a path matches a compiled route pattern.
+ */
+export function testRoutePattern(pattern, path) {
+    return pattern.regex.test(path);
+}
+/**
+ * Matches a path against a compiled route pattern.
+ */
+export function matchRoutePattern(pattern, path) {
+    const match = path.match(pattern.regex);
+    if (!match) {
+        return undefined;
+    }
+    const params = {};
+    const kinds = new Map();
+    for (const segment of pattern.segments) {
+        if (segment.type !== "static") {
+            kinds.set(segment.name, segment.type);
+        }
+    }
+    for (const name of pattern.paramNames) {
+        const value = match.groups?.[name];
+        if (value === undefined) {
+            continue;
+        }
+        const decoded = decodeCapture(value, kinds.get(name) ?? "parameter");
+        if (decoded === undefined) {
+            return undefined;
+        }
+        params[name] = decoded;
+    }
+    return {
+        params,
+        path,
+        pattern: pattern.original,
+    };
+}
+/**
+ * Matches a path against multiple compiled route patterns.
+ */
+export function matchRoutePatterns(patterns, path) {
+    for (const pattern of patterns) {
+        const match = matchRoutePattern(pattern, path);
+        if (match) {
+            return match;
+        }
+    }
+    return undefined;
+}
+/**
+ * Tests if a path matches any of the compiled route patterns.
+ */
+export function testRoutePatterns(patterns, path) {
+    return patterns.some((p) => testRoutePattern(p, path));
+}
+//# sourceMappingURL=httpPattern.matching.js.map

package/dist/httpRouter/pattern/core/httpPattern.regexBuilding.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Regex building for route patterns.
+ *
+ * @module httpRoute/pattern/regexBuilding
+ */
+import type { RouteSegment, RoutePatternOptions } from "./httpPattern.type.js";
+/**
+ * Builds a regex from route segments.
+ */
+export declare function buildRegex(segments: readonly RouteSegment[], options: RoutePatternOptions): RegExp;
+//# sourceMappingURL=httpPattern.regexBuilding.d.ts.map