Join

Defines an object join of Left and Right by Key resulting R.

Implementing this interface provides a join of Left and Right to R with respect to Key, which can be used in Join.Monadic[]. For instance, to declare that a Car has an Engine with respect to CarId and they can be merged to CarWithEngine, implementing Join[CarWithEngine, Carid, Car, Engine] and passing it to Join.Monadic defines an accessor from a Car to a CarWithEngine.

object HasEngine
    extends Join[CarWithEngine, CarId, Car, Engine] {
  def leftKey(car: Car): CarId = ???
  def rightKey(engine: Engine): CarId = ???
  def map(from: Seq[Car]): Seq[Engine] = ???
  def merge(car: Car, engine: Engine): CarWithEngine = ???
}

// An accessor provider
case class CarRelation(car: Car) {
  def withEngine = Join.Monadic(car, HasEngine)
}

You need to implement four methods. First, leftKey() and rightKey() defines how to resolve a Key from a Left and a Right. Second, map() which maps values of Left to values of Right. Finally, merge() defines how to merge two objects into a value of R.

Although the defined accessor is for a single instance, the mapping defines a list-to-list mapping. This allows you to define an efficient way to retrieve multiple objects at once. The resulting list may NOT be in the same order as the input list or it may lack some elements correspond to those in the input, i.e., the mapping is actually a set-to-set mapping and the mapping function may not be total. If a value lacks a mapping result, that value is excluded from the merged result. If there are multiple values in the resulting list with the same Key (which is resolved by rightKey), then a source value with the Key will be merged with one of them.

In the above example, you may want to have an implicit conversion from a Car to an CarRelation to allow merging an Engine to a Car.

implicit def carRelation(car: Car): CarRelation = CarRelation(car)

// Single object mapping
val car: Car = ???
val enginedCar: Option[CarWithEngine] = car.withEngine

// Multiple object mapping
val cars: Seq[Car] = ???
val enginedCars: Seq[CarWithEngine] = cars.map(_.withEngine)

See the documentation of Join.Monadic for the detail of the accessor behavior.