@plumjs/core/lib/core.d.ts

/// <reference types="koa-bodyparser" />
/// <reference types="node" />
import { IncomingHttpHeaders } from "http";
import Koa, { Context, Request } from "koa";
import { ClassReflection, MethodReflection, ParameterReflection } from "tinspector";
export declare type HttpMethod = "post" | "get" | "put" | "delete";
export declare type KoaMiddleware = (ctx: Context, next: () => Promise<void>) => Promise<any>;
export declare type RequestPart = keyof Request;
export declare type HeaderPart = keyof IncomingHttpHeaders;
export declare type Class = new (...args: any[]) => any;
export declare type DefaultConverter = "Boolean" | "Number" | "Date" | "Object" | "Array";
export declare type Converters = {
    default: {
        [key in DefaultConverter]: ConverterFunction;
    };
    converters: Map<Function, ConverterFunction>;
};
export declare type ConverterFunction = (value: any, path: string[], expectedType: Function | Function[], converters: Converters) => any;
export declare type TypeConverter = {
    type: Class;
    converter: ConverterFunction;
};
export declare type ValidatorFunction = (value: string, ctx: Context) => Promise<string | undefined>;
export declare type ValidatorStore = {
    [key: string]: ValidatorFunction;
};
export interface BindingDecorator {
    type: "ParameterBinding";
    process: (ctx: Context) => any;
}
export interface RouteDecorator {
    name: "Route";
    method: HttpMethod;
    url?: string;
}
export interface IgnoreDecorator {
    name: "Ignore";
}
export interface RootDecorator {
    name: "Root";
    url: string;
}
export interface MiddlewareDecorator {
    name: "Middleware";
    value: Middleware[];
}
export interface AuthDecorator {
    type: "authorize:public" | "authorize:role";
    value: string[];
}
export interface RouteInfo {
    url: string;
    method: HttpMethod;
    action: MethodReflection;
    controller: ClassReflection;
}
export interface ValidatorDecorator {
    type: "ValidatorDecorator";
    validator: ValidatorFunction | string;
}
export interface Invocation {
    context: Readonly<Context>;
    proceed(): Promise<ActionResult>;
}
export interface Middleware {
    execute(invocation: Readonly<Invocation>): Promise<ActionResult>;
}
export interface Facility {
    setup(app: Readonly<PlumierApplication>): Promise<void>;
}
export interface DependencyResolver {
    resolve(type: (new (...args: any[]) => any)): any;
}
export interface BodyParserOption {
    enableTypes?: string[];
    encode?: string;
    formLimit?: string;
    jsonLimit?: string;
    strict?: boolean;
    detectJSON?: (ctx: Koa.Context) => boolean;
    extendTypes?: {
        json?: string[];
        form?: string[];
        text?: string[];
    };
    onerror?: (err: Error, ctx: Koa.Context) => void;
}
export interface ValidationIssue {
    path: string[];
    messages: string[];
}
export interface FileUploadInfo {
    field: string;
    fileName: string;
    originalName: string;
    mime: string;
    size: number;
    encoding: string;
}
export interface FileParser {
    save(subDirectory?: string): Promise<FileUploadInfo[]>;
}
export interface Configuration {
    mode: "debug" | "production";
    /**
     * Specify controller path (absolute or relative to entry point) or the controller classes array.
     */
    controller: string | Class[] | Class;
    /**
     * Set custom dependency resolver for dependency injection
     */
    dependencyResolver: DependencyResolver;
    /**
     * Define default response status for method type get/post/put/delete, default 200
    ```
    responseStatus: { post: 201, put: 204, delete: 204 }
    ```
    */
    responseStatus?: Partial<{
        [key in HttpMethod]: number;
    }>;
    /**
     * Set custom converters for parameter binding
    ```
    converters: {
        AnimalDto: (value:any, type:Function) => new AnimalDto(value)
    }
    ```
     */
    converters?: TypeConverter[];
    /**
     * Set custom validator
     */
    validator?: (value: any, metadata: ParameterReflection, context: Context, validators?: {
        [key: string]: ValidatorFunction;
    }) => Promise<ValidationIssue[]>;
    /**
     * Multi part form file parser implementation
     */
    fileParser?: (ctx: Context) => FileParser;
    /**
     * Key-value pair to store validator logic
     */
    validators?: ValidatorStore;
}
export interface PlumierConfiguration extends Configuration {
    middleware: Middleware[];
    facilities: Facility[];
}
export interface Application {
    /**
     * Use Koa middleware
    ```
    use(KoaBodyParser())
    ```
     * Use inline Koa middleware
    ```
    use(async (ctx, next) => { })
    ```
     */
    use(middleware: KoaMiddleware): Application;
    /**
     * Use plumier middleware by class instance inherited from Middleware
    ```
    use(new MyMiddleware())
    ```
     * Use plumier middleware by inline object
    ```
    use({ execute: x => x.proceed()})
    use({ execute: async x => {
        return new ActionResult({ json: "body" }, 200)
    })
    ```
     */
    use(middleware: Middleware): Application;
    /**
     * Set facility (advanced configuration)
    ```
    set(new WebApiFacility())
    ```
     */
    set(facility: Facility): Application;
    /**
     * Set part of configuration
    ```
    set({ controllerPath: "./my-controller" })
    ```
     * Can be specified more than one configuration
    ```
    set({ mode: "production", rootPath: __dirname })
    ```
     */
    set(config: Partial<Configuration>): Application;
    /**
     * Initialize Plumier app and return Koa application
    ```
    app.initialize().then(koa => koa.listen(8000))
    ```
     * For testing purposes
    ```
    const koa = await app.initialize()
    supertest(koa.callback())
    ```
     */
    initialize(): Promise<Koa>;
}
export interface PlumierApplication extends Application {
    readonly koa: Koa;
    readonly config: Readonly<PlumierConfiguration>;
}
declare module "koa" {
    interface Context {
        route?: Readonly<RouteInfo>;
        config: Readonly<Configuration>;
        parameters?: any[];
    }
}
export declare namespace MiddlewareUtil {
    function fromKoa(middleware: KoaMiddleware): Middleware;
}
export declare class ActionResult {
    body?: any;
    status?: number | undefined;
    static fromContext(ctx: Context): ActionResult;
    private readonly headers;
    constructor(body?: any, status?: number | undefined);
    setHeader(key: string, value: string): this;
    setStatus(status: number): this;
    execute(ctx: Context): Promise<void>;
}
export declare class HttpStatusError extends Error {
    status: number;
    constructor(status: number, message?: string);
}
export declare class ConversionError extends HttpStatusError {
    issues: ValidationIssue;
    constructor(issues: ValidationIssue);
}
export declare class ValidationError extends HttpStatusError {
    issues: ValidationIssue[];
    constructor(issues: ValidationIssue[]);
}
export declare class DefaultDependencyResolver implements DependencyResolver {
    resolve(type: new (...args: any[]) => any): any;
}
export declare namespace bind {
    /**
     * Bind Koa Context
     *
     *    method(@bind.ctx() ctx:any) {}
     *
     * Use dot separated string to access child property
     *
     *    method(@bind.ctx("state.user") ctx:User) {}
     *    method(@bind.ctx("request.headers.ip") ip:string) {}
     *    method(@bind.ctx("body[0].id") id:string) {}
     *
     * @param part part of context, use dot separator to access child property
     */
    function ctx(part?: string): (target: any, name: string, index: number) => void;
    /**
     * Bind Koa request to parameter
     *
     *    method(@bind.request() req:Request){}
     *
     * If parameter provided, part of request property will be bound
     *
     *    method(@bind.request("method") httpMethod:string){}
     *    method(@bind.request("status") status:number){}
     *
     * @param part part of request ex: body, method, query etc
     */
    function request(part?: RequestPart): (target: any, name: string, index: number) => void;
    /**
     * Bind request body to parameter
     *
     *     method(@bind.body() body:AnimalDto){}
     *
     * If parameter provided, part of body property will be bound
     *
     *     method(@bind.body("name") name:string){}
     *     method(@bind.body("age") age:number){}
     */
    function body(part?: string): (target: any, name: string, index: number) => void;
    /**
     * Bind request header to parameter
     *
     *     method(@bind.header() header:any){}
     *
     * If parameter provided, part of header property will be bound
     *
     *     method(@bind.header("accept") accept:string){}
     *     method(@bind.header("cookie") age:any){}
     */
    function header(key?: HeaderPart): (target: any, name: string, index: number) => void;
    /**
     * Bind request query object to parameter
     *
     *     method(@bind.query() query:any){}
     *
     * If parameter provided, part of query property will be bound
     *
     *     method(@bind.query("id") id:string){}
     *     method(@bind.query("type") type:string){}
     */
    function query(name?: string): (target: any, name: string, index: number) => void;
    /**
     * Bind current login user to parameter
     *
     *     method(@bind.user() user:User){}
     */
    function user(): (target: any, name: string, index: number) => void;
    /**
     * Bind file parser for multi part file upload. This function required `FileUploadFacility`
    ```
    @route.post()
    async method(@bind.file() file:FileParser){
        const info = await file.parse()
    }
    ```
     */
    function file(): (target: any, name: string, index: number) => void;
    /**
     * Bind custom part of Koa context into parameter
     * example:
     *
     *    method(@bind.custom(ctx => ctx.request.body) user:User){}
     * @param process callback function to process the Koa context
     */
    function custom(process: (ctx: Koa.Context) => any): (target: any, name: string, index: number) => void;
}
export declare class RouteDecoratorImpl {
    private decorateRoute;
    /**
     * Mark method as POST method http handler
     ```
     class AnimalController{
        @route.post()
        method(id:number){}
     }
     //result: POST /animal/method?id=<number>
     ```
     * Override method name with absolute url
     ```
     class AnimalController{
        @route.post("/beast/:id")
        method(id:number){}
     }
     //result: POST /beast/:id
     ```
     * Override method name with relative url
     ```
     class AnimalController{
        @route.post("get")
        method(id:number){}
     }
     //result: POST /animal/get?id=<number>
     ```
     * @param url url override
     */
    post(url?: string): (target: any, name: string) => void;
    /**
     * Mark method as GET method http handler
     ```
     class AnimalController{
        @route.get()
        method(id:number){}
     }
     //result: GET /animal/method?id=<number>
     ```
     * Override method name with absolute url
     ```
     class AnimalController{
        @route.get("/beast/:id")
        method(id:number){}
     }
     //result: GET /beast/:id
     ```
     * Override method name with relative url
     ```
     class AnimalController{
        @route.get("get")
        method(id:number){}
     }
     //result: GET /animal/get?id=<number>
     ```
     * @param url url override
     */
    get(url?: string): (target: any, name: string) => void;
    /**
     * Mark method as PUT method http handler
     ```
     class AnimalController{
        @route.put()
        method(id:number){}
     }
     //result: PUT /animal/method?id=<number>
     ```
     * Override method name with absolute url
     ```
     class AnimalController{
        @route.put("/beast/:id")
        method(id:number){}
     }
     //result: PUT /beast/:id
     ```
     * Override method name with relative url
     ```
     class AnimalController{
        @route.put("get")
        method(id:number){}
     }
     //result: PUT /animal/get?id=<number>
     ```
     * @param url url override
     */
    put(url?: string): (target: any, name: string) => void;
    /**
     * Mark method as DELETE method http handler
     ```
     class AnimalController{
        @route.delete()
        method(id:number){}
     }
     //result: DELETE /animal/method?id=<number>
     ```
     * Override method name with absolute url
     ```
     class AnimalController{
        @route.delete("/beast/:id")
        method(id:number){}
     }
     //result: DELETE /beast/:id
     ```
     * Override method name with relative url
     ```
     class AnimalController{
        @route.delete("get")
        method(id:number){}
     }
     //result: DELETE /animal/get?id=<number>
     ```
     * @param url url override
     */
    delete(url?: string): (target: any, name: string) => void;
    /**
     * Override controller name on route generation
     ```
     @route.root("/beast")
     class AnimalController{
        @route.get()
        method(id:number){}
     }
     //result: GET /beast/method?id=<number>
     ```
     * Parameterized root, useful for nested Restful resource
     ```
     @route.root("/beast/:type/bunny")
     class AnimalController{
        @route.get(":id")
        method(type:string, id:number){}
     }
     //result: GET /beast/:type/bunny/:id
     ```
     * @param url url override
     */
    root(url: string): (target: any) => void;
    /**
     * Ignore method from route generation
     ```
     class AnimalController{
        @route.get()
        method(id:number){}
        @route.ignore()
        otherMethod(type:string, id:number){}
     }
     //result: GET /animal/method?id=<number>
     //otherMethod not generated
     ```
     */
    ignore(): (target: any, name: string) => void;
}
export declare const route: RouteDecoratorImpl;
export declare namespace middleware {
    function use(...middleware: (Middleware | KoaMiddleware)[]): (...args: any[]) => void;
}
export declare function domain(): (target: any) => void;
export declare class AuthDecoratorImpl {
    /**
     * Authorize controller/action to public
     */
    public(): (...args: any[]) => void;
    /**
     * Authorize controller/action accessible by sepecific role
     * @param roles List of roles allowed
     */
    role(...roles: string[]): (...args: any[]) => void;
}
export declare const authorize: AuthDecoratorImpl;
export declare const DefaultConfiguration: Configuration;
export declare namespace errorMessage {
    const RouteDoesNotHaveBackingParam = "PLUM1000: Route parameters ({0}) doesn't have appropriate backing parameter";
    const ActionDoesNotHaveTypeInfo = "PLUM1001: Parameter binding skipped because action doesn't have @route decorator";
    const DuplicateRouteFound = "PLUM1003: Duplicate route found in {0}";
    const ControllerPathNotFound = "PLUM1004: Controller file or directory {0} not found";
    const ModelWithoutTypeInformation = "PLUM1005: Parameter binding skipped because  {0} doesn't have @domain() decorator";
    const ArrayWithoutTypeInformation = "PLUM1006: Parameter binding skipped because array field without @array() decorator found in ({0})";
    const ModelNotFound = "PLUM1007: Domain model not found, no class decorated with @domain() on provided classes";
    const ModelPathNotFound = "PLUM1007: Domain model not found, no class decorated with @domain() on path {0}";
    const PublicNotInParameter = "PLUM1008: @authorize.public() can not be applied to parameter";
    const UnableToInstantiateModel = "PLUM2000: Unable to instantiate model {0}. Domain model should be instantiable using default constructor";
    const UnableToConvertValue = "Unable to convert \"{0}\" into {1}";
    const FileSizeExceeded = "File {0} size exceeded the maximum size";
    const NumberOfFilesExceeded = "Number of files exceeded the maximum allowed";
}