From a0166f3c37663f6481ec83dfadb95310c85d889b Mon Sep 17 00:00:00 2001
From: Piotr Gajek <piotr.gajek95@gmail.com>
Date: Fri, 10 Nov 2023 10:38:58 +0100
Subject: [PATCH] toLabel (#95)

* toLabel

* toLabel documentation
---
 force-app/main/default/classes/SOQL.cls      | 16 +++++++++
 force-app/main/default/classes/SOQL_Test.cls | 24 +++++++++++++
 website/docs/api/soql.md                     | 38 ++++++++++++++++++++
 3 files changed, 78 insertions(+)

diff --git a/force-app/main/default/classes/SOQL.cls b/force-app/main/default/classes/SOQL.cls
index 30b42b5..2d4b2e5 100644
--- a/force-app/main/default/classes/SOQL.cls
+++ b/force-app/main/default/classes/SOQL.cls
@@ -77,6 +77,9 @@ public virtual inherited sharing class SOQL implements Queryable {
         Queryable sum(SObjectField field, String alias);
         // SELECT - GROUPING
         Queryable grouping(SObjectField field, String alias);
+        // SELECT - toLabel
+        Queryable toLabel(SObjectField field);
+        Queryable toLabel(String field);
         // USING SCOPE
         Queryable delegatedScope();
         Queryable mineScope();
@@ -414,6 +417,15 @@ public virtual inherited sharing class SOQL implements Queryable {
         return this;
     }
 
+    public SOQL toLabel(SObjectField field) {
+        return toLabel(field.getDescribe().getName());
+    }
+
+    public SOQL toLabel(String field) {
+        builder.fields.toLabel(field);
+        return this;
+    }
+
     public SOQL delegatedScope() {
         builder.scope.delegated();
         return this;
@@ -862,6 +874,10 @@ public virtual inherited sharing class SOQL implements Queryable {
             fields.add(field.getDescribe().getName());
         }
 
+        public void toLabel(String field) {
+            fields.add('toLabel(' + field + ')');
+        }
+
         public void with(String relationshipPath, List<SObjectField> fields) {
             for (SObjectField field : fields) {
                 with(relationshipPath, field);
diff --git a/force-app/main/default/classes/SOQL_Test.cls b/force-app/main/default/classes/SOQL_Test.cls
index 760185b..a3bad53 100644
--- a/force-app/main/default/classes/SOQL_Test.cls
+++ b/force-app/main/default/classes/SOQL_Test.cls
@@ -219,6 +219,30 @@ private class SOQL_Test {
         Assert.areEqual('SELECT LeadSource, Rating, GROUPING(LeadSource) grpLS, GROUPING(Rating) grpRating, COUNT(Name) cnt FROM Lead GROUP BY ROLLUP(LeadSource, Rating)', soql);
     }
 
+    @IsTest
+    static void toLabelWithSObjectField() {
+         // Test
+        String soql = SOQL.of(Lead.SObjectType)
+            .with(Lead.Company)
+            .toLabel(Lead.Status)
+            .toString();
+
+         // Verify
+        Assert.areEqual('SELECT Company, toLabel(Status) FROM Lead', soql);
+    }
+
+    @IsTest
+    static void toLabelWithStringField() {
+         // Test
+        String soql = SOQL.of(Lead.SObjectType)
+            .with(Lead.Company)
+            .toLabel('Recordtype.Name')
+            .toString();
+
+         // Verify
+        Assert.areEqual('SELECT Company, toLabel(Recordtype.Name) FROM Lead', soql);
+    }
+
     @IsTest
     static void withField() {
         // Test
diff --git a/website/docs/api/soql.md b/website/docs/api/soql.md
index 98b4450..28bd4e9 100644
--- a/website/docs/api/soql.md
+++ b/website/docs/api/soql.md
@@ -52,6 +52,11 @@ The following are methods for `SOQL`.
 
 - [`grouping(SObjectField field, String alias)`](#grouping)
 
+[**toLabel**](#tolabel)
+
+- [`toLabel(SObjectField field)`](#tolabel)
+- [`toLabel(String field)`](#tolabel)
+
 [**SUBQUERY**](#sub-query)
 
 - [`with(SubQuery subQuery)`](#with-subquery)
@@ -687,6 +692,39 @@ SOQL.of(Lead.SObjectType)
     .toAggregated();
 ```
 
+## toLabel
+
+> To translate SOQL query results into the language of the user who submits the query, use the toLabel method.
+
+**Signature**
+
+```apex
+toLabel(SObjectField field)
+toLabel(String field)
+```
+
+**Example**
+
+```sql
+SELECT Company, toLabel(Status) FROM Lead
+```
+```apex
+SOQL.of(Lead.SObjectType)
+    .with(Lead.Company)
+    .toLabel(Lead.Status)
+    .toList();
+```
+
+```sql
+SELECT Company, toLabel(Recordtype.Name) FROM Lead
+```
+```apex
+SOQL.of(Lead.SObjectType)
+    .with(Lead.Company)
+    .toLabel('Recordtype.Name')
+    .toList();
+```
+
 ## USING SCOPE
 
 [USING SCOPE](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_using_scope.htm)