elysiajs/elysia
github.com/elysiajs/elysia ↗ · 270 files · 1.9 MB
Elysia Ergonomic Framework for Humans Documentation | Discord | Sponsors TypeScript with End-to-End Type Safety, type integrity, and exceptional developer experience.
Overview
Elysia is a TypeScript HTTP and WebSocket framework for developers building typed server APIs, distributed here as the elysia npm package at version 1.4.30. Its central Elysia class combines fluent route registration, runtime schemas, lifecycle hooks and plugins with generated request handlers and a separate dynamic execution path. Bun supplies native serving and WebSockets, while Web Standard and experimental Cloudflare adapters expose alternative runtime boundaries.
System map
The public Elysia class owns application configuration, routes, schemas, hooks and shared state. Execution divides between generated AOT handlers and a dynamic handler, with adapters supplying serving and response behavior. Storage in the inspected framework core consists of application memory and HTTP cookies. Packaging and CI target multiple module formats and runtime integrations.
- Elysia's generic parameters track base paths, singleton context, definitions, metadata, routes and scoped/local additions; runtime fields hold corresponding stores and registries.
- The constructor defaults AOT from ELYSIA_AOT, enables normalization, schema encoding and native static responses, and selects BunAdapter when Bun exists unless an adapter is supplied.
- Routing separates static path tables, native response tables, route history and lazy Memoirist HTTP/dynamic routers; parameter decoding uses fastDecodeURIComponent.
- The fetch getter installs either composeGeneralHandler or createDynamicHandler; compile also invokes adapter.beforeCompile, while listen delegates to the adapter.
- BunAdapter owns Bun.serve and WebSocket integration; WebStandardAdapter rejects listen, and CloudflareAdapter extends it with eager route and error-handler compilation.
- Validation integrates TypeBox and Standard Schema; normalization can use exact-mirror with a cleaner fallback, and the manifest declares cookie, URI decoding and Memoirist dependencies.
- Application state resides in singleton.store; request contexts reference that object, while cookie changes become HTTP headers rather than framework database writes in this inspected path.
- build.ts emits unbundled ESM/CJS files targeting Node 20 and generates declarations; package exports expose both formats, CI builds and tests, and release-published events trigger npm provenance publishing.
Feature catalog
The developer-facing surface centers on typed routing, validation and lifecycle control. Applications can share context and state, manage cookies, compose plugins and mount other fetch handlers. Response facilities cover ordinary values, files, streams and SSE, with Bun-specific WebSockets. These are framework APIs demonstrated by tests and examples, rather than product screens or application-specific endpoints.
- get and post register method-specific routes; route uppercases arbitrary method names, and add applies prefixes and distinguishes literal paths from parameter/wildcard paths.
- Route schemas cover body, headers, params, query, cookie and status-dependent responses; Standard Schema tests demonstrate Zod validation and numeric query coercion.
- Built-in body parsing supports JSON, text, URL encoding, ArrayBuffer and multipart forms; multipart parsing groups repeated values and reconstructs dotted/indexed nested fields.
- Lifecycle hooks can transform context before validation, derive or resolve request properties, and intercept handling; tracing exposes request through error stages with timing and completion listeners.
- state supports named values, object merges and store-mapping functions; decorate adds reusable context members, and the counter example mutates shared state on GET /.
- Cookie objects expose values and attributes plus update, set and remove operations; parsing supports selected or all signed cookies and verification against rotated signing keys.
- Bun WebSocket routes support connection callbacks, parsed/validated messages and response validation; ElysiaWS exposes send, subscription and publish facilities.
- Response mapping handles JSON objects, strings, custom statuses, Response, files and streams; shared helpers implement byte ranges and SSE formatting, while use/group/guard/mount compose application behavior.
Data flow
Registration converts developer declarations into route records and execution machinery before requests arrive. Requests enter through Fetch-compatible Request objects and acquire per-request context alongside shared application state. Parsing and schema providers transform boundary values before application handlers run. Responses cross adapter mapping, cookie serialization, streaming or WebSocket output boundaries.
- add expands macros, normalizes/prefixes paths and selects route schemas over inherited candidates before constructing route validators and compiled handlers.
- WebStandard createContext extracts URL path/query positions, shares store and decorator values, and allocates request-local set headers/status.
- Dynamic dispatch runs application request hooks first, then searches method, WebSocket method and ALL routes; missing routes receive parsed query context before NotFoundError.
- Dynamic body parsing skips GET/HEAD, then places parsed body, matched params, query values and header entries into context; parseQuery preserves repeated keys as arrays.
- Standard Schema Validate propagates value/issues results and awaits Promise results; dynamic HTTP validation replaces context fields with validated output or throws ValidationError.
- Parsed cookies become a proxy of Cookie objects backed by request-local set.cookie; outgoing properties are serialized and handleSet installs one or multiple Set-Cookie headers.
- Web Standard mapResponse turns arrays/objects into JSON and dispatches files, custom statuses, promises and streams to specialized handlers; byte ranges slice Blob/File responses.
- WebSocket frames pass through createWSMessageParser, validation and the message callback; createHandleWSResponse resolves promises, iterates generators and serializes objects before sending.
Behavior traces
The inspected flows cover server startup, request validation and cookie persistence across HTTP boundaries. Additional traces follow shared counter state, native constant responses, WebSockets and file ranges. Execution order includes early returns and adapter-specific conditions. These walkthroughs describe source behavior and test intent; they are not recorded runtime executions.
- Startup: example/counter constructs Elysia, calls state then get, and listen delegates to BunAdapter.listen; that calls compile, builds serving options, invokes Bun.serve, then start hooks and the callback.
- AOT first request: handle accesses fetch, composeGeneralHandler builds dispatch and installs the error handler, request hooks precede routing, and a route's lazy compile closure calls composeHandler and caches its result.
- Dynamic POST: createDynamicHandler constructs context, runs request hooks, finds the route, parses JSON, runs transform hooks, validates body, runs beforeHandle, invokes handle and maps its response.
- Invalid-input branch: validateStandardSchema awaits Validate and throws on issues; dynamic dispatch catches the error and delegates to handleError, whose dynamic implementation runs error hooks before its status/message fallback.
- Cookie persistence: the /create example assigns name.value; the jar records outgoing changes, AOT encodeCookie signs selected cookies with the first configured key, handleSet serializes them, and later parseCookie verifies keys before decoding values.
- Shared counter: state('counter', 0) populates singleton.store, createContext passes that same store into the request, and the GET handler returns the previous counter value while incrementing it in memory.
- Native constant response: add asks createNativeStaticHandler for a literal handler, that helper rejects nonempty pipeline hooks, and BunAdapter refuses native static route assembly when request hooks, tracing or higher-order wrappers exist.
- File range request: mapResponse dispatches Blob/File to handleFile; a bytes range is parsed and clamped, invalid positions return 416, and valid positions produce a sliced 206 response with range/length headers.
Testing signals
Tests and CI were inspected, not executed; no passing result is asserted. Bun tests exercise request behavior and regressions, while a separate TypeScript project checks public inference. Node and Cloudflare scripts provide integration smoke checks with narrower assertions. The inspected inventory is bounded, and commented tests identify local coverage limits without establishing repository-wide absence.
- The documented unit framework is bun:test with files under test; CONTRIBUTING recommends bun test test/<test-file>.ts for a focused check.
- Tests and CI were inspected, not executed: the aggregate test script chains functionality, type and Node checks, and CI separately invokes Cloudflare checks after building.
- Dynamic-mode tests explicitly configure aot:false and assert JSON body validation, derive/resolve context and invalid-input 422 behavior.
- Standard Schema integration tests check valid and invalid Zod bodies, coerced queries and combined status-specific responses; validator unit tests insist Check returns booleans rather than truthy failure wrappers.
- Native-static regressions assert promotion refusal for request schemas and observing hooks, preserve eligible constant routes, and require request hooks to remain uncalled during registration.
- Cookie tests exercise signature verification and key rotation; range tests check open-ended, bounded, suffix and invalid ranges, explicitly accepting only the first range of a multi-range request.
- Type tests use expect-type and tsc with test/types as the configured include; Node CJS/ESM fixtures each validate a simple typed GET through app.handle, while Cloudflare polls only the root response.
- Local coverage limits include commented cookie decoding cases, dynamic query-reference cases and a WebSocket subscribe/publish case; active WebSocket tests do exercise a real listen(0) connection.
Risk map
The main sensitive boundaries are generated code, cookie signatures, validation output, filesystem reads and WebSocket validation. Native static routing introduces a separate execution boundary that existing guards and regressions explicitly protect. Several implementation differences merit targeted investigation across runtimes and AOT modes. These are source observations or labeled hypotheses, not confirmed vulnerabilities.
- AOT executes generated JavaScript through Function, and compilation failures log generated instructions, hook source and definitions before potentially exiting the process; this is a broad failure and diagnostic boundary.
- Hypothesis: compilation diagnostics could expose cookie signing material because encodeCookie embeds the configured secret in generated code and the failure logger prints fnLiteral; no failure was induced. (inferred)
- Cookie verification uses crypto.timingSafeEqual when available but falls back to string equality otherwise; HMAC generation uses Web Crypto SHA-256 and Buffer-based base64 encoding.
- file(path) passes the supplied path to Bun.file or Node createReadStream/stat without a root restriction in this constructor; applications exposing request-derived paths must establish their own boundary.
- Native promotion bypasses the composed request pipeline; isEmptyPipelineHook rejects substantive hooks/schemas, while start, stop, error and afterResponse are explicitly allowed exceptions.
- Multipart reconstruction has explicit dangerous-key checks in both generated and dynamic nested traversal; duplicated parser implementations make consistent handling of dotted and indexed keys a sensitive edit boundary.
- Hypothesis: asynchronous Standard Schema WebSocket validators may escape validation because message and response checks read .issues directly from validate(data), whereas HTTP validation awaits Validate; this was not reproduced. (inferred)
- Production Standard Schema validation messages still include found:value; separately, dynamic selected-cookie signing requires schema membership and truthy values, while the AOT selected-cookie branch lacks that membership condition.
Extension points
Extensions attach through explicit adapter, plugin, hook, parser, macro and model surfaces. The core owns registration and schema composition, while adapters supply execution literals and output handlers. Context additions and mounted fetch applications support application integration without replacing the framework. Public type inference accompanies these runtime extension contracts.
- ElysiaAdapter defines listen/stop, response mappers, parser/context code generation, error mapping, optional WebSockets, native router integration and beforeCompile.
- use accepts arrays and promised plugins, resolves function/instance/default-export forms, and ultimately incorporates plugin routes through add.
- Plugin composition imports decorators, state, models and errors through their public registration methods and merges macro and inference state.
- on converts functions into HookContainers and assigns local or explicit lifecycle scope; guard can add standalone validators or update scoped schema layers and register lifecycle hooks.
- macro registers named/object expansions; applyMacro deduplicates by checksum, inserts standalone schemas, supports introspection/detail and recursively expands nested macros with a 16-iteration limit.
- parser stores named BodyHandlers in ~parser, which generated route handlers receive; model accepts TypeBox and Standard Schema definitions, and type-system exports TypeRegistry and FormatRegistry.
- Context extension separates shared state/decorators from request-derived additions: dynamic derive merges transform results, while resolve merges beforeHandle results and continues without treating them as responses.
- mount accepts Elysia instances or fetch functions and rewrites prefixed Request paths; higher-order functions wrap generated dispatch through createHoc.
Contributor handoff
This brief is pinned to e037eca710e7ad193be09cc6615ab0dbe54af914 and comes from bounded public-source inspection of more than twelve source files. Tests and CI were inspected, not executed, and test existence does not establish passing behavior. Future edits should preserve execution parity, adapter boundaries and public inference. Repository contribution policies and script side effects need attention before moving beyond read-only analysis.
- Treat validation and routing conclusions as source-backed behavior, not execution results: tests and CI were inspected, not executed, and only selected tests were read.
- For routing changes, read add, its compile/cache closure, composeGeneralHandler and createDynamicHandler together; static tables and dynamic route stores use different representations.
- When checks are authorized, begin with a focused Bun test as CONTRIBUTING documents; relevant starting suites include dynamic-mode, native-static, cookie-signature and range tests.
- Preserve provider contracts: Standard Schema Check deliberately fails closed for Promise results, while asynchronous callers should use Validate and consume value/issues.
- Public API edits require inference review as well as runtime review: Elysia generics and MacroToContext feed route/context types, and test:types compiles the dedicated test/types project.
- Keep runtime checks specific: default adapter choice depends on Bun availability, WebStandard listen throws, Cloudflare precompiles routes, and Node fixtures only smoke-test app.handle.
- Match tabs, single quotes, no semicolons and no trailing commas; AGENTS requires surgical edits and reading exports/callers, while AI_POLICY requires human-reviewed contributions and rejects fully automated issue/PR creation.
- Do not treat scripts as harmless checks: build removes dist and shells out to tsc, Node/Cloudflare scripts install packages, Cloudflare testing spawns a server, and release publishes the package.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 237 | 99% |
| JSON | 8 | docs/config |
| Markdown | 7 | docs/config |
| YAML | 7 | docs/config |
| JavaScript | 2 | 1% |
| HTML | 1 | docs/config |
Start reading here
Probable source entrypoint: src/index.ts — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (39 files)
Source layout — src/
| Path | Files |
|---|---|
src/adapter/ | 10 |
src/type-system/ | 4 |
src/universal/ | 7 |
src/ws/ | 3 |
src/compose.ts | 1 |
src/context.ts | 1 |
src/cookies.ts | 1 |
src/dynamic-handle.ts | 1 |
src/error.ts | 1 |
src/formats.ts | 1 |
src/index.ts | 1 |
src/manifest.ts | 1 |
src/parse-query.ts | 1 |
src/replace-schema.ts | 1 |
Repository structure
| Top-level path | Files |
|---|---|
test/ | 160 |
example/ | 45 |
src/ | 39 |
.github/ | 8 |
Docs found: CONTRIBUTING.mdREADME.md
Package
package.json — elysia v1.4.30, 25 declared dependencies.
@elysiajs/openapi@sinclair/typebox@types/bun@types/cookie@types/fast-decode-uri-component@typescript-eslint/eslint-plugin@typescript-eslint/parserarktypecookieesbuild-fix-imports-plugineslinteslint-plugin-security
CI & config entrypoints
README.md— Repository readmesrc/index.ts— TS entrypoint.github/workflows/publish.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflowpackage.json— npm scripts: build, deadcode, dev, release, test, test:cf, test:functionality, test:imports
Structural health signals
Average score 8.3/10 across 96 analyzed source files; 4 hotspots surfaced.
src/dynamic-handle.ts— 1018 lines, score 4 (Large file, Deep nesting)src/index.ts— 3648 lines, score 6.2 (Large file, Deep nesting)test/types/schema-standalone.ts— 1245 lines, score 6.2 (Large file, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
e037eca710e72026-08-26 — :broom: chore: correct spelling mistake in changelogacea3a76f0f72026-08-26 — :broom: chore: add SECURITY.mda6b9fc71824a2026-08-26 — :broom: chore: update for bun 1.4b1c325f354192026-08-26 — Merge branch 'main' of https://github.com/elysiajs/elysiab8256ccf6a062026-08-26 — :broom: chore: update for bun 1.4