Elysia 0.3 – 大地の閾を探して
(Looking for Edge of Ground)

Author: @saltyaom
Published: 17 Mar 2023

Overview

Named after Camellia's song “大地の閾を探して [Looking for Edge of Ground]” ft. Hatsune Miku, this release is the most challenging update yet for Elysia. The architecture has been re‑thought and redesigned for high scalability while keeping breaking changes to a minimum.

Below are the highlights of Elysia 0.3:

• Elysia Fn – run backend functions on the frontend with full type‑safety and auto‑completion.
• Type Rework – 6.5–9× faster type checking, massive line‑of‑code reduction.
• File Upload – built‑in form‑data support with validation.
• OpenAPI 3.0.x – default schema, better Swagger support.
• Eden Rework – new architecture for scalability, improved type inference and more.

Elysia Fn

Elysia Fn lets you expose any backend function for frontend usage. It preserves original code comments, offers click‑to‑definition, and supports full type‑safety.

<video controls autoplay muted>
  <source src="/blog/elysia-03/elysia-fn.mp4" type="video/mp4">
</video>

Permission

You can control access to functions by:

• Allowing or denying scopes.
• Checking authorization headers or other header fields.
• Validating parameters.
• Limiting keys programmatically.

Keys checking is type‑safe and auto‑completes all possible functions, ensuring you don't miss or typo a function name.

Narrowing a key scope also narrows the parameter type.

Full type‑safety when the scope is narrowed.

Technical Detail

Elysia Fn uses JavaScript’s Proxy to capture object properties and parameters, batching requests to the server and returning results across the network.
It extends superjson, allowing native JavaScript types such as Error, Map, Set, and undefined to be serialized.

Use cases – accessing Prisma from a Next.js client, using Redis, Sequelize, RabbitMQ, etc.
Performance – runs on Bun and can handle over 1.2 million operations per second (tested on M1 Max).

Learn more about Elysia Fn at the Eden Fn page.

Type Rework

Elysia 0.3 rewrites 80 % of Elysia and Eden types, focusing on performance, inference, and auto‑completion.

• Speed – 350+ complex routes generate a type declaration in only ~0.22 s.
• Size – route types compile directly to literal objects rather than Typebox references, shrinking declarations by 50–99 %.
• Flexibility – plugin registration is less strict; use now infers the parent type, and nested guards reference parent model types more accurately.
• Export – type declarations can be built and exported.

For further details, see the Twitter thread.

File Upload

Thanks to Bun 0.5.7, Form Data is enabled by default with multipart/formdata.

• Elysia.t extends Typebox with File and Files for validation.
• Validation includes file type auto‑completion, size constraints (min/max), and total files per field.
• schema.contentType strictly validates request headers before data validation.

OpenAPI Schema 3.0.x

Elysia now defaults to OpenAPI 3.0.x, improving API definition clarity and multi‑type support based on content‑type.

• schema.details updated to OpenAPI 3.0.x.
• Swagger plugin matches the new schema, leveraging file‑upload features.

Eden Rework

Eden now exposes three function types:

Key improvements:

• Type inference and auto‑completion are faster and more efficient.
• Type declaration rewritten almost 100 % for faster inference (~0.26 s).
• Ability to narrow types based on response status (see image).

Notable Improvements

• Added string formats: email, uuid, date, date-time.
• Updated @sinclair/typebox to 0.25.24.
• Updated Raikiri to 0.2.0‑beta.0.
• File upload tests added.
• Lowercase method pre‑compile.
• Reduced complex instructions.
• Compiled ElysiaRoute type to literal.
• Optimized type compilation and inference.
• Context creation optimization.
• Default to Raikiri router.
• Removed unused functions.
• Refactored registerSchemaPath for OpenAPI 3.0.3.
• Added error inference for Eden.
• Made @sinclair/typebox an optional peer dependency.

Fixes

• Raikiri 0.2 error on not found.
• t.File union responses not working.
• Swagger definitions missing.
• Group plugin schema missing.
• Export issues with EXPOSED in fn.permission.
• t.Files in Swagger refers to single file.
• Other minor bugs listed in the original changelog.

Breaking Changes

• inject renamed to derive.
• ElysiaRoute deprecation, inline replacement.
• Removed derive.
• Migrated from OpenAPI 2.x to 3.0.3.
• Moved context.store[SYMBOL] to meta[SYMBOL].

Afterward

Elysia Fn bridges frontend and backend development, while the Type Rework dramatically improves type‑checking speed and auto‑completion.

Feel free to experiment and build amazing things. Join the community on Discord or drop a comment.

Poetry

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)