@kubb/plugin-valibot 0.0.0-stage → 0.0.0
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/LICENSE +21 -0
- package/README.md +73 -2
- package/dist/index.cjs +2105 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +308 -0
- package/dist/index.d.ts +308 -0
- package/dist/index.js +2096 -0
- package/dist/index.js.map +1 -0
- package/docs/guides/coercion.md +52 -0
- package/docs/guides/customization.md +131 -0
- package/docs/guides/format-mappings.md +98 -0
- package/docs/guides/inferred-types.md +70 -0
- package/docs/options.md +215 -0
- package/docs/overview.md +70 -0
- package/kubb-extension.json +224 -0
- package/package.json +93 -3
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Valibot schemas for OpenAPI formats
|
|
2
|
+
|
|
3
|
+
Look up the Valibot call Kubb writes for each OpenAPI type and format, such as `v.uuid()` for `format: uuid`, and the keywords that add a `v.check`.
|
|
4
|
+
|
|
5
|
+
`@kubb/plugin-valibot` reads the `type` and `format` of each schema and prints the matching Valibot call. Constraints such as `minLength` and `maximum` go into the same `v.pipe(...)`.
|
|
6
|
+
|
|
7
|
+
## Numbers
|
|
8
|
+
|
|
9
|
+
| OpenAPI type and format | Valibot | Notes |
|
|
10
|
+
| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| `number` | `v.number()` | |
|
|
12
|
+
| `integer` | `v.pipe(v.number(), v.integer())` | `format: int8`, `int16`, `int32`, and their `uint` forms add `v.minValue()` and `v.maxValue()` for the format's range |
|
|
13
|
+
| `integer`, `format: int64` / `uint64` | `v.pipe(v.union([v.bigint(), v.number(), v.string()]), v.toBigint(), v.minValue(BigInt('…')), v.maxValue(BigInt('…')))` | Converts, because JSON holds a number or a string, then checks the format's range |
|
|
14
|
+
| `string`, `format: int32` / `int64` | `v.pipe(v.string(), v.regex(/^-?\d+$/))` | An integer sent as a JSON string. A `pattern` in the spec wins. |
|
|
15
|
+
| `minimum`, `maximum` | `v.minValue(n)`, `v.maxValue(n)` | |
|
|
16
|
+
| `exclusiveMinimum`, `exclusiveMaximum` | `v.gtValue(n)`, `v.ltValue(n)` | |
|
|
17
|
+
| `multipleOf` | `v.multipleOf(n)` | |
|
|
18
|
+
|
|
19
|
+
With [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, `format: int64` prints `v.pipe(v.number(), v.integer())`.
|
|
20
|
+
|
|
21
|
+
## Strings
|
|
22
|
+
|
|
23
|
+
| OpenAPI type and format | Valibot | Notes |
|
|
24
|
+
| :---------------------------------- | :------------------------------------------------- | :-------------------------------------------------------------------------------------------- |
|
|
25
|
+
| `string` | `v.string()` | |
|
|
26
|
+
| `string`, `format: uuid` | `v.pipe(v.string(), v.uuid())` | |
|
|
27
|
+
| `string`, `format: email` | `v.pipe(v.string(), v.email())` | |
|
|
28
|
+
| `string`, `format: uri` | `v.pipe(v.string(), v.url())` | |
|
|
29
|
+
| `string`, `format: ipv4` / `ipv6` | `v.pipe(v.string(), v.ipv4())` | `v.ipv6()` for `ipv6` |
|
|
30
|
+
| `string`, `format: byte` | `v.pipe(v.string(), v.base64())` | Also for `contentEncoding: base64` |
|
|
31
|
+
| `string`, `format: ulid` | `v.pipe(v.string(), v.ulid())` | |
|
|
32
|
+
| `string`, `format: binary` | `v.blob()` | |
|
|
33
|
+
| `minLength`, `maxLength`, `pattern` | `v.minLength(n)`, `v.maxLength(n)`, `v.regex(...)` | See [`regexType`](https://kubb.dev/extensions/kubb-labs/plugin-valibot/options#regextype) |
|
|
34
|
+
| `enum` | `v.picklist([...])` | A single value prints `v.literal(...)`. A boolean or mixed set prints a `v.union` of literals |
|
|
35
|
+
|
|
36
|
+
Any other string format prints `v.string()`.
|
|
37
|
+
|
|
38
|
+
## Dates and times
|
|
39
|
+
|
|
40
|
+
| OpenAPI type and format | Valibot | Notes |
|
|
41
|
+
| :---------------------------- | :------------------------------------- | :------------------------------------------------------------- |
|
|
42
|
+
| `string`, `format: date` | `v.pipe(v.string(), v.isoDate())` | ISO 8601 date |
|
|
43
|
+
| `string`, `format: date-time` | `v.pipe(v.string(), v.isoTimestamp())` | Needs a `Z` or an offset |
|
|
44
|
+
| `string`, `format: time` | `v.string()` | Not checked. Valibot's time actions reject fractional seconds. |
|
|
45
|
+
|
|
46
|
+
These rows apply to the adapter's default `dateType: 'string'`. With `dateType: 'stringLocal'`, a date-time prints `v.string()`, because Valibot has no check for a date-time without an offset.
|
|
47
|
+
|
|
48
|
+
### Date fields
|
|
49
|
+
|
|
50
|
+
With `dateType: 'date'`, a date, date-time, or time is a `Date` in your code and a string on the wire. A response schema converts the string to a `Date`, and a request schema converts it back:
|
|
51
|
+
|
|
52
|
+
| OpenAPI type and format | Response schema | Request schema |
|
|
53
|
+
| :---------------------------- | :------------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
|
|
54
|
+
| `string`, `format: date` | `v.pipe(v.string(), v.isoDate(), v.transform((value) => new Date(value)))` | `v.pipe(v.date(), v.transform((value) => value.toISOString().slice(0, 10)))` |
|
|
55
|
+
| `string`, `format: date-time` | `v.pipe(v.string(), v.isoTimestamp(), v.transform(...))` | `v.pipe(v.date(), v.transform((value) => value.toISOString()))` |
|
|
56
|
+
| `string`, `format: time` | Parses onto `1970-01-01`, as UTC when the value has no offset | Writes `HH:mm:ssZ`, with milliseconds when the value has them |
|
|
57
|
+
|
|
58
|
+
A component schema with such a field is generated twice: `petSchema` for responses and `petInputSchema` for requests. With [`coercion`](https://kubb.dev/extensions/kubb-labs/plugin-valibot/options#coercion) for dates, the response schema prints `v.pipe(v.unknown(), v.toDate())`.
|
|
59
|
+
|
|
60
|
+
## Objects, arrays, and unions
|
|
61
|
+
|
|
62
|
+
| OpenAPI | Valibot | Notes |
|
|
63
|
+
| :----------------------------------------- | :----------------------------------- | :--------------------------------------------------------------------------------------------------------- |
|
|
64
|
+
| `object` | `v.object(entries)` | Drops unknown keys from the output |
|
|
65
|
+
| `object`, `additionalProperties: false` | `v.strictObject(entries)` | Rejects extra keys |
|
|
66
|
+
| `object`, `additionalProperties: true` | `v.looseObject(entries)` | Keeps extra keys |
|
|
67
|
+
| `object`, `additionalProperties: <schema>` | `v.record(v.string(), schema)` | `v.objectWithRest(entries, schema)` next to `properties` |
|
|
68
|
+
| Optional property | `v.optional(schema)` | A `default` prints `v.optional(schema, value)` |
|
|
69
|
+
| `nullable: true` | `v.nullable(schema)` | |
|
|
70
|
+
| `array` | `v.array(schema)` | `uniqueItems` adds a `v.check(...)` |
|
|
71
|
+
| `prefixItems` | `v.tuple([...])` | `v.tupleWithRest([...], schema)` with `items` |
|
|
72
|
+
| `anyOf` | `v.union([...])` | |
|
|
73
|
+
| `oneOf` | `v.union([...])` | Plain object members are strict, so a value with another member's keys does not match them |
|
|
74
|
+
| `oneOf` with a `discriminator` | `v.variant(key, [...])` | `v.union` when a member is not a plain object |
|
|
75
|
+
| `allOf` of objects | `v.object({ ...base.entries, ... })` | Other members print `v.intersect([...])`, or extra actions in the pipe when a member only adds constraints |
|
|
76
|
+
| `$ref` | The schema's const | `v.lazy(() => schema)` for a circular reference |
|
|
77
|
+
|
|
78
|
+
## JSON Schema keywords
|
|
79
|
+
|
|
80
|
+
These keywords print a `v.check`:
|
|
81
|
+
|
|
82
|
+
| Keyword | Check |
|
|
83
|
+
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
84
|
+
| `if`/`then`/`else`, `dependentRequired`, `dependentSchemas` | Checks the input before parsing, in `v.pipe(v.unknown(), v.check(...), schema)`. |
|
|
85
|
+
| `minProperties`, `maxProperties` | Counts the keys of the input before parsing, in the same `v.pipe(...)`. |
|
|
86
|
+
| `propertyNames` on an object that also declares `properties` | Checks every key of the input. A dictionary keeps `v.record(keySchema, schema)`. |
|
|
87
|
+
| `patternProperties` next to `properties` and `additionalProperties: false` | Rejects a key that is not declared and matches no pattern. |
|
|
88
|
+
| `contains` with `minContains` and `maxContains` | Counts the matching items of an array. |
|
|
89
|
+
| `contentSchema` on a string that holds JSON | Parses the string and checks the result. |
|
|
90
|
+
| `uniqueItems` | Rejects an array with duplicate entries. |
|
|
91
|
+
|
|
92
|
+
A request body that is a circular schema prints inline without its `readOnly` keys. In a circular `allOf`, a `$ref` member that declares such a key prints inline too.
|
|
93
|
+
|
|
94
|
+
A schema with a check on the input is a `v.pipe`, so it is no member of a `v.variant` and does not merge into an `allOf` object. A request body that drops `readOnly` keys from such a schema leaves the input checks out.
|
|
95
|
+
|
|
96
|
+
The plugin does not write `description` or `examples` into the schemas.
|
|
97
|
+
|
|
98
|
+
To change the call for one type, replace its handler with [`printer`](https://kubb.dev/extensions/kubb-labs/plugin-valibot/options#printer).
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Infer TypeScript types from Valibot schemas
|
|
2
|
+
|
|
3
|
+
Set `inferred` to export a type next to each Valibot schema, so you can skip `@kubb/plugin-ts`.
|
|
4
|
+
|
|
5
|
+
## Turn on inferred types
|
|
6
|
+
|
|
7
|
+
With `inferred: true`, each schema gets a type named after it: the PascalCase schema name plus `SchemaType`, so `petSchema` gets `PetSchemaType`.
|
|
8
|
+
|
|
9
|
+
::code-group
|
|
10
|
+
|
|
11
|
+
```typescript [kubb.config.ts]
|
|
12
|
+
import { pluginValibot } from '@kubb/plugin-valibot'
|
|
13
|
+
|
|
14
|
+
pluginValibot({ inferred: true })
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```typescript [src/gen/valibot/petSchema.ts]
|
|
18
|
+
export const petSchema = v.object({
|
|
19
|
+
id: v.pipe(v.number(), v.integer()),
|
|
20
|
+
name: v.string(),
|
|
21
|
+
})
|
|
22
|
+
|
|
23
|
+
export type PetSchemaType = v.InferOutput<typeof petSchema>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
::
|
|
27
|
+
|
|
28
|
+
To rename the types, see [Prefix inferred types](https://kubb.dev/extensions/kubb-labs/plugin-valibot/guides/customization#prefix-inferred-types).
|
|
29
|
+
|
|
30
|
+
## Input and output types
|
|
31
|
+
|
|
32
|
+
Kubb writes `v.InferInput<typeof schema>` for request schemas (bodies and params) and `v.InferOutput<typeof schema>` for every other schema.
|
|
33
|
+
|
|
34
|
+
- A request takes the value the caller passes, such as a `Date`, which the schema encodes.
|
|
35
|
+
- A response returns the converted value.
|
|
36
|
+
- The two differ only for a schema that converts, such as a `Date` field or a default.
|
|
37
|
+
|
|
38
|
+
When a schema prints differently per direction, Kubb also writes an `${name}InputSchema`, which request bodies use, also through a `$ref`. Its type gets the `InputSchemaType` suffix:
|
|
39
|
+
|
|
40
|
+
```typescript [src/gen/valibot/slotSchema.ts]
|
|
41
|
+
export type SlotSchemaType = v.InferOutput<typeof slotSchema>
|
|
42
|
+
|
|
43
|
+
export type SlotInputSchemaType = v.InferInput<typeof slotInputSchema>
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
See [Encode custom types](https://kubb.dev/extensions/kubb-labs/plugin-valibot/guides/customization#encode-custom-types) for a full example.
|
|
47
|
+
|
|
48
|
+
## Options and responses per operation
|
|
49
|
+
|
|
50
|
+
`inferred` also writes two schemas for each operation, with their types: an `OptionsSchema` that combines `body`, `path`, `query`, and `headers`, and a `ResponsesSchema` with one schema per status code.
|
|
51
|
+
|
|
52
|
+
```typescript [src/gen/valibot/listPetsSchema.ts]
|
|
53
|
+
export const listPetsResponsesSchema = v.object({
|
|
54
|
+
'200': listPetsStatus200Schema,
|
|
55
|
+
})
|
|
56
|
+
|
|
57
|
+
export type ListPetsResponsesSchemaType = v.InferOutput<typeof listPetsResponsesSchema>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Circular schemas
|
|
61
|
+
|
|
62
|
+
A schema that is part of a circular reference is annotated as `v.GenericSchema`, so its inferred type is `unknown`. Add `@kubb/plugin-ts` when you need the types of those schemas.
|
|
63
|
+
|
|
64
|
+
## Type guards
|
|
65
|
+
|
|
66
|
+
With [`typeGuards`](https://kubb.dev/extensions/kubb-labs/plugin-valibot/options#typeguards), each component schema gets an `is*` guard and an `assert*` function. Both narrow to `v.InferInput`, the value the schema accepts before it converts anything.
|
|
67
|
+
|
|
68
|
+
```typescript [src/gen/valibot/petSchema.ts]
|
|
69
|
+
export const isPet = (data: unknown): data is v.InferInput<typeof petSchema> => v.is(petSchema, data)
|
|
70
|
+
```
|
package/docs/options.md
ADDED
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# Options
|
|
2
|
+
|
|
3
|
+
Pass these options to `pluginValibot()`. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options).
|
|
4
|
+
|
|
5
|
+
## Options overview
|
|
6
|
+
|
|
7
|
+
| Option | Purpose | Default |
|
|
8
|
+
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------ |
|
|
9
|
+
| [`output`](https://kubb.dev/docs/5.x/reference/plugin-options#output) | Where files are written. | `{ path: 'valibot', barrel: { type: 'named' } }` |
|
|
10
|
+
| [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group) | Split output by tag or path. | None |
|
|
11
|
+
| [`importPath`](#importpath) | Module the generated files import `v` from. | `'valibot'` |
|
|
12
|
+
| [`inferred`](#inferred) | Export a type next to each schema. | `false` |
|
|
13
|
+
| [`coercion`](#coercion) | Convert input before validation. | `false` |
|
|
14
|
+
| [`coercion.strings`](#coercion) | Convert a `string` with `v.toString()`. | `false` |
|
|
15
|
+
| [`coercion.numbers`](#coercion) | Convert a `number` and an `integer` with `v.toNumber()`. | `false` |
|
|
16
|
+
| [`coercion.dates`](#coercion) | Convert a `Date` field of a response with `v.toDate()`. | `false` |
|
|
17
|
+
| [`typeGuards`](#typeguards) | Generate `is*` type guards and `assert*` assertions. | `false` |
|
|
18
|
+
| [`typeGuards.is`](#typeguards) | Generate the `is*` type guard. | `true` |
|
|
19
|
+
| [`typeGuards.assert`](#typeguards) | Generate the `assert*` function. | `true` |
|
|
20
|
+
| [`regexType`](#regextype) | How an OpenAPI `pattern` is written. | `'literal'` |
|
|
21
|
+
| [`oneOfType`](#oneoftype) | How a `oneOf` without a discriminator is validated. | `'union'` |
|
|
22
|
+
| [`printer`](#printer) | Replace the handler for a schema type. | None |
|
|
23
|
+
| [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include) | Keep only operations and schemas that match. | None |
|
|
24
|
+
| [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude) | Skip operations and schemas that match. | `[]` |
|
|
25
|
+
| [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) | Apply different options per pattern. | `[]` |
|
|
26
|
+
| [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver) | Customize generated names and file paths. See [resolver members](#resolver-members). | `resolverValibot` |
|
|
27
|
+
| [`macros`](https://kubb.dev/docs/5.x/reference/plugin-options#macros) | Rewrite AST nodes before printing. | `[]` |
|
|
28
|
+
|
|
29
|
+
## Option details
|
|
30
|
+
|
|
31
|
+
### importPath
|
|
32
|
+
|
|
33
|
+
Module the generated files import `v` from, such as your own module that re-exports Valibot.
|
|
34
|
+
|
|
35
|
+
| | |
|
|
36
|
+
| -------- | ----------- |
|
|
37
|
+
| Type | `string` |
|
|
38
|
+
| Required | `false` |
|
|
39
|
+
| Default | `'valibot'` |
|
|
40
|
+
|
|
41
|
+
The module is imported as `import * as v`, so it must export every Valibot function the schemas call.
|
|
42
|
+
|
|
43
|
+
### inferred
|
|
44
|
+
|
|
45
|
+
Exports a type next to each schema, so you do not need `@kubb/plugin-ts`.
|
|
46
|
+
|
|
47
|
+
| | |
|
|
48
|
+
| -------- | --------- |
|
|
49
|
+
| Type | `boolean` |
|
|
50
|
+
| Required | `false` |
|
|
51
|
+
| Default | `false` |
|
|
52
|
+
|
|
53
|
+
```typescript [petSchema.ts]
|
|
54
|
+
export type PetSchemaType = v.InferOutput<typeof petSchema>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
A request schema, such as a request body or a query schema, gets `v.InferInput`, which is the value the caller passes. Every other schema gets `v.InferOutput`. The two differ for a schema that converts, such as a `Date` field or a default.
|
|
58
|
+
|
|
59
|
+
A schema that is part of a circular reference is annotated as `v.GenericSchema`, so its inferred type is `unknown`. Add `@kubb/plugin-ts` when you need the types of those schemas.
|
|
60
|
+
|
|
61
|
+
### coercion
|
|
62
|
+
|
|
63
|
+
Converts input before validation, so a query string such as `'5'` passes an integer schema.
|
|
64
|
+
|
|
65
|
+
| | |
|
|
66
|
+
| -------- | ---------------------------------------------------------------------- |
|
|
67
|
+
| Type | `boolean \| { dates?: boolean; strings?: boolean; numbers?: boolean }` |
|
|
68
|
+
| Required | `false` |
|
|
69
|
+
| Default | `false` |
|
|
70
|
+
|
|
71
|
+
::field-group
|
|
72
|
+
|
|
73
|
+
:::field{name="strings"}
|
|
74
|
+
Writes `v.pipe(v.unknown(), v.toString())` for a `string`.
|
|
75
|
+
:::
|
|
76
|
+
|
|
77
|
+
:::field{name="numbers"}
|
|
78
|
+
Writes `v.pipe(v.unknown(), v.toNumber())` for a `number` and an `integer`.
|
|
79
|
+
:::
|
|
80
|
+
|
|
81
|
+
:::field{name="dates"}
|
|
82
|
+
Writes `v.pipe(v.unknown(), v.toDate())` for a response field that is a `Date`. This needs `dateType: 'date'` on the adapter.
|
|
83
|
+
:::
|
|
84
|
+
|
|
85
|
+
::
|
|
86
|
+
|
|
87
|
+
`true` turns on all three. An `integer` with `format: int64` converts with or without this option, because JSON holds a number or a string.
|
|
88
|
+
|
|
89
|
+
### typeGuards
|
|
90
|
+
|
|
91
|
+
Generates an `is*` type guard and an `assert*` function for every component schema.
|
|
92
|
+
|
|
93
|
+
| | |
|
|
94
|
+
| -------- | ----------------------------------------------- |
|
|
95
|
+
| Type | `boolean \| { is?: boolean; assert?: boolean }` |
|
|
96
|
+
| Required | `false` |
|
|
97
|
+
| Default | `false` |
|
|
98
|
+
|
|
99
|
+
```typescript [petSchema.ts]
|
|
100
|
+
export const isPet = (data: unknown): data is v.InferInput<typeof petSchema> => v.is(petSchema, data)
|
|
101
|
+
|
|
102
|
+
export function assertPet(data: unknown): asserts data is v.InferInput<typeof petSchema> {
|
|
103
|
+
v.assert(petSchema, data)
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Both narrow to `v.InferInput`, the value the schema accepts before it converts anything.
|
|
108
|
+
|
|
109
|
+
### regexType
|
|
110
|
+
|
|
111
|
+
How an OpenAPI `pattern` is written inside `v.regex(...)`. Use `'constructor'` when a regex literal breaks your build or you need a string pattern.
|
|
112
|
+
|
|
113
|
+
| | |
|
|
114
|
+
| -------- | ---------------------------- |
|
|
115
|
+
| Type | `'literal' \| 'constructor'` |
|
|
116
|
+
| Required | `false` |
|
|
117
|
+
| Default | `'literal'` |
|
|
118
|
+
|
|
119
|
+
::field-group
|
|
120
|
+
|
|
121
|
+
:::field{name="'literal'"}
|
|
122
|
+
Writes `v.regex(/^[a-z]+$/)`.
|
|
123
|
+
:::
|
|
124
|
+
|
|
125
|
+
:::field{name="'constructor'"}
|
|
126
|
+
Writes `v.regex(new RegExp("^[a-z]+$"))`.
|
|
127
|
+
:::
|
|
128
|
+
|
|
129
|
+
::
|
|
130
|
+
|
|
131
|
+
### oneOfType
|
|
132
|
+
|
|
133
|
+
How a `oneOf` without a discriminator is validated. Use `'xor'` when values may carry extra keys.
|
|
134
|
+
|
|
135
|
+
| | |
|
|
136
|
+
| -------- | ------------------ |
|
|
137
|
+
| Type | `'union' \| 'xor'` |
|
|
138
|
+
| Required | `false` |
|
|
139
|
+
| Default | `'union'` |
|
|
140
|
+
|
|
141
|
+
::field-group
|
|
142
|
+
|
|
143
|
+
:::field{name="'union'"}
|
|
144
|
+
Writes `v.union([...])` with strict object members, so extra keys fail, even keys the spec allows.
|
|
145
|
+
:::
|
|
146
|
+
|
|
147
|
+
:::field{name="'xor'"}
|
|
148
|
+
Writes `v.union([...])` behind a `v.check` that passes only when exactly one member matches.
|
|
149
|
+
:::
|
|
150
|
+
|
|
151
|
+
::
|
|
152
|
+
|
|
153
|
+
### printer
|
|
154
|
+
|
|
155
|
+
Replaces the handler for a schema type such as `'date'`. Each handler returns the Valibot expression as a string. `this.base(node)` returns the built-in output, and `this.transform(node)` recurses into nested nodes. See the [printer guide](https://kubb.dev/docs/5.x/how-to/customize#printers).
|
|
156
|
+
|
|
157
|
+
| | |
|
|
158
|
+
| -------- | --------------------------------- |
|
|
159
|
+
| Type | `{ nodes?: PrinterValibotNodes }` |
|
|
160
|
+
| Required | `false` |
|
|
161
|
+
|
|
162
|
+
```typescript [kubb.config.ts]
|
|
163
|
+
import { pluginValibot } from '@kubb/plugin-valibot'
|
|
164
|
+
|
|
165
|
+
pluginValibot({
|
|
166
|
+
printer: {
|
|
167
|
+
nodes: {
|
|
168
|
+
date() {
|
|
169
|
+
return 'v.pipe(v.string(), v.isoDate(), v.transform((value) => new Date(value)))'
|
|
170
|
+
},
|
|
171
|
+
},
|
|
172
|
+
},
|
|
173
|
+
})
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Resolver members
|
|
177
|
+
|
|
178
|
+
Besides the shared members of [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver), `resolverValibot` has these. Members you leave out keep the default.
|
|
179
|
+
|
|
180
|
+
::code-collapse{name="ResolverValibot patch members"}
|
|
181
|
+
|
|
182
|
+
```typescript [Partial override]
|
|
183
|
+
type ResolverValibotPatch = {
|
|
184
|
+
schema?: {
|
|
185
|
+
typeName?(name: string): string
|
|
186
|
+
type?(name: string): string
|
|
187
|
+
inputName?(name: string): string
|
|
188
|
+
inputTypeName?(name: string): string
|
|
189
|
+
isName?(name: string): string
|
|
190
|
+
assertName?(name: string): string
|
|
191
|
+
}
|
|
192
|
+
param?: {
|
|
193
|
+
name?(node: OperationNode, param: ParameterNode): string
|
|
194
|
+
path?(node: OperationNode, param: ParameterNode): string
|
|
195
|
+
query?(node: OperationNode, param: ParameterNode): string
|
|
196
|
+
headers?(node: OperationNode, param: ParameterNode): string
|
|
197
|
+
cookies?(node: OperationNode, param: ParameterNode): string
|
|
198
|
+
}
|
|
199
|
+
response?: {
|
|
200
|
+
status?(node: OperationNode, statusCode: StatusCode): string
|
|
201
|
+
headers?(node: OperationNode, statusCode: StatusCode): string
|
|
202
|
+
body?(node: OperationNode): string
|
|
203
|
+
responses?(node: OperationNode): string
|
|
204
|
+
response?(node: OperationNode): string
|
|
205
|
+
error?(node: OperationNode): string
|
|
206
|
+
options?(node: OperationNode): string
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
::
|
|
212
|
+
|
|
213
|
+
## Format and type mappings
|
|
214
|
+
|
|
215
|
+
Kubb maps each OpenAPI format to its Valibot call, such as `format: email` to `v.pipe(v.string(), v.email())`. See [Valibot schemas for OpenAPI formats](https://kubb.dev/extensions/kubb-labs/plugin-valibot/guides/format-mappings).
|
package/docs/overview.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Valibot
|
|
2
|
+
|
|
3
|
+
The Valibot plugin generates a Valibot v1 schema for every schema in your OpenAPI spec, plus the parameter, request, and response schemas of each operation.
|
|
4
|
+
|
|
5
|
+
Every generated schema is a [Standard Schema](https://standardschema.dev), so any library that takes one can validate with it.
|
|
6
|
+
|
|
7
|
+
`@kubb/plugin-fetch`, `@kubb/plugin-axios`, and `@kubb/plugin-client` validate with these schemas when you set their `validator` option to `'valibot'`.
|
|
8
|
+
|
|
9
|
+
## Setup
|
|
10
|
+
|
|
11
|
+
- No other plugins are needed.
|
|
12
|
+
- Install `valibot` 1.2 or later in the app that uses the generated code.
|
|
13
|
+
|
|
14
|
+
## Options worth knowing
|
|
15
|
+
|
|
16
|
+
| Option | Default | What it does |
|
|
17
|
+
| --------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------- |
|
|
18
|
+
| [`inferred`](https://kubb.dev/extensions/kubb-labs/plugin-valibot/options#inferred) | `false` | Adds a type next to each schema, so you can skip `@kubb/plugin-ts`. |
|
|
19
|
+
| [`coercion`](https://kubb.dev/extensions/kubb-labs/plugin-valibot/options#coercion) | `false` | Converts input before validation, such as query strings. |
|
|
20
|
+
| [`typeGuards`](https://kubb.dev/extensions/kubb-labs/plugin-valibot/options#typeguards) | `false` | Adds `is*` type guards and `assert*` assertions. |
|
|
21
|
+
| [`printer`](https://kubb.dev/extensions/kubb-labs/plugin-valibot/options#printer) | None | Replaces the Valibot call for a schema type. |
|
|
22
|
+
|
|
23
|
+
## Example
|
|
24
|
+
|
|
25
|
+
This config generates the schemas with a `v.InferOutput` type next to each one. For a `Pet` schema, the plugin writes `petSchema.ts`:
|
|
26
|
+
|
|
27
|
+
::code-group
|
|
28
|
+
|
|
29
|
+
```typescript [kubb.config.ts]
|
|
30
|
+
import { defineConfig } from 'kubb/config'
|
|
31
|
+
import { pluginValibot } from '@kubb/plugin-valibot'
|
|
32
|
+
|
|
33
|
+
export default defineConfig({
|
|
34
|
+
input: './petStore.yaml',
|
|
35
|
+
output: { path: './src/gen' },
|
|
36
|
+
plugins: [pluginValibot({ inferred: true })],
|
|
37
|
+
})
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```typescript [src/gen/valibot/petSchema.ts]
|
|
41
|
+
import * as v from 'valibot'
|
|
42
|
+
|
|
43
|
+
export const petSchema = v.object({
|
|
44
|
+
id: v.pipe(v.number(), v.integer()),
|
|
45
|
+
name: v.string(),
|
|
46
|
+
status: v.optional(v.string()),
|
|
47
|
+
tags: v.optional(v.array(v.string())),
|
|
48
|
+
})
|
|
49
|
+
|
|
50
|
+
export type PetSchemaType = v.InferOutput<typeof petSchema>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
::
|
|
54
|
+
|
|
55
|
+
## Guides
|
|
56
|
+
|
|
57
|
+
- [Valibot schemas for OpenAPI formats](https://kubb.dev/extensions/kubb-labs/plugin-valibot/guides/format-mappings)
|
|
58
|
+
- [Infer TypeScript types from Valibot schemas](https://kubb.dev/extensions/kubb-labs/plugin-valibot/guides/inferred-types)
|
|
59
|
+
- [Coerce input with Valibot](https://kubb.dev/extensions/kubb-labs/plugin-valibot/guides/coercion)
|
|
60
|
+
- [Customize generated schemas](https://kubb.dev/extensions/kubb-labs/plugin-valibot/guides/customization)
|
|
61
|
+
|
|
62
|
+
## Differences from the Zod plugin
|
|
63
|
+
|
|
64
|
+
The two plugins share option names, generated names, and file layout. These Zod options have no Valibot counterpart:
|
|
65
|
+
|
|
66
|
+
| Zod option | In this plugin |
|
|
67
|
+
| -------------------- | --------------------------------------------------------------------------------------- |
|
|
68
|
+
| `guidType` | Not needed. `v.uuid()` checks the shape only, so it already accepts any GUID. |
|
|
69
|
+
| `inferred: 'codec'` | Always on. A request schema gets `v.InferInput` and every other schema `v.InferOutput`. |
|
|
70
|
+
| `compile` and `mini` | Zod features. Valibot is modular by default. |
|