@tsed/platform-params 8.0.1 → 8.0.3

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

@@ -3,7 +3,7 @@
  *
  * ::: 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.
+ * See [Templating](https://tsed.dev/tutorials/templating.html) section for more details.
  * :::
  *
  * #### Example

package/package.json

@@ -2,13 +2,14 @@
   "name": "@tsed/platform-params",
   "description": "Params module for Ts.ED Framework",
   "type": "module",
-  "version": "8.0.1",
+  "version": "8.0.3",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
   "typings": "./lib/types/index.d.ts",
   "exports": {
     ".": {
+      "@tsed/source": "./src/index.ts",
       "types": "./lib/types/index.d.ts",
       "import": "./lib/esm/index.js",
       "default": "./lib/esm/index.js"
@@ -25,23 +26,23 @@
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.0.1",
-    "@tsed/core": "8.0.1",
-    "@tsed/di": "8.0.1",
-    "@tsed/exceptions": "8.0.1",
-    "@tsed/json-mapper": "8.0.1",
-    "@tsed/schema": "8.0.1",
-    "@tsed/typescript": "8.0.1",
+    "@tsed/barrels": "8.0.3",
+    "@tsed/core": "8.0.3",
+    "@tsed/di": "8.0.3",
+    "@tsed/exceptions": "8.0.3",
+    "@tsed/json-mapper": "8.0.3",
+    "@tsed/schema": "8.0.3",
+    "@tsed/typescript": "8.0.3",
     "eslint": "9.12.0",
     "typescript": "5.4.5",
     "vitest": "2.1.2"
   },
   "peerDependencies": {
-    "@tsed/core": "8.0.1",
-    "@tsed/di": "8.0.1",
-    "@tsed/exceptions": "8.0.1",
-    "@tsed/json-mapper": "8.0.1",
-    "@tsed/schema": "8.0.1"
+    "@tsed/core": "8.0.3",
+    "@tsed/di": "8.0.3",
+    "@tsed/exceptions": "8.0.3",
+    "@tsed/json-mapper": "8.0.3",
+    "@tsed/schema": "8.0.3"
   },
   "peerDependenciesMeta": {
     "@tsed/core": {

package/src/builder/PlatformParams.spec.ts

@@ -0,0 +1,431 @@
+import {Injectable, ProviderScope} from "@tsed/di";
+import {PlatformTest} from "@tsed/platform-http/testing";
+
+import {buildPlatformParams, invokePlatformParams} from "../../test/helpers/buildPlatformParams.js";
+import {PathParams} from "../decorators/pathParams.js";
+import {QueryParams} from "../decorators/queryParams.js";
+import {ParamTypes} from "../domain/ParamTypes.js";
+
+describe("PlatformParams", () => {
+  beforeEach(() => PlatformTest.create());
+  afterEach(() => PlatformTest.reset());
+  describe("getArg()", () => {
+    it("should return REQUEST (node)", async () => {
+      // GIVEN
+      const {param, $ctx, h, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.NODE_REQUEST,
+        dataPath: "$ctx.request.req"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getReq());
+    });
+    it("should return REQUEST (framework)", async () => {
+      // GIVEN
+      const {param, $ctx, h, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.REQUEST,
+        dataPath: "$ctx.request.request"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getRequest());
+    });
+    it("should return REQUEST (platform)", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.PLATFORM_REQUEST,
+        dataPath: "$ctx.request"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.request);
+    });
+    it("should return RESPONSE (node)", async () => {
+      // GIVEN
+      const {param, $ctx, h, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.NODE_RESPONSE,
+        dataPath: "$ctx.response.res"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getRes());
+    });
+    it("should return RESPONSE (framework)", async () => {
+      // GIVEN
+      const {param, $ctx, h, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.RESPONSE,
+        dataPath: "$ctx.response.response"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getResponse());
+    });
+    it("should return RESPONSE (platform)", async () => {
+      // GIVEN
+      const {param, $ctx, h, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.PLATFORM_RESPONSE,
+        dataPath: "$ctx.response"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.response);
+    });
+    it("should return NEXT", async () => {
+      // GIVEN
+      const {param, h, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.NEXT_FN,
+        dataPath: "next"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toBeInstanceOf(Function);
+    });
+    it("should return ERR", async () => {
+      // GIVEN
+      const {param, h, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.ERR,
+        dataPath: "$ctx.error"
+      });
+      h.$ctx.error = new Error();
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual(h.$ctx.error);
+    });
+    it("should return $CTX", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.$CTX,
+        dataPath: "$ctx"
+      });
+
+      // WHEN
+      // @ts-ignore
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx);
+    });
+    it("should return RESPONSE_DATA", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.RESPONSE_DATA,
+        dataPath: "$ctx.data"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.data);
+    });
+    it("should return ENDPOINT_INFO", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.ENDPOINT_INFO,
+        dataPath: "$ctx.endpoint"
+      });
+
+      // @ts-ignore
+      $ctx.endpoint = "endpoint";
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.endpoint);
+    });
+    it("should return BODY", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.BODY,
+        dataPath: "$ctx.request.body"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getRequest().body);
+    });
+    it("should return PATH", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.PATH,
+        dataPath: "$ctx.request.params"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getRequest().params);
+    });
+    it("should return QUERY", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.QUERY,
+        dataPath: "$ctx.request.query"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getRequest().query);
+    });
+    it("should return HEADER", async () => {
+      // GIVEN
+      const {param, h, platformParams, ctx} = await buildPlatformParams({
+        paramType: ParamTypes.HEADER,
+        dataPath: "$ctx.request.headers"
+      });
+
+      ctx.request.raw.headers["accept"] = "application/json";
+      ctx.request.raw.headers["content-type"] = "application/json";
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual({
+        accept: "application/json",
+        "content-type": "application/json"
+      });
+    });
+    it("should return COOKIES", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.COOKIES,
+        dataPath: "$ctx.request.cookies"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getRequest().cookies);
+    });
+    it("should return SESSION", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.SESSION,
+        dataPath: "$ctx.request.session"
+      });
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.request.session);
+    });
+    it("should return LOCALS", async () => {
+      // GIVEN
+      const {param, h, $ctx, platformParams} = await buildPlatformParams({
+        paramType: ParamTypes.LOCALS,
+        dataPath: "$ctx.response.locals"
+      });
+
+      h.$ctx.error = new Error();
+
+      // WHEN
+      const pipes = await platformParams.getPipes(param);
+      const value = await platformParams.getArg(h, pipes, param);
+
+      // THEN
+      expect(value).toEqual($ctx.getResponse().locals);
+    });
+  });
+  describe("compileHandler()", () => {
+    it("should build all params and return value (SINGLETON)", async () => {
+      const platformParams = await invokePlatformParams();
+
+      @Injectable()
+      class MyCtrTest {
+        get(@PathParams() params: any, @QueryParams() query: any) {
+          return {params, query};
+        }
+      }
+
+      PlatformTest.injector.addProvider(MyCtrTest);
+
+      const handler = await platformParams.compileHandler({
+        token: MyCtrTest,
+        propertyKey: "get"
+      });
+
+      const $ctx = PlatformTest.createRequestContext({
+        event: {
+          request: {
+            query: {
+              test: "test"
+            },
+            params: {
+              s: "s"
+            }
+          }
+        }
+      });
+
+      const result = await handler({
+        $ctx
+      });
+
+      expect(result).toEqual({
+        query: {
+          test: "test"
+        },
+        params: {
+          s: "s"
+        }
+      });
+    });
+    it("should build all params and return value (REQUEST)", async () => {
+      const platformParams = await invokePlatformParams();
+
+      @Injectable({
+        scope: ProviderScope.REQUEST
+      })
+      class MyCtrTest {
+        get(@PathParams() params: any, @QueryParams() query: any) {
+          return {params, query};
+        }
+      }
+
+      const $ctx = PlatformTest.createRequestContext({
+        event: {
+          request: {
+            query: {
+              test: "test"
+            },
+            params: {
+              s: "s"
+            }
+          }
+        }
+      });
+
+      PlatformTest.injector.addProvider(MyCtrTest);
+
+      const handler = await platformParams.compileHandler({
+        token: MyCtrTest,
+        propertyKey: "get"
+      });
+
+      const result = await handler({
+        $ctx
+      });
+
+      expect(result).toEqual({
+        query: {
+          test: "test"
+        },
+        params: {
+          s: "s"
+        }
+      });
+    });
+    it("should call without args", async () => {
+      const platformParams = await invokePlatformParams();
+
+      @Injectable()
+      class MyCtrTest {
+        get() {
+          return "test";
+        }
+      }
+
+      PlatformTest.injector.addProvider(MyCtrTest);
+
+      const $ctx = PlatformTest.createRequestContext({
+        event: {
+          request: {
+            query: {
+              test: "test"
+            },
+            params: {
+              s: "s"
+            }
+          }
+        }
+      });
+
+      const handler = await platformParams.compileHandler({
+        token: MyCtrTest,
+        propertyKey: "get"
+      });
+
+      const result = await handler({
+        $ctx
+      });
+
+      expect(result).toEqual("test");
+    });
+    it("should return handler", async () => {
+      const platformParams = await invokePlatformParams();
+
+      const $ctx = PlatformTest.createRequestContext({
+        event: {
+          request: {
+            query: {
+              test: "test"
+            },
+            params: {
+              s: "s"
+            }
+          }
+        }
+      });
+
+      const handler = await platformParams.compileHandler({
+        handler: ($ctx: any) => $ctx.request.query.test
+      });
+
+      const result = await handler({
+        $ctx
+      });
+
+      expect(result).toEqual("test");
+    });
+  });
+});

package/src/builder/PlatformParams.ts

@@ -0,0 +1,86 @@
+import {DIContext, Inject, Injectable, injectable, injector, InjectorService, ProviderScope, TokenProvider} from "@tsed/di";
+import {JsonMethodStore, JsonParameterStore, PipeMethods} from "@tsed/schema";
+
+import {ParamValidationError} from "../errors/ParamValidationError.js";
+import {ParseExpressionPipe} from "../pipes/ParseExpressionPipe.js";
+
+export type PlatformParamsScope<Context extends DIContext = DIContext> = {$ctx: Context} & Record<string, any>;
+export type PlatformParamsCallback<Context extends DIContext = DIContext> = (scope: PlatformParamsScope<Context>) => Promise<any>;
+
+/**
+ * Platform Params abstraction layer.
+ * @platform
+ */
+
+export class PlatformParams {
+  getPipes(param: JsonParameterStore) {
+    const get = (pipe: TokenProvider) => {
+      return injector().getProvider(pipe)!.priority || 0;
+    };
+
+    const sort = (p1: TokenProvider, p2: TokenProvider) => (get(p1) < get(p2) ? -1 : get(p1) > get(p2) ? 1 : 0);
+    const map = (token: TokenProvider) => injector().get<PipeMethods>(token)!;
+
+    return [ParseExpressionPipe, ...param.pipes.sort(sort)].map(map).filter(Boolean);
+  }
+
+  /**
+   * Return a handler with injectable parameters
+   * @param handlerMetadata
+   */
+  compileHandler<Context extends DIContext = DIContext>({
+    propertyKey,
+    token,
+    handler
+  }: {
+    propertyKey?: string | symbol;
+    token?: any;
+    handler?: any;
+  }): PlatformParamsCallback<Context> {
+    if (!token || !propertyKey) {
+      return (scope: PlatformParamsScope<Context>) => handler(scope.$ctx);
+    }
+
+    const inj = injector();
+    const store = JsonMethodStore.fromMethod(token, propertyKey);
+    const getArguments = this.compile<Context>(store);
+    const provider = inj.getProvider(token)!;
+
+    return async (scope: PlatformParamsScope<Context>) => {
+      const container = provider.scope === ProviderScope.REQUEST ? scope.$ctx.container : undefined;
+
+      const [instance, args] = await Promise.all([inj.invoke<any>(token, {locals: container}), getArguments(scope)]);
+
+      return instance[propertyKey].call(instance, ...args, scope.$ctx);
+    };
+  }
+
+  compile<Context extends DIContext = DIContext>(entity: JsonMethodStore): PlatformParamsCallback<Context> {
+    const params = JsonParameterStore.getParams(entity.target, entity.propertyKey);
+    const argsPipes = params.map((param) => {
+      return {
+        param,
+        pipes: this.getPipes(param)
+      };
+    });
+
+    return (scope) => {
+      const promises = argsPipes.map(({param, pipes}) => this.getArg(scope, pipes, param));
+      return Promise.all(promises);
+    };
+  }
+
+  getArg<Context extends DIContext = DIContext>(scope: PlatformParamsScope, pipes: PipeMethods[], param: JsonParameterStore): Promise<any> {
+    return pipes.reduce(async (value: any | Promise<any>, pipe) => {
+      value = await value;
+
+      try {
+        return await pipe.transform(value, param);
+      } catch (er) {
+        throw ParamValidationError.from(param, er);
+      }
+    }, scope);
+  }
+}
+
+injectable(PlatformParams).imports([ParseExpressionPipe]);

package/src/decorators/bodyParams.spec.ts

@@ -0,0 +1,121 @@
+import {Controller} from "@tsed/di";
+import {getSpec, JsonParameterStore, Post, SpecTypes} from "@tsed/schema";
+
+import {ParamTypes} from "../domain/ParamTypes.js";
+import {BodyParams, RawBodyParams} from "./bodyParams.js";
+
+describe("@BodyParams", () => {
+  it("should call useParam method with the correct parameters", () => {
+    class Test {}
+
+    class Ctrl {
+      test(@BodyParams("expression", 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);
+  });
+  it("should create params with Buffer type", () => {
+    @Controller("/")
+    class MyCtrl {
+      @Post()
+      test(@BodyParams() body: Buffer) {}
+    }
+
+    const spec = getSpec(MyCtrl, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          post: {
+            operationId: "myCtrlTest",
+            parameters: [],
+            requestBody: {
+              content: {
+                "*/*": {
+                  schema: {
+                    type: "string"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyCtrl"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyCtrl"
+        }
+      ]
+    });
+  });
+});
+
+describe("RawBodyParams()", () => {
+  it("should declare a RawBodyParams", () => {
+    @Controller("/")
+    class MyCtrl {
+      @Post()
+      test(@RawBodyParams() body: Buffer) {}
+    }
+
+    const spec = getSpec(MyCtrl, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          post: {
+            operationId: "myCtrlTest",
+            parameters: [],
+            requestBody: {
+              content: {
+                "*/*": {
+                  schema: {
+                    type: "string"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyCtrl"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyCtrl"
+        }
+      ]
+    });
+
+    const param = JsonParameterStore.get(MyCtrl, "test", 0);
+    expect(param.paramType).toEqual(ParamTypes.RAW_BODY);
+    expect(param.type).toEqual(Buffer);
+    expect(param.pipes).toHaveLength(0);
+  });
+  it("should declare RawBodyParams with options", () => {
+    class Ctrl {
+      test(@RawBodyParams({useValidation: true, useType: String}) param: Date) {}
+    }
+
+    const param = JsonParameterStore.get(Ctrl, "test", 0);
+    expect(param.expression).toEqual(undefined);
+    expect(param.paramType).toEqual(ParamTypes.RAW_BODY);
+    expect(param.type).toEqual(String);
+    expect(param.pipes).toHaveLength(1);
+  });
+});