@tsed/common 6.87.2 → 6.90.0

package/lib/types/services/Platform.d.ts

@@ -0,0 +1,37 @@
+import { InjectorService, TokenProvider } from "@tsed/di";
+import { PlatformRouteDetails } from "../domain";
+import { Route, RouteController } from "../interfaces/Route";
+import { PlatformApplication } from "./PlatformApplication";
+/**
+ * `Platform` is used to provide all routes collected by annotation `@Controller`.
+ *
+ * @platform
+ */
+export declare class Platform {
+    readonly injector: InjectorService;
+    readonly platformApplication: PlatformApplication;
+    private _routes;
+    private _controllers;
+    constructor(injector: InjectorService, platformApplication: PlatformApplication);
+    get app(): PlatformApplication<TsED.Application, TsED.Router>;
+    get routes(): PlatformRouteDetails[];
+    addRoutes(routes: Route[]): void;
+    addRoute(basePath: string, token: TokenProvider): this | undefined;
+    /**
+     * Get all routes built by TsExpressDecorators and mounted on Express application.
+     * @returns {PlatformRouteDetails[]}
+     */
+    getRoutes(): PlatformRouteDetails[];
+    getMountedControllers(): RouteController[];
+    protected $onInit(): void;
+    /**
+     * Create routers from the collected controllers.
+     * @private
+     */
+    private createRouters;
+    /**
+     * Create controllers from DI
+     * @private
+     */
+    private buildControllers;
+}

package/lib/types/services/PlatformApplication.d.ts

@@ -0,0 +1,21 @@
+import { PlatformHandler } from "./PlatformHandler";
+import { PlatformRouter } from "./PlatformRouter";
+declare global {
+    namespace TsED {
+        interface Application {
+        }
+    }
+}
+/**
+ * `PlatformApplication` is used to provide all routes collected by annotation `@Controller`.
+ *
+ * @platform
+ */
+export declare class PlatformApplication<App = TsED.Application, Router = TsED.Router> extends PlatformRouter<Router> {
+    raw: App;
+    rawApp: App;
+    rawRouter: Router;
+    constructor(platformHandler: PlatformHandler);
+    protected static createRawApp(): any;
+    getApp(): App;
+}

package/lib/types/services/PlatformHandler.d.ts

@@ -0,0 +1,80 @@
+import { InjectorService, Provider } from "@tsed/di";
+import { ArgScope, HandlerWithScope, PlatformParams } from "@tsed/platform-params";
+import { PlatformResponseFilter } from "@tsed/platform-response-filter";
+import { EndpointMetadata } from "../domain/EndpointMetadata";
+import { HandlerMetadata } from "../domain/HandlerMetadata";
+import { PlatformContext } from "../domain/PlatformContext";
+import { PlatformRouteWithoutHandlers } from "../interfaces/PlatformRouteOptions";
+export interface OnRequestOptions {
+    $ctx: PlatformContext;
+    metadata: HandlerMetadata;
+    handler: HandlerWithScope;
+    next?: any;
+    err?: any;
+    [key: string]: any;
+}
+/**
+ * Platform Handler abstraction layer. Wrap original class method to a pure platform handler (Express, Koa, etc...).
+ * @platform
+ */
+export declare class PlatformHandler {
+    protected injector: InjectorService;
+    protected params: PlatformParams;
+    protected responseFilter: PlatformResponseFilter;
+    constructor(injector: InjectorService, params: PlatformParams);
+    /**
+     * Create a native middleware based on the given metadata and return an instance of AnyToPromiseWithCtx
+     * @param input
+     * @param options
+     */
+    createHandler(input: EndpointMetadata | HandlerMetadata | any, options?: PlatformRouteWithoutHandlers): any;
+    /**
+     * Create injectable handler from the given provider
+     * @param provider
+     * @param propertyKey
+     */
+    createCustomHandler(provider: Provider, propertyKey: string): ($ctx: PlatformContext, next?: any) => Promise<any>;
+    /**
+     * Send the response to the consumer.
+     * @param data
+     * @param ctx
+     * @protected
+     */
+    flush(data: any, ctx: PlatformContext): Promise<void>;
+    compileHandler(metadata: HandlerMetadata): (scope: Record<string, any>) => Promise<any>;
+    protected onCtxRequest(requestOptions: OnRequestOptions): Promise<any>;
+    /**
+     * Call handler when a request his handle
+     * @param requestOptions
+     */
+    protected onRequest(requestOptions: OnRequestOptions): Promise<any>;
+    protected onError(er: Error, requestOptions: OnRequestOptions): Promise<any>;
+    /**
+     * Manage success scenario
+     * @param data
+     * @param requestOptions
+     * @protected
+     */
+    protected onSuccess(data: any, requestOptions: OnRequestOptions): Promise<any>;
+    /**
+     * Call the returned middleware by the handler.
+     * @param middleware
+     * @param ctx
+     * @param next
+     * @protected
+     */
+    protected callReturnedMiddleware(middleware: any, ctx: PlatformContext, next: any): any;
+    /**
+     * create Raw handler
+     * @param metadata
+     */
+    protected createRawHandler(metadata: HandlerMetadata): any;
+    /**
+     * Set response headers
+     * @param ctx
+     * @protected
+     */
+    protected setHeaders(ctx: PlatformContext): void;
+    protected next(requestOptions: OnRequestOptions): any;
+    protected getDefaultArgs(metadata: HandlerMetadata): (scope: ArgScope<PlatformContext>) => Promise<any[]>;
+}

package/lib/types/services/PlatformMiddlewaresChain.d.ts

@@ -0,0 +1,6 @@
+import { JsonOperationRoute } from "@tsed/schema";
+import { ControllerProvider } from "../domain/ControllerProvider";
+import { EndpointMetadata } from "../domain/EndpointMetadata";
+export declare class PlatformMiddlewaresChain {
+    get(provider: ControllerProvider, operationRoute: JsonOperationRoute<EndpointMetadata>): any[];
+}

package/lib/types/services/PlatformRequest.d.ts

@@ -0,0 +1,112 @@
+/// <reference types="node" />
+import { IncomingHttpHeaders, IncomingMessage } from "http";
+import type { PlatformContext } from "../domain/PlatformContext";
+import { IncomingEvent } from "../interfaces/IncomingEvent";
+import type { PlatformResponse } from "./PlatformResponse";
+declare global {
+    namespace TsED {
+        interface Request {
+            id: string;
+            $ctx: PlatformContext;
+        }
+    }
+}
+/**
+ * Platform Request abstraction layer.
+ * @platform
+ */
+export declare class PlatformRequest<T extends {
+    [key: string]: any;
+} = any> {
+    protected $ctx: PlatformContext;
+    raw: T;
+    /**
+     * The current @@PlatformResponse@@.
+     */
+    response: PlatformResponse;
+    constructor({ request }: IncomingEvent, $ctx: PlatformContext);
+    get secure(): boolean;
+    get host(): string;
+    get protocol(): string;
+    /**
+     * Get the url of the request.
+     *
+     * Is equivalent of `express.response.originalUrl || express.response.url`.
+     */
+    get url(): string;
+    get headers(): IncomingHttpHeaders;
+    get method(): string;
+    /**
+     * Contains key-value pairs of data submitted in the request body. By default, it is `undefined`, and is populated when you use
+     * `body-parsing` middleware such as `express.json()` or `express.urlencoded()`.
+     */
+    get body(): any;
+    get rawBody(): any;
+    /**
+     * When using `cookie-parser` middleware, this property is an object that contains cookies sent by the request.
+     * If the request contains no cookies, it defaults to `{}`.
+     */
+    get cookies(): {
+        [key: string]: any;
+    };
+    /**
+     * This property is an object containing properties mapped to the named route `parameters`.
+     * For example, if you have the route `/user/:name`, then the `name` property is available as `req.params.name`.
+     * This object defaults to `{}`.
+     */
+    get params(): {
+        [key: string]: any;
+    };
+    /**
+     * This property is an object containing a property for each query string parameter in the route.
+     * When query parser is set to disabled, it is an empty object `{}`, otherwise it is the result of the configured query parser.
+     */
+    get query(): {
+        [key: string]: any;
+    };
+    /**
+     * This property is an object containing a property for each session attributes set by any code.
+     * It require to install a middleware like express-session to work.
+     */
+    get session(): {
+        [key: string]: any;
+    };
+    get files(): any;
+    /**
+     * Return the original request framework instance
+     */
+    get request(): T;
+    /**
+     * Return the original request node.js instance
+     */
+    get req(): IncomingMessage;
+    /**
+     * Returns the HTTP request header specified by field. The match is case-insensitive.
+     *
+     * ```typescript
+     * request.get('Content-Type') // => "text/plain"
+     * ```
+     *
+     * @param name
+     */
+    get(name: string): any;
+    /**
+     * Checks if the specified content types are acceptable, based on the request’s Accept HTTP header field. The method returns the best match, or if none of the specified content types is acceptable, returns false (in which case, the application should respond with 406 "Not Acceptable").
+     *
+     * The type value may be a single MIME type string (such as “application/json”), an extension name such as “json”, a comma-delimited list, or an array. For a list or array, the method returns the best match (if any).
+     *
+     * @param mime
+     */
+    accepts(mime: string): string | false;
+    accepts(mime: string[]): string[] | false;
+    isAborted(): any;
+    destroy(): void;
+    /**
+     * Return the Framework response object (express, koa, etc...)
+     */
+    getRequest<Req = T>(): Req;
+    /**
+     * Return the Node.js response object
+     */
+    getReq(): IncomingMessage;
+}

package/lib/types/services/PlatformResponse.d.ts

@@ -0,0 +1,161 @@
+/// <reference types="node" />
+import { ServerResponse } from "http";
+import { IncomingEvent } from "../interfaces/IncomingEvent";
+import type { PlatformRequest } from "./PlatformRequest";
+import type { PlatformContext } from "../domain/PlatformContext";
+declare global {
+    namespace TsED {
+        interface Response {
+        }
+    }
+}
+export declare type HeaderValue = Array<boolean | number | string> | boolean | number | string;
+/**
+ * Platform Response abstraction layer.
+ * @platform
+ */
+export declare class PlatformResponse<T extends Record<string, any> = any> {
+    protected $ctx: PlatformContext;
+    /**
+     * The current @@PlatformRequest@@.
+     */
+    request: PlatformRequest;
+    data: any;
+    raw: T;
+    constructor({ response }: IncomingEvent, $ctx: PlatformContext);
+    /**
+     * Get the current statusCode
+     */
+    get statusCode(): any;
+    /**
+     * An object that contains response local variables scoped to the request, and therefore available only to the view(s) rendered during that request / response cycle (if any). Otherwise, this property is identical to app.locals.
+     *
+     * This property is useful for exposing request-level information such as the request path name, authenticated user, user settings, and so on.
+     */
+    get locals(): any;
+    /**
+     * Return the original response framework instance
+     */
+    get response(): T;
+    /**
+     * Return the original response node.js instance
+     */
+    get res(): ServerResponse;
+    static onFinished(res: any, cb: Function): void;
+    /**
+     * Returns the HTTP response header specified by field. The match is case-insensitive.
+     *
+     * ```typescript
+     * response.get('Content-Type') // => "text/plain"
+     * ```
+     *
+     * @param name
+     */
+    get(name: string): any;
+    getHeaders(): Record<string, HeaderValue>;
+    /**
+     * Return the Framework response object (express, koa, etc...)
+     */
+    getResponse<Res = T>(): Res;
+    /**
+     * Return the Node.js response object
+     */
+    getRes(): ServerResponse;
+    hasStatus(): boolean;
+    /**
+     * Sets the HTTP status for the response.
+     *
+     * @param status
+     */
+    status(status: number): this;
+    /**
+     * Set header `field` to `val`, or pass
+     * an object of header fields.
+     *
+     * Examples:
+     * ```typescript
+     * response.setHeaders({ Accept: 'text/plain', 'X-API-Key': 'tobi' });
+     * ```
+     *
+     * Aliased as `res.header()`.
+     */
+    setHeaders(headers: Record<string, HeaderValue>): this;
+    setHeader(key: string, item: any): this;
+    /**
+     * Set `Content-Type` response header with `type` through `mime.lookup()`
+     * when it does not contain "/", or set the Content-Type to `type` otherwise.
+     *
+     * Examples:
+     *
+     *     res.type('.html');
+     *     res.type('html');
+     *     res.type('json');
+     *     res.type('application/json');
+     *     res.type('png');
+     */
+    contentType(contentType: string): this;
+    contentLength(length: number): this;
+    getContentLength(): number | undefined;
+    getContentType(): any;
+    /**
+     * Sets the HTTP response Content-Disposition header field to “attachment”.
+     * If a filename is given, then it sets the Content-Type based on the extension name via res.type(), and sets the Content-Disposition “filename=” parameter.
+     *
+     * ```typescript
+     * res.attachment()
+     * // Content-Disposition: attachment
+     *
+     * res.attachment('path/to/logo.png')
+     * // Content-Disposition: attachment; filename="logo.png"
+     * // Content-Type: image/png
+     * ```
+     *
+     * @param filename
+     */
+    attachment(filename: string): this;
+    /**
+     * Redirects to the URL derived from the specified path, with specified status, a positive integer that corresponds to an [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
+     * If not specified, status defaults to `302 Found`.
+     *
+     * @param status
+     * @param url
+     */
+    redirect(status: number, url: string): this;
+    /**
+     * Sets the response Location HTTP header to the specified path parameter.
+     *
+     * @param location
+     */
+    location(location: string): this;
+    /**
+     * Stream the given data.
+     *
+     * @param data
+     */
+    stream(data: ReadableStream | any): this;
+    /**
+     * Renders a view and sends the rendered HTML string to the client.
+     *
+     * @param path
+     * @param options
+     */
+    render(path: string, options?: any): Promise<any>;
+    /**
+     * Send any data to your consumer.
+     *
+     * This method accept a ReadableStream, a plain object, boolean, string, number, null and undefined data.
+     * It choose the better way to send the data.
+     *
+     * @param data
+     */
+    body(data: any): this;
+    getBody(): any;
+    /**
+     * Add a listener to handler the end of the request/response.
+     * @param cb
+     */
+    onEnd(cb: Function): this;
+    isDone(): boolean;
+    destroy(): void;
+    isHeadersSent(): boolean;
+}

package/lib/types/services/PlatformRouter.d.ts

@@ -0,0 +1,48 @@
+import { InjectorService, PathType } from "@tsed/di";
+import { PlatformMulter, PlatformMulterSettings, PlatformStaticsOptions } from "../config";
+import { PlatformRouteOptions, PlatformRouteWithoutHandlers } from "../interfaces";
+import { PlatformHandler } from "./PlatformHandler";
+/**
+ * @ignore
+ */
+export declare const PLATFORM_ROUTER_OPTIONS: unique symbol;
+declare global {
+    namespace TsED {
+        interface Router {
+        }
+    }
+}
+/**
+ * Platform Router abstraction layer.
+ * @platform
+ */
+export declare class PlatformRouter<Router = TsED.Router> {
+    protected platformHandler: PlatformHandler;
+    rawRouter: Router;
+    raw: any;
+    isBuilt: boolean;
+    injector: InjectorService;
+    constructor(platformHandler: PlatformHandler);
+    /**
+     * Create a new instance of PlatformRouter
+     * @param injector
+     * @param routerOptions
+     */
+    static create(injector: InjectorService, routerOptions?: any): PlatformRouter<TsED.Router>;
+    protected static createRawRouter(): any;
+    callback(): any;
+    getRouter(): Router;
+    use(...handlers: any[]): this;
+    addRoute(options: Partial<PlatformRouteOptions>): this;
+    all(path: PathType, ...handlers: any[]): this;
+    get(path: PathType, ...handlers: any[]): this;
+    post(path: PathType, ...handlers: any[]): this;
+    put(path: PathType, ...handlers: any[]): this;
+    delete(path: PathType, ...handlers: any[]): this;
+    patch(path: PathType, ...handlers: any[]): this;
+    head(path: PathType, ...handlers: any[]): this;
+    options(path: PathType, ...handlers: any[]): this;
+    statics(path: string, options: PlatformStaticsOptions): this;
+    multer(options: PlatformMulterSettings): PlatformMulter;
+    protected mapHandlers(handlers: any[], options?: PlatformRouteWithoutHandlers): any[];
+}

package/lib/types/services/PlatformTest.d.ts

@@ -0,0 +1,58 @@
+import { DITest, InjectorService } from "@tsed/di";
+import { PlatformContext, PlatformContextOptions } from "../domain/PlatformContext";
+import { PlatformAdapter, PlatformBuilderSettings } from "../interfaces/PlatformAdapter";
+import { Type } from "@tsed/core";
+/**
+ * @platform
+ */
+export declare class PlatformTest extends DITest {
+    static adapter: Type<PlatformAdapter>;
+    static create(settings?: Partial<TsED.Configuration>): Promise<void>;
+    /**
+     * Create a new injector with the right default services
+     */
+    static createInjector(settings?: any): InjectorService;
+    /**
+     * Load the server silently without listening port and configure it on test profile.
+     * @decorator
+     * @param mod
+     * @param listen
+     * @param settings
+     * @returns {Promise<void>}
+     */
+    static bootstrap(mod: any, { listen, ...settings }?: Partial<PlatformBuilderSettings & {
+        listen: boolean;
+    }>): () => Promise<void>;
+    /**
+     * It injects services into the test function where you can alter, spy on, and manipulate them.
+     *
+     * The inject function has two parameters
+     *
+     * * an array of Service dependency injection tokens,
+     * * a test function whose parameters correspond exactly to each item in the injection token array.
+     *
+     * @param targets
+     * @param func
+     */
+    static inject<T>(targets: any[], func: (...args: any[]) => Promise<T> | T): () => Promise<T>;
+    /**
+     * Return the raw application (express or koa).
+     * Use this callback with SuperTest.
+     *
+     * ```typescript
+     * let request: SuperTest.SuperTest<SuperTest.Test>;
+     * beforeEach(PlatformTest.bootstrap(Server, {
+     *   mount: {
+     *     "/rest": [ProductsController]
+     *   }
+     * }));
+     * beforeEach(() => {
+     *   request = SuperTest(PlatformTest.callback());
+     * });
+     * ```
+     */
+    static callback(): any;
+    static createRequest(options?: any): any;
+    static createResponse(options?: any): any;
+    static createRequestContext(options?: Partial<PlatformContextOptions & any>): PlatformContext;
+}

package/lib/types/services/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./Platform";
+export * from "./PlatformApplication";
+export * from "./PlatformHandler";
+export * from "./PlatformRequest";
+export * from "./PlatformResponse";
+export * from "./PlatformRouter";
+export * from "./PlatformTest";
+export * from "./PlatformMiddlewaresChain";

package/lib/types/utils/createContext.d.ts

@@ -0,0 +1,9 @@
+import { InjectorService } from "@tsed/di";
+import { PlatformContext } from "../domain/PlatformContext";
+import { IncomingEvent } from "../interfaces/IncomingEvent";
+/**
+ * Create the TsED context to wrap request, response, injector, etc...
+ * @param injector
+ * @ignore
+ */
+export declare function createContext(injector: InjectorService): (event: IncomingEvent) => Promise<PlatformContext>;

package/lib/types/utils/createHandlerMetadata.d.ts

@@ -0,0 +1,8 @@
+import { InjectorService } from "@tsed/di";
+import { EndpointMetadata } from "../domain/EndpointMetadata";
+import { HandlerMetadata } from "../domain/HandlerMetadata";
+import { PlatformRouteWithoutHandlers } from "../interfaces/PlatformRouteOptions";
+/**
+ * @ignore
+ */
+export declare function createHandlerMetadata(injector: InjectorService, obj: any | EndpointMetadata, routeOptions?: PlatformRouteWithoutHandlers): HandlerMetadata;

package/lib/types/utils/createHttpServer.d.ts

@@ -0,0 +1,3 @@
+import { InjectorService } from "@tsed/di";
+export declare function createHttpServer(injector: InjectorService): void;
+export declare function listenHttpServer(injector: InjectorService): Promise<void>;

package/lib/types/utils/createHttpsServer.d.ts

@@ -0,0 +1,3 @@
+import { InjectorService } from "@tsed/di";
+export declare function createHttpsServer(injector: InjectorService): void;
+export declare function listenHttpsServer(injector: InjectorService): Promise<void>;

package/lib/types/utils/createInjector.d.ts

@@ -0,0 +1,7 @@
+import { InjectorService, IProvider } from "@tsed/di";
+interface CreateInjectorOptions {
+    providers?: IProvider[];
+    settings?: Partial<TsED.Configuration>;
+}
+export declare function createInjector({ providers, settings }: CreateInjectorOptions): InjectorService;
+export {};

package/lib/types/utils/getConfiguration.d.ts

@@ -0,0 +1,2 @@
+import { Type } from "@tsed/core";
+export declare function getConfiguration(configuration?: any, module?: Type<any> | null): any;

package/lib/types/utils/getStaticsOptions.d.ts

@@ -0,0 +1,5 @@
+import { PlatformStaticsOptions, PlatformStaticsSettings } from "../config/interfaces/PlatformStaticsSettings";
+export declare function getStaticsOptions(statics?: PlatformStaticsSettings): {
+    path: string;
+    options: PlatformStaticsOptions;
+}[];

package/lib/types/utils/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./createInjector";
+export * from "./createHttpServer";
+export * from "./createHttpsServer";
+export * from "./loadInjector";
+export * from "./printRoutes";
+export * from "./listenServer";
+export * from "./createContext";
+export * from "./useCtxHandler";

package/lib/types/utils/listenServer.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+import Http from "http";
+import Https from "https";
+export declare function listenServer(http: Http.Server | Https.Server, settings: {
+    address: string | number;
+    port: number;
+}): Promise<{
+    address: string;
+    port: number;
+}>;

package/lib/types/utils/loadInjector.d.ts

@@ -0,0 +1,6 @@
+import { Container, InjectorService, LocalsContainer } from "@tsed/di";
+/**
+ * @ignore
+ * @deprecated User injector.load(container, module) instead
+ */
+export declare function loadInjector(injector: InjectorService, container?: Container): Promise<LocalsContainer<any>>;

package/lib/types/utils/mapReturnedResponse.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @ignore
+ */
+export declare function mapReturnedResponse({ use, collection, ...options }: any): any;

package/lib/types/utils/printRoutes.d.ts

@@ -0,0 +1,2 @@
+import { PlatformRouteDetails } from "../domain/PlatformRouteDetails";
+export declare function printRoutes(routes: PlatformRouteDetails[]): string;

package/lib/types/utils/setResponseHeaders.d.ts

@@ -0,0 +1,5 @@
+import { PlatformContext } from "../domain/PlatformContext";
+/**
+ * @ignore
+ */
+export declare function setResponseHeaders(ctx: PlatformContext): void;

package/lib/types/utils/useCtxHandler.d.ts

@@ -0,0 +1,13 @@
+import { PlatformContext } from "../domain/PlatformContext";
+import { HandlerType } from "../interfaces/HandlerType";
+export declare type PlatformCtxHandler = ($ctx: PlatformContext) => any | Promise<any>;
+/**
+ * Create Ts.ED context handler
+ * @param fn
+ * @ignore
+ */
+export declare function useCtxHandler(fn: PlatformCtxHandler & {
+    type?: HandlerType;
+}): PlatformCtxHandler & {
+    type?: HandlerType | undefined;
+};