@fluojs/http 1.1.2 → 3.0.0

package/dist/context/request-id.js

@@ -0,0 +1,27 @@
+import { getRequestHeader } from '../header-helpers.js';
+const REQUEST_ID_HEADER = 'x-request-id';
+const CORRELATION_ID_HEADER = 'x-correlation-id';
+function readInboundHeaderValue(request, headerName) {
+  const rawHeaderValue = getRequestHeader(request, headerName);
+  const value = Array.isArray(rawHeaderValue) ? rawHeaderValue[0] : rawHeaderValue;
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+}
+function createRequestId() {
+  const randomUUID = globalThis.crypto?.randomUUID;
+  if (randomUUID) {
+    return randomUUID.call(globalThis.crypto);
+  }
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+
+/**
+ * Resolves the request identity before dispatcher observers begin.
+ *
+ * @param request Adapter-normalized request carrying inbound correlation headers.
+ * @param generate Whether to generate an ID when neither supported inbound header is present.
+ * @returns The adopted request or legacy correlation ID, or a newly generated ID.
+ */
+export function resolveRequestId(request, generate = true) {
+  return readInboundHeaderValue(request, REQUEST_ID_HEADER) ?? readInboundHeaderValue(request, CORRELATION_ID_HEADER) ?? (generate ? createRequestId() : undefined);
+}

package/dist/context/sse.d.ts

@@ -53,6 +53,8 @@ export declare function encodeSseMessage(data: unknown, options?: SseSendOptions
 export declare class SseResponse {
     private readonly context;
     private closed;
+    private resolveCompletion;
+    private readonly completionPromise;
     private readonly stream;
     private removeCloseListener?;
     private readonly onAbort;
@@ -72,8 +74,19 @@ export declare class SseResponse {
      * @returns `true` when the underlying stream accepted the frame without backpressure.
      */
     comment(comment: string): boolean;
+    /** @internal Completion signal consumed by the dispatcher for manual SSE responses. */
+    get completion(): Promise<void>;
     /** Closes the SSE stream and removes registered abort/close listeners exactly once. */
     close(): void;
     private writeFrame;
 }
+/**
+ * Resolves after a manual SSE response closes through any supported termination path.
+ *
+ * @param response Manual SSE response whose lifecycle is observed.
+ * @returns A promise that resolves after the response closes.
+ *
+ * @internal
+ */
+export declare function waitForSseResponseCompletion(response: SseResponse): Promise<void>;
 //# sourceMappingURL=sse.d.ts.map

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,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;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,cAAc;IAC7D,4DAA4D;IAC5D,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,CAAC,CAAC,CAEhF;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"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/context/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8C,cAAc,EAAE,MAAM,aAAa,CAAC;AAG9F,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;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,cAAc;IAC7D,4DAA4D;IAC5D,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,CAAC,CAAC,CAEhF;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;IAcV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAbpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAE/B;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,mBAAmB,CAAC,CAAa;IAEzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGtB;gBAE2B,OAAO,EAAE,cAAc;IAoCpD;;;;;;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,IAAI,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9B;IAED,uFAAuF;IACvF,KAAK,IAAI,IAAI;IAoBb,OAAO,CAAC,UAAU;CAanB;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjF"}

package/dist/context/sse.js

@@ -1,3 +1,5 @@
+import { markRequestContextAborted } from '../dispatch/request-abort.js';
+
 /** Options that customize the fields emitted for one server-sent event frame. */
 
 /**
@@ -90,9 +92,14 @@ export function encodeSseMessage(data, options = {}) {
  */
 export class SseResponse {
   closed = false;
+  resolveCompletion = () => undefined;
+  completionPromise = new Promise(resolve => {
+    this.resolveCompletion = resolve;
+  });
   stream;
   removeCloseListener;
   onAbort = () => {
+    markRequestContextAborted(this.context);
     this.close();
   };
   constructor(context) {
@@ -121,6 +128,7 @@ export class SseResponse {
     }
     this.removeCloseListener = removeCloseListener;
     if (this.stream.closed) {
+      markRequestContextAborted(this.context);
       this.close();
     }
   }
@@ -146,28 +154,50 @@ export class SseResponse {
     return this.writeFrame(encodeSseComment(comment));
   }
 
+  /** @internal Completion signal consumed by the dispatcher for manual SSE responses. */
+  get completion() {
+    return this.completionPromise;
+  }
+
   /** Closes the SSE stream and removes registered abort/close listeners exactly once. */
   close() {
     if (this.closed) {
       return;
     }
     this.closed = true;
-    this.context.request.signal?.removeEventListener('abort', this.onAbort);
-    this.removeCloseListener?.();
-    this.removeCloseListener = undefined;
-    if (!this.stream.closed) {
-      this.stream.close();
+    try {
+      this.context.request.signal?.removeEventListener('abort', this.onAbort);
+      this.removeCloseListener?.();
+      this.removeCloseListener = undefined;
+      if (!this.stream.closed) {
+        this.stream.close();
+      }
+    } finally {
+      this.context.response.committed = true;
+      this.resolveCompletion();
     }
-    this.context.response.committed = true;
   }
   writeFrame(frame) {
     if (this.closed) {
       return false;
     }
     if (this.stream.closed) {
+      markRequestContextAborted(this.context);
       this.close();
       return false;
     }
     return this.stream.write(frame);
   }
+}
+
+/**
+ * Resolves after a manual SSE response closes through any supported termination path.
+ *
+ * @param response Manual SSE response whose lifecycle is observed.
+ * @returns A promise that resolves after the response closes.
+ *
+ * @internal
+ */
+export function waitForSseResponseCompletion(response) {
+  return response.completion;
 }

package/dist/cookie-helpers.d.ts

@@ -0,0 +1,47 @@
+import type { FrameworkResponse } from './types.js';
+/** SameSite policies supported by the portable cookie serializer. */
+export type CookieSameSite = 'lax' | 'none' | 'strict';
+/** Runtime-neutral attributes used when serializing one response cookie. */
+export interface CookieOptions {
+    /** Domain that scopes the cookie. */
+    readonly domain?: string;
+    /** Absolute expiry time for the cookie. */
+    readonly expires?: Date;
+    /** Whether the cookie is inaccessible to client-side scripts. */
+    readonly httpOnly?: boolean;
+    /** Lifetime in whole seconds. */
+    readonly maxAgeSeconds?: number;
+    /** URL path that scopes the cookie. */
+    readonly path?: string;
+    /** Cross-site request policy for the cookie. */
+    readonly sameSite?: CookieSameSite;
+    /** Whether the cookie is sent only over secure connections. */
+    readonly secure?: boolean;
+}
+/**
+ * Attributes accepted when clearing a cookie.
+ *
+ * Only `path` and `domain` identify the browser cookie to delete. `httpOnly`,
+ * `secure`, and `sameSite` are deletion attributes, not cookie identity keys.
+ */
+export type ClearCookieOptions = Omit<CookieOptions, 'expires' | 'maxAgeSeconds'>;
+/**
+ * Serialize one runtime-neutral response cookie as an independent `Set-Cookie` field.
+ *
+ * @param response Mutable response that receives the cookie header.
+ * @param name Cookie name, validated as an HTTP token.
+ * @param value Cookie value, percent-encoded before serialization.
+ * @param options Explicit cookie attributes shared by all supported adapters.
+ * @returns Nothing. The response receives one independent cookie field.
+ */
+export declare function setCookie(response: FrameworkResponse, name: string, value: string, options?: CookieOptions): void;
+/**
+ * Expire one runtime-neutral response cookie while retaining its matching scope attributes.
+ *
+ * @param response Mutable response that receives the deletion cookie header.
+ * @param name Cookie name, validated as an HTTP token.
+ * @param options Original Path and Domain attributes required to target the same cookie.
+ * @returns Nothing. The response receives one independent deletion cookie field.
+ */
+export declare function clearCookie(response: FrameworkResponse, name: string, options?: ClearCookieOptions): void;
+//# sourceMappingURL=cookie-helpers.d.ts.map

package/dist/cookie-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-helpers.d.ts","sourceRoot":"","sources":["../src/cookie-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAMpD,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,uCAAuC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,eAAe,CAAC,CAAC;AA8KlF;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,IAAI,CAEN;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,kBAAuB,GAC/B,IAAI,CAUN"}

package/dist/cookie-helpers.js

@@ -0,0 +1,166 @@
+const COOKIE_DELETION_EXPIRES = new Date(0);
+const COOKIE_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const COOKIE_DOMAIN = /^(?:\.)?(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+
+/** SameSite policies supported by the portable cookie serializer. */
+
+/** Runtime-neutral attributes used when serializing one response cookie. */
+
+/**
+ * Attributes accepted when clearing a cookie.
+ *
+ * Only `path` and `domain` identify the browser cookie to delete. `httpOnly`,
+ * `secure`, and `sameSite` are deletion attributes, not cookie identity keys.
+ */
+
+function readCookieOptions(options) {
+  const {
+    domain,
+    expires,
+    httpOnly,
+    maxAgeSeconds,
+    path,
+    sameSite,
+    secure
+  } = options;
+  return {
+    domain,
+    expires,
+    httpOnly,
+    maxAgeSeconds,
+    path,
+    sameSite,
+    secure
+  };
+}
+function validateCookieName(name) {
+  if (typeof name !== 'string' || !COOKIE_NAME_TOKEN.test(name)) {
+    throw new TypeError('Cookie names must be non-empty HTTP tokens.');
+  }
+}
+function validateOptionalBoolean(value, optionName) {
+  if (value !== undefined && typeof value !== 'boolean') {
+    throw new TypeError(`${optionName} must be a boolean when provided.`);
+  }
+}
+function validateDomain(domain) {
+  const host = domain.startsWith('.') ? domain.slice(1) : domain;
+  if (typeof domain !== 'string' || host.length === 0 || host.length > 253 || !COOKIE_DOMAIN.test(domain)) {
+    throw new TypeError('Cookie domains must be valid ASCII DNS names.');
+  }
+}
+function validatePath(path) {
+  if (typeof path !== 'string' || path.length === 0) {
+    throw new TypeError('Cookie paths must be non-empty RFC 6265 path values.');
+  }
+  for (const character of path) {
+    const codePoint = character.charCodeAt(0);
+    if (codePoint < 0x20 || codePoint === 0x3b || codePoint > 0x7e) {
+      throw new TypeError('Cookie paths must be RFC 6265 path values.');
+    }
+  }
+}
+function formatExpiry(expires) {
+  const timestamp = Date.prototype.getTime.call(expires);
+  if (!Number.isFinite(timestamp)) {
+    throw new TypeError('Cookie expiry must be a valid Date.');
+  }
+  const normalized = new Date(timestamp);
+  const year = normalized.getUTCFullYear();
+  if (year < 1601 || year > 9999) {
+    throw new TypeError('Cookie expiry must have a four-digit RFC 6265 year.');
+  }
+  return normalized.toUTCString();
+}
+function normalizeSameSite(sameSite, secure) {
+  if (sameSite === undefined) {
+    return undefined;
+  }
+  switch (sameSite) {
+    case 'lax':
+      return 'Lax';
+    case 'strict':
+      return 'Strict';
+    case 'none':
+      if (secure !== true) {
+        throw new TypeError('SameSite=None cookies require secure: true.');
+      }
+      return 'None';
+    default:
+      throw new TypeError('sameSite must be lax, none, or strict.');
+  }
+}
+function serializeCookie(name, value, options) {
+  validateCookieName(name);
+  if (typeof value !== 'string') {
+    throw new TypeError('Cookie values must be strings.');
+  }
+  validateOptionalBoolean(options.httpOnly, 'httpOnly');
+  validateOptionalBoolean(options.secure, 'secure');
+  if (options.maxAgeSeconds !== undefined) {
+    if (typeof options.maxAgeSeconds !== 'number' || !Number.isSafeInteger(options.maxAgeSeconds) || options.maxAgeSeconds < 0) {
+      throw new TypeError('maxAgeSeconds must be a non-negative safe integer.');
+    }
+  }
+  if (options.domain !== undefined) {
+    validateDomain(options.domain);
+  }
+  if (options.path !== undefined) {
+    validatePath(options.path);
+  }
+  const sameSite = normalizeSameSite(options.sameSite, options.secure);
+  const encodedValue = encodeURIComponent(value);
+  const parts = [`${name}=${encodedValue}`];
+  if (options.maxAgeSeconds !== undefined) {
+    parts.push(`Max-Age=${options.maxAgeSeconds}`);
+  }
+  if (options.expires !== undefined) {
+    parts.push(`Expires=${formatExpiry(options.expires)}`);
+  }
+  if (options.path !== undefined) {
+    parts.push(`Path=${options.path}`);
+  }
+  if (options.domain !== undefined) {
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (options.secure === true) {
+    parts.push('Secure');
+  }
+  if (options.httpOnly === true) {
+    parts.push('HttpOnly');
+  }
+  if (sameSite !== undefined) {
+    parts.push(`SameSite=${sameSite}`);
+  }
+  return parts.join('; ');
+}
+
+/**
+ * Serialize one runtime-neutral response cookie as an independent `Set-Cookie` field.
+ *
+ * @param response Mutable response that receives the cookie header.
+ * @param name Cookie name, validated as an HTTP token.
+ * @param value Cookie value, percent-encoded before serialization.
+ * @param options Explicit cookie attributes shared by all supported adapters.
+ * @returns Nothing. The response receives one independent cookie field.
+ */
+export function setCookie(response, name, value, options = {}) {
+  response.setHeader('Set-Cookie', serializeCookie(name, value, readCookieOptions(options)));
+}
+
+/**
+ * Expire one runtime-neutral response cookie while retaining its matching scope attributes.
+ *
+ * @param response Mutable response that receives the deletion cookie header.
+ * @param name Cookie name, validated as an HTTP token.
+ * @param options Original Path and Domain attributes required to target the same cookie.
+ * @returns Nothing. The response receives one independent deletion cookie field.
+ */
+export function clearCookie(response, name, options = {}) {
+  const values = readCookieOptions(options);
+  response.setHeader('Set-Cookie', serializeCookie(name, '', {
+    ...values,
+    expires: COOKIE_DELETION_EXPIRES,
+    maxAgeSeconds: 0
+  }));
+}

package/dist/decorators.d.ts

@@ -1,4 +1,4 @@
-import { type Constructor, type MetadataPropertyKey } from '@fluojs/core';
+import type { Constructor, MetadataPropertyKey } from '@fluojs/core';
 import type { ConverterLike, GuardLike, InterceptorLike } from './types.js';
 type StandardClassDecoratorFn = (value: Function, context: ClassDecoratorContext) => void;
 type StandardMethodDecoratorFn = (value: Function, context: ClassMethodDecoratorContext) => void;
@@ -24,69 +24,90 @@ export declare function Version(version: string): ClassOrMethodDecoratorLike;
 /**
  * Registers a `GET` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `GET` handler mapping.
  */
-export declare const Get: (path: string) => MethodDecoratorLike;
+export declare const Get: (path?: string) => MethodDecoratorLike;
 /**
  * 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.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @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 declare const Sse: (path: string) => MethodDecoratorLike;
+export declare const Sse: (path?: string) => MethodDecoratorLike;
+/**
+ * Registers a route handler for one validated HTTP method token.
+ *
+ * @param method HTTP method token, canonicalized to uppercase before metadata registration.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
+ * @returns A method decorator that registers the method-specific handler mapping.
+ *
+ * @throws {InvalidHttpMethodError} When `method` is empty, contains non-token characters, or is the reserved `ALL` sentinel.
+ *
+ * @remarks
+ * Adapter wire support remains runtime-specific. `CONNECT` is outside ordinary routing conformance,
+ * and custom methods are not implied to be OpenAPI Path Item operations.
+ */
+export declare function Route(method: string, path?: string): MethodDecoratorLike;
+/**
+ * Registers an RFC `QUERY` route handler.
+ *
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
+ * @returns A method decorator that registers a `QUERY` handler mapping.
+ */
+export declare const Query: (path?: string) => MethodDecoratorLike;
 /**
  * Registers a `POST` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `POST` handler mapping.
  */
-export declare const Post: (path: string) => MethodDecoratorLike;
+export declare const Post: (path?: string) => MethodDecoratorLike;
 /**
  * Registers a `PUT` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `PUT` handler mapping.
  */
-export declare const Put: (path: string) => MethodDecoratorLike;
+export declare const Put: (path?: string) => MethodDecoratorLike;
 /**
  * Registers a `PATCH` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `PATCH` handler mapping.
  */
-export declare const Patch: (path: string) => MethodDecoratorLike;
+export declare const Patch: (path?: string) => MethodDecoratorLike;
 /**
  * Registers a `DELETE` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `DELETE` handler mapping.
  */
-export declare const Delete: (path: string) => MethodDecoratorLike;
+export declare const Delete: (path?: string) => MethodDecoratorLike;
 /**
  * Registers an `OPTIONS` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers an `OPTIONS` handler mapping.
  */
-export declare const Options: (path: string) => MethodDecoratorLike;
+export declare const Options: (path?: string) => MethodDecoratorLike;
 /**
  * Registers a `HEAD` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `HEAD` handler mapping.
  */
-export declare const Head: (path: string) => MethodDecoratorLike;
+export declare const Head: (path?: string) => MethodDecoratorLike;
 /**
  * Registers a route handler that matches all HTTP methods.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers an all-method handler mapping.
  */
-export declare const All: (path: string) => MethodDecoratorLike;
+export declare const All: (path?: string) => MethodDecoratorLike;
 /**
  * Associates a DTO class used for request binding and validation.
  *
@@ -151,6 +172,18 @@ export declare const FromCookie: (key?: string) => FieldDecoratorLike;
  * @returns A field decorator that marks the binding source as `body`.
  */
 export declare const FromBody: (key?: string) => FieldDecoratorLike;
+/**
+ * Binds a DTO field from portable multipart files.
+ *
+ * The binding always yields a readonly array when the request exposes a file
+ * collection, preserving adapter order and filtering by the optional field name.
+ * An absent file collection remains absent so `@Optional()` can opt out of the
+ * normal required-field error.
+ *
+ * @param key Optional multipart field-name filter. Defaults to the DTO field name.
+ * @returns A field decorator that marks the binding source as `files`.
+ */
+export declare const FromFiles: (key?: string) => FieldDecoratorLike;
 /**
  * Marks a DTO field binding as optional.
  *

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