feat: sourceRecordsFilter option added

[nktnet1]

Resolves #935

Added the sourceRecordsFilter which behaves similar to targetRecordsFilter for the ScriptObject .

Unit tests for this contribution are available here:

• https://github.com/nktnet1/soql-parser-merge-where-clause

I've written some basic documentation below.

---

Overview

Purpose: This feature provides an additional method to apply filters only when retrieving them from the Source environment. The filters are not applied to the Target environment.

Use case: In some scenarios, the filter condition will only work in the context of the source environment. For example, a parent "Event" object whose "Start Time" depends on children "Block" objects, but the Block objects are not being migrated. This is especially important for UPSERT operations, as this relies on equivalent Source and Target objects (by their externalId) to be matched to determine whether to UPDATE or INSERT. With the source-only condition never satisfying any Target objects, only INSERT will be used, resulting in duplicate records.

Examples of Using Source Record Filter

Supposed you have an Event whose Start Time is calculated by the minimum Block time:

The settings below will retrieve all Event records made after 2024 from the Source, then insert all records retrieved to the Target without applying the same filter.

{
  "query": "SELECT Id, Start_Date1__c FROM Event__c",
  "targetRecordsFilter": "CALENDAR_YEAR(Start_Date1__c) >= 2024"
}

Understanding the TargetRecordsFilter Syntax

The sourceRecordsFilter uses the same syntax as regular SOQL. Please note that this behaviour is slightly different from the targetRecordsFilter.

[salesforce-cla]

Thanks for the contribution! Before we can merge this, we need @nktnet1 to sign the Salesforce Inc. Contributor License Agreement.