0
# HTTP and Status Types
1

2
Core HTTP method and status code types for building type-safe OpenAPI integrations and web applications.
3

4
## Capabilities
5

6
### HTTP Method Type
7

8
Union type representing all standard HTTP methods.
9

10
```typescript { .api }
11
/**
12
 * Standard HTTP methods as defined in RFC specifications
13
 */
14
type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
15
```
16

17
**Usage Examples:**
18

19
```typescript
20
import type { HttpMethod } from "openapi-typescript-helpers";
21

22
// Type-safe method validation
23
function isValidMethod(method: string): method is HttpMethod {
24
  return ["get", "put", "post", "delete", "options", "head", "patch", "trace"].includes(method);
25
}
26

27
// Generic API client method
28
function makeRequest<T>(method: HttpMethod, url: string): Promise<T> {
29
  return fetch(url, { method }).then(res => res.json());
30
}
31
```
32

33
### Success Status Codes
34

35
Union type for 2XX success status codes.
36

37
```typescript { .api }
38
/**
39
 * 2XX success status codes
40
 */
41
type OkStatus = 200 | 201 | 202 | 203 | 204 | 206 | 207 | "2XX";
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import type { OkStatus } from "openapi-typescript-helpers";
48

49
// Type-safe success status checking
50
function isSuccessStatus(status: number): status is OkStatus {
51
  return status >= 200 && status < 300;
52
}
53

54
// Response type based on status
55
type SuccessfulResponse<T> = {
56
  status: OkStatus;
57
  data: T;
58
};
59
```
60

61
### Error Status Codes
62

63
Union type for 4XX and 5XX error status codes.
64

65
```typescript { .api }
66
/**
67
 * 4XX and 5XX error status codes including specific codes and wildcard patterns
68
 */
69
type ErrorStatus = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | '5XX' | 
70
  400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 420 | 421 | 422 | 423 | 424 | 425 | 426 | 427 | 428 | 429 | 430 | 431 | 444 | 450 | 451 | 497 | 498 | 499 | '4XX' | "default";
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import type { ErrorStatus } from "openapi-typescript-helpers";
77

78
// Error response type
79
type ErrorResponse<T = unknown> = {
80
  status: ErrorStatus;
81
  error: T;
82
};
83

84
// Type-safe error handling
85
function handleError(status: ErrorStatus, message: string) {
86
  if (typeof status === 'string') {
87
    // Handle wildcard statuses: "4XX", "5XX", "default"
88
    console.error(`${status} error: ${message}`);
89
  } else if (status >= 400 && status < 500) {
90
    // Handle 4XX client errors
91
    console.error(`Client error ${status}: ${message}`);
92
  } else {
93
    // Handle 5XX server errors
94
    console.error(`Server error ${status}: ${message}`);
95
  }
96
}
97
```
98

99
### Status Utilities
100

101
#### OK Status Union Extractor
102

103
Extract union of OK statuses from a type.
104

105
```typescript { .api }
106
/**
107
 * Get a union of OK statuses from a response type
108
 */
109
type OKStatusUnion<T> = FilterKeys<T, OkStatus>;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import type { OKStatusUnion } from "openapi-typescript-helpers";
116

117
// Extract success statuses from response object
118
type ApiResponse = {
119
  200: { data: User };
120
  201: { data: User };
121
  400: { error: string };
122
  404: { error: string };
123
};
124

125
type SuccessStatuses = OKStatusUnion<ApiResponse>; // 200 | 201
126
```
127

128
#### First Error Status Extractor
129

130
Get the first error status in priority order (5XX first, then 4XX, then default).
131

132
```typescript { .api }
133
/**
134
 * Get first error status, in priority order (5XX → 4XX → default)
135
 */
136
type FirstErrorStatus<T> =
137
  T extends { 500: any }   ? T[500] :
138
  T extends { 501: any }   ? T[501] :
139
  T extends { 502: any }   ? T[502] :
140
  T extends { 503: any }   ? T[503] :
141
  T extends { 504: any }   ? T[504] :
142
  T extends { 505: any }   ? T[505] :
143
  T extends { 506: any }   ? T[506] :
144
  T extends { 507: any }   ? T[507] :
145
  T extends { 508: any }   ? T[508] :
146
  T extends { 510: any }   ? T[510] :
147
  T extends { 511: any }   ? T[511] :
148
  T extends { "5XX": any } ? T["5XX"] :
149
  T extends { 400: any }   ? T[400] :
150
  T extends { 401: any }   ? T[401] :
151
  T extends { 402: any }   ? T[402] :
152
  T extends { 403: any }   ? T[403] :
153
  T extends { 404: any }   ? T[404] :
154
  T extends { 405: any }   ? T[405] :
155
  T extends { 406: any }   ? T[406] :
156
  T extends { 407: any }   ? T[407] :
157
  T extends { 408: any }   ? T[408] :
158
  T extends { 409: any }   ? T[409] :
159
  T extends { 410: any }   ? T[410] :
160
  T extends { 411: any }   ? T[411] :
161
  T extends { 412: any }   ? T[412] :
162
  T extends { 413: any }   ? T[413] :
163
  T extends { 414: any }   ? T[414] :
164
  T extends { 415: any }   ? T[415] :
165
  T extends { 416: any }   ? T[416] :
166
  T extends { 417: any }   ? T[417] :
167
  T extends { 418: any }   ? T[418] :
168
  T extends { 420: any }   ? T[420] :
169
  T extends { 421: any }   ? T[421] :
170
  T extends { 422: any }   ? T[422] :
171
  T extends { 423: any }   ? T[423] :
172
  T extends { 424: any }   ? T[424] :
173
  T extends { 425: any }   ? T[425] :
174
  T extends { 426: any }   ? T[426] :
175
  T extends { 427: any }   ? T[427] :
176
  T extends { 428: any }   ? T[428] :
177
  T extends { 429: any }   ? T[429] :
178
  T extends { 430: any }   ? T[430] :
179
  T extends { 431: any }   ? T[431] :
180
  T extends { 444: any }   ? T[444] :
181
  T extends { 450: any }   ? T[450] :
182
  T extends { 451: any }   ? T[451] :
183
  T extends { 497: any }   ? T[497] :
184
  T extends { 498: any }   ? T[498] :
185
  T extends { 499: any }   ? T[499] :
186
  T extends { "4XX": any } ? T["4XX"] :
187
  T extends { default: any } ? T["default"] : never;
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
import type { FirstErrorStatus } from "openapi-typescript-helpers";
194

195
// Extract first error from response type
196
type ApiResponse = {
197
  200: { data: User };
198
  400: { error: "Bad Request" };
199
  404: { error: "Not Found" };
200
  500: { error: "Internal Error" };
201
};
202

203
type FirstError = FirstErrorStatus<ApiResponse>; // { error: "Internal Error" } (500 takes priority)
204

205
// Use in error handling
206
type ErrorHandler<T> = (error: FirstErrorStatus<T>) => void;
207
```