documentation

Author: pgajek2

website/docs/docs/getting-started.md

@@ -52,7 +52,7 @@ Profile systemAdminProfile = (Profile) SOQLCache.of(Profile.SObjectType)
 
 ## Selector
 
-```apex
+```apex title="SOQL_Contact.cls"
 public inherited sharing class SOQL_Contact extends SOQL implements SOQL.Selector {
     public static SOQL_Contact query() {
         return new SOQL_Contact();
@@ -80,7 +80,7 @@ public inherited sharing class SOQL_Contact extends SOQL implements SOQL.Selecto
 
 **Usage**
 
-```apex
+```apex title="ExampleController.cls"
 public with sharing class ExampleController {
     @AuraEnabled
     public static List<Contact> getAccountContacts(Id accountId) {
@@ -95,7 +95,7 @@ public with sharing class ExampleController {
 
 ## Cached Selector
 
-```apex
+```apex title="SOQL_ProfileCache.cls"
 public with sharing class SOQL_ProfileCache extends SOQLCache implements SOQLCache.Selector {
     public static SOQL_ProfileCache query() {
         return new SOQL_ProfileCache();
@@ -120,7 +120,7 @@ public with sharing class SOQL_ProfileCache extends SOQLCache implements SOQLCac
 
 **Usage**
 
-```apex
+```apex title="ExampleController.cls"
 public with sharing class ExampleController {
     @AuraEnabled
     public static void createNewAdministrator(User newUser) {

website/docs/docs/overview.md

@@ -4,69 +4,95 @@ sidebar_position: 15
 
 # Overview
 
-## Assumptions
+## Concept
 
-1. **Small Selector Classes** - The selector class should be small and contain 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 method 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 method 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** - The selector should allow mocking data in unit tests.
+SOQL Lib is a modern Apex library designed as an intuitive alternative to the popular [FFLib Selectors](https://github.com/apex-enterprise-patterns/fflib-apex-common) framework. While FFLib was created over 10 years ago, we believe it hasn't kept up with modern Apex development practices, becoming a complex and cumbersome solution that often makes code more complicated than necessary.
 
-## Concepts
+Drawing from the best aspects of FFLib and other selector patterns, we've built SOQL Lib to be intuitive, performant, and reliable. This library is part of the Beyond The Cloud ecosystem, designed specifically for modern Salesforce development.
 
-SOQL Library consists of:
+## Design Principles
 
-- `SOQL Builder`
-- `SOQL Selector`
+We built SOQL Lib based on several key design principles that address common pain points in Salesforce development:
 
-## SOQL Builder
+1. **Lightweight Selector Classes** - Selector classes should remain focused and contain only essential query configurations (default fields, sharing settings) and generic, chainable methods like `byId()`, `byRecordType()`, and `byParentId()`. We avoid storing all queries in selector classes because:
+   - Large selector classes become difficult to maintain and navigate
+   - They create frequent merge conflicts in team environments  
+   - Complex query methods lead to unwieldy naming conventions
 
-SOQL Builder allows you to build queries dynamically and execute them.
+2. **Inline Query Construction** - Business-specific queries should be built inline using the `SOQL` builder exactly where they're needed:
+   - Most queries in a project are context-specific rather than reusable
+   - Developers can construct queries dynamically using our fluent API
+   - This approach eliminates the need for countless specialized selector methods
+
+3. **Dynamic Query Building** - The library provides full flexibility to adjust queries with specific fields, conditions, and SOQL clauses at runtime, enabling responsive and adaptable code.
+
+4. **Simplified Method Naming** - By building queries inline, developers avoid the complexity of naming methods like `selectByFieldAAndFieldBWithDescOrder()`. The fluent API speaks for itself.
+
+5. **Granular Security Controls** - Built-in support for Field-Level Security and sharing settings through intuitive methods like `.systemMode()`, `.withSharing()`, and `.withoutSharing()`.
+
+6. **Automatic Variable Binding** - Dynamic variable binding eliminates boilerplate code and reduces the potential for binding errors.
+
+7. **Comprehensive Testing Support** - Native mocking capabilities make unit testing SOQL queries straightforward and reliable.
+
+8. **Performance Optimization** - Query results can be cached at multiple levels (Org Cache, Session Cache, Apex Transaction Cache) to improve application performance.
+
+9. **Developer Experience** - The API is designed to be intuitive and self-documenting, minimizing the learning curve while maximizing productivity.
+
+## Architecture
+
+SOQL Lib consists of three distinct modules, each designed to address different use cases and development preferences:
+
+### [`SOQL`](../soql/getting-started.md) - Core Module
+
+The foundation of SOQL Lib, providing a comprehensive fluent API for constructing and executing SOQL queries. This module includes both SOQL Builder for direct query construction and SOQL Selectors for reusable query patterns. The architecture is flexible—developers can build queries directly without selectors or leverage selectors for commonly used query configurations.
+
+**Key Features:**
+- Fluent API for intuitive query construction
+- Field-Level Security enforcement with `withUserMode()` and `systemMode()`
+- Granular sharing control (`withSharing()` and `withoutSharing()`)
+- Automatic variable binding and SOQL injection prevention
+- Comprehensive result transformation methods
+- Built-in mocking support for unit tests
 
 ```apex
-// SELECT Id, Name, Industry FROM Account
+// SELECT Id, Name, Industry FROM Account WITH USER_MODE
 List<Account> accounts = SOQL.of(Account.SObjectType)
    .with(Account.Id, Account.Name, Account.Industry)
    .toList();
 ```
 
-## SOQL Selector
-
-> A selector layer contains code responsible for querying records from the database. Although you can place SOQL queries in other layers, a few things can happen as the complexity of your code grows. ~ Salesforce
-
-**SOQL Lib provides the whole new concept for Selectors usage.**
-
-### Old Approach
+### [`Cache`](../cache/getting-started.md) - Performance Module _(Optional)_
 
-[FFLIB Selector](https://github.com/apex-enterprise-patterns/fflib-apex-common/blob/master/sfdx-source/apex-common/main/classes/fflib_SObjectSelector.cls) concept assumes that all queries should be stored in the Selector class.
+An optional but highly recommended module that dramatically improves application performance by caching query results across different storage levels. Ideal for frequently accessed, slowly-changing data such as configuration records, metadata, and reference data.
 
-- To avoid duplicates.
-- One place to manage all queries.
+**Key Features:**
+- Multi-level caching: Org Cache, Session Cache, and Apex Transaction Cache
+- Automatic cache expiration with `maxHoursWithoutRefresh()`
+- Built-in cache management and removal capabilities
 
-**Issues**:
-- One-time queries (like aggregation, case specific) added to Selector.
-- Huge class with a lot of methods.
-- Queries are difficult to reuse.
-- Similar methods with small differences like limit, offset.
-- Problem with naming methods.
-- Merge conflicts.
-
-### New Approach
+```apex
+// Cached query with 24-hour refresh policy
+Profile profile = (Profile) SOQLCache.of(Profile.SObjectType)
+    .with(Profile.Id, Profile.Name)
+    .whereEqual(Profile.Name, 'System Administrator')
+    .cacheInOrgCache()
+    .maxHoursWithoutRefresh(24)
+    .toObject();
+```
 
-The SOQL Lib has a slightly different approach.
+### [`Evaluator`](../evaluator/getting-started.md) - Legacy Bridge Module _(Optional)_
 
-**Assumption**:
+Designed for developers who prefer traditional SOQL syntax but want to leverage SOQL Lib's enhanced capabilities. This module processes static query result, providing advanced result transformation methods and mocking capabilities without requiring adoption of the full SOQL Builder syntax.
 
-Most of the SOQLs on the project are **one-time** queries executed for specific business cases.
+**Key Features:**
+- Process results from standard SOQL queries
+- Enhanced result transformation methods (`toIds()`, `toValueOf()`, `toMap()`, etc.)
+- Simplified mocking for unit tests
+- Field-Level Security processing with `stripInaccessible()`
+- Zero learning curve for traditional SOQL developers
 
-**Solution**:
-1. **Small Selector Classes** - Selector class should be small and contain ONLY query base configuration (fields, sharing settings) and very generic methods (`byId`, `byRecordType`)
-2. **Build SOQL inline in a place of need** - Business-specific SOQLs should be built inline via the SOQL builder in the place of need.
-3. **Do not spend time on selector method naming** - Queries are created inline, so there's no need to find a name.
-4. **Keep Selector Strengths** - Set default Selector configuration (default fields, sharing settings), keep generic methods.
+```apex
+// Enhanced processing of standard SOQL results
+Set<Id> accountIds = SOQLEvaluator.of([SELECT Id FROM Account]).toIds();
+Boolean hasAccounts = SOQLEvaluator.of([SELECT Id FROM Account]).doExist();
+```

website/docs/soql/build-selector.md

@@ -19,6 +19,35 @@ 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**. 
 
+## Old Approach
+
+[FFLIB Selector](https://github.com/apex-enterprise-patterns/fflib-apex-common/blob/master/sfdx-source/apex-common/main/classes/fflib_SObjectSelector.cls) concept assumes that all queries should be stored in the Selector class.
+
+- To avoid duplicates.
+- One place to manage all queries.
+
+**Issues**:
+- One-time queries (like aggregation, case specific) added to Selector.
+- Huge class with a lot of methods.
+- Queries are difficult to reuse.
+- Similar methods with small differences like limit, offset.
+- Problem with naming methods.
+- Merge conflicts.
+
+## New Approach
+
+The SOQL Lib has a slightly different approach.
+
+**Assumption**:
+
+Most of the SOQLs on the project are **one-time** queries executed for specific business cases.
+
+**Solution**:
+1. **Small Selector Classes** - Selector class should be small and contain ONLY query base configuration (fields, sharing settings) and very generic methods (`byId`, `byRecordType`)
+2. **Build SOQL inline in a place of need** - Business-specific SOQLs should be built inline via the SOQL builder in the place of need.
+3. **Do not spend time on selector method naming** - Queries are created inline, so there's no need to find a name.
+4. **Keep Selector Strengths** - Set default Selector configuration (default fields, sharing settings), keep generic methods.
+
 ## A - Inheritance - extends SOQL, implements Interface + static _(Recommended)_
 
 Most Flexible Approach: