moost 0.2.26 → 0.2.28

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 import { Infact } from '@prostojs/infact';
 import { Mate } from '@prostojs/mate';
 import { TConsoleBase } from '@prostojs/logger';
+import { TMateClassMeta } from '@prostojs/mate';
+import { TMateParamMeta } from '@prostojs/mate';
+import { TMatePropMeta } from '@prostojs/mate';
 import { TProvideFn } from '@prostojs/infact';
 import { TProvideRegistry } from '@prostojs/infact';
 import { TValidoDtoOptions } from '@prostojs/valido';
 import { TValidoFn } from '@prostojs/valido';
+import { useEventLogger } from '@wooksjs/event-core';
 import { validoIsBoolean } from '@prostojs/valido';
 import { validoIsNumber } from '@prostojs/valido';
 import { validoIsString } from '@prostojs/valido';
@@ -30,12 +34,68 @@ export declare function Const<T>(value: T, label?: string): ParameterDecorator &
 export declare function ConstFactory<T>(factory: () => T | Promise<T>, label?: string): ParameterDecorator & PropertyDecorator;
 
 /**
+ * ## Controller
+ * ### @Decorator
  * Set Class as a Controller
- * @decorator
  * @param prefix - define the prefix for all the paths of this controller
  */
 export declare function Controller(prefix?: string): ClassDecorator;
 
+/**
+ * ### Define Interceptor Function
+ *
+ * ```ts
+ * defineInterceptorFn((before, after, onError) => {
+ *         //init
+ *         before(() => {
+ *              // before handler
+ *         })
+ *         after((response, reply) => {
+ *              // after handler
+ *         })
+ *         onError((error, reply) => {
+ *              // when error occured
+ *         })
+ *     },
+ *     TInterceptorPriority.INTERCEPTOR,
+ * )
+ * ```
+ *
+ * @param fn interceptor function
+ * @param priority priority of the interceptor where BEFORE_ALL = 0, BEFORE_GUARD = 1, GUARD = 2, AFTER_GUARD = 3, INTERCEPTOR = 4, CATCH_ERROR = 5, AFTER_ALL = 6
+ * @returns
+ */
+export declare function defineInterceptorFn(fn: TInterceptorFn, priority?: TInterceptorPriority): TInterceptorFn;
+
+export declare function defineMoostEventHandler<T>(options: TMoostEventHandlerOptions<T>): () => Promise<unknown>;
+
+/**
+ * ### Define Pipe Function
+ *
+ * ```ts
+ * // example of a transform pipe
+ * const uppercaseTransformPipe = definePipeFn((value, metas, level) => {
+ *         return typeof value === 'string' ? value.toUpperCase() : value
+ *     },
+ *     TPipePriority.TRANSFORM,
+ * )
+ * ```
+ *
+ * @param fn interceptor function
+ * @param priority priority of the pipe where BEFORE_RESOLVE = 0, RESOLVE = 1, AFTER_RESOLVE = 2, BEFORE_TRANSFORM = 3, TRANSFORM = 4, AFTER_TRANSFORM = 5, BEFORE_VALIDATE = 6, VALIDATE = 7, AFTER_VALIDATE = 8
+ * @returns
+ */
+export declare function definePipeFn(fn: TPipeFn, priority?: TPipePriority): TPipeFn<TEmpty>;
+
+/**
+ * ## Description
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Description metadata
+ */
+export declare function Description(value: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+
 export declare function Dto(dtoOptions?: TValidoDtoOptions): ClassDecorator;
 
 export declare const genericTypesCastPipe: (strict?: boolean) => TPipeFn;
@@ -46,28 +106,45 @@ export declare function getMoostMate<Class extends TObject = TEmpty, Prop extend
 
 export declare function getNewMoostInfact(): Infact<TMoostMetadata, TMoostMetadata, TMoostParamsMetadata, TCustom>;
 
+/**
+ * ## Id
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Id metadata
+ */
 export declare function Id(value: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
 /**
- * Set Class as a Controller
- * @decorator
+ * ## ImportController
+ * ### @Decorator
+ * Attach sub-controller
  * @param controller - target controller (instance) to import
  * @param provide - provide registry for the target controller
  */
 export declare function ImportController(controller: TFunction | TObject, provide?: TProvideRegistry): ClassDecorator;
 
 /**
- * Set Class as a Controller
- * @decorator
+ * ## ImportController
+ * ### @Decorator
+ * Attach sub-controller
  * @param prefix - redefine the prefix for all the paths of this controller
  * @param controller - point to a controller (instance) to import
  * @param provide - provide registry for the target controller
  */
 export declare function ImportController(prefix: string, controller: TFunction | TObject, provide?: TProvideRegistry): ClassDecorator;
 
+/**
+ * ## Inherit
+ * ### @Decorator
+ * Inherit metadata from super class
+ * @returns
+ */
 export declare const Inherit: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
 /**
+ * ## Inject
+ * ### @Decorator
  * Defines a key from provide registry to inject value
  * (For optional values use with @Nullable())
  * @param type - string or class constructor
@@ -75,8 +152,9 @@ export declare const Inherit: () => MethodDecorator & ClassDecorator & Parameter
 export declare function Inject(type: string | TClassConstructor): ParameterDecorator;
 
 /**
+ * ## Injectable
+ * ### @Decorator
  * Mark the Class as Injectable to enable it to be used in dependency injection
- * @decorator
  * @param scope - Scope for injection ("FOR_EVENT" | "SINGLETON" | true)
  * FOR_EVENT - will create a new instance for each incoming request
  * SINGLETON | true - will create a new instance only once
@@ -91,6 +169,14 @@ export declare function Injectable(scope?: true | TInjectableScope): ClassDecora
  */
 export declare function InjectEventLogger(topic?: string): ParameterDecorator & PropertyDecorator;
 
+/**
+ * ## Intercept
+ * ### @Decorator
+ * Set interceptor
+ * @param handler interceptor fn (use defineInterceptorFn)
+ * @param priority interceptor priority
+ * @returns
+ */
 export declare function Intercept(handler: TCallableClassFunction<TInterceptorFn>, priority?: TInterceptorPriority): ClassDecorator & MethodDecorator;
 
 export declare class InterceptorHandler {
@@ -102,7 +188,7 @@ export declare class InterceptorHandler {
     response?: unknown;
     responseOverwritten: boolean;
     replyFn(reply: unknown): void;
-    init(): Promise<void>;
+    init(): Promise<unknown>;
     fireBefore(response: unknown): Promise<unknown>;
     fireAfter(response: unknown): Promise<unknown>;
 }
@@ -117,8 +203,65 @@ export declare function IsString(...args: Parameters<typeof validoIsString>): Pr
 
 export declare function IsTypeOf(type: 'string' | 'object' | 'number' | 'boolean', errorText?: string): PropertyDecorator & ParameterDecorator;
 
+/**
+ * ## Label
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Label metadata
+ */
 export declare function Label(value: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
+/**
+ * ## Moost
+ * Main moostjs class that serves as a shell for Moost Adapters
+ *
+ * ### Usage with HTTP Adapter
+ * ```ts
+ * │  // HTTP server example
+ * │  import { MoostHttp, Get } from '@moostjs/event-http'
+ * │  import { Moost, Param } from 'moost'
+ * │
+ * │  class MyServer extends Moost {
+ * │      @Get('test/:name')
+ * │      test(@Param('name') name: string) {
+ * │          return { message: `Hello ${name}!` }
+ * │      }
+ * │  }
+ * │
+ * │  const app = new MyServer()
+ * │  const http = new MoostHttp()
+ * │  app.adapter(http).listen(3000, () => {
+ * │      app.getLogger('MyApp').log('Up on port 3000')
+ * │  })
+ * │  app.init()
+ * ```
+ * ### Usage with CLI Adapter
+ * ```ts
+ * │  // CLI example
+ * │  import { MoostCli, Cli, CliOption, cliHelpInterceptor } from '@moostjs/event-cli'
+ * │  import { Moost, Param } from 'moost'
+ * │
+ * │  class MyApp extends Moost {
+ * │      @Cli('command/:arg')
+ * │      command(
+ * │         @Param('arg')
+ * │         arg: string,
+ * │         @CliOption('test', 't')
+ * │         test: boolean,
+ * │      ) {
+ * │          return `command run with flag arg=${ arg }, test=${ test }`
+ * │      }
+ * │  }
+ * │
+ * │  const app = new MyApp()
+ * │  app.applyGlobalInterceptors(cliHelpInterceptor())
+ * │
+ * │  const cli = new MoostCli()
+ * │  app.adapter(cli)
+ * │  app.init()
+ * ```
+ */
 export declare class Moost {
     protected options?: TMoostOptions | undefined;
     protected logger: TConsoleBase;
@@ -128,12 +271,35 @@ export declare class Moost {
     protected provide: TProvideRegistry;
     protected unregisteredControllers: (TObject | TFunction)[];
     constructor(options?: TMoostOptions | undefined);
+    /**
+     * ### getLogger
+     * Provides application logger
+     * ```js
+     * // get logger with topic = "App"
+     * const logger = app.getLogger('App')
+     * logger.log('...')
+     * ```
+     * @param topic
+     * @returns
+     */
     getLogger(topic: string): TConsoleBase;
-    adapter<T extends object, A extends TMoostAdapter<T>>(a: A): A;
+    adapter<T>(a: TMoostAdapter<T>): TMoostAdapter<T>;
+    /**
+     * ### init
+     * Ititializes adapter. Must be called after adapters are attached.
+     */
     init(): Promise<void>;
     protected bindControllers(): Promise<void>;
     protected bindController(controller: TFunction | TObject, provide: TProvideRegistry, globalPrefix: string, replaceOwnPrefix?: string): Promise<void>;
     applyGlobalPipes(...items: (TPipeFn | TPipeData)[]): this;
+    protected globalInterceptorHandler?: Promise<InterceptorHandler>;
+    /**
+     * Provides InterceptorHandler with global interceptors and pipes.
+     * Used to process interceptors when event handler was not found.
+     *
+     * @returns array of interceptors
+     */
+    getGlobalInterceptorHandler(): Promise<InterceptorHandler>;
     applyGlobalInterceptors(...items: (TInterceptorData['handler'] | TInterceptorData)[]): this;
     /**
      * Register new entried to provide as dependency injections
@@ -150,11 +316,20 @@ export declare class Moost {
 }
 
 /**
+ * ## Nullable
+ * ### @Decorator
  * Makes injectable value optional
  * @param value default true
  */
 export declare function Nullable(v?: boolean): ParameterDecorator;
 
+/**
+ * ## Optional
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Optional metadata
+ */
 export declare function Optional(): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
 /**
@@ -163,7 +338,7 @@ export declare function Optional(): MethodDecorator & ClassDecorator & Parameter
  * @param name - param name
  * @paramType string
  */
-export declare function Param(name: string): ParameterDecorator & PropertyDecorator;
+export declare function Param(name: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
 /**
  * Get Parsed Params from url parh
@@ -173,12 +348,23 @@ export declare function Param(name: string): ParameterDecorator & PropertyDecora
 export declare function Params(): ParameterDecorator & PropertyDecorator;
 
 /**
+ * ## Provide
+ * ### @Decorator
  * Defines provide registry for class (and all the children)
  * @param type - string or class constructor
  * @param fn - factory function for provided value
  */
 export declare function Provide(type: string | TClassConstructor, fn: TProvideFn): ClassDecorator;
 
+export declare function registerEventScope(scopeId: string): () => void;
+
+/**
+ * ## Required
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Required metadata
+ */
 declare function Required_2(): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 export { Required_2 as Required }
 
@@ -191,7 +377,9 @@ export { Required_2 as Required }
  */
 export declare function Resolve<T extends TObject = TEmpty>(resolver: (metas: TPipeMetas<T>, level: TDecoratorLevel) => unknown, label?: string): ParameterDecorator & PropertyDecorator;
 
-export declare const resolvePipe: TPipeFn;
+export declare const resolvePipe: TPipeFn<TEmpty>;
+
+export declare function setControllerContext<T>(controller: T, method: keyof T): void;
 
 declare type TAny = any;
 
@@ -214,6 +402,8 @@ declare interface TClassFunctionConstructor<T extends TAnyFn = TAnyFn> {
 declare interface TCommonMetaFields {
     id?: string;
     label?: string;
+    value?: unknown;
+    description?: string;
     optional?: boolean;
     required?: boolean;
 }
@@ -245,13 +435,15 @@ export declare type TInterceptorAfter = (response: TAny, reply: (response: TAny)
 
 export declare type TInterceptorBefore = (reply: (response: TAny) => void) => void | Promise<void>;
 
+export declare type TInterceptorClass = TClassFunction<TInterceptorFn>;
+
 export declare interface TInterceptorData {
     handler: TCallableClassFunction<TInterceptorFn>;
     priority: TInterceptorPriority;
 }
 
 export declare type TInterceptorFn = {
-    (before: (fn: TInterceptorBefore) => void, after: (fn: TInterceptorAfter) => void, onError: (fn: TInterceptorOnError) => void): void | Promise<void>;
+    (before: (fn: TInterceptorBefore) => void, after: (fn: TInterceptorAfter) => void, onError: (fn: TInterceptorOnError) => void): unknown | Promise<unknown>;
     priority?: TInterceptorPriority;
 };
 
@@ -267,25 +459,51 @@ export declare enum TInterceptorPriority {
     AFTER_ALL = 6
 }
 
-export declare interface TMoostAdapter<H extends object> {
+export declare interface TMoostAdapter<H> {
     bindHandler<T extends TObject = TObject>(options: TMoostAdapterOptions<H, T>): void | Promise<void>;
-    onInit?: () => void | Promise<void>;
+    onInit?: (moost: Moost) => void | Promise<void>;
     getProvideRegistry?: () => TProvideRegistry;
 }
 
-export declare interface TMoostAdapterOptions<H extends object, T extends object> {
+export declare interface TMoostAdapterOptions<H, T> {
     prefix: string;
     fakeInstance: T;
     getInstance: () => Promise<T>;
     method: keyof T;
     handlers: TMoostHandler<H>[];
     getIterceptorHandler: () => Promise<InterceptorHandler>;
-    registerEventScope: (scopeId: string) => () => void;
     resolveArgs: () => Promise<unknown[]>;
     logHandler: (eventName: string) => void;
 }
 
-export declare type TMoostHandler<T extends object> = T & {
+export declare interface TMoostEventHandlerHookOptions<T> {
+    restoreCtx: () => void;
+    scopeId: string;
+    logger: ReturnType<typeof useEventLogger>;
+    unscope: () => void;
+    instance?: T;
+    method?: keyof T;
+    getResponse: () => unknown;
+    reply: (r: unknown) => void;
+}
+
+export declare interface TMoostEventHandlerOptions<T> {
+    contextType?: string | string[];
+    loggerTitle: string;
+    getIterceptorHandler: () => Promise<InterceptorHandler> | InterceptorHandler | undefined;
+    getControllerInstance: () => Promise<T> | T | undefined;
+    controllerMethod?: keyof T;
+    callControllerMethod?: (args: unknown[]) => unknown;
+    resolveArgs?: () => Promise<unknown[]> | unknown[];
+    logErrors?: boolean;
+    manualUnscope?: boolean;
+    hooks?: {
+        init?: (opts: TMoostEventHandlerHookOptions<T>) => unknown;
+        end?: (opts: TMoostEventHandlerHookOptions<T>) => unknown;
+    };
+}
+
+export declare type TMoostHandler<T> = T & {
     type: string;
 };
 
@@ -308,6 +526,9 @@ export declare interface TMoostMetadata extends TCommonMetaFields, TCommonMoostM
 }
 
 export declare interface TMoostOptions {
+    /**
+     * Prefix that is used for each event path
+     */
     globalPrefix?: string;
     logger?: TConsoleBase;
 }
@@ -316,6 +537,7 @@ export declare interface TMoostParamsMetadata extends TCommonMetaFields, TCommon
     circular?: () => TAny;
     inject?: string | symbol | TClassConstructor;
     nullable?: boolean;
+    isRouteParam?: string;
 }
 
 declare type TObject = object;
@@ -363,8 +585,24 @@ declare interface TValidatePipeOptions {
     errorCb?: (message: string, details: string | TObject) => unknown;
 }
 
+export declare function useControllerContext<T extends object>(): {
+    getController: () => T;
+    getMethod: () => keyof T;
+    getControllerMeta: () => Partial<TMoostMetadata & TEmpty & TMateClassMeta & TMatePropMeta<TMoostMetadata & TMoostParamsMetadata & TEmpty> & TMoostParamsMetadata & TMateParamMeta> | undefined;
+    getMethodMeta: () => Partial<TMoostMetadata & TEmpty & TMateClassMeta & TMatePropMeta<TMoostMetadata & TMoostParamsMetadata & TEmpty> & TMoostParamsMetadata & TMateParamMeta> | undefined;
+};
+
 export declare function Validate<T = unknown>(validator: TValidoFn<T>): PropertyDecorator & ParameterDecorator;
 
 export declare const validatePipe: (opts?: TValidatePipeOptions) => TPipeFn;
 
+/**
+ * ## Value
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Value metadata
+ */
+export declare function Value(value: unknown): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+
 export { }