@zudojs/http 0.1.0 → 1.1.0

package/dist/httpRouter/core/register/httpRouter.register.js

@@ -0,0 +1,309 @@
+/**
+ * HTTP router registration, matching, and dispatch.
+ */
+import { HttpRouterError, RouteConflictError, } from "../error/httpRouter.error.js";
+import { HttpRouterGroup } from "../group/httpRouterGroup.core.js";
+import { collectAllowedMethods, createFallbackRoute, createOptionsResponse, defaultMethodNotAllowedHandler, defaultNotFoundHandler, executeRoute, extractRouteSequence, isHttpMethod, normalizeMethod, normalizeMethods, normalizeResponse, } from "../factory/httpRoute.factory.base.js";
+import { getRequestMethod, getRequestSignal, getRequestUrl, normalizePath, parseQuery, parseUrl, } from "../util/httpRoute.util.js";
+import { matchCompiledRoute } from "../../matching/httpRoute.matcher.core.js";
+import { compileRoute } from "../../pattern/httpRoute.pattern.parse.js";
+import { createRouterMiddlewareContext } from "../../httpRouter.context.js";
+export class HttpRouter {
+    routes = [];
+    routerOptions;
+    notFoundHandler;
+    methodNotAllowedHandler;
+    sequence = 0;
+    constructor(options = {}) {
+        this.routerOptions = {
+            caseSensitive: options.caseSensitive ?? false,
+            strictTrailingSlash: options.strictTrailingSlash ?? false,
+            automaticHead: options.automaticHead ?? true,
+            automaticOptions: options.automaticOptions ?? true,
+        };
+        this.notFoundHandler = options.notFoundHandler ?? defaultNotFoundHandler;
+        this.methodNotAllowedHandler =
+            options.methodNotAllowedHandler ?? defaultMethodNotAllowedHandler;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Route Registration                                                       */
+    /* ------------------------------------------------------------------------ */
+    add(definition) {
+        const methods = normalizeMethods(definition.method);
+        for (const method of methods) {
+            this.register(method, definition.path, definition.handler, {
+                name: definition.name,
+                middleware: definition.middleware,
+                metadata: definition.metadata,
+                strictTrailingSlash: definition.strictTrailingSlash,
+            });
+        }
+        return () => {
+            for (const method of methods) {
+                this.remove(method, definition.path);
+            }
+        };
+    }
+    on(method, path, handler, options = {}) {
+        return this.register(method, path, handler, 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);
+    }
+    connect(path, handler, options = {}) {
+        return this.on("CONNECT", path, handler, options);
+    }
+    trace(path, handler, options = {}) {
+        return this.on("TRACE", path, handler, options);
+    }
+    all(path, handler, options = {}) {
+        return this.on("*", path, handler, options);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Route Groups                                                             */
+    /* ------------------------------------------------------------------------ */
+    group(prefix, configure, options = {}) {
+        const group = new HttpRouterGroup(this, prefix, options);
+        configure(group);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Route Management                                                         */
+    /* ------------------------------------------------------------------------ */
+    remove(method, path) {
+        const normalizedMethod = normalizeMethod(method);
+        const index = this.routes.findIndex((route) => route.definition.method === normalizedMethod &&
+            route.definition.path === normalizePath(path));
+        if (index === -1) {
+            return false;
+        }
+        this.routes.splice(index, 1);
+        return true;
+    }
+    clear() {
+        this.routes.length = 0;
+    }
+    count() {
+        return this.routes.length;
+    }
+    list() {
+        return Object.freeze(this.sortedRoutes().map((route) => route.definition));
+    }
+    /**
+     * Returns the registered routes with their compiled segments, most
+     * specific first.
+     */
+    compiled() {
+        return Object.freeze(this.sortedRoutes());
+    }
+    find(id) {
+        return this.routes.find((route) => route.definition.id === id)?.definition;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Matching                                                                 */
+    /* ------------------------------------------------------------------------ */
+    match(method, path) {
+        const normalizedMethod = method.toUpperCase();
+        const normalizedPath = normalizePath(path);
+        const candidates = this.sortedRoutes();
+        const allowed = new Set();
+        let pathMatched = false;
+        for (const route of candidates) {
+            const params = matchCompiledRoute(route, normalizedPath, this.routerOptions.caseSensitive);
+            if (!params) {
+                continue;
+            }
+            pathMatched = true;
+            const routeMethod = route.definition.method;
+            if (routeMethod === normalizedMethod || routeMethod === "*") {
+                return {
+                    matched: true,
+                    route: route.definition,
+                    params,
+                    allowedMethods: Object.freeze([
+                        ...collectAllowedMethods(candidates, normalizedPath),
+                    ]),
+                    path: normalizedPath,
+                    method: normalizedMethod,
+                };
+            }
+            if (isHttpMethod(routeMethod)) {
+                allowed.add(routeMethod);
+            }
+        }
+        if (normalizedMethod === "HEAD" && this.routerOptions.automaticHead) {
+            for (const route of candidates) {
+                if (route.definition.method !== "GET") {
+                    continue;
+                }
+                const params = matchCompiledRoute(route, normalizedPath, this.routerOptions.caseSensitive);
+                if (params) {
+                    return {
+                        matched: true,
+                        route: route.definition,
+                        params,
+                        allowedMethods: Object.freeze([
+                            ...collectAllowedMethods(candidates, normalizedPath),
+                            "HEAD",
+                        ]),
+                        path: normalizedPath,
+                        method: normalizedMethod,
+                    };
+                }
+            }
+        }
+        if (this.routerOptions.automaticOptions &&
+            normalizedMethod === "OPTIONS" &&
+            pathMatched) {
+            return {
+                matched: true,
+                route: undefined,
+                params: {},
+                allowedMethods: Object.freeze([
+                    ...collectAllowedMethods(candidates, normalizedPath),
+                    "OPTIONS",
+                ]),
+                path: normalizedPath,
+                method: normalizedMethod,
+            };
+        }
+        return {
+            matched: false,
+            route: undefined,
+            params: {},
+            allowedMethods: Object.freeze([...allowed]),
+            path: normalizedPath,
+            method: normalizedMethod,
+        };
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Dispatch                                                                 */
+    /* ------------------------------------------------------------------------ */
+    async dispatch(request, options = {}) {
+        const method = getRequestMethod(request);
+        const url = getRequestUrl(request);
+        const parsed = parseUrl(url);
+        const path = parsed.pathname;
+        const match = this.match(method, path);
+        const signal = options.signal ??
+            getRequestSignal(request) ??
+            new AbortController().signal;
+        const state = options.state ?? new Map();
+        const route = match.route ?? createFallbackRoute(path, method);
+        const routerContext = {
+            request,
+            params: match.params,
+            query: parseQuery(parsed.searchParams),
+            route,
+            state,
+            middleware: createRouterMiddlewareContext(request, signal, state, route.metadata),
+            signal,
+        };
+        if (match.matched && match.route) {
+            const response = await executeRoute(match.route, routerContext);
+            return {
+                response: await normalizeResponse(response),
+                route: match.route,
+            };
+        }
+        if (method.toUpperCase() === "OPTIONS" &&
+            match.allowedMethods.length > 0 &&
+            this.routerOptions.automaticOptions) {
+            return {
+                response: createOptionsResponse(match.allowedMethods),
+                route: undefined,
+            };
+        }
+        if (match.allowedMethods.length > 0) {
+            const response = await this.methodNotAllowedHandler({
+                request,
+                path,
+                method,
+                signal,
+                state,
+            }, match.allowedMethods);
+            return {
+                response: await normalizeResponse(response),
+                route: undefined,
+            };
+        }
+        const response = await this.notFoundHandler({
+            request,
+            path,
+            method,
+            signal,
+            state,
+        });
+        return {
+            response: await normalizeResponse(response),
+            route: undefined,
+        };
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Internals                                                                */
+    /* ------------------------------------------------------------------------ */
+    register(method, path, handler, options) {
+        const normalizedMethod = normalizeMethod(method);
+        const normalizedPath = normalizePath(path);
+        if (typeof handler !== "function") {
+            throw new HttpRouterError("Route handler must be a function.");
+        }
+        const compiled = compileRoute(normalizedPath, this.routerOptions.strictTrailingSlash ||
+            options.strictTrailingSlash === true);
+        const existing = this.routes.find((route) => route.definition.method === normalizedMethod &&
+            route.definition.path === normalizedPath);
+        if (existing) {
+            throw new RouteConflictError(normalizedPath, normalizedMethod);
+        }
+        this.sequence += 1;
+        const definition = {
+            id: `route:${this.sequence}`,
+            method: normalizedMethod,
+            path: normalizedPath,
+            name: options.name,
+            params: {},
+            metadata: Object.freeze({
+                ...(options.metadata ?? {}),
+            }),
+            handler,
+            middleware: Object.freeze([...(options.middleware ?? [])]),
+        };
+        this.routes.push({
+            definition,
+            segments: compiled.segments,
+            score: compiled.score,
+            strictTrailingSlash: compiled.strictTrailingSlash,
+        });
+        return () => {
+            this.remove(normalizedMethod, normalizedPath);
+        };
+    }
+    sortedRoutes() {
+        return [...this.routes].sort((left, right) => {
+            const score = right.score - left.score;
+            if (score !== 0) {
+                return score;
+            }
+            return (extractRouteSequence(left.definition.id) -
+                extractRouteSequence(right.definition.id));
+        });
+    }
+}
+//# sourceMappingURL=httpRouter.register.js.map

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

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

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

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

package/dist/httpRouter/core/registry/core/httpRegistry.helper.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Route registry helper functions.
+ *
+ * @module httpRoute/registry/helpers
+ */
+import type { RouteRegistryEntry, RouteRegistryOptions } from "./httpRegistry.type.js";
+declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "TRACE", "CONNECT"];
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+/**
+ * Normalizes an HTTP method to uppercase.
+ */
+export declare function normalizeMethod(method: string): string;
+/**
+ * Normalizes one or more HTTP methods to uppercase.
+ */
+export declare function normalizeMethods(method: string | readonly string[]): readonly string[];
+/**
+ * Checks if a string is a valid HTTP method.
+ */
+export declare function isHttpMethod(method: string): method is HttpMethod;
+/**
+ * Normalizes a path based on registry options.
+ */
+export declare function normalizePath(path: string, options: RouteRegistryOptions): string;
+/**
+ * Checks if an entry matches a lookup query.
+ */
+export declare function matchesLookup(entry: RouteRegistryEntry, path: string, method: string | undefined, options: RouteRegistryOptions): boolean;
+/**
+ * Extracts the sequence number from a path for sorting.
+ */
+export declare function extractSequence(path: string): number;
+export {};
+//# sourceMappingURL=httpRegistry.helper.d.ts.map

package/dist/httpRouter/core/registry/core/httpRegistry.helper.js

@@ -0,0 +1,69 @@
+/**
+ * Route registry helper functions.
+ *
+ * @module httpRoute/registry/helpers
+ */
+const HTTP_METHODS = [
+    "GET",
+    "POST",
+    "PUT",
+    "DELETE",
+    "PATCH",
+    "HEAD",
+    "OPTIONS",
+    "TRACE",
+    "CONNECT",
+];
+/**
+ * Normalizes an HTTP method to uppercase.
+ */
+export function normalizeMethod(method) {
+    return method.toUpperCase();
+}
+/**
+ * Normalizes one or more HTTP methods to uppercase.
+ */
+export function normalizeMethods(method) {
+    const methods = typeof method === "string" ? [method] : method;
+    return methods.map(normalizeMethod);
+}
+/**
+ * Checks if a string is a valid HTTP method.
+ */
+export function isHttpMethod(method) {
+    return HTTP_METHODS.includes(method.toUpperCase());
+}
+/**
+ * Normalizes a path based on registry options.
+ */
+export function normalizePath(path, options) {
+    let normalized = path;
+    if (!options.caseSensitive) {
+        normalized = normalized.toLowerCase();
+    }
+    if (!options.strict) {
+        normalized = normalized.replace(/(?<!\/)\/+$/, "") || "/";
+    }
+    return normalized;
+}
+/**
+ * Checks if an entry matches a lookup query.
+ */
+export function matchesLookup(entry, path, method, options) {
+    const normalizedPath = normalizePath(entry.path, options);
+    if (normalizedPath !== path) {
+        return false;
+    }
+    if (method && entry.method.toUpperCase() !== method.toUpperCase()) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Extracts the sequence number from a path for sorting.
+ */
+export function extractSequence(path) {
+    const sequence = /:(\d+)/.exec(path)?.[1];
+    return sequence === undefined ? 0 : parseInt(sequence, 10);
+}
+//# sourceMappingURL=httpRegistry.helper.js.map

package/dist/httpRouter/core/registry/core/httpRegistry.type.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Route registry types.
+ *
+ * @module httpRoute/registry/types
+ */
+export interface RouteRegistryEntry {
+    readonly path: string;
+    readonly method: string;
+    readonly handler: unknown;
+    readonly options: RouteRegistrationOptions;
+    readonly metadata: Record<string, unknown>;
+}
+export interface RouteRegistryOptions {
+    readonly caseSensitive?: boolean;
+    readonly strict?: boolean;
+    readonly end?: boolean;
+}
+export interface RouteRegistrationOptions {
+    readonly middleware?: readonly unknown[];
+    readonly metadata?: Record<string, unknown>;
+    readonly priority?: number;
+}
+export interface RouteLookupOptions {
+    readonly method?: string;
+    readonly path?: string;
+    readonly includeMetadata?: boolean;
+}
+export interface RouteRegistrySnapshot {
+    readonly routes: readonly RouteRegistryEntry[];
+    readonly timestamp: number;
+    readonly version: number;
+}
+//# sourceMappingURL=httpRegistry.type.d.ts.map

package/dist/httpRouter/core/registry/core/httpRegistry.type.js

@@ -0,0 +1,7 @@
+/**
+ * Route registry types.
+ *
+ * @module httpRoute/registry/types
+ */
+export {};
+//# sourceMappingURL=httpRegistry.type.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * Core registry utilities.
+ *
+ * @module httpRoute/registry/core
+ */
+export * from "./httpRegistry.type.js";
+export * from "./httpRegistry.helper.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,8 @@
+/**
+ * Core registry utilities.
+ *
+ * @module httpRoute/registry/core
+ */
+export * from "./httpRegistry.type.js";
+export * from "./httpRegistry.helper.js";
+//# sourceMappingURL=index.js.map

package/dist/httpRouter/core/registry/httpRegistry.core.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Route registry implementation.
+ *
+ * @module httpRoute/registry/registry
+ */
+import type { RouteRegistryEntry, RouteRegistryOptions, RouteRegistrationOptions, RouteLookupOptions, RouteRegistrySnapshot } from "./core/httpRegistry.type.js";
+export declare class RouteRegistry {
+    private readonly routes;
+    private readonly options;
+    private version;
+    constructor(options?: RouteRegistryOptions);
+    register(path: string, method: string | readonly string[], handler: unknown, options?: RouteRegistrationOptions): void;
+    unregister(path: string, method: string): boolean;
+    lookup(path: string, options?: RouteLookupOptions): RouteRegistryEntry | undefined;
+    findAll(path: string, options?: RouteLookupOptions): readonly RouteRegistryEntry[];
+    has(path: string, method: string): boolean;
+    clear(): void;
+    snapshot(): RouteRegistrySnapshot;
+    get size(): number;
+    get version_number(): number;
+    private createKey;
+}
+//# sourceMappingURL=httpRegistry.core.d.ts.map

package/dist/httpRouter/core/registry/httpRegistry.core.js

@@ -0,0 +1,97 @@
+/**
+ * Route registry implementation.
+ *
+ * @module httpRoute/registry/registry
+ */
+import { normalizeMethod, normalizeMethods, normalizePath, matchesLookup, extractSequence, } from "./core/httpRegistry.helper.js";
+export class RouteRegistry {
+    routes = new Map();
+    options;
+    version = 0;
+    constructor(options = {}) {
+        this.options = {
+            caseSensitive: false,
+            strict: false,
+            end: true,
+            ...options,
+        };
+    }
+    register(path, method, handler, options = {}) {
+        const normalizedPath = normalizePath(path, this.options);
+        const methods = normalizeMethods(method);
+        for (const m of methods) {
+            const key = this.createKey(normalizedPath, m);
+            const entry = {
+                path: normalizedPath,
+                method: m,
+                handler,
+                options,
+                metadata: options.metadata ?? {},
+            };
+            this.routes.set(key, entry);
+            this.version++;
+        }
+    }
+    unregister(path, method) {
+        const normalizedPath = normalizePath(path, this.options);
+        const normalizedMethod = normalizeMethod(method);
+        const key = this.createKey(normalizedPath, normalizedMethod);
+        const existed = this.routes.delete(key);
+        if (existed) {
+            this.version++;
+        }
+        return existed;
+    }
+    lookup(path, options = {}) {
+        const normalizedPath = normalizePath(path, this.options);
+        const method = options.method ? normalizeMethod(options.method) : undefined;
+        for (const entry of this.routes.values()) {
+            if (matchesLookup(entry, normalizedPath, method, this.options)) {
+                return entry;
+            }
+        }
+        return undefined;
+    }
+    findAll(path, options = {}) {
+        const normalizedPath = normalizePath(path, this.options);
+        const method = options.method ? normalizeMethod(options.method) : undefined;
+        const results = [];
+        for (const entry of this.routes.values()) {
+            if (matchesLookup(entry, normalizedPath, method, this.options)) {
+                results.push(entry);
+            }
+        }
+        return results.sort((a, b) => {
+            const seqA = extractSequence(a.path);
+            const seqB = extractSequence(b.path);
+            return seqA - seqB;
+        });
+    }
+    has(path, method) {
+        return this.lookup(path, { method }) !== undefined;
+    }
+    clear() {
+        this.routes.clear();
+        this.version++;
+    }
+    snapshot() {
+        return {
+            routes: Array.from(this.routes.values()),
+            timestamp: Date.now(),
+            version: this.version,
+        };
+    }
+    get size() {
+        return this.routes.size;
+    }
+    get version_number() {
+        return this.version;
+    }
+    createKey(path, method) {
+        const caseSensitive = this.options.caseSensitive ?? false;
+        const normalizedPath = caseSensitive ? path : path.toLowerCase();
+        const normalizedMethod = caseSensitive ? method : method.toUpperCase();
+        return `${normalizedMethod}:${normalizedPath}`;
+    }
+}
+//# sourceMappingURL=httpRegistry.core.js.map

package/dist/httpRouter/core/registry/httpRegistry.factory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Route registry factory functions.
+ *
+ * @module httpRoute/registry/factory
+ */
+import type { RouteRegistryOptions } from "./core/httpRegistry.type.js";
+import { RouteRegistry } from "./httpRegistry.core.js";
+import { RouteRegistryGroup } from "./httpRegistry.group.js";
+/**
+ * Creates a new route registry.
+ */
+export declare function createRouteRegistry(options?: RouteRegistryOptions): RouteRegistry;
+/**
+ * Creates a new route registry group.
+ */
+export declare function createRouteRegistryGroup(options?: RouteRegistryOptions): RouteRegistryGroup;
+/**
+ * Type guard for RouteRegistry.
+ */
+export declare function isRouteRegistry(value: unknown): value is RouteRegistry;
+/**
+ * Type guard for RouteRegistryGroup.
+ */
+export declare function isRouteRegistryGroup(value: unknown): value is RouteRegistryGroup;
+//# sourceMappingURL=httpRegistry.factory.d.ts.map

package/dist/httpRouter/core/registry/httpRegistry.factory.js

@@ -0,0 +1,32 @@
+/**
+ * Route registry factory functions.
+ *
+ * @module httpRoute/registry/factory
+ */
+import { RouteRegistry } from "./httpRegistry.core.js";
+import { RouteRegistryGroup } from "./httpRegistry.group.js";
+/**
+ * Creates a new route registry.
+ */
+export function createRouteRegistry(options = {}) {
+    return new RouteRegistry(options);
+}
+/**
+ * Creates a new route registry group.
+ */
+export function createRouteRegistryGroup(options = {}) {
+    return new RouteRegistryGroup(options);
+}
+/**
+ * Type guard for RouteRegistry.
+ */
+export function isRouteRegistry(value) {
+    return value instanceof RouteRegistry;
+}
+/**
+ * Type guard for RouteRegistryGroup.
+ */
+export function isRouteRegistryGroup(value) {
+    return value instanceof RouteRegistryGroup;
+}
+//# sourceMappingURL=httpRegistry.factory.js.map