Skip to content

Commit 5ff33bd

Browse files
autofix-ci[bot]autofix-ci[bot]
authored
chore: apply automated updates
1 parent fc5d6ff commit 5ff33bd

File tree

1 file changed

+3
-258
lines changed

1 file changed

+3
-258
lines changed

‎docs/2.utils/1.request.md

+3-258
Original file line numberDiff line numberDiff line change
@@ -8,264 +8,9 @@ icon: material-symbols-light:input
88
99
<!-- automd:jsdocs src="../../src/utils/request.ts" -->
1010

11-
### `assertMethod(event, expected, allowHead?)`
12-
13-
Asserts that the incoming request method is of the expected type using `isMethod`.
14-
15-
If the method is not allowed, it will throw a 405 error with the message "HTTP method is not allowed".
16-
17-
If `allowHead` is `true`, it will allow `HEAD` requests to pass if the expected method is `GET`.
18-
19-
**Example:**
20-
21-
```ts
22-
export default defineEventHandler((event) => {
23-
assertMethod(event, "GET");
24-
// Handle GET request, otherwise throw 405 error
25-
});
26-
```
27-
28-
### `getHeader(event, name)`
29-
30-
Get a request header by name.
31-
32-
**Example:**
33-
34-
```ts
35-
export default defineEventHandler((event) => {
36-
const contentType = getRequestHeader(event, "content-type"); // "application/json"
37-
});
38-
```
39-
40-
### `getHeaders(event)`
41-
42-
Get the request headers object.
43-
44-
Array headers are joined with a comma.
45-
46-
**Example:**
47-
48-
```ts
49-
export default defineEventHandler((event) => {
50-
const headers = getRequestHeaders(event); // { "content-type": "application/json", "x-custom-header": "value" }
51-
});
52-
```
53-
54-
### `getQuery(event)`
55-
56-
Get query the params object from the request URL parsed with [unjs/ufo](https://ufo.unjs.io).
57-
58-
**Example:**
59-
60-
```ts
61-
export default defineEventHandler((event) => {
62-
const query = getQuery(event); // { key: "value", key2: ["value1", "value2"] }
63-
});
64-
```
65-
66-
### `getRequestHeader(event, name)`
67-
68-
Get a request header by name.
69-
70-
**Example:**
71-
72-
```ts
73-
export default defineEventHandler((event) => {
74-
const contentType = getRequestHeader(event, "content-type"); // "application/json"
75-
});
76-
```
77-
78-
### `getRequestHeaders(event)`
79-
80-
Get the request headers object.
81-
82-
Array headers are joined with a comma.
83-
84-
**Example:**
85-
86-
```ts
87-
export default defineEventHandler((event) => {
88-
const headers = getRequestHeaders(event); // { "content-type": "application/json", "x-custom-header": "value" }
89-
});
90-
```
91-
92-
### `getRequestHost(event, opts: { xForwardedHost? })`
93-
94-
Get the request hostname.
95-
96-
If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists.
97-
98-
If no host header is found, it will default to "localhost".
99-
100-
**Example:**
101-
102-
```ts
103-
export default defineEventHandler((event) => {
104-
const host = getRequestHost(event); // "example.com"
105-
});
106-
```
107-
108-
### `getRequestIP(event)`
109-
110-
Try to get the client IP address from the incoming request.
111-
112-
If `xForwardedFor` is `true`, it will use the `x-forwarded-for` header if it exists.
113-
114-
If IP cannot be determined, it will default to `undefined`.
115-
116-
**Example:**
117-
118-
```ts
119-
export default defineEventHandler((event) => {
120-
const ip = getRequestIP(event); // "192.0.2.0"
121-
});
122-
```
123-
124-
### `getRequestProtocol(event, opts: { xForwardedProto? })`
125-
126-
Get the request protocol.
127-
128-
If `x-forwarded-proto` header is set to "https", it will return "https". You can disable this behavior by setting `xForwardedProto` to `false`.
129-
130-
If protocol cannot be determined, it will default to "http".
131-
132-
**Example:**
133-
134-
```ts
135-
export default defineEventHandler((event) => {
136-
const protocol = getRequestProtocol(event); // "https"
137-
});
138-
```
139-
140-
### `getRequestURL(event, opts: { xForwardedHost?, xForwardedProto? })`
141-
142-
Generated the full incoming request URL using `getRequestProtocol`, `getRequestHost` and `event.path`.
143-
144-
If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists.
145-
146-
If `xForwardedProto` is `false`, it will not use the `x-forwarded-proto` header.
147-
148-
**Example:**
149-
150-
```ts
151-
export default defineEventHandler((event) => {
152-
const url = getRequestURL(event); // "https://example.com/path"
153-
});
154-
```
155-
156-
### `getRouterParam(event, name, opts: { decode? })`
157-
158-
Get a matched route param by name.
159-
160-
If `decode` option is `true`, it will decode the matched route param using `decodeURI`.
161-
162-
**Example:**
163-
164-
```ts
165-
export default defineEventHandler((event) => {
166-
const param = getRouterParam(event, "key");
167-
});
168-
```
169-
170-
### `getRouterParams(event, opts: { decode? })`
171-
172-
Get matched route params.
173-
174-
If `decode` option is `true`, it will decode the matched route params using `decodeURI`.
175-
176-
**Example:**
177-
178-
```ts
179-
export default defineEventHandler((event) => {
180-
const params = getRouterParams(event); // { key: "value" }
181-
});
182-
```
183-
184-
### `getValidatedQuery(event, validate)`
185-
186-
Get the query param from the request URL parsed with [unjs/ufo](https://ufo.unjs.io) and validated with validate function.
187-
188-
You can use a simple function to validate the query object or a library like `zod` to define a schema.
189-
190-
**Example:**
191-
192-
```ts
193-
export default defineEventHandler((event) => {
194-
const query = getValidatedQuery(event, (data) => {
195-
return "key" in data && typeof data.key === "string";
196-
});
197-
});
198-
```
199-
200-
**Example:**
201-
202-
```ts
203-
import { z } from "zod";
204-
export default defineEventHandler((event) => {
205-
const query = getValidatedQuery(
206-
event,
207-
z.object({
208-
key: z.string(),
209-
}),
210-
);
211-
});
212-
```
213-
214-
### `getValidatedRouterParams(event, validate, opts: { decode? })`
215-
216-
Get matched route params and validate with validate function.
217-
218-
If `decode` option is `true`, it will decode the matched route params using `decodeURI`.
219-
220-
You can use a simple function to validate the params object or a library like `zod` to define a schema.
221-
222-
**Example:**
223-
224-
```ts
225-
export default defineEventHandler((event) => {
226-
const params = getValidatedRouterParams(event, (data) => {
227-
return "key" in data && typeof data.key === "string";
228-
});
229-
});
230-
```
231-
232-
**Example:**
233-
234-
```ts
235-
import { z } from "zod";
236-
export default defineEventHandler((event) => {
237-
const params = getValidatedRouterParams(
238-
event,
239-
z.object({
240-
key: z.string(),
241-
}),
242-
);
243-
});
244-
```
245-
246-
### `isMethod(event, expected, allowHead?)`
247-
248-
Checks if the incoming request method is of the expected type.
249-
250-
If `allowHead` is `true`, it will allow `HEAD` requests to pass if the expected method is `GET`.
251-
252-
**Example:**
253-
254-
```ts
255-
export default defineEventHandler((event) => {
256-
if (isMethod(event, "GET")) {
257-
// Handle GET request
258-
} else if (isMethod(event, ["POST", "PUT"])) {
259-
// Handle POST or PUT request
260-
}
261-
});
262-
```
263-
264-
### `toWebRequest(event)`
265-
266-
Convert the H3Event to a WebRequest object.
267-
268-
**NOTE:** This function is not stable and might have edge cases that are not handled properly.
11+
<!-- ⚠️ (jsdocs) Cannot find module './symbols'
12+
Require stack:
13+
- /home/runner/work/h3/h3/src/utils/request.ts -->
26914

27015
<!-- /automd -->
27116

0 commit comments

Comments
 (0)