Function call cache (#222)

* Add import-data command to start-dev workflow

* Implement equality and hashCode methods for Literal expressions and add unit tests for expression comparison

* Implement equals and hashCode methods for StringLiteral and add unit tests for equality comparison

* Implement equals and hashCode methods for Variable class and add unit tests for variable equality comparison

* Implement equals and hashCode methods for MergeFieldOrScopeVariable and add unit tests for equality comparison

* Implement equals and hashCode methods for Logical expressions and add unit tests for equality comparison

* Implement equals and hashCode methods for Binary expressions and add unit tests for equality comparison

* Implement equals and hashCode methods for Grouping expressions and add unit tests for equality comparison

* Implement equals and hashCode methods for FunctionCall and add unit tests for equality comparison

* Implement equals and hashCode methods for various expression types and add unit tests for equality comparison

* Implement caching for function calls and update hashCode method for Expr class

* Remove debug statements from function execution in FunctionCaller and add a TODO comment for handling line spreads in array literals in Interpreter

* Implement caching for query results

* Implement caching for function calls and query results in EnvironmentCache class

* `nocache` keyword deprecation

* Revert "`nocache` keyword deprecation"

This reverts commit cb839b8.

* Add caching configuration and disable function result caching option

* Rename caching configuration for clarity and update related methods

* Implement caching control for custom functions and update related classes

* Add caching documentation and update navigation

* Releasing a new package version

Author: cesarParra

docs/public/packages.json

@@ -1,4 +1,4 @@
 {
-  "packageId": "04tRb000003tVPdIAM",
+  "packageId": "04tRb000003xe4XIAQ",
   "componentPackageId": "04tRb0000012Mv8IAE"
 }

docs/src/app/docs/caching/page.md

@@ -0,0 +1,51 @@
+---
+title: Caching
+nextjs:
+  metadata:
+    title: Caching
+    description: Learn how caching works and how to control it.
+---
+
+By default, all calls to Expression built-in functions are cached for performance.
+This means that if you call the same function with the same arguments multiple times,
+the result will be retrieved from the cache instead of being recalculated.
+
+For example, if you have an Expression that for a given reason executes the same `Query`
+twice with the same parameters, the second execution will return the cached result of the first execution,
+preventing the Salesforce governor limits from being hit.
+
+This aggressive caching is generally safe, because all Expression functions are pure (give the same
+output for the same input, without side effects). Caching is also contextual, meaning that if you
+call the `expression.Evaluator.run` method multiple times with different contexts, the caches will not
+interfere with each other, even if you have the same function calls in different expressions.
+
+But there are situations where you might want to disable caching, for example, if you have a custom
+function that performs non-deterministic operations (like generating random numbers) or side effects, like
+DML operations. For these cases, you can control the caching behavior in the following ways:
+
+## Global Caching
+
+Global caching is enabled by default for all Expression built-in (standard) functions. You can
+disable it by calling the `disableStandardFunctionResultCaching` method of the `Configuration` object:
+
+```apex
+expression.Configuration config = new expression.Configuration()
+    .disableStandardFunctionResultCaching();
+expression.Evaluator.run('your expression here', config);
+```
+
+## User-defined Function Caching
+
+You can control cache independently for any function you declare yourself, by using the `nocache` keyword.
+See [Declaring Functions](./declaring-functions) for more information.
+
+But be aware that if global caching is enabled, the `nocache` keyword will have no effect on built-in functions
+called from within your custom function. These will still be cached.
+
+## Custom Metadata Type Functions
+
+If you are using [Custom Metadata Type Functions](./custom-functions), you can control caching by setting
+the `Cache Result` field on the Custom Metadata record to `false`. This flag is independent of the global caching
+setting,
+so regardless of whether global caching is enabled or disabled, setting this flag will enable/disable caching for that
+specific function.

docs/src/lib/navigation.json

@@ -31,6 +31,10 @@
         "title": "Configuring the Evaluation",
         "href": "/docs/configuring-the-evaluation"
       },
+      {
+        "title": "Caching",
+        "href": "/docs/caching"
+      },
       {
         "title": "Debugging",
         "href": "/docs/debugging"
@@ -214,4 +218,4 @@
       }
     ]
   }
-]
+]

expression-src/main/api/Configuration.cls

@@ -11,6 +11,7 @@ global with sharing class Configuration {
     global SharingMode sharing = SharingMode.WITH;
     global Boolean printAst = false;
     global Map<String, Object> customContext = new Map<String, Object>();
+    global Boolean cacheStandardFunctionResults = true;
     public Boolean withDiagnostics = false;
 
     global Configuration respectSharing(Boolean respect) {
@@ -28,6 +29,11 @@ global with sharing class Configuration {
         return this;
     }
 
+    global Configuration disableStandardFunctionResultCaching() {
+        cacheStandardFunctionResults = false;
+        return this;
+    }
+
     global Configuration withCustomContext(Map<String, Object> objectsByStrings) {
         Map<String, Object> objectToSet = objectsByStrings ?? new Map<String, Object>();
         this.customContext = objectToSet;

expression-src/main/api/Configuration.cls-meta.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>60.0</apiVersion>
+    <apiVersion>65.0</apiVersion>
     <status>Active</status>
 </ApexClass>

expression-src/main/api/IExpressionFunction.cls-meta.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>60.0</apiVersion>
+    <apiVersion>65.0</apiVersion>
     <status>Active</status>
 </ApexClass>

expression-src/main/schema/layouts/Expression_Function__mdt-Expression Function Layout.layout-meta.xml

@@ -18,6 +18,10 @@
                 <behavior>Edit</behavior>
                 <field>Apex_Class__c</field>
             </layoutItems>
+            <layoutItems>
+                <behavior>Edit</behavior>
+                <field>CacheResult__c</field>
+            </layoutItems>
         </layoutColumns>
         <layoutColumns>
             <layoutItems>
@@ -55,6 +59,8 @@
         <detailHeading>false</detailHeading>
         <editHeading>false</editHeading>
         <layoutColumns/>
+        <layoutColumns/>
+        <layoutColumns/>
         <style>CustomLinks</style>
     </layoutSections>
     <showEmailCheckbox>false</showEmailCheckbox>

expression-src/main/schema/objects/Expression_Function__mdt/fields/CacheResult__c.field-meta.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>CacheResult__c</fullName>
+    <defaultValue>true</defaultValue>
+    <description>Whether the result of evaluating this function should be cached or not. If cached, after the function is called the first time, the first result will be returned for any subsequent calls.</description>
+    <fieldManageability>DeveloperControlled</fieldManageability>
+    <inlineHelpText>Whether the result of evaluating this function should be cached or not. If cached, after the function is called the first time, the first result will be returned for any subsequent calls.</inlineHelpText>
+    <label>Cache Result</label>
+    <type>Checkbox</type>
+</CustomField>

expression-src/main/src/interpreter/ContextResolver.cls

@@ -252,7 +252,8 @@ public with sharing class ContextResolver implements Visitor {
         }
 
         // See if the function exists as a Custom Metadata function
-        IExpressionFunction customMetadataFunction = CustomFunctionRepository.getInstance().getByName(function.functionName);
+        CustomMetadataExpressionFunction customMetadataFunction =
+            CustomFunctionRepository.getInstance().getByName(function.functionName);
         if (customMetadataFunction != null) {
             // Resolve arguments
             for (Expr argument : function.arguments) {

expression-src/main/src/interpreter/ContextResolver.cls-meta.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>60.0</apiVersion>
+    <apiVersion>65.0</apiVersion>
     <status>Active</status>
 </ApexClass>