From e986a25180203959a2c547a8fa23d76ab737585b Mon Sep 17 00:00:00 2001
From: William Velzeboer <6429417+wimvelzeboer@users.noreply.github.com>
Date: Thu, 22 Jan 2026 10:21:29 +0000
Subject: [PATCH] Add replaceKey method to fflib_ArrayUtils (#76)

---
 .../classes/utils/fflib_ArrayUtils.cls        | 45 +++++++++++++++
 .../classes/utils/fflib_ArrayUtilsTest.cls    | 56 +++++++++++++++++++
 2 files changed, 101 insertions(+)

diff --git a/sfdx-source/apex-extensions/main/default/classes/utils/fflib_ArrayUtils.cls b/sfdx-source/apex-extensions/main/default/classes/utils/fflib_ArrayUtils.cls
index e37aaaf..0736592 100644
--- a/sfdx-source/apex-extensions/main/default/classes/utils/fflib_ArrayUtils.cls
+++ b/sfdx-source/apex-extensions/main/default/classes/utils/fflib_ArrayUtils.cls
@@ -343,6 +343,26 @@ public class fflib_ArrayUtils
 		return results;
 	}
 
+	/**
+	 * Takes two maps and replaces the key of the source with the value of the replacement,
+	 * where the source key matches the replacement key.
+	 * The key will be removed if it does not exists as key in replacement map
+	 *
+	 * @param source The map to replace its key
+	 * @param replacement The map to use its value for replacement
+	 *
+	 * @return Returns a Map<{Replacement-value} Id, {Source-value} Id>
+	 */
+	public static Map<Id, Id> replaceKey(Map<Id, Id> source, Map<Id, Id> replacement) {
+		Map<Id, Id> result = new Map<Id, Id>();
+		for (Id keyId : replacement.keySet()) {
+			if (source.containsKey(keyId) == false) continue;
+
+			result.put(replacement.get(keyId), source.get(keyId));
+		}
+		return result;
+	}
+
 	/**
 	 * Takes two maps and replaces the value of the source with the value of the replacement,
 	 * where the source value matches the replacement key.
@@ -463,6 +483,31 @@ public class fflib_ArrayUtils
 		return result;
 	}
 
+	/**
+	 * Takes two maps and replaces the value of the source with the value of the replacement,
+	 * where the source value matches the replacement key.
+	 * The value will become null if the source value does not exists as key in replacement map
+	 *
+	 * @param source The map to replace its value
+	 * @param replacement The map to use its value for replacement
+	 *
+	 * @return Returns a Map<{Source-key} Id, {Replacement-value} Id>
+	 */
+	public static Map<Id, Id> replaceValue(Map<Id, String> source, Map<String, Id> replacement) {
+		Map<Id, Id> result = new Map<Id, Id>();
+		for (Id keyId : source.keySet()) {
+			String sourceValue = source.get(keyId);
+
+			if (replacement.containsKey(sourceValue)) {
+				result.put(keyId, replacement.get(sourceValue));
+			} else {
+				// There is no replacement value for this keyId
+				result.put(keyId, null);
+			}
+		}
+		return result;
+	}
+
 	/**
 	 * Takes two maps and replaces the value of the source with the value of the replacement,
 	 * where the source value matches the replacement key.
diff --git a/sfdx-source/apex-extensions/tests/classes/utils/fflib_ArrayUtilsTest.cls b/sfdx-source/apex-extensions/tests/classes/utils/fflib_ArrayUtilsTest.cls
index 8becf6f..374c180 100644
--- a/sfdx-source/apex-extensions/tests/classes/utils/fflib_ArrayUtilsTest.cls
+++ b/sfdx-source/apex-extensions/tests/classes/utils/fflib_ArrayUtilsTest.cls
@@ -238,6 +238,33 @@ private class fflib_ArrayUtilsTest
         System.Assert.areEqual(8, result, 'Did not return the last value in the list of objects');
     }
 
+    @IsTest
+    static void itShouldReplaceKeyInTheMap()
+    {
+        Id accountIdA = fflib_IDGenerator.generate(Schema.Account.SObjectType);
+        Id accountIdB = fflib_IDGenerator.generate(Schema.Account.SObjectType);
+        Id accountIdC = fflib_IDGenerator.generate(Schema.Account.SObjectType);
+        Id contactIdA = fflib_IDGenerator.generate(Schema.Contact.SObjectType);
+        Id contactIdB = fflib_IDGenerator.generate(Schema.Contact.SObjectType);
+        Map<Id, Id> source = new Map<Id, Id>
+        {
+                accountIdA => contactIdA,
+                accountIdB => contactIdB,
+                accountIdC => fflib_IDGenerator.generate(Schema.Contact.SObjectType)
+        };
+        Map<Id, Id> replacement = new Map<Id, Id>
+        {
+                accountIdA => contactIdA,
+                accountIdB => accountIdA
+        };
+
+        Map<Id, Id> result = fflib_ArrayUtils.replaceKey(source, replacement);
+
+        System.Assert.areEqual(2, result.size());
+        System.Assert.areEqual(contactIdA, result.get(contactIdA));
+        System.Assert.areEqual(contactIdB, result.get(accountIdA));
+    }
+
     @IsTest
     static void itShouldReplaceValueInTheMap()
     {
@@ -322,6 +349,35 @@ private class fflib_ArrayUtilsTest
         System.Assert.isNull(result.get(accountIdC));
     }
 
+    @IsTest
+    static void itShouldReplaceValueInTheMap_stringToId()
+    {
+        String accountName = 'AccountName';
+        Id accountIdA = fflib_IDGenerator.generate(Schema.Account.SObjectType);
+        Id accountIdB = fflib_IDGenerator.generate(Schema.Account.SObjectType);
+        Id accountIdC = fflib_IDGenerator.generate(Schema.Account.SObjectType);
+        Id contactIdA = fflib_IDGenerator.generate(Schema.Contact.SObjectType);
+        Id contactIdB = fflib_IDGenerator.generate(Schema.Contact.SObjectType);
+        Map<Id, String> source = new Map<Id, String>
+        {
+                accountIdA => accountName + 'A',
+                accountIdB => accountName + 'B',
+                accountIdC => accountName + 'C'
+        };
+        Map<String, Id> replacement = new Map<String, Id>
+        {
+                accountName + 'A' => contactIdA,
+                accountName + 'B' => contactIdB
+        };
+
+        Map<Id, Id> result = fflib_ArrayUtils.replaceValue(source, replacement);
+
+        System.Assert.areEqual(3, result.size());
+        System.Assert.areEqual(contactIdA, result.get(accountIdA));
+        System.Assert.areEqual(contactIdB, result.get(accountIdB));
+        System.Assert.isNull(result.get(accountIdC));
+    }
+
     @IsTest
     static void itShouldReplaceValueInTheMap_boolean()
     {