@elysiumjs/core 0.7.0 → 0.10.0

package/dist/errors.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Base class of every error thrown by the Elysium framework.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ElysiumError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the module graph contains an import cycle.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ModuleCycleError extends ElysiumError {
+    readonly path: string[];
+    constructor(path: string[]);
+}
+/**
+ * Thrown when a class used as a module is not decorated with `@Module`.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class InvalidModuleError extends ElysiumError {
+    readonly className: string;
+    constructor(className: string);
+}
+/**
+ * Thrown when two modules declare the same global service.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class DuplicateGlobalServiceError extends ElysiumError {
+    readonly serviceName: string;
+    readonly modules: [string, string];
+    constructor(serviceName: string, modules: [string, string]);
+}
+/**
+ * Thrown when two modules register the same command.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class DuplicateCommandError extends ElysiumError {
+    readonly command: string;
+    readonly modules: [string, string];
+    constructor(command: string, modules: [string, string]);
+}
+/**
+ * Thrown when a module is configured from two conflicting sites.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ConflictingModuleConfigError extends ElysiumError {
+    readonly module: string;
+    readonly sites: [string, string];
+    constructor(module: string, sites: [string, string]);
+}
+/**
+ * Thrown when a module requires configuration that was never provided.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class MissingModuleConfigError extends ElysiumError {
+    readonly module: string;
+    readonly keys: string[];
+    constructor(module: string, keys: string[]);
+}
+/**
+ * Thrown when a module's configuration is present but invalid.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class InvalidModuleConfigError extends ElysiumError {
+    readonly module: string;
+    readonly key: string;
+    readonly reason: string;
+    constructor(module: string, key: string, reason: string);
+}
+/**
+ * Thrown when a service is requested from a module that cannot see it.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ServiceNotVisibleError extends ElysiumError {
+    readonly service: string;
+    readonly requester: string;
+    readonly module: string | null;
+    readonly owner: string | null;
+    constructor(service: string, requester: string, module: string | null, owner: string | null);
+}
+/**
+ * Thrown when a service is not registered anywhere.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ServiceNotFoundError extends ElysiumError {
+    readonly service: string;
+    constructor(service: string);
+}
+/**
+ * Thrown when a service is requested before it has been initialized.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ServiceNotReadyError extends ElysiumError {
+    readonly service: string;
+    readonly owner: string | null;
+    constructor(service: string, owner?: string | null);
+}
+/**
+ * Thrown when services depend on each other in a cycle.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class CircularDependencyError extends ElysiumError {
+    readonly path: string[];
+    constructor(path: string[]);
+}
+/**
+ * Thrown when two different module classes share the same name.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class DuplicateModuleNameError extends ElysiumError {
+    readonly moduleName: string;
+    constructor(moduleName: string);
+}
+/**
+ * Thrown when a service lives in a module skipped for the current environment.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class EnvironmentSkippedModuleError extends ElysiumError {
+    readonly service: string;
+    readonly requester: string;
+    readonly skippedModule: string;
+    readonly environment: string;
+    constructor(service: string, requester: string, skippedModule: string, environment: string);
+}
+/**
+ * Thrown when a class listed in a module's `controllers` is not a decorated controller.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class InvalidControllerError extends ElysiumError {
+    readonly className: string;
+    readonly moduleName: string;
+    constructor(className: string, moduleName: string);
+}
+/**
+ * Thrown when an instance method of a class that is not a service is declared an event listener.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class EventListenerNotSupportedError extends ElysiumError {
+    readonly className: string;
+    readonly method: string;
+    readonly moduleName: string;
+    constructor(className: string, method: string, moduleName: string);
+}

package/dist/event-wiring.d.ts

@@ -0,0 +1,23 @@
+import type { Class } from 'type-fest';
+import type { EventData } from './event';
+import type { ModuleNode } from './module-graph';
+/**
+ * A listener the kernel added to the event bus.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WiredListener = {
+    readonly event: string;
+    readonly wrapper: (data: EventData<any>) => Promise<void>;
+};
+/**
+ * Registers the decorated event listeners of `owned` classes on the event bus, each running
+ * in `node`'s module context.
+ *
+ * @param node The module the classes belong to.
+ * @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.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function wireEventListeners(node: ModuleNode, owned: readonly Class<any>[], services: ReadonlySet<Class<any>>): WiredListener[];

package/dist/event.d.ts

@@ -1,3 +1,15 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Internal event bus used by the framework.
+ * @internal
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class EventBus extends EventEmitter {
+    static readonly instance: EventBus;
+    private constructor();
+    emitError(error: unknown): void;
+    emitEvent(event: string, data: unknown, source?: unknown): void;
+}
 /**
  * Stores the event data with the source.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -39,6 +51,23 @@ export type ListenProps = {
      */
     prepend?: boolean;
 };
+/**
+ * A listener recorded on a class by `@Event.on` / `@Event.once`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type EventListenerMeta = {
+    readonly event: string;
+    readonly method: string | symbol;
+    readonly mode: 'on' | 'once';
+    readonly prepend: boolean;
+    readonly static: boolean;
+};
+/**
+ * Gets the listeners recorded on a class by the `@Event.on` / `@Event.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 {
     /**
      * Emits an event with the provided data and source.
@@ -49,7 +78,14 @@ export declare namespace Event {
      */
     const emit: <TData, TSource = any>(event: string, data: TData, source?: TSource | null) => void;
     /**
-     * Marks a method as an event listener.
+     * Marks a method as an event listener. The decorator only records the listener on the class.
+     * The kernel registers it when the module that lists the class in its `services` or
+     * `controllers` initialises, and runs it in that module's context, so it sees the module's
+     * private services. Listeners on classes that no loaded module lists never fire, and a lazy
+     * CLI boot only wires the modules it prepares (eager boot wires every module).
+     *
+     * 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.
      */
@@ -63,6 +99,7 @@ export declare namespace Event {
     function on<TData, TSource = any>(event: string, handler: EventHandler<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.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param options The decorator options.
      */
@@ -88,6 +125,7 @@ export declare namespace Event {
     /**
      * Marks a method as an event listener.
      * @param options The decorator options.
+     * @throws {ElysiumError} If `options.mode` is neither `on` nor `once`.
      */
     const listen: (options: ListenProps) => MethodDecorator;
 }

package/dist/http.d.ts

@@ -62,6 +62,12 @@ export type Context<TBody = unknown, TController = unknown, TModule extends Modu
     body: TBody;
 }, Singleton<TController, TModule>>;
 export type ElysiaApp = Elysia<Route, Singleton>;
+/**
+ * Name of the global service running a callback in a database transaction, used by
+ * `@transactional` handlers. Provided by database modules such as `DrizzleModule`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const DATABASE_TRANSACTION_SERVICE = "db.transaction";
 /**
  * The scope of an HTTP controller.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -92,7 +98,7 @@ export type HttpControllerProps = {
     scope?: HttpControllerScope;
     /**
      * The list of tags for the controller.
-     * Used in Swagger documentation.
+     * Used in OpenAPI documentation.
      */
     tags?: Array<string>;
     /**
@@ -120,12 +126,12 @@ export type RequestHandlerDecoratorProps = {
     response?: TSchema | Record<number, TSchema>;
     /**
      * The operation ID for the handler.
-     * Used in Swagger documentation.
+     * Used in OpenAPI documentation.
      */
     operationId?: string;
     /**
      * The description for the handler.
-     * Used in Swagger documentation.
+     * Used in OpenAPI documentation.
      */
     description?: string;
     /**

package/dist/index.d.ts

@@ -5,17 +5,22 @@ export { type CommandArgumentProps, type CommandClass, Command, CommandArgumentT
 export { ConsoleFormat, InteractsWithConsole } from './console';
 export { Env } from './env';
 export { type EventData, type EventHandler, Event } from './event';
-export { type LoggerInterface, ConsoleLogger } from './logger';
-export { type Context, type Route, HttpControllerScope, Http } from './http';
-export { Job } from './job';
+export { type LoggerInterface, ConsoleLogger, getLogger, LOGGER_SERVICE } from './logger';
+export { type Context, type Route, DATABASE_TRANSACTION_SERVICE, HttpControllerScope, Http } from './http';
+export { Metadata } from './metadata';
 export { Middleware } from './middleware';
 export { RequestLoggerMiddleware } from './middlewares/request-logger.middleware';
-export { type ModuleClass, Module } from './module';
-export { Redis } from './redis';
-export { ServiceScope, Service } from './service';
-export { type WampRegistrationOptions, type WampSubscriptionOptions, type WampProps, type WampRegistrationHandlerArgs, type WampSubscriptionHandlerArgs, type WampRegistrationHandler, type WampSubscriptionHandler, Wamp } from './wamp';
+export { CircularDependencyError, ConflictingModuleConfigError, DuplicateCommandError, DuplicateGlobalServiceError, DuplicateModuleNameError, ElysiumError, EnvironmentSkippedModuleError, EventListenerNotSupportedError, InvalidModuleError, InvalidModuleConfigError, MissingModuleConfigError, ModuleCycleError, ServiceNotFoundError, ServiceNotReadyError, ServiceNotVisibleError } from './errors';
+export { needsDefaultAlias, runAll } from './connections';
+export { Kernel, KERNEL_SERVICE } from './kernel';
+export { type ConfiguredModule, type ModuleClass, type ModuleProps, Module } from './module';
+export { ModuleContext } from './module-context';
+export { type ModuleGraph, type ModuleNode } from './module-graph';
+export { type TestingApp, type TestingOptions } from './testing';
+export { type RedisConnectionProps, type RedisModuleConfig, Redis, RedisModule } from './redis';
+export { type ServiceDefinition, type ServiceFactoryDefinition, ServiceScope, Service } from './service';
+export { type WampRegistrationOptions, type WampSubscriptionOptions, type WampProps, type WampRegistrationHandlerArgs, type WampSubscriptionHandlerArgs, type WampRegistrationHandler, type WampSubscriptionHandler, type WampClientProps, type WampModuleConfig, Wamp, WampModule } from './wamp';
 export { type WS, type WSError, Websocket } from './websocket';
-export { type QueueOptions, WorkerPool, Worker } from './worker';
 /**
  * The type for the context of the application.
  * @author Axel Nana <axel.nana@workbud.com>