moost 0.5.28 → 0.5.30

package/dist/index.d.ts

@@ -2,7 +2,8 @@ import { useEventLogger } from '@wooksjs/event-core';
 export { ContextInjector, EventLogger, THook, getContextInjector, replaceContextInjector, useAsyncEventContext, useEventLogger } from '@wooksjs/event-core';
 import { TProvideRegistry, Infact, TReplaceRegistry, TProvideFn } from '@prostojs/infact';
 export { TProvideRegistry, createProvideRegistry, createReplaceRegistry } from '@prostojs/infact';
-import { TConsoleBase } from '@prostojs/logger';
+import * as _prostojs_logger from '@prostojs/logger';
+import { TConsoleBase, TProstoLoggerOptions, ProstoLogger } from '@prostojs/logger';
 export { ProstoLogger, TConsoleBase } from '@prostojs/logger';
 import { Hookable } from 'hookable';
 import * as _prostojs_mate from '@prostojs/mate';
@@ -20,17 +21,93 @@ interface TEmpty {
 
 declare function Circular<T = unknown>(resolver: () => TClassConstructor<T>): ParameterDecorator;
 
+/**
+ * Apply Multiple Decorators
+ *
+ * @param decorators - array of decorators
+ * @returns
+ */
+declare function ApplyDecorators(...decorators: (MethodDecorator | ClassDecorator | ParameterDecorator | PropertyDecorator)[]): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * ## Label
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Label metadata
+ */
 declare function Label(value: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * ## Description
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Description metadata
+ */
 declare function Description(value: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * ## Value
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Value metadata
+ */
 declare function Value(value: unknown): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * ## Id
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Id metadata
+ */
 declare function Id(value: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * ## Optional
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Optional metadata
+ */
 declare function Optional(): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * ## Required
+ * ### @Decorator
+ * _Common purpose decorator that may be used by various adapters for various purposes_
+ *
+ * Stores Required metadata
+ */
 declare function Required(): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
+/**
+ * ## Controller
+ * ### @Decorator
+ * Set Class as a Controller
+ * @param prefix - define the prefix for all the paths of this controller
+ */
 declare function Controller(prefix?: string): ClassDecorator;
+/**
+ * ## ImportController
+ * ### @Decorator
+ * Attach sub-controller
+ * @param controller - target controller (instance) to import
+ * @param provide - provide registry for the target controller
+ */
 declare function ImportController(controller: TFunction | TObject, provide?: TProvideRegistry): ClassDecorator;
+/**
+ * ## 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
+ */
 declare function ImportController(prefix: string, controller: TFunction | TObject, provide?: TProvideRegistry): ClassDecorator;
 
+/**
+ * ## Inherit
+ * ### @Decorator
+ * Inherit metadata from super class
+ * @returns
+ */
 declare const Inherit: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
 interface TClassFunction<T extends TAnyFn = TAnyFn> {
@@ -56,6 +133,14 @@ declare enum TInterceptorPriority {
     CATCH_ERROR = 5,
     AFTER_ALL = 6
 }
+/**
+ * ## Intercept
+ * ### @Decorator
+ * Set interceptor
+ * @param handler interceptor fn (use defineInterceptorFn)
+ * @param priority interceptor priority
+ * @returns
+ */
 declare function Intercept(handler: TCallableClassFunction<TInterceptorFn>, priority?: TInterceptorPriority, name?: string): ClassDecorator & MethodDecorator;
 
 type TDecoratorLevel = 'CLASS' | 'METHOD' | 'PROP' | 'PARAM';
@@ -70,8 +155,23 @@ declare function getMoostInfact(): Infact<TMoostMetadata<TEmpty>, TMoostMetadata
 interface TCustom {
     pipes?: TPipeData[];
 }
+/**
+ * Define global scope name to be used with `@InjectFromScope` and `@InjectScopeVars` decorators
+ *
+ * You can read scoped vars with `getInfactScopeVars`
+ * @param name scope name
+ * @param scopeVars key-value object as scoped vars
+ */
 declare function defineInfactScope<T extends object>(name: string | symbol, scopeVars: T): void;
+/**
+ * Read scoped vars defined with `defineInfactScope`
+ * @param name scope name
+ * @returns key-value object as scoped vars
+ */
 declare function getInfactScopeVars<T extends object>(name: string | symbol): T | undefined;
+/**
+ * Get Infact instance (used for Dependency Injections)
+ */
 declare function getNewMoostInfact(): Infact<TMoostMetadata<TEmpty>, TMoostMetadata<TEmpty>, TMoostParamsMetadata, TCustom>;
 
 interface TPipeMetas<T extends TObject = TEmpty> {
@@ -146,9 +246,9 @@ interface TInterceptorData {
     priority: TInterceptorPriority;
     name: string;
 }
-declare function getMoostMate<Class extends TObject = TEmpty, Prop extends TObject = TEmpty, Param extends TObject = TEmpty>(): Mate<TMoostMetadata<TEmpty> & Class & {
+declare function getMoostMate<Class extends TObject = TEmpty, Prop extends TObject = TEmpty, Param extends TObject = TEmpty>(): Mate<TMoostMetadata & Class & {
     params: Array<Param & TMateParamMeta>;
-}, TMoostMetadata<TEmpty> & Prop & {
+}, TMoostMetadata & Prop & {
     params: Array<Param & TMateParamMeta>;
 }>;
 interface TCommonMetaFields {
@@ -166,24 +266,119 @@ interface TCommonMoostMeta {
     type?: TFunction;
 }
 
+/**
+ * ## Injectable
+ * ### @Decorator
+ * Mark the Class as Injectable to enable it to be used in dependency injection
+ * @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
+ * @param label - field label
+ */
 declare function Injectable(scope?: true | TInjectableScope): ClassDecorator;
 
+/**
+ * Resolves event logger from event context
+ * @param topic
+ * @returns Resolver to '@wooksjs/event-core' (EventLogger)
+ */
 declare function InjectEventLogger(topic?: string): ParameterDecorator & PropertyDecorator;
+/**
+ * Resolves app-level logger
+ * @param topic - logger topic (can be overrided by @LoggerTopic)
+ * @returns
+ */
 declare function InjectMoostLogger(topic?: string): ParameterDecorator & PropertyDecorator;
+/**
+ * Sets logger topic (used in @InjectMoostLogger)
+ * @param topic - logger topic (banner)
+ * @returns
+ */
 declare function LoggerTopic(topic: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
+/**
+ * ## Pipe
+ * ### @Decorator
+ * Attach pipe
+ * @param handler pipe handler
+ * @param priority pipe priority
+ * @returns
+ */
 declare function Pipe(handler: TPipeFn, priority?: TPipePriority): ClassDecorator & MethodDecorator & ParameterDecorator;
 
+/**
+ * ## Provide
+ * ### @Decorator
+ * Defines provide registry for class (and all the children)
+ * @param type - string or class constructor
+ * @param fn - factory function for provided value
+ */
 declare function Provide(type: string | TClassConstructor, fn: TProvideFn): ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * ## Replace
+ * ### @Decorator
+ * Defines class to replace in DI
+ * @param type - class to replace
+ * @param newType - new class
+ */
 declare function Replace(type: TClassConstructor, newType: TClassConstructor): ClassDecorator;
+/**
+ * ## Inject
+ * ### @Decorator
+ * Defines a key from provide registry to inject value
+ * (For optional values use with @Optional())
+ * @param type - string or class constructor
+ */
 declare function Inject(type: string | TClassConstructor): ParameterDecorator & PropertyDecorator;
+/**
+ * Injects instance from scope
+ *
+ * (scope must be defined by `defineInfactScope` fn)
+ * @param name scope name
+ */
 declare function InjectFromScope(name: string | symbol): ParameterDecorator & PropertyDecorator;
+/**
+ * Inject vars from scope for instances
+ * instantiated with `@InjectFromScope` decorator
+ */
 declare function InjectScopeVars(name?: string): ParameterDecorator & PropertyDecorator;
 
+/**
+ * Hook to the Response Status
+ * @decorator
+ * @param resolver - resolver function
+ * @param label - field label
+ * @paramType unknown
+ */
 declare function Resolve<T extends TObject = TEmpty>(resolver: (metas: TPipeMetas<T>, level: TDecoratorLevel) => unknown, label?: string): ParameterDecorator & PropertyDecorator;
+/**
+ * Get Param Value from url parh
+ * @decorator
+ * @param name - param name
+ * @paramType string
+ */
 declare function Param(name: string): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * Get Parsed Params from url parh
+ * @decorator
+ * @paramType object
+ */
 declare function Params(): ParameterDecorator & PropertyDecorator;
+/**
+ * Provide Const Value
+ * @decorator
+ * @param value - provided value
+ * @param label - label of the field
+ * @paramType unknown
+ */
 declare function Const<T>(value: T, label?: string): ParameterDecorator & PropertyDecorator;
+/**
+ * Provide Const Value from Factory fn
+ * @decorator
+ * @param factory - value Factory fn
+ * @param label - label of the field
+ * @paramType unknown
+ */
 declare function ConstFactory<T>(factory: () => T | Promise<T>, label?: string): ParameterDecorator & PropertyDecorator;
 
 declare class InterceptorHandler {
@@ -271,9 +466,62 @@ interface THandlerOverview {
 type TContextInjectorHook = 'Event:start' | 'Interceptors:init' | 'Arguments:resolve' | 'Interceptors:before' | 'Handler' | 'Interceptors:after';
 
 interface TMoostOptions {
+    /**
+     * Prefix that is used for each event path
+     */
     globalPrefix?: string;
     logger?: TConsoleBase;
 }
+/**
+ * ## 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()
+ * ```
+ */
 declare class Moost extends Hookable {
     protected options?: TMoostOptions | undefined;
     protected logger: TConsoleBase;
@@ -287,18 +535,54 @@ declare class Moost extends Hookable {
     constructor(options?: TMoostOptions | undefined);
     _fireEventStart(source: TMoostAdapter<unknown>): void;
     _fireEventEnd(source: TMoostAdapter<unknown>): void;
+    /**
+     * ### 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 TMoostAdapter<TAny>>(a: T): T;
     getControllersOverview(): TControllerOverview[];
+    /**
+     * ### init
+     * Ititializes adapter. Must be called after adapters are attached.
+     */
     init(): Promise<void>;
     protected bindControllers(): Promise<void>;
     protected bindController(controller: TFunction | TObject, provide: TProvideRegistry, replace: TReplaceRegistry, globalPrefix: string, replaceOwnPrefix?: string): Promise<void>;
     applyGlobalPipes(...items: Array<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 IterceptorHandler
+     */
     getGlobalInterceptorHandler(): Promise<InterceptorHandler>;
     applyGlobalInterceptors(...items: Array<TInterceptorData['handler'] | TInterceptorData>): this;
+    /**
+     * Register new entries to provide as dependency injections
+     * @param provide - Provide Registry (use createProvideRegistry from '\@prostojs/infact')
+     * @returns
+     */
     setProvideRegistry(provide: TProvideRegistry): this;
+    /**
+     * Register replace classes to provide as dependency injections
+     * @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)
+     * @returns
+     */
     registerControllers(...controllers: Array<TObject | TFunction | [string, TObject | TFunction]>): this;
     logMappedHandler(eventName: string, classConstructor: Function, method: string, stroke?: boolean, prefix?: string): void;
 }
@@ -326,17 +610,17 @@ declare function useControllerContext<T extends object>(): {
     getRoute: () => string | undefined;
     getController: () => T;
     getMethod: () => string | undefined;
-    getControllerMeta: <TT_1 extends object>() => (TMoostMetadata<TEmpty> & TT_1 & {
-        params: (TT_1 & _prostojs_mate.TMateParamMeta)[];
+    getControllerMeta: <TT extends object>() => (TMoostMetadata<TEmpty> & TT & {
+        params: (TT & _prostojs_mate.TMateParamMeta)[];
     }) | undefined;
-    getMethodMeta: <TT_2 extends object>(name?: string) => (TMoostMetadata<TEmpty> & TT_2 & {
-        params: (TT_2 & _prostojs_mate.TMateParamMeta)[];
+    getMethodMeta: <TT extends object>(name?: string) => (TMoostMetadata<TEmpty> & TT & {
+        params: (TT & _prostojs_mate.TMateParamMeta)[];
     } & {
-        params: (TT_2 & _prostojs_mate.TMateParamMeta)[];
-    } & _prostojs_mate.TMateClassMeta<(TMoostMetadata<TEmpty> & TT_2 & {
-        params: (TT_2 & _prostojs_mate.TMateParamMeta)[];
-    })["params"][0]> & _prostojs_mate.TMatePropMeta<(TMoostMetadata<TEmpty> & TT_2 & {
-        params: (TT_2 & _prostojs_mate.TMateParamMeta)[];
+        params: (TT & _prostojs_mate.TMateParamMeta)[];
+    } & _prostojs_mate.TMateClassMeta<(TMoostMetadata<TEmpty> & TT & {
+        params: (TT & _prostojs_mate.TMateParamMeta)[];
+    })["params"][0]> & _prostojs_mate.TMatePropMeta<(TMoostMetadata<TEmpty> & TT & {
+        params: (TT & _prostojs_mate.TMateParamMeta)[];
     })["params"][0]>) | undefined;
     getPropertiesList: () => (string | symbol)[];
     getScope: () => true | TInjectableScope;
@@ -348,8 +632,74 @@ declare function useControllerContext<T extends object>(): {
     } & _prostojs_mate.TMateClassMeta<_prostojs_mate.TMateParamMeta & TMoostParamsMetadata & object> & _prostojs_mate.TMatePropMeta<_prostojs_mate.TMateParamMeta & TMoostParamsMetadata & object>) | undefined;
 };
 
+/**
+ * ### 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
+ */
 declare function defineInterceptorFn(fn: TInterceptorFn, priority?: TInterceptorPriority): TInterceptorFn;
+/**
+ * Class based interceptor interface
+ *
+ * Use it to create class-based interceptors and don't forget to make it **@Injectable()**
+ *
+ * @example
+ * "@Injectable()
+ * export class MyInterceptor implements TInterceptorClass {
+ *     static priority = TInterceptorPriority.INTERCEPTOR
+ *     handler: TInterceptorClass['handler'] = (before, after, onError) => {
+ *         before((reply) => {
+ *             console.log('before')
+ *         })
+ *         after((response, reply) => {
+ *             console.log('after')
+ *         })
+ *         onError((error, reply) => {
+ *             console.log('error')
+ *         })
+ *     }
+ * }
+ */
 type TInterceptorClass = TClassFunction<TInterceptorFn>;
+/**
+ * ### 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
+ */
 declare function definePipeFn<T extends TObject = TEmpty>(fn: TPipeFn<T>, priority?: TPipePriority): TPipeFn<T>;
 
-export { Circular, Const, ConstFactory, Controller, Description, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, InterceptorHandler, Label, LoggerTopic, Moost, Optional, Param, Params, Pipe, Provide, Replace, Required, Resolve, type TCallableClassFunction, type TClassConstructor, type TClassFunction, type TContextInjectorHook, type TControllerOverview, type TInjectableScope, type TInterceptorAfter, type TInterceptorBefore, type TInterceptorClass, type TInterceptorData, type TInterceptorFn, type TInterceptorOnError, TInterceptorPriority, type TMoostAdapter, type TMoostAdapterOptions, type TMoostEventHandlerHookOptions, type TMoostEventHandlerOptions, type TMoostHandler, type TMoostMetadata, type TMoostOptions, type TMoostParamsMetadata, type TPipeData, type TPipeFn, type TPipeMetas, TPipePriority, Value, defineInfactScope, defineInterceptorFn, defineMoostEventHandler, definePipeFn, getInfactScopeVars, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, useControllerContext };
+declare function createLogger(opts?: Partial<TProstoLoggerOptions>): ProstoLogger;
+declare const loggerConsoleTransport: _prostojs_logger.TProstoLoggerTransportFn<any>;
+
+export { ApplyDecorators, Circular, Const, ConstFactory, Controller, Description, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, InterceptorHandler, Label, LoggerTopic, Moost, Optional, Param, Params, Pipe, Provide, Replace, Required, Resolve, TInterceptorPriority, TPipePriority, Value, createLogger, defineInfactScope, defineInterceptorFn, defineMoostEventHandler, definePipeFn, getInfactScopeVars, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, loggerConsoleTransport, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, useControllerContext };
+export type { TCallableClassFunction, TClassConstructor, TClassFunction, TContextInjectorHook, TControllerOverview, TInjectableScope, TInterceptorAfter, TInterceptorBefore, TInterceptorClass, TInterceptorData, TInterceptorFn, TInterceptorOnError, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostOptions, TMoostParamsMetadata, TPipeData, TPipeFn, TPipeMetas };