@kubb/ast 5.0.0-alpha.34 → 5.0.0-alpha.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3032 +0,0 @@
1
- import { t as __name } from "./chunk--u3MIqq1.js";
2
-
3
- //#region src/constants.d.ts
4
- /**
5
- * Traversal depth used by AST visitor utilities.
6
- */
7
- type VisitorDepth = 'shallow' | 'deep';
8
- declare const nodeKinds: {
9
- readonly input: "Input";
10
- readonly output: "Output";
11
- readonly operation: "Operation";
12
- readonly schema: "Schema";
13
- readonly property: "Property";
14
- readonly parameter: "Parameter";
15
- readonly response: "Response";
16
- readonly functionParameter: "FunctionParameter";
17
- readonly parameterGroup: "ParameterGroup";
18
- readonly functionParameters: "FunctionParameters";
19
- readonly type: "Type";
20
- readonly file: "File";
21
- readonly import: "Import";
22
- readonly export: "Export";
23
- readonly source: "Source";
24
- readonly text: "Text";
25
- readonly break: "Break";
26
- };
27
- /**
28
- * Canonical schema type strings used by AST schema nodes.
29
- *
30
- * These values are used across the AST as stable discriminators
31
- * (for example `schema.type === schemaTypes.object`).
32
- *
33
- * The map is grouped by intent:
34
- * - primitives (`string`, `number`, `boolean`, ...)
35
- * - structural/composite (`object`, `array`, `union`, ...)
36
- * - special OpenAPI-oriented types (`ref`, `datetime`, `uuid`, ...)
37
- */
38
- declare const schemaTypes: {
39
- /**
40
- * Text value.
41
- */
42
- readonly string: "string";
43
- /**
44
- * Floating-point number (`float`, `double`).
45
- */
46
- readonly number: "number";
47
- /**
48
- * Whole number (`int32`). Use `bigint` for `int64`.
49
- */
50
- readonly integer: "integer";
51
- /**
52
- * 64-bit integer (`int64`). Only used when `integerType` is set to `'bigint'`.
53
- */
54
- readonly bigint: "bigint";
55
- /**
56
- * Boolean value
57
- */
58
- readonly boolean: "boolean";
59
- /**
60
- * Explicit null value.
61
- */
62
- readonly null: "null";
63
- /**
64
- * Any value (no type restriction).
65
- */
66
- readonly any: "any";
67
- /**
68
- * Unknown value (must be narrowed before usage).
69
- */
70
- readonly unknown: "unknown";
71
- /**
72
- * No return value (`void`).
73
- */
74
- readonly void: "void";
75
- /**
76
- * Object with named properties.
77
- */
78
- readonly object: "object";
79
- /**
80
- * Sequential list of items.
81
- */
82
- readonly array: "array";
83
- /**
84
- * Fixed-length list with position-specific items.
85
- */
86
- readonly tuple: "tuple";
87
- /**
88
- * "One of" multiple schema members.
89
- */
90
- readonly union: "union";
91
- /**
92
- * "All of" multiple schema members.
93
- */
94
- readonly intersection: "intersection";
95
- /**
96
- * Enum schema.
97
- */
98
- readonly enum: "enum";
99
- /**
100
- * Reference to another schema.
101
- */
102
- readonly ref: "ref";
103
- /**
104
- * Calendar date (for example `2026-03-24`).
105
- */
106
- readonly date: "date";
107
- /**
108
- * Date-time value (for example `2026-03-24T09:00:00Z`).
109
- */
110
- readonly datetime: "datetime";
111
- /**
112
- * Time-only value (for example `09:00:00`).
113
- */
114
- readonly time: "time";
115
- /**
116
- * UUID value.
117
- */
118
- readonly uuid: "uuid";
119
- /**
120
- * Email address value.
121
- */
122
- readonly email: "email";
123
- /**
124
- * URL value.
125
- */
126
- readonly url: "url";
127
- /**
128
- * IPv4 address value.
129
- */
130
- readonly ipv4: "ipv4";
131
- /**
132
- * IPv6 address value.
133
- */
134
- readonly ipv6: "ipv6";
135
- /**
136
- * Binary/blob value.
137
- */
138
- readonly blob: "blob";
139
- /**
140
- * Impossible value (`never`).
141
- */
142
- readonly never: "never";
143
- };
144
- type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'boolean';
145
- /**
146
- * Returns `true` when `type` is a scalar primitive schema type.
147
- */
148
- declare function isScalarPrimitive(type: string): type is ScalarPrimitive;
149
- declare const httpMethods: {
150
- readonly get: "GET";
151
- readonly post: "POST";
152
- readonly put: "PUT";
153
- readonly patch: "PATCH";
154
- readonly delete: "DELETE";
155
- readonly head: "HEAD";
156
- readonly options: "OPTIONS";
157
- readonly trace: "TRACE";
158
- };
159
- declare const mediaTypes: {
160
- readonly applicationJson: "application/json";
161
- readonly applicationXml: "application/xml";
162
- readonly applicationFormUrlEncoded: "application/x-www-form-urlencoded";
163
- readonly applicationOctetStream: "application/octet-stream";
164
- readonly applicationPdf: "application/pdf";
165
- readonly applicationZip: "application/zip";
166
- readonly applicationGraphql: "application/graphql";
167
- readonly multipartFormData: "multipart/form-data";
168
- readonly textPlain: "text/plain";
169
- readonly textHtml: "text/html";
170
- readonly textCsv: "text/csv";
171
- readonly textXml: "text/xml";
172
- readonly imagePng: "image/png";
173
- readonly imageJpeg: "image/jpeg";
174
- readonly imageGif: "image/gif";
175
- readonly imageWebp: "image/webp";
176
- readonly imageSvgXml: "image/svg+xml";
177
- readonly audioMpeg: "audio/mpeg";
178
- readonly videoMp4: "video/mp4";
179
- };
180
- //#endregion
181
- //#region src/nodes/base.d.ts
182
- /**
183
- * `kind` values used by AST nodes.
184
- *
185
- * @example
186
- * ```ts
187
- * const kind: NodeKind = 'Schema'
188
- * ```
189
- */
190
- type NodeKind = 'Input' | 'Output' | 'Operation' | 'Schema' | 'Property' | 'Parameter' | 'Response' | 'FunctionParameter' | 'ParameterGroup' | 'FunctionParameters' | 'Type' | 'ParamsType' | 'File' | 'Import' | 'Export' | 'Source' | 'Const' | 'Function' | 'ArrowFunction' | 'Text' | 'Break' | 'Jsx';
191
- /**
192
- * Base shape shared by all AST nodes.
193
- *
194
- * @example
195
- * ```ts
196
- * const base: BaseNode = { kind: 'Input' }
197
- * ```
198
- */
199
- type BaseNode = {
200
- /**
201
- * Node discriminator.
202
- */
203
- kind: NodeKind;
204
- };
205
- //#endregion
206
- //#region src/nodes/code.d.ts
207
- /**
208
- * JSDoc documentation metadata attached to code declarations.
209
- */
210
- type JSDocNode = {
211
- /**
212
- * JSDoc comment lines. `undefined` entries are filtered out during rendering.
213
- * @example ['@description A pet resource', '@deprecated']
214
- */
215
- comments?: Array<string | undefined>;
216
- };
217
- /**
218
- * AST node representing a TypeScript `const` declaration.
219
- *
220
- * Mirrors the props of the `Const` component from `@kubb/renderer-jsx`.
221
- * The `children` prop of the component is represented as `nodes`.
222
- *
223
- * @example
224
- * ```ts
225
- * createConst({ name: 'pet', export: true, asConst: true })
226
- * // export const pet = ... as const
227
- * ```
228
- */
229
- type ConstNode = BaseNode & {
230
- /**
231
- * Node kind.
232
- */
233
- kind: 'Const';
234
- /**
235
- * Name of the constant declaration.
236
- */
237
- name: string;
238
- /**
239
- * Whether the declaration should be exported.
240
- * @default false
241
- */
242
- export?: boolean;
243
- /**
244
- * Optional explicit type annotation.
245
- * @example 'Pet'
246
- */
247
- type?: string;
248
- /**
249
- * JSDoc documentation metadata.
250
- */
251
- JSDoc?: JSDocNode;
252
- /**
253
- * Whether to append `as const` to the declaration.
254
- * @default false
255
- */
256
- asConst?: boolean;
257
- /**
258
- * Child nodes representing the value of the constant (children of the `Const` component).
259
- * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
260
- */
261
- nodes?: Array<CodeNode>;
262
- };
263
- /**
264
- * AST node representing a TypeScript `type` alias declaration.
265
- *
266
- * Mirrors the props of the `Type` component from `@kubb/renderer-jsx`.
267
- * The `children` prop of the component is represented as `nodes`.
268
- *
269
- * @example
270
- * ```ts
271
- * createType({ name: 'Pet', export: true })
272
- * // export type Pet = ...
273
- * ```
274
- */
275
- type TypeNode = BaseNode & {
276
- /**
277
- * Node kind.
278
- */
279
- kind: 'Type';
280
- /**
281
- * Name of the type alias.
282
- */
283
- name: string;
284
- /**
285
- * Whether the declaration should be exported.
286
- * @default false
287
- */
288
- export?: boolean;
289
- /**
290
- * JSDoc documentation metadata.
291
- */
292
- JSDoc?: JSDocNode;
293
- /**
294
- * Child nodes representing the type body (children of the `Type` component).
295
- * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
296
- */
297
- nodes?: Array<CodeNode>;
298
- };
299
- /**
300
- * Convenience alias for {@link TypeNode}.
301
- * @deprecated Use `TypeNode` directly.
302
- */
303
- type TypeDeclarationNode = TypeNode;
304
- /**
305
- * AST node representing a TypeScript `function` declaration.
306
- *
307
- * Mirrors the props of the `Function` component from `@kubb/renderer-jsx`.
308
- * The `children` prop of the component is represented as `nodes`.
309
- *
310
- * @example
311
- * ```ts
312
- * createFunctionDeclaration({ name: 'getPet', export: true, async: true, returnType: 'Pet' })
313
- * // export async function getPet(): Promise<Pet> { ... }
314
- * ```
315
- */
316
- type FunctionNode = BaseNode & {
317
- /**
318
- * Node kind.
319
- */
320
- kind: 'Function';
321
- /**
322
- * Name of the function.
323
- */
324
- name: string;
325
- /**
326
- * Whether the function is a default export.
327
- * @default false
328
- */
329
- default?: boolean;
330
- /**
331
- * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
332
- */
333
- params?: string;
334
- /**
335
- * Whether the function should be exported.
336
- * @default false
337
- */
338
- export?: boolean;
339
- /**
340
- * Whether the function is async. When `true`, the return type is wrapped in `Promise<>`.
341
- * @default false
342
- */
343
- async?: boolean;
344
- /**
345
- * TypeScript generic type parameters.
346
- * @example ['T', 'U extends string']
347
- */
348
- generics?: string | string[];
349
- /**
350
- * Return type annotation.
351
- * @example 'Pet'
352
- */
353
- returnType?: string;
354
- /**
355
- * JSDoc documentation metadata.
356
- */
357
- JSDoc?: JSDocNode;
358
- /**
359
- * Child nodes representing the function body (children of the `Function` component).
360
- * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
361
- */
362
- nodes?: Array<CodeNode>;
363
- };
364
- /**
365
- * AST node representing a TypeScript arrow function (`const name = () => { ... }`).
366
- *
367
- * Mirrors the props of the `Function.Arrow` component from `@kubb/renderer-jsx`.
368
- * The `children` prop of the component is represented as `nodes`.
369
- *
370
- * @example
371
- * ```ts
372
- * createArrowFunctionDeclaration({ name: 'getPet', export: true, singleLine: true })
373
- * // export const getPet = () => ...
374
- * ```
375
- */
376
- type ArrowFunctionNode = BaseNode & {
377
- /**
378
- * Node kind.
379
- */
380
- kind: 'ArrowFunction';
381
- /**
382
- * Name of the arrow function (used as the `const` variable name).
383
- */
384
- name: string;
385
- /**
386
- * Whether the function is a default export.
387
- * @default false
388
- */
389
- default?: boolean;
390
- /**
391
- * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
392
- */
393
- params?: string;
394
- /**
395
- * Whether the arrow function should be exported.
396
- * @default false
397
- */
398
- export?: boolean;
399
- /**
400
- * Whether the arrow function is async. When `true`, the return type is wrapped in `Promise<>`.
401
- * @default false
402
- */
403
- async?: boolean;
404
- /**
405
- * TypeScript generic type parameters.
406
- * @example ['T', 'U extends string']
407
- */
408
- generics?: string | string[];
409
- /**
410
- * Return type annotation.
411
- * @example 'Pet'
412
- */
413
- returnType?: string;
414
- /**
415
- * JSDoc documentation metadata.
416
- */
417
- JSDoc?: JSDocNode;
418
- /**
419
- * Render the arrow function body as a single-line expression.
420
- * @default false
421
- */
422
- singleLine?: boolean;
423
- /**
424
- * Child nodes representing the function body (children of the `Function.Arrow` component).
425
- * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
426
- */
427
- nodes?: Array<CodeNode>;
428
- };
429
- /**
430
- * AST node representing a raw text/string fragment in the source output.
431
- *
432
- * Used instead of bare `string` values so that all entries in `nodes` arrays
433
- * are typed `CodeNode` objects rather than a mixed `CodeNode | string` union.
434
- *
435
- * @example
436
- * ```ts
437
- * createText('return fetch(id)')
438
- * // { kind: 'Text', value: 'return fetch(id)' }
439
- * ```
440
- */
441
- type TextNode = BaseNode & {
442
- /**
443
- * Node kind.
444
- */
445
- kind: 'Text';
446
- /**
447
- * The raw string content.
448
- */
449
- value: string;
450
- };
451
- /**
452
- * AST node representing a line break in the source output.
453
- *
454
- * Corresponds to `<br/>` in JSX components. When printed, produces an empty
455
- * string that — joined with `\n` by `printNodes` — creates a blank line
456
- * between surrounding code nodes.
457
- *
458
- * @example
459
- * ```ts
460
- * createBreak()
461
- * // { kind: 'Break' }
462
- * // prints as '' → blank line when surrounded by other nodes
463
- * ```
464
- */
465
- type BreakNode = BaseNode & {
466
- /**
467
- * Node kind.
468
- */
469
- kind: 'Break';
470
- };
471
- /**
472
- * AST node representing a raw JSX fragment in the source output.
473
- *
474
- * Mirrors the `Jsx` component from `@kubb/renderer-jsx`. Use this to embed raw
475
- * JSX/TSX markup (including fragments `<>…</>`) directly in generated code.
476
- *
477
- * @example
478
- * ```ts
479
- * createJsx('<>\n <a href={href}>Open</a>\n</>')
480
- * // { kind: 'Jsx', value: '<>\n <a href={href}>Open</a>\n</>' }
481
- * ```
482
- */
483
- type JsxNode = BaseNode & {
484
- /**
485
- * Node kind.
486
- */
487
- kind: 'Jsx';
488
- /**
489
- * The raw JSX string content.
490
- */
491
- value: string;
492
- };
493
- /**
494
- * Union of all code-generation AST nodes.
495
- *
496
- * These nodes mirror the JSX components from `@kubb/renderer-jsx` and are used as
497
- * structured children in {@link SourceNode.nodes}.
498
- */
499
- type CodeNode = ConstNode | TypeNode | FunctionNode | ArrowFunctionNode | TextNode | BreakNode | JsxNode;
500
- //#endregion
501
- //#region src/nodes/file.d.ts
502
- /**
503
- * Supported file extensions.
504
- */
505
- type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`;
506
- type ImportName = string | Array<string | {
507
- propertyName: string;
508
- name?: string;
509
- }>;
510
- /**
511
- * Represents a language-agnostic import/dependency declaration.
512
- *
513
- * @example Named import (TypeScript: `import { useState } from 'react'`)
514
- * ```ts
515
- * createImport({ name: ['useState'], path: 'react' })
516
- * ```
517
- *
518
- * @example Default import (TypeScript: `import React from 'react'`)
519
- * ```ts
520
- * createImport({ name: 'React', path: 'react' })
521
- * ```
522
- *
523
- * @example Type-only import (TypeScript: `import type { FC } from 'react'`)
524
- * ```ts
525
- * createImport({ name: ['FC'], path: 'react', isTypeOnly: true })
526
- * ```
527
- *
528
- * @example Namespace import (TypeScript: `import * as React from 'react'`)
529
- * ```ts
530
- * createImport({ name: 'React', path: 'react', isNameSpace: true })
531
- * ```
532
- */
533
- type ImportNode = BaseNode & {
534
- kind: 'Import';
535
- /**
536
- * Import name(s) to be used.
537
- * @example ['useState']
538
- * @example 'React'
539
- */
540
- name: ImportName;
541
- /**
542
- * Path for the import.
543
- * @example '@kubb/core'
544
- */
545
- path: string;
546
- /**
547
- * Add type-only import prefix.
548
- * - `true` generates `import type { Type } from './path'`
549
- * - `false` generates `import { Type } from './path'`
550
- * @default false
551
- */
552
- isTypeOnly?: boolean;
553
- /**
554
- * Import entire module as namespace.
555
- * - `true` generates `import * as Name from './path'`
556
- * - `false` generates standard import
557
- * @default false
558
- */
559
- isNameSpace?: boolean;
560
- /**
561
- * When set, the import path is resolved relative to this root.
562
- */
563
- root?: string;
564
- };
565
- /**
566
- * Represents a language-agnostic export/public API declaration.
567
- *
568
- * @example Named export (TypeScript: `export { Pets } from './Pets'`)
569
- * ```ts
570
- * createExport({ name: ['Pets'], path: './Pets' })
571
- * ```
572
- *
573
- * @example Type-only export (TypeScript: `export type { Pet } from './Pet'`)
574
- * ```ts
575
- * createExport({ name: ['Pet'], path: './Pet', isTypeOnly: true })
576
- * ```
577
- *
578
- * @example Wildcard export (TypeScript: `export * from './utils'`)
579
- * ```ts
580
- * createExport({ path: './utils' })
581
- * ```
582
- *
583
- * @example Namespace alias (TypeScript: `export * as utils from './utils'`)
584
- * ```ts
585
- * createExport({ name: 'utils', path: './utils', asAlias: true })
586
- * ```
587
- */
588
- type ExportNode = BaseNode & {
589
- kind: 'Export';
590
- /**
591
- * Export name(s) to be used. When omitted, generates a wildcard export.
592
- * @example ['useState']
593
- * @example 'React'
594
- */
595
- name?: string | Array<string>;
596
- /**
597
- * Path for the export.
598
- * @example '@kubb/core'
599
- */
600
- path: string;
601
- /**
602
- * Add type-only export prefix.
603
- * - `true` generates `export type { Type } from './path'`
604
- * - `false` generates `export { Type } from './path'`
605
- * @default false
606
- */
607
- isTypeOnly?: boolean;
608
- /**
609
- * Export as an aliased namespace.
610
- * - `true` generates `export * as aliasName from './path'`
611
- * - `false` generates a standard export
612
- * @default false
613
- */
614
- asAlias?: boolean;
615
- };
616
- /**
617
- * Represents a fragment of source code within a file.
618
- *
619
- * @example Named exportable source
620
- * ```ts
621
- * createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')], isExportable: true, isIndexable: true })
622
- * ```
623
- *
624
- * @example Inline unnamed code block
625
- * ```ts
626
- * createSource({ nodes: [createText('const x = 1')] })
627
- * ```
628
- */
629
- type SourceNode = BaseNode & {
630
- kind: 'Source';
631
- /**
632
- * Optional name identifying this source (used for deduplication and barrel generation).
633
- */
634
- name?: string;
635
- /**
636
- * Mark this source as a type-only export.
637
- * @default false
638
- */
639
- isTypeOnly?: boolean;
640
- /**
641
- * Include `export` keyword in the generated source.
642
- * @default false
643
- */
644
- isExportable?: boolean;
645
- /**
646
- * Include this source in barrel/index file generation.
647
- * @default false
648
- */
649
- isIndexable?: boolean;
650
- /**
651
- * Structured child nodes representing the content of this source fragment, in DOM order.
652
- * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
653
- */
654
- nodes?: Array<CodeNode>;
655
- };
656
- /**
657
- * Represents a fully resolved file in the AST.
658
- *
659
- * Created via `createFile()`, which computes the `id`, `name`, and `extname` from the input
660
- * and deduplicates `imports`, `exports`, and `sources`.
661
- *
662
- * @example
663
- * ```ts
664
- * const file = createFile({
665
- * baseName: 'petStore.ts',
666
- * path: 'src/models/petStore.ts',
667
- * sources: [createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')], isExportable: true })],
668
- * imports: [createImport({ name: ['z'], path: 'zod' })],
669
- * exports: [createExport({ name: ['Pet'], path: './petStore' })],
670
- * })
671
- * // file.id = SHA256 hash of the path
672
- * // file.name = 'petStore'
673
- * // file.extname = '.ts'
674
- * ```
675
- */
676
- type FileNode<TMeta extends object = object> = BaseNode & {
677
- kind: 'File';
678
- /**
679
- * Unique identifier derived from a SHA256 hash of the file path.
680
- * @default hash
681
- */
682
- id: string;
683
- /**
684
- * File name without extension, derived from `baseName`.
685
- * @link https://nodejs.org/api/path.html#pathformatpathobject
686
- */
687
- name: string;
688
- /**
689
- * File base name, including extension.
690
- * Based on UNIX basename: `${name}${extname}`
691
- * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
692
- */
693
- baseName: `${string}.${string}`;
694
- /**
695
- * Full qualified path to the file.
696
- */
697
- path: string;
698
- /**
699
- * File extension extracted from `baseName`.
700
- */
701
- extname: Extname;
702
- /**
703
- * Deduplicated list of source code fragments.
704
- */
705
- sources: Array<SourceNode>;
706
- /**
707
- * Deduplicated list of import declarations.
708
- */
709
- imports: Array<ImportNode>;
710
- /**
711
- * Deduplicated list of export declarations.
712
- */
713
- exports: Array<ExportNode>;
714
- /**
715
- * Optional metadata attached to this file (used by plugins for barrel generation etc.).
716
- */
717
- meta?: TMeta;
718
- /**
719
- * Optional banner prepended to the generated file content.
720
- */
721
- banner?: string;
722
- /**
723
- * Optional footer appended to the generated file content.
724
- */
725
- footer?: string;
726
- };
727
- //#endregion
728
- //#region src/nodes/function.d.ts
729
- /**
730
- * AST node representing a language-agnostic type expression used as a function parameter
731
- * type annotation. Each language printer renders the variant into its own syntax.
732
- *
733
- * - `struct` — an inline anonymous type grouping named fields.
734
- * TypeScript renders as `{ petId: string; name?: string }`.
735
- * - `member` — a single named field accessed from a named group type.
736
- * TypeScript renders as `PathParams['petId']`.
737
- *
738
- * @example Reference variant
739
- * ```ts
740
- * createParamsType({ variant: 'reference', name: 'QueryParams' })
741
- * // QueryParams
742
- * ```
743
- *
744
- * @example Struct variant
745
- * ```ts
746
- * createParamsType({ variant: 'struct', properties: [{ name: 'petId', optional: false, type: createParamsType({ variant: 'reference', name: 'string' }) }] })
747
- * // { petId: string }
748
- * ```
749
- *
750
- * @example Member variant
751
- * ```ts
752
- * createParamsType({ variant: 'member', base: 'PathParams', key: 'petId' })
753
- * // PathParams['petId']
754
- * ```
755
- */
756
- type ParamsTypeNode = BaseNode & {
757
- /**
758
- * Node kind.
759
- */
760
- kind: 'ParamsType';
761
- } & ({
762
- /**
763
- * Reference variant — a plain type name or identifier.
764
- * TypeScript renders as-is, e.g. `string`, `QueryParams`, `Partial<Config>`.
765
- */
766
- variant: 'reference';
767
- /**
768
- * The full type name string, e.g. `'string'`, `'QueryParams'`, `'Partial<Config>'`.
769
- */
770
- name: string;
771
- } | {
772
- /**
773
- * Struct variant — an inline anonymous type grouping named fields.
774
- * TypeScript renders as `{ key: Type; other?: OtherType }`.
775
- */
776
- variant: 'struct';
777
- /**
778
- * Properties of the struct type.
779
- */
780
- properties: Array<{
781
- name: string;
782
- optional: boolean;
783
- type: ParamsTypeNode;
784
- }>;
785
- } | {
786
- /**
787
- * Member variant — a single named field accessed from a group type.
788
- * TypeScript renders as `Base['key']`.
789
- */
790
- variant: 'member';
791
- /**
792
- * Base type name, e.g. `'DeletePetPathParams'`.
793
- */
794
- base: string;
795
- /**
796
- * The field name to access, e.g. `'petId'`.
797
- */
798
- key: string;
799
- });
800
- /**
801
- * AST node for one function parameter.
802
- *
803
- * @example Required parameter
804
- * `name: Type`
805
- *
806
- * @example Optional parameter
807
- * `name?: Type`
808
- *
809
- * @example Parameter with default value
810
- * `name: Type = defaultValue`
811
- *
812
- * @example Rest parameter
813
- * `...name: Type[]`
814
- */
815
- type FunctionParameterNode = BaseNode & {
816
- /**
817
- * Node kind.
818
- */
819
- kind: 'FunctionParameter';
820
- /**
821
- * Parameter name in the generated signature.
822
- */
823
- name: string;
824
- /**
825
- * Type annotation as a structured {@link ParamsTypeNode}.
826
- * Omit for untyped output.
827
- *
828
- * @example Reference type node
829
- * `{ kind: 'ParamsType', variant: 'reference', name: 'string' }` → `petId: string`
830
- *
831
- * @example Struct type node
832
- * `{ kind: 'ParamsType', variant: 'struct', properties: [...] }` → `{ key: Type; other?: OtherType }`
833
- *
834
- * @example Member type node
835
- * `{ kind: 'ParamsType', variant: 'member', base: 'PathParams', key: 'petId' }` → `PathParams['petId']`
836
- */
837
- type?: ParamsTypeNode;
838
- /**
839
- * When `true` the parameter is emitted as a rest parameter.
840
- *
841
- * @example Rest parameter
842
- * `...name: Type[]`
843
- */
844
- rest?: boolean;
845
- }
846
- /**
847
- * Optional parameter — rendered with `?` and may be omitted by the caller.
848
- * Cannot be combined with `default` because a defaulted parameter is already optional.
849
- */
850
- & ({
851
- optional: true;
852
- default?: never;
853
- }
854
- /**
855
- * Required parameter, or a parameter with a default value.
856
- *
857
- * @example Required
858
- * `name: Type`
859
- *
860
- * @example With default
861
- * `name: Type = default`
862
- */
863
- | {
864
- optional?: false;
865
- default?: string;
866
- });
867
- /**
868
- * AST node for a group of related function parameters treated as a single unit.
869
- *
870
- * Each language printer decides how to render this group:
871
- * - TypeScript/JS: destructured object `{ key1, key2 }: { key1: Type1; key2: Type2 } = {}`
872
- * - Python: keyword-only args or a typed dict parameter
873
- * - C# / Kotlin: named record / data-class parameter
874
- *
875
- * When `inline` is `true`, the group is spread as individual top-level parameters
876
- * rather than wrapped in a single grouped construct.
877
- *
878
- * @example Grouped destructuring
879
- * `{ id, name }: { id: string; name: string } = {}`
880
- *
881
- * @example Inline (spread as individual parameters)
882
- * `id: string, name: string`
883
- */
884
- type ParameterGroupNode = BaseNode & {
885
- /**
886
- * Node kind.
887
- */
888
- kind: 'ParameterGroup';
889
- /**
890
- * The individual parameters that form the group.
891
- * Rendered as a destructured object or spread inline when `inline` is `true`.
892
- */
893
- properties: Array<FunctionParameterNode>;
894
- /**
895
- * Optional explicit type annotation for the whole group.
896
- * When absent, printers auto-compute it from `properties`.
897
- */
898
- type?: ParamsTypeNode;
899
- /**
900
- * When `true`, `properties` are emitted as individual top-level parameters instead of
901
- * being wrapped in a single grouped construct.
902
- *
903
- * @default false
904
- */
905
- inline?: boolean;
906
- /**
907
- * Whether the group as a whole is optional.
908
- * If omitted, printers infer this from child properties.
909
- */
910
- optional?: boolean;
911
- /**
912
- * Default value for the group, written verbatim after `=`.
913
- * Commonly `'{}'` to allow omitting the argument entirely.
914
- */
915
- default?: string;
916
- };
917
- /**
918
- * AST node for a complete function parameter list.
919
- *
920
- * Printers are responsible for sorting (`required` → `optional` → `defaulted`).
921
- * Nodes are plain immutable data.
922
- *
923
- * Renders differently depending on the output mode:
924
- * - `declaration` → `(id: string, config: Config = {})` — function declaration parameters
925
- * - `call` → `(id, { method, url })` — function call arguments
926
- * - `keys` → `{ id, config }` — key names only (for destructuring)
927
- * - `values` → `{ id: id, config: config }` — key → value pairs
928
- */
929
- type FunctionParametersNode = BaseNode & {
930
- /**
931
- * Node kind.
932
- */
933
- kind: 'FunctionParameters';
934
- /**
935
- * Ordered parameter nodes.
936
- */
937
- params: ReadonlyArray<FunctionParameterNode | ParameterGroupNode>;
938
- };
939
- /**
940
- * Union of all function-parameter AST node variants used by the function-parameter printer.
941
- */
942
- type FunctionParamNode = FunctionParameterNode | ParameterGroupNode | FunctionParametersNode | ParamsTypeNode;
943
- /**
944
- * Handler map keys — one per `FunctionParamNode` kind.
945
- */
946
- type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'paramsType';
947
- //#endregion
948
- //#region src/nodes/property.d.ts
949
- /**
950
- * AST node representing one named object property.
951
- *
952
- * @example
953
- * ```ts
954
- * const property: PropertyNode = {
955
- * kind: 'Property',
956
- * name: 'id',
957
- * schema: createSchema({ type: 'integer' }),
958
- * required: true,
959
- * }
960
- * ```
961
- */
962
- type PropertyNode = BaseNode & {
963
- /**
964
- * Node kind.
965
- */
966
- kind: 'Property';
967
- /**
968
- * Property key.
969
- */
970
- name: string;
971
- /**
972
- * Property schema.
973
- */
974
- schema: SchemaNode;
975
- /**
976
- * Whether the property is required.
977
- */
978
- required: boolean;
979
- };
980
- //#endregion
981
- //#region src/nodes/schema.d.ts
982
- type PrimitiveSchemaType =
983
- /**
984
- * Text value.
985
- */
986
- 'string'
987
- /**
988
- * Floating-point number.
989
- */
990
- | 'number'
991
- /**
992
- * Integer number.
993
- */
994
- | 'integer'
995
- /**
996
- * Big integer number.
997
- */
998
- | 'bigint'
999
- /**
1000
- * Boolean value.
1001
- */
1002
- | 'boolean'
1003
- /**
1004
- * Null value.
1005
- */
1006
- | 'null'
1007
- /**
1008
- * Any value.
1009
- */
1010
- | 'any'
1011
- /**
1012
- * Unknown value.
1013
- */
1014
- | 'unknown'
1015
- /**
1016
- * No value (`void`).
1017
- */
1018
- | 'void'
1019
- /**
1020
- * Never value.
1021
- */
1022
- | 'never'
1023
- /**
1024
- * Object value.
1025
- */
1026
- | 'object'
1027
- /**
1028
- * Array value.
1029
- */
1030
- | 'array'
1031
- /**
1032
- * Date value.
1033
- */
1034
- | 'date';
1035
- /**
1036
- * Composite schema types.
1037
- */
1038
- type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum';
1039
- /**
1040
- * Schema types that need special handling in generators.
1041
- */
1042
- type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'ipv4' | 'ipv6' | 'blob';
1043
- /**
1044
- * All schema type strings.
1045
- */
1046
- type SchemaType = PrimitiveSchemaType | ComplexSchemaType | SpecialSchemaType;
1047
- /**
1048
- * Scalar schema types without extra object/array/ref structure.
1049
- */
1050
- type ScalarSchemaType = Exclude<SchemaType, 'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint' | 'url' | 'uuid' | 'email'>;
1051
- /**
1052
- * Fields shared by all schema nodes.
1053
- */
1054
- type SchemaNodeBase = BaseNode & {
1055
- /**
1056
- * Node kind.
1057
- */
1058
- kind: 'Schema';
1059
- /**
1060
- * Schema name for named definitions (for example, `"Pet"`).
1061
- * Inline schemas omit this field.
1062
- * `null` means kubb has processed this and determined there is no applicable name.
1063
- * `undefined` means the name has not been set yet.
1064
- */
1065
- name?: string | null;
1066
- /**
1067
- * Short schema title.
1068
- */
1069
- title?: string;
1070
- /**
1071
- * Schema description text.
1072
- */
1073
- description?: string;
1074
- /**
1075
- * Whether `null` is allowed.
1076
- */
1077
- nullable?: boolean;
1078
- /**
1079
- * Whether the field is optional.
1080
- */
1081
- optional?: boolean;
1082
- /**
1083
- * Both optional and nullable (`optional` + `nullable`).
1084
- */
1085
- nullish?: boolean;
1086
- /**
1087
- * Whether the schema is deprecated.
1088
- */
1089
- deprecated?: boolean;
1090
- /**
1091
- * Whether the schema is read-only.
1092
- */
1093
- readOnly?: boolean;
1094
- /**
1095
- * Whether the schema is write-only.
1096
- */
1097
- writeOnly?: boolean;
1098
- /**
1099
- * Default value.
1100
- */
1101
- default?: unknown;
1102
- /**
1103
- * Example value.
1104
- */
1105
- example?: unknown;
1106
- /**
1107
- * Base primitive type.
1108
- * For example, this is `'string'` for a `uuid` schema.
1109
- */
1110
- primitive?: PrimitiveSchemaType;
1111
- };
1112
- /**
1113
- * Object schema with ordered properties.
1114
- *
1115
- * @example
1116
- * ```ts
1117
- * const objectSchema: ObjectSchemaNode = {
1118
- * kind: 'Schema',
1119
- * type: 'object',
1120
- * properties: [],
1121
- * }
1122
- * ```
1123
- */
1124
- type ObjectSchemaNode = SchemaNodeBase & {
1125
- /**
1126
- * Schema type discriminator.
1127
- */
1128
- type: 'object';
1129
- /**
1130
- * Primitive type — always `'object'` for object schemas.
1131
- */
1132
- primitive: 'object';
1133
- /**
1134
- * Ordered object properties.
1135
- */
1136
- properties: Array<PropertyNode>;
1137
- /**
1138
- * Additional object properties behavior:
1139
- * - `true`: allow any value
1140
- * - `false`: reject unknown properties (maps to `.strict()` in Zod)
1141
- * - `SchemaNode`: allow values that match that schema
1142
- * - `undefined`: no additional properties constraint (open object)
1143
- */
1144
- additionalProperties?: SchemaNode | boolean;
1145
- /**
1146
- * Pattern-based property schemas.
1147
- */
1148
- patternProperties?: Record<string, SchemaNode>;
1149
- /**
1150
- * Minimum number of properties allowed.
1151
- */
1152
- minProperties?: number;
1153
- /**
1154
- * Maximum number of properties allowed.
1155
- */
1156
- maxProperties?: number;
1157
- };
1158
- /**
1159
- * Array-like schema (`array` or `tuple`).
1160
- *
1161
- * @example
1162
- * ```ts
1163
- * const arraySchema: ArraySchemaNode = {
1164
- * kind: 'Schema',
1165
- * type: 'array',
1166
- * items: [],
1167
- * }
1168
- * ```
1169
- */
1170
- type ArraySchemaNode = SchemaNodeBase & {
1171
- /**
1172
- * Schema type discriminator (`array` or `tuple`).
1173
- */
1174
- type: 'array' | 'tuple';
1175
- /**
1176
- * Item schemas.
1177
- */
1178
- items?: Array<SchemaNode>;
1179
- /**
1180
- * Tuple rest-item schema for elements beyond positional `items`.
1181
- */
1182
- rest?: SchemaNode;
1183
- /**
1184
- * Minimum item count (or tuple length).
1185
- */
1186
- min?: number;
1187
- /**
1188
- * Maximum item count (or tuple length).
1189
- */
1190
- max?: number;
1191
- /**
1192
- * Whether all items must be unique.
1193
- */
1194
- unique?: boolean;
1195
- };
1196
- /**
1197
- * Shared shape for union and intersection schemas.
1198
- */
1199
- type CompositeSchemaNodeBase = SchemaNodeBase & {
1200
- /**
1201
- * Member schemas.
1202
- */
1203
- members?: Array<SchemaNode>;
1204
- };
1205
- /**
1206
- * Union schema, often from `oneOf` or `anyOf`.
1207
- *
1208
- * @example
1209
- * ```ts
1210
- * const unionSchema: UnionSchemaNode = {
1211
- * kind: 'Schema',
1212
- * type: 'union',
1213
- * members: [],
1214
- * }
1215
- * ```
1216
- */
1217
- type UnionSchemaNode = CompositeSchemaNodeBase & {
1218
- /**
1219
- * Schema type discriminator.
1220
- */
1221
- type: 'union';
1222
- /**
1223
- * Discriminator property name from OpenAPI `discriminator.propertyName`.
1224
- */
1225
- discriminatorPropertyName?: string;
1226
- };
1227
- /**
1228
- * Intersection schema, often from `allOf`.
1229
- *
1230
- * @example
1231
- * ```ts
1232
- * const intersectionSchema: IntersectionSchemaNode = {
1233
- * kind: 'Schema',
1234
- * type: 'intersection',
1235
- * members: [],
1236
- * }
1237
- * ```
1238
- */
1239
- type IntersectionSchemaNode = CompositeSchemaNodeBase & {
1240
- /**
1241
- * Schema type discriminator.
1242
- */
1243
- type: 'intersection';
1244
- };
1245
- /**
1246
- * One named enum item.
1247
- */
1248
- type EnumValueNode = {
1249
- /**
1250
- * Enum item name.
1251
- */
1252
- name: string;
1253
- /**
1254
- * Enum item value.
1255
- */
1256
- value: string | number | boolean;
1257
- /**
1258
- * Primitive type of the enum value.
1259
- */
1260
- primitive: Extract<PrimitiveSchemaType, 'string' | 'number' | 'boolean'>;
1261
- };
1262
- /**
1263
- * Enum schema node.
1264
- *
1265
- * @example
1266
- * ```ts
1267
- * const enumSchema: EnumSchemaNode = {
1268
- * kind: 'Schema',
1269
- * type: 'enum',
1270
- * enumValues: ['a', 'b'],
1271
- * }
1272
- * ```
1273
- */
1274
- type EnumSchemaNode = SchemaNodeBase & {
1275
- /**
1276
- * Schema type discriminator.
1277
- */
1278
- type: 'enum';
1279
- /**
1280
- * Enum values in simple form.
1281
- */
1282
- enumValues?: Array<string | number | boolean | null>;
1283
- /**
1284
- * Enum values in named form.
1285
- * If present, this is used instead of `enumValues`.
1286
- */
1287
- namedEnumValues?: Array<EnumValueNode>;
1288
- };
1289
- /**
1290
- * Reference schema that points to another schema definition.
1291
- *
1292
- * @example
1293
- * ```ts
1294
- * const refSchema: RefSchemaNode = {
1295
- * kind: 'Schema',
1296
- * type: 'ref',
1297
- * ref: '#/components/schemas/Pet',
1298
- * }
1299
- * ```
1300
- */
1301
- type RefSchemaNode = SchemaNodeBase & {
1302
- /**
1303
- * Schema type discriminator.
1304
- */
1305
- type: 'ref';
1306
- /**
1307
- * Referenced schema name.
1308
- */
1309
- name?: string;
1310
- /**
1311
- * Original `$ref` path, for example, `#/components/schemas/Order`.
1312
- * Used to resolve names later.
1313
- */
1314
- ref?: string;
1315
- /**
1316
- * Pattern copied from a sibling `pattern` field.
1317
- */
1318
- pattern?: string;
1319
- /**
1320
- * The fully-parsed schema that this ref resolves to.
1321
- * Populated during OAS parsing when the referenced definition can be resolved.
1322
- * `undefined` when the ref cannot be resolved or is part of a circular chain.
1323
- *
1324
- * Useful for inspecting the referenced schema's structure (e.g. `primitive`, `properties`)
1325
- * without following the reference manually.
1326
- */
1327
- schema?: SchemaNode;
1328
- };
1329
- /**
1330
- * Datetime schema.
1331
- *
1332
- * @example
1333
- * ```ts
1334
- * const datetimeSchema: DatetimeSchemaNode = { kind: 'Schema', type: 'datetime' }
1335
- * ```
1336
- */
1337
- type DatetimeSchemaNode = SchemaNodeBase & {
1338
- /**
1339
- * Schema type discriminator.
1340
- */
1341
- type: 'datetime';
1342
- /**
1343
- * Whether the datetime includes a timezone offset (`dateType: 'stringOffset'`).
1344
- */
1345
- offset?: boolean;
1346
- /**
1347
- * Whether the datetime is local (no timezone, `dateType: 'stringLocal'`).
1348
- */
1349
- local?: boolean;
1350
- };
1351
- /**
1352
- * Shared base for `date` and `time` schemas.
1353
- */
1354
- type TemporalSchemaNodeBase<T extends 'date' | 'time'> = SchemaNodeBase & {
1355
- /**
1356
- * Schema type discriminator.
1357
- */
1358
- type: T;
1359
- /**
1360
- * Output representation in generated code.
1361
- */
1362
- representation: 'date' | 'string';
1363
- };
1364
- /**
1365
- * Date schema node.
1366
- *
1367
- * @example
1368
- * ```ts
1369
- * const dateSchema: DateSchemaNode = { kind: 'Schema', type: 'date', representation: 'string' }
1370
- * ```
1371
- */
1372
- type DateSchemaNode = TemporalSchemaNodeBase<'date'>;
1373
- /**
1374
- * Time schema node.
1375
- *
1376
- * @example
1377
- * ```ts
1378
- * const timeSchema: TimeSchemaNode = { kind: 'Schema', type: 'time', representation: 'string' }
1379
- * ```
1380
- */
1381
- type TimeSchemaNode = TemporalSchemaNodeBase<'time'>;
1382
- /**
1383
- * String schema node.
1384
- *
1385
- * @example
1386
- * ```ts
1387
- * const stringSchema: StringSchemaNode = { kind: 'Schema', type: 'string' }
1388
- * ```
1389
- */
1390
- type StringSchemaNode = SchemaNodeBase & {
1391
- /**
1392
- * Schema type discriminator.
1393
- */
1394
- type: 'string';
1395
- /**
1396
- * Minimum string length.
1397
- */
1398
- min?: number;
1399
- /**
1400
- * Maximum string length.
1401
- */
1402
- max?: number;
1403
- /**
1404
- * Regex pattern.
1405
- */
1406
- pattern?: string;
1407
- };
1408
- /**
1409
- * Numeric schema (`number`, `integer`, or `bigint`).
1410
- *
1411
- * @example
1412
- * ```ts
1413
- * const numberSchema: NumberSchemaNode = { kind: 'Schema', type: 'number' }
1414
- * ```
1415
- */
1416
- type NumberSchemaNode = SchemaNodeBase & {
1417
- /**
1418
- * Schema type discriminator.
1419
- */
1420
- type: 'number' | 'integer' | 'bigint';
1421
- /**
1422
- * Minimum value.
1423
- */
1424
- min?: number;
1425
- /**
1426
- * Maximum value.
1427
- */
1428
- max?: number;
1429
- /**
1430
- * Exclusive minimum value.
1431
- */
1432
- exclusiveMinimum?: number;
1433
- /**
1434
- * Exclusive maximum value.
1435
- */
1436
- exclusiveMaximum?: number;
1437
- /**
1438
- * The value must be a multiple of this number.
1439
- */
1440
- multipleOf?: number;
1441
- };
1442
- /**
1443
- * Scalar schema with no extra constraints.
1444
- *
1445
- * @example
1446
- * ```ts
1447
- * const anySchema: ScalarSchemaNode = { kind: 'Schema', type: 'any' }
1448
- * ```
1449
- */
1450
- type ScalarSchemaNode = SchemaNodeBase & {
1451
- /**
1452
- * Schema type discriminator.
1453
- */
1454
- type: ScalarSchemaType;
1455
- };
1456
- /**
1457
- * URL schema node.
1458
- * Can include an OpenAPI-style path template for template literal types.
1459
- *
1460
- * @example
1461
- * ```ts
1462
- * const urlSchema: UrlSchemaNode = { kind: 'Schema', type: 'url', path: '/pets/{petId}' }
1463
- * ```
1464
- */
1465
- type UrlSchemaNode = SchemaNodeBase & {
1466
- /**
1467
- * Schema type discriminator.
1468
- */
1469
- type: 'url';
1470
- /**
1471
- * OpenAPI-style path template, for example, `'/pets/{petId}'`.
1472
- */
1473
- path?: string;
1474
- /**
1475
- * Minimum string length.
1476
- */
1477
- min?: number;
1478
- /**
1479
- * Maximum string length.
1480
- */
1481
- max?: number;
1482
- };
1483
- /**
1484
- * Format-string schema for string-based formats that support length constraints.
1485
- *
1486
- * @example
1487
- * ```ts
1488
- * const uuidSchema: FormatStringSchemaNode = { kind: 'Schema', type: 'uuid', min: 36, max: 36 }
1489
- * ```
1490
- */
1491
- type FormatStringSchemaNode = SchemaNodeBase & {
1492
- /**
1493
- * Schema type discriminator.
1494
- */
1495
- type: 'uuid' | 'email';
1496
- /**
1497
- * Minimum string length.
1498
- */
1499
- min?: number;
1500
- /**
1501
- * Maximum string length.
1502
- */
1503
- max?: number;
1504
- };
1505
- /**
1506
- * IPv4 address schema node.
1507
- *
1508
- * @example
1509
- * ```ts
1510
- * const ipv4Schema: Ipv4SchemaNode = { kind: 'Schema', type: 'ipv4' }
1511
- * ```
1512
- */
1513
- type Ipv4SchemaNode = SchemaNodeBase & {
1514
- /**
1515
- * Schema type discriminator.
1516
- */
1517
- type: 'ipv4';
1518
- };
1519
- /**
1520
- * IPv6 address schema node.
1521
- *
1522
- * @example
1523
- * ```ts
1524
- * const ipv6Schema: Ipv6SchemaNode = { kind: 'Schema', type: 'ipv6' }
1525
- * ```
1526
- */
1527
- type Ipv6SchemaNode = SchemaNodeBase & {
1528
- /**
1529
- * Schema type discriminator.
1530
- */
1531
- type: 'ipv6';
1532
- };
1533
- /**
1534
- * Mapping from schema type literals to concrete schema node types.
1535
- * Used by `narrowSchema`.
1536
- */
1537
- type SchemaNodeByType = {
1538
- object: ObjectSchemaNode;
1539
- array: ArraySchemaNode;
1540
- tuple: ArraySchemaNode;
1541
- union: UnionSchemaNode;
1542
- intersection: IntersectionSchemaNode;
1543
- enum: EnumSchemaNode;
1544
- ref: RefSchemaNode;
1545
- datetime: DatetimeSchemaNode;
1546
- date: DateSchemaNode;
1547
- time: TimeSchemaNode;
1548
- string: StringSchemaNode;
1549
- number: NumberSchemaNode;
1550
- integer: NumberSchemaNode;
1551
- bigint: NumberSchemaNode;
1552
- boolean: ScalarSchemaNode;
1553
- null: ScalarSchemaNode;
1554
- any: ScalarSchemaNode;
1555
- unknown: ScalarSchemaNode;
1556
- void: ScalarSchemaNode;
1557
- never: ScalarSchemaNode;
1558
- uuid: FormatStringSchemaNode;
1559
- email: FormatStringSchemaNode;
1560
- url: UrlSchemaNode;
1561
- ipv4: Ipv4SchemaNode;
1562
- ipv6: Ipv6SchemaNode;
1563
- blob: ScalarSchemaNode;
1564
- };
1565
- /**
1566
- * Union of all schema node types.
1567
- */
1568
- type SchemaNode = ObjectSchemaNode | ArraySchemaNode | UnionSchemaNode | IntersectionSchemaNode | EnumSchemaNode | RefSchemaNode | DatetimeSchemaNode | DateSchemaNode | TimeSchemaNode | StringSchemaNode | NumberSchemaNode | UrlSchemaNode | FormatStringSchemaNode | Ipv4SchemaNode | Ipv6SchemaNode | ScalarSchemaNode;
1569
- //#endregion
1570
- //#region src/nodes/parameter.d.ts
1571
- type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
1572
- /**
1573
- * AST node representing one operation parameter.
1574
- *
1575
- * @example
1576
- * ```ts
1577
- * const param: ParameterNode = {
1578
- * kind: 'Parameter',
1579
- * name: 'petId',
1580
- * in: 'path',
1581
- * schema: createSchema({ type: 'string' }),
1582
- * required: true,
1583
- * }
1584
- * ```
1585
- */
1586
- type ParameterNode = BaseNode & {
1587
- /**
1588
- * Node kind.
1589
- */
1590
- kind: 'Parameter';
1591
- /**
1592
- * Parameter name.
1593
- */
1594
- name: string;
1595
- /**
1596
- * Parameter location (`path`, `query`, `header`, or `cookie`).
1597
- */
1598
- in: ParameterLocation;
1599
- /**
1600
- * Parameter schema.
1601
- */
1602
- schema: SchemaNode;
1603
- /**
1604
- * Whether the parameter is required.
1605
- */
1606
- required: boolean;
1607
- };
1608
- //#endregion
1609
- //#region src/nodes/http.d.ts
1610
- /**
1611
- * All supported HTTP status code literals as strings, as used in API specs
1612
- * (for example, `"200"` and `"404"`).
1613
- */
1614
- type HttpStatusCode = '100' | '101' | '102' | '103' | '200' | '201' | '202' | '203' | '204' | '205' | '206' | '207' | '208' | '226' | '300' | '301' | '302' | '303' | '304' | '305' | '307' | '308' | '400' | '401' | '402' | '403' | '404' | '405' | '406' | '407' | '408' | '409' | '410' | '411' | '412' | '413' | '414' | '415' | '416' | '417' | '418' | '421' | '422' | '423' | '424' | '425' | '426' | '428' | '429' | '431' | '451' | '500' | '501' | '502' | '503' | '504' | '505' | '506' | '507' | '508' | '510' | '511';
1615
- /**
1616
- * Response status code literal used by operations.
1617
- *
1618
- * Includes specific HTTP status code strings and `"default"` for catch-all responses.
1619
- *
1620
- * @example
1621
- * ```ts
1622
- * const status: StatusCode = '200'
1623
- * const fallback: StatusCode = 'default'
1624
- * ```
1625
- */
1626
- type StatusCode = HttpStatusCode | 'default';
1627
- /**
1628
- * Supported media type strings used in request and response bodies.
1629
- *
1630
- * @example
1631
- * ```ts
1632
- * const mediaType: MediaType = 'application/json'
1633
- * ```
1634
- */
1635
- type MediaType = 'application/json' | 'application/xml' | 'application/x-www-form-urlencoded' | 'application/octet-stream' | 'application/pdf' | 'application/zip' | 'application/graphql' | 'multipart/form-data' | 'text/plain' | 'text/html' | 'text/csv' | 'text/xml' | 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/svg+xml' | 'audio/mpeg' | 'video/mp4';
1636
- //#endregion
1637
- //#region src/nodes/response.d.ts
1638
- /**
1639
- * AST node representing one operation response variant.
1640
- *
1641
- * @example
1642
- * ```ts
1643
- * const response: ResponseNode = {
1644
- * kind: 'Response',
1645
- * statusCode: '200',
1646
- * schema: createSchema({ type: 'string' }),
1647
- * }
1648
- * ```
1649
- */
1650
- type ResponseNode = BaseNode & {
1651
- /**
1652
- * Node kind.
1653
- */
1654
- kind: 'Response';
1655
- /**
1656
- * HTTP status code or `'default'` for a fallback response.
1657
- */
1658
- statusCode: StatusCode;
1659
- /**
1660
- * Optional response description.
1661
- */
1662
- description?: string;
1663
- /**
1664
- * Response body schema.
1665
- */
1666
- schema: SchemaNode;
1667
- /**
1668
- * Response media type.
1669
- */
1670
- mediaType?: MediaType | null;
1671
- /**
1672
- * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
1673
- * Set when a referenced schema has `writeOnly` fields that should not appear in response types.
1674
- */
1675
- keysToOmit?: Array<string>;
1676
- };
1677
- //#endregion
1678
- //#region src/nodes/operation.d.ts
1679
- type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
1680
- /**
1681
- * AST node representing one API operation.
1682
- *
1683
- * @example
1684
- * ```ts
1685
- * const operation: OperationNode = {
1686
- * kind: 'Operation',
1687
- * operationId: 'listPets',
1688
- * method: 'GET',
1689
- * path: '/pets',
1690
- * tags: [],
1691
- * parameters: [],
1692
- * responses: [],
1693
- * }
1694
- * ```
1695
- */
1696
- type OperationNode = BaseNode & {
1697
- /**
1698
- * Node kind.
1699
- */
1700
- kind: 'Operation';
1701
- /**
1702
- * Operation identifier, usually from OpenAPI `operationId`.
1703
- */
1704
- operationId: string;
1705
- /**
1706
- * HTTP Method like 'GET'
1707
- */
1708
- method: HttpMethod;
1709
- /**
1710
- * OpenAPI-style path string, for example `/pets/{petId}`.
1711
- * Path parameters retain the `{param}` notation from the original spec.
1712
- */
1713
- path: string;
1714
- /**
1715
- * Group labels for the operation.
1716
- * Usually copied from OpenAPI `tags`.
1717
- */
1718
- tags: Array<string>;
1719
- /**
1720
- * Short one-line operation summary.
1721
- */
1722
- summary?: string;
1723
- /**
1724
- * Full operation description.
1725
- */
1726
- description?: string;
1727
- /**
1728
- * Marks the operation as deprecated.
1729
- */
1730
- deprecated?: boolean;
1731
- /**
1732
- * Parameters that could be used, we have QueryParams, PathParams, HeaderParams and CookieParams
1733
- */
1734
- parameters: Array<ParameterNode>;
1735
- /**
1736
- * Request body metadata for the operation.
1737
- */
1738
- requestBody?: {
1739
- /**
1740
- * Human-readable request body description.
1741
- */
1742
- description?: string;
1743
- /**
1744
- * Request body schema.
1745
- * For OpenAPI, this is the schema from the first `content` entry.
1746
- */
1747
- schema?: SchemaNode;
1748
- /**
1749
- * Property keys to exclude from the generated request body type via `Omit<Type, Keys>`.
1750
- * Set when a referenced schema has `readOnly` fields that should be omitted in request types.
1751
- */
1752
- keysToOmit?: Array<string>;
1753
- /**
1754
- * Whether the request body is required (`requestBody.required: true` in the spec).
1755
- * When `false` or absent, the generated `data` parameter should be optional.
1756
- */
1757
- required?: boolean;
1758
- /**
1759
- * Media type of the request body (e.g. `'application/json'`, `'multipart/form-data'`).
1760
- * Extracted from the first `content` entry of the OpenAPI `requestBody`.
1761
- */
1762
- contentType?: string;
1763
- };
1764
- /**
1765
- * Operation responses.
1766
- */
1767
- responses: Array<ResponseNode>;
1768
- };
1769
- //#endregion
1770
- //#region src/nodes/output.d.ts
1771
- /**
1772
- * Output AST node that groups all generated file output for one API document.
1773
- *
1774
- * Produced by generators and consumed by the build pipeline to write files.
1775
- *
1776
- * @example
1777
- * ```ts
1778
- * const output: OutputNode = {
1779
- * kind: 'Output',
1780
- * files: [],
1781
- * }
1782
- * ```
1783
- */
1784
- type OutputNode = BaseNode & {
1785
- /**
1786
- * Node kind.
1787
- */
1788
- kind: 'Output';
1789
- /**
1790
- * Generated file nodes.
1791
- */
1792
- files: Array<FileNode>;
1793
- };
1794
- //#endregion
1795
- //#region src/nodes/root.d.ts
1796
- /**
1797
- * Basic metadata for an API document.
1798
- * Adapters fill fields that exist in their source format.
1799
- *
1800
- * @example
1801
- * ```ts
1802
- * const meta: InputMeta = { title: 'Pet API', version: '1.0.0' }
1803
- * ```
1804
- */
1805
- type InputMeta = {
1806
- /**
1807
- * API title (from `info.title` in OAS/AsyncAPI).
1808
- */
1809
- title?: string;
1810
- /**
1811
- * API description (from `info.description` in OAS/AsyncAPI).
1812
- */
1813
- description?: string;
1814
- /**
1815
- * API version string (from `info.version` in OAS/AsyncAPI).
1816
- */
1817
- version?: string;
1818
- /**
1819
- * Resolved API base URL.
1820
- * For OpenAPI and AsyncAPI, this comes from the selected server URL.
1821
- */
1822
- baseURL?: string;
1823
- };
1824
- /**
1825
- * Input AST node that contains all schemas and operations for one API document.
1826
- * Produced by the adapter and consumed by all Kubb plugins.
1827
- *
1828
- * @example
1829
- * ```ts
1830
- * const input: InputNode = {
1831
- * kind: 'Input',
1832
- * schemas: [],
1833
- * operations: [],
1834
- * }
1835
- * ```
1836
- */
1837
- type InputNode = BaseNode & {
1838
- /**
1839
- * Node kind.
1840
- */
1841
- kind: 'Input';
1842
- /**
1843
- * All schema nodes in the document.
1844
- */
1845
- schemas: Array<SchemaNode>;
1846
- /**
1847
- * All operation nodes in the document.
1848
- */
1849
- operations: Array<OperationNode>;
1850
- /**
1851
- * Optional document metadata populated by the adapter.
1852
- */
1853
- meta?: InputMeta;
1854
- };
1855
- //#endregion
1856
- //#region src/nodes/index.d.ts
1857
- /**
1858
- * Union of all AST node types.
1859
- *
1860
- * This lets TypeScript narrow types in `switch (node.kind)` blocks.
1861
- *
1862
- * @example
1863
- * ```ts
1864
- * function getKind(node: Node): string {
1865
- * switch (node.kind) {
1866
- * case 'Input':
1867
- * return 'input'
1868
- * case 'Output':
1869
- * return 'output'
1870
- * default:
1871
- * return 'other'
1872
- * }
1873
- * }
1874
- * ```
1875
- */
1876
- type Node = InputNode | OutputNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode | FunctionParamNode | FileNode | ImportNode | ExportNode | SourceNode | ConstNode | TypeNode | ParamsTypeNode | FunctionNode | ArrowFunctionNode;
1877
- //#endregion
1878
- //#region src/infer.d.ts
1879
- /**
1880
- * Shared parser options used by OAS-to-AST inference and parser flows.
1881
- */
1882
- type ParserOptions = {
1883
- /**
1884
- * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
1885
- */
1886
- dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date';
1887
- /**
1888
- * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
1889
- */
1890
- integerType?: 'number' | 'bigint';
1891
- /**
1892
- * AST type used when no schema type can be inferred.
1893
- */
1894
- unknownType: 'any' | 'unknown' | 'void';
1895
- /**
1896
- * AST type used for completely empty schemas (`{}`).
1897
- */
1898
- emptySchemaType: 'any' | 'unknown' | 'void';
1899
- /**
1900
- * Suffix appended to derived enum names when building property schema names.
1901
- */
1902
- enumSuffix: 'enum' | (string & {});
1903
- };
1904
- /**
1905
- * Maps each `dateType` option value to the AST node produced by `format: 'date-time'`.
1906
- */
1907
- type DateTimeNodeByDateType = {
1908
- date: DateSchemaNode;
1909
- string: DatetimeSchemaNode;
1910
- stringOffset: DatetimeSchemaNode;
1911
- stringLocal: DatetimeSchemaNode;
1912
- false: StringSchemaNode;
1913
- };
1914
- /**
1915
- * Resolves the AST node produced by `format: 'date-time'` based on the `dateType` option.
1916
- */
1917
- type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTimeNodeByDateType[TDateType extends keyof DateTimeNodeByDateType ? TDateType : 'string'];
1918
- /**
1919
- * Ordered list of `[schema-shape, SchemaNode]` pairs.
1920
- * `InferSchemaNode` walks this tuple in order and returns the first matching node type.
1921
- */
1922
- type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [[{
1923
- $ref: string;
1924
- }, RefSchemaNode], [{
1925
- allOf: ReadonlyArray<unknown>;
1926
- properties: object;
1927
- }, IntersectionSchemaNode], [{
1928
- allOf: readonly [unknown, unknown, ...unknown[]];
1929
- }, IntersectionSchemaNode], [{
1930
- allOf: ReadonlyArray<unknown>;
1931
- }, SchemaNode], [{
1932
- oneOf: ReadonlyArray<unknown>;
1933
- }, UnionSchemaNode], [{
1934
- anyOf: ReadonlyArray<unknown>;
1935
- }, UnionSchemaNode], [{
1936
- const: null;
1937
- }, ScalarSchemaNode], [{
1938
- const: string | number | boolean;
1939
- }, EnumSchemaNode], [{
1940
- type: ReadonlyArray<string>;
1941
- }, UnionSchemaNode], [{
1942
- type: 'array';
1943
- enum: ReadonlyArray<unknown>;
1944
- }, ArraySchemaNode], [{
1945
- enum: ReadonlyArray<unknown>;
1946
- }, EnumSchemaNode], [{
1947
- type: 'enum';
1948
- }, EnumSchemaNode], [{
1949
- type: 'union';
1950
- }, UnionSchemaNode], [{
1951
- type: 'intersection';
1952
- }, IntersectionSchemaNode], [{
1953
- type: 'tuple';
1954
- }, ArraySchemaNode], [{
1955
- type: 'ref';
1956
- }, RefSchemaNode], [{
1957
- type: 'datetime';
1958
- }, DatetimeSchemaNode], [{
1959
- type: 'date';
1960
- }, DateSchemaNode], [{
1961
- type: 'time';
1962
- }, TimeSchemaNode], [{
1963
- type: 'url';
1964
- }, UrlSchemaNode], [{
1965
- type: 'object';
1966
- }, ObjectSchemaNode], [{
1967
- additionalProperties: boolean | {};
1968
- }, ObjectSchemaNode], [{
1969
- type: 'array';
1970
- }, ArraySchemaNode], [{
1971
- items: object;
1972
- }, ArraySchemaNode], [{
1973
- prefixItems: ReadonlyArray<unknown>;
1974
- }, ArraySchemaNode], [{
1975
- type: string;
1976
- format: 'date-time';
1977
- }, ResolveDateTimeNode<TDateType>], [{
1978
- type: string;
1979
- format: 'date';
1980
- }, DateSchemaNode], [{
1981
- type: string;
1982
- format: 'time';
1983
- }, TimeSchemaNode], [{
1984
- format: 'date-time';
1985
- }, ResolveDateTimeNode<TDateType>], [{
1986
- format: 'date';
1987
- }, DateSchemaNode], [{
1988
- format: 'time';
1989
- }, TimeSchemaNode], [{
1990
- type: 'string';
1991
- }, StringSchemaNode], [{
1992
- type: 'number';
1993
- }, NumberSchemaNode], [{
1994
- type: 'integer';
1995
- }, NumberSchemaNode], [{
1996
- type: 'bigint';
1997
- }, NumberSchemaNode], [{
1998
- type: string;
1999
- }, ScalarSchemaNode], [{
2000
- minLength: number;
2001
- }, StringSchemaNode], [{
2002
- maxLength: number;
2003
- }, StringSchemaNode], [{
2004
- pattern: string;
2005
- }, StringSchemaNode], [{
2006
- minimum: number;
2007
- }, NumberSchemaNode], [{
2008
- maximum: number;
2009
- }, NumberSchemaNode]];
2010
- /**
2011
- * Infers the matching AST `SchemaNode` type from an input schema shape.
2012
- */
2013
- type InferSchemaNode<TSchema extends object, TDateType extends ParserOptions['dateType'] = 'string', TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>> = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>] ? TSchema extends TEntry[0] ? TEntry[1] : InferSchemaNode<TSchema, TDateType, TRest> : SchemaNode;
2014
- /**
2015
- * Backward-compatible alias for `InferSchemaNode`.
2016
- */
2017
- type InferSchema<TSchema extends object, TDateType extends ParserOptions['dateType'] = 'string', TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>> = InferSchemaNode<TSchema, TDateType, TEntries>;
2018
- //#endregion
2019
- //#region src/factory.d.ts
2020
- /**
2021
- * Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
2022
- *
2023
- * - `optional` is set for non-required, non-nullable schemas.
2024
- * - `nullish` is set for non-required, nullable schemas.
2025
- */
2026
- declare function syncOptionality(schema: SchemaNode, required: boolean): SchemaNode;
2027
- /**
2028
- * Distributive `Omit` that preserves each member of a union.
2029
- *
2030
- * @example
2031
- * ```ts
2032
- * type A = { kind: 'a'; keep: string; drop: number }
2033
- * type B = { kind: 'b'; keep: boolean; drop: number }
2034
- * type Result = DistributiveOmit<A | B, 'drop'>
2035
- * // -> { kind: 'a'; keep: string } | { kind: 'b'; keep: boolean }
2036
- * ```
2037
- */
2038
- type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
2039
- type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties' | 'primitive'> & {
2040
- properties?: Array<PropertyNode>;
2041
- primitive?: 'object';
2042
- };
2043
- type CreateSchemaInput = CreateSchemaObjectInput | DistributiveOmit<Exclude<SchemaNode, ObjectSchemaNode>, 'kind'>;
2044
- type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & {
2045
- kind: 'Schema';
2046
- };
2047
- /**
2048
- * Creates an `InputNode` with stable defaults for `schemas` and `operations`.
2049
- *
2050
- * @example
2051
- * ```ts
2052
- * const input = createInput()
2053
- * // { kind: 'Input', schemas: [], operations: [] }
2054
- * ```
2055
- *
2056
- * @example
2057
- * ```ts
2058
- * const input = createInput({ schemas: [petSchema] })
2059
- * // keeps default operations: []
2060
- * ```
2061
- */
2062
- declare function createInput(overrides?: Partial<Omit<InputNode, 'kind'>>): InputNode;
2063
- /**
2064
- * Creates an `OutputNode` with a stable default for `files`.
2065
- *
2066
- * @example
2067
- * ```ts
2068
- * const output = createOutput()
2069
- * // { kind: 'Output', files: [] }
2070
- * ```
2071
- *
2072
- * @example
2073
- * ```ts
2074
- * const output = createOutput({ files: [petFile] })
2075
- * ```
2076
- */
2077
- declare function createOutput(overrides?: Partial<Omit<OutputNode, 'kind'>>): OutputNode;
2078
- /**
2079
- * Creates an `OperationNode` with default empty arrays for `tags`, `parameters`, and `responses`.
2080
- *
2081
- * @example
2082
- * ```ts
2083
- * const operation = createOperation({
2084
- * operationId: 'getPetById',
2085
- * method: 'GET',
2086
- * path: '/pet/{petId}',
2087
- * })
2088
- * // tags, parameters, and responses are []
2089
- * ```
2090
- *
2091
- * @example
2092
- * ```ts
2093
- * const operation = createOperation({
2094
- * operationId: 'findPets',
2095
- * method: 'GET',
2096
- * path: '/pet/findByStatus',
2097
- * tags: ['pet'],
2098
- * })
2099
- * ```
2100
- */
2101
- declare function createOperation(props: Pick<OperationNode, 'operationId' | 'method' | 'path'> & Partial<Omit<OperationNode, 'kind' | 'operationId' | 'method' | 'path'>>): OperationNode;
2102
- /**
2103
- * Creates a `SchemaNode`, narrowed to the variant of `props.type`.
2104
- * For object schemas, `properties` defaults to an empty array.
2105
- * `primitive` is automatically inferred from `type` when not explicitly provided.
2106
- *
2107
- * @example
2108
- * ```ts
2109
- * const scalar = createSchema({ type: 'string' })
2110
- * // { kind: 'Schema', type: 'string', primitive: 'string' }
2111
- * ```
2112
- *
2113
- * @example
2114
- * ```ts
2115
- * const uuid = createSchema({ type: 'uuid' })
2116
- * // { kind: 'Schema', type: 'uuid', primitive: 'string' }
2117
- * ```
2118
- *
2119
- * @example
2120
- * ```ts
2121
- * const object = createSchema({ type: 'object' })
2122
- * // { kind: 'Schema', type: 'object', primitive: 'object', properties: [] }
2123
- * ```
2124
- *
2125
- * @example
2126
- * ```ts
2127
- * const enumSchema = createSchema({
2128
- * type: 'enum',
2129
- * primitive: 'string',
2130
- * enumValues: ['available', 'pending'],
2131
- * })
2132
- * ```
2133
- */
2134
- declare function createSchema<T extends CreateSchemaInput>(props: T): CreateSchemaOutput<T>;
2135
- declare function createSchema(props: CreateSchemaInput): SchemaNode;
2136
- type UserPropertyNode = Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>;
2137
- /**
2138
- * Creates a `PropertyNode`.
2139
- *
2140
- * `required` defaults to `false`.
2141
- * `schema.optional` and `schema.nullish` are derived from `required` and `schema.nullable`.
2142
- *
2143
- * @example
2144
- * ```ts
2145
- * const property = createProperty({
2146
- * name: 'status',
2147
- * schema: createSchema({ type: 'string' }),
2148
- * })
2149
- * // required=false, schema.optional=true
2150
- * ```
2151
- *
2152
- * @example
2153
- * ```ts
2154
- * const property = createProperty({
2155
- * name: 'status',
2156
- * required: true,
2157
- * schema: createSchema({ type: 'string', nullable: true }),
2158
- * })
2159
- * // required=true, no optional/nullish
2160
- * ```
2161
- */
2162
- declare function createProperty(props: UserPropertyNode): PropertyNode;
2163
- /**
2164
- * Creates a `ParameterNode`.
2165
- *
2166
- * `required` defaults to `false`.
2167
- * Nested schema flags are set from `required` and `schema.nullable`.
2168
- *
2169
- * @example
2170
- * ```ts
2171
- * const param = createParameter({
2172
- * name: 'petId',
2173
- * in: 'path',
2174
- * required: true,
2175
- * schema: createSchema({ type: 'string' }),
2176
- * })
2177
- * ```
2178
- *
2179
- * @example
2180
- * ```ts
2181
- * const param = createParameter({
2182
- * name: 'status',
2183
- * in: 'query',
2184
- * schema: createSchema({ type: 'string', nullable: true }),
2185
- * })
2186
- * // required=false, schema.nullish=true
2187
- * ```
2188
- */
2189
- declare function createParameter(props: Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>): ParameterNode;
2190
- /**
2191
- * Creates a `ResponseNode`.
2192
- *
2193
- * @example
2194
- * ```ts
2195
- * const response = createResponse({
2196
- * statusCode: '200',
2197
- * description: 'Success',
2198
- * schema: createSchema({ type: 'object', properties: [] }),
2199
- * })
2200
- * ```
2201
- */
2202
- declare function createResponse(props: Pick<ResponseNode, 'statusCode' | 'schema'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'schema'>>): ResponseNode;
2203
- /**
2204
- * Creates a `FunctionParameterNode`.
2205
- *
2206
- * `optional` defaults to `false`.
2207
- *
2208
- * @example Required typed param
2209
- * ```ts
2210
- * createFunctionParameter({ name: 'petId', type: createParamsType({ variant: 'reference', name: 'string' }) })
2211
- * // → petId: string
2212
- * ```
2213
- *
2214
- * @example Optional param
2215
- * ```ts
2216
- * createFunctionParameter({ name: 'params', type: createParamsType({ variant: 'reference', name: 'QueryParams' }), optional: true })
2217
- * // → params?: QueryParams
2218
- * ```
2219
- *
2220
- * @example Param with default (implicitly optional; cannot combine with `optional: true`)
2221
- * ```ts
2222
- * createFunctionParameter({ name: 'config', type: createParamsType({ variant: 'reference', name: 'RequestConfig' }), default: '{}' })
2223
- * // → config: RequestConfig = {}
2224
- * ```
2225
- */
2226
- declare function createFunctionParameter(props: {
2227
- name: string;
2228
- type?: ParamsTypeNode;
2229
- rest?: boolean;
2230
- } & ({
2231
- optional: true;
2232
- default?: never;
2233
- } | {
2234
- optional?: false;
2235
- default?: string;
2236
- })): FunctionParameterNode;
2237
- /**
2238
- * Creates a {@link TypeNode} representing a language-agnostic structured type expression.
2239
- *
2240
- * Use `variant: 'struct'` for inline anonymous types and `variant: 'member'` for a single
2241
- * named field accessed from a group type. Each language's printer renders the variant
2242
- * into its own syntax (TypeScript, Python, C#, Kotlin, …).
2243
- *
2244
- * @example Reference type (TypeScript: `QueryParams`)
2245
- * ```ts
2246
- * createParamsType({ variant: 'reference', name: 'QueryParams' })
2247
- * ```
2248
- *
2249
- * @example Struct type (TypeScript: `{ petId: string }`)
2250
- * ```ts
2251
- * createParamsType({ variant: 'struct', properties: [{ name: 'petId', optional: false, type: createParamsType({ variant: 'reference', name: 'string' }) }] })
2252
- * ```
2253
- *
2254
- * @example Member type (TypeScript: `DeletePetPathParams['petId']`)
2255
- * ```ts
2256
- * createParamsType({ variant: 'member', base: 'DeletePetPathParams', key: 'petId' })
2257
- * ```
2258
- */
2259
- declare function createParamsType(props: {
2260
- variant: 'reference';
2261
- name: string;
2262
- } | {
2263
- variant: 'struct';
2264
- properties: Array<{
2265
- name: string;
2266
- optional: boolean;
2267
- type: ParamsTypeNode;
2268
- }>;
2269
- } | {
2270
- variant: 'member';
2271
- base: string;
2272
- key: string;
2273
- }): ParamsTypeNode;
2274
- /**
2275
- * Creates a `ParameterGroupNode` representing a group of related parameters treated as a unit.
2276
- *
2277
- * @example Grouped param (TypeScript declaration)
2278
- * ```ts
2279
- * createParameterGroup({
2280
- * properties: [
2281
- * createFunctionParameter({ name: 'id', type: createParamsType({ variant: 'reference', name: 'string' }), optional: false }),
2282
- * createFunctionParameter({ name: 'name', type: createParamsType({ variant: 'reference', name: 'string' }), optional: true }),
2283
- * ],
2284
- * default: '{}',
2285
- * })
2286
- * // declaration → { id, name? }: { id: string; name?: string } = {}
2287
- * // call → { id, name }
2288
- * ```
2289
- *
2290
- * @example Inline (spread) — children emitted as individual top-level parameters
2291
- * ```ts
2292
- * createParameterGroup({
2293
- * properties: [createFunctionParameter({ name: 'petId', type: createParamsType({ variant: 'reference', name: 'string' }), optional: false })],
2294
- * inline: true,
2295
- * })
2296
- * // declaration → petId: string
2297
- * // call → petId
2298
- * ```
2299
- */
2300
- declare function createParameterGroup(props: Pick<ParameterGroupNode, 'properties'> & Partial<Omit<ParameterGroupNode, 'kind' | 'properties'>>): ParameterGroupNode;
2301
- /**
2302
- * Creates a `FunctionParametersNode` from an ordered list of parameters.
2303
- *
2304
- * @example
2305
- * ```ts
2306
- * createFunctionParameters({
2307
- * params: [
2308
- * createFunctionParameter({ name: 'petId', type: createParamsType({ variant: 'reference', name: 'string' }), optional: false }),
2309
- * createFunctionParameter({ name: 'config', type: createParamsType({ variant: 'reference', name: 'RequestConfig' }), optional: false, default: '{}' }),
2310
- * ],
2311
- * })
2312
- * ```
2313
- *
2314
- * @example
2315
- * ```ts
2316
- * const empty = createFunctionParameters()
2317
- * // { kind: 'FunctionParameters', params: [] }
2318
- * ```
2319
- */
2320
- declare function createFunctionParameters(props?: Partial<Omit<FunctionParametersNode, 'kind'>>): FunctionParametersNode;
2321
- /**
2322
- * Creates an `ImportNode` representing a language-agnostic import/dependency declaration.
2323
- *
2324
- * @example Named import
2325
- * ```ts
2326
- * createImport({ name: ['useState'], path: 'react' })
2327
- * // import { useState } from 'react'
2328
- * ```
2329
- *
2330
- * @example Type-only import
2331
- * ```ts
2332
- * createImport({ name: ['FC'], path: 'react', isTypeOnly: true })
2333
- * // import type { FC } from 'react'
2334
- * ```
2335
- */
2336
- declare function createImport(props: Omit<ImportNode, 'kind'>): ImportNode;
2337
- /**
2338
- * Creates an `ExportNode` representing a language-agnostic export/public API declaration.
2339
- *
2340
- * @example Named export
2341
- * ```ts
2342
- * createExport({ name: ['Pet'], path: './Pet' })
2343
- * // export { Pet } from './Pet'
2344
- * ```
2345
- *
2346
- * @example Wildcard export
2347
- * ```ts
2348
- * createExport({ path: './utils' })
2349
- * // export * from './utils'
2350
- * ```
2351
- */
2352
- declare function createExport(props: Omit<ExportNode, 'kind'>): ExportNode;
2353
- /**
2354
- * Creates a `SourceNode` representing a fragment of source code within a file.
2355
- *
2356
- * @example
2357
- * ```ts
2358
- * createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')], isExportable: true })
2359
- * ```
2360
- */
2361
- declare function createSource(props: Omit<SourceNode, 'kind'>): SourceNode;
2362
- type UserFileNode<TMeta extends object = object> = Omit<FileNode<TMeta>, 'kind' | 'id' | 'name' | 'extname' | 'imports' | 'exports' | 'sources'> & Pick<Partial<FileNode<TMeta>>, 'imports' | 'exports' | 'sources'>;
2363
- /**
2364
- * Creates a fully resolved `FileNode` from a file input descriptor.
2365
- *
2366
- * Computes:
2367
- * - `id` — SHA256 hash of the file path
2368
- * - `name` — `baseName` without extension
2369
- * - `extname` — extension extracted from `baseName`
2370
- *
2371
- * Deduplicates:
2372
- * - `sources` via `combineSources`
2373
- * - `exports` via `combineExports`
2374
- * - `imports` via `combineImports` (also filters unused imports)
2375
- *
2376
- * @throws {Error} when `baseName` has no extension.
2377
- *
2378
- * @example
2379
- * ```ts
2380
- * const file = createFile({
2381
- * baseName: 'petStore.ts',
2382
- * path: 'src/models/petStore.ts',
2383
- * sources: [createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')] })],
2384
- * imports: [createImport({ name: ['z'], path: 'zod' })],
2385
- * exports: [createExport({ name: ['Pet'], path: './petStore' })],
2386
- * })
2387
- * // file.id = SHA256 hash of 'src/models/petStore.ts'
2388
- * // file.name = 'petStore'
2389
- * // file.extname = '.ts'
2390
- * ```
2391
- */
2392
- declare function createFile<TMeta extends object = object>(input: UserFileNode<TMeta>): FileNode<TMeta>;
2393
- /**
2394
- * Creates a `ConstNode` representing a TypeScript `const` declaration.
2395
- *
2396
- * Mirrors the `Const` component from `@kubb/renderer-jsx`.
2397
- * The component's `children` are represented as `nodes`.
2398
- *
2399
- * @example Simple constant
2400
- * ```ts
2401
- * createConst({ name: 'pet' })
2402
- * // const pet = ...
2403
- * ```
2404
- *
2405
- * @example Exported constant with type and `as const`
2406
- * ```ts
2407
- * createConst({ name: 'pets', export: true, type: 'Pet[]', asConst: true })
2408
- * // export const pets: Pet[] = ... as const
2409
- * ```
2410
- *
2411
- * @example With JSDoc and child nodes
2412
- * ```ts
2413
- * createConst({
2414
- * name: 'config',
2415
- * export: true,
2416
- * JSDoc: { comments: ['@description App configuration'] },
2417
- * nodes: [],
2418
- * })
2419
- * ```
2420
- */
2421
- declare function createConst(props: Omit<ConstNode, 'kind'>): ConstNode;
2422
- /**
2423
- * Creates a `TypeNode` representing a TypeScript `type` alias declaration.
2424
- *
2425
- * Mirrors the `Type` component from `@kubb/renderer-jsx`.
2426
- * The component's `children` are represented as `nodes`.
2427
- *
2428
- * @example Simple type alias
2429
- * ```ts
2430
- * createType({ name: 'Pet' })
2431
- * // type Pet = ...
2432
- * ```
2433
- *
2434
- * @example Exported type with JSDoc
2435
- * ```ts
2436
- * createType({
2437
- * name: 'PetStatus',
2438
- * export: true,
2439
- * JSDoc: { comments: ['@description Status of a pet'] },
2440
- * })
2441
- * // export type PetStatus = ...
2442
- * ```
2443
- */
2444
- declare function createType(props: Omit<TypeNode, 'kind'>): TypeNode;
2445
- /**
2446
- * Creates a `FunctionNode` representing a TypeScript `function` declaration.
2447
- *
2448
- * Mirrors the `Function` component from `@kubb/renderer-jsx`.
2449
- * The component's `children` are represented as `nodes`.
2450
- *
2451
- * @example Simple function
2452
- * ```ts
2453
- * createFunction({ name: 'getPet' })
2454
- * // function getPet() { ... }
2455
- * ```
2456
- *
2457
- * @example Exported async function with return type
2458
- * ```ts
2459
- * createFunction({ name: 'fetchPet', export: true, async: true, returnType: 'Pet' })
2460
- * // export async function fetchPet(): Promise<Pet> { ... }
2461
- * ```
2462
- *
2463
- * @example Function with generics and params
2464
- * ```ts
2465
- * createFunction({
2466
- * name: 'identity',
2467
- * export: true,
2468
- * generics: ['T'],
2469
- * params: 'value: T',
2470
- * returnType: 'T',
2471
- * })
2472
- * // export function identity<T>(value: T): T { ... }
2473
- * ```
2474
- */
2475
- declare function createFunction(props: Omit<FunctionNode, 'kind'>): FunctionNode;
2476
- /**
2477
- * Creates an `ArrowFunctionNode` representing a TypeScript arrow function.
2478
- *
2479
- * Mirrors the `Function.Arrow` component from `@kubb/renderer-jsx`.
2480
- * The component's `children` are represented as `nodes`.
2481
- *
2482
- * @example Simple arrow function
2483
- * ```ts
2484
- * createArrowFunction({ name: 'getPet' })
2485
- * // const getPet = () => { ... }
2486
- * ```
2487
- *
2488
- * @example Single-line exported arrow function
2489
- * ```ts
2490
- * createArrowFunction({ name: 'double', export: true, params: 'n: number', singleLine: true })
2491
- * // export const double = (n: number) => ...
2492
- * ```
2493
- *
2494
- * @example Async arrow function with generics
2495
- * ```ts
2496
- * createArrowFunction({
2497
- * name: 'fetchPet',
2498
- * export: true,
2499
- * async: true,
2500
- * generics: ['T'],
2501
- * params: 'id: string',
2502
- * returnType: 'T',
2503
- * })
2504
- * // export const fetchPet = async <T>(id: string): Promise<T> => { ... }
2505
- * ```
2506
- */
2507
- declare function createArrowFunction(props: Omit<ArrowFunctionNode, 'kind'>): ArrowFunctionNode;
2508
- /**
2509
- * Creates a {@link TextNode} representing a raw string fragment in the source output.
2510
- *
2511
- * Use this instead of bare strings when building `nodes` arrays so that every
2512
- * entry in the array is a typed {@link CodeNode}.
2513
- *
2514
- * @example
2515
- * ```ts
2516
- * createText('return fetch(id)')
2517
- * // { kind: 'Text', value: 'return fetch(id)' }
2518
- * ```
2519
- */
2520
- declare function createText(value: string): TextNode;
2521
- /**
2522
- * Creates a {@link BreakNode} representing a line break in the source output.
2523
- *
2524
- * Corresponds to `<br/>` in JSX components. Prints as an empty string which,
2525
- * when joined with `\n` by `printNodes`, produces a blank line.
2526
- *
2527
- * @example
2528
- * ```ts
2529
- * createBreak()
2530
- * // { kind: 'Break' }
2531
- * ```
2532
- */
2533
- declare function createBreak(): BreakNode;
2534
- /**
2535
- * Creates a {@link JsxNode} representing a raw JSX fragment in the source output.
2536
- *
2537
- * Use this to embed JSX markup (including fragments `<>…</>`) directly in generated code.
2538
- *
2539
- * @example
2540
- * ```ts
2541
- * createJsx('<>\n <a href={href}>Open</a>\n</>')
2542
- * // { kind: 'Jsx', value: '<>\n <a href={href}>Open</a>\n</>' }
2543
- * ```
2544
- */
2545
- declare function createJsx(value: string): JsxNode;
2546
- //#endregion
2547
- //#region src/printer.d.ts
2548
- /**
2549
- * Runtime context passed as `this` to printer handlers.
2550
- *
2551
- * `this.transform` dispatches to node-level handlers from `nodes`.
2552
- *
2553
- * @example
2554
- * ```ts
2555
- * const context: PrinterHandlerContext<string, {}> = {
2556
- * options: {},
2557
- * transform: () => 'value',
2558
- * }
2559
- * ```
2560
- */
2561
- type PrinterHandlerContext<TOutput, TOptions extends object> = {
2562
- /**
2563
- * Recursively transform a nested `SchemaNode` to `TOutput` using the node-level handlers.
2564
- * Use `this.transform` inside `nodes` handlers and inside the `print` override.
2565
- */
2566
- transform: (node: SchemaNode) => TOutput | null | undefined;
2567
- /**
2568
- * Options for this printer instance.
2569
- */
2570
- options: TOptions;
2571
- };
2572
- /**
2573
- * Handler for one schema node type.
2574
- *
2575
- * Use a regular function (not an arrow function) if you need `this`.
2576
- *
2577
- * @example
2578
- * ```ts
2579
- * const handler: PrinterHandler<string, {}, 'string'> = function () {
2580
- * return 'string'
2581
- * }
2582
- * ```
2583
- */
2584
- type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (this: PrinterHandlerContext<TOutput, TOptions>, node: SchemaNodeByType[T]) => TOutput | null | undefined;
2585
- /**
2586
- * Partial map of per-node-type handler overrides for a printer.
2587
- *
2588
- * Each key is a `SchemaType` string (e.g. `'date'`, `'string'`).
2589
- * Supply only the handlers you want to replace; the printer's built-in
2590
- * defaults fill in the rest.
2591
- *
2592
- * @example
2593
- * ```ts
2594
- * pluginZod({
2595
- * printer: {
2596
- * nodes: {
2597
- * date(): string {
2598
- * return 'z.string().date()'
2599
- * },
2600
- * } satisfies PrinterPartial<string, PrinterZodOptions>,
2601
- * },
2602
- * })
2603
- * ```
2604
- */
2605
- type PrinterPartial<TOutput, TOptions extends object> = Partial<{ [K in SchemaType]: PrinterHandler<TOutput, TOptions, K> }>;
2606
- /**
2607
- * Generic shape used by `definePrinter`.
2608
- *
2609
- * - `TName` — unique string identifier (e.g. `'zod'`, `'ts'`)
2610
- * - `TOptions` — options passed to and stored on the printer instance
2611
- * - `TOutput` — the type emitted by node handlers
2612
- * - `TPrintOutput` — type returned by public `print` (defaults to `TOutput`)
2613
- *
2614
- * @example
2615
- * ```ts
2616
- * type MyPrinter = PrinterFactoryOptions<'my', { strict: boolean }, string>
2617
- * ```
2618
- */
2619
- type PrinterFactoryOptions<TName extends string = string, TOptions extends object = object, TOutput = unknown, TPrintOutput = TOutput> = {
2620
- name: TName;
2621
- options: TOptions;
2622
- output: TOutput;
2623
- printOutput: TPrintOutput;
2624
- };
2625
- /**
2626
- * Printer instance returned by a printer factory.
2627
- *
2628
- * @example
2629
- * ```ts
2630
- * const printer = definePrinter((options: {}) => ({ name: 'x', options, nodes: {} }))({})
2631
- * ```
2632
- */
2633
- type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
2634
- /**
2635
- * Unique identifier supplied at creation time.
2636
- */
2637
- name: T['name'];
2638
- /**
2639
- * Options for this printer instance.
2640
- */
2641
- options: T['options'];
2642
- /**
2643
- * Node-level dispatcher — converts a `SchemaNode` directly to `TOutput` using the `nodes` handlers.
2644
- * Always dispatches through the `nodes` map; never calls the `print` override.
2645
- * Use this when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
2646
- */
2647
- transform: (node: SchemaNode) => T['output'] | null | undefined;
2648
- /**
2649
- * Public printer. If the builder provides a root-level `print`, this calls that
2650
- * higher-level function (which may produce full declarations).
2651
- * Otherwise, falls back to the node-level dispatcher.
2652
- */
2653
- print: (node: SchemaNode) => T['printOutput'] | null | undefined;
2654
- };
2655
- /**
2656
- * Builder function passed to `definePrinter`.
2657
- *
2658
- * It receives resolved options and returns:
2659
- * - `name`
2660
- * - `options`
2661
- * - `nodes` handlers
2662
- * - optional top-level `print` override
2663
- *
2664
- * @example
2665
- * ```ts
2666
- * const build = (options: {}) => ({ name: 'x' as const, options, nodes: {} })
2667
- * ```
2668
- */
2669
- type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) => {
2670
- name: T['name'];
2671
- /**
2672
- * Options to store on the printer.
2673
- */
2674
- options: T['options'];
2675
- nodes: Partial<{ [K in SchemaType]: PrinterHandler<T['output'], T['options'], K> }>;
2676
- /**
2677
- * Optional root-level print override. When provided, becomes the public `printer.print`.
2678
- * Use `this.transform(node)` inside this function to dispatch to the node-level handlers (`nodes`),
2679
- * not the override itself — so recursion is safe.
2680
- */
2681
- print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null;
2682
- };
2683
- /**
2684
- * Creates a schema printer factory.
2685
- *
2686
- * This function wraps a builder and makes options optional at call sites.
2687
- *
2688
- * The builder receives resolved options and returns:
2689
- * - `name` — a unique identifier for the printer
2690
- * - `options` — options stored on the returned printer instance
2691
- * - `nodes` — a map of `SchemaType` → handler functions that convert a `SchemaNode` to `TOutput`
2692
- * - `print` _(optional)_ — top-level override exposed as `printer.print`
2693
- * - Inside this function, use `this.transform(node)` to dispatch to the `nodes` map
2694
- * - This keeps recursion safe and avoids self-calls
2695
- *
2696
- * When no `print` override is provided, `printer.print` falls back to `printer.transform` (the node-level dispatcher).
2697
- *
2698
- * @example Basic usage — Zod schema printer
2699
- * ```ts
2700
- * type PrinterZod = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
2701
- *
2702
- * export const zodPrinter = definePrinter<PrinterZod>((options) => ({
2703
- * name: 'zod',
2704
- * options: { strict: options.strict ?? true },
2705
- * nodes: {
2706
- * string: () => 'z.string()',
2707
- * object(node) {
2708
- * const props = node.properties.map(p => `${p.name}: ${this.transform(p.schema)}`).join(', ')
2709
- * return `z.object({ ${props} })`
2710
- * },
2711
- * },
2712
- * }))
2713
- * ```
2714
- */
2715
- declare function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOptions>(build: PrinterBuilder<T>): (options?: T['options']) => Printer<T>;
2716
- /**
2717
- * Generic printer-factory function used by `definePrinter` and `defineFunctionPrinter`.
2718
- **
2719
- * @example
2720
- * ```ts
2721
- * export const defineFunctionPrinter = createPrinterFactory<FunctionNode, FunctionNodeType, FunctionNodeByType>(
2722
- * (node) => kindToHandlerKey[node.kind],
2723
- * )
2724
- * ```
2725
- */
2726
- declare function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | undefined): <T extends PrinterFactoryOptions>(build: (options: T["options"]) => {
2727
- name: T["name"];
2728
- options: T["options"];
2729
- nodes: Partial<{ [K in TKey]: (this: {
2730
- transform: (node: TNode) => T["output"] | null | undefined;
2731
- options: T["options"];
2732
- }, node: TNodeByKey[K]) => T["output"] | null | undefined }>;
2733
- print?: (this: {
2734
- transform: (node: TNode) => T["output"] | null | undefined;
2735
- options: T["options"];
2736
- }, node: TNode) => T["printOutput"] | null | undefined;
2737
- }) => (options?: T["options"]) => {
2738
- name: T["name"];
2739
- options: T["options"];
2740
- transform: (node: TNode) => T["output"] | null | undefined;
2741
- print: (node: TNode) => T["printOutput"] | null | undefined;
2742
- };
2743
- //#endregion
2744
- //#region src/refs.d.ts
2745
- /**
2746
- * Lookup map from schema name to `SchemaNode`.
2747
- */
2748
- type RefMap = Map<string, SchemaNode>;
2749
- /**
2750
- * Returns the last path segment of a reference string.
2751
- *
2752
- * Example: `#/components/schemas/Pet` becomes `Pet`.
2753
- *
2754
- * @example
2755
- * ```ts
2756
- * extractRefName('#/components/schemas/Pet') // 'Pet'
2757
- * ```
2758
- */
2759
- declare function extractRefName(ref: string): string;
2760
- //#endregion
2761
- //#region src/visitor.d.ts
2762
- /**
2763
- * Ordered mapping of `[NodeType, ParentType]` pairs.
2764
- *
2765
- * `ParentOf` uses this map to find parent types.
2766
- */
2767
- type ParentNodeMap = [[InputNode, undefined], [OutputNode, undefined], [OperationNode, InputNode], [SchemaNode, InputNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode], [PropertyNode, SchemaNode], [ParameterNode, OperationNode], [ResponseNode, OperationNode]];
2768
- /**
2769
- * Resolves the parent node type for a given AST node type.
2770
- *
2771
- * This is used by visitor context so `ctx.parent` is correctly typed
2772
- * for each callback.
2773
- *
2774
- * @example
2775
- * ```ts
2776
- * type InputParent = ParentOf<InputNode>
2777
- * // undefined
2778
- * ```
2779
- *
2780
- * @example
2781
- * ```ts
2782
- * type PropertyParent = ParentOf<PropertyNode>
2783
- * // SchemaNode
2784
- * ```
2785
- *
2786
- * @example
2787
- * ```ts
2788
- * type SchemaParent = ParentOf<SchemaNode>
2789
- * // InputNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode
2790
- * ```
2791
- */
2792
- type ParentOf<T extends Node, TEntries extends ReadonlyArray<[Node, unknown]> = ParentNodeMap> = TEntries extends [infer TEntry extends [Node, unknown], ...infer TRest extends ReadonlyArray<[Node, unknown]>] ? T extends TEntry[0] ? TEntry[1] : ParentOf<T, TRest> : Node;
2793
- /**
2794
- * Traversal context passed as the second argument to every visitor callback.
2795
- * `parent` is typed from the current node type.
2796
- *
2797
- * @example
2798
- * ```ts
2799
- * const visitor: Visitor = {
2800
- * schema(node, { parent }) {
2801
- * // parent type is narrowed by node kind
2802
- * },
2803
- * }
2804
- * ```
2805
- */
2806
- type VisitorContext<T extends Node = Node> = {
2807
- /**
2808
- * Parent node of the currently visited node.
2809
- * For `InputNode`, this is `undefined`.
2810
- */
2811
- parent?: ParentOf<T>;
2812
- };
2813
- /**
2814
- * Synchronous visitor used by `transform`.
2815
- *
2816
- * @example
2817
- * ```ts
2818
- * const visitor: Visitor = {
2819
- * operation(node) {
2820
- * return { ...node, operationId: `x_${node.operationId}` }
2821
- * },
2822
- * }
2823
- * ```
2824
- */
2825
- type Visitor = {
2826
- input?(node: InputNode, context: VisitorContext<InputNode>): void | InputNode;
2827
- output?(node: OutputNode, context: VisitorContext<OutputNode>): void | OutputNode;
2828
- operation?(node: OperationNode, context: VisitorContext<OperationNode>): void | OperationNode;
2829
- schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): void | SchemaNode;
2830
- property?(node: PropertyNode, context: VisitorContext<PropertyNode>): void | PropertyNode;
2831
- parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): void | ParameterNode;
2832
- response?(node: ResponseNode, context: VisitorContext<ResponseNode>): void | ResponseNode;
2833
- };
2834
- /**
2835
- * Utility type for values that can be returned directly or asynchronously.
2836
- */
2837
- type MaybePromise<T> = T | Promise<T>;
2838
- /**
2839
- * Async visitor for `walk`. Synchronous `Visitor` objects are compatible.
2840
- *
2841
- * @example
2842
- * ```ts
2843
- * const visitor: AsyncVisitor = {
2844
- * async operation(node) {
2845
- * await Promise.resolve(node.operationId)
2846
- * },
2847
- * }
2848
- * ```
2849
- */
2850
- type AsyncVisitor = {
2851
- input?(node: InputNode, context: VisitorContext<InputNode>): MaybePromise<void | InputNode>;
2852
- output?(node: OutputNode, context: VisitorContext<OutputNode>): MaybePromise<void | OutputNode>;
2853
- operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<void | OperationNode>;
2854
- schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): MaybePromise<void | SchemaNode>;
2855
- property?(node: PropertyNode, context: VisitorContext<PropertyNode>): MaybePromise<void | PropertyNode>;
2856
- parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): MaybePromise<void | ParameterNode>;
2857
- response?(node: ResponseNode, context: VisitorContext<ResponseNode>): MaybePromise<void | ResponseNode>;
2858
- };
2859
- /**
2860
- * Visitor used by `collect`.
2861
- *
2862
- * @example
2863
- * ```ts
2864
- * const visitor: CollectVisitor<string> = {
2865
- * operation(node) {
2866
- * return node.operationId
2867
- * },
2868
- * }
2869
- * ```
2870
- */
2871
- type CollectVisitor<T> = {
2872
- input?(node: InputNode, context: VisitorContext<InputNode>): T | undefined;
2873
- output?(node: OutputNode, context: VisitorContext<OutputNode>): T | undefined;
2874
- operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | undefined;
2875
- schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | undefined;
2876
- property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | undefined;
2877
- parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | undefined;
2878
- response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | undefined;
2879
- };
2880
- /**
2881
- * Options for `transform`.
2882
- *
2883
- * @example
2884
- * ```ts
2885
- * const options: TransformOptions = { depth: 'deep', schema: (node) => node }
2886
- * ```
2887
- *
2888
- * @example
2889
- * ```ts
2890
- * // Only transform the current node, not nested children
2891
- * const options: TransformOptions = { depth: 'shallow', schema: (node) => node }
2892
- * ```
2893
- */
2894
- type TransformOptions = Visitor & {
2895
- /**
2896
- * Traversal depth (`'deep'` by default).
2897
- * @default 'deep'
2898
- */
2899
- depth?: VisitorDepth;
2900
- /**
2901
- * Internal parent override used during recursion.
2902
- */
2903
- parent?: Node;
2904
- };
2905
- /**
2906
- * Options for `walk`.
2907
- *
2908
- * @example
2909
- * ```ts
2910
- * const options: WalkOptions = { depth: 'deep', concurrency: 10, root: () => {} }
2911
- * ```
2912
- */
2913
- type WalkOptions = AsyncVisitor & {
2914
- /**
2915
- * Traversal depth (`'deep'` by default).
2916
- * @default 'deep'
2917
- */
2918
- depth?: VisitorDepth;
2919
- /**
2920
- * Maximum number of sibling nodes visited concurrently.
2921
- * @default 30
2922
- */
2923
- concurrency?: number;
2924
- };
2925
- /**
2926
- * Options for `collect`.
2927
- *
2928
- * @example
2929
- * ```ts
2930
- * const options: CollectOptions<string> = { depth: 'shallow', schema: () => undefined }
2931
- * ```
2932
- */
2933
- type CollectOptions<T> = CollectVisitor<T> & {
2934
- /**
2935
- * Traversal depth (`'deep'` by default).
2936
- * @default 'deep'
2937
- */
2938
- depth?: VisitorDepth;
2939
- /**
2940
- * Internal parent override used during recursion.
2941
- */
2942
- parent?: Node;
2943
- };
2944
- /**
2945
- * Depth-first traversal for side effects. Visitor return values are ignored.
2946
- * Sibling nodes at each level are visited concurrently up to `options.concurrency`
2947
- * (default: `WALK_CONCURRENCY`).
2948
- *
2949
- * @example
2950
- * ```ts
2951
- * await walk(root, {
2952
- * operation(node) {
2953
- * console.log(node.operationId)
2954
- * },
2955
- * })
2956
- * ```
2957
- *
2958
- * @example
2959
- * ```ts
2960
- * // Visit only the current node
2961
- * await walk(root, { depth: 'shallow', root: () => {} })
2962
- * ```
2963
- */
2964
- declare function walk(node: Node, options: WalkOptions): Promise<void>;
2965
- /**
2966
- * Runs a depth-first immutable transform.
2967
- *
2968
- * If a visitor returns a node, it replaces the current node.
2969
- * If it returns `undefined`, the current node stays the same.
2970
- *
2971
- * @example
2972
- * ```ts
2973
- * const next = transform(root, {
2974
- * operation(node) {
2975
- * return { ...node, operationId: `prefixed_${node.operationId}` }
2976
- * },
2977
- * })
2978
- * ```
2979
- *
2980
- * @example
2981
- * ```ts
2982
- * // Shallow mode: only transform the input node
2983
- * const next = transform(root, { depth: 'shallow', root: (node) => node })
2984
- * ```
2985
- */
2986
- declare function transform(node: InputNode, options: TransformOptions): InputNode;
2987
- declare function transform(node: OutputNode, options: TransformOptions): OutputNode;
2988
- declare function transform(node: OperationNode, options: TransformOptions): OperationNode;
2989
- declare function transform(node: SchemaNode, options: TransformOptions): SchemaNode;
2990
- declare function transform(node: PropertyNode, options: TransformOptions): PropertyNode;
2991
- declare function transform(node: ParameterNode, options: TransformOptions): ParameterNode;
2992
- declare function transform(node: ResponseNode, options: TransformOptions): ResponseNode;
2993
- declare function transform(node: Node, options: TransformOptions): Node;
2994
- /**
2995
- * Composes multiple visitors into one visitor, applied left to right.
2996
- *
2997
- * For each node kind, output from one visitor is input to the next.
2998
- * If a visitor returns `undefined`, the previous node value is kept.
2999
- *
3000
- * @example
3001
- * ```ts
3002
- * const visitor = composeTransformers(
3003
- * { operation: (node) => ({ ...node, operationId: `a_${node.operationId}` }) },
3004
- * { operation: (node) => ({ ...node, operationId: `b_${node.operationId}` }) },
3005
- * )
3006
- * ```
3007
- */
3008
- declare function composeTransformers(...visitors: Array<Visitor>): Visitor;
3009
- /**
3010
- * Runs a depth-first synchronous collection pass.
3011
- *
3012
- * Non-`undefined` values returned by visitor callbacks are appended to the result.
3013
- *
3014
- * @example
3015
- * ```ts
3016
- * const ids = collect(root, {
3017
- * operation(node) {
3018
- * return node.operationId
3019
- * },
3020
- * })
3021
- * ```
3022
- *
3023
- * @example
3024
- * ```ts
3025
- * // Collect from only the current node
3026
- * const values = collect(root, { depth: 'shallow', root: () => 'root' })
3027
- * ```
3028
- */
3029
- declare function collect<T>(node: Node, options: CollectOptions<T>): Array<T>;
3030
- //#endregion
3031
- export { ResponseNode as $, VisitorDepth as $t, createInput as A, FunctionNodeType as At, createSource as B, ArrowFunctionNode as Bt, createConst as C, SchemaType as Ct, createFunctionParameter as D, UnionSchemaNode as Dt, createFunction as E, TimeSchemaNode as Et, createParameterGroup as F, ParamsTypeNode as Ft, InferSchemaNode as G, JSDocNode as Gt, createType as H, CodeNode as Ht, createParamsType as I, ExportNode as It, InputMeta as J, TypeDeclarationNode as Jt, ParserOptions as K, JsxNode as Kt, createProperty as L, FileNode as Lt, createOperation as M, FunctionParameterNode as Mt, createOutput as N, FunctionParametersNode as Nt, createFunctionParameters as O, UrlSchemaNode as Ot, createParameter as P, ParameterGroupNode as Pt, OperationNode as Q, ScalarPrimitive as Qt, createResponse as R, ImportNode as Rt, createBreak as S, SchemaNodeByType as St, createFile as T, StringSchemaNode as Tt, syncOptionality as U, ConstNode as Ut, createText as V, BreakNode as Vt, InferSchema as W, FunctionNode as Wt, OutputNode as X, BaseNode as Xt, InputNode as Y, TypeNode as Yt, HttpMethod as Z, NodeKind as Zt, PrinterPartial as _, PrimitiveSchemaType as _t, TransformOptions as a, ArraySchemaNode as at, DistributiveOmit as b, ScalarSchemaType as bt, WalkOptions as c, DatetimeSchemaNode as ct, transform as d, FormatStringSchemaNode as dt, httpMethods as en, HttpStatusCode as et, walk as f, IntersectionSchemaNode as ft, PrinterFactoryOptions as g, ObjectSchemaNode as gt, Printer as h, NumberSchemaNode as ht, ParentOf as i, schemaTypes as in, ParameterNode as it, createJsx as j, FunctionParamNode as jt, createImport as k, PropertyNode as kt, collect as l, EnumSchemaNode as lt, extractRefName as m, Ipv6SchemaNode as mt, CollectOptions as n, mediaTypes as nn, StatusCode as nt, Visitor as o, ComplexSchemaType as ot, RefMap as p, Ipv4SchemaNode as pt, Node as q, TextNode as qt, CollectVisitor as r, nodeKinds as rn, ParameterLocation as rt, VisitorContext as s, DateSchemaNode as st, AsyncVisitor as t, isScalarPrimitive as tn, MediaType as tt, composeTransformers as u, EnumValueNode as ut, createPrinterFactory as v, RefSchemaNode as vt, createExport as w, SpecialSchemaType as wt, createArrowFunction as x, SchemaNode as xt, definePrinter as y, ScalarSchemaNode as yt, createSchema as z, SourceNode as zt };
3032
- //# sourceMappingURL=visitor-CJMIoAE3.d.ts.map