@zintrust/core 0.1.28 → 0.1.30

package/src/profiling/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Profiling Type Definitions
+ * Shared interfaces for query logging, N+1 detection, and memory profiling
+ */
+export declare const PROFILING_TYPES_MODULE: string;
+/**
+ * Log entry for a single database query execution
+ */
+export interface QueryLogEntry {
+    sql: string;
+    params: unknown[];
+    duration: number;
+    timestamp: Date;
+    context: string;
+    executionCount?: number;
+}
+/**
+ * Detected N+1 query pattern
+ */
+export interface N1Pattern {
+    table: string;
+    queryCount: number;
+    query: string;
+    severity: 'warning' | 'critical';
+}
+/**
+ * Memory snapshot at a point in time
+ */
+export interface MemorySnapshot {
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+    rss: number;
+    timestamp: Date;
+}
+/**
+ * Memory delta between two snapshots
+ */
+export interface MemoryDelta {
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+    rss: number;
+}
+/**
+ * N1Detector analyzes query logs to identify N+1 patterns
+ * Groups identical queries and flags those executed 5+ times as critical
+ */
+export interface IN1Detector {
+    /**
+     * Extract table name from SQL query
+     */
+    extractTableFromSQL(sql: string): string;
+    /**
+     * Detect N+1 patterns in query log
+     */
+    detect(queryLog: QueryLogEntry[]): N1Pattern[];
+    /**
+     * Get severity level based on repetition count
+     */
+    getSeverity(count: number): 'warning' | 'critical';
+    /**
+     * Generate human-readable summary of N+1 patterns
+     */
+    generateSummary(patterns: N1Pattern[]): string;
+}
+/**
+ * Complete profile report for a request
+ */
+export interface ProfileReport {
+    duration: number;
+    queriesExecuted: number;
+    n1Patterns: N1Pattern[];
+    memoryDelta: MemoryDelta;
+    timestamp: Date;
+}
+//# sourceMappingURL=types.d.ts.map

package/src/profiling/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/profiling/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,sBAAsB,QAAkC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,GAAG,UAAU,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzC;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,SAAS,EAAE,CAAC;IAE/C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAEnD;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,IAAI,CAAC;CACjB"}

package/src/profiling/types.js

@@ -0,0 +1,5 @@
+/**
+ * Profiling Type Definitions
+ * Shared interfaces for query logging, N+1 detection, and memory profiling
+ */
+export const PROFILING_TYPES_MODULE = Object.freeze('ProfilingTypes');

package/src/routes/CoreRoutes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Core Routes - Framework built-in routes
+ * Health, metrics, and documentation endpoints
+ * Not customizable by developers; provide env-based configuration
+ */
+import type { IRouter } from './Router';
+/**
+ * Register all core framework routes
+ */
+export declare const registerCoreRoutes: (router: IRouter) => void;
+export default registerCoreRoutes;
+//# sourceMappingURL=CoreRoutes.d.ts.map

package/src/routes/CoreRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoreRoutes.d.ts","sourceRoot":"","sources":["../../../src/routes/CoreRoutes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAoBnD;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,OAAO,KAAG,IAOpD,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/src/routes/CoreRoutes.js

@@ -0,0 +1,39 @@
+/**
+ * Core Routes - Framework built-in routes
+ * Health, metrics, and documentation endpoints
+ * Not customizable by developers; provide env-based configuration
+ */
+import { PrometheusMetrics } from '../observability/PrometheusMetrics.js';
+import { registerOpenApiRoutes } from '../routes/openapi.js';
+import { registerHealthRoutes } from '../common/HealthRoutes.js';
+import { Env } from '../config/env.js';
+import { registerDocRoutes } from './doc.js';
+import { registerErrorRoutes } from './error.js';
+import { registerErrorPagesRoutes } from './errorPages.js';
+import { Router } from './Router.js';
+/**
+ * Register metrics endpoint
+ */
+const registerMetricsRoutes = (router) => {
+    if (Env.getBool('METRICS_ENABLED', false) === false)
+        return;
+    const pathFromEnv = Env.get('METRICS_PATH', '/metrics').trim();
+    const metricsPath = pathFromEnv === '' ? '/metrics' : pathFromEnv;
+    Router.get(router, metricsPath, async (_req, res) => {
+        const { contentType, body } = await PrometheusMetrics.getMetricsText();
+        res.setHeader('Content-Type', contentType);
+        res.send(body);
+    });
+};
+/**
+ * Register all core framework routes
+ */
+export const registerCoreRoutes = (router) => {
+    registerHealthRoutes(router);
+    registerMetricsRoutes(router);
+    registerDocRoutes(router);
+    registerErrorPagesRoutes(router);
+    registerErrorRoutes(router);
+    registerOpenApiRoutes(router);
+};
+export default registerCoreRoutes;

package/src/routes/RouteRegistry.d.ts

@@ -0,0 +1,39 @@
+import type { ISchema, SchemaType } from '../validation/Validator';
+export type ValidationSchema = ISchema | SchemaType;
+export type RouteMetaInput = RouteMeta | {
+    summary?: string;
+    description?: string;
+    tags?: readonly string[];
+    requestSchema?: ValidationSchema;
+    responseSchema?: unknown;
+    responseStatus?: number;
+};
+export type RouteMeta = {
+    summary?: string;
+    description?: string;
+    tags?: readonly string[];
+    request?: {
+        bodySchema?: ValidationSchema;
+        querySchema?: ValidationSchema;
+        paramsSchema?: ValidationSchema;
+        headersSchema?: ValidationSchema;
+    };
+    response?: {
+        status?: number;
+        schema?: unknown;
+    };
+};
+export type RouteRegistration = {
+    method: string;
+    path: string;
+    middleware?: readonly string[];
+    meta?: RouteMeta;
+};
+export declare const normalizeRouteMeta: (input?: RouteMetaInput) => RouteMeta | undefined;
+export declare const RouteRegistry: Readonly<{
+    record(route: RouteRegistration): void;
+    list(): readonly RouteRegistration[];
+    clear(): void;
+}>;
+export default RouteRegistry;
+//# sourceMappingURL=RouteRegistry.d.ts.map

package/src/routes/RouteRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteRegistry.d.ts","sourceRoot":"","sources":["../../../src/routes/RouteRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEjE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,CAAC;AAEpD,MAAM,MAAM,cAAc,GACtB,SAAS,GACT;IACE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,gBAAgB,CAAC;QAC9B,WAAW,CAAC,EAAE,gBAAgB,CAAC;QAC/B,YAAY,CAAC,EAAE,gBAAgB,CAAC;QAChC,aAAa,CAAC,EAAE,gBAAgB,CAAC;KAClC,CAAC;IAEF,QAAQ,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,cAAc,KAAG,SAAS,GAAG,SAwCvE,CAAC;AAUF,eAAO,MAAM,aAAa;kBACV,iBAAiB,GAAG,IAAI;YAI9B,SAAS,iBAAiB,EAAE;aAK3B,IAAI;EAGb,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/src/routes/RouteRegistry.js

@@ -0,0 +1,44 @@
+export const normalizeRouteMeta = (input) => {
+    if (input === undefined)
+        return undefined;
+    // If it already looks like the normalized shape, return as-is.
+    if (typeof input === 'object' &&
+        input !== null &&
+        ('request' in input || 'response' in input || 'summary' in input || 'tags' in input)) {
+        const any = input;
+        return any;
+    }
+    const any = input;
+    return {
+        summary: any.summary,
+        description: any.description,
+        tags: any.tags,
+        request: any.requestSchema === undefined
+            ? undefined
+            : {
+                bodySchema: any.requestSchema,
+            },
+        response: any.responseSchema === undefined && any.responseStatus === undefined
+            ? undefined
+            : {
+                status: any.responseStatus,
+                schema: any.responseSchema,
+            },
+    };
+};
+const state = {
+    routes: [],
+};
+export const RouteRegistry = Object.freeze({
+    record(route) {
+        state.routes.push(route);
+    },
+    list() {
+        // Return readonly reference to avoid unnecessary array cloning
+        return state.routes;
+    },
+    clear() {
+        state.routes.length = 0;
+    },
+});
+export default RouteRegistry;

package/src/routes/Router.d.ts

@@ -0,0 +1,73 @@
+import { type RouteMeta, type RouteMetaInput } from './RouteRegistry';
+import type { IRequest } from '../http/Request';
+import type { IResponse } from '../http/Response';
+/**
+ * Router - HTTP Routing Engine
+ * Matches incoming requests to route handlers
+ */
+export type RouteHandler = (req: IRequest, res: IResponse) => Promise<void> | void;
+export type RouteOptions<MiddlewareName extends string = string> = {
+    middleware?: ReadonlyArray<MiddlewareName>;
+    meta?: RouteMetaInput;
+};
+export interface RouteMatch {
+    handler: RouteHandler;
+    params: Record<string, string>;
+    middleware?: string[];
+    meta?: RouteMeta;
+    routePath?: string;
+}
+export interface Route {
+    method: string;
+    path: string;
+    pattern: RegExp;
+    handler: RouteHandler;
+    paramNames: string[];
+    middleware?: string[];
+    meta?: RouteMeta;
+}
+export type RouteGroupCallback = (router: IRouter) => void;
+export type GroupOptions<MiddlewareName extends string = string> = {
+    middleware?: ReadonlyArray<MiddlewareName>;
+};
+export interface ResourceController {
+    index?: RouteHandler;
+    show?: RouteHandler;
+    store?: RouteHandler;
+    update?: RouteHandler;
+    destroy?: RouteHandler;
+}
+export type ResourceOptions<MiddlewareName extends string = string> = RouteOptions<MiddlewareName> & {
+    index?: RouteOptions<MiddlewareName>;
+    show?: RouteOptions<MiddlewareName>;
+    store?: RouteOptions<MiddlewareName>;
+    update?: RouteOptions<MiddlewareName>;
+    destroy?: RouteOptions<MiddlewareName>;
+};
+export type IRouter = {
+    routes: Route[];
+    prefix: string;
+    routeIndex: Map<string, Route[]>;
+    inheritedMiddleware?: ReadonlyArray<string>;
+};
+export declare const createRouter: () => IRouter;
+/**
+ * Router - Sealed namespace for HTTP routing
+ * All operations grouped in frozen namespace to prevent mutation
+ */
+export declare const Router: Readonly<{
+    createRouter: () => IRouter;
+    scopeRouter: (router: IRouter, prefix: string, inheritedMiddleware?: ReadonlyArray<string>) => IRouter;
+    group: <M extends string = string>(router: IRouter, prefix: string, callback: RouteGroupCallback, options?: GroupOptions<M>) => void;
+    resource: <M extends string = string>(router: IRouter, path: string, controller: ResourceController, options?: ResourceOptions<M>) => void;
+    get: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    post: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    put: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    patch: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    del: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    any: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    match: (router: IRouter, method: string, path: string) => RouteMatch | null;
+    getRoutes: (router: IRouter) => Route[];
+}>;
+export default Router;
+//# sourceMappingURL=Router.d.ts.map

package/src/routes/Router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../../src/routes/Router.ts"],"names":[],"mappings":"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"}

package/src/routes/Router.js

@@ -0,0 +1,250 @@
+import { RouteRegistry, normalizeRouteMeta, } from './RouteRegistry.js';
+export const createRouter = () => ({
+    routes: [],
+    prefix: '',
+    routeIndex: new Map(),
+});
+/**
+ * Router - HTTP Routing Engine
+ * Matches incoming requests to route handlers
+ */
+/**
+ * Convert a path pattern to a regex
+ * Example: /users/:id/posts/:postId -> /users/([^/]+)/posts/([^/]+)
+ */
+const pathToRegex = (path) => {
+    const paramNames = [];
+    // Supports:
+    // - :id     => single path segment (no slashes)
+    // - :path*  => greedy match (may include slashes)
+    let regexPath = path.replaceAll(/:([a-zA-Z_]\w*)(\*)?/g, (_full, paramName, star) => {
+        paramNames.push(paramName);
+        const isGreedy = star === '*';
+        return isGreedy ? '(.+)' : '([^/]+)';
+    });
+    regexPath = `^${regexPath}$`;
+    const pattern = new RegExp(regexPath);
+    return { pattern, paramNames };
+};
+/**
+ * Register a route
+ */
+const registerRoute = (router, method, path, handler, options) => {
+    const { pattern, paramNames } = pathToRegex(path);
+    // Merge inherited middleware with route-specific middleware
+    let routeMiddleware;
+    if (router.inheritedMiddleware && router.inheritedMiddleware.length > 0) {
+        const routeSpecificMiddleware = Array.isArray(options?.middleware)
+            ? options?.middleware
+            : [];
+        routeMiddleware = [...router.inheritedMiddleware, ...routeSpecificMiddleware];
+    }
+    else {
+        const hasRouteSpecificMiddleware = Array.isArray(options?.middleware);
+        if (hasRouteSpecificMiddleware) {
+            routeMiddleware = options?.middleware;
+        }
+    }
+    const route = {
+        method,
+        path,
+        pattern,
+        handler,
+        paramNames,
+        middleware: routeMiddleware,
+        meta: normalizeRouteMeta(options?.meta),
+    };
+    router.routes.push(route);
+    RouteRegistry.record({
+        method,
+        path,
+        middleware: route.middleware,
+        meta: route.meta,
+    });
+    // Index by method for faster lookup
+    if (!router.routeIndex.has(method)) {
+        router.routeIndex.set(method, []);
+    }
+    router.routeIndex.get(method)?.push(route);
+};
+/**
+ * Extract parameters from a matching route
+ */
+const getRouteMatch = (route, path) => {
+    const match = route.pattern.exec(path);
+    if (!match)
+        return null;
+    const params = {};
+    route.paramNames.forEach((paramName, index) => {
+        params[paramName] = match[index + 1];
+    });
+    return {
+        handler: route.handler,
+        params,
+        middleware: route.middleware,
+        meta: route.meta,
+        routePath: route.path,
+    };
+};
+/**
+ * Fallback linear search for manually added routes
+ */
+const findInFallback = (router, method, path) => {
+    for (const route of router.routes) {
+        // Skip if already checked via index
+        if (router.routeIndex !== undefined) {
+            const methodRoutes = router.routeIndex.get(route.method);
+            if (methodRoutes?.includes(route) ?? false)
+                continue;
+        }
+        if (route.method !== method && route.method !== '*')
+            continue;
+        const match = getRouteMatch(route, path);
+        if (match)
+            return match;
+    }
+    return null;
+};
+/**
+ * Match a request to a route
+ */
+const matchRoute = (router, method, path) => {
+    // Try fast lookup first
+    if (router.routeIndex !== undefined) {
+        const candidates = [
+            ...(router.routeIndex.get(method) ?? []),
+            ...(router.routeIndex.get('*') ?? []),
+        ];
+        for (const route of candidates) {
+            const match = getRouteMatch(route, path);
+            if (match)
+                return match;
+        }
+    }
+    // Fallback to linear search for manually added routes or if index is missing
+    return findInFallback(router, method, path);
+};
+const stripTrailingSlashes = (value) => {
+    let end = value.length;
+    while (end > 0 && value.codePointAt(end - 1) === 47) {
+        end--;
+    }
+    return value.slice(0, end);
+};
+const normalizePrefix = (prefix) => {
+    const trimmed = prefix.trim();
+    if (trimmed === '' || trimmed === '/')
+        return '';
+    const withoutTrailing = stripTrailingSlashes(trimmed);
+    return withoutTrailing.startsWith('/') ? withoutTrailing : `/${withoutTrailing}`;
+};
+const normalizePath = (path) => {
+    const trimmed = path.trim();
+    if (trimmed === '')
+        return '/';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+const joinPaths = (prefix, path) => {
+    const pfx = normalizePrefix(prefix);
+    const pth = normalizePath(path);
+    if (pfx === '')
+        return pth;
+    if (pth === '/')
+        return pfx || '/';
+    return `${pfx}${pth}`;
+};
+const scopeRouter = (router, prefix, inheritedMiddleware) => ({
+    routes: router.routes,
+    prefix: joinPaths(router.prefix, prefix),
+    routeIndex: router.routeIndex,
+    inheritedMiddleware,
+});
+const group = (router, prefix, callback, options) => {
+    callback(scopeRouter(router, prefix, options?.middleware));
+};
+function buildResourcePaths(prefix, path) {
+    const base = joinPaths(prefix, path);
+    const withId = `${base.endsWith('/') ? base.slice(0, -1) : base}/:id`;
+    return { base, withId };
+}
+function resolveResourceDefaultOptions(options) {
+    return options?.middleware ? { middleware: options.middleware } : undefined;
+}
+function registerResourceIndex(router, base, controller, options, defaultOptions) {
+    if (!controller.index)
+        return;
+    registerRoute(router, 'GET', base, controller.index, options?.index ?? defaultOptions);
+}
+function registerResourceStore(router, base, controller, options, defaultOptions) {
+    if (!controller.store)
+        return;
+    registerRoute(router, 'POST', base, controller.store, options?.store ?? defaultOptions);
+}
+function registerResourceShow(router, withId, controller, options, defaultOptions) {
+    if (!controller.show)
+        return;
+    registerRoute(router, 'GET', withId, controller.show, options?.show ?? defaultOptions);
+}
+function registerResourceUpdate(router, withId, controller, options, defaultOptions) {
+    if (!controller.update)
+        return;
+    const updateOptions = options?.update ?? defaultOptions;
+    registerRoute(router, 'PUT', withId, controller.update, updateOptions);
+    registerRoute(router, 'PATCH', withId, controller.update, updateOptions);
+}
+function registerResourceDestroy(router, withId, controller, options, defaultOptions) {
+    if (!controller.destroy)
+        return;
+    registerRoute(router, 'DELETE', withId, controller.destroy, options?.destroy ?? defaultOptions);
+}
+const resource = (router, path, controller, options) => {
+    const { base, withId } = buildResourcePaths(router.prefix, path);
+    const defaultOptions = resolveResourceDefaultOptions(options);
+    registerResourceIndex(router, base, controller, options, defaultOptions);
+    registerResourceStore(router, base, controller, options, defaultOptions);
+    registerResourceShow(router, withId, controller, options, defaultOptions);
+    registerResourceUpdate(router, withId, controller, options, defaultOptions);
+    registerResourceDestroy(router, withId, controller, options, defaultOptions);
+};
+const get = (router, path, handler, options) => {
+    registerRoute(router, 'GET', joinPaths(router.prefix, path), handler, options);
+};
+const post = (router, path, handler, options) => {
+    registerRoute(router, 'POST', joinPaths(router.prefix, path), handler, options);
+};
+const put = (router, path, handler, options) => {
+    registerRoute(router, 'PUT', joinPaths(router.prefix, path), handler, options);
+};
+const patch = (router, path, handler, options) => {
+    registerRoute(router, 'PATCH', joinPaths(router.prefix, path), handler, options);
+};
+const del = (router, path, handler, options) => {
+    registerRoute(router, 'DELETE', joinPaths(router.prefix, path), handler, options);
+};
+const any = (router, path, handler, options) => {
+    const fullPath = joinPaths(router.prefix, path);
+    ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].forEach((method) => {
+        registerRoute(router, method, fullPath, handler, options);
+    });
+};
+const match = (router, method, path) => matchRoute(router, method, path);
+const getRoutes = (router) => router.routes;
+/**
+ * Router - Sealed namespace for HTTP routing
+ * All operations grouped in frozen namespace to prevent mutation
+ */
+export const Router = Object.freeze({
+    createRouter,
+    scopeRouter,
+    group,
+    resource,
+    get,
+    post,
+    put,
+    patch,
+    del,
+    any,
+    match,
+    getRoutes,
+});
+export default Router;

package/src/routes/common.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Routing Common Utilities
+ * Shared helpers for static routes and content-type resolution.
+ */
+/**
+ * MIME types for static file serving.
+ */
+export declare const MIME_TYPES_MAP: Record<string, string>;
+export declare const tryDecodeURIComponent: (value: string) => string;
+/**
+ * Resolves a relative path against a base directory and ensures it stays within it.
+ * Returns undefined if the resolved path escapes the base.
+ */
+export declare const resolveSafePath: (baseDir: string, relativePath: string) => string | undefined;
+//# sourceMappingURL=common.d.ts.map

package/src/routes/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/routes/common.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBjD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,KAAG,MAMrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,EAAE,cAAc,MAAM,KAAG,MAAM,GAAG,SAQhF,CAAC"}

package/src/routes/common.js

@@ -0,0 +1,47 @@
+/**
+ * Routing Common Utilities
+ * Shared helpers for static routes and content-type resolution.
+ */
+import { MIME_TYPES } from '../config/constants.js';
+import * as path from '../node-singletons/path.js';
+/**
+ * MIME types for static file serving.
+ */
+export const MIME_TYPES_MAP = {
+    '.html': MIME_TYPES.HTML,
+    '.js': MIME_TYPES.JS,
+    '.css': MIME_TYPES.CSS,
+    '.json': MIME_TYPES.JSON,
+    '.png': MIME_TYPES.PNG,
+    '.jpg': MIME_TYPES.JPG,
+    '.gif': MIME_TYPES.GIF,
+    '.svg': MIME_TYPES.SVG,
+    '.wav': MIME_TYPES.WAV,
+    '.mp4': MIME_TYPES.MP4,
+    '.woff': MIME_TYPES.WOFF,
+    '.ttf': MIME_TYPES.TTF,
+    '.eot': MIME_TYPES.EOT,
+    '.otf': MIME_TYPES.OTF,
+    '.wasm': MIME_TYPES.WASM,
+};
+export const tryDecodeURIComponent = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+/**
+ * Resolves a relative path against a base directory and ensures it stays within it.
+ * Returns undefined if the resolved path escapes the base.
+ */
+export const resolveSafePath = (baseDir, relativePath) => {
+    const baseAbs = path.resolve(baseDir);
+    const candidate = path.resolve(baseDir, relativePath);
+    if (candidate === baseAbs)
+        return candidate;
+    if (!candidate.startsWith(baseAbs + path.sep))
+        return undefined;
+    return candidate;
+};

package/src/routes/doc.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Documentation Routes
+ * Serves static files from /doc/* paths with relaxed CSP headers.
+ */
+import type { IRouter } from './Router';
+import type { IResponse } from '../http/Response';
+export { MIME_TYPES_MAP } from './common';
+/**
+ * Find the package root directory
+ */
+export { findPackageRoot, findPackageRootAsync, getFrameworkPublicRoots, getFrameworkPublicRootsAsync, getPublicRoot, getPublicRootAsync, } from './publicRoot';
+/**
+ * Set relaxed CSP headers for docs (allows external assets like Tailwind CDN, Google Fonts)
+ */
+export declare const setDocumentationCSPHeaders: (response: IResponse) => void;
+/**
+ * Serve a documentation static file (async)
+ */
+export declare const serveDocumentationFileAsync: (urlPath: string, response: IResponse) => Promise<boolean>;
+export declare const registerDocRoutes: (router: IRouter) => void;
+declare const _default: {
+    registerDocRoutes: (router: IRouter) => void;
+    setDocumentationCSPHeaders: (response: IResponse) => void;
+    serveDocumentationFileAsync: (urlPath: string, response: IResponse) => Promise<boolean>;
+};
+export default _default;
+//# sourceMappingURL=doc.d.ts.map

package/src/routes/doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/routes/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,aAAa,EACb,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AAiBjC;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,SAAS,KAAG,IAWhE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,MAAM,EACf,UAAU,SAAS,KAClB,OAAO,CAAC,OAAO,CAgDjB,CAAC;AASF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,OAAO,KAAG,IAMnD,CAAC;;gCANwC,OAAO,KAAG,IAAI;2CA5EH,SAAS,KAAG,IAAI;2CAiB1D,MAAM,YACL,SAAS,KAClB,OAAO,CAAC,OAAO,CAAC;;AAiEnB,wBAIE"}