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

package/dist/context/sse.d.ts

@@ -1,11 +1,35 @@
 import type { RequestContext } from '../types.js';
+/** Options that customize the fields emitted for one server-sent event frame. */
 export interface SseSendOptions {
+    /** Optional SSE event name. Newline characters are stripped before writing. */
     event?: string;
+    /** Optional SSE event id. Newline characters are stripped before writing. */
     id?: string | number;
+    /** Optional client retry delay in milliseconds. Non-finite or negative values are ignored. */
     retry?: number;
 }
+/**
+ * Encodes a comment as a canonical server-sent event comment frame.
+ *
+ * @param comment Comment text to split into SSE comment lines.
+ * @returns A complete SSE comment frame ending in a blank line.
+ */
 export declare function encodeSseComment(comment: string): string;
+/**
+ * Encodes data and optional event fields as a server-sent event message frame.
+ *
+ * @param data Payload to write. Strings are sent as-is; other values are JSON serialized.
+ * @param options Optional event metadata fields.
+ * @returns A complete SSE message frame ending in a blank line.
+ * @throws {TypeError} When `data` cannot be represented as an SSE data field.
+ */
 export declare function encodeSseMessage(data: unknown, options?: SseSendOptions): string;
+/**
+ * Response helper for server-sent event streams backed by an adapter-provided response stream.
+ *
+ * The helper commits SSE headers immediately, closes idempotently on request abort
+ * or raw stream close, and removes all registered close/abort listeners during cleanup.
+ */
 export declare class SseResponse {
     private readonly context;
     private closed;
@@ -13,8 +37,22 @@ export declare class SseResponse {
     private removeCloseListener?;
     private readonly onAbort;
     constructor(context: RequestContext);
+    /**
+     * Writes one SSE data message when the stream is still open.
+     *
+     * @param data Payload to encode into `data:` lines.
+     * @param options Optional event metadata fields.
+     * @returns `true` when the underlying stream accepted the frame without backpressure.
+     */
     send(data: unknown, options?: SseSendOptions): boolean;
+    /**
+     * Writes one SSE comment frame when the stream is still open.
+     *
+     * @param comment Comment text to encode.
+     * @returns `true` when the underlying stream accepted the frame without backpressure.
+     */
     comment(comment: string): boolean;
+    /** Closes the SSE stream and removes registered abort/close listeners exactly once. */
     close(): void;
     private writeFrame;
 }

package/dist/context/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/context/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8C,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9F,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAoCD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAoBpF;AAED,qBAAa,WAAW;IASV,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,mBAAmB,CAAC,CAAa;IAEzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAEtB;gBAE2B,OAAO,EAAE,cAAc;IA0BpD,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO;IAI1D,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIjC,KAAK,IAAI,IAAI;IAiBb,OAAO,CAAC,UAAU;CAYnB"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/context/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8C,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9F,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,8FAA8F;IAC9F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAoCD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAoBpF;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IASV,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,mBAAmB,CAAC,CAAa;IAEzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAEtB;gBAE2B,OAAO,EAAE,cAAc;IAmCpD;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO;IAI1D;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIjC,uFAAuF;IACvF,KAAK,IAAI,IAAI;IAiBb,OAAO,CAAC,UAAU;CAYnB"}

package/dist/context/sse.js

@@ -1,3 +1,5 @@
+/** Options that customize the fields emitted for one server-sent event frame. */
+
 function sanitizeSseField(value) {
   return value.replace(/\r/g, '').replace(/\n/g, '');
 }
@@ -23,11 +25,27 @@ function resolveSseStream(response) {
   }
   return response.stream;
 }
+
+/**
+ * Encodes a comment as a canonical server-sent event comment frame.
+ *
+ * @param comment Comment text to split into SSE comment lines.
+ * @returns A complete SSE comment frame ending in a blank line.
+ */
 export function encodeSseComment(comment) {
   const lines = splitSseLines(comment);
   const encoded = lines.map(line => line.length === 0 ? ':' : `: ${line}`);
   return `${encoded.join('\n')}\n\n`;
 }
+
+/**
+ * Encodes data and optional event fields as a server-sent event message frame.
+ *
+ * @param data Payload to write. Strings are sent as-is; other values are JSON serialized.
+ * @param options Optional event metadata fields.
+ * @returns A complete SSE message frame ending in a blank line.
+ * @throws {TypeError} When `data` cannot be represented as an SSE data field.
+ */
 export function encodeSseMessage(data, options = {}) {
   const lines = [];
   if (options.event !== undefined) {
@@ -44,6 +62,13 @@ export function encodeSseMessage(data, options = {}) {
   }
   return `${lines.join('\n')}\n\n`;
 }
+
+/**
+ * Response helper for server-sent event streams backed by an adapter-provided response stream.
+ *
+ * The helper commits SSE headers immediately, closes idempotently on request abort
+ * or raw stream close, and removes all registered close/abort listeners during cleanup.
+ */
 export class SseResponse {
   closed = false;
   stream;
@@ -70,16 +95,39 @@ export class SseResponse {
     context.request.signal?.addEventListener('abort', this.onAbort, {
       once: true
     });
-    if (context.request.signal === undefined) {
-      this.removeCloseListener = this.stream.onClose?.(this.onAbort) ?? undefined;
+    const removeCloseListener = this.stream.onClose?.(this.onAbort) ?? undefined;
+    if (this.closed) {
+      removeCloseListener?.();
+      return;
+    }
+    this.removeCloseListener = removeCloseListener;
+    if (this.stream.closed) {
+      this.close();
     }
   }
+
+  /**
+   * Writes one SSE data message when the stream is still open.
+   *
+   * @param data Payload to encode into `data:` lines.
+   * @param options Optional event metadata fields.
+   * @returns `true` when the underlying stream accepted the frame without backpressure.
+   */
   send(data, options = {}) {
     return this.writeFrame(encodeSseMessage(data, options));
   }
+
+  /**
+   * Writes one SSE comment frame when the stream is still open.
+   *
+   * @param comment Comment text to encode.
+   * @returns `true` when the underlying stream accepted the frame without backpressure.
+   */
   comment(comment) {
     return this.writeFrame(encodeSseComment(comment));
   }
+
+  /** Closes the SSE stream and removes registered abort/close listeners exactly once. */
   close() {
     if (this.closed) {
       return;

package/dist/decorators.d.ts.map

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

package/dist/decorators.js

@@ -1,8 +1,11 @@
-import { 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);
@@ -77,29 +187,55 @@ function mergeStandardDtoBinding(metadata, propertyKey, partial) {
 function createRouteDecorator(method) {
   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;
+        return;
+      }
+      if (isMetadataPropertyKey(contextOrPropertyKey)) {
+        mergeLegacyRouteMetadata(valueOrTarget, contextOrPropertyKey, {
+          method,
+          path
+        });
+      }
     };
     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 +249,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 +268,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;
 }
@@ -233,9 +389,9 @@ export const HttpCode = createRouteValueDecorator((record, status) => {
  * @returns A defensive copy of declared media types, or `undefined` when not configured.
  */
 export function getRouteProducesMetadata(controllerToken, propertyKey) {
-  const bag = controllerToken[metadataSymbol];
+  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 +437,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 +460,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 +484,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 +508,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 +535,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 +564,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;
     }
-    const route = getStandardRouteRecord(context.metadata, context.name);
-    route.interceptors = mergeUnique(route.interceptors, interceptors);
+    if (isMetadataPropertyKey(contextOrPropertyKey)) {
+      appendLegacyRouteInterceptors(target, contextOrPropertyKey, interceptors);
+      return;
+    }
+    if (typeof target === 'function') {
+      appendLegacyControllerInterceptors(target, interceptors);
+    }
   };
   return decorator;
 }

package/dist/dispatch/dispatch-content-negotiation.d.ts

@@ -1,9 +1,26 @@
 import type { ContentNegotiationOptions, FrameworkRequest, HandlerDescriptor, ResponseFormatter } from '../types.js';
+/**
+ * Describes the resolved content negotiation contract.
+ */
 export interface ResolvedContentNegotiation {
     defaultFormatter: ResponseFormatter;
     formatters: ResponseFormatter[];
     normalizedMediaTypes: string[];
 }
+/**
+ * Resolve content negotiation.
+ *
+ * @param options The options.
+ * @returns The resolve content negotiation result.
+ */
 export declare function resolveContentNegotiation(options: ContentNegotiationOptions | undefined): ResolvedContentNegotiation | undefined;
+/**
+ * Select response formatter.
+ *
+ * @param handler The handler.
+ * @param request The request.
+ * @param contentNegotiation The content negotiation.
+ * @returns The select response formatter result.
+ */
 export declare function selectResponseFormatter(handler: HandlerDescriptor, request: FrameworkRequest, contentNegotiation: ResolvedContentNegotiation): ResponseFormatter;
 //# sourceMappingURL=dispatch-content-negotiation.d.ts.map

package/dist/dispatch/dispatch-content-negotiation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-content-negotiation.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-content-negotiation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAQrB,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,iBAAiB,CAAC;IACpC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AA2GD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,yBAAyB,GAAG,SAAS,GAAG,0BAA0B,GAAG,SAAS,CA+BhI;AAqCD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,EAAE,0BAA0B,GAC7C,iBAAiB,CA2CnB"}
+{"version":3,"file":"dispatch-content-negotiation.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-content-negotiation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAQrB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,iBAAiB,CAAC;IACpC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AA2GD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,yBAAyB,GAAG,SAAS,GAAG,0BAA0B,GAAG,SAAS,CA+BhI;AAqCD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,EAAE,0BAA0B,GAC7C,iBAAiB,CA2CnB"}

package/dist/dispatch/dispatch-content-negotiation.js

@@ -1,4 +1,9 @@
 import { NotAcceptableException } from '../exceptions.js';
+
+/**
+ * Describes the resolved content negotiation contract.
+ */
+
 const NO_ACCEPTABLE_REPRESENTATION_MESSAGE = 'No acceptable response representation found.';
 function normalizeMediaType(value) {
   return value.split(';')[0]?.trim().toLowerCase() ?? '';
@@ -77,6 +82,13 @@ function matchesMediaRange(mediaRange, mediaType) {
   }
   return rangeSubtype === '*' || rangeSubtype === mediaTypeSubtype;
 }
+
+/**
+ * Resolve content negotiation.
+ *
+ * @param options The options.
+ * @returns The resolve content negotiation result.
+ */
 export function resolveContentNegotiation(options) {
   if (!options?.formatters?.length) {
     return undefined;
@@ -128,6 +140,15 @@ function resolveDefaultFormatter(allowedFormatters, allowedNormalizedMediaTypes,
   const idx = allowedNormalizedMediaTypes.indexOf(defaultMediaType);
   return idx >= 0 ? allowedFormatters[idx] : allowedFormatters[0] ?? contentNegotiation.defaultFormatter;
 }
+
+/**
+ * Select response formatter.
+ *
+ * @param handler The handler.
+ * @param request The request.
+ * @param contentNegotiation The content negotiation.
+ * @returns The select response formatter result.
+ */
 export function selectResponseFormatter(handler, request, contentNegotiation) {
   const {
     formatters: allowedFormatters,

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

@@ -1,3 +1,11 @@
 import type { FrameworkResponse } from '../types.js';
+/**
+ * Write error response.
+ *
+ * @param error The error.
+ * @param response The response.
+ * @param requestId The request id.
+ * @returns The write error response result.
+ */
 export declare function writeErrorResponse(error: unknown, response: FrameworkResponse, requestId?: string): Promise<void>;
 //# sourceMappingURL=dispatch-error-policy.d.ts.map