You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For 3 years, Elysia use TypeBox as the only validator, and it is one of the most loved feature of Elysia due to its performance, and type inference.
52
51
53
-
But one of the most requested feature from our community is to support more validator other than TypeBox since the very early day ([elysia#20](https://github.com/elysiajs/elysia/issues/20)).
52
+
For 3 years, Elysia used TypeBox as the only validator. It became one of Elysia's most loved features due to its performance and type inference.
54
53
55
-
As Elysia is deeply tied with TypeBox, it required a lot of effort to add support for each validators individually, and a lot of maintenance to keep up with the changes of each one.
54
+
However, one of the most requested features from our community since the very beginning ([elysia#20](https://github.com/elysiajs/elysia/issues/20)) was to support validators other than TypeBox.
56
55
57
-
Luckily, there is a new proposal called [Standard Schema](https://github.com/standard-schema/standard-schema) to define a standard way to use a different schema with the same API allowing us to support multiple validators without having to write custom integration for each of them.
56
+
Because Elysia was deeply tied to TypeBox, adding support for each validator individually required a lot of effort and ongoing maintenance to keep up with changes.
57
+
58
+
Fortunately, a new proposal called [Standard Schema](https://github.com/standard-schema/standard-schema) defines a standard way to use different schemas with the same API. This allowed us to support multiple validators without writing custom integrations for each one.
59
+
60
+
Elysia now supports Standard Schema, allowing you to use your favorite validators like:
58
61
59
-
Elysia now support Standard Schema, allowing you to use your favorite validators like:
60
62
- Zod
61
63
- Valibot
62
64
- Effect Schema
63
65
- ArkType
64
66
- Joi
65
67
- and more!
66
68
67
-
You can provide the schema similar to TypeBox, and it will just work out of the box:
69
+
You can provide the schema in a way similar to TypeBox, and it will just work out of the box:
70
+
68
71
```ts twoslash
69
72
import { Elysia, t } from'elysia'
70
73
import { z } from'zod'
@@ -95,31 +98,33 @@ const app = new Elysia()
95
98
})
96
99
```
97
100
98
-
You can use multiple validators in a single route, and it will work together seamlessly, and it will have a correct type inference as well.
101
+
You can use multiple validators in a single route, and they will work together seamlessly with correct type inference.
99
102
100
103
### OpenAPI
101
-
There is a request to support JSON Schema for OpenAPI generation for Standard Schema but it is not implemented yet.
102
104
103
-
However, we use [xsschema](https://xsai.js.org/docs/packages-top/xsschema) internally as a workaround to convert Standard Schema to JSON Schema for OpenAPI generation (if the validation library support it).
105
+
There is a request to support JSON Schema for OpenAPI generation with Standard Schema, but it is not implemented yet.
104
106
105
-
Allowing you to have a beautiful OpenAPI documentation with your favorite validator.
107
+
However, we use [xsschema](https://xsai.js.org/docs/packages-top/xsschema) internally as a workaround to convert Standard Schema to JSON Schema for OpenAPI generation (if the validation library supports it).
108
+
109
+
This allows you to have beautiful OpenAPI documentation with your favorite validator.
106
110
107
111
108
112
> Using Zod native OpenAPI schema support with **describe** to add description to the schema
109
113
110
114
But if your validator does not support JSON Schema, we provide our unique [OpenAPI type gen](/blog/openapi-type-gen.html) to generate OpenAPI schema directly from TypeScript type from your validator.
111
115
112
-
This means that Elysia support OpenAPI generation for all validators that support Standard Schema even if it doesn't directly support JSON Schema.
116
+
This means that Elysia supports OpenAPI generation for all validators that support Standard Schema, even if they don't directly support JSON Schema.
113
117
114
118
115
119
> Valibot doesn't directly support JSON Schema, but we OpenAPI type gen to handle it
116
120
117
-
Not only that it will input type correctly, but OpenAPI type gen will also generate all possible output type as well, including error response.
121
+
Not only will it generate the correct input type, but OpenAPI type gen will also generate all possible output types, including error responses.
118
122
119
-
This is truly a unique feature for Elysia, that we are truly proud to offer.
123
+
This is truly a unique feature for Elysia, and we are very proud to offer it.
120
124
121
125
### Standalone Validator
122
-
You can also use multiple schema to validate a single input using standalone validator:
126
+
127
+
You can also use multiple schemas to validate a single input using a standalone validator:
123
128
124
129
```ts twoslash
125
130
import { Elysia, t } from'elysia'
@@ -140,133 +145,141 @@ const app = new Elysia()
140
145
141
146
142
147
148
+
143
149
{
144
150
body: v.object({
145
151
name: v.literal('lilith')
146
152
})
147
153
})
148
154
```
149
-
> This example use both Zod, and Valibot to validate the body. Allowing you to use already existing schema in your codebase from a different validator together.
155
+
> This example uses both Zod and Valibot to validate the body, allowing you to use existing schemas in your codebase from different validators together.
150
156
151
-
This works using each validator to parse a part of an input, then store each result as a snapshot that merge together to form a single output to ensure type integrity.
157
+
This works by using each validator to parse a part of the input, then storing each result as a snapshot that merges together to form a single output, ensuring type integrity.
152
158
153
159
154
-
> Using TypeBox, Zod, Valibot, Joi, Yup, ArkType, Effect Schema, TypeMap, Rescript Schema to validate different part of the body
160
+
> Using TypeBox, Zod, Valibot, Joi, Yup, ArkType, Effect Schema, TypeMap, and Rescript Schema to validate different parts of the body
155
161
156
-
We test 8 validators at the same time, validating each part of the input, and it just works flawlessly.
162
+
We tested 8 validators at the same time, validating each part of the input, and it just works flawlessly.
157
163
158
-
We are proud to support Standard Schema out of the box, it is a big step for Elysia to not be tied to a single validator, and we are excited to see what you will build with it.
164
+
We are proud to support Standard Schema out of the box. This is a big step for Elysia to not be tied to a single validator, and we are excited to see what you will build with it.
159
165
160
166
## Macro
161
-
Macro is one of the most powerful, and flexible feature of Elysia.
162
167
163
-
Allowing you to a define custom property that can modify, and extend the functionality of Elysia allowing you to create your own "sub framework" to your liking.
168
+
Macro is one of the most powerful and flexible features of Elysia.
169
+
170
+
It allows you to define custom properties that can modify and extend the functionality of Elysia, enabling you to create your own "sub-framework" to your liking.
164
171
165
-
The versatility of Macro is truly amazing, allowing you to do things that are hardly possible with other frameworks effortlessly.
172
+
The versatility of Macro is truly amazing, letting you do things that are nearly impossible with other frameworks, effortlessly.
166
173
167
-
And with Elysia 1.4, we bring several improvement to make macro even more versatile.
174
+
With Elysia 1.4, we bring several improvements to make macros even more versatile.
168
175
169
176
### Macro Schema
170
-
You can now define a schema for your macro, allowing you to define custom validation directly from your macro.
177
+
178
+
You can now define a schema for your macro, allowing you to add custom validation directly from your macro.
171
179
172
180
173
181
> Macro with schema support
174
182
175
-
Macro with schema will automatically validate and infer type to ensure type safety, and it can co-exist with existing schema as well.
183
+
Macro with schema will automatically validate and infer types to ensure type safety, and it can coexist with existing schemas as well.
176
184
177
-
You can also stack multiple schema from different macro, or even from Standard Validator and it will work together seamlessly.
185
+
You can also stack multiple schemas from different macros, or even from Standard Validator, and they will work together seamlessly.
178
186
179
-
Macro schema also support type inference for **lifecycle within the same macro****BUT** only with named single macro due to TypeScript limitation.
187
+
Macro schema also supports type inference for **lifecycle within the same macro****BUT** only with a named single macro due to a TypeScript limitation.
180
188
181
189
182
190
> Using a named single macro to infer type into lifecycle within the same macro
183
191
184
-
If you want to use lifecycle type inference within the same macro, you might want to use a named single macro instead of multiple stacked macro
192
+
If you want to use lifecycle type inference within the same macro, you should use a named single macro instead of multiple stacked macros.
185
193
186
-
> Not to confused with using macro schema to infer type into route's lifecycle event. That works just finethis limitation only apply to using lifecycle within the same macro.
194
+
> Not to be confused with using macro schema to infer types into a route's lifecycle event. That works just fine—this limitation only applies to using lifecycle within the same macro.
187
195
188
196
### Macro Extension
189
-
You can now extend existing macro, allowing you to build upon existing functionality.
197
+
198
+
You can now extend existing macros, allowing you to build upon existing functionality.
190
199
191
200
192
201
> Macro with extension support
193
202
194
-
This allow you to build upon existing macro, and add more functionality to it.
203
+
This allows you to build upon existing macros and add more functionality to them.
195
204
196
-
It also works recursively with automatic deduplication, allowing you to extends existing macro that already extends another macro without any issue.
205
+
It also works recursively with automatic deduplication, allowing you to extend existing macros that already extend other macros without any issues.
197
206
198
-
However, if you evert accidentally create a circular dependency, Elysia have a limit stack of 16 to prevent infinite loop in both runtime and type inference.
207
+
However, if you ever accidentally create a circular dependency, Elysia has a stack limit of 16 to prevent infinite loops in both runtime and type inference.
199
208
200
209
### Macro Detail
210
+
201
211
You can now define OpenAPI detail for your macro, allowing you to add more detail to your OpenAPI documentation directly from your macro.
202
212
203
213
If the route already has OpenAPI detail, it will merge the detail together but prefers the route detail over macro detail.
204
214
205
215
## Lifecycle Type Soundness
206
-
Since the introduction of [OpenAPI Type Gen](/blog/openapi-type-gen) which generate OpenAPI schema directly from type, we found that it would be great to have a type soundness for every lifecycle event.
207
216
208
-
That way we can accurately document the return type for each lifecycle event, and macro to accurately represent all of the possibility of what a single route can return.
217
+
Since the introduction of [OpenAPI Type Gen](/blog/openapi-type-gen), which generates OpenAPI schema directly from types, we realized it would be great to have type soundness for every lifecycle event.
209
218
210
-
By refactoring over 3,000+ lines of pure type, response status type reconcilation, including unit tests in type-level for all lifecycle API to ensure type integrity, and a lot of type performance optimization to make sure that type inference doesn't get slower.
219
+
This way, we can accurately document the return type for each lifecycle event and macro, representing all the possibilities of what a single route can return.
211
220
212
-
All of these complex acheivement allow us to create document all of possibility of what a single route can return.
221
+
By refactoring over 3,000+ lines of pure types, reconciling response status types, including unit tests at the type level for all lifecycle APIs to ensure type integrity, and optimizing type performance, we made sure that type inference doesn't get slower.
> Documenting all the possibilities of what a single route can return
217
227
218
-
Not only this improve the developer experience, but it also improve the reliability of your codebase by ensuring that all of the possibility are accounted for both in the API documentation, and client with Eden Treaty.
228
+
Not only does this improve the developer experience, but it also improves the reliability of your codebase by ensuring that all possibilities are accounted for in both the API documentation and the client with Eden Treaty.
219
229
220
-
> Type Soundness covers all lifecycle event, and macro, allowing you to have a complete documentation of your API. The only exception is an inline lifecycle event due to slowness.
230
+
> Type Soundness covers all lifecycle events and macros, allowing you to have complete documentation of your API. The only exception is an inline lifecycle event due to slowness.
221
231
222
-
We also managed to improve type inference performance by ~9-11%, and decrease type instantiation by 11.5% despite the massive increase in type complexity.
232
+
We also managed to improve type inference performance by a factor of ~9-11% and decrease type instantiation by 11.5%, despite the massive increase in type complexity.
> Type instantiation is reduced by 11.57% from our internal benchmark
226
236
227
237
## Group standalone schema
228
-
Previously `group` with schema will use an overwrite strategy, meaning that if you define a schema in `group` it will overwrite the existing schema in the route.
229
238
230
-
If you want to define a new schema, you have to include the existing schema manually. This is not very ergonomic, and it can lead to errors if you forget to include the existing schema.
239
+
Previously, `group` with schema used an overwrite strategy, meaning that if you defined a schema in `group`, it would overwrite the existing schema in the route.
240
+
241
+
If you wanted to define a new schema, you had to include the existing schema manually. This was not very ergonomic, and it could lead to errors if you forgot to include the existing schema.
231
242
232
-
Starting from 1.4, `group` with schema will use a standalone strategy, meaning that if you define a schema in `group` it will not overwrite but co-exists the route schema.
243
+
Starting from 1.4, `group` with schema uses a standalone strategy, meaning that if you define a schema in `group`, it will not overwrite but will coexist with the route schema.
> `group` with schema will co-exists with route schema
246
+
> `group` with schema will coexist with route schema
236
247
237
-
This allow you to define a new schema in `group` without having to include the existing schema manually.
248
+
This allows you to define a new schema in `group` without having to include the existing schema manually.
238
249
239
250
## Notable changes
240
-
We have closed around 300 issues on 1.3.9 so we don't really have much bug fixes to make for 1.4 as solved most of the problems we know.
241
251
242
-
### Improvement
252
+
We have closed around 300 issues on 1.3.9, so we don't really have many bug fixes to make for 1.4, as we have solved most of the problems we know.
253
+
254
+
### Improvements
255
+
243
256
-[#861](https://github.com/elysiajs/elysia/issues/861) automatically add HEAD method when defining GET route
244
-
-[#1389](https://github.com/elysiajs/elysia/pull/1389) NoValidate in refernce model
257
+
-[#1389](https://github.com/elysiajs/elysia/pull/1389) NoValidate in reference model
245
258
246
-
### Change
247
-
- ObjectString/ArrayString no longer produce default value by default due to security reasons
248
-
- Cookie now dynamically parse when format is likely JSON
259
+
### Changes
260
+
261
+
- ObjectString/ArrayString no longer produces default values by default due to security reasons
262
+
- Cookie now dynamically parses when format is likely JSON
249
263
- export `fileType` for external file type validation for accurate response
250
-
- ObjectString/ArrayString no longer produce default value by default due to security reasons
251
-
- Cookie now dynamically parse when format is likely JSON
252
264
253
-
### Breaking Change
254
-
- remove macro v1 due to non type soundness
255
-
- remove `error` function, use `status` instead
256
-
- deprecation notice for `response` in `mapResponse`, `afterResponse`, use `responseValue` instead
265
+
### Breaking Changes
266
+
267
+
- remove macro v1 due to lack of type soundness
268
+
- remove `error` function; use `status` instead
269
+
- deprecation notice for `response` in `mapResponse`, `afterResponse`; use `responseValue` instead
257
270
258
271
## Afterword
259
272
260
-
This is the first time that we featured our mascot, Elysia chan as part of release note cover image! This will become a tradition for later release notes as well!
273
+
This is the first time we have featured our mascot, Elysia chan, as part of the release note cover image! This will become a tradition for future release notes as well!
261
274
262
-
Our cover art mirror the theme with Supersymmetry (music) cover art where ElysiaJS chan is mirroring Weirs with a similar pose
275
+
Our cover art mirrors the theme of the Supersymmetry (music) cover art, where ElysiaJS chan is mirroring Weirs with a similar pose.
0 commit comments