From ae821ae490b6b8ee8400963170dcdf1ed71e50f0 Mon Sep 17 00:00:00 2001
From: Arthur <abrantesarthur1997@gmail.com>
Date: Tue, 14 Jan 2025 04:40:44 +0000
Subject: [PATCH] write docs for aggregateObjects

---
 .../helpers/flattenOneTrustAssessment.ts      | 33 ++++++++++++++-----
 .../helpers/oneTrustAssessmentToCsvRecord.ts  |  4 +--
 .../helpers/syncOneTrustAssessments.ts        |  4 +--
 3 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/src/oneTrust/helpers/flattenOneTrustAssessment.ts b/src/oneTrust/helpers/flattenOneTrustAssessment.ts
index 5609add9..ae24381a 100644
--- a/src/oneTrust/helpers/flattenOneTrustAssessment.ts
+++ b/src/oneTrust/helpers/flattenOneTrustAssessment.ts
@@ -15,9 +15,7 @@ import {
   OneTrustEnrichedRisk,
 } from '../codecs';
 
-// TODO: will have to use something like csv-stringify
-
-// TODO: test what happens when a value is null -> it should convert to ''
+// FIXME: move to @transcend/type-utils, document and write tests
 const flattenObject = (obj: any, prefix = ''): any =>
   Object.keys(obj ?? []).reduce((acc, key) => {
     const newKey = prefix ? `${prefix}_${key}` : key;
@@ -42,22 +40,42 @@ const flattenObject = (obj: any, prefix = ''): any =>
     return acc;
   }, {} as Record<string, any>);
 
-// TODO: move to helpers
+// FIXME: move to @transcend/type-utils
+/**
+ * Aggregates multiple objects into a single object by combining values of matching keys.
+ * For each key present in any of the input objects, creates a comma-separated string
+ * of values from all objects.
+ *
+ * @param param - the objects to aggregate and the aggregation method
+ * @returns a single object containing all unique keys with aggregated values
+ * @example
+ * const obj1 = { name: 'John', age: 30 };
+ * const obj2 = { name: 'Jane', city: 'NY' };
+ * const obj3 = { name: 'Bob', age: 25 };
+ *
+ * // Without wrap
+ * aggregateObjects({ objs: [obj1, obj2, obj3] })
+ * // Returns: { name: 'John,Jane,Bob', age: '30,,25', city: ',NY,' }
+ *
+ * // With wrap
+ * aggregateObjects({ objs: [obj1, obj2, obj3], wrap: true })
+ * // Returns: { name: '[John],[Jane],[Bob]', age: '[30],[],[25]', city: '[],[NY],[]' }
+ */
 const aggregateObjects = ({
   objs,
   wrap = false,
 }: {
   /** the objects to aggregate in a single one */
   objs: any[];
-  /** whether to wrap the values in a [] */
+  /** whether to wrap the concatenated values in a [] */
   wrap?: boolean;
 }): any => {
   const allKeys = Array.from(new Set(objs.flatMap((a) => Object.keys(a))));
 
-  // build a single object where all the keys contain the respective values of objs
+  // Reduce into a single object, where each key contains concatenated values from all input objects
   return allKeys.reduce((acc, key) => {
     const values = objs
-      .map((a) => (wrap ? `[${a[key] ?? ''}]` : a[key] ?? ''))
+      .map((o) => (wrap ? `[${o[key] ?? ''}]` : o[key] ?? ''))
       .join(',');
     acc[key] = values;
     return acc;
@@ -80,7 +98,6 @@ const flattenOneTrustNestedQuestions = (
   questions: OneTrustAssessmentNestedQuestion[],
   prefix: string,
 ): any => {
-  // TODO: how do extract properties handle null
   const { options: allOptions, rest: restQuestions } = extractProperties(
     questions,
     ['options'],
diff --git a/src/oneTrust/helpers/oneTrustAssessmentToCsvRecord.ts b/src/oneTrust/helpers/oneTrustAssessmentToCsvRecord.ts
index af164be2..ee704528 100644
--- a/src/oneTrust/helpers/oneTrustAssessmentToCsvRecord.ts
+++ b/src/oneTrust/helpers/oneTrustAssessmentToCsvRecord.ts
@@ -5,8 +5,8 @@ import { flattenOneTrustAssessment } from './flattenOneTrustAssessment';
 import { OneTrustAssessmentCsvRecord } from '@transcend-io/privacy-types';
 
 /**
- * Converts the assessment into a csv record (header + values). It always
- * returns a record with every key in the same order.
+ * Converts the assessment into a csv record (i.e. a map from the csv header
+ * to values). It always returns a record with every key in the same order.
  *
  * @param assessment - the assessment to convert to a csv record
  * @returns a stringified csv entry ready to be appended to a file
diff --git a/src/oneTrust/helpers/syncOneTrustAssessments.ts b/src/oneTrust/helpers/syncOneTrustAssessments.ts
index b4894cdd..8ee4e88a 100644
--- a/src/oneTrust/helpers/syncOneTrustAssessments.ts
+++ b/src/oneTrust/helpers/syncOneTrustAssessments.ts
@@ -48,7 +48,7 @@ export const syncOneTrustAssessments = async ({
   const assessments = await getListOfOneTrustAssessments({ oneTrust });
 
   /**
-   * fetch details about one assessment in series and push to transcend or write to disk
+   * fetch details about each assessment in series and write to transcend or to disk
    * (depending on the dryRun argument) right away to avoid running out of memory
    */
   await mapSeries(assessments, async (assessment, index) => {
@@ -86,7 +86,7 @@ export const syncOneTrustAssessments = async ({
       );
     }
 
-    // enrich the sections with risk details
+    // enrich the assessments with risk and details
     const enrichedAssessment = enrichOneTrustAssessment({
       assessment,
       assessmentDetails,