@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/querying-soql/references/selector-patterns.md

@@ -0,0 +1,479 @@
+<!-- Parent: querying-soql/SKILL.md -->
+# Selector Patterns: Query Abstraction in Vanilla Apex
+
+This guide teaches query abstraction patterns using pure Apex — no external libraries required. These patterns improve testability, maintainability, and security compliance.
+
+---
+
+## Why Use a Selector Layer?
+
+### The Problem
+
+Without abstraction, SOQL queries are scattered everywhere:
+
+```apex
+// In TriggerHandler.cls
+List<Account> accounts = [SELECT Id, Name FROM Account WHERE Id IN :accountIds];
+
+// In BatchJob.cls (duplicate!)
+List<Account> accounts = [SELECT Id, Name FROM Account WHERE Id IN :ids];
+
+// In ServiceClass.cls (slightly different fields!)
+List<Account> accounts = [SELECT Id, Name, Industry FROM Account WHERE Id IN :accountIds];
+```
+
+**Problems**:
+1. **Duplication**: Same query logic repeated
+2. **Inconsistency**: Different fields queried in different places
+3. **Fragility**: Field deletion breaks multiple classes
+4. **Testability**: Must create real records to test
+5. **Security**: FLS/sharing often forgotten
+
+### The Solution
+
+Centralize queries in Selector classes:
+
+```apex
+// Single source of truth
+public class AccountSelector {
+    public static List<Account> byIds(Set<Id> accountIds) {
+        return [
+            SELECT Id, Name, Industry
+            FROM Account
+            WHERE Id IN :accountIds
+            WITH SECURITY_ENFORCED
+        ];
+    }
+}
+
+// Usage everywhere
+List<Account> accounts = AccountSelector.byIds(accountIds);
+```
+
+---
+
+## Pattern 1: Basic Selector Class
+
+The simplest approach - a class with static query methods.
+
+```apex
+/**
+ * AccountSelector - Centralized queries for Account object
+ */
+public inherited sharing class AccountSelector {
+
+    // ═══════════════════════════════════════════════════════════════════
+    // FIELD SETS (centralized field lists)
+    // ═══════════════════════════════════════════════════════════════════
+
+    private static final List<SObjectField> STANDARD_FIELDS = new List<SObjectField>{
+        Account.Id,
+        Account.Name,
+        Account.Industry,
+        Account.AnnualRevenue,
+        Account.OwnerId
+    };
+
+    // ═══════════════════════════════════════════════════════════════════
+    // QUERY METHODS
+    // ═══════════════════════════════════════════════════════════════════
+
+    /**
+     * Query accounts by their IDs
+     */
+    public static List<Account> byIds(Set<Id> accountIds) {
+        if (accountIds == null || accountIds.isEmpty()) {
+            return new List<Account>();
+        }
+        return [
+            SELECT Id, Name, Industry, AnnualRevenue, OwnerId
+            FROM Account
+            WHERE Id IN :accountIds
+            WITH SECURITY_ENFORCED
+        ];
+    }
+
+    /**
+     * Query accounts by Owner
+     */
+    public static List<Account> byOwnerId(Id ownerId) {
+        return [
+            SELECT Id, Name, Industry, AnnualRevenue, OwnerId
+            FROM Account
+            WHERE OwnerId = :ownerId
+            WITH SECURITY_ENFORCED
+            LIMIT 1000
+        ];
+    }
+
+    /**
+     * Query accounts with their contacts
+     */
+    public static List<Account> withContactsByIds(Set<Id> accountIds) {
+        return [
+            SELECT Id, Name,
+                   (SELECT Id, FirstName, LastName, Email
+                    FROM Contacts
+                    WHERE IsActive__c = true
+                    LIMIT 50)
+            FROM Account
+            WHERE Id IN :accountIds
+            WITH SECURITY_ENFORCED
+        ];
+    }
+}
+```
+
+**Usage**:
+```apex
+// Clean, readable, testable
+List<Account> accounts = AccountSelector.byIds(accountIdSet);
+List<Account> myAccounts = AccountSelector.byOwnerId(UserInfo.getUserId());
+```
+
+---
+
+## Pattern 2: Selector with Sharing Modes
+
+Control sharing rules at the selector level.
+
+```apex
+/**
+ * ContactSelector with sharing mode control
+ */
+public class ContactSelector {
+
+    // ═══════════════════════════════════════════════════════════════════
+    // USER MODE (respects sharing rules - default)
+    // ═══════════════════════════════════════════════════════════════════
+
+    public inherited sharing class UserMode {
+        public static List<Contact> byAccountIds(Set<Id> accountIds) {
+            return [
+                SELECT Id, FirstName, LastName, Email, AccountId
+                FROM Contact
+                WHERE AccountId IN :accountIds
+                WITH USER_MODE
+            ];
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════════════
+    // SYSTEM MODE (bypasses sharing - use carefully!)
+    // ═══════════════════════════════════════════════════════════════════
+
+    public without sharing class SystemMode {
+        public static List<Contact> byAccountIds(Set<Id> accountIds) {
+            return [
+                SELECT Id, FirstName, LastName, Email, AccountId
+                FROM Contact
+                WHERE AccountId IN :accountIds
+                WITH SYSTEM_MODE
+            ];
+        }
+    }
+}
+
+// Usage
+List<Contact> visibleContacts = ContactSelector.UserMode.byAccountIds(ids);
+List<Contact> allContacts = ContactSelector.SystemMode.byAccountIds(ids);
+```
+
+---
+
+## Pattern 3: Mockable Selector (for Unit Tests)
+
+Enable query mocking without database calls.
+
+```apex
+/**
+ * OpportunitySelector with mocking support
+ */
+public inherited sharing class OpportunitySelector {
+
+    // Test-visible mock data
+    @TestVisible
+    private static List<Opportunity> mockData;
+
+    /**
+     * Query opportunities by Account IDs
+     * Returns mock data in tests if set
+     */
+    public static List<Opportunity> byAccountIds(Set<Id> accountIds) {
+        if (Test.isRunningTest() && mockData != null) {
+            return mockData;
+        }
+        return [
+            SELECT Id, Name, StageName, Amount, CloseDate, AccountId
+            FROM Opportunity
+            WHERE AccountId IN :accountIds
+            WITH SECURITY_ENFORCED
+        ];
+    }
+
+    /**
+     * Set mock data for testing
+     */
+    @TestVisible
+    private static void setMockData(List<Opportunity> opportunities) {
+        mockData = opportunities;
+    }
+}
+```
+
+**Test Usage**:
+```apex
+@IsTest
+private class OpportunitySelectorTest {
+    @IsTest
+    static void testByAccountIds_returnsMockData() {
+        // Arrange - no database records needed!
+        List<Opportunity> mockOpps = new List<Opportunity>{
+            new Opportunity(Name = 'Test Opp', StageName = 'Prospecting', Amount = 1000)
+        };
+        OpportunitySelector.setMockData(mockOpps);
+
+        // Act
+        List<Opportunity> result = OpportunitySelector.byAccountIds(new Set<Id>());
+
+        // Assert
+        System.assertEquals(1, result.size());
+        System.assertEquals('Test Opp', result[0].Name);
+    }
+}
+```
+
+---
+
+## Pattern 4: Query Builder (Dynamic SOQL)
+
+For complex, dynamic queries that vary at runtime.
+
+```apex
+/**
+ * Dynamic query builder for flexible SOQL construction
+ */
+public inherited sharing class QueryBuilder {
+
+    private String objectName;
+    private Set<String> fields = new Set<String>();
+    private List<String> conditions = new List<String>();
+    private Map<String, Object> bindings = new Map<String, Object>();
+    private String orderByClause;
+    private Integer limitCount;
+
+    /**
+     * Constructor
+     */
+    public QueryBuilder(String objectName) {
+        this.objectName = objectName;
+    }
+
+    /**
+     * Add fields to select
+     */
+    public QueryBuilder selectFields(List<String> fieldList) {
+        fields.addAll(fieldList);
+        return this;
+    }
+
+    /**
+     * Add fields using SObjectField tokens (type-safe!)
+     */
+    public QueryBuilder selectFields(List<SObjectField> fieldTokens) {
+        for (SObjectField token : fieldTokens) {
+            fields.add(String.valueOf(token));
+        }
+        return this;
+    }
+
+    /**
+     * Add WHERE condition with binding
+     */
+    public QueryBuilder whereEquals(String field, Object value) {
+        String bindName = 'bind' + bindings.size();
+        conditions.add(field + ' = :' + bindName);
+        bindings.put(bindName, value);
+        return this;
+    }
+
+    /**
+     * Add WHERE IN condition
+     */
+    public QueryBuilder whereIn(String field, Set<Id> ids) {
+        String bindName = 'bind' + bindings.size();
+        conditions.add(field + ' IN :' + bindName);
+        bindings.put(bindName, ids);
+        return this;
+    }
+
+    /**
+     * Add ORDER BY
+     */
+    public QueryBuilder orderBy(String field, Boolean ascending) {
+        orderByClause = field + (ascending ? ' ASC' : ' DESC');
+        return this;
+    }
+
+    /**
+     * Add LIMIT
+     */
+    public QueryBuilder setLimit(Integer count) {
+        limitCount = count;
+        return this;
+    }
+
+    /**
+     * Build and execute the query
+     */
+    public List<SObject> execute() {
+        String query = buildQuery();
+        return Database.queryWithBinds(query, bindings, AccessLevel.USER_MODE);
+    }
+
+    /**
+     * Build query string (for debugging)
+     */
+    public String buildQuery() {
+        List<String> parts = new List<String>();
+
+        // SELECT
+        if (fields.isEmpty()) {
+            fields.add('Id');
+        }
+        parts.add('SELECT ' + String.join(new List<String>(fields), ', '));
+
+        // FROM
+        parts.add('FROM ' + objectName);
+
+        // WHERE
+        if (!conditions.isEmpty()) {
+            parts.add('WHERE ' + String.join(conditions, ' AND '));
+        }
+
+        // ORDER BY
+        if (orderByClause != null) {
+            parts.add('ORDER BY ' + orderByClause);
+        }
+
+        // LIMIT
+        if (limitCount != null) {
+            parts.add('LIMIT ' + limitCount);
+        }
+
+        return String.join(parts, ' ');
+    }
+}
+```
+
+**Usage**:
+```apex
+// Fluent API for dynamic queries
+List<SObject> results = new QueryBuilder('Account')
+    .selectFields(new List<SObjectField>{Account.Id, Account.Name, Account.Industry})
+    .whereEquals('Industry', 'Technology')
+    .whereIn('Id', accountIds)
+    .orderBy('Name', true)
+    .setLimit(100)
+    .execute();
+
+// Debug the generated query
+System.debug(new QueryBuilder('Account').selectFields(...).buildQuery());
+// "SELECT Id, Name, Industry FROM Account WHERE Industry = :bind0 AND Id IN :bind1 ORDER BY Name ASC LIMIT 100"
+```
+
+---
+
+## Pattern 5: Bulkified Query Pattern
+
+The Map-based lookup pattern for bulk operations.
+
+```apex
+/**
+ * BulkQueryHelper - Reusable bulk query patterns
+ */
+public inherited sharing class BulkQueryHelper {
+
+    /**
+     * Get Accounts by ID as a Map (O(1) lookup)
+     */
+    public static Map<Id, Account> getAccountMapByIds(Set<Id> accountIds) {
+        return new Map<Id, Account>([
+            SELECT Id, Name, Industry
+            FROM Account
+            WHERE Id IN :accountIds
+            WITH SECURITY_ENFORCED
+        ]);
+    }
+
+    /**
+     * Get Contacts grouped by AccountId
+     */
+    public static Map<Id, List<Contact>> getContactsByAccountId(Set<Id> accountIds) {
+        Map<Id, List<Contact>> contactsByAccount = new Map<Id, List<Contact>>();
+
+        for (Contact c : [
+            SELECT Id, FirstName, LastName, Email, AccountId
+            FROM Contact
+            WHERE AccountId IN :accountIds
+            WITH SECURITY_ENFORCED
+        ]) {
+            if (!contactsByAccount.containsKey(c.AccountId)) {
+                contactsByAccount.put(c.AccountId, new List<Contact>());
+            }
+            contactsByAccount.get(c.AccountId).add(c);
+        }
+
+        return contactsByAccount;
+    }
+}
+```
+
+**Usage in Trigger**:
+```apex
+// ❌ WRONG: Query per record
+for (Opportunity opp : Trigger.new) {
+    Account a = [SELECT Name FROM Account WHERE Id = :opp.AccountId];
+}
+
+// ✅ CORRECT: Bulk query with Map lookup
+Set<Id> accountIds = new Set<Id>();
+for (Opportunity opp : Trigger.new) {
+    accountIds.add(opp.AccountId);
+}
+
+Map<Id, Account> accountMap = BulkQueryHelper.getAccountMapByIds(accountIds);
+
+for (Opportunity opp : Trigger.new) {
+    Account a = accountMap.get(opp.AccountId);
+    if (a != null) {
+        // Use account data
+    }
+}
+```
+
+---
+
+## Best Practices Summary
+
+| Practice | Benefit |
+|----------|---------|
+| Centralize in Selector classes | One place to update field lists |
+| Use `WITH SECURITY_ENFORCED` | Automatic FLS enforcement |
+| Return empty List, not null | Prevents NullPointerException |
+| Use `inherited sharing` | Respects caller's sharing context |
+| Make fields list a constant | Easy to update across queries |
+| Add null/empty checks | Prevent unnecessary queries |
+| Support mocking in tests | Faster tests, no database dependencies |
+
+---
+
+## When to Use Each Pattern
+
+| Scenario | Pattern |
+|----------|---------|
+| Simple, static queries | Pattern 1: Basic Selector |
+| Need sharing mode control | Pattern 2: Sharing Modes |
+| Heavy unit testing | Pattern 3: Mockable Selector |
+| Dynamic filters at runtime | Pattern 4: Query Builder |
+| Trigger/batch bulk operations | Pattern 5: Bulkified Query |

package/skills/querying-soql/references/soql-reference.md

@@ -0,0 +1,227 @@
+<!-- Parent: querying-soql/SKILL.md -->
+# SOQL Quick Reference
+
+## Query Structure
+
+```sql
+SELECT fields
+FROM object
+[WHERE conditions]
+[WITH filter]
+[GROUP BY fields]
+[HAVING conditions]
+[ORDER BY fields [ASC|DESC] [NULLS FIRST|LAST]]
+[LIMIT number]
+[OFFSET number]
+[FOR UPDATE]
+```
+
+---
+
+## Operators
+
+### Comparison Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `=` | Equal | `Name = 'Acme'` |
+| `!=` | Not equal | `Status != 'Closed'` |
+| `<` | Less than | `Amount < 1000` |
+| `<=` | Less than or equal | `Amount <= 1000` |
+| `>` | Greater than | `Amount > 1000` |
+| `>=` | Greater than or equal | `Amount >= 1000` |
+| `LIKE` | Pattern match | `Name LIKE 'Acme%'` |
+| `IN` | In list | `Status IN ('New', 'Open')` |
+| `NOT IN` | Not in list | `Type NOT IN ('Other')` |
+| `INCLUDES` | Multi-select contains | `Skills__c INCLUDES ('Java')` |
+| `EXCLUDES` | Multi-select excludes | `Skills__c EXCLUDES ('Java')` |
+
+### Logical Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `AND` | Both conditions | `A = 1 AND B = 2` |
+| `OR` | Either condition | `A = 1 OR B = 2` |
+| `NOT` | Negate condition | `NOT (A = 1)` |
+
+### LIKE Patterns
+
+| Pattern | Matches |
+|---------|---------|
+| `'Acme%'` | Starts with "Acme" |
+| `'%Corp'` | Ends with "Corp" |
+| `'%test%'` | Contains "test" |
+| `'A_me'` | "A" + any char + "me" |
+
+---
+
+## Date Literals
+
+### Relative Dates
+
+| Literal | Description |
+|---------|-------------|
+| `TODAY` | Current day |
+| `YESTERDAY` | Previous day |
+| `TOMORROW` | Next day |
+| `THIS_WEEK` | Current week (Sun-Sat) |
+| `LAST_WEEK` | Previous week |
+| `NEXT_WEEK` | Next week |
+| `THIS_MONTH` | Current month |
+| `LAST_MONTH` | Previous month |
+| `NEXT_MONTH` | Next month |
+| `THIS_QUARTER` | Current quarter |
+| `LAST_QUARTER` | Previous quarter |
+| `NEXT_QUARTER` | Next quarter |
+| `THIS_YEAR` | Current year |
+| `LAST_YEAR` | Previous year |
+| `NEXT_YEAR` | Next year |
+| `THIS_FISCAL_QUARTER` | Current fiscal quarter |
+| `THIS_FISCAL_YEAR` | Current fiscal year |
+
+### N Days/Weeks/Months/Years
+
+| Literal | Description |
+|---------|-------------|
+| `LAST_N_DAYS:n` | Last n days |
+| `NEXT_N_DAYS:n` | Next n days |
+| `LAST_N_WEEKS:n` | Last n weeks |
+| `NEXT_N_WEEKS:n` | Next n weeks |
+| `LAST_N_MONTHS:n` | Last n months |
+| `NEXT_N_MONTHS:n` | Next n months |
+| `LAST_N_QUARTERS:n` | Last n quarters |
+| `NEXT_N_QUARTERS:n` | Next n quarters |
+| `LAST_N_YEARS:n` | Last n years |
+| `NEXT_N_YEARS:n` | Next n years |
+
+### Specific Dates
+
+```sql
+-- Date only
+WHERE CloseDate = 2024-12-31
+
+-- DateTime
+WHERE CreatedDate >= 2024-01-01T00:00:00Z
+```
+
+---
+
+## Aggregate Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `COUNT()` | Count all rows | `SELECT COUNT() FROM Account` |
+| `COUNT(field)` | Count non-null values | `SELECT COUNT(Email) FROM Contact` |
+| `COUNT_DISTINCT(field)` | Count unique values | `SELECT COUNT_DISTINCT(Industry) FROM Account` |
+| `SUM(field)` | Sum of values | `SELECT SUM(Amount) FROM Opportunity` |
+| `AVG(field)` | Average of values | `SELECT AVG(Amount) FROM Opportunity` |
+| `MIN(field)` | Minimum value | `SELECT MIN(Amount) FROM Opportunity` |
+| `MAX(field)` | Maximum value | `SELECT MAX(Amount) FROM Opportunity` |
+
+---
+
+## Date Functions
+
+| Function | Returns | Example |
+|----------|---------|---------|
+| `CALENDAR_YEAR(date)` | Year (e.g., 2024) | `SELECT CALENDAR_YEAR(CloseDate) FROM Opportunity` |
+| `CALENDAR_QUARTER(date)` | Quarter (1-4) | `SELECT CALENDAR_QUARTER(CloseDate) FROM Opportunity` |
+| `CALENDAR_MONTH(date)` | Month (1-12) | `SELECT CALENDAR_MONTH(CloseDate) FROM Opportunity` |
+| `DAY_IN_MONTH(date)` | Day (1-31) | `SELECT DAY_IN_MONTH(CreatedDate) FROM Account` |
+| `DAY_IN_WEEK(date)` | Day (1=Sun, 7=Sat) | `SELECT DAY_IN_WEEK(CreatedDate) FROM Account` |
+| `DAY_IN_YEAR(date)` | Day (1-366) | `SELECT DAY_IN_YEAR(CreatedDate) FROM Account` |
+| `WEEK_IN_MONTH(date)` | Week (1-5) | `SELECT WEEK_IN_MONTH(CreatedDate) FROM Account` |
+| `WEEK_IN_YEAR(date)` | Week (1-53) | `SELECT WEEK_IN_YEAR(CreatedDate) FROM Account` |
+| `HOUR_IN_DAY(date)` | Hour (0-23) | `SELECT HOUR_IN_DAY(CreatedDate) FROM Account` |
+| `FISCAL_YEAR(date)` | Fiscal year | `SELECT FISCAL_YEAR(CloseDate) FROM Opportunity` |
+| `FISCAL_QUARTER(date)` | Fiscal quarter | `SELECT FISCAL_QUARTER(CloseDate) FROM Opportunity` |
+| `FISCAL_MONTH(date)` | Fiscal month | `SELECT FISCAL_MONTH(CloseDate) FROM Opportunity` |
+
+---
+
+## Relationship Queries
+
+### Child-to-Parent (Dot Notation)
+
+```sql
+-- Standard objects
+SELECT Contact.Name, Contact.Account.Name FROM Contact
+
+-- Custom objects (use __r)
+SELECT Child__c.Name, Child__c.Parent__r.Name FROM Child__c
+```
+
+### Parent-to-Child (Subquery)
+
+```sql
+-- Standard objects
+SELECT Id, (SELECT Id FROM Contacts) FROM Account
+
+-- Custom objects (use __r)
+SELECT Id, (SELECT Id FROM Children__r) FROM Parent__c
+```
+
+---
+
+## WITH Clauses
+
+| Clause | Description |
+|--------|-------------|
+| `WITH SECURITY_ENFORCED` | Enforce FLS (throws exception if no access) |
+| `WITH USER_MODE` | Respect sharing and FLS |
+| `WITH SYSTEM_MODE` | Bypass sharing rules |
+
+---
+
+## Governor Limits
+
+| Limit | Synchronous | Asynchronous |
+|-------|-------------|--------------|
+| Total SOQL Queries | 100 | 200 |
+| Records Retrieved | 50,000 | 50,000 |
+| QueryLocator Rows | 10,000,000 | 10,000,000 |
+| OFFSET Maximum | 2,000 | 2,000 |
+| Subqueries | 20 | 20 |
+| Relationship Depth | 5 levels | 5 levels |
+
+---
+
+## Index Usage
+
+### Always Indexed
+
+- `Id`
+- `Name`
+- `OwnerId`
+- `CreatedDate`
+- `LastModifiedDate`
+- `RecordTypeId`
+- External ID fields
+- Master-Detail fields
+
+### Selective Query Rules
+
+- Query is selective if WHERE returns < 10% of first 1M records
+- Or uses an indexed field with < 1M matching records
+- Non-selective queries on large tables fail
+
+---
+
+## CLI Commands
+
+```bash
+# Basic query
+sf data query --query "SELECT Id, Name FROM Account LIMIT 10" --target-org my-org
+
+# JSON output
+sf data query --query "SELECT Id, Name FROM Account" --target-org my-org --json
+
+# CSV output
+sf data query --query "SELECT Id, Name FROM Account" --result-format csv --target-org my-org
+
+# Bulk export (for large results, > 2,000 records)
+sf data export bulk --query "SELECT Id, Name FROM Account" --target-org my-org --output-file accounts.csv
+
+# Query plan (uses REST API explain endpoint)
+sf api request rest "/query/?explain=SELECT+Id+FROM+Account+WHERE+Name='Test'" --target-org my-org --json
+```