docs: add jsdoc examples for request utils

docs/2.utils/1.request.md

@@ -14,30 +14,81 @@ Asserts that the incoming request method is of the expected type using `isMethod
 
 If the method is not allowed, it will throw a 405 error with the message "HTTP method is not allowed".
 
+If `allowHead` is `true`, it will allow `HEAD` requests to pass if the expected method is `GET`.
+
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  assertMethod(event, "GET");
+  // Handle GET request, otherwise throw 405 error
+});
+```
+
 ### `getHeader(event, name)`
 
 Get a request header by name.
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const contentType = getRequestHeader(event, "content-type"); // "application/json"
+});
+```
+
 ### `getHeaders(event)`
 
 Get the request headers object.
 
 Array headers are joined with a comma.
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const headers = getRequestHeaders(event); // { "content-type": "application/json", "x-custom-header": "value" }
+});
+```
+
 ### `getQuery(event)`
 
 Get query the params object from the request URL parsed with [unjs/ufo](https://ufo.unjs.io).
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const query = getQuery(event); // { key: "value", key2: ["value1", "value2"] }
+});
+```
+
 ### `getRequestHeader(event, name)`
 
 Get a request header by name.
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const contentType = getRequestHeader(event, "content-type"); // "application/json"
+});
+```
+
 ### `getRequestHeaders(event)`
 
 Get the request headers object.
 
 Array headers are joined with a comma.
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const headers = getRequestHeaders(event); // { "content-type": "application/json", "x-custom-header": "value" }
+});
+```
+
 ### `getRequestHost(event, opts: { xForwardedHost? })`
 
 Get the request hostname.
@@ -46,6 +97,14 @@ If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it e
 
 If no host header is found, it will default to "localhost".
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const host = getRequestHost(event); // "example.com"
+});
+```
+
 ### `getRequestIP(event)`
 
 Try to get the client IP address from the incoming request.
@@ -54,6 +113,14 @@ If `xForwardedFor` is `true`, it will use the `x-forwarded-for` header if it exi
 
 If IP cannot be determined, it will default to `undefined`.
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const ip = getRequestIP(event); // "192.0.2.0"
+});
+```
+
 ### `getRequestProtocol(event, opts: { xForwardedProto? })`
 
 Get the request protocol.
@@ -62,6 +129,14 @@ If `x-forwarded-proto` header is set to "https", it will return "https". You can
 
 If protocol cannot be determined, it will default to "http".
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const protocol = getRequestProtocol(event); // "https"
+});
+```
+
 ### `getRequestURL(event, opts: { xForwardedHost?, xForwardedProto? })`
 
 Generated the full incoming request URL using `getRequestProtocol`, `getRequestHost` and `event.path`.
@@ -70,30 +145,122 @@ If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it e
 
 If `xForwardedProto` is `false`, it will not use the `x-forwarded-proto` header.
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const url = getRequestURL(event); // "https://example.com/path"
+});
+```
+
 ### `getRouterParam(event, name, opts: { decode? })`
 
 Get a matched route param by name.
 
+If `decode` option is `true`, it will decode the matched route param using `decodeURI`.
+
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const param = getRouterParam(event, "key");
+});
+```
+
 ### `getRouterParams(event, opts: { decode? })`
 
 Get matched route params.
 
 If `decode` option is `true`, it will decode the matched route params using `decodeURI`.
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const params = getRouterParams(event); // { key: "value" }
+});
+```
+
 ### `getValidatedQuery(event, validate)`
 
 Get the query param from the request URL parsed with [unjs/ufo](https://ufo.unjs.io) and validated with validate function.
 
+You can use a simple function to validate the query object or a library like `zod` to define a schema.
+
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const query = getValidatedQuery(event, (data) => {
+    return "key" in data && typeof data.key === "string";
+  });
+});
+```
+
+**Example:**
+
+```ts
+import { z } from "zod";
+export default defineEventHandler((event) => {
+  const query = getValidatedQuery(
+    event,
+    z.object({
+      key: z.string(),
+    }),
+  );
+});
+```
+
 ### `getValidatedRouterParams(event, validate, opts: { decode? })`
 
 Get matched route params and validate with validate function.
 
+If `decode` option is `true`, it will decode the matched route params using `decodeURI`.
+
+You can use a simple function to validate the params object or a library like `zod` to define a schema.
+
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  const params = getValidatedRouterParams(event, (data) => {
+    return "key" in data && typeof data.key === "string";
+  });
+});
+```
+
+**Example:**
+
+```ts
+import { z } from "zod";
+export default defineEventHandler((event) => {
+  const params = getValidatedRouterParams(
+    event,
+    z.object({
+      key: z.string(),
+    }),
+  );
+});
+```
+
 ### `isMethod(event, expected, allowHead?)`
 
 Checks if the incoming request method is of the expected type.
 
 If `allowHead` is `true`, it will allow `HEAD` requests to pass if the expected method is `GET`.
 
+**Example:**
+
+```ts
+export default defineEventHandler((event) => {
+  if (isMethod(event, "GET")) {
+    // Handle GET request
+  } else if (isMethod(event, ["POST", "PUT"])) {
+    // Handle POST or PUT request
+  }
+});
+```
+
 ### `toWebRequest(event)`
 
 Convert the H3Event to a WebRequest object.