Whitelist and transform options in NestJS - Step-by-Step Execution

Concept Flow - Whitelist and transform options

Receive incoming request data

↓

Apply ValidationPipe with options

↓

Whitelist enabled?

↓

Remove extra props

↓

Pass validated and transformed data to handler

↓

Response

Incoming data is checked by ValidationPipe; if whitelist is on, extra properties are removed; if transform is on, data types convert to expected classes before reaching the handler.

Execution Sample

NestJS

app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));

@Post()
create(@Body() dto: CreateUserDto) {
  return dto;
}

This code sets up a global validation pipe that removes extra properties and converts input to CreateUserDto instance.

Execution Table

Step	Incoming Data	Whitelist Action	Transform Action	Resulting Data
1	{"name":"Alice","age":"25","extra":"remove me"}	Remove 'extra' property	Convert 'age' from string '25' to number 25	{"name":"Alice","age":25}
2	{"name":"Bob","age":30}	No extra properties to remove	No type conversion needed (age already number)	{"name":"Bob","age":30}
3	{"name":"Eve","age":"not a number"}	No extra properties to remove	Conversion fails, validation error thrown	Error: Validation failed
4	{"name":"Mallory","age":40,"admin":true}	Remove 'admin' property	No type conversion needed	{"name":"Mallory","age":40}
Exit	N/A	Processing stops on validation error	N/A	Request rejected if validation fails

💡 Execution stops if validation fails or after data is cleaned and transformed.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	Final
requestBody	N/A	{"name":"Alice","age":"25","extra":"remove me"}	{"name":"Bob","age":30}	{"name":"Eve","age":"not a number"}	{"name":"Mallory","age":40,"admin":true}	N/A
whitelistedData	N/A	{"name":"Alice","age":"25"}	{"name":"Bob","age":30}	{"name":"Eve","age":"not a number"}	{"name":"Mallory","age":40}	N/A
transformedData	N/A	{"name":"Alice","age":25}	{"name":"Bob","age":30}	Validation error	{"name":"Mallory","age":40}	N/A

Key Moments - 3 Insights

Why does the 'extra' property disappear from the data after validation?

Because whitelist: true removes any properties not defined in the DTO, as shown in execution_table step 1 and 4.

What happens if a property cannot be converted to the expected type during transform?

Validation fails and an error is thrown, stopping execution as shown in execution_table step 3.

Does transform convert data only if whitelist is enabled?

No, transform works independently; whitelist removes extra props, transform converts types, both can be enabled together as in the example.

Visual Quiz - 3 Questions

Look at the execution_table at step 1, what is the type of 'age' after transformation?

A string

B number

C boolean

D undefined

💡 Hint

Check the 'Transform Action' and 'Resulting Data' columns at step 1.

At which step does the validation pipe reject the request due to a conversion error?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Look for 'Validation error thrown' in the 'Transform Action' column.

If whitelist was set to false, what would happen to the 'extra' property in step 1?

A It would remain in the data passed to the handler

B It would cause a validation error

C It would be removed anyway

D It would be converted to a number

💡 Hint

Whitelist controls removal of extra properties; see execution_table step 1 for effect.

Concept Snapshot

ValidationPipe options:
- whitelist: true removes properties not in DTO
- transform: true converts input to DTO instances
Use together to clean and convert incoming data
Validation errors stop request processing
Configured globally or per-route

Full Transcript

In NestJS, the ValidationPipe can be configured with whitelist and transform options. When whitelist is true, any properties not defined in the DTO class are removed from the incoming data. When transform is true, the incoming plain data is converted into instances of the DTO class, including type conversions like string to number. This process happens before the controller method receives the data. If validation or transformation fails, the request is rejected with an error. This ensures the controller only works with clean, correctly typed data. The execution table shows examples of data before and after these steps, including when extra properties are removed and when type conversion succeeds or fails.

Practice

1. What does the whitelist option do when enabled in NestJS validation pipe?

easy

A. It disables validation for unknown properties.

B. It removes any properties not defined in the DTO from the input data.

C. It transforms input data types to match the DTO automatically.

D. It logs all incoming requests for debugging.

Solution

1. Step 1: Understand the whitelist option purpose

   The whitelist option removes any properties from the input that are not explicitly defined in the DTO (Data Transfer Object).

2. Step 2: Compare with other options

   Transform changes types, logging is unrelated, and disabling validation is not whitelist's role.

3. Final Answer:

   It removes any properties not defined in the DTO from the input data. -> Option B

4. Quick Check:

   Whitelist = remove extra fields [OK]

Hint: Whitelist = remove unwanted fields from input [OK]

Common Mistakes:

• Confusing whitelist with transform option
• Thinking whitelist disables validation
• Assuming whitelist logs data

2. Which is the correct way to enable both whitelist and transform options in a global validation pipe in NestJS?

easy

A. app.useGlobalPipes(new ValidationPipe({ whitelist: false, transform: true }));

B. app.useGlobalPipes(new ValidationPipe(whitelist: true, transform: true));

C. app.useGlobalPipes(new ValidationPipe({ whitelist: 'true', transform: 'true' }));

D. app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));

Solution

1. Step 1: Check the syntax for ValidationPipe options

   Options must be passed as an object with keys and boolean values inside curly braces.

2. Step 2: Validate option values

   Both whitelist and transform must be boolean true, not strings or missing braces.

3. Final Answer:

   app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true })); -> Option D

4. Quick Check:

   Correct object syntax with booleans [OK]

Hint: Use object with booleans inside braces for options [OK]

Common Mistakes:

• Missing curly braces around options
• Using strings instead of booleans
• Setting whitelist to false by mistake

3. Given this DTO and input, what will be the output after validation with whitelist: true and transform: true?

class UserDto {
  name: string;
  age: number;
}

const input = { name: 'Alice', age: '30', extra: 'remove me' };

medium

A. { name: 'Alice', age: 30 }

B. { name: 'Alice', age: '30', extra: 'remove me' }

C. { name: 'Alice', age: 30, extra: 'remove me' }

D. Validation error due to extra property

Solution

1. Step 1: Apply whitelist option

   The extra property 'extra' is removed because whitelist is true.

2. Step 2: Apply transform option

   The age string '30' is converted to number 30 as per DTO type.

3. Final Answer:

   { name: 'Alice', age: 30 } -> Option A

4. Quick Check:

   Whitelist removes extra, transform converts types [OK]

Hint: Whitelist removes extras; transform converts types [OK]

Common Mistakes:

• Expecting extra fields to remain
• Not realizing transform converts string to number
• Thinking validation fails on extra fields with whitelist

4. You set whitelist: true but forgot transform: true in your ValidationPipe. What issue might you face when receiving input with number fields as strings?

medium

A. Input number fields remain strings, causing type errors later.

B. Extra fields are not removed from input.

C. ValidationPipe throws a syntax error.

D. Input is automatically converted to correct types.

Solution

1. Step 1: Understand whitelist without transform

   Whitelist removes extra fields but does not convert types.

2. Step 2: Consequence of missing transform

   Number fields sent as strings remain strings, which can cause errors in code expecting numbers.

3. Final Answer:

   Input number fields remain strings, causing type errors later. -> Option A

4. Quick Check:

   Missing transform = no type conversion [OK]

Hint: Whitelist only removes fields; transform converts types [OK]

Common Mistakes:

• Assuming whitelist converts types
• Expecting syntax errors from missing transform
• Thinking extra fields remain with whitelist true

5. You want to accept a nested object in your DTO and ensure unwanted fields are removed and types are converted. Which ValidationPipe options setup correctly handles nested objects with whitelist and transform?

hard

A. new ValidationPipe({ whitelist: true, transform: true, forbidNonWhitelisted: true })

B. new ValidationPipe({ whitelist: false, transform: true, transformOptions: { enableImplicitConversion: false } })

C. new ValidationPipe({ whitelist: true, transform: true, transformOptions: { enableImplicitConversion: true } })

D. new ValidationPipe({ whitelist: true, transform: false, forbidNonWhitelisted: true })

Solution

1. Step 1: Recognize nested object handling needs transform options

   For nested objects, enabling implicit conversion helps transform nested types correctly.

2. Step 2: Check options for whitelist and transform

   Whitelist true removes unwanted fields; transform true with transformOptions enables nested conversion.

3. Step 3: Compare other options

   Options with forbidNonWhitelisted: true throw errors on extras instead of removing; others disable whitelist or transform or lack transformOptions.

4. Final Answer:

   new ValidationPipe({ whitelist: true, transform: true, transformOptions: { enableImplicitConversion: true } }) -> Option C

5. Quick Check:

   whitelist + transform + enableImplicitConversion [OK]

Hint: Use transformOptions with enableImplicitConversion for nested objects [OK]

Common Mistakes:

• Ignoring transformOptions for nested conversion
• Disabling transform but expecting type conversion
• Not using whitelist to remove extra nested fields