@tsed/platform-params 8.0.1 → 8.0.3

package/src/decorators/queryParams.ts

@@ -0,0 +1,102 @@
+import {Type} from "@tsed/core";
+
+import {ParamOptions} from "../domain/ParamOptions.js";
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {mapParamsOptions} from "../utils/mapParamsOptions.js";
+import {UseParam} from "./useParam.js";
+
+/**
+ * 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/json-mapper.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 function QueryParams(expression: string, useType: Type<any>): ParameterDecorator;
+export function QueryParams(expression: string): ParameterDecorator;
+export function QueryParams(useType: Type<any>): ParameterDecorator;
+export function QueryParams(options: Partial<ParamOptions>): ParameterDecorator;
+export function QueryParams(): ParameterDecorator;
+export function QueryParams(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = true, useValidation = true} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.QUERY,
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}
+
+/**
+ * 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/json-mapper.md) page.
+ *
+ * @param expression The path of the property to get.
+ * @decorator
+ * @operation
+ * @input
+ */
+export function RawQueryParams(expression: string): ParameterDecorator;
+export function RawQueryParams(options: Partial<ParamOptions>): ParameterDecorator;
+export function RawQueryParams(): ParameterDecorator;
+export function RawQueryParams(...args: any[]) {
+  const {expression, useType, useMapper = false, useValidation = false} = mapParamsOptions(args);
+
+  return QueryParams({
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}

package/src/decorators/session.spec.ts

@@ -0,0 +1,47 @@
+import {JsonParameterStore} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {Session} from "./session.js";
+
+describe("@Session", () => {
+  it("should declare a session params", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@Session() body: any) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual(undefined);
+    expect(param.paramType).toEqual(ParamTypes.SESSION);
+    expect(param.type).toEqual(Object);
+    expect(param.pipes).toHaveLength(0);
+  });
+  it("should declare a session params with options", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@Session({expression: "expression", useType: Test}) body: Test) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.SESSION);
+    expect(param.type).toEqual(Test);
+    expect(param.pipes).toHaveLength(0);
+  });
+
+  it("should declare a session params with options (validation + mapping)", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@Session({expression: "expression", useType: Test, useValidation: true, useMapper: true}) body: Test) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.SESSION);
+    expect(param.type).toEqual(Test);
+    expect(param.pipes).toHaveLength(2);
+  });
+});

package/src/decorators/session.ts

@@ -0,0 +1,51 @@
+import {ParamOptions} from "../domain/ParamOptions.js";
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {mapParamsOptions} from "../utils/mapParamsOptions.js";
+import {UseParam} from "./useParam.js";
+
+/**
+ * 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', useMapper: true}) user: User) {
+ *       console.log('user', user);
+ *       console.log('instanceOf user', user instanceof User);
+ *    }
+ * }
+ * ```
+ * > For more information on deserialization see [converters](/docs/json-mapper.md) page.
+ *
+ * @param expression The path of the property to get.
+ * @decorator
+ * @operation
+ * @input
+ */
+export function Session(expression: string): ParameterDecorator;
+export function Session(options: Partial<ParamOptions>): ParameterDecorator;
+export function Session(): ParameterDecorator;
+export function Session(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = false, useValidation = false} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.SESSION,
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}

package/src/decorators/useDeserialization.ts

@@ -0,0 +1,14 @@
+import {DeserializerPipe} from "../pipes/DeserializerPipe.js";
+import {UsePipe} from "./usePipe.js";
+
+/**
+ * Use JsonMapper to deserialize the data.
+ *
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export function UseDeserialization(options: any = {}) {
+  return UsePipe(DeserializerPipe, options);
+}

package/src/decorators/useParam.spec.ts

@@ -0,0 +1,82 @@
+import {Description, Example, Get, getSpec, JsonParameterStore, Property, Required, SpecTypes, Title} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {QueryParams} from "./queryParams.js";
+import {UseParam} from "./useParam.js";
+
+export class MyModel {
+  @Title("iD")
+  @Description("Description of calendar model id")
+  @Example("Description example")
+  @Property()
+  public id: string;
+
+  @Property()
+  @Required()
+  public name: string;
+}
+
+describe("@UseParam", () => {
+  describe("when use a param", () => {
+    it("should create useParam", () => {
+      class Test {}
+
+      class Ctrl {
+        test(
+          @UseParam({
+            expression: "expression",
+            useMapper: true,
+            useValidation: true,
+            paramType: ParamTypes.BODY,
+            useType: Test
+          })
+          body: Test
+        ) {}
+      }
+
+      const param = JsonParameterStore.get(Ctrl, "test", 0);
+      expect(param.expression).toEqual("expression");
+      expect(param.paramType).toEqual(ParamTypes.BODY);
+      expect(param.type).toEqual(Test);
+    });
+  });
+  describe("when is a Query param with boolean", () => {
+    it("should return the right spec", () => {
+      class Ctrl {
+        @Get("/")
+        get(@QueryParams("test") value: boolean) {}
+      }
+
+      const spec = getSpec(Ctrl, {specType: SpecTypes.OPENAPI});
+
+      expect(spec).toEqual({
+        paths: {
+          "/": {
+            get: {
+              operationId: "ctrlGet",
+              parameters: [
+                {
+                  in: "query",
+                  name: "test",
+                  required: false,
+                  schema: {type: "boolean"}
+                }
+              ],
+              responses: {
+                "200": {
+                  description: "Success"
+                }
+              },
+              tags: ["Ctrl"]
+            }
+          }
+        },
+        tags: [
+          {
+            name: "Ctrl"
+          }
+        ]
+      });
+    });
+  });
+});

package/src/decorators/useParam.ts

@@ -0,0 +1,38 @@
+import {useDecorators} from "@tsed/core";
+
+import {ParamOptions} from "../domain/ParamOptions.js";
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {UseDeserialization} from "./useDeserialization.js";
+import {UseParamType} from "./useParamType.js";
+import {UseType} from "./useType.js";
+import {UseValidation} from "./useValidation.js";
+
+/**
+ * @ignore
+ * @param options
+ */
+function mapPipes(options: Partial<ParamOptions>) {
+  const {paramType, useType, expression, useValidation, useMapper, ...props} = options;
+
+  return [paramType !== ParamTypes.FILES && UseType(useType), useValidation && UseValidation(), useMapper && UseDeserialization(props)];
+}
+
+/**
+ * Register a new param. It uses 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.
+ * - useMapper: Apply json mapper from the returned value by the previous pipe.
+ *
+ * @param options
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export function UseParam(options: Partial<ParamOptions>): ParameterDecorator {
+  return useDecorators(UseParamType(options as any), ...mapPipes(options)) as ParameterDecorator;
+}

package/src/decorators/useParamExpression.ts

@@ -0,0 +1,16 @@
+import {ParamFn} from "./paramFn.js";
+
+/**
+ * Get data from a path inside the given object
+ *
+ * @param expression
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export function UseParamExpression(expression?: string) {
+  return ParamFn((param) => {
+    param.expression = expression || "";
+  });
+}

package/src/decorators/useParamType.ts

@@ -0,0 +1,36 @@
+import {isBuffer, useDecorators} from "@tsed/core";
+import {isParameterType, Name} from "@tsed/schema";
+
+import {ParamOptions} from "../domain/ParamOptions.js";
+import {PARAM_TYPES_DATA_PATH, ParamTypes} from "../domain/ParamTypes.js";
+import {ParamFn} from "./paramFn.js";
+import {UseParamExpression} from "./useParamExpression.js";
+
+/**
+ * Get the object from request (like body, params, query, etc...).
+ *
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export function UseParamType(options: ParamOptions) {
+  return useDecorators(
+    ParamFn((param) => {
+      if (isParameterType(options.paramType)) {
+        param.parameter!.in(options.paramType);
+      }
+
+      param.paramType = options.paramType;
+
+      if (isBuffer(param.type) || isBuffer(options.useType) || options.paramType === ParamTypes.RAW_BODY) {
+        param.paramType = ParamTypes.RAW_BODY;
+        param.parent.operation?.consumes(["*/*"]);
+      }
+
+      param.dataPath = options.dataPath || PARAM_TYPES_DATA_PATH[param.paramType] || "$ctx";
+    }),
+    options.expression && UseParamExpression(options.expression),
+    options.expression && Name(options.expression)
+  );
+}

package/src/decorators/usePipe.ts

@@ -0,0 +1,21 @@
+import {Type} from "@tsed/core";
+import {PipeMethods} from "@tsed/schema";
+
+import {ParamFn} from "./paramFn.js";
+
+/**
+ * Register a Pipe to be used with the current decorated param.
+ *
+ * @param token
+ * @param options
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export function UsePipe(token: Type<PipeMethods>, options: any = {}) {
+  return ParamFn((param) => {
+    param.store.set(token, options);
+    param.pipes.push(token);
+  });
+}

package/src/decorators/useType.ts

@@ -0,0 +1,35 @@
+import {Type} from "@tsed/core";
+import {Any, CollectionOf, type JsonParameterStore} from "@tsed/schema";
+
+import {ParamFn} from "./paramFn.js";
+
+function shouldFallBackToAny(entity: JsonParameterStore) {
+  if (entity.itemSchema.has("allOf") || entity.itemSchema.has("anyOf") || entity.itemSchema.has("oneOf")) {
+    return false;
+  }
+
+  return entity.isCollection && entity.type === Object && [undefined, "object"].includes(entity.itemSchema.get("type"));
+}
+
+/**
+ * Set the type of the item collection.
+ *
+ * Prefer @@CollectionOf@@ usage.
+ *
+ * @param useType
+ * @decorator
+ * @operation
+ * @input
+ * @alias CollectionOf
+ */
+export function UseType(useType: undefined | any | Type<any>) {
+  return ParamFn((entity, parameters) => {
+    if (useType) {
+      return CollectionOf(useType);
+    }
+
+    if (shouldFallBackToAny(entity)) {
+      Any()(...parameters);
+    }
+  });
+}

package/src/decorators/useValidation.ts

@@ -0,0 +1,18 @@
+import {ValidationPipe} from "../pipes/ValidationPipe.js";
+import {ParamFn} from "./paramFn.js";
+
+/**
+ * Enable validation on the decoratored parameter.
+ *
+ * @decorator
+ * @operation
+ * @input
+ * @pipe
+ */
+export function UseValidation() {
+  return ParamFn((param) => {
+    if (param.type || param.collectionType) {
+      param.pipes.push(ValidationPipe);
+    }
+  });
+}

package/src/domain/ParamMetadata.ts

@@ -0,0 +1 @@
+export {ParamMetadata} from "@tsed/schema";

package/src/domain/ParamOptions.ts

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

package/src/domain/ParamTypes.ts

@@ -0,0 +1,37 @@
+export enum ParamTypes {
+  $CTX = "$CTX",
+  BODY = "BODY",
+  PATH = "PATH",
+  QUERY = "QUERY",
+  HEADER = "HEADER",
+  RAW_BODY = "RAW_BODY",
+  COOKIES = "COOKIES",
+  LOCALS = "LOCALS",
+  SESSION = "SESSION",
+  FILES = "FILES",
+
+  /// NOT STD
+  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"
+}
+
+export const PARAM_TYPES_DATA_PATH: Record<string, string> = {
+  [ParamTypes.HEADER]: "$ctx.request.headers",
+  [ParamTypes.RAW_BODY]: "$ctx.request.rawBody",
+  [ParamTypes.BODY]: "$ctx.request.body",
+  [ParamTypes.QUERY]: "$ctx.request.query",
+  [ParamTypes.PATH]: "$ctx.request.params",
+  [ParamTypes.COOKIES]: "$ctx.request.cookies",
+  [ParamTypes.SESSION]: "$ctx.request.session",
+  [ParamTypes.LOCALS]: "$ctx.response.locals"
+};

package/src/errors/ParamValidationError.spec.ts

@@ -0,0 +1,152 @@
+import {ParamValidationError} from "./ParamValidationError.js";
+import {RequiredValidationError} from "./RequiredValidationError.js";
+import {ValidationError} from "./ValidationError.js";
+
+describe("ParseExpressionError", () => {
+  it("should return error without transformation", () => {
+    expect(ParamValidationError.from({} as any, new Error("error")).message).toEqual("error");
+  });
+  it("should return error", () => {
+    const validationError = new ValidationError("message");
+
+    const error = ParamValidationError.from(
+      {
+        paramType: "name",
+        expression: "expression"
+      } as any,
+      validationError
+    );
+    expect(error.message).toEqual('Bad request on parameter "request.name.expression".\nmessage');
+    expect(error.name).toEqual("PARAM_VALIDATION_ERROR");
+    expect(error.dataPath).toEqual("expression");
+    expect(error.requestType).toEqual("name");
+    expect({
+      name: error.name,
+      status: error.status,
+      headers: error.headers,
+      type: error.type,
+      message: error.message,
+      dataPath: error.dataPath,
+      requestType: error.requestType,
+      origin: {
+        name: error.origin.name,
+        status: error.origin.status,
+        headers: error.origin.headers,
+        type: error.origin.type,
+        message: error.origin.message,
+        errors: error.origin.errors
+      }
+    }).toEqual({
+      dataPath: "expression",
+      headers: {},
+      name: "PARAM_VALIDATION_ERROR",
+      requestType: "name",
+      status: 400,
+      type: "HTTP_EXCEPTION",
+      message: 'Bad request on parameter "request.name.expression".\nmessage',
+      origin: {
+        errors: [],
+        headers: {},
+        message: "message",
+        name: "VALIDATION_ERROR",
+        status: 400,
+        type: "HTTP_EXCEPTION"
+      }
+    });
+  });
+  it("should throw error from origin error (RequiredValidationError)", () => {
+    const metadata = {
+      paramType: "name",
+      expression: "expression"
+    } as any;
+    const origin = RequiredValidationError.from(metadata);
+
+    const error = ParamValidationError.from(metadata, origin);
+    expect(error.message).toEqual("Bad request on parameter \"request.name.expression\".\nIt should have required parameter 'expression'");
+    expect(error.dataPath).toEqual("expression");
+    expect(error.requestType).toEqual("name");
+
+    expect({
+      ...error,
+      message: error.message,
+      origin: {
+        ...error.origin,
+        message: error.origin.message
+      }
+    }).toEqual({
+      dataPath: "expression",
+      headers: {},
+      name: "PARAM_VALIDATION_ERROR",
+      message: "Bad request on parameter \"request.name.expression\".\nIt should have required parameter 'expression'",
+      origin: {
+        errors: [
+          {
+            requestPath: "name",
+            dataPath: ".expression",
+            keyword: "required",
+            message: "It should have required parameter 'expression'",
+            modelName: "name",
+            params: {
+              missingProperty: "expression"
+            },
+            schemaPath: "#/required"
+          }
+        ],
+        headers: {},
+        name: "REQUIRED_VALIDATION_ERROR",
+        message: "It should have required parameter 'expression'",
+        status: 400,
+        type: "HTTP_EXCEPTION"
+      },
+      requestType: "name",
+      status: 400,
+      type: "HTTP_EXCEPTION"
+    });
+  });
+  it("should throw error from origin error (ValidationError)", () => {
+    const metadata = {
+      paramType: "name",
+      expression: "expression"
+    } as any;
+    const origin = new ValidationError("It should have 1 item", [
+      {
+        dataPath: "hello"
+      }
+    ]);
+
+    const error = ParamValidationError.from(metadata, origin);
+    expect(error.message).toEqual('Bad request on parameter "request.name.expression".\nIt should have 1 item');
+    expect(error.dataPath).toEqual("expression");
+    expect(error.requestType).toEqual("name");
+
+    expect({
+      ...error,
+      message: error.message,
+      origin: {
+        ...error.origin,
+        message: error.origin.message
+      }
+    }).toEqual({
+      dataPath: "expression",
+      headers: {},
+      name: "PARAM_VALIDATION_ERROR",
+      origin: {
+        errors: [
+          {
+            requestPath: "name",
+            dataPath: "hello"
+          }
+        ],
+        headers: {},
+        message: "It should have 1 item",
+        name: "VALIDATION_ERROR",
+        status: 400,
+        type: "HTTP_EXCEPTION"
+      },
+      message: 'Bad request on parameter "request.name.expression".\nIt should have 1 item',
+      requestType: "name",
+      status: 400,
+      type: "HTTP_EXCEPTION"
+    });
+  });
+});