@kubb/ast 5.0.0-beta.3 → 5.0.0-beta.31
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.
- package/README.md +1 -1
- package/dist/index.cjs +694 -331
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +1433 -1007
- package/dist/index.js +682 -332
- package/dist/index.js.map +1 -1
- package/package.json +3 -4
- package/src/dedupe.ts +202 -0
- package/src/dialect.ts +64 -0
- package/src/dispatch.ts +53 -0
- package/src/factory.ts +127 -11
- package/src/guards.ts +18 -3
- package/src/index.ts +11 -3
- package/src/infer.ts +16 -5
- package/src/nodes/base.ts +2 -0
- package/src/nodes/code.ts +21 -21
- package/src/nodes/content.ts +37 -0
- package/src/nodes/file.ts +16 -14
- package/src/nodes/index.ts +7 -3
- package/src/nodes/operation.ts +98 -62
- package/src/nodes/response.ts +21 -14
- package/src/nodes/root.ts +72 -10
- package/src/nodes/schema.ts +9 -3
- package/src/printer.ts +34 -28
- package/src/refs.ts +4 -2
- package/src/resolvers.ts +4 -4
- package/src/signature.ts +135 -0
- package/src/transformers.ts +20 -15
- package/src/types.ts +8 -0
- package/src/utils.ts +109 -68
- package/src/visitor.ts +229 -275
package/package.json
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kubb/ast",
|
|
3
|
-
"version": "5.0.0-beta.
|
|
4
|
-
"description": "Spec-agnostic AST layer for Kubb. Defines
|
|
3
|
+
"version": "5.0.0-beta.31",
|
|
4
|
+
"description": "Spec-agnostic AST layer for Kubb. Defines the node tree, visitor pattern, factory functions, and type guards used across all code generation plugins.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ast",
|
|
7
7
|
"codegen",
|
|
8
8
|
"kubb",
|
|
9
|
-
"openapi",
|
|
10
9
|
"typescript"
|
|
11
10
|
],
|
|
12
11
|
"license": "MIT",
|
|
@@ -40,7 +39,7 @@
|
|
|
40
39
|
"registry": "https://registry.npmjs.org/"
|
|
41
40
|
},
|
|
42
41
|
"devDependencies": {
|
|
43
|
-
"@types/node": "^
|
|
42
|
+
"@types/node": "^22.19.19",
|
|
44
43
|
"@internals/utils": "0.0.0"
|
|
45
44
|
},
|
|
46
45
|
"engines": {
|
package/src/dedupe.ts
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
import { createSchema } from './factory.ts'
|
|
2
|
+
import type { Node, OperationNode, SchemaNode } from './nodes/index.ts'
|
|
3
|
+
import { signatureOf } from './signature.ts'
|
|
4
|
+
import { collectLazy, transform } from './visitor.ts'
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* A canonical destination for a deduplicated shape: the shared schema name and
|
|
8
|
+
* the synthetic `$ref` path that points at it.
|
|
9
|
+
*/
|
|
10
|
+
export type DedupeCanonical = {
|
|
11
|
+
/**
|
|
12
|
+
* Canonical schema name every duplicate occurrence refers to.
|
|
13
|
+
*/
|
|
14
|
+
name: string
|
|
15
|
+
/**
|
|
16
|
+
* `$ref` path stored on the generated `ref` nodes (for example `#/components/schemas/Status`).
|
|
17
|
+
*/
|
|
18
|
+
ref: string
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* The result of {@link buildDedupePlan}: a lookup from structural signature to its
|
|
23
|
+
* canonical target, plus the freshly hoisted definitions that must be added to
|
|
24
|
+
* the schema list.
|
|
25
|
+
*/
|
|
26
|
+
export type DedupePlan = {
|
|
27
|
+
/**
|
|
28
|
+
* Maps a structural signature to the canonical schema that represents it.
|
|
29
|
+
*/
|
|
30
|
+
canonicalBySignature: Map<string, DedupeCanonical>
|
|
31
|
+
/**
|
|
32
|
+
* New top-level schema definitions created for inline shapes that had no existing
|
|
33
|
+
* named component. Nested duplicates inside each definition are already collapsed.
|
|
34
|
+
*/
|
|
35
|
+
hoisted: Array<SchemaNode>
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Options that inject the naming and candidate policy into {@link buildDedupePlan}.
|
|
40
|
+
* The mechanics (grouping, counting, rewriting) live here; the policy lives in the caller.
|
|
41
|
+
*/
|
|
42
|
+
export type BuildDedupePlanOptions = {
|
|
43
|
+
/**
|
|
44
|
+
* Returns `true` when a node should be deduplicated. This is the only gate, so it must
|
|
45
|
+
* reject both ineligible kinds (return `false` for anything other than, say, enums and
|
|
46
|
+
* objects) and unsafe shapes (e.g. nodes that reference a circular schema).
|
|
47
|
+
*/
|
|
48
|
+
isCandidate: (node: SchemaNode) => boolean
|
|
49
|
+
/**
|
|
50
|
+
* Produces the canonical name for an inline shape with no existing named component.
|
|
51
|
+
* Return `null` to leave the shape inline (for example when no contextual name exists).
|
|
52
|
+
*/
|
|
53
|
+
nameFor: (node: SchemaNode, signature: string) => string | null
|
|
54
|
+
/**
|
|
55
|
+
* Builds the `$ref` path for a canonical name.
|
|
56
|
+
*/
|
|
57
|
+
refFor: (name: string) => string
|
|
58
|
+
/**
|
|
59
|
+
* Minimum number of occurrences before a shape is deduplicated.
|
|
60
|
+
*
|
|
61
|
+
* @default 2
|
|
62
|
+
*/
|
|
63
|
+
minOccurrences?: number
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Builds the shared `ref` replacement for a duplicate occurrence, carrying the
|
|
68
|
+
* usage-slot and documentation fields that are not part of the canonical type.
|
|
69
|
+
*/
|
|
70
|
+
function createRefNode(node: SchemaNode, canonical: DedupeCanonical): SchemaNode {
|
|
71
|
+
return createSchema({
|
|
72
|
+
type: 'ref',
|
|
73
|
+
name: canonical.name,
|
|
74
|
+
ref: canonical.ref,
|
|
75
|
+
optional: node.optional,
|
|
76
|
+
nullish: node.nullish,
|
|
77
|
+
readOnly: node.readOnly,
|
|
78
|
+
writeOnly: node.writeOnly,
|
|
79
|
+
deprecated: node.deprecated,
|
|
80
|
+
description: node.description,
|
|
81
|
+
default: node.default,
|
|
82
|
+
example: node.example,
|
|
83
|
+
})
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Rewrites a node, replacing every candidate sub-schema whose signature has a canonical
|
|
88
|
+
* target with a `ref` to that target. Replacing a node with a `ref` prunes its subtree,
|
|
89
|
+
* so nested duplicates inside a replaced shape are not visited again.
|
|
90
|
+
*
|
|
91
|
+
* Pass `skipRootMatch` when rewriting a canonical definition so its own root is not
|
|
92
|
+
* turned into a reference to itself; nested duplicates are still collapsed.
|
|
93
|
+
*
|
|
94
|
+
* @example
|
|
95
|
+
* ```ts
|
|
96
|
+
* const next = applyDedupe(operationNode, plan.canonicalBySignature)
|
|
97
|
+
* ```
|
|
98
|
+
*/
|
|
99
|
+
export function applyDedupe(node: SchemaNode, canonicalBySignature: ReadonlyMap<string, DedupeCanonical>, skipRootMatch?: boolean): SchemaNode
|
|
100
|
+
export function applyDedupe(node: OperationNode, canonicalBySignature: ReadonlyMap<string, DedupeCanonical>, skipRootMatch?: boolean): OperationNode
|
|
101
|
+
export function applyDedupe(node: Node, canonicalBySignature: ReadonlyMap<string, DedupeCanonical>, skipRootMatch = false): Node {
|
|
102
|
+
if (canonicalBySignature.size === 0) return node
|
|
103
|
+
|
|
104
|
+
const signatures = new Map<SchemaNode, string>()
|
|
105
|
+
const root = node
|
|
106
|
+
|
|
107
|
+
return transform(node, {
|
|
108
|
+
schema(schemaNode) {
|
|
109
|
+
const signature = signatureOf(schemaNode, signatures)
|
|
110
|
+
if (skipRootMatch && schemaNode === root) return undefined
|
|
111
|
+
|
|
112
|
+
const canonical = canonicalBySignature.get(signature)
|
|
113
|
+
if (!canonical) return undefined
|
|
114
|
+
|
|
115
|
+
return createRefNode(schemaNode, canonical)
|
|
116
|
+
},
|
|
117
|
+
})
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Strips usage-slot flags from a hoisted definition and applies its canonical name.
|
|
122
|
+
* A standalone definition is never optional, so `optional`/`nullish` are cleared.
|
|
123
|
+
*/
|
|
124
|
+
function cleanDefinition(node: SchemaNode, name: string): SchemaNode {
|
|
125
|
+
return { ...node, name, optional: undefined, nullish: undefined }
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Scans a forest of schema and operation nodes and produces a {@link DedupePlan}.
|
|
130
|
+
*
|
|
131
|
+
* A shape that occurs at least `minOccurrences` times is deduplicated: if any occurrence
|
|
132
|
+
* is a named top-level schema, that name becomes the canonical (so other top-level duplicates
|
|
133
|
+
* and inline copies turn into references to it); otherwise a new definition is hoisted using
|
|
134
|
+
* `nameFor`. The plan is then applied per node with {@link applyDedupe}.
|
|
135
|
+
*
|
|
136
|
+
* @example
|
|
137
|
+
* ```ts
|
|
138
|
+
* const plan = buildDedupePlan([...schemaNodes, ...operationNodes], {
|
|
139
|
+
* isCandidate: (node) => node.type === 'enum' || node.type === 'object',
|
|
140
|
+
* nameFor: (node) => node.name ?? null,
|
|
141
|
+
* refFor: (name) => `#/components/schemas/${name}`,
|
|
142
|
+
* })
|
|
143
|
+
* ```
|
|
144
|
+
*/
|
|
145
|
+
export function buildDedupePlan(roots: ReadonlyArray<Node>, options: BuildDedupePlanOptions): DedupePlan {
|
|
146
|
+
const { isCandidate, nameFor, refFor, minOccurrences = 2 } = options
|
|
147
|
+
|
|
148
|
+
const signatures = new Map<SchemaNode, string>()
|
|
149
|
+
const topLevelNodes = new Set<SchemaNode>()
|
|
150
|
+
|
|
151
|
+
type Group = {
|
|
152
|
+
count: number
|
|
153
|
+
representative: SchemaNode
|
|
154
|
+
topLevelName?: string
|
|
155
|
+
}
|
|
156
|
+
const groups = new Map<string, Group>()
|
|
157
|
+
|
|
158
|
+
function record(schemaNode: SchemaNode): void {
|
|
159
|
+
const signature = signatureOf(schemaNode, signatures)
|
|
160
|
+
if (!isCandidate(schemaNode)) return
|
|
161
|
+
|
|
162
|
+
const isTopLevel = topLevelNodes.has(schemaNode) && !!schemaNode.name
|
|
163
|
+
const group = groups.get(signature)
|
|
164
|
+
if (group) {
|
|
165
|
+
group.count++
|
|
166
|
+
if (isTopLevel && !group.topLevelName) group.topLevelName = schemaNode.name!
|
|
167
|
+
} else {
|
|
168
|
+
groups.set(signature, { count: 1, representative: schemaNode, topLevelName: isTopLevel ? schemaNode.name! : undefined })
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
for (const root of roots) {
|
|
173
|
+
if (root.kind === 'Schema') topLevelNodes.add(root)
|
|
174
|
+
for (const schemaNode of collectLazy<SchemaNode>(root, { schema: (node) => node })) {
|
|
175
|
+
record(schemaNode)
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
const canonicalBySignature = new Map<string, DedupeCanonical>()
|
|
180
|
+
const pendingHoists: Array<{ name: string; representative: SchemaNode }> = []
|
|
181
|
+
|
|
182
|
+
for (const [signature, group] of groups) {
|
|
183
|
+
if (group.count < minOccurrences) continue
|
|
184
|
+
|
|
185
|
+
if (group.topLevelName) {
|
|
186
|
+
canonicalBySignature.set(signature, { name: group.topLevelName, ref: refFor(group.topLevelName) })
|
|
187
|
+
continue
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
const name = nameFor(group.representative, signature)
|
|
191
|
+
if (!name) continue
|
|
192
|
+
|
|
193
|
+
canonicalBySignature.set(signature, { name, ref: refFor(name) })
|
|
194
|
+
pendingHoists.push({ name, representative: group.representative })
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// Build hoisted definitions only after every canonical name is known, so nested
|
|
198
|
+
// duplicates inside a definition also resolve to refs.
|
|
199
|
+
const hoisted = pendingHoists.map(({ name, representative }) => cleanDefinition(applyDedupe(representative, canonicalBySignature, true), name))
|
|
200
|
+
|
|
201
|
+
return { canonicalBySignature, hoisted }
|
|
202
|
+
}
|
package/src/dialect.ts
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The spec-specific decisions a schema parser makes while converting a source
|
|
3
|
+
* document's schemas into Kubb AST nodes.
|
|
4
|
+
*
|
|
5
|
+
* Everything else in an adapter's schema pipeline is generic JSON Schema shared
|
|
6
|
+
* across specs; the dialect is the one seam where a spec differs — the
|
|
7
|
+
* "dialect layer" analogue of a database driver targeting Postgres vs MySQL.
|
|
8
|
+
* Pair it with {@link dispatch}: the rule table decides *which* converter runs,
|
|
9
|
+
* the dialect answers the spec-specific questions inside them.
|
|
10
|
+
*
|
|
11
|
+
* The guard methods (`isReference`, `isDiscriminator`) are type predicates so
|
|
12
|
+
* converters narrow the schema after a check; the type parameters carry those
|
|
13
|
+
* narrowed types through.
|
|
14
|
+
*
|
|
15
|
+
* Scope: this is the seam for the **JSON Schema family** — OpenAPI, AsyncAPI, and
|
|
16
|
+
* plain JSON Schema all share `$ref`, `allOf`/`oneOf`, `enum`, and `format`, and
|
|
17
|
+
* differ only in these few decisions. A spec built on a different type system
|
|
18
|
+
* (e.g. GraphQL, with non-null wrappers, interfaces, and named-type references
|
|
19
|
+
* instead of `$ref`) does not implement a `SchemaDialect`; it reuses the universal
|
|
20
|
+
* layer directly — the `Adapter` port, the AST factories, and {@link dispatch}
|
|
21
|
+
* with its own rule table — to emit the same nodes.
|
|
22
|
+
*
|
|
23
|
+
* @typeParam TSchema - The adapter's schema object type (e.g. an OpenAPI `SchemaObject`).
|
|
24
|
+
* @typeParam TRef - The narrowed `$ref` pointer type `isReference` proves.
|
|
25
|
+
* @typeParam TDiscriminated - The narrowed discriminated-schema type `isDiscriminator` proves.
|
|
26
|
+
* @typeParam TDocument - The source document `resolveRef` resolves against.
|
|
27
|
+
*/
|
|
28
|
+
export type SchemaDialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown> = {
|
|
29
|
+
/** Identifies the dialect in logs and while debugging dispatch. */
|
|
30
|
+
name: string
|
|
31
|
+
/** Whether a schema should be treated as nullable. */
|
|
32
|
+
isNullable: (schema?: TSchema) => boolean
|
|
33
|
+
/** Whether a value is a `$ref` pointer object. */
|
|
34
|
+
isReference: (value?: unknown) => value is TRef
|
|
35
|
+
/** Whether a schema carries a structured discriminator (polymorphism). */
|
|
36
|
+
isDiscriminator: (value?: unknown) => value is TDiscriminated
|
|
37
|
+
/** Whether a schema represents binary data (converted to a `blob` node). */
|
|
38
|
+
isBinary: (schema: TSchema) => boolean
|
|
39
|
+
/** Resolves a local `$ref` pointer against the document, or nullish when it cannot. */
|
|
40
|
+
resolveRef: <TResolved>(document: TDocument, ref: string) => TResolved | null | undefined
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Identity helper that types a {@link SchemaDialect} for an adapter. Like
|
|
45
|
+
* `defineParser`, it adds no runtime behavior — it pins the dialect's type for
|
|
46
|
+
* inference and gives adapter authors a discoverable anchor.
|
|
47
|
+
*
|
|
48
|
+
* @example
|
|
49
|
+
* ```ts
|
|
50
|
+
* export const oasDialect = defineSchemaDialect({
|
|
51
|
+
* name: 'oas',
|
|
52
|
+
* isNullable,
|
|
53
|
+
* isReference,
|
|
54
|
+
* isDiscriminator,
|
|
55
|
+
* isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
|
|
56
|
+
* resolveRef,
|
|
57
|
+
* })
|
|
58
|
+
* ```
|
|
59
|
+
*/
|
|
60
|
+
export function defineSchemaDialect<TSchema, TRef, TDiscriminated, TDocument>(
|
|
61
|
+
dialect: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>,
|
|
62
|
+
): SchemaDialect<TSchema, TRef, TDiscriminated, TDocument> {
|
|
63
|
+
return dialect
|
|
64
|
+
}
|
package/src/dispatch.ts
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One entry in an ordered dispatch table: a predicate paired with a converter.
|
|
3
|
+
*
|
|
4
|
+
* @typeParam TContext - Per-input context handed to every rule. A spec adapter typically
|
|
5
|
+
* pre-computes this once per node (the source spec node plus derived fields like a
|
|
6
|
+
* normalized type or resolved options) so individual rules stay cheap predicates.
|
|
7
|
+
* @typeParam TNode - The node a rule produces, e.g. a Kubb AST `SchemaNode`.
|
|
8
|
+
*/
|
|
9
|
+
export type DispatchRule<TContext, TNode> = {
|
|
10
|
+
/** Identifies the rule when reading the table or debugging which branch ran. */
|
|
11
|
+
name: string
|
|
12
|
+
/** Returns `true` when this rule is responsible for the given context. */
|
|
13
|
+
match: (context: TContext) => boolean
|
|
14
|
+
/**
|
|
15
|
+
* Produces a node for the context, or `null` to fall through to the next rule.
|
|
16
|
+
*
|
|
17
|
+
* Returning `null` lets a broad `match` defer: e.g. "has a `format`" matches many schemas,
|
|
18
|
+
* but only some formats are convertible — the rest fall through to plain `type` handling.
|
|
19
|
+
*/
|
|
20
|
+
convert: (context: TContext) => TNode | null
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Walks an ordered list of {@link DispatchRule}s and returns the first node produced.
|
|
25
|
+
*
|
|
26
|
+
* This is the shared backbone for spec adapters (OpenAPI today, AsyncAPI and others later).
|
|
27
|
+
* The contract an adapter follows is intentionally minimal:
|
|
28
|
+
*
|
|
29
|
+
* context → [rule.match → rule.convert] → node
|
|
30
|
+
*
|
|
31
|
+
* An adapter derives a context from a source spec node, then declares an ordered table of
|
|
32
|
+
* rules mapping spec shapes onto Kubb AST nodes. To add support for a new spec, write a new
|
|
33
|
+
* context type and a new rules table — the traversal here is reused unchanged.
|
|
34
|
+
*
|
|
35
|
+
* Order is significant: earlier rules win, so list higher-precedence or more specific shapes
|
|
36
|
+
* first (e.g. composition keywords before plain `type`). A rule whose `match` returns `true`
|
|
37
|
+
* may still `convert` to `null` to defer to later rules. When no rule produces a node this
|
|
38
|
+
* returns `null`, leaving the caller to apply its own fallback.
|
|
39
|
+
*
|
|
40
|
+
* @example
|
|
41
|
+
* ```ts
|
|
42
|
+
* const node = dispatch(schemaRules, schemaContext) ?? createSchema({ type: fallbackType })
|
|
43
|
+
* ```
|
|
44
|
+
*/
|
|
45
|
+
export function dispatch<TContext, TNode>(rules: ReadonlyArray<DispatchRule<TContext, TNode>>, context: TContext): TNode | null {
|
|
46
|
+
for (const rule of rules) {
|
|
47
|
+
if (!rule.match(context)) continue
|
|
48
|
+
const node = rule.convert(context)
|
|
49
|
+
if (node !== null && node !== undefined) return node
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
return null
|
|
53
|
+
}
|
package/src/factory.ts
CHANGED
|
@@ -6,14 +6,20 @@ import type {
|
|
|
6
6
|
ArrowFunctionNode,
|
|
7
7
|
BreakNode,
|
|
8
8
|
ConstNode,
|
|
9
|
+
ContentNode,
|
|
9
10
|
ExportNode,
|
|
10
11
|
FileNode,
|
|
11
12
|
FunctionNode,
|
|
12
13
|
FunctionParameterNode,
|
|
13
14
|
FunctionParametersNode,
|
|
15
|
+
GenericOperationNode,
|
|
16
|
+
HttpOperationNode,
|
|
14
17
|
ImportNode,
|
|
18
|
+
InputMeta,
|
|
15
19
|
InputNode,
|
|
20
|
+
InputStreamNode,
|
|
16
21
|
JsxNode,
|
|
22
|
+
Node,
|
|
17
23
|
ObjectSchemaNode,
|
|
18
24
|
OperationNode,
|
|
19
25
|
OutputNode,
|
|
@@ -22,6 +28,7 @@ import type {
|
|
|
22
28
|
ParamsTypeNode,
|
|
23
29
|
PrimitiveSchemaType,
|
|
24
30
|
PropertyNode,
|
|
31
|
+
RequestBodyNode,
|
|
25
32
|
ResponseNode,
|
|
26
33
|
SchemaNode,
|
|
27
34
|
SourceNode,
|
|
@@ -31,10 +38,13 @@ import type {
|
|
|
31
38
|
import { combineExports, combineImports, combineSources, extractStringsFromNodes } from './utils.ts'
|
|
32
39
|
|
|
33
40
|
/**
|
|
34
|
-
*
|
|
41
|
+
* Updates a schema's `optional` and `nullish` flags from a parent's `required`
|
|
42
|
+
* value and the schema's own `nullable`. Mirrors how OpenAPI parameters and
|
|
43
|
+
* object properties combine "required" and "nullable" into a single AST.
|
|
35
44
|
*
|
|
36
|
-
* -
|
|
37
|
-
* -
|
|
45
|
+
* - Non-required + non-nullable → `optional: true`.
|
|
46
|
+
* - Non-required + nullable → `nullish: true`.
|
|
47
|
+
* - Required → both flags cleared.
|
|
38
48
|
*/
|
|
39
49
|
export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNode {
|
|
40
50
|
const nullable = schema.nullable ?? false
|
|
@@ -59,6 +69,32 @@ export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNo
|
|
|
59
69
|
*/
|
|
60
70
|
export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
|
|
61
71
|
|
|
72
|
+
/**
|
|
73
|
+
* Identity-preserving node update: returns `node` unchanged when every field in
|
|
74
|
+
* `changes` already equals (by reference) the current value, otherwise a new node
|
|
75
|
+
* with the changes applied.
|
|
76
|
+
*
|
|
77
|
+
* Mirrors the TypeScript compiler's `factory.updateX` contract — pair it with the
|
|
78
|
+
* structural sharing in {@link transform} so a no-op rewrite doesn't allocate and
|
|
79
|
+
* downstream passes can detect "nothing changed" by identity. Comparison is
|
|
80
|
+
* shallow: a structurally-equal but newly-allocated array/object counts as a change.
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* ```ts
|
|
84
|
+
* update(node, { name: node.name }) // -> same `node` reference
|
|
85
|
+
* update(node, { name: 'renamed' }) // -> new node, `name` replaced
|
|
86
|
+
* ```
|
|
87
|
+
*/
|
|
88
|
+
export function update<T extends Node>(node: T, changes: Partial<T>): T {
|
|
89
|
+
for (const key in changes) {
|
|
90
|
+
if (changes[key] !== node[key as keyof T]) {
|
|
91
|
+
return { ...node, ...changes }
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
return node
|
|
96
|
+
}
|
|
97
|
+
|
|
62
98
|
type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties' | 'primitive'> & { properties?: Array<PropertyNode>; primitive?: 'object' }
|
|
63
99
|
type CreateSchemaInput = CreateSchemaObjectInput | DistributiveOmit<Exclude<SchemaNode, ObjectSchemaNode>, 'kind'>
|
|
64
100
|
type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & {
|
|
@@ -84,11 +120,24 @@ export function createInput(overrides: Partial<Omit<InputNode, 'kind'>> = {}): I
|
|
|
84
120
|
return {
|
|
85
121
|
schemas: [],
|
|
86
122
|
operations: [],
|
|
123
|
+
meta: { circularNames: [], enumNames: [] },
|
|
87
124
|
...overrides,
|
|
88
125
|
kind: 'Input',
|
|
89
126
|
}
|
|
90
127
|
}
|
|
91
128
|
|
|
129
|
+
/**
|
|
130
|
+
* Creates an `InputStreamNode` from pre-built `AsyncIterable` sources.
|
|
131
|
+
*
|
|
132
|
+
* @example
|
|
133
|
+
* ```ts
|
|
134
|
+
* const node = createStreamInput(schemasIterable, operationsIterable, { title: 'My API' })
|
|
135
|
+
* ```
|
|
136
|
+
*/
|
|
137
|
+
export function createStreamInput(schemas: AsyncIterable<SchemaNode>, operations: AsyncIterable<OperationNode>, meta?: InputMeta): InputStreamNode {
|
|
138
|
+
return { kind: 'Input', schemas, operations, meta }
|
|
139
|
+
}
|
|
140
|
+
|
|
92
141
|
/**
|
|
93
142
|
* Creates an `OutputNode` with a stable default for `files`.
|
|
94
143
|
*
|
|
@@ -134,16 +183,70 @@ export function createOutput(overrides: Partial<Omit<OutputNode, 'kind'>> = {}):
|
|
|
134
183
|
* })
|
|
135
184
|
* ```
|
|
136
185
|
*/
|
|
186
|
+
/**
|
|
187
|
+
* Loosely-typed content entry accepted by the builders, normalized into a {@link ContentNode}.
|
|
188
|
+
*/
|
|
189
|
+
type UserContent = Omit<ContentNode, 'kind'>
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* Creates a `ContentNode` for a single request-body or response content type.
|
|
193
|
+
*/
|
|
194
|
+
export function createContent(props: UserContent): ContentNode {
|
|
195
|
+
return {
|
|
196
|
+
...props,
|
|
197
|
+
kind: 'Content',
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* Loosely-typed request body accepted by `createOperation`, normalized into a {@link RequestBodyNode}.
|
|
203
|
+
*/
|
|
204
|
+
type UserRequestBody = Omit<RequestBodyNode, 'kind' | 'content'> & {
|
|
205
|
+
content?: Array<UserContent>
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Creates a `RequestBodyNode`, normalizing each content entry into a `ContentNode`.
|
|
210
|
+
*/
|
|
211
|
+
export function createRequestBody(props: UserRequestBody): RequestBodyNode {
|
|
212
|
+
return {
|
|
213
|
+
...props,
|
|
214
|
+
kind: 'RequestBody',
|
|
215
|
+
content: props.content?.map(createContent),
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
export function createOperation(
|
|
220
|
+
props: Pick<HttpOperationNode, 'operationId' | 'method' | 'path'> &
|
|
221
|
+
Partial<Omit<HttpOperationNode, 'kind' | 'operationId' | 'method' | 'path' | 'requestBody'>> & {
|
|
222
|
+
requestBody?: UserRequestBody
|
|
223
|
+
},
|
|
224
|
+
): HttpOperationNode
|
|
137
225
|
export function createOperation(
|
|
138
|
-
props: Pick<
|
|
139
|
-
|
|
226
|
+
props: Pick<GenericOperationNode, 'operationId'> &
|
|
227
|
+
Partial<Omit<GenericOperationNode, 'kind' | 'operationId' | 'requestBody'>> & {
|
|
228
|
+
requestBody?: UserRequestBody
|
|
229
|
+
},
|
|
230
|
+
): GenericOperationNode
|
|
231
|
+
export function createOperation(props: {
|
|
232
|
+
operationId: string
|
|
233
|
+
method?: HttpOperationNode['method']
|
|
234
|
+
path?: HttpOperationNode['path']
|
|
235
|
+
requestBody?: UserRequestBody
|
|
236
|
+
[key: string]: unknown
|
|
237
|
+
}): OperationNode {
|
|
238
|
+
const { requestBody, ...rest } = props
|
|
239
|
+
const isHttp = rest.method !== undefined && rest.path !== undefined
|
|
240
|
+
|
|
140
241
|
return {
|
|
141
242
|
tags: [],
|
|
142
243
|
parameters: [],
|
|
143
244
|
responses: [],
|
|
144
|
-
...
|
|
245
|
+
...rest,
|
|
246
|
+
...(isHttp ? { protocol: 'http' } : {}),
|
|
145
247
|
kind: 'Operation',
|
|
146
|
-
|
|
248
|
+
requestBody: requestBody ? createRequestBody(requestBody) : undefined,
|
|
249
|
+
} as OperationNode
|
|
147
250
|
}
|
|
148
251
|
|
|
149
252
|
/**
|
|
@@ -304,21 +407,34 @@ export function createParameter(
|
|
|
304
407
|
/**
|
|
305
408
|
* Creates a `ResponseNode`.
|
|
306
409
|
*
|
|
410
|
+
* Response body schemas live inside `content`. For convenience a single legacy `schema`
|
|
411
|
+
* (with optional `mediaType`/`keysToOmit`) is normalized into one `content` entry, so the same
|
|
412
|
+
* schema is never stored both at the node root and inside `content`.
|
|
413
|
+
*
|
|
307
414
|
* @example
|
|
308
415
|
* ```ts
|
|
309
416
|
* const response = createResponse({
|
|
310
417
|
* statusCode: '200',
|
|
311
|
-
*
|
|
312
|
-
* schema: createSchema({ type: 'object', properties: [] }),
|
|
418
|
+
* content: [{ contentType: 'application/json', schema: createSchema({ type: 'object', properties: [] }) }],
|
|
313
419
|
* })
|
|
314
420
|
* ```
|
|
315
421
|
*/
|
|
316
422
|
export function createResponse(
|
|
317
|
-
props: Pick<ResponseNode, 'statusCode'
|
|
423
|
+
props: Pick<ResponseNode, 'statusCode'> &
|
|
424
|
+
Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'content'>> & {
|
|
425
|
+
content?: Array<UserContent>
|
|
426
|
+
schema?: SchemaNode
|
|
427
|
+
mediaType?: string | null
|
|
428
|
+
keysToOmit?: Array<string> | null
|
|
429
|
+
},
|
|
318
430
|
): ResponseNode {
|
|
431
|
+
const { schema, mediaType, keysToOmit, content, ...rest } = props
|
|
432
|
+
const entries = content ?? (schema ? [{ contentType: mediaType ?? 'application/json', schema, keysToOmit: keysToOmit ?? null }] : undefined)
|
|
433
|
+
|
|
319
434
|
return {
|
|
320
|
-
...
|
|
435
|
+
...rest,
|
|
321
436
|
kind: 'Response',
|
|
437
|
+
content: entries?.map(createContent),
|
|
322
438
|
}
|
|
323
439
|
}
|
|
324
440
|
|
package/src/guards.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type {
|
|
2
2
|
FunctionParameterNode,
|
|
3
3
|
FunctionParametersNode,
|
|
4
|
+
HttpOperationNode,
|
|
4
5
|
InputNode,
|
|
5
6
|
Node,
|
|
6
7
|
NodeKind,
|
|
@@ -20,11 +21,11 @@ import type {
|
|
|
20
21
|
* @example
|
|
21
22
|
* ```ts
|
|
22
23
|
* const schema = createSchema({ type: 'string' })
|
|
23
|
-
* const stringNode = narrowSchema(schema, 'string') // StringSchemaNode |
|
|
24
|
+
* const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null
|
|
24
25
|
* ```
|
|
25
26
|
*/
|
|
26
|
-
export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] |
|
|
27
|
-
return node?.type === type ? (node as SchemaNodeByType[T]) :
|
|
27
|
+
export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | null {
|
|
28
|
+
return node?.type === type ? (node as SchemaNodeByType[T]) : null
|
|
28
29
|
}
|
|
29
30
|
|
|
30
31
|
function isKind<T extends Node>(kind: NodeKind) {
|
|
@@ -67,6 +68,20 @@ export const isOutputNode = isKind<OutputNode>('Output')
|
|
|
67
68
|
*/
|
|
68
69
|
export const isOperationNode = isKind<OperationNode>('Operation')
|
|
69
70
|
|
|
71
|
+
/**
|
|
72
|
+
* Narrows an `OperationNode` to an `HttpOperationNode`, guaranteeing `method` and `path`.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```ts
|
|
76
|
+
* if (isHttpOperationNode(node)) {
|
|
77
|
+
* console.log(node.method, node.path)
|
|
78
|
+
* }
|
|
79
|
+
* ```
|
|
80
|
+
*/
|
|
81
|
+
export function isHttpOperationNode(node: OperationNode): node is HttpOperationNode {
|
|
82
|
+
return node.protocol === 'http' || (node.method !== undefined && node.path !== undefined)
|
|
83
|
+
}
|
|
84
|
+
|
|
70
85
|
/**
|
|
71
86
|
* Returns `true` when the input is a `SchemaNode`.
|
|
72
87
|
*
|
package/src/index.ts
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
export { httpMethods, isScalarPrimitive, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
|
|
2
|
+
export { applyDedupe, buildDedupePlan } from './dedupe.ts'
|
|
3
|
+
export { defineSchemaDialect } from './dialect.ts'
|
|
4
|
+
export { dispatch } from './dispatch.ts'
|
|
2
5
|
export {
|
|
3
6
|
createArrowFunction,
|
|
4
7
|
createBreak,
|
|
5
8
|
createConst,
|
|
9
|
+
createContent,
|
|
6
10
|
createExport,
|
|
7
11
|
createFile,
|
|
8
12
|
createFunction,
|
|
@@ -10,6 +14,7 @@ export {
|
|
|
10
14
|
createFunctionParameters,
|
|
11
15
|
createImport,
|
|
12
16
|
createInput,
|
|
17
|
+
createStreamInput,
|
|
13
18
|
createJsx,
|
|
14
19
|
createOperation,
|
|
15
20
|
createOutput,
|
|
@@ -17,18 +22,21 @@ export {
|
|
|
17
22
|
createParameterGroup,
|
|
18
23
|
createParamsType,
|
|
19
24
|
createProperty,
|
|
25
|
+
createRequestBody,
|
|
20
26
|
createResponse,
|
|
21
27
|
createSchema,
|
|
22
28
|
createSource,
|
|
23
29
|
createText,
|
|
24
30
|
createType,
|
|
25
31
|
syncOptionality,
|
|
32
|
+
update,
|
|
26
33
|
} from './factory.ts'
|
|
27
|
-
export { isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
|
|
34
|
+
export { isHttpOperationNode, isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
|
|
28
35
|
export { createPrinterFactory, definePrinter } from './printer.ts'
|
|
29
36
|
export { extractRefName } from './refs.ts'
|
|
30
37
|
export { childName, collectImports, enumPropName, findDiscriminator } from './resolvers.ts'
|
|
31
|
-
export {
|
|
38
|
+
export { isSchemaEqual, schemaSignature } from './signature.ts'
|
|
39
|
+
export { mergeAdjacentObjects, mergeAdjacentObjectsLazy, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
|
|
32
40
|
export type * from './types.ts'
|
|
33
41
|
export {
|
|
34
42
|
caseParams,
|
|
@@ -43,4 +51,4 @@ export {
|
|
|
43
51
|
resolveRefName,
|
|
44
52
|
syncSchemaRef,
|
|
45
53
|
} from './utils.ts'
|
|
46
|
-
export { collect, transform, walk } from './visitor.ts'
|
|
54
|
+
export { collect, collectLazy, transform, walk } from './visitor.ts'
|