release/v2.2.0 (#73)

* Btc 49 main filters group order (#72)

* BTC-49 Control condition order for a main group

* Documentation update

* Date Literals Fix (#71)

* SOQL Filter Group refactoring (#76)

* SOQL Filter Group refactoring

* Restore asDateLiteral

* readme update

Author: pgajek2

README.md

@@ -5,7 +5,9 @@
 
 The SOQL Lib provides functional constructs for SOQL queries in Apex.
 
-For more details, please refer to the [documentation](https://soql-lib.vercel.app/). You may also find [this blog post](https://beyondthecloud.dev/blog/soql-lib) about SOQL Lib interesting
+For more details, please refer to the [documentation](https://soql-lib.vercel.app/).
+
+You may also find [this blog post](https://beyondthecloud.dev/blog/soql-lib) about SOQL Lib interesting.
 
 ## Examples
 
@@ -23,6 +25,8 @@ List<Account> accounts = SOQL.of(Account.SObjectType)
 
 ## Selector
 
+Read [how to build your selector class](https://soql-lib.vercel.app/building-your-selector).
+
 ```apex
 public inherited sharing class SOQL_Contact extends SOQL implements SOQL.Selector {
     public static SOQL_Contact query() {
@@ -69,23 +73,32 @@ public with sharing class ExampleController {
        src="https://raw.githubusercontent.com/afawcett/githubsfdeploy/master/deploy.png">
 </a>
 
-## Read the documentation
-
-[Query Selector documentation](https://soql-lib.vercel.app/)
-
-## Assumptions
-
-1. **Small Selector Classes** - The selector class should be small and contains ONLY query base configuration (fields, sharing settings) and very generic methods (`byId`, `byRecordType`). Why?
-   - Huge classes are hard to manage.
-   - A lot of merge conflicts.
-   - Problems with methods naming.
-2. **Build SOQL inline in a place of need** - Business-specific SOQLs should be built inline via `SOQL` builder in a place of need.
-   - Most of the queries on the project are case-specific and are not generic. There is no need to keep them in the Selector class.
-3. **Build SOQL dynamically via builder** - Developers should be able to adjust queries with specific fields, conditions, and other SOQL clauses.
-4. **Do not spend time on selector methods naming** - It can be difficult to find a proper name for a method that builds a query. The selector class contains methods like `selectByFieldAAndFieldBWithDescOrder`. It can be avoided by building SOQL inline in a place of need.
-5. **Control FLS and sharing settings** - Selector should allow to control Field Level Security and sharing settings by simple methods like `.systemMode()`, `.withSharing()`, `.withoutSharing()`.
-6. **Auto binding** - The selector should be able to bind variables dynamically without additional effort from the developer side.
-7. **Mock results in Unit Tests** - Selector should allow for mocking data in unit tests.
+## Documentation
+
+[SOQL Lib documentation](https://soql-lib.vercel.app/)
+
+## Features
+
+Read about the features in the [documentation](https://soql-lib.vercel.app/docs/basic-features).
+
+1. **Dynamic SOQL**
+2. **Automatic binding**
+3. **Control FLS**
+- 3.1 **User Mode**
+- 3.2 **System Mode**
+- 3.3 **stripInaccessible**
+4. **Control Sharings Mode**
+- 4.1 **with sharing**
+- 4.2 **without sharing**
+- 4.3 **inherited sharing**
+5. **Mocking**
+- 5.1 **Mock list of records**
+- 5.2 **Mock single record**
+- 5.3 **Mock with static resources**
+- 5.4 **Mock count result**
+6. **Avoid query duplicates**
+7. **The default configuration for all queries**
+8. **Dynamic conditions**
 
 ----
 

force-app/main/default/classes/SOQL.cls

@@ -74,6 +74,8 @@ public virtual inherited sharing class SOQL implements Queryable {
         Queryable whereAre(FilterGroup filterGroup); // SOQL.FilterGroup
         Queryable whereAre(Filter filter); // SOQL.Filter
         Queryable whereAre(String conditions); // Conditions to evaluate
+        Queryable conditionLogic(String order);
+        Queryable anyConditionMatching();
 
         Queryable groupBy(SObjectField field);
         Queryable groupByRollup(SObjectField field);
@@ -200,6 +202,7 @@ public virtual inherited sharing class SOQL implements Queryable {
         Filter excludesAll(Iterable<String> values); // join with ,
         Filter excludesSome(Iterable<String> values);  // join with ;
 
+        Filter asDateLiteral();
         Filter ignoreWhen(Boolean logicExpression); // Condition will be removed when logicExpression evaluates to true
 
         Boolean hasValue();
@@ -381,6 +384,16 @@ public virtual inherited sharing class SOQL implements Queryable {
         return this;
     }
 
+    public SOQL conditionLogic(String conditionLogic) {
+        builder.conditions.conditionLogic(conditionLogic);
+        return this;
+    }
+
+    public SOQL anyConditionMatching() {
+        builder.conditions.anyConditionMatching();
+        return this;
+    }
+
     public SOQL groupBy(SObjectField field) {
         builder.groupBy.with(field);
         return this;
@@ -939,47 +952,31 @@ public virtual inherited sharing class SOQL implements Queryable {
             return '(' + buildNested() + ')';
         }
 
-        private void setDefaultOrderWhenEmpty() {
+        private void setDefaultOrderWhenNotSpecified() {
             if (String.isNotEmpty(order)) {
                 return;
             }
 
             List<String> defaultOrder = new List<String>();
 
-            for (Integer i = 1; i <= queryConditions.size(); i++) {
-                defaultOrder.add(String.valueOf(i));
+            for (Integer i = 0; i < queryConditions.size(); i++) {
+                defaultOrder.add(String.valueOf(i + 1));
             }
 
-            order = String.join(defaultOrder, ' ' + connector + ' '); // e.g (1 AND 2 AND 3)
+            order = String.join(defaultOrder, ' ' + connector + ' ');
         }
 
         public String buildNested() {
-            setDefaultOrderWhenEmpty();
-
-            String conditions = applySpecialCharactersToOrder(); // e.g (*1* AND (*2* OR *3*))
-
-            for (Integer i = 0; i < queryConditions.size(); i++) {
-                conditions = conditions.replace(
-                    conditionNumberWithSpecialCharacters(i + 1), // e.g *1*
-                    queryConditions.get(i).toString()
-                );
-            }
+            setDefaultOrderWhenNotSpecified(); // e.g (0 AND 1 AND 2)
+            addSpecialCharactersToOrder(); // e.g ({0} AND ({1} AND {2}))
 
-            return conditions;
+            return String.format(order, queryConditions);
         }
 
-        private String applySpecialCharactersToOrder() {
-            String orderWithSpecialCharacters = order;
-
-            for (Integer i = 1; i <= queryConditions.size(); i++) {
-                orderWithSpecialCharacters = orderWithSpecialCharacters.replace(String.valueOf(i), conditionNumberWithSpecialCharacters(i));
+        private void addSpecialCharactersToOrder() {
+            for (Integer i = 0; i < queryConditions.size(); i++) {
+                order = order.replace(String.valueOf(i + 1), '{' + i + '}');
             }
-
-            return orderWithSpecialCharacters; // e.g (*1* AND (*2* OR *3*))
-        }
-
-        private String conditionNumberWithSpecialCharacters(Integer conditionNumber) {
-            return '*' + conditionNumber + '*';
         }
     }
 
@@ -1042,8 +1039,6 @@ public virtual inherited sharing class SOQL implements Queryable {
     }
 
     private class QFilter implements Filter {
-        private final List<DisplayType> TYPES_WITHOUT_BINDING = new List<DisplayType>{ DisplayType.DateTime };
-
         private String field;
         private String comperator;
         private Object value;
@@ -1064,12 +1059,10 @@ public virtual inherited sharing class SOQL implements Queryable {
         }
 
         public Filter with(SObjectField field) {
-            skipBinding = TYPES_WITHOUT_BINDING.contains(field.getDescribe().getType());
             return with(field.getDescribe().getName());
         }
 
         public Filter with(String relationshipName, SObjectField field) {
-            skipBinding = TYPES_WITHOUT_BINDING.contains(field.getDescribe().getType());
             return with(relationshipName + '.' + field);
         }
 
@@ -1133,7 +1126,7 @@ public virtual inherited sharing class SOQL implements Queryable {
         public Filter endsWith(String value) {
             return contains('%', formattedString(value), '');
         }
-        
+
         public Filter notEndsWith(String value) {
             return notLike().endsWith(value);
         }
@@ -1222,12 +1215,18 @@ public virtual inherited sharing class SOQL implements Queryable {
             }
             return this;
         }
-        
+
+        public Filter asDateLiteral() {
+            // Date Literals can't be binded
+            skipBinding = true;
+            return this;
+        }
+
         public override String toString() {
             if (skipBinding) {
                 return String.format(wrapper, new List<String> { field + ' ' + comperator + ' ' + value });
             }
-            
+
             return String.format(wrapper, new List<String> { field + ' ' + comperator + ' :' + binder.bind(value) });
         }
     }

force-app/main/default/classes/SOQL_Test.cls

@@ -998,7 +998,7 @@ private class SOQL_Test {
     static void dateLiteral() {
         // Test
         String soql = SOQL.of(Account.SObjectType)
-            .whereAre(SOQL.Filter.with(Account.CreatedDate).greaterThan('LAST_N_QUARTERS:2'))
+            .whereAre(SOQL.Filter.with(Account.CreatedDate).greaterThan('LAST_N_QUARTERS:2').asDateLiteral())
             .toString();
 
         // Verify
@@ -1056,7 +1056,7 @@ private class SOQL_Test {
     }
 
     @IsTest
-    static void anyConditionMatching() {
+    static void anyConditionMatchingForInnerGroup() {
         // Test
         SOQL builder = SOQL.of(Account.SObjectType)
             .whereAre(SOQL.FilterGroup
@@ -1074,6 +1074,40 @@ private class SOQL_Test {
         Assert.areEqual('Krakow', binding.get('v2'));
     }
 
+    @IsTest
+    static void anyConditionMatchingForMainGroup() {
+        // Test
+        SOQL builder = SOQL.of(Account.SObjectType)
+            .whereAre(SOQL.Filter.with(Account.Name).equal('Test'))
+            .whereAre(SOQL.Filter.with(Account.BillingCity).equal('Krakow'))
+            .anyConditionMatching();
+
+        // Verify
+        String soql = builder.toString();
+        Assert.areEqual('SELECT Id FROM Account WHERE Name = :v1 OR BillingCity = :v2', soql);
+
+        Map<String, Object> binding = builder.binding();
+        Assert.areEqual('Test', binding.get('v1'));
+        Assert.areEqual('Krakow', binding.get('v2'));
+    }
+
+    @IsTest
+    static void conditionLogicForMainGroup() {
+        // Test
+        SOQL builder = SOQL.of(Account.SObjectType)
+            .whereAre(SOQL.Filter.with(Account.Name).equal('Test'))
+            .whereAre(SOQL.Filter.with(Account.BillingCity).equal('Krakow'))
+            .conditionLogic('1 OR 2');
+
+        // Verify
+        String soql = builder.toString();
+        Assert.areEqual('SELECT Id FROM Account WHERE Name = :v1 OR BillingCity = :v2', soql);
+
+        Map<String, Object> binding = builder.binding();
+        Assert.areEqual('Test', binding.get('v1'));
+        Assert.areEqual('Krakow', binding.get('v2'));
+    }
+
     @IsTest
     static void nestedFiltersGroup() {
         // Test

force-app/main/default/classes/example/ExampleController.cls

@@ -28,10 +28,11 @@ public with sharing class ExampleController {
     }
 
     @AuraEnabled
-    public static List<Account> getAccountsByRecordType(String recordType) {
+    public static List<Account> getAccountsByRecordTypeOrITIndustry(String recordType) {
         return SOQL_Account.query()
             .byRecordType(recordType)
             .byIndustry('IT')
+            .anyConditionMatching()
             .with(Account.Industry, Account.AccountSource)
             .toList();
     }

website/docs/api/soql-filter.md

@@ -53,6 +53,7 @@ The following are methods for `Filter`.
 
 [**ADDITIONAL**](#additional)
 
+- [`asDateLiteral()`](#asdateliteral)
 - [`ignoreWhen(Boolean logicExpression)`](#ignorewhen)
 
 ## FIELDS
@@ -840,6 +841,34 @@ SOQL builder = SOQL.of(AccountContactRelation.SObjectType)
 
 ## ADDITIONAL
 
+### asDateLiteral
+
+[Date Literals](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_dateformats.htm)
+
+SOQL Lib automatically binds all variables; however, Date Literals cannot be binded.
+To skip binding for Date Literals, add `asDateLiteral()` to your `Filter`.
+
+**Signature**
+
+```apex
+Filter asDateLiteral();
+```
+
+**Example**
+
+```sql
+SELECT Id
+FROM Account
+WHERE CreatedDate > 'LAST_90_DAYS'
+```
+```apex
+String accountName = '';
+
+SOQL.of(Account.SObjectType)
+    .whereAre(SOQL.Filter.with(Account.CreatedDate).greaterThan('LAST_90_DAYS').asDateLiteral());
+    .toList();
+```
+
 ### ignoreWhen
 
 Condition will be removed when logic expression will evaluate to true.
@@ -849,7 +878,7 @@ Note! It does not work when [SOQL.FilterGroup.conditionLogic()](./soql-filters-g
 **Signature**
 
 ```apex
- Filter ignoreWhen(Boolean logicExpression);
+Filter ignoreWhen(Boolean logicExpression);
 ```
 
 **Example**

website/docs/api/soql-filters-group.md

@@ -109,7 +109,7 @@ SOQL.of(Account.SObjectType)
 
 ### anyConditionMatching
 
-When the [conditionLogic](#anyconditionmatching) is not specified, all conditions are joined using the `AND` operator by default.
+When the [conditionLogic](#conditionlogic) is not specified, all conditions are joined using the `AND` operator by default.
 
 To change the default condition logic, you can utilize the `anyConditionMatching` method, which joins conditions using the `OR` operator.