SOQL Lib

When mocking results, SOQL Lib simulates standard Salesforce SOQL behavior regarding fields:

1. Automatic Id Inclusion: The Id field is always included in mocked results, even if it was not explicitly requested in the .with() clause.
2. Field Stripping: To simulate real SOQL, SOQL Lib strips all fields from the mocked data that were not explicitly included in the query's .with() clause.
   • Note: This currently applies to simple fields and subqueries.
   • Limitation: Relationship fields and queries using functions (like COUNT, AVG) are not yet subject to stripping and will return the exact mock provided.

// Setup data with extra fields
List<Account> accounts = new List<Account>{ 
    new Account(Name = 'Test 1', Description = 'Should be stripped') 
};
SOQL.mock('mockingQuery').thenReturn(accounts);

// Query only Name
List<Account> result = SOQL.of(Account.SObjectType)
    .with(Account.Name)
    .mockId('mockingQuery')
    .toList();

// result[0].Name is 'Test 1'
// result[0].Description is null (stripped)

SOQL Lib supports a FIFO (First In, First Out) stack for multiple mocks assigned to the same ID. This allows you to simulate a query returning different results on consecutive calls.

• Single Mock: If you only define one mock for an ID, it is reused for every execution of that query.
• Multiple Mocks: Each call to SOQL.mock(id).thenReturn(data) adds a new entry to the stack. Each time the query is executed, the first mock in the stack is consumed and removed. The last mock in the stack is not removed and will be returned for all subsequent calls.

// Setup multiple sequential mocks
SOQL.mock('testQuery').thenReturn(new Account(Name = 'First Call'));
SOQL.mock('testQuery').thenReturn(new Account(Name = 'Second Call'));
SOQL.mock('testQuery').thenReturn(new Account(Name = 'Third Call'));

// First execution returns "First Call", then removes that mock
Account result1 = SOQL.of(Account.SObjectType).mockId('testQuery').toObject();

// Second execution returns "Second Call", then removes that mock
Account result2 = SOQL.of(Account.SObjectType).mockId('testQuery').toObject();

// Third execution returns "Third Call", but does not remove it
Account result3 = SOQL.of(Account.SObjectType).mockId('testQuery').toObject();

// Fourth execution also returns "Third Call"
Account result4 = SOQL.of(Account.SObjectType).mockId('testQuery').toObject();

SOQL Cached Selectors are the recommended way to implement caching. Instead of building queries ad-hoc, you create a class per SObjectType that extends SOQLCache and implements SOQLCache.Selector.

This approach allows you to:

1. Set default caching configurations (fields, cache scope, TTL) for a specific object in the constructor.
2. Centralize reusable cached queries in one place.
3. Provide a clean, domain-specific API (e.g., .byName()) for querying that object.

public inherited sharing class SOQL_CachedProfile extends SOQLCache implements SOQLCache.Selector {
    public static SOQL_CachedProfile query() {
        return new SOQL_CachedProfile();
    }

    private SOQL_CachedProfile() {
        super(Profile.SObjectType);
        // default settings
        with(Profile.Id, Profile.Name, Profile.UserType)
            .cacheInOrgCache()
            .maxHoursWithoutRefresh(36);
    }

    public override SOQL.Queryable initialQuery() {
        return SOQL.of(Profile.SObjectType);
    }

    public SOQL_CachedProfile byName(String profileName) {
        whereEqual(Profile.Name, profileName);
        return this;
    }
}

Instead of returning a raw List<SObject> or Object immediately, you can design custom query classes that extend SOQL and implement SOQL.Selector. By having domain-specific methods return this (the concrete class instance), you allow developers to chain additional SOQL clauses or domain-specific filters without duplicating code.

This pattern enables a highly readable and reusable query builder for specific SObjects.

// 1. Define a custom query class
public inherited sharing class SOQL_Account extends SOQL implements SOQL.Selector {
    public static SOQL_Account query() {
        return new SOQL_Account();
    }

    private SOQL_Account() {
        super(Account.SObjectType);
        // default settings
        with(Account.Name, Account.AccountNumber)
            .systemMode();
    }

    public SOQL_Account byIndustry(String industry) {
        with(Account.Industry)
            .whereAre(Filter.with(Account.Industry).equal(industry));
        return this; // Returns the concrete class to allow further chaining
    }
}

// 2. Use the custom query class with chaining
SOQL_Account.query()
    .byIndustry('IT')
    .orderBy(Account.Name)
    .toList();

The Cacheable interface (used by SOQLCache) provides a limited set of operations specifically for retrieving and managing cached records. Unlike the standard SOQL Library, methods related to sharing rules (e.g., withSharing(), withoutSharing()) or query scoping (e.g., forView()) are not available because cached records are retrieved directly from storage, bypassing standard database access controls.

Key categories of methods available in the Cacheable interface include:

• Configuration: cacheInApexTransaction(), cacheInOrgCache(), cacheInSessionCache(), and maxHoursWithoutRefresh(Integer hours).
• Selection: with(...) to specify fields, whereEqual(...) for filtering, and byId(...) for direct ID lookups.
• Security: stripInaccessible() to enforce field-level security.
• Results: toId(), doExist(), toObject(), and toValueOf(SObjectField fieldToExtract) to extract the data.

public interface Cacheable {
    // CONFIG
    Cacheable cacheInApexTransaction();
    Cacheable cacheInOrgCache();
    Cacheable cacheInSessionCache();
    Cacheable maxHoursWithoutRefresh(Integer hours);
    // SELECT
    Cacheable with(SObjectField field);
    Cacheable with(List<SObjectField> fields);
    Cacheable with(String fields);
    // WHERE
    Cacheable whereEqual(SObjectField field, Object value);
    Cacheable whereEqual(String field, Object value);
    // FIELD-LEVEL SECURITY
    Cacheable stripInaccessible();
    Cacheable stripInaccessible(AccessType accessType);
    // MOCKING
    Cacheable mockId(String queryIdentifier);
    // DEBUGGING
    Cacheable preview();
    // PREDEFINED
    Cacheable byId(SObject record);
    Cacheable byId(Id recordId);
    // RESULT
    Id toId();
    Boolean doExist();
    SObject toObject();
    Object toValueOf(SObjectField fieldToExtract);
}

A Selector is a specialized class extending SOQL that implements SOQL.Selector. It is designed to encapsulate core query logic for a specific object while remaining lightweight.

Best Practices:

1. Minimal Default Fields: Only include essential identifiers (like Id) and commonly used fields in the constructor to improve performance.
2. Method Chaining: Implement domain-specific methods (e.g., byIndustry(String industry)) that return this to allow for fluent query construction.
3. Dynamic Extension: Allow callers to add additional fields via .with() or complex clauses via .whereAre() at the point of use, rather than bloating the selector with every possible permutation.

public inherited sharing class SOQL_Account extends SOQL implements SOQL.Selector {
    public static SOQL_Account query() {
        return new SOQL_Account();
    }

    private SOQL_Account() {
        super(Account.SObjectType);
        with(Account.Id, Account.Name);
        systemMode();
        withoutSharing();
    }

    public SOQL_Account byType(String type) {
        whereAre(Filter.with(Account.Type).equal(type));
        return this;
    }
}

// Usage
List<Account> accounts = SOQL_Account.query()
    .byType('Partner')
    .with(Account.AnnualRevenue)
    .toList();