From 786b9d5577cbae59bbd2d3ae05a17dcbf3074dfc Mon Sep 17 00:00:00 2001
From: Braden Wong <13159333+braden-w@users.noreply.github.com>
Date: Fri, 5 Dec 2025 15:03:59 -0800
Subject: [PATCH 1/2] docs: add JSDoc for status() documenting string and
 number arguments

---
 src/error.ts | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/error.ts b/src/error.ts
index 0e7af679..2a299db3 100644
--- a/src/error.ts
+++ b/src/error.ts
@@ -103,6 +103,28 @@ export class ElysiaCustomStatusResponse<
 	}
 }
 
+/**
+ * Create an HTTP response with a specific status code.
+ *
+ * The status code can be specified as either a number or a string status name.
+ * String status names provide autocompletion and are constrained to valid HTTP statuses.
+ *
+ * @param code - HTTP status code as a number (e.g., `418`) or status name string (e.g., `"I'm a teapot"`)
+ * @param response - Optional response body. If omitted, defaults to the status message.
+ *
+ * @example
+ * // Using numeric status code
+ * status(418, 'I am a teapot')
+ *
+ * @example
+ * // Using string status name (autocompletes in TypeScript)
+ * status("I'm a teapot", 'I am a teapot')
+ *
+ * @example
+ * // Without response body (defaults to status message)
+ * status(204)
+ * status("No Content")
+ */
 export const status = <
 	const Code extends number | keyof StatusMap,
 	const T = Code extends keyof InvertedStatusMap

From c111652adf71f710e6ef76f96cbd01aea792d699 Mon Sep 17 00:00:00 2001
From: Braden Wong <13159333+braden-w@users.noreply.github.com>
Date: Fri, 5 Dec 2025 15:17:56 -0800
Subject: [PATCH 2/2] docs(status): clarify empty HTTP status body behavior

Document that numeric codes in emptyHttpStatus (101, 204, 205, 304, 307, 308)
always omit the response body, while string status names bypass this check.

Update examples to show:
- status(204) yields undefined (no body)
- status("No Content") yields "No Content" string body
- status(404) defaults to "Not Found" body
---
 src/error.ts | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/src/error.ts b/src/error.ts
index 2a299db3..4b7d866a 100644
--- a/src/error.ts
+++ b/src/error.ts
@@ -110,7 +110,9 @@ export class ElysiaCustomStatusResponse<
  * String status names provide autocompletion and are constrained to valid HTTP statuses.
  *
  * @param code - HTTP status code as a number (e.g., `418`) or status name string (e.g., `"I'm a teapot"`)
- * @param response - Optional response body. If omitted, defaults to the status message.
+ * @param response - Optional response body. If omitted, defaults to the status message
+ * for most codes. However, for empty HTTP statuses (101, 204, 205, 304, 307, 308),
+ * the response body is always omitted when using numeric codes.
  *
  * @example
  * // Using numeric status code
@@ -122,8 +124,13 @@ export class ElysiaCustomStatusResponse<
  *
  * @example
  * // Without response body (defaults to status message)
- * status(204)
- * status("No Content")
+ * status(404) // body: "Not Found"
+ * status("Not Found") // body: "Not Found"
+ *
+ * @example
+ * // Empty HTTP statuses: numeric codes have no body
+ * status(204) // body: undefined (no content)
+ * status("No Content") // body: "No Content" (string body)
  */
 export const status = <
 	const Code extends number | keyof StatusMap,