@tsed/platform-params 6.88.1 → 6.89.0

package/lib/types/decorators/headerParams.d.ts

@@ -0,0 +1,33 @@
+import { Type } from "@tsed/core";
+import { ParamOptions } from "../domain/ParamOptions";
+/**
+ * HeaderParams return the value from [`request.get()`](http://expressjs.com/en/4x/api.html#req.get) method.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Get('/')
+ *    get(@HeaderParams() body: any) {
+ *       console.log('Entire body', body);
+ *    }
+ *
+ *    @Get('/')
+ *    get(@HeaderParams('x-token') token: string) {
+ *       console.log('token', id);
+ *    }
+ * }
+ * ```
+ *
+ * @param expression The path of the property to get.
+ * @param useType
+ * @decorator
+ * @operation
+ * @input
+ */
+export declare function HeaderParams(expression: string, useType: Type<any>): ParameterDecorator;
+export declare function HeaderParams(expression: string): ParameterDecorator;
+export declare function HeaderParams(useType: Type<any>): ParameterDecorator;
+export declare function HeaderParams(options: Partial<ParamOptions>): ParameterDecorator;
+export declare function HeaderParams(): ParameterDecorator;

package/lib/types/decorators/locals.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Locals return the value from [response.locals](http://expressjs.com/en/4x/api.html#res.locals) object.
+ *
+ * ::: tip
+ * Locals are generally used by express and third-party like templating engine to render a page/template.
+ * See [Templating](http://tsed.io/tutorials/templating.html) section for more details.
+ * :::
+ *
+ * #### Example
+ *
+ * ```typescript
+ *  * @Middleware()
+ * class LocalsMiddleware {
+ *   use(@Locals() locals: any) {
+ *      // set some on locals
+ *      locals.user = "user"
+ *   }
+ * }
+ *
+ * @Controller('/')
+ * @UseBefore(LocalsMiddleware)
+ * class MyCtrl {
+ *    @Get('/')
+ *    @View('home.ejs') // will use locals and returned data to render the page
+ *    get(@Locals('user') user: any) {
+ *       console.log('user', user);
+ *
+ *       return {
+ *         description: 'Hello world'
+ *       }
+ *    }
+ * }
+ * ```
+ *
+ * @param expression The path of the property to get.
+ * @decorator
+ * @operation
+ * @input
+ * @response
+ */
+export declare function Locals(expression: string): ParameterDecorator;
+export declare function Locals(): ParameterDecorator;

package/lib/types/decorators/paramFn.d.ts

@@ -0,0 +1,11 @@
+import { DecoratorParameters } from "@tsed/core";
+import { ParamMetadata } from "../domain/ParamMetadata";
+/**
+ * Get the Param metadata. Use this decorator to compose your own decorator.
+ *
+ * @param fn
+ * @decorator
+ * @operation
+ * @input
+ */
+export declare function ParamFn(fn: (param: ParamMetadata, parameters: DecoratorParameters) => void): ParameterDecorator;

package/lib/types/decorators/pathParams.d.ts

@@ -0,0 +1,68 @@
+import { Type } from "@tsed/core";
+import { ParamOptions } from "../domain/ParamOptions";
+/**
+ * PathParams return the value from [request.params](http://expressjs.com/en/4x/api.html#req.params) object.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Get('/')
+ *    get(@PathParams() params: any) {
+ *       console.log('Entire params', params);
+ *    }
+ *
+ *    @Get('/')
+ *    get(@PathParams('id') id: string) {
+ *       console.log('ID', id);
+ *    }
+ *
+ *    @Get('/')
+ *    get(@PathParams({expression: 'id', useType: () => new MyCustomModel() }) id: string) {
+ *       console.log('ID', id);
+ *    }
+ * }
+ * ```
+ * > For more information on deserialization see [converters](/docs/converters.md) page.
+ *
+ * @param expression The path of the property to get.
+ * @param useType The type of the class that to be used to deserialize the data.
+ * @decorator
+ * @operation
+ * @input
+ */
+export declare function PathParams(expression: string, useType: Type<any>): ParameterDecorator;
+export declare function PathParams(expression: string): ParameterDecorator;
+export declare function PathParams(useType: Type<any>): ParameterDecorator;
+export declare function PathParams(options: Partial<ParamOptions>): ParameterDecorator;
+export declare function PathParams(): ParameterDecorator;
+/**
+ * RawPathParams return the raw value from [request.params](http://expressjs.com/en/4x/api.html#req.params) object.
+ *
+ * Any validation and transformation are performed on the value. Use [pipes](/docs/pipes.html) to validate and/or transform the value.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Get('/')
+ *    get(@RawPathParams() params: string) {
+ *       console.log('Entire params', params);
+ *    }
+ *
+ *    @Get('/')
+ *    get(@RawPathParams('id') id: string) {
+ *       console.log('ID', id);
+ *    }
+ * }
+ * ```
+ * > For more information on deserialization see [converters](/docs/converters.md) page.
+ *
+ * @param expression The path of the property to get.
+ * @decorator
+ * @operation
+ * @input
+ */
+export declare function RawPathParams(expression: string): ParameterDecorator;

package/lib/types/decorators/queryParams.d.ts

@@ -0,0 +1,73 @@
+import { Type } from "@tsed/core";
+import { ParamOptions } from "../domain/ParamOptions";
+/**
+ * QueryParams return the value from [request.query](http://expressjs.com/en/4x/api.html#req.query) object.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Get('/')
+ *    get(@QueryParams() query: any) {
+ *       console.log('Entire query', query);
+ *    }
+ *
+ *    @Get('/')
+ *    get(@QueryParams('id') id: string) {
+ *       console.log('ID', id);
+ *    }
+ *
+ *    @Get('/')
+ *    get(@QueryParams('user') user: User) { // with deserialization
+ *       console.log('user', user);
+ *    }
+ *
+ *    @Get('/')
+ *    get(@QueryParams('users', User) users: User[]) { // with deserialization
+ *       console.log('users', users);
+ *    }
+ * }
+ * ```
+ * > For more information on deserialization see [converters](/docs/converters.md) page.
+ *
+ * @param expression The path of the property to get.
+ * @param useType The type of the class that to be used to deserialize the data.
+ * @decorator
+ * @operation
+ * @input
+ */
+export declare function QueryParams(expression: string, useType: Type<any>): ParameterDecorator;
+export declare function QueryParams(expression: string): ParameterDecorator;
+export declare function QueryParams(useType: Type<any>): ParameterDecorator;
+export declare function QueryParams(options: Partial<ParamOptions>): ParameterDecorator;
+export declare function QueryParams(): ParameterDecorator;
+/**
+ * RawQueryParams return the value from [request.query](http://expressjs.com/en/4x/api.html#req.query) object.
+ *
+ * Any validation and transformation are performed on the value. Use [pipes](/docs/pipes.html) to validate and/or transform the value.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Get('/')
+ *    get(@RawPathParams() params: any) {
+ *       console.log('Entire params', params);
+ *    }
+ *
+ *    @Get('/')
+ *    get(@RawPathParams('id') id: string) {
+ *       console.log('ID', id);
+ *    }
+ * }
+ * ```
+ * > For more information on deserialization see [converters](/docs/converters.md) page.
+ *
+ * @param expression The path of the property to get.
+ * @decorator
+ * @operation
+ * @input
+ */
+export declare function RawQueryParams(expression: string): ParameterDecorator;

package/lib/types/decorators/session.d.ts

@@ -0,0 +1,36 @@
+import { ParamOptions } from "../domain/ParamOptions";
+/**
+ * Session return the value from [request.session](http://expressjs.com/en/4x/api.html#req.session) object.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Post('/')
+ *    create(@Session() session: Express.Session) {
+ *       console.log('Entire session', session);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@Session('id') id: string) {
+ *       console.log('ID', id);
+ *    }
+ *
+ *    @Post('/') // Example to deserialize use from session
+ *    create(@Session({expression: 'user', useConverter: true}) user: User) {
+ *       console.log('user', user);
+ *       console.log('instanceOf user', user instanceof User);
+ *    }
+ * }
+ * ```
+ * > For more information on deserialization see [converters](/docs/converters.md) page.
+ *
+ * @param expression The path of the property to get.
+ * @decorator
+ * @operation
+ * @input
+ */
+export declare function Session(expression: string): ParameterDecorator;
+export declare function Session(options: Partial<ParamOptions>): ParameterDecorator;
+export declare function Session(): ParameterDecorator;

package/lib/types/decorators/useDeserialization.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Use JsonMapper to deserialize the data.
+ *
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export declare function UseDeserialization(options?: any): ParameterDecorator;

package/lib/types/decorators/useParam.d.ts

@@ -0,0 +1,22 @@
+import { ParamOptions } from "../domain/ParamOptions";
+/**
+ * Register a new param. It use the paramType to extract value and give it to the next pipe.
+ *
+ * Given options allow to enable or disable following pipes:
+ *
+ * - useType: Add extra type for the json mapper,
+ * - expression: Get property from the returned value by the previous pipe.
+ * - useValidation: Apply validation from the returned value by the previous pipe.
+ * - useConverter: Apply json mapper from the returned value by the previous pipe.
+ *
+ * @param options
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export declare function UseParam(options: Partial<ParamOptions>): ParameterDecorator;
+/**
+ * @deprecated Since v6
+ */
+export declare function UseParam(paramType: string, options?: Partial<ParamOptions>): ParameterDecorator;

package/lib/types/decorators/useParamExpression.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Get data from a path inside the given object
+ *
+ * @param expression
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export declare function UseParamExpression(expression?: string): ParameterDecorator;

package/lib/types/decorators/useParamType.d.ts

@@ -0,0 +1,10 @@
+import { ParamOptions } from "../domain/ParamOptions";
+/**
+ * Get the object from request (like body, params, query, etc...).
+ *
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export declare function UseParamType(options: ParamOptions): any;

package/lib/types/decorators/usePipe.d.ts

@@ -0,0 +1,13 @@
+import { Type } from "@tsed/core";
+import { PipeMethods } from "../domain/ParamMetadata";
+/**
+ * Register a Pipe to be used with the current decorated param.
+ *
+ * @param token
+ * @param options
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export declare function UsePipe(token: Type<PipeMethods>, options?: any): ParameterDecorator;

package/lib/types/decorators/useType.d.ts

@@ -0,0 +1,13 @@
+import { Type } from "@tsed/core";
+/**
+ * Set the type of the item colllection.
+ *
+ * Prefer @@CollectionOf@@ usage.
+ *
+ * @param type
+ * @decorator
+ * @operation
+ * @input
+ * @alias CollectionOf
+ */
+export declare function UseType(type: any | Type<any>): import("@tsed/schema").CollectionOfChainedDecorators;

package/lib/types/decorators/useValidation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Enable validation on the decoratored parameter.
+ *
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export declare function UseValidation(): ParameterDecorator;

package/lib/types/domain/ParamMetadata.d.ts

@@ -0,0 +1,16 @@
+import { Type } from "@tsed/core";
+import { JsonEntityStoreOptions, JsonParameterStore } from "@tsed/schema";
+import { ParamOptions } from "./ParamOptions";
+export interface PipeMethods<T = any, R = any> {
+    transform(value: T, metadata: ParamMetadata): R;
+}
+export declare type ParamConstructorOptions = JsonEntityStoreOptions & ParamOptions;
+export declare class ParamMetadata extends JsonParameterStore implements ParamConstructorOptions {
+    expression: string;
+    dataPath: string;
+    paramType: string;
+    pipes: Type<PipeMethods>[];
+    constructor(options: ParamConstructorOptions);
+    get key(): string;
+    static get(target: Type<any>, propertyKey: string | symbol, index: number): ParamMetadata;
+}

package/lib/types/domain/ParamOptions.d.ts

@@ -0,0 +1,10 @@
+import { Type } from "@tsed/core";
+export interface ParamOptions<T = any> {
+    dataPath: string;
+    paramType: string;
+    expression?: string;
+    useType?: Type<T>;
+    useConverter?: boolean;
+    useValidation?: boolean;
+    [key: string]: any;
+}

package/lib/types/domain/ParamTypes.d.ts

@@ -0,0 +1,24 @@
+export declare enum ParamTypes {
+    $CTX = "$CTX",
+    BODY = "BODY",
+    PATH = "PATH",
+    QUERY = "QUERY",
+    HEADER = "HEADER",
+    RAW_BODY = "RAW_BODY",
+    COOKIES = "COOKIES",
+    LOCALS = "LOCALS",
+    SESSION = "SESSION",
+    FILES = "FILES",
+    NEXT_FN = "NEXT_FN",
+    ERR = "ERR",
+    REQUEST = "REQUEST",
+    PLATFORM_REQUEST = "PLATFORM_REQUEST",
+    NODE_REQUEST = "NODE_REQUEST",
+    RESPONSE = "RESPONSE",
+    PLATFORM_RESPONSE = "PLATFORM_RESPONSE",
+    NODE_RESPONSE = "NODE_RESPONSE",
+    RESPONSE_DATA = "RESPONSE_DATA",
+    ENDPOINT_INFO = "ENDPOINT_INFO",
+    RES = "RES",
+    REQ = "REQ"
+}

package/lib/types/errors/ParamValidationError.d.ts

@@ -0,0 +1,8 @@
+import { BadRequest } from "@tsed/exceptions";
+import { ParamMetadata } from "../domain/ParamMetadata";
+export declare class ParamValidationError extends BadRequest {
+    name: string;
+    dataPath: string;
+    requestType: string;
+    static from(metadata: ParamMetadata, origin?: any): any;
+}

package/lib/types/errors/RequiredValidationError.d.ts

@@ -0,0 +1,6 @@
+import { ParamMetadata } from "../domain/ParamMetadata";
+import { ValidationError } from "./ValidationError";
+export declare class RequiredValidationError extends ValidationError {
+    name: string;
+    static from(metadata: ParamMetadata): RequiredValidationError;
+}

package/lib/types/errors/ValidationError.d.ts

@@ -0,0 +1,6 @@
+import { BadRequest } from "@tsed/exceptions";
+export declare class ValidationError extends BadRequest {
+    name: string;
+    errors: any[];
+    constructor(message: string, errors?: any[]);
+}

package/lib/types/index.d.ts

@@ -0,0 +1,28 @@
+export * from "./utils/mapParamsOptions";
+export * from "./domain/ParamMetadata";
+export * from "./domain/ParamOptions";
+export * from "./domain/ParamTypes";
+export * from "./pipes/ParseExpressionPipe";
+export * from "./pipes/DeserializerPipe";
+export * from "./pipes/ValidationPipe";
+export * from "./builder/PlatformParams";
+export * from "./errors/RequiredValidationError";
+export * from "./errors/ValidationError";
+export * from "./errors/ParamValidationError";
+export * from "./decorators/context";
+export * from "./decorators/bodyParams";
+export * from "./decorators/usePipe";
+export * from "./decorators/useParam";
+export * from "./decorators/useParamType";
+export * from "./decorators/useType";
+export * from "./decorators/useValidation";
+export * from "./decorators/useDeserialization";
+export * from "./decorators/useParamExpression";
+export * from "./decorators/useParamType";
+export * from "./decorators/headerParams";
+export * from "./decorators/cookies";
+export * from "./decorators/locals";
+export * from "./decorators/pathParams";
+export * from "./decorators/queryParams";
+export * from "./decorators/session";
+export * from "./decorators/paramFn";

package/lib/types/pipes/DeserializerPipe.d.ts

@@ -0,0 +1,5 @@
+import { ParamMetadata, PipeMethods } from "../domain/ParamMetadata";
+export declare class DeserializerPipe implements PipeMethods {
+    private settings;
+    transform(value: any, param: ParamMetadata): any;
+}

package/lib/types/pipes/ParseExpressionPipe.d.ts

@@ -0,0 +1,5 @@
+import { PipeMethods, ParamMetadata } from "../domain/ParamMetadata";
+import type { ArgScope } from "../builder/PlatformParams";
+export declare class ParseExpressionPipe implements PipeMethods {
+    transform(scope: ArgScope, param: ParamMetadata): any;
+}

package/lib/types/pipes/ValidationPipe.d.ts

@@ -0,0 +1,10 @@
+import { InjectorService } from "@tsed/di";
+import { PipeMethods, ParamMetadata } from "../domain/ParamMetadata";
+export declare class ValidationPipe implements PipeMethods {
+    private validator;
+    constructor(injector: InjectorService);
+    coerceTypes(value: any, metadata: ParamMetadata): any;
+    skip(value: any, metadata: ParamMetadata): boolean;
+    transform(value: any, metadata: ParamMetadata): Promise<any>;
+    protected checkIsRequired(value: any, metadata: ParamMetadata): boolean;
+}

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

@@ -0,0 +1,5 @@
+import { ParamOptions } from "../domain/ParamOptions";
+/**
+ * @ignore
+ */
+export declare function mapParamsOptions(args: any[]): Partial<ParamOptions<any>>;

package/package.json

@@ -1,34 +1,38 @@
 {
   "name": "@tsed/platform-params",
-  "version": "6.88.1",
+  "version": "6.89.0",
   "description": "Params module for Ts.ED Framework",
   "private": false,
   "source": "./src/index.ts",
-  "main": "./lib/index.js",
-  "typings": "./lib/index.d.ts",
+  "main": "./lib/cjs/index.js",
+  "typings": "./lib/types/index.d.ts",
   "exports": {
-    "require": "./lib/index.js",
-    "default": "./lib/index.modern.js"
+    "types": "./lib/types/index.d.ts",
+    "import": "./lib/esm/index.js",
+    "require": "./lib/cjs/index.js",
+    "default": "./lib/esm/index.js"
   },
   "scripts": {
-    "build": "microbundle --target node --no-compress --format modern,cjs --tsconfig ./tsconfig.compile.json"
+    "build": "yarn run build:esm && yarn run build:cjs",
+    "build:cjs": "tsc --build tsconfig.compile.json",
+    "build:esm": "tsc --build tsconfig.compile.esm.json"
   },
   "dependencies": {
     "tslib": "2.2.0"
   },
   "devDependencies": {
-    "@tsed/core": "6.88.1",
-    "@tsed/di": "6.88.1",
-    "@tsed/exceptions": "6.88.1",
-    "@tsed/json-mapper": "6.88.1",
-    "@tsed/schema": "6.88.1"
+    "@tsed/core": "6.89.0",
+    "@tsed/di": "6.89.0",
+    "@tsed/exceptions": "6.89.0",
+    "@tsed/json-mapper": "6.89.0",
+    "@tsed/schema": "6.89.0"
   },
   "peerDependencies": {
-    "@tsed/core": "^6.88.1",
-    "@tsed/di": "^6.88.1",
-    "@tsed/exceptions": "^6.88.1",
-    "@tsed/json-mapper": "^6.88.1",
-    "@tsed/schema": "^6.88.1"
+    "@tsed/core": "^6.89.0",
+    "@tsed/di": "^6.89.0",
+    "@tsed/exceptions": "^6.89.0",
+    "@tsed/json-mapper": "^6.89.0",
+    "@tsed/schema": "^6.89.0"
   },
   "repository": "https://github.com/tsedio/tsed",
   "bugs": {

package/tsconfig.compile.esm.json

@@ -0,0 +1,23 @@
+{
+  "extends": "./tsconfig.compile.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "module": "ES2020",
+    "rootDir": "src",
+    "outDir": "./lib/esm",
+    "declaration": true,
+    "declarationDir": "./lib/types"
+  },
+  "exclude": [
+    "node_modules",
+    "test",
+    "lib",
+    "benchmark",
+    "coverage",
+    "spec",
+    "**/*.benchmark.ts",
+    "**/*.spec.ts",
+    "keys",
+    "jest.config.js"
+  ]
+}