feat: Add optional parameter for registerDirty to specify exactly what fields need to be updated

This allows a unit of work's uncommited changes to not be overwritten when multiple areas of code update the same record on the same unit of work.

e.g. a stack of processes that update different fields on the same record while being passed a unit of work allowing for changes to be commited after http callouts

Comes form Traction on Demand's John Rogers, has been sitting in our code base for a long time

There is a breaking change compared to a previous versions of fflib, where an excpetion is thrown if the same record is registered dirty twice without fields being specified. This could be modified to overwrite the existing registered dirty record (which is the current behaviour) instead of throwing an exception.

Author: JonnyPower

fflib/src/classes/fflib_ISObjectUnitOfWork.cls

@@ -59,6 +59,16 @@ public interface fflib_ISObjectUnitOfWork
      * @param record An existing record
      **/
     void registerDirty(SObject record);
+    /**
+     * Register specific fields on record to be updated when work is commited
+     *
+     * If the record has previously been registered as dirty, the dirty fields on the record in this call will overwrite
+     * the values of the previously registered dirty record
+     *
+     * @param record An existing record
+     * @param dirtyFields The fields to update if record is already registered
+     **/
+    void registerDirty(SObject record, List<SObjectField> dirtyFields);
     /**
      * Register an existing record to be updated when commitWork is called,
      *   you may also provide a reference to the parent record instance (should also be registered as new separatly)

fflib/src/classes/fflib_SObjectMocks.cls

@@ -81,6 +81,15 @@ public class fflib_SObjectMocks
 			mocks.mockVoidMethod(this, 'registerDirty', new List<Type> {SObject.class}, new List<Object> {record});
 		}
 
+		public void registerDirty(SObject record, List<SObjectField> dirtyFields)
+		{
+			mocks.mockVoidMethod(this, 'registerDirty', new List<Type> {
+					SObject.class, System.Type.forName('List<SObjectField>')
+			}, new List<Object> {
+					record, dirtyFields
+			});
+		}
+
         public void registerDirty(SObject record, Schema.sObjectField relatedToParentField, SObject relatedToParentRecord)
         {
             mocks.mockVoidMethod(this, 'registerDirty', new List<Type> {SObject.class}, new List<Object> {record});

fflib/src/classes/fflib_SObjectUnitOfWork.cls

@@ -247,12 +247,41 @@ public virtual class fflib_SObjectUnitOfWork
      * @param record An existing record
      **/
     public void registerDirty(SObject record)
+    {
+        registerDirty(record, new List<SObjectField>());
+    }
+
+    public void registerDirty(SObject record, List<SObjectField> dirtyFields)
     {
         if(record.Id == null)
             throw new UnitOfWorkException('New records cannot be registered as dirty');
         String sObjectType = record.getSObjectType().getDescribe().getName();
         if(!m_dirtyMapByType.containsKey(sObjectType))
             throw new UnitOfWorkException(String.format('SObject type {0} is not supported by this unit of work', new String[] { sObjectType }));
+
+        // If record isn't registered as dirty
+        if (!m_dirtyMapByType.get(sObjectType).containsKey(record.Id))
+        {
+            // Register the record as dirty
+            m_dirtyMapByType.get(sObjectType).put(record.Id, record);
+        }
+        else
+        {
+            // Update the registered record's fields
+            SObject registeredRecord = m_dirtyMapByType.get(sObjectType).get(record.Id);
+
+            // If the caller has supplied a different instance of the same record with no list of updated fields
+            if (dirtyFields.isEmpty() && registeredRecord !== record)
+            {
+                // Cannot determine what updates to make to the record (assuming updating nothing is incorrect)
+                throw new UnitOfWorkException('Cannot determine what fields to update on record ' + record);
+            }
+
+            for (SObjectField dirtyField : dirtyFields) {
+                registeredRecord.put(dirtyField, record.get(dirtyField));
+            }
+        }
+
         m_dirtyMapByType.get(sObjectType).put(record.Id, record);
     }
 

fflib/src/classes/fflib_SObjectUnitOfWorkTest.cls

@@ -338,6 +338,78 @@ private with sharing class fflib_SObjectUnitOfWorkTest
             , uow.getCommitWorkEventsFired(), new Set<Schema.SObjectType>(MY_SOBJECTS), uow.getRegisteredTypes());
     }
 
+    /**
+     * Try registering two instances of the same record as dirty.
+     *
+     *  Testing:
+     *
+     *      - Exception is thrown stopping second registration
+     */
+    @isTest
+    private static void testRegisterDirty_DoubleException() {
+        Opportunity opp = new Opportunity(Id = '00636000005loIj', Name = 'UpdateName');
+        Opportunity opp2 = new Opportunity(Id = '00636000005loIj', Amount = 250);
+        UnitOfWork uow = new UnitOfWork(MY_SOBJECTS);
+        uow.registerDirty(opp);
+        Boolean exceptionThrown = false;
+        try {
+            // Second registration would undo updates of first registration
+            uow.registerDirty(opp2);
+        } catch (UnitOfWork.UnitOfWorkException e) {
+            System.assert(e.getMessage().contains(opp.Id));
+            exceptionThrown = true;
+        }
+        System.assert(exceptionThrown);
+    }
+
+    /**
+     * Try registering a single field as dirty.
+     *
+     *  Testing:
+     *
+     *      - field is updated
+     */
+    @isTest
+    private static void testRegisterDirty_field() {
+        Opportunity opp = new Opportunity(Name = 'test name', StageName = 'Open', CloseDate = System.today());
+        insert opp;
+
+        Opportunity nameUpdate = new Opportunity(Id = opp.Id, Name = 'UpdateName');
+        Opportunity amountUpdate = new Opportunity(Id = opp.Id, Amount = 250);
+        UnitOfWork uow = new UnitOfWork(MY_SOBJECTS);
+        uow.registerDirty(nameUpdate);
+        uow.registerDirty(amountUpdate, Opportunity.Amount);
+        uow.commitWork();
+
+        opp = [SELECT Name, Amount FROM Opportunity WHERE Id = :opp.Id];
+        System.assertEquals(opp.Name, nameUpdate.Name);
+        System.assertEquals(opp.Amount, amountUpdate.Amount);
+    }
+
+    /**
+     * Try registering a single unupdateable field as dirty in secure mode
+     *
+     *  Testing:
+     *
+     *      - exception is thrown
+     */
+    @isTest
+    private static void testRegisterDirty_field_secure() {
+        Opportunity opp = new Opportunity(Name = 'test name', StageName = 'Open', CloseDate = System.today());
+        insert opp;
+
+        UnitOfWork uow = new UnitOfWork(MY_SOBJECTS, new AccessConfig());
+        uow.registerDirty(opp, Opportunity.Id); // Should throw exception because ID is not updatable
+
+        Boolean exceptionThrown = false;
+        try {
+            uow.commitWork();
+        } catch (fflib_SecurityUtils.SecurityException e) {
+            exceptionThrown = true;
+        }
+        System.assert(exceptionThrown);
+    }
+
     /**
      * Assert that actual events exactly match expected events (size, order and name)
      * and types match expected types