@elysiumjs/core 0.8.0 → 0.11.0

package/dist/config.d.ts

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

package/dist/console.d.ts

@@ -1,4 +1,4 @@
-import type { WriteStream } from 'node:tty';
+import type { OutputLevel } from './runtime';
 /**
  * ANSI color codes and styles for console output.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -18,46 +18,78 @@ export declare enum ConsoleFormat {
     ITALIC = 11,
     INVERSE = 12
 }
+/**
+ * The kinds of messages the level shortcuts of {@link InteractsWithConsole} write.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ConsoleTag = 'debug' | 'info' | 'success' | 'warning' | 'error';
+/**
+ * The tag written before a message: its label and the styles of the label.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ConsoleTagStyle = {
+    label: string;
+    styles: ConsoleFormat[];
+};
 /**
  * A utility class for console IO with various formatting options.
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export declare class InteractsWithConsole {
     protected static readonly SPACE_WIDTH = 60;
+    /**
+     * Changes the tags the level shortcuts write before their messages, for every console. A tag
+     * is a label, or a label and its styles; the tags left out keep their defaults (`[D]`, `[I]`,
+     * `[S]`, `[W]` and `[E]`, in gray, blue, green, yellow and red).
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @example
+     * ```ts
+     * InteractsWithConsole.useTags({ info: '[INFO]', error: { label: '[ERR]', styles: [ConsoleFormat.RED, ConsoleFormat.BOLD] } });
+     * ```
+     */
+    static useTags(custom: Partial<Record<ConsoleTag, string | ConsoleTagStyle>>): void;
+    /** Restores the default tags. */
+    static resetTags(): void;
     /**
      * Write a message to the console.
      * @param message The message to write.
      * @param newLine Whether to add a newline at the end (default: `true`).
-     * @param out The output stream to write to (default: `process.stdout`).
+     * @param out The stream to write to (default: `'stdout'`). The runtime decides how it is
+     * written: hosts without streams, such as Cloudflare Workers, write to the console instead,
+     * and so does the framework when no runtime is set yet.
+     * @param level The level of the message. A host that writes through the console uses the
+     * console method of the level, so that its logs keep the level.
      */
-    write(message: string, newLine?: boolean, out?: WriteStream): void;
+    write(message: string, newLine?: boolean, out?: 'stdout' | 'stderr', level?: OutputLevel): void;
     /**
      * Write a new line to the console.
      */
     newLine(): void;
+    /** Writes a message after the tag of its kind, at the level and on the stream of that kind. */
+    protected tagged(tag: ConsoleTag, message: string): void;
     /**
-     * Write an info message to the console (blue text).
+     * Write an info message to the console, after the `info` tag.
      * @param message The message to write.
      */
     info(message: string): void;
     /**
-     * Write a success message to the console (green text).
+     * Write a success message to the console, after the `success` tag.
      * @param message The message to write.
      */
     success(message: string): void;
     /**
-     * Write a warning message to the console (yellow text).
+     * Write a warning message to the console, after the `warning` tag.
      * @param message The message to write.
      */
     warning(message: string): void;
     /**
-     * Write an error message to the console (red text).
+     * Write an error message to the standard error stream, after the `error` tag.
      * @param message The message to write.
      */
     error(message: string): void;
     /**
-     * Write a debug message to the console (gray text).
-     * Only shown if the DEBUG environment variable is set.
+     * Write a debug message to the console, after the `debug` tag. Only written when the `DEBUG`
+     * environment variable is set.
      * @param message The message to write.
      */
     debug(message: string): void;
@@ -129,6 +161,11 @@ export declare class InteractsWithConsole {
      * Clear the current line in the console.
      */
     clearLine(): void;
+    /**
+     * Gets the interactive terminal of the runtime.
+     * @throws {RuntimeNotSupportedError} When the runtime has no terminal.
+     */
+    private terminal;
     /**
      * Prompt the user for input.
      * @param question The question to ask.

package/dist/container.d.ts

@@ -1,13 +1,16 @@
 import type { Class } from 'type-fest';
 import type { ModuleNode } from './module-graph';
 import type { ServiceDefinition } from './service';
+import type { ServiceToken } from './token';
 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. */
+    /** The token the service is registered under: its name, or its class. */
+    token: ServiceToken;
+    /** A readable name for messages. Never used to look the service up. */
     name: string;
     /** The service's scope. */
     scope: ServiceScope;
@@ -37,8 +40,8 @@ export type ContainerEntry = {
 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 service tokens `owner` exports, or `true` when it exports all its services. */
+    exportsOf(owner: ModuleNode): readonly ServiceToken[] | true;
 };
 /**
  * The scoped service container: a global scope plus one scope per module.
@@ -52,10 +55,10 @@ export declare namespace Container {
      * @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.
+     * @returns The token the service was registered under: its name, or its class.
      * @throws {DuplicateGlobalServiceError} If a global service with that name already exists.
      */
-    function register(owner: ModuleNode | null, def: ServiceDefinition, config: unknown): string;
+    function register(owner: ModuleNode | null, def: ServiceDefinition, config: unknown): ServiceToken;
     /**
      * 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.
@@ -66,7 +69,7 @@ export declare namespace Container {
      * any definition with one of these names, so lookups reach the global entry.
      * Pass `null` to clear.
      */
-    function setOverrides(names: Iterable<string> | null): void;
+    function setOverrides(tokens: Iterable<ServiceToken> | null): void;
     /**
      * Sets the module graph's visibility rules. Without a resolver, a module only sees
      * its own services and the global ones.
@@ -81,7 +84,7 @@ export declare namespace Container {
      * 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) => {
+    function setSkippedLookup(lookup: ((token: ServiceToken) => {
         module: string;
         environment: string;
     } | null) | null): void;
@@ -89,7 +92,7 @@ export declare namespace Container {
      * 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): {
+    function lookup(service: ServiceToken, from: ModuleNode | undefined): {
         entry: ContainerEntry;
         owner: ModuleNode | null;
     } | null;
@@ -98,31 +101,90 @@ export declare namespace Container {
      * @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;
+    function get(service: ServiceToken): 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(service: ServiceToken): 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>;
+    function resolve(service: ServiceToken, requester: string): Promise<unknown>;
+    /**
+     * Awaits everything `cls` injects, so that {@link make} can then build it synchronously:
+     * module initialisation, singletons and, inside a request scope, request-scoped services
+     * with an asynchronous `onInit`.
+     * @param cls The class about to be built from the current module context.
+     */
+    function prepareClass(cls: Class<unknown>): Promise<void>;
+    /**
+     * Awaits a service like {@link resolve}, but returns `null` when it is not visible from the
+     * current module context, like {@link get}. A factory service is built once, with its `onInit` done.
+     * @param service The service token.
+     */
+    function resolveVisible(service: ServiceToken): 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. */
+    /**
+     * Instantiates a class that is kept for the app lifetime, like {@link make}. A request-scoped
+     * dependency throws {@link ScopeMismatchError}, since the instance would keep the first
+     * request's copy.
+     * @param cls The class to instantiate.
+     */
+    function makeSingleton<T>(cls: Class<T>): T;
+    /** The modules that declare a service with that token in their own scope, in registration order. */
+    const ownersOf: (service: ServiceToken) => ModuleNode[];
+    /** Whether the global scope has a service with that token. */
+    const hasGlobal: (service: ServiceToken) => boolean;
+    /** The names registered in the global scope (services registered by class are left out). */
     const globalNames: () => string[];
     /** Removes a service from the global scope. */
-    const removeGlobal: (name: string) => void;
+    const removeGlobal: (service: ServiceToken) => void;
+    /**
+     * Runs `fn` in a request scope: request-scoped services resolved inside it, including in the
+     * asynchronous work it starts, get one instance for the whole run.
+     *
+     * Without `key`, a run inside another request scope joins it. With `key` (such as the request
+     * object), every run with the same key shares one scope, so separate hooks of one request see
+     * the same instances.
+     * @param fn The work to run.
+     * @param key The object the scope belongs to.
+     */
+    const runInRequestScope: <T>(fn: () => T, key?: object) => T;
+    /**
+     * Ends the request scope of `key`: removes its store and calls `onDestroy` on its instances,
+     * the last created first, each in its owner's module context. Errors are logged, never thrown.
+     * Disposing a scope twice returns the first disposal, so that every caller, such as a host
+     * that keeps the invocation alive until it ends, waits for the `onDestroy` work. Disposing a
+     * scope that never existed does nothing.
+     * @param key The object the scope was started with.
+     */
+    const disposeRequestScope: (key: object) => Promise<void>;
+    /** Whether the current code runs in a request scope. */
+    const inRequestScope: () => boolean;
     /** 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 {
+        token: ServiceToken;
         name: string;
         instance: unknown;
         owner: ModuleNode | null;
     }[];
+    /**
+     * Forgets the singletons whose `onInit` failed, so that the next resolution builds them
+     * again.
+     * @param nodes The modules of the application to retry: only their services, and the global
+     * services they own, are forgotten, so that two applications in one process do not reset each
+     * other's failures. Every failed singleton when omitted.
+     */
+    function forgetFailures(nodes?: readonly ModuleNode[]): void;
     /** Clears every scope and the construction record. */
     function reset(): void;
 }

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import type { ServiceToken } from './token';
 /**
  * Base class of every error thrown by the Elysium framework.
  *
@@ -104,7 +105,13 @@ export declare class ServiceNotFoundError extends ElysiumError {
 export declare class ServiceNotReadyError extends ElysiumError {
     readonly service: string;
     readonly owner: string | null;
-    constructor(service: string, owner?: string | null);
+    readonly token: ServiceToken;
+    /**
+     * @param service The service label, used in the message.
+     * @param owner The id of the module owning the service.
+     * @param token The token to pass to `Service.resolve()` to wait for the service.
+     */
+    constructor(service: string, owner?: string | null, token?: ServiceToken);
 }
 /**
  * Thrown when services depend on each other in a cycle.
@@ -151,9 +158,37 @@ export declare class InvalidControllerError extends ElysiumError {
  *
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export declare class EventListenerNotSupportedError extends ElysiumError {
+export declare class LifecycleListenerNotSupportedError extends ElysiumError {
     readonly className: string;
     readonly method: string;
     readonly moduleName: string;
     constructor(className: string, method: string, moduleName: string);
 }
+/**
+ * Thrown when a request-scoped service is resolved outside a request.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class OutsideRequestScopeError extends ElysiumError {
+    readonly service: string;
+    constructor(service: string);
+}
+/**
+ * Thrown when a singleton service depends on a request-scoped one.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ScopeMismatchError extends ElysiumError {
+    readonly service: string;
+    readonly dependency: string;
+    constructor(service: string, dependency: string);
+}
+/**
+ * Thrown when an interceptor calls `next()` more than once, which would run the handler twice.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class InterceptorNextCalledTwiceError extends ElysiumError {
+    readonly interceptor: string;
+    constructor(interceptor: string);
+}

package/dist/filter.d.ts

@@ -0,0 +1,78 @@
+import type { Class } from 'type-fest';
+import type { ModuleNode } from './module-graph';
+/**
+ * The context an exception filter receives: the request, the response being built (`set`), the
+ * route and its parameters, as Elysia's error hook gives them.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type FilterContext = {
+    request: Request;
+    set: {
+        status?: number | string;
+        headers: Record<string, string | number>;
+    };
+    path: string;
+    route?: string;
+    params?: Record<string, string>;
+    query?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * Turns some errors into responses. Return a value to send it (a body, a `Response`, or problem
+ * details, sent as `application/problem+json`), or `undefined` to pass the error to the next
+ * level. Filters are services: they can inject other services of their module.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TError The errors the filter handles.
+ */
+export interface ExceptionFilter<TError = any> {
+    catch(error: TError, ctx: FilterContext): unknown | Promise<unknown>;
+}
+/**
+ * A class of exception filter.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type FilterClass = Class<ExceptionFilter>;
+/**
+ * Declares which errors an exception filter handles, by class (`instanceof`). Without arguments,
+ * the filter handles every error. Only records metadata.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param errors The error classes handled by the filter.
+ * @example
+ * ```ts
+ * @Catch(PaymentDeclinedError)
+ * class PaymentFilter implements ExceptionFilter<PaymentDeclinedError> {
+ *   catch(error: PaymentDeclinedError) {
+ *     return { type: 'payment-declined', title: 'Payment declined', status: 402, reason: error.reason };
+ *   }
+ * }
+ * ```
+ */
+export declare const Catch: (...errors: Class<unknown>[]) => ClassDecorator;
+/**
+ * One level of filters (route, controller, module or app) and the module they run in.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type FilterLevel = {
+    filters: FilterClass[];
+    node: ModuleNode | null;
+};
+/** The filter levels below the app (route, controller, module) of each route handler. */
+export declare const routeFilterLevels: WeakMap<Function, FilterLevel[]>;
+/**
+ * The key under which a route stores its filter levels on the request context, once routed, so
+ * that the error hook finds them. Errors raised before routing (parsing) find them by route.
+ */
+export declare const FILTER_LEVELS: unique symbol;
+/**
+ * Runs the filters of each level in order, and returns the response of the first one that
+ * returns a value. Each filter runs in its module's context and in the request scope. A filter
+ * that throws is logged, and the original error goes on to the next filter.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param levels The levels, most specific first.
+ * @param error The error to handle.
+ * @param ctx The error context of the request.
+ * @returns The response, or `undefined` when no filter handled the error.
+ */
+export declare const runFilters: (levels: FilterLevel[], error: unknown, ctx: FilterContext) => Promise<{
+    response: unknown;
+} | undefined>;

package/dist/http-client.d.ts

@@ -0,0 +1,80 @@
+import { ElysiumError } from './errors';
+/**
+ * Sends a request to an application and returns its response, e.g. `(r) => elysia.handle(r)` or a
+ * Worker's `fetch`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type RequestHandler = (request: Request) => Promise<Response>;
+/**
+ * Raised by `TestResponse.expectStatus()` when the response has another status. The message holds
+ * the response body, so a failing test shows why the request failed.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class UnexpectedStatusError extends ElysiumError {
+    readonly expected: number;
+    readonly actual: number;
+    readonly body: string;
+    constructor(expected: number, actual: number, body: string);
+}
+/**
+ * A response from the HTTP test client.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TestResponse = Response & {
+    /** Parses the body as JSON. */
+    json<T = any>(): Promise<T>;
+    /**
+     * Checks the status, and throws an {@link UnexpectedStatusError} holding the body otherwise.
+     * @returns The response itself, with its body unread.
+     */
+    expectStatus(status: number): Promise<TestResponse>;
+};
+/**
+ * A request being built by the HTTP test client. Send it with `send()`, or await it directly.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class TestRequest implements PromiseLike<TestResponse> {
+    #private;
+    constructor(handle: RequestHandler, method: string, path: string, baseUrl: string);
+    /** Sets a request header. */
+    header(name: string, value: string): this;
+    /** Sets several request headers. */
+    headers(headers: Record<string, string>): this;
+    /** Adds query string parameters. Arrays add one parameter per value. */
+    query(params: Record<string, string | number | boolean | (string | number)[]>): this;
+    /** Sends a JSON body, with `content-type: application/json`. */
+    json(body: unknown): this;
+    /** Sends a URL-encoded form body. */
+    form(fields: Record<string, string>): this;
+    /** Sends a raw body: a string, bytes, a stream, `FormData` or `URLSearchParams`. */
+    body(body: BodyInit): this;
+    /** Builds the `Request` this builder describes, without sending it. */
+    toRequest(): Request;
+    /** Sends the request. */
+    send(): Promise<TestResponse>;
+    then<TResult1 = TestResponse, TResult2 = never>(onfulfilled?: ((value: TestResponse) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+/**
+ * An HTTP client that drives an application in memory, without a server.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type HttpTestClient = {
+    get(path: string): TestRequest;
+    post(path: string): TestRequest;
+    put(path: string): TestRequest;
+    patch(path: string): TestRequest;
+    delete(path: string): TestRequest;
+    head(path: string): TestRequest;
+    options(path: string): TestRequest;
+    /** Starts a request with any method. */
+    request(method: string, path: string): TestRequest;
+    /** Sends a prebuilt `Request` as is. */
+    send(request: Request): Promise<TestResponse>;
+};
+/**
+ * Creates an HTTP test client on top of a request handler.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param handle Sends a request to the application, e.g. `(r) => elysia.handle(r)`.
+ * @param baseUrl The origin relative paths resolve against. Defaults to `http://localhost`.
+ */
+export declare const createHttpClient: (handle: RequestHandler, baseUrl?: string) => HttpTestClient;