Elysia 0.3 - 大地の閾を探して [Looking for Edge of Ground]

This release is named after Camellia’s song 「大地の閾を探して [Looking for Edge of Ground]」 ft. Hatsune Miku, the last track of my favorite Camellia album,「U.U.F.O」. This song has a high impact on me personally, so I’m not taking the name lightly.

This is the most challenging update, bringing the biggest release of Elysia yet, with a rethinking and redesign of Elysia’s architecture to be highly scalable while making as few breaking changes as possible.

I’m pleased to announce the release candidate of Elysia 0.3 with exciting new features coming right up.

Introducing Elysia Fn. Run any backend function on the frontend with full auto-completion and full type support.

For rapid development, Elysia Fn allows you to “expose” backend code to call from the frontend with full type-safety, autocompletion, original code comments, and “click-to-definition”, allowing you to speed up the development.

You can use Elysia Fn with Eden for full-type safety via Eden Fn.

You can limit the function’s allow or deny scopes, check for an authorization header and other header fields, validate parameters, or limit access to keys programmatically.

Key checking supports type-safety and auto-completion of all possible functions, so you’re not missing out on some functions or accidentally typing down the wrong name.

And narrowing the scope of a property programmatically also narrows down the type of parameters, providing full type-safety.

In technical terms, Elysia Fn uses JavaScript’s Proxy to capture object properties and parameters to create batched requests for the server to handle and return values across the network. Elysia Fn extends superjson, allowing native types in JavaScript like Error, Map, Set, and undefined to be parsed across JSON data.

Elysia Fn supports multiple use-cases, for example accessing Prisma on the client-side Nextjs app. Theoretically, it’s possible to use Redis, Sequelize, RabbitMQ, and more. As Elysia is running on Bun, Elysia Fn can run over 1.2 million operations/second concurrently (tested on M1 Max).

Learn more about Elysia Fn at Eden Fn.

Over 6.5-9x faster for type checking, and an uncountable reduction in the types’ LoC.

In Elysia 0.3, over 80% of Elysia and Eden types have been rewritten to focus on performance, type-inference, and fast auto-completion.

Testing for over 350 routes with complex types, Elysia uses only 0.22 seconds to generate a type declaration to use with Eden.

As Elysia routes now compile directly to literal objects instead of Typebox references, Elysia’s type declaration is much smaller than it was in 0.2 and is easier for Eden to consume. And by much smaller, it means 50-99% smaller.

Not only is Elysia’s integration with TypeScript significantly faster, but Elysia is also better at understanding TypeScript and your code.

For example, with 0.3, Elysia will be less strict with plugin registration, allowing you to register the plugin without full type-completion of Elysia Instance. Inlining the use function now infers the parent type, and the nested guard can reference types of models from the parent more accurately.

Type declarations can now also be built and exported.

With the type rewrite, Elysia understands TypeScript far better than it used to. Type-completion will be significantly faster than it was, and we encourage you to try it out to see how fast it is. For more detail, see this thread on Twitter.

Thanks to Bun 0.5.7, Form Data is implemented and enabled by default in Elysia 0.3 with multipart/formdata.

To define type completion and validation for uploading a file, Elysia.t now extends TypeBox with File and Files for file validation.

The validation includes checking for file type with auto-completion of standard file size, the minimum and maximum size of the file, and the total number of files per field.

Elysia 0.3 also features schema.contentType to explicitly validate the incoming request type to strictly check headers before validating the data.

With Elysia 0.3, Elysia now uses OpenAPI schema 3.0.x by default to better state API definitions and better support multiple types based on content-type.

schema.details is now updated to OpenAPI 3.0.x, and Elysia also updates the Swagger plugin to match the OpenAPI 3.0.x to take advantage of new features in OpenAPI 3 and Swagger, especially with file uploading.

To support more demand for Elysia, including Elysia Fn and Rest together, Eden has been reworked to scale with the new architecture.

Eden now exports 3 types of functions.

• Eden Treaty eden/treaty: Original Eden syntax you know and love
• Eden Fn eden/fn: Access to Eden Fn
• Eden Fetch eden/fetch: Fetch-like syntax, for highly complex Elysia type (> 1,000 routes / Elysia instance)

With the rework of type definitions and support for Elysia Eden, Eden is now much faster and better at inferring types from the server.

Auto-completion is faster and uses fewer resources than it used to. In fact, Eden’s type declaration has been almost 100% reworked to reduce the size and inference time, making it support over 350 routes of auto-completion in a blink of an eye (~0.26 seconds).

To make Elysia Eden fully type-safe, with Elysia’s better understanding of TypeScript, Eden can now narrow down the type based on response status, allowing you to capture the type correctly under any condition.

• Add string format: ‘email’, ‘uuid’, ‘date’, ‘date-time’
• Update @sinclair/typebox to 0.25.24
• Update Raikiri to 0.2.0-beta.0 (ei)
• Add file upload test thanks to #21 (@amirrezamahyari)
• Pre compile lowercase method for Eden
• Reduce complex instruction for most Elysia types
• Compile ElysiaRoute type to literal
• Optimize type compilation, type inference and auto-completion
• Improve type compilation speed
• Improve TypeScript inference between plugin registration
• Optimize TypeScript inference size
• Context creation optimization
• Use Raikiri router by default
• Remove unused function
• Refactor registerSchemaPath to support OpenAPI 3.0.3
• Add error inference for Eden
• Mark @sinclair/typebox as optional peerDependencies

Fix:

• Raikiri 0.2 throws an error on not found
• Union response with t.File is not working
• Definitions aren’t defined on Swagger
• details are missing on the group plugin
• group plugin is unable to compile schema
• group is not exportable because EXPOSED is a private property
• Multiple cookies don’t set content-type to application/json
• EXPOSED is not exported when using fn.permission
• Missing merged return type for .ws
• Missing nanoid
• context side-effects
• t.Files in swagger refers to a single file
• Eden response type is unknown
• Unable to type setModel inference definition via Eden
• Handle errors thrown in a non-permission function
• Exported variable has or is using name ‘SCHEMA’ from external module
• Exported variable has or is using name ‘DEFS’ from external module
• Possible errors for building Elysia app with declaration: true in tsconfig.json

Breaking Change:

• Rename inject to derive
• Deprecate ElysiaRoute, changed to inline
• Remove derive
• Update from OpenAPI 2.x to OpenAPI 3.0.3
• Move context.store[SYMBOL] to meta[SYMBOL]

With the introduction of Elysia Fn, I’m personally excited to see how it will be adopted in frontend development, removing the line between frontend and backend. And Elysia’s Type Rework makes type-checking and auto-completion much faster.

I’m excited to see how you will use Elysia to create the wonderful things you are going to build.

We have a Discord server dedicated to Elysia. Feel free to say hi or just chill and hang out.

Thank you for supporting Elysia.

Under a celestial map that never have ends

On a cliff that never have name

I just holwed

Hoping the neverending reverberation will reach you

And I believe someday, I will stand on edge of the ground

(Until the day I can be back to you to tell it)