From 5ff33bd8b66ac93327b66a52aefe19e1db9285fa Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Wed, 19 Jun 2024 12:11:02 +0000 Subject: [PATCH] chore: apply automated updates --- docs/2.utils/1.request.md | 261 +------------------------------------- 1 file changed, 3 insertions(+), 258 deletions(-) diff --git a/docs/2.utils/1.request.md b/docs/2.utils/1.request.md index 6dca6488..5e83284d 100644 --- a/docs/2.utils/1.request.md +++ b/docs/2.utils/1.request.md @@ -8,264 +8,9 @@ icon: material-symbols-light:input -### `assertMethod(event, expected, allowHead?)` - -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. - -If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists. - -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. - -If `xForwardedFor` is `true`, it will use the `x-forwarded-for` header if it exists. - -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. - -If `x-forwarded-proto` header is set to "https", it will return "https". You can disable this behavior by setting `xForwardedProto` to `false`. - -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`. - -If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists. - -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. - -**NOTE:** This function is not stable and might have edge cases that are not handled properly. +