@tsed/platform-params 8.0.1 → 8.0.3

package/src/decorators/bodyParams.ts

@@ -0,0 +1,93 @@
+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";
+
+/**
+ * BodyParams return the value from [request.body](http://expressjs.com/en/4x/api.html#req.body) object.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Post('/')
+ *    create(@BodyParams() body: any) {
+ *       console.log('Entire body', body);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@BodyParams('id') id: string) {
+ *       console.log('ID', id);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@BodyParams('user') user: User) { // with deserialization
+ *       console.log('user', user);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@BodyParams('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 BodyParams(expression: string, useType: Type<any>): ParameterDecorator;
+export function BodyParams(expression: string): ParameterDecorator;
+export function BodyParams(useType: Type<any>): ParameterDecorator;
+export function BodyParams(options: Partial<ParamOptions>): ParameterDecorator;
+export function BodyParams(): ParameterDecorator;
+export function BodyParams(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = true, useValidation = true} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.BODY,
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}
+
+/**
+ * RawBodyParams return the value from [request.body](http://expressjs.com/en/4x/api.html#req.body) as a Buffer.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Post('/')
+ *    create(@RawBodyParams() body: Buffer) {
+ *       console.log('Entire body', body.toString("utf8"));
+ *    }
+ * }
+ * ```
+ *
+ * @decorator
+ * @operation
+ * @input
+ * @alias BodyParams Example: @BodyParams() payload: Buffer
+ */
+export function RawBodyParams(options: Partial<Omit<ParamOptions, "expression">>): ParameterDecorator;
+export function RawBodyParams(): ParameterDecorator;
+export function RawBodyParams(...args: any[]): ParameterDecorator {
+  const {useType, useMapper = false, useValidation = false} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.RAW_BODY,
+    useType,
+    useMapper,
+    useValidation
+  });
+}

package/src/decorators/context.spec.ts

@@ -0,0 +1,16 @@
+import {JsonParameterStore} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {Context} from "./context.js";
+
+describe("@Context", () => {
+  it("should call ParamFilter.useParam method with the correct parameters", () => {
+    class Ctrl {
+      test(@Context("expression") test: any) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.$CTX);
+  });
+});

package/src/decorators/context.ts

@@ -0,0 +1,70 @@
+import {BaseContext} from "@tsed/di";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {mapParamsOptions} from "../utils/mapParamsOptions.js";
+import {UseParam} from "./useParam.js";
+
+/**
+ * Context decorator return the @@PlatformContext@@ created by Ts.ED when request is handled by the server.
+ *
+ * It contains some information as following:
+ *
+ * - The request id,
+ * - The request container used by the Ts.ED DI. It contain all services annotated with `@Scope(ProviderScope.REQUEST)`,
+ * - The current @@EndpointMetadata@@ resolved by Ts.ED during the request,
+ * - The data return by the previous endpoint if you use multiple handler on the same route. By default data is empty.
+ *
+ * ::: tip
+ * The @@PlatformContext@@ inherit from Map class. So you can store any information with.
+ * :::
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Middleware()
+ * class AuthTokenMiddleware {
+ *   use(@Req() request: Req, @Context() context: PlatformContext) {
+ *      if (!context.has("auth")){
+ *        context.set('auth', new AuthToken(request))
+ *      }
+ *
+ *      try {
+ *        context.get("auth").claims() // check token
+ *      } catch(er){
+ *        throw new Forbidden("Access forbidden - Bad token")
+ *      }
+ *   }
+ * }
+ *
+ * @Controller('/')
+ * @UseBefore(AuthTokenMiddleware) // protect all routes for this controller
+ * class MyCtrl {
+ *    @Get('/')
+ *    get(@Context('auth') auth: AuthToken) {
+ *       console.log('auth', auth);
+ *       console.log('auth.accessToken', auth.accessToken);
+ *       console.log('auth.idToken', auth.idToken);
+ *    }
+ * }
+ * ```
+ *
+ * @param expression The path of the property to get.
+ * @decorator
+ * @operation
+ * @input
+ */
+export function Context(expression: string): ParameterDecorator;
+export function Context(): ParameterDecorator;
+export function Context(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = false, useValidation = false} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.$CTX,
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}
+
+export type Context = BaseContext;

package/src/decorators/cookies.spec.ts

@@ -0,0 +1,19 @@
+import {JsonParameterStore} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {Cookies} from "./cookies.js";
+
+describe("@Cookies", () => {
+  it("should call ParamFilter.useParam method with the correct parameters", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@Cookies("expression", Test) body: Test) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.COOKIES);
+    expect(param.type).toEqual(Test);
+  });
+});

package/src/decorators/cookies.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";
+
+/**
+ * Cookies or CookiesParams return the value from [request.cookies](http://expressjs.com/en/4x/api.html#req.cookies) object.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Post('/')
+ *    create(@Cookies() cookies: any) {
+ *       console.log('Entire cookies', cookies);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@Cookies('id') id: string) {
+ *       console.log('ID', id);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@Cookies('user') user: IUser) {
+ *       console.log('user', user);
+ *    }
+ * }
+ * ```
+ * > 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 CookiesParams(expression: string | any, useType: any): ParameterDecorator;
+export function CookiesParams(): ParameterDecorator;
+export function CookiesParams(expression: string | any): ParameterDecorator;
+export function CookiesParams(options: ParamOptions<any>): ParameterDecorator;
+export function CookiesParams(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = false, useValidation = false} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.COOKIES,
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}
+
+/**
+ * Cookies or CookiesParams return the value from [request.cookies](http://expressjs.com/en/4x/api.html#req.cookies) object.
+ *
+ * #### Example
+ *
+ * ```typescript
+ * @Controller('/')
+ * class MyCtrl {
+ *    @Post('/')
+ *    create(@Cookies() body: any) {
+ *       console.log('Entire body', body);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@Cookies('id') id: string) {
+ *       console.log('ID', id);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@Cookies('user') user: User) { // with deserialization
+ *       console.log('user', user);
+ *    }
+ *
+ *    @Post('/')
+ *    create(@Cookies('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
+ * @aliasof CookiesParams
+ * @operation
+ * @input
+ */
+export function Cookies(expression: string, useType: Type<any>): ParameterDecorator;
+export function Cookies(expression: string): ParameterDecorator;
+export function Cookies(useType: Type<any>): ParameterDecorator;
+export function Cookies(options: Partial<ParamOptions>): ParameterDecorator;
+export function Cookies(): ParameterDecorator;
+export function Cookies(...args: any[]): ParameterDecorator {
+  // @ts-ignore
+  return CookiesParams(...args);
+}

package/src/decorators/headerParams.spec.ts

@@ -0,0 +1,16 @@
+import {JsonParameterStore} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {HeaderParams} from "./headerParams.js";
+
+describe("@HeaderParams", () => {
+  it("should call ParamFilter.useParam method with the correct parameters", () => {
+    class Ctrl {
+      test(@HeaderParams("expression") header: string) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.HEADER);
+  });
+});

package/src/decorators/headerParams.ts

@@ -0,0 +1,49 @@
+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";
+
+/**
+ * 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 function HeaderParams(expression: string, useType: Type<any>): ParameterDecorator;
+export function HeaderParams(expression: string): ParameterDecorator;
+export function HeaderParams(useType: Type<any>): ParameterDecorator;
+export function HeaderParams(options: Partial<ParamOptions>): ParameterDecorator;
+export function HeaderParams(): ParameterDecorator;
+export function HeaderParams(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = false, useValidation = false} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.HEADER,
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}

package/src/decorators/locals.spec.ts

@@ -0,0 +1,16 @@
+import {JsonParameterStore} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {Locals} from "./locals.js";
+
+describe("@Locals", () => {
+  it("should call ParamFilter.useParam method with the correct parameters", () => {
+    class Ctrl {
+      test(@Locals("expression") test: any) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.LOCALS);
+  });
+});

package/src/decorators/locals.ts

@@ -0,0 +1,57 @@
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {mapParamsOptions} from "../utils/mapParamsOptions.js";
+import {UseParam} from "./useParam.js";
+
+/**
+ * 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](https://tsed.dev/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 function Locals(expression: string): ParameterDecorator;
+export function Locals(): ParameterDecorator;
+export function Locals(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = false, useValidation = false} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.LOCALS,
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}

package/src/decorators/paramFn.ts

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

package/src/decorators/pathParams.spec.ts

@@ -0,0 +1,58 @@
+import {JsonParameterStore} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {PathParams, RawPathParams} from "./pathParams.js";
+
+describe("@PathParams", () => {
+  it("should declare a path params", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@PathParams("expression", Test) header: Test) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.PATH);
+    expect(param.type).toEqual(Test);
+    expect(param.pipes).toHaveLength(2);
+  });
+  it("should declara a path params with options", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@PathParams({expression: "expression", useType: Test, useValidation: false}) param: Test) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.PATH);
+    expect(param.type).toEqual(Test);
+    expect(param.pipes).toHaveLength(1);
+  });
+});
+
+describe("@RawPathParams", () => {
+  it("should declare a raw path params", () => {
+    class Ctrl {
+      test(@RawPathParams("expression") header: string) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.PATH);
+    expect(param.type).toEqual(String);
+    expect(param.pipes).toHaveLength(0);
+  });
+  it("should declare a raw path params with options", () => {
+    class Ctrl {
+      test(@RawPathParams({expression: "expression", useValidation: true, useType: String}) param: Date) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.PATH);
+    expect(param.type).toEqual(String);
+    expect(param.pipes).toHaveLength(1);
+  });
+});

package/src/decorators/pathParams.ts

@@ -0,0 +1,97 @@
+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";
+
+/**
+ * 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/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 PathParams(expression: string, useType: Type<any>): ParameterDecorator;
+export function PathParams(expression: string): ParameterDecorator;
+export function PathParams(useType: Type<any>): ParameterDecorator;
+export function PathParams(options: Partial<ParamOptions>): ParameterDecorator;
+export function PathParams(): ParameterDecorator;
+export function PathParams(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = true, useValidation = true} = mapParamsOptions(args);
+
+  return UseParam({
+    paramType: ParamTypes.PATH,
+    expression,
+    useType,
+    useMapper,
+    useValidation
+  });
+}
+
+/**
+ * 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/json-mapper.md) page.
+ *
+ * @param expression The path of the property to get.
+ * @decorator
+ * @operation
+ * @input
+ */
+export function RawPathParams(expression: string): ParameterDecorator;
+export function RawPathParams(options: Partial<ParamOptions>): ParameterDecorator;
+export function RawPathParams(): ParameterDecorator;
+export function RawPathParams(...args: any[]): ParameterDecorator {
+  const {expression, useType, useMapper = false, useValidation = false} = mapParamsOptions(args);
+
+  return PathParams({
+    expression,
+    useValidation,
+    useMapper,
+    useType
+  });
+}

package/src/decorators/queryParams.spec.ts

@@ -0,0 +1,58 @@
+import {JsonParameterStore} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {QueryParams, RawQueryParams} from "./queryParams.js";
+
+describe("@QueryParams", () => {
+  it("should declare query params", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@QueryParams("expression", Test) header: Test) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.QUERY);
+    expect(param.type).toEqual(Test);
+    expect(param.pipes).toHaveLength(2);
+  });
+  it("should declare query params with options", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@QueryParams({expression: "expression", useType: Test, useValidation: false}) param: Test) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.QUERY);
+    expect(param.type).toEqual(Test);
+    expect(param.pipes).toHaveLength(1);
+  });
+});
+
+describe("@RawQueryParams", () => {
+  it("should declare raw query params", () => {
+    class Ctrl {
+      test(@RawQueryParams("expression") header: string) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.QUERY);
+    expect(param.type).toEqual(String);
+    expect(param.pipes).toHaveLength(0);
+  });
+  it("should declare raw query params with options", () => {
+    class Ctrl {
+      test(@RawQueryParams({expression: "expression", useValidation: true, useType: String}) param: Date) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual("expression");
+    expect(param.paramType).toEqual(ParamTypes.QUERY);
+    expect(param.type).toEqual(String);
+    expect(param.pipes).toHaveLength(1);
+  });
+});