moost 0.6.31 → 0.6.33

package/dist/index.d.ts

@@ -12,6 +12,43 @@ export { ProstoLogger, TConsoleBase } from '@prostojs/logger';
 import { Hookable } from 'hookable';
 export { clearGlobalWooks, getGlobalWooks } from 'wooks';
 
+/**
+ * Duplicate-copy detection for moost
+ *
+ * Mate stores decorator metadata in WeakMaps keyed by constructor
+ * reference, and moost keeps module-scoped DI singletons
+ * (`sharedMoostInfact`, `moostMate`). If a bundler loads two copies of
+ * moost, decorators run against one copy while lookups hit the other,
+ * and DI fails with distant "Class is not Injectable" errors. The first
+ * loaded copy stamps `globalThis` under a global symbol; any subsequent
+ * copy finds the stamp and warns.
+ */
+declare const MOOST_MODULE_IDENTITY_KEY: unique symbol;
+interface TMoostModuleIdentity {
+    version?: string;
+    path?: string;
+}
+/**
+ * Stamps the global object with this module's identity and warns when
+ * another copy of moost was already loaded — decorator metadata and DI
+ * singletons do not interoperate between copies.
+ *
+ * Exported for testability; invoked once at module scope.
+ */
+declare function stampModuleIdentity(identity: TMoostModuleIdentity, globalObject?: object): void;
+/**
+ * One-shot wrapper around `stampModuleIdentity` for this module copy.
+ *
+ * Invoked at module scope AND from `getMoostMate()`: the package ships
+ * `"sideEffects": false`, so a tree-shaking bundler may drop the
+ * module-scope invocation when nothing imports from this file — the
+ * `getMoostMate()` call keeps the duplicate check reachable in bundled
+ * apps (it fires on first decorator use, exactly when per-copy metadata
+ * divergence begins), which are the environments that produce duplicate
+ * copies in the first place.
+ */
+declare function stampOnce(): void;
+
 /** Escape-hatch type alias for `any`. */
 type TAny = any;
 /** Generic function signature accepting any arguments. */
@@ -172,6 +209,28 @@ interface TPipeData {
 
 declare const resolvePipe: TPipeFn<TEmpty>;
 
+/** Summary of a registered controller, its metadata, prefix, and handlers. */
+interface TControllerOverview {
+    meta: TMoostMetadata;
+    computedPrefix: string;
+    type: TFunction;
+    handlers: THandlerOverview[];
+}
+/** Summary of a registered handler method within a controller. */
+interface THandlerOverview {
+    meta: TMoostMetadata;
+    path?: string;
+    type: string;
+    method: string;
+    handler: TMoostHandler<TEmpty>;
+    registeredAs: {
+        path: string;
+        args: string[];
+    }[];
+}
+/** Hook points in the event handler lifecycle where context injectors are invoked. */
+type TContextInjectorHook = 'Event:start' | 'Interceptors:init' | 'Arguments:resolve' | 'Interceptors:before' | 'Handler' | 'Interceptors:after';
+
 type TInterceptorBeforeFn = (reply: (response: TAny) => void) => void | Promise<void>;
 type TInterceptorAfterFn = (response: TAny, reply: (response: TAny) => void) => void | Promise<void>;
 type TInterceptorErrorFn = (error: Error, reply: (response: TAny) => void) => void | Promise<void>;
@@ -328,6 +387,20 @@ declare function getInfactScopeVars<T extends object>(name: string | symbol): T
  */
 declare function getNewMoostInfact(): Infact<TMoostMetadata<TEmpty>, TMoostMetadata<TEmpty>, TMoostParamsMetadata, TCustom>;
 
+/**
+ * `fatal-capable` findings may reject `init()` (only non-optional constructor
+ * params — they would fail at instantiation anyway); `warn-only` findings are
+ * always logged as warnings and never thrown (silent `undefined` is legal there).
+ */
+type TParamAuditSeverity = 'fatal-capable' | 'warn-only';
+/** A single diagnostic produced by {@link auditParams}. */
+interface TParamAuditFinding {
+    message: string;
+    severity: TParamAuditSeverity;
+}
+/** Mode for the bind-time param-type audit (see `TMoostOptions['diagnostics']`). */
+type TParamAuditMode = 'error' | 'warn' | 'off';
+
 /**
  * A `@MoostInit`-decorated controller method, collected at bind time and run
  * once by `Moost.init()` after all controllers are bound. Interceptors are not
@@ -341,34 +414,101 @@ interface TInitHook {
     resolveArgs?: () => unknown[] | Promise<unknown[]>;
 }
 
-/** Summary of a registered controller, its metadata, prefix, and handlers. */
-interface TControllerOverview {
-    meta: TMoostMetadata;
-    computedPrefix: string;
-    type: TFunction;
-    handlers: THandlerOverview[];
-}
-/** Summary of a registered handler method within a controller. */
-interface THandlerOverview {
-    meta: TMoostMetadata;
-    path?: string;
-    type: string;
-    method: string;
-    handler: TMoostHandler<TEmpty>;
-    registeredAs: {
-        path: string;
-        args: string[];
-    }[];
-}
-/** Hook points in the event handler lifecycle where context injectors are invoked. */
-type TContextInjectorHook = 'Event:start' | 'Interceptors:init' | 'Arguments:resolve' | 'Interceptors:before' | 'Handler' | 'Interceptors:after';
+/** Mode for the bind-time inheritance audit (see `TMoostOptions['diagnostics']`). */
+type TInheritanceAuditMode = 'warn' | 'off';
 
 interface TMoostOptions {
     /**
-     * Prefix that is used for each event path
+     * Global path prefix — mounts the whole app under one path segment.
+     *
+     * This is the first-class "serve everything under `/api`" option: every
+     * controller (registered via `registerControllers`, imported through
+     * `@ImportController`, or the Moost subclass itself) computes its mount
+     * path as `globalPrefix + '/' + <own prefix>`, so
+     * `new Moost({ globalPrefix: 'api' })` mounts a `@Controller('users')`
+     * class at `/api/users` without touching any registration call.
+     *
+     * All registration forms stay under `globalPrefix` — even the
+     * prefix-replacing ones (`[prefix, Ctrl]` tuple, `mode: 'replace'`) only
+     * replace the controller's own `@Controller` prefix, never the global one.
+     * Extra/duplicate slashes are normalized by the router.
      */
     globalPrefix?: string;
     logger?: TConsoleBase;
+    /**
+     * Bind-time DI diagnostics, evaluated during `init()`.
+     *
+     * `paramTypes` audits constructor and handler params whose emitted design
+     * type is unusable for DI — `Object` (class imported with `import type`, or
+     * an interface/union type) or `undefined` (circular import) — and that carry
+     * no explicit resolution (`@Inject`, `@Resolve`-based decorators, `@Circular`):
+     * - `'error'` — log every finding and reject `init()` when a non-optional
+     *   constructor param is affected (it would fail at instantiation anyway);
+     * - `'warn'` — log findings, never throw;
+     * - `'off'` — skip the audit entirely.
+     *
+     * Defaults to `'error'` when `NODE_ENV !== 'production'`, `'warn'` otherwise.
+     * Optional/nullable constructor params and handler method params are always
+     * warn-only (`undefined` injection is legal there).
+     */
+    diagnostics?: {
+        paramTypes?: TParamAuditMode;
+        /**
+         * `inheritance` audits every registered controller for the two subclassing
+         * traps (warn-only, never rejects `init()`):
+         * - a class that registered 0 handlers while an ancestor defines some,
+         *   without a deliberate `@Inherit(false)` opt-out — parent routes
+         *   silently 404 (fires both when no `@Inherit` decision exists and when
+         *   `@Inherit()` is present but an undecorated intermediate class breaks
+         *   the chain — the warning names the broken link);
+         * - a DI-instantiated class with no effective constructor param metadata
+         *   while a decorated ancestor declares constructor params — dependencies
+         *   silently resolve to `undefined` (or the class is not seen as
+         *   injectable at all when it carries no metadata).
+         *
+         * `'warn'` (default) logs a warning naming both classes and the fix
+         * (`@Inherit()` or re-declaring); `'off'` skips the audit.
+         */
+        inheritance?: TInheritanceAuditMode;
+    };
+}
+/**
+ * Object registration form for {@link Moost.registerControllers}: mounts a
+ * group of controllers under a shared path prefix with explicit composition
+ * semantics (see `mode`).
+ */
+interface TControllersGroup {
+    /**
+     * Path segment applied to every controller of the group
+     * (always mounted under `globalPrefix` when one is set).
+     */
+    prefix: string;
+    /** Controllers (classes or instances) to register. */
+    controllers: (TObject | TFunction)[];
+    /**
+     * How `prefix` combines with each controller's own `@Controller(...)` prefix:
+     * - `'prepend'` (default) — `globalPrefix + '/' + prefix + '/' + own prefix`;
+     * - `'replace'` — `prefix` replaces the controller's own prefix
+     *   (same semantics as the `[prefix, controller]` tuple form).
+     */
+    mode?: 'prepend' | 'replace';
+}
+/**
+ * Normalized internal shape of a pending controller registration —
+ * `registerControllers` reduces all of its accepted forms to this.
+ */
+interface TControllerRegistration {
+    controller: TObject | TFunction;
+    /**
+     * Replaces the controller's own `@Controller` prefix
+     * (tuple form / object form with `mode: 'replace'`).
+     */
+    replaceOwnPrefix?: string;
+    /**
+     * Inserted between `globalPrefix` and the controller's own prefix
+     * (object form with `mode: 'prepend'`).
+     */
+    prependPrefix?: string;
 }
 /**
  * ## Moost
@@ -431,7 +571,15 @@ declare class Moost extends Hookable {
     protected initHooks: TInitHook[];
     protected provide: TProvideRegistry;
     protected replace: TReplaceRegistry;
-    protected unregisteredControllers: (TObject | TFunction | [string, TObject | TFunction])[];
+    protected unregisteredControllers: TControllerRegistration[];
+    /** D1 param-audit findings collected while binding controllers, flushed by `init()`. */
+    protected paramAuditFindings: TParamAuditFinding[];
+    /** Effective `diagnostics.paramTypes` mode, resolved once (see {@link TMoostOptions}). */
+    protected readonly paramAuditMode: TParamAuditMode;
+    /** Effective `diagnostics.inheritance` mode (see {@link TMoostOptions}). */
+    protected readonly inheritanceAuditMode: TInheritanceAuditMode;
+    /** D5: set once `init()` completes — late provide/replace registrations then warn. */
+    protected initialized: boolean;
     constructor(options?: TMoostOptions | undefined);
     _fireEventStart(source: TMoostAdapter<unknown>): void;
     _fireEventEnd(source: TMoostAdapter<unknown>): void;
@@ -469,6 +617,22 @@ declare class Moost extends Hookable {
      * A throwing hook rejects `init()` (fail-fast).
      */
     protected runInitHooks(): Promise<void>;
+    /**
+     * D1 audit of a DI-instantiated controller class' constructor params.
+     * Findings are collected for `init()` to flush. Returns `true` when the
+     * bind-time SINGLETON instantiation must be skipped: in `'error'` mode a
+     * fatal-capable finding guarantees `init()` rejects with the aggregated
+     * audit error (naming class and param), which the generic infact
+     * instantiation error would otherwise preempt.
+     */
+    protected collectConstructorAudit(className: string, classMeta?: TMoostMetadata): boolean;
+    /**
+     * Flushes D1 findings collected during binding: every finding is logged as a
+     * warning; in `'error'` mode, fatal-capable findings are folded into one
+     * aggregate error message listing all of them, returned for `init()` to
+     * throw (`init()` owns the precedence between this and a bind error).
+     */
+    protected flushParamAudit(): string | undefined;
     protected bindControllers(): Promise<void>;
     protected bindController(controller: TFunction | TObject, provide: TProvideRegistry, replace: TReplaceRegistry, globalPrefix: string, replaceOwnPrefix?: string): Promise<void>;
     applyGlobalPipes(...items: (TPipeFn | TPipeData)[]): this;
@@ -483,22 +647,60 @@ declare class Moost extends Hookable {
     applyGlobalInterceptors(...items: (TClassConstructor | TInterceptorDef | TInterceptorData)[]): this;
     /**
      * Register new entries to provide as dependency injections
+     *
+     * Ordering rule: call this **before `init()`**. `init()` snapshots the
+     * provide registry once when binding controllers, so entries added later are
+     * never seen by already-bound controllers (sibling registration order does
+     * not matter — only the before/after-`init()` boundary does). To scope
+     * providers to part of the app, use class-level `@Provide` on a parent
+     * controller — it flows parent → child through `@ImportController`, never
+     * to siblings.
      * @param provide - Provide Registry (use createProvideRegistry from '\@prostojs/infact')
      * @returns
      */
     setProvideRegistry(provide: TProvideRegistry): this;
     /**
      * Register replace classes to provide as dependency injections
+     *
+     * Ordering rule: call this **before `init()`**. `init()` snapshots the
+     * replace registry once when binding controllers, so replacements added
+     * later are never seen by already-bound controllers.
      * @param replace - Replace Registry (use createReplaceRegistry from '\@prostojs/infact')
      * @returns
      */
     setReplaceRegistry(replace: TReplaceRegistry): this;
     /**
-     * Register controllers (similar to @ImportController decorator)
-     * @param controllers - list of target controllers (instances)
+     * Register controllers with the app (similar to the `@ImportController` decorator).
+     *
+     * Accepted forms (mixable in one call):
+     *
+     * 1. **Class or instance** — `registerControllers(UsersController)`.
+     *    Mounted at `globalPrefix + '/' + own @Controller prefix`.
+     *
+     * 2. **Tuple `[prefix, controller]`** — `registerControllers(['api/users', UsersController])`.
+     *    **IMPORTANT: the string REPLACES the controller's own `@Controller(...)` prefix — it does
+     *    NOT prepend to it.** `['api', UsersController]` mounts a `@Controller('users')` class at
+     *    `/api`, not `/api/users`, so every tuple registration must repeat the full path.
+     *    To compose prefixes instead, use the object form below.
+     *
+     * 3. **Object group `{ prefix, controllers, mode? }`** —
+     *    `registerControllers({ prefix: 'api', controllers: [UsersController] })`.
+     *    Registers every entry of `controllers` under `prefix`:
+     *    - `mode: 'prepend'` (default) composes the prefixes:
+     *      `globalPrefix + '/' + prefix + '/' + own @Controller prefix`
+     *      (a `@Controller('users')` class mounts at `/api/users`);
+     *    - `mode: 'replace'` replaces each controller's own prefix with `prefix`
+     *      (same semantics as the tuple form).
+     *
+     * The object form is detected only for plain objects with a `controllers` array, so
+     * controller classes, instances and tuples keep working unchanged. To mount the whole
+     * app under one segment, prefer the `globalPrefix` option (see {@link TMoostOptions}).
+     *
+     * @param controllers - controllers to register: classes, instances,
+     *   `[prefix, controller]` tuples or `{ prefix, controllers, mode? }` groups
      * @returns
      */
-    registerControllers(...controllers: (TObject | TFunction | [string, TObject | TFunction])[]): this;
+    registerControllers(...controllers: (TObject | TFunction | [string, TObject | TFunction] | TControllersGroup)[]): this;
     logMappedHandler(eventName: string, classConstructor: Function, method: string, stroke?: boolean, prefix?: string): void;
 }
 interface TMoostAdapterOptions<H, T> {
@@ -797,11 +999,20 @@ declare function Resolve<T extends TObject = TEmpty>(resolver: (metas: TPipeMeta
  */
 declare function Param(name: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 /**
- * Get Parsed Params from url parh
+ * Get Parsed Params from url path
+ *
+ * Stamps `paramSource: 'ROUTE'` metadata (like `@Param(name)` does), so
+ * source-aware pipes (e.g. coercion pipes that only coerce string-transport
+ * input) recognize the whole params object as route input.
+ *
+ * Tip: type the argument with an interface-based DTO (e.g. an atscript `.as`
+ * interface) — interfaces emit as `declare class`, so the design type survives
+ * every metadata toolchain, unlike scalar type aliases which only survive
+ * syntactic emitters.
  * @decorator
  * @paramType object
  */
-declare function Params(): ParameterDecorator & PropertyDecorator;
+declare function Params(): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 /**
  * Provide Const Value
  * @decorator
@@ -1048,5 +1259,5 @@ declare function createLogger(opts?: Partial<TProstoLoggerOptions>): ProstoLogge
 /** Default colored console transport used by Moost loggers. */
 declare const loggerConsoleTransport: _prostojs_logger.TProstoLoggerTransportFn<any>;
 
-export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, LoggerTopic, Moost, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, createLogger, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, getHandlerPaths, getInfactScopeVars, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, globalKey, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, useControllerContext, useHandlerPaths, useInterceptResult, useOvertake, useScopeId };
-export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TEmpty, TFunction, TGetHandlerPathsOptions, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives };
+export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, LoggerTopic, MOOST_MODULE_IDENTITY_KEY, Moost, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, createLogger, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, getHandlerPaths, getInfactScopeVars, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, globalKey, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptResult, useOvertake, useScopeId };
+export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TControllerRegistration, TControllersGroup, TEmpty, TFunction, TGetHandlerPathsOptions, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostModuleIdentity, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives };