Announcing Decisions4s: When Ifs Are Not Enough

Defining and visualising core business logic.

Almost any non-trivial application contains some core pieces of conditional logic. Until now we lacked tools in the Scala ecosystem to give appropriate weight to that logic. This has changed.

TL;DR: This post explains what is Decisions4s and why you might want to use it.

What is Decisions4s?

It’s a lightweight Scala library that allows you to model, visualise, evaluate and debug conditional logic. This might sound a bit abstract, so here is an example. Decisions4s allows you to convert this “pull request logic”:

val allowMerging =
  if (numOfApprovals > 0) {
    if (isTargetBranchProtected && (numOfApprovals > 1 || isUserAdmin)) true
    else !isTargetBranchProtected
  } else if (isUserAdmin) true
  else false
val notifyUnusualAction = numOfApprovals == 0 && allowMerging

Into a DSL that looks like this:

Rule(
  matching = Input(
    numOfApprovals = it > 0,
    isTargetBranchProtected = it.isFalse,
    authorIsAdmin = it.catchAll,
  ),
  output = Output(allowMerging = true, notifyUnusualAction = false),
)

That allows you to render diagrams such as:

Evaluate it with:

decisionTable.evaluateFirst(
    Input(
      numOfApprovals = 2,
      isTargetBranchProtected = true,
      authorIsAdmin = false,
    ),
  )

While also providing helpful diagnostics similar to:

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)

Moreover it can also handle effectful inputs (through lazy, memoized evaluation) and visualise decision in other ways, e.g. via Markdown table.

Now the scope of the library should be much clearer. If you wonder about all the nitty-gritty details, check the full example in our Getting Started doc.

Aren’t If Expressions Enough?

You might wonder why you need a library for something as ubiquitous as conditional logic. Here are some reasons:

• You were given the logic directly by the business and need to ensure it's matching what was requested.
• You were asked at least a few times how the given piece of logic works.
• Your logic is hard to modify and understand because of how complex it is.
• You have to frequently understand why the logic took a certain path.
• You want to give more focus to the business side of your system and strengthen the collaboration between engineers and non-technical stakeholders.

We believe that in all of these cases, standard ifs are not enough.

Boring Technical Solution To An Important Human Problem

Let’s make a controversial statement: engineers should talk to the business. Considering that sometimes engineers don’t excel in talking to other engineers, this is no easy feat. Unfortunately, your stakeholders & domain experts are the key component of software development at scale.

But to have a meaningful conversation, people need to have a common language. And this can be hard to achieve: business doesn’t understand technical concepts, and engineers tend to speak purely in terms of those.

Decisions4s aims to bridge that gap by providing a medium of communication that is

1. Generated directly from the code (so no need to hand-write anything!)
2. Understandable by non-technical people.

We believe this can be a game changer when it comes to strengthening the collaboration culture in your organisation.

Summary

The next time you find yourself struggling with complicated conditional logic, know that you have new tools at your disposal!

Decisions4s was just released and comes with comprehensive documentation about not only what it can do and how, but also about its design, Scala 2 support, production readiness and more! It’s a great moment to give it a try.

Decisions4s is also the first released project of the Business4s community. If you have not heard about it before, read the announcement and join our Discord!