![lament-of-the-fallent](https://github.com/elysiajs/elysia/assets/35027979/f029eeb3-9404-48b0-b5b1-8212b05a3387) Elysia 1.0 is the first stable release after development for 1.8 years. Since started, we have always waiting for a framework that focuses on developer experience, velocity, and how to make writing code for humans, not a machine. We battle-test Elysia in various situations, simulate medium and large-scale projects, shipping code to clients and this is the first version that we felt confident enough to ship. Elysia 1.0 introduces significant improvements and contains 1 necessary breaking change. - [Sucrose](#sucrose) - Rewritten pattern matching static analysis instead of RegEx - [Improved startup time](#improved-startup-time) up to 14x - [Remove ~40 routes/instance TypeScript limitation](#remove-40-routesinstance-limit) - [Faster type inference](#type-inference-improvement) up to ~3.8x - [Treaty 2](#treaty-2) - [Hook type](#hook-type-breaking-change) (breaking changes) - [Inline error](#inline-error) for strict error check --- It's a tradition that Elysia's release note have a version named after a song or media. This important version is named after ["Lament of the Fallen"](https://youtu.be/v1sd5CzR504). Animated short from **"Honkai Impact 3rd"** from my favorite arc, and my favorite character, **"Raiden Mei"** featuring her theme song, ["Honkai World Diva"](https://youtu.be/s_ZLfaZMpe0). It's a very good game, and you should check it out. ー SaltyAom Also known as Raiden Mei from Gun Girl Z, Honkai Impact 3rd, Honkai Star Rail. And her "variation", Raiden Shogun from Genshin Impact, and possibly Acheron from Honkai Star Rail (since she's likely a bad-end herrscher form mentioned in Star Rail 2.1). ::: tip Remember, ElysiaJS is an open source library maintain by volunteers, and isn't associate with Mihoyo nor Hoyoverse. But we are a huge fan of Honkai series, alright? ::: ## Sucrose Elysia is optimized to have an excellent performance proven in various benchmarks, one of the main factors is thanks to Bun, and our custom JIT static code analysis. If you are not aware, Elysia has some sort of "compiler" embedded that reads your code and produces an optimized way to handle functions. The process is fast and happens on the fly without a need for a build step. However, it's challenging to maintain as it's written mostly in many complex RegEx, and can be slow at times if recursion happens. That's why we rewrote our static analysis part to separate the code injection phase using a hybrid approach between partial AST-based and pattern-matching name **"Sucrose"**. Instead of using full AST-based which is more accurate, we choose to implement only a subset of rules that is needed to improve performance as it needs to be fast on runtime. Sucrose is good at inferring the recursive property of the handler function accurately with low memory usage, resulting in up to 37% faster inference time and significantly reduced memory usage. Sucrose is shipped to replace RegEx-based to partial AST, and pattern matching starting from Elysia 1.0. ## Improved Startup time Thanks to Sucrose, and separation from the dynamic injection phase, we can defer the analysis time JIT instead of AOT. In other words, the "compile" phase can be lazily evaluated. Offloading the evaluation phase from AOT to JIT when a route is matched for the first time and caching the result to compile on demand instead of all routes before server start. In a runtime performance, a single compilation is usually fast and takes no longer than 0.01-0.03 ms (millisecond not second). In a medium-sized application and stress test, we measure up to between ~6.5-14x faster start-up time. ## Remove ~40 routes/instance limit Previously you could only stack up to ~40 routes / 1 Elysia instance since Elysia 0.1. This is the limitation of TypeScript that each queue that has a limited memory and if exceeded, TypeScript will think that **"Type instantiation is excessively deep and possibly infinite"**. ```typescript const main = new Elysia() .get('/1', () => '1') .get('/2', () => '2') .get('/3', () => '3') // repeat for 40 times .get('/42', () => '42') // Type instantiation is excessively deep and possibly infinite ``` As a workaround, we need to separate an instance into a controller to overcome the limit and remerge the type to offload the queue like this. ```typescript const controller1 = new Elysia() .get('/42', () => '42') .get('/43', () => '43') const main = new Elysia() .get('/1', () => '1') .get('/2', () => '2') // repeat for 40 times .use(controller1) ``` However, starting from Elysia 1.0, we have overcome the limit after a year after optimizing for type-performance, specifically Tail Call Optimization, and variances. This means theoretically, we can stack an unlimited amount of routes and methods until TypeScript breaks. (spoiler: we have done that and it's around 558 routes/instance before TypeScript CLI and language server because of JavaScript memory limit per stack/queue) ```typescript const main = new Elysia() .get('/1', () => '1') .get('/2', () => '2') .get('/3', () => '42') // repeat for n times .get('/550', () => '550') ``` So we increase the limit of ~40 routes to JavaScript memory limit instead, so try not to stack more than ~558 routes/instance, and separate into a plugin if necessary. ![TypeScript breaks on 558 routes](https://github.com/elysiajs/elysia/assets/35027979/334c59e1-f963-4834-afb8-4c9b75423da3) The blocker that made us feel like Elysia is not ready for production has been finally resolved. ## Type Inference improvement Thanks to the effort we put into optimization, we measure **up to ~82%** in most Elysia servers. Thanks to the removed limitation of stack, and improved type performance, we can expect almost instant type check and auto-completion even after 500 routes stacks. https://github.com/elysiajs/elysia/assets/35027979/2048c7fe-72b8-4274-8d48-b6eac3372215 **Up to 13x faster for Eden Treaty**, type inference performance by precomputing the type instead offload type remap to Eden. Overall, Elysia, and Eden Treaty performing together would be **up to ~3.9x faster**. Here's a comparison between the Elysia + Eden Treaty on 0.8 and 1.0 for 450 routes. ![Type performance comparison between Elysia Eden 0.8 and 1.0, the graph shows that Elysia 0.8 took ~1500ms while Elysia 1.0 took ~400ms](https://github.com/elysiajs/elysia/assets/35027979/733c3c25-a611-41c3-ac23-194c1b521a03) Stress test with 450 routes for Elysia with Eden Treaty, result as follows: - Elysia 0.8 took ~1500ms - Elysia 1.0 took ~400ms And thanks to the removal of stack limitation, and remapping process, it's now possible to stack up to over 1,000 routes for a single Eden Treaty instance. ## Treaty 2 We ask you for feedback on Eden Treaty what you like and what could have been improved. and you have given us some flaws in Treaty design and several proposals to improvement. That's why today, we introduce Eden Treaty 2, an overhaul to a more ergonomic design. As much as we dislike breaking change, Treaty 2 is a successor to Treaty 1. **What's new in Treaty 2**: - More ergonomic syntax - End-to-end type safety for Unit Test - Interceptor - No "$" prefix and property Our favorite one is end-to-end type safety for Unit tests. So instead of starting a mock server and sending a fetch request, we can use Eden Treaty 2 to write unit tests with auto-completion and type safety instead. ```typescript // test/index.test.ts import { describe, expect, it } from 'bun:test' import { Elysia } from 'elysia' import { treaty } from '@elysiajs/eden' const app = new Elysia().get('/hello', () => 'hi') const api = treaty(app) describe('Elysia', () => { it('return a response', async () => { const { data } = await api.hello.get() expect(data).toBe('hi') }) }) ``` The difference between the two is that **Treaty 2 is a successor to Treaty 1.** We don't intend to introduce any breaking change to Treaty 1 nor force you to update to Treaty 2. You can choose to continue using Treaty 1 for your current project without updating to Treaty 2, and we maintain it in a maintenance mode. - You can import `treaty` to use Treaty 2. - And import `edenTreaty` for Treaty 1. The documentation for the new Treaty can be found in [Treaty overview](https://elysiajs.com/eden/treaty/overview.html), and for Treaty 1 in [Treaty legacy](https://elysiajs.com/eden/treaty/legacy.html) ## Hook type (breaking change) We hate breaking changes, and this is the first time we do it in large-scale. We put a lot of effort into API design to reduce changes made to Elysia, but this is necessary to fix a flawed design. Previously when we added a hook with **"on"** like `onTransform`, or `onBeforeHandle`, it would become a global hook. This is great for creating something like a plugin but is not ideal for a local instance like a controller. ```typescript const plugin = new Elysia() .onBeforeHandle(() => { console.log('Hi') }) // log Hi .get('/hi', () => 'in plugin') const app = new Elysia() .use(plugin) // will also log hi .get('/no-hi-please', () => 'oh no') ``` However, we found several problems arise from this behavior. - We found that many developers have a lot of nested guards even on the new instance. Guard is almost used as a way to start a new instance to avoid side effects. - global by default may cause unpredictable (side-effect) behavior if not careful, especially in a team with inexperienced developers. - We asked many developers both familiar and not familiar with Elysia, and found that most expected hook to be local at first. - Following the previous point, we found that making hook global by default can easily cause accidental bugs (side-effect) if not reviewed carefully and hard to debug and observe. --- To fix this, we introduce a hook type to specify how the hook should be inherited by introducing a **"hook-type"**. Hook types can be classified as follows: - local (default) - apply to only current instance and descendant only - scoped - apply to only 1 ascendant, current instance, and descendants - global (old behavior) - apply to all instances that apply the plugin (all ascendants, current, and descendants) To specify the hook's type, simply add a `{ as: hookType }` to the hook. ```typescript const plugin = new Elysia() .onBeforeHandle(() => { // [!code --] .onBeforeHandle({ as: 'global' }, () => { // [!code ++] console.log('hi') }) .get('/child', () => 'log hi') const main = new Elysia() .use(plugin) .get('/parent', () => 'log hi') ``` This API is designed to fix the **guard nesting problem** for Elysia, where developers are afraid to introduce a hook on root instances because of fear of side effects. For example, to create an authentication check for an entire instance, we need to wrap a route in a guard. ```typescript const plugin = new Elysia() .guard((app) => app .onBeforeHandle(checkAuthSomehow) .get('/profile', () => 'log hi') ) ``` However, with the introduction of hook type, we can remove the nesting guard boilerplate. ```typescript const plugin = new Elysia() .guard((app) => // [!code --] app // [!code --] .onBeforeHandle(checkAuthSomehow) .get('/profile', () => 'log hi') ) // [!code --] ``` Hook type will specify how the hook should be inherited, let's create a plugin to illustrate how hook type works. ```typescript // ? Value based on table value provided below const type = 'local' const child = new Elysia() .get('/child', () => 'hello') const current = new Elysia() .onBeforeHandle({ as: type }, () => { console.log('hi') }) .use(child) .get('/current', () => 'hello') const parent = new Elysia() .use(current) .get('/parent', () => 'hello') const main = new Elysia() .use(parent) .get('/main', () => 'hello') ``` By changing the `type` value, the result should be as follows: | type | child | current | parent | main | | ---------- | ----- | ------- | ------ | ---- | | 'local' | ✅ | ✅ | ❌ | ❌ | | 'scope' | ✅ | ✅ | ✅ | ❌ | | 'global' | ✅ | ✅ | ✅ | ✅ | Migrating from Elysia 0.8, if you want make a hook global, you have to specify that hook is global. ```typescript // From Elysia 0.8 new Elysia() .onBeforeHandle(() => "A") .derive(() => {}) // Into Elysia 1.0 new Elysia() .onBeforeHandle({ as: 'global' }, () => "A") .derive({ as: 'global' }, () => {}) ``` As much as we hate breaking change and migration, we think this is an important fix that will happen sooner or later to fix problems. Most of the server might not need to apply migration yourself but **heavily depends on plugin authors**, or should migration required, it usually take no longer than 5-15 minutes. For a complete migration note, see [Elysia#513](https://github.com/elysiajs/elysia/issues/513). For the documentation of hook type, see [Lifecycle#hook-type](https://beta.elysiajs.com/essential/life-cycle.html#hook-type) ## Inline error Starting from Elysia 0.8, we can use the `error` function to return a response with a status code for Eden inference. However, this has some flaws. If you specify a response schema for a route, Elysia will be unable to provide an accurate auto-completion for the status code. For example, narrowing down an available status code. ![Using import error in Elysia](https://github.com/elysiajs/elysia/assets/35027979/84a79485-e8ef-489d-a5f8-7d924528e8e5) Inline error can be destructured from handler as follows: ```typescript import { Elysia } from 'elysai' new Elysia() .get('/hello', ({ error }) => { if(Math.random() > 0.5) return error(418, 'Nagisa') return 'Azusa' }, { response: t.Object({ 200: t.Literal('Azusa'), 418: t.Literal('Nagisa') }) }) ``` Inline error can produce a fine-grained type from a schema, providing type narrowing, auto-completion, and type checking to the accuracy of value, underlining red squiggly at a value instead of an entire function. ![Using inline error function from Elysia with an auto-completion that shows narrowed down status code](https://github.com/elysiajs/elysia/assets/35027979/b14b6a77-10bc-4e4c-a6ac-1de2043dcb06) We recommended using inline error instead of import error for more accurate type safety. ## What does it mean for v1, and what's next Reaching stable release means we believe that Elysia is stable enough and ready to be used in production. Maintaining backward compatibility is now one of our goals, putting effort into not introducing breaking changes to Elysia except for security. Our goal is to make backend development feel easy, fun, and intuitive while making sure that the product built with Elysia will have a solid foundation. After this, we will be focusing on refining our ecosystem and plugins. Introducing an ergonomic way to handle redundant and mundane tasks, starting some internal plugin rewrite, authentication, synchronize behavior between JIT and non-JIT mode, and **universal runtime support.** Bun works excellently in both runtime, package manager and all the toolings they offers, and we believe that Bun is going to be a future of JavaScript. We believe that by opening Elysia to more runtime and offers interesting Bun specific feature (or at-least easy to config, eg. [Bun Loaders API](https://bun.sh/docs/bundler/loaders)) will eventually gets people to try Bun more than Elysia choosing to support only Bun.

Bun was right, the best way to migrate people from Node is to have compatibility layer and offers better DX, and performance on Bun
— SaltyAom (@saltyAom) March 14, 2024

Elysia core itself partially WinterCG compatible, but not all the official plugin works with WinterCG, there are some with Bun specific features, and we want to fix that. We don't have a specific date or version for universal runtime supports yet as we will gradually adopting and test until we make sure that it would works without unexpected behavior. You can looks forward for the following runtime to support: - Node - Deno - Cloudflare Worker We also want to support the following: - Vercel Edge Function - Netlify Function - AWS Lambda / LLRT More over, we also support, and test Elysia on the following frameworks that support Server Side Rendering or Edge Function: - Nextjs - Expo - Astro - SvelteKit In the meantime, there's an [Elysia Polyfills](https://github.com/bogeychan/elysia-polyfills) maintained by Bogeychan, one of an active contributor to Elysia. Additionally, we have rewrote [Eden documentation](https://elysiajs.com/eden/overview) to explain more in depth details about Eden and we think you should check it out. We also improve several pages, and remove redundant part of the documentation, You can check the affected pages on [Elysia 1.0 documentation PR](https://github.com/elysiajs/documentation/pull/282/files). And finally, if you have problems with migration and additional questions related to Elysia, feels free to ask one in Elysia's Discord server.