Merge branch 'main' of https://github.com/beyond-the-cloud-dev/soql-lib into release/v5.2.0

Author: pgajek2

website/docs/advanced-usage/fls.md

@@ -16,7 +16,7 @@ none (by default) | `USER_MODE` | enforced
 
 ## Default
 
-`USER_MODE` is a enabled by default. It means that **the object permissions, field-level security**, as well as sharing rules, **are enforced**.
+`USER_MODE` is enabled by default. It means that **the object permissions, field-level security**, as well as sharing rules, **are enforced**.
 
 ```apex title="SOQL_Account.cls"
 public inherited sharing class SOQL_Account extends SOQL implements SOQL.Selector {
@@ -46,7 +46,7 @@ public without sharing class ExampleController {
 
 ### System Mode
 
-Developer can disable `USER_MODE` and enable `SYSTEM_MODE` using `.systemMode()` method.
+Developers can disable `USER_MODE` and enable `SYSTEM_MODE` using the `.systemMode()` method.
 
 ```apex title="SOQL_Account.cls"
 public inherited sharing class SOQL_Account extends SOQL implements SOQL.Selector {

website/docs/advanced-usage/knownIssues.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 40
+---
+
+# Known Issues
+
+## Variable does not exist
+
+Error: `System.QueryException: Variable does not exist: v1`
+
+### Root Cause
+
+This is **NOT** the lib issue but rather a Salesforce platform limitation that occurs when `Database.getQueryLocatorWithBinds` is used with insufficient permissions.
+
+This error occurs when all of the following conditions are met:
+- `toQueryLocator()` is executed
+- Query is executed with `USER_MODE` (which is the default mode if not otherwise specified)
+- Query contains fields to which the user doesn't have access
+- Query has at least one condition, which means that a binding map is used
+
+**Example that fails:**
+
+**Apex**
+
+```apex
+Database.getQueryLocatorWithBinds(
+    'SELECT Type FROM Task WHERE Type != :v1', 
+    new Map<String, Object>{'v1' => null}, 
+    AccessLevel.USER_MODE
+);
+```
+
+**SOQL Lib**
+
+```apex
+SOQL.of(Task.SObjectType)
+    .with(Task.Type) // <== no access to this field
+    .whereAre(SOQL.Filter.with(Task.Type).isNotNull())
+    .toQueryLocator();
+```
+
+### Solutions
+
+#### Ensure user has field access permissions
+
+Grant the user appropriate field-level security permissions for the fields used in the query.
+
+#### Use SYSTEM_MODE
+
+**Apex**
+```apex
+Database.getQueryLocatorWithBinds(
+    'SELECT Type FROM Task WHERE Type != :v1', 
+    new Map<String, Object>{'v1' => null}, 
+    AccessLevel.SYSTEM_MODE
+);
+```
+
+**SOQL Lib**
+
+```apex
+SOQL.of(Task.SObjectType)
+    .with(Task.Type) 
+    .whereAre(SOQL.Filter.with(Task.Type).isNotNull())
+    .systemMode()
+    .toQueryLocator();
+```

website/docs/advanced-usage/mocking.md

@@ -4,8 +4,8 @@ sidebar_position: 30
 
 # Mocking
 
-Mocking provides a way to substitute records from a Database with some prepared data. Data can be prepared in form of SObject records and lists in Apex code or Static Resource `.csv` file.
-Mocked queries won't make any SOQL's and simply return data set in method definition, mock __will ignore all filters and relations__, what is returned depends __solely on data provided to the method__. Mocking is working __only during test execution__. To mock SOQL query, use `.mockId(id)` method to make it identifiable. If you mark more than one query with the same ID, all marked queries will return the same data.
+Mocking provides a way to substitute records from a database with some prepared data. Data can be prepared in the form of SObject records and lists in Apex code or Static Resource `.csv` file.
+Mocked queries won't make any SOQLs and simply return data set in method definition, mock __will ignore all filters and relations__, what is returned depends __solely on data provided to the method__. Mocking is working __only during test execution__. To mock SOQL query, use `.mockId(id)` method to make it identifiable. If you mark more than one query with the same ID, all marked queries will return the same data.
 
 ```apex title="ExampleController.cls"
 public with sharing class ExampleController {
@@ -23,7 +23,7 @@ public with sharing class ExampleController {
 }
 ```
 
-Then in test simply pass data you want to get from Selector to `SOQL.mock(id).thenReturn(data)` method. Acceptable formats are: `List<SObject>` or `SObject`. Then during execution Selector will return desired data.
+Then in tests simply pass data you want to get from Selector to `SOQL.mock(id).thenReturn(data)` method. Acceptable formats are: `List<SObject>` or `SObject`. Then during execution Selector will return the desired data.
 
 ## Insights
 

website/docs/advanced-usage/sharing.md

@@ -17,7 +17,7 @@ none (by default) | `USER_MODE` | `with sharing`
 
 ## Default
 
-`USER_MODE` is a enabled by default. It means that the object permissions, field-level security and **sharing rules are enforced**.
+`USER_MODE` is enabled by default. It means that the object permissions, field-level security and **sharing rules are enforced**.
 
 ```apex title="SOQL_Account.cls"
 public inherited sharing class SOQL_Account extends SOQL implements SOQL.Selector {

website/docs/api/standard-soql/soql-join.md

@@ -34,7 +34,7 @@ The following are methods for `FilterGroup`.
 ## INIT
 ### of
 
-Conctructs an `JoinQuery`.
+Constructs a `JoinQuery`.
 
 **Signature**
 

website/docs/api/standard-soql/soql-sub.md

@@ -67,7 +67,7 @@ The following are methods for `SubQuery`.
 ## INIT
 ### of
 
-Conctructs an `SubQuery`.
+Constructs a `SubQuery`.
 
 **Signature**
 

website/docs/api/standard-soql/soql.md

@@ -211,7 +211,7 @@ The following are methods for using `SOQL`:
 ## INIT
 ### of
 
-Conctructs an `SOQL`.
+Constructs an `SOQL`.
 
 **Signature**
 

website/docs/docs/basic-features.md

@@ -84,7 +84,7 @@ By default, all queries are executed `with sharing`, enforced by `AccessLevel.US
 
 `AccessLevel.USER_MODE` enforces object permissions and field-level security.
 
-Developer can skip FLS by adding `.systemMode()` and `.withSharing()`.
+Developers can skip FLS by adding `.systemMode()` and `.withSharing()`.
 
 ```apex
 // Query executed in without sharing
@@ -97,7 +97,7 @@ SOQL.of(Account.SObjectType)
 
 ### without sharing
 
-Developer can control sharing rules by adding `.systemMode()` (record sharing rules are controlled by the sharingMode) and `.withoutSharing()`.
+Developers can control sharing rules by adding `.systemMode()` (record sharing rules are controlled by the sharingMode) and `.withoutSharing()`.
 
 ```apex
 // Query executed in with sharing
@@ -110,7 +110,7 @@ SOQL.of(Account.SObjectType)
 
 ### inherited sharing
 
-Developer can control sharing rules by adding `.systemMode()` (record sharing rules are controlled by the sharingMode) by default it is `inherited sharing`.
+Developers can control sharing rules by adding `.systemMode()` (record sharing rules are controlled by the sharingMode); by default it is `inherited sharing`.
 
 ```apex
 // Query executed in inherited sharing
@@ -204,7 +204,7 @@ private class ExampleControllerTest {
 
 ### Count Result
 
-```
+```apex
 @IsTest
 private class ExampleControllerTest {
 
@@ -219,9 +219,39 @@ private class ExampleControllerTest {
 }
 ```
 
+### Aggregate Result
+
+```apex
+@IsTest
+private class ExampleControllerTest {
+
+    @IsTest
+    static void getLeadSourceCounts() {
+        List<Map<String, Object>> aggregateResults = new List<Map<String, Object>>{
+            new Map<String, Object>{ 'LeadSource' => 'Web',  'total' => 10},
+            new Map<String, Object>{ 'LeadSource' => 'Phone', 'total' => 5},
+            new Map<String, Object>{ 'LeadSource' => 'Email', 'total' => 3}
+        };
+
+        SOQL.mock('mockingQuery').thenReturn(aggregateResults);
+
+        List<SOQL.AggregateResultProxy> result = SOQL.of(Lead.SObjectType)
+            .with(Lead.LeadSource)
+            .count(Lead.Id, 'total')
+            .groupBy(Lead.LeadSource)
+            .mockId('mockingQuery')
+            .toAggregatedProxy();
+
+        Assert.areEqual(3, result.size());
+        Assert.areEqual(10, result[0].get('total'));
+        Assert.areEqual('Web', result[0].get('LeadSource'));
+    }
+}
+```
+
 ## Avoid duplicates
 
-Generic SOQLs can be keep in selector class.
+Generic SOQLs can be kept in the selector class.
 
 ```apex
 public inherited sharing class SOQL_Account extends SOQL implements SOQL.Selector {
@@ -325,7 +355,7 @@ Did you know that?
 - Retrieving data from the cache takes less than 10ms.
 - Read operations (SOQL) account for approximately 70% of an org’s activity.
 
-Cache can significantly boost yours org’s performance. You can it use for objects like:
+Cache can significantly boost your org's performance. You can use it for objects like:
 
 - `Profile`
 - `BusinessHours`
@@ -358,21 +388,26 @@ public with sharing class SOQL_ProfileCache extends SOQLCache implements SOQLCac
 }
 ```
 
-## Enchanced SOQL
+## Enhanced SOQL
 
-Developers perform different SOQL results transformation.
-You can use many of predefined method that will reduce your code complexity.
+Developers perform different SOQL result transformations.
+You can use many predefined methods that will reduce your code complexity.
 
 ```apex
 Id toId();
+Set<Id> toIds();
+Set<Id> toIdsOf(SObjectField field);
+Set<Id> toIdsOf(String relationshipName, SObjectField field);
 Boolean doExist();
 String toString();
 Object toValueOf(SObjectField fieldToExtract);
 Set<String> toValuesOf(SObjectField fieldToExtract);
+Set<String> toValuesOf(String relationshipName, SObjectField targetKeyField);
 Integer toInteger();
 SObject toObject();
 List<SObject> toList();
 List<AggregateResult> toAggregated();
+List<AggregateResultProxy> toAggregatedProxy();
 Map<Id, SObject> toMap();
 Map<String, SObject> toMap(SObjectField keyField);
 Map<String, SObject> toMap(String relationshipName, SObjectField targetKeyField);

website/docs/docs/build-cached-selector.md

@@ -8,7 +8,7 @@ Check examples in the [repository](https://github.com/beyond-the-cloud-dev/soql-
 
 
 SOQL-Lib is agile, so you can adjust the solution according to your needs.
-We don't force one approach over another, you can choose your own. Here are our propositions:
+We don't force one approach over another; you can choose your own. Here are our suggestions:
 
 ## A - Inheritance - extends SOQLCache, implements Interface + static (Recommended)
 

website/docs/docs/build-your-selector.md

@@ -9,7 +9,7 @@ Check examples in the [repository](https://github.com/beyond-the-cloud-dev/soql-
 
 
 SOQL-Lib is agile, so you can adjust the solution according to your needs.
-We don't force one approach over another, you can choose your own. Here are our propositions:
+We don't force one approach over another; you can choose your own. Here are our suggestions:
 
 ## A - Inheritance - extends SOQL, implements Interface + static (Recommended)