@elysiumjs/core 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @elysiumjs/core
 
+## 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

package/dist/app.d.ts

@@ -1,24 +1,22 @@
-import type { ElysiaSwaggerConfig } from '@elysiajs/swagger';
+import type { ElysiaOpenAPIConfig } from '@elysiajs/openapi';
 import type { AnyElysia, ElysiaConfig, ErrorContext, TSchema } from 'elysia';
-import type { DatabaseConnectionProps } from './database';
 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.
      */
@@ -33,54 +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 database configuration for the app.
-     */
-    database?: {
-        /**
-         * The default connection name.
-         */
-        default: string;
-        /**
-         * The list of connections.
-         */
-        connections: Record<string, DatabaseConnectionProps>;
-    };
+    modules?: (ModuleClass | ConfiguredModule<any>)[];
     /**
-     * The redis configuration for the app.
-     */
-    redis?: {
-        /**
-         * The default connection name.
-         */
-        default: string;
-        /**
-         * The list of connections.
-         */
-        connections: Record<string, RedisConnectionProps>;
-    };
-    /**
-     * 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.
      */
@@ -108,6 +67,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;
     /**
@@ -119,6 +79,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.
      */
@@ -148,32 +123,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,128 @@
+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;
+    /**
+     * 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;
+}