@fluojs/http 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/dispatch/dispatch-response-policy.js

@@ -11,6 +11,45 @@ function resolveDefaultSuccessStatus(handler, value) {
       return 200;
   }
 }
+function canUseSimpleJsonFastPath(response, value) {
+  return isSimpleJsonResponseBody(value) && !isResponseBodyForbidden(response.statusCode) && hasJsonCompatibleContentType(response);
+}
+function hasSimpleJsonResponseWriter(response) {
+  return typeof response.sendSimpleJson === 'function';
+}
+function isSimpleJsonResponseBody(value) {
+  if (Array.isArray(value)) {
+    return true;
+  }
+  return typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+function isResponseBodyForbidden(status) {
+  return status === 204 || status === 205 || status === 304;
+}
+function hasJsonCompatibleContentType(response) {
+  const contentType = readHeader(response.headers, 'content-type');
+  return contentType === undefined || isJsonContentType(contentType);
+}
+function readHeader(headers, name) {
+  const lowerName = name.toLowerCase();
+  const entry = Object.entries(headers).find(([headerName]) => headerName.toLowerCase() === lowerName);
+  const value = entry?.[1];
+  return typeof value === 'string' ? value : undefined;
+}
+function isJsonContentType(contentType) {
+  return contentType.toLowerCase().includes('application/json') || contentType.toLowerCase().endsWith('+json');
+}
+
+/**
+ * Write success response.
+ *
+ * @param handler The handler.
+ * @param request The request.
+ * @param response The response.
+ * @param value The value.
+ * @param contentNegotiation The content negotiation.
+ * @returns The write success response result.
+ */
 export async function writeSuccessResponse(handler, request, response, value, contentNegotiation) {
   if (response.committed) {
     return;
@@ -39,6 +78,10 @@ export async function writeSuccessResponse(handler, request, response, value, co
   } else if (response.statusSet !== true) {
     response.setStatus(resolveDefaultSuccessStatus(handler, value));
   }
+  if (!formatter && hasSimpleJsonResponseWriter(response) && canUseSimpleJsonFastPath(response, value)) {
+    await response.sendSimpleJson(value);
+    return;
+  }
   const responseBody = formatter ? formatter.format(value) : value;
   await response.send(responseBody);
 }

package/dist/dispatch/dispatch-routing-policy.d.ts

@@ -1,4 +1,17 @@
 import type { FrameworkRequest, HandlerMapping, HandlerMatch, RequestContext } from '../types.js';
+/**
+ * Match handler or throw.
+ *
+ * @param handlerMapping The handler mapping.
+ * @param request The request.
+ * @returns The match handler or throw result.
+ */
 export declare function matchHandlerOrThrow(handlerMapping: HandlerMapping, request: FrameworkRequest): HandlerMatch;
+/**
+ * Update request params.
+ *
+ * @param requestContext The request context.
+ * @param params The params.
+ */
 export declare function updateRequestParams(requestContext: RequestContext, params: Readonly<Record<string, string>>): void;
 //# sourceMappingURL=dispatch-routing-policy.d.ts.map

package/dist/dispatch/dispatch-routing-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-routing-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-routing-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElG,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAQ3G;AAED,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAKlH"}
+{"version":3,"file":"dispatch-routing-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-routing-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElG;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAQ3G;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAKlH"}

package/dist/dispatch/dispatch-routing-policy.js

@@ -1,4 +1,11 @@
 import { HandlerNotFoundError } from '../errors.js';
+/**
+ * Match handler or throw.
+ *
+ * @param handlerMapping The handler mapping.
+ * @param request The request.
+ * @returns The match handler or throw result.
+ */
 export function matchHandlerOrThrow(handlerMapping, request) {
   const match = handlerMapping.match(request);
   if (!match) {
@@ -6,6 +13,13 @@ export function matchHandlerOrThrow(handlerMapping, request) {
   }
   return match;
 }
+
+/**
+ * Update request params.
+ *
+ * @param requestContext The request context.
+ * @param params The params.
+ */
 export function updateRequestParams(requestContext, params) {
   requestContext.request = {
     ...requestContext.request,

package/dist/dispatch/dispatcher.d.ts

@@ -1,5 +1,5 @@
 import type { Container } from '@fluojs/di';
-import type { Binder, ContentNegotiationOptions, Dispatcher, DispatcherLogger, FrameworkRequest, FrameworkResponse, HandlerMapping, InterceptorLike, MiddlewareLike, RequestObserverLike } from '../types.js';
+import type { Binder, ContentNegotiationOptions, ConverterLike, Dispatcher, DispatcherLogger, FrameworkRequest, FrameworkResponse, HandlerMapping, InterceptorLike, MiddlewareLike, RequestObserverLike } from '../types.js';
 /**
  * Type definition for a global HTTP error handler function.
  */
@@ -22,6 +22,11 @@ export interface CreateDispatcherOptions {
     observers?: RequestObserverLike[];
     /** Optional global error handler. */
     onError?: ErrorHandler;
+    /** Request-scope optimization hints supplied by runtime bootstrap. */
+    requestScope?: {
+        /** Global DTO converters used by the default binder. */
+        converterDefinitions?: readonly ConverterLike[];
+    };
     logger?: DispatcherLogger;
     /** Root DI container for creating request scopes. */
     rootContainer: Container;

package/dist/dispatch/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAW5C,OAAO,KAAK,EACV,MAAM,EACN,yBAAyB,EACzB,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAGjB,cAAc,EACd,eAAe,EAGf,cAAc,EAId,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpK;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC;IACjC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sDAAsD;IACtD,cAAc,EAAE,cAAc,CAAC;IAC/B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClC,qCAAqC;IACrC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qDAAqD;IACrD,aAAa,EAAE,SAAS,CAAC;CAC1B;AAmQD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CA8B7E"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,YAAY,CAAC;AAanE,OAAO,KAAK,EACV,MAAM,EACN,yBAAyB,EACzB,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAGjB,cAAc,EACd,eAAe,EAEf,cAAc,EAId,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpK;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC;IACjC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sDAAsD;IACtD,cAAc,EAAE,cAAc,CAAC;IAC/B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClC,qCAAqC;IACrC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,sEAAsE;IACtE,YAAY,CAAC,EAAE;QACb,wDAAwD;QACxD,oBAAoB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;KACjD,CAAC;IACF,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qDAAqD;IACrD,aAAa,EAAE,SAAS,CAAC;CAC1B;AA8bD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CAuD7E"}

package/dist/dispatch/dispatcher.js

@@ -1,10 +1,12 @@
+import { readFrameworkRequestNativeRouteHandoff } from './native-route-handoff.js';
 import { invokeControllerHandler } from './dispatch-handler-policy.js';
 import { resolveContentNegotiation, writeErrorResponse, writeSuccessResponse } from './dispatch-response-policy.js';
 import { matchHandlerOrThrow, updateRequestParams } from './dispatch-routing-policy.js';
+import { getCompiledDtoBindingPlan } from '../adapters/dto-binding-plan.js';
 import { RequestAbortedError } from '../errors.js';
 import { runGuardChain } from '../guards.js';
 import { runInterceptorChain } from '../interceptors.js';
-import { runMiddlewareChain } from '../middleware/middleware.js';
+import { isMiddlewareRouteConfig, matchRoutePattern, runMiddlewareChain } from '../middleware/middleware.js';
 import { createRequestContext, runWithRequestContext } from '../context/request-context.js';
 import { SseResponse } from '../context/sse.js';
 
@@ -31,20 +33,126 @@ function createDispatchRequest(request) {
     }
   };
 }
+function cloneHandlerDescriptor(descriptor) {
+  return {
+    ...descriptor,
+    metadata: {
+      ...descriptor.metadata,
+      moduleMiddleware: [...descriptor.metadata.moduleMiddleware],
+      pathParams: [...descriptor.metadata.pathParams]
+    },
+    route: {
+      ...descriptor.route,
+      guards: descriptor.route.guards ? [...descriptor.route.guards] : undefined,
+      headers: descriptor.route.headers?.map(header => ({
+        ...header
+      })),
+      interceptors: descriptor.route.interceptors ? [...descriptor.route.interceptors] : undefined,
+      produces: descriptor.route.produces ? [...descriptor.route.produces] : undefined,
+      redirect: descriptor.route.redirect ? {
+        ...descriptor.route.redirect
+      } : undefined
+    }
+  };
+}
 function readRequestId(request) {
   const raw = request.headers['x-request-id'] ?? request.headers['X-Request-Id'];
   const value = Array.isArray(raw) ? raw[0] : raw;
   const normalized = value?.trim();
   return normalized ? normalized : undefined;
 }
-function createDispatchContext(request, response, rootContainer) {
-  return createRequestContext({
-    container: rootContainer.createRequestScope(),
+function createDispatchContext(request, response, container, promoteOnContainerAccess) {
+  const context = createRequestContext({
+    container,
     metadata: {},
     request,
     requestId: readRequestId(request),
     response
   });
+  if (!promoteOnContainerAccess) {
+    return context;
+  }
+  let activeContainer = container;
+  Object.defineProperty(context, 'container', {
+    configurable: true,
+    enumerable: true,
+    get() {
+      activeContainer = promoteOnContainerAccess();
+      return activeContainer;
+    },
+    set(value) {
+      activeContainer = value;
+    }
+  });
+  return context;
+}
+function createRootDispatchScope(rootContainer) {
+  return {
+    container: rootContainer,
+    requestScoped: false
+  };
+}
+function createRequestDispatchScope(rootContainer) {
+  return {
+    container: rootContainer.createRequestScope(),
+    requestScoped: true
+  };
+}
+function activeMiddlewareMayRequireRequestScope(definitions, request) {
+  return definitions.some(definition => {
+    if (!isMiddlewareRouteConfig(definition)) {
+      return true;
+    }
+    return definition.routes.length === 0 || definition.routes.some(route => matchRoutePattern(route, request.path));
+  });
+}
+function requestDtoMayRequireRequestScope(handler, options) {
+  if (!handler.route.request) {
+    return false;
+  }
+  if ((options.requestScope?.converterDefinitions ?? []).length > 0) {
+    return true;
+  }
+  if (options.binder) {
+    return true;
+  }
+  const plan = getCompiledDtoBindingPlan(handler.route.request);
+  return plan.entries.some(entry => entry.converter !== undefined);
+}
+function handlerMethodMayUseRequestContext(handler) {
+  const method = handler.controllerToken.prototype[handler.methodName];
+  return typeof method === 'function' && method.length >= 2;
+}
+function hasRequestScopeInspector(container) {
+  return typeof container === 'object' && container !== null && 'hasRequestScopedDependency' in container && typeof container.hasRequestScopedDependency === 'function';
+}
+function handlerMayRequireRequestScope(handler, request, options) {
+  if (handler.route.guards && handler.route.guards.length > 0) {
+    return true;
+  }
+  if ((options.interceptors ?? []).length > 0 || (handler.route.interceptors ?? []).length > 0) {
+    return true;
+  }
+  if (activeMiddlewareMayRequireRequestScope(handler.metadata.moduleMiddleware, request)) {
+    return true;
+  }
+  if (requestDtoMayRequireRequestScope(handler, options)) {
+    return true;
+  }
+  if (handlerMethodMayUseRequestContext(handler)) {
+    return true;
+  }
+  return hasRequestScopeInspector(options.rootContainer) ? options.rootContainer.hasRequestScopedDependency(handler.controllerToken) : true;
+}
+function dispatchStartMayRequireRequestScope(request, observers, options) {
+  return observers.length > 0 || activeMiddlewareMayRequireRequestScope(options.appMiddleware ?? [], request);
+}
+function ensureRequestScope(context) {
+  if (context.dispatchScope.requestScoped) {
+    return;
+  }
+  context.dispatchScope = createRequestDispatchScope(context.options.rootContainer);
+  context.requestContext.container = context.dispatchScope.container;
 }
 function ensureRequestNotAborted(request) {
   if (request.signal?.aborted) {
@@ -71,29 +179,41 @@ async function notifyObservers(observers, requestContext, callback, handler) {
   }
 }
 async function notifyObserversSafely(observers, requestContext, callback, logger, handler) {
+  if (observers.length === 0) {
+    return;
+  }
   try {
     await notifyObservers(observers, requestContext, callback, handler);
   } catch (error) {
     logDispatchFailure(logger, 'Request observer threw an unhandled error.', error);
   }
 }
-async function dispatchMatchedHandler(handler, requestContext, observers, contentNegotiation, binder, globalInterceptors, logger) {
-  const guardContext = {
-    handler,
-    requestContext
-  };
-  const interceptorContext = {
-    handler,
-    requestContext
-  };
-  await runGuardChain(handler.route.guards ?? [], guardContext);
+function mergeInterceptors(globalInterceptors, routeInterceptors) {
+  if (globalInterceptors.length === 0) {
+    return routeInterceptors;
+  }
+  if (routeInterceptors.length === 0) {
+    return globalInterceptors;
+  }
+  return [...globalInterceptors, ...routeInterceptors];
+}
+async function dispatchMatchedHandler(handler, requestContext, controllerContainer, observers, contentNegotiation, binder, globalInterceptors, logger) {
+  const routeGuards = handler.route.guards ?? [];
+  if (routeGuards.length > 0) {
+    const guardContext = {
+      handler,
+      requestContext
+    };
+    await runGuardChain(routeGuards, guardContext);
+  }
   if (requestContext.response.committed) {
     return;
   }
-  const interceptors = [...(globalInterceptors ?? []), ...(handler.route.interceptors ?? [])];
-  const result = await runInterceptorChain(interceptors, interceptorContext, async () => {
-    return invokeControllerHandler(handler, requestContext, binder);
-  });
+  const routeInterceptors = handler.route.interceptors ?? [];
+  const result = globalInterceptors.length === 0 && routeInterceptors.length === 0 ? await invokeControllerHandler(handler, requestContext, binder, controllerContainer) : await runInterceptorChain(mergeInterceptors(globalInterceptors, routeInterceptors), {
+    handler,
+    requestContext
+  }, async () => invokeControllerHandler(handler, requestContext, binder, controllerContainer));
   ensureRequestNotAborted(requestContext.request);
   if (!(result instanceof SseResponse) && !requestContext.response.committed) {
     await writeSuccessResponse(handler, requestContext.request, requestContext.response, result, contentNegotiation);
@@ -133,8 +253,11 @@ async function runDispatchPipeline(context) {
     if (context.response.committed) {
       return;
     }
-    const match = matchHandlerOrThrow(context.options.handlerMapping, appMiddlewareContext.request);
+    const match = readFrameworkRequestNativeRouteHandoff(appMiddlewareContext.request) ?? matchHandlerOrThrow(context.options.handlerMapping, appMiddlewareContext.request);
     context.matchedHandler = match.descriptor;
+    if (handlerMayRequireRequestScope(match.descriptor, appMiddlewareContext.request, context.options)) {
+      ensureRequestScope(context);
+    }
     updateRequestParams(context.requestContext, match.params);
     await notifyHandlerMatched(context, match.descriptor);
     const moduleMiddlewareContext = {
@@ -143,7 +266,7 @@ async function runDispatchPipeline(context) {
       response: context.response
     };
     await runMiddlewareChain(match.descriptor.metadata.moduleMiddleware ?? [], moduleMiddlewareContext, async () => {
-      await dispatchMatchedHandler(match.descriptor, context.requestContext, context.observers, context.contentNegotiation, context.options.binder, context.options.interceptors, context.options.logger);
+      await dispatchMatchedHandler(match.descriptor, context.requestContext, context.dispatchScope.container, context.observers, context.contentNegotiation, context.options.binder, context.options.interceptors ?? [], context.options.logger);
     });
   });
 }
@@ -167,13 +290,29 @@ async function handleDispatchError(context, error) {
  */
 export function createDispatcher(options) {
   const contentNegotiation = resolveContentNegotiation(options.contentNegotiation);
-  return {
+  const observers = options.observers ?? [];
+  const dispatcher = {
+    describeRoutes() {
+      return options.handlerMapping.descriptors.map(descriptor => cloneHandlerDescriptor(descriptor));
+    },
     async dispatch(request, response) {
-      const phaseContext = {
+      const dispatchRequest = createDispatchRequest(request);
+      const dispatchScope = dispatchStartMayRequireRequestScope(dispatchRequest, observers, options) ? createRequestDispatchScope(options.rootContainer) : createRootDispatchScope(options.rootContainer);
+      let phaseContext;
+      let containerPromotionOpen = true;
+      const requestContext = createDispatchContext(dispatchRequest, response, dispatchScope.container, () => {
+        if (!containerPromotionOpen) {
+          return phaseContext.dispatchScope.container;
+        }
+        ensureRequestScope(phaseContext);
+        return phaseContext.dispatchScope.container;
+      });
+      phaseContext = {
         contentNegotiation,
-        observers: options.observers ?? [],
+        dispatchScope,
+        observers,
         options,
-        requestContext: createDispatchContext(createDispatchRequest(request), response, options.rootContainer),
+        requestContext,
         response
       };
       await runWithRequestContext(phaseContext.requestContext, async () => {
@@ -184,13 +323,17 @@ export function createDispatcher(options) {
           await handleDispatchError(phaseContext, error);
         } finally {
           await notifyRequestFinish(phaseContext);
-          try {
-            await phaseContext.requestContext.container.dispose();
-          } catch (error) {
-            logDispatchFailure(options.logger, 'Request-scoped container dispose threw an error.', error);
+          containerPromotionOpen = false;
+          if (phaseContext.dispatchScope.requestScoped) {
+            try {
+              await phaseContext.dispatchScope.container.dispose();
+            } catch (error) {
+              logDispatchFailure(options.logger, 'Request-scoped container dispose threw an error.', error);
+            }
           }
         }
       });
     }
   };
+  return dispatcher;
 }

package/dist/dispatch/native-route-handoff.d.ts

@@ -0,0 +1,53 @@
+import type { FrameworkRequest, HandlerMatch } from '../types.js';
+/** Internal handoff payload that lets adapters skip duplicate route matching safely. */
+export type NativeRouteHandoff = HandlerMatch;
+/**
+ * Associates one adapter-selected route handoff with a raw platform request.
+ *
+ * Platform adapters call this before translating the native request into a
+ * `FrameworkRequest`, allowing the shared dispatcher to reuse the semantically
+ * safe native match without changing the public dispatcher surface.
+ *
+ * @param rawRequest Raw platform request object used as the lookup key.
+ * @param handoff Pre-matched descriptor and params selected by the adapter.
+ */
+export declare function bindRawRequestNativeRouteHandoff(rawRequest: object, handoff: NativeRouteHandoff): void;
+/**
+ * Reads and clears a native route handoff previously bound to a raw request.
+ *
+ * Request factories consume this once while constructing `FrameworkRequest`
+ * instances so the handoff remains request-local and does not leak across
+ * platform object reuse.
+ *
+ * @param rawRequest Raw platform request object used as the lookup key.
+ * @returns The cloned handoff when one was registered for this request.
+ */
+export declare function consumeRawRequestNativeRouteHandoff(rawRequest: unknown): NativeRouteHandoff | undefined;
+/**
+ * Stores a pre-matched native route handoff on one framework request.
+ *
+ * @param request Framework request that should carry the adapter-native match.
+ * @param handoff Pre-matched descriptor and params selected by the adapter.
+ * @returns The same request instance for fluent adapter construction.
+ */
+export declare function attachFrameworkRequestNativeRouteHandoff(request: FrameworkRequest, handoff: NativeRouteHandoff): FrameworkRequest;
+/**
+ * Reads a pre-matched native route handoff from one framework request.
+ *
+ * @param request Framework request being dispatched.
+ * @returns The cloned handoff when the adapter supplied one.
+ */
+export declare function readFrameworkRequestNativeRouteHandoff(request: FrameworkRequest): NativeRouteHandoff | undefined;
+/**
+ * Reports whether a request path depends on fluo's normalization semantics.
+ *
+ * Duplicate slashes and trailing slashes are intentionally normalized by the
+ * shared matcher. Adapters use this helper to keep those requests on the
+ * generic dispatcher path when native routing may not preserve identical path
+ * selection semantics.
+ *
+ * @param path Raw framework request path.
+ * @returns `true` when normalization would change the incoming path.
+ */
+export declare function isRoutePathNormalizationSensitive(path: string): boolean;
+//# sourceMappingURL=native-route-handoff.d.ts.map

package/dist/dispatch/native-route-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-route-handoff.d.ts","sourceRoot":"","sources":["../../src/dispatch/native-route-handoff.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsBlE,wFAAwF;AACxF,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAEtG;AAED;;;;;;;;;GASG;AACH,wBAAgB,mCAAmC,CAAC,UAAU,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAavG;AAED;;;;;;GAMG;AACH,wBAAgB,wCAAwC,CACtD,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,kBAAkB,GAC1B,gBAAgB,CAYlB;AAED;;;;;GAKG;AACH,wBAAgB,sCAAsC,CACpD,OAAO,EAAE,gBAAgB,GACxB,kBAAkB,GAAG,SAAS,CAWhC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvE"}

package/dist/dispatch/native-route-handoff.js

@@ -0,0 +1,94 @@
+import { normalizeRoutePath } from '../route-path.js';
+const FRAMEWORK_REQUEST_NATIVE_ROUTE_HANDOFF = Symbol('fluo.http.nativeRouteHandoff');
+const RAW_REQUEST_NATIVE_ROUTE_HANDOFFS = new WeakMap();
+function cloneNativeRouteHandoff(handoff) {
+  return {
+    descriptor: handoff.descriptor,
+    params: {
+      ...handoff.params
+    }
+  };
+}
+
+/** Internal handoff payload that lets adapters skip duplicate route matching safely. */
+
+/**
+ * Associates one adapter-selected route handoff with a raw platform request.
+ *
+ * Platform adapters call this before translating the native request into a
+ * `FrameworkRequest`, allowing the shared dispatcher to reuse the semantically
+ * safe native match without changing the public dispatcher surface.
+ *
+ * @param rawRequest Raw platform request object used as the lookup key.
+ * @param handoff Pre-matched descriptor and params selected by the adapter.
+ */
+export function bindRawRequestNativeRouteHandoff(rawRequest, handoff) {
+  RAW_REQUEST_NATIVE_ROUTE_HANDOFFS.set(rawRequest, cloneNativeRouteHandoff(handoff));
+}
+
+/**
+ * Reads and clears a native route handoff previously bound to a raw request.
+ *
+ * Request factories consume this once while constructing `FrameworkRequest`
+ * instances so the handoff remains request-local and does not leak across
+ * platform object reuse.
+ *
+ * @param rawRequest Raw platform request object used as the lookup key.
+ * @returns The cloned handoff when one was registered for this request.
+ */
+export function consumeRawRequestNativeRouteHandoff(rawRequest) {
+  if (typeof rawRequest !== 'object' || rawRequest === null) {
+    return undefined;
+  }
+  const handoff = RAW_REQUEST_NATIVE_ROUTE_HANDOFFS.get(rawRequest);
+  if (!handoff) {
+    return undefined;
+  }
+  RAW_REQUEST_NATIVE_ROUTE_HANDOFFS.delete(rawRequest);
+  return cloneNativeRouteHandoff(handoff);
+}
+
+/**
+ * Stores a pre-matched native route handoff on one framework request.
+ *
+ * @param request Framework request that should carry the adapter-native match.
+ * @param handoff Pre-matched descriptor and params selected by the adapter.
+ * @returns The same request instance for fluent adapter construction.
+ */
+export function attachFrameworkRequestNativeRouteHandoff(request, handoff) {
+  Reflect.set(request, FRAMEWORK_REQUEST_NATIVE_ROUTE_HANDOFF, {
+    handoff: cloneNativeRouteHandoff(handoff),
+    method: request.method,
+    path: request.path
+  });
+  return request;
+}
+
+/**
+ * Reads a pre-matched native route handoff from one framework request.
+ *
+ * @param request Framework request being dispatched.
+ * @returns The cloned handoff when the adapter supplied one.
+ */
+export function readFrameworkRequestNativeRouteHandoff(request) {
+  const record = Reflect.get(request, FRAMEWORK_REQUEST_NATIVE_ROUTE_HANDOFF);
+  if (!record || record.method !== request.method || record.path !== request.path) {
+    return undefined;
+  }
+  return cloneNativeRouteHandoff(record.handoff);
+}
+
+/**
+ * Reports whether a request path depends on fluo's normalization semantics.
+ *
+ * Duplicate slashes and trailing slashes are intentionally normalized by the
+ * shared matcher. Adapters use this helper to keep those requests on the
+ * generic dispatcher path when native routing may not preserve identical path
+ * selection semantics.
+ *
+ * @param path Raw framework request path.
+ * @returns `true` when normalization would change the incoming path.
+ */
+export function isRoutePathNormalizationSensitive(path) {
+  return normalizeRoutePath(path) !== path;
+}

package/dist/errors.d.ts

@@ -5,6 +5,9 @@ import { FluoError } from '@fluojs/core';
 export declare class RouteConflictError extends FluoError {
     constructor(message: string);
 }
+/**
+ * Represents the invalid route path error.
+ */
 export declare class InvalidRoutePathError extends FluoError {
     constructor(message: string);
 }

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,SAA4C;CAGhE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,SAA4C;CAGhE"}

package/dist/errors.js

@@ -10,6 +10,10 @@ export class RouteConflictError extends FluoError {
     });
   }
 }
+
+/**
+ * Represents the invalid route path error.
+ */
 export class InvalidRoutePathError extends FluoError {
   constructor(message) {
     super(message, {

package/dist/guards.d.ts

@@ -1,3 +1,10 @@
 import type { GuardContext, GuardLike } from './types.js';
+/**
+ * Run guard chain.
+ *
+ * @param definitions The definitions.
+ * @param context The context.
+ * @returns The run guard chain result.
+ */
 export declare function runGuardChain(definitions: GuardLike[], context: GuardContext): Promise<void>;
 //# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAS,YAAY,EAAE,SAAS,EAAkB,MAAM,YAAY,CAAC;AAcjF,wBAAsB,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CASlG"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAS,YAAY,EAAE,SAAS,EAAkB,MAAM,YAAY,CAAC;AAcjF;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAalG"}

package/dist/guards.js

@@ -8,7 +8,18 @@ async function resolveGuard(definition, requestContext) {
   }
   return requestContext.container.resolve(definition);
 }
+
+/**
+ * Run guard chain.
+ *
+ * @param definitions The definitions.
+ * @param context The context.
+ * @returns The run guard chain result.
+ */
 export async function runGuardChain(definitions, context) {
+  if (definitions.length === 0) {
+    return;
+  }
   for (const definition of definitions) {
     const guard = await resolveGuard(definition, context.requestContext);
     const result = await guard.canActivate(context);

package/dist/input-error-detail.d.ts

@@ -1,10 +1,19 @@
 import type { MetadataSource } from '@fluojs/core';
 import type { HttpExceptionDetail } from './exceptions.js';
+/**
+ * Describes the input error detail contract.
+ */
 export interface InputErrorDetail {
     code: string;
     field?: string;
     message: string;
     source?: MetadataSource;
 }
+/**
+ * To input error detail.
+ *
+ * @param detail The detail.
+ * @returns The to input error detail result.
+ */
 export declare function toInputErrorDetail(detail: InputErrorDetail): HttpExceptionDetail;
 //# sourceMappingURL=input-error-detail.d.ts.map

package/dist/input-error-detail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"input-error-detail.d.ts","sourceRoot":"","sources":["../src/input-error-detail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,mBAAmB,CAOhF"}
+{"version":3,"file":"input-error-detail.d.ts","sourceRoot":"","sources":["../src/input-error-detail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,mBAAmB,CAOhF"}