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

package/README.md

@@ -4,14 +4,16 @@ 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.
+paths, synchronous custom validators, synchronous payload
+transformation/sanitization, array size constraints, and deeply nested
+array/object validation while keeping the validation schema simple.
 
 ## Quick Links
 
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
 - [Validation Rules](#validation-rules)
+- [Array Size and Nested Validation](#array-size-and-nested-validation)
 - [Transformations and
   Sanitization](#transformations-and-sanitization)
 - [Custom Validators](#customvalidator)
@@ -293,6 +295,68 @@ Error code: `EMPTY_ARRAY_NOT_ALLOWED`
 
 ---
 
+### `minItems`
+
+Defines the minimum number of items required in an array.
+
+Default: Not applied when omitted.
+
+```js
+const rules = {
+  tags: {
+    type: "array",
+    minItems: 2,
+  },
+};
+```
+
+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 `[]`.
+
+Error code: `MIN_ITEMS`
+
+---
+
+### `maxItems`
+
+Defines the maximum number of items allowed in an array.
+
+Default: Not applied when omitted.
+
+```js
+const rules = {
+  tags: {
+    type: "array",
+    maxItems: 5,
+  },
+};
+```
+
+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)"
+}
+```
+
+`minItems` and `maxItems` can be used together.
+
+Error code: `MAX_ITEMS`
+
+---
+
 ### `type`
 
 Validates the expected data type.
@@ -415,6 +479,8 @@ INVALID_UUID_V5
 INVALID_OBJECT_ID
 ```
 
+For `type: "number"`, `NaN` is rejected as `INVALID_TYPE`.
+
 ---
 
 ### `regex`
@@ -731,6 +797,103 @@ 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.
+
+### Array size constraints
+
+Use `minItems` and `maxItems` with `type: "array"`:
+
+```js
+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 },
+      },
+    },
+  },
+};
+```
+
+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:
+
+```text
+products[1].quantity
+```
+
+### Deeply nested arrays and objects
+
+`objectAttr` and `elementConstraints` can be combined recursively:
+
+```js
+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 },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+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:
+
+```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 and Sanitization
 
 `perfectPayload()` can transform a field before its validation rules
@@ -922,9 +1085,17 @@ not passed to transformation functions; null handling remains controlled
 by `allowNull`.
 
 **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.
+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 propagate to the caller.
+
+For example, returning `undefined` throws:
+
+```text
+perfect-payload:- transform must not return undefined for attribute username
+```
 
 ### `customValidator`
 
@@ -1051,6 +1222,10 @@ EMPTY_OBJECT_NOT_ALLOWED
 
 EMPTY_ARRAY_NOT_ALLOWED
 
+MIN_ITEMS
+
+MAX_ITEMS
+
 INVALID_ARRAY_ELEMENT
 
 REGEX_MISMATCH
@@ -1086,6 +1261,8 @@ MIN_VALUE
 MAX_VALUE
 
 OUT_OF_RANGE
+
+CUSTOM_VALIDATION_FAILED
 ```
 
 These codes are designed for programmatic handling while `message`
@@ -1733,6 +1910,8 @@ 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`.
+
 ### Nested Fields Inside Arrays
 
 Paths can also identify fields inside array elements.

package/index.js

@@ -633,6 +633,12 @@ function perfectPayloadStructured(
         );
       }
 
+      if (transformedValue === undefined) {
+        throw new Error(
+          `perfect-payload:- transform must not return undefined for attribute ${attributePath}`,
+        );
+      }
+
       attributeValue = transformedValue;
     }
     // TRANSFORMATIONS END
@@ -803,6 +809,45 @@ function perfectPayloadStructured(
 
           break;
 
+        case "minItems":
+          if (
+            addNextError &&
+            attrExist &&
+            attributeValue !== null &&
+            isArray(attributeValue) &&
+            attributeValue.length < attributeRules[ruleName]
+          ) {
+            addStructuredError(
+              rowErrors,
+              attributePath,
+              "MIN_ITEMS",
+              `Attribute ${attributePath} must contain at least ${attributeRules[ruleName]} item(s)`,
+            );
+
+            addNextError = false;
+          }
+
+          break;
+
+        case "maxItems":
+          if (
+            addNextError &&
+            attrExist &&
+            attributeValue !== null &&
+            isArray(attributeValue) &&
+            attributeValue.length > attributeRules[ruleName]
+          ) {
+            addStructuredError(
+              rowErrors,
+              attributePath,
+              "MAX_ITEMS",
+              `Attribute ${attributePath} must contain at most ${attributeRules[ruleName]} item(s)`,
+            );
+
+            addNextError = false;
+          }
+
+          break;
         // ==================================================
         // REGEX
         // ==================================================
@@ -837,7 +882,10 @@ function perfectPayloadStructured(
 
               switch (expectedType) {
                 case "number":
-                  if (!isNumber(attributeValue)) {
+                  if (
+                    !isNumber(attributeValue) ||
+                    Number.isNaN(attributeValue)
+                  ) {
                     addStructuredError(
                       rowErrors,
                       attributePath,
@@ -854,7 +902,6 @@ function perfectPayloadStructured(
                   }
 
                   break;
-
                 case "string":
                   if (!isString(attributeValue)) {
                     addStructuredError(

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "perfect-payload",
-  "version": "1.4.0-beta.0",
+  "version": "1.5.0-beta.1",
   "type": "module",
   "description": "Lightweight JSON payload validation library with structured errors, nested validation, field paths, and customizable validation rules.",
   "main": "index.js",
   "scripts": {
     "test": "jest"
   },
+  "files": [
+    "index.js"
+  ],
+  "jest": {
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/test.js",
+      "/testingV1.js"
+    ]
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kiranpoojary/perfect-payload.git"

package/.babelrc

@@ -1,4 +0,0 @@
-{
-    "presets": ["@babel/preset-env"]
-  }
-  

package/.github/workflows/publish.yml

@@ -1,332 +0,0 @@
-name: Stage npm package
-
-on:
-  push:
-    # Beta:
-    # Run for pushes to every branch except main.
-    branches:
-      - "**"
-      - "!main"
-
-    # Production:
-    # Run only when a version tag is pushed.
-    # Examples: v1.3.0, v1.3.1, v2.0.0
-    tags:
-      - "v*.*.*"
-
-permissions:
-  contents: read
-  id-token: write
-
-jobs:
-  # ==========================================================
-  # 1. PACKAGE INFO
-  # ==========================================================
-  package-info:
-    name: Package Info
-    runs-on: ubuntu-latest
-
-    outputs:
-      name: ${{ steps.package.outputs.name }}
-      version: ${{ steps.package.outputs.version }}
-      release_type: ${{ steps.package.outputs.release_type }}
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v7
-
-      - name: Read package information
-        id: package
-        shell: bash
-        run: |
-          NAME=$(node -p "require('./package.json').name")
-          VERSION=$(node -p "require('./package.json').version")
-
-          echo "name=$NAME" >> "$GITHUB_OUTPUT"
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-
-          if [[ "$GITHUB_REF_TYPE" == "tag" ]]; then
-            RELEASE_TYPE="production"
-          else
-            RELEASE_TYPE="beta"
-          fi
-
-          echo "release_type=$RELEASE_TYPE" >> "$GITHUB_OUTPUT"
-
-          echo "======================================"
-          echo "PACKAGE INFORMATION"
-          echo "======================================"
-          echo "Package:      $NAME"
-          echo "Version:      $VERSION"
-          echo "Release type: $RELEASE_TYPE"
-          echo "Git ref:      $GITHUB_REF_NAME"
-          echo "Git ref type: $GITHUB_REF_TYPE"
-          echo "======================================"
-
-  # ==========================================================
-  # 2. VALIDATE RELEASE
-  # ==========================================================
-  validate-release:
-    name: Validate Release
-    needs: package-info
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Validate branch / tag and version
-        shell: bash
-        run: |
-          VERSION="${{ needs.package-info.outputs.version }}"
-
-          echo "Version:  $VERSION"
-          echo "Ref:      $GITHUB_REF_NAME"
-          echo "Ref type: $GITHUB_REF_TYPE"
-
-          # --------------------------------------------------
-          # PRODUCTION
-          # Must come from a Git tag.
-          #
-          # Tag:             v1.3.0
-          # package version: 1.3.0
-          # --------------------------------------------------
-          if [[ "$GITHUB_REF_TYPE" == "tag" ]]; then
-
-            TAG="$GITHUB_REF_NAME"
-
-            if [[ "$VERSION" == *"-beta"* ]]; then
-              echo "::error::Production releases cannot contain -beta."
-              echo "::error::Current package version: $VERSION"
-              exit 1
-            fi
-
-            EXPECTED_TAG="v$VERSION"
-
-            if [[ "$TAG" != "$EXPECTED_TAG" ]]; then
-              echo "::error::Git tag does not match package.json version."
-              echo "::error::Tag:          $TAG"
-              echo "::error::Expected tag: $EXPECTED_TAG"
-              exit 1
-            fi
-
-            echo "Valid production release."
-            echo "Tag $TAG matches package version $VERSION."
-
-          # --------------------------------------------------
-          # BETA
-          # Any non-main branch.
-          #
-          # Example:
-          # feature/custom-validator
-          # package version: 1.3.0-beta.0
-          # --------------------------------------------------
-          else
-
-            if [[ "$GITHUB_REF_NAME" == "main" ]]; then
-              echo "::error::Production releases from main pushes are disabled."
-              echo "::error::Create a Git tag to release production."
-              exit 1
-            fi
-
-            if [[ "$VERSION" != *"-beta"* ]]; then
-              echo "::error::Non-main branches must contain a beta version."
-              echo "::error::Current version: $VERSION"
-              echo "::error::Expected something like 1.3.0-beta.0"
-              exit 1
-            fi
-
-            echo "Valid beta release."
-            echo "Branch:  $GITHUB_REF_NAME"
-            echo "Version: $VERSION"
-
-          fi
-
-  # ==========================================================
-  # 3. INSTALL DEPENDENCIES
-  # ==========================================================
-  install:
-    name: Install Dependencies
-    needs:
-      - package-info
-      - validate-release
-
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v7
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v7
-        with:
-          node-version: 24
-          registry-url: https://registry.npmjs.org
-          package-manager-cache: false
-
-      - name: Setup npm
-        run: npm install --global npm@11.19.1
-
-      - name: Verify Node and npm versions
-        run: |
-          node -v
-          npm -v
-
-      - name: Install dependencies
-        run: npm ci
-
-  # ==========================================================
-  # 4. RUN TESTS
-  # ==========================================================
-  test:
-    name: Run Tests
-    needs: install
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v7
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v7
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm test -- --passWithNoTests
-
-  # ==========================================================
-  # 5. CHECK NPM VERSION
-  # ==========================================================
-  check-npm:
-    name: Check npm Version
-    needs:
-      - package-info
-      - validate-release
-      - test
-
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Setup Node.js
-        uses: actions/setup-node@v7
-        with:
-          node-version: 24
-          registry-url: https://registry.npmjs.org
-          package-manager-cache: false
-
-      - name: Check whether version already exists
-        shell: bash
-        run: |
-          NAME="${{ needs.package-info.outputs.name }}"
-          VERSION="${{ needs.package-info.outputs.version }}"
-
-          echo "Checking npm for $NAME@$VERSION..."
-
-          if npm view "$NAME@$VERSION" version >/dev/null 2>&1; then
-            echo "::error::$NAME@$VERSION is already published."
-            echo "::error::Use a new package version."
-            exit 1
-          fi
-
-          echo "$NAME@$VERSION is not published."
-          echo "Release is ready to stage."
-
-  # ==========================================================
-  # 6. STAGE NPM PACKAGE
-  #
-  # This environment can optionally have a GitHub
-  # Required Reviewer configured.
-  #
-  # npm itself still requires approval + 2FA after staging.
-  # ==========================================================
-  stage-npm:
-    name: Stage npm Package
-    needs:
-      - package-info
-      - check-npm
-
-    runs-on: ubuntu-latest
-
-    environment:
-      name: npm-stage
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v7
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v7
-        with:
-          node-version: 24
-          registry-url: https://registry.npmjs.org
-          package-manager-cache: false
-
-      - name: Setup npm
-        run: npm install --global npm@11.19.1
-
-      - name: Show release information
-        shell: bash
-        run: |
-          echo "======================================"
-          echo "READY TO STAGE"
-          echo "======================================"
-          echo "Package: ${{ needs.package-info.outputs.name }}"
-          echo "Version: ${{ needs.package-info.outputs.version }}"
-          echo "Type:    ${{ needs.package-info.outputs.release_type }}"
-          echo "Ref:     $GITHUB_REF_NAME"
-          echo "======================================"
-
-      # ------------------------------------------------------
-      # BETA
-      # Triggered only from non-main branch pushes.
-      # ------------------------------------------------------
-      - name: Stage Beta Package
-        if: >
-          github.ref_type == 'branch' &&
-          needs.package-info.outputs.release_type == 'beta'
-        run: |
-          echo "Staging beta package..."
-          echo "${{ needs.package-info.outputs.name }}@${{ needs.package-info.outputs.version }}"
-
-          npm stage publish --tag beta
-
-      # ------------------------------------------------------
-      # PRODUCTION
-      # Triggered ONLY from Git tags.
-      # ------------------------------------------------------
-      - name: Stage Production Package
-        if: >
-          github.ref_type == 'tag' &&
-          needs.package-info.outputs.release_type == 'production'
-        run: |
-          echo "Staging production package..."
-          echo "${{ needs.package-info.outputs.name }}@${{ needs.package-info.outputs.version }}"
-
-          npm stage publish
-
-  # ==========================================================
-  # 7. COMPLETION
-  # ==========================================================
-  complete:
-    name: npm Package Staged
-    needs:
-      - package-info
-      - stage-npm
-
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Staging completed
-        run: |
-          echo "======================================"
-          echo "NPM STAGING COMPLETED"
-          echo "======================================"
-          echo "Package: ${{ needs.package-info.outputs.name }}"
-          echo "Version: ${{ needs.package-info.outputs.version }}"
-          echo "Type:    ${{ needs.package-info.outputs.release_type }}"
-          echo ""
-          echo "The package has been staged on npm."
-          echo "Review and approve it on npm with 2FA."
-          echo "======================================"