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
Copy file name to clipboardExpand all lines: docs/blog/elysia-14.md
+91-77Lines changed: 91 additions & 77 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,11 +11,11 @@ head:
11
11
12
12
- - meta
13
13
- name: 'description'
14
-
content: Support for Standard Validator. Macro with schema, extension, and OpenAPI detail. Lifecycle type soundness. Improve type inference performance by 10%.
14
+
content: Support for Standard Schema. Macro with schema, extension, and OpenAPI detail. Lifecycle type soundness. Improves type inference performance by 10%.
15
15
16
16
- - meta
17
17
- property: 'og:description'
18
-
content: Support for Standard Validator. Macro with schema, extension, and OpenAPI detail. Lifecycle type soundness. Improve type inference performance by 10%.
18
+
content: Support for Standard Schema. Macro with schema, extension, and OpenAPI detail. Lifecycle type soundness. Improves type inference performance by 10%.
19
19
20
20
- - meta
21
21
- property: 'og:image'
@@ -41,31 +41,34 @@ head:
41
41
42
42
Named after the song [Supersymmetry](https://youtu.be/NYyjQjtbteA) by Sta, a Tone Sphere ending theme.
43
43
44
-
Elysia 1.4 highlight is on Standard Schema, and **"Type Soundness"**.
44
+
The highlight of Elysia 1.4 is the introduction of Standard Schema and **"Type Soundness"**.
45
45
46
46
-[Standard Schema](#standard-schema)
47
47
-[Macro](#macro)
48
48
-[Lifecycle Type Soundness](#lifecycle-type-soundness)
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.
53
52
54
-
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)).
53
+
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.
55
54
56
-
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.
55
+
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.
57
56
58
-
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.
57
+
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.
58
+
59
+
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.
60
+
61
+
Elysia now supports Standard Schema, allowing you to use your favorite validators like:
59
62
60
-
Elysia now support Standard Schema, allowing you to use your favorite validators like:
61
63
- Zod
62
64
- Valibot
63
65
- Effect Schema
64
66
- ArkType
65
67
- Joi
66
68
- and more!
67
69
68
-
You can provide the schema similar to TypeBox, and it will just work out of the box:
70
+
You can provide the schema in a way similar to TypeBox, and it will just work out of the box:
71
+
69
72
```ts twoslash
70
73
import { Elysia, t } from'elysia'
71
74
import { z } from'zod'
@@ -96,31 +99,33 @@ const app = new Elysia()
96
99
})
97
100
```
98
101
99
-
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.
102
+
You can use multiple validators in a single route, and they will work together seamlessly with correct type inference.
100
103
101
104
### OpenAPI
102
-
There is a request to support JSON Schema for OpenAPI generation for Standard Schema but it is not implemented yet.
105
+
106
+
There is a request to support JSON Schema for OpenAPI generation with Standard Schema, but it is not implemented yet.
103
107
104
108
However, we provide a custom `mapJsonSchema` to `openapi` allow you to provide a custom function to map schema to Json Schema as a workaround.
105
109
106
-
Allowing you to have a beautiful OpenAPI documentation with your favorite validator.
110
+
This allows you to have beautiful OpenAPI documentation with your favorite validator.
107
111
108
112
109
-
> Using Zod native OpenAPI schema support with **describe** to add description to the schema
113
+
> Using Zod's native OpenAPI schema support with **describe** to add description to the schema
110
114
111
-
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.
115
+
But if your validator does not support JSON Schema, we provide [OpenAPI type gen](/blog/openapi-type-gen.html) to generate OpenAPI schema directly from TypeScript type from your validator.
112
116
113
-
This means that Elysia support OpenAPI generation for all validators that support Standard Schema even if it doesn't directly support JSON Schema.
117
+
This means Elysia supports OpenAPI generation for all validators that support Standard Schema, even if they don't directly support JSON Schema.
114
118
115
119
116
-
> Valibot doesn't directly support JSON Schema, but we OpenAPI type gen to handle it
120
+
> Valibot doesn't directly support JSON Schema, but we use OpenAPI type gen to handle it
117
121
118
-
Not only that it will input type correctly, but OpenAPI type gen will also generate all possible output type as well, including error response.
122
+
Not only will it generate correct input type, but OpenAPI type gen will also generate all possible output types, including error responses.
119
123
120
-
This is truly a unique feature for Elysia, that we are truly proud to offer.
124
+
This is truly a unique feature for Elysia, and we are very proud to offer it.
121
125
122
126
### Standalone Validator
123
-
You can also use multiple schema to validate a single input using standalone validator:
127
+
128
+
You can also use multiple schemas to validate a single input using a standalone validator:
124
129
125
130
```ts twoslash
126
131
import { Elysia, t } from'elysia'
@@ -134,140 +139,149 @@ const app = new Elysia()
134
139
id: z.coerce.number()
135
140
})
136
141
})
137
-
.post(
138
-
'/user/:id',
139
-
({ body }) =>body,
142
+
.post(
143
+
'/user/:id',
144
+
({ body }) =>body,
140
145
// ^?
141
146
142
147
143
148
144
-
{
145
-
body: v.object({
146
-
name: v.literal('lilith')
147
-
})
148
-
})
149
+
150
+
{
151
+
body: v.object({
152
+
name: v.literal('lilith')
153
+
})
154
+
}
155
+
)
149
156
```
150
-
> 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.
157
+
> This example uses both Zod and Valibot to validate the body, allowing you to use existing schemas in your codebase from different validators together.
151
158
152
-
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.
159
+
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.
153
160
154
161
155
-
> Using TypeBox, Zod, Valibot, Joi, Yup, ArkType, Effect Schema, TypeMap, Rescript Schema to validate different part of the body
162
+
> Using TypeBox, Zod, Valibot, Joi, Yup, ArkType, Effect Schema, TypeMap, and ReScript Schema to validate different parts of the body
156
163
157
-
We test 8 validators at the same time, validating each part of the input, and it just works flawlessly.
164
+
We tested 8 validators at the same time, validating each part of the input, and it just works flawlessly.
158
165
159
-
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.
166
+
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.
160
167
161
168
## Macro
162
-
Macro is one of the most powerful, and flexible feature of Elysia.
163
169
164
-
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.
170
+
Macro is one of the most powerful and flexible features of Elysia.
171
+
172
+
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.
165
173
166
-
The versatility of Macro is truly amazing, allowing you to do things that are hardly possible with other frameworks effortlessly.
174
+
The versatility of Macro is truly amazing, letting you do things that are nearly impossible with other frameworks, effortlessly.
167
175
168
-
And with Elysia 1.4, we bring several improvement to make macro even more versatile.
176
+
With Elysia 1.4, we bring several improvements to make macros even more versatile.
169
177
170
178
### Macro Schema
171
-
You can now define a schema for your macro, allowing you to define custom validation directly from your macro.
179
+
180
+
You can now define a schema for your macro, allowing you to add custom validation directly from your macro.
172
181
173
182
174
183
> Macro with schema support
175
184
176
-
Macro with schema will automatically validate and infer type to ensure type safety, and it can co-exist with existing schema as well.
185
+
Macro with schema will automatically validate and infer types to ensure type safety, and it can coexist with existing schemas as well.
177
186
178
-
You can also stack multiple schema from different macro, or even from Standard Validator and it will work together seamlessly.
187
+
You can also stack multiple schemas from different macros, or even from Standard Schema, and they will work together seamlessly.
179
188
180
-
Macro schema also support type inference for **lifecycle within the same macro****BUT** only with named single macro due to TypeScript limitation.
189
+
Macro schema also supports type inference for **lifecycle within the same macro****BUT** only with a named single macro due to a TypeScript limitation.
181
190
182
191
183
192
> Using a named single macro to infer type into lifecycle within the same macro
184
193
185
-
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
194
+
If you want to use lifecycle type inference within the same macro, you should use a named single macro instead of multiple stacked macros.
186
195
187
-
> 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.
196
+
> 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.
188
197
189
198
### Macro Extension
190
-
You can now extend existing macro, allowing you to build upon existing functionality.
199
+
200
+
You can now extend existing macros, allowing you to build upon existing functionality.
191
201
192
202
193
203
> Macro with extension support
194
204
195
-
This allow you to build upon existing macro, and add more functionality to it.
205
+
This allows you to build upon existing macros and add more functionality to them.
196
206
197
-
It also works recursively with automatic deduplication, allowing you to extends existing macro that already extends another macro without any issue.
207
+
It also works recursively with automatic deduplication, allowing you to extend existing macros that already extend other macros without any issues.
198
208
199
-
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.
209
+
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.
200
210
201
211
### Macro Detail
212
+
202
213
You can now define OpenAPI detail for your macro, allowing you to add more detail to your OpenAPI documentation directly from your macro.
203
214
204
215
If the route already has OpenAPI detail, it will merge the detail together but prefers the route detail over macro detail.
205
216
206
217
## Lifecycle Type Soundness
207
-
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.
208
218
209
-
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.
219
+
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.
210
220
211
-
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.
221
+
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.
212
222
213
-
All of these complex acheivement allow us to create document all of possibility of what a single route can return.
223
+
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
218
229
219
-
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.
230
+
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.
220
231
221
-
> 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.
232
+
> Type Soundness covers all lifecycle events and macros, allowing you to have complete documentation of your API. The only exception is inline lifecycle events due to performance.
222
233
223
-
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.
234
+
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.
> Type instantiation is reduced by 11.57% from our internal benchmark
227
238
228
239
## Group standalone schema
229
-
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.
230
240
231
-
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.
241
+
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.
242
+
243
+
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.
232
244
233
-
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.
245
+
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
248
+
> `group` with schema will coexist with route schema
237
249
238
-
This allow you to define a new schema in `group` without having to include the existing schema manually.
250
+
This allows you to define a new schema in `group` without having to include the existing schema manually.
239
251
240
252
## Notable changes
241
-
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.
242
253
243
-
### Improvement
254
+
We closed around 300 issues in 1.3.9, so there aren’t many bug fixes in 1.4—we’ve addressed most known issues.
255
+
256
+
### Improvements
257
+
244
258
-[#861](https://github.com/elysiajs/elysia/issues/861) automatically add HEAD method when defining GET route
245
-
-[#1389](https://github.com/elysiajs/elysia/pull/1389) NoValidate in refernce model
259
+
-[#1389](https://github.com/elysiajs/elysia/pull/1389) NoValidate in reference model
260
+
261
+
### Changes
246
262
247
-
### Change
248
-
- ObjectString/ArrayString no longer produce default value by default due to security reasons
249
-
- Cookie now dynamically parse when format is likely JSON
263
+
- ObjectString/ArrayString no longer produce default values due to security reasons
264
+
- Cookie now dynamically parses when format is likely JSON
250
265
- export `fileType` for external file type validation for accurate response
251
-
- ObjectString/ArrayString no longer produce default value by default due to security reasons
252
-
- Cookie now dynamically parse when format is likely JSON
253
266
254
-
### Breaking Change
255
-
- remove macro v1 due to non type soundness
256
-
- remove `error` function, use `status` instead
257
-
- deprecation notice for `response` in `mapResponse`, `afterResponse`, use `responseValue` instead
267
+
### Breaking Changes
268
+
269
+
- remove macro v1 due to lack of type soundness
270
+
- remove `error` function; use `status` instead
271
+
- deprecation notice for `response` in `mapResponse`, `afterResponse`; use `responseValue` instead
258
272
259
273
## Afterword
260
274
261
-
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!
275
+
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!
262
276
263
-
Our cover art mirror the theme with Supersymmetry (music) cover art where ElysiaJS chan is mirroring Weirs with a similar pose
277
+
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