Changes

Full Changelog: v3.1.1...v3.1.2

Metadata API Version Updated to v58.0

• Updated all metadata to API v58.0 (Summer '23 release)

Bugfixes

• Fixed an issue in Query.filterWhere() when filtering on Set<T> that would previously result in an exception due to invalid formatting in the generated query. Thanks to @ctcforce for reporting this (issue #43) and thanks to @jamessimone for fixing it! (PR #44)

Code Cleanup

• Updated all references to classes & enums in the Schema & System namespaces to explicitly include the namespaces (e.g., SObjectField is now Schema.SObjectField). This avoids installation issues due to naming collisions in orgs that have custom Apex classes with the same name as a class/enum in the System namespace

Installation Info

Core Unlocked Package - no namespace

• SF CLI: sf package install --apex-compile package --wait 20 --security-type AdminsOnly --package 04t5Y000001TsbQQAS
• SFDX CLI: sfdx package install --wait 20 --security-type AdminsOnly --package 04t5Y000001TsbQQAS
• Sandbox: https://test.salesforce.com/packaging/installPackage.apexp?p0=04t5Y000001TsbQQAS
• Production: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t5Y000001TsbQQAS

Core Unlocked Package - Nebula namespace

• SF CLI: sf package install --apex-compile package --wait 20 --security-type AdminsOnly --package 04t5Y000001TsbVQAS
• SFDX CLI: sfdx package install --wait 20 --security-type AdminsOnly --package 04t5Y000001TsbVQAS
• Sandbox: https://test.salesforce.com/packaging/installPackage.apexp?p0=04t5Y000001TsbVQAS
• Production: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t5Y000001TsbVQAS

Summary

Since it's been nearly 3 years since the last release, this release is not focused on making any major enhancements or bugfixes to the existing code. Instead, this PR is primarily focused on improving 2 areas:

1. Modernizing the repo: this PR includes the setup of dev tools like pre-commit hooks, prettier formatting, PMD scanning with sfdx scanner, document generation, and so on
2. Switching to using 2nd Generation Packages (2GP) for distributing the code: to try to make this switch easier for orgs that currently have the repo's code deployed, I don't want to make any drastic functional changes yet. Subsequent releases will focus on enhancements & bugfixes

New Unlocked Packages

Fixes #34 by providing 2 new unlocked packages:

• No namespace - this package can/should be used in orgs that have been previously been deploying the repo's code to their org. When the package is installed, the existing metadata in the org will be absorbed by the package, and orgs will then be able to easily upgrade to future versions of the package
• Nebula namespace - this package can be used in orgs where having a namespace is preferred. All metadata is the same, with the exception that the test suite QueryAndSearch is not included in the namespaced package

Code Cleanup & Changes

• Simplified directory structure within nebula-query-and-search directory
• Added & updated project config files (package.json, .forceignore, .gitignore, .prettierrc, etc)
• Bumped all Apex classes to API v57.0 (Spring '23)
• Added @SuppressWarnings annotations in Apex test classes. Several of these suppressions will eventually be removed in future releases, once I have time to address some of these issues - but for now, I've suppressed all known warnings
• Reformatted all of the Apex code, in a few ways
  • Changed casing of class names from Soql & Sosl to SOQL & SOSL
  • Added missing curly braces to any one-liner statements (e.g., statements like if (someBoolean) return; now uses curly braces like if (someBoolean) { return; }
  • Ran prettier on all files, including changing the tabWidth from 4 to 2 spaces
• Added ApexDocs comments to the top of each class + added precommit hooks for auto-generating docs markdown any time an Apex class is committed (using apexdocs)
  • I'll add more ApexDocs comments in future releases for methods, enums, and inner classes - for now, I just wanted to get the basics working
• Added Apex test suite QueryAndSearch
• Made some very minor improvements & clean-up in the test classes

Installation Info

Full Changelog: v3.1.0...v3.1.1

Core Unlocked Package - no namespace

• SF CLI: sf package install --apex-compile package --wait 20 --security-type AdminsOnly --package 04t5Y000001TsMOQA0
• SFDX CLI: sfdx package install --wait 20 --security-type AdminsOnly --package 04t5Y000001TsMOQA0
• Sandbox: https://test.salesforce.com/packaging/installPackage.apexp?p0=04t5Y000001TsMOQA0
• Production: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t5Y000001TsMOQA0

Core Unlocked Package - Nebula namespace

• SF CLI: sf package install --apex-compile package --wait 20 --security-type AdminsOnly --package 04t5Y000001TsMTQA0
• SFDX CLI: sfdx package install --wait 20 --security-type AdminsOnly --package 04t5Y000001TsMTQA0
• Sandbox: https://test.salesforce.com/packaging/installPackage.apexp?p0=04t5Y000001TsMTQA0
• Production: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t5Y000001TsMTQA0

• Converted metadata to SFDX format
• Upgraded to API v49.0
• Simplified naming convention used for classes

There are now 3 builder classes (SobjectQueryBuilder, AggregateQueryBuilder & SearchBuilder) and 2 abstract classes (Soql & Sosl). This seems to be a good balance between keeping the library relatively small (5 classes + test classes) while still keeping everything structured & scalable.

• Added new enum value, Soql.FieldCategory.IGNORE_FLS. This can be used to add a field to a query, regardless of the field-level security (FLS)
• Added 2 new overloaded versions of filterWhere method
  • public Soql filterWhere(QueryFilter filter)
  • public Soql filterWhere(List<QueryFilter> filters)
• Created 2 new subclasses
  • Soql.QueryArgument - takes an Object and formats it to use in a query
  • Soql.QueryFilter - represents a single where clause filter

Everything in the project has been simplified & consolidated into just 2 classes: Soql.cls and Sosl.cls.

The previous implementation had a growing number of interfaces & classes, so it was a fairly heavy package to install & learn to use. Rewriting and simplifying the library makes it easier to deploy & easier to learn.

The Nebula project has added a lot of new features for dynamic querying, but it's currently dependent on the rest of the Nebula framework. The query engine from Nebula has been ported so that it's a freestanding project that can be deployed without the rest of the framework.

• SObjectRepository.cls now handles query & serach execution, returning either an sobject or list of sobject (depending on which method is called)
  1. Existing classes will need to be updated to reflect this change
• Created SOQLUtils class to handle parsing a list of objects into the formatted expected by SOQL for each data type
• Deleted some old classes

Dynamic SOSL has been implemented with minimal changes to how the framework is used.

• Added ISObjectRespository.List<SObject> searchInAllFields(String searchTerm); to require one basic SOSL method per object
• Public methods can switch between using SOQL and SOSL by making 2 changes:
  1. Call the getSearchQuery method instead of getSearchQuery. 2 parameters are expected, String searchTerm and SObjectRepository.SearchGroup searchGroup
  2. Change return (Lead)Database.query(query); to return (Lead)Search.query(query)[0];. This is because SOSL returns a list of lists, so we need to get the first list from the... list of lists (this seems silly to explain).
• All other protected & private methods are shared between the SOQL & SOSL queries, with one exception: SObjectRepository.setAsUpdate() can be called, but is ignored for SOSL since SOSL does not support it. A debug statement with LoggingLevel.WARN will be shown in the logs in this situation.

Refactored again - core logic lives in the abstract class SObjectRepository & interface ISObjectRepository

• SObjectRepository uses field sets in the constructor and has several protected builder methods. These are used to give a structured method of building a query string
• Class constructors can be overloaded to allow a field set to passed in
• By default, some the common query fields are automatically added to the query. This includes audit fields (created by ID/created date, etc), name/subject fields, and a few other similar fields. A boolean can be passed to disable this
• Any queries needed in your codebase should be packaged as public methods. These should call any private/protected builder methods and return the results of the query, casted to the appropriate data type
• Two example concrete classes are included - LeadRepository.cls & TaskRepository.cls
• Two utils classes, CollectionUtils & StringUtils, are also included