@elysiumjs/core 0.10.0 → 0.11.0

package/dist/service.d.ts

@@ -1,4 +1,6 @@
 import type { Class } from 'type-fest';
+import type { ModuleNode } from './module-graph';
+import type { ServiceToken } from './token';
 /**
  * The scope of a service.
  * @author Axel Nana <axel.nana@workbud.com>
@@ -11,7 +13,13 @@ export declare enum ServiceScope {
     /**
      * A new instance of the service is created every time it is injected or retrieved.
      */
-    FACTORY = 1
+    FACTORY = 1,
+    /**
+     * One instance of the service is created per request, and shared by everything resolved
+     * while handling that request. Resolving it outside a request throws, and so does injecting
+     * it into a singleton.
+     */
+    REQUEST = 2
 }
 /**
  * A generic service class.
@@ -34,7 +42,9 @@ type FactoryFn<T> = () => T extends void ? never : T;
  */
 export type ServiceProps = Partial<{
     /**
-     * The name of the service. If not set, it will default to the service class name.
+     * The name (token) of the service. Without one, the service is identified by its class:
+     * inject it with `@Service.inject(TheClass)` or by its parameter type, and get it with
+     * `Service.get(TheClass)`.
      */
     name: string;
     /**
@@ -59,8 +69,8 @@ export type ServiceProps = Partial<{
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export type ServiceFactoryDefinition = {
-    /** The name of the service. */
-    name: string;
+    /** The token of the service: a name, or a class to register the service by class. */
+    name: ServiceToken;
     /** Builds the service from the owning module's config and a resolver for visible services. */
     factory: (config: any, get: <T>(name: string | Class<T>) => T) => unknown;
     /** The service's scope. Defaults to `ServiceScope.SINGLETON`. */
@@ -84,9 +94,11 @@ export declare namespace Service {
     /**
      * Resolves a registered service and set it as a parameter value.
      * @author Axel Nana <axel.nana@workbud.com>
-     * @param service An optional name for the service. If not set, the name of the parameter's type is used instead.
+     * @param service The name or class of the service. Without it, the parameter's type is used,
+     * which needs the compiler to emit decorator metadata (`emitDecoratorMetadata`).
+     * @throws {ElysiumError} When no service is given and the parameter type is unknown.
      */
-    const inject: (service?: string | ServiceClass) => ParameterDecorator;
+    const inject: (service?: ServiceToken) => ParameterDecorator;
     /**
      * Retrieves a service visible from the current module context (global services only
      * when there is none). Lazy services are built on first access.
@@ -95,14 +107,14 @@ export declare namespace Service {
      * @returns The service, or `null` if none with that name/type is visible.
      * @throws {ServiceNotReadyError} If the service, or its module, is still initialising.
      */
-    const get: <T>(service: string | TypedServiceClass<T>) => T | null;
+    const get: <T>(service: ServiceToken | TypedServiceClass<T>) => T | null;
     /**
      * Like `get`, but waits for the `onInit` of the service and of its owning module.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param service The name of the service, or its class.
      * @throws {ServiceNotFoundError | ServiceNotVisibleError | EnvironmentSkippedModuleError}
      */
-    const resolve: <T>(service: string | TypedServiceClass<T>) => Promise<T>;
+    const resolve: <T>(service: ServiceToken | TypedServiceClass<T>) => Promise<T>;
     /**
      * Registers a global lazy service that is only instantiated on first access.
      * @author Axel Nana <axel.nana@workbud.com>
@@ -127,7 +139,7 @@ export declare namespace Service {
      * Binds a service to the global scope and sets it as a singleton.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param service The service class to bind.
-     * @param name An optional name for the service. If not set, the name of the service class is used instead.
+     * @param name An optional name for the service. Without it, the service is bound to its class.
      */
     const bind: <T>(service: TypedServiceClass<T>, name?: string) => T;
     /**
@@ -141,7 +153,7 @@ export declare namespace Service {
      * Binds a service to the global scope and sets it as a factory.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param service The service class to bind.
-     * @param name An optional name for the service. If not set, the name of the service class is used instead.
+     * @param name An optional name for the service. Without it, the service is bound to its class.
      */
     function factory<T>(service: TypedServiceClass<T>, name?: string): T;
     /**
@@ -151,29 +163,53 @@ export declare namespace Service {
      * @param instance The instance to bind.
      * @throws {DuplicateGlobalServiceError} If a global service with that name exists.
      */
-    const instance: <T>(service: string | TypedServiceClass<T>, instance: T) => T;
+    const instance: <T>(service: ServiceToken | TypedServiceClass<T>, instance: T) => T;
     /**
      * Removes a service from the global scope.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param service The service class or name to remove.
      */
-    const remove: (service: string | TypedServiceClass<any>) => void;
+    const remove: (service: ServiceToken) => void;
     /**
      * Checks if a service exists in the global scope.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param service The service class or name to check.
      * @returns `true` if the service exists, `false` otherwise.
      */
-    const exists: (service: string | TypedServiceClass<any>) => boolean;
+    const exists: (service: ServiceToken) => boolean;
+    /**
+     * The modules that declare a service in their own scope, rather than as a global service, in
+     * registration order. Run code in one of them with `ModuleContext.run()` to resolve the service
+     * as that module sees it.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param service The service class or name.
+     * @returns The modules, empty when no module declares it.
+     */
+    const ownersOf: (service: ServiceToken) => readonly ModuleNode[];
     /**
      * Checks if a service has already been built, without building it.
      * Matches by name in any scope (global or module), not only the global one.
      * Lets modules release only the resources they actually created.
      * @author Axel Nana <axel.nana@workbud.com>
-     * @param name The name of the service to check.
+     * @param service The name or class of the service to check.
      * @returns `true` if the service has a live instance, `false` otherwise.
      */
-    const isConstructed: (name: string) => boolean;
+    const isConstructed: (service: ServiceToken) => boolean;
+    /**
+     * Runs `fn` in a request scope: request-scoped services resolved inside it, including in the
+     * asynchronous work it starts, share one instance. HTTP route handlers already run in one.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param fn The work to run, such as a job or a test.
+     */
+    const runInRequestScope: <T>(fn: () => T) => T;
+    /**
+     * Ends the request scope started for `key`, calling `onDestroy` on its request-scoped
+     * instances, the last created first. Errors are logged, never thrown, and a second call does
+     * nothing. Runtimes that keep a scope per request call this once the response is sent.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param key The request object the scope belongs to.
+     */
+    const disposeRequestScope: (key: object) => Promise<void>;
     /**
      * Clears the global scope.
      * @author Axel Nana <axel.nana@workbud.com>

package/dist/testing.d.ts

@@ -1,5 +1,8 @@
 import type { Class } from 'type-fest';
+import type { Application } from './app';
+import type { HttpTestClient } from './http-client';
 import type { ConfiguredModule, ModuleClass } from './module';
+import type { ServiceToken } from './token';
 import { Kernel } from './kernel';
 /**
  * Options of {@link Application.testing}.
@@ -8,8 +11,11 @@ import { Kernel } from './kernel';
 export type TestingOptions = {
     /** The modules to boot. */
     modules: (ModuleClass | ConfiguredModule<any>)[];
-    /** Services registered as globals; they win over module services of the same name. */
-    overrides?: Record<string, unknown>;
+    /**
+     * Services registered as globals; they win over module services with the same token.
+     * Give named services by name, or any service by class with a `Map`.
+     */
+    overrides?: Record<string, unknown> | Map<ServiceToken, unknown>;
     /** The environment to build the graph for. Defaults to `test`. */
     environment?: string;
     /** `eager` initialises every module and builds every service. Defaults to `lazy`. */
@@ -31,6 +37,43 @@ export type TestingApp = {
     /** Destroys the services and modules, and resets the container. */
     shutdown(): Promise<void>;
 };
+/**
+ * Empties the service container and clears its overrides, module visibility rules, module
+ * init hook and skipped-module lookup. The container is global to the process: call this
+ * between tests or scenarios that each boot their own application.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const resetContainer: () => void;
+/**
+ * Options of {@link Application.testing} for a whole application, driven over HTTP.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TestingAppOptions = {
+    /** The application class to build. It must not be started. */
+    app: new () => Application;
+    /**
+     * Services registered as globals before the application boots; they win over module services
+     * with the same token. Give named services by name, or any service by class with a `Map`.
+     */
+    overrides?: Record<string, unknown> | Map<ServiceToken, unknown>;
+};
+/**
+ * A built application under test, with an HTTP client that drives it in memory.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TestingHttpApp = TestingApp & {
+    /** The application instance. */
+    app: Application;
+    /** Sends requests to the application through `app.handle(Request)`, without a server. */
+    http: HttpTestClient;
+};
+/**
+ * Builds an application, as a host that owns the server would (`app.build()`), and returns an
+ * HTTP client for it. Modules boot on the first request.
+ * @param options See {@link TestingAppOptions}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function createTestingHttpApp(options: TestingAppOptions): Promise<TestingHttpApp>;
 /**
  * Boots a module graph without a CLI or an HTTP server.
  * @param options See {@link TestingOptions}.

package/dist/token.d.ts

@@ -0,0 +1,22 @@
+import type { Class } from 'type-fest';
+/**
+ * What identifies a service in the container: the name it is registered under, or its class.
+ *
+ * A class registered without a name is identified by the class itself, never by the class name,
+ * so services resolve the same way in minified builds, where bundlers rename classes.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ServiceToken = string | Class<any>;
+/**
+ * The token a service is registered under: a string as given, and for a class the name declared
+ * with `@Service.register({ name })`, or else the class itself.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param service The service name or class.
+ */
+export declare const tokenOf: (service: ServiceToken) => ServiceToken;
+/**
+ * A readable label for a token, for messages only: it must never be used to look a service up.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param token The service token.
+ */
+export declare const tokenLabel: (token: ServiceToken) => string;

package/dist/user.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The id of a user as guards leave it in `currentUser`: the user itself when it is a string or a
+ * number, else its `id`, else its `sub` (JWT claims).
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param user The user.
+ */
+export declare const userIdOf: (user: unknown) => string | undefined;
+/**
+ * The id of the user of the current request, read from `currentUser` in its context, which
+ * authentication middlewares set. `undefined` outside a request or without a user.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const currentUserId: () => string | undefined;

package/dist/utils.d.ts

@@ -11,7 +11,7 @@ export declare namespace Symbols {
     const arg: unique symbol;
     const elysiaPlugin: unique symbol;
     const middlewareGuards: unique symbol;
-    const eventListeners: unique symbol;
+    const lifecycleListeners: unique symbol;
     const serviceOptions: unique symbol;
     const module: unique symbol;
     const configuredModule: unique symbol;
@@ -20,12 +20,12 @@ export declare namespace Symbols {
 }
 /**
  * Gets the current environment name.
- * @returns `NODE_ENV`, or `development` when unset.
+ * @returns `NODE_ENV` from the runtime, or `development` when unset or when no runtime is set.
  *
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export declare function currentEnvironment(): string;
-export declare const nextTick: () => Promise<unknown>;
+export declare const nextTick: () => Promise<void>;
 /** The factory stored on a controller class; builds its Elysia plugin in a module's context. */
 export type ElysiaPlugin = (node: ModuleNode) => Promise<Elysia>;
 /**

package/dist/websocket.d.ts

@@ -1,27 +1,42 @@
-import type { ServerWebSocket } from 'bun';
-import type { Context, ErrorContext, TSchema } from 'elysia';
-import type { Class, ConditionalPick, JsonObject, Primitive } from 'type-fest';
+import type { Context, ErrorContext } from 'elysia';
+import type { Class } from 'type-fest';
+import type { TSchema } from 'typebox';
 import type { Route } from './http';
 /**
- * Properties required when declaring a websocket controller using the `@websocket()` decorator.
+ * The options of the websocket server, shared by every runtime.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type WebsocketProps<TWebsocketData = any> = {
-    /**
-     * The path of the websocket route.
-     */
-    path: Route;
-    /**
-     * The options for the websocket server.
-     */
-    options?: ConditionalPick<Bun.WebSocketHandler<TWebsocketData>, Primitive | JsonObject>;
+export type WebSocketHandlerOptions = {
+    /** Seconds of inactivity after which a connection is closed. */
+    idleTimeout?: number;
+    /** The largest message accepted, in bytes. */
+    maxPayloadLength?: number;
+    /** Whether messages are compressed. */
+    perMessageDeflate?: boolean | Record<string, unknown>;
+};
+/**
+ * A websocket connection, as seen by controllers. Structural, so that it fits every runtime.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TData Data stored in the connection.
+ */
+export type ElysiumWebSocket<TData = unknown> = {
+    /** Sends a message to the client. */
+    send(data: string | BufferSource, compress?: boolean): unknown;
+    /** Closes the connection. */
+    close(code?: number, reason?: string): unknown;
+    /** The data stored in the connection. */
+    data: TData;
+    /** Subscribes the connection to a topic. */
+    subscribe(topic: string): unknown;
+    /** Publishes a message to every subscriber of a topic. */
+    publish(topic: string, data: string | BufferSource, compress?: boolean): unknown;
 };
 /**
  * The websocket connection instance.
  * @author Axel Nana <axel.nana@workbud.com>
  * @template TData Additional data stored in the websocket connection.
  */
-export type WS<TData = unknown> = ServerWebSocket<{
+export type WS<TData = unknown> = ElysiumWebSocket<{
     /**
      * Unique identifier for the websocket connection.
      */
@@ -43,9 +58,15 @@ export declare namespace Websocket {
      * `onAfterResponse` run once the socket is upgraded: there is no response to read or replace.
      *
      * @author Axel Nana <axel.nana@workbud.com>
-     * @param props The websocket route properties.
+     * @param path The path of the websocket route.
+     * @param options The options of the websocket server.
+     * @example
+     * ```ts
+     * @Websocket.controller('/chat', { idleTimeout: 60 })
+     * class ChatController {}
+     * ```
      */
-    const controller: (props: WebsocketProps) => (target: Class<any>) => void;
+    const controller: (path: Route, options?: WebSocketHandlerOptions) => (target: Class<any>) => void;
     /**
      * Marks a method as the websocket "open" event handler.
      *

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elysiumjs/core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "Apache-2.0",
-  "description": "A super-charged web framework for Bun, built on top of ElysiaJS.",
+  "description": "A structured web framework built on ElysiaJS, for Bun, Node.js and Cloudflare Workers.",
   "private": false,
   "author": "Workbud Technologies Inc.",
   "repository": {
@@ -17,13 +17,15 @@
   "scripts": {
     "format": "prettier --write \"./src/**/*.ts\"",
     "clean": "rimraf dist",
-    "build:js": "bun build ./src/index.ts --outdir ./dist --target bun --packages external --root ./src --minify-syntax --minify-whitespace",
+    "build:js": "bun build ./src/index.ts --outdir ./dist --target node --packages external --root ./src --minify-syntax --minify-whitespace",
     "build:ts": "tsc",
     "build": "bun run clean && bun run build:js && bun run build:ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run build",
     "test": "bun test",
-    "test:coverage": "bun test --coverage"
+    "test:coverage": "bun test --coverage",
+    "check:runtime": "bun scripts/check-runtime.ts",
+    "check:minified": "bun scripts/check-minified.ts"
   },
   "keywords": [
     "elysium",
@@ -43,9 +45,13 @@
     "./src/index.ts"
   ],
   "dependencies": {
-    "@elysiajs/openapi": "^1.4.16",
-    "elysia": "^1.4.30",
+    "@elysia/openapi": "^2.0.0-rc.0",
+    "elysia": "^2.0.0-rc.1",
+    "exact-mirror": "^1.2.6",
+    "http-status": "^2.1.0",
+    "openapi-types": "^12.1.3",
     "radash": "^12.1.1",
+    "typebox": "^1.3.0",
     "wampy": "^8.0.2"
   },
   "trustedDependencies": [

package/dist/redis.d.ts

@@ -1,86 +0,0 @@
-/**
- * Properties used to create a new redis connection.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export type RedisConnectionProps = Bun.RedisOptions & {
-    url: string;
-};
-/**
- * Configuration of the {@link RedisModule}.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export type RedisModuleConfig = {
-    /** The name of the connection that `default` resolves to. */
-    default: string;
-    /** The connections to declare, by name. */
-    connections: Record<string, RedisConnectionProps>;
-};
-export declare namespace Redis {
-    /**
-     * Creates a service name for a redis connection.
-     * @author Axel Nana <axel.nana@workbud.com>
-     * @param name The name of the connection.
-     * @returns A service name for the connection.
-     */
-    const getConnectionName: (name: string) => string;
-    /**
-     * Retrieves the client for a redis connection declared by the {@link RedisModule}.
-     * @author Axel Nana <axel.nana@workbud.com>
-     * @param name The name of the connection.
-     * @returns The Bun.RedisClient for the connection with the given name.
-     * @throws {ServiceNotFoundError} If no connection with that name is declared.
-     */
-    const getConnection: (name?: string) => Bun.RedisClient;
-    /**
-     * Checks if a redis connection with the given name exists.
-     * @author Axel Nana <axel.nana@workbud.com>
-     * @param name The name of the connection to check.
-     * @returns `true` if the connection exists, `false` otherwise.
-     */
-    const connectionExists: (name: string) => boolean;
-    /**
-     * Retrieves the default redis connection.
-     * @author Axel Nana <axel.nana@workbud.com>
-     * @returns The default redis connection.
-     */
-    const getDefaultConnection: () => Bun.RedisClient;
-}
-declare const RedisModule_base: (abstract new () => {
-    get config(): RedisModuleConfig;
-    onInit(): Promise<void> | void;
-    onDestroy(): Promise<void> | void;
-    onServe(_app: import("elysia").default<any>): Promise<void> | void;
-}) & {
-    get config(): string;
-    with(config: Partial<RedisModuleConfig> | (() => Partial<RedisModuleConfig> | Promise<Partial<RedisModuleConfig>>)): import("./module").ConfiguredModule<RedisModuleConfig>;
-    resolveConfig(input?: Partial<RedisModuleConfig>): RedisModuleConfig;
-    register<TConfig = any>(props?: import("./module").ModuleProps<TConfig>): (target: import("./module").ModuleClass) => void;
-    configurable<TConfig extends object>(options?: {
-        defaults?: Partial<TConfig>;
-        required?: (keyof TConfig)[];
-    }): (abstract new () => {
-        get config(): TConfig;
-        onInit(): Promise<void> | void;
-        onDestroy(): Promise<void> | void;
-        onServe(_app: import("elysia").default<any>): Promise<void> | void;
-    }) & {
-        get config(): string;
-        with(config: Partial<TConfig> | (() => Partial<TConfig> | Promise<Partial<TConfig>>)): import("./module").ConfiguredModule<TConfig>;
-        resolveConfig(input?: Partial<TConfig>): TConfig;
-        register<TConfig_1 = any>(props?: import("./module").ModuleProps<TConfig_1>): (target: import("./module").ModuleClass) => void;
-        configurable<TConfig extends object>(options?: {
-            defaults?: Partial<TConfig>;
-            required?: (keyof TConfig)[];
-        }): /*elided*/ any;
-    };
-};
-/**
- * Declares redis connections as global services named `redis.connection.{name}`, plus
- * `redis.connection.default` aliasing the configured default. Clients are created on first use.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export declare class RedisModule extends RedisModule_base {
-    /** Closes the clients that were created. */
-    onDestroy(): Promise<void>;
-}
-export {};