Getting Started

To get a glimpse of what Decisions4s can do, we'll model rules governing a pull request process.

We want to define four rules:

• An unprotected branch requires 1 approval.
• A protected branch requires 2 approvals.
• An admin can merge anything without approvals, but this sends a notification.
• Nothing can be merged otherwise.

As the first step, add the following dependency to your project:

"org.business4s" %% "decisions4s-core" % "0.0.1"

Defining the Rules

We start by defining the input and output of the decision:

import decisions4s.*

case class Input[F[_]](
    numOfApprovals: F[Int],
    isTargetBranchProtected: F[Boolean],
    authorIsAdmin: F[Boolean],
) derives HKD

case class Output[F[_]](
    allowMerging: F[Boolean],
    notifyUnusualAction: F[Boolean],
) derives HKD

We take three values as input and provide two values as output. Both input and output are defined as case classes, with each field wrapped in the F[_] type parameter. This pattern is sometimes referred to as Higher Kinded Data, which is also the name of the typeclass automatically derived for our types.

Now let's define the rules:

def rules: List[Rule[Input, Output]] = List(
  // Unprotected branch requires 1 approval
  Rule(
    matching = Input(
      numOfApprovals = it > 0,
      isTargetBranchProtected = it.isFalse,
      authorIsAdmin = it.catchAll,
    ),
    output = Output(allowMerging = true, notifyUnusualAction = false),
  ),
  // Protected branch requires 2 approvals
  Rule(
    matching = Input(
      numOfApprovals = it > 1,
      isTargetBranchProtected = it.isTrue,
      authorIsAdmin = it.catchAll,
    ),
    output = Output(allowMerging = true, notifyUnusualAction = false),
  ),
  // Admin can merge anything without approvals but this sends a notification
  Rule(
    matching = Input(
      numOfApprovals = it.catchAll,
      isTargetBranchProtected = it.catchAll,
      authorIsAdmin = it.isTrue,
    ),
    output = Output(allowMerging = true, notifyUnusualAction = true),
  ),
  // Nothing can be merged otherwise
  Rule.default(
    Output(allowMerging = false, notifyUnusualAction = false),
  ),
)

And create a decision:

val decisionTable: DecisionTable[Input, Output, HitPolicy.First] =
  DecisionTable(rules, name = "PullRequestDecision", HitPolicy.First)

By doing this, we specified a name that will be used for the generated diagram. We also defined the hit policy, which in our case will capture the first satisfied rule.

Evaluating the Decision

Now we can evaluate our decision:

val result: EvalResult.First[Input, Output] = decisionTable.evaluateFirst(
  Input[Value](
    numOfApprovals = 2,
    isTargetBranchProtected = true,
    authorIsAdmin = false,
  ),
)
assert(result.output == Some(Output[Value](allowMerging = true, notifyUnusualAction = false)))

It works!

Understanding the decision

But you might wonder why the given decision was made. Wonder no more!

println(result.makeDiagnosticsString)

Which gives us the following:

Evaluation diagnostics for "PullRequestDecision"
Hit policy: First
Result: Some(Output(true,false))
Input:
  numOfApprovals: 2
  isTargetBranchProtected: true
  authorIsAdmin: false
Rule 0 [✗]:
  numOfApprovals          [✓]: > 0
  isTargetBranchProtected [✗]: false
  authorIsAdmin           [✓]: -
  == ✗
Rule 1 [✓]:
  numOfApprovals          [✓]: > 1
  isTargetBranchProtected [✓]: true
  authorIsAdmin           [✓]: -
  == Output(true,false)

This not only tells us which rules were satisfied but also shows the results of specific predicates. This way, we can easily understand what happened!

Visualizing the Logic

Let's see how our logic presents itself in a more concise and human-friendly way:

import decisions4s.markdown.MarkdownRenderer
val markdown = MarkdownRenderer.render(decisionTable)

That's the output:

(I) numOfApprovals	(I) isTargetBranchProtected	(I) authorIsAdmin	(O) allowMerging	(O) notifyUnusualAction
> 0	false	-	true	false
> 1	true	-	true	false
-	-	true	true	true
-	-	-	false	false

And if that's not enough, we can also generate the DMN diagram. To do this, we need to add another dependency:

"org.business4s" %% "decisions4s-dmn" % "0.0.1"

And use the provided utilities:

import decisions4s.dmn.DmnRenderer
val dmnXML: String = DmnRenderer.render(decisionTable).toXML

Now if we open this file in bpmn.io or Camunda Modeler, we will see the following table:

This can now be shared with non-technical folks or saved as documentation!