Design

Single class

SOQL Lib is a single-class solution.

You don't need to think about dependencies; everything you need is stored in SOQL.cls. The SOQL.cls only takes around 1500 lines of code.

Different clauses are encapsulated in small, inner classes. All crucial information is kept at the top of the class, so developers can use it even without reading the documentation.

public static SubQuery SubQuery {
    get {
        return new QSubQuery();
    }
}

public static FilterGroup FilterGroup { // A group to nest more filters
    get {
        return new QFilterGroup();
    }
}

public static Filter Filter {
    get {
        return new QFilter();
    }
}

public static InnerJoin InnerJoin {
    get {
        return new QJoinQuery();
    }
}

public interface Selector {
    Queryable query();
}

public interface Queryable {
    Queryable of(SObjectType ofObject);
    Queryable of(String ofObject); // Dynamic SOQL

    Queryable with(SObjectField field);
    Queryable with(SObjectField field1, SObjectField field2);
    Queryable with(SObjectField field1, SObjectField field2, SObjectField field3);
    Queryable with(SObjectField field1, SObjectField field2, SObjectField field3, SObjectField field4);
    Queryable with(SObjectField field1, SObjectField field2, SObjectField field3, SObjectField field4, SObjectField field5);
    Queryable with(List<SObjectField> fields); // For more than 5 fields
    Queryable with(String fields); // Dynamic SOQL
    Queryable with(SObjectField field, String alias); // Only aggregate expressions use field aliasing
    Queryable with(String relationshipName, SObjectField field);
    Queryable with(String relationshipName, SObjectField field1, SObjectField field2);
    Queryable with(String relationshipName, SObjectField field1, SObjectField field2, SObjectField field3);
    Queryable with(String relationshipName, SObjectField field1, SObjectField field2, SObjectField field3, SObjectField field4);
    Queryable with(String relationshipName, SObjectField field1, SObjectField field2, SObjectField field3, SObjectField field4, SObjectField field5);
    Queryable with(String relationshipName, List<SObjectField> fields); // For more than 5 fields
    Queryable with(SubQuery subQuery); // SOQL.SubQuery

    Queryable count();
    Queryable count(SObjectField field);
    Queryable count(SObjectField field, String alias);

    Queryable delegatedScope();
    Queryable mineScope();
    Queryable mineAndMyGroupsScope();
    Queryable myTerritoryScope();
    Queryable myTeamTerritoryScope();
    Queryable teamScope();

    Queryable whereAre(FilterGroup filterGroup); // SOQL.FilterGroup
    Queryable whereAre(Filter filter); // SOQL.Filter
    Queryable whereAre(String conditions); // Conditions to evaluate

    Queryable groupBy(SObjectField field);
    Queryable groupByRollup(SObjectField field);
    Queryable groupByCube(SObjectField field);

    Queryable orderBy(String field); // ASC, NULLS FIRST by default
    Queryable orderBy(String field, String direction); // dynamic order by, NULLS FIRST by default
    Queryable orderBy(SObjectField field); // ASC, NULLS FIRST by default
    Queryable orderBy(String relationshipName, SObjectField field); // ASC, NULLS FIRST by default
    Queryable sortDesc();
    Queryable nullsLast();

    Queryable setLimit(Integer amount);

    Queryable offset(Integer startingRow);

    Queryable forReference();
    Queryable forView();
    Queryable forUpdate();
    Queryable allRows();

    Queryable systemMode(); // USER_MODE by default

    Queryable withSharing(); // Works only with .systemMode()
    Queryable withoutSharing(); // Works only with .systemMode()

    Queryable mockId(String id);

    Queryable preview();

    Queryable stripInaccessible();
    Queryable stripInaccessible(AccessType accessType);

    Queryable byId(SObject record);
    Queryable byId(Id recordId);
    Queryable byIds(Iterable<Id> recordIds); // List or Set
    Queryable byIds(List<SObject> records);

    String toString();
    Object toValueOf(SObjectField fieldToExtract);
    Set<String> toValuesOf(SObjectField fieldToExtract);
    Integer toInteger(); // For COUNT query
    SObject toObject();
    List<SObject> toList();
    List<AggregateResult> toAggregated();
    Map<Id, SObject> toMap();
    Database.QueryLocator toQueryLocator();
}

public interface SubQuery { // SOQL.SubQuery
    SubQuery of(String ofObject);

    SubQuery with(SObjectField field);
    SubQuery with(SObjectField field1, SObjectField field2);
    SubQuery with(SObjectField field1, SObjectField field2, SObjectField field3);
    SubQuery with(SObjectField field1, SObjectField field2, SObjectField field3, SObjectField field4);
    SubQuery with(SObjectField field1, SObjectField field2, SObjectField field3, SObjectField field4, SObjectField field5);
    SubQuery with(List<SObjectField> fields); // For more than 5 fields
    SubQuery with(String relationshipName, List<SObjectField> fields);
    SubQuery with(SubQuery subQuery); // SOQL.SubQuery

    SubQuery whereAre(FilterGroup filterGroup); // SOQL.FilterGroup
    SubQuery whereAre(Filter filter); // SOQL.Filter

    SubQuery orderBy(SObjectField field);
    SubQuery orderBy(String relationshipName, SObjectField field);
    SubQuery sortDesc();
    SubQuery nullsLast();

    SubQuery setLimit(Integer amount);

    SubQuery offset(Integer startingRow);

    SubQuery forReference();
    SubQuery forView();
}

public interface FilterGroup { // SOQL.FilterGroup
    FilterGroup add(FilterGroup filterGroup); // SOQL.FilterGroup
    FilterGroup add(Filter filter); // SOQL.Filter
    FilterGroup add(String dynamicCondition); // Pass condition as String

    FilterGroup anyConditionMatching(); // All group filters will be join by OR
    FilterGroup conditionLogic(String order);

    Boolean hasValues();
}

public interface Filter { // SOQL.Filter
    Filter id();
    Filter recordType();
    Filter name();
    Filter with(SObjectField field);
    Filter with(String field);
    Filter with(String relationshipName, SObjectField field);

    Filter isNull(); // = NULL
    Filter isNotNull(); // != NULL
    Filter isTrue(); // = TRUE
    Filter isFalse(); // = FALSE
    Filter equal(Object value); // = :value
    Filter notEqual(Object value); // != :value
    Filter lessThan(Object value); // < :value
    Filter greaterThan(Object value); // > :value
    Filter lessOrEqual(Object value); // <= :value
    Filter greaterOrEqual(Object value); // >= :value
    Filter containsSome(List<String> values); // LIKE :values
    Filter contains(String value); // LIKE :'%' + value + '%'
    Filter endsWith(String value); // LIKE :'%' + value
    Filter startsWith(String value); // LIKE :value + '%'
    Filter contains(String prefix, String value, String suffix); // custom LIKE
    Filter isIn(Iterable<Object> iterable); // IN :inList or inSet
    Filter isIn(List<Object> inList); // IN :inList
    Filter isIn(InnerJoin joinQuery); // SOQL.InnerJoin
    Filter notIn(Iterable<Object> iterable); // NOT IN :inList or inSet
    Filter notIn(List<Object> inList); // NOT IN :inList
    Filter notIn(InnerJoin joinQuery); // SOQL.InnerJoin
    Filter includesAll(Iterable<String> values); // join with ;
    Filter includesSome(Iterable<String> values); // join with ,
    Filter excludesAll(Iterable<String> values); // join with ,
    Filter excludesSome(Iterable<String> values);  // join with ;

    Filter ignoreWhen(Boolean logicExpression);

    Boolean hasValue();
}

public interface InnerJoin { // SOQL.InnerJoin
    InnerJoin of(SObjectType ofObject);

    InnerJoin with(SObjectField field);

    InnerJoin whereAre(FilterGroup filterGroup); // SOQL.FilterGroup
    InnerJoin whereAre(Filter filter); // SOQL.Filter
}

@TestVisible
private static void setMock(String mockId, SObject record) {
    setMock(mockId, new List<SObject>{ record });
}

@TestVisible
private static void setMock(String mockId, List<SObject> records) {
    mock.setMock(mockId, records);
}

@TestVisible
private static void setCountMock(String mockId, Integer amount) {
    mock.setCountMock(mockId, amount);
}

Functional Programming

SOQL Lib uses the concept called Apex Functional Programming.

You can see an example of it with SOQL.SubQuery, SOQL.FilterGroup, SOQL.Filter and SOQL.InnerJoin. Those classes encapsulate the logic, and only necessary methods are exposed via interfaces.

Queryable whereAre(FilterGroup filterGroup); // SOQL.FilterGroup
Queryable whereAre(Filter filter); // SOQL.Filter

SOQL.of(Account.SObjectType)
     .with(Account.Id, Account.Name);
     .whereAre(SOQL.FilterGroup
        .add(SOQL.Filter.id().equal(accountId))
        .add(SOQL.Filter.with(Account.Name).contains(accountName))
        .anyConditionMatching() // OR
      )
     .toList();

Return Concrete SOQL instance

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;
    }
}

As you can see, the method byIndustry(String industry) returns an instance of SOQL_Account instead of List<SObject> or Object. Why is that? You can adjust the query to your needs and add more SOQL clauses without duplicating the code.

SOQL_Account.query()
    .byIndustry('IT')
    .orderBy(Account.Name)
    .toList();