@elysiumjs/core 0.7.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # @elysiumjs/core
 
+## 0.10.0
+
+### Minor Changes
+
+- [`68a0cdd`](https://github.com/na2axl/elysiumjs/commit/68a0cdd8b2e4a003d6e0af2d78985623cae40428) Thanks [@na2axl](https://github.com/na2axl)! - Route the framework's own diagnostics through the logger service.
+
+  Breaking changes:
+
+  - `@Event.listen()` with a mode other than `on` or `once` now throws an `ElysiumError` when the class is defined, instead of logging to the console and ignoring the listener.
+
+  Fixes and additions:
+
+  - `getLogger(context?)` and `LOGGER_SERVICE` (`'logger'`) are exported by `@elysiumjs/core`. `getLogger()` returns the `logger` service when one is registered (such as the one `HermesModule` provides), and a `ConsoleLogger` otherwise or when the service cannot be built or fails to create a child logger. It is resolved at call time from the global scope only, so a module's own `logger` service does not replace it, and returns a child logger bound to `context` when one is given.
+  - `Middleware.logger` (used by `RequestLoggerMiddleware`) falls back to a `ConsoleLogger` when no `logger` service is registered. It threw before.
+  - Core diagnostics go through the logger with structured context instead of `console.*`: the debug-mode request log (`debug`, with `method` and `url`), `onDestroy` failures on shutdown (`error`, with `target` and `error`), WAMP connection attempts (`warn` while retrying, `error` when giving up, with `connection`, `attempt`/`attempts`, `maxRetries` and `error`), and WAMP registrations and subscriptions (`info`, with `connection`, `topic` and the registration or subscription id).
+  - In debug mode, incoming requests are logged through the logger at `debug` level instead of printed with `console.log`. With `HermesModule`, they show only when its `level` is `debug` or `trace`.
+  - A failed WAMP registration or subscription is logged at `error` level and emitted as `elysium:error` with an error naming the topic and the connection, instead of becoming an unhandled rejection.
+  - The `elysium:error` emitted for a WAMP client error names the connection and its URL and includes the client's message (or the value it reported, when it is not an `Error`), with that value as `cause` when there is one.
+  - `HermesLogger` serialises an `error` field of the log context like pino's `err` (type, message and stack), so logged errors keep their stack trace. Elysium logs errors under `error`.
+  - `@Logged` resolves its fallback logger with `getLogger()`, and logs a thrown error whole under `error` (it logged only its message), so its stack trace is kept.
+  - The `elysium:error` emitted when a WAMP connection gives up states the number of attempts actually made (the first one plus the retries), as the logged `attempts` does. It stated `maxRetries` before.
+
+- [`76ba0ff`](https://github.com/na2axl/elysiumjs/commit/76ba0ff18f3c196cebc2189426328f67cb699f46) Thanks [@na2axl](https://github.com/na2axl)! - `onRequest` middlewares registered on a module or a controller now run only for its routes. Elysia runs `onRequest` hooks on every request of the app, so such a middleware could reject requests meant for other modules.
+
+  They now run in the transform step of their own routes, so after routing and body parsing, and each one runs right before its own `onTransform`: module `onRequest`, module `onTransform`, then controller `onRequest`, controller `onTransform`. Any value they return still stops the request and is sent as the response. Application middlewares still run `onRequest` before routing, for every request.
+
+- [`bacce71`](https://github.com/na2axl/elysiumjs/commit/bacce7146f667a1a46bf474dc0344fb0111ae12a) Thanks [@na2axl](https://github.com/na2axl)! - WebSocket controllers now run the middlewares registered on them with `@Middleware.register()`, on the upgrade request. `onRequest`, `onTransform` and `onBeforeHandle` can refuse the connection by returning a response. `onAfterHandle` and `onAfterResponse` run after the upgrade, with no response to read.
+
+### Patch Changes
+
+- [`2c49acd`](https://github.com/na2axl/elysiumjs/commit/2c49acd3b552aa43765d70339fa216961499e1b5) Thanks [@na2axl](https://github.com/na2axl)! - The tenant set by a middleware, such as a `TenantMiddleware` reading its own header, is no longer replaced by the `x-tenant-id` header (or `public`) before the handler runs.
+
+- [`4ebf029`](https://github.com/na2axl/elysiumjs/commit/4ebf029611e6d753a4f1bfdbe247a75d954d9ded) Thanks [@na2axl](https://github.com/na2axl)! - WAMP clients use Bun's own `WebSocket` again. The subclass that faked the `protocol` field is gone, since Bun now fills it (oven-sh/bun#18744).
+
+## 0.9.0
+
+### Minor Changes
+
+- [`5fef4a7`](https://github.com/na2axl/elysiumjs/commit/5fef4a7199f502fc4fe035299e7670739459a108) Thanks [@na2axl](https://github.com/na2axl)! - Fix tenant isolation, transactions and query caching in the database layer.
+
+  Breaking changes:
+
+  - `TenantMiddleware.validateTenant()` now rejects every tenant unless you override it, and tenant identifiers must match `TENANT_ID_PATTERN` (1 to 63 ASCII letters, digits, `_` or `-`, not starting with `pg_` and other than `information_schema`, in any case) before it is called. Requests that send any other tenant now fail with `Invalid tenant`. Requests without a tenant still resolve to `public` on `SimpleTenantMiddleware`. To migrate, check the tenant against your own data:
+
+    ```ts
+    class OrganizationMiddleware extends SimpleTenantMiddleware {
+    	protected async validateTenant(tenant: string): Promise<boolean> {
+    		return Organization.exists(tenant);
+    	}
+    }
+    ```
+
+  - `getTenantSchema()`, `registerTenantSchema()` and `wrapTenantSchema()` throw on tenant identifiers that do not match `TENANT_ID_PATTERN`.
+  - `setConnectionTenant()` is removed. It set the tenant on a pooled connection for the whole session, so the tenant leaked to other requests. Use `withRLS()`, or `Database.transaction()` in RLS mode, which scope the tenant to a transaction.
+  - `RepositoryInterface.update()` and `delete()`, and the `DrizzleRepository` implementations, return `null` when no row has the id. They returned `undefined` while typed as a row. `DrizzleRepository` also requires a model whose table has an `id` column.
+  - `@transactional` handlers run through the `db.transaction` service that `DrizzleModule` provides (its name is exported by `@elysiumjs/core` as `DATABASE_TRANSACTION_SERVICE`, and still re-exported by `@elysiumjs/mnemosyne`). A transactional handler without a database module now fails with an error naming the service.
+  - `@transactional` generator handlers commit only when the whole stream was sent. A stream closed early, or whose client disconnects (even while the handler is waiting), rolls back.
+  - In RLS mode, a transaction is bound to one tenant for its whole life: the tenant set (with a transaction-local `set_config`) when `Database.transaction()`, a `@transactional` handler, `withRLS()` or `withIsolation()` opens it, from the explicit tenant or the current one (`public` when there is none). Work that finds a transaction open on its connection (`withRLS()`, `withIsolation()`, `Database.transaction()`, repository calls) joins it only when its tenant is the transaction's tenant, and throws `TenantMismatchError` otherwise, without running anything: the tenant of an open transaction never changes. Inside a transaction, `Database.getConnection()` only returns it to work for its tenant (the current tenant, or `public`), and throws `TenantMismatchError` otherwise, so raw queries never run for another tenant; queries on the `tx` handle a callback received run as the transaction's tenant. Work for several tenants, such as an admin fan-out, must use one `withRLS()` per tenant outside any transaction, not nested in one.
+  - In RLS mode, each repository call made outside a transaction runs in its own transaction bound to the current tenant: `BEGIN`, `set_config` of the tenant, the query, `COMMIT`. These calls do not use the query cache, since the cache is bypassed inside transactions. Group calls in `Database.transaction()` or `withRLS()` to share one transaction.
+  - In RLS mode, code running without a tenant in context (background jobs, CLI commands, scripts) is scoped to the `public` tenant. Set the tenant with `withTenant(tenant, () => ...)` around the work (repository calls and `Database.transaction()` then use it), or with `withRLS(tenant, (tx) => ...)`.
+  - `migration:run` validates `--tenant` against `TENANT_ID_PATTERN`. Without a terminal it no longer creates a missing schema: pass `--create-schema` (which also skips the question in a terminal), or it fails.
+  - Query cache keys start with the connection name, and each connection has its own cache transaction scope. When several applications or environments share one cache store and use the same connection names for different databases, set `cache: { prefix }` on each connection: the prefix comes before the connection name in every key (empty by default).
+  - `DrizzleDatabaseCache` keys and values changed: entries written by earlier versions are ignored. The default TTL of cached queries (including with `cache: true`) is now 60 seconds instead of 1 second, and is set with `cache: { ttl }` in seconds.
+  - `Cache.memory` keeps a separate LRU per tag namespace, so `lruSize` applies to each namespace.
+
+  Fixes and additions:
+
+  - In RLS mode, repository operations outside a transaction run in one bound to the current tenant, through the strategy's `withIsolation()`. Transactions opened with `Database.transaction()` or by `@transactional` handlers set the tenant variable when they open. `withIsolation()` and `withRLS()` expose their transaction to repositories and `Database.getConnection()`. `TenantMismatchError` is exported.
+  - `Database.transaction(callback, connection?)` opens a transaction and registers it for the callback. When a transaction is already open on the same connection, the callback joins it (no savepoint: an error rolls back the whole transaction); in RLS mode only if the current tenant is the transaction's tenant (see above). Transactions are tracked by connection, so every name of a connection (`default` and the name it aliases) sees them, and named connections take part in transactions. `Database.getBaseConnection()`, `Database.inTransaction()` and `Database.runInTransaction()` are added. The `db:tx` context entry is still set for the default connection.
+  - `@transactional` generator handlers keep their transaction open until the stream ends, then commit (or roll back if the handler throws). They previously committed before running and failed with `generator.next is not a function`. Generator handlers also see the request context (`tenant`, `http:context`).
+  - The query cache is scoped to the connection and the current tenant, is shared correctly by several app instances (table versions stored in the cache), is not read or written inside transactions, and invalidates the tables a transaction changed once it commits. A result is only stored when no mutation happened since its query started, including when concurrent queries of the same key finish out of order. Cached queries honour Drizzle's `ex`, `px`, `exat`, `pxat` and `keepTtl` options.
+  - Cache namespaces (`Cache.redis.tags(...)`, `Cache.memory.tags(...)`) no longer overwrite each other: reads, deletes and `clear()` stay within their namespace.
+  - `getSessionTenant()` reads the Bun SQL result correctly, and `getCurrentTenant()` works without an application instance (for example under `Application.testing`).
+  - `migration:run` takes an advisory lock per tenant, adds a unique index on `elysium_migrations.name` (also to existing tables), finds the migrations from the project root (`.elysiumrc`), sets the `search_path` for the transaction only, asks before opening the transaction whether to create a missing schema, and always closes its client. Existing duplicate migration names must be removed before the unique index can be created.
+  - `migration:generate` only removes `"public".` qualifiers from the migration it generates, and leaves string literals, comments and dollar-quoted bodies (`DO` blocks, functions) untouched.
+  - `DatabaseDriver.createConnection()` receives the connection name as an optional second argument.
+  - `KeyvRedis` deletes with a single `UNLINK` (or `DEL`) per call or batch and reports failed deletes in `clear()` as `error` events.
+
+## 0.8.0
+
+### Minor Changes
+
+- [`8ac91ab`](https://github.com/na2axl/elysiumjs/commit/8ac91ab676b1119b4eecf0ddb3fd0a3e84017cac) Thanks [@na2axl](https://github.com/na2axl)! - Upgrade dependencies to their latest major versions: wampy 8, zod 4, commander 15, @casl/ability 7, OpenTelemetry SDK 2 (sdk-node 0.300, resources 3), @sentry/bun 11. Generated projects now use TypeScript 7.
+
+  Breaking in `@elysiumjs/mnemosyne-drizzle`: it now requires drizzle-orm 1.0 (release candidate) and generated projects use drizzle-kit 1.0. `ColumnsWithTable` is no longer re-exported. `migration:generate` writes 1.0 migration folders (`<timestamp>_<name>/migration.sql`), and `migration:run` tracks those by folder name while still running flat `*.sql` files. Existing projects can upgrade their migrations folder with `drizzle-kit up`: `migration:run` recognises the moved migrations as already applied and renames their records. The `make:model` stub now generates a `pgTable` and a `DrizzleModel` built from it.
+
+  Breaking in `@elysiumjs/core`: the deprecated `@elysiajs/swagger` plugin is replaced by `@elysiajs/openapi`, and the app option `swagger` is renamed `openapi` (typed `ElysiaOpenAPIConfig | false`). Without a `path`, the docs now live at `/openapi` instead of `/swagger`. The UI options `scalarConfig` and `swaggerOptions` are now `scalar` and `swagger`. Elysia stays on 1.4 (now `^1.4.30`) until Elysia 2 and its OpenAPI plugin are stable.
+
+  Also in `@elysiumjs/core`: the WAMP `onChallenge` callback must return a string (or a promise of one); `null` is no longer accepted. `onError` now receives the error and `onReconnectSuccess` receives wampy's details object. `WampClient` is now wampy's own `Wampy` type. `onOpen` is called by Elysium once the connection is established, since wampy 8 no longer has that callback.
+
+- [`3625883`](https://github.com/na2axl/elysiumjs/commit/3625883dba92f1596e7444ee52f9399d8e9b049f) Thanks [@na2axl](https://github.com/na2axl)! - Drop the `reflect-metadata` dependency. Decorator metadata now lives in a small store in `@elysiumjs/core`, exported as `Metadata` (`define`, `get`, `getOwn`, `has`). Use it instead of `Reflect.defineMetadata` and `Reflect.getMetadata` to read or write Elysium metadata.
+
+  Apps no longer need `import 'reflect-metadata'` in their entrypoint, and generated projects leave it out. Keep `emitDecoratorMetadata` enabled: `@Service.inject()` and `@Command.arg()` still infer types from it. An app that loads `reflect-metadata` for another library keeps working; Elysium also reads the types stored there.
+
+- [`07236b3`](https://github.com/na2axl/elysiumjs/commit/07236b386c2506590d74e8753ce847c1e184b3ee) Thanks [@na2axl](https://github.com/na2axl)! - Introduce the module system. Modules are now the only way to register anything in an Elysium.js app. This is a breaking change with no compatibility layer.
+
+  Breaking changes:
+
+  - `@Module.register()` takes `imports`, `services`, `exports`, `controllers`, `commands`, `jobs`, `prefix` and `env`. Services are private to their module unless exported (or global). The `beforeRegister` and `afterRegister` hooks are replaced by `onInit`, `onServe` and `onDestroy`.
+  - Configurable modules are bound with `with()`, for example `HermesModule.with({ level: 'debug' })`. `with()` accepts an object or a function.
+  - Decorators only record metadata. Importing a file no longer registers commands, services or event wiring, and the side-effect imports of the packages are removed. List commands, jobs and services in the module that owns them.
+  - `@Application.register()` no longer takes `database`, `redis`, `wamp` or `'elysium:hermes'`/`'elysium:cerberus'` keys. Use `DrizzleModule`, `RedisModule`, `WampModule`, `HermesModule` and `CerberusModule`. Package plugins are replaced by modules: add `SentryModule` instead of the `plugin()` function. `plugins` still accepts plain Elysia plugin factories.
+  - Constructing an `Application` no longer runs it. Use `await App.start()`; `Application.testing()` boots a module graph for tests. The `styx` binary loads `src/app.ts` (or `index.ts`) and starts the exported application, so a project entry no longer needs to import commands.
+  - The job system of core (`Job`, `Worker`, `WorkerPool`, `commandWork`) is removed. `@elysiumjs/heracles` is the only job system: extend its `Job`, list jobs in a module's `jobs`, declare queues with `HeraclesModule.with({ queues })`, and dispatch with `Heracles.dispatch()`.
+  - `@elysiumjs/styx` ships `StyxModule`, active in development only. The `migration:generate` and `migration:run` commands move to `DrizzleModule` and are available in production.
+  - `@elysiumjs/mnemosyne` ships `MnemosyneModule` for its caches (`redis: false` or `memory: false` opts out). `DrizzleModule` imports it.
+  - New modules: `HephaestusModule`, `ArgusModule` (`serviceName` is required), `SentryModule` (needs a `dsn` or `SENTRY_DSN`) and `CerberusModule` (`getSubject` is required).
+  - Module and service code throws typed errors (for example `InvalidModuleConfigError`) instead of exiting the process. `Application.run()` prints them and exits; command `run()` methods may still exit, and package plugin factories are unchanged.
+  - `Application.register` merges subclass props over the parent's (own props, then own metadata, then parent, then defaults), and concatenates `modules` parent first. Previously defaults and parent values won, so `openapi` could not be enabled.
+  - `Heracles.dispatch` starts a stopped queue on first use, so producers no longer start queues. `Queue.start()` is idempotent.
+  - `create-elysium` generates apps that use modules, and adds Sentry and Hephaestus to the `modules` list.
+  - `@Event.on`/`@Event.once` method listeners on classes in a loaded module's `services` or `controllers` are wired by the kernel and run in their module's context. Jobs, commands and middlewares are not wired, and an instance listener on a class that is not a service throws `EventListenerNotSupportedError`. Listeners on classes not listed in a loaded module no longer fire.
+  - New typed errors: `CircularDependencyError` (services that depend on each other, in sync and async resolution), `DuplicateModuleNameError` (two different module classes sharing a name; module scopes and config tokens are name based) and `EventListenerNotSupportedError`.
+  - Lazy boot contract: a CLI command initialises only its own module and that module's imports. Sync helpers such as `Database.getConnection()` work when the owning module's `onInit` is synchronous; otherwise they throw `ServiceNotReadyError` naming the module. Use `await Service.resolve()` or set `static boot = true` on the command.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -24,7 +24,7 @@ bun install @elysiumjs/core
 - PostgreSQL database support with Drizzle ORM
 - Model classes and repositories for database interactions
 - Multi-tenancy support enabled
-- Swagger documentation
+- OpenAPI documentation (Scalar or Swagger UI)
 
 ## Usage
 
@@ -42,40 +42,39 @@ export class UserController {
 }
 ```
 
-Create a module class:
+Create a module class. A module is the only way to register anything in an Elysium.js app:
+controllers, commands, jobs and services are all declared by the module that owns them.
 
 ```typescript
 import { Module } from '@elysiumjs/core';
 
 import { UserController } from './controllers/http/user.controller';
+import { UserService } from './services/user.service';
 
 @Module.register({
+	services: [UserService],
 	controllers: [UserController]
 })
-export class MainModule extends Module {
-	public constructor() {
-		super();
-	}
-
-	public async beforeRegister(): Promise<void> {
-		console.log('Module is being registered');
-	}
-
-	public async afterRegister(): Promise<void> {
-		console.log('Module registered successfully');
-	}
-}
+export class MainModule extends Module {}
 ```
 
-Create an application class:
+Create an application class. Modules that need configuration are bound to it with `with()`:
 
 ```typescript
-import { Application } from '@elysiumjs/core';
+import { Application, RedisModule } from '@elysiumjs/core';
+import { HermesModule } from '@elysiumjs/hermes';
 
 import { MainModule } from './main.module';
 
 @Application.register({
-	modules: [MainModule],
+	modules: [
+		HermesModule.with({ level: 'debug', format: 'pretty' }),
+		RedisModule.with({
+			default: 'cache',
+			connections: { cache: { url: process.env.REDIS_URL! } }
+		}),
+		MainModule
+	],
 	server: {
 		name: 'Elysium',
 		port: 3000
@@ -87,11 +86,9 @@ export class App extends Application {}
 Create an entrypoint file:
 
 ```typescript
-import 'reflect-metadata'; // <- IMPORTANT TO ADD THIS LINE IN THE ENTRYPOINT FILE
-
 import { App } from './app';
 
-new App();
+await App.start();
 ```
 
 Start the server:
@@ -106,6 +103,24 @@ Or, if using `styx`, run:
 bun styx serve
 ```
 
+## 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`.
+
+- **Sync helpers are safe** (`Service.get()`, `Database.getConnection()`, `Redis.getConnection()`, ...) when the module that owns the service initialises synchronously. Elysium then initialises that module on the spot, even if the command does not import it.
+- **Use `await Service.resolve(...)`** when the owning module has an asynchronous `onInit`. A sync `get` then throws `ServiceNotReadyError`, which names the module.
+- **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`.
+
+## 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.
+- `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.
+- The `beforeRegister` and `afterRegister` module hooks are replaced by `onInit`, `onServe` and `onDestroy`.
+- Jobs and workers moved to `@elysiumjs/heracles`; `WorkerPool` is removed.
+
 ## Documentation
 
 TODO
@@ -118,4 +133,4 @@ Feel free to open issues for any bugs or questions you may have. Pull requests a
 
 ## License
 
-This project is licensed under the Apache License, Version 2.0. See the [LICENSE](https://github.com/workbud/elysium/blob/main/LICENSE) file for more information.
+This project is licensed under the Apache License, Version 2.0. See the [LICENSE](https://github.com/na2axl/elysiumjs/blob/main/LICENSE) file for more information.

package/dist/app.d.ts

@@ -1,23 +1,22 @@
-import type { ElysiaSwaggerConfig } from '@elysiajs/swagger';
+import type { ElysiaOpenAPIConfig } from '@elysiajs/openapi';
 import type { AnyElysia, ElysiaConfig, ErrorContext, TSchema } from 'elysia';
 import type { Route } from './http';
-import type { ModuleClass } from './module';
-import type { RedisConnectionProps } from './redis';
-import type { WampClientProps } from './wamp';
+import type { ConfiguredModule, ModuleClass } from './module';
+import type { TestingApp, TestingOptions } from './testing';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Elysia } from 'elysia';
 import { InteractsWithConsole } from './console';
+import { Kernel } from './kernel';
 /**
  * An application plugin, consisting of a function that returns an Elysia instance.
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export type ElysiumPlugin = (app: Application) => Promise<AnyElysia>;
 /**
- * Properties required when declaring an app using the `@app()` decorator.
+ * Properties required when declaring an app using the `@Application.register()` decorator.
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export type AppProps = {
-    [key: string]: any;
     /**
      * Enables or disables debug mode.
      */
@@ -32,41 +31,15 @@ export type AppProps = {
         port?: number;
     };
     /**
-     * The wamp client configuration for the app.
+     * The modules the application is made of. They act as the imports of the root module.
      */
-    wamp?: {
-        /**
-         * The default connection name.
-         */
-        default: string;
-        /**
-         * The list of connections.
-         */
-        connections: Record<string, WampClientProps>;
-    };
-    /**
-     * The list of modules provided the app.
-     */
-    modules?: ModuleClass[];
-    /**
-     * The redis configuration for the app.
-     */
-    redis?: {
-        /**
-         * The default connection name.
-         */
-        default: string;
-        /**
-         * The list of connections.
-         */
-        connections: Record<string, RedisConnectionProps>;
-    };
+    modules?: (ModuleClass | ConfiguredModule<any>)[];
     /**
-     * Swagger documentation configuration.
+     * OpenAPI documentation configuration.
      *
-     * Set it to `false` to disable Swagger documentation.
+     * Set it to `false` to disable OpenAPI documentation.
      */
-    swagger?: ElysiaSwaggerConfig<Route> | false;
+    openapi?: ElysiaOpenAPIConfig | false;
     /**
      * The validation schema for the application environment.
      */
@@ -78,9 +51,15 @@ export type AppProps = {
 };
 /**
  * Type for the application context.
+ *
+ * - `tenant`: the current tenant.
+ * - `http:context`: the context of the HTTP request being handled.
+ * - `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`.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type AppContext = AsyncLocalStorage<Map<'tenant' | 'http:context' | 'db:tx', unknown>>;
+export type AppContext = AsyncLocalStorage<Map<'tenant' | 'http:context' | 'db:transactions' | 'db:tx', unknown>>;
 /**
  * Base class for the application main entry.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -94,6 +73,7 @@ export declare abstract class Application extends InteractsWithConsole {
     static get instance(): Application;
     /**
      * Gets the application context shared between asynchronous operations.
+     * Falls back to a module-level storage when no application instance exists.
      */
     static get context(): AppContext;
     /**
@@ -105,6 +85,21 @@ export declare abstract class Application extends InteractsWithConsole {
      * Creates a new instance of the application.
      */
     constructor();
+    /**
+     * Creates the application and runs it.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    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.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    static testing(options: TestingOptions): Promise<TestingApp>;
+    /**
+     * The kernel running this application's module graph. Available once `run()` has started.
+     */
+    get kernel(): Kernel;
     /**
      * Gets the Elysia instance.
      */
@@ -134,32 +129,55 @@ export declare abstract class Application extends InteractsWithConsole {
      * @param _elysia The Elysia instance.
      */
     protected onStop(_elysia: Elysia<Route>): Promise<void>;
-    protected run(): Promise<void>;
     /**
-     * Retrieves the configuration value for the given key.
-     * @param key The key to retrieve the configuration value for.
-     * @returns The configuration value for the given key, or `null` if not found.
+     * Runs the CLI action given in `argv`: describe, `list`, `help`, `serve` or a command.
+     * Prints any error and exits with a non-zero code.
+     * @param argv The command line arguments, without the executable and script.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    run(argv?: string[]): Promise<void>;
+    private props;
+    private dispatch;
+    /** Prints an error, shuts down what was started and exits with code 1. */
+    private fail;
+    /** Exits the process, after detaching the signal handlers. */
+    private exit;
+    private removeSignalHandlers;
+    private installSignalHandlers;
+    /** The commands available in the module graph, with their owning module. */
+    private getCommands;
+    private findCommand;
+    /**
+     * Builds a command inside its owning module: lazily by default, after an eager boot
+     * when the command sets `boot`.
+     */
+    private prepareCommand;
+    /** Registers the kernel (and boots it eagerly if asked), then announces the launch. */
+    private bootKernel;
+    /**
+     * Prints the help of a command.
+     * @param name The command name.
      */
-    getConfig<T>(key: keyof AppProps): T | null;
+    private commandHelp;
     /**
      * Executes a command.
-     * @param command The command to execute.
+     * @param name The command to execute.
      * @param argv The command line arguments.
      */
     private commandExec;
     /**
-     * Discovers all registered commands from the service container.
-     * Commands are registered via `@Command.register()` and stored with the
-     * `elysium.command.*` service name pattern.
-     *
-     * @returns An array of all discovered command classes, filtered by build mode.
-     */
-    private getCommands;
-    private commandWork;
-    /**
-     * Starts the server on the specified port.
+     * Starts the server: boots the kernel, builds the root Elysia app, lets modules hook into it,
+     * mounts their controllers and listens.
      */
     private commandServe;
+    /** 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. */
+    private handleServerError;
     /**
      * Describes the CLI and available commands.
      */

package/dist/command.d.ts

@@ -90,7 +90,18 @@ export type CommandClass<T extends Command = Command> = Class<T> & {
      * Whether the command is only available in development mode.
      */
     readonly dev: boolean;
+    /**
+     * Whether the application is booted eagerly before the command runs.
+     */
+    readonly boot: boolean;
 };
+/**
+ * Gets the name a command is invoked by: the `name` given to `@Command.register()`,
+ * or else the static `command`.
+ * @param cls The command class.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function getCommandName(cls: Class<any>): string;
 /**
  * Base class for commands.
  *
@@ -118,12 +129,17 @@ export declare abstract class Command extends InteractsWithConsole {
      */
     static readonly dev: boolean;
     /**
-     * Registers a command in the service container for autodiscovery.
-     *
-     * Commands registered with this decorator will be automatically discovered
-     * and made available in the CLI without needing to be listed explicitly.
+     * Whether the whole application is booted before the command runs.
+     * When `true`, every module is initialised and every service constructed first,
+     * as for `serve`. Otherwise modules are initialised lazily, on demand.
+     */
+    static readonly boot: boolean;
+    /**
+     * Marks a class as a command. Records metadata only: the command still has to be
+     * listed in the `commands` of a module to be available in the CLI.
      *
      * @param options Optional registration options.
+     * @author Axel Nana <axel.nana@workbud.com>
      */
     static register(options?: {
         name?: string;

package/dist/connections.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Checks the `default` and `connections` keys of a connection module's config.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param module The module name, for error messages.
+ * @param config The resolved config.
+ * @returns Whether a separate alias entry is needed for the default connection.
+ * @throws {InvalidModuleConfigError} When the default is unknown or collides with a `default` connection.
+ */
+export declare function needsDefaultAlias(module: string, config: {
+    default: string;
+    connections: Record<string, unknown>;
+}): boolean;
+/**
+ * Runs every task even if some fail, then rethrows: the single error, or an `AggregateError`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function runAll(tasks: (() => unknown)[]): Promise<void>;

package/dist/container.d.ts

@@ -0,0 +1,134 @@
+import type { Class } from 'type-fest';
+import type { ModuleNode } from './module-graph';
+import type { ServiceDefinition } from './service';
+import { ServiceScope } from './service';
+/**
+ * A service registered in the container.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ContainerEntry = {
+    /** The name the service is registered under. */
+    name: string;
+    /** The service's scope. */
+    scope: ServiceScope;
+    /** Whether the service is visible from every scope. */
+    global: boolean;
+    /** The module that declared the service, or `null` for services registered imperatively. */
+    owner: ModuleNode | null;
+    /** Builds a new instance of the service. */
+    create: () => unknown;
+    /** The singleton instance, once built. */
+    instance?: unknown;
+    /** Whether the instance has been built and its `onInit` has completed. */
+    initialised: boolean;
+    /** Pending `onInit` of a singleton, when it is asynchronous. */
+    initPromise?: Promise<void>;
+    /** The error thrown by a singleton's `onInit`, once it has failed. */
+    initFailure?: {
+        error: unknown;
+    };
+    /** The service class, when the entry was registered from one. Used to await its dependencies. */
+    cls?: Class<any>;
+};
+/**
+ * Supplies the visibility rules of the module graph to the container.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type VisibilityResolver = {
+    /** The modules whose exports `node` can see. */
+    visibleOwners(node: ModuleNode): readonly ModuleNode[];
+    /** The service names `owner` exports, or `true` when it exports all its services. */
+    exportsOf(owner: ModuleNode): readonly string[] | true;
+};
+/**
+ * The scoped service container: a global scope plus one scope per module.
+ * Visibility between module scopes is supplied by the module graph.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare namespace Container {
+    /**
+     * Registers a service definition.
+     * @param owner The declaring module, or `null` for a service registered outside any module.
+     * @param def A service class or factory definition.
+     * @param config The owning module's resolved config, handed to factory definitions.
+     * @returns The name the service was registered under.
+     * @throws {DuplicateGlobalServiceError} If a global service with that name already exists.
+     */
+    function register(owner: ModuleNode | null, def: ServiceDefinition, config: unknown): string;
+    /**
+     * Adds a prebuilt entry. A global entry goes to the global scope, any other to its owner's scope.
+     * @throws {DuplicateGlobalServiceError} If the name is already taken in the global scope.
+     */
+    function add(entry: ContainerEntry): void;
+    /**
+     * Declares global service names that win over module registrations: `register` skips
+     * any definition with one of these names, so lookups reach the global entry.
+     * Pass `null` to clear.
+     */
+    function setOverrides(names: Iterable<string> | null): void;
+    /**
+     * Sets the module graph's visibility rules. Without a resolver, a module only sees
+     * its own services and the global ones.
+     */
+    function setVisibility(resolver: VisibilityResolver | null): void;
+    /**
+     * Sets the hook called before building a service whose owning module may not be initialised.
+     * It returns `void` when the module is ready, or a promise while initialisation is pending.
+     */
+    function setModuleInitHook(hook: ((owner: ModuleNode) => Promise<void> | void) | null): void;
+    /**
+     * Sets the lookup consulted when a name isn't found, to report services
+     * that belong to modules skipped for the current environment.
+     */
+    function setSkippedLookup(lookup: ((name: string) => {
+        module: string;
+        environment: string;
+    } | null) | null): void;
+    /**
+     * Finds a service visible from `from`: its own scope, then the exports of the modules
+     * it can see, then the global scope. Without `from`, only the global scope is searched.
+     */
+    function lookup(name: string, from: ModuleNode | undefined): {
+        entry: ContainerEntry;
+        owner: ModuleNode | null;
+    } | null;
+    /**
+     * Gets a service visible from the current module context.
+     * @returns The service, or `null` if none is visible.
+     * @throws {ServiceNotReadyError} If the service or its module is still initialising.
+     */
+    function get(name: string): unknown;
+    /**
+     * Gets a service of the global scope, ignoring the services of the current module context.
+     * @returns The service, or `null` if there is no global service with that name.
+     * @throws {ServiceNotReadyError} If the service or its module is still initialising.
+     */
+    function getGlobal(name: string): unknown;
+    /**
+     * Like {@link get}, but awaits the `onInit` of the service and of its owning module.
+     * @throws {ServiceNotFoundError | ServiceNotVisibleError | EnvironmentSkippedModuleError}
+     */
+    function resolve(name: string, requester: string): Promise<unknown>;
+    /**
+     * Builds `cls` with its injected dependencies, resolved from the current module context.
+     * @throws {ServiceNotFoundError | ServiceNotVisibleError | EnvironmentSkippedModuleError}
+     */
+    function make<T>(cls: Class<T>): T;
+    /** Whether the global scope has a service with that name. */
+    const hasGlobal: (name: string) => boolean;
+    /** The names registered in the global scope. */
+    const globalNames: () => string[];
+    /** Removes a service from the global scope. */
+    const removeGlobal: (name: string) => void;
+    /** Clears the global scope. */
+    const clearGlobal: () => void;
+    /** The live singletons, in construction order (those whose `onInit` failed are left out). Returns a snapshot. */
+    const constructed: () => readonly {
+        name: string;
+        instance: unknown;
+        owner: ModuleNode | null;
+    }[];
+    /** Clears every scope and the construction record. */
+    function reset(): void;
+}