Edomata

https://edomata.ir/
Admin
Edomata is a lightweight, purely functional Scala library for implementing event-driven automatons...
Tokens:10,136
Snippets:153
Trust Score:5.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### EitherNec Examples

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Demonstrates basic usage and composition of EitherNec, including creating Right and Left values and mapping.

```scala
val e1 = Right(1)
// e1: Right[Nothing, Int] = Right(1)
val e2 = "Missile Launched!".asRight
// e2: Either[Nothing, String] = Right(Missile Launched!)
val e3 = "No remained missiles to launch!".leftNec
// e3: Either[Type[String], Nothing] = Left(Chain(No remained missiles to launch!))
```

```scala
val e4 = e1.map(_ * 2)
// e4: Either[Nothing, Int] = Right(2)
val e5 = e2 >> e1
// e5: Either[Nothing, Int] = Right(1)
```

```scala
val e6 = for {
  a <- e4
  b <- e5
} yield a + b
// e6: Either[Nothing, Int] = Right(3)
```

--------------------------------

### Install Edomata Skunk dependencies

Source: https://edomata.ir/backends/skunk.html

Add the necessary library dependencies to your build file for standard, integrated, or Scala.js projects.

```sbt
libraryDependencies += "dev.hnaderi" %% "edomata-skunk" % "0.12.8"
```

```sbt
libraryDependencies += "dev.hnaderi" %% "edomata-skunk-circe" % "0.12.8"
libraryDependencies += "dev.hnaderi" %% "edomata-skunk-upickle" % "0.12.8"
```

```sbt
libraryDependencies += "dev.hnaderi" %%% "edomata-skunk" % "0.12.8"
```

--------------------------------

### Run Edomaton with Raw Response

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Illustrates using the `.run` method to get the raw `ResponseT` model from an Edomaton execution, which can be interpreted as needed.

```scala
AccountService[Id].run(scenario1)
```

--------------------------------

### Testing Domain Model Logic

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Provides examples of testing the domain logic for the Order model, demonstrating the outcomes of placing and marking orders.

```scala
Order.Empty.place("kebab", "home")
// res0: Either[Type[Rejection], Placed] = Right(Placed(kebab,home,New))
Order.Placed("pizza", "office").markAsCooking("chef")
// res1: Either[Type[Rejection], Placed] = Right(Placed(pizza,office,Cooking(chef)))
```

--------------------------------

### Compile Application to Service

Source: https://edomata.ir/backends/skunk.html

Build the backend using SkunkDriver or SkunkCQRSDriver and compile the application service.

```scala
val app  = ??? // your application from previous chapter
val pool : Resource[IO, Session[IO]] = ??? // create your own session pool

val buildBackend = Backend
  .builder(AccountService)               // 1
  .use(SkunkDriver("domainname", pool))  // 2
  // .persistedSnapshot(maxInMem = 200)  // 3
  .inMemSnapshot(200)
  .withRetryConfig(retryInitialDelay = 2.seconds)
  .build

val application = buildBackend.use { backend =>
  val service = backend.compile(app)
  // compiling your application will give you a function
  // that takes a messages and does everything required,
  // and returns result.

  service(
    CommandMessage("abc", Instant.now, "a", "receive")
  ).flatMap(IO.println)
}
```

--------------------------------

### Create Decisions using Syntax

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Shows alternative syntax for creating Decisions using imported extension methods.

```scala
import edomata.syntax.all.*

1.asDecision
// res0: Decision[Nothing, Nothing, Int] = InDecisive(1)
```

```scala
"Missile Launched!".accept
// res1: Decision[Nothing, String, Unit] = Accepted(Chain(Missile Launched!),())
```

```scala
"No remained missiles to launch!".reject
// res2: Decision[String, Nothing, Nothing] = Rejected(Chain(No remained missiles to launch!))
```

--------------------------------

### Import Edomata Core and Syntax

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Imports necessary Edomata modules for core functionality and convenient extension methods.

```scala
import edomata.core.*
import edomata.syntax.all.* // for convenient extension methods
```

--------------------------------

### Create an AccountService Edomaton

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Implement the AccountService, an Edomaton that handles account-related commands and publishes notifications. It uses a tagless final style for composability.

```scala
object AccountService extends Account.Service[Command, Notification] {
  import cats.Monad

  def apply[F[_] : Monad] : App[F, Unit] = App.router {

    case Command.Open => for {
      ns <- App.state.decide(_.open)
      acc <- App.aggregateId
      _ <- App.publish(Notification.AccountOpened(acc))
    } yield ()

    case Command.Deposit(amount) => for {
      deposited <- App.state.decide(_.deposit(amount))
      accId <- App.aggregateId
      _ <- App.publish(Notification.BalanceUpdated(accId, deposited.balance))
    } yield ()

    case Command.Withdraw(amount) => for {
      withdrawn <- App.state.decide(_.withdraw(amount))
      accId <- App.aggregateId
      _ <- App.publish(Notification.BalanceUpdated(accId, withdrawn.balance))
    } yield ()

    case Command.Close => 
      App.state.decide(_.close).void
  }

}
```

--------------------------------

### Implement OrderService Stomaton

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Create a service using App.router to handle commands, modify state, and publish notifications.

```scala
object OrderService extends Order.Service[Command, Notification] {
  import cats.Monad

  def apply[F[_] : Monad]: App[F, Unit] = App.router{
    case Command.Place(food, address) => for {
      ns <- App.modifyS(_.place(food, address))
      _ <- App.publish(Notification.Received(food))
    } yield ()
    case Command.MarkAsCooking(cook: String) => for {
      ns <- App.modifyS(_.markAsCooking(cook))
      _ <- App.publish(Notification.Cooking)
    } yield ()
    case _ => ??? // other command handling logic
  }
}
```

--------------------------------

### Import Edomata Skunk

Source: https://edomata.ir/backends/skunk.html

Import the required packages to access Skunk-specific functionality.

```scala
import edomata.skunk.*
```

--------------------------------

### Execute Edomaton with Cats Effect IO

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Demonstrates executing an Edomaton using the `execute` method with the `cats.effect.IO` monad for asynchronous operations.

```scala
import cats.effect.IO

AccountService[IO].execute(scenario1)
```

--------------------------------

### Define a Request Scenario for Testing

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Create a RequestContext to simulate a command scenario for testing an Edomaton. This includes command details like ID, time, address, and payload, along with the initial state.

```scala
import java.time.Instant

val scenario1 = RequestContext(
  command = CommandMessage(
    id = "some random id for request",
    time = Instant.MIN,
    address = "our account id",
    payload = Command.Open
  ),
  state = Account.New
)
```

--------------------------------

### Compile Application with DoobieDriver

Source: https://edomata.ir/backends/doobie.html

Build the Edomata backend service using DoobieDriver for event sourcing. Configure transactor, schema name, snapshotting, and retry policies.

```scala
val app  = ??? // your application from previous chapter
val trx : Transactor[IO] = ??? // create your Transactor

val buildBackend = Backend
  .builder(AccountService)               // 1
  .use(DoobieDriver("domainname", trx))  // 2
  // .persistedSnapshot(maxInMem = 200)  // 3
  .inMemSnapshot(200)
  .withRetryConfig(retryInitialDelay = 2.seconds)
  .build

val application = buildBackend.use {
  backend =>
    val service = backend.compile(app)
    // compiling your application will give you a function
    // that takes a messages and does everything required,
    // and returns result.

    service(
      CommandMessage("abc", Instant.now, "a", "receive")
    ).flatMap(IO.println)
}
```

--------------------------------

### Create Decisions

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Demonstrates the creation of Decision objects with different states: indecisive, accepted, and rejected.

```scala
val d1 = Decision(1)
// d1: Decision[Nothing, Nothing, Int] = InDecisive(1)
```

```scala
val d2 = Decision.accept("Missile Launched!")
// d2: Decision[Nothing, String, Unit] = Accepted(Chain(Missile Launched!),())
```

```scala
val d3 = Decision.reject("No remained missiles to launch!")
// d3: Decision[String, Nothing, Nothing] = Rejected(Chain(No remained missiles to launch!))
```

--------------------------------

### Implement Account Domain Logic with Edomata Decisions

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Implement domain logic for account operations (open, close, withdraw, deposit) using Edomata's Decision type. This includes state transitions, validations, and rejection handling. Requires Edomata core and syntax imports.

```scala
import edomata.core.*
import edomata.syntax.all.*
import cats.implicits.*
import cats.data.ValidatedNec

enum Account {
  case New
  case Open(balance: BigDecimal)
  case Close
  
  def open : Decision[Rejection, Event, Open] = this.decide { // 1
    case New => Decision.accept(Event.Opened)
    case _ => Decision.reject(Rejection.ExistingAccount)
  }.validate(_.mustBeOpen) // 2
  
  def close : Decision[Rejection, Event, Account] = this.perform(mustBeOpen.toDecision.flatMap { account => // 3, 4
    if account.balance == 0 then Event.Closed.accept
    else Decision.reject(Rejection.NotSettled)
  })
  
  def withdraw(amount: BigDecimal): Decision[Rejection, Event, Open] = this.perform(mustBeOpen.toDecision.flatMap { account => 
    if account.balance >= amount && amount > 0 
    then Decision.accept(Event.Withdrawn(amount))
    else Decision.reject(Rejection.InsufficientBalance) 
    // We can model rejections to have values, which helps a lot for showing error messages, but it's out of scope for this document
  }).validate(_.mustBeOpen)

  def deposit(amount: BigDecimal): Decision[Rejection, Event, Open] = this.perform(mustBeOpen.toDecision.flatMap { account =>
    if amount > 0 then Decision.accept(Event.Deposited(amount))
    else Decision.reject(Rejection.BadRequest)
  }).validate(_.mustBeOpen)
  
  private def mustBeOpen : ValidatedNec[Rejection, Open] = this match { // 5
    case o@Open(_) => o.validNec
    case New => Rejection.NoSuchAccount.invalidNec
    case Close => Rejection.AlreadyClosed.invalidNec
  }
}
```

--------------------------------

### Define Backend Codecs with Circe

Source: https://edomata.ir/backends/doobie.html

Configure backend codecs for event sourcing or CQRS using Circe for JSON serialization. Specify either JSON or JSONB format.

```scala
given BackendCodec[Event] = CirceCodec.jsonb // or .json
given BackendCodec[Notification] = CirceCodec.jsonb
```

```scala
given BackendCodec[State] = CirceCodec.jsonb
```

```scala
given BackendCodec[State] = CirceCodec.jsonb
```

--------------------------------

### Decision Composition with Cats Syntax

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Shows how to compose Decisions using Cats' syntax for tupled operations and traversals.

```scala
import cats.implicits.*

val d8 = (d1, d7).mapN(_ + _)
// d8: Decision[Nothing, String, Int] = Accepted(Chain(A, B, C, D, E),4)
```

```scala
val d9 = List.range(1, 5).traverse(Decision.accept(_))
// d9: Decision[Nothing, Int, List[Unit]] = Accepted(Chain(1, 2, 3, 4),List((), (), (), ()))
```

```scala
val d10 = Decision(List.range(1, 5)).sequence[List, Int]
// d10: List[Decision[Nothing, Nothing, Int]] = List(InDecisive(1), InDecisive(2), InDecisive(3), InDecisive(4))
```

--------------------------------

### Edomata and Cats Imports

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Imports necessary for using Edomata's core functionalities and convenient extension methods from Cats.

```scala
import edomata.core.*
import edomata.syntax.all.* // for convenient extension methods
import cats.implicits.* // to make life easier
```

--------------------------------

### Define Backend Interface

Source: https://edomata.ir/tutorials/3_processes.html

Initial backend definition required for subsequent operations.

```scala
def backend : Backend[IO, Account, Event, Rejection, Notification] = ???
```

--------------------------------

### Add Edomata Core to Build (Scala)

Source: https://edomata.ir/tutorials/0_getting_started.html

Use this dependency for Scala projects. Ensure you are using the correct version.

```scala
libraryDependencies += "dev.hnaderi" %% "edomata-core" % "0.12.8"
```

--------------------------------

### Import Edomata Doobie Package

Source: https://edomata.ir/backends/doobie.html

Import the necessary Doobie package from Edomata to enable its functionalities in your Scala code.

```scala
import edomata.doobie.*
```

--------------------------------

### Add Edomata Core to Build (Scala.js)

Source: https://edomata.ir/tutorials/0_getting_started.html

Use this dependency for Scala.js projects. Ensure you are using the correct version.

```scala
libraryDependencies += "dev.hnaderi" %%% "edomata-core" % "0.12.8"
```

--------------------------------

### Execute Edomaton with Cats Id Monad

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Demonstrates executing an Edomaton using the `execute` method with the `cats.Id` monad for synchronous, pure computations.

```scala
import cats.Id
val obtained = AccountService[Id].execute(scenario1)
```

--------------------------------

### Decision For-Comprehension

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Demonstrates creating a complex Decision using a for-comprehension, including accepting multiple events and returning a value.

```scala
val d7 = for {
  i <- Decision.pure(1)
  _ <- Decision.accept("A") // accepting one event
  _ <- Decision.accept("B", "C") // accepting several events
  j <- Decision.acceptReturn(i * 2)("D", "E") // accepting several events and returning a value
} yield i + j
// d7: Decision[Nothing, String, Int] = Accepted(Chain(A, B, C, D, E),3)
```

--------------------------------

### Define Commands and Notifications for Edomaton

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Define the command and notification ADTs (Algebraic Data Types) required for an Edomaton. These types model the messages an Edomaton can receive and emit.

```scala
enum Command {
  case Open
  case Deposit(amount: BigDecimal)
  case Withdraw(amount: BigDecimal)
  case Close
}

enum Notification {
  case AccountOpened(accountId: String)
  case BalanceUpdated(accountId: String, balance: BigDecimal)
  case AccountClosed(accountId: String)
}
```

--------------------------------

### Order Domain Logic with EitherNec

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Implements domain logic for the Order enum, including placing an order and marking it as cooking, using EitherNec for error handling.

```scala
import edomata.core.*
import cats.implicits.*
import cats.data.ValidatedNec

enum Order {
  case Empty
  case Placed(food: String, address: String, status: OrderStatus = OrderStatus.New)
  case Delivered(rating: Int)
  
  def place(food: String, address: String) = this match {
    case Empty => Placed(food, address).asRight
    case _ => Rejection.ExistingOrder.leftNec
  }
  
  def markAsCooking(cook: String) = this match {
    case st@Placed(_, _, OrderStatus.New) => st.copy(status = OrderStatus.Cooking(cook)).asRight
    case _ => Rejection.InvalidRequest.leftNec
  }
  
  // other logics from business
}
```

--------------------------------

### Test a Stomaton

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Execute a service definition using an effect type like cats.Id to verify state transitions and notifications.

```scala
import java.time.Instant

// as we've written our service definition in a tagless style, 
// we are free to provide any type param that satisfies required type-classes
val srv = OrderService[cats.Id] // or any other effect type

val scenario1 = srv.run(
  CommandMessage(
    id = "cmd id",
    time = Instant.MIN,
    address = "aggregate id",
    payload = Command.Place("taco", "home")
  ),
  Order.Empty    // state to run command on
)
```

```scala
scenario1.result
// res2: Either[Type[Rejection], Tuple2[Order, Unit]] = Right((Placed(taco,home,New),()))
scenario1.notifications
// res3: Chain[Notification] = Chain(Received(taco))
```

--------------------------------

### Compose Decisions

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Illustrates how Decision objects can be composed using map and the ">>" operator.

```scala
val d4 = d1.map(_ * 2)
// d4: Decision[Nothing, Nothing, Int] = InDecisive(2)
```

```scala
val d5 = d2 >> d1
// d5: Decision[Nothing, String, Int] = Accepted(Chain(Missile Launched!),1)
```

```scala
val d6 = d5 >> d3
// d6: Decision[String, String, Nothing] = Rejected(Chain(No remained missiles to launch!))
```

--------------------------------

### Define Domain Model Transitions

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Implement the DomainModel trait to define the initial state and transition logic for an account domain model.

```scala
object Account extends DomainModel[Account, Event, Rejection] {
  def initial = New  // 1
  def transition = { // 2
    case Event.Opened => _ => Open(0).validNec
    case Event.Withdrawn(b) => _.mustBeOpen.map(s => s.copy(balance = s.balance - b)) // 3
    case Event.Deposited(b) => _.mustBeOpen.map(s => s.copy(balance = s.balance + b)) 
    case Event.Closed => _=> Close.validNec
  }

}
```

--------------------------------

### Test Domain Model Logic

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Execute domain model operations to verify state transitions and decision outcomes.

```scala
Account.New.open
// res4: Decision[Rejection, Event, Open] = Accepted(Chain(Opened),Open(0))
Account.Open(10).deposit(2)
// res5: Decision[Rejection, Event, Open] = Accepted(Chain(Deposited(2)),Open(12))
Account.Open(5).close
// res6: Decision[Rejection, Event, Account] = Rejected(Chain(NotSettled))
Account.New.open.flatMap(_.close)
// res7: Decision[Rejection, Event, Account] = Accepted(Chain(Opened, Closed),Close)
```

--------------------------------

### Access Aggregate Repository

Source: https://edomata.ir/tutorials/3_processes.html

Retrieve aggregate history or the current state from the repository.

```scala
def history : Stream[IO, AggregateState[Account, Event, Rejection]] = backend.repository.history("interesting-stream")
```

```scala
def current : IO[AggregateState[Account, Event, Rejection]] = backend.repository.get("interesting-stream")
```

--------------------------------

### Assert Edomaton Execution Result

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Shows how to assert the expected outcome of an Edomaton execution, comparing the actual result with the anticipated `EdomatonResult.Accepted` state, events, and notifications.

```scala
assertEquals(
  obtained,
  EdomatonResult.Accepted(
    newState = Account.Open(0),
    events = ...
    notifications = ...
  )
)
```

--------------------------------

### Order CQRSModel Definition

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Defines the initial state for the Order aggregate using CQRSModel, ensuring model consistency.

```scala
object Order extends CQRSModel[Order, Rejection] {
  def initial = Empty
}
```

--------------------------------

### Define Command and Notification ADTs

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Define the domain-specific commands and notifications required for the service state machine.

```scala
enum Command {
  case Place(food: String, address: String)
  case MarkAsCooking(cook: String)
  case MarkAsCooked
  case MarkAsDelivering(unit: String)
  case MarkAsDelivered
  case Rate(score: Int)
}

enum Notification {
  case Received(food: String)
  case Cooking
  case Cooked
  case Delivering
  case Delivered
}
```

--------------------------------

### Command Handler Signature

Source: https://edomata.ir/principles/definitions.html

A command handler is a function that receives a command message, applies domain logic, and returns a result. It can be rejected based on system logic or state.

```Scala
cmd => F[EitherNec[Rejection, Unit]]
```

--------------------------------

### Consume Outbox Items

Source: https://edomata.ir/tutorials/3_processes.html

Use OutboxConsumer to process outboxed items. Note that this does not handle action failures automatically.

```scala
def publisher : Stream[IO, Nothing] = OutboxConsumer(backend){ item =>
  // use outboxed item
  ???
}
```

--------------------------------

### Add Edomata Doobie Dependency

Source: https://edomata.ir/backends/doobie.html

Include the Doobie library dependency in your Scala project's build.sbt file. Choose the appropriate module based on your serialization needs (circe or upickle).

```scala
libraryDependencies += "dev.hnaderi" %% "edomata-doobie" % "0.12.8"
```

```scala
libraryDependencies += "dev.hnaderi" %% "edomata-doobie-circe" % "0.12.8"
libraryDependencies += "dev.hnaderi" %% "edomata-doobie-upickle" % "0.12.8"
```

--------------------------------

### Model Rejection Scenarios with Scala 3 Enums

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Model potential rejection scenarios like ExistingAccount, NoSuchAccount, InsufficientBalance, NotSettled, AlreadyClosed, and BadRequest using Scala 3 enums.

```scala
enum Rejection {
  case ExistingAccount
  case NoSuchAccount
  case InsufficientBalance
  case NotSettled
  case AlreadyClosed
  case BadRequest
}
```

--------------------------------

### Model Aggregate Root with Scala 3 Enums

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Represent the state of an account aggregate root (New, Open, Close) using Scala 3 enums.

```scala
enum Account {
  case New
  case Open(balance: BigDecimal)
  case Close
}
```

--------------------------------

### Read Journal Streams

Source: https://edomata.ir/tutorials/3_processes.html

Methods for reading from the event journal, including full history, specific streams, and sequence-based filtering.

```scala
def all = backend.journal.readAll
```

```scala
def singleStream = backend.journal.readStream("interesting-stream")
```

```scala
def allAfter = backend.journal.readAllAfter(100)
def singleBefore = backend.journal.readStreamBefore("interesting-stream" ,100)
```

--------------------------------

### Rejection Enum Definition

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Defines the Rejection enum for modeling potential business rule violations or errors in the domain.

```scala
enum Rejection {
  case ExistingOrder
  case NoSuchOrder
  case InvalidRequest // this should be more fine grained in real world applications
}
```

--------------------------------

### Model Domain Events with Scala 3 Enums

Source: https://edomata.ir/tutorials/1-1_eventsourcing.html

Define domain events such as Opened, Deposited, Withdrawn, and Closed using Scala 3 enums for ADTs.

```scala
enum Event {
  case Opened
  case Deposited(amount: BigDecimal)
  case Withdrawn(amount: BigDecimal)
  case Closed
}
```

--------------------------------

### Event Handler Transformation

Source: https://edomata.ir/principles/definitions.html

An event handler transforms an event stream into a process stream, potentially running side effects. It can be modeled as a pipe.

```Scala
fs2.Pipe[F, Event, Nothing]
```

--------------------------------

### Order Enum Definition

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Defines the Order aggregate root using Scala 3 enums, representing different states of an order.

```scala
enum Order {
  case Empty
  case Placed(food: String, address: String, status: OrderStatus = OrderStatus.New)
  case Delivered(rating: Int)
}
```

--------------------------------

### OrderStatus Enum Definition

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Defines the OrderStatus enum to represent the various stages an order can be in during its lifecycle.

```scala
enum OrderStatus {
  case New
  case Cooking(cook: String)
  case WaitingToPickUp
  case Delivering(unit: String)
}
```

--------------------------------

### EitherNec Type Alias

Source: https://edomata.ir/tutorials/1-2_cqrs.html

Defines EitherNec as a type alias for Either with NonEmptyChain on the left side, commonly used for error handling.

```scala
type EitherNec[L, R] = Either[NonEmptyChain[L], R]
```
Tokens:
Raw