@fluojs/http 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/dispatch/fast-path/eligibility-checker.d.ts

@@ -0,0 +1,22 @@
+import type { Container } from '@fluojs/di';
+import type { Binder, HandlerDescriptor } from '../../types.js';
+import type { CreateDispatcherOptions } from '../dispatcher.js';
+import { type FastPathEligibility } from './eligibility.js';
+interface CompiledEligibilityPlan {
+    eligibility: FastPathEligibility;
+    isEligible: boolean;
+}
+export declare function compileFastPathEligibility(handler: HandlerDescriptor, options: CreateDispatcherOptions, adapter: string): CompiledEligibilityPlan;
+export declare function getHandlerFastPathEligibility(handler: HandlerDescriptor): FastPathEligibility | undefined;
+export declare function setHandlerFastPathEligibility(handler: HandlerDescriptor, eligibility: FastPathEligibility): void;
+export interface FastPathExecutorOptions {
+    binder?: Binder;
+    rootContainer: Container;
+}
+export interface FastPathExecutionResult {
+    executed: boolean;
+    result?: unknown;
+    error?: unknown;
+}
+export {};
+//# sourceMappingURL=eligibility-checker.d.ts.map

package/dist/dispatch/fast-path/eligibility-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility-checker.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/eligibility-checker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,KAAK,EACV,MAAM,EACN,iBAAiB,EAElB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,KAAK,mBAAmB,EAAgC,MAAM,kBAAkB,CAAC;AAM1F,UAAU,uBAAuB;IAC/B,WAAW,EAAE,mBAAmB,CAAC;IACjC,UAAU,EAAE,OAAO,CAAC;CACrB;AA0DD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,MAAM,GACd,uBAAuB,CA6DzB;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,GACzB,mBAAmB,GAAG,SAAS,CAIjC;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,mBAAmB,GAC/B,IAAI,CAGN;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}

package/dist/dispatch/fast-path/eligibility-checker.js

@@ -0,0 +1,107 @@
+import { getCompiledDtoBindingPlan } from '../../adapters/dto-binding-plan.js';
+import { FAST_PATH_ELIGIBILITY_SYMBOL } from './eligibility.js';
+function hasRequestScopeInspector(container) {
+  return typeof container === 'object' && container !== null && 'hasRequestScopedDependency' in container && typeof container.hasRequestScopedDependency === 'function';
+}
+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 determineRequestScopeRequirement(handler, options) {
+  if (handler.route.guards && handler.route.guards.length > 0) {
+    return true;
+  }
+  if (handler.route.interceptors && handler.route.interceptors.length > 0) {
+    return true;
+  }
+  if (handler.metadata.moduleMiddleware && handler.metadata.moduleMiddleware.length > 0) {
+    return true;
+  }
+  if (requestDtoMayRequireRequestScope(handler, options)) {
+    return true;
+  }
+  if (hasRequestScopeInspector(options.rootContainer)) {
+    return options.rootContainer.hasRequestScopedDependency(handler.controllerToken);
+  }
+  return true;
+}
+function determineMiddlewareRequirement(handler, appMiddleware) {
+  if (appMiddleware.length > 0) {
+    return true;
+  }
+  const moduleMiddleware = handler.metadata.moduleMiddleware;
+  return moduleMiddleware !== undefined && moduleMiddleware.length > 0;
+}
+export function compileFastPathEligibility(handler, options, adapter) {
+  const routeId = `${handler.route.method}:${handler.route.path}`;
+  const hasGuard = (handler.route.guards?.length ?? 0) > 0;
+  const hasInterceptor = (handler.route.interceptors?.length ?? 0) > 0 || (options.interceptors?.length ?? 0) > 0;
+  const hasPipe = handler.route.request !== undefined;
+  const hasRequestScopedDI = determineRequestScopeRequirement(handler, options);
+  const hasMiddleware = determineMiddlewareRequirement(handler, options.appMiddleware ?? []);
+  const hasContentNegotiation = options.contentNegotiation?.formatters !== undefined && options.contentNegotiation.formatters.length > 0;
+  const eligibility = {
+    adapter,
+    executionPath: 'full',
+    hasAdapterPluginInfluence: false,
+    hasCustomBodyParser: options.binder !== undefined,
+    hasCustomErrorFilter: options.onError !== undefined,
+    hasGlobalHook: (options.observers?.length ?? 0) > 0,
+    hasGuard,
+    hasInterceptor,
+    hasMiddleware,
+    hasPipe,
+    hasRequestScopedDI,
+    routeId
+  };
+  const blockingReasons = [];
+  if (eligibility.hasGuard) {
+    blockingReasons.push('guards');
+  }
+  if (eligibility.hasInterceptor) {
+    blockingReasons.push('interceptors');
+  }
+  if (eligibility.hasRequestScopedDI) {
+    blockingReasons.push('request-scoped DI');
+  }
+  if (eligibility.hasMiddleware) {
+    blockingReasons.push('middleware');
+  }
+  if (eligibility.hasGlobalHook) {
+    blockingReasons.push('request observers');
+  }
+  if (eligibility.hasCustomErrorFilter) {
+    blockingReasons.push('custom error filter');
+  }
+  if (eligibility.hasCustomBodyParser) {
+    blockingReasons.push('custom binder');
+  }
+  if (hasContentNegotiation) {
+    blockingReasons.push('content negotiation');
+  }
+  const isEligible = blockingReasons.length === 0;
+  if (!isEligible) {
+    eligibility.fallbackReason = `Full path required due to: ${blockingReasons.join(', ')}`;
+  } else {
+    eligibility.executionPath = 'fast';
+  }
+  return {
+    eligibility,
+    isEligible
+  };
+}
+export function getHandlerFastPathEligibility(handler) {
+  return handler[FAST_PATH_ELIGIBILITY_SYMBOL];
+}
+export function setHandlerFastPathEligibility(handler, eligibility) {
+  handler[FAST_PATH_ELIGIBILITY_SYMBOL] = eligibility;
+}

package/dist/dispatch/fast-path/eligibility.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Per-route capability model used to decide whether a route can safely bypass
+ * optional framework overhead and execute through the fast path.
+ *
+ * Fast path selection is automatic and conservative: if safety cannot be proven,
+ * the route uses the full path with all framework features enabled.
+ */
+export interface FastPathEligibility {
+    /** Stable identifier for the route being analyzed. */
+    readonly routeId: string;
+    /** Active runtime adapter such as Fastify or Bun. */
+    readonly adapter: string;
+    /** Benchmark or runtime scenario associated with the route. */
+    readonly scenario?: string;
+    /** Whether a global hook may affect route execution. */
+    readonly hasGlobalHook: boolean;
+    /** Whether middleware applies to the route. */
+    readonly hasMiddleware: boolean;
+    /** Whether guard logic applies to the route. */
+    readonly hasGuard: boolean;
+    /** Whether pipe or validation logic applies to the route. */
+    readonly hasPipe: boolean;
+    /** Whether interceptor logic applies to the route. */
+    readonly hasInterceptor: boolean;
+    /** Whether request-scoped dependency resolution is needed. */
+    readonly hasRequestScopedDI: boolean;
+    /** Whether body parsing behavior has been customized. */
+    readonly hasCustomBodyParser: boolean;
+    /** Whether a custom exception filter applies. */
+    readonly hasCustomErrorFilter: boolean;
+    /** Whether adapter-level plugin behavior may affect execution. */
+    readonly hasAdapterPluginInfluence: boolean;
+    /** Resolved execution path, either 'fast' or 'full'. */
+    executionPath: 'fast' | 'full';
+    /** Explanation for full-path fallback when fast path is not selected. */
+    fallbackReason?: string;
+}
+/**
+ * Statistics collected about fast path decisions for observability.
+ */
+export interface FastPathStats {
+    /** Total number of routes analyzed. */
+    totalRoutes: number;
+    /** Number of routes eligible for fast path. */
+    fastPathRoutes: number;
+    /** Number of routes using full path. */
+    fullPathRoutes: number;
+    /** Per-route eligibility details. */
+    routes: ReadonlyArray<Readonly<FastPathEligibility>>;
+}
+/**
+ * Symbol used to attach fast path eligibility metadata to handler descriptors.
+ * @internal
+ */
+export declare const FAST_PATH_ELIGIBILITY_SYMBOL: unique symbol;
+/**
+ * Symbol used to attach fast path execution stats to dispatcher.
+ * @internal
+ */
+export declare const FAST_PATH_STATS_SYMBOL: unique symbol;
+//# sourceMappingURL=eligibility.d.ts.map

package/dist/dispatch/fast-path/eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IAEjC,8DAA8D;IAC9D,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IAErC,yDAAyD;IACzD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IAEtC,iDAAiD;IACjD,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IAEvC,kEAAkE;IAClE,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;IAE5C,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAE/B,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IAEpB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IAEvB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IAEvB,qCAAqC;IACrC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC;CACtD;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,eAAgC,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,sBAAsB,eAA0B,CAAC"}

package/dist/dispatch/fast-path/eligibility.js

@@ -0,0 +1,23 @@
+/**
+ * Per-route capability model used to decide whether a route can safely bypass
+ * optional framework overhead and execute through the fast path.
+ *
+ * Fast path selection is automatic and conservative: if safety cannot be proven,
+ * the route uses the full path with all framework features enabled.
+ */
+
+/**
+ * Statistics collected about fast path decisions for observability.
+ */
+
+/**
+ * Symbol used to attach fast path eligibility metadata to handler descriptors.
+ * @internal
+ */
+export const FAST_PATH_ELIGIBILITY_SYMBOL = Symbol('fastPathEligibility');
+
+/**
+ * Symbol used to attach fast path execution stats to dispatcher.
+ * @internal
+ */
+export const FAST_PATH_STATS_SYMBOL = Symbol('fastPathStats');

package/dist/dispatch/fast-path/fast-path-executor.d.ts

@@ -0,0 +1,21 @@
+import type { RequestScopeContainer } from '@fluojs/di';
+import { type ResolvedContentNegotiation } from '../dispatch-response-policy.js';
+import type { Binder, FrameworkRequest, FrameworkResponse, HandlerDescriptor, RequestContext } from '../../types.js';
+import type { FastPathExecutionResult } from './eligibility-checker.js';
+interface ExecuteFastPathOptions {
+    binder?: Binder;
+    contentNegotiation?: ResolvedContentNegotiation;
+    controllerContainer: RequestScopeContainer;
+    controller?: object;
+    handler: HandlerDescriptor;
+    method?: (this: object, input: unknown, requestContext: RequestContext) => unknown;
+    request: FrameworkRequest;
+    requestContext: RequestContext;
+    response: FrameworkResponse;
+}
+export declare function executeFastPath(options: ExecuteFastPathOptions): Promise<FastPathExecutionResult>;
+export declare function shouldUseFastPathForRequest(eligibility: {
+    executionPath: 'fast' | 'full';
+} | undefined, request: FrameworkRequest): boolean;
+export {};
+//# sourceMappingURL=fast-path-executor.d.ts.map

package/dist/dispatch/fast-path/fast-path-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fast-path-executor.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/fast-path-executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOxD,OAAO,EAAE,KAAK,0BAA0B,EAAwB,MAAM,gCAAgC,CAAC;AACvG,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AASxE,UAAU,sBAAsB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IAChD,mBAAmB,EAAE,qBAAqB,CAAC;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,KAAK,OAAO,CAAC;IACnF,OAAO,EAAE,gBAAgB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAoDlC;AASD,wBAAgB,2BAA2B,CACzC,WAAW,EAAE;IAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,SAAS,EAC3D,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAWT"}

package/dist/dispatch/fast-path/fast-path-executor.js

@@ -0,0 +1,80 @@
+import { DefaultBinder } from '../../adapters/binding.js';
+import { getCompiledDtoBindingPlan } from '../../adapters/dto-binding-plan.js';
+import { HttpDtoValidationAdapter } from '../../adapters/dto-validation-adapter.js';
+import { SseResponse } from '../../context/sse.js';
+import { RequestAbortedError } from '../../errors.js';
+import { writeSuccessResponse } from '../dispatch-response-policy.js';
+const defaultBinder = new DefaultBinder();
+const defaultValidator = new HttpDtoValidationAdapter();
+export async function executeFastPath(options) {
+  const {
+    binder,
+    contentNegotiation,
+    controllerContainer,
+    handler,
+    request,
+    requestContext,
+    response
+  } = options;
+  try {
+    const controller = options.controller ?? (await controllerContainer.resolve(handler.controllerToken));
+    const method = options.method ?? controller[handler.methodName];
+    if (typeof method !== 'function') {
+      return {
+        error: new Error(`Controller ${handler.controllerToken.name} does not expose handler method ${handler.methodName}.`),
+        executed: false
+      };
+    }
+    const requestDto = handler.route.request;
+    let input;
+    if (requestDto) {
+      const bindingPlan = getCompiledDtoBindingPlan(requestDto);
+      const activeBinder = binder ?? defaultBinder;
+      input = await activeBinder.bind(requestDto, {
+        handler,
+        requestContext
+      });
+      if (bindingPlan.needsValidation) {
+        await defaultValidator.validate(input, requestDto);
+      }
+    }
+    const maybeResult = method.call(controller, input, requestContext);
+    const result = isThenable(maybeResult) ? await maybeResult : maybeResult;
+    if (isRequestAborted(request)) {
+      throw new RequestAbortedError();
+    }
+    if (!(result instanceof SseResponse) && !response.committed) {
+      const writeResult = writeSuccessResponse(handler, request, response, result, contentNegotiation);
+      if (isThenable(writeResult)) {
+        await writeResult;
+      }
+    }
+    return {
+      executed: true,
+      result
+    };
+  } catch (error) {
+    return {
+      error,
+      executed: false
+    };
+  }
+}
+function isThenable(value) {
+  return typeof value === 'object' && value !== null && 'then' in value && typeof value.then === 'function';
+}
+export function shouldUseFastPathForRequest(eligibility, request) {
+  if (!eligibility) {
+    return false;
+  }
+  if (eligibility.executionPath !== 'fast') {
+    return false;
+  }
+  if (isRequestAborted(request)) {
+    return false;
+  }
+  return true;
+}
+function isRequestAborted(request) {
+  return request.isAborted?.() ?? request.signal?.aborted === true;
+}

package/dist/dispatch/fast-path/index.d.ts

@@ -0,0 +1,6 @@
+export type { FastPathEligibility, FastPathStats } from './eligibility.js';
+export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL } from './eligibility.js';
+export { compileFastPathEligibility, getHandlerFastPathEligibility, setHandlerFastPathEligibility, type FastPathExecutionResult, } from './eligibility-checker.js';
+export { executeFastPath, shouldUseFastPathForRequest } from './fast-path-executor.js';
+export { addPathDebugHeader, createFastPathStats, createPathDebugInfo, formatFastPathStats, } from './debug-visibility.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dispatch/fast-path/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,6BAA6B,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/dispatch/fast-path/index.js

@@ -0,0 +1,4 @@
+export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL } from './eligibility.js';
+export { compileFastPathEligibility, getHandlerFastPathEligibility, setHandlerFastPathEligibility } from './eligibility-checker.js';
+export { executeFastPath, shouldUseFastPathForRequest } from './fast-path-executor.js';
+export { addPathDebugHeader, createFastPathStats, createPathDebugInfo, formatFastPathStats } from './debug-visibility.js';

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":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA2BlE,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,97 @@
+const FRAMEWORK_REQUEST_NATIVE_ROUTE_HANDOFF = Symbol('fluo.http.nativeRouteHandoff');
+const RAW_REQUEST_NATIVE_ROUTE_HANDOFFS = new WeakMap();
+const EMPTY_ROUTE_PARAMS = Object.freeze({});
+function cloneNativeRouteHandoff(handoff) {
+  return {
+    descriptor: handoff.descriptor,
+    params: cloneRouteParams(handoff.params)
+  };
+}
+function cloneRouteParams(params) {
+  return Object.keys(params).length === 0 ? EMPTY_ROUTE_PARAMS : {
+    ...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 path.length > 1 && path.endsWith('/') || path.includes('//');
+}

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/index.d.ts

@@ -3,6 +3,8 @@ export * from './middleware/correlation.js';
 export * from './middleware/cors.js';
 export { All, Controller, Convert, Delete, FromBody, FromCookie, FromHeader, FromPath, FromQuery, Get, Head, Header, HttpCode, Optional, Options, Patch, Post, Produces, Put, Redirect, RequestDto, UseGuards, UseInterceptors, Version, } from './decorators.js';
 export * from './dispatch/dispatcher.js';
+export type { FastPathEligibility, FastPathStats } from './dispatch/fast-path/index.js';
+export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL, formatFastPathStats, getDispatcherFastPathStats, } from './dispatch/dispatcher.js';
 export * from './errors.js';
 export * from './exceptions.js';
 export * from './mapping.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,GAAG,EACH,UAAU,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,UAAU,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,IAAI,EACJ,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,GAAG,EACH,QAAQ,EACR,UAAU,EACV,SAAS,EACT,eAAe,EACf,OAAO,GACR,MAAM,iBAAiB,CAAC;AACzB,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,GAAG,EACH,UAAU,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,UAAU,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,IAAI,EACJ,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,GAAG,EACH,QAAQ,EACR,UAAU,EACV,SAAS,EACT,eAAe,EACf,OAAO,GACR,MAAM,iBAAiB,CAAC;AACzB,cAAc,0BAA0B,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACxF,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -3,6 +3,7 @@ export * from './middleware/correlation.js';
 export * from './middleware/cors.js';
 export { All, Controller, Convert, Delete, FromBody, FromCookie, FromHeader, FromPath, FromQuery, Get, Head, Header, HttpCode, Optional, Options, Patch, Post, Produces, Put, Redirect, RequestDto, UseGuards, UseInterceptors, Version } from './decorators.js';
 export * from './dispatch/dispatcher.js';
+export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL, formatFastPathStats, getDispatcherFastPathStats } from './dispatch/dispatcher.js';
 export * from './errors.js';
 export * from './exceptions.js';
 export * from './mapping.js';

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"}

package/dist/input-error-detail.js

@@ -1,3 +1,13 @@
+/**
+ * Describes the input error detail contract.
+ */
+
+/**
+ * To input error detail.
+ *
+ * @param detail The detail.
+ * @returns The to input error detail result.
+ */
 export function toInputErrorDetail(detail) {
   return {
     code: detail.code,

package/dist/interceptors.d.ts

@@ -1,3 +1,11 @@
 import type { InterceptorContext, InterceptorLike } from './types.js';
+/**
+ * Run interceptor chain.
+ *
+ * @param definitions The definitions.
+ * @param context The context.
+ * @param terminal The terminal.
+ * @returns The run interceptor chain result.
+ */
 export declare function runInterceptorChain(definitions: InterceptorLike[], context: InterceptorContext, terminal: () => Promise<unknown>): Promise<unknown>;
 //# sourceMappingURL=interceptors.d.ts.map