@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/querying-soql/assets/relationship-queries.soql

@@ -0,0 +1,203 @@
+/**
+ * RELATIONSHIP QUERY PATTERNS
+ *
+ * SOQL supports two types of relationships:
+ * 1. Child-to-Parent (dot notation) - Traverse up
+ * 2. Parent-to-Child (subquery) - Traverse down
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CHILD-TO-PARENT (DOT NOTATION)
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- Basic parent field access
+SELECT Id, Name, Account.Name, Account.Industry
+FROM Contact
+
+-- Multiple levels up (max 5 levels)
+SELECT Id, Name,
+       Account.Name,
+       Account.Owner.Name,
+       Account.Owner.Manager.Name
+FROM Contact
+
+-- Filter by parent field
+SELECT Id, Name, Email
+FROM Contact
+WHERE Account.Industry = 'Technology'
+AND Account.AnnualRevenue > 1000000
+
+-- Custom object parent relationship (__r suffix)
+SELECT Id, Name, Custom_Parent__r.Name, Custom_Parent__r.Status__c
+FROM Custom_Child__c
+
+-- Standard lookup relationships
+SELECT Id, Subject, WhatId, What.Name
+FROM Task
+WHERE What.Type = 'Account'
+
+SELECT Id, CaseNumber, Account.Name, Contact.Name
+FROM Case
+WHERE Account.Industry = 'Healthcare'
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PARENT-TO-CHILD (SUBQUERIES)
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- Basic child records
+SELECT Id, Name,
+       (SELECT Id, FirstName, LastName, Email FROM Contacts)
+FROM Account
+LIMIT 100
+
+-- Multiple child relationships
+SELECT Id, Name,
+       (SELECT Id, Name, Email FROM Contacts),
+       (SELECT Id, Name, Amount, StageName FROM Opportunities),
+       (SELECT Id, CaseNumber, Subject FROM Cases)
+FROM Account
+WHERE Industry = 'Technology'
+LIMIT 50
+
+-- Filtered child records
+SELECT Id, Name,
+       (SELECT Id, Name, Amount
+        FROM Opportunities
+        WHERE StageName = 'Closed Won'
+        AND Amount > 10000
+        ORDER BY Amount DESC
+        LIMIT 5)
+FROM Account
+
+-- Custom child relationship (__r suffix, plural)
+SELECT Id, Name,
+       (SELECT Id, Name, Status__c FROM Custom_Children__r)
+FROM Custom_Parent__c
+
+-- Order in subquery
+SELECT Id, Name,
+       (SELECT Id, FirstName, LastName, CreatedDate
+        FROM Contacts
+        ORDER BY CreatedDate DESC
+        LIMIT 10)
+FROM Account
+
+// ═══════════════════════════════════════════════════════════════════════════
+// COMMON RELATIONSHIP NAMES
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- Account relationships
+SELECT Id, Name,
+       (SELECT Id FROM Contacts),           -- Standard
+       (SELECT Id FROM Opportunities),      -- Standard
+       (SELECT Id FROM Cases),              -- Standard
+       (SELECT Id FROM Notes),              -- Standard
+       (SELECT Id FROM Attachments),        -- Standard
+       (SELECT Id FROM Tasks),              -- Standard
+       (SELECT Id FROM Events)              -- Standard
+FROM Account
+LIMIT 10
+
+-- Contact relationships
+SELECT Id, Name,
+       (SELECT Id FROM Cases),
+       (SELECT Id FROM Tasks),
+       (SELECT Id FROM Events),
+       (SELECT Id FROM OpportunityContactRoles)
+FROM Contact
+LIMIT 10
+
+-- Opportunity relationships
+SELECT Id, Name,
+       (SELECT Id FROM OpportunityLineItems),
+       (SELECT Id FROM OpportunityContactRoles),
+       (SELECT Id FROM Tasks)
+FROM Opportunity
+LIMIT 10
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SEMI-JOINS AND ANTI-JOINS
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- Semi-join: Accounts WITH contacts
+SELECT Id, Name FROM Account
+WHERE Id IN (SELECT AccountId FROM Contact)
+
+-- Semi-join: Accounts WITH opportunities over $100k
+SELECT Id, Name FROM Account
+WHERE Id IN (
+    SELECT AccountId FROM Opportunity
+    WHERE Amount > 100000
+    AND StageName = 'Closed Won'
+)
+
+-- Anti-join: Accounts WITHOUT contacts
+SELECT Id, Name FROM Account
+WHERE Id NOT IN (SELECT AccountId FROM Contact WHERE AccountId != null)
+
+-- Anti-join: Accounts WITHOUT opportunities
+SELECT Id, Name FROM Account
+WHERE Id NOT IN (SELECT AccountId FROM Opportunity WHERE AccountId != null)
+
+-- Anti-join: Leads not converted
+SELECT Id, Name, Email FROM Lead
+WHERE IsConverted = false
+AND Id NOT IN (SELECT LeadId FROM Contact WHERE LeadId != null)
+
+-- Multiple semi-joins
+SELECT Id, Name FROM Account
+WHERE Id IN (SELECT AccountId FROM Contact WHERE Email != null)
+AND Id IN (SELECT AccountId FROM Opportunity WHERE Amount > 50000)
+
+// ═══════════════════════════════════════════════════════════════════════════
+// POLYMORPHIC RELATIONSHIPS (TYPEOF)
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- Basic polymorphic query
+SELECT Id, Subject, Who.Name, What.Name
+FROM Task
+WHERE Who.Type = 'Contact'
+AND What.Type = 'Opportunity'
+
+-- TYPEOF for conditional fields
+SELECT
+    Id,
+    Subject,
+    TYPEOF What
+        WHEN Account THEN Name, Industry, AnnualRevenue
+        WHEN Opportunity THEN Name, Amount, StageName
+        WHEN Case THEN CaseNumber, Subject, Status
+    END
+FROM Task
+WHERE What.Type IN ('Account', 'Opportunity', 'Case')
+
+-- TYPEOF with ELSE clause
+SELECT
+    Id,
+    TYPEOF Owner
+        WHEN User THEN FirstName, LastName, Email
+        WHEN Group THEN Name
+        ELSE Name
+    END
+FROM Account
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ADVANCED PATTERNS
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- Get accounts with contact count > 5 (requires Apex filtering)
+-- Note: SOQL can't filter by aggregate of subquery
+SELECT Id, Name, (SELECT Id FROM Contacts)
+FROM Account
+-- Then filter in Apex: WHERE Contacts.size() > 5
+
+-- Get hierarchical data (self-reference)
+SELECT Id, Name, ParentId, Parent.Name, Parent.Parent.Name
+FROM Account
+WHERE ParentId != null
+
+-- Get users with role hierarchy
+SELECT Id, Name, Manager.Name, Manager.Manager.Name
+FROM User
+WHERE IsActive = true
+AND ManagerId != null

package/skills/querying-soql/assets/selector-class.cls

@@ -0,0 +1,219 @@
+/**
+ * ${OBJECT_NAME}Selector - Centralized SOQL queries for ${OBJECT_NAME}
+ *
+ * This selector class follows the Selector Layer pattern to:
+ * - Centralize all ${OBJECT_NAME} queries in one place
+ * - Enforce Field-Level Security (FLS) by default
+ * - Support query mocking in unit tests
+ * - Provide consistent field selection across the codebase
+ *
+ * @see https://blog.beyondthecloud.dev/blog/why-do-you-need-selector-layer
+ * @see https://www.jamessimone.net/blog/joys-of-apex/repository-pattern/
+ */
+public inherited sharing class ${OBJECT_NAME}Selector {
+
+    // ═══════════════════════════════════════════════════════════════════
+    // FIELD DEFINITIONS
+    // Centralize field lists to make updates easy
+    // ═══════════════════════════════════════════════════════════════════
+
+    /**
+     * Standard fields queried in most operations
+     */
+    private static final List<SObjectField> STANDARD_FIELDS = new List<SObjectField>{
+        ${OBJECT_NAME}.Id,
+        ${OBJECT_NAME}.Name,
+        ${OBJECT_NAME}.OwnerId,
+        ${OBJECT_NAME}.CreatedDate,
+        ${OBJECT_NAME}.LastModifiedDate
+        // Add commonly needed fields here
+    };
+
+    /**
+     * Extended fields for detail views
+     */
+    private static final List<SObjectField> DETAIL_FIELDS = new List<SObjectField>{
+        ${OBJECT_NAME}.Id,
+        ${OBJECT_NAME}.Name,
+        ${OBJECT_NAME}.OwnerId,
+        ${OBJECT_NAME}.CreatedDate,
+        ${OBJECT_NAME}.LastModifiedDate
+        // Add detail-specific fields here
+    };
+
+    // ═══════════════════════════════════════════════════════════════════
+    // MOCKING SUPPORT (for unit tests)
+    // ═══════════════════════════════════════════════════════════════════
+
+    @TestVisible
+    private static List<${OBJECT_NAME}> mockResults;
+
+    @TestVisible
+    private static void setMockResults(List<${OBJECT_NAME}> records) {
+        mockResults = records;
+    }
+
+    @TestVisible
+    private static void clearMockResults() {
+        mockResults = null;
+    }
+
+    private static Boolean useMock() {
+        return Test.isRunningTest() && mockResults != null;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════
+    // QUERY METHODS
+    // ═══════════════════════════════════════════════════════════════════
+
+    /**
+     * Query records by their IDs
+     *
+     * @param recordIds Set of record IDs to query
+     * @return List of matching records with standard fields
+     */
+    public static List<${OBJECT_NAME}> byIds(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<${OBJECT_NAME}>();
+        }
+        if (useMock()) {
+            return mockResults;
+        }
+        return [
+            SELECT Id, Name, OwnerId, CreatedDate, LastModifiedDate
+            FROM ${OBJECT_NAME}
+            WHERE Id IN :recordIds
+            WITH SECURITY_ENFORCED
+        ];
+    }
+
+    /**
+     * Query records by their IDs, returning a Map for O(1) lookups
+     *
+     * @param recordIds Set of record IDs to query
+     * @return Map of Id to record
+     */
+    public static Map<Id, ${OBJECT_NAME}> byIdsAsMap(Set<Id> recordIds) {
+        return new Map<Id, ${OBJECT_NAME}>(byIds(recordIds));
+    }
+
+    /**
+     * Query records by Owner
+     *
+     * @param ownerId The owner's User Id
+     * @return List of records owned by the specified user
+     */
+    public static List<${OBJECT_NAME}> byOwnerId(Id ownerId) {
+        if (ownerId == null) {
+            return new List<${OBJECT_NAME}>();
+        }
+        if (useMock()) {
+            return mockResults;
+        }
+        return [
+            SELECT Id, Name, OwnerId, CreatedDate, LastModifiedDate
+            FROM ${OBJECT_NAME}
+            WHERE OwnerId = :ownerId
+            WITH SECURITY_ENFORCED
+            ORDER BY LastModifiedDate DESC
+            LIMIT 1000
+        ];
+    }
+
+    /**
+     * Query records created within a date range
+     *
+     * @param startDate Start of date range (inclusive)
+     * @param endDate End of date range (inclusive)
+     * @return List of records created within the range
+     */
+    public static List<${OBJECT_NAME}> byCreatedDateRange(Date startDate, Date endDate) {
+        if (startDate == null || endDate == null) {
+            return new List<${OBJECT_NAME}>();
+        }
+        if (useMock()) {
+            return mockResults;
+        }
+        return [
+            SELECT Id, Name, OwnerId, CreatedDate, LastModifiedDate
+            FROM ${OBJECT_NAME}
+            WHERE CreatedDate >= :startDate
+            AND CreatedDate <= :endDate
+            WITH SECURITY_ENFORCED
+            ORDER BY CreatedDate DESC
+            LIMIT 10000
+        ];
+    }
+
+    // ═══════════════════════════════════════════════════════════════════
+    // RELATIONSHIP QUERIES
+    // ═══════════════════════════════════════════════════════════════════
+
+    /**
+     * Query records with related child records
+     * Customize the subquery for your object relationships
+     *
+     * @param recordIds Set of parent record IDs
+     * @return List of parent records with child records populated
+     */
+    public static List<${OBJECT_NAME}> withChildRecordsByIds(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<${OBJECT_NAME}>();
+        }
+        if (useMock()) {
+            return mockResults;
+        }
+        return [
+            SELECT Id, Name, OwnerId,
+                   (SELECT Id, Name
+                    FROM ChildRelationshipName__r  // Replace with actual relationship
+                    WHERE IsActive__c = true
+                    LIMIT 50)
+            FROM ${OBJECT_NAME}
+            WHERE Id IN :recordIds
+            WITH SECURITY_ENFORCED
+        ];
+    }
+
+    // ═══════════════════════════════════════════════════════════════════
+    // AGGREGATE QUERIES
+    // ═══════════════════════════════════════════════════════════════════
+
+    /**
+     * Count records by a grouping field
+     *
+     * @return List of AggregateResult with grouping and count
+     */
+    public static List<AggregateResult> countByOwner() {
+        return [
+            SELECT OwnerId, COUNT(Id) recordCount
+            FROM ${OBJECT_NAME}
+            GROUP BY OwnerId
+            HAVING COUNT(Id) > 0
+        ];
+    }
+
+    // ═══════════════════════════════════════════════════════════════════
+    // EXISTENCE CHECK
+    // ═══════════════════════════════════════════════════════════════════
+
+    /**
+     * Check if a record exists by ID (efficient single record lookup)
+     *
+     * @param recordId The record ID to check
+     * @return true if the record exists
+     */
+    public static Boolean existsById(Id recordId) {
+        if (recordId == null) {
+            return false;
+        }
+        List<${OBJECT_NAME}> results = [
+            SELECT Id
+            FROM ${OBJECT_NAME}
+            WHERE Id = :recordId
+            WITH SECURITY_ENFORCED
+            LIMIT 1
+        ];
+        return !results.isEmpty();
+    }
+}