docs: review json replacer and reviver jsDocs (#852)

# Motivation Since I'm already there, I propose to refresh the jsdoc of JSON replacer and reviver. # Changes - Update jsdoc with few additional details and different wording --------- Signed-off-by: David Dal Busco <[email protected]> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
dfinity · Feb 26, 2025 · 6150930 · 6150930
1 parent d5ebf25
commit 6150930
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 6 deletions.
diff --git a/packages/utils/README.md b/packages/utils/README.md
@@ -453,23 +453,48 @@ Parameters:
 
 #### :gear: jsonReplacer
 
-A parser that interprets revived BigInt, Principal, and Uint8Array when constructing JavaScript values or objects.
+A custom replacer for `JSON.stringify` that converts specific types not natively supported
+by the API into JSON-compatible formats.
+
+Supported conversions:
+
+- `BigInt` → `{ "__bigint__": string }`
+- `Principal` → `{ "__principal__": string }`
+- `Uint8Array` → `{ "__uint8array__": number[] }`
 
 | Function       | Type                                        |
 | -------------- | ------------------------------------------- |
 | `jsonReplacer` | `(_key: string, value: unknown) => unknown` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/json.utils.ts#L11)
+Parameters:
+
+- `_key`: - Ignored. Only provided for API compatibility.
+- `value`: - The value to transform before stringification.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/json.utils.ts#L21)
 
 #### :gear: jsonReviver
 
-A function that alters the behavior of the stringification process for BigInt, Principal and Uint8Array.
+A custom reviver for `JSON.parse` that reconstructs specific types from their JSON-encoded representations.
+
+This reverses the transformations applied by `jsonReplacer`, restoring the original types.
+
+Supported conversions:
+
+- `{ "__bigint__": string }` → `BigInt`
+- `{ "__principal__": string }` → `Principal`
+- `{ "__uint8array__": number[] }` → `Uint8Array`
 
 | Function      | Type                                        |
 | ------------- | ------------------------------------------- |
 | `jsonReviver` | `(_key: string, value: unknown) => unknown` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/json.utils.ts#L30)
+Parameters:
+
+- `_key`: - Ignored but provided for API compatibility.
+- `value`: - The parsed value to transform.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/json.utils.ts#L51)
 
 #### :gear: principalToSubAccount
 

diff --git a/packages/utils/src/utils/json.utils.ts b/packages/utils/src/utils/json.utils.ts
@@ -6,7 +6,17 @@ const JSON_KEY_PRINCIPAL = "__principal__";
 const JSON_KEY_UINT8ARRAY = "__uint8array__";
 
 /**
- * A parser that interprets revived BigInt, Principal, and Uint8Array when constructing JavaScript values or objects.
+ * A custom replacer for `JSON.stringify` that converts specific types not natively supported
+ * by the API into JSON-compatible formats.
+ *
+ * Supported conversions:
+ * - `BigInt` → `{ "__bigint__": string }`
+ * - `Principal` → `{ "__principal__": string }`
+ * - `Uint8Array` → `{ "__uint8array__": number[] }`
+ *
+ * @param {string} _key - Ignored. Only provided for API compatibility.
+ * @param {unknown} value - The value to transform before stringification.
+ * @returns {unknown} The transformed value if it matches a known type, otherwise the original value.
  */
 export const jsonReplacer = (_key: string, value: unknown): unknown => {
   if (typeof value === "bigint") {
@@ -25,7 +35,18 @@ export const jsonReplacer = (_key: string, value: unknown): unknown => {
 };
 
 /**
- * A function that alters the behavior of the stringification process for BigInt, Principal and Uint8Array.
+ * A custom reviver for `JSON.parse` that reconstructs specific types from their JSON-encoded representations.
+ *
+ * This reverses the transformations applied by `jsonReplacer`, restoring the original types.
+ *
+ * Supported conversions:
+ * - `{ "__bigint__": string }` → `BigInt`
+ * - `{ "__principal__": string }` → `Principal`
+ * - `{ "__uint8array__": number[] }` → `Uint8Array`
+ *
+ * @param {string} _key - Ignored but provided for API compatibility.
+ * @param {unknown} value - The parsed value to transform.
+ * @returns {unknown} The reconstructed value if it matches a known type, otherwise the original value.
  */
 export const jsonReviver = (_key: string, value: unknown): unknown => {
   const mapValue = <T>(key: string): T => (value as Record<string, T>)[key];