fork of hey-api/openapi-ts because I need some additional things
docs: add Resolvers API
+243
-11
+5
.changeset/curly-geckos-play.md
+5
.changeset/curly-geckos-play.md
+7
.changeset/fruity-camels-type.md
+7
.changeset/fruity-camels-type.md
···
1
+
---
2
+
'@hey-api/openapi-ts': minor
3
+
---
4
+
5
+
**plugin(valibot)**: **BREAKING:** standardize `~resolvers` API
6
+
7
+
The [Resolvers API](https://heyapi.dev/openapi-ts/plugins/concepts/resolvers) has been simplified and expanded to provide a more consistent behavior across plugins. You can view a few common examples on the [Resolvers](https://heyapi.dev/openapi-ts/plugins/concepts/resolvers) page.
+7
.changeset/upset-weeks-dream.md
+7
.changeset/upset-weeks-dream.md
···
1
+
---
2
+
'@hey-api/openapi-ts': minor
3
+
---
4
+
5
+
**plugin(zod)**: **BREAKING:** standardize `~resolvers` API
6
+
7
+
The [Resolvers API](https://heyapi.dev/openapi-ts/plugins/concepts/resolvers) has been simplified and expanded to provide a more consistent behavior across plugins. You can view a few common examples on the [Resolvers](https://heyapi.dev/openapi-ts/plugins/concepts/resolvers) page.
+9
-9
dev/openapi-ts.config.ts
+9
-9
dev/openapi-ts.config.ts
···
443
443
// });
444
444
// return $(v).attr('instance').call(big);
445
445
// },
446
-
// object(ctx) {
447
-
// const { $, symbols } = ctx;
448
-
// const { v } = symbols;
449
-
// const additional = ctx.nodes.additionalProperties(ctx);
450
-
// if (additional === undefined) {
451
-
// const shape = ctx.nodes.shape(ctx);
452
-
// ctx.nodes.base = () => $(v).attr('looseObject').call(shape);
453
-
// }
454
-
// },
446
+
object(ctx) {
447
+
const { $, symbols } = ctx;
448
+
const { v } = symbols;
449
+
const additional = ctx.nodes.additionalProperties(ctx);
450
+
if (additional === undefined) {
451
+
const shape = ctx.nodes.shape(ctx);
452
+
ctx.nodes.base = () => $(v).attr('looseObject').call(shape);
453
+
}
454
+
},
455
455
// string(ctx) {
456
456
// const { $, schema, symbols } = ctx;
457
457
// const { v } = symbols;
+10
docs/.vitepress/config/en.ts
+10
docs/.vitepress/config/en.ts
···
259
259
collapsed: true,
260
260
items: [
261
261
{
262
+
link: '/openapi-ts/plugins/concepts/resolvers',
263
+
text: 'Resolvers',
264
+
},
265
+
],
266
+
text: 'Concepts',
267
+
},
268
+
{
269
+
collapsed: true,
270
+
items: [
271
+
{
262
272
link: '/openapi-ts/plugins/custom',
263
273
text: 'Plugin',
264
274
},
+2
-2
docs/openapi-ts/clients.md
+2
-2
docs/openapi-ts/clients.md
···
1
1
---
2
2
title: Clients
3
-
description: REST clients for Hey API. Compatible with all our features.
3
+
description: HTTP clients for Hey API. Compatible with all our features.
4
4
---
5
5
6
6
<script setup lang="ts">
7
7
import { embedProject } from '../embed'
8
8
</script>
9
9
10
-
# REST Clients
10
+
# HTTP Clients
11
11
12
12
We all send HTTP requests in a slightly different way. Hey API doesn't force you to use any specific technology. What we do, however, is support your choice with great clients. All seamlessly integrated with our other features.
13
13
+6
docs/openapi-ts/migrating.md
+6
docs/openapi-ts/migrating.md
···
7
7
8
8
While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code. If you run into a problem with migration, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
9
9
10
+
## v0.90.0
11
+
12
+
### Resolvers API
13
+
14
+
The [Resolvers API](/openapi-ts/plugins/concepts/resolvers) has been simplified and expanded to provide a more consistent behavior across plugins. You can view a few common examples on the [Resolvers](/openapi-ts/plugins/concepts/resolvers) page.
15
+
10
16
## v0.89.0
11
17
12
18
### Prefer named exports
+181
docs/openapi-ts/plugins/concepts/resolvers.md
+181
docs/openapi-ts/plugins/concepts/resolvers.md
···
1
+
---
2
+
title: Resolvers
3
+
description: Understand the concepts behind plugins.
4
+
---
5
+
6
+
# Resolvers
7
+
8
+
Sometimes the default plugin behavior isn't what you need or expect. Resolvers let you patch plugins in a safe and performant way, without forking or reimplementing core logic.
9
+
10
+
Currently available for [Valibot](/openapi-ts/plugins/valibot) and [Zod](/openapi-ts/plugins/zod).
11
+
12
+
## Examples
13
+
14
+
This page demonstrates resolvers through a few common scenarios.
15
+
16
+
1. [Handle arbitrary schema formats](#example-1)
17
+
2. [Validate high precision numbers](#example-2)
18
+
3. [Replace default base](#example-3)
19
+
20
+
## Terminology
21
+
22
+
Before we look at examples, let's go through the resolvers API to help you understand how they work. Plugins that support resolvers expose them through the `~resolvers` option. Each resolver is a function that receives context and returns an implemented node (or patches existing ones).
23
+
24
+
The resolver context will usually contain:
25
+
26
+
- `$` - The node builder interface. Use it to build your custom logic.
27
+
- `nodes` - Parts of the plugin logic. You can use these to avoid reimplementing the functionality, or replace them with custom implementation.
28
+
- `plugin` - The plugin instance. You'll most likely use it to register new symbols.
29
+
- `symbols` - Frequently used symbols. These are effectively shorthands for commonly used `plugin.referenceSymbol()` calls.
30
+
31
+
Other fields may include the current schema or relevant utilities.
32
+
33
+
## Example 1
34
+
35
+
### Handle arbitrary schema formats
36
+
37
+
By default, the Valibot plugin may produce the following schemas for `date` and `date-time` strings.
38
+
39
+
```js
40
+
export const vDates = v.object({
41
+
created: v.pipe(v.string(), v.isoDate()),
42
+
modified: v.pipe(v.string(), v.isoTimestamp()),
43
+
});
44
+
```
45
+
46
+
We can override this behavior by patching the `nodes.format` function only for strings with `date` or `date-time` formats.
47
+
48
+
```js
49
+
{
50
+
name: 'valibot',
51
+
'~resolvers': {
52
+
string(ctx) {
53
+
const { $, schema, symbols } = ctx;
54
+
const { v } = symbols;
55
+
if (schema.format === 'date' || schema.format === 'date-time') {
56
+
ctx.nodes.format = () => $(v).attr('isoDateTime').call();
57
+
}
58
+
}
59
+
}
60
+
}
61
+
```
62
+
63
+
This applies custom logic with surgical precision, without affecting the rest of the default behavior.
64
+
65
+
::: code-group
66
+
67
+
```js [after]
68
+
export const vDates = v.object({
69
+
created: v.pipe(v.string(), v.isoDateTime()),
70
+
modified: v.pipe(v.string(), v.isoDateTime()),
71
+
});
72
+
```
73
+
74
+
```js [before]
75
+
export const vDates = v.object({
76
+
created: v.pipe(v.string(), v.isoDate()),
77
+
modified: v.pipe(v.string(), v.isoTimestamp()),
78
+
});
79
+
```
80
+
81
+
:::
82
+
83
+
## Example 2
84
+
85
+
### Validate high precision numbers
86
+
87
+
Let's say you're dealing with very large or unsafe numbers.
88
+
89
+
```js
90
+
export const vAmount = v.number();
91
+
```
92
+
93
+
In this case, you'll want to use a third-party library to validate your values. We can use big.js to validate all numbers by replacing the whole resolver.
94
+
95
+
```js
96
+
{
97
+
name: 'valibot',
98
+
'~resolvers': {
99
+
number(ctx) {
100
+
const { $, plugin, symbols } = ctx;
101
+
const { v } = symbols;
102
+
const big = plugin.symbolOnce('Big', {
103
+
external: 'big.js',
104
+
importKind: 'default',
105
+
});
106
+
return $(v).attr('instance').call(big);
107
+
}
108
+
}
109
+
}
110
+
```
111
+
112
+
We're calling `plugin.symbolOnce()` to ensure we always use the same symbol reference.
113
+
114
+
::: code-group
115
+
116
+
```js [after]
117
+
import Big from 'big.js';
118
+
119
+
export const vAmount = v.instance(Big);
120
+
```
121
+
122
+
```js [before]
123
+
export const vAmount = v.number();
124
+
```
125
+
126
+
:::
127
+
128
+
## Example 3
129
+
130
+
### Replace default base
131
+
132
+
You might want to replace the default base schema, e.g. `v.object()`.
133
+
134
+
```js
135
+
export const vUser = v.object({
136
+
age: v.number(),
137
+
});
138
+
```
139
+
140
+
Let's say we want to interpret any schema without explicitly defined additional properties as a loose object.
141
+
142
+
```js
143
+
{
144
+
name: 'valibot',
145
+
'~resolvers': {
146
+
object(ctx) {
147
+
const { $, symbols } = ctx;
148
+
const { v } = symbols;
149
+
const additional = ctx.nodes.additionalProperties(ctx);
150
+
if (additional === undefined) {
151
+
const shape = ctx.nodes.shape(ctx);
152
+
ctx.nodes.base = () => $(v).attr('looseObject').call(shape);
153
+
}
154
+
}
155
+
}
156
+
}
157
+
```
158
+
159
+
Above we demonstrate patching a node based on the result of another node.
160
+
161
+
::: code-group
162
+
163
+
```js [after]
164
+
export const vUser = v.looseObject({
165
+
age: v.number(),
166
+
});
167
+
```
168
+
169
+
```js [before]
170
+
export const vUser = v.object({
171
+
age: v.number(),
172
+
});
173
+
```
174
+
175
+
:::
176
+
177
+
## Feedback
178
+
179
+
We welcome feedback on the Resolvers API. [Open a GitHub issue](https://github.com/hey-api/openapi-ts/issues) to request support for additional plugins.
180
+
181
+
<!--@include: ../../../partials/sponsors.md-->
+4
docs/openapi-ts/plugins/valibot.md
+4
docs/openapi-ts/plugins/valibot.md
···
207
207
208
208
:::
209
209
210
+
## Resolvers
211
+
212
+
You can further customize this plugin's behavior using [resolvers](/openapi-ts/plugins/concepts/resolvers).
213
+
210
214
## API
211
215
212
216
You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/valibot/types.d.ts) interface.
+4
docs/openapi-ts/plugins/zod.md
+4
docs/openapi-ts/plugins/zod.md
···
299
299
300
300
You can customize the naming and casing pattern for schema-specific `types` using the `.name` and `.case` options.
301
301
302
+
## Resolvers
303
+
304
+
You can further customize this plugin's behavior using [resolvers](/openapi-ts/plugins/concepts/resolvers).
305
+
302
306
## API
303
307
304
308
You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/zod/types.d.ts) interface.
+4
docs/openapi-ts/plugins/zod/mini.md
+4
docs/openapi-ts/plugins/zod/mini.md
···
312
312
313
313
You can customize the naming and casing pattern for schema-specific `types` using the `.name` and `.case` options.
314
314
315
+
## Resolvers
316
+
317
+
You can further customize this plugin's behavior using [resolvers](/openapi-ts/plugins/concepts/resolvers).
318
+
315
319
## API
316
320
317
321
You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/zod/types.d.ts) interface.
+4
docs/openapi-ts/plugins/zod/v3.md
+4
docs/openapi-ts/plugins/zod/v3.md
···
310
310
311
311
You can customize the naming and casing pattern for schema-specific `types` using the `.name` and `.case` options.
312
312
313
+
## Resolvers
314
+
315
+
You can further customize this plugin's behavior using [resolvers](/openapi-ts/plugins/concepts/resolvers).
316
+
313
317
## API
314
318
315
319
You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/zod/types.d.ts) interface.