@elysiumjs/core 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,160 @@
 # @elysiumjs/core
 
+## 0.11.1
+
+### Patch Changes
+
+- [#26](https://github.com/na2axl/elysiumjs/pull/26) [`4cd1ef2`](https://github.com/na2axl/elysiumjs/commit/4cd1ef217826164e69cd641ca99f74c6f5a7ebe7) Thanks [@na2axl](https://github.com/na2axl)! - Type the query string of the query DSL. `Query.define` keeps the names of the filters, their operators and the sortable fields, `Query.Params<typeof spec>` types the parameter that `@Http.query()` decorates (`filter[status]`, `filter[status][in]`, `sort`, `cursor`, `limit`, `fields`, each an optional string), and `Query.schema(spec)` returns a schema of that type. Because the generated routes read the parameter's type, clients get typed query keys. Core re-exports TypeBox's `TOptional` and `TString` types.
+
+## 0.11.0
+
+### Minor Changes
+
+- [#8](https://github.com/na2axl/elysiumjs/pull/8) [`6bc48fe`](https://github.com/na2axl/elysiumjs/commit/6bc48febd51f7090c582e73f349eaeff7261241c) Thanks [@na2axl](https://github.com/na2axl)! - `Application.build()` builds the root Elysia app without listening, for hosts that own the server (Cloudflare Workers) and for ahead-of-time compilation with `elysia/plugin/aot`. Modules are registered but boot on the first request (once, shared by concurrent requests), so building runs no `onInit` work. A boot failure fails the requests.
+
+  HTTP and websocket controllers in the server scope, and middlewares, are now built on their first request instead of when the app is built. `serve` still boots every module before listening.
+
+  `@elysiumjs/runtime-workers` gets a `check:aot` script, run in CI: it compiles a sample app with the AOT plugin for workerd, checks that the bundle holds no `new Function` or `eval`, and serves a validated route and the OpenAPI document under Node.js with code generation from strings disallowed.
+
+- [#7](https://github.com/na2axl/elysiumjs/pull/7) [`e9c3d98`](https://github.com/na2axl/elysiumjs/commit/e9c3d98dd2714b69100215f7c8a80046da463148) Thanks [@na2axl](https://github.com/na2axl)! - Elysium runs on Elysia 2 (`elysia@^2.0.0-rc.1`), with TypeBox 1 (`typebox`), `@elysia/openapi` and `@elysia/opentelemetry`.
+
+  Breaking:
+
+  - `TSchema` and `Static` are re-exported from `typebox` instead of `@sinclair/typebox`; `Value` comes from `typebox/value` and `Value.Errors()` returns an array.
+  - `Application.onError()` receives a `ServerError` (exported from core). Elysia now names its errors in kebab case; the default error response keeps the upper snake case names (`VALIDATION`, `NOT_FOUND`, `UNKNOWN` for other errors).
+  - `AppHttpContext` is a plain interface with `decorator`, `store` and `derive` records (Elysia 2 renamed `resolve` to `derive`).
+  - Websocket controllers install Elysia's `websocket()` capability themselves.
+
+  A module or controller `onRequest` middleware that answers now stops the request: Elysia 2 ignores values returned from a transform hook, so the response is thrown as a status and sent as is, without going through `onError`.
+
+  `mnemosyne` builds date columns with `t.Codec` (TypeBox 1 dropped `Transform`). `argus` traces every route of the app it is installed on and ends each span once, keeping the error status when the request failed.
+
+- [#5](https://github.com/na2axl/elysiumjs/pull/5) [`557a3ca`](https://github.com/na2axl/elysiumjs/commit/557a3cab7af8053a8bab9944e492e5022d91aa82) Thanks [@na2axl](https://github.com/na2axl)! - Core runs outside Bun. Environment variables, timers, the HTTP server, process exit and shutdown signals now come from a `Runtime` set with the new `runtime` option of `@Application.register()` or with `Runtime.use()`. Runtimes ship as packages, each exporting `runtime`: `@elysiumjs/runtime-bun`, `@elysiumjs/runtime-node` and `@elysiumjs/runtime-workers` (which also exports `createRuntime({ env })`).
+
+  Breaking: an application needs a runtime (add `runtime` from `@elysiumjs/runtime-bun`), and `Redis` and `RedisModule` moved from core to the new `@elysiumjs/redis` package, which also accepts a `client` factory for runtimes without `Bun.RedisClient`.
+
+  Console colours are plain ANSI codes instead of `Bun.color`, `node:readline` is loaded only when a prompt runs, and core's dist is built for the `node` target so `node:` imports keep their prefix. `check:runtime` scripts in core and runtime-workers fail when their bundles touch the `Bun` global.
+
+  `create-elysium` gets a runtime step: it installs the chosen runtime package and sets it in the generated app. Bun is selectable today; Node.js and Cloudflare Workers are listed as coming later.
+
+- [#24](https://github.com/na2axl/elysiumjs/pull/24) [`ccc3f5b`](https://github.com/na2axl/elysiumjs/commit/ccc3f5bb904d1bf52d8c72ebf7ea8d10f617a8c4) Thanks [@na2axl](https://github.com/na2axl)! - `Service.ownersOf(service)` lists the modules that declare a service in their own scope, and `ModuleContext.outside(fn)` runs code outside of any module, so that lookups only see the global scope.
+
+- [#19](https://github.com/na2axl/elysiumjs/pull/19) [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562) Thanks [@na2axl](https://github.com/na2axl)! - Domain errors as classes with a code, returned as values.
+
+  - `DomainError` is an Elysia `HTTPError`. Each error is a class made with `DomainError.for(code, status)`, which keeps its code and status as literal types, with `errors`, `retryAfterSeconds` (served as `retryAfter` and the Retry-After header) and extensions.
+  - Ready-made errors: `BadRequestError`, `ValidationFailedError`, `UnauthenticatedError`, `ForbiddenError`, `NotFoundError` and `ConflictError`.
+  - `ProblemCatalogue`, extended through declaration merging, lists the codes of an application; once it has keys, `DomainError.for()` takes only those and `ELYSIUM_PROBLEM_CODES`.
+  - Every problem carries `code`, `requestId` (from `problems.requestId`, a valid `x-request-id` header, or a random UUID) and `instance`. Its `type` is the kebab-case slug of the code, under `problems.typeBase`.
+  - Errors as values: a handler, a flow step, `UnitOfWork.run()` or a `@Transactional()` method that returns a DomainError rolls back and sends or returns it like a thrown one. `Commands.execute()` and `Queries.ask()` return the DomainError that refused the call, and a returned error joins the route's response type for typed clients.
+
+- [#20](https://github.com/na2axl/elysiumjs/pull/20) [`87299fd`](https://github.com/na2axl/elysiumjs/commit/87299fd9da82d1a408ced1891c0c3d42991444e5) Thanks [@na2axl](https://github.com/na2axl)! - The framework event bus is `Lifecycle`: `Lifecycle.on`, `Lifecycle.once`, `Lifecycle.emit`, `Lifecycle.off`, `@Lifecycle.on()` and `@Lifecycle.once()`, with the `LifecycleEvent` and `LifecycleHandler` types. It carries the framework's own signals (`elysium:error`, app and server lifecycle, heracles queue events) and in-process listeners.
+
+- [#22](https://github.com/na2axl/elysiumjs/pull/22) [`bee66bd`](https://github.com/na2axl/elysiumjs/commit/bee66bdc874b8f23fea356f7d3adf7555a48ca64) Thanks [@na2axl](https://github.com/na2axl)! - Decorators take their main identifier first and their options second.
+
+  - `@Http.controller(path, options)` and the route decorators `@Http.get(path, options)`, `post`, `put`, `patch`, `del`, `head`, `options`, `trace` and `sse`. The path defaults to `/`. `@Http.custom(method, path, options)` takes its method first. The options are `HttpControllerOptions` and `HttpRouteOptions`.
+  - `@Websocket.controller(path, options)`, where the options are those of the websocket server.
+  - `@Flow.controller(name, options)`, and `@Flow.step(name, options)` or `@Flow.step(options)` for a step named after its method.
+  - `@Lifecycle.on(event, options)` and `@Lifecycle.once(event, options)`, like their function forms `Lifecycle.on(event, handler)`.
+  - The styx controller stubs generate the same forms.
+
+- [#10](https://github.com/na2axl/elysiumjs/pull/10) [`0057b67`](https://github.com/na2axl/elysiumjs/commit/0057b67df0e3abecab8a9accff6b55a6a64c21df) Thanks [@na2axl](https://github.com/na2axl)! - `styx routes:generate` writes the route types of an app to `src/routes.gen.ts`: an `AppRoutes` type for Eden (`treaty<AppRoutes>(url)`), built from the controllers of every module. Request types come from the method parameters decorated with `@Http.param`, `@Http.query` and `@Http.body`, and response types from the method return types. The file holds types only; requests are served by the decorated controllers. New projects run the command in their `typecheck` script and keep the file out of git.
+
+  `Http.describe(controller)` reports the routes of an HTTP controller, and `Application.moduleGraph()` builds the module graph of an app class without booting it.
+
+- [#11](https://github.com/na2axl/elysiumjs/pull/11) [`632d77b`](https://github.com/na2axl/elysiumjs/commit/632d77b561fc43ade605fb69b06ac1b9b9a2ffc4) Thanks [@na2axl](https://github.com/na2axl)! - Services are identified by their class, or by the name given to `@Service.register({ name })`. Class names are never used as identifiers, so services resolve the same way in minified builds; `bun run check:minified` in core bundles a minified app and checks that every service resolves. `@Service.inject()` without an argument injects the class of the parameter type, and throws when the type is unknown. Factory services in a module's `services` take a class or a name in `name`.
+
+  `ServiceScope.REQUEST` gives one instance per HTTP request, shared by the request's middlewares, controller and handler. `Service.runInRequestScope(fn)` opens a request scope outside a route. Resolving a request-scoped service outside a request throws `OutsideRequestScopeError`, and a singleton (or a server-scoped controller) depending on one throws `ScopeMismatchError`.
+
+  `HermesModule` registers the logger by the `HermesLogger` class and as `logger`.
+
+- [#13](https://github.com/na2axl/elysiumjs/pull/13) [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d) Thanks [@na2axl](https://github.com/na2axl)! - Hardening of the runtimes, the container and the CLI, checked by a conformance suite that runs on Bun, Node.js and workerd.
+
+  Breaking changes:
+
+  - `Runtime` gains the required `argv()`, `write(stream, text)` and `terminal()` members: core reaches the host's arguments, output streams and terminal only through the runtime. Custom runtimes must implement them.
+  - The third parameter of `InteractsWithConsole.write` is now `'stdout' | 'stderr'`.
+  - The WebSocket options are narrowed to `idleTimeout`, `maxPayloadLength` and `perMessageDeflate`, and the `bun` WebSocket types are replaced by `ElysiumWebSocket`.
+  - Redis connections are `RedisConnection`s, a port any Redis client can implement, instead of `Bun.RedisClient`.
+  - `styx create @scope/name` creates the project in `name/`, and refuses project and module names with upper-case letters.
+  - Queue handlers no longer reject the batch: after the handlers ran, each message is acked or retried on its own. `@Workers.queue(name, { each: true })` receives one message at a time, so a failure retries only that message.
+
+  Fixes:
+
+  - Request-scoped services are destroyed when the request ends, also on failure, and an async `onInit` is awaited. A second dispose of a request scope waits for the one in progress, so a Worker's `waitUntil` covers an async `onDestroy`.
+  - A failed module or service `onInit` no longer breaks later requests: the boot is retried, and the module's event listeners are unwired.
+  - `@elysiumjs/runtime-node` serves through `node:http`, keeping the Host header authoritative.
+  - `styx create` validates names before creating files, ships `.gitignore`, declares the dependencies of created projects and imports their default controllers.
+
+- [#14](https://github.com/na2axl/elysiumjs/pull/14) [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4) Thanks [@na2axl](https://github.com/na2axl)! - The request pipeline: problem details, exception filters, interceptors, typed configuration, HTTP security options and an HTTP test client, checked on Bun, Node.js, workerd and AOT-compiled Workers.
+
+  Breaking changes:
+
+  - Error responses are RFC 9457 problem details (`application/problem+json`). Request validation errors answer 422 with an `errors` list of JSON pointers (`problems.validationStatus: 400` keeps 400). Server errors only show their message and stack in development. Thrown statuses (`c.status(...)`) are sent as they are.
+  - Client errors (4xx) are no longer reported to `onError`, the `elysium:error` event or the trace.
+  - `Runtime.serve` may return a handle with `close()`, which the application calls on shutdown.
+  - Request bodies are limited to 1 MiB by default (`http.bodyLimit`), also when chunked.
+  - The environment schema is validated when the app is built or run, with every error reported at once, instead of in the constructor.
+
+  Features:
+
+  - `DomainError`, with `status`, `type`, `title`, `detail` and extensions, and shortcuts such as `DomainError.notFound()`.
+  - Exception filters (`@Catch()`, `filters` on routes, controllers, modules and the app) and interceptors (`interceptors` on the same levels), with `TimingInterceptor`, `TransformInterceptor` and mnemosyne's `CacheInterceptor`.
+  - Typed configuration: `Secret` values, module `envSchema`s merged into the app's, `InvalidEnvironmentError`.
+  - `http` options: CORS, security headers, body limits and trusted proxies (`ctx.ip`). Runtimes report the client address through `clientAddress`.
+  - `createTestingHttpApp` and `createHttpClient` send requests to an app in memory, with `expectStatus()`.
+
+  Fixes:
+
+  - App-level `onRequest` middlewares run in the request scope.
+  - On Workers, the request scope of a streamed response is disposed when the body ends, not when `fetch` returns.
+  - `KeyvWorkersKV.clear()` stays within an operation budget (`maxOperations`).
+  - The Node.js bridge treats a destroyed socket as a client abort.
+  - Heracles performance metrics report through the Redis port (`connection` or `client`), not a Bun client.
+  - `styx routes:generate` names anonymous default controllers after their file; `styx create` pins `@elysiumjs/*` packages to the versions it was released with; invalid names are reported as Elysium errors.
+
+- [#15](https://github.com/na2axl/elysiumjs/pull/15) [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88) Thanks [@na2axl](https://github.com/na2axl)! - Resources, queries, units of work and rate limits.
+
+  Breaking:
+
+  - A route with a `response` schema serializes its handler result through it: fields the schema does not declare are dropped, a `Date` becomes an ISO string (`YYYY-MM-DD` for `format: 'date'`), and an object with `toJSON()` becomes what it returns. Set `serialize: false` on a route to send the result as it is.
+
+  Added:
+
+  - `Resource.hidden(schema)` marks a field that never reaches responses nor the OpenAPI document. `Resource.serialize()` and `Resource.project()` are exported for use outside routes.
+  - Sparse fieldsets: `?fields=id,title` keeps only those fields of an object, of each item of an array, or of each item of a `data` array. An unknown or hidden field answers a 400 problem.
+  - Rate limits with `@RateLimit({ window, max, key?, store?, name? })` on routes and controllers (`@RateLimit(false)` turns one off), and a default limit and store in the app's `rateLimit` option, with fixed windows. Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`; a client over the limit gets a 429 problem with `Retry-After`. Counts are kept by a `RateLimitStore`: `MemoryRateLimitStore` (core), `RedisRateLimitStore` (`@elysiumjs/redis`) or `WorkersRateLimitStore` over a Cloudflare rate limiting binding (`@elysiumjs/runtime-workers`), which only decides whether a hit is over the limit, so its responses carry no `RateLimit-Reset`.
+  - `ModelResource(model, { hidden, pick, omit, extend })` (`@elysiumjs/mnemosyne`) builds a response schema from a model.
+  - `Query.define(model, spec)` declares the filters (`filter[field][op]=value`), sorts, page size and cursor a list accepts; `Query.schema()` gives its query schema, `Query.parse()` turns a request query into a `ParsedQuery` and answers a 400 problem with a pointer per mistake, and `Query.page()` / `Query.pageSchema()` build cursor pages (`{ data, nextCursor }`).
+  - `DrizzleRepository.list(query)` and `count(query)` run a `ParsedQuery` with keyset pagination (`@elysiumjs/mnemosyne-drizzle`), and `compileQuery()` gives its `where` and `orderBy`.
+  - Units of work: `UnitOfWork.run()` and the `@Transactional()` method decorator run work in one transaction, and `UnitOfWork.afterCommit()` / `afterRollback()` defer work, such as sending a message, until the outermost transaction has ended. `transactional` routes open a unit of work too.
+
+- [#16](https://github.com/na2axl/elysiumjs/pull/16) [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576) Thanks [@na2axl](https://github.com/na2axl)! - Redis, databases, logs, jobs and builds on Bun, Node.js and Cloudflare Workers.
+
+  Breaking:
+
+  - The level shortcuts of `InteractsWithConsole` (`info`, `success`, `warning`, `error` and `debug`) write a tag (`[I]`, `[S]`, `[W]`, `[E]` and `[D]`, in color) before the message, which `InteractsWithConsole.useTags()` changes. `trace()` writes to stderr.
+  - Outside Bun, a Drizzle connection needs a `driver`. Without one, the `connection` and `client` props are a Bun SQL connection, which is only available on Bun; elsewhere the connection throws `MissingDriverError`, which names the drivers.
+
+  Added:
+
+  - Redis adapters (`@elysiumjs/redis`): `ioredis(create)` plugs an ioredis client into the Redis port on Node.js, and `upstash({ token, url?, fetch? })` talks to Upstash over its REST API, for Workers (no pub/sub). `bunRedis` explains which adapter to use when it runs outside Bun.
+  - Drizzle drivers (`@elysiumjs/mnemosyne-drizzle`): a `DrizzleDriver` port set with the `driver` prop of a connection, and drivers on subpaths so that only the chosen database client is imported: `/bun-sql` (`bunSql()`), `/postgres-js` (`postgresJs()`), `/node-postgres` (`nodePostgres()`) and `/hyperdrive` (`hyperdrive({ binding, driver })`, a client per Worker invocation over a Cloudflare Hyperdrive binding). `DrizzleModule` closes connections through their driver, and `migration:run` runs on any driver.
+  - `InteractsWithConsole.write()` and `Runtime.write()` take the level of the line (`OutputLevel`), which the level shortcuts pass. On Cloudflare Workers, a line is written with the console method of its level, so Workers Logs keep it.
+  - `JsonConsoleLogger` (`@elysiumjs/hermes`): JSON lines through the console of the runtime (warnings and errors on stderr), with levels, error serialization and `child()`. `HermesModule.with({ transport: 'console' | 'pino' })` picks it, and it is the default on Workers. `RequestLogInterceptor` writes one structured line per request: method, route, status, duration, client address and request id.
+  - Scheduled jobs (`@elysiumjs/heracles`): `@Schedule(cron, { timezone, args })` on a job class, a five-field cron parser (`Cron`, with lists, ranges, steps and names), and a `Scheduler` that dispatches the jobs on time on Bun and Node.js, taking a Redis lock per tick when a Redis connection is set. The `heracles:schedule` command runs it.
+  - `@elysiumjs/heracles-workers`: `CloudflareQueueTransport` sends jobs to a Cloudflare Queue (dispatch delays become `delaySeconds`), and `HeraclesWorkersModule` consumes them in the Worker's `queue` handler (ack on success, retry with a delay up to the job's retries) and dispatches the `@Schedule()` jobs whose expression is the cron of a trigger.
+  - Queue handlers (`@elysiumjs/runtime-workers`) can settle a message themselves with `ack()` or `retry({ delaySeconds })`; the messages they leave are acked when no handler failed on them.
+  - `styx build --target node` (`@elysiumjs/hephaestus`) bundles the app into one ES module for Node.js, with decorator metadata emitted at build time, run with `node dist/server.js serve`. `styx build --target workers` runs from the CLI, resolves packages to their browser entry, and leaves Node.js modules imported by bare names to workerd (`nodejs_compat`).
+  - `styx create` (`@elysiumjs/styx`) takes `--runtime bun|node|workers`, `--database`, `--cache` and `--package-manager bun|npm|pnpm`. Each runtime gets its entry, tsconfig types, scripts and drivers: postgres.js and ioredis on Node.js; Hyperdrive, Upstash, console logs and a `wrangler.jsonc` on Workers.
+
+- [#12](https://github.com/na2axl/elysiumjs/pull/12) [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b) Thanks [@na2axl](https://github.com/na2axl)! - `createWorker(app)` from `@elysiumjs/runtime-workers` builds an application and returns the handlers a Cloudflare Worker exports: `fetch` serves the routes, `queue` hands each batch to the service methods marked `@Workers.queue(name)`, and `scheduled` calls the methods marked `@Workers.cron(expression)`. Each invocation runs with its own env and execution context: `Workers.env()`, `Workers.context()` and `Workers.binding(name)` read them, and `WorkersModule` provides them, and the bindings it lists, as request-scoped services injected with `@Workers.inject(name)`. `KeyvWorkersKV` stores mnemosyne caches in a KV namespace. `bun run check:wrangler` runs a sample Worker in `wrangler dev`.
+
+  `MnemosyneModule` takes other Keyv stores in `cache.stores`, read with `Cache.store(name)`.
+
+  `styx build --target workers` (Hephaestus `hephaestus:build --target workers`, `WorkersBuilder`) bundles a Worker with its routes compiled ahead of time and refuses a bundle that generates code at runtime.
+
+  In core, `Application.boot()` initialises the modules once, for hosts that handle more than requests; `Kernel.serviceClasses(node)` lists the service classes of a module; console output falls back to `console` where the host has no output streams; and a singleton depending on a request-scoped service throws `ScopeMismatchError` even when it is built outside a request.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -19,7 +19,7 @@ bun install @elysiumjs/core
 - WebSocket support
 - WAMP protocol integration
 - Command-line interface (`@elysiumjs/styx`), with support for custom commands
-- Event system
+- Lifecycle events
 - Caching (memory and Redis)
 - PostgreSQL database support with Drizzle ORM
 - Model classes and repositories for database interactions
@@ -33,9 +33,9 @@ Create a controller class:
 ```typescript
 import { Http } from '@elysiumjs/core';
 
-@Http.controller({ path: '/users' })
+@Http.controller('/users')
 export class UserController {
-	@Http.get({ path: '/:id' })
+	@Http.get('/:id')
 	public getUser(id: string) {
 		return { id };
 	}
@@ -103,6 +103,40 @@ Or, if using `styx`, run:
 bun styx serve
 ```
 
+## Services
+
+A service is identified by its class. Give it a name with `@Service.register({ name })` to look it up by that string instead. Class names are never used as identifiers, so services resolve the same way after a bundler renames classes (`bun run check:minified` builds a minified app and checks it).
+
+```typescript
+import { Service, ServiceScope } from '@elysiumjs/core';
+
+@Service.register()
+export class UserRepository {}
+
+@Service.register({ name: 'mailer' })
+export class MailerService {}
+
+@Service.register()
+export class UserService {
+	constructor(
+		@Service.inject(UserRepository) private readonly users: UserRepository,
+		@Service.inject('mailer') private readonly mailer: MailerService
+	) {}
+}
+```
+
+`@Service.inject()` without an argument injects the class of the parameter type, read from `emitDecoratorMetadata`. Pass the class or the name when the type is an interface or is missing; Elysium throws at declaration time when it cannot tell which service to inject.
+
+A service has one of three scopes:
+
+| Scope                    | Instances                                                   |
+| ------------------------ | ----------------------------------------------------------- |
+| `ServiceScope.SINGLETON` | One for the app (the default)                               |
+| `ServiceScope.FACTORY`   | A new one each time the service is resolved                 |
+| `ServiceScope.REQUEST`   | One per HTTP request, shared by its middlewares and handler |
+
+A request-scoped service resolves only inside a request: resolving it elsewhere throws `OutsideRequestScopeError`. Code outside a route, such as a job or a test, opens a scope with `Service.runInRequestScope(fn)`; every request-scoped service resolved inside `fn`, including after an `await`, is shared for that run. A singleton, or a controller with the default server scope, cannot depend on a request-scoped service, since it would keep the first request's instance: Elysium throws `ScopeMismatchError`. Use a request-scoped controller (`scope: HttpControllerScope.REQUEST`), or inject the service in the route handler's parameters.
+
 ## Lazy boot
 
 A CLI command boots lazily: running `app:cmd` initialises the command's own module and the modules it imports, not the whole graph. `help <cmd>` is always lazy, even for commands with `static boot = true`.
@@ -112,9 +146,33 @@ A CLI command boots lazily: running `app:cmd` initialises the command's own modu
 - **Use `static boot = true`** on a command that needs every module initialised before it runs (workers, servers). It initialises every module and builds every service first.
 - Service factories receive a synchronous `get`; it may only read services whose owning modules initialise synchronously, otherwise it throws `ServiceNotReadyError`.
 
+## Runtimes
+
+Core never calls a host API directly. Environment variables, timers, the HTTP server, process exit and shutdown signals come from a runtime, which ships as its own package:
+
+| Package                      | Exports                             | Notes                                                                                                     |
+| ---------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@elysiumjs/runtime-bun`     | `runtime`                           | `Bun.env`, `Bun.sleep`, `listen`, process exit and signals                                                |
+| `@elysiumjs/runtime-node`    | `runtime`                           | Same on Node.js; set `server: { adapter: node() }` from `@elysiajs/node`                                  |
+| `@elysiumjs/runtime-workers` | `runtime`, `createRuntime({ env })` | Env from `process.env` (`nodejs_compat`) or `env`; no `serve` (export the app's `fetch`), exit or signals |
+
+Each package exports `runtime` (rename it at import if you like). Pass it to the application, or call `Runtime.use()` before anything needs it:
+
+```ts
+import { Application } from '@elysiumjs/core';
+import { runtime } from '@elysiumjs/runtime-bun';
+
+@Application.register({ runtime, modules: [] })
+class App extends Application {}
+```
+
+Without a runtime, `Runtime.get()` throws `RuntimeNotConfiguredError`; only the environment name falls back to `development`. `bun run check:runtime` bundles core, fails if it touches the `Bun` global, and boots an application from the bundle under Node.js.
+
 ## Migrating from the pre-module API
 
 - The `database`, `redis`, `wamp` and `elysium:hermes` keys of `@Application.register()` are gone. Add `DrizzleModule.with()`, `RedisModule.with()`, `WampModule.with()` and `HermesModule.with()` to `modules` instead.
+- `Redis` and `RedisModule` moved to `@elysiumjs/redis`.
+- An application needs a runtime: add `runtime` from `@elysiumjs/runtime-bun` to `@Application.register()`.
 - `plugins` no longer takes package plugins. Add the package's module (for example `SentryModule`) to `modules`.
 - Importing a file no longer registers its commands or services. List commands in a module's `commands`, services in `services`, and jobs in `jobs`.
 - `new App()` is replaced by `await App.start()`. `Application.testing()` boots a module graph for tests.

package/dist/app.d.ts

@@ -1,8 +1,16 @@
-import type { ElysiaOpenAPIConfig } from '@elysiajs/openapi';
-import type { AnyElysia, ElysiaConfig, ErrorContext, TSchema } from 'elysia';
+import type { ElysiaOpenAPIConfig } from '@elysia/openapi';
+import type { AnyElysia, ErrorContext } from 'elysia';
+import type { TSchema } from 'typebox';
+import type { FilterClass } from './filter';
 import type { Route } from './http';
+import type { InterceptorClass } from './interceptor';
 import type { ConfiguredModule, ModuleClass } from './module';
-import type { TestingApp, TestingOptions } from './testing';
+import type { ModuleGraph } from './module-graph';
+import type { ProblemOptions } from './problem';
+import type { AppRateLimitOptions } from './rate-limit';
+import type { Runtime as RuntimePort } from './runtime';
+import type { HttpOptions } from './security';
+import type { TestingApp, TestingAppOptions, TestingHttpApp, TestingOptions } from './testing';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Elysia } from 'elysia';
 import { InteractsWithConsole } from './console';
@@ -24,12 +32,18 @@ export type AppProps = {
     /**
      * The Elysia server configuration.
      */
-    server?: ElysiaConfig<Route> & {
+    server?: ElysiaConfig & {
         /**
          * The port to listen on.
          */
         port?: number;
     };
+    /**
+     * The runtime the application runs on, from `@elysiumjs/runtime-bun`, `@elysiumjs/runtime-node`
+     * or `@elysiumjs/runtime-workers`. Can be omitted when `Runtime.use()` was called before.
+     * The runtime is process-wide: when several applications are constructed, the last one wins.
+     */
+    runtime?: RuntimePort;
     /**
      * The modules the application is made of. They act as the imports of the root module.
      */
@@ -39,7 +53,7 @@ export type AppProps = {
      *
      * Set it to `false` to disable OpenAPI documentation.
      */
-    openapi?: ElysiaOpenAPIConfig | false;
+    openapi?: ElysiaOpenAPIConfig<boolean, string> | false;
     /**
      * The validation schema for the application environment.
      */
@@ -48,6 +62,39 @@ export type AppProps = {
      * The list of plugins to load.
      */
     plugins?: ElysiumPlugin[];
+    /**
+     * How errors are rendered as RFC 9457 problem details: the base of relative problem types, and
+     * the status of validation errors.
+     */
+    problems?: ProblemOptions;
+    /**
+     * Exception filters for every request, run after the filters of the route, the controller and
+     * the module, and before the default problem details rendering.
+     */
+    filters?: FilterClass[];
+    /** Interceptors around every request handler, outside those of the modules. */
+    interceptors?: InterceptorClass[];
+    /**
+     * HTTP security: CORS, security headers, the request body limit (1 MiB by default) and the
+     * trusted proxies that give `ctx.ip`.
+     */
+    http?: HttpOptions;
+    /**
+     * Rate limiting: the store of every limit (in memory by default), and a limit for every route
+     * whose controller and route set none, when `window` and `max` are given.
+     */
+    rateLimit?: AppRateLimitOptions;
+};
+/** The options of the root Elysia app. */
+type ElysiaConfig = NonNullable<ConstructorParameters<typeof Elysia>[0]>;
+/**
+ * An error raised while handling a request, as given to the Elysia error hook. `code` is set for
+ * the errors Elysia raises ('validation', 'not-found', ...).
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ServerError = ErrorContext & {
+    code?: string;
+    error: any;
 };
 /**
  * Type for the application context.
@@ -57,9 +104,11 @@ export type AppProps = {
  * - `db:transactions`: the open database transactions, keyed by the connection they run on.
  * - `db:tx`: the transaction open on the default database connection. Kept for existing callers;
  *   prefer `db:transactions`.
+ * - `uow:frame`: the outermost unit of work, which collects the hooks run after it commits or
+ *   rolls back (`@elysiumjs/mnemosyne`).
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type AppContext = AsyncLocalStorage<Map<'tenant' | 'http:context' | 'db:transactions' | 'db:tx', unknown>>;
+export type AppContext = AsyncLocalStorage<Map<'tenant' | 'http:context' | 'db:transactions' | 'db:tx' | 'uow:frame', unknown>>;
 /**
  * Base class for the application main entry.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -91,10 +140,13 @@ export declare abstract class Application extends InteractsWithConsole {
      */
     static start<T extends Application>(this: new () => T): Promise<void>;
     /**
-     * Boots a module graph without a CLI or an HTTP server, for tests.
-     * @param options The modules to boot, service overrides, environment and boot mode.
+     * Sets up code under test. Given `app`, builds that application and returns an HTTP client that
+     * drives it in memory (`http.get('/x').send()`). Given `modules`, boots a module graph without a
+     * CLI or an HTTP server.
+     * @param options The application or the modules, service overrides, environment and boot mode.
      * @author Axel Nana <axel.nana@workbud.com>
      */
+    static testing(options: TestingAppOptions): Promise<TestingHttpApp>;
     static testing(options: TestingOptions): Promise<TestingApp>;
     /**
      * The kernel running this application's module graph. Available once `run()` has started.
@@ -118,7 +170,7 @@ export declare abstract class Application extends InteractsWithConsole {
      * @param _error The error context.
      * @returns Whether to continue the error propagation.
      */
-    protected onError(_error: ErrorContext): Promise<boolean>;
+    protected onError(_error: ServerError): Promise<boolean>;
     /**
      * Hook that is executed when the application starts.
      * @param _elysia The Elysia instance.
@@ -135,8 +187,15 @@ export declare abstract class Application extends InteractsWithConsole {
      * @param argv The command line arguments, without the executable and script.
      * @author Axel Nana <axel.nana@workbud.com>
      */
-    run(argv?: string[]): Promise<void>;
+    run(argv?: readonly string[]): Promise<void>;
     private props;
+    /**
+     * Builds the module graph of an application class without creating or booting anything.
+     * Used by tools that read the app's structure, such as the route type generator.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param environment The environment to build the graph for. Defaults to the current one.
+     */
+    static moduleGraph(environment?: string): ModuleGraph;
     private dispatch;
     /** Prints an error, shuts down what was started and exits with code 1. */
     private fail;
@@ -166,18 +225,65 @@ export declare abstract class Application extends InteractsWithConsole {
      */
     private commandExec;
     /**
-     * Starts the server: boots the kernel, builds the root Elysia app, lets modules hook into it,
-     * mounts their controllers and listens.
+     * Builds the root Elysia app without listening, for hosts that own the server (Cloudflare
+     * Workers) and for ahead-of-time compilation with `elysia/plugin/aot`, which evaluates the
+     * entry at build time.
+     *
+     * Modules are registered but not initialised: they boot on the first request, so building the
+     * app runs no `onInit` work and builds no service.
+     *
+     * @example
+     * ```ts
+     * export const app = await new App().build();
+     * export default { fetch: (request: Request) => app.fetch(request) };
+     * ```
+     * @returns The root Elysia app.
+     * @throws When the module graph is invalid or a module config is missing.
+     */
+    build(): Promise<Elysia<Route>>;
+    /**
+     * Validates the environment against the schemas of the app and its active modules, then makes
+     * the validated values available through `Env.get()`.
+     * @throws {InvalidEnvironmentError} Listing every missing or invalid variable.
+     */
+    private configureEnvironment;
+    /**
+     * Initialises every module and builds every singleton service, once. An app from
+     * {@link build} calls it on its first request; hosts call it before other work, such as a
+     * queue batch or a scheduled event.
+     * @throws When a module or a singleton fails to initialise. Later calls retry the failed ones,
+     * so that a transient failure does not break every later request. A permanent failure is
+     * retried, and fails, on every request.
      */
+    boot(): Promise<void>;
+    /** Starts the server: boots the kernel, builds the root Elysia app and listens. */
     private commandServe;
+    /**
+     * Builds the root Elysia app: lets modules hook into it and mounts their controllers.
+     * @param bootOnFirstRequest Whether the first request boots the modules, when they were only
+     * registered.
+     */
+    private buildServer;
+    /** Maps each route of the built server to the filter levels of its handler. */
+    private indexRouteFilters;
     /** Lets every module hook into the root app, then mounts the controllers of each module. */
     private serveModules;
     /** Builds the Elysia plugin of a module: its middlewares and the plugins of its controllers. */
     private mountModule;
     /** Registers the error handler and the start and stop hooks of the root app. */
     private setupServerHooks;
-    /** Turns an error raised while handling a request into the response sent to the client. */
+    /**
+     * Turns an error raised while handling a request into the response sent to the client: a
+     * thrown status as is, anything else as problem details. Only server errors are reported
+     * (`onError`, the `elysium:error` event and the trace); client errors are part of normal
+     * operation.
+     */
     private handleServerError;
+    /**
+     * Reports a server error: calls `onError`, emits `elysium:error` and traces it.
+     * @returns `false` when `onError` handled the error itself.
+     */
+    private reportError;
     /**
      * Describes the CLI and available commands.
      */
@@ -185,3 +291,4 @@ export declare abstract class Application extends InteractsWithConsole {
     private commandList;
     private commandDescription;
 }
+export {};

package/dist/config.d.ts

@@ -0,0 +1,74 @@
+import type { TObject, TSchema } from 'typebox';
+import type { ModuleGraph } from './module-graph';
+import { t } from 'elysia';
+import { ElysiumError } from './errors';
+/**
+ * A value that must not leak: it prints as `[secret]` in logs, `JSON.stringify`, string
+ * conversion and error messages. Read it with `reveal()`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template T The type of the value.
+ */
+export declare class Secret<T = string> {
+    #private;
+    constructor(value: T);
+    /** The secret value. Pass it where it is used, never to a log. */
+    reveal(): T;
+    toString(): string;
+    toJSON(): string;
+    /**
+     * Marks an environment variable as a secret: once validated, it is read as a `Secret` from
+     * `Env.get()`.
+     * @param schema The schema of the value. Defaults to a string.
+     * @example
+     * ```ts
+     * @Application.register({ env: t.Object({ DATABASE_URL: Secret.schema() }) })
+     * ```
+     */
+    static schema<S extends TSchema = ReturnType<typeof t.String>>(schema?: S): S;
+    /** Whether a schema was made by {@link Secret.schema}. */
+    static isSchema(schema: unknown): boolean;
+}
+/**
+ * One missing or invalid environment variable.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type EnvironmentIssue = {
+    key: string;
+    message: string;
+};
+/**
+ * Thrown at boot when environment variables are missing or invalid. It lists every issue, and
+ * never the values.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class InvalidEnvironmentError extends ElysiumError {
+    readonly issues: EnvironmentIssue[];
+    constructor(issues: EnvironmentIssue[]);
+}
+/**
+ * Thrown when two schemas declare the same environment variable differently.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ConflictingEnvironmentSchemaError extends ElysiumError {
+    readonly key: string;
+    readonly owners: [string, string];
+    constructor(key: string, owners: [string, string]);
+}
+/**
+ * Merges the environment schema of the app with those of the active modules (`envSchema`).
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param appSchema The `env` option of the application.
+ * @param graph The module graph, or `null` for the app schema alone.
+ * @throws {ConflictingEnvironmentSchemaError} When two schemas declare a key differently.
+ */
+export declare const mergeEnvironmentSchemas: (appSchema: TSchema | undefined, graph: ModuleGraph | null) => TObject | undefined;
+/**
+ * Validates environment variables against a schema: applies defaults, converts strings to the
+ * declared types, keeps only the declared keys and wraps secrets.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param schema The merged schema.
+ * @param raw The variables from the runtime.
+ * @returns The validated variables.
+ * @throws {InvalidEnvironmentError} Listing every missing or invalid variable.
+ */
+export declare const validateEnvironment: (schema: TObject, raw: Record<string, unknown>) => Record<string, unknown>;