@salesforce/afv-skills 1.22.0 → 1.24.0

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

@@ -1,479 +0,0 @@
-<!-- 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

@@ -1,227 +0,0 @@
-<!-- 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
-```