The Vapors library provides an embedded-DSL for writing expressions that look similar to the Scala collections library and can be interpreted to produce a function that computes the result given a set of source facts.

These expressions are descriptions of computations that can be optimized, serialized, and interpreted in various ways using a tagless final recursive visitor (see Expr.Visitor).

This library is built on top of Scala's cats library for typeclass definitions. See the Implementation section for more details.

You might want to also check out these helpful slides on the library design for more details. (The slides are a little bit out of date, but the basic ideas are the same)

1. Add it to your build.sbt using version=

   libraryDependencies += "com.rallyhealth" %% "vapors-v1" % "version"

2. Define your fact types.

   Every fact type must have a unique name as well as a Scala type. You can define a FactType with any Scala type you want, so long as it defines an Order. This is so the facts can be pulled from the FactTable in a reasonable order.

   object FactTypes {
     val DateOfBirth = FactType[LocalDate]("DateOfBirth")
     val Role = FactType[Role]("Role")
   }
   
   sealed trait Role
   object Role {
     case object Admin extends Role
     case object User extends Role
   
     implicit val order: Order[Role] = Order.reverse[Role] {
       Order.by {
         case Admin => 1
         case User => 2
       }
     }
   }

   Typically, if you have it, you'll order things by timestamp. Stay tuned for a data type that encapsulates Timestamped facts.

3. Import the DSL.

   You get different behavior and add support for different interpreters based on which DSL you use.

   If you just want to compute an expression quickly, with no justification wrapper, then you can use:

   import com.rallyhealth.vapors.v1.dsl.uncached._
   

   If you want your expression to produce a Justified wrapped value, then you can use:

   import com.rallyhealth.vapors.v1.dsl.uncached.justified._
   

   Now when you call .run() or .runWith() on your expression, you can traverse the tree of justification for what operations produced that value.

4. Craft your expressions.

   Typically, you will start your expression using a value from the FactTable. You can use the valuesOfType operation to do so.

   Since every FactType can have multiple instances defined in the FactTable, they must also define an Order, so that the facts can come out of the FactTable in some natural ordering:

   import com.rallyhealth.vapors.v1.dsl.uncached._
   
   val isAdmin = {
     valuesOfType(FactTypes.Role).exists(_ === Role.Admin)
   }
   val isOver18 = {
     valuesOfType(FactTypes.DateOfBirth).exists { fact =>
       dateDiff(fact, today, ChronoUnit.YEARS.const) >= 18.const
     }
   }

5. Run your expression with a set of facts.

   Assuming you have these facts:

   import FactTypes._
   
   val dob = FactTypes.DateOfBirth(LocalDate.of(1980, 1, 1))
   val adminRole = FactTypes.Role(Role.Admin)
   val userRole = FactTypes.Role(Role.User)
   
   val facts = FactTable(
     dob,
     adminRole,
     userRole
   )

   If you use the justified DSL, then you can get the list of facts (i.e. the Evidence) used to produce the output.

   import com.rallyhealth.vapors.v1.dsl.uncached.justified._
   
   val isAdminResult = isAdmin.run(facts)
   assert(isAdminResult.value)
   assertEquals(isAdminResult.evidence, Evidence(adminRole))
   
   val combinedResult = and(isAdmin, isOver18).run(facts)
   assert(combinedResult.value)
   assertEquals(combinedResult.evidence, Evidence(adminRole, dob))

   If your expression requires anything other than Any, then you can only call .runWith() to provide the required input of the expected type.

   val isGt3 = ident[Int] > 3.const
   assert(isGt3.runWith(5))
   compileErrors("isGt3.run()")

The type of operators that are available for a type are dependent on the instances of cats typeclasses that are available in implicit scope. So for example, if you want to be able to use <, >=, ===, =!=, etc then you need to define an Order instance for your type.

case class FeetAndInches(feet: Int, inches: Int)
object FeetAndInches {
  implicit val order: Order[FeetAndInches] = Order.fromLessThan { (l, r) =>
    l.feet < r.feet || (l.feet == r.feet && l.inches < r.inches)
  }
}

In essence, every expression (Expr[I, O, OP]) can be optimized and interpreted to produce a function like:

(FactTable, I) => O

NOTE: If the I type is Any, then the framework will substitute ExprState.Nothing for the input and allow you to treat the function like:

FactTable => O

The goal of this library is to provide a way to build serializable and introspectable definitions for facts. These can also be thought of as "rules". Thus making this a rules engine library where the "rules" are built using a strongly-typed, embedded domain-specific language (eDSL) using the Scala compiler.

You might wonder: Why not just use an existing rules engine DSL? Or why not just serialize native Scala code?

1. Justification

   The limited DSL allows computing a value alongside the chain of inferences that justifies that value from some set of source facts, config values, and / or constants.

   While many rules engines support serialization and ways of representing this capability, AFAICT none explicitly support it.

2. Type-Safety

   By using an embedded DSL, we take advantage of the Scala compiler to catch errors at compile-time and provide an IDE experience.

   While a goal of this project is to allow parsing expressions from files or strings, it should only be done so in a manner that does not violate strongly-typed schemas. In the meantime, we offer capabilities to operate on algebraic data types using shapeless.HList operations.

3. Customization

   By using embedding the construct within a fully-featured language, the library user is empowered to interpret and customize the DSL to suit their own needs with the full power of the Scala programming language with an interface that is designed for extension.

Every Fact -- whether a source fact or derived fact -- is produced from a FactType.

A FactType[T] is constructed with both a String name and a Scala type parameter. The FactType[T] then acts like a function that produces TypedFact[T] instances given values of type T.

val Age = FactType[Int]("age")
val sourceFact = Age(23)

All TypedFact[_] instances extend Fact which has a dependent type member called Value which is assigned to the type parameter. This allows using these Fact instances inside invariant collections (like Set[Fact]). You could also conceivably match on the .factType of a Fact to determine the Value type from the original FactType[T].

In the case that you need to handle multiple facts with the same Scala type, but different names (thus different FactType[T] definitions), you can use a FactTypeSet[T]. This can be useful if you are able to handle a common supertype of multiple FactType[_] definitions in a common way. All operations that handle a single FactType[T] can also handle a FactTypeSet[T]. Just be careful not to combine two different fact types with the same Scala type that have different units of measurement. For example, FactType[Double]("weight_kg") and FactType[Double]("weight_lbs") might have the same Scala type, Double, but you should be careful not to perform calculations that are only valid if you are operating in the metric system.

Every expression can be computed by providing a FactTable. This is a map of FactTypes to instances of those TypedFacts that can be retrieved at any point in the computation with O(1) performance.

When computing an expression, you will often want to feed the expression some starting set of source facts. These facts are available in all computations using the valuesOfType operation, which can retrieve all instances of these facts from the FactTable that was initially provided.

There is no distinction between source facts and derived facts beyond the understanding of when they were defined. If they are defined as part of the process of evaluating an expression, then they are "derived", otherwise, they must have been provided to the FactTable as "source" facts.

You can use a define operation to create a definition expression, which can be provided to a using expression to compute some values from the result of that definition expression having added all the values computed by the expression into the FactTable.

import com.rallyhealth.vapors.v1.data.{FactType, FactTable}
import com.rallyhealth.vapors.v1.dsl.uncached._

import java.time.LocalDate
import java.time.temporal.ChronoUnit

val Age = FactType[Int]("age")
val DateOfBirth = FactType[LocalDate]("date_of_birth")
val defineAgeFromDob = define(Age).fromSeq {
  valuesOfType(DateOfBirth).map { dob =>
    dateDiff(today, dob, ChronoUnit.YEARS)
  }
}
val isOver18 = using(defineAgeFromDob).thenReturn {
  _.forall(_ >= 18.const)
}
// This will be true when run any day after 2007-12-31
assert(isOver18.run(FactTable(LocalDate.of(1990, 1, 1))))

(_, ft: FactTable) =>
  ft.getSortedSeq(FactTypeSet.one(Age))
    .map(_.value)

(i: I, ft: FactTable) =>
  ft.addAll(defineAge(i))
    .getSortedSeq(Age)
    .map(_.value)
    .exists(_ > 21)

ident[Person].matching(
  Case[Admin] ==> Role.Admin.const,
  Case[Employee].when {
    _.get(_.select(_.role)) >= Role.Editor.const
  } ==> ident[Employee].get(_.role),
)

(_: Person) match {
  case _: Admin => Some(Role.Admin)
  case e: Employee if e.role >= Role.Editor => Some(e.role)
  case _ => None
}

when(true.const)
  .thenReturn(1.const)
  .elseReturn(0.const)

ident[RoleClass].matching(
  Case[Editor].when(_.get(_.select(_.articles)) > 0.const) ==>
    ident[Editor].get(_.select(_.permissions))
)

(_: RoleClass) match {
  case e: Editor if e.articles > 0 => Some(e.permissions)
  case _ => None
}

wrap(
  Seq(1, 2, 3).const,
  repeatConstForever(0.const)
).zipToShortest

Seq(1, 2, 3)
  .zip(IterableOnce.continually(0))
  .map {
    case (l, r) } => l :: r :: HNil
  }

^* Every Expr has 3 parameters, -I input, +O output, and OP[_] the output parameter. Since the OP type is repeated throughout every expression and has no real implication on the standard behavior of the language, I have removed it from the signatures. So, for example, if we have a subclass of Expr named Op, the signature would be shown as Op[-I, +O], rather than Op[-I, +O, OP[_]].

^** Every Expr[I, O, OP[_]] built by an unwrapped DSL is interpreted as a function (I, FactTable) => O, however to simplify this column, any expression that does not depend on the FactTable will only use the input parameter, I.

^† These operations have a custom "wrapper" type W[+_]. This is not the ideal state for the expression algebra, as the wrapper type is an artifact of the DSL, and not the underlying logic of the language. Unfortunately, I was not able to figure out how to solve various issues that arose from using a single concrete type parameter (rather than a higher-kinded parameter and a concrete inner parameter).

Note that the type OP is the "output parameter" that can be used when building an interpreter (i.e. Expr.Visitor) to provide type-bounded context for the output of every expression node. It can also be used when defining mathematic or comparison operations like addition, equality, etc. Lastly, it can be used when interpreting an ExprResult (more details on this later).

In the simple uncached DSL, the result is computed directly without any wrapper. The interpreter produces a stream-lined and efficient function because it can ignore any work required to wrap the results. You can define custom DSLs and interpreters that produce different results, but they will likely be slower.

The following a more complete example of a set of facts and an evaluated query.

import cats.Order
import com.rallyhealth.vapors.v1.dsl.uncached.justified._

case class SemVer(major: Int, minor: Int, patch: Int)
object SemVer {
  implicit val order: Order[SemVer] = Order.fromLessThan { (l, r) =>
    l.major < r.major || l.major == r.major && l.minor < r.minor || l.major == r.major && l.minor == r.minor && l.patch < r.patch
  }
}

case class PredictionModel(
  modelName: String,
  modelVersion: SemVer,
  score: Double
)

object FactTypes {
  val DateOfBirth = FactType[LocalDate]("date_of_birth")
  val HeightFt = FactType[FeetAndInches]("height_ft")
  val WeightLbs = FactType[Int]("weight_lbs")
  val Prediction = FactType[PredictionModel]("prediction")
}

object JoeSchmoe {
  val height = FactTypes.HeightFt(FeetAndInches(5, 8))
  val weight = FactTypes.WeightLbs(260)
  val dateOfBirth = FactTypes.DateOfBirth(LocalDate.of(1980, 1, 1))
  val predictWeightloss = FactTypes.Prediction(PredictionModel("weightloss", SemVer(2, 0, 1), 0.85))
  val facts = FactTable(height, weight, dateOfBirth, predictWeightloss)
}

object Example {
  val query: Any ~:> Boolean = {
    or(
      and(
        valuesOfType(FactTypes.WeightLbs).exists(_ > 250.const),
        valuesOfType(FactTypes.HeightFt).exists(_ < FeetAndInches(6, 0).const)
      ),
      and(
        valuesOfType(FactTypes.WeightLbs).exists(_ > 300.const),
        valuesOfType(FactTypes.HeightFt).exists(_ >= FeetAndInches(6, 0).const)
      ),
      valuesOfType(FactTypes.Prediction).exists { prediction =>
        and(
          prediction.get(_.select(_.modelName)) === "weightloss".const,
          prediction.get(_.select(_.score)) > 0.8.const,
          prediction.get(_.select(_.modelVersion)) >= SemVer(2, 0, 0).const
        )
      }
    )
  }
  val rs = query.run(JoeSchmoe.facts)
  assert(rs.value)
  assert(rs.evidence == Evidence(JoeSchmoe.height, JoeSchmoe.weight, JoeSchmoe.predictWeightloss))
}

Since you cannot drop a breakpoint at a specific point in the construction of the expression (as you probably want access to the value when it is running, rather than the mostly visible information available when the expression is being constructed), we provide a mechanism to attach a debug function.

For example, you can call .debug on any Expr to provide a ExprState[?, O] => Unit function that will be evaluated when the expression is run. By attaching this debug function, you also get place where you can drop a breakpoint.

Note: The input type of the ExprState provided to the debug function depends on the Expr subclass. This is the primary reason why DSLs return the specific Expr subclass rather than their widened I ~:> O type. Likewise, the specific Expr type is unaffected by attaching a debug function.

import com.rallyhealth.vapors.v1.dsl.uncached._

object Example {
  val query: Seq[String] ~:> Boolean = ident[Seq[String]].exists {
    _.sizeIs > 3
  }.debug { s =>
    val in = s.input
    val out = s.output
    println(s"INPUT: $in")
    println(s"OUTPUT: $out")
  }
}

✅ - Fully implemented and tested. Only minor changes to be expected.

☑️ - Fully implemented but with some inconsistencies. Major changes are plausible.

◽️ - Partially implemented. Major changes are likely.

In order to convert from an Expr into something useful, we must interpret the expression.

The main interpreter is the engine provided by your imported DSL. If you are using an unwrapped DSL, then this is probably the SimpleEngine.Visitor which converts an Expr[I, O, OP] into a function (I, FactTable) => O.

There is also a Justified DSL that uses the same SimpleEngine, but it returns a Justified[O] instead of just the O. This allows you to follow the chain of justification for any produced output.

Lastly, there is a StandardEngine^† which interprets the Expr as a function that produces an ExprResult, which is another recursive data structure that mirrors the expressions used to construct it. This mirror data structure contains all the information of the original expression combined with the state and the captured output parameters at the point where it was evaluated. This data structure can be re-interpreted with an ExprResult.Visitor to serialize the evaluation, create some kind of visualization, etc. It is much slower to capture all of this data, so this DSL is only recommended if you need any of these capabilities. This is a large part of the reason why the name will likely change from "standard" to something more descrtiptive to its purpose.

^† This engine requires redesign. The name and implementation are likely to change fairly dramatically.

You can define your own Expr.Visitor to produce something other than a function. For example, we can interpret an Expr as a Json object by providing an interpreter that looks like:

import io.circe.Json
import io.circe.syntax._

object VisitExprAsJson {
  type G[-_, +_] = Json
}

class VisitExprAsJson[OP[a] <: HasEncoder[a]] extends Expr.Visitor[VisitExprAsJson.G, OP] {

  implicit def encodeOutput[O](implicit op: OP[O]): Encoder[O] = op.encoder

  override def visitConst[O : OP](expr: Expr.Const[O, OP]): Json = Json.obj(
    "$type" -> expr.name.asJson,
    "value" -> expr.value.asJson,
  )

  // ... implement all other visitX methods to produce Json
}