📒Middlewares

✔️checkSchema()

checkSchema(schema: Schema, defaultLocations?: Location[]): ValidationChain[] & ContextRunner

주어진 schema를 바탕으로 하는 validation chains의 리스트를 생성하고 express.js의 라우트에서 미들웨어로서 사용할 수 있다.

기본적으로 요청 객체의 모든 locations(body, cookies, headers, params, query)에 있는 필드들이 검증된다.

하지만 위에 소개된 locations들 목록은 defaultLocations 파라미터에 특정 location들을 명시한 배열을 인수로 넘겨서 변경할 수 있다.

checkSchema(schema, ['body', 'query']);

각 검증될 필드의 location을 세부 조정하고 싶다면, in 프로퍼티를 설정할 수 있다. in 프로퍼티는 defaultLocations 매개변수보다 더 높은 우선순위를 가진다.

📌Manually running checkSchema()

checkSchema()는 미들웨어를

📒ValidationChain

validation chain은 빌트인 검증자, sanitizers, 유틸리티 메서드를 포함하여 특정 필드에 대한 검증 동작을 조정할 수 있다.

validation chains는 check() 함수에 의해 만들어지며 다음과 같은 사용 예로 사용할 수 있다.

• express.js 라우트의 미들웨어로 사용할 수 있다.
• express-validator의 함수(oneOf() or checkExact() 등)의 매개변수로 사용할 수 있다.
• 독립 실행 형태로 검증이 실행되는 시기와 방법을 완전히 제어할 수 있다.

✔️Built-in validators

📌.custom()

custom(validator: (value, { req, location, path }) => any): ValidationChain

커스텀 검증자 함수를 체인에 추가한다.

필드 값은 다음과 같은 경우에 유효 값으로 판정된다.

• 커스텀 검증자가 truthy 값을 반환할 때
• 커스텀 검증자가 resolve된 프로미스를 반환할 때

만약 커스텀 생성자가 falsy값을 반환하거나, rejects된 프로미스를 반환하거나, 에러를 반환한다면, 해당 필드 값은 유효한 값이 아니라고 판정된다.

📌.exsits()

exists(options?: {
  values?: 'undefined' | 'null' | 'falsy',
  checkNull?: boolean,
  checkFalsy?: boolean
}): ValidationChain

필드가 존재하는지 확인하는 검증기를 추가한다.

options.values에 명시된 값에 따라 필드가 존재하는지 존재하지 않는지 여부가 결정되며, 기본값은 undefined다.

options.values	Behavior
undefined	필드 값이 undefined라면 필드가 존재하지 않는 것으로 간주한다.
null	필드 값이 undefined 혹은 null이라면 필드가 존재하지 않는 것으로 간주한다.
falsy	필드 값이 falsy 값이라면('',0,false,null,undefined) 필드가 존재하지 않는 것으로 간주한다.

options.checkNull과 options.checkFalsy는 deprecated 옵션이다. options.values로 null, falsy를 사용하라.

🚨.exists()는 다른 검증기나 sanitizers를 추가하지 않는 경우에만 필요하다.

📌.isArray()

isArray(options?: { min?: number; max?: number }): ValidationChain

필드 값이 배열인지 확인하는 검증기를 추가한다. 자바스크립트의 Array.isArray() 함수와 유사하다.

옵션으로 options.min, options.max를 추가하여 허용 배열 길이를 제한할 수 있다.

// Verifies that the friends list is an array
body('friends').isArray();

// Verifies that ingredients is an array with length >= 0
body('ingredients').isArray({ min: 0 });

// Verifies that team_members is an array with length >= 0 and <= 10
check('team_members').isArray({ min: 0, max: 10 });

📌.isObject()

isObject(options?: { strict?: boolean }): ValidationChain

필드 값이 객체인지 확인하는 검증기를 추가한다. 예를 들어 {}, { foo: 'bar'}, new MyCustomClass()는 이 검증기를 통과한다.

strict 옵션을 false로 설정하면 pure Javascript의

typeof value === 'object'(javascript에서 배열과 null을 typeof 연산자를 사용하여 타입을 확인하면 object로 나온다.)와 동일하게 작동한다.

📌.isString(), .notEmpty()

isString(): ValidationChain

pure Javascript의 typeof value === 'string'과 동일하게 동작한다.

notEmpty(): ValidationChain

빈 문자열이 아닌지 확인하는 검증기를 추가한다. .not().isEmpty()와 동일하게 동작한다.

그 외 standard vaildators

Standard validators 확인
guide Standard validators/sanitizers 확인

✔️Built-in sanitizers(정제기)

📌.customSanitizer()

customSanitizer(sanitizer: (value, { req, location, path }) => any): ValidationChain

커스텀 정제기 함수를 체인에 추가한다. 정제기를 거쳐 필드 값이 변경된다.

app.post('/object/:id', param('id').customSanitizer((value, { req }) => {
  // In this app, users have MongoDB style object IDs, everything else, numbers
  return req.query.type === 'user' ? ObjectId(value) : Number(value);
})), (req, res) => {
  // Handle request
});

📌.default()

default(defaultValue: any): ValidationChain

필드 값이 빈 문자열, null, undefined, NaN 일 경우 defaultValue로 변경한다.

app.post('/', body('username').default('foo'), (req, res, next) => {
  // 'bar'     => 'bar'
  // ''        => 'foo'
  // undefined => 'foo'
  // null      => 'foo'
  // NaN       => 'foo'
});

📌.toArray()

toArray(): ValidationChain

배열로 변경한다. 이미 배열이면 아무것도 하지 않는다. undefined 값이라면 빈 배열이 된다.

📌.toLowerCase(), .toUpperCase()

toLowerCase(): ValidationChain

toUpperCase(): ValidationChain

문자열을 소문자로 혹은 대문자로 변경한다. 필드값이 문자열이 아니라면 아무것도 하지 않는다.

📌그 외 Standard sanitizers

Standard sanitizers 확인
guide Standard validators/sanitizers 확인

✔️Modifiers

📌.bail()

bail(options?: { level: 'chain' | 'request' }): ValidationChain

파라미터 options.level의 기본값은 chain이다.

request로 설정하면 이전 검증기 중 하나라도 실패한 경우 validation chain 실행이 멈춘다.

실패 시 .bail({level:'request'}) 이후의 검증기는 실행되지 않기 때문에 이 뒤의 데이터베이스나 외부 API를 사용하는 커스텀 검증기가 실행되는 것을 방지할 때 유용하다.

.bail()은 같은 validation 체인에서 여러번 사용할 수 있다.

body('username')
  .isEmail()
  // If not an email, stop here
  .bail()
  .custom(checkDenylistDomain)
  // If domain is not allowed, don't go check if it already exists
  .bail()
  .custom(checkEmailExists);

app.get(
  '/search',
  query('query').notEmpty().bail({ level: 'request' }),
  // If `query` is empty, then the following validation chains won't run:
  query('query_type').isIn(['user', 'posts']),
  query('num_results').isInt(),
  (req, res) => {
    // Handle request
  },
);

🚨oneOf()와 checkExact()를 사용할 때 request-level bail을 사용할 경우, 병렬로 실행되던 validation chains가 순차적으로 실행되어야 해서 실행이 느려질 수 있다.

📌if()

if(condition: CustomValidator | ContextRunner): ValidationChain

이 필드에 대해 validation chain이 계속 실행되어야 하는지 아닌지 조건을 추가한다.

조건은 커스텀 검증기 혹은 contextRunner 인스턴스일 수 있다.

body('newPassword')
  // Only validate if the old password has been provided
  .if((value, { req }) => req.body.oldPassword)
  // Or, use a validation chain instead
  .if(body('oldPassword').notEmpty())
  // The length of the new password will only be checked if `oldPassword` is provided.
  .isLength({ min: 6 });

📌.not()

not(): ValidationChain

체인 내에 있는 다음 검증기의 결과를 부정한다.

check('weekday').not().isIn(['sunday', 'saturday']);

📌.optional()

optional(options?: boolean | {
  values?: 'undefined' | 'null' | 'falsy',
  nullable?: boolean,
  checkFalsy?: boolean,
}): ValidationChain

현재 validation chain을 선택사항으로 표시한다.

optional 필드는 value에 따라 검증을 건너뛴다.

어떤 값이 optinal로 간주되는지는 options.values에 따라 다르다. 기본적으로 undefined로 설정된다.

options.values	behavior
undefined	필드 값이 undefined 라면 optional로 간주된다.
null	필드 값이 undefined나 null이면 optional로 간주된다.
falsy	필드 값이 falsy 값(빈 문자열 0, false, null, undefined)이면 optionaly로 간주된다.

nullable, checkFalsy는 deprecated다. options.values를 null혹은 falsy로 설정해서 사용하라

🚨vaildator와 nasitizer와 달리 .optional()은 위치에 상관없이 값이 해석되는 방식에 영향을 준다. 즉, 체인 어디에서 발생하더라도 영향을 준다.

body('json_string').isLength({ max: 100 }).isJSON().optional().

body('json_string').optional().isLength({ max: 100 }).isJSON().

둘의 차이는 없다.

📌.withMessage()

withMessage(message: any): ValidationChain

이전 검증기에 의해 사용될 에러 메시지를 설정한다.

📒ExpressValidator

import { ExpressValidator } from 'express-validator';
new ExpressValidator(
  customValidators?: Record<string, CustomValidator>,
  customSanitizers?: Record<string, CustomSanitizer>,
  options?: {
    errorFormatter: ErrorFormatter<E>;
  }
);

ExpressValidator는 express-validator API를 래핑한 클래스다.

그리고 다음과 같은 차이점이 있다.

1. 검증 체인에서 항상 사용 가능한 커스텀 검증기/정제기를 지정할 수 있다.
2. 일부 함수에 기본적으로 적용되는 옵션을 지정할 수 있다.

사용자 정의 검증기 및 정제기" 가이드를 참고

.errorFormatter가 설정된 경우, .validationResult()에 사용되는 기본 오류 포매터로 사용된다.

나중에 번역

📒MatchedData()

✔️matchedData()

import { matchedData } from 'express-validator';
matchedData(req, options?: {
  includeOptionals?: boolean,
  onlyValidData?: boolean,
  locations?: Location[],
})

express-validator로 검증 및 정제된 데이터를 추출하고, 그 데이터가 있는 객체를 반환한다.

app.post(
  '/contact-us',
  [body('email').isEmail(), body('message').notEmpty(), body('phone').optional().isMobilePhone()],
  (req, res) => {
    const result = validationResult(req);
    if (!result.isEmpty()) {
      // handle validation errors
      return res.send('Please fix the request');
    }

    const data = matchedData(req);
    // If phone isn't set:
    // => { email: 'foo@bar.com', message: 'Hi hello' }
    // If phone is set:
    // => { email: 'foo@bar.com', message: 'Hi hello', phone: '+1223334444' }
  },
);

📌With optional data

기본적으로 matchedData는 optional이거나 request에 포함되지 않은 데이터는 반환 객체에 담지 않는다.

이 동작을 변경하려면 options.includeOptionals을 true로 설정한다.

app.post(
  '/contact-us',
  [body('email').isEmail(), body('message').notEmpty(), body('phone').optional().isMobilePhone()],
  (req, res) => {
    const data = matchedData(req, { includeOptionals: true });
    // If phone isn't set:
    // => { email: 'foo@bar.com', message: 'Hi hello', phone: undefined }
  },
);

📌With invalid data

기본적으로 matchedData는 유효한 데이터만 반환한다. 요청에 유효하지 않은 데이터가 있으면 반환 객체에 담지 않는다.

이 동작을 변경하려변 options.onlyValidData를 false로 설정한다.

app.post('/signup', body('email').isEmail(), body('password').notEmpty(), (req, res) => {
  const data = matchedData(req, { onlyValidData: false });
  // => { email: 'not_actually_an_email', password: '' }
});

📌Selecting data from specific locations

기본적으로 matchedData는 검증을 통과한 request의 모든 locations의 데이터를 결과 객체에 담아 반환한다.

이 동작을 수정하려면 options.locations를 수정한다. options.locations를 리스트로 설정하고 해당 locations에 속한 데이터만 결과 객체에 담도록 할 수 있다.

app.post(
  '/signup',
  [body('email').isEmail(), body('password').notEmpty(), query('subscribe_newsletter').isBoolean()],
  (req, res) => {
    const data = matchedData(req);
    // => { email: 'foo@bar.com', password: '12345', subscribe_newsletter: true }

    const data2 = matchedData(req, { locations: ['query'] });
    // => { subscribe_newsletter: true }
  },
);

📒Errors and Validation Results

요청이 유효한지, 발생 가능한 검증 에러는 무엇인지 살펴보자.

✔️validationResult()

validationResult(req: Request): Result<ValidationError>

request로부터 검증 결과를 추출한다. 검증 후에는 Result 객체로 검증 결과 데이터를 래핑한다.

const { query, validationResult } = require('express-validator');

app.post('/hello', query('person').notEmpty(), (req, res) => {
  const result = validationResult(req);
  // Use `result` to figure out if the request is valid or not
});

📌withDefaults()

validationResult.withDefaults<T>(options: { formatter?: ErrorFormatter<T> }): ResultFactory<T>

validationResult()와 유사한 새로운 함수를 생성한다.

생성된 함수는 주어진 옵션을 반환된 Result 객체의 기본값으로 사용한다.

예를 들어, 결과의 기본 오류 포맷터를 다음과 같이 설정할 수 있다.

const { query, validationResult } = require('express-validator');
const myValidationResult = validationResult.withDefaults({
  formatter: error => error.msg,
});

app.post('/hello', query('person').notEmpty(), (req, res) => {
  const errors = myValidationResult(req).array();
  // => ['Invalid value']
});

✔️ResultFactory<T>

✔️Result<T>

결과 객체는 요청의 상태를 둘러싼 래퍼다. 결과 객체는 요청이 유효한지 판단할 수 있는 몇 가지 메서드를 제공한다.

🚨타입 매개 변수 T는 .array() 및 .mapped()와 같은 메서드에서 반환되는 오류의 타입을 나타낸다. 기본적으로 ValidationError이며, .formatWith()를 사용해서 변경할 수 있다.

📌.isEmpty()

isEmpty(): boolean

request가 검증 에러를 포함하는지 아닌지를 반환한다.

📌.formatWith()

formatWith<T>(formatter: ErrorFormatter<T>): Result<T>

검증 상태를 다시 둘러싼 새로운 Result 객체를 반환한다. 새로운 Result 객체는 주어진 formatter를 에러 포매터로 사용한다.

const { query, validationResult } = require('express-validator');

app.post('/hello', query('person').notEmpty(), (req, res) => {
  const result = validationResult(req);
  const errors = result.array();
  // => [{ msg: 'Invalid value', ... }]

  const result2 = result.formatWith(error => error.msg);
  const errors2 = result2.array();
  // => ['Invalid value']
});

📌.array()

array(options?: { onlyFirstError?: boolean }): T[]

검증된 모든 필드로부터 발생된 모든 에러를 리스트로 만들어 반환한다.

const result = validationResult(req).array();
// => [{ msg: 'Invalid value', path: 'field1' }, { msg: 'Invalid value', path: 'field1' }]

options.onlyFirstError가 true로 세팅되면 각 필드의 첫 번째 에러만 반환한다.

const result = validationResult(req).array({ onlyFirstError: true });
// => [{ msg: 'Invalid value', path: 'field1' }]

📌.mapped()

mapped(): Record<string, T>

필드와 발생한 에러를 매핑한 객체를 반환한다. 필드로부터 발생한 에러가 여러 개라면 첫 번째 에러만 반환한다.

const result = validationResult(req).mapped();
// => { field1: { msg: 'Invalid value', ... }, field2: { msg: 'Invalid value', ... } }

📌.throw()

throw(): void

결과 객체가 에러를 가지고 있다면, 이 메서드는 Result 타입과 동일한 메소드로 장식된 오류를 발생시킵니다.(this method throws an error decorated with the same methods as the Result type.)

만약 결과 객체에 에러가 없다면 이 메서드는 아무것도 하지 않는다.

app.post('/hello', query('person').notEmpty(), (req, res) => {
  try {
    validationResult(req).throw();
    res.send(`Hello, ${req.query.person}!`);
  } catch (e) {
    res.status(400).send({ errors: e.mapped() });
  }
});

✔️Error types

express-validator의 다양한 API는 서로 다른 종류의 검증 오류를 발생시킨다.

📌FieldValidationError

type FieldValidationError = {
  type: 'field';
  location: Location;
  path: string;
  value: any;
  msg: any;
};

단일 필드 검증시 발생하는 오류를 나타낸다.

📌AlternativeValidationError

type AlternativeValidationError = {
  type: 'alternative';
  msg: any;
  nestedErrors: FieldValidationError[];
};

사용할 수 있는 모든 검증 작업(ex. in oneOf())에서 실패했을 때 발생하는 오류를 나타낸다. nestedErrors에는 개별 필드 오류의 flat list가 포함된다.

📌GroupedAlternativeValidationError

모든 대체 방법(ex. in oneOf())이 유효하지 않았을 때 발생하는 오류를 나타냅니다. nestedErrors에는 대체 방법별로 그룹화된 개별 필드 오류 목록이 포함됩니다.

📌UnknownFieldValidationError

type UnknownFieldsError = {
  type: 'unknown_fields';
  msg: any;
  fields: { path: string; location: Location; value: any }[];
};

하나 이상의 필드가 unknown 필드일 때 발생하는 에러를 나타낸다.

즉, checkExact()가 실행될 때 검증 체인이 없는 경우이다.

fields에는 모든 unknown 필드들의 경로와 locations, values 들어있는 리스트들 반환한다.

📌ValidationError

어떠한 검증 오류든 발생할 수 있다. type 속성을 살펴보면 실제로 발생한 오류가 무엇인지 확인할 수 있다.

switch (error.type) {
  case 'field':
    // `error` is a `FieldValidationError`
    console.log(error.path, error.location, error.value);
    break;

  case 'alternative':
    // `error` is an `AlternativeValidationError`
    console.log(error.nestedErrors);
    break;

  case 'alternative_grouped':
    // `error` is a `GroupedAlternativeValidationError`
    error.nestedErrors.forEach((nestedErrors, i) => {
      console.log(`Errors from chain ${i}:`);
      console.log(nestedErrors);
    });
    break;

  case 'unknown_fields':
    // `error` is an `UnknownFieldsError`
    console.log(error.fields);
    break;

  default:
    // Error is not any of the known types! Do something else.
    throw new Error(`Unknown error type ${error.type}`);
}

✔️ErrorFormatter<T>

type ErrorFormatter<T> = (error: ValidationError) => T;

Result#mapped() 및 Result#array()와 같은 메소드에서 반환된 오류를 포맷하는 데 사용되는 함수다.

이 함수는 포맷되지 않은 오류를 사용하고 새로운 값을 반환해야 한다.