@elysiumjs/core 0.10.0 → 0.11.1

package/dist/kernel.d.ts

@@ -18,12 +18,19 @@ export declare class Kernel {
     private readonly initOrder;
     private readonly inFlight;
     private readonly failures;
+    private readonly rejected;
     private readonly ownClasses;
     private readonly wired;
     private shutdownPromise;
     constructor(moduleGraph: ModuleGraph);
     /** The module graph this kernel runs. */
     get graph(): ModuleGraph;
+    /**
+     * The service classes a module registers, from its `services` (factory definitions left out).
+     * Empty until {@link register} has run.
+     * @param node The module.
+     */
+    serviceClasses(node: ModuleNode): readonly Class<any>[];
     /**
      * Phase 2: resolves each module's config, instantiates the module and registers its services.
      * @throws {ConflictingModuleConfigError | MissingModuleConfigError}
@@ -34,7 +41,12 @@ export declare class Kernel {
      * and a failure is remembered and rethrown.
      */
     initModule(node: ModuleNode): Promise<void>;
-    /** Initialises every module in graph order, then constructs every non-factory service. */
+    /**
+     * Forgets the modules whose initialisation failed, so that the next {@link initModule}
+     * runs their `onInit` again. Initialisations still in flight are kept.
+     */
+    resetFailures(): void;
+    /** Initialises every module in graph order, then constructs every singleton service. */
     bootEager(): Promise<void>;
     /**
      * Lazily builds a class owned by `owner`, such as a command: initialises the owner,
@@ -63,6 +75,8 @@ export declare class Kernel {
      * @throws The error of a failing synchronous `onInit`, which is remembered.
      */
     private initSync;
+    /** Removes event listeners wired by {@link initOwn}. */
+    private unwire;
     private runShutdown;
     /** Evaluates the config that applies to `node`, checking function-form ties. */
     private resolveNodeConfig;

package/dist/{event-wiring.d.ts → lifecycle-wiring.d.ts}

@@ -1,5 +1,5 @@
 import type { Class } from 'type-fest';
-import type { EventData } from './event';
+import type { LifecycleEvent } from './lifecycle';
 import type { ModuleNode } from './module-graph';
 /**
  * A listener the kernel added to the event bus.
@@ -7,7 +7,7 @@ import type { ModuleNode } from './module-graph';
  */
 export type WiredListener = {
     readonly event: string;
-    readonly wrapper: (data: EventData<any>) => Promise<void>;
+    readonly wrapper: (data: LifecycleEvent<any>) => Promise<void>;
 };
 /**
  * Registers the decorated event listeners of `owned` classes on the event bus, each running
@@ -17,7 +17,7 @@ export type WiredListener = {
  * @param owned The module's own classes (services and controllers).
  * @param services The subset of `owned` registered as services in the module.
  * @returns The listeners added, so they can be removed on shutdown.
- * @throws {EventListenerNotSupportedError} For an instance listener on a non-service class.
+ * @throws {LifecycleListenerNotSupportedError} For an instance listener on a non-service class.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export declare function wireEventListeners(node: ModuleNode, owned: readonly Class<any>[], services: ReadonlySet<Class<any>>): WiredListener[];
+export declare function wireLifecycleListeners(node: ModuleNode, owned: readonly Class<any>[], services: ReadonlySet<Class<any>>): WiredListener[];

package/dist/{event.d.ts → lifecycle.d.ts}

@@ -4,8 +4,8 @@ import { EventEmitter } from 'node:events';
  * @internal
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export declare class EventBus extends EventEmitter {
-    static readonly instance: EventBus;
+export declare class LifecycleBus extends EventEmitter {
+    static readonly instance: LifecycleBus;
     private constructor();
     emitError(error: unknown): void;
     emitEvent(event: string, data: unknown, source?: unknown): void;
@@ -14,7 +14,7 @@ export declare class EventBus extends EventEmitter {
  * Stores the event data with the source.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type EventData<TData, TSource = null> = {
+export type LifecycleEvent<TData, TSource = null> = {
     /**
      * The emitted data.
      */
@@ -25,10 +25,10 @@ export type EventData<TData, TSource = null> = {
     source: TSource | null;
 };
 /**
- * Event handler function.
+ * Lifecycle handler function.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type EventHandler<TData, TSource = any> = (event: EventData<TData, TSource>) => void | Promise<void>;
+export type LifecycleHandler<TData, TSource = any> = (event: LifecycleEvent<TData, TSource>) => void | Promise<void>;
 /**
  * Properties required when declaring a method as an event listener.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -52,10 +52,10 @@ export type ListenProps = {
     prepend?: boolean;
 };
 /**
- * A listener recorded on a class by `@Event.on` / `@Event.once`.
+ * A listener recorded on a class by `@Lifecycle.on` / `@Lifecycle.once`.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type EventListenerMeta = {
+export type LifecycleListenerMeta = {
     readonly event: string;
     readonly method: string | symbol;
     readonly mode: 'on' | 'once';
@@ -63,12 +63,12 @@ export type EventListenerMeta = {
     readonly static: boolean;
 };
 /**
- * Gets the listeners recorded on a class by the `@Event.on` / `@Event.once` decorators.
+ * Gets the listeners recorded on a class by the `@Lifecycle.on` / `@Lifecycle.once` decorators.
  * @author Axel Nana <axel.nana@workbud.com>
  * @param cls The class to inspect.
  */
-export declare function getEventListeners(cls: object): readonly EventListenerMeta[];
-export declare namespace Event {
+export declare function getLifecycleListeners(cls: object): readonly LifecycleListenerMeta[];
+export declare namespace Lifecycle {
     /**
      * Emits an event with the provided data and source.
      * @author Axel Nana <axel.nana@workbud.com>
@@ -87,30 +87,37 @@ export declare namespace Event {
      * Static methods are called on the class. Instance methods require a class registered as a
      * service: they run on the instance the container resolves.
      * @author Axel Nana <axel.nana@workbud.com>
-     * @param options The decorator options.
+     * @param event The event name.
+     * @param options Whether the listener goes first (`prepend`).
+     * @example
+     * ```ts
+     * @Lifecycle.on('elysium:error')
+     * public static report(e: LifecycleEvent<Error>) {}
+     * ```
      */
-    function on(options: Omit<ListenProps, 'mode'>): MethodDecorator;
+    function on(event: string, options?: Omit<ListenProps, 'mode' | 'event'>): MethodDecorator;
     /**
      * Registers an event listener for the specified event.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param event The event name.
      * @param handler The event handler function.
      */
-    function on<TData, TSource = any>(event: string, handler: EventHandler<TData, TSource>): void;
+    function on<TData, TSource = any>(event: string, handler: LifecycleHandler<TData, TSource>): void;
     /**
      * Marks a method as an event listener that listens for the event only once.
-     * Like {@link Event.on}, the decorator is metadata-only and the kernel wires it per module.
+     * Like {@link Lifecycle.on}, the decorator is metadata-only and the kernel wires it per module.
      * @author Axel Nana <axel.nana@workbud.com>
-     * @param options The decorator options.
+     * @param event The event name.
+     * @param options Whether the listener goes first (`prepend`).
      */
-    function once(options: Omit<ListenProps, 'mode'>): MethodDecorator;
+    function once(event: string, options?: Omit<ListenProps, 'mode' | 'event'>): MethodDecorator;
     /**
      * Registers an event listener for the specified event that listens for the event only once.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param event The event name.
      * @param handler The event handler function.
      */
-    function once<TData, TSource = any>(event: string, handler: EventHandler<TData, TSource>): void;
+    function once<TData, TSource = any>(event: string, handler: LifecycleHandler<TData, TSource>): void;
     /**
      * Removes all event listeners for the specified event.
      * @author Axel Nana <axel.nana@workbud.com>
@@ -127,5 +134,5 @@ export declare namespace Event {
      * @param options The decorator options.
      * @throws {ElysiumError} If `options.mode` is neither `on` nor `once`.
      */
-    const listen: (options: ListenProps) => MethodDecorator;
+    const listen: ({ mode, event, ...options }: ListenProps) => MethodDecorator;
 }

package/dist/middleware.d.ts

@@ -12,6 +12,11 @@ import type { ModuleNode } from './module-graph';
  * @param node The module the middlewares belong to. The chain runs in its context.
  */
 export declare const executeMiddlewareChain: (middlewares: Middleware[], context: any, method: Exclude<keyof Middleware, 'guards'>, node?: ModuleNode | null) => Promise<any>;
+/**
+ * The status responses thrown by middlewares to stop a request. They are responses, not errors.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const middlewareStops: WeakSet<object>;
 /**
  * Builds middleware instances in the context of a module.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -20,19 +25,24 @@ export declare const executeMiddlewareChain: (middlewares: Middleware[], context
  */
 export declare const makeMiddlewares: (middlewares: Class<Middleware>[], node: ModuleNode | null) => Middleware[];
 /**
- * Apply a list of middlewares to an Elysia plugin.
+ * Remembers the middlewares a request went through, so that their onError runs if it fails.
  * @author Axel Nana <axel.nana@workbud.com>
- * @param middlewares The list of middlewares to apply.
- * @param plugin The Elysia plugin instance.
- * @param node The module the middlewares belong to, or `null` for application-level middlewares.
  */
+export declare const enlist: (context: any, middlewares: Middleware[], node: ModuleNode | null) => void;
+/**
+ * Runs the `onError` hook of the middlewares a failed request went through, innermost first.
+ * Called by the error handler before it builds the response; a failing hook is logged.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param context The context of the failed request, with its `error`.
+ */
+export declare const runErrorMiddlewares: (context: any) => Promise<void>;
 export declare const applyMiddlewares: (middlewares: Class<Middleware>[], plugin: AnyElysia, node: ModuleNode | null) => void;
 /**
  * Base class for middleware.
  * @author Axel Nana <axel.nana@workbud.com>
  * @template TGuards The list of guards for the middleware.
  */
-export declare abstract class Middleware<TGuards extends string[] = []> {
+export declare abstract class Middleware<TGuards extends string[] = string[]> {
     /**
      * Registers a list of middlewares to be applied on a controller or endpoint.
      * @author Axel Nana <axel.nana@workbud.com>
@@ -81,6 +91,15 @@ export declare abstract class Middleware<TGuards extends string[] = []> {
      * @param _ctx The request context.
      */
     onBeforeHandle(_ctx: Context): any;
+    /**
+     * Called when the request fails, before the error response is built, such as to save what the
+     * request changed or to set headers on the error response. Its context carries the `error`.
+     * It cannot replace the response: exception filters do that.
+     * @param _ctx The request context.
+     */
+    onError(_ctx: Context & {
+        error: unknown;
+    }): any;
     /**
      * Called after the response has been sent.
      * @param _ctx The request context.

package/dist/module-context.d.ts

@@ -13,6 +13,12 @@ export declare namespace ModuleContext {
      * @returns The value returned by `fn`.
      */
     function run<T>(node: ModuleNode, fn: () => T): T;
+    /**
+     * Runs `fn` outside of any module, so that service lookups only see the global scope.
+     * @param fn The function to run.
+     * @returns The value returned by `fn`.
+     */
+    function outside<T>(fn: () => T): T;
     /**
      * Gets the module current in this async context, if any.
      */

package/dist/module-graph.d.ts

@@ -1,5 +1,6 @@
 import type { Class } from 'type-fest';
 import type { ConfiguredModule, ModuleClass, ModuleProps } from './module';
+import type { ServiceToken } from './token';
 /**
  * A configuration given to a module from one import site.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -36,8 +37,8 @@ export type ModuleGraph = {
     node(cls: ModuleClass): ModuleNode | undefined;
     /** The direct imports of `node`, plus the modules they re-export. */
     visibleOwners(node: ModuleNode): readonly ModuleNode[];
-    /** The service names `node` exports, or `true` when it exports everything. */
-    exportsOf(node: ModuleNode): readonly string[] | true;
+    /** The service tokens `node` exports, or `true` when it exports everything. */
+    exportsOf(node: ModuleNode): readonly ServiceToken[] | true;
     /** Gathers controllers, commands or jobs across modules, with their owner. */
     collect<K extends Collectable>(key: K): readonly {
         item: Class<any>;

package/dist/module.d.ts

@@ -1,7 +1,10 @@
 import type { Elysia } from 'elysia';
 import type { Class } from 'type-fest';
+import type { TSchema } from 'typebox';
 import type { CommandClass } from './command';
+import type { FilterClass } from './filter';
 import type { Route } from './http';
+import type { InterceptorClass } from './interceptor';
 import type { ServiceDefinition } from './service';
 import { Symbols } from './utils';
 /**
@@ -39,6 +42,21 @@ export type ModuleProps<TConfig = unknown> = {
     prefix?: Route;
     /** Environments (`NODE_ENV` values) in which the module is active. */
     env?: string[];
+    /**
+     * The environment variables the module needs, as a TypeBox object. Merged with the schemas of
+     * the app and the other active modules, and validated at boot.
+     */
+    envSchema?: TSchema;
+    /**
+     * Exception filters for the routes of this module's controllers. They run after the filters
+     * of the route and the controller, and before those of the app.
+     */
+    filters?: FilterClass[];
+    /**
+     * Interceptors around the handlers of this module's controllers, inside those of the app and
+     * outside those of the controller.
+     */
+    interceptors?: InterceptorClass[];
 };
 /**
  * Checks whether a value is a configured module.