@fluojs/http 1.0.0-beta.9 → 1.1.0

package/dist/decorators.js

@@ -1,8 +1,11 @@
-import { getStandardMetadataBag as readStandardMetadataBag, metadataSymbol } from '@fluojs/core/internal';
+import { defineControllerMetadata, defineDtoFieldBindingMetadata, defineRouteMetadata, ensureMetadataSymbol, getControllerMetadata, getDtoFieldBindingMetadata, getRouteMetadata, getStandardMetadataBag as readStandardMetadataBag } from '@fluojs/core/internal';
 import { validateRoutePath } from './route-path.js';
 const standardControllerMetadataKey = Symbol.for('fluo.standard.controller');
 const standardRouteMetadataKey = Symbol.for('fluo.standard.route');
 const standardDtoBindingMetadataKey = Symbol.for('fluo.standard.dto-binding');
+const legacyRouteMetadataStore = new WeakMap();
+const legacyDtoBindingMetadataStore = new WeakMap();
+ensureMetadataSymbol();
 function normalizeProducesMediaTypes(mediaTypes) {
   const normalized = [];
   for (const mediaType of mediaTypes) {
@@ -24,8 +27,115 @@ function mergeUnique(existing, values) {
   return merged;
 }
 function getStandardMetadataBag(metadata) {
-  void metadataSymbol;
-  return metadata;
+  return typeof metadata === 'object' && metadata !== null ? metadata : {};
+}
+function isStandardDecoratorContext(value) {
+  return typeof value === 'object' && value !== null && 'kind' in value && 'name' in value;
+}
+function isMetadataPropertyKey(value) {
+  return typeof value === 'string' || typeof value === 'symbol';
+}
+function getLegacyRouteRecord(target, propertyKey) {
+  let routeMap = legacyRouteMetadataStore.get(target);
+  if (!routeMap) {
+    routeMap = new Map();
+    legacyRouteMetadataStore.set(target, routeMap);
+  }
+  let record = routeMap.get(propertyKey);
+  if (!record) {
+    record = {};
+    routeMap.set(propertyKey, record);
+  }
+  return record;
+}
+function flushLegacyRouteMetadata(target, propertyKey, record) {
+  if (!record.method || record.path === undefined) {
+    return;
+  }
+  const existing = getRouteMetadata(target, propertyKey);
+  const metadata = {
+    guards: mergeUnique(existing?.guards, record.guards ?? []),
+    headers: record.headers ?? existing?.headers,
+    interceptors: mergeUnique(existing?.interceptors, record.interceptors ?? []),
+    method: record.method,
+    path: record.path,
+    redirect: record.redirect ?? existing?.redirect,
+    request: record.request ?? existing?.request,
+    successStatus: record.successStatus ?? existing?.successStatus,
+    version: record.version ?? existing?.version
+  };
+  defineRouteMetadata(target, propertyKey, metadata);
+}
+function mergeLegacyRouteMetadata(target, propertyKey, partial) {
+  const record = getLegacyRouteRecord(target, propertyKey);
+  Object.assign(record, partial);
+  flushLegacyRouteMetadata(target, propertyKey, record);
+}
+function defineLegacyControllerMetadata(target, partial) {
+  const existing = getControllerMetadata(target);
+  defineControllerMetadata(target, {
+    basePath: partial.basePath ?? existing?.basePath ?? '',
+    guards: partial.guards ?? existing?.guards,
+    interceptors: partial.interceptors ?? existing?.interceptors,
+    version: partial.version ?? existing?.version
+  });
+}
+function getLegacyDtoBindingRecord(target, propertyKey) {
+  let bindingMap = legacyDtoBindingMetadataStore.get(target);
+  if (!bindingMap) {
+    bindingMap = new Map();
+    legacyDtoBindingMetadataStore.set(target, bindingMap);
+  }
+  let record = bindingMap.get(propertyKey);
+  if (!record) {
+    record = {};
+    bindingMap.set(propertyKey, record);
+  }
+  return record;
+}
+function mergeLegacyDtoBinding(target, propertyKey, partial) {
+  const record = getLegacyDtoBindingRecord(target, propertyKey);
+  Object.assign(record, partial);
+  const source = record.source ?? getDtoFieldBindingMetadata(target, propertyKey)?.source;
+  if (!source) {
+    return;
+  }
+  defineDtoFieldBindingMetadata(target, propertyKey, {
+    converter: record.converter,
+    key: record.key,
+    optional: record.optional,
+    source
+  });
+}
+function appendLegacyRouteHeader(target, propertyKey, name, value) {
+  const record = getLegacyRouteRecord(target, propertyKey);
+  record.headers = [...(record.headers ?? []), {
+    name,
+    value
+  }];
+  flushLegacyRouteMetadata(target, propertyKey, record);
+}
+function appendLegacyControllerGuards(target, guards) {
+  const existing = getControllerMetadata(target);
+  defineLegacyControllerMetadata(target, {
+    guards: mergeUnique(existing?.guards, guards)
+  });
+}
+function appendLegacyControllerInterceptors(target, interceptors) {
+  const existing = getControllerMetadata(target);
+  defineLegacyControllerMetadata(target, {
+    interceptors: mergeUnique(existing?.interceptors, interceptors)
+  });
+}
+function appendLegacyRouteGuards(target, propertyKey, guards) {
+  const record = getLegacyRouteRecord(target, propertyKey);
+  record.guards = mergeUnique(record.guards, guards);
+  flushLegacyRouteMetadata(target, propertyKey, record);
+}
+function appendLegacyRouteInterceptors(target, propertyKey, interceptors) {
+  const record = getLegacyRouteRecord(target, propertyKey);
+  record.interceptors = mergeUnique(record.interceptors, interceptors);
+  flushLegacyRouteMetadata(target, propertyKey, record);
 }
 function getStandardControllerRecord(metadata) {
   const bag = getStandardMetadataBag(metadata);
@@ -74,32 +184,65 @@ function mergeStandardDtoBinding(metadata, propertyKey, partial) {
     ...partial
   });
 }
-function createRouteDecorator(method) {
+function createRouteDecorator(method, produces) {
   return path => {
     validateRoutePath(path, `@${method}() path`);
-    const decorator = (_value, context) => {
-      const route = getStandardRouteRecord(context.metadata, context.name);
-      route.method = method;
-      route.path = path;
+    const decorator = (valueOrTarget, contextOrPropertyKey) => {
+      if (isStandardDecoratorContext(contextOrPropertyKey)) {
+        const route = getStandardRouteRecord(contextOrPropertyKey.metadata, contextOrPropertyKey.name);
+        route.method = method;
+        route.path = path;
+        if (produces) {
+          route.produces = normalizeProducesMediaTypes(produces);
+        }
+        return;
+      }
+      if (isMetadataPropertyKey(contextOrPropertyKey)) {
+        const routeMetadata = {
+          method,
+          path
+        };
+        if (produces) {
+          routeMetadata.produces = normalizeProducesMediaTypes(produces);
+        }
+        mergeLegacyRouteMetadata(valueOrTarget, contextOrPropertyKey, routeMetadata);
+      }
     };
     return decorator;
   };
 }
 function createRouteValueDecorator(apply) {
   return value => {
-    const decorator = (_target, context) => {
-      apply(getStandardRouteRecord(context.metadata, context.name), value);
+    const decorator = (valueOrTarget, contextOrPropertyKey) => {
+      if (isStandardDecoratorContext(contextOrPropertyKey)) {
+        apply(getStandardRouteRecord(contextOrPropertyKey.metadata, contextOrPropertyKey.name), value);
+        return;
+      }
+      if (isMetadataPropertyKey(contextOrPropertyKey)) {
+        const record = getLegacyRouteRecord(valueOrTarget, contextOrPropertyKey);
+        apply(record, value);
+        flushLegacyRouteMetadata(valueOrTarget, contextOrPropertyKey, record);
+      }
     };
     return decorator;
   };
 }
 function createDtoFieldDecorator(source) {
   return key => {
-    const decorator = (_value, context) => {
-      mergeStandardDtoBinding(context.metadata, context.name, {
-        key,
-        source
-      });
+    const decorator = (valueOrTarget, contextOrPropertyKey) => {
+      if (isStandardDecoratorContext(contextOrPropertyKey)) {
+        mergeStandardDtoBinding(contextOrPropertyKey.metadata, contextOrPropertyKey.name, {
+          key,
+          source
+        });
+        return;
+      }
+      if (isMetadataPropertyKey(contextOrPropertyKey) && valueOrTarget && typeof valueOrTarget === 'object') {
+        mergeLegacyDtoBinding(valueOrTarget, contextOrPropertyKey, {
+          key,
+          source
+        });
+      }
     };
     return decorator;
   };
@@ -113,8 +256,14 @@ function createDtoFieldDecorator(source) {
  */
 export function Controller(basePath = '') {
   validateRoutePath(basePath, '@Controller() base path');
-  const decorator = (_target, context) => {
-    getStandardControllerRecord(context.metadata).basePath = basePath;
+  const decorator = (target, context) => {
+    if (isStandardDecoratorContext(context)) {
+      getStandardControllerRecord(context.metadata).basePath = basePath;
+      return;
+    }
+    defineLegacyControllerMetadata(target, {
+      basePath
+    });
   };
   return decorator;
 }
@@ -126,12 +275,26 @@ export function Controller(basePath = '') {
  * @returns A decorator that applies version metadata at class or method scope.
  */
 export function Version(version) {
-  const decorator = (_target, context) => {
-    if (context.kind === 'class') {
-      getStandardControllerRecord(context.metadata).version = version;
+  const decorator = (target, contextOrPropertyKey) => {
+    if (isStandardDecoratorContext(contextOrPropertyKey)) {
+      if (contextOrPropertyKey.kind === 'class') {
+        getStandardControllerRecord(contextOrPropertyKey.metadata).version = version;
+        return;
+      }
+      getStandardRouteRecord(contextOrPropertyKey.metadata, contextOrPropertyKey.name).version = version;
       return;
     }
-    getStandardRouteRecord(context.metadata, context.name).version = version;
+    if (isMetadataPropertyKey(contextOrPropertyKey)) {
+      mergeLegacyRouteMetadata(target, contextOrPropertyKey, {
+        version
+      });
+      return;
+    }
+    if (typeof target === 'function') {
+      defineLegacyControllerMetadata(target, {
+        version
+      });
+    }
   };
   return decorator;
 }
@@ -143,6 +306,16 @@ export function Version(version) {
  * @returns A method decorator that registers a `GET` handler mapping.
  */
 export const Get = createRouteDecorator('GET');
+/**
+ * Registers a server-sent events route handler as `GET` with `text/event-stream` produces metadata.
+ *
+ * @param path Route path relative to the controller base path.
+ * @returns A method decorator that registers a `GET` SSE handler mapping.
+ *
+ * @remarks
+ * Handlers may return `SseResponse` for manual control or `AsyncIterable<SseMessage<T> | T>` for managed dispatcher streaming.
+ */
+export const Sse = createRouteDecorator('GET', ['text/event-stream']);
 /**
  * Registers a `POST` route handler.
  *
@@ -235,7 +408,7 @@ export const HttpCode = createRouteValueDecorator((record, status) => {
 export function getRouteProducesMetadata(controllerToken, propertyKey) {
   const bag = readStandardMetadataBag(controllerToken);
   const routeMap = bag?.[standardRouteMetadataKey];
-  const produces = routeMap?.get(propertyKey)?.produces;
+  const produces = routeMap?.get(propertyKey)?.produces ?? legacyRouteMetadataStore.get(controllerToken.prototype)?.get(propertyKey)?.produces;
   return produces ? [...produces] : undefined;
 }
 
@@ -281,10 +454,18 @@ export const FromBody = createDtoFieldDecorator('body');
  * @returns A field decorator that marks the DTO binding as optional.
  */
 export function Optional() {
-  const decorator = (_value, context) => {
-    mergeStandardDtoBinding(context.metadata, context.name, {
-      optional: true
-    });
+  const decorator = (valueOrTarget, contextOrPropertyKey) => {
+    if (isStandardDecoratorContext(contextOrPropertyKey)) {
+      mergeStandardDtoBinding(contextOrPropertyKey.metadata, contextOrPropertyKey.name, {
+        optional: true
+      });
+      return;
+    }
+    if (isMetadataPropertyKey(contextOrPropertyKey) && valueOrTarget && typeof valueOrTarget === 'object') {
+      mergeLegacyDtoBinding(valueOrTarget, contextOrPropertyKey, {
+        optional: true
+      });
+    }
   };
   return decorator;
 }
@@ -296,10 +477,18 @@ export function Optional() {
  * @returns A field decorator that stores converter metadata for the DTO field.
  */
 export function Convert(converter) {
-  const decorator = (_value, context) => {
-    mergeStandardDtoBinding(context.metadata, context.name, {
-      converter
-    });
+  const decorator = (valueOrTarget, contextOrPropertyKey) => {
+    if (isStandardDecoratorContext(contextOrPropertyKey)) {
+      mergeStandardDtoBinding(contextOrPropertyKey.metadata, contextOrPropertyKey.name, {
+        converter
+      });
+      return;
+    }
+    if (isMetadataPropertyKey(contextOrPropertyKey) && valueOrTarget && typeof valueOrTarget === 'object') {
+      mergeLegacyDtoBinding(valueOrTarget, contextOrPropertyKey, {
+        converter
+      });
+    }
   };
   return decorator;
 }
@@ -312,12 +501,18 @@ export function Convert(converter) {
  * @returns A method decorator that appends route-level response-header metadata.
  */
 export function Header(name, value) {
-  const decorator = (_target, context) => {
-    const route = getStandardRouteRecord(context.metadata, context.name);
-    route.headers = [...(route.headers ?? []), {
-      name,
-      value
-    }];
+  const decorator = (valueOrTarget, contextOrPropertyKey) => {
+    if (isStandardDecoratorContext(contextOrPropertyKey)) {
+      const route = getStandardRouteRecord(contextOrPropertyKey.metadata, contextOrPropertyKey.name);
+      route.headers = [...(route.headers ?? []), {
+        name,
+        value
+      }];
+      return;
+    }
+    if (isMetadataPropertyKey(contextOrPropertyKey)) {
+      appendLegacyRouteHeader(valueOrTarget, contextOrPropertyKey, name, value);
+    }
   };
   return decorator;
 }
@@ -330,11 +525,22 @@ export function Header(name, value) {
  * @returns A method decorator that writes redirect metadata for the route.
  */
 export function Redirect(url, statusCode) {
-  const decorator = (_target, context) => {
-    getStandardRouteRecord(context.metadata, context.name).redirect = {
-      url,
-      statusCode
-    };
+  const decorator = (valueOrTarget, contextOrPropertyKey) => {
+    if (isStandardDecoratorContext(contextOrPropertyKey)) {
+      getStandardRouteRecord(contextOrPropertyKey.metadata, contextOrPropertyKey.name).redirect = {
+        url,
+        statusCode
+      };
+      return;
+    }
+    if (isMetadataPropertyKey(contextOrPropertyKey)) {
+      mergeLegacyRouteMetadata(valueOrTarget, contextOrPropertyKey, {
+        redirect: {
+          url,
+          statusCode
+        }
+      });
+    }
   };
   return decorator;
 }
@@ -346,14 +552,24 @@ export function Redirect(url, statusCode) {
  * @returns A decorator applicable to classes and methods.
  */
 export function UseGuards(...guards) {
-  const decorator = (_target, context) => {
-    if (context.kind === 'class') {
-      const controller = getStandardControllerRecord(context.metadata);
-      controller.guards = mergeUnique(controller.guards, guards);
+  const decorator = (target, contextOrPropertyKey) => {
+    if (isStandardDecoratorContext(contextOrPropertyKey)) {
+      if (contextOrPropertyKey.kind === 'class') {
+        const controller = getStandardControllerRecord(contextOrPropertyKey.metadata);
+        controller.guards = mergeUnique(controller.guards, guards);
+        return;
+      }
+      const route = getStandardRouteRecord(contextOrPropertyKey.metadata, contextOrPropertyKey.name);
+      route.guards = mergeUnique(route.guards, guards);
+      return;
+    }
+    if (isMetadataPropertyKey(contextOrPropertyKey)) {
+      appendLegacyRouteGuards(target, contextOrPropertyKey, guards);
       return;
     }
-    const route = getStandardRouteRecord(context.metadata, context.name);
-    route.guards = mergeUnique(route.guards, guards);
+    if (typeof target === 'function') {
+      appendLegacyControllerGuards(target, guards);
+    }
   };
   return decorator;
 }
@@ -365,14 +581,24 @@ export function UseGuards(...guards) {
  * @returns A decorator applicable to classes and methods.
  */
 export function UseInterceptors(...interceptors) {
-  const decorator = (_target, context) => {
-    if (context.kind === 'class') {
-      const controller = getStandardControllerRecord(context.metadata);
-      controller.interceptors = mergeUnique(controller.interceptors, interceptors);
+  const decorator = (target, contextOrPropertyKey) => {
+    if (isStandardDecoratorContext(contextOrPropertyKey)) {
+      if (contextOrPropertyKey.kind === 'class') {
+        const controller = getStandardControllerRecord(contextOrPropertyKey.metadata);
+        controller.interceptors = mergeUnique(controller.interceptors, interceptors);
+        return;
+      }
+      const route = getStandardRouteRecord(contextOrPropertyKey.metadata, contextOrPropertyKey.name);
+      route.interceptors = mergeUnique(route.interceptors, interceptors);
+      return;
+    }
+    if (isMetadataPropertyKey(contextOrPropertyKey)) {
+      appendLegacyRouteInterceptors(target, contextOrPropertyKey, interceptors);
       return;
     }
-    const route = getStandardRouteRecord(context.metadata, context.name);
-    route.interceptors = mergeUnique(route.interceptors, interceptors);
+    if (typeof target === 'function') {
+      appendLegacyControllerInterceptors(target, interceptors);
+    }
   };
   return decorator;
 }

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,EAAyB,MAAM,YAAY,CAAC;AAQnE,OAAO,KAAK,EACV,MAAM,EACN,yBAAyB,EACzB,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAIjB,cAAc,EAEd,eAAe,EAEf,cAAc,EAId,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAKL,KAAK,aAAa,EAOnB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE5F,gEAAgE;AAChE,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,uDAAuD;AACvD,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,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,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,qDAAqD;IACrD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qDAAqD;IACrD,aAAa,EAAE,SAAS,CAAC;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAoyBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CAuF7E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAE5F;AAED,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,YAAY,CAAC;AAQnE,OAAO,KAAK,EACV,MAAM,EACN,yBAAyB,EACzB,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAKjB,cAAc,EAEd,eAAe,EAEf,cAAc,EAId,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAKL,KAAK,aAAa,EAOnB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE5F,gEAAgE;AAChE,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,uDAAuD;AACvD,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,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,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,qDAAqD;IACrD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qDAAqD;IACrD,aAAa,EAAE,SAAS,CAAC;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAy8BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CAuF7E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAE5F;AAED,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/dispatch/dispatcher.js

@@ -1,6 +1,6 @@
 import { getCompiledDtoBindingPlan } from '../adapters/dto-binding-plan.js';
 import { createRequestContext, runWithRequestContext } from '../context/request-context.js';
-import { SseResponse } from '../context/sse.js';
+import { SseResponse, isSseMessage } from '../context/sse.js';
 import { RequestAbortedError } from '../errors.js';
 import { runGuardChain } from '../guards.js';
 import { runInterceptorChain } from '../interceptors.js';
@@ -255,6 +255,140 @@ function ensureRequestNotAborted(request) {
 function isRequestAborted(request) {
   return request.isAborted?.() ?? request.signal?.aborted === true;
 }
+function isSseRoute(handler) {
+  return handler.route.produces?.some(mediaType => mediaType.toLowerCase().startsWith('text/event-stream')) === true;
+}
+function isAsyncIterable(value) {
+  return typeof value === 'object' && value !== null && Symbol.asyncIterator in value && typeof value[Symbol.asyncIterator] === 'function';
+}
+function createAbortPromise(request) {
+  if (!request.signal) {
+    return undefined;
+  }
+  if (request.signal.aborted) {
+    return {
+      cleanup: () => undefined,
+      promise: Promise.resolve('aborted')
+    };
+  }
+  let listener;
+  const promise = new Promise(resolve => {
+    listener = () => resolve('aborted');
+    request.signal?.addEventListener('abort', listener, {
+      once: true
+    });
+  });
+  return {
+    cleanup: () => {
+      if (listener) {
+        request.signal?.removeEventListener('abort', listener);
+      }
+    },
+    promise
+  };
+}
+function createStreamClosePromise(stream) {
+  if (stream.closed) {
+    return {
+      cleanup: () => undefined,
+      promise: Promise.resolve('aborted')
+    };
+  }
+  if (!stream.onClose) {
+    return undefined;
+  }
+  let cleanup;
+  const promise = new Promise(resolve => {
+    cleanup = stream.onClose?.(() => resolve('aborted')) ?? undefined;
+  });
+  return {
+    cleanup: () => {
+      cleanup?.();
+    },
+    promise
+  };
+}
+function createManagedSseStopPromise(request, stream) {
+  const stops = [createAbortPromise(request), createStreamClosePromise(stream)].filter(entry => entry !== undefined);
+  if (stops.length === 0) {
+    return undefined;
+  }
+  return {
+    cleanup: () => {
+      for (const stop of stops) {
+        stop.cleanup();
+      }
+    },
+    promise: Promise.race(stops.map(stop => stop.promise))
+  };
+}
+function resolveManagedSseFrame(value) {
+  if (isSseMessage(value)) {
+    const {
+      data,
+      event,
+      id,
+      retry
+    } = value;
+    return {
+      data,
+      options: {
+        event,
+        id,
+        retry
+      }
+    };
+  }
+  return {
+    data: value,
+    options: {}
+  };
+}
+function closeAsyncIteratorEventually(iterator) {
+  void iterator.return?.().catch(() => undefined);
+}
+async function readManagedSseNext(request, stream, iterator) {
+  const abort = createManagedSseStopPromise(request, stream);
+  if (!abort) {
+    return iterator.next();
+  }
+  try {
+    return await Promise.race([iterator.next(), abort.promise]);
+  } finally {
+    abort.cleanup();
+  }
+}
+async function writeManagedSseIterable(handler, requestContext, source) {
+  if (!isSseRoute(handler)) {
+    return false;
+  }
+  const sse = new SseResponse(requestContext);
+  const stream = requestContext.response.stream;
+  if (!stream) {
+    return true;
+  }
+  const iterator = source[Symbol.asyncIterator]();
+  try {
+    while (!isRequestAborted(requestContext.request)) {
+      const next = await readManagedSseNext(requestContext.request, stream, iterator);
+      if (next === 'aborted') {
+        closeAsyncIteratorEventually(iterator);
+        break;
+      }
+      if (next.done === true) {
+        break;
+      }
+      const frame = resolveManagedSseFrame(next.value);
+      const accepted = sse.send(frame.data, frame.options);
+      if (!accepted) {
+        await requestContext.response.stream?.waitForDrain?.();
+      }
+    }
+  } finally {
+    sse.close();
+  }
+  return true;
+}
 function resolveFastPathHandlerRuntimeCache(handler, cache) {
   const cached = cache.get(handler);
   if (cached) {
@@ -335,7 +469,9 @@ async function dispatchMatchedHandler(handler, executionPlan, requestContext, co
     requestContext
   }, async () => invokeControllerHandler(handler, requestContext, binder, controllerContainer));
   ensureRequestNotAborted(requestContext.request);
-  if (!(result instanceof SseResponse) && !requestContext.response.committed) {
+  if (isAsyncIterable(result) && (await writeManagedSseIterable(handler, requestContext, result))) {
+    // Managed SSE streams are already committed and closed by writeManagedSseIterable.
+  } else if (!(result instanceof SseResponse) && !requestContext.response.committed) {
     await writeSuccessResponse(handler, requestContext.request, requestContext.response, result, contentNegotiation);
   }
   await notifyObserversSafely(observers, requestContext, async (observer, context) => {
@@ -356,6 +492,10 @@ async function dispatchNativeFastRoute(match, request, response, options, conten
   if (!shouldUseFastPathForRequest(eligibility, request)) {
     return false;
   }
+  if (options.fastPathDebugHeaders === true && eligibility && !response.committed) {
+    const debugInfo = createPathDebugInfo(eligibility);
+    addPathDebugHeader(response.setHeader.bind(response), debugInfo);
+  }
   const dispatchRequest = request;
   const dispatchScope = createRootDispatchScope(options.rootContainer);
   let phaseContext;

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

@@ -6,13 +6,35 @@ interface CompiledEligibilityPlan {
     eligibility: FastPathEligibility;
     isEligible: boolean;
 }
+/**
+ * Compiles the conservative fast-path eligibility decision for one handler.
+ *
+ * @param handler Handler descriptor being analyzed.
+ * @param options Dispatcher options that can introduce full-path requirements.
+ * @param adapter Human-readable adapter label used in observability metadata.
+ * @returns The compiled eligibility metadata and boolean eligibility flag.
+ */
 export declare function compileFastPathEligibility(handler: HandlerDescriptor, options: CreateDispatcherOptions, adapter: string): CompiledEligibilityPlan;
+/**
+ * Reads fast-path eligibility metadata attached to a handler descriptor.
+ *
+ * @param handler Handler descriptor previously analyzed by the dispatcher.
+ * @returns The attached eligibility metadata, when present.
+ */
 export declare function getHandlerFastPathEligibility(handler: HandlerDescriptor): FastPathEligibility | undefined;
+/**
+ * Attaches fast-path eligibility metadata to a handler descriptor.
+ *
+ * @param handler Handler descriptor to annotate.
+ * @param eligibility Eligibility metadata to expose through dispatcher observability.
+ */
 export declare function setHandlerFastPathEligibility(handler: HandlerDescriptor, eligibility: FastPathEligibility): void;
+/** Options shared by fast-path executor helpers. */
 export interface FastPathExecutorOptions {
     binder?: Binder;
     rootContainer: Container;
 }
+/** Result returned after attempting fast-path handler execution. */
 export interface FastPathExecutionResult {
     executed: boolean;
     result?: unknown;

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

@@ -1 +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"}
+{"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;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,MAAM,GACd,uBAAuB,CAiEzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,GACzB,mBAAmB,GAAG,SAAS,CAIjC;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,mBAAmB,GAC/B,IAAI,CAGN;AAED,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,SAAS,CAAC;CAC1B;AAED,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}