json-mask-validator 1.0.3

package/README.md

@@ -0,0 +1,125 @@
+# json-mask-validator
+
+A lightweight, high-performance Node.js utility for validating JSON payloads against a JSON Schema and masking/filtering fields using dynamic dot-notation paths. It seamlessly supports deep nesting, structural preservation, and **dynamic array mapping traversal**.
+
+## Features
+
+- 🛡️ **Schema Validation:** Built on top of `ajv` (the fastest JSON Schema validator for Node.js).
+- 🔍 **Dynamic Filtering:** Mask objects to retain only explicitly requested field paths.
+- 🌳 **Structure Preservation:** Keeps original parent hierarchies, nesting depths, and structures intact.
+- 🔄 **Smart Array Traversal:** Automatically detects mid-path arrays and maps fields across every element inside the collection.
+
+---
+
+## Installation
+
+```bash
+npm install json-mask-validator
+```
+
+Make sure your project is configured for ES Modules (`"type": "module"` in your `package.json`), or use a bundler/transpiler like TypeScript/Babel.
+
+---
+
+## Usage
+
+### 1. Standard Nested Objects
+Filter deeply nested structures without losing their shape.
+
+```javascript
+import { maskAndValidate } from 'json-mask-validator';
+
+const sampleData = {
+  a: {
+    b: {
+      c: "ddc",
+      d: [1, 2, 3, 4]
+    },
+    x: "fc"
+  }
+};
+
+const sampleSchema = {
+  type: "object",
+  properties: {
+    a: { type: "object" }
+  },
+  required: ["a"]
+};
+
+// Mask a deep sub-property
+const res1 = maskAndValidate(sampleData, ['a.b.d'], sampleSchema);
+console.log(res1);
+// Output: { a: { b: { d: [1, 2, 3, 4] } } }
+
+// Mask an intermediate parent object
+const res2 = maskAndValidate(sampleData, ['a.x'], sampleSchema);
+console.log(res2);
+// Output: { a: { x: "fc" } }
+```
+
+### 2. Smart Array Traversal
+If a path targets a property inside an array of objects, the package automatically iterates through the array items to extract and re-structure the target field.
+
+```javascript
+import { maskAndValidate } from 'json-mask-validator';
+
+const arrayData = {
+  a: [
+    { b: "scd", c: "df" },
+    { b: "rt", c: "gh" }
+  ]
+};
+
+const schema = {
+  type: "object",
+  properties: {
+    a: {
+      type: "array",
+      items: { type: "object" }
+    }
+  }
+};
+
+// Requesting 'a.b' automatically loops through the collection in 'a'
+const result = maskAndValidate(arrayData, ['a.b'], schema);
+console.log(JSON.stringify(result));
+// Output: { "a": [{ "b": "scd" }, { "b": "rt" }] }
+```
+
+### 3. Multiple Paths Extraction
+Combine multiple paths to pick and choose specific disjointed sections of the JSON tree.
+
+```javascript
+const combined = maskAndValidate(sampleData, ['a.b.c', 'a.x'], sampleSchema);
+console.log(combined);
+// Output: { a: { b: { c: "ddc" }, x: "fc" } }
+```
+
+---
+
+## API Reference
+
+### `maskAndValidate(jsonData, paths, schema)`
+
+Validates the input structural integrity, filters the fields, and reconstructs the mapped result object.
+
+#### Parameters:
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `jsonData` | `Object` | The input JSON object to parse and filter. |
+| `paths` | `Array<string>` | An array of dot-notation string paths to preserve (e.g., `['a.b.c', 'user.profile.id']`). |
+| `schema` | `Object` | A valid standard **JSON Schema** object compatible with Ajv. |
+
+#### Returns:
+- `Object`: A new object containing only the matched structure and values.
+
+#### Throws:
+- `Error`: Throws an explicit schema validation error if the incoming `jsonData` violates the rules defined in `schema`.
+
+---
+
+## License
+
+MIT © Abhijith C U

package/index.js

@@ -0,0 +1,95 @@
+import Ajv from 'ajv';
+
+const ajv = new Ajv();
+
+/**
+ * Recursively extracts data based on a path array, handling mid-path arrays gracefully.
+ */
+function getDeepValue(source, pathArray) {
+    if (source === null || source === undefined) return undefined;
+    if (pathArray.length === 0) return source;
+
+    const [currentKey, ...remainingPath] = pathArray;
+
+    // If the current source is an array, we need to extract the path from EVERY item inside it
+    if (Array.isArray(source)) {
+        return source
+            .map(item => getDeepValue(item, pathArray)) // pass the same path array down to items
+            .filter(val => val !== undefined);
+    }
+
+    // If it's an object, dig deeper
+    if (typeof source === 'object') {
+        const nextValue = source[currentKey];
+        
+        // If the next value is an array, we handle it sequentially
+        if (Array.isArray(nextValue)) {
+            return nextValue.map(item => getDeepValue(item, remainingPath));
+        }
+        
+        return getDeepValue(nextValue, remainingPath);
+    }
+
+    return undefined;
+}
+
+/**
+ * Recursively builds the target object/array structure based on the path and extracted value.
+ */
+function setDeepValue(target, pathArray, value) {
+    if (pathArray.length === 0 || value === undefined) return;
+
+    const [currentKey, ...remainingPath] = pathArray;
+
+    // Case 1: The value provided is an array resulting from an array-mapping traversal
+    if (Array.isArray(value) && remainingPath.length > 0) {
+        if (!target[currentKey]) {
+            target[currentKey] = [];
+        }
+
+        value.forEach((subValue, index) => {
+            if (!target[currentKey][index]) {
+                target[currentKey][index] = {};
+            }
+            setDeepValue(target[currentKey][index], remainingPath, subValue);
+        });
+        return;
+    }
+
+    // Case 2: Standard leaf-node assignment
+    if (remainingPath.length === 0) {
+        target[currentKey] = JSON.parse(JSON.stringify(value));
+        return;
+    }
+
+    // Case 3: Standard nested object traversal
+    if (!target[currentKey]) {
+        target[currentKey] = {};
+    }
+    setDeepValue(target[currentKey], remainingPath, value);
+}
+
+/**
+ * Main export function
+ */
+export function maskAndValidate(jsonData, paths, schema) {
+    const validate = ajv.compile(schema);
+    const valid = validate(jsonData);
+    
+    if (!valid) {
+        throw new Error(`Schema Validation Failed: ${ajv.errorsText(validate.errors)}`);
+    }
+
+    const result = {};
+
+    for (const path of paths) {
+        const pathArray = path.split('.');
+        const val = getDeepValue(jsonData, pathArray);
+
+        if (val !== undefined) {
+            setDeepValue(result, pathArray, val);
+        }
+    }
+
+    return result;
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "json-mask-validator", 
+  "version": "1.0.3",
+  "description": "A lightweight Node.js utility to validate JSON data against a schema and extract specific fields while preserving their nested structures and automatically traversing arrays.",
+  "type": "module",
+  "main": "index.js",
+  "keywords": [
+    "json",
+    "mask",
+    "filter",
+    "validator",
+    "ajv",
+    "dot-notation"
+  ],
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "author": "Abhijith C U <abhijithcucu@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "ajv": "8.12.0"
+  }
+}