The Equinox Programming Model

Unknown — Mon, 05 Dec 2022 00:00:00 +0000

My team at birdie</a> recently moved from a home-rolled event-sourcing library to Equinox</a> in one of our services. Equinox describes itself as a set of low-dependency libraries allowing event-sourced processing against stream-based stores. While this description is technically accurate, a cursory look at the codebase reveals that a programming model has formed around the library over time. This article seeks to explore that programming model.

In this article, I will show you the building blocks at play in the equinox model and how they fit together. We'll go through Events, Folds, Decisions, Domain Services, how to test them, and how to wire them up. A base-level knowledge of event-sourcing is assumed.

Terminology</h1>
As usual, it is best to get some terminology out of the way before diving in.

Stream</dt>
A sequence of ordered events, typically for a single process or entity e.g. `User-1</code></dd>`
`Category</dt>`
`A grouping of related streams e.g. User-1</code> belongs to the User</code> category</dd>`
`Optimistic Concurrency Control</dt>`
`the ability to request that a write be rejected if a specified precondition no longer holds. In a message stream, this is achieved by checking that the last event considered when deriving the state is still the last event </dd>`
`DU</dt>`
`Discriminated Union. A data type that allows you to represent one of a fixed set of choices. also called a tagged union, variant, choice type, disjoint union, sum type, or coproduct</dd> </dl>`The Domain</h1>
Because this article's purpose is pedagogical, we must choose a simple domain. The goal is to explain the different parts that make up an event-sourced application under Equinox, not to learn the intricacies of a domain. The process we'll be modeling is a simplified invoicing process for which we'll use four events.

`InvoiceRaised</code> - the invoice was raised</li>`
`InvoiceEmailed</code> - the invoice was emailed to the payer</li>`
`PaymentReceived</code> - The payer has posted payment for the invoice</li>`
`InvoiceFinalized</code> - The invoice has been finalised</li> </ol>`The Events</h1> In an event-sourced system, a Category can be considered analogous to a class. A key insight of Equinox is that all relevant events for a category can be united as a single Event DU. By convention, we place the Event DU into an Events</code> module. module Events = type InvoiceRaised = { InvoiceNumber: int Payer: string Amount: decimal } type Payment = { Amount: decimal } type EmailReceipt = { IdempotencyKey: string; Recipient: string; SentAt: DateTimeOffset } type Event = | InvoiceRaised of InvoiceRaised | InvoiceEmailed of EmailReceipt | PaymentReceived of Payment | InvoiceFinalized</code></pre> Using a DU to represent a given category's set of events is beneficial because the F# compiler can warn us when we forget to handle an event. F# will warn any time it notices a match expression doesn't match its inputs totally. While a sensible choice, it is not without drawbacks. With this model, the common practise of utilising global TypeMap</code> containing a mapping from an event type to a class is a non-starter. A follow-on consequence is that we must handle encoding and decoding for each category separately. Many practitioners choose to hand-roll</a> serialisation and deserialisation functions. module Serialization = open System.Text.Json let serialize x = JsonSerializer.SerializeToUtf8Bytes(x) |> ReadOnlyMemory let encode event = match event with | InvoiceRaised data -> "InvoiceRaised", serialize data | InvoiceEmailed data -> "InvoiceEmailed", serialize data | PaymentReceived data -> "PaymentReceived", serialize data | InvoiceFinalized -> "InvoiceFinalized", serialize null let decode (eventType, data) = match eventType with | "InvoiceRaised" -> InvoiceRaised (JsonSerializer.Deserialize(data.Span)) | "InvoiceEmailed" -> InvoiceEmailed (JsonSerializer.Deserialize(data.Span)) | "PaymentReceived" -> PaymentReceived (JsonSerializer.Deserialize(data.Span)) | "InvoiceFinalized" -> InvoiceFinalized</code></pre> Hand-rolled functions have the advantage of giving complete control over the serialisation format, which can be necessary in cases where you're migrating to F#. On the other hand, the typical method in equinox is to use FsCodec</a>. FsCodec can generate codecs for events as long as you constrain yourself to use types that work with System.Text.Json</code>. This codec typically lives in the same module as the events. module Events = type Event = | InvoiceRaised of InvoiceRaised | InvoiceEmailed of EmailReceipt | PaymentReceived of Payment | InvoiceFinalized // TypeShape's UnionEncoder, which does the codec generation, insists on this marker interface being present // to remind us that this is a long term storage contract that needs to be versionable interface TypeShape.UnionContract.IUnionContract let codec = FsCodec.SystemTextJson.Codec.Create<Event>()</code></pre>The Fold</h1> Current state is a left fold of previous events </blockquote> What exactly does the above quote mean? The concept of folding has different names in different languages. You may have heard a JavaScripter talk about reduce</code> and reducers. A C# practitioner might talk about calling Aggregate</code> on an IEnumerable</code>. In F#, we call it fold</code>. In Equinox parlance, the Fold is a module responsible for defining the state and how it evolves in response to events. module Fold = open Events type InvoiceState = { Amount: decimal InvoiceNumber: int Payer: string EmailedTo: Set<string> Payments: Set<string> AmountPaid: decimal } type State = | Initial | Raised of InvoiceState | Finalized of InvoiceState let initial = Initial let evolve state event = match state with | Initial -> match event with | InvoiceRaised data -> Raised { Amount = data.Amount InvoiceNumber = data.InvoiceNumber Payer = data.Payer EmailedTo = Set.empty Payments = Set.empty AmountPaid = 0m } // We're guaranteed to not have two InvoiceRaised events and that it is the first event in the stream | e -> failwithf "Unexpected %A" e | Raised state -> match event with | InvoiceRaised _ as e -> failwithf "Unexpected %A" e | InvoiceEmailed r -> Raised { state with EmailedTo = state.EmailedTo |> Set.add r.Recipient } | PaymentReceived p -> Raised { state with AmountPaid = state.AmountPaid + p.Amount Payments = state.Payments |> Set.add p.PaymentId } | InvoiceFinalized -> Finalized state // A Finalized invoice is terminal. No further events should be appended | Finalized _ -> failwithf "Unexpected %A" event let fold: State -> Event seq -> State = Seq.fold evolve </code></pre>The Decisions</h1> The Command pattern can be considered the standard way to implement decisions. Create a Command</code> DU, and a decide : Command -> State -> Event list</code> function. This pattern has benefits in that it forces you to enumerate all the different actions you'd like to take on the state in a single place. In practice, I've found the pattern more of a hindrance than a help and usually end up refactoring it away in favour of a Decisions</code> module. module Decisions = let raiseInvoice data state = match state with | Fold.Initial -> [ Events.InvoiceRaised data ] // This is known as an idempotency check. We could be receiving the same // command due to a retry, in which case it is not considered a failure // since the Fold will already be in the state that this command should put it in | Fold.Raised state when state.Amount = data.Amount && state.Payer = data.Payer -> [] | Fold.Raised _ -> failwith "Invoice is already raised" | Fold.Finalized _ -> failwith "Invoice is finalized" let private hasSentEmailToRecipient recipient (state: Fold.InvoiceState) = state.EmailedTo |> Set.contains recipient let recordEmailReceipt (data: Events.EmailReceipt) state = match state with | Fold.Raised state when not (hasSentEmailToRecipient data.Recipient state) -> [ Events.InvoiceEmailed data ] | Fold.Raised _ -> [] | Fold.Initial -> failwith "Invoice not found" | Fold.Finalized _ -> failwith "Invoice is finalized" let recordPayment (data: Events.Payment) state = match state with | Fold.Raised state when state.Payments |> Set.contains data.PaymentId -> [] | Fold.Raised _ -> [ Events.PaymentReceived data ] | Fold.Finalized _ -> failwith "Invoice is finalized" | Fold.Initial -> failwith "Invoice not found" let finalize state = match state with | Fold.Finalized _ -> [] | Fold.Raised _ -> [ Events.InvoiceFinalized ] | Fold.Initial -> failwith "Invoice not found"</code></pre>Testing</h1> Everything we've written so far is pure and easily testable. For an exceptional testing experience, I recommend using FsCheck</code>, FsCheck.Xunit</code>, and Unquote</code>. An important principle when testing event-sourced applications is to not assert against the state of a decider. Doing so leads to brittle tests and hampers your ability to evolve the state as time goes on. It is generally advisable to write tests in the form of Given these events have occured When I interpret this command Then I expect these new events </blockquote> I commonly write an operator (=>)</code> to encapsulate this such that the tests read as previous events => command = new events</code></pre>module Tests open Invoice open Swensen.Unquote open FsCheck.Xunit open FsCodec.Core [<Property>] let ``The event codec round-trips cleanly`` event = let encoded = Events.codec.Encode((), event) let saved = TimelineEvent.Create(0L, encoded.EventType, encoded.Data) let decoded = Events.codec.TryDecode(saved) test <@ ValueSome event = decoded @> let (=>) events interpret = Fold.fold Fold.initial events |> interpret open Events [<Property>] let ``Raising an invoice`` data = test <@ [] => Decisions.raiseInvoice data = [ InvoiceRaised data ] @> // test the idempotency test <@ [ InvoiceRaised data ] => Decisions.raiseInvoice data = [] @> // A finalized invoice will throw raises <@ [ InvoiceRaised data; InvoiceFinalized ] => Decisions.raiseInvoice data @> [<Property>] let ``Recording payments`` raised data = raises <@ [] => Decisions.recordPayment data @> test <@ [ InvoiceRaised raised ] => Decisions.recordPayment data = [ PaymentReceived data ] @> test <@ [ InvoiceRaised raised; PaymentReceived data ] => Decisions.recordPayment data = [] @> raises <@ [ InvoiceRaised raised; InvoiceFinalized ] => Decisions.recordPayment data @> [<Property>] let ``Recording email receipts`` raised data = raises <@ [] => Decisions.recordEmailReceipt data @> test <@ [ InvoiceRaised raised ] => Decisions.recordEmailReceipt data = [ InvoiceEmailed data ] @> test <@ [ InvoiceRaised raised; InvoiceEmailed data ] => Decisions.recordEmailReceipt data = [] @> raises <@ [ InvoiceRaised raised; InvoiceFinalized ] => Decisions.recordEmailReceipt data @> [<Property>] let ``Finalizing`` raised = raises <@ [] => Decisions.finalize @> test <@ [ InvoiceRaised raised ] => Decisions.finalize = [ InvoiceFinalized ] @> test <@ [ InvoiceRaised raised; InvoiceFinalized ] => Decisions.finalize = [] @></code></pre>Identity</h1> It is important to note that we have not mentioned identity until this point. There is no InvoiceId</code> on any of the events! The reason for this is that the aggregate should not be concerned with its own identity. Identity in the Equinox programming model should be considered an infrastructural routing concern. In an event-sourced system, we store the events in streams, and these streams have names of the format {Category}-{streamId}</code>. The identity of the aggregate lives exclusively within the stream name. Events without identity may sound strange, but it does make sense. A functional programming idiom is to "make illegal states unrepresentable." Imagine for a second a stream with these events: StreamName: Invoice-1234 1: InvoiceRaised { InvoiceId = 5678 }</code></pre> The above stream is an absurdity! To make the illegal state unrepresentable, we must apply the DRY principle. Every piece of knowledge must have a single, unambiguous, authoritative representation within a system. </blockquote> That single, unambiguous, authoritative representation is the stream name. Treating identity this way has numerous benefits. Imagine if you later wanted to run a multi-tenanted version of your system. You could spin up an event store per tenant or include the tenant's ID in the stream name so they can all share one database. Either way, we would not force the tenant's ID on any event, and the domain logic and schema remain unchanged. Though identity exists exclusively in the stream name, we would like to avoid passing around unbranded string</code>s and Guid</code>s. To that end, it is common practice to use FSharp.UMX</code> to create a type-safe, branded identifier type. open FSharp.UMX open System type InvoiceId = Guid<invoiceId> and [<Measure>] invoiceId module InvoiceId = let inline ofGuid (g: Guid) : InvoiceId = %g let inline parse (s: string) = Guid.Parse s |> ofGuid let inline toGuid (id: InvoiceId) : Guid = %id // We choose the dashless N format to make the distinct parts of the stream's ID // easier for humans to read let inline toString (id: InvoiceId) = (toGuid id).ToString("N")</code></pre> Equinox exposes a helper to create well-formed stream IDs that, when used with branded identifiers, can ensure we don't resolve the wrong stream at runtime. [<Literal>] let Category = "Invoice" let streamId = Equinox.StreamId.gen InvoiceId.toString // InvoiceId -> StreamId // The example above of adding a tenant to the stream id would look like so: // let streamId = Equinox.StreamId.gen2 TenantId.toString InvoiceId.toString</code></pre>The Service</h1> To recap. We've created an Events</code> module defining the events in play and their storage format.</li> We've created a Fold</code> representing the state and how it evolves in response to events.</li> We've created a Decisions</code> module exposing the actions we can take on a given invoice.</li> We've written tests that combine all three into a cohesive whole.</li> We've created a branded InvoiceId</code> type.</li> We've created a streamId</code> helper and defined the Category</code>.</li> </ul> One way to expose the behaviour we've programmed to the rest of the application would be for consumers to wire it up, similar to how we did in the tests. That would ultimately be a bad idea. Alternatively, we can represent the operations relevant to this aggregate as a cohesive Domain Service. The convention in equinox is to call this type Service</code>. type Service internal (resolve: InvoiceId -> Equinox.Decider<Events.Event, Fold.State>) = member _.Raise(id, data) = let decider = resolve id decider.Transact(Decisions.raiseInvoice data) member _.RecordEmailReceipt(id, data) = let decider = resolve id decider.Transact(Decisions.recordEmailReceipt data) member _.RecordPayment(id, data) = let decider = resolve id decider.Transact(Decisions.recordPayment data) member _.Finalize(id) = let decider = resolve id decider.Transact(Decisions.finalize)</code></pre> There are a couple of things to call out here. First, we've made the service's constructor internal</code> because we'll expose it via a factory later. Second, this is our first encounter with Equinox's Decider concept. This concept encapsulates the retrieving of events, their fold, and writing to storage. The main API is Transact</code>, which performs the actions necessary to get the current state of the aggregate, calls the supplied function, and appends the resulting events to the underlying storage. It does this with multiple layers of retries and can, in addition, do caching and snapshotting transparently. A simplified version of what Transact does would look something like this: let! version, events = store.ReadStream(streamName) let newEvents = events |> Seq.choose tryDecode |> fold initial |> decide do! store.AppendEvents(streamName, newEvents |> Seq.map encode, version)</code></pre> There's a second API called Query</code>. This method will load the current state, call the supplied transformation function and return the result. It is considered a bad idea to expose anything inside the Fold</code> module to the outside. Therefore, for querying purposes, we'll add an InvoiceModel</code> type. type InvoiceModel = { InvoiceNumber: int Amount: decimal Payer: string EmailedTo: string[] Finalized: bool } module InvoiceModel = let fromState finalized (state: Fold.InvoiceState) = { InvoiceNumber = state.InvoiceNumber Amount = state.Amount Payer = state.Payer EmailedTo = state.EmailedTo |> Set.toArray Finalized = finalized } module Queries = let summary = function | Fold.Initial -> None | Fold.Raised invoice -> Some(InvoiceModel.fromState false invoice) | Fold.Finalized invoice -> Some(InvoiceModel.fromState true invoice)</code></pre> With this in place, we can update our service to expose the current state of the aggregate. type Service internal (resolve: InvoiceId -> Equinox.Decider<Events.Event, Fold.State>) = member _.Raise(id, data) = let decider = resolve id decider.Transact(Decisions.raiseInvoice data) member _.RecordEmailReceipt(id, data) = let decider = resolve id decider.Transact(Decisions.recordEmailReceipt data) member _.RecordPayment(id, data) = let decider = resolve id decider.Transact(Decisions.recordPayment data) member _.Finalize(id) = let decider = resolve id decider.Transact(Decisions.finalize) member _.ReadInvoice(id) = let decider = resolve id decider.Query(Queries.summary)</code></pre> Because of the aforementioned internal constructor, we'll need to create a factory to expose our service to the outside. let create resolve = Service(streamId >> resolve Category)</code></pre> This code looks confusing at first glance, so I think it's worth spelling out what's going on. The create</code> function receives a resolve: string -> StreamId -> Decider<_, _></code> where the first argument is the Category</li> The Service expects a resolve</code> function of type InvoiceId -> Decider<_, _></code></li> </ol> To get from the first to the second type, we must create a third function let resolveInvoiceDecider resolve invoiceId = let id = streamId invoiceId resolve Category id // this is the same as let resolveInvoiceDecider resolve invoiceId = streamId invoiceId |> resolve Category // which in turn is the same as let resolveInvoiceDecider resolve = streamId >> resolve Category // we could use it as such let create resolve = Service(resolveInvoiceDecider resolve) // but the preference is to inline it let create resolve = Service(streamId >> resolve Category)</code></pre>The API</h1> To use the Service</code>, we'll finally need to wire it up to one of Equinox's many available stores</a>. For this illustration, We'll use Equinox.MessageDb</code> as the backing store. module Program open System open Equinox.MessageDb open Serilog module Environment = let tryGetEnv = Environment.GetEnvironmentVariable >> Option.ofObj let log = LoggerConfiguration().WriteTo.Console().CreateLogger() let cache = Equinox.Cache("test", sizeMb = 50) let defaultConnString = "Host=localhost; Database=message_store; Username=message_store" let writeUrl = Environment.tryGetEnv "MESSAGE_DB_URL" |> Option.defaultValue defaultConnString let readUrl = Environment.tryGetEnv "MESSAGE_DB_REPLICA_URL" |> Option.defaultValue writeUrl let connection = MessageDbConnector(writeUrl, readUrl).Establish() let context = MessageDbContext(connection) let caching = CachingStrategy.SlidingWindow(cache, TimeSpan.FromMinutes(20)) let service = MessageDbCategory(context, Invoice.Events.codec, Invoice.Fold.fold, Invoice.Fold.initial, caching) |> Equinox.Decider.resolve log |> Invoice.create</code></pre> With the service in place, we can finally expose it over the wire. To achieve this, we'll use a Minimal API. open Microsoft.AspNetCore.Builder open Microsoft.Extensions.Hosting let builder = WebApplication.CreateBuilder() let app = builder.Build() let raiseInvoice body = task { let id = Guid.NewGuid() |> Invoice.InvoiceId.ofGuid do! service.Raise(id, body) return id } app.MapPost("/", Func<_, _>(raiseInvoice)) |> ignore let finalizeInvoice id = task { do! service.Finalize(id) return "OK" } app.MapPost("/{id}/finalize", Func<_, _>(finalizeInvoice)) |> ignore let recordPayment id payment = task { do! service.RecordPayment(id, payment) return "OK" } app.MapPost("/{id}/record-payment", Func<_, _, _>(recordPayment)) |> ignore let readInvoice id = task { return! service.ReadInvoice(id) } app.MapGet("/{id}", Func<_, _>(readInvoice)) |> ignore app.Run()</code></pre> You should now be able to run the API $ curl -XPOST localhost:5244/ -H 'Content-Type: application/json' --data '{"InvoiceNumber": 1, "Payer": "1", "amount": 1230}' "932c5ca2-3870-468d-85c9-5e5f406d5c7d"⏎ $ curl localhost:5244/932c5ca2-3870-468d-85c9-5e5f406d5c7d {"invoiceNumber":1,"amount":1230,"payer":"1","emailedTo":[],"finalized":false} $ curl -XPOST localhost:5244/932c5ca2-3870-468d-85c9-5e5f406d5c7d/finalize OK $ curl localhost:5244/f3bec945-2cbd-4a57-84fa-16481d394490 {"amount":1230,"invoiceNumber":1,"emailedTo":[],"amountPaid":0,"finalized":true}</code></pre>Conclusion</h1> We've reached the end of our journey. The programming model described in this article is one with a heavy emphasis on composition. We compose larger behaviours from smaller ones. I hope that through this post, I've demonstrated its merits. Part two of this series will focus on Reactions. We'll set up a reactor that, when an invoice is raised, will reserve a unique invoice number for it and another reactor that, when an invoice is raised and numbered, will send it to the payer via email and record the receipt. If you'd like to see the code in a runnable form, I've pushed it to a GitHub repository</a>.

The Tyranny of Constructors

Unknown — Sun, 24 Jul 2022 00:00:00 +0000

The tyranny of constructors is what happens when you create collaborators inside object constructors.

class UserRepository { constructor(connectionString: string) { this.pool = new Pool({connectionString}) } async getAllUsers() { try { const client = await this.pool.connect() const result = await client.query(`select * from users`) return result.rows.map(User.ofDatabaseRow) } finally { client.release() } } }</code></pre> This class has too many responsibilities. It is responsible for: Constructing and managing a database pool</li> Managing a connection from the pool</li> Issuing the right query to the database connection</li> </ol> In reality it should only be responsible for the last item. Everything else is a distraction for the class which makes it less testable, and more error prone. let's see what it looks like when we relieve it of these responsibilities Constructing and managing a pool</h1> When we create collaborators inside our constructor we sacrifice a lot. We can no longer substitute the pool for a different object, we're locked to a specific concrete implementation of the pool, etc. class UserRepository { constructor(private readonly pool: Pool) {} async getAllUsers() { try { const client = await this.pool.connect() const result = await client.query(`select * from users`) return result.rows.map(User.ofDatabaseRow) } finally { client.release() } } }</code></pre> With this change we can now construct our pool as a singleton for our application. This in turn means we can share that pool across objects. Our startup file might now look like: export async function main() { const config = readConfig() const pool = new Pool(config.pool) const userService = new UserRepository(pool) const todoService = new TodoService(pool) // ... app.start() }</code></pre>Managing a client from the pool</h1> The logic of getting a client connection with pool.connect</code> and subsequently releasing it after use with client.release</code> is something we'll likely want to do in a number of places. It really deserves its own object. class UserRepository { constructor(private readonly connection: IConnection) {} async getAllUsers() { const rows = await this.connection.query(`select * from users`) return rows.map(User.ofDatabaseRow) } } interface IConnection { query(text: string, values?: any[]): Promise<any[]> } class Connection implements IConnection { constructor(private readonly pool: Pool) {} async query(text: string, values?: any[]) { try { const client = await this.pool.connect() const result = await client.query(text, values) return result.rows } finally { client.release() } } }</code></pre> Where we used to have one object we now have two, and each object has a more defined responsibility. Takeaway</h1> Constructing collaborators in constructors is a fairly big code smell. Do not mix object graph construction with your application logic. Addendum</h1> An additional rule that is good to follow is "Every object passed into a constructor should be fully initialized." </blockquote> async function configure() { const config = readConfig() const client = new Client(config.client) await client.initialize() const connection = new Connection(client) const userService = new UserService(connection) // ... }</code></pre>

Using EventStore with NestJS

Unknown — Mon, 12 Oct 2020 00:00:00 +0000

A while ago I wrote a blog post about using EventStore with NestJS. I've regretted that post for a while because the pattern I advocated for was overly complex and introduced abstractions for no good reason. I ended up de-listing that post but I'm sure you'll be able to find it if you look. This is meant as an updated version.

Using EventStore with NestJS

Unknown — Mon, 12 Oct 2020 00:00:00 +0000

Since writing this post my views have changed a lot, I describe my current way of using EventStore with NestJS in a v2 of this post here</a>

Event sourcing is a pattern that gained traction recently. It can be boiled down to:

Every change to application state is an event. Instead of storing current state, state is stored a sequence of events </blockquote>

As software developers, we've been trained to think in terms of current state since the 1960's. It makes sense because memory was very expensive back then. Adding a megabyte of storage was a $1,000 decision, so we got good at optimizing storage. Storage simply isn't a major issue anymore and keeping a ledger of events represents a more natural way to think about systems.

NestJS</a> is a relatively new backend javascript framework. It builds on a solid foundation of patterns that enable you to write well factored code that's easy to refactor. It provides modules for working with common libraries like TypeORM</a>, Sequelize</a>, Passport</a>, and more. On top of that there's a hidden gem of a package called @nestjs/cqrs</code></a> that provides a lightweight CQRS framework. In this post, we're going to look at the command side of the CQRS equation usingEventStore</a> to persist our events.

The high level conceptual overview of what we want to achieve is this:


  
  Figure 1. Command Architecture</span>
</div>
The NestJS CQRS module has utilities to help us with Commands</code>, CommandHandlers</code>, and the domain concept of AggregateRoots</code>. We'll be using my pacakge @nordfjord/nestjs-cqrs-es</code> to provide the Repository layer.</p>
Getting Started</h1>
Let's start by creating a new Nest project with some wiring</p>
$</span> npx @nestjs/cli new cqrs-app</span></span>
$</span> cd cqrs-app</span></span>
$</span> yarn add @nestjs/cqrs @nordfjord/nestjs-cqrs-es @nestjs/cli bcrypt</span></span>
$</span> yarn nest g module user</span></span></code></pre>
Now that we have the essential boilerplate up, let's start by wiring up the event store</p>
// app.module.ts</span></span>
@</span>Module</span>({</span></span>
  imports</span>: [</span></span>
    CqrsModule</span>,</span></span>
    EventStoreModule</span>.</span>forRoot</span>({</span></span>
      connection</span>: {</span></span>
        defaultUserCredentials</span>: {</span> username</span>:</span> 'admin'</span>,</span> password</span>:</span> 'changeit'</span> },</span></span>
      },</span></span>
      tcpEndpoint</span>:</span> 'tcp://127.0.0.1:1113'</span>,</span></span>
    }),</span></span>
    UserModule</span>,</span></span>
  ],</span></span>
  controllers</span>: [</span>AppController</span>],</span></span>
  providers</span>: [</span>AppService</span>],</span></span>
})</span></span>
export class</span> AppModule</span> implements</span> OnModuleInit</span> {</span></span>
  constructor</span>(</span></span>
    private readonly</span> eventStore</span>:</span> EventStore</span>,</span></span>
    private readonly</span> eventBus</span>:</span> EventBus</span><</span>Event</span>>,</span></span>
  ) {}</span></span>
</span>
  async</span> onModuleInit</span>() {</span></span>
    this</span>.</span>eventBus</span>.</span>publisher</span> =</span> this</span>.</span>eventStore</span></span>
  }</span></span>
}</span></span></code></pre>
Here we're adding a tcp connection to eventstore on localhost. If you don't have eventstore already running on your machine, here's</a> a docker-compose file you can use.</p>
The User Module</h1>
Next up we can start writing our user module. We begin by creating a command.
The command should create a user, with an email and a password.</p>
// user/dto/register-user.dto.ts</span></span>
export class</span> RegisterUserDto</span> {</span></span>
  email</span>:</span> string</span></span>
  password</span>:</span> string</span></span>
}</span></span></code></pre>// user/command/impl/register-user.command.ts</span></span>
export class</span> RegisterUser</span> {</span></span>
  constructor</span>(</span>public readonly</span> data</span>:</span> RegisterUserDto</span>) {}</span></span>
}</span></span></code></pre>
Now that we have our command defined we need a way to handle it.</p>
// user/command/handler/register-user.handler.ts</span></span>
@</span>CommandHandler</span>(</span>RegisterUser</span>)</span></span>
export class</span> RegisterUserHandler</span> implements</span> ICommandHandler</span><</span>RegisterUser</span>> {</span></span>
  constructor</span>() {}</span></span>
</span>
  async</span> execute</span>(</span>command</span>:</span> RegisterUser</span>) {}</span></span>
}</span></span></code></pre>
The job of a command handler according to our diagram above</a> is to pass data on to the domain layer.
Since we don't have a domain layer yet, we should pause development of the handler and create the User AggregateRoot first.</p>
User Aggregate Root</h1>
Let's start by defining what on earth an Aggregate Root is.</p>

  Aggregate</dt>
  
Constituting or amounting to a whole; total.</dd>
  
Root</dt>
  
Something that is an origin or source</dd>
</dl>
An aggregate root guarantees the consistency of changes being made within
the aggregate by forbidding external objects from holding references to its members.</p>
For example when driving a car, you are just driving a car.
You're not moving the wheels in circular motion to move forward. You're just driving a car!</em></p>
Our User aggregate root has the job of enforcing our domain logic. For instance, a user cannot register twice.</p>
// user/model/user.ts</span></span>
</span>
export class</span> User</span> extends</span> AggregateRoot</span><</span>Event</span>> {</span></span>
  private</span> isRegistered</span> =</span> false</span></span>
  private</span> email</span>:</span> string</span></span>
  private</span> passwordHash</span>:</span> string</span></span>
  constructor</span>(</span>private</span> id</span>:</span> string</span>) {</span></span>
    super</span>()</span></span>
  }</span></span>
</span>
  async</span> register</span>(</span>email</span>:</span> string</span>,</span> password</span>:</span> string</span>) {</span></span>
    if</span> (</span>this</span>.</span>isRegistered</span>)</span> throw new</span> ConflictException</span>()</span></span>
</span>
    this</span>.</span>apply</span>(</span></span>
      new</span> UserRegistered</span>({</span></span>
        email</span>,</span></span>
        passwordHash</span>:</span> await</span> hash</span>(</span>password</span>,</span> await</span> genSalt</span>()),</span></span>
      }),</span></span>
    )</span></span>
  }</span></span>
</span>
  onUserRegistered</span>(</span>event</span>:</span> UserRegistered</span>) {</span></span>
    this</span>.</span>isRegistered</span> =</span> true</span></span>
    this</span>.</span>email</span> =</span> event</span>.</span>data</span>.</span>email</span></span>
    this</span>.</span>passwordHash</span> =</span> event</span>.</span>data</span>.</span>passwordHash</span></span>
  }</span></span>
}</span></span></code></pre>
NestJS aggregate roots will automatically call on${EventType}</code> when we apply events. This is useful when hydrating our aggregates.</p>
With this AggregateRoot in place it's clear that the CommandHandler</code> will instantiate the User AggregateRoot, and call the register</code> method.
The register</code> method will then apply a UserRegistered</code> event or throw an exception.</p>
Let's create the UserRegistered</code> event.</p>
// user/dto/user-registered.dto.ts</span></span>
export class</span> UserRegisteredDto</span> {</span></span>
  email</span>:</span> string</span></span>
  passwordHash</span>:</span> string</span></span>
}</span></span></code></pre>// user/events/user-registered.event.ts</span></span>
export class</span> UserRegistered</span> extends</span> Event</span><</span>UserRegisteredDto</span>> {</span></span>
  constructor</span>(</span>data</span>:</span> UserRegisteredDto</span>) {</span></span>
    super</span>(</span>`User-</span>${</span>data</span>.</span>email</span>}</span>`</span>,</span> data</span>,</span> ExpectedVersion</span>.</span>noStream</span>)</span></span>
  }</span></span>
}</span></span></code></pre>
The Event</code> constructor takes a few arguments.</p>
Argument</th> Type</th> Description</th></tr></thead>

eventStreamId</td> string</code></td> The stream id the event belongs to</td></tr>
data</td> any</code></td> The payload of the event</td></tr>
expectedVersion</td> number</code></td> For optimistic concurrency checks. Here we're using noStream</code> as we don't expect the stream to exist when the user registers.</td></tr>
eventId</td> UUID</code></td> Id of the event, auto generated uuid v4 by default</td></tr>
correlationId</td> UUID</code></td> CorrelationId of the event</td></tr>
causationId</td> UUID</code></td> CausationId of the event</td></tr>
</tbody></table>
Now that our event is defined, we wire up our User Module.</p>
// user/user.module.ts</span></span>
@</span>Module</span>({</span></span>
  imports</span>: [</span></span>
    CqrsModule</span>,</span></span>
    EventStoreModule</span>.</span>forFeature</span>([</span>User</span>], {</span></span>
      UserRegistered</span>:</span> event</span> => new</span> UserRegistered</span>(</span>event</span>.</span>data</span>),</span></span>
    }),</span></span>
  ],</span></span>
  providers</span>: [</span>RegisterUserHandler</span>],</span></span>
})</span></span>
export class</span> UserModule</span> {}</span></span></code></pre>
The EventStoreModule.forFeature</code> takes 2 arguments.</p>
Argument</th> Type</th> Description</th></tr></thead>

aggregateRoots</td> AggregateRootConstructor[]</code></td> A list of aggregate roots that will be made available as repositories</td></tr>
eventTransformers</td> Record<string, (event: EventStoreEvent)=> Event></code></td> A map of transfomers to map event store events to NestJS events</td></tr>
</tbody></table>
Now when reading events from the event store they'll be transformed into classes that NestJS can deal with.</p>
Before returning to the command handler, this is a summary of what we've done.</p>

Commands are executed by Command Handlers</li>
Command Handlers instantiate AggregateRoots</li>
AggregateRoots apply Events</li>
</ul>
Command Handler</h1>
@</span>CommandHandler</span>(</span>RegisterUser</span>)</span></span>
export class</span> RegisterUserHandler</span> implements</span> ICommandHandler</span><</span>RegisterUser</span>> {</span></span>
  constructor</span>(</span></span>
    @</span>InjectAggregateRepository</span>(</span>User</span>)</span></span>
    private readonly</span> userRepository</span>:</span> AggregateRepository</span><</span>User</span>>,</span></span>
  ) {}</span></span>
</span>
  async</span> execute</span>(</span>command</span>:</span> RegisterUser</span>) {</span></span>
    const</span> user</span> =</span> await</span> this</span>.</span>userRepository</span>.</span>findOne</span>(</span>command</span>.</span>data</span>.</span>email</span>)</span></span>
</span>
    await</span> user</span>.</span>register</span>(</span>command</span>.</span>data</span>.</span>email</span>,</span> command</span>.</span>data</span>.</span>password</span>)</span></span>
</span>
    await</span> this</span>.</span>userRepository</span>.</span>save</span>(</span>user</span>)</span></span>
</span>
    return</span> {</span> success</span>:</span> true</span> }</span></span>
  }</span></span>
}</span></span></code></pre>
@InjectAggregateRepository(User)</code> tells nest to inject the provider for the User AggregateRepository.</p>
The execute method calls userRepository.findOne(id)</code>. Behind the scenes findOne</code> fetches all
events belonging to the user with that id and applies them to a newly instantiated User AggregateRoot.</p>
then calling user.register</code> applies a UserRegistered event or throws.</p>
If the register</code> call didn't throw userRepository.save(user)</code> will get all the uncommited events from the aggregate and persist them to the event store.</p>
To finish this up we will create a NestJS controller to invoke the command handler.</p>
$</span> yarn nest g controller user</span></span></code></pre>// user/user.controller.ts</span></span>
@</span>Controller</span>(</span>'user'</span>)</span></span>
export class</span> UserController</span> {</span></span>
  constructor</span>(</span>private readonly</span> commandBus</span>:</span> CommandBus</span>) {}</span></span>
</span>
  @</span>Post</span>(</span>'register'</span>)</span></span>
  async</span> register</span>(@</span>Body</span>()</span> data</span>:</span> RegisterUserDto</span>) {</span></span>
    return await</span> this</span>.</span>commandBus</span>.</span>execute</span>(</span>new</span> RegisterUser</span>(</span>data</span>))</span></span>
  }</span></span>
}</span></span></code></pre>
Now we can run our code and test it out.</p>
$</span> yarn start:dev</span></span></code></pre>
In another terminal let's use curl to try it out</p>
curl</span> -X</span> POST</span> \</span></span>
-H</span> 'Content-Type: application/json'</span> \</span></span>
-H</span> 'Accept: application/json'</span> \</span></span>
--data</span> '{"email": "test@example.com", "password": "12345"}'</span> \</span></span>
http://localhost:3000/user/register</span></span></code></pre>
We should see a</p>
{</span> "success"</span>:</span> true</span> }</span></span></code></pre>
If we then open our browser at
http://localhost:2113/web/index.html#/streams/User-test@example.com</a>,
we should see the event having been persisted to EventStoreDB.</p>
If we try issuing the same request again though, we should see</p>
{</span> "statusCode"</span>:</span> 409</span>,</span> "message"</span>:</span> "Conflict"</span> }</span></span></code></pre>Conclusion</h1>
In this post we've created a Command Side module in NestJS that can register users. You can view the full example on GitHub</a>.</p>
The Query side is left as an excercise to the reader.</p>


Thoughs on Async Redux
Unknown — Mon, 31 Aug 2020 00:00:00 +0000
Redux has been a go-to state management solution ever since it entered the mainstream. It takes a solid
functional programming approach to the Flux Architecture. It uses a reducer and action objects to maintain state.</p>
Although Redux is fantastic for local state, the core library
does not provide a way to handle asynchronicity.</p>
Many options exist, and I will compare three of them.</p>
redux-thunk</a>,
redux-observable</a>,
and redux-saga</a></p>
Redux Thunk</h1>
Redux thunk is the minimum viable async middleware for redux. It
achieves its goals using (unsurprisingly) thunks, which are functions
returned from functions.
When dispatched, they look identical to regular action creators.</p>
// fetchUser could be an action creator</span></span>
// or a thunk, we don't care</span></span>
dispatch</span>(</span>fetchUser</span>())</span></span></code></pre>
The basic example of fetching a user from an api would look like this:</p>
function</span> fetchUser</span>() {</span></span>
  return async</span> dispatch</span> =></span> {</span></span>
    dispatch</span>(</span>fetchUserStart</span>())</span></span>
    try</span> {</span></span>
      const</span> user</span> =</span> await</span> fetch</span>(</span>'/api/user'</span>).</span>then</span>(</span>x</span> =></span> x</span>.</span>json</span>())</span></span>
      dispatch</span>(</span>fetchUserSuccess</span>(</span>user</span>))</span></span>
    }</span> catch</span> (</span>error</span>) {</span></span>
      dispatch</span>(</span>fetchUserError</span>(</span>error</span>))</span></span>
    }</span></span>
  }</span></span>
}</span></span></code></pre>
This is great for most scenarios. It feels natural. In my opinion, redux-thunk should be preferred in 90% of cases. When I'm writing a redux application, I tend to keep redux-thunk around even if I adopt another async middleware later.</p>
While redux-thunk is excellent at what it does well, it's pretty terrible where it's lacking. Things like debouncing inputs, canceling current requests, and action sequences are practically impossible to implement in a straight forward manner using thunks.</p>
That's where the other middlewares come in!</p>
Redux Observable</h1>
It was while writing redux-observable code that I decided to make this post. RxJS Observables are immensely powerful for async. Redux-observables brings us this power in the form of Epics.</p>
An epic is a mapping from an action to an action. In type terms:</p>
type</span> AppEpic</span> =</span> (</span></span>
  action$</span>:</span> Observable</span><</span>Action</span>>,</span></span>
  state$</span>:</span> Observable</span><</span>AppState</span>>,</span></span>
)</span> =></span> Observable</span><</span>Action</span>></span></span></code></pre>
This type might look a bit weird, but let's consider how to do the basic async example using observables.</p>
const</span> fetchUserEpic</span>:</span> AppEpic</span> =</span> action$</span> =></span></span>
  action$</span>.</span>pipe</span>(</span></span>
    filter</span>(</span>fetchUserStart</span>.</span>match</span>),</span></span>
    switchMap</span>(</span>action</span> =></span></span>
      fromPromise</span>(</span>fetch</span>(</span>'/api/user'</span>).</span>then</span>(</span>x</span> =></span> x</span>.</span>json</span>())).</span>pipe</span>(</span></span>
        map</span>(</span>payload</span> =></span> fetchUserFulfilled</span>(</span>payload</span>)),</span></span>
        catchError</span>(</span>error</span> =></span> of</span>(</span>fetchUserError</span>(</span>error</span>))),</span></span>
      ),</span></span>
    ),</span></span>
  )</span></span></code></pre>
This is more complicated than the redux-thunk example, in order to understand what's going on you
need a working knowledge of Observables, what the operators switchMap</code>, map</code>, filter</code>, and catchError</code> do.
Not to mention needing to know what an operator even is!</p>
Compared to observables, thunks require less knowledge to use. But as discussed before, thunks don't deal well with debouncing inputs, canceling current requests, and action sequences.</p>
Imagine a search box where as the user types, search results are shown.</p>
This has some important constraints:</p>

we don't want to send a request on every keystroke (that would choke the server)</li>
we want to cancel in progress requests on a new keystroke because the one in progress is no longer relevant</li>
we need to make sure that the last request corresponds to the last keystroke, otherwise we might display stale data</li>
</ol>
Imagine this component:</p>
export function</span> RepoFetcher</span>() {</span></span>
  const</span> dispatch</span> =</span> useDispatch</span>()</span></span>
  const</span> repos</span> =</span> useSelector</span>(</span>x</span> =></span> x</span>.</span>repos</span>)</span></span>
  return</span> (</span></span>
    <></span></span>
      <</span>input</span></span>
        type</span>=</span>"text"</span></span>
        onChange</span>=</span>{</span>ev</span> =></span> dispatch</span>(</span>fetchReposInput</span>(</span>ev</span>.</span>currentTarget</span>.</span>value</span>))</span>}</span></span>
      /></span></span>
      <</span>h3</span>></span></span>
        {</span>repos</span>.</span>error</span> ?</span> 'Error!'</span> :</span> repos</span>.</span>isLoading</span> ?</span> 'Loading...'</span> :</span> 'Results'</span>}{</span>' '</span>}</span></span>
      </</span>h3</span>></span></span>
      <</span>ul</span>></span></span>
        {</span>repos</span>.</span>repos</span>.</span>map</span>(</span>x</span> =></span> (</span></span>
          <</span>li</span> key</span>=</span>{</span>x</span>.</span>id</span>}</span>></span></span>
            <</span>a</span> href</span>=</span>{</span>x</span>.</span>html_url</span>}</span>></span>{</span>x</span>.</span>full_name</span>}</span></</span>a</span>></span></span>
          </</span>li</span>></span></span>
        ))</span>}</span></span>
      </</span>ul</span>></span></span>
    </></span></span>
  )</span></span>
}</span></span></code></pre>
If we used a thunk to handle the fetchReposInput action, it might look like this:</p>
const</span> fetchReposInput</span> =</span> input</span> => async</span> dispatch</span> =></span> {</span></span>
  dispatch</span>(</span>fetchReposStart</span>())</span></span>
  try</span> {</span></span>
    const</span> repos</span> =</span> await</span> fetch</span>(</span></span>
      'https://api.github.com/search/repositories?per_page=10&q='</span> +</span></span>
        encodeURIComponent</span>(</span>input</span>),</span></span>
    ).</span>then</span>(</span>x</span> =></span> x</span>.</span>json</span>())</span></span>
    dispatch</span>(</span>fetchReposSuccess</span>(</span>repos</span>))</span></span>
  }</span> catch</span> (</span>error</span>) {</span></span>
    dispatch</span>(</span>fetchReposError</span>(</span>error</span>))</span></span>
  }</span></span>
}</span></span></code></pre>
We have broken all 3 of the constraints with this code.</p>

Every keystroke triggers a request</li>
The old fetch is still alive when a new keystroke arrives</li>
There's no correlation between time of keystroke and time of response</li>
</ol>
The errors these constraint violations cause can be hard to track down as well.</p>
Using observables, we can write code that fits within the constraints fairly easily</p>
const</span> searchRepos</span> =</span> q</span> =></span></span>
  // utility exported by rxjs/ajax</span></span>
  // it returns an Observable<JSON></span></span>
  // and uses XMLHttpRequest under the hood</span></span>
  // to facilitate cancellations</span></span>
  ajax</span>.</span>getJSON</span>(</span></span>
    `https://api.github.com/search/repositories?per_page=10&q=</span>${</span>encodeURIComponent</span>(</span></span>
      q</span>,</span></span>
    )</span>}</span>`</span>,</span></span>
  )</span></span>
const</span> fetchReposEpic</span> =</span> action$</span> =></span></span>
  action$</span>.</span>pipe</span>(</span></span>
    filter</span>(</span>fetchReposInput</span>.</span>match</span>),</span></span>
    debounceTime</span>(</span>300</span>),</span></span>
    switchMap</span>(</span>action</span> =></span></span>
      of</span>(</span>fetchReposStart</span>()).</span>pipe</span>(</span></span>
        concat</span>(</span></span>
          searchRepos</span>(</span>action</span>.</span>payload</span>).</span>pipe</span>(</span></span>
            map</span>(</span>payload</span> =></span> fetchReposSuccess</span>(</span>payload</span>.</span>items</span>)),</span></span>
            catchError</span>(</span>error</span> =></span> of</span>(</span>fetchReposError</span>(</span>error</span>))),</span></span>
          ),</span></span>
        ),</span></span>
      ),</span></span>
    ),</span></span>
  )</span></span></code></pre>
Let's step through this:</p>

We get every action that's a fetchReposInput action</li>
We debounce by 300ms; this means that we don't continue
the pipe until 300ms have passed since the last action</li>
We switchMap</code>, this is also known as a flatMap</code>, chain</code>, or bind</code> in other languages,
but here we can think of it as going from Observable<Observable<Action>></code> to an Observable<Action></code></li>
In the switchMap we create a new observable that has a fetchReposStart</code> action, and concatenate
the searchRepos</code> request result</li>
</ul>
This means our Epic will return in order:</p>

fetchReposStart()</code></li>
fetchReposSuccess(payload.items)</code> | fetchReposError(error)</code></li>
</ol>
switchMap</code> has properties that help us adhere to our constraints.
When a new input action is dispatched while we're still fetching, it automatically stops subscribing to the current observable and cancels it.</p>
Since we're "just" using RxJS we also gain access to a whole host of operators.</p>

debounceTime</code> for waiting</li>
filter</code> to select actions</li>
concat</code> to append an observable to another</li>
map</code> to transform</li>
catchError</code> to catch errors</li>
</ul>
There are literally over a hundred operators like these. So it's very likely There's an operator for</em> that</em></strong></p>
Thoughts on Redux Observable</h2>
I think observables have some benefits over thunks in cases where</p>

You're doing something more complicated than a set and forget async fetch</li>
You already know observables, or are willing to put in the effort to learn them, and teach your team.</li>
</ol>
Redux Saga</h1>
Redux saga is the final middleware we'll be looking at here.</p>
Redux saga aims to make side effects more natural to manage,
more efficient to execute, better at handling failures, and easy to test.</p>
It does this while also maintaining an imperative syntax.</p>
Let's take a look at how we would implement the observable example using sagas.</p>
function*</span> fetchRepos</span>(</span>action</span>) {</span></span>
  yield</span> delay</span>(</span>300</span>)</span></span>
  yield</span> put</span>(</span>fetchReposStart</span>())</span></span>
  try</span> {</span></span>
    const</span> response</span> =</span> yield</span> call</span>(</span>Api</span>.</span>fetchRepos</span>,</span> action</span>.</span>payload</span>)</span></span>
    yield</span> put</span>(</span>fetchReposSuccess</span>(</span>response</span>.</span>items</span>))</span></span>
  }</span> catch</span> (</span>error</span>) {</span></span>
    yield</span> put</span>(</span>fetchReposError</span>(</span>error</span>))</span></span>
  }</span></span>
}</span></span>
function*</span> watchFetchReposInput</span>() {</span></span>
  yield</span> takeLatest</span>(</span>fetchReposInput</span>.</span>match</span>,</span> fetchRepos</span>)</span></span>
}</span></span></code></pre>
If you squint a bit, the fetchRepos</code> method almost looks familiar. It's the same structure as
the basic async thunk. Swap out put</code> for dispatch</code>, remove the yields, and we're there!
There's some added noise, but in return, we get great benefits.</p>
takeLatest</code> also handles cancelling in progress effects.</p>
A more convoluted example</h2>
For a basic async thunk, you do not need</strong> sagas. Where sagas shine are action sequences, especially with dependent actions.</p>
Imagine a card game, where before you can play a card, a modal should be displayed where
you pick a mana distribution to pay for the card (think two blue, three white).</p>
The sequence of actions would be</p>
      Request Play Card</span></span>
              |</span></span>
        Show Mana Modal</span></span>
          /</span>          \</span></span>
         /</span>            \</span></span>
        /</span>              \</span></span>
Close Mana Modal    Pay Mana</span></span>
                        |</span></span>
                    Play Card</span></span></code></pre>
To be clear this example is not something you need</em> sagas for,
to illustrate let's look at how we would implement this
sequence using observables.</p>
export const</span> payMana</span> =</span> (</span>cost</span>,</span> action$</span>,</span> onPayAction</span>)</span> =></span></span>
  of</span>(</span>manaModalSlice</span>.</span>actions</span>.</span>showModal</span>(</span>cost</span>)).</span>pipe</span>(</span></span>
    concat</span>(</span></span>
      action$</span>.</span>pipe</span>(</span></span>
        takeUntil</span>(</span></span>
          actions$</span>.</span>pipe</span>(</span>filter</span>(</span>manaModalSlice</span>.</span>actions</span>.</span>closeModal</span>.</span>match</span>)),</span></span>
        ),</span></span>
        filter</span>(</span>manaSlice</span>.</span>actions</span>.</span>payMana</span>.</span>match</span>),</span></span>
        mapTo</span>(</span>onPayAction</span>),</span></span>
      ),</span></span>
    ),</span></span>
  )</span></span>
</span>
export const</span> rootEpic</span> =</span> (</span>action$</span>,</span> state$</span>)</span> =></span></span>
  action$</span>.</span>pipe</span>(</span></span>
    filter</span>(</span>requestPlayCard</span>.</span>match</span>),</span></span>
    switchMap</span>(</span>action</span> =></span> {</span></span>
      const</span> id</span> =</span> action</span>.</span>payload</span>.</span>id</span></span>
      const</span> card</span> =</span> cardSelectors</span>.</span>selectById</span>(</span>id</span>)(</span>state$</span>.</span>value</span>)</span></span>
      return</span> payMana</span>(</span></span>
        card</span>.</span>manaCost</span>,</span></span>
        action$</span>,</span></span>
        playerSlice</span>.</span>actions</span>.</span>playCard</span>({</span> id</span> }),</span></span>
      )</span></span>
    }),</span></span>
  )</span></span></code></pre>
This is very declarative. A gripe I've had with redux-observable is just how
unintuitive it is to create dependent action sequences. It always requires a flatMap,
and this amount of code is for an event series with only one branch.</p>
How would we handle this use case with a saga?</p>
function*</span> payMana</span>(</span>cost</span>) {</span></span>
  yield</span> put</span>(</span>manaModalSlice</span>.</span>actions</span>.</span>showModal</span>(</span>cost</span>))</span></span>
  // an infinite while loop is okay, because we know</span></span>
  // that the only way to get out of the modal</span></span>
  // is through the two actions handled in the loop</span></span>
  while</span> (</span>true</span>) {</span></span>
    const</span> action</span> =</span> yield</span> take</span>()</span></span>
    if</span> (</span>manaSlice</span>.</span>actions</span>.</span>payMana</span>.</span>match</span>(</span>action</span>)) {</span></span>
      return</span> true</span></span>
    }</span></span>
    if</span> (</span>manaModalSlice</span>.</span>actions</span>.</span>closeManaModal</span>.</span>match</span>(</span>action</span>)) {</span></span>
      return</span> false</span></span>
    }</span></span>
  }</span></span>
}</span></span>
</span>
function*</span> playCard</span>(</span>action</span>) {</span></span>
  const</span> id</span> =</span> action</span>.</span>payload</span>.</span>id</span></span>
  const</span> card</span> =</span> yield</span> select</span>(</span>cardSelectors</span>.</span>selectById</span>(</span>id</span>))</span></span>
  const</span> isPayed</span> =</span> yield</span> call</span>(</span>getManaPayment</span>,</span> card</span>.</span>manaCost</span>)</span></span>
  if</span> (</span>isPayed</span>) {</span></span>
    yield</span> put</span>(</span>playerSlice</span>.</span>actions</span>.</span>playCard</span>({</span> id</span> }))</span></span>
  }</span></span>
}</span></span>
</span>
function*</span> watchRequestPlayCard</span>() {</span></span>
  yield</span> takeEvery</span>(</span>requestPlayCard</span>.</span>match</span>,</span> playCard</span>)</span></span>
}</span></span></code></pre>
In my opinion, this code is easier to follow than the Observable example.
I can read through the code step by step to get an understanding
of what's going on.</p>

For every requestPlayCard</code> action we run the playCard</code> method.</li>
To play a card we first call getManaPayment</code></li>
getManaPayment</code> dispatches a showModal</code> action and then waits for a closeModal</code> or a payMana</code> action and returns a corresponding boolean</li>
Back in the playCard</code> method, we check whether the mana has been paid and if so we dispatch the playCard</code> action</li>
</ul>
This sort of understanding is harder to come by in the Observable version.
I believe this is because in that example we need an understanding of RxJS operators
to know what's going on.
With sagas, we only require an understanding of JavaScript language primitives.</p>
I believe, redux-saga is to redux-observable what async/await is to Promises.
It's a really great syntax for declaring side effects in an imperative way.
All the heavy lifting is handled by redux-saga: waiting, dispatching, and so on.
We just yield descriptions of what should be done making sagas inherently testable.</p>
Conclusion</h1>
The argument for redux-observable is that it's just RxJS, which is honestly fantastic.
RxJS has been a godsend for reactive programming and async in general. But when it
comes to complex dependent sequences the syntax sagas provide fits better.</p>
I would much rather onboard a newbie to a codebase with sagas than observables.
That being said I have a few rules of thumb to guide me towards the correct async middleware
for a given scenario.</p>

For basic asynchronous set/forget calls, use thunks</li>
To immediately dispatch multiple actions, use thunks</li>
For everything else there're sagas</li>
</ul>
After using both sagas and observables, I'll stick with sagas for now.</p>
If you already know RxJS, and need an async middleware,
I think redux-observable is fantastically expressive.
But I think there're tradeoffs to everything, and with redux-observable
I felt more constrained than with sagas. Furthermore, it was less difficult for me
to explain to others what was going on in a saga than an observable,
which to me, weighs much higher than terse, meaning dense, code.</p>


Thoughts on Testing Components
Unknown — Wed, 22 Jul 2020 00:00:00 +0000
Testing components is a large undertaking. It can be difficult to decide the scope of testing or if something even needs
tesing.</p>
I recently came upon a problem with an occlusion culled list. Occlusion culling is a technique used to increase
performance of long lists and tables. It does so by not rendering the parts of the component that aren't visible on the
user's screen. This also means that fewer DOM nodes are needed.</p>
Occlusion Culling</h1>
A simple occlusion culled list might look like this in code:
{% raw %}</p>
const</span> itemHeight</span> =</span> 31</span></span>
const</span> tableHeight</span> =</span> 312</span></span>
const</span> items</span> =</span> Array</span>.</span>from</span>({</span> length</span>:</span> 5000</span> }).</span>map</span>((</span>_</span>,</span> i</span>)</span> =></span> ({</span></span>
  id</span>:</span> i</span> +</span> 1</span>,</span></span>
  utilization</span>: (</span>i</span> +</span> 1</span>)</span> /</span> 100</span>,</span></span>
}))</span></span>
</span>
export default function</span> OcclusionList</span>() {</span></span>
  const</span> [</span>scrollTop</span>,</span> setScrollTop</span>]</span> =</span> useState</span>(</span>0</span>)</span></span>
  const</span> begin</span> =</span> (</span>scrollTop</span> /</span> itemHeight</span>)</span> |</span> 0</span></span>
  // Add 2 so that the top and bottom of the page are filled with</span></span>
  // next/prev item, not just whitespace if item not in full view</span></span>
  const</span> end</span> =</span> begin</span> +</span> ((</span>tableHeight</span> /</span> itemHeight</span>)</span> |</span> 0</span>)</span> +</span> 2</span></span>
</span>
  const</span> offset</span> =</span> scrollTop</span> %</span> itemHeight</span></span>
</span>
  const</span> visibleItems</span> =</span> items</span>.</span>slice</span>(</span>begin</span>,</span> end</span>)</span></span>
  return</span> (</span></span>
    <</span>div</span></span>
      className</span>=</span>"table"</span></span>
      onScroll</span>=</span>{</span>e</span> =></span> setScrollTop</span>((</span>e</span>.</span>target</span> as</span> HTMLDivElement</span>).</span>scrollTop</span>)</span>}</span></span>
      style</span>=</span>{</span>{</span></span>
        maxHeight</span>:</span> `</span>${</span>tableHeight</span>}</span>px`</span>,</span></span>
        overflowY</span>:</span> 'scroll'</span>,</span></span>
      }</span>}</span></span>
    ></span></span>
      <</span>div</span></span>
        className</span>=</span>"fake-height"</span></span>
        style</span>=</span>{</span>{</span> height</span>:</span> `</span>${</span>items</span>.</span>length</span> *</span> itemHeight</span>}</span>px`</span> }</span>}</span></span>
      ></span></span>
        <</span>ul</span> className</span>=</span>"body"</span> style</span>=</span>{</span>{</span> top</span>:</span> `</span>${</span>scrollTop</span> -</span> offset</span>}</span>px`</span> }</span>}</span>></span></span>
          {</span>visibleItems</span>.</span>map</span>(</span>item</span> =></span> (</span></span>
            <</span>li</span> className</span>=</span>"row"</span> key</span>=</span>{</span>item</span>.</span>id</span>}</span>></span></span>
              <</span>span</span> className</span>=</span>"id"</span>></span>{</span>item</span>.</span>id</span>}</span></</span>span</span>></span></span>
              <</span>span</span> className</span>=</span>"utilization"</span>></span></span>
                {</span>(</span>item</span>.</span>utilization</span> *</span> 100</span>).</span>toFixed</span>(</span>0</span>)</span> +</span> '%'</span>}</span></span>
              </</span>span</span>></span></span>
            </</span>li</span>></span></span>
          ))</span>}</span></span>
        </</span>ul</span>></span></span>
      </</span>div</span>></span></span>
    </</span>div</span>></span></span>
  )</span></span>
}</span></span></code></pre>
{% endraw %}</p>

Takeaways</h1>

Structured logging and tracing aren't very different</li>
OpenTelemetry takes care of a lot of the hard parts of distributed tracing</li>
You can derive logs (and metrics) from traces.</li>
Tracing requires a shift in mindset</li> </ul>

Addendum</h1>

Further "fun" issues</h2>

Thoughs on Async Redux

Thoughts on Testing Components

Nordfjord's blog

Transitioning to OpenTelemetry

The Equinox Programming Model

The Tyranny of Constructors

Takeaway</h1>
Constructing collaborators in constructors is a fairly big code smell. Do not</strong> mix object graph construction with your application logic.</p>

SQL Event Store. Maybe Yes?

SQL Event Store. Maybe Not.

Using EventStore with NestJS

Using EventStore with NestJS

Nordfjord's blog

Transitioning to OpenTelemetry

Takeaways</h1> Structured logging and tracing aren't very different</li> OpenTelemetry takes care of a lot of the hard parts of distributed tracing</li> You can derive logs (and metrics) from traces.</li> Tracing requires a shift in mindset</li> </ul>

The Equinox Programming Model

The Events</h1> In an event-sourced system, a Category can be considered analogous to a class. A key insight of Equinox is that all relevant events for a category can be united as a single Event DU. By convention, we place the Event DU into an Events</code> module.</p>

The Tyranny of Constructors

Takeaway</h1> Constructing collaborators in constructors is a fairly big code smell. Do not</strong> mix object graph construction with your application logic.</p>

SQL Event Store. Maybe Yes?

Terminology</h1> Before we go further it's a good idea to get some terminology out of the way to make sure we're speaking the same language.</p>

So why would I consider NOT using a purpose built event store?</h1> I think you'd be wise to consider at least two challenges</p>

SQL Event Store. Maybe Not.

Addendum</h1>

Further "fun" issues</h2>

Using EventStore with NestJS

Event sourcing</h1> Event sourcing is a very simple notion:</p>

Conclusion</h1> The previous iteration of this post used many concepts:</p>

Using EventStore with NestJS

Thoughs on Async Redux

Thoughts on Testing Components

Takeaways</h1>

Structured logging and tracing aren't very different</li>
OpenTelemetry takes care of a lot of the hard parts of distributed tracing</li>
You can derive logs (and metrics) from traces.</li>
Tracing requires a shift in mindset</li> </ul>

Takeaway</h1>
Constructing collaborators in constructors is a fairly big code smell. Do not</strong> mix object graph construction with your application logic.</p>