@zintrust/core 0.1.19 → 0.1.21

package/src/profiling/RequestProfiler.d.ts

@@ -2,9 +2,9 @@
  * Request Profiler
  * Comprehensive profiling of request execution combining query, N+1, and memory metrics
  */
-import { IMemoryProfiler } from './MemoryProfiler';
-import { IQueryLogger } from './QueryLogger';
-import { IN1Detector, ProfileReport } from './types';
+import type { IMemoryProfiler } from './MemoryProfiler';
+import type { IQueryLogger } from './QueryLogger';
+import type { IN1Detector, ProfileReport } from './types';
 export interface IRequestProfiler {
     getQueryLogger(): IQueryLogger;
     getN1Detector(): IN1Detector;

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

@@ -1 +1 @@
-{"version":3,"file":"RequestProfiler.d.ts","sourceRoot":"","sources":["../../../src/profiling/RequestProfiler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAkB,MAAM,2BAA2B,CAAC;AAE5E,OAAO,EAAE,YAAY,EAAe,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAa,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,cAAc,IAAI,YAAY,CAAC;IAC/B,aAAa,IAAI,WAAW,CAAC;IAC7B,iBAAiB,IAAI,eAAe,CAAC;IACrC,cAAc,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACnE,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAAC;CAChD;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B;;OAEG;cACO,gBAAgB;EAkE1B,CAAC;AAmBH;;GAEG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,eAAe,eAAe,CAAC"}
+{"version":3,"file":"RequestProfiler.d.ts","sourceRoot":"","sources":["../../../src/profiling/RequestProfiler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAC,MAAM,2BAA2B,CAAC;AAGhE,OAAO,KAAK,EAAE,YAAY,EAAC,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAa,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,cAAc,IAAI,YAAY,CAAC;IAC/B,aAAa,IAAI,WAAW,CAAC;IAC7B,iBAAiB,IAAI,eAAe,CAAC;IACrC,cAAc,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACnE,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAAC;CAChD;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B;;OAEG;cACO,gBAAgB;EAkE1B,CAAC;AAmBH;;GAEG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,eAAe,eAAe,CAAC"}

package/src/routes/metrics.d.ts

@@ -0,0 +1,2 @@
+export { registerMetricsRoutes } from '../../routes/metrics';
+//# sourceMappingURL=metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/routes/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}

package/src/routes/metrics.js

@@ -0,0 +1 @@
+export { registerMetricsRoutes } from '../../routes/metrics.js';

package/src/routing/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/routing/CoreRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoreRoutes.d.ts","sourceRoot":"","sources":["../../../src/routing/CoreRoutes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAqJ/C;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,OAAO,KAAG,IAMpD,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/src/routing/CoreRoutes.js

@@ -0,0 +1,151 @@
+/**
+ * Core Routes - Framework built-in routes
+ * Health, metrics, and documentation endpoints
+ * Not customizable by developers; provide env-based configuration
+ */
+import { RuntimeHealthProbes } from '../health/RuntimeHealthProbes.js';
+import { PrometheusMetrics } from '../observability/PrometheusMetrics.js';
+import { appConfig } from '../config/app.js';
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { useDatabase } from '../orm/Database.js';
+import { QueryBuilder } from '../orm/QueryBuilder.js';
+import { registerDocRoutes } from './doc.js';
+import { registerErrorRoutes } from './error.js';
+import { registerErrorPagesRoutes } from './errorPages.js';
+import { Router } from './Router.js';
+/**
+ * Register health endpoints
+ */
+async function handleHealthRoute(_req, res) {
+    const environment = Env.NODE_ENV ?? 'development';
+    try {
+        const db = useDatabase();
+        const maybeIsConnected = db.isConnected;
+        const maybeConnect = db.connect;
+        if (typeof maybeIsConnected === 'function' && maybeIsConnected.call(db) === false) {
+            if (typeof maybeConnect === 'function') {
+                await maybeConnect.call(db);
+            }
+        }
+        await QueryBuilder.ping(db);
+        const uptime = typeof process !== 'undefined' && typeof process.uptime === 'function' ? process.uptime() : 0;
+        res.json({
+            status: 'healthy',
+            timestamp: new Date().toISOString(),
+            uptime,
+            database: 'connected',
+            environment,
+        });
+    }
+    catch (error) {
+        Logger.error('Health check failed:', error);
+        const isProd = environment === 'production' || environment === 'prod';
+        res.setStatus(503).json({
+            status: 'unhealthy',
+            timestamp: new Date().toISOString(),
+            database: 'disconnected',
+            error: isProd ? 'Service unavailable' : error.message,
+        });
+    }
+}
+function handleHealthLiveRoute(_req, res) {
+    const uptime = typeof process !== 'undefined' && typeof process.uptime === 'function' ? process.uptime() : 0;
+    res.json({
+        status: 'alive',
+        timestamp: new Date().toISOString(),
+        uptime,
+    });
+}
+async function handleHealthReadyRoute(_req, res) {
+    const startTime = Date.now();
+    const environment = appConfig.environment;
+    let databaseResponseTime = null;
+    let cacheResponseTime = null;
+    try {
+        const db = useDatabase();
+        const maybeIsConnected = db.isConnected;
+        const maybeConnect = db.connect;
+        if (typeof maybeIsConnected === 'function' && maybeIsConnected.call(db) === false) {
+            if (typeof maybeConnect === 'function') {
+                await maybeConnect.call(db);
+            }
+        }
+        await QueryBuilder.ping(db);
+        databaseResponseTime = Date.now() - startTime;
+        cacheResponseTime = await RuntimeHealthProbes.pingKvCache(2000);
+        res.json({
+            status: 'ready',
+            timestamp: new Date().toISOString(),
+            environment,
+            dependencies: {
+                database: {
+                    status: 'ready',
+                    responseTime: databaseResponseTime,
+                },
+                ...(cacheResponseTime === null
+                    ? {}
+                    : {
+                        cache: {
+                            status: 'ready',
+                            responseTime: cacheResponseTime,
+                        },
+                    }),
+            },
+        });
+    }
+    catch (error) {
+        Logger.error('Readiness check failed:', error);
+        const isProd = environment === 'production';
+        const responseTime = Date.now() - startTime;
+        const dependencies = {
+            database: {
+                status: databaseResponseTime === null ? 'unavailable' : 'ready',
+                responseTime: databaseResponseTime ?? responseTime,
+            },
+        };
+        if (RuntimeHealthProbes.getCacheDriverName() === 'kv') {
+            dependencies['cache'] = {
+                status: 'unavailable',
+                responseTime: cacheResponseTime ?? responseTime,
+            };
+        }
+        res.setStatus(503).json({
+            status: 'not_ready',
+            timestamp: new Date().toISOString(),
+            environment,
+            dependencies,
+            error: isProd ? 'Service unavailable' : error.message,
+        });
+    }
+}
+function registerHealthRoutes(router) {
+    Router.get(router, '/health', handleHealthRoute);
+    Router.get(router, '/health/live', handleHealthLiveRoute);
+    Router.get(router, '/health/ready', handleHealthReadyRoute);
+}
+/**
+ * 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);
+};
+export default registerCoreRoutes;

package/src/routing/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/routing/RouteRegistry.d.ts.map

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

@@ -1,13 +1,21 @@
-import { IRequest } from '../http/Request';
-import { IResponse } from '../http/Response';
+import type { IRequest } from '../http/Request';
+import type { IResponse } from '../http/Response';
+import { type RouteMeta, type RouteMetaInput } from './RouteRegistry';
 /**
  * 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;
@@ -15,6 +23,8 @@ export interface Route {
     pattern: RegExp;
     handler: RouteHandler;
     paramNames: string[];
+    middleware?: string[];
+    meta?: RouteMeta;
 }
 export type RouteGroupCallback = (router: IRouter) => void;
 export interface ResourceController {
@@ -24,6 +34,13 @@ export interface ResourceController {
     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;
@@ -38,13 +55,13 @@ export declare const Router: Readonly<{
     createRouter: () => IRouter;
     scopeRouter: (router: IRouter, prefix: string) => IRouter;
     group: (router: IRouter, prefix: string, callback: RouteGroupCallback) => void;
-    resource: (router: IRouter, path: string, controller: ResourceController) => void;
-    get: (router: IRouter, path: string, handler: RouteHandler) => void;
-    post: (router: IRouter, path: string, handler: RouteHandler) => void;
-    put: (router: IRouter, path: string, handler: RouteHandler) => void;
-    patch: (router: IRouter, path: string, handler: RouteHandler) => void;
-    del: (router: IRouter, path: string, handler: RouteHandler) => void;
-    any: (router: IRouter, path: string, handler: RouteHandler) => 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[];
 }>;

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

@@ -1 +1 @@
-{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../../src/routing/Router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;GAGG;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnF,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;CAClC,CAAC;AAEF,eAAO,MAAM,YAAY,QAAO,OAI9B,CAAC;AAoMH;;;GAGG;AACH,eAAO,MAAM,MAAM;wBA5Ma,OAAO;0BA8IV,OAAO,UAAU,MAAM,KAAG,OAAO;oBAMvC,OAAO,UAAU,MAAM,YAAY,kBAAkB,KAAG,IAAI;uBAIzD,OAAO,QAAQ,MAAM,cAAc,kBAAkB,KAAG,IAAI;kBAgBjE,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;mBAIlD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;kBAIpD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;oBAIjD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;kBAIrD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;kBAInD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;oBAOjD,OAAO,UAAU,MAAM,QAAQ,MAAM,KAAG,UAAU,GAAG,IAAI;wBAGrD,OAAO,KAAG,KAAK,EAAE;EAmB1C,CAAC;AAEH,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../../src/routing/Router.ts"],"names":[],"mappings":"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"}

package/src/routing/Router.js

@@ -1,3 +1,4 @@
+import { RouteRegistry, normalizeRouteMeta, } from './RouteRegistry.js';
 export const createRouter = () => ({
     routes: [],
     prefix: '',
@@ -13,9 +14,13 @@ export const createRouter = () => ({
  */
 const pathToRegex = (path) => {
     const paramNames = [];
-    let regexPath = path.replaceAll(/:([a-zA-Z_]\w*)/g, (_, paramName) => {
+    // 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);
-        return '([^/]+)';
+        const isGreedy = star === '*';
+        return isGreedy ? '(.+)' : '([^/]+)';
     });
     regexPath = `^${regexPath}$`;
     const pattern = new RegExp(regexPath);
@@ -24,7 +29,7 @@ const pathToRegex = (path) => {
 /**
  * Register a route
  */
-const registerRoute = (router, method, path, handler) => {
+const registerRoute = (router, method, path, handler, options) => {
     const { pattern, paramNames } = pathToRegex(path);
     const route = {
         method,
@@ -32,8 +37,16 @@ const registerRoute = (router, method, path, handler) => {
         pattern,
         handler,
         paramNames,
+        middleware: Array.isArray(options?.middleware) ? options?.middleware : undefined,
+        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, []);
@@ -54,6 +67,9 @@ const getRouteMatch = (route, path) => {
     return {
         handler: route.handler,
         params,
+        middleware: route.middleware,
+        meta: route.meta,
+        routePath: route.path,
     };
 };
 /**
@@ -131,41 +147,69 @@ const scopeRouter = (router, prefix) => ({
 const group = (router, prefix, callback) => {
     callback(scopeRouter(router, prefix));
 };
-const resource = (router, path, controller) => {
-    const base = joinPaths(router.prefix, path);
+function buildResourcePaths(prefix, path) {
+    const base = joinPaths(prefix, path);
     const withId = `${base.endsWith('/') ? base.slice(0, -1) : base}/:id`;
-    if (controller.index)
-        registerRoute(router, 'GET', base, controller.index);
-    if (controller.store)
-        registerRoute(router, 'POST', base, controller.store);
-    if (controller.show)
-        registerRoute(router, 'GET', withId, controller.show);
-    if (controller.update) {
-        registerRoute(router, 'PUT', withId, controller.update);
-        registerRoute(router, 'PATCH', withId, controller.update);
-    }
-    if (controller.destroy)
-        registerRoute(router, 'DELETE', withId, controller.destroy);
-};
-const get = (router, path, handler) => {
-    registerRoute(router, 'GET', joinPaths(router.prefix, path), handler);
-};
-const post = (router, path, handler) => {
-    registerRoute(router, 'POST', joinPaths(router.prefix, path), handler);
-};
-const put = (router, path, handler) => {
-    registerRoute(router, 'PUT', joinPaths(router.prefix, path), handler);
-};
-const patch = (router, path, handler) => {
-    registerRoute(router, 'PATCH', joinPaths(router.prefix, path), handler);
-};
-const del = (router, path, handler) => {
-    registerRoute(router, 'DELETE', joinPaths(router.prefix, path), handler);
-};
-const any = (router, path, handler) => {
+    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);
+        registerRoute(router, method, fullPath, handler, options);
     });
 };
 const match = (router, method, path) => matchRoute(router, method, path);

package/src/routing/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/routing/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/routing/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/routing/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/routing/doc.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Documentation Routes
+ * Serves static files from /doc/* paths with relaxed CSP headers.
+ */
+import type { IResponse } from '../http/Response';
+import type { IRouter } from './Router';
+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/routing/doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/routing/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,aAAa,EACb,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAiB7B;;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"}