Merge pull request #26 from storyofams/beta

Release v1.2.0

Author: ggurkal

.github/workflows/release.yaml

@@ -3,6 +3,7 @@ on:
   push:
     branches:
       - master
+      - beta
 jobs:
   release:
     name: Release

lib/decorators/parameter.decorator.spec.ts

@@ -13,7 +13,7 @@ describe('Parameter decorators', () => {
     const meta = Reflect.getMetadata(PARAMETER_TOKEN, Test, 'index');
     expect(Array.isArray(meta)).toBe(true);
     expect(meta).toHaveLength(1);
-    expect(meta).toMatchObject(expect.arrayContaining([{ index: 0, location: 'body' }]));
+    expect(meta).toMatchObject(expect.arrayContaining([expect.objectContaining({ index: 0, location: 'body' })]));
   });
 
   it('Header should be set.', () => {
@@ -26,13 +26,26 @@ describe('Parameter decorators', () => {
     expect(meta).toHaveLength(2);
     expect(meta).toMatchObject(
       expect.arrayContaining([
-        { index: 0, location: 'header', name: 'Content-Type' },
-        { index: 1, location: 'header', name: 'Referer' }
+        expect.objectContaining({ index: 0, location: 'header', name: 'Content-Type' }),
+        expect.objectContaining({ index: 1, location: 'header', name: 'Referer' })
       ])
     );
   });
 
-  it('Header should be set.', () => {
+  it('Query should be set for the whole query string.', () => {
+    class Test {
+      public index(@Query() query: any) {}
+    }
+
+    const meta = Reflect.getMetadata(PARAMETER_TOKEN, Test, 'index');
+    expect(Array.isArray(meta)).toBe(true);
+    expect(meta).toHaveLength(1);
+    expect(meta).toMatchObject(
+      expect.arrayContaining([expect.objectContaining({ index: 0, location: 'query', name: undefined })])
+    );
+  });
+
+  it('Query parameters should be set.', () => {
     class Test {
       public index(
         @Query('firstName') firstName: string,
@@ -46,9 +59,9 @@ describe('Parameter decorators', () => {
     expect(meta).toHaveLength(3);
     expect(meta).toMatchObject(
       expect.arrayContaining([
-        { index: 0, location: 'query', name: 'firstName' },
-        { index: 1, location: 'query', name: 'lastName' },
-        { index: 2, location: 'query', name: 'city' }
+        expect.objectContaining({ index: 0, location: 'query', name: 'firstName' }),
+        expect.objectContaining({ index: 1, location: 'query', name: 'lastName' }),
+        expect.objectContaining({ index: 2, location: 'query', name: 'city' })
       ])
     );
   });
@@ -61,7 +74,7 @@ describe('Parameter decorators', () => {
     const meta = Reflect.getMetadata(PARAMETER_TOKEN, Test, 'index');
     expect(Array.isArray(meta)).toBe(true);
     expect(meta).toHaveLength(1);
-    expect(meta).toMatchObject(expect.arrayContaining([{ index: 0, location: 'request' }]));
+    expect(meta).toMatchObject(expect.arrayContaining([expect.objectContaining({ index: 0, location: 'request' })]));
   });
 
   it('Res should be set.', () => {
@@ -72,7 +85,7 @@ describe('Parameter decorators', () => {
     const meta = Reflect.getMetadata(PARAMETER_TOKEN, Test, 'index');
     expect(Array.isArray(meta)).toBe(true);
     expect(meta).toHaveLength(1);
-    expect(meta).toMatchObject(expect.arrayContaining([{ index: 0, location: 'response' }]));
+    expect(meta).toMatchObject(expect.arrayContaining([expect.objectContaining({ index: 0, location: 'response' })]));
   });
 
   it('Request and Response should be set.', () => {
@@ -85,8 +98,8 @@ describe('Parameter decorators', () => {
     expect(meta).toHaveLength(2);
     expect(meta).toMatchObject(
       expect.arrayContaining([
-        { index: 0, location: 'request' },
-        { index: 1, location: 'response' }
+        expect.objectContaining({ index: 0, location: 'request' }),
+        expect.objectContaining({ index: 1, location: 'response' })
       ])
     );
   });

lib/decorators/parameter.decorators.ts

@@ -19,18 +19,33 @@ function addParameter(location: MetaParameter['location'], name?: MetaParameter[
   };
 }
 
+/** Returns the query string. */
+export function Query(): ParameterDecorator;
 /**
  * Returns a parameter from the query string.
  *
  * @param name Parameter name
  */
-export function Query(name: string, ...pipes: ParameterPipe<any>[]): ParameterDecorator {
-  return addParameter('query', name, pipes.length ? pipes : undefined);
+export function Query(name: string, ...pipes: ParameterPipe<any>[]): ParameterDecorator;
+/**
+ * Returns the query string with pipes applied.
+ *
+ * @param pipes Pipes to be applied.
+ */
+export function Query(...pipes: ParameterPipe<any>[]): ParameterDecorator;
+export function Query(nameOrPipes?: string | ParameterPipe<any>, ...pipes: ParameterPipe<any>[]): ParameterDecorator {
+  if (typeof nameOrPipes === 'string') {
+    return addParameter('query', nameOrPipes, pipes.length ? pipes : undefined);
+  } else if (typeof nameOrPipes === 'function') {
+    return addParameter('query', undefined, [nameOrPipes, ...pipes]);
+  } else {
+    return addParameter('query', undefined);
+  }
 }
 
 /** Returns the request body. */
-export function Body(): ParameterDecorator {
-  return addParameter('body');
+export function Body(...pipes: ParameterPipe<any>[]): ParameterDecorator {
+  return addParameter('body', undefined, pipes);
 }
 
 /**

lib/e2e.test.ts

@@ -4,8 +4,10 @@ import express from 'express';
 import type { NextApiRequest, NextApiResponse } from 'next';
 import request from 'supertest';
 import { createHandler } from './createHandler';
-import { Body, Delete, Get, Header, HttpCode, Post, Put, Query, Req, Response, SetHeader } from './decorators';
+import { Body, Delete, Get, Header, HttpCode, Post, Put, Query, Req, Res, Response, SetHeader } from './decorators';
+import { ValidationPipe } from './pipes';
 import { ParseBooleanPipe } from './pipes/parseBoolean.pipe';
+import { ParseDatePipe } from './pipes/parseDate.pipe';
 import { ParseNumberPipe } from './pipes/parseNumber.pipe';
 
 enum CreateSource {
@@ -47,23 +49,36 @@ class TestHandler {
   public read(
     @Header('Content-Type') contentType: string,
     @Query('id') id: string,
-    @Query('step', ParseNumberPipe) step: number,
-    @Query('redirect', ParseBooleanPipe) redirect: boolean
+    @Query('step', ParseNumberPipe({ nullable: false })) step: number,
+    @Query('redirect', ParseBooleanPipe) redirect: boolean,
+    @Query('startAt', ParseDatePipe) startAt: Date
   ) {
-    return { contentType, id, step, redirect, test: this.testField };
+    return {
+      contentType,
+      id,
+      step,
+      redirect,
+      test: this.testField,
+      startAt,
+      isStartAtDateInstance: startAt instanceof Date
+    };
   }
 
   @HttpCode(201)
   @Post()
   @SetHeader('X-Method', 'create')
-  public create(@Header('Content-Type') contentType: string, @Body() body: CreateDto) {
+  public create(@Header('Content-Type') contentType: string, @Body(ValidationPipe) body: CreateDto) {
     return { contentType, receivedBody: body, test: this.testField, instanceOf: body instanceof CreateDto };
   }
 
   @Put()
   @SetHeader('X-Method', 'update')
-  public update(@Header('Content-Type') contentType: string, @Query('id') id: string, @Body() body: any) {
-    return { contentType, id, receivedBody: body, test: this.testField };
+  public update(@Req() req: NextApiRequest, @Res() res: NextApiResponse) {
+    const { headers, query, body } = req;
+    const { 'content-type': contentType } = headers;
+    const { id } = query;
+
+    res.status(200).json({ contentType, id, receivedBody: body, test: this.testField });
   }
 
   @Delete()
@@ -89,7 +104,7 @@ describe('E2E', () => {
 
   it('read', () =>
     request(server)
-      .get('/?id=my-id&step=1&redirect=true')
+      .get('/?id=my-id&step=1&redirect=true&startAt=2021-01-01T22:00:00')
       .set('Content-Type', 'application/json')
       .expect(200)
       .then(res =>
@@ -103,7 +118,21 @@ describe('E2E', () => {
             contentType: 'application/json',
             id: 'my-id',
             step: 1,
-            redirect: true
+            redirect: true,
+            isStartAtDateInstance: true
+          }
+        })
+      ));
+
+  it('read without "step"', () =>
+    request(server)
+      .get('/?id=my-id&redirect=true')
+      .set('Content-Type', 'application/json')
+      .expect(400)
+      .then(res =>
+        expect(res).toMatchObject({
+          body: {
+            message: 'step is a required parameter.'
           }
         })
       ));
@@ -205,4 +234,16 @@ describe('E2E', () => {
           }
         })
       ));
+
+  it('should throw express style 404 for an undefined http verb', () =>
+    request(server)
+      .patch('/')
+      .set('Content-Type', 'application/json')
+      .expect(404)
+      .then(res =>
+        expect(res.body).toMatchObject({
+          statusCode: 404,
+          error: 'Not Found'
+        })
+      ));
 });

lib/internals/classValidator.ts

@@ -1,9 +1,14 @@
 import type { ClassConstructor } from 'class-transformer';
 import { BadRequestException } from '../exceptions';
+import type { ValidationPipeOptions } from '../pipes';
 import { flattenValidationErrors } from './getClassValidatorError';
 import { loadPackage } from './loadPackage';
 
-export async function validateObject(cls: ClassConstructor<any>, value: Record<string, string>): Promise<any> {
+export async function validateObject(
+  cls: ClassConstructor<any>,
+  value: Record<string, string>,
+  validatorOptions?: ValidationPipeOptions
+): Promise<any> {
   const classValidator = loadPackage('class-validator');
   if (!classValidator) {
     return value;
@@ -15,10 +20,12 @@ export async function validateObject(cls: ClassConstructor<any>, value: Record<s
   }
 
   const bodyValue = classTransformer.plainToClass(cls, value, {
-    enableImplicitConversion: true
+    enableImplicitConversion: true,
+    ...validatorOptions?.transformOptions
   });
   const validationErrors = await classValidator.validate(bodyValue, {
-    enableDebugMessages: process.env.NODE_ENV === 'development'
+    enableDebugMessages: process.env.NODE_ENV === 'development',
+    ...validatorOptions
   });
 
   if (validationErrors.length) {

lib/internals/handler.ts

@@ -4,25 +4,18 @@ import type { ClassConstructor } from 'class-transformer';
 import type { NextApiRequest, NextApiResponse } from 'next';
 import { HEADER_TOKEN, HttpVerb, HTTP_CODE_TOKEN, MetaParameter, PARAMETER_TOKEN } from '../decorators';
 import { HttpException } from '../exceptions';
-import { validateObject } from './classValidator';
 import { notFound } from './notFound';
 
-async function getParameterValue(
+function getParameterValue(
   req: NextApiRequest,
   res: NextApiResponse,
-  bodyParamType: ClassConstructor<any>[],
-  { location, name, index }: MetaParameter
-): Promise<string | object | undefined> {
+  { location, name }: MetaParameter
+): string | object | undefined {
   switch (location) {
     case 'query':
       return name ? req.query[name] : req.query;
-    case 'body': {
-      if (index < bodyParamType.length && typeof bodyParamType[index] === 'function') {
-        return validateObject(bodyParamType[index], req.body);
-      }
-
+    case 'body':
       return req.body;
-    }
     case 'header':
       return name ? req.headers[name.toLowerCase()] : req.headers;
     case 'method':
@@ -58,16 +51,24 @@ export function Handler(method?: HttpVerb): MethodDecorator {
         target.constructor,
         propertyKey
       );
-      const bodyParamType: ClassConstructor<any>[] =
-        Reflect.getMetadata('design:paramtypes', target, propertyKey) ?? [];
+      const paramTypes: ClassConstructor<any>[] = Reflect.getMetadata('design:paramtypes', target, propertyKey) ?? [];
 
       try {
         const parameters = await Promise.all(
           metaParameters.map(async ({ location, name, pipes, index }) => {
-            let returnValue = await getParameterValue(req, res, bodyParamType, { location, name, index });
+            const paramType =
+              index < paramTypes.length && typeof paramTypes[index] === 'function' ? paramTypes[index] : undefined;
+
+            let returnValue = getParameterValue(req, res, { location, name, index });
 
-            if (returnValue && pipes && pipes.length) {
-              pipes.forEach(pipeFn => (returnValue = pipeFn(returnValue)));
+            if (pipes && pipes.length) {
+              for (const pipeFn of pipes) {
+                returnValue = pipeFn.name
+                  ? // Bare pipe function. i.e: `ParseNumberPipe`
+                    await pipeFn.call(null, null).call(null, returnValue, { name, metaType: paramType })
+                  : // Pipe with options. i.e: `ParseNumberPipe({ nullable: false })`
+                    await pipeFn.call(null, returnValue, { name, metaType: paramType });
+              }
             }
 
             return returnValue;
@@ -79,7 +80,7 @@ export function Handler(method?: HttpVerb): MethodDecorator {
 
         const returnValue = await originalHandler.call(this, ...parameters);
 
-        if (returnValue instanceof ServerResponse || res.headersSent) {
+        if (returnValue instanceof ServerResponse || res.writableEnded || res.finished) {
           return;
         }
 

lib/pipes/ParameterPipe.ts

@@ -1 +1,10 @@
-export type ParameterPipe<T> = (value: any) => T;
+export interface PipeMetadata<T = any> {
+  readonly metaType?: T;
+  readonly name?: string;
+}
+
+export interface PipeOptions {
+  readonly nullable?: boolean;
+}
+
+export type ParameterPipe<TOutput, TMeta = unknown> = (value: any, metadata?: PipeMetadata<TMeta>) => TOutput;

lib/pipes/index.ts

@@ -1,2 +1,4 @@
 export * from './parseBoolean.pipe';
 export * from './parseNumber.pipe';
+export * from './validation.pipe';
+export * from './validateEnum.pipe';

lib/pipes/parseBoolean.pipe.spec.ts

@@ -1,10 +1,14 @@
 import { ParseBooleanPipe } from './parseBoolean.pipe';
 
 describe('ParseBooleanPipe', () => {
-  it('Should parse the given string as boolean (true)', () => expect(ParseBooleanPipe('true')).toStrictEqual(true));
+  it('Should parse the given string as boolean (true)', () => expect(ParseBooleanPipe()('true')).toStrictEqual(true));
 
-  it('Should parse the given string as boolean (false)', () => expect(ParseBooleanPipe('false')).toStrictEqual(false));
+  it('Should parse the given string as boolean (false)', () =>
+    expect(ParseBooleanPipe()('false')).toStrictEqual(false));
+
+  it('Should throw required error the given value is empty', () =>
+    expect(() => ParseBooleanPipe({ nullable: false })('')).toThrow());
 
   it('Should throw when the given string is not a boolean string', () =>
-    expect(() => ParseBooleanPipe('test')).toThrow());
+    expect(() => ParseBooleanPipe()('test')).toThrow());
 });

lib/pipes/parseBoolean.pipe.ts

@@ -1,13 +1,21 @@
 import { BadRequestException } from '../exceptions';
+import type { ParameterPipe, PipeOptions, PipeMetadata } from './ParameterPipe';
+import { validatePipeOptions } from './validatePipeOptions';
 
-export function ParseBooleanPipe(value: any): boolean {
-  if (value === true || value === 'true') {
-    return true;
-  }
+export function ParseBooleanPipe(options?: PipeOptions): ParameterPipe<boolean> {
+  return (value: any, metadata?: PipeMetadata) => {
+    validatePipeOptions(value, metadata?.name, options);
 
-  if (value === false || value === 'false') {
-    return false;
-  }
+    if (value === true || value === 'true') {
+      return true;
+    }
 
-  throw new BadRequestException('Validation failed (boolean string is expected)');
+    if (value === false || value === 'false') {
+      return false;
+    }
+
+    throw new BadRequestException(
+      `Validation failed${metadata?.name ? ` for ${metadata.name}` : ''} (boolean string is expected)`
+    );
+  };
 }