0
# OpenAPI TypeScript Helpers
1

2
OpenAPI TypeScript Helpers provides essential TypeScript utility types and helpers for consuming OpenAPI-generated types. It includes comprehensive HTTP method and status code types, sophisticated type manipulation utilities for extracting request/response types from OpenAPI schemas, and advanced TypeScript conditional types for handling success and error responses.
3

4
This package serves as the foundational type system that powers openapi-fetch and other tools in the OpenAPI TypeScript ecosystem, offering generic utilities that can be reused across any TypeScript project working with OpenAPI schemas.
5

6
## Package Information
7

8
- **Package Name**: openapi-typescript-helpers
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install openapi-typescript-helpers`
12

13
## Core Imports
14

15
```typescript
16
// Most commonly used types
17
import type { 
18
  HttpMethod, 
19
  OkStatus, 
20
  ErrorStatus,
21
  PathsWithMethod,
22
  SuccessResponse,
23
  ErrorResponse,
24
  FilterKeys,
25
  MediaType,
26
  JSONLike
27
} from "openapi-typescript-helpers";
28

29
// Additional OpenAPI utilities
30
import type {
31
  OperationObject,
32
  OperationRequestBody,
33
  IsOperationRequestBodyOptional,
34
  SuccessResponseJSON,
35
  ErrorResponseJSON,
36
  RequestBodyJSON
37
} from "openapi-typescript-helpers";
38

39
// Status and key utilities
40
import type {
41
  OKStatusUnion,
42
  FirstErrorStatus,
43
  RequiredKeysOf
44
} from "openapi-typescript-helpers";
45
```
46

47
## Basic Usage
48

49
```typescript
50
import type { 
51
  HttpMethod, 
52
  PathsWithMethod, 
53
  SuccessResponse, 
54
  ErrorResponse,
55
  FilterKeys 
56
} from "openapi-typescript-helpers";
57

58
// Define OpenAPI paths type (typically generated by openapi-typescript)
59
type Paths = {
60
  "/users": {
61
    get: {
62
      responses: {
63
        200: { content: { "application/json": User[] } };
64
        404: { content: { "application/json": { error: string } } };
65
      };
66
    };
67
    post: {
68
      requestBody: { content: { "application/json": CreateUser } };
69
      responses: {
70
        201: { content: { "application/json": User } };
71
        400: { content: { "application/json": { error: string } } };
72
      };
73
    };
74
  };
75
};
76

77
// Extract paths that support GET method
78
type GetPaths = PathsWithMethod<Paths, "get">; // "/users"
79

80
// Extract success response types
81
type UserListResponse = SuccessResponse<Paths["/users"]["get"]["responses"]>;
82
// Result: User[]
83

84
// Extract error response types  
85
type UserListError = ErrorResponse<Paths["/users"]["get"]["responses"]>;
86
// Result: { error: string }
87

88
// Use FilterKeys to extract specific media type
89
type JsonResponse = FilterKeys<
90
  Paths["/users"]["get"]["responses"][200]["content"], 
91
  "application/json"
92
>; // User[]
93
```
94

95
## Architecture
96

97
OpenAPI TypeScript Helpers is organized around several key type categories:
98

99
- **HTTP Types**: Fundamental HTTP method and status code types for OpenAPI schemas
100
- **OpenAPI Utilities**: Advanced type manipulation for extracting and transforming OpenAPI operation types
101
- **TypeScript Utilities**: Generic TypeScript conditional types and utility functions for type-level programming
102

103
The package provides no runtime code - all exports are TypeScript type definitions designed for compile-time type checking and inference.
104

105
## Capabilities
106

107
### HTTP and Status Types
108

109
Core HTTP method and status code types for building type-safe OpenAPI integrations.
110

111
```typescript { .api }
112
type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
113

114
type OkStatus = 200 | 201 | 202 | 203 | 204 | 206 | 207 | "2XX";
115

116
type ErrorStatus = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | '5XX' | 
117
  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";
118
```
119

120
[HTTP and Status Types](./http-types.md)
121

122
### OpenAPI Path and Operation Utilities
123

124
Advanced type utilities for extracting and manipulating OpenAPI path and operation objects, including request/response type extraction.
125

126
```typescript { .api }
127
type PathsWithMethod<Paths extends {}, PathnameMethod extends HttpMethod> = {
128
  [Pathname in keyof Paths]: Paths[Pathname] extends {
129
    [K in PathnameMethod]: any;
130
  }
131
    ? Pathname
132
    : never;
133
}[keyof Paths];
134

135
type SuccessResponse<
136
  T extends Record<string | number, any>,
137
  Media extends MediaType = MediaType,
138
> = GetResponseContent<T, Media, OkStatus>;
139

140
type ErrorResponse<
141
  T extends Record<string | number, any>,
142
  Media extends MediaType = MediaType,
143
> = GetResponseContent<T, Media, ErrorStatus>;
144
```
145

146
[OpenAPI Utilities](./openapi-utilities.md)
147

148
### Generic TypeScript Utilities
149

150
General-purpose TypeScript utility types for advanced type manipulation and conditional type logic.
151

152
```typescript { .api }
153
type FilterKeys<Obj, Matchers> = Obj[keyof Obj & Matchers];
154

155
type MediaType = `${string}/${string}`;
156

157
type JSONLike<T> = FilterKeys<T, `${string}/json`>;
158

159
type RequiredKeysOf<T> = RequiredKeysOfHelper<T> extends undefined ? never : RequiredKeysOfHelper<T>;
160
```
161

162
[TypeScript Utilities](./typescript-utilities.md)