Skip to content

Commit

Permalink
chore: apply automated updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@autofix-ci
autofix-ci[bot] authored Jun 19, 2024
1 parent fc5d6ff commit 5ff33bd
Showing 1 changed file with 3 additions and 258 deletions.
261 changes: 3 additions & 258 deletions docs/2.utils/1.request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,264 +8,9 @@ icon: material-symbols-light:input
<!-- automd:jsdocs src="../../src/utils/request.ts" -->

### `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.
<!-- ⚠️ (jsdocs) Cannot find module './symbols'
Require stack:
- /home/runner/work/h3/h3/src/utils/request.ts -->

<!-- /automd -->

Expand Down

0 comments on commit 5ff33bd

Please sign in to comment.