perfect-payload 1.5.0-beta.1 → 1.7.0-beta.0

package/README.md

@@ -1,22 +1,48 @@
 # perfect-payload
 
-A lightweight JavaScript payload validation utility for validating API
-and JSON payloads with simple rule-based configuration.
-
-`perfect-payload` supports structured validation errors, nested field
-paths, synchronous custom validators, synchronous payload
-transformation/sanitization, array size constraints, and deeply nested
-array/object validation while keeping the validation schema simple.
+A lightweight JavaScript payload validation and transformation utility
+for API and JSON payloads.
+
+`perfect-payload` provides structured validation errors, exact nested
+field paths, synchronous and asynchronous custom validation, synchronous
+transformation/sanitization, array constraints, and deeply nested
+object/array validation while keeping schemas simple and the package
+lightweight.
+
+## Highlights
+
+- Lightweight, rule-based payload validation
+- Structured errors with stable machine-readable codes
+- Exact nested paths such as `profile.email` and
+  `products[1].quantity`
+- Recursive `objectAttr` and `elementConstraints` validation
+- `minItems` and `maxItems` array constraints
+- Built-in `trim`, `lowercase`, and `uppercase` sanitization
+- Custom synchronous `transform(value, payload)`
+- Custom synchronous validators with `perfectPayload()`
+- Custom synchronous or asynchronous validators with
+  `perfectPayloadAsync()`
+- Transformed values returned through `validatedPayload`
+- Original input payload is not mutated
+- Configurable unknown-field handling: `strip`, `allow`, or `reject`
+- Clean three-argument API with validation options in one object
+- Legacy `perfectPayloadV1()` retained during the migration period
 
 ## Quick Links
 
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
+- [Public API](#public-api)
+- [Unknown Field Handling](#unknown-field-handling)
+- [Synchronous vs Asynchronous
+  Validation](#synchronous-vs-asynchronous-validation)
 - [Validation Rules](#validation-rules)
-- [Array Size and Nested Validation](#array-size-and-nested-validation)
+- [Array Size and Nested
+  Validation](#array-size-and-nested-validation)
 - [Transformations and
   Sanitization](#transformations-and-sanitization)
 - [Custom Validators](#customvalidator)
+- [Asynchronous Validation](#asynchronous-validation)
 - [Error Codes](#error-codes)
 - [Custom Error Messages](#custom-error-messages)
 - [Nested Objects and Array Field
@@ -24,6 +50,31 @@ array/object validation while keeping the validation schema simple.
 - [Examples and Usage](#examples-and-usage)
 - [Legacy API](#legacy-api)
 
+## What's New in v1.7.0
+
+v1.7.0 introduces two API-level improvements:
+
+1.  `unknownFields` gives explicit control over fields that are not
+    declared in the validation schema: `"strip"`, `"allow"`, or
+    `"reject"`.
+2.  `perfectPayload()` and `perfectPayloadAsync()` now use a clean
+    three-argument API where custom response objects and other API
+    options live inside one `options` object.
+
+```js
+const result = perfectPayload(payload, rules, {
+  unknownFields: "reject",
+  inValidPayloadResponse: {
+    statusCode: 422,
+    valid: false,
+    message: "Payload validation failed",
+  },
+});
+```
+
+The default `unknownFields` mode is `"strip"`, preserving the previous
+validated-payload filtering behavior when no option is supplied.
+
 ## Installation
 
 ```bash
@@ -79,29 +130,28 @@ console.log(result);
 
 {
 
-  statusCode: 200,
+  statusCode: 200,
 
-  valid: true,
+  valid: true,
 
-  validatedPayload: {
+  validatedPayload: {
 
-    name: "Kiran",
+    name: "Kiran",
 
-    email: "kiran@example.com",
+    email: "kiran@example.com",
 
-    age: 29
+    age: 29
 
-  }
+  }
 
 }
 ```
 
-Note: The validatedPayload contains only the fields
-defined in the
-
-schema, automatically filtering out any extra attributes. You can use it
+By default, `validatedPayload` contains only fields defined in the
+validation schema. Extra payload fields are stripped unless
+`unknownFields` is explicitly configured as `"allow"` or `"reject"`.
 
-to safely overwrite request.body or assign it to a new request property
+The original input payload is not mutated.
 
 (such as validatedBody, sanitisedData or parsedBody).
 
@@ -111,25 +161,25 @@ to safely overwrite request.body or assign it to a new request property
 
 {
 
-  statusCode: 400,
+  statusCode: 400,
 
-  valid: false,
+  valid: false,
 
-  message: "One or more attribute values are invalid",
+  message: "One or more attribute values are invalid",
 
-  errors: [
+  errors: [
 
-    {
+    {
 
-      path: "email",
+      path: "email",
 
-      code: "INVALID_EMAIL",
+      code: "INVALID_EMAIL",
 
-      message: "Invalid email format for attribute email"
+      message: "Invalid email format for attribute email"
 
-    }
+    }
 
-  ]
+  ]
 
 }
 ```
@@ -140,11 +190,11 @@ Each error returned by `perfectPayload()` contains:
 
 {
 
-  path: "field.path",
+  path: "field.path",
 
-  code: "ERROR_CODE",
+  code: "ERROR_CODE",
 
-  message: "Human readable validation message"
+  message: "Human readable validation message"
 
 }
 ```
@@ -159,6 +209,424 @@ failure.
 
 \- Submitted payload values are not included in default error messages.
 
+## Public API
+
+For new implementations, both supported APIs use the same clean
+three-argument signature:
+
+```js
+perfectPayload(data, validationRules, options?)
+await perfectPayloadAsync(data, validationRules, options?)
+```
+
+The arguments are:
+
+---
+
+Argument Required Description
+
+---
+
+`data` No Payload/object to
+validate. Defaults to
+`{}`.
+
+`validationRules` No Validation schema.
+Defaults to `{}`.
+
+`options` No API-level configuration
+such as unknown-field
+handling and custom
+response objects.
+
+---
+
+The third argument is a single options object. You no longer need to
+pass separate positional arguments for custom valid and invalid
+responses.
+
+### Options
+
+```js
+{
+  unknownFields: "strip" | "allow" | "reject",
+
+  validPayloadResponse: {
+    statusCode: 200,
+    valid: true,
+  },
+
+  inValidPayloadResponse: {
+    statusCode: 400,
+    valid: false,
+    message: "One or more attribute values are invalid",
+  },
+}
+```
+
+All properties are optional.
+
+The defaults are equivalent to:
+
+```js
+{
+  unknownFields: "strip",
+
+  validPayloadResponse: {
+    statusCode: 200,
+    valid: true,
+  },
+
+  inValidPayloadResponse: {
+    statusCode: 400,
+    valid: false,
+    message: "One or more attribute values are invalid",
+  },
+}
+```
+
+Example:
+
+```js
+const result = perfectPayload(payload, validationRules, {
+  unknownFields: "reject",
+
+  validPayloadResponse: {
+    statusCode: 201,
+    valid: true,
+    message: "Payload accepted",
+  },
+
+  inValidPayloadResponse: {
+    statusCode: 422,
+    valid: false,
+    message: "Payload validation failed",
+  },
+});
+```
+
+The same options object is supported by `perfectPayloadAsync()`:
+
+```js
+const result = await perfectPayloadAsync(payload, validationRules, {
+  unknownFields: "reject",
+  inValidPayloadResponse: {
+    statusCode: 422,
+    valid: false,
+    message: "Payload validation failed",
+  },
+});
+```
+
+## Unknown Field Handling
+
+`unknownFields` controls what happens when the input payload contains a
+field that is not defined in the validation schema.
+
+Supported values:
+
+---
+
+Value Behavior
+
+---
+
+`"strip"` Removes unknown fields from
+`validatedPayload`. This is the
+default and preserves the existing
+behavior.
+
+`"allow"` Preserves unknown fields in
+`validatedPayload`.
+
+`"reject"` Rejects unknown fields with
+structured `UNKNOWN_FIELD`
+validation errors.
+
+---
+
+### `strip` --- default
+
+```js
+const payload = {
+  name: "Kiran",
+  role: "developer",
+};
+
+const rules = {
+  name: {
+    type: "string",
+  },
+};
+
+const result = perfectPayload(payload, rules);
+```
+
+Result:
+
+```js
+{
+  statusCode: 200,
+  valid: true,
+  validatedPayload: {
+    name: "Kiran"
+  }
+}
+```
+
+`role` is not part of the schema, so it is removed from
+`validatedPayload`.
+
+You can also set the default behavior explicitly:
+
+```js
+perfectPayload(payload, rules, {
+  unknownFields: "strip",
+});
+```
+
+### `allow` --- preserve unknown fields
+
+```js
+const result = perfectPayload(payload, rules, {
+  unknownFields: "allow",
+});
+```
+
+Result:
+
+```js
+{
+  statusCode: 200,
+  valid: true,
+  validatedPayload: {
+    name: "Kiran",
+    role: "developer"
+  }
+}
+```
+
+Schema-defined fields are still validated normally. Unknown fields are
+simply preserved.
+
+### `reject` --- reject unknown fields
+
+```js
+const result = perfectPayload(payload, rules, {
+  unknownFields: "reject",
+});
+```
+
+Result:
+
+```js
+{
+  statusCode: 400,
+  valid: false,
+  message: "One or more attribute values are invalid",
+  errors: [
+    {
+      path: "role",
+      code: "UNKNOWN_FIELD",
+      message: "Unknown field role is not allowed"
+    }
+  ]
+}
+```
+
+Unknown-field errors use the same structured error format as all other
+validation errors.
+
+### Nested objects
+
+Unknown-field handling is recursive for schemas using `objectAttr`.
+
+```js
+const payload = {
+  profile: {
+    city: "Bengaluru",
+    role: "developer",
+  },
+};
+
+const rules = {
+  profile: {
+    type: "object",
+    objectAttr: {
+      city: {
+        type: "string",
+      },
+    },
+  },
+};
+
+const result = perfectPayload(payload, rules, {
+  unknownFields: "reject",
+});
+```
+
+Returns:
+
+```js
+{
+  statusCode: 400,
+  valid: false,
+  message: "One or more attribute values are invalid",
+  errors: [
+    {
+      path: "profile.role",
+      code: "UNKNOWN_FIELD",
+      message: "Unknown field profile.role is not allowed"
+    }
+  ]
+}
+```
+
+### Arrays and deep paths
+
+`unknownFields` also applies recursively through `elementConstraints`.
+
+For an unknown field inside an array element, the error path includes
+the array index:
+
+```js
+{
+  path: "products[0].internalId",
+  code: "UNKNOWN_FIELD",
+  message: "Unknown field products[0].internalId is not allowed"
+}
+```
+
+This continues through deeply nested combinations of objects and arrays,
+for example:
+
+```text
+profile.teams[0].members[0].role
+```
+
+### Normal validation errors and unknown fields
+
+With `"reject"`, unknown-field errors can be returned together with
+normal validation errors.
+
+For example, an invalid email plus two unknown fields can produce:
+
+```js
+{
+  statusCode: 400,
+  valid: false,
+  message: "One or more attribute values are invalid",
+  errors: [
+    {
+      path: "email",
+      code: "INVALID_EMAIL",
+      message: "Invalid email format for attribute email"
+    },
+    {
+      path: "role",
+      code: "UNKNOWN_FIELD",
+      message: "Unknown field role is not allowed"
+    },
+    {
+      path: "active",
+      code: "UNKNOWN_FIELD",
+      message: "Unknown field active is not allowed"
+    }
+  ]
+}
+```
+
+With `"allow"`, unknown fields do not create validation errors. Normal
+schema validation continues unchanged.
+
+### Async behavior
+
+`perfectPayloadAsync()` supports the same `unknownFields` option:
+
+```js
+const result = await perfectPayloadAsync(payload, rules, {
+  unknownFields: "reject",
+});
+```
+
+Unknown-field checking is part of the synchronous validation phase. If
+`"reject"` finds an unknown field, asynchronous `customValidator`
+functions are not executed for that payload. This follows the normal
+two-phase contract of `perfectPayloadAsync()`.
+
+### Own properties only
+
+Unknown-field handling considers only the payload object's own
+enumerable properties. Enumerable properties inherited through the
+prototype chain are ignored.
+
+### Invalid option values
+
+Only these values are accepted:
+
+```text
+strip
+allow
+reject
+```
+
+Any other value throws a configuration error:
+
+```text
+perfect-payload:- unknownFields must be one of strip, allow, reject
+```
+
+This is a configuration error, not a payload validation error.
+
+## Synchronous vs Asynchronous Validation
+
+For normal synchronous validation, use `perfectPayload()`:
+
+```js
+import { perfectPayload } from "perfect-payload";
+
+const result = perfectPayload(payload, validationRules, options);
+```
+
+When any `customValidator` needs to perform asynchronous work, use
+`perfectPayloadAsync()` and `await` the result:
+
+```js
+import { perfectPayloadAsync } from "perfect-payload";
+
+const result = await perfectPayloadAsync(payload, validationRules, options);
+```
+
+The public APIs are:
+
+```text
+perfectPayloadV1()                            legacy API; deprecated
+perfectPayload(data, rules, options?)         synchronous validation
+perfectPayloadAsync(data, rules, options?)    synchronous + asynchronous customValidator
+```
+
+`perfectPayload()` remains synchronous and intentionally rejects a
+`customValidator` that returns a Promise. This preserves the existing
+synchronous API contract.
+
+`perfectPayloadAsync()` first performs transformations and normal
+synchronous validation. If synchronous validation fails, the result is
+returned immediately and asynchronous validators are not executed. This
+avoids unnecessary asynchronous work for payloads that are already
+invalid.
+
+```text
+transformations
+      ↓
+synchronous validation
+      ↓
+sync errors? ── yes ──→ return validation errors
+      ↓ no
+async customValidator
+      ↓
+return result
+```
+
 ## Legacy API
 
 `perfectPayloadV1()` is still available for backward compatibility.
@@ -173,10 +641,16 @@ March 31, 2027.
 
 Existing applications can continue using it during the migration period,
 
-but all new implementations should use:
+but all new implementations should use the current API:
 
 ```js
-perfectPayload();
+perfectPayload(data, validationRules, options?);
+```
+
+For asynchronous custom validation:
+
+```js
+await perfectPayloadAsync(data, validationRules, options?);
 ```
 
 The legacy API continues to return validation errors as:
@@ -200,6 +674,7 @@ errors: [
 ```
 
 Note: If an inValidPayloadResponse is provided, the
+
 system returns
 
 it alongside an automatically generated errors property. Do not include
@@ -211,6 +686,7 @@ object.
 ## Validation Rules
 
 `perfectPayload()` supports validation, nested-schema,
+
 custom-validation, and transformation rules.
 
 ### `mandatory`
@@ -305,6 +781,7 @@ Default: Not applied when omitted.
 const rules = {
   tags: {
     type: "array",
+
     minItems: 2,
   },
 };
@@ -313,14 +790,20 @@ const rules = {
 An array with fewer than 2 items returns `MIN_ITEMS`.
 
 ```js
+
 {
+
   path: "tags",
+
   code: "MIN_ITEMS",
+
   message: "Attribute tags must contain at least 2 item(s)"
+
 }
 ```
 
-`minItems` is enforced even when `allowEmptyArray: true` is set. For example, `minItems: 2` still rejects `[]`.
+`minItems` is enforced even when `allowEmptyArray: true` is set. For
+example, `minItems: 2` still rejects `[]`.
 
 Error code: `MIN_ITEMS`
 
@@ -336,6 +819,7 @@ Default: Not applied when omitted.
 const rules = {
   tags: {
     type: "array",
+
     maxItems: 5,
   },
 };
@@ -344,10 +828,15 @@ const rules = {
 An array with more than 5 items returns `MAX_ITEMS`.
 
 ```js
+
 {
+
   path: "tags",
+
   code: "MAX_ITEMS",
+
   message: "Attribute tags must contain at most 5 item(s)"
+
 }
 ```
 
@@ -554,6 +1043,7 @@ Error code: `MAX_LENGTH`
 Prevents decimal numbers.
 
 Default: `false`; both integer and decimal numbers are
+
 allowed.
 
 Example:
@@ -664,13 +1154,13 @@ Example error:
 
 {
 
-  path: "marks[2]",
+  path: "marks[2]",
 
-  code: "OUT_OF_RANGE",
+  code: "OUT_OF_RANGE",
 
-  message:
+  message:
 
-    "Attribute marks[2] should have a value between 0 and 100"
+    "Attribute marks[2] should have a value between 0 and 100"
 
 }
 ```
@@ -739,13 +1229,13 @@ Nested errors include the complete field path:
 
 {
 
-  path: "address.location.latitude",
+  path: "address.location.latitude",
 
-  code: "INVALID_TYPE",
+  code: "INVALID_TYPE",
 
-  message:
+  message:
 
-    "Invalid type for attribute address.location.latitude, required number value"
+    "Invalid type for attribute address.location.latitude, required number value"
 
 }
 ```
@@ -784,13 +1274,13 @@ Example error:
 
 {
 
-  path: "maxSalary",
+  path: "maxSalary",
 
-  code: "MIN_VALUE",
+  code: "MIN_VALUE",
 
-  message:
+  message:
 
-    "maxSalary must be more than minSalary"
+    "maxSalary must be more than minSalary"
 
 }
 ```
@@ -799,7 +1289,9 @@ Example error:
 
 ## Array Size and Nested Validation
 
-`perfectPayload()` supports array size constraints and recursive validation of arrays and objects at multiple depths. Array indexes and nested object keys are preserved in structured error paths.
+`perfectPayload()` supports array size constraints and recursive
+validation of arrays and objects at multiple depths. Array indexes and
+nested object keys are preserved in structured error paths.
 
 ### Array size constraints
 
@@ -809,12 +1301,17 @@ Use `minItems` and `maxItems` with `type: "array"`:
 const rules = {
   products: {
     type: "array",
+
     minItems: 1,
+
     maxItems: 3,
+
     elementConstraints: {
       type: "object",
+
       objectAttr: {
         productId: { mandatory: true, type: "string" },
+
         quantity: { mandatory: true, type: "number", min: 1 },
       },
     },
@@ -825,18 +1322,26 @@ const rules = {
 If the array is empty, `minItems` reports the array path itself:
 
 ```js
+
 {
+
   path: "products",
+
   code: "MIN_ITEMS",
+
   message: "Attribute products must contain at least 1 item(s)"
+
 }
 ```
 
 ### Arrays of objects
 
-`elementConstraints` can contain `objectAttr`, allowing every object in an array to use a nested schema. An invalid quantity in the second product is reported as:
+`elementConstraints` can contain `objectAttr`, allowing every object in
+an array to use a nested schema. An invalid quantity in the second
+product is reported as:
 
 ```text
+
 products[1].quantity
 ```
 
@@ -848,21 +1353,32 @@ products[1].quantity
 const rules = {
   orders: {
     type: "array",
+
     minItems: 1,
+
     maxItems: 2,
+
     elementConstraints: {
       type: "object",
+
       objectAttr: {
         orderId: { mandatory: true, type: "string" },
+
         items: {
           mandatory: true,
+
           type: "array",
+
           minItems: 1,
+
           maxItems: 2,
+
           elementConstraints: {
             type: "object",
+
             objectAttr: {
               productId: { mandatory: true, type: "string" },
+
               quantity: { mandatory: true, type: "number", min: 1 },
             },
           },
@@ -873,31 +1389,41 @@ const rules = {
 };
 ```
 
-A deep validation failure preserves the complete indexed path, for example:
+A deep validation failure preserves the complete indexed path, for
+example:
 
 ```text
+
 orders[1].items[2].quantity
 ```
 
-Array constraints work at nested levels too. A nested array can report paths such as:
+Array constraints work at nested levels too. A nested array can report
+paths such as:
 
 ```text
+
 orders[1].items
 ```
 
 Nested arrays are supported and every array index is preserved:
 
 ```text
+
 matrix[1][1]
+
 matrix[1][1][1]
 ```
 
-Transformations applied inside nested objects or array elements are preserved in `validatedPayload`, while the original input remains unchanged.
+Transformations applied inside nested objects or array elements are
+preserved in `validatedPayload`, while the original input remains
+unchanged.
 
 ### Transformations and Sanitization
 
 `perfectPayload()` can transform a field before its validation rules
+
 run. The transformed value is returned in `validatedPayload`, while the
+
 original input object is not mutated.
 
 Supported transformation rules:
@@ -907,53 +1433,81 @@ Rule Purpose
 ---
 
 `trim` Removes leading and trailing whitespace from strings
+
 `lowercase` Converts strings to lowercase
+
 `uppercase` Converts strings to uppercase
+
 `transform` Runs a custom synchronous transformation function
 
 Transformations always run in this fixed order, regardless of the order
+
 in which the rule properties are written:
 
 ```text
+
 trim
+
 ↓
+
 lowercase
+
 ↓
+
 uppercase
+
 ↓
+
 transform(value, payload)
+
 ↓
+
 validation rules
+
 ↓
+
 customValidator
+
 ↓
+
 validatedPayload
 ```
 
 #### `trim`
 
 ```js
+
 const payload = {
+
   name: "   Kiran Poojary   ",
+
 };
 
 const rules = {
+
   name: {
+
     type: "string",
+
     trim: true,
+
   },
+
 };
 
 const result = perfectPayload(payload, rules);
 
 console.log(result.validatedPayload.name);
-// "Kiran Poojary"
+
+*// "Kiran Poojary"*
 
 console.log(payload.name);
-// "   Kiran Poojary   "
+
+*// "   Kiran Poojary   "*
 ```
 
 `trim` applies only to string values. Non-string values are left
+
 unchanged.
 
 #### `lowercase`
@@ -962,13 +1516,16 @@ unchanged.
 const rules = {
   email: {
     trim: true,
+
     lowercase: true,
+
     type: "email",
   },
 };
 ```
 
 For `"  KIRAN@EXAMPLE.COM  "`, the validated value becomes
+
 `"kiran@example.com"`.
 
 #### `uppercase`
@@ -977,6 +1534,7 @@ For `"  KIRAN@EXAMPLE.COM  "`, the validated value becomes
 const rules = {
   countryCode: {
     type: "string",
+
     uppercase: true,
   },
 };
@@ -985,6 +1543,7 @@ const rules = {
 For `"in"`, the validated value becomes `"IN"`.
 
 `lowercase: true` and `uppercase: true` cannot be enabled together for
+
 the same field. Doing so throws a schema configuration error.
 
 #### `transform`
@@ -995,6 +1554,7 @@ Use `transform` when the built-in string transformations are not enough.
 const rules = {
   phone: {
     type: "string",
+
     transform: (value) => value.replace(/\s+/g, ""),
   },
 };
@@ -1011,31 +1571,46 @@ transform: (value, payload) => {
 ```
 
 - `value` is the field value after the built-in transformations have
+
   run.
+
 - `payload` is the current payload/object being validated.
 
 This makes cross-field transformations possible:
 
 ```js
+
 const payload = {
+
   amount: 100,
+
   multiplier: 2,
+
 };
 
 const rules = {
+
   amount: {
+
     transform: (value, payload) => value * payload.multiplier,
+
     type: "number",
+
   },
+
   multiplier: {
+
     type: "number",
+
   },
+
 };
 
 const result = perfectPayload(payload, rules);
 
 console.log(result.validatedPayload.amount);
-// 200
+
+*// 200*
 ```
 
 A custom transformer may also change the data type before validation:
@@ -1044,36 +1619,48 @@ A custom transformer may also change the data type before validation:
 const rules = {
   quantity: {
     transform: (value) => Number(value),
+
     type: "number",
+
     min: 1,
+
     max: 100,
   },
 };
 ```
 
 The transformed value is validated by the normal validation rules and is
+
 also the value received by `customValidator`.
 
 Transformations work inside `objectAttr` and `elementConstraints`, and
+
 transformed nested/array values are preserved in `validatedPayload`.
 
 ```js
 const rules = {
   profile: {
     type: "object",
+
     objectAttr: {
       name: {
         trim: true,
+
         uppercase: true,
+
         type: "string",
       },
     },
   },
+
   tags: {
     type: "array",
+
     elementConstraints: {
       trim: true,
+
       lowercase: true,
+
       type: "string",
     },
   },
@@ -1081,29 +1668,39 @@ const rules = {
 ```
 
 Missing optional fields are not transformed. An input value of `null` is
+
 not passed to transformation functions; null handling remains controlled
+
 by `allowNull`.
 
-**Important:** `transform` is synchronous. A non-function transformer,
+\*\*\*\*Important:\*\*\*\* `transform` is synchronous. A non-function
+transformer,
+
 an `async` transformer, a transformer that returns a Promise, or a
-transformer that returns `undefined` is not supported and throws an error.
-Returning `null`, `""`, `0`, or `false` is allowed; the transformed value is
-then processed by the normal validation rules. Exceptions thrown inside the
+
+transformer that returns `undefined` is not supported and throws an
+error.
+
+Returning `null`, `""`, `0`, or `false` is allowed; the transformed
+value is
+
+then processed by the normal validation rules. Exceptions thrown inside
+the
+
 transformer propagate to the caller.
 
 For example, returning `undefined` throws:
 
 ```text
+
 perfect-payload:- transform must not return undefined for attribute username
 ```
 
 ### `customValidator`
 
-Allows you to define custom synchronous validation logic for a field
-when the built-in validation rules are not enough.
+Defines custom validation logic when the built-in rules are not enough.
 
-The validator receives the field value and the current payload/object
-being validated:
+The validator receives:
 
 ```js
 customValidator: (value, payload) => {
@@ -1111,100 +1708,302 @@ customValidator: (value, payload) => {
 };
 ```
 
-The validator must return `true` to pass validation. Any other return
-value causes validation to fail.
+- `value` is the field value after transformations have been applied.
+- `payload` is the current payload/object being validated.
+- Return `true` to pass.
+- Any value other than `true` fails validation.
+- Exceptions thrown by the validator propagate to the caller.
+
+For nested validation, `payload` means the current nested object rather
+than the root request body.
 
-Example:
+#### Synchronous custom validator
+
+Use a synchronous validator with `perfectPayload()`:
 
 ```js
 const rules = {
   username: {
     mandatory: true,
-
     type: "string",
+    trim: true,
 
     customValidator: (value) => {
       return !value.toLowerCase().includes("admin");
     },
 
     customValidatorCode: "RESERVED_USERNAME",
-
     customValidatorError: "Username cannot contain admin",
   },
 };
+
+const result = perfectPayload({ username: "  admin_kiran  " }, rules);
 ```
 
-For this payload:
+A failure returns:
 
 ```js
-const payload = {
-  username: "admin_kiran",
+{
+  statusCode: 400,
+  valid: false,
+  message: "One or more attribute values are invalid",
+  errors: [
+    {
+      path: "username",
+      code: "RESERVED_USERNAME",
+      message: "Username cannot contain admin"
+    }
+  ]
+}
+```
+
+The current payload/object can be used for cross-field validation:
+
+```js
+const rules = {
+  limit: {
+    type: "number",
+  },
+
+  amount: {
+    type: "number",
+
+    customValidator: (value, payload) => {
+      return value <= payload.limit;
+    },
+
+    customValidatorCode: "LIMIT_EXCEEDED",
+    customValidatorError: "Amount cannot exceed limit",
+  },
 };
 ```
 
-The validation error is:
+If `customValidatorCode` and `customValidatorError` are omitted, the
+default error is:
 
 ```js
+{
+  path: "username",
+  code: "CUSTOM_VALIDATION_FAILED",
+  message: "Custom validation failed for attribute username"
+}
+```
+
+`customValidator` works recursively inside `objectAttr` and
+`elementConstraints`. Structured errors preserve the corresponding
+nested and array paths.
+
+When using `perfectPayload()`, `customValidator` must remain
+synchronous. A Promise-returning validator throws:
+
+```text
+perfect-payload:- customValidator must be synchronous for attribute username
+```
+
+For asynchronous custom validation, use `perfectPayloadAsync()`.
+
+## Asynchronous Validation
+
+`perfectPayloadAsync()` supports both synchronous and asynchronous
+`customValidator` functions without changing the behavior of
+`perfectPayload()`.
 
+```js
+import { perfectPayloadAsync } from "perfect-payload";
+
+const rules = {
+  username: {
+    mandatory: true,
+    type: "string",
+    trim: true,
+
+    customValidator: async (value) => {
+      const available = await checkUsernameAvailability(value);
+      return available;
+    },
+
+    customValidatorCode: "USERNAME_TAKEN",
+    customValidatorError: "Username is already taken",
+  },
+};
+
+const result = await perfectPayloadAsync(
+  {
+    username: "  kiran  ",
+  },
+  rules,
+);
+```
+
+On success, transformations are preserved:
+
+```js
 {
+  statusCode: 200,
+  valid: true,
+  validatedPayload: {
+    username: "kiran"
+  }
+}
+```
+
+On asynchronous validation failure:
+
+```js
+{
+  statusCode: 400,
+  valid: false,
+  message: "One or more attribute values are invalid",
+  errors: [
+    {
+      path: "username",
+      code: "USERNAME_TAKEN",
+      message: "Username is already taken"
+    }
+  ]
+}
+```
+
+### Async validator contract
+
+For `perfectPayloadAsync()`:
+
+```text
+true             → pass
+false            → validation failure
+anything != true → validation failure
+throw            → exception propagates
+rejected Promise → rejection propagates
+```
+
+A normal synchronous validator is also valid when using the asynchronous
+API:
+
+```js
+const rules = {
+  username: {
+    type: "string",
+    customValidator: (value) => value !== "admin",
+  },
+};
+
+const result = await perfectPayloadAsync(payload, rules);
+```
+
+A configured `customValidator` must be a function. Otherwise an error is
+thrown:
+
+```text
+perfect-payload:- customValidator must be a function for attribute username
+```
+
+### Validation order
+
+`perfectPayloadAsync()` uses two phases:
+
+1.  Transform the payload and run normal synchronous validation.
+2.  If phase 1 succeeds, run custom validators with `await`.
+
+If any synchronous validation error exists, phase 2 is skipped and the
+synchronous validation result is returned immediately.
+
+This means asynchronous validators can assume the payload has already
+passed its normal synchronous validation rules.
+
+### Nested async validation
+
+Async custom validators work recursively inside `objectAttr`:
+
+```js
+const rules = {
+  profile: {
+    type: "object",
+
+    objectAttr: {
+      username: {
+        type: "string",
+        trim: true,
+
+        customValidator: async (value) => {
+          return await isUsernameAvailable(value);
+        },
+
+        customValidatorCode: "USERNAME_TAKEN",
+        customValidatorError: "Username is already taken",
+      },
+    },
+  },
+};
+```
+
+A failure produces the complete path:
+
+```text
+profile.username
+```
+
+They also work inside `elementConstraints`:
+
+```js
+const rules = {
+  usernames: {
+    type: "array",
+
+    elementConstraints: {
+      type: "string",
+      trim: true,
+
+      customValidator: async (value) => {
+        return await isUsernameAvailable(value);
+      },
+
+      customValidatorCode: "USERNAME_TAKEN",
+      customValidatorError: "Username is already taken",
+    },
+  },
+};
+```
 
-  path: "username",
+For an invalid second element:
 
-  code: "RESERVED_USERNAME",
+```text
+usernames[1]
+```
 
-  message: "Username cannot contain admin"
+Deep combinations of objects and arrays preserve every level of the
+path:
 
-}
+```text
+products[1].seller.username
+profile.teams[1].members[1].username
 ```
 
-If `customValidatorCode` and `customValidatorError` are not provided,
-the default error is:
+Default async custom-validation messages also use the final indexed
+path:
 
 ```js
-
 {
-
-  path: "username",
-
-  code: "CUSTOM_VALIDATION_FAILED",
-
-  message: "Custom validation failed for attribute username"
-
+  path: "users[1].username",
+  code: "CUSTOM_VALIDATION_FAILED",
+  message: "Custom validation failed for attribute users[1].username"
 }
 ```
 
-The current payload/object being validated can be used as the second
-argument when required:
-
-```js
-const rules = {
-  limit: {
-    type: "number",
-  },
-
-  amount: {
-    type: "number",
+### Transform remains synchronous
 
-    customValidator: (value, payload) => {
-      return value <= payload.limit;
-    },
+`perfectPayloadAsync()` makes custom validation asynchronous; it does
+not make `transform` asynchronous.
 
-    customValidatorCode: "LIMIT_EXCEEDED",
+`transform` must still be synchronous:
 
-    customValidatorError: "Amount cannot exceed limit",
-  },
+```js
+transform: (value, payload) => {
+  return value;
 };
 ```
 
-`customValidator` also works with nested objects and array
-`elementConstraints`. The generated structured error automatically
-contains the corresponding nested or array path.
-
-Important: `customValidator` is synchronous. An `async`
-validator or a validator that returns a Promise is not supported and
-throws an error. Asynchronous validation is not part of this feature.
-
-Error code when no custom code is provided: `CUSTOM_VALIDATION_FAILED`
+An async transformer or a transformer that returns a Promise is not
+supported.
 
 ## Error Codes
 
@@ -1263,6 +2062,8 @@ MAX_VALUE
 OUT_OF_RANGE
 
 CUSTOM_VALIDATION_FAILED
+
+UNKNOWN_FIELD
 ```
 
 These codes are designed for programmatic handling while `message`
@@ -1277,17 +2078,17 @@ const result = perfectPayload(payload, validationRules);
 
 if (!result.valid) {
 
-  const emailError = result.errors.find(
+  const emailError = result.errors.find(
 
-    (error) => error.code === "INVALID_EMAIL",
+    (error) => error.code === "INVALID_EMAIL",
 
-  );
+  );
 
-  if (emailError) {
+  if (emailError) {
 
-    **// Handle invalid email**
+    ***// Handle invalid email***
 
-  }
+  }
 
 }
 ```
@@ -1304,11 +2105,11 @@ keeping the same structured error format:
 
 {
 
-  path: "email",
+  path: "email",
 
-  code: "INVALID_EMAIL",
+  code: "INVALID_EMAIL",
 
-  message: "Email address is invalid"
+  message: "Email address is invalid"
 
 }
 ```
@@ -1335,11 +2136,11 @@ If `email` is missing:
 
 {
 
-  path: "email",
+  path: "email",
 
-  code: "REQUIRED",
+  code: "REQUIRED",
 
-  message: "Email is required"
+  message: "Email is required"
 
 }
 ```
@@ -1350,11 +2151,11 @@ If `email` is present but invalid:
 
 {
 
-  path: "email",
+  path: "email",
 
-  code: "INVALID_EMAIL",
+  code: "INVALID_EMAIL",
 
-  message: "Email address is invalid"
+  message: "Email address is invalid"
 
 }
 ```
@@ -1443,53 +2244,53 @@ Example result:
 
 {
 
-  statusCode: 400,
+  statusCode: 400,
 
-  valid: false,
+  valid: false,
 
-  message:
+  message:
 
-    "One or more attribute values are invalid",
+    "One or more attribute values are invalid",
 
-  errors: [
+  errors: [
 
-    {
+    {
 
-      path: "username",
+      path: "username",
 
-      code: "MIN_LENGTH",
+      code: "MIN_LENGTH",
 
-      message:
+      message:
 
-        "Username must contain at least 3 characters"
+        "Username must contain at least 3 characters"
 
-    },
+    },
 
-    {
+    {
 
-      path: "age",
+      path: "age",
 
-      code: "MIN_VALUE",
+      code: "MIN_VALUE",
 
-      message:
+      message:
 
-        "Age must be at least 18"
+        "Age must be at least 18"
 
-    },
+    },
 
-    {
+    {
 
-      path: "score",
+      path: "score",
 
-      code: "OUT_OF_RANGE",
+      code: "OUT_OF_RANGE",
 
-      message:
+      message:
 
-        "Score must be between 0 and 100"
+        "Score must be between 0 and 100"
 
-    }
+    }
 
-  ]
+  ]
 
 }
 ```
@@ -1520,11 +2321,11 @@ Still returns:
 
 {
 
-  path: "age",
+  path: "age",
 
-  code: "MIN_VALUE",
+  code: "MIN_VALUE",
 
-  message: "You must be 18 or older"
+  message: "You must be 18 or older"
 
 }
 ```
@@ -1541,157 +2342,156 @@ handling
 
 ## Custom Response Objects
 
-`perfectPayload()` allows you to customize both the valid and invalid
-
-response objects.
+Custom valid and invalid response objects are configured inside the
+optional third `options` argument.
 
-The third argument is the custom valid response.
+```js
+perfectPayload(data, validationRules, options?)
+await perfectPayloadAsync(data, validationRules, options?)
+```
 
-The fourth argument is the custom invalid response.
+This keeps API-level configuration in one place and avoids positional
+`undefined` arguments.
 
 ### Custom Valid Response
 
-Example:
-
 ```js
-const customValidResponse = {
-  statusCode: 201,
-
-  valid: true,
-
-  message: "Payload validated successfully",
-};
-
-const result = perfectPayload(payload, validationRules, customValidResponse);
+const result = perfectPayload(payload, validationRules, {
+  validPayloadResponse: {
+    statusCode: 201,
+    valid: true,
+    message: "Payload validated successfully",
+  },
+});
 ```
 
 When validation succeeds, `validatedPayload` is automatically added:
 
 ```js
-
 {
-
-  statusCode: 201,
-
-  valid: true,
-
-  message: "Payload validated successfully",
-
-  validatedPayload: {
-
-    name: "Kiran",
-
-    email: "kiran@example.com",
-
-    age: 29
-
-  }
-
+  statusCode: 201,
+  valid: true,
+  message: "Payload validated successfully",
+  validatedPayload: {
+    name: "Kiran",
+    email: "kiran@example.com",
+    age: 29
+  }
 }
 ```
 
 ### Custom Invalid Response
 
-Example:
-
 ```js
-const customInvalidResponse = {
-  statusCode: 422,
-
-  valid: false,
-
-  message: "Payload validation failed",
-};
-
-const result = perfectPayload(
-  payload,
-
-  validationRules,
-
-  undefined,
-
-  customInvalidResponse,
-);
+const result = perfectPayload(payload, validationRules, {
+  inValidPayloadResponse: {
+    statusCode: 422,
+    valid: false,
+    message: "Payload validation failed",
+  },
+});
 ```
 
 When validation fails, `errors` is automatically added:
 
 ```js
-
 {
-
-  statusCode: 422,
-
-  valid: false,
-
-  message: "Payload validation failed",
-
-  errors: [
-
-    {
-
-      path: "email",
-
-      code: "INVALID_EMAIL",
-
-      message:
-
-        "Invalid email format for attribute email"
-
-    }
-
-  ]
-
+  statusCode: 422,
+  valid: false,
+  message: "Payload validation failed",
+  errors: [
+    {
+      path: "email",
+      code: "INVALID_EMAIL",
+      message: "Invalid email format for attribute email"
+    }
+  ]
 }
 ```
 
 ### Custom Valid and Invalid Responses Together
 
 ```js
-const customValidResponse = {
-  statusCode: 201,
+const result = perfectPayload(payload, validationRules, {
+  validPayloadResponse: {
+    statusCode: 201,
+    valid: true,
+    message: "CUSTOM_VALID_RESPONSE",
+  },
 
-  valid: true,
+  inValidPayloadResponse: {
+    statusCode: 422,
+    valid: false,
+    message: "CUSTOM_INVALID_RESPONSE",
+  },
+});
+```
 
-  message: "CUSTOM_VALID_RESPONSE",
-};
+You can combine response customization with other API options:
 
-const customInvalidResponse = {
-  statusCode: 422,
+```js
+const result = perfectPayload(payload, validationRules, {
+  unknownFields: "reject",
 
-  valid: false,
+  validPayloadResponse: {
+    statusCode: 201,
+    valid: true,
+  },
 
-  message: "CUSTOM_INVALID_RESPONSE",
-};
+  inValidPayloadResponse: {
+    statusCode: 422,
+    valid: false,
+    message: "Payload validation failed",
+  },
+});
+```
 
-const result = perfectPayload(
-  payload,
+The response object you provide is preserved while `perfectPayload()`
+automatically adds `validatedPayload` for successful validation or
+`errors` for failed validation.
 
-  validationRules,
+The same response options are supported by `perfectPayloadAsync()`.
 
-  customValidResponse,
+## v1.7 API Migration
 
-  customInvalidResponse,
-);
-```
+The current `perfectPayload()` and `perfectPayloadAsync()` APIs use one
+optional third argument for configuration:
 
-The response object you provide is preserved, while `perfectPayload()`
+```js
+perfectPayload(data, validationRules, options?)
+perfectPayloadAsync(data, validationRules, options?)
+```
 
-automatically adds either:
+Custom response objects now belong inside `options`.
 
-```text
+Use:
 
-validatedPayload
+```js
+perfectPayload(payload, rules, {
+  validPayloadResponse: customValidResponse,
+  inValidPayloadResponse: customInvalidResponse,
+});
 ```
 
-for successful validation, or:
+instead of passing custom response objects as separate positional
+arguments.
 
-```text
+This also makes it possible to combine response customization with
+`unknownFields` without placeholder arguments:
 
-errors
+```js
+perfectPayload(payload, rules, {
+  unknownFields: "reject",
+  inValidPayloadResponse: {
+    statusCode: 422,
+    valid: false,
+    message: "Payload validation failed",
+  },
+});
 ```
 
-for failed validation.
+`perfectPayloadV1()` is unchanged and retains its legacy signature
+during its deprecation period.
 
 ## Default Responses
 
@@ -1703,15 +2503,15 @@ is:
 
 {
 
-  statusCode: 200,
+  statusCode: 200,
 
-  valid: true,
+  valid: true,
 
-  validatedPayload: {
+  validatedPayload: {
 
-    **// validated fields**
+    ***// validated fields***
 
-  }
+  }
 
 }
 ```
@@ -1722,25 +2522,25 @@ The default invalid response is:
 
 {
 
-  statusCode: 400,
+  statusCode: 400,
 
-  valid: false,
+  valid: false,
 
-  message: "One or more attribute values are invalid",
+  message: "One or more attribute values are invalid",
 
-  errors: [
+  errors: [
 
-    {
+    {
 
-      path: "field",
+      path: "field",
 
-      code: "ERROR_CODE",
+      code: "ERROR_CODE",
 
-      message: "Validation error message"
+      message: "Validation error message"
 
-    }
+    }
 
-  ]
+  ]
 
 }
 ```
@@ -1771,11 +2571,11 @@ An error can be returned as:
 
 {
 
-  path: "email",
+  path: "email",
 
-  code: "INVALID_EMAIL",
+  code: "INVALID_EMAIL",
 
-  message: "Invalid email format for attribute email"
+  message: "Invalid email format for attribute email"
 
 }
 ```
@@ -1834,13 +2634,13 @@ its complete nested path:
 
 {
 
-  path: "address.location.latitude",
+  path: "address.location.latitude",
 
-  code: "INVALID_TYPE",
+  code: "INVALID_TYPE",
 
-  message:
+  message:
 
-    "Invalid type for attribute address.location.latitude, required number value"
+    "Invalid type for attribute address.location.latitude, required number value"
 
 }
 ```
@@ -1888,13 +2688,13 @@ The invalid third element is reported as:
 
 {
 
-  path: "marks[2]",
+  path: "marks[2]",
 
-  code: "OUT_OF_RANGE",
+  code: "OUT_OF_RANGE",
 
-  message:
+  message:
 
-    "Attribute marks[2] should have a value between 0 and 100"
+    "Attribute marks[2] should have a value between 0 and 100"
 
 }
 ```
@@ -1910,7 +2710,9 @@ marks[1]
 marks[2]
 ```
 
-Array-level constraints such as `minItems` and `maxItems` report the path of the array itself. For nested arrays, the complete parent path is retained, for example `orders[1].items`.
+Array-level constraints such as `minItems` and `maxItems` report the
+path of the array itself. For nested arrays, the complete parent path is
+retained, for example `orders[1].items`.
 
 ### Nested Fields Inside Arrays
 
@@ -1969,11 +2771,11 @@ Result:
 
 {
 
-  "email": "Invalid email format for attribute email",
+  "email": "Invalid email format for attribute email",
 
-  "address.location.latitude": "Invalid type for attribute address.location.latitude, required number value",
+  "address.location.latitude": "Invalid type for attribute address.location.latitude, required number value",
 
-  "marks[2]": "Attribute marks[2] should have a value between 0 and 100"
+  "marks[2]": "Attribute marks[2] should have a value between 0 and 100"
 
 }
 ```
@@ -1988,61 +2790,61 @@ sample-1
 
 {
 
-  firstName: {
+  firstName: {
 
-    mandatory: true,
+    mandatory: true,
 
-    allowNull: false,
+    allowNull: false,
 
-    type: "string",
+    type: "string",
 
-    minLength: 3,
+    minLength: 3,
 
-    minLengthError: "First name must have minimum 3 characters."
+    minLengthError: "First name must have minimum 3 characters."
 
-  },
+  },
 
-  lastName: {
+  lastName: {
 
-    mandatory: false,
+    mandatory: false,
 
-    allowNull: true,
+    allowNull: true,
 
-    type: "string",
+    type: "string",
 
-  },
+  },
 
-  email: {
+  email: {
 
-    mandatory: true,
+    mandatory: true,
 
-    allowNull: false,
+    allowNull: false,
 
-    type: "email",
+    type: "email",
 
-  },
+  },
 
-  phone: {
+  phone: {
 
-    mandatory: true,
+    mandatory: true,
 
-    allowNull: false,
+    allowNull: false,
 
-    type: "string",
+    type: "string",
 
-  },
+  },
 
-  age: {
+  age: {
 
-    mandatory: false,
+    mandatory: false,
 
-    type: "number",
+    type: "number",
 
-    min: 1,
+    min: 1,
 
-    max: 120,
+    max: 120,
 
-  },
+  },
 
 };
 ```
@@ -2053,271 +2855,271 @@ sample-2
 
 {
 
-  id: {
+  id: {
 
-    mandatory: true,
+    mandatory: true,
 
-    allowNull: true,
+    allowNull: true,
 
-    type: "uuidv4",
+    type: "uuidv4",
 
-  },
+  },
 
-  batchId: {
+  batchId: {
 
-    mandatory: true,
+    mandatory: true,
 
-    allowNull: true,
+    allowNull: true,
 
-    type: "objectId",
+    type: "objectId",
 
-  },
+  },
 
-  firstName: {
+  firstName: {
 
-    mandatory: true,
+    mandatory: true,
 
-    type: "string",
+    type: "string",
 
-    minLength: 3,
+    minLength: 3,
 
-  },
+  },
 
-  lastName: {
+  lastName: {
 
-    mandatory: false,
+    mandatory: false,
 
-    allowNull: true,
+    allowNull: true,
 
-    type: "string",
+    type: "string",
 
-  },
+  },
 
-  age: {
+  age: {
 
-    type: "number",
+    type: "number",
 
-    min: 0.1,
+    min: 0.1,
 
-    max: 120,
+    max: 120,
 
-  },
+  },
 
-  isAdult: {
+  isAdult: {
 
-    type: "boolean",
+    type: "boolean",
 
-  },
+  },
 
-  totalWins: {
+  totalWins: {
 
-    type: "number",
+    type: "number",
 
-    min: 0,
+    min: 0,
 
-    preventDecimal: true,
+    preventDecimal: true,
 
-  },
+  },
 
-  email: {
+  email: {
 
-    regex: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\.[a-zA-Z]{2,}$/,
+    regex: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\\\\\.[a-zA-Z]{2,}$/,
 
-  },
+  },
 
-  githubLink: {
+  githubLink: {
 
-    type: "url",
+    type: "url",
 
-  },
+  },
 
-  accountStatus: {
+  accountStatus: {
 
-    type: "enum",
+    type: "enum",
 
-    enumValues: ["Active", "Inactive", 200],
+    enumValues: ["Active", "Inactive", 200],
 
-  },
+  },
 
-  marks: {
+  marks: {
 
-    range: "0-100",
+    range: "0-100",
 
-  },
+  },
 
-  allMarks: {
+  allMarks: {
 
-    type: "array",
+    type: "array",
 
-    allowEmptyArray: false,
+    allowEmptyArray: false,
 
-    elementConstraints: {
+    elementConstraints: {
 
-      type: "number",
+      type: "number",
 
-      allowNull: false,
+      allowNull: false,
 
-      range: "0-100",
+      range: "0-100",
 
-    },
+    },
 
-  },
+  },
 
-  totalScore: {
+  totalScore: {
 
-    type: "number",
+    type: "number",
 
-    dependency: {
+    dependency: {
 
-      result: {
+      result: {
 
-        setDependencyRule: (totalScore, result) => {
+        setDependencyRule: (totalScore, result) => {
 
-          return { mandatory: true, allowNull: false, type: "string" };
+          return { mandatory: true, allowNull: false, type: "string" };
 
-        },
+        },
 
-      },
+      },
 
-    },
+    },
 
-  },
+  },
 
-  result: {
+  result: {
 
-    type: "string",
+    type: "string",
 
-    dependency: {
+    dependency: {
 
-      totalScore: {
+      totalScore: {
 
-        setDependencyRule: (result, totalScore) => {
+        setDependencyRule: (result, totalScore) => {
 
-          return { mandatory: true, allowNull: false, type: "number" };
+          return { mandatory: true, allowNull: false, type: "number" };
 
-        },
+        },
 
-      },
+      },
 
-    },
+    },
 
-  },
+  },
 
-  minSalary: {
+  minSalary: {
 
-    mandatory: true,
+    mandatory: true,
 
-    min: 1,
+    min: 1,
 
-    type: "number",
+    type: "number",
 
-    dependency: {
+    dependency: {
 
-      maxSalary: {
+      maxSalary: {
 
-        setDependencyRule: (minSalary, maxSalary) => {
+        setDependencyRule: (minSalary, maxSalary) => {
 
-          return {
+          return {
 
-            mandatory: true,
+            mandatory: true,
 
-            min: minSalary + 1,
+            min: minSalary + 1,
 
-            minError: "maxSalary must be more than minSalary",
+            minError: "maxSalary must be more than minSalary",
 
-          };
+          };
 
-        },
+        },
 
-      },
+      },
 
-    },
+    },
 
-  },
+  },
 
-  maxSalary: {
+  maxSalary: {
 
-    dependency: {
+    dependency: {
 
-      minSalary: {
+      minSalary: {
 
-        setDependencyRule: (maxSalary, minSalary) => {
+        setDependencyRule: (maxSalary, minSalary) => {
 
-          return {
+          return {
 
-            mandatory: true,
+            mandatory: true,
 
-            max: maxSalary - 1,
+            max: maxSalary - 1,
 
-            maxError: "minSalary must be less than maxSalary",
+            maxError: "minSalary must be less than maxSalary",
 
-          };
+          };
 
-        },
+        },
 
-      },
+      },
 
-    },
+    },
 
-  },
+  },
 
-  address: {
+  address: {
 
-    mandatory: true,
+    mandatory: true,
 
-    type: "object",
+    type: "object",
 
-    allowEmptyObject: false,
+    allowEmptyObject: false,
 
-    objectAttr: {
+    objectAttr: {
 
-      country: { mandatory: true, type: "string" },
+      country: { mandatory: true, type: "string" },
 
-      state: {
+      state: {
 
-        mandatory: true,
+        mandatory: true,
 
-        type: "string",
+        type: "string",
 
-      },
+      },
 
-      city: {},
+      city: {},
 
-      zip: {
+      zip: {
 
-        mandatory: true,
+        mandatory: true,
 
-        type: "string",
+        type: "string",
 
-      },
+      },
 
-      position: {
+      position: {
 
-        mandatory: true,
+        mandatory: true,
 
-        type: "object",
+        type: "object",
 
-        allowEmptyObject: false,
+        allowEmptyObject: false,
 
-        objectAttr: {
+        objectAttr: {
 
-          lattitude: { mandatory: true, type: "number" },
+          lattitude: { mandatory: true, type: "number" },
 
-          longitude: {
+          longitude: {
 
-            mandatory: true,
+            mandatory: true,
 
-            type: "number",
+            type: "number",
 
-          },
+          },
 
-        },
+        },
 
-      },
+      },
 
-    },
+    },
 
-  },
+  },
 
 }
 ```
@@ -2328,15 +3130,15 @@ sample-2
 
 ```js
 
-**// validatePayload is the middleware that invokes perfectPayload()**
+***// validatePayload is the middleware that invokes perfectPayload()***
 
 router.post(
 
-  "/payload-validation",
+  "/payload-validation",
 
-  validatePayload({ rule: <your validation rule json object> }),
+  validatePayload({ rule: <your validation rule json object> }),
 
-  (req, res) => res.send("OK")
+  (req, res) => res.send("OK")
 
 );
 ```
@@ -2365,6 +3167,47 @@ export const validatePayload = ({ rule }) => {
 };
 ```
 
+#### Async ES Modules middleware example
+
+When your schema contains an asynchronous `customValidator`, the
+middleware itself must be `async` and `perfectPayloadAsync()` must be
+awaited:
+
+```js
+import { perfectPayloadAsync } from "perfect-payload";
+
+export const validatePayloadAsync = ({ rule }) => {
+  return async (req, res, next) => {
+    try {
+      const { statusCode, ...response } = await perfectPayloadAsync(
+        req?.body,
+        rule,
+      );
+
+      if (+statusCode >= 200 && +statusCode <= 299) {
+        req.validatedBody = response?.validatedPayload;
+        next();
+      } else {
+        res.status(statusCode).json(response);
+      }
+    } catch (error) {
+      console.error("Error validating payload", error);
+      res.status(500).json({ error: "Internal Server Error" });
+    }
+  };
+};
+```
+
+Route usage:
+
+```js
+router.post(
+  "/payload-validation",
+  validatePayloadAsync({ rule: <your validation rule json object> }),
+  (req, res) => res.send("OK"),
+);
+```
+
 #### CommonJS middleware example
 
 ```js