Injiver 1512 js claim 169 mapper

js/Readme.md

@@ -4,15 +4,42 @@ Pixelpass is a library which can do multiple things which are listed below,
 
 - Given a data → `generateQRCode` → returns a QR Code.
 
-- Given a JSON String → `generateQRData` → Gives back CBOR encoded data.
+- Given a JSON String → `generateQRData` → Gives back CBOR-encoded data.
 
-- Given a CBOR encoded data as byte array → `decode` → Gives back JSON String.
-
+- Given a CBOR-encoded data as byte array → `decode` → Gives back JSON String.
 - Given data as byteArray → `decodeBinary` → Gives back JSON String.
-
-- Given a JSON and Mapper → `getMappedData` → Gives back CBOR encoded data.
+- Given a JSON and Mapper → `getMappedData` → Gives back CBOR-encoded data or mapped JSON.
 
-- Given a CBOR encoded data and Mapper → `decodeMappedData` → Gives back a JSON.
+- Given a CBOR-encoded data and Mapper → `decodeMappedData` → Gives back a JSON.
+
+## 🚨 Breaking Changes (`0.8.0` and later)
+
+Starting from version `0.8.0`, the following APIs have undergone changes
+to support advanced key/value compression and depth-aware decoding.
+
+These updates improve interoperability and reduce CBOR payload sizes.
+
+## 🔄 API Contract Changes
+
+### 1. `getMappedData` --- Signature Change
+
+#### Old (Deprecated)
+
+`getMappedData(jsonData, mapper, cborEnable?)`
+
+#### New (Recommended)
+
+`getMappedData(jsonData, keyMapper, valueMapper, cborEnable?)`
+
+### 2. `decodeMappedData` --- Signature Change
+
+#### Old (Deprecated)
+
+`decodeMappedData(data, mapper)`
+
+#### New (Recommended)
+
+`decodeMappedData(data, keyMapper, valueMapperFunction?)`.
 
 ## Features
 
@@ -24,15 +51,18 @@ Pixelpass is a library which can do multiple things which are listed below,
 
 - When JSON and a Mapper is given, it maps the JSON with Mapper and then does the CBOR encode/decode which further reduces the size of the data.
 
-## Usage 
+## Usage
+
 `npm i @mosip/pixelpass`
 
 [npm](https://www.npmjs.com/package/@mosip/pixelpass)
 
 ## Example
+
 Prerequisites
-* [nodejs](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)
-* [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+
+- [nodejs](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)
+- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 
 To run the example app copy the below command and paste it to your terminal.
 
@@ -41,23 +71,25 @@ git clone https://github.com/mosip/pixelpass.git && cd pixelpass && git checkout
 ```
 
 ## APIs
+
 ### generateQRCode( data, ecc , header )
 
- - `data` - Data needs to be compressed and encoded.
+- `data` - Data needs to be compressed and encoded.
 
- - `ecc` - Error Correction Level for the QR generated. defaults to `"L"`.
+- `ecc` - Error Correction Level for the QR generated. defaults to `"L"`.
 
- - `header` - Data header need to be prepend to identify the encoded data. defaults to `""`.
+- `header` - Data header need to be prepend to identify the encoded data. defaults to `""`.
 
 ```javascript
-import { generateQRCode } from '@mosip/pixelpass';
+import { generateQRCode } from "@mosip/pixelpass";
 
 const data = "Hello";
 const qrCode = generateQRCode(data, ecc, header);
 
 // ecc is Error Correction Level for the QR generated. defaults to "L".
 // header defaults to empty string if not passed.
 ```
+
 The `generateQRCode` takes a data, ECC (Error correction level) which when not passed defaults to L and header which defaults to empty string if not passed.
 Returns a base64 encoded PNG image.
 
@@ -68,30 +100,32 @@ Returns a base64 encoded PNG image.
 - `header` - Data header need to be prepend to identify the encoded data. defaults to `""`.
 
 ```javascript
-import { generateQRData } from '@mosip/pixelpass';
+import { generateQRData } from "@mosip/pixelpass";
 
-const jsonString = "{\"name\":\"Steve\",\"id\":\"1\",\"l_name\":\"jobs\"}";
+const jsonString = '{"name":"Steve","id":"1","l_name":"jobs"}';
 const header = "jsonstring";
 
 const encodedCBORData = generateQRData(jsonString, header);
 
 // header defaults to empty string if not passed.
 ```
+
 The `generateQRData` takes a valid JSON string and a header which when not passed defaults to an empty string.
 This API will return a base45 encoded string which is `Compressed > CBOR Encoded > Base45 Encoded`.
 
-
 ### decode( data )
 
 - `data` - Data needs to be decoded and decompressed without header.
 
 ```javascript
-import { decode } from '@mosip/pixelpass';
+import { decode } from "@mosip/pixelpass";
 
-const b45EncodedData = "NCFWTL$PPB$PN$AWGAE%5UW5A%ADFAHR9 IE:GG6ZJJCL2.AJKAMHA100+8S.1";
+const b45EncodedData =
+  "NCFWTL$PPB$PN$AWGAE%5UW5A%ADFAHR9 IE:GG6ZJJCL2.AJKAMHA100+8S.1";
 const jsonString = decode(b45EncodedData);
 ```
-The `decode` will take a `string`  as parameter and gives us decoded JSON string which is Base45 `Decoded > CBOR Decoded > Decompressed`.
+
+The `decode` will take a `string` as parameter and gives us decoded JSON string which is Base45 `Decoded > CBOR Decoded > Decompressed`.
 
 ### decodeBinary( data )
 
@@ -103,52 +137,137 @@ import { decodeBinary } from '@mosip/pixelpass';
 const zipdata = <zip-byte-array>;
 const decompressedData = decodeBinary(zipdata);
 ```
-The `decodeBinary` will take a `UInt8ByteArray`  as parameter and gives us unzipped string. Currently only zip binary data is only supported.
 
+The `decodeBinary` will take a `UInt8ByteArray` as parameter and gives us unzipped string. Currently only zip binary data is supported.
 
-### getMappedData( jsonData, mapper, cborEnable );
+### getMappedData( jsonData, keyMapper, valueMapper, cborEnable )
 
-- `jsonData` - A JSON data.
-- `mapper` - A Map which is used to map with the JSON.
+- `jsonData` - A JSON data or an array of JSON data.
+- `keyMapper` - A Map which is used to map the keys of the JSON.
+- `valueMapper` - A Map which is used to map the values of the JSON.
 - `cborEnable` - A Boolean which is used to enable or disable CBOR encoding on mapped data. Defaults to `false` if not provided.
 
 ```javascript
-import { getMappedData } from '@mosip/pixelpass';
+import { getMappedData } from "@mosip/pixelpass";
 
-const jsonData = {"name": "Jhon", "id": "207", "l_name": "Honay"};
-const mapper = {"id": "1", "name": "2", "l_name": "3"};
+const jsonData = { name: "Jhon", id: "207", l_name: "Honay" };
+const keyMapper = { id: "1", name: "2", l_name: "3" };
+const valueMapper = {}; // Optional value mapping
 
-const byteBuffer = getMappedData(jsonData, mapper,true);
+const result = getMappedData(jsonData, keyMapper, valueMapper, true);
 
-const cborEncodedString = byteBuffer.toString('hex');
+// If cborEnable is true, result is a hex string of CBOR-encoded data
+const cborEncodedString = result;
+
+// If cborEnable is false, result is the mapped JSON object
+const mappedJson = getMappedData(jsonData, keyMapper, valueMapper, false);
 ```
-The `getMappedData` takes 3 arguments a JSON and a map with which we will be creating a new map with keys and values mapped based on the mapper. The third parameter is an optional value to enable or disable CBOR encoding on the mapped data.  
+
+The `getMappedData` takes 4 arguments:
+
+1. A JSON object or array of JSON objects
+2. A key mapper to map JSON keys
+3. A value mapper to map JSON values (can be empty object if no value mapping needed)
+4. An optional boolean to enable or disable CBOR encoding on the mapped data (defaults to `false`)
+
 The example of a converted map would look like, `{ "1": "207", "2": "Jhon", "3": "Honay"}`
 
-### decodeMappedData( data, mapper )
+When `cborEnable` is `true`, the function returns a hex string of the CBOR-encoded mapped data.
+When `cborEnable` is `false`, the function returns the mapped JSON object directly.
+
+**⚠️ DEPRECATION NOTICE**: The previous 3-argument signature `getMappedData(jsonData, mapper, cborEnable)` is deprecated. Please use the new 4-argument signature with separate `keyMapper` and `valueMapper` parameters.
 
-- `data` - A CBOREncoded string or a mapped JSON.
-- `mapper` - A Map which is used to map with the JSON.
+### decodeMappedData( data, keyMapper, valueMapper )
+
+- `data` - A CBOR-encoded hex string, a mapped JSON string, or an array of either.
+- `keyMapper` - An array of mapper objects for depth-aware key decoding. Each mapper object handles keys at a specific depth level.
+- `valueMapper` - A function to transform values in the decoded JSON. Optional.
 
 ```javascript
-import { decodeMappedData } from '@mosip/pixelpass';
+import { decodeMappedData } from "@mosip/pixelpass";
 
 const cborEncodedString = "a302644a686f6e01633230370365486f6e6179";
-const mapper = {"1": "id", "2": "name", "3": "l_name"};
+const keyMapper = [
+  { 1: "id", 2: "name", 3: "l_name" }, // Mapper for depth 0
+];
+const valueMapper = (jsonData) => {
+  // Optional: transform values if needed
+  return jsonData;
+};
+
+const jsonString = decodeMappedData(cborEncodedString, keyMapper, valueMapper);
+const jsonData = JSON.parse(jsonString);
+```
+
+The `decodeMappedData` takes 3 arguments:
+
+1. A CBOR-encoded hex string, a JSON string, or an array of either
+2. An array of mapper objects for depth-aware key decoding (each index corresponds to a depth level)
+3. An optional value mapper function to transform the decoded data
+
+The function will:
+
+- First attempt to decode the data as CBOR (if it's a hex string)
+- If CBOR decoding fails, it will try to parse it as JSON
+- Apply key mapping at each depth level using the provided keyMapper array
+- Apply value transformation using the valueMapper function (if provided)
+- Return a JSON string representation of the decoded and mapped data
+
+Example with nested objects:
+
+```javascript
+const keyMapper = [
+  { 1: "id", 2: "name" }, // Maps keys at depth 0
+  { a: "street", b: "city" }, // Maps keys at depth 1 (nested objects)
+];
+
+const result = decodeMappedData(cborEncodedData, keyMapper);
+```
 
+The function also supports arrays of data:
+
+```javascript
+const dataArray = [encodedData1, encodedData2, encodedData3];
+const results = decodeMappedData(dataArray, keyMapper, valueMapper);
+// Returns an array of decoded JSON strings
+```
+
+**⚠️ BREAKING CHANGE**: The signature has been updated from the previous 2-argument version `decodeMappedData(data, mapper)` to the new 3-argument version `decodeMappedData(data, keyMapper, valueMapper)`. The `keyMapper` is now expected to be an array of mapper objects for depth-aware decoding, and an optional `valueMapper` function can be provided for value transformations.
+
+#### Migration Guide from Old to New API
+
+**Old API (Deprecated):**
+
+```javascript
+const mapper = { 1: "id", 2: "name", 3: "l_name" };
 const jsonData = decodeMappedData(cborEncodedString, mapper);
 ```
 
-The `decodeMappedData` takes 2 arguments a string which is CBOR Encoded or a mapped JSON and a map with which we will be creating a JSON by mapping the keys and values. If the data provided is CBOR encoded string the API will do a CBOR decode first ad then proceed with re-mapping the data.
-The example of the returned JSON would look like, `{"name": "Jhon", "id": "207", "l_name": "Honay"}`
+**New API:**
+
+```javascript
+const keyMapper = [
+  { 1: "id", 2: "name", 3: "l_name" }, // Wrap mapper in array
+];
+const valueMapper = null; // or a transformation function
+const jsonString = decodeMappedData(cborEncodedString, keyMapper, valueMapper);
+const jsonData = JSON.parse(jsonString); // Parse the returned JSON string
+```
+
+Key differences:
 
+- `keyMapper` must now be an array (for depth-aware mapping)
+- `valueMapper` is a new optional parameter for value transformations
+- Returns a JSON string instead of an object (needs `JSON.parse()`)
+- Supports arrays of data for batch processing
 
 ## Errors / Exceptions
+
 - `Cannot read properties of null (reading 'length')` - thrown when the string passed to encode is null.
 
 - `Cannot read properties of undefined (reading 'length')` - thrown when the string passed to encode is undefined.
 
-- `byteArrayArg is null or undefined.` -  thrown when the string passed to encode is null or undefined.
+- `byteArrayArg is null or undefined.` - thrown when the string passed to encode is null or undefined.
 
 - `utf8StringArg is null or undefined.` - thrown when the string passed to decode is null or undefined.
 
@@ -158,6 +277,7 @@ The example of the returned JSON would look like, `{"name": "Jhon", "id": "207",
 
 - `incorrect data check` - thrown when the string passed to decode is invalid.
 
+- `jsonData must not be null or undefined` - thrown when null or undefined is passed to `getMappedData`.
 
 ## License
 MPL-2.0

js/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mosip/pixelpass",
-  "version": "0.7.0",
-  "repository": "https://github.com/mosip/pixelpass",
+  "version": "0.8.0",
+  "repository": "https://github.com/inji/pixelpass",
   "author": "MOSIP",
   "license": "MPL-2.0",
-  "homepage": "https://github.com/mosip/pixelpass",
+  "homepage": "https://github.com/inji/pixelpass",
   "description": "JS module that can be used to compress (zlib) , encode (base45) and generate QR out of given any data. Also can be used to do the operation vice versa",
   "main": "src/index.js",
   "scripts": {