Elysia 1.1 - Grown-up's Paradise

Named after a song by Mili, “Grown-up’s Paradise”, and used as the opening for commercial announcement of Arknights TV animation season 3.

As a day one Arknights player and long time Mili fan, never once would I have thought Mili would do a song for Arknights. You should check them out as they are the goat.

Elysia 1.1 focuses on several improvements to Developer Experience as follows:

• OpenTelemetry
• Trace v2 (breaking change)
• Normalization
• Data coercion
• Guard as
• Bulk as cast
• Response status reconciliation
• Optional path parameter
• Generator response stream

Observability is one of the important aspects for production.

It allows us to understand how our server works in production, identifying problems and bottlenecks.

One of the most popular tools for observability is OpenTelemetry. However, we acknowledge that it’s hard and takes time to set up and instrument your server correctly.

It’s hard to integrate OpenTelemetry into most existing frameworks and libraries.

Most revolve around hacky solutions, monkey patching, prototype pollution, or manual instrumentation as the framework is not designed for observability from the start.

That’s why we introduce first party support for OpenTelemetry on Elysia.

To start using OpenTelemetry, install @elysiajs/opentelemetry and apply the plugin to any instance.

import { Elysia } from 'elysia'
import { opentelemetry } from '@elysiajs/opentelemetry'

import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'

new Elysia()
  .use(
    opentelemetry({
      spanProcessors: [
        new BatchSpanProcessor(
          new OTLPTraceExporter()
        )
      ]
    })
  )

Elysia OpenTelemetry will collect spans of any library compatible with the OpenTelemetry standard, and will apply parent and child spans automatically.

In the code above, we apply Prisma to trace how long each query took.

By applying OpenTelemetry, Elysia will then:

• collect telemetry data
• Group relevant lifecycle events together
• Measure how long each function took
• Instrument HTTP requests and responses
• Collect errors and exceptions

You can export telemetry data to Jaeger, Zipkin, New Relic, Axiom or any other OpenTelemetry compatible backend.

Here’s an example of exporting telemetry to Axiom.

import { Elysia } from 'elysia'
import { opentelemetry } from '@elysiajs/opentelemetry'

import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'

new Elysia()
  .use(
    opentelemetry({
      spanProcessors: [
        new BatchSpanProcessor(
          new OTLPTraceExporter({
            url: 'https://api.axiom.co/v1/traces',
            headers: {
                Authorization: `Bearer ${Bun.env.AXIOM_TOKEN}`,
                'X-Axiom-Dataset': Bun.env.AXIOM_DATASET
            }
          })
        )
      ]
    })
  )

Elysia OpenTelemetry is for applying OpenTelemetry to an Elysia server only.

You can use OpenTelemetry SDK normally, and if the span is run under Elysia’s request span, it will automatically appear in Elysia’s trace.

However, we also provide a getTracer, and record utility to collect spans from any part of your application.

import { Elysia } from 'elysia'
import { record } from '@elysiajs/opentelemetry'

export const plugin = new Elysia()
  .get('', () => {
    return record('database.query', () => {
      return db.query('SELECT * FROM users')
    })
  })

record is an equivalent to OpenTelemetry’s startActiveSpan but it will handle auto-closing and capture exceptions automatically.

You may think of record as a label for your code that will be shown in a trace.

Elysia OpenTelemetry will group lifecycle and read the function name of each hook as the name of the span.

It’s a good time to name your function.

If your hook handler is an arrow function, you may refactor it to a named function to understand the trace better. Otherwise, your trace span will be named as anonymous.

const bad = new Elysia()
  // ⚠️ span name will be anonymous
  .derive(async ({ cookie: { session } }) => {
    return {
      user: await getProfile(session)
    }
  })

const good = new Elysia()
  // ✅ span name will be getProfile
  .derive(async function getProfile({ cookie: { session } }) {
    return {
      user: await getProfile(session)
    }
  })

Elysia OpenTelemetry is built on Trace v2, replacing Trace v1.

Trace v2 allows us to trace any part of our server with 100% synchronous behavior, instead of relying on a parallel event listener bridge (goodbye deadlock).

It’s entirely rewritten to not only be faster, but also reliable, and accurate down to the microsecond by relying on Elysia’s ahead of time compilation and code injection.

Trace v2 uses a callback listener instead of Promise to ensure that the callback is finished before moving on to the next lifecycle event.

Here’s an example usage of Trace v2:

import { Elysia } from 'elysia'

new Elysia()
  .trace(({ onBeforeHandle, set }) => {
    // Listen to before handle event
    onBeforeHandle(({ onEvent }) => {
      // Listen to all child event in order
      onEvent(({ onStop, name }) => {
        // Execute something after a child event is finished
        onStop(({ elapsed }) => {
          console.log(name, 'took', elapsed, 'ms')

          // callback is executed synchronously before next event
          set.headers['x-trace'] = 'true'
        })
      })
    })
  })

You may also use async inside trace. Elysia will block an event before proceeding to the next event until the callback is finished.

Trace v2 is a breaking change to Trace v1, please check out trace api documentation for more information.

Elysia 1.1 now normalizes data before it’s being processed.

To ensure that data is consistent and safe, Elysia will try to coerce data into an exact data shape defined in schema, removing additional fields, and normalizing data into a consistent format.

For example, if you have a schema like this:

import { Elysia, t } from 'elysia'
import { treaty } from '@elysiajs/eden'

const app = new Elysia()
  .post('/', ({ body }) => body, {
    body: t.Object({
      name: t.String(),
      point: t.Number()
    }),
    response: t.Object({
      name: t.String()
    })
  })

const { data } = await treaty(app).index.post({
  name: 'SaltyAom',
  point: 9001,
  // ⚠️ additional field
  title: 'maintainer'
})

// 'point' is removed as defined in response
console.log(data) // { name: 'SaltyAom' }

This code does 2 things:

• Remove title from body before it’s being used on the server
• Remove point from response before it’s being sent to the client

This is useful to prevent data inconsistency, and ensure that data is always in the correct format, and does not leak any sensitive information.

Previously Elysia used an exact data type without coercion unless explicitly specified to.

For example, to parse a query parameter as a number, you need to explicitly cast it as t.Numeric instead of t.Number.

import { Elysia, t } from 'elysia'

const app = new Elysia()
  .get('/', ({ query }) => query, {
    query: t.Object({
      page: t.Numeric()
    })
  })

However, in Elysia 1.1, we introduce data type coercion, which will automatically coerce data into the correct data type if possible.

This allows us to simply set t.Number instead of t.Numeric to parse a query parameter as a number.

import { Elysia, t } from 'elysia'

const app = new Elysia()
  .get('/', ({ query }) => query, {
    query: t.Object({
      // ✅ page will be coerced into a number automatically
      page: t.Number()
    })
  })

This also applies to t.Boolean, t.Object, and t.Array.

This is done by swapping schemas with possible coercion counterparts during the compilation phase ahead of time, and has the same effect as using t.Numeric or other coercion counterparts.

Previously, guard will only apply to the current instance only.

import { Elysia } from 'elysia'

const plugin = new Elysia()
  .guard({
    beforeHandle() {
      console.log('called')
    }
  })
  .get('/plugin', () => 'ok')

const main = new Elysia()
  .use(plugin)
  .get('/', () => 'ok')

Using this code, onBeforeHandle will only be called when accessing /plugin but not /.

In Elysia 1.1, we add an as property to guard allowing us to apply guard as scoped or global the same as adding an event listener.

import { Elysia } from 'elysia'

const plugin1 = new Elysia()
  .guard({
    as: 'scoped',
    beforeHandle() {
      console.log('called')
    }
  })
  .get('/plugin', () => 'ok')

// Same as
const plugin2 = new Elysia()
  .onBeforeHandle({ as: 'scoped' }, () => {
    console.log('called')
  })
  .get('/plugin', () => 'ok')

This will ensure that onBeforeHandle will be called on the parent as well, and follow the scoping mechanism.

Adding as to guard is useful, because it allows us to apply multiple hooks respecting the scoping mechanism all at once.

However, it also allows us to apply schema to ensure type safety for all the routes at once.

import { Elysia, t } from 'elysia'

const plugin = new Elysia()
  .guard({
    as: 'scoped',
    response: t.String()
  })
  .get('/ok', () => 'ok')
  .get('/not-ok', () => 1)

const instance = new Elysia()
  .use(plugin)
  .get('/no-ok-parent', () => 2)

const parent = new Elysia()
  .use(instance)
  // This is fine because response is defined as scoped
  .get('/ok', () => 3)

Continuing from the code above, sometimes we want to reapply a plugin to the parent instance as well, but as it’s limited by the scoped mechanism, it’s limited to 1 parent only.

To apply to the parent instance, we need to lift the scope up to the parent instance.

We can achieve this by casting it as as(‘plugin’).

import { Elysia, t } from 'elysia'

const plugin = new Elysia()
  .guard({
    as: 'scoped',
    response: t.String()
  })
  .get('/ok', () => 'ok')
  .get('/not-ok', () => 1)

const instance = new Elysia()
  .use(plugin)
  .as('plugin')
  .get('/no-ok-parent', () => 2)

const parent = new Elysia()
  .use(instance)
  // This now error because `scoped` is lifted up to parent
  .get('/ok', () => 3)

The as cast will lift all an instance’s scope up.

It works by reading all hook and schema scopes and lifting them up to the parent instance.

This means if you have a local scope, and want to apply it to the parent instance, you can use as('plugin') to lift it up.

import { Elysia, t } from 'elysia'

const plugin = new Elysia()
  .guard({
    response: t.String()
  })
  .onBeforeHandle(() => { console.log('called') })
  .get('/ok', () => 'ok')
  .get('/not-ok', () => 1)
  .as('plugin')

const instance = new Elysia()
  .use(plugin)
  .get('/no-ok-parent', () => 2)
  .as('plugin')

const parent = new Elysia()
  .use(instance)
  // This now error because `scoped` is lifted up to parent
  .get('/ok', () => 3)

This will cast guard’s response and onBeforeHandle as scoped thus lifting it up to the parent instance.

as accepts two possible arguments:

• plugin casts events to scoped
• global casts events to global

import { Elysia, t } from 'elysia'

const plugin = new Elysia()
  .guard({
    response: t.String()
  })
  .onBeforeHandle(() => { console.log('called') })
  .get('/ok', () => 'ok')
  .get('/not-ok', () => 1)
  .as('global')

const instance = new Elysia()
  .use(plugin)
  .get('/no-ok-parent', () => 2)

const parent = new Elysia()
  .use(instance)
  // This now error because `scoped` is lifted up to parent
  .get('/ok', () => 3)

This allows us to cast multiple hook scopes all at once without adding as to each hook or applying it to guard, or lifting an existing plugin scope up.

import { Elysia, t } from 'elysia'

// On 1.0
const from = new Elysia()
  // Not possible to apply guard to parent on 1.0
  .guard({
    response: t.String()
  })
  .onBeforeHandle({ as: 'scoped' }, () => { console.log('called') })
  .onAfterHandle({ as: 'scoped' }, () => { console.log('called') })
  .onParse({ as: 'scoped' }, () => { console.log('called') })

// On 1.1
const to = new Elysia()
  .guard({
    response: t.String()
  })
  .onBeforeHandle(() => { console.log('called') })
  .onAfterHandle(() => { console.log('called') })
  .onParse(() => { console.log('called') })
  .as('plugin')

In Elysia 1.0, Elysia will prefer one of the schemas from the scope, and will not merge them together.

However, in Elysia 1.1, Elysia will try to reconcile response schemas from all scopes from each status code and merge them together.

import { Elysia, t } from 'elysia'

const plugin = new Elysia()
  .guard({
    as: 'global',
    response: {
      200: t.Literal('ok'),
      418: t.Literal('Teapot')
    }
  })
  .get('/ok', ({ error }) => error(418, 'Teapot'))

const instance = new Elysia()
  .use(plugin)
  .guard({
    response: {
      418: t.String()
    }
  })
  // This is fine because local response override
  .get('/ok', ({ error }) => error(418, 'ok'))

const parent = new Elysia()
  .use(instance)
  // Error because global response
  .get('/not-ok', ({ error }) => error(418, 'ok'))

We can see that:

• on instance: the response schema from the global scope is merged with the local scope, allowing us to override the global response schema in this instance
• on parent: the response schema from the global scope is used, the local scope from instance is not applied because of scoping mechanism

This is handled both at the type level and at runtime, providing us with a better type-integrity.

Elysia now supports optional path parameters by adding ? to the end of a path parameter.

import { Elysia } from 'elysia'

new Elysia()
  .get('/ok/:id?', ({ params: { id } }) => id)
  .get('/ok/:id/:name?', ({ params: { id, name } }) => name)

In the example above, if we access: /ok/1 will return 1 /ok will return undefined

By default, accessing the optional path parameter will return undefined if it’s not provided.

You can provide a default value by either using JavaScript default value or schema default value.

import { Elysia, t } from 'elysia'

new Elysia()
  .get('/ok/:id?', ({ params: { id } }) => id, {
    params: t.Object({
      id: t.Number({
        default: 1
      })
    })
  })

In this example, if we access: /ok/2 will return 1 /ok will return 1

Previously, you could stream a response by using the @elysiajs/stream package.

However, there are limitations:

• Doesn’t provide inference type safety for Eden
• Not as straightforward a way to stream a response

Now, Elysia supports response streaming out of the box by using a generator function.

import { Elysia } from 'elysia'

const app = new Elysia()
  .get('/ok', function* () {
    yield 1
    yield 2
    yield 3
  })

In this example, we can stream a response by using the yield keyword.

Using a generator function, we can now infer the return type from the generator function and provide it to Eden directly.

Eden will now infer the response type from the generator function as AsyncGenerator.

import { Elysia } from 'elysia'
import { treaty } from '@elysiajs/eden'

const app = new Elysia()
  .get('/ok', function* () {
    yield 1
    yield 2
    yield 3
  })

const { data, error } = await treaty(app).ok.get()
if (error) throw error

for await (const chunk of data)
  console.log(chunk)

While streaming a response, it’s common that a request may be cancelled before the response is fully streamed. In that case, Elysia will automatically stop the generator function when the request is cancelled.

We recommend migrating from @elysiajs/stream to generator functions for streaming responses, as it’s more straightforward and provides better type inference.

The stream plugin will be in maintenance mode and will be deprecated in the future.

• Parse value as string for all validators unless explicitly specified.
  • See 50a5d92, 44bf279.
  • Remove objects auto-parsing in query unless explicitly specified via query
  • Except query string as defined in RFC 3986, TLDR; query string could be either a string or an array of strings.
• Rename onResponse to onAfterResponse
• [Internal] Remove $passthrough in favor of toResponse
• [Internal] UnwrapRoute type now always resolves with status code

• Add auto-complete for set.headers
• Remove prototype pollution from hook
• remove static analysis for query name
• remove query replace ’+’ in favor removing static query analysis
• Add server property
• mapResponse is now called in error event
• reconcile decorators at the type level
• onError supports arrays of functions
• Parse query object with and without schema
• Deprecated ObjectString for parsing array
• Sucrose: improve isContextPassToFunction, and extractMainParameter stability
• Add replaceSchemaType
• Add route to context
• Optimize recursive MacroToProperty type
• Parse query array and object
• Optimize code path for composeGeneralHandler
• Add debug report on compiler panic
• Using Cookie<unknown> instead of Cookie<any> if schema is not defined
• Reduce memory usage of route registration ~36% on large codebase
  • Reduce compilation code path
  • Remove trace inference
  • Reduce router compilation code path
  • removing route handler compilation cache (st${index}, stc${index})
• Add undefined union to cookie in case a cookie is not present
• Optimize response status resolve type inference

• Normalize headers accidentally uses query validator check instead
• onError missing trace symbol
• Headers validator compilation is not cached
• Deduplicate macro propagation
• Websocket in nested groups now works
• Error response is not checked unless successful status code is provided

Hi, SaltyAom here again and thank you for supporting Elysia for the past 2 years.

It has been a lovely journey, and seeing so much overwhelming support for Elysia makes me feel so happy that I don’t know how to express it.

I’m still very happy to work on Elysia and looking forward to a long journey with you and Elysia.

However, working alone on Elysia is not easy. That’s why I need your help to support Elysia by reporting a bug, creating a PR (we are opensource after all), sharing anything you like about Elysia, or even just saying hi.

For the past 2 years, I’ve known that Elysia is not perfect, and sometimes I might not have all the time to respond to issues but I’m trying my best to make it better and have a vision of what it could be.

That’s why in the future, we will have more maintainers to help maintain Elysia plugins. Currently Bogeychan and Fecony are doing great at helping maintain the community server.

As you may or may not know, originally ElysiaJS was named “KingWorld” before changing its name to “Elysia”.

Same as Elysia naming convention, both are inspired by anime/game/vtuber subculture.

KingWorld is named after the song KINGWORLD by Shirakami Fubuki and Sasakure.uk, who are my favorite vtuber and music producer, respectively.

That’s why the logo is designed in the style of an Arctic fox after Fubuki.

Elysia is obviously named after Elysia, my favorite character from the game Honkai Impact 3rd, after whom I also named my cat.

Also I have a little gift. As you may know, I’m also a cosplayer in my spare time, and I have a cosplay of Honkai 3rd Elysia as well.

So uh, Elysia maintaining Elysia I guess?

I’m planning to do a photoshoot of Elysia cosplay and share it with you in the future. As I like her so much, I want to make it perfect.

That being said, I’m looking forward to seeing you in the next release, and thank you for supporting Elysia.

We were so easily satisfied and happy

Even if I break your favorite teddy bear

A “sorry” could fix everything

When did it change? When did we forget?

Why is it now so hard to forgive?

Do we advance, never stopping our steps

Because we are scared to look back on what we did?

Truth is, I know as long as we live

Our ideals dye rivers scarlet

Answer me, my sinking ship

Where’s our tomorrow?

Where does our future go?

Does our hope have to be sown upon somebody’s sorrow?

ขอให้โลกใจดีกับเธอบ้างนะ