perfect-payload 1.2.3 → 1.4.0-beta.0

package/README.md

@@ -3,6 +3,25 @@
 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, and synchronous payload
+transformation/sanitization while keeping the validation schema simple.
+
+## Quick Links
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Validation Rules](#validation-rules)
+- [Transformations and
+  Sanitization](#transformations-and-sanitization)
+- [Custom Validators](#customvalidator)
+- [Error Codes](#error-codes)
+- [Custom Error Messages](#custom-error-messages)
+- [Nested Objects and Array Field
+  Paths](#nested-objects-and-array-field-paths)
+- [Examples and Usage](#examples-and-usage)
+- [Legacy API](#legacy-api)
+
 ## Installation
 
 ```bash
@@ -19,24 +38,30 @@ import { perfectPayload } from "perfect-payload";
 
 const payload = {
   name: "Kiran",
+
   email: "kiran@example.com",
+
   age: 29,
 };
 
 const validationRules = {
   name: {
     mandatory: true,
+
     type: "string",
   },
 
   email: {
     mandatory: true,
+
     type: "email",
   },
 
   age: {
     mandatory: true,
+
     type: "number",
+
     min: 18,
   },
 };
@@ -51,19 +76,31 @@ console.log(result);
 ```js
 
 {
+
   statusCode: 200,
+
   valid: true,
+
   validatedPayload: {
+
     name: "Kiran",
+
     email: "kiran@example.com",
+
     age: 29
+
   }
+
 }
 ```
 
-**Note:** The validatedPayload contains only the fields defined in the
+Note: The validatedPayload contains only the fields
+defined in the
+
 schema, automatically filtering out any extra attributes. You can use it
+
 to safely overwrite request.body or assign it to a new request property
+
 (such as validatedBody, sanitisedData or parsedBody).
 
 ### Invalid Response
@@ -71,16 +108,27 @@ to safely overwrite request.body or assign it to a new request property
 ```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"
+
     }
+
   ]
+
 }
 ```
 
@@ -89,17 +137,25 @@ Each error returned by `perfectPayload()` contains:
 ```js
 
 {
+
   path: "field.path",
+
   code: "ERROR_CODE",
+
   message: "Human readable validation message"
+
 }
 ```
 
-- `path` identifies the exact field that failed validation.
-- `code` provides a stable machine-readable validation error code.
-- `message` provides a human-readable description of the validation
-  failure.
-- Submitted payload values are not included in default error messages.
+\- `path` identifies the exact field that failed validation.
+
+\- `code` provides a stable machine-readable validation error code.
+
+\- `message` provides a human-readable description of the validation
+
+failure.
+
+\- Submitted payload values are not included in default error messages.
 
 ## Legacy API
 
@@ -110,9 +166,11 @@ import { perfectPayloadV1 } from "perfect-payload";
 ```
 
 `perfectPayloadV1()` is deprecated and will no longer be supported after
-**\*\*March 31, 2027\*\***.
+
+March 31, 2027.
 
 Existing applications can continue using it during the migration period,
+
 but all new implementations should use:
 
 ```js
@@ -131,26 +189,33 @@ while the new `perfectPayload()` API returns structured errors:
 errors: [
   {
     path: "email",
+
     code: "INVALID_EMAIL",
+
     message: "Invalid email format for attribute email",
   },
 ];
 ```
 
-**Note:** If an inValidPayloadResponse is provided, the system returns
+Note: If an inValidPayloadResponse is provided, the
+system returns
+
 it alongside an automatically generated errors property. Do not include
+
 your own errors attribute inside the custom inValidPayloadResponse
+
 object.
 
 ## Validation Rules
 
-`perfectPayload()` supports the following validation rules.
+`perfectPayload()` supports validation, nested-schema,
+custom-validation, and transformation rules.
 
 ### `mandatory`
 
-Marks a field as required(even empty string also not allowed)
+Marks a field as required. An empty string is also treated as missing.
 
-**Default:** `false`, the field is not required.
+Default: `false`, the field is not required.
 
 ```js
 const rules = {
@@ -168,7 +233,7 @@ Error code: `REQUIRED`
 
 Controls whether `null` values are accepted.
 
-**Default:** `true` , `null` values are allowed.
+Default: `true`, `null` values are allowed.
 
 Example:
 
@@ -188,7 +253,7 @@ Error code: `NULL_NOT_ALLOWED`
 
 Controls whether an empty object `{}` is accepted.
 
-**Default:** `true`, empty objects are allowed.
+Default: `true`, empty objects are allowed.
 
 Example:
 
@@ -196,6 +261,7 @@ Example:
 const rules = {
   address: {
     type: "object",
+
     allowEmptyObject: false,
   },
 };
@@ -209,7 +275,7 @@ Error code: `EMPTY_OBJECT_NOT_ALLOWED`
 
 Controls whether an empty array `[]` is accepted.
 
-**Default:** `true`, empty arrays are allowed.
+Default: `true`, empty arrays are allowed.
 
 Example:
 
@@ -217,6 +283,7 @@ Example:
 const rules = {
   products: {
     type: "array",
+
     allowEmptyArray: false,
   },
 };
@@ -235,18 +302,31 @@ Supported values:
 ```text
 
 number
+
 string
+
 boolean
+
 email
+
 url
+
 enum
+
 uuid
+
 uuidv1
+
 uuidv3
+
 uuidv4
+
 uuidv5
+
 objectId
+
 array
+
 object
 ```
 
@@ -257,9 +337,11 @@ const rules = {
   age: {
     type: "number",
   },
+
   email: {
     type: "email",
   },
+
   active: {
     type: "boolean",
   },
@@ -280,6 +362,7 @@ Example:
 const rules = {
   status: {
     type: "enum",
+
     enumValues: ["active", "inactive", "blocked", 1, 0],
   },
 };
@@ -299,6 +382,7 @@ Example:
 const rules = {
   status: {
     type: "enum",
+
     enumValues: ["active", "inactive", "blocked"],
   },
 };
@@ -311,14 +395,23 @@ Possible error codes for types:
 ```text
 
 INVALID_TYPE
+
 INVALID_EMAIL
+
 INVALID_URL
+
 INVALID_ENUM
+
 INVALID_UUID
+
 INVALID_UUID_V1
+
 INVALID_UUID_V3
+
 INVALID_UUID_V4
+
 INVALID_UUID_V5
+
 INVALID_OBJECT_ID
 ```
 
@@ -328,7 +421,7 @@ INVALID_OBJECT_ID
 
 Validates a value using a regular expression.
 
-**Default:** Not applied when omitted.
+Default: Not applied when omitted.
 
 Example:
 
@@ -336,6 +429,7 @@ Example:
 const rules = {
   employeeCode: {
     type: "string",
+
     regex: /^[A-Z]{3}[0-9]{3}$/,
   },
 };
@@ -349,7 +443,7 @@ Error code: `REGEX_MISMATCH`
 
 Defines the minimum allowed string length.
 
-**Default:** Not applied when omitted.
+Default: Not applied when omitted.
 
 Example:
 
@@ -357,6 +451,7 @@ Example:
 const rules = {
   username: {
     type: "string",
+
     minLength: 5,
   },
 };
@@ -370,7 +465,7 @@ Error code: `MIN_LENGTH`
 
 Defines the maximum allowed string length.
 
-**Default:** Not applied when omitted.
+Default: Not applied when omitted.
 
 Example:
 
@@ -378,6 +473,7 @@ Example:
 const rules = {
   username: {
     type: "string",
+
     maxLength: 20,
   },
 };
@@ -391,7 +487,8 @@ Error code: `MAX_LENGTH`
 
 Prevents decimal numbers.
 
-**Default:** `false` both integer and decimal numbers are allowed.
+Default: `false`; both integer and decimal numbers are
+allowed.
 
 Example:
 
@@ -399,6 +496,7 @@ Example:
 const rules = {
   quantity: {
     type: "number",
+
     preventDecimal: true,
   },
 };
@@ -412,7 +510,7 @@ Error code: `DECIMAL_NOT_ALLOWED`
 
 Defines the minimum allowed numeric value.
 
-**Default:** Not applied when omitted.
+Default: Not applied when omitted.
 
 Example:
 
@@ -420,6 +518,7 @@ Example:
 const rules = {
   age: {
     type: "number",
+
     min: 18,
   },
 };
@@ -433,7 +532,7 @@ Error code: `MIN_VALUE`
 
 Defines the maximum allowed numeric value.
 
-**Default:** Not applied when omitted.
+Default: Not applied when omitted.
 
 Example:
 
@@ -441,6 +540,7 @@ Example:
 const rules = {
   quantity: {
     type: "number",
+
     max: 100,
   },
 };
@@ -454,7 +554,7 @@ Error code: `MAX_VALUE`
 
 Defines the allowed numeric range.
 
-**Default:** Not applied when omitted.
+Default: Not applied when omitted.
 
 Example:
 
@@ -462,6 +562,7 @@ Example:
 const rules = {
   marks: {
     type: "number",
+
     range: "0-100",
   },
 };
@@ -481,8 +582,10 @@ Example:
 const rules = {
   marks: {
     type: "array",
+
     elementConstraints: {
       type: "number",
+
       range: "0-100",
     },
   },
@@ -496,13 +599,18 @@ Example error:
 {
 
   path: "marks[2]",
+
   code: "OUT_OF_RANGE",
+
   message:
+
     "Attribute marks[2] should have a value between 0 and 100"
+
 }
 ```
 
 When `elementConstraintsError` is explicitly provided, the error code
+
 is: `INVALID_ARRAY_ELEMENT`
 
 Example:
@@ -511,9 +619,11 @@ Example:
 const rules = {
   marks: {
     type: "array",
+
     elementConstraints: {
       type: "number",
     },
+
     elementConstraintsError: "Every marks element must be a number",
   },
 };
@@ -531,17 +641,22 @@ Example:
 const rules = {
   address: {
     type: "object",
+
     objectAttr: {
       city: {
         mandatory: true,
+
         type: "string",
       },
+
       location: {
         type: "object",
+
         objectAttr: {
           latitude: {
             type: "number",
           },
+
           longitude: {
             type: "number",
           },
@@ -557,10 +672,15 @@ Nested errors include the complete field path:
 ```js
 
 {
+
   path: "address.location.latitude",
+
   code: "INVALID_TYPE",
+
   message:
+
     "Invalid type for attribute address.location.latitude, required number value"
+
 }
 ```
 
@@ -576,11 +696,14 @@ Example:
 const rules = {
   minSalary: {
     type: "number",
+
     dependency: {
       maxSalary: {
         setDependencyRule: (minSalary, maxSalary) => ({
           type: "number",
+
           min: minSalary + 1,
+
           minError: "maxSalary must be more than minSalary",
         }),
       },
@@ -596,171 +719,540 @@ Example error:
 {
 
   path: "maxSalary",
+
   code: "MIN_VALUE",
+
   message:
+
     "maxSalary must be more than minSalary"
+
 }
 ```
 
-## Error Codes
+---
 
-`perfectPayload()` currently exposes the following machine-readable
-validation error codes:
+### Transformations and Sanitization
 
-```text
+`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.
 
-REQUIRED
-NULL_NOT_ALLOWED
-EMPTY_OBJECT_NOT_ALLOWED
-EMPTY_ARRAY_NOT_ALLOWED
-INVALID_ARRAY_ELEMENT
-REGEX_MISMATCH
-INVALID_TYPE
-INVALID_EMAIL
-INVALID_URL
-INVALID_ENUM
-INVALID_UUID
-INVALID_UUID_V1
-INVALID_UUID_V3
-INVALID_UUID_V4
-INVALID_UUID_V5
-INVALID_OBJECT_ID
-MIN_LENGTH
-MAX_LENGTH
-DECIMAL_NOT_ALLOWED
-MIN_VALUE
-MAX_VALUE
-OUT_OF_RANGE
-```
+Supported transformation rules:
 
-These codes are designed for programmatic handling while `message`
-remains suitable for human-readable API responses.
+Rule Purpose
 
-For example:
+---
 
-```js
-const result = perfectPayload(payload, validationRules);
+`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
 
-if (!result.valid) {
-  const emailError = result.errors.find(
-    (error) => error.code === "INVALID_EMAIL",
-  );
+Transformations always run in this fixed order, regardless of the order
+in which the rule properties are written:
 
-  if (emailError) {
-    // Handle invalid email
-  }
-}
+```text
+trim
+↓
+lowercase
+↓
+uppercase
+↓
+transform(value, payload)
+↓
+validation rules
+↓
+customValidator
+↓
+validatedPayload
 ```
 
-## Custom Error Messages
+#### `trim`
 
-Every validation rule can use its corresponding custom error message.
+```js
+const payload = {
+  name: "   Kiran Poojary   ",
+};
 
-Custom messages replace the default human-readable `message` while
-keeping the same structured error format:
+const rules = {
+  name: {
+    type: "string",
+    trim: true,
+  },
+};
 
-```js
+const result = perfectPayload(payload, rules);
 
-{
-  path: "email",
-  code: "INVALID_EMAIL",
-  message: "Email address is invalid"
-}
+console.log(result.validatedPayload.name);
+// "Kiran Poojary"
+
+console.log(payload.name);
+// "   Kiran Poojary   "
 ```
 
-Example:
+`trim` applies only to string values. Non-string values are left
+unchanged.
+
+#### `lowercase`
 
 ```js
 const rules = {
   email: {
-    mandatory: true,
+    trim: true,
+    lowercase: true,
     type: "email",
-    mandatoryError: "Email is required",
-    typeError: "Email address is invalid",
   },
 };
 ```
 
-If `email` is missing:
+For `"  KIRAN@EXAMPLE.COM  "`, the validated value becomes
+`"kiran@example.com"`.
 
-```js
+#### `uppercase`
 
-{
-  path: "email",
-  code: "REQUIRED",
-  message: "Email is required"
-}
+```js
+const rules = {
+  countryCode: {
+    type: "string",
+    uppercase: true,
+  },
+};
 ```
 
-If `email` is present but invalid:
+For `"in"`, the validated value becomes `"IN"`.
 
-```js
+`lowercase: true` and `uppercase: true` cannot be enabled together for
+the same field. Doing so throws a schema configuration error.
 
-{
-  path: "email",
-  code: "INVALID_EMAIL",
-  message: "Email address is invalid"
-}
+#### `transform`
+
+Use `transform` when the built-in string transformations are not enough.
+
+```js
+const rules = {
+  phone: {
+    type: "string",
+    transform: (value) => value.replace(/\s+/g, ""),
+  },
+};
 ```
 
-### Supported Custom Error Properties
+For `"98765 43210"`, the validated value becomes `"9876543210"`.
 
-\| Validation Rule      \| Custom Error Property     \|
+The transformer receives two arguments:
 
-\| -------------------- \| ------------------------- \|
+```js
+transform: (value, payload) => {
+  return value;
+};
+```
+
+- `value` is the field value after the built-in transformations have
+  run.
+- `payload` is the current payload/object being validated.
 
-\| `mandatory`          \| `mandatoryError`          \|
+This makes cross-field transformations possible:
 
-\| `allowNull`          \| `allowNullError`          \|
+```js
+const payload = {
+  amount: 100,
+  multiplier: 2,
+};
+
+const rules = {
+  amount: {
+    transform: (value, payload) => value * payload.multiplier,
+    type: "number",
+  },
+  multiplier: {
+    type: "number",
+  },
+};
 
-\| `allowEmptyObject`   \| `emptyObjectError`        \|
+const result = perfectPayload(payload, rules);
 
-\| `allowEmptyArray`    \| `emptyArrayError`         \|
+console.log(result.validatedPayload.amount);
+// 200
+```
 
-\| `elementConstraints` \| `elementConstraintsError` \|
+A custom transformer may also change the data type before validation:
 
-\| `regex`              \| `regexError`              \|
+```js
+const rules = {
+  quantity: {
+    transform: (value) => Number(value),
+    type: "number",
+    min: 1,
+    max: 100,
+  },
+};
+```
 
-\| `type`               \| `typeError`               \|
+The transformed value is validated by the normal validation rules and is
+also the value received by `customValidator`.
 
-\| `minLength`          \| `minLengthError`          \|
+Transformations work inside `objectAttr` and `elementConstraints`, and
+transformed nested/array values are preserved in `validatedPayload`.
 
-\| `maxLength`          \| `maxLengthError`          \|
+```js
+const rules = {
+  profile: {
+    type: "object",
+    objectAttr: {
+      name: {
+        trim: true,
+        uppercase: true,
+        type: "string",
+      },
+    },
+  },
+  tags: {
+    type: "array",
+    elementConstraints: {
+      trim: true,
+      lowercase: true,
+      type: "string",
+    },
+  },
+};
+```
 
-\| `preventDecimal`     \| `preventDecimalError`     \|
+Missing optional fields are not transformed. An input value of `null` is
+not passed to transformation functions; null handling remains controlled
+by `allowNull`.
 
-\| `min`                \| `minError`                \|
+**Important:** `transform` is synchronous. A non-function transformer,
+an `async` transformer, or a transformer that returns a Promise is not
+supported and throws an error. Exceptions thrown inside the transformer
+propagate to the caller.
 
-\| `max`                \| `maxError`                \|
+### `customValidator`
 
-\| `range`              \| `rangeError`              \|
+Allows you to define custom synchronous validation logic for a field
+when the built-in validation rules are not enough.
 
-### Example with Multiple Custom Errors
+The validator receives the field value and the current payload/object
+being validated:
 
 ```js
-const payload = {
-  username: "ab",
-  age: 15,
-  score: 120,
+customValidator: (value, payload) => {
+  return true;
 };
+```
+
+The validator must return `true` to pass validation. Any other return
+value causes validation to fail.
+
+Example:
 
+```js
 const rules = {
   username: {
     mandatory: true,
+
     type: "string",
-    minLength: 3,
-    mandatoryError: "Username is required",
-    typeError: "Username must be a string",
-    minLengthError: "Username must contain at least 3 characters",
+
+    customValidator: (value) => {
+      return !value.toLowerCase().includes("admin");
+    },
+
+    customValidatorCode: "RESERVED_USERNAME",
+
+    customValidatorError: "Username cannot contain admin",
   },
-  age: {
-    type: "number",
+};
+```
+
+For this payload:
+
+```js
+const payload = {
+  username: "admin_kiran",
+};
+```
+
+The validation error is:
+
+```js
+
+{
+
+  path: "username",
+
+  code: "RESERVED_USERNAME",
+
+  message: "Username cannot contain admin"
+
+}
+```
+
+If `customValidatorCode` and `customValidatorError` are not provided,
+the default error is:
+
+```js
+
+{
+
+  path: "username",
+
+  code: "CUSTOM_VALIDATION_FAILED",
+
+  message: "Custom validation failed for attribute 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",
+
+    customValidator: (value, payload) => {
+      return value <= payload.limit;
+    },
+
+    customValidatorCode: "LIMIT_EXCEEDED",
+
+    customValidatorError: "Amount cannot exceed limit",
+  },
+};
+```
+
+`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`
+
+## Error Codes
+
+`perfectPayload()` currently exposes the following machine-readable
+
+validation error codes:
+
+```text
+
+REQUIRED
+
+NULL_NOT_ALLOWED
+
+EMPTY_OBJECT_NOT_ALLOWED
+
+EMPTY_ARRAY_NOT_ALLOWED
+
+INVALID_ARRAY_ELEMENT
+
+REGEX_MISMATCH
+
+INVALID_TYPE
+
+INVALID_EMAIL
+
+INVALID_URL
+
+INVALID_ENUM
+
+INVALID_UUID
+
+INVALID_UUID_V1
+
+INVALID_UUID_V3
+
+INVALID_UUID_V4
+
+INVALID_UUID_V5
+
+INVALID_OBJECT_ID
+
+MIN_LENGTH
+
+MAX_LENGTH
+
+DECIMAL_NOT_ALLOWED
+
+MIN_VALUE
+
+MAX_VALUE
+
+OUT_OF_RANGE
+```
+
+These codes are designed for programmatic handling while `message`
+
+remains suitable for human-readable API responses.
+
+For example:
+
+```js
+
+const result = perfectPayload(payload, validationRules);
+
+if (!result.valid) {
+
+  const emailError = result.errors.find(
+
+    (error) => error.code === "INVALID_EMAIL",
+
+  );
+
+  if (emailError) {
+
+    **// Handle invalid email**
+
+  }
+
+}
+```
+
+## Custom Error Messages
+
+Every validation rule can use its corresponding custom error message.
+
+Custom messages replace the default human-readable `message` while
+
+keeping the same structured error format:
+
+```js
+
+{
+
+  path: "email",
+
+  code: "INVALID_EMAIL",
+
+  message: "Email address is invalid"
+
+}
+```
+
+Example:
+
+```js
+const rules = {
+  email: {
+    mandatory: true,
+
+    type: "email",
+
+    mandatoryError: "Email is required",
+
+    typeError: "Email address is invalid",
+  },
+};
+```
+
+If `email` is missing:
+
+```js
+
+{
+
+  path: "email",
+
+  code: "REQUIRED",
+
+  message: "Email is required"
+
+}
+```
+
+If `email` is present but invalid:
+
+```js
+
+{
+
+  path: "email",
+
+  code: "INVALID_EMAIL",
+
+  message: "Email address is invalid"
+
+}
+```
+
+### Supported Custom Error Properties
+
+\| Validation Rule \| Custom Error Property \|
+
+\| -------------------- \| ------------------------- \|
+
+\| `mandatory` \| `mandatoryError` \|
+
+\| `allowNull` \| `allowNullError` \|
+
+\| `allowEmptyObject` \| `emptyObjectError` \|
+
+\| `allowEmptyArray` \| `emptyArrayError` \|
+
+\| `elementConstraints` \| `elementConstraintsError` \|
+
+\| `regex` \| `regexError` \|
+
+\| `type` \| `typeError` \|
+
+\| `minLength` \| `minLengthError` \|
+
+\| `maxLength` \| `maxLengthError` \|
+
+\| `preventDecimal` \| `preventDecimalError` \|
+
+\| `min` \| `minError` \|
+
+\| `max` \| `maxError` \|
+
+\| `range` \| `rangeError` \|
+
+### Example with Multiple Custom Errors
+
+```js
+const payload = {
+  username: "ab",
+
+  age: 15,
+
+  score: 120,
+};
+
+const rules = {
+  username: {
+    mandatory: true,
+
+    type: "string",
+
+    minLength: 3,
+
+    mandatoryError: "Username is required",
+
+    typeError: "Username must be a string",
+
+    minLengthError: "Username must contain at least 3 characters",
+  },
+
+  age: {
+    type: "number",
+
     min: 18,
+
     minError: "Age must be at least 18",
   },
+
   score: {
     type: "number",
+
     range: "0-100",
+
     rangeError: "Score must be between 0 and 100",
   },
 };
@@ -773,30 +1265,55 @@ Example result:
 ```js
 
 {
+
   statusCode: 400,
+
   valid: false,
+
   message:
+
     "One or more attribute values are invalid",
+
   errors: [
+
     {
+
       path: "username",
+
       code: "MIN_LENGTH",
+
       message:
+
         "Username must contain at least 3 characters"
+
     },
+
     {
+
       path: "age",
+
       code: "MIN_VALUE",
+
       message:
+
         "Age must be at least 18"
+
     },
+
     {
+
       path: "score",
+
       code: "OUT_OF_RANGE",
+
       message:
+
         "Score must be between 0 and 100"
+
     }
+
   ]
+
 }
 ```
 
@@ -812,7 +1329,9 @@ For example:
 const rules = {
   age: {
     type: "number",
+
     min: 18,
+
     minError: "You must be 18 or older",
   },
 };
@@ -823,22 +1342,30 @@ Still returns:
 ```js
 
 {
+
   path: "age",
+
   code: "MIN_VALUE",
+
   message: "You must be 18 or older"
+
 }
 ```
 
 This makes it possible to:
 
-- show custom messages to API consumers
-- use stable error codes in application logic
-- change user-facing wording without changing programmatic error
-  handling
+\- show custom messages to API consumers
+
+\- use stable error codes in application logic
+
+\- change user-facing wording without changing programmatic error
+
+handling
 
 ## Custom Response Objects
 
 `perfectPayload()` allows you to customize both the valid and invalid
+
 response objects.
 
 The third argument is the custom valid response.
@@ -852,7 +1379,9 @@ Example:
 ```js
 const customValidResponse = {
   statusCode: 201,
+
   valid: true,
+
   message: "Payload validated successfully",
 };
 
@@ -864,14 +1393,23 @@ 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
+
   }
+
 }
 ```
 
@@ -882,14 +1420,19 @@ Example:
 ```js
 const customInvalidResponse = {
   statusCode: 422,
+
   valid: false,
+
   message: "Payload validation failed",
 };
 
 const result = perfectPayload(
   payload,
+
   validationRules,
+
   undefined,
+
   customInvalidResponse,
 );
 ```
@@ -901,16 +1444,27 @@ When validation fails, `errors` is automatically added:
 {
 
   statusCode: 422,
+
   valid: false,
+
   message: "Payload validation failed",
+
   errors: [
+
     {
+
       path: "email",
+
       code: "INVALID_EMAIL",
+
       message:
+
         "Invalid email format for attribute email"
+
     }
+
   ]
+
 }
 ```
 
@@ -919,25 +1473,33 @@ When validation fails, `errors` is automatically added:
 ```js
 const customValidResponse = {
   statusCode: 201,
+
   valid: true,
+
   message: "CUSTOM_VALID_RESPONSE",
 };
 
 const customInvalidResponse = {
   statusCode: 422,
+
   valid: false,
+
   message: "CUSTOM_INVALID_RESPONSE",
 };
 
 const result = perfectPayload(
   payload,
+
   validationRules,
+
   customValidResponse,
+
   customInvalidResponse,
 );
 ```
 
 The response object you provide is preserved, while `perfectPayload()`
+
 automatically adds either:
 
 ```text
@@ -957,16 +1519,23 @@ for failed validation.
 ## Default Responses
 
 If no custom response objects are provided, the default valid response
+
 is:
 
 ```js
 
 {
+
   statusCode: 200,
+
   valid: true,
+
   validatedPayload: {
-    // validated fields
+
+    **// validated fields**
+
   }
+
 }
 ```
 
@@ -975,25 +1544,38 @@ The default invalid response is:
 ```js
 
 {
+
   statusCode: 400,
+
   valid: false,
+
   message: "One or more attribute values are invalid",
+
   errors: [
+
     {
+
       path: "field",
+
       code: "ERROR_CODE",
+
       message: "Validation error message"
+
     }
+
   ]
+
 }
 ```
 
 ## Nested Objects and Array Field Paths
 
 `perfectPayload()` returns the exact location of a validation failure
+
 through the `path` property.
 
 This makes validation errors easier to map to API fields, forms, logs,
+
 and frontend components.
 
 ### Top-Level Field
@@ -1011,9 +1593,13 @@ An error can be returned as:
 ```js
 
 {
+
   path: "email",
+
   code: "INVALID_EMAIL",
+
   message: "Invalid email format for attribute email"
+
 }
 ```
 
@@ -1025,8 +1611,10 @@ Use `objectAttr` to validate properties inside an object.
 const payload = {
   address: {
     city: "Bengaluru",
+
     location: {
       latitude: "12.9716",
+
       longitude: 77.5946,
     },
   },
@@ -1035,16 +1623,20 @@ const payload = {
 const rules = {
   address: {
     type: "object",
+
     objectAttr: {
       city: {
         type: "string",
       },
+
       location: {
         type: "object",
+
         objectAttr: {
           latitude: {
             type: "number",
           },
+
           longitude: {
             type: "number",
           },
@@ -1058,15 +1650,21 @@ const result = perfectPayload(payload, rules);
 ```
 
 Because `latitude` is a string instead of a number, the error contains
+
 its complete nested path:
 
 ```js
 
 {
+
   path: "address.location.latitude",
+
   code: "INVALID_TYPE",
+
   message:
+
     "Invalid type for attribute address.location.latitude, required number value"
+
 }
 ```
 
@@ -1075,13 +1673,16 @@ Nested paths use dot notation:
 ```text
 
 address.city
+
 address.location.latitude
+
 address.location.longitude
 ```
 
 ### Array Elements
 
 When `elementConstraints` validation fails, the array index is included
+
 in the error path.
 
 ```js
@@ -1092,8 +1693,10 @@ const payload = {
 const rules = {
   marks: {
     type: "array",
+
     elementConstraints: {
       type: "number",
+
       range: "0-100",
     },
   },
@@ -1107,10 +1710,15 @@ The invalid third element is reported as:
 ```js
 
 {
+
   path: "marks[2]",
+
   code: "OUT_OF_RANGE",
+
   message:
+
     "Attribute marks[2] should have a value between 0 and 100"
+
 }
 ```
 
@@ -1119,7 +1727,9 @@ Array paths use zero-based indexes:
 ```text
 
 marks[0]
+
 marks[1]
+
 marks[2]
 ```
 
@@ -1132,16 +1742,20 @@ For example:
 ```text
 
 products[0].quantity
+
 products[1].quantity
+
 products[2].price
 ```
 
 This provides enough information for consumers to identify the exact
+
 field that caused the validation error.
 
 ### Why Structured Paths Are Useful
 
 Instead of parsing an error message to determine which field failed,
+
 applications can directly use:
 
 ```js
@@ -1177,246 +1791,421 @@ Result:
 {
 
   "email": "Invalid email format for attribute email",
+
   "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"
 
 }
 ```
 
-## Examples And Usage
+## Examples and Usage
 
 ### Sample Validation Rule
 
 sample-1
 
-```javascript
+```js
 
 {
 
   firstName: {
+
     mandatory: true,
+
     allowNull: false,
+
     type: "string",
+
     minLength: 3,
-    minLengthError:"First name must have minimum 3 characters."
+
+    minLengthError: "First name must have minimum 3 characters."
+
   },
+
   lastName: {
+
     mandatory: false,
+
     allowNull: true,
+
     type: "string",
+
   },
+
   email: {
+
     mandatory: true,
+
     allowNull: false,
+
     type: "email",
+
   },
+
   phone: {
+
     mandatory: true,
+
     allowNull: false,
+
     type: "string",
+
   },
+
   age: {
+
     mandatory: false,
+
     type: "number",
+
     min: 1,
+
     max: 120,
+
   },
+
 };
 ```
 
 sample-2
 
-```javascript
+```js
 
 {
+
   id: {
+
     mandatory: true,
+
     allowNull: true,
+
     type: "uuidv4",
+
   },
+
   batchId: {
+
     mandatory: true,
+
     allowNull: true,
+
     type: "objectId",
+
   },
+
   firstName: {
+
     mandatory: true,
+
     type: "string",
+
     minLength: 3,
+
   },
+
   lastName: {
+
     mandatory: false,
+
     allowNull: true,
+
     type: "string",
+
   },
+
   age: {
+
     type: "number",
+
     min: 0.1,
+
     max: 120,
+
   },
+
   isAdult: {
+
     type: "boolean",
+
   },
+
   totalWins: {
+
     type: "number",
+
     min: 0,
+
     preventDecimal: true,
+
   },
+
   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: {
+
     type: "url",
+
   },
+
   accountStatus: {
+
     type: "enum",
+
     enumValues: ["Active", "Inactive", 200],
+
   },
+
   marks: {
+
     range: "0-100",
+
   },
+
   allMarks: {
+
     type: "array",
+
     allowEmptyArray: false,
+
     elementConstraints: {
+
       type: "number",
+
       allowNull: false,
+
       range: "0-100",
+
     },
+
   },
+
   totalScore: {
+
     type: "number",
+
     dependency: {
+
       result: {
+
         setDependencyRule: (totalScore, result) => {
+
           return { mandatory: true, allowNull: false, type: "string" };
+
         },
+
       },
+
     },
+
   },
+
   result: {
+
     type: "string",
+
     dependency: {
+
       totalScore: {
+
         setDependencyRule: (result, totalScore) => {
+
           return { mandatory: true, allowNull: false, type: "number" };
+
         },
+
       },
+
     },
+
   },
+
   minSalary: {
+
     mandatory: true,
+
     min: 1,
+
     type: "number",
+
     dependency: {
+
       maxSalary: {
+
         setDependencyRule: (minSalary, maxSalary) => {
+
           return {
+
             mandatory: true,
+
             min: minSalary + 1,
+
             minError: "maxSalary must be more than minSalary",
+
           };
+
         },
+
       },
+
     },
+
   },
+
   maxSalary: {
+
     dependency: {
+
       minSalary: {
+
         setDependencyRule: (maxSalary, minSalary) => {
+
           return {
+
             mandatory: true,
+
             max: maxSalary - 1,
+
             maxError: "minSalary must be less than maxSalary",
+
           };
+
         },
+
       },
+
     },
+
   },
+
   address: {
+
     mandatory: true,
+
     type: "object",
+
     allowEmptyObject: false,
+
     objectAttr: {
+
       country: { mandatory: true, type: "string" },
+
       state: {
+
         mandatory: true,
+
         type: "string",
+
       },
+
       city: {},
+
       zip: {
+
         mandatory: true,
+
         type: "string",
+
       },
+
       position: {
+
         mandatory: true,
+
         type: "object",
+
         allowEmptyObject: false,
+
         objectAttr: {
+
           lattitude: { mandatory: true, type: "number" },
+
           longitude: {
+
             mandatory: true,
+
             type: "number",
+
           },
+
         },
+
       },
+
     },
+
   },
+
 }
 ```
 
 ### Usage
 
-#### creating your route with payload validation middleware
+#### Creating a route with payload validation middleware
 
-```javascript
+```js
 
-//Here validatePayload is your middleware function, where you're invoking perfect payload
+**// validatePayload is the middleware that invokes perfectPayload()**
 
 router.post(
+
   "/payload-validation",
+
   validatePayload({ rule: <your validation rule json object> }),
+
   (req, res) => res.send("OK")
+
 );
 ```
 
-#### 1 Use perfect-payload in your middleware like below(for MODULE JS)
+#### ES Modules middleware example
 
-```javascript
-import { perfectPayloadV1 } from "perfect-payload";
+```js
+import { perfectPayload } from "perfect-payload";
 
 export const validatePayload = ({ rule }) => {
   return (req, res, next) => {
     try {
-      const { statusCode, ...response } = perfectPayloadV1(req?.body, rule);
+      const { statusCode, ...response } = perfectPayload(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" });
     }
   };
 };
 ```
 
-#### 2 Use perfect-payload in your middleware like below(for COMMON JS)
+#### CommonJS middleware example
 
-```javascript
+```js
 function validatePayload({ rule }) {
   return async (req, res, next) => {
     try {
-      const { perfectPayloadV1 } = await import("perfect-payload");
-      const { statusCode, ...response } = perfectPayloadV1(req?.body, rule);
+      const { perfectPayload } = await import("perfect-payload");
+
+      const { statusCode, ...response } = perfectPayload(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" });
     }
   };
@@ -1428,5 +2217,7 @@ module.exports = { validatePayload };
 ---
 
 This documentation provides a comprehensive guide to using the data
+
 validation module effectively. Ensure to define your validation rules
+
 clearly to maintain data quality and consistency in your applications.