feat: create new assert function

docs/docs/reference/builtin-functions/feel-built-in-functions-boolean.md

@@ -80,3 +80,53 @@ get or default(null, "default")
 get or default(null, null)     
 // null
 ```
+
+## assert(value, condition)
+
+<MarkerCamundaExtension></MarkerCamundaExtension>
+
+Verify that the given condition is met. If the condition is `true`, the function returns the value. 
+Otherwise, the evaluation fails with an error.
+
+**Function signature**
+
+```js
+assert(value: Any, condition: Any)
+```
+
+**Examples**
+
+```js
+assert(x, x != null)
+// "value" - if x is "value"
+// error - if x is null or doesn't exist
+
+assert(x, x >= 0) 
+// 4 - if x is 4
+// error - if x is less than zero
+```
+
+## assert(value, condition, cause)
+
+<MarkerCamundaExtension></MarkerCamundaExtension>
+
+Verify that the given condition is met. If the condition is `true`, the function returns the value.
+Otherwise, the evaluation fails with an error containing the given message.
+
+**Function signature**
+
+```js
+assert(value: Any, condition: Any, cause: String)
+```
+
+**Examples**
+
+```js
+assert(x, x != null, "'x' should not be null")
+// "value" - if x is "value"
+// error('x' should not be null) - if x is null or doesn't exist
+
+assert(x, x >= 0, "'x' should be positive")
+// 4 - if x is 4
+// error('x' should be positive) - if x is less than zero
+```

src/main/scala/org/camunda/feel/FeelEngine.scala

@@ -18,7 +18,7 @@ package org.camunda.feel
 
 import fastparse.Parsed
 import org.camunda.feel.FeelEngine.{Configuration, EvalExpressionResult, EvalUnaryTestsResult, Failure}
-import org.camunda.feel.api.{EvaluationResult, FailedEvaluationResult, SuccessfulEvaluationResult}
+import org.camunda.feel.api.{EvaluationFailure, EvaluationFailureType, EvaluationResult, FailedEvaluationResult, SuccessfulEvaluationResult}
 import org.camunda.feel.context.{Context, FunctionProvider}
 import org.camunda.feel.impl.interpreter.{BuiltinFunctions, EvalContext, FeelInterpreter}
 import org.camunda.feel.impl.parser.{ExpressionValidator, FeelParser}
@@ -156,6 +156,13 @@ class FeelEngine(
   private def eval(exp: ParsedExpression,
                    context: EvalContext): EvaluationResult = {
     interpreter.eval(exp.expression)(context) match {
+      case _ if containsAssertionError(context) => {
+        val failureMessage = getAssertErrorMessage(context)
+        FailedEvaluationResult(
+          failure = Failure(s"Assertion failure on evaluate the expression '${exp.text}': ${failureMessage}'"),
+          suppressedFailures = context.failureCollector.failures
+        )
+      }
       case ValError(cause) =>
         FailedEvaluationResult(
           failure = Failure(s"failed to evaluate expression '${exp.text}': $cause"),
@@ -169,6 +176,19 @@ class FeelEngine(
     }
   }
 
+  /**
+   * Check if an {@link EvaluationFailureType.ASSERT_FAILURE} error is raised during the evaluation of an expression
+   * @param context the context of the evaluation
+   * @return true if an an {@link EvaluationFailureType.ASSERT_FAILURE} is raised, false otherwise
+   */
+  private def containsAssertionError(context: EvalContext): Boolean = {
+    context.failureCollector.failures.exists(_.failureType == EvaluationFailureType.ASSERT_FAILURE);
+  }
+
+  private def getAssertErrorMessage(context: EvalContext): String = {
+    context.failureCollector.failures.find(_.failureType == EvaluationFailureType.ASSERT_FAILURE).get.failureMessage
+  }
+
   // ============ public API ============
 
   /**

src/main/scala/org/camunda/feel/api/EvaluationFailureType.scala

@@ -39,6 +39,8 @@ object EvaluationFailureType {
 
   case object FUNCTION_INVOCATION_FAILURE extends EvaluationFailureType
 
+  case object ASSERT_FAILURE extends EvaluationFailureType
+
 }
 
 

src/main/scala/org/camunda/feel/impl/builtin/BooleanBuiltinFunctions.scala

@@ -17,14 +17,15 @@
 package org.camunda.feel.impl.builtin
 
 import org.camunda.feel.impl.builtin.BuiltinFunction.builtinFunction
-import org.camunda.feel.syntaxtree.{Val, ValBoolean, ValError, ValNull}
+import org.camunda.feel.syntaxtree.{Val, ValBoolean, ValError, ValNull, ValString}
 
 object BooleanBuiltinFunctions {
 
   def functions = Map(
     "not" -> List(notFunction),
     "is defined" -> List(isDefinedFunction),
-    "get or else" -> List(getOrElse)
+    "get or else" -> List(getOrElse),
+    "assert" -> List(assertFunction, assertFunction2)
   )
 
   private def notFunction =
@@ -49,4 +50,21 @@ object BooleanBuiltinFunctions {
       case List(value, _)         => value
     }
   )
+
+  private def assertFunction = builtinFunction(
+    params = List("value", "condition"),
+    invoke = {
+      case List(value, ValBoolean(true)) => value
+      case _ => ValError("The condition is not fulfilled")
+    }
+  )
+
+  private def assertFunction2 = builtinFunction(
+    params = List("value", "condition", "cause"),
+    invoke = {
+      case List(value, ValBoolean(true), _) => value
+      case List(_, _, ValString(cause)) => ValError(cause)
+    }
+  )
+
 }

src/main/scala/org/camunda/feel/impl/interpreter/FeelInterpreter.scala

@@ -207,6 +207,9 @@ class FeelInterpreter {
       case FunctionInvocation(name, params) =>
         withFunction(findFunction(context, name, params),
           f => invokeFunction(f, params) match {
+            case ValError(failure) if name == "assert" =>
+              error(EvaluationFailureType.ASSERT_FAILURE, failure)
+              ValError(failure)
             case ValError(failure) =>
               error(EvaluationFailureType.FUNCTION_INVOCATION_FAILURE, s"Failed to invoke function '$name': $failure")
               ValNull