Skip to content
Source
Sign inSign up
pingdotgg/t3code
Open History to see the last commit

ParsedOperation.ts

303 lines8.4 KB

1/**
2 * Normalized OpenAPI operation model shared by the generator pipeline.
3 *
4 * This module records the shape produced after an OpenAPI document is resolved
5 * into stable generator inputs: document metadata, tags, security schemes,
6 * per-operation parameters, request bodies, response media types, derived
7 * schema references, path templates, and streaming capabilities. Renderers
8 * consume this representation to emit HttpClient or HttpApi modules without
9 * reinterpreting raw OpenAPI path-item structures.
10 *
11 * @since 4.0.0
12 */
13import type {
14 OpenAPISecurityRequirement,
15 OpenAPISpecExternalDocs,
16 OpenAPISpecLicense,
17 OpenAPISpecServer
18} from "effect/http-api/OpenApi"
19import type { HttpMethod } from "effect/http/HttpMethod"
20import type * as Types from "effect/Types"
21​
22/**
23 * Root OpenAPI metadata preserved for generated client and HttpApi output.
24 *
25 * @category models
26 * @since 4.0.0
27 */
28export interface ParsedOpenApiMetadata {
29 readonly title: string
30 readonly version: string
31 readonly summary: string | undefined
32 readonly description: string | undefined
33 readonly license: OpenAPISpecLicense | undefined
34 readonly servers: ReadonlyArray<OpenAPISpecServer> | undefined
36​
37/**
38 * Tag metadata used to group and annotate generated operations.
39 *
40 * @category models
41 * @since 4.0.0
42 */
43export interface ParsedOpenApiTag {
44 readonly name: string
45 readonly description: string | undefined
46 readonly externalDocs: OpenAPISpecExternalDocs | undefined
48​
49/**
50 * Supported security scheme extracted from an OpenAPI components section.
51 *
52 * @category models
53 * @since 4.0.0
54 */
55export interface ParsedOpenApiSecurityScheme {
56 readonly name: string
57 readonly type: "basic" | "bearer" | "apiKey" | "http"
58 readonly description: string | undefined
59 readonly bearerFormat: string | undefined
60 readonly scheme: string | undefined
61 readonly key: string | undefined
62 readonly in: "header" | "query" | "cookie" | undefined
64​
65/**
66 * Normalized OpenAPI document consumed by the generator renderers.
67 *
68 * @category models
69 * @since 4.0.0
70 */
71export interface ParsedOpenApi {
72 readonly metadata: ParsedOpenApiMetadata
73 readonly tags: ReadonlyArray<ParsedOpenApiTag>
74 readonly securitySchemes: ReadonlyArray<ParsedOpenApiSecurityScheme>
75 readonly operations: ReadonlyArray<ParsedOperation>
77​
78/**
79 * Documentation and lifecycle metadata associated with an operation.
80 *
81 * @category models
82 * @since 4.0.0
83 */
84export interface ParsedOperationMetadata {
85 readonly summary: string | undefined
86 readonly description: string | undefined
87 readonly deprecated: boolean
88 readonly externalDocs: OpenAPISpecExternalDocs | undefined
90​
91/**
92 * Resolved OpenAPI parameter grouped by where it appears in the request.
93 *
94 * @category models
95 * @since 4.0.0
96 */
97export interface ParsedOperationParameter {
98 readonly name: string
99 readonly in: "path" | "query" | "header" | "cookie"
100 readonly required: boolean
101 readonly description: string | undefined
102 readonly schema: {}
104​
105/**
106 * Summary of the request body declaration before per-media schemas are rendered.
107 *
108 * @category models
109 * @since 4.0.0
110 */
111export interface ParsedOperationRequestBody {
112 readonly required: boolean
113 readonly contentTypes: Array<string>
115​
116/**
117 * Encoding strategy the generator can use for a request or response media type.
118 *
119 * @category models
120 * @since 4.0.0
121 */
122export type ParsedOperationMediaTypeEncoding =
123 | "json"
124 | "multipart"
125 | "form-url-encoded"
126 | "text"
127 | "binary"
128​
129/**
130 * Media type whose schema can be represented in generated Effect code.
131 *
132 * @category models
133 * @since 4.0.0
134 */
135export type ParsedOperationMediaTypeSchema =
136 | {
137 readonly contentType: string
138 readonly encoding: ParsedOperationMediaTypeEncoding
139 readonly schema: string
140 readonly effectStream?: undefined
141 }
142 | {
143 readonly contentType: string
144 readonly encoding: "text"
145 readonly schema: string
146 readonly effectStream: "sse"
147 readonly errorSchema: string
148 }
149 | {
150 readonly contentType: string
151 readonly encoding: "binary"
152 readonly schema?: undefined
153 readonly effectStream: "uint8array"
154 }
155 | {
156 readonly contentType: string
157 readonly encoding: "json"
158 readonly schema: string
159 readonly effectStream: "ndjson"
160 }
161​
162/**
163 * Parsed response metadata together with generated schema references.
164 *
165 * @category models
166 * @since 4.0.0
167 */
168export interface ParsedOperationResponse {
169 readonly status: string
170 readonly description: string | undefined
171 readonly contentTypes: Array<string>
172 readonly hasHeaders: boolean
173 readonly isEmpty: boolean
174 readonly representable: ReadonlyArray<ParsedOperationMediaTypeSchema>
176​
177/**
178 * Resolved security requirement applied to a parsed operation.
179 *
180 * @category models
181 * @since 4.0.0
182 */
183export type ParsedOperationSecurityRequirement = Readonly<OpenAPISecurityRequirement>
184​
185/**
186 * Response state used only by the generated HttpClient renderers.
187 *
188 * @category models
189 * @since 4.0.0
190 */
191export interface ParsedOperationHttpClientResponses {
192 readonly successSchemas: ReadonlyMap<string, string>
193 readonly errorSchemas: ReadonlyMap<string, string>
194 readonly voidSuccessStatuses: ReadonlySet<string>
195 readonly voidErrorStatuses: ReadonlySet<string>
196 readonly sseSchema?: string
197 readonly sseSchemaMode: "data" | "event"
198 readonly binarySuccessStatuses: ReadonlySet<string>
200​
201/**
202 * Normalized operation model shared by all OpenAPI generator backends.
203 *
204 * @category models
205 * @since 4.0.0
206 */
207export interface ParsedOperation {
208 readonly id: string
209 readonly operationId: string | undefined
210 readonly path: string
211 readonly method: Lowercase<HttpMethod>
212 readonly tags: ReadonlyArray<string>
213 readonly metadata: ParsedOperationMetadata
214 readonly parameters: {
215 readonly path: ReadonlyArray<ParsedOperationParameter>
216 readonly query: ReadonlyArray<ParsedOperationParameter>
217 readonly header: ReadonlyArray<ParsedOperationParameter>
218 readonly cookie: ReadonlyArray<ParsedOperationParameter>
219 }
220 readonly requestBody: ParsedOperationRequestBody | undefined
221 readonly responses: ReadonlyArray<ParsedOperationResponse>
222 readonly defaultResponse: ParsedOperationResponse | undefined
223 readonly effectiveSecurity: ReadonlyArray<ParsedOperationSecurityRequirement>
224 readonly description: string | undefined
225 readonly params?: string
226 readonly paramsOptional: boolean
227 readonly urlParams: ReadonlyArray<string>
228 /**
229 * Query parameters declared with `style: "form"` and `explode: false`, whose
230 * arrays are sent as one comma-separated value.
231 */
232 readonly commaUrlParams: ReadonlyArray<string>
233 readonly headers: ReadonlyArray<string>
234 readonly cookies: ReadonlyArray<string>
235 readonly payload?: string
236 readonly payloadFormData: boolean
237 readonly payloadFormUrlEncoded: boolean
238 readonly pathSchema: string | undefined
239 readonly querySchema: string | undefined
240 readonly querySchemaOptional: boolean
241 readonly headersSchema: string | undefined
242 readonly headersSchemaOptional: boolean
243 readonly requestBodyRepresentable: ReadonlyArray<ParsedOperationMediaTypeSchema>
244 readonly pathIds: ReadonlyArray<string>
245 readonly pathTemplate: string
246 readonly httpClientResponses: ParsedOperationHttpClientResponses
248​
249/**
250 * Creates a mutable operation accumulator populated with parser defaults.
251 *
252 * @category constructors
253 * @since 4.0.0
254 */
255export const makeDeepMutable = (options: {
256 readonly id: string
257 readonly method: Lowercase<HttpMethod>
258 readonly pathIds: Array<string>
259 readonly pathTemplate: string
260 readonly description: string | undefined
261}): Types.DeepMutable<ParsedOperation> => ({
262 ...options,
263 operationId: undefined,
264 path: "",
265 tags: [],
266 metadata: {
267 summary: undefined,
268 description: options.description,
269 deprecated: false,
270 externalDocs: undefined
271 },
272 parameters: {
273 path: [],
274 query: [],
275 header: [],
276 cookie: []
277 },
278 requestBody: undefined,
279 responses: [],
280 defaultResponse: undefined,
281 effectiveSecurity: [],
282 urlParams: [],
283 commaUrlParams: [],
284 headers: [],
285 cookies: [],
286 payloadFormData: false,
287 payloadFormUrlEncoded: false,
288 pathSchema: undefined,
289 querySchema: undefined,
290 querySchemaOptional: true,
291 headersSchema: undefined,
292 headersSchemaOptional: true,
293 requestBodyRepresentable: [],
294 httpClientResponses: {
295 successSchemas: new Map(),
296 errorSchemas: new Map(),
297 voidSuccessStatuses: new Set(),
298 voidErrorStatuses: new Set(),
299 sseSchemaMode: "data",
300 binarySuccessStatuses: new Set()
301 },
302 paramsOptional: true
303})