@elysiumjs/core 0.7.0 → 0.8.0

package/dist/middleware.d.ts

@@ -2,21 +2,31 @@ import type { AnyElysia } from 'elysia';
 import type { Class } from 'type-fest';
 import type { Context } from './http';
 import type { LoggerInterface } from './logger';
+import type { ModuleNode } from './module-graph';
 /**
  * Execute a chain of middlewares, stopping on the first return or throw.
  * @author Axel Nana <axel.nana@workbud.com>
  * @param middlewares The list of middleware instances to execute.
  * @param context The context to pass to each middleware.
  * @param method The method to call on each middleware.
+ * @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">) => Promise<any>;
+export declare const executeMiddlewareChain: (middlewares: Middleware[], context: any, method: Exclude<keyof Middleware, 'guards'>, node?: ModuleNode | null) => Promise<any>;
+/**
+ * Builds middleware instances in the context of a module.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param middlewares The middleware classes.
+ * @param node The owning module, or `null` to build them with global visibility only.
+ */
+export declare const makeMiddlewares: (middlewares: Class<Middleware>[], node: ModuleNode | null) => Middleware[];
 /**
  * Apply a list of middlewares to an Elysia plugin.
  * @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 applyMiddlewares: (middlewares: Class<Middleware>[], plugin: AnyElysia) => 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>

package/dist/module-context.d.ts

@@ -0,0 +1,20 @@
+import type { ModuleNode } from './module-graph';
+/**
+ * Tracks which module is currently being booted or is serving a request,
+ * so that service lookups can enforce module visibility.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare namespace ModuleContext {
+    /**
+     * Runs `fn` with `node` as the current module. The context follows async continuations.
+     * @param node The module to make current.
+     * @param fn The function to run.
+     * @returns The value returned by `fn`.
+     */
+    function run<T>(node: ModuleNode, fn: () => T): T;
+    /**
+     * Gets the module current in this async context, if any.
+     */
+    function current(): ModuleNode | undefined;
+}

package/dist/module-graph.d.ts

@@ -0,0 +1,68 @@
+import type { Class } from 'type-fest';
+import type { ConfiguredModule, ModuleClass, ModuleProps } from './module';
+/**
+ * A configuration given to a module from one import site.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ConfigSource = {
+    readonly site: string;
+    readonly depth: number;
+    readonly config: ConfiguredModule<unknown>['config'];
+};
+/**
+ * A module in the graph.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ModuleNode = {
+    readonly id: string;
+    readonly moduleClass: ModuleClass;
+    readonly props: ModuleProps;
+    readonly imports: readonly ModuleNode[];
+    readonly depth: number;
+    readonly configSources: readonly ConfigSource[];
+};
+type Collectable = 'controllers' | 'commands' | 'jobs';
+/**
+ * The resolved module graph.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ModuleGraph = {
+    /** Active modules, imports first. */
+    readonly nodes: readonly ModuleNode[];
+    /** Modules excluded by their `env`. */
+    readonly skipped: readonly ModuleClass[];
+    /** The environment the graph was built for. */
+    readonly environment: string;
+    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;
+    /** Gathers controllers, commands or jobs across modules, with their owner. */
+    collect<K extends Collectable>(key: K): readonly {
+        item: Class<any>;
+        module: ModuleNode;
+    }[];
+};
+type Entry = ModuleClass | ConfiguredModule<any>;
+/**
+ * Builds the module graph from decorator metadata. Pure: constructs nothing.
+ *
+ * @param rootModules The modules declared by the application.
+ * @param environment The active environment.
+ * @throws {ModuleCycleError} On an import cycle.
+ * @throws {DuplicateModuleNameError} When two different module classes share a name.
+ * @throws {DuplicateCommandError} When two modules register the same command.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function buildModuleGraph(rootModules: Entry[], environment?: string): ModuleGraph;
+/**
+ * Picks the configuration that applies to a module: the one from the lowest depth.
+ * Equal object-form configs at the same depth are accepted; different ones conflict.
+ * Function-form configs are not compared here.
+ *
+ * @throws {ConflictingModuleConfigError} When two different object configs tie.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function selectConfig(node: ModuleNode): ConfigSource | undefined;
+export {};

package/dist/module.d.ts

@@ -1,48 +1,106 @@
+import type { Elysia } from 'elysia';
 import type { Class } from 'type-fest';
+import type { CommandClass } from './command';
 import type { Route } from './http';
+import type { ServiceDefinition } from './service';
+import { Symbols } from './utils';
 /**
- * Properties required when declaring a module using the `@module()` decorator.
+ * Type for a module class.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type ModuleProps = {
-    /**
-     * The list of controllers provided by the module.
-     */
+export type ModuleClass = Class<Module>;
+/**
+ * A module bound to a configuration, as returned by `Module.with()`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ConfiguredModule<TConfig> = {
+    readonly [Symbols.configuredModule]: true;
+    readonly module: ModuleClass;
+    readonly config: Partial<TConfig> | (() => Partial<TConfig> | Promise<Partial<TConfig>>);
+};
+/**
+ * Properties used when declaring a module with `@Module.register()`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ModuleProps<TConfig = unknown> = {
+    /** Modules (or configured modules) whose exports this module can use. */
+    imports?: (ModuleClass | ConfiguredModule<any>)[];
+    /** The services this module provides, optionally derived from its resolved config. */
+    services?: ServiceDefinition[] | ((config: TConfig) => ServiceDefinition[]);
+    /** What this module exposes to importers, or `true` to expose everything. */
+    exports?: (Class<any> | string | ModuleClass)[] | true;
+    /** The controllers provided by the module. */
     controllers?: Class<any>[];
-    /**
-     * The list of jobs provided by the module.
-     */
+    /** The commands provided by the module. */
+    commands?: CommandClass[];
+    /** The jobs provided by the module. */
     jobs?: Class<any>[];
-    /**
-     * The base path for all the controllers registered by this module.
-     * This value will be prefixed to each controllers path.
-     */
+    /** The base path prefixed to every controller path of this module. */
     prefix?: Route;
+    /** Environments (`NODE_ENV` values) in which the module is active. */
+    env?: string[];
 };
 /**
- * Type for a module class.
+ * Checks whether a value is a configured module.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type ModuleClass = Class<Module>;
+export declare function isConfiguredModule(value: unknown): value is ConfiguredModule<unknown>;
+/**
+ * Reads the props a module class was declared with.
+ * @throws {InvalidModuleError} When the class is not decorated with `@Module.register()`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function getModuleProps(cls: ModuleClass): ModuleProps;
 /**
  * Base class for all modules.
  * @author Axel Nana <axel.nana@workbud.com>
- *
- * This class provides base features for modules, such as hooks and lifecycle methods.
  */
 export declare abstract class Module {
     /**
-     * Marks a class as a module.
+     * Marks a class as a module. Only stores metadata.
      * @author Axel Nana <axel.nana@workbud.com>
-     * @param options The decorator options.
      */
-    static register(options?: ModuleProps): (target: ModuleClass) => void;
+    static register<TConfig = any>(props?: ModuleProps<TConfig>): (target: ModuleClass) => void;
     /**
-     * Hooks that are executed before the module is registered.
-     */
-    beforeRegister(): Promise<void>;
-    /**
-     * Hooks that are executed after the module is registered.
+     * Creates a base class for modules that accept configuration.
+     * @author Axel Nana <axel.nana@workbud.com>
      */
-    afterRegister(): Promise<void>;
+    static configurable<TConfig extends object>(options?: {
+        defaults?: Partial<TConfig>;
+        required?: (keyof TConfig)[];
+    }): (abstract new () => {
+        /** The resolved configuration, set by the kernel. */
+        get config(): TConfig;
+        /** Called once the module's services are ready. */
+        onInit(): Promise<void> | void;
+        /** Called when the application shuts down. */
+        onDestroy(): Promise<void> | void;
+        /** Called with the Elysia app before it starts listening. */
+        onServe(_app: Elysia<any>): Promise<void> | void;
+    }) & {
+        /** Injection token of the resolved config of this module. */
+        get config(): string;
+        /** Binds a configuration to this module. */
+        with(config: Partial<TConfig> | (() => Partial<TConfig> | Promise<Partial<TConfig>>)): ConfiguredModule<TConfig>;
+        /**
+         * Merges the defaults with the input and checks required keys. Array defaults are
+         * concatenated with the user's arrays (primitives are de-duplicated), not replaced.
+         */
+        resolveConfig(input?: Partial<TConfig>): TConfig;
+        /**
+         * Marks a class as a module. Only stores metadata.
+         * @author Axel Nana <axel.nana@workbud.com>
+         */
+        register<TConfig_1 = any>(props?: ModuleProps<TConfig_1>): (target: ModuleClass) => void;
+        configurable<TConfig extends object>(options?: {
+            defaults?: Partial<TConfig>;
+            required?: (keyof TConfig)[];
+        }): /*elided*/ any;
+    };
+    /** Called once the module's services are ready. */
+    onInit(): Promise<void> | void;
+    /** Called when the application shuts down. */
+    onDestroy(): Promise<void> | void;
+    /** Called with the Elysia app before it starts listening. */
+    onServe(_app: Elysia<any>): Promise<void> | void;
 }

package/dist/redis.d.ts

@@ -5,27 +5,32 @@
 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 {
     /**
-     * Retrieves the client for a redis connection.
+     * Creates a service name for a redis connection.
      * @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.
+     * @returns A service name for the connection.
      */
-    const getConnection: (name: string) => Bun.RedisClient;
+    const getConnectionName: (name: string) => string;
     /**
-     * Creates and registers a new redis connection.
-     *
-     * This will make the registered connection available for dependency injection with
-     * the key `redis.connection.{name}`, where `{name}` is replaced with the given name.
-     *
+     * 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.
-     * @param config The configuration for the redis connection.
-     * @returns The newly created and registered redis connection.
+     * @returns The Bun.RedisClient for the connection with the given name.
+     * @throws {ServiceNotFoundError} If no connection with that name is declared.
      */
-    const registerConnection: (name: string, config: RedisConnectionProps) => Bun.RedisClient;
+    const getConnection: (name?: string) => Bun.RedisClient;
     /**
      * Checks if a redis connection with the given name exists.
      * @author Axel Nana <axel.nana@workbud.com>
@@ -39,11 +44,43 @@ export declare namespace Redis {
      * @returns The default redis connection.
      */
     const getDefaultConnection: () => Bun.RedisClient;
-    /**
-     * Sets the default redis connection.
-     * @author Axel Nana <axel.nana@workbud.com>
-     * @param name The name of the connection to set as default.
-     * @returns The default redis connection.
-     */
-    const setDefaultConnection: (name: string) => 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 {};

package/dist/service.d.ts

@@ -49,14 +49,38 @@ export type ServiceProps = Partial<{
      * @see ServiceScope
      */
     scope: ServiceScope;
+    /**
+     * Whether the service is visible from every module without being exported.
+     */
+    global: boolean;
 }>;
+/**
+ * Describes a service built by a factory function instead of a class.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ServiceFactoryDefinition = {
+    /** The name of the service. */
+    name: string;
+    /** 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`. */
+    scope?: ServiceScope;
+    /** Whether the service is visible from every module. */
+    global?: boolean;
+};
+/**
+ * Anything a module can list in its `services`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ServiceDefinition = Class<any> | ServiceFactoryDefinition;
 export declare namespace Service {
     /**
-     * Marks a class as a service
+     * Marks a class as a service. This only records metadata: the service is registered
+     * when the module that lists it is loaded.
      * @author Axel Nana <axel.nana@workbud.com>
-     * @param options The decorator options.
+     * @param props The service options.
      */
-    const register: (options?: ServiceProps) => (target: ServiceClass) => void;
+    const register: (props?: ServiceProps) => (target: ServiceClass) => void;
     /**
      * Resolves a registered service and set it as a parameter value.
      * @author Axel Nana <axel.nana@workbud.com>
@@ -64,22 +88,31 @@ export declare namespace Service {
      */
     const inject: (service?: string | ServiceClass) => ParameterDecorator;
     /**
-     * Retrieves a registered service's instance from the container.
-     * Resolves lazy services on first access and caches the result.
+     * Retrieves a service visible from the current module context (global services only
+     * when there is none). Lazy services are built on first access.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param service The name of the service, or its class.
-     * @returns An instance of the registered service, or `null` if no service with that name/type was registered.
+     * @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;
     /**
-     * Registers a lazy service that is only instantiated on first access.
+     * 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>;
+    /**
+     * Registers a global lazy service that is only instantiated on first access.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param name The name of the service.
      * @param resolver A factory function called on first access.
+     * @throws {DuplicateGlobalServiceError} If a global service with that name exists.
      */
     const registerLazy: <T>(name: string, resolver: () => T) => void;
     /**
-     * Instantiates a service with its dependencies.
+     * Instantiates a service with its dependencies, resolved from the current module context.
      *
      * This function always create a new instance of the service, even if the service's scope is `ServiceScope.SINGLETON`
      * and it has already been registered in the container.
@@ -87,56 +120,67 @@ export declare namespace Service {
      * @author Axel Nana <axel.nana@workbud.com>
      *
      * @param service The service class to instantiate.
+     * @throws {ServiceNotFoundError | ServiceNotVisibleError | EnvironmentSkippedModuleError}
      */
     const make: <T>(service: TypedServiceClass<T>) => T;
     /**
-     * Binds a service to the container and sets it as a singleton.
+     * 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.
      */
     const bind: <T>(service: TypedServiceClass<T>, name?: string) => T;
     /**
-     * Binds a service to the container and sets it as a factory.
+     * Binds a service to the global scope and sets it as a factory.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param name A name for the service.
      * @param factory The factory function used to instantiate the service.
      */
     function factory<T>(name: string, factory: FactoryFn<T>): T;
     /**
-     * Binds a service to the container and sets it as a factory.
+     * 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.
      */
     function factory<T>(service: TypedServiceClass<T>, name?: string): T;
     /**
-     * Binds a service's instance to the container.
+     * Binds a service's instance to the global scope.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param service The service class or name to bind.
      * @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;
     /**
-     * Removes a service from the container.
+     * 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;
     /**
-     * Checks if a service exists in the container.
+     * 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;
     /**
-     * Clears the container.
+     * 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.
+     * @returns `true` if the service has a live instance, `false` otherwise.
+     */
+    const isConstructed: (name: string) => boolean;
+    /**
+     * Clears the global scope.
      * @author Axel Nana <axel.nana@workbud.com>
      */
     const clear: () => void;
     /**
-     * Returns an array of registered service names matching the given pattern.
+     * Returns an array of global service names matching the given pattern.
      * Pattern supports '*' (any sequence) and '?' (any single character), similarly to Redis KEYS.
      * @author Axel Nana <axel.nana@workbud.com>
      * @param pattern The glob-like pattern to match service names.

package/dist/testing.d.ts

@@ -0,0 +1,39 @@
+import type { Class } from 'type-fest';
+import type { ConfiguredModule, ModuleClass } from './module';
+import { Kernel } from './kernel';
+/**
+ * Options of {@link Application.testing}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+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>;
+    /** The environment to build the graph for. Defaults to `test`. */
+    environment?: string;
+    /** `eager` initialises every module and builds every service. Defaults to `lazy`. */
+    boot?: 'lazy' | 'eager';
+};
+/**
+ * A booted module graph, for tests.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type TestingApp = {
+    /** The kernel running the graph. */
+    kernel: Kernel;
+    /**
+     * Resolves a service, optionally from inside a module, so that visibility applies.
+     * @param name The service name or class.
+     * @param from The module to resolve from. Defaults to global lookups only.
+     */
+    get<T>(name: string | Class<T>, from?: ModuleClass): Promise<T>;
+    /** Destroys the services and modules, and resets the container. */
+    shutdown(): Promise<void>;
+};
+/**
+ * Boots a module graph without a CLI or an HTTP server.
+ * @param options See {@link TestingOptions}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function createTestingApp(options: TestingOptions): Promise<TestingApp>;

package/dist/utils.d.ts

@@ -1,4 +1,5 @@
 import type { Elysia } from 'elysia';
+import type { ModuleNode } from './module-graph';
 export declare namespace Symbols {
     const app: unique symbol;
     const controller: unique symbol;
@@ -7,19 +8,35 @@ export declare namespace Symbols {
     const websocket: unique symbol;
     const wamp: unique symbol;
     const http: unique symbol;
-    const job: unique symbol;
     const arg: unique symbol;
     const elysiaPlugin: unique symbol;
     const middlewareGuards: unique symbol;
+    const eventListeners: unique symbol;
+    const serviceOptions: unique symbol;
+    const module: unique symbol;
+    const configuredModule: unique symbol;
+    const moduleConfig: unique symbol;
+    const command: unique symbol;
 }
+/**
+ * Gets the current environment name.
+ * @returns `NODE_ENV`, or `development` when unset.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare function currentEnvironment(): string;
 export declare const nextTick: () => Promise<unknown>;
-export type ElysiaPlugin = () => Promise<Elysia>;
+/** The factory stored on a controller class; builds its Elysia plugin in a module's context. */
+export type ElysiaPlugin = (node: ModuleNode) => Promise<Elysia>;
 /**
- * Deeply merges objects from right to left
- * Arrays are also merged if they are found in child objects
+ * Deeply merges objects from right to left. The target's values win over the sources'.
+ * Arrays are also merged if they are found in child objects.
+ *
+ * Neither `target` nor any source is mutated, and the result shares no plain object or
+ * array with them. Class instances and functions are kept by reference.
  *
- * @param target The target object to merge into
- * @param sources One or more source objects to merge from
- * @returns The merged object (same reference as target)
+ * @param target The base object
+ * @param sources One or more source objects providing the missing values
+ * @returns A new merged object
  */
 export declare function deepMerge<T extends Record<string, any | any[]>>(target: T, ...sources: T[]): T;