chore(utils): add comments + cleanup util functions (#10628)

remnants from https://github.com/medusajs/medusa/pull/10579

packages/core/utils/src/common/filter-object-by-keys.ts

@@ -1,5 +1,30 @@
 import { isDefined } from "./is-defined"
 
+/*
+  Given an array of keys that are object paths (like product.categories.id), this function will
+  return an object that contains keys from those object paths
+
+  Given an object: testObject = {
+    product: {
+      id: "test-product",
+      name: "Test Product",
+      categories: [{
+        id: "test-category",
+        name: "Test Category"
+      }]
+    }
+  }
+
+  filterObjectByKeys(testObject, ['product.categories.id']) will return
+
+  {
+    product: {
+      categories: [{
+        id: "test-category"
+      }]
+    }
+  }
+*/
 export function filterObjectByKeys(obj, paths) {
   function buildObject(paths) {
     const result = {}

packages/core/utils/src/common/flatten-object-to-key-value-pairs.ts

@@ -1,7 +1,33 @@
+import { isObject } from "./is-object"
+
 type NestedObject = {
   [key: string]: any
 }
 
+/*
+  Given a deeply nested object that can be arrays or objects, this function will flatten
+  it to an object that is 1 level deep.
+
+  Given an object: testObject = {
+    product: {
+      id: "test-product",
+      name: "Test Product",
+      categories: [{
+        id: "test-category",
+        name: "Test Category"
+      }]
+    }
+  }
+
+  flattenObjectToKeyValuePairs(testObject) will return
+
+  {
+    "product.id": "test-product",
+    "product.name": "Test Product",
+    "product.categories.id": ["test-category"],
+    "product.categories.name": ["Test Category"]
+  }
+*/
 export function flattenObjectToKeyValuePairs(obj: NestedObject): NestedObject {
   const result: NestedObject = {}
 
@@ -17,12 +43,12 @@ export function flattenObjectToKeyValuePairs(obj: NestedObject): NestedObject {
     }
 
     // If it's an array of objects, add this path
-    if (Array.isArray(obj) && obj.length > 0 && typeof obj[0] === "object") {
+    if (Array.isArray(obj) && obj.length > 0 && isObject(obj[0])) {
       paths.push(currentPath)
     }
 
     // Check all properties
-    if (typeof obj === "object") {
+    if (isObject(obj)) {
       Object.entries(obj as Record<string, unknown>).forEach(([key, value]) => {
         const newPath = [...currentPath, key]
         paths.push(...findArrayPaths(value, newPath))
@@ -35,7 +61,7 @@ export function flattenObjectToKeyValuePairs(obj: NestedObject): NestedObject {
   // Extract array values at a specific path
   function getArrayValues(obj: unknown, path: string[]): unknown[] {
     const arrayObj = path.reduce((acc: unknown, key: string) => {
-      if (acc && typeof acc === "object") {
+      if (acc && isObject(acc)) {
         return (acc as Record<string, unknown>)[key]
       }
       return undefined
@@ -57,7 +83,7 @@ export function flattenObjectToKeyValuePairs(obj: NestedObject): NestedObject {
 
     Object.entries(obj as Record<string, unknown>).forEach(([key, value]) => {
       const newPrefix = prefix ? `${prefix}.${key}` : key
-      if (value && typeof value === "object" && !Array.isArray(value)) {
+      if (value && isObject(value) && !Array.isArray(value)) {
         processRegularPaths(value, newPrefix)
       } else if (!Array.isArray(value)) {
         result[newPrefix] = value
@@ -78,7 +104,7 @@ export function flattenObjectToKeyValuePairs(obj: NestedObject): NestedObject {
       // Get all possible keys from the array objects
       const keys = new Set<string>()
       arrayObjects.forEach((item) => {
-        if (item && typeof item === "object") {
+        if (item && isObject(item)) {
           Object.keys(item as object).forEach((k) => keys.add(k))
         }
       })
@@ -87,7 +113,7 @@ export function flattenObjectToKeyValuePairs(obj: NestedObject): NestedObject {
       keys.forEach((key) => {
         const values = arrayObjects
           .map((item) => {
-            if (item && typeof item === "object") {
+            if (item && isObject(item)) {
               return (item as Record<string, unknown>)[key]
             }
             return undefined
@@ -96,7 +122,7 @@ export function flattenObjectToKeyValuePairs(obj: NestedObject): NestedObject {
 
         if (values.length > 0) {
           const newPath = `${pathStr}.${key}`
-          if (values.every((v) => typeof v === "object" && !Array.isArray(v))) {
+          if (values.every((v) => isObject(v) && !Array.isArray(v))) {
             // If these are all objects, recursively process them
             const subObj = { [key]: values }
             const subResult = flattenObjectToKeyValuePairs(subObj)