diff --git a/docs/blog/elysia-14.md b/docs/blog/elysia-14.md index dd32077a..6199cf83 100644 --- a/docs/blog/elysia-14.md +++ b/docs/blog/elysia-14.md @@ -11,11 +11,11 @@ head: - - meta - name: 'description' - content: Support for Standard Validator. Macro with schema, extension, and OpenAPI detail. Lifecycle type soundness. Improve type inference performance by 10%. + content: Support for Standard Schema. Macro with schema, extension, and OpenAPI detail. Lifecycle type soundness. Improves type inference performance by 10%. - - meta - property: 'og:description' - content: Support for Standard Validator. Macro with schema, extension, and OpenAPI detail. Lifecycle type soundness. Improve type inference performance by 10%. + content: Support for Standard Schema. Macro with schema, extension, and OpenAPI detail. Lifecycle type soundness. Improves type inference performance by 10%. - - meta - property: 'og:image' @@ -41,7 +41,7 @@ head: Named after the song [Supersymmetry](https://youtu.be/NYyjQjtbteA) by Sta, a Tone Sphere ending theme. -Elysia 1.4 highlight is on Standard Schema, and **"Type Soundness"**. +The highlight of Elysia 1.4 is the introduction of Standard Schema and **"Type Soundness"**. - [Standard Schema](#standard-schema) - [Macro](#macro) @@ -49,15 +49,17 @@ Elysia 1.4 highlight is on Standard Schema, and **"Type Soundness"**. - [Group standalone schema](#group-standalone-schema) ## Standard Schema -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. -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)). +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. -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. +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. -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. +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. + +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. + +Elysia now supports Standard Schema, allowing you to use your favorite validators like: -Elysia now support Standard Schema, allowing you to use your favorite validators like: - Zod - Valibot - Effect Schema @@ -65,7 +67,8 @@ Elysia now support Standard Schema, allowing you to use your favorite validators - Joi - and more! -You can provide the schema similar to TypeBox, and it will just work out of the box: +You can provide the schema in a way similar to TypeBox, and it will just work out of the box: + ```ts twoslash import { Elysia, t } from 'elysia' import { z } from 'zod' @@ -96,31 +99,33 @@ const app = new Elysia() }) ``` -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. +You can use multiple validators in a single route, and they will work together seamlessly with correct type inference. ### OpenAPI -There is a request to support JSON Schema for OpenAPI generation for Standard Schema but it is not implemented yet. + +There is a request to support JSON Schema for OpenAPI generation with Standard Schema, but it is not implemented yet. However, we provide a custom `mapJsonSchema` to `openapi` allow you to provide a custom function to map schema to Json Schema as a workaround. -Allowing you to have a beautiful OpenAPI documentation with your favorite validator. +This allows you to have beautiful OpenAPI documentation with your favorite validator. ![Zod with OpenAPI support](/blog/elysia-14/openapi-zod.webp) -> Using Zod native OpenAPI schema support with **describe** to add description to the schema +> Using Zod's native OpenAPI schema support with **describe** to add description to the schema -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. +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. -This means that Elysia support OpenAPI generation for all validators that support Standard Schema even if it doesn't directly support JSON Schema. +This means Elysia supports OpenAPI generation for all validators that support Standard Schema, even if they don't directly support JSON Schema. ![Valibot with OpenAPI support](/blog/elysia-14/openapi-valibot.webp) -> Valibot doesn't directly support JSON Schema, but we OpenAPI type gen to handle it +> Valibot doesn't directly support JSON Schema, but we use OpenAPI type gen to handle it -Not only that it will input type correctly, but OpenAPI type gen will also generate all possible output type as well, including error response. +Not only will it generate correct input type, but OpenAPI type gen will also generate all possible output types, including error responses. -This is truly a unique feature for Elysia, that we are truly proud to offer. +This is truly a unique feature for Elysia, and we are very proud to offer it. ### Standalone Validator -You can also use multiple schema to validate a single input using standalone validator: + +You can also use multiple schemas to validate a single input using a standalone validator: ```ts twoslash import { Elysia, t } from 'elysia' @@ -134,140 +139,149 @@ const app = new Elysia() id: z.coerce.number() }) }) - .post( - '/user/:id', - ({ body }) => body, + .post( + '/user/:id', + ({ body }) => body, // ^? - { - body: v.object({ - name: v.literal('lilith') - }) - }) + + { + body: v.object({ + name: v.literal('lilith') + }) + } + ) ``` -> 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. +> This example uses both Zod and Valibot to validate the body, allowing you to use existing schemas in your codebase from different validators together. -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. +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. ![Using multiple validators to validate part of a body](/blog/elysia-14/standard-schema.webp) -> Using TypeBox, Zod, Valibot, Joi, Yup, ArkType, Effect Schema, TypeMap, Rescript Schema to validate different part of the body +> Using TypeBox, Zod, Valibot, Joi, Yup, ArkType, Effect Schema, TypeMap, and ReScript Schema to validate different parts of the body -We test 8 validators at the same time, validating each part of the input, and it just works flawlessly. +We tested 8 validators at the same time, validating each part of the input, and it just works flawlessly. -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. +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. ## Macro -Macro is one of the most powerful, and flexible feature of Elysia. -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. +Macro is one of the most powerful and flexible features of Elysia. + +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. -The versatility of Macro is truly amazing, allowing you to do things that are hardly possible with other frameworks effortlessly. +The versatility of Macro is truly amazing, letting you do things that are nearly impossible with other frameworks, effortlessly. -And with Elysia 1.4, we bring several improvement to make macro even more versatile. +With Elysia 1.4, we bring several improvements to make macros even more versatile. ### Macro Schema -You can now define a schema for your macro, allowing you to define custom validation directly from your macro. + +You can now define a schema for your macro, allowing you to add custom validation directly from your macro. ![Macro with schema](/blog/elysia-14/macro-schema.webp) > Macro with schema support -Macro with schema will automatically validate and infer type to ensure type safety, and it can co-exist with existing schema as well. +Macro with schema will automatically validate and infer types to ensure type safety, and it can coexist with existing schemas as well. -You can also stack multiple schema from different macro, or even from Standard Validator and it will work together seamlessly. +You can also stack multiple schemas from different macros, or even from Standard Schema, and they will work together seamlessly. -Macro schema also support type inference for **lifecycle within the same macro** **BUT** only with named single macro due to TypeScript limitation. +Macro schema also supports type inference for **lifecycle within the same macro** **BUT** only with a named single macro due to a TypeScript limitation. ![Macro with extension](/blog/elysia-14/macro-schema-lifecycle.webp) > Using a named single macro to infer type into lifecycle within the same macro -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 +If you want to use lifecycle type inference within the same macro, you should use a named single macro instead of multiple stacked macros. -> Not to confused with using macro schema to infer type into route's lifecycle event. That works just fine this limitation only apply to using lifecycle within the same macro. +> 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. ### Macro Extension -You can now extend existing macro, allowing you to build upon existing functionality. + +You can now extend existing macros, allowing you to build upon existing functionality. ![Macro with extension](/blog/elysia-14/macro-extension.webp) > Macro with extension support -This allow you to build upon existing macro, and add more functionality to it. +This allows you to build upon existing macros and add more functionality to them. -It also works recursively with automatic deduplication, allowing you to extends existing macro that already extends another macro without any issue. +It also works recursively with automatic deduplication, allowing you to extend existing macros that already extend other macros without any issues. -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. +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. ### Macro Detail + You can now define OpenAPI detail for your macro, allowing you to add more detail to your OpenAPI documentation directly from your macro. If the route already has OpenAPI detail, it will merge the detail together but prefers the route detail over macro detail. ## Lifecycle Type Soundness -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. -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. +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. -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. +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. -All of these complex acheivement allow us to create document all of possibility of what a single route can return. +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. -![Type Soundness](/blog/elysia-14/type-soundness.webp) -> Documenting all of the possibility of what a single route can return +All of these complex achievements allow us to document all possibilities of what a single route can return. +![Type Soundness](/blog/elysia-14/type-soundness.webp) +> Documenting all the possibilities of what a single route can return -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. +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. -> 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. +> 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. -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. +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 inference](/blog/elysia-14/type-inference.webp) > Type instantiation is reduced by 11.57% from our internal benchmark ## Group standalone schema -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. -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. +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. + +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. -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. +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 standalone](/blog/elysia-14/group-standalone.webp) -> `group` with schema will co-exists with route schema +> `group` with schema will coexist with route schema -This allow you to define a new schema in `group` without having to include the existing schema manually. +This allows you to define a new schema in `group` without having to include the existing schema manually. ## Notable changes -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. -### Improvement +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. + +### Improvements + - [#861](https://github.com/elysiajs/elysia/issues/861) automatically add HEAD method when defining GET route -- [#1389](https://github.com/elysiajs/elysia/pull/1389) NoValidate in refernce model +- [#1389](https://github.com/elysiajs/elysia/pull/1389) NoValidate in reference model + +### Changes -### Change -- ObjectString/ArrayString no longer produce default value by default due to security reasons -- Cookie now dynamically parse when format is likely JSON +- ObjectString/ArrayString no longer produce default values due to security reasons +- Cookie now dynamically parses when format is likely JSON - export `fileType` for external file type validation for accurate response -- ObjectString/ArrayString no longer produce default value by default due to security reasons -- Cookie now dynamically parse when format is likely JSON -### Breaking Change -- remove macro v1 due to non type soundness -- remove `error` function, use `status` instead -- deprecation notice for `response` in `mapResponse`, `afterResponse`, use `responseValue` instead +### Breaking Changes + +- remove macro v1 due to lack of type soundness +- remove `error` function; use `status` instead +- deprecation notice for `response` in `mapResponse`, `afterResponse`; use `responseValue` instead ## Afterword -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! +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! -Our cover art mirror the theme with Supersymmetry (music) cover art where ElysiaJS chan is mirroring Weirs with a similar pose +Our cover art mirrors the theme of the Supersymmetry (music) cover art, where ElysiaJS chan is mirroring Weirs with a similar pose. ![Elysia chan mirroring Supersymmetry](/blog/elysia-14/elysia-supersymmetry.webp) -> Elysia chan mirroring same pose as Weirs from Supersymmetry cover art [(pixiv)](https://www.pixiv.net/en/artworks/134997229) +> Elysia chan mirroring the same pose as Weirs from the Supersymmetry cover art [(pixiv)](https://www.pixiv.net/en/artworks/134997229) -Isn't she so cute? I really love how she turn out! I personally work hard to improve my art skill to be able to draw, hope you like it! +Isn't she so cute? I really love how she turned out! I personally worked hard to improve my art skills to be able to draw her. Hope you like it! -Anyway, hope you like this release! We are excited to see what you will build with it! +Anyway, I hope you like this release! We are excited to see what you will build with it! Have a nice day!