fix: Introduced unanimous single valued output in decision evaluation result

Author: Dmytro Gundartsev

api/src/main/kotlin/dev/bpmcrafters/processengineapi/decision/CollectDecisionEvaluationResult.kt

@@ -2,8 +2,8 @@ package dev.bpmcrafters.processengineapi.decision
 
 /**
  * Decision evaluation result for all collect-valued hit policies.
- * @since 2.0
+ * @since 1.4
  */
 data class CollectDecisionEvaluationResult(
   val result: List<DecisionEvaluationOutput>
-) : DecisionEvaluationResult
+) : DecisionEvaluationResult()

api/src/main/kotlin/dev/bpmcrafters/processengineapi/decision/DecisionEvaluationMultiOutput.kt

@@ -0,0 +1,12 @@
+package dev.bpmcrafters.processengineapi.decision
+
+/**
+ * Decision evaluation output representing multiple named values
+ * produced by a decision with multiple outputs.
+ *
+ * @since 1.4
+ */
+data class DecisionEvaluationMultiOutput (
+  val outputs: Map<String, Any>
+
+) :DecisionEvaluationOutput

api/src/main/kotlin/dev/bpmcrafters/processengineapi/decision/DecisionEvaluationOutput.kt

@@ -2,15 +2,23 @@ package dev.bpmcrafters.processengineapi.decision
 
 /**
  * Decision output.
- * @since 2.0
+ * @since 1.4
  */
-data class DecisionEvaluationOutput(
+
+sealed interface DecisionEvaluationOutput {
   /**
-   * Keys are output names pointing to values.
+   * Returns as a single output value
    */
-  val values: Map<String, Any>,
+  fun single(): DecisionEvaluationSingleOutput {
+    require(this is DecisionEvaluationSingleOutput) { "Decision evaluation single output expected but it was ${this::class.simpleName}" }
+    return this
+  }
+
   /**
-   * Additional metadata about the task.
+   * Returns as multi-outputs with names
    */
-  val meta: Map<String, String> = emptyMap()
-)
+  fun many(): DecisionEvaluationMultiOutput {
+    require(this is DecisionEvaluationMultiOutput) { "Decision evaluation multi output expected but it was ${this::class.simpleName}" }
+    return this
+  }
+}

api/src/main/kotlin/dev/bpmcrafters/processengineapi/decision/DecisionEvaluationResult.kt

@@ -2,8 +2,9 @@ package dev.bpmcrafters.processengineapi.decision
 
 /**
  * Represents result of decision evaluation.
+ *
  */
-sealed interface DecisionEvaluationResult {
+sealed class DecisionEvaluationResult {
   /**
    * Returns the result as single.
    */
@@ -19,4 +20,9 @@ sealed interface DecisionEvaluationResult {
     require(this is CollectDecisionEvaluationResult) { "Decision evaluation result must be a collect but it was ${this::class.simpleName}" }
     return this
   }
+
+  /**
+  *  Additional metadata on evaluation result.
+  */
+  val meta: Map<String, String> = emptyMap()
 }

api/src/main/kotlin/dev/bpmcrafters/processengineapi/decision/DecisionEvaluationSingleOutput.kt

@@ -0,0 +1,10 @@
+package dev.bpmcrafters.processengineapi.decision
+
+/**
+ * Decision evaluation output representing a single anonymous output
+ *
+ *  @since 1.4
+ */
+data class DecisionEvaluationSingleOutput(
+  val output: Any?
+): DecisionEvaluationOutput

api/src/main/kotlin/dev/bpmcrafters/processengineapi/decision/SingleDecisionEvaluationResult.kt

@@ -6,4 +6,4 @@ package dev.bpmcrafters.processengineapi.decision
  */
 data class SingleDecisionEvaluationResult(
   val result: DecisionEvaluationOutput
-) : DecisionEvaluationResult
+) : DecisionEvaluationResult()

api/src/test/kotlin/dev/bpmcrafters/processengineapi/decision/DecisionUseCase.kt

@@ -25,12 +25,64 @@ internal class DecisionUseCase(
     ).get()
       .single()
       .result
-      .values["discount"] as Double
+      .single().output as Double
   }
 
+  fun calculateCustomerOffer(customerStatus: CustomerStatus, year: Int): Offer {
+    return decisionApi.evaluateDecision(
+      DecisionByRefEvaluationCommand(
+        decisionRef = "customerOffer",
+        payloadSupplier = PayloadSupplier {
+          mapOf<String, Any>(
+            "customerStatus" to customerStatus,
+            "year" to year
+          )
+        },
+        restrictionSupplier = Supplier {
+          mapOf<String, String>(CommonRestrictions.TENANT_ID to "tenant-1")
+        }
+      )
+    ).get()
+      .single()
+      .result
+      .many()
+      .outputs
+      .let { Offer (it["id"] as Integer, it["name"] as String) }
+  }
+
+  fun calculateCustomerOffers(customerStatus: CustomerStatus, year: Int): List<Offer> {
+    return decisionApi.evaluateDecision(
+      DecisionByRefEvaluationCommand(
+        decisionRef = "customerOffers",
+        payloadSupplier = PayloadSupplier {
+          mapOf<String, Any>(
+            "customerStatus" to customerStatus,
+            "year" to year
+          )
+        },
+        restrictionSupplier = Supplier {
+          mapOf<String, String>(CommonRestrictions.TENANT_ID to "tenant-1")
+        }
+      )
+    ).get()
+      .collect()
+      .result
+      .map {
+        it.many()
+          .outputs
+          .let { Offer (it["id"] as Integer, it["name"] as String) }
+      }
+  }
+
+
   enum class CustomerStatus {
     SILVER,
     GOLD,
     PLATINUM
   }
+
+  data class Offer (
+      val id: Integer,
+      val name: String
+    )
 }

docs/decision-api.md

@@ -2,10 +2,18 @@
 title: Decision Evaluation API
 ---
 
-The Decision Evaluation API provides functionality to evaluate DMN decision. The API returns a generic 
-`DecisionEvaluationResult` which can be cast to single or collect result with the corresponding method.
+The Decision Evaluation API provides functionality to evaluate a DMN decision. The API returns a generic
+`DecisionEvaluationResult` which can be cast to a single or collect result using the corresponding method:
 
-And here is the example code to evaluate decision:
+- `single()` → returns `SingleDecisionEvaluationResult`
+- `collect()` → returns `CollectDecisionEvaluationResult`
+
+Each of those wraps a `DecisionEvaluationOutput` value which can be either:
+
+- `DecisionEvaluationSingleOutput` for context-less single values (access via `single().getOutput()`), or
+- `DecisionEvaluationMultiOutput` for named/context values (access via `many().getOutputs()`).
+
+Below are example snippets in Java showing the new API usage.
 
 ```java
 class DecisionUseCase {
@@ -19,7 +27,7 @@ class DecisionUseCase {
    * @return calculated discount.
    */
   public Double evaluateDiscount(CustomerStatus customerStatus, Integer year) {
-    return (Double)evaluateDecisionApi.evaluateDecision(
+    return (Double) evaluateDecisionApi.evaluateDecision(
       new DecisionByRefEvaluationCommand(
         "customerDiscount",
         () -> Map.of(
@@ -28,11 +36,58 @@ class DecisionUseCase {
         ),
         Map.of(CommonRestrictions.TENANT_ID, "myTenant")
       )
-    ).get()
-      .single()
-      .getResult()
-      .get("discount")
-    ;
+    ).get()                 // DecisionEvaluationResult
+     .single()              // SingleDecisionEvaluationResult
+     .getResult()           // DecisionEvaluationOutput
+     .single()              // DecisionEvaluationSingleOutput
+     .getOutput();          // actual value, e.g. Double
+  }
+
+  /**
+   * Calculates a customer offer with multiple named outputs (multi-output decision).
+   */
+  public Offer evaluateOffer(CustomerStatus customerStatus, Integer year) {
+    Map<String, Object> outputs = evaluateDecisionApi.evaluateDecision(
+      new DecisionByRefEvaluationCommand(
+        
+        "customerOffer",
+        () -> Map.of(
+          "customerStatus", customerStatus,
+          "registrationYear", year
+        ),
+        Map.of(CommonRestrictions.TENANT_ID, "myTenant")
+      )
+    ).get()                 // DecisionEvaluationResult
+     .single()              // SingleDecisionEvaluationResult
+     .getResult()           // DecisionEvaluationOutput
+     .many()                // DecisionEvaluationMultiOutput
+     .getOutputs();         // Map<String, Object>
+
+    return new Offer((Integer) outputs.get("id"), (String) outputs.get("name"));
+  }
+
+  /**
+   * Calculates multiple customer offers (collect decision result).
+   */
+  public List<Offer> evaluateOffers(CustomerStatus customerStatus, Integer year) {
+    return evaluateDecisionApi.evaluateDecision(
+      new DecisionByRefEvaluationCommand(
+        "customerOffers",
+        () -> Map.of(
+          "customerStatus", customerStatus,
+          "registrationYear", year
+        ),
+        Map.of(CommonRestrictions.TENANT_ID, "myTenant")
+      )
+    ).get()                 // DecisionEvaluationResult
+     .collect()             // CollectDecisionEvaluationResult
+     .getResult()           // List<DecisionEvaluationOutput>
+     .stream()
+     .map(o -> {
+       Map<String, Object> outputs = o.many().getOutputs();
+       return new Offer((Integer) outputs.get("id"), (String) outputs.get("name"));
+     })
+     .toList();
   }
 }