DEV Community: Margarita Krutikova

Set up Event Store on AWS with CDK

Margarita Krutikova — Sun, 27 Feb 2022 18:44:31 +0000

Event store can be deployed as a managed instance via Event Store Cloud which will take care of availability, clustering and other candies. The only drawback is the high cost of the hosting resources plus a separate cost (also high IMO 😛) for support. Here we won't take any fancy shortcuts with managed clouds and do it on our own in AWS using infrastructure as code with CDK in Typescript. We will have one event store cluster running in ECS Fargate service accessing an external file system, or EFS.

The CDK code is available on github.

Quick links to content:

Setup overview
CDK best practices
CDK Infrastructure
- Stateful resources
- Event store
- Creating stacks and dependencies
- Enable access to event store
Scientific diagram of how everything hangs together
Access EventStore Admin UI
Bonus: generating certificate
Next steps
Acknowledgments

Setup overview

Our CDK code will:

create a VPC (Virtual Private Cloud) where the file system will reside,
create a file system for persisting events,
spin up a container running EventStoreDB on ECS Fargate,
configure security group access to the event store from another Fargate service.

CDK best practices

A couple of very important CDK best practices that we will follow in our setup:

organize app in logical units that extend Construct,
group constructs into deployment units that extend Stack,
separate stacks with stateful and stateless resources.

Following these will greatly help when your app grows - you will need to refactor or add more resources. For the above setup we will have:

Constructs:
- VPC where we will attach the file system and ECS cluster for event store,
- file system,
- ECS cluster and Fargate service for running event store,
Stacks:
- a stateful stack with the VPC and EFS constructs,
- a stateless stack with the event store construct.

CDK Infrastructure

EFS is a stateful resource and it depends on VPC (removing it will nuke the EFS), so it makes sense to group these two resources in one stack. The rest - ECS cluster and event store service - belong to a separate stack that can be destroyed and re-deployed without any data loss.

Stateful resources

Here is how the vpc and file system look, one thing to note is enableAutomaticBackups when creating the file system:

new efs.FileSystem(this, "AppFileSystem", {
  vpc: props.vpc,
  ...
  removalPolicy: RemovalPolicy.RETAIN,
  enableAutomaticBackups: true,
})

You can configure backups manually or turn on automatic backups (enableAutomaticBackups is set to true). However you need to be aware of the default setting of automatic backups. According to the docs:

The default backup window (the time frame when the backup will run) is set to start at 5 AM UTC (Coordinated Universal Time) and lasts 8 hours.

And to ensure consistent backups AWS recommends pausing any writes to the file system or unmounting it during the backup.

If you don't want to keep these default settings, you shouldn't enable automatic backups and instead configure your own backup vault and backup rules, e.g. here is a backup rule to run at 2AM UTC within 2 hours:

const backupVault = new backup.BackupVault(...);

const plan = new backup.BackupPlan(this, "FileSystemBackupPlan`, {
    backupVault,
    backupPlanRules: [
      new backup.BackupPlanRule({
        completionWindow: Duration.hours(2),
        startWindow: Duration.hours(1),
        scheduleExpression: events.Schedule.cron({ hour: "2", minute: "0" }),
        deleteAfter: Duration.days(35),
      }),
    ],
});

Once you enable automatic backups and change your mind later, the automatic backup vault can't be removed. It will just be there, cold and lonely, until the end of times.

Now the stateful resources and their dependencies (VPC and file system) are packaged into a deployment unit StatefulStack. From this stack we expose the VPC and file system as two publicly accessible properties so that our event store construct can use them later when constructing the app:

export class StatefulStack extends Stack {
  fileSystem: FileSystem;
  vpc: IVpc;

  constructor(scope: Construct, id: string, props?: StackProps) {
    this.vpc = ...;
    this.fileSystem = ...;
  }
}

Event store

This beast is tricky, here is what we do:

create an ECS cluster to run a Fargate service,
create volumes for event store logs and data in the file system,
create a Fargate task definition and attack the volumes,
create an event store container and mount the volumes,
create a Fargate service and connect it with the task definition,
give the Fargate service access to the file system.

Here is the full code for the event store construct. It needs access to the file system and the VPC and we can pass them as props when creating an instance of the construct.

Let's assume we have created a cluster and a Fargate task definition:

const cluster = new ecs.Cluster(...)
const taskDefiniton = new ecs.FargateTaskDefinition(...)

Next we create volumes and attach them to the task definition:

const esVolumeLogs: ecs.Volume = {
  name: "eventstore-volume-logs",
  efsVolumeConfiguration: {
    fileSystemId: props.fileSystem.fileSystemId,
  },
}

const esVolumeData: ecs.Volume = {
  name: "eventstore-volume-data",
  efsVolumeConfiguration: {
    fileSystemId: props.fileSystem.fileSystemId,
    transitEncryption: "ENABLED",
  },
}

taskDefinition.addVolume(esVolumeLogs)
taskDefinition.addVolume(esVolumeData)

When creating an event store we are pulling an eventstore image from docker hub, specifying two external ports for TCP (1113) and HTTP (2113) communication:

const esContainer = taskDefinition.addContainer("EventStoreContainer", {
  image: ecs.ContainerImage.fromRegistry(
    "eventstore/eventstore:21.10.0-buster-slim"
  ),
  containerName: "EventStore",
  portMappings: [{ containerPort: 2113 }, { containerPort: 1113 }],
  user: "root",
  environment: {
    EVENTSTORE_CLUSTER_SIZE: "1",
    EVENTSTORE_EXT_TCP_PORT: "1113",
    EVENTSTORE_HTTP_PORT: "2113",
    EVENTSTORE_ENABLE_EXTERNAL_TCP: "true",
    EVENTSTORE_INSECURE: "true",
  },
})

EventStore image supports built-in self-signed or real certificate, see event store security. Setting EVENTSTORE_INSECURE to true will allow us to skip this for now, we will deal with it later.

And now we can mount the volumes we created earlier:

esContainer.addMountPoints({
  containerPath: "/var/log/eventstore",
  sourceVolume: esVolumeLogs.name,
  readOnly: false,
})

esContainer.addMountPoints({
  containerPath: "/var/lib/eventstore",
  sourceVolume: esVolumeData.name,
  readOnly: false,
})

Last, we create a Fargate service on the cluster and with the task definition defined above.

Creating stacks and dependencies

In our bin/app.ts we assemble the stacks and constructs taking into account their dependencies. An instance of StatefulStack is created first, the event store stack is created on the fly inside the construct and accepts resources from StatefulStack as dependencies in props:

const app = new cdk.App()

const statefulResources = new StatefulStack(app, "StatefulResources")

const eventStoreResources = new EventStoreConstruct(
  new Stack(app, "EventStore"),
  "EventStore",
  {
    fileSystem: statefulResources.fileSystem,
    vpc: statefulResources.vpc,
  }
)

Enable access to event store

Assume we have another Fargate service and we want to give it access to our event store. We need to add inbound rules in the event store security group to allow access on specific ports from the security group of this new service.

Ideally we don't want to configure security group rules inside the event store construct/stack because it will invert the dependency arrow - it is not the event store that depends on that external service, but the external service depends on the event store. In this way the deployment cycle of the event store is not affected by deployments of the dependent stacks.

One solution is to allow other CDK constructs to configure access to the event store security group that we can expose from the event store construct. The plan is:

expose connections object from the Fargate service on the construct,
pass the connections as a dependency in props in the other service construct,
configure access to the service security group via allowTo.

Changes we want to make inside the event store construct:

export class EventStoreConstruct extends Construct {
  connections: ec2.Connections;

  constructor(scope: Construct, id: string, props: EventStoreProps) {
    super(scope, id);
    const fargateService = new ecs.FargateService(..);

    // a lot of code

    this.connections = fargateService.connections;
  }
}

And our service construct:

type OtherServiceProps = {
  vpc: IVpc;
  eventStoreConnections: ec2.IConnectable;
};

export class OtherServiceConstruct extends Construct {
  constructor(scope: Construct, id: string, props: OtherServiceProps) {
    // setup cluster, fargate service, task definition etc.

    const fargateService = new ecs.FargateService(...);

    fargateService.connections.allowTo(props.eventStoreConnections, ec2.Port.tcp(2113));
    fargateService.connections.allowTo(props.eventStoreConnections, ec2.Port.tcp(1113));
  }
}

Our bin/app.ts can now include the new service and accept event store connections as dependency.

Scientific diagram of how everything hangs together

Here is a highly scientific graph of the AWS resources and connections between them:

Access EventStore Admin UI

You can enable access to EventStore Admin UI for testing purposes by exposing port 2113 to your IP in the inbound rules of the security group that belongs to the Fargate service we created above. This is not pretty, but hej, we are having fun here ... You should be able to access the Admin UI at http://<FARGATE_TASK_IP>:2113.

I guess it goes without saying that you should remove your IP from the rules and set up a more robust solution (external DNS, service discovery via AWS Cloud Map etc) when going live.

Bonus: generating certificate

To secure communication to/from event store we can generate a certificate with the certification generation tool that comes with event store. There is a docker image and a CLI that will generate a certificate authority and a node certificate for EventStoreDB, located in a separate github repo es-gencert-cli.

This task is not for the faint-hearted, the complete code can be looked at/copied entirely at your discretion here.

The certificate won't be stored in the file system but in the Fargate task storage and will be re-generated every time the task is updated. Here are the steps:

create a bind mount host volume and attack it to the task definition,
add container with es-gencert-cli image and specify command that will generate a certificate and place it in task storage,
add mount point to the container,
add the certificate generator container to the dependencies in the main event store container.

The communication to/from the event store is now encrypted with a self-signed certificate. A more production-ready setup would be nice, but hej, it is just an experiment for now.

Next steps

Things to do before going live:

add logging and alerts to the event store container,
change the default password and save it in AWS SecretsManager so that event store clients can safely access it,
add cloud map service discovery to the event store Fargate service.

Acknowledgments

I had the chance to carry out this cool experiment while working at a wonderful place, called Insurello in Stockholm, Sweden, with the help of my brilliant colleagues. They do tons of functional programming with F# and Elm, event sourcing, AWS with CDK and much more (I am not employed there right now and I miss them).

Why IaC and high-level overview of terraform

Margarita Krutikova — Tue, 14 Sep 2021 14:25:22 +0000

Infrastructure as code, or IaC, is becoming more mature and there are many tools that help describe infrastructure in code, such terraform, pulumi, farmer (Azure only) etc. Let's see why we should jump on this IaC bandwagon and understand its main ideas and benefits, and also learn how terraform implements them.

What is infrastructure?

It is where your app and its individual parts live - virtual machines, networks, load balancers, db servers, message queues etc. With cloud providers like Azure, you might have specific resources such as web app, cosmos db, storage account etc.

A common way of managing infrastructure is manual intervention via some GUI (all of us have at least once logged in to a production server to make a "small" change 😅), writing custom configuration tools to implement a specific setup etc. All of this can become error-prone: no one knows why a change was made or why stuff just stopped working. This can lead to hours of troubleshooting on the production servers.. fun stuff 😱

With modern cloud providers, manual configuration would look like this: you open your favourite browser, enter https://portal.azure.com/ and click through the UI to create a virtual machine:

So what does IaC do to mitigate these issues?

IaC goals

Reproducible infrastructure. Dev, stage, prod environments are consistent, easily reproduced and tested. Stop logging into your server and tweaking some settings or installing some software - you won't be able to reproduce it later and won't know why stuff broke.
Manage infrastructure state in a declarative way. If you need to make changes to you environment, you don't need to think about how to achieve it or what's already present in the environment. The imperative way is: if A is not installed run command B, then run command C to apply setting D to A. The declarative way is: I want to have A with setting C in my environment, make it happen.
Increase automation. Apply infrastructure changes as part of the deployment process. Minimize manual human labour (and thus decrease the number of mistakes made).
Keep infrastructure configuration version-controlled to make changes easier, trace back changes made overtime, collaborate with others and all the other fun stuff one can do with git.

Terraform

Terraform allows representing infrastructure as code. Or kinda code ... not like F# or C#, but more like declarative configuration files, like json or yml but with some support for functions, modules, etc. The language is called HCL - HashiCorp Configuration Language.

Keeping with the declarative paradigm of IaC, the idea is that you tell terraform what the desired state of the infrastructure is and it will make it happen.

How it works

You install terraform on your machine (fun fact - it is written in Go) and run terraform commands in a terminal.

You tell terraform what you want your environment to look like by writing your configuration in .tf files in some folder on your machine. The real state of the environment that corresponds to the configuration is tracked in a terraform state file and acts as a source of truth. When making changes to the configuration, terraform will use the current state file to know what changes to make in the environment so that it matches the new configuration.

Do not bypass terraform by changing your environment via GUI or elsewhere, terraform state file won't match the actual configuration!

Terraform provider

Terraform can work with different cloud platforms - Azure, Amazon, Digital Ocean, etc. Code you write will differ depending on the cloud platform, since they usually have their own resources and rules specific for that platform.

Terraform itself is agnostic of the underlying platform, but for managing remote objects on that platform it needs to know how to interact with it - in other words how to call the platform's API to create/modify/delete resources. This is done via terraform plugins called providers. You will need to install a specific cloud provider locally before creating your infrastructure with terraform.

Here is the sequence of actions terraform takes to make changes to the remote environment:

Terraform commands

You run terraform commands in a terminal to apply changes to the configuration:

plan - reads current state, compares to the configuration, creates a plan of changes (preview of the actions),
apply - executed the action proposed in the plan on remote objects,
destroy - delete all remote infrastructure for the configuration.

Terraform supports many other exciting features, like remote backends, workspaces, modules etc, but that's for another time.

Conclusion

You want to use infrastructure as code to:

track changes to the infrastructure in git,
share and collaborate with others,
revert changes easily if something goes boom 💥,
make changes easily,
recreate the same environment easily many times,
automate changes to the infrastructure during deployment.

Terraform implements IaC and stores a file with the state of your remote environment, keeps track of the differences between the configuration and the current state and synchronises the state file with the environment after changes have been made.

Also published at margareta.dev.

Modelling domain with state machines in ReasonML

Margarita Krutikova — Sun, 03 May 2020 08:54:01 +0000

Today we are going to focus on modelling state and state handling logic of a system in a functional way, without touching the user interface.

The idea behind "functional way" here is applying functional patterns and constructs in order to:

model the domain area correctly making impossible states unrepresentable,
handle domain logic eliminating impossible transitions on the state,
create a convenient interface for manipulating state that can be plugged in into any frontend (but not necessarily) application,
write readable and succinct code (less code - fewer bugs 🐛).

The code examples are written in ReasonML, but will look very similar in other functional languages such as F# or Elm. Some familiarity with functional concepts in general will help along the way, but not required.

Important concepts that we will use extensively:

Immutability and pure functions,
Variants and pattern matching,
Partial application and currying.

Just wanted to emphasise that we won't mutate anything here, since it might lead to unexpected bugs, systems that are difficult to follow and debug, and unexpected bugs. Did I mention unexpected bugs?

Overview

Let's imagine that we are building a time tracking system, like an upgraded to-do list, where the user can keep track of how much time it takes to finish tasks. Such a system can be used as a personal tool in private projects or a time reporting tool for software developers at work.

We will create a module for handling state of this system, gradually introducing more concepts along the way. Our best functional friends in this article will be variants (or discriminated union in F# and custom types in Elm) and pattern matching, which we will use to build a state machine.

The source code is available on github.

Modelling task

According to the requirements of the system, we should be able to:

add tasks,
start added and pause running tasks,
mark running or paused tasks as done,
keep track of how much time a task has been run.

So apart from having a name and probably id, a task should know whether it is running, paused, done etc., which we will call status. Then our task could look like this:

type task = {
  id: string,
  name: string,
  status: ???,
}

The status can only be assigned one of the following values:

not started (just added),
running with how much time it has been running,
paused with how much time it ran before it was paused,
finished with how much time it took in total.

Moreover, there are special rules that define whether a task can change its status to a particular value. For example, it wouldn't make sense to pause a task that is done, or start an already running tasks, however it is perfectly fine to set paused or running tasks as done. And the best way to model these rules is using a state machine, which is...

State machine

A mathematical model defined by a certain (limited!) number of states, where it can only be in one of these states at a time and can transition between the states based on the current state and some input.

My first reaction to the definition of a state machine was similar to the one of a "monad" 😨 But let's not allow it happen to you, reader! Simply put, it is a thing that has a limited number of predefined values, the thing can't change its value arbitrary, in order to choose the next value it needs to know the current value and some external input (like a user action).

State transitions in a state machine can be represented as a function:

nextState = transition (currentState, input)

We will model our status property as a state machine and represent its possible states with a ReasonML variant:

type elapsed = float;

type taskStatus =
  | NotStarted
  | Running(elapsed)
  | Paused(elapsed)
  | Done(elapsed);

Each state except NotStarted, will hold a time interval which we will represent as float with an alias elapsed (just for clarity). Those are the possible states of our little state machine. Now, we can define valid state transitions as a following table:

NotStarted -> Running
Running -> Paused
Running -> Done
Paused -> Running
Paused -> Done

I will add one more transition from Running to Running with elapsed time increased after each timer tick. The input that the state machine will accept can be represented as a variant too:

type input =
  | Start
  | Pause
  | Resume
  | Finish
  | Tick(elapsed);

Here Tick with elapsed time will come from a timer running somewhere in the app, while all the other input values will trigger state transition from the user input (e.g. click on the "Pause" button in the UI).

Before we implement our transition function, let's look into how we can visualise our state machine with an online tool.

State machine visualiser

A great way to illustrate the states and transitions of a state machine is to visualise them with a state diagram. There is an open source visualiser as part of the xstate library, which is an interactive tool where you can click on state transitions and see how state changes.

Check the task-status example live here, and here is a little preview:

xstate is an incredibly powerful library for implementing state machines in Typescript/Javascript projects with bindings to React and Vue.

Transition function

The transition function itself will accept a value of type input and the current state, and do a pattern match on both values matching only on valid combinations of pairs (state, input):

let transition = (input, state) =>
  switch (state, input) {
  | (NotStarted, Start) => Running(0.0)
  | (Running(elapsed), Pause) => Paused(elapsed)
  | (Running(elapsed), Finish) => Done(elapsed)
  | (Paused(elapsed), Resume) => Running(elapsed)
  | (Paused(elapsed), Finish) => Done(elapsed)
  | (Running(elapsed), Tick(tick)) => Running(elapsed +. tick)
  | _ => state
  };

The last case will handle all invalid transitions by returning the current state.

EDIT: I have been pointed out that when handling default cases with a wildcard match (_), it is easy to miss potentially valid transitions. Moreover, when making changes and adding states or inputs, the compiler won't give any warning if not handling all combinations explicitly. And I agree!😅

However, in more complex systems with many states and inputs, it becomes unreasonable to account for all combinations, since the number of cases is state * inputs. But let's see how we can do it for our little state machine:

let transition = (input, state) =>
  switch (state) {
  | NotStarted =>
    switch (input) {
    | Start => Running(0.0)
    | Pause | Finish | Tick(_) | Resume => state
    }
  | Running(elapsed) =>
    switch (input) {
    | Pause => Paused(elapsed)
    | Finish => Done(elapsed)
    | Tick(tick) => Running(elapsed +. tick)
    | Start | Resume => state
    }
  | Paused(elapsed) =>
    switch (input) {
    | Resume => Running(elapsed)
    | Finish => Done(elapsed)
    | Tick(_) | Start | Pause => state
    }
  | Done(_) => state
  };

A little bit more verbose, but still manageable.

Notice how we encode the business rules of the system in the transition function by allowing to move both running and paused tasks to done. If those rules have to change in the future (and they certainly will), there is only one place where we have to make adjustment and it is quite easy to modify the necessary transitions.

Speaking of making changes to the system and making sure nothing breaks, it is probably time to test our state machine and fortunately it is quite easy to do.

Testing

We will use bs-jest for writing tests in ReasonML and specifically the testAll function to generate tests based on lists of data.

Since we probably don't want to write a test per each valid and invalid transition (that would make for a total of 20 tests), we will use testAll for just two tests - valid and invalid state transitions - to achieve 100% coverage.

Testing valid transitions:

  testAll(
    "Transition works correctly for valid state transitions",
    [
      (NotStarted, Start, Running(0.0)),
      (Running(10.0), Pause, Paused(10.0)),
      (Running(10.0), Finish, Done(10.0)),
      (Paused(10.0), Resume, Running(10.0)),
      (Paused(10.0), Finish, Done(10.0)),
      (Running(10.0), Tick(15.0), Running(25.0)),
    ],
    ((currentState, input, nextState)) =>
    expect(currentState |> transition(input)) |> toEqual(nextState)
  );

Here we are feeding a tuple of three values into each test: currentState, input and the expected next state.

Testing invalid transitions is very similar. We will pass a tuple of a list of states and an input, where each of the combination (state, input) is invalid and should result in the same state after applying the transition function.

  testAll(
    "Transition returns current state for invalid state transitions",
    [
      ([|Running(10.0), Paused(10.0), Done(10.0)|], Start),
      ([|NotStarted, Paused(10.0), Done(10.0)|], Pause),
      ([|NotStarted, Running(10.0), Done(10.0)|], Resume),
      ([|NotStarted, Done(10.0)|], Finish),
      ([|NotStarted, Paused(10.0), Done(10.0)|], Tick(15.0)),
    ],
    ((states, input)) =>
    expect(states->Belt.Array.map(state => state |> transition(input)))
    |> toEqual(states)
  );

Summary

State machines help model domain area correctly making sure invalid states and transitions are simply impossible. Moreover, with tools like xstate visualiser we can discover hidden states or edge cases in a complex system by visualising it with a state diagram.

State machines are especially useful in frontend development, since a rich app will typically have a fair amount of state that changes based on the user actions. Since the user will probably not use your app as you would expect, eliminating invalid state transitions when the user clicks on the wrong button will spare your app a few crashes 💥

And the truth is, once you understand a state machine, you will see it everywhere (you are welcome!). However a language that supports variants (or discriminated unions) will truly uncover the power and beauty of state machines.

What's next

In the next article I will show how to manipulate a list of tasks in order to implement extra business requirements while writing nice, compact and readable code using partial application and reducer pattern.
Coming 🔜

ReasonReact context explained in action

Margarita Krutikova — Sun, 22 Sep 2019 15:54:29 +0000

Context in react is designed for sharing some global data between components located at different levels of the component tree. It allows to avoid passing props all the way down to those components ("prop-drilling") while still updating them whenever the value in context changes.

Worth noting that it is recommended to use context for low-frequent updates (quote by Sebastian Markbåge), due to a possible performance impact because of to the way react finds subscribers to the context value. This topic would require its own article (or perhaps a book?), and I will not touch upon it here and instead focus on a practical example of using context for seldom updates in a react application with ReasonML.

What are we building

We are going to build a feature with log in/log out, where we will put information about the user in context, so that we can access it from anywhere in our app and customise it depending on whether the user is browsing anonymously or not. The source code in the article is in this repo, and a link to the mini-app with this feature is here.

There are many bits and pieces that have to be wired up together in order to get benefits and all the convenience react context provides, especially in a strongly-typed environment with ReasonML, but it is definitely worth.

I will go through the steps needed to connect everything together and we will end up with a simple hook that allows to read the user data from context and dispatch and action to update it from any component, like this:

let (user, dispatch) = UserContext.useUser();
let handleLogIn = () => dispatch(UserLoggedIn(userName));

switch (user) {
  | Anonymous => /** display login form */
  | LoggedIn(userName) => /** say hi to the user! */
};

Scroll down to learn how 👇

Create provider and context

We will start with these steps:

Create context,
Create provider component,
Create reusable hook to access context value.

We need to know whether the user using our app is anonymous or logged in, and what actions can change this, so let's start with a few types:

/** Types.re */
type user =
  | Anonymous
  | LoggedIn(string);

type userAction =
  | UserLoggedIn(string)
  | UserLoggedOut;

LoggedIn will hold user name, but can be any other type with more user data. We will use userAction when implementing a reducer for our user state.

Now let's create context and reusable hook to access the context value, in a file UserContext.re:

/** initial value is Anonymous */
let context = React.createContext(Anonymous);

/** hook to easily access context value */
let useUser = () => React.useContext(context);

This is very similar to how you would do it in JS. Now let's create context provider in a file UserProvider.re

/** UserProvider.re */
let make = React.Context.provider(UserContext.context);

/** Tell bucklescript how to translate props into JS */
let makeProps = (~value, ~children, ()) => {
  "value": value,
  "children": children,
};

What is that makeProps for and why can't we just create a normal component with [@react.component] and make? The question I asked myself many times until I got tired and dug into it and found out 🤦‍♀️🙃

Remember how we always have named arguments for props in our reason components, like ~id or ~className? JS doesn't have such a feature, and all regular JS components just want to have props as an object. So how does it compile to valid react components in JS?

That's what the attribute [@react.component] is for. It will generate a function called makeProps, that transforms those named arguments into a JS object to be used as props in the JS compiled component.

React.Context.provider already generates a react component, that uses props as a JS object, but we want to use it as a reason component with named args. That's why we create makeProps by hand and it will tell bucklescript how to translate our named args into a JS object, consumed as props by the JS component. And in order to create an object that will compile cleanly to a JS object, we use bucklescript Object 2 bindings, that look like this:

{
  "value": value,
  "children": children,
}

So we are basically doing the job of [@react.component], but luckily it is not much, since the provider just needs a value and children 😅.

We can now use our provider component like <UserProvider...> since we followed the convention of having two functions make and makeProps in a file UserProvider.

Update value in context

Now, we want to use our Provider component and give it the user info, that we can update when the user logs in or logs out.

The important thing to understand here, is that if we want to update the value in context and propagate the update to subscriber-components, the value needs to be on the state of some component. This component needs to render the provider component with the value from its own state.

Let's call it Root component:

/** Root.re */
type state = {user};

/** user and userAction defined in Types.re */
let reducer = (_, action) =>
  switch (action) {
  | UserLoggedIn(userName) => {user: LoggedIn(userName)}
  | UserLoggedOut => {user: Anonymous}
  };

[@react.component]
let make = () => {
  let (state, dispatch) = React.useReducer(reducer, {user: Anonymous});

  <UserProvider value=state.user>
    <Page />
  </UserProvider>;
};

Cool, now whenever the value in context changes, components using useUser will be updated with the new value! Wait, the value actually never changes.. oh no! 😯

Let's give our components possibility to update user data via context. We could pass the update function down as props, which will be back to prop-drilling approach, but a more fun way is to include dispatch in the context value itself.

Pass dispatch in context

Let's pass our dispatch along with user as context value. Knowing that dispatch accepts userAction and returns unit, we can modify the type of context value in UserContext.re:

/** UserContext.re */
type dispatch = userAction => unit;
type contextValue = (user, dispatch);

let initValue: contextValue = (Anonymous, _ => ignore());
/** no changes when creating context */

and the root component:

/** Root.re */
let make = () => {
  let (state, dispatch) = React.useReducer(reducer, {user: Anonymous});

  <UserProvider value=(state.user, dispatch)>
    <Page />
  </UserProvider>;
}

Use context value via hook

And now the reward I promised in the beginning, an easy to use and convenient hook. I will just repeat it here once more, because it is cool:

let (user, dispatch) = UserContext.useUser();
let handleLogIn = () => dispatch(UserLoggedIn(userName));

switch (user) {
  | Anonymous => /** display login form */
  | LoggedIn(userName) => /** say hi to the user! */
};

Bonus: optimization techniques

Updating context value will cause subscribed components to re-render. In some cases we might want to avoid extra re-renders if we know they won't bring any updates to our UI. For example, if a component only needs to update user via dispatch, it won't be interested in any updates to the actual user data, but it will still re-render if the user is updated.

This can be solved by having the dispatch function in a separate context, which won't update, since dispatch is guaranteed to be stable. The other context will have the user data and will update the components that rely on it.

When the Root component itself updates (if its props are updated for example), it will recreate the tuple (user, dispatch) passed in context and cause subscribed components to update. This can be solved by using useMemo around the context value to make it stable.

We have now set up all we need to use context for storing and updating a small amount of global data in our reason-react application. We have also looked into some underlying mechanisms of how context works in react and how components are compiled in reason-react.

Have I missed something or made a mistake? Please let me know in the comments. Or just drop a line about how you are using context in your application! 💬

Keyboard accessible dropdown in Elm

Margarita Krutikova — Fri, 14 Jun 2019 23:59:30 +0000

^{- and how I discovered that browsers are awesome! 😍}
This is a follow-up on my previous post, where I showed how to decode DOM nodes from the event object to detect click outside. I am going to use this trick and a couple of more to create a dropdown that can be used with only keyboard.

I will explain how to properly handle keyboard and focus events, which will serve a good basis for an accessible dropdown. However, I will not cover another important aspect of accessibility - ARIA attributes. The final version will look like this:

All source code is on my github and also on ellie.

Requirements

Let's get formal and define what functionality we want to have. The user should be able to:

tab into the dropdown,
open it with Enter or Space keys,
focus options while navigating with arrow keys ⬆️ and ⬇️,
select currently focused option with Enter/Space,
close the dropdown with Escape or by tabbing out of it.

The implementation includes:

subscribe to keydown event,
decode the key that was pressed,
update the model according to the pressed key,
set focus on option when navigating with arrow keys,
handle focus in/out to open/close the dropdown.

HTML structure

Let's throw in some HTML for our open dropdown to better understand its structure:



<div id="dropdown">
  <button id="dropdown-button">Select option</button>
  <div>
    <ul id="dropdown-list">
      <li id="option_1">Option 1</li>
      <li id="option_2">Option 2</li>
      ...
    </ul>
  </div>
</div>

Here we want to attach a custom event listener for keydown to the root div (with id dropdown), and depending on the pressed key, update the model according to the requirements we defined above.

Model

In order to navigate the options list with up/down arrows, we need to keep track of the currently focused item. We also need to know whether
the dropdown is open, selected option id, and a list of options to show:



type alias Model =
    { open : Bool
    , selectedId : Maybe String
    , focusedId : Maybe String
    , options : List String
    }

Attach custom key event

Elm allows to attach custom event listeners and decode properties from the event object. Html.Events exposes on, which takes in the event name and a JSON decoder.

However, if we just listen to keydown with on and try pressing up/down arrows, we will see that the whole page scrolls, since it is the default browser behaviour (you can check it yourself in this little ellie).

We can fix this by using preventDefaultOn instead of on when attaching the event listener. preventDefaultOn needs a decoder of tuple for message and a boolean value, that indicates whether to prevent default. Let's use it in the view together with the message for keydown event:



import Html.Events as Events

type KeyPressed
    = Up
    | Down
    | Escape
    | Enter
    | Space
    | Other

type Msg  =
    ...
    | KeyPress KeyPressed

viewDropdown : Model -> Html Msg
viewDropdown model =
    div
        [ id "dropdown"
        , Events.preventDefaultOn "keydown" keyDecoder
        ]
        [...]

Let's implement keyDecoder that will receive the event object, decode it, dispatch KeyPress and prevent default scrolling behaviour. In order to extract the pressed key we can use event.key from the event object and convert it to our custom type KeyPressed:



keyDecoder : Decode.Decoder ( Msg, Bool )
keyDecoder =
    Decode.field "key" Decode.string
        |> Decode.map toKeyPressed
        |> Decode.map
            (\key ->
                ( KeyPress key, preventDefault key )
            )

preventDefault key =
    key == Up || key == Down

toKeyPressed : String -> KeyPressed
toKeyPressed key =
    case key of
        "ArrowUp" -> Up

        "ArrowDown" -> Down

        "Escape" -> Escape

        "Enter" -> Enter

        " " -> Space

        _ -> Other

Note: this is not the original formatting of the elm formatter, some extra line breaks were removed to save space on the screen.

A similar approach of handling keyboard events is documented on elm keyboard notes.

Update function

In the update function we can handle KeyPress and react to a specific set of keys depending if the dropdown is currently closed or open. Let's see how the implementation looks in the open state:



handleKeyWhenOpen : Model -> KeyPressed -> ( Model, Cmd Msg )
handleKeyWhenOpen model key =
    case key of
        Enter ->
            ( { model | selectedId = model.focusedId }, Cmd.none )
        Space ->
            ( { model | selectedId = model.focusedId }, Cmd.none )
        Up ->
            ( { model | focusedId = getPrevId model }, Cmd.none )
        Down ->
            ( { model | focusedId = getNextId model }, Cmd.none )
        Escape ->
            ( { model | open = False }, Cmd.none )
        Other ->
            ( model, Cmd.none )

Here getPrevId and getNextId find the item to the left and to the right from the focused item. You can check their implementation on my github.

Let's check what we have so far:

Uh oh ... The list doesn't scroll into the focused option, and it disappears from the visible area. So we need to update the scroll position when the focused item changes. To solve this, I first rolled up my sleeves and came up with my own implementation using Dom.getViewportOf, Dom.getElement, Dom.setViewportOf and calculating offset positions. 🤯

I was very proud of my smart solution, only to discover later that browsers have this behaviour built-in for focused elements. 😲🤦‍♀️

From MDN docs, focus method on the element:

will scroll the element into the visible area of the browser window

^{Wow! Browsers are awesome! 💪}
By setting focus on the option while navigating with keys, we will automatically get the desired scroll behaviour, so let's do exactly that!

Focus option on navigation

Browser.Dom exposes focus that accepts the element's id and attempts to focus it. We will use Task.attempt to transform Task returned from focus into a command:



import Task

type Msg
    = KeyPress KeyPressed
    | NoOp


focusOption : String -> Cmd Msg
focusOption optionId =
    Task.attempt (\_ -> NoOp) (Dom.focus optionId)

And let's use focusOption each time we navigate with arrow keys:



handleKeyWhenOpen model key =
    case key of
        Up ->
            navigateWithKey model (getPrevId model)
        Down ->
            navigateWithKey model (getNextId model)
        ...


navigateWithKey : Model -> Maybe String -> ( Model, Cmd Msg )
navigateWithKey model focusedId =
    ( { model | focusedId = focusedId }
    -- here we use focusOption
    , focusedId |> Maybe.map focusOption |> Maybe.withDefault Cmd.none
    )

For this to work, each li in our html needs to have an id and tab index to be focusable. So let's modify our view accordingly:



import Html.Attributes exposing (id, tabindex)

viewOption : Model -> Option -> Html Msg
viewOption model option =
    li
        [ id option.id, tabindex -1 ]
        [ text option.label ]

I also cheated a bit here and added scroll-behavior: smooth; in my css to make scrolling look nicer, because why not?

Now, we have one more thing left - close the dropdown on focus out.

Handle focus out

In my previous post, I showed how to decode event object to close dropdown on click outside. In short, the decoder takes event.target, traverses the DOM tree and for each element checks whether its id matches the id of the dropdown, if it finds a match - the event happened inside the dropdown.

Let's use the same approach, but for focusout event and relatedTarget property on the event object. relatedTarget in this case will be the element receiving focus. We will attach a custom event listener using on from Browser.Events:



viewDropdown : Model -> Html Msg
viewDropdown model =
    div
        [ id "dropdown"
        , Events.preventDefaultOn "keydown" keyDecoder
        , Events.on "focusout" (onFocusOut "dropdown")
        ]
        [...]

onFocusOut : String -> Decode.Decoder Msg
onFocusOut id =
    outsideTarget "relatedTarget" id

Here outsideTarget is a decoder that will answer the question: is an element outside the dropdown taking over focus? and dispatch the message that closes the dropdown. Here is the source code for the decoder.

Finale

We have now implemented keyboard support for our dropdown. What is left to comply with the accessibility requirements is to add the appropriate ARIA attributes and test the dropdown with a screen reader.

For my implementation of the dropdown, I consulted the following resources on accessibility, which might be helpful to improve it even further:

Thanks for stopping by! 💨

Elm DOM node decoder to detect click outside

Margarita Krutikova — Thu, 30 May 2019 18:21:51 +0000

The other day I was implementing a reusable dropdown on a side project in elm, and wanted the dropdown to close when I click outside of it.

I came up with an ad-hoc solution, that felt like 😕, so I asked the elm community on slack to point me in the right direction. The folks there came up with a couple of creative solutions, and went on to implement them for different edge cases. As en elm noob, I was thrilled to learn from more experienced elm devs, and decided to share what I have learned from that discussion in a couple of posts.

This one is going to be about implementing a generic way to detect click outside using some advanced decoding mechanisms to get DOM nodes from the event object.

How cool is that, decode a DOM node in elm? 🤯

Solution outline

I will use a simple dropdown as an example, but it can be any other element that benefits from detecting click outside (autocomplete, menu, popover etc).

The solution is to determine whether the DOM node that was clicked is located within the dropdown:

subscribe to the global mousedown event on the document,
get the element that dispatched the event (event target),
check whether the target element is a descendant of the dropdown by recursively traversing up the DOM tree,
if there is a match (either by id, className or any other attribute), the click happened within the dropdown - keep it open.

DOM API has Node.contains that checks whether a node is a descendant of another node. This function doesn't seem to exist in Elm, but no worry, we are going to roll our own implementation.

Subscribe to global `mousedown`

Browser.Events package allows to attach listeners to events on the whole document. It exposes onMouseDown listener, that accepts a JSON decoder to decode the event object and sends a message with the result if decoding succeeds.

To use JSON decoder install Json-Decode package:

elm install elm/json

and use onMouseDown in subscriptions:

import Browser.Events
import Json.Decode as Decode

subscriptions : Model -> Sub Msg
subscriptions _ =
    Browser.Events.onMouseDown (Decode.succeed MouseDown)

NOTE: To use subscriptions, the elm program should be at least of type Browser.element, Browser.sandbox can't talk to the outside world and doesn't support subscriptions, see effects on elm guide.

Our subscription doesn't do much right now: Decode.succeed ignores the JSON event object and only sends MouseDown message to the update function.

Recursive decoding of event target

The event target of the mousedown event is a DOM node that has a property parentNode, which we can use to recursively traverse up the DOM tree until we find the dropdown node or reach the top of the tree. To determine whether the nodes match we will use their ids.

I will first explain a more detailed implementation of the decoder before jumping to the eventual compact and elegant solution, which might seem quite cryptic at first glance.

Naive decoding

Here is a data structure that represents a DOM node:

type DomNode
    = RootNode { id : String }
    | ChildNode { id : String, parentNode : DomNode }

A decoder of this union type will use Decode.lazy for decoding recursive structures, and Decode.oneOf for decoding the individual constructors of the union.

In general, Decode.oneOf is useful for decoding data that can be in different formats, and works by accepting different decoders and trying them in sequence until one of them succeeds.

Here is the implementation:

domNode : Decode.Decoder DomNode
domNode =
    Decode.oneOf [ childNode, rootNode ]


rootNode : Decode.Decoder DomNode
rootNode =
    Decode.map (\x -> RootNode { id = x })
        (Decode.field "id" Decode.string)


childNode : Decode.Decoder DomNode
childNode =
    Decode.map2 (\id parentNode -> ChildNode { id = id, parentNode = parentNode })
        (Decode.field "id" Decode.string)
        (Decode.field "parentNode" (Decode.lazy (\_ -> domNode)))

The trick here is the decoders that recursively reference each other: decoding ChildNode references the domNode decoder and requires using Decode.lazy, and decoding DomNode references the child node decoder.

Now we can decode target from the event in the subscriptions and send a message with the decoded DomNode. The update function will then recursively traverse the node up the tree and check for nodes that match the dropdown.

But here comes the mind-blowing idea: what if we let the decoder determine whether the clicked node is inside the dropdown while recursively traversing the tree? 🤔

Instead of handing the whole recursive DOM structure to the update function, the decoder just answers the essential question of what to do with the dropdown: to close or not to close?

Outside-dropdown-decoder

A better decoder will consist of a sequence of decoders traversing the DOM tree and making the decision on the fly:

isOutsideDropdown : String -> Decode.Decoder Bool
isOutsideDropdown dropdownId =
    Decode.oneOf
        [ Decode.field "id" Decode.string
            |> Decode.andThen
                (\id ->
                    if dropdownId == id then
                        -- found match by id
                        Decode.succeed False

                    else
                        -- try next decoder
                        Decode.fail "continue"
                )
        , Decode.lazy (\_ -> isOutsideDropdown dropdownId |> Decode.field "parentNode")

        -- fallback if all previous decoders failed
        , Decode.succeed True
        ]

The responsibilities of these decoders are:

the first decoder will check the node's id and succeed with False (inside dropdown) if it finds a match, or fail causing the other decoders to step in,
the second decoder will recursively call the parent decoder, and might fail if the parentNode is null (the top of the tree is reached), causing the last decoder to run,
the last decoder simply succeeds with True (outside dropdown).

As a side note, Decode.fail takes in an arbitrary string which becomes a custom error message.

We need one more decoder that gets target, feeds it to the isOutsideDropdown decoder and sends message Close based on the result:

outsideTarget : String -> Decode.Decoder Msg
outsideTarget dropdownId =
    Decode.field "target" (isOutsideDropdown "dropdown")
        |> Decode.andThen
            (\isOutside ->
                if isOutside then
                    Decode.succeed Close

                else
                    Decode.fail "inside dropdown"
            )

Decode.andThen is used to create a new decoder that depends on the result of isOutsideDropdown decoder.

Final step, we subscribe to mousedown if the dropdown is open (to avoid listening to the event unnecessarily) and pass the id of the dropdown to the decoder.

subscriptions : Model -> Sub Msg
subscriptions model =
    if model.open then
        Browser.Events.onMouseDown (outsideTarget "dropdown")

    else
        Sub.none

Other applications of the decoder

This technique of DOM node decoding is extremely powerful and can be extended to more than determining click outside.

To improve keyboard accessibility of the dropdown, we need to close it when it loses focus (when "tabbing out" of it). One trick is to use the focusout event and apply the same decoder to the relatedTarget property, which gives the element that is about to receive focus.

In my next post I will show how to make the dropdown more accessible and handle focus and keyboard events.

Here is the source code on github, and here is a slightly trimmed version in ellie for you to play with.

Disclaimer: none of this magic would have happened without the amazing elm community, and none of this would have mattered without you, reader! 😍 To be continued...

P.S. If by any chance, you need to implement detecting click outside in ReasonML, you can drop by my other post, where I explain how to create a custom useClickOutside hook in a ReasonReact application.

I seem to have a click-outside obsession... Anyway, thanks for reading! 😅

Modelling remote data in ReasonReact

Margarita Krutikova — Thu, 23 May 2019 22:46:37 +0000

Let's look at a very common way of modelling state for api data in a react app with Typescript. You have an isLoading flag, the actual data and an error property in case something goes wrong:

type State = {
  isLoading: boolean
  data: Data | null
  error: string | null
}

This structure is easy to work with, but is far from perfect, since it allows to represent invalid states and can be error-prone when rendering the UI parts for a particular state (a bunch of ifs in the render function).

An example of such an error is setting initial data to an empty array of, let's say notifications, and forgetting to hide it while loading the actual notifications. This results in "you have no notifications" message, while it should show "loading notifications". This example is described in details in this great article How Elm Slays a UI Antipattern.

When writing reason, the language gives us a solid type system which allows to model remote data in a better way by using variants and pattern matching. With a proper data model, the language will also force us to give the user correct feedback for each possible state.

In this article I want to show a way to model state for api data, while avoiding invalid states. I will show how to use the library remotedata-re, and finally how to create our own abstraction over it to reuse it in different parts of the application.

Remote data states

The examples I am going to show to explain the concepts of remote data, are from a mini app I built - an advice generator with the api at api.adviceslip.com.

Now you might think, this sounds silly :) But it was actually fun to play with the app, and some pieces of advice were really enlightening, like these ones:

Enjoy a little nonsense now and then.

You don't need to floss all of your teeth. Only the ones you want to keep.

The source code for the app is in this repo on my github. In the app the user can search for advice by typing into a search input, which calls the api when the user presses Enter and displays a list of hits.

When making api calls, we are interested in the following states:

I don't have any data to show and haven't made an api call yet,
I don't have any data yet, but I have sent an api call and waiting for response (loading),
I have received an error from the server,
I have received some data and can render it,
I am re-fetching the data, (loading but showing the old data to prevent content blinking).

Modelling states with a variant

So we want to express those states and we start with a variant. The search api response and the search result could look like this:

type searchResponse = {
  total_results: int,
  items: string,
};

type searchResult =
  | NotAsked
  | Loading(option(searchResponse))
  | Failure(string)
  | Success(searchResponse)

Here we have constrained the data type to be only in one of these states: loading with possible data of searchResponse, failure with a string and success with data of searchResponse.

Note how loading state can also hold data, which is going to be empty before the first search, but will have the previous search result on any subsequent search.

If loading state doesn't carry any information, next time we search the current search result will disappear before the next response comes back. In some scenarios that might be okay or even useful (to prevent showing stale data e.g.), but in this case we don't want the screen jumping unnecessarily in between the calls.

Using `RemoteData`

In order to reuse the above data structure, we could make it polymorphic and add a type parameter:

type apiData(a') =
  | NotAsked
  | Loading(option(a'))
  | Failure(string)
  | Success(a')

Now we can create our type like type searchResult = apiData(searchResponse).

But there is already a small and handy library called remotedata-re with a similar data type. The library also comes with a couple utility functions for working with this data structure. The type defined in RemoteData looks very similar to our own webData:

type t('a, 'p, 'e) =
  | NotAsked
  | Loading('p)
  | Failure('e)
  | Success('a);

Using this structure, we can redefine searchResult, and model our state like this:

type state = {
  searchResult: RemoteData.t(searchResponse, option(searchResponse), string),
};

let initialState = {searchResult: RemoteData.NotAsked};

Transition between states

In order to transition between the states when making api calls, we need to define actions that will bear the information about the transition, and a reducer that will respond to those actions.

Here is how it might look:

type action =
  | SearchLoading
  | SearchError(string)
  | SearchSuccess(searchResponse);

let reducer = (state, action) => {
  switch (action) {
  | SearchLoading => {
      ...state,
      searchResult: RemoteData.(Loading(
          state.searchResult |> map(d => Some(d)) |> withDefault(None),
        )),
    }
  | SearchError(error) => {...state, searchResult: RemoteData.Failure(error)}
  | SearchSuccess(result) => {...state, searchResult: RemoteData.Success(result)}
  };
};

When processing the loading state, I am using helper functions RemoteData.map to apply the function (d => Some(d)) to the underlying data if searchResult is Success, and RemoteData.withDefault to "unwrap" the data from state Success, or give back None otherwise.

RemoteData.(...) opens the module locally and allows to refer to the module values inside the scope without prefixing them with RemoteData.

Custom remote data type

Usually a bigger app with several pages will need to perform different api calls at different points of time. So do we have to repeat that monster-block of code in our reducer when handling Loading, Error and Success cases?

I wanted to avoid doing so and, as an experiment, created a small abstraction over that piece of logic in a module called WebData (name borrowed from an elm package elm-web-data):

type t('a) = RemoteData.t('a, option('a), string);

type apiAction('a) =
  | RequestLoading
  | RequestError(string)
  | RequestSuccess('a);

let toLoading = (data: t('a)): t('a) =>
  RemoteData.(Loading(data |> map(d => Some(d)) |> withDefault(None)));

let updateWebData = (data: t('a), action: apiAction('a)): t('a) => {
  switch (action) {
  | RequestLoading => data |> toLoading
  | RequestError(error) => RemoteData.Failure(error)
  | RequestSuccess(response) => RemoteData.Success(response)
  };
};

Here I define a polymorphic type that already has option('a) as Loading state. I am also including an action type for transitioning between the states and a helper function to handle the actual transitions.

Now we can modify the above code for search result like this:

type state = {searchResult: WebData.t(searchResponse)};

type action =
  | SearchRequest(WebData.apiAction(searchResponse));

let reducer = (state, action) => {
  switch (action) {
  | SearchRequest(searchAction) => {
      searchResult: WebData.updateWebData(state.searchResult, searchAction),
    }
  };
};

This looks much cleaner! I am wrapping the api action for search result in a more specific variant SearchRequest. Then when pattern matching over it, I can extract the underlying api action and pass it into the function updateWebData, which gives back the new state for searchResult.

This pattern was inspired by The Elm Architecture, where you can create a module that owns its own state and exposes its update function and message. When the module is plugged into the main program, its message is wrapped into a new constructor that is part of the global message, the global update function can then unwrap it and call the update function of that module with the underlying message that the module understands.

In the advice generator app, the WebData module is reused for both fetching search results and generating random advice, you can check the implementation here.

Render remote data

Let's see how we can pattern match all the possible states of our state.searchResult and give the user correct feedback for each case:

{switch (state.searchResult) {
  | NotAsked =>
    <Message type_=Information text="You haven't searched yet!" />
  | Loading(None) => <Spinner />
  | Success(data) => <SearchResult data />
  | Loading(Some(data)) => <> <Spinner /> <SearchResult data /> </>
  | Failure(err) => <Message type_=Error text=err />
  }}

Here Message, Spinner and SearchResult are components I defined in the app (source code here).

There is a bit of duplication going on here. Success and Loading with Some(data) both use SearchResult to render that data, but the actual rendering logic could be more complicated, so we might want to handle it in one case to avoid this duplication:

{switch (state.searchResult) {
  | NotAsked =>
    <Message type_=Information text="You haven't searched yet!" />
  | Loading(None) => <Spinner show=true />
  | (Success(data) | Loading(Some(data))) as searchState =>
    <>
      <Spinner show={RemoteData.isLoading(searchState)} />
      <SearchResult data />
    </>
  | Failure(err) => <Message type_=Error text=err />
  }}

There can be different ways to render RemoteData or WebData with pattern matching and using helper functions from remotedata-re, and they will most likely vary with different UI requirements (e.g. placement of the spinner, disabling other elements on the page while loading etc.).

Conclusion

The key points are:

using variants to model remote data in ReasonMl helps to avoid invalid states,
each constructor in the variant represents a particular state of an api call and can carry extra information (like Success state with api data),
remotedata-re is a handy package that already implements a remote data type and exposes functions for working with it,
you can create your own reusable abstractions to help manage api data throughout your application,
rendering remote data involves pattern matching directly in your jsx and the implementation might vary depending on the UI.

What patterns have you found useful when working with remote data in reason? Curious to hear about your experience and appreciate sharing it in the comments :)

ReasonReact: use DOM API and hooks to detect click outside

Margarita Krutikova — Mon, 29 Apr 2019 22:12:01 +0000

Working on a reason-react application is an absolute delight. The language is perfectly suitable for writing the application's logic with reducers, especially with the latest version of ReasonReact with simpler and more concise syntax for writing components with hooks.

But when you need to do DOM manipulations, use refs on DOM elements, attach some event handlers or work with event objects, it gets less pleasant. There are not many resources available, it is difficult to get the types right and compiler errors are sometimes not very helpful.

In this article I want to show how to do all of the above without pain, while solving a very common problem: detecting a click outside of a DOM element.

The end result will be a useClickOutside hook, which takes in a function to run when a click is detected outside of an element, and returns a ref that you need to attach to that element. The source code is in my github repo with an example usage of the hook, so feel free to check it out directly if you just need a working solution.

Use case

There are quite a few reasons why you might want to detect clicks outside of an element. The most common is to hide an element when the user clicks outside of its area, like closing a modal, a dropdown, a notification etc. So here is a straight forward solution:

Listen to the onmousedown event on the document,
In the event handler get the element that dispatched the event (event target),
Check whether the target element is a descendant of the main element that needs to react on click outside using Node.contains,
Call the function if it is not within the main element.

Implementation

I am using the latest ReasonReact version (>= 0.7.0) that allows using hooks, if you haven't used them already in ReasonReact, I highly recommend checking out this article.

For the implementation we will use bs-webapi with reason bindings to the DOM API and a couple of react hooks (useRef and useEffect).

So let's embrace the OCaml type system and dive right into the implementation.

Add dependencies

Install bs-webapi:

npm install bs-webapi --save

and add it to the dependencies in bsconfig.json:

"bs-dependencies": ["reason-react", "bs-webapi"]

Add event listener in useEffect

Let's start implementing the useClickOutside hook by adding a mousedown event listener in useEffect:

open Webapi.Dom;

let useClickOutside = (onClickOutside: Dom.mouseEvent => unit) => {
  let handleMouseDown = (_) => ();

  React.useEffect0(() => {
    Document.addMouseDownEventListener(handleMouseDown, document);
    // cleanup - unsubscribe on unmount.
    Some(
      () => Document.removeMouseDownEventListener(handleMouseDown, document),
    );
  });
}

Here Document.addMouseDownEventListener and document come from Webapi.Dom.

We start listening to the mousedown event on the document inside useEffect hook. useEffect0 means it has no dependencies and thus only runs once after the component is rendered the first time.

In order to unsubscribe from the event, we can return a "cleanup" function from the effect. In ReasonReact the type signature of the function in useEffect is (unit => option(unit => unit)), so we need to wrap our cleanup function in Some.

Working with refs

Now we define the handleMouseDown function, which also needs to access a ref to the main element which lets us determine the outside area:

let elementRef = React.useRef(Js.Nullable.null);

let handleClickOutside = (elRef, e, fn) => ();

let handleMouseDown = (e: Dom.mouseEvent) => {
  elementRef
  ->React.Ref.current
  ->Js.Nullable.toOption
  ->Belt.Option.map(refValue =>
      handleClickOutside(refValue, e, onClickOutside)
    )
  ->ignore;
};

This looks cryptic ... What we are doing here:

define a ref with useRef, initialise it with null,
access the underline value of the reference with React.Ref.current and convert it to option,
use Belt.Option.map to run handleClickOutside only if the ref value is Some and return the result wrapped in Some, otherwise None,
ignore to disregard the result returned from Belt.Option.map.

I am using the fast pipe -> here to apply an expression as the first argument to the functions. Here is a great article explaining how the fast pipe works if you are curious.

There is more info on working with refs in reason-react docs.

Check if element is outside

Great, almost done! Now we need to implement handleClickOutside that will actually determine whether to call our custom function or not:

let handleClickOutside = (domElement: Dom.element, e: Dom.mouseEvent, fn) => {
  let targetElement = MouseEvent.target(e) |> EventTarget.unsafeAsElement;

  !(domElement |> Element.contains(targetElement)) ? fn(e) : ();
};

Here domElement will determine the inside/outside boundary. It is important to mention that the mouse event in this case is not a react event (a.k.a. Synthetic event), since we manually attached our callback to the document. In case of react mouse event you would use ReactEvent.Mouse.t, in our case however we use Dom.mouseEvent.

We will use Element.contains to check whether the target element is a descendant of the domElement. But here is a problem. This function takes in two parameters of type Element, but the target element is of type EventTarget, which strictly speaking, is not always an element and could for example be of type XMLHttpRequest (mdn docs).

However, since we attached the event handler to a DOM element we know for sure it is an element and can use EventTarget.unsafeAsElement to convert it to one.

Here is the link with the complete code of useClickOutside hook.

Example usage

Here is how the hook can be used in the wild:

open ClickOutside;

[@react.component]
let make = () => {
  let handleClickOutside = _ => {
    Js.log("Click outside detected");
  };
  let divRef = useClickOutside(handleClickOutside);

  <div ref={ReactDOMRe.Ref.domRef(divRef)} />;
};

I have created a simple dropdown component to show a real use-case scenario, source code on github.

I hope this article can help beyond this specific case of detecting click outside by providing some helpful tips and explanations when it comes to working with the DOM API.

Have you found anything that helped you? Or are you having trouble with DOM manipulations and refs while solving your particular case? Let me know by leaving a comment and we will figure it out :)

How to: mobx-state-tree + react + typescript

Margarita Krutikova — Sat, 06 Apr 2019 21:20:45 +0000

This is a walkthrough on how to get a full setup with mobx-state-tree and react in a CRA app with typescript. This guide doesn't focus too much on the theory or how things work under the hood and mostly includes practical examples (code!) on how to make things work.

I have been mostly using redux in all of my work and side projects, and eventually got curios about the other side of the state management world with mobx and decided to jump right into mobx-state-tree.

Trying to make mobx-state-tree work in react with typescript appeared to be quite a struggle. Especially making everything properly typed (no cheating with any!) in Typescript was a challenge, so when eventually everything fell in place I thought I would share my setup in order to (hopefully) make someone else's life easier :)

The application I build is a simple poll maker that allows to create a new poll, publish it, view and delete published polls. The source code with a cute little demo is available on my github.

Here are the quick links to jump to directly if you have a particular problem that is covered:

Setup stores in mobx-state-tree
- Create a base model
- Use composition to create domain stores
- CRUD on models in a nested list
- Convert between models
- Root store
- Communicate between stores
Connect react to mobx
- Why not mobx-react
- mobx-react-lite to the rescue
- Context provider to pass store
- Custom hook to inject stores

Setup stores in mobx-state-tree

I started developing my app with designing stores of the domain area in mobx-state-tree and was immediately faced with the following "how-to"s:

how to create a base model and use composition to extend it with properties and functionality in different stores,
how to create a store with a nested list of items representing another model and perform CRUD operations on it,
how to create a root store composing all the other domain stores,
how to communicate between stores.

I figured those might be common problems when designing stores for any domain area, so I will go through them in more detail and show my solutions.

In my poll-maker app there is going to be a base model PollBase, a store responsible for creating a new poll PollDraft, a model for a published poll PublishedPoll and a store for published polls PublishedPolls.

Create a base model

Before we start, install the necessary dependencies:

yarn add mobx mobx-state-tree

Now let's create a base model for the domain object poll, which will have a poll question and a list of choices, and abase model for choice with a string property and id:

import { types } from "mobx-state-tree"

const PollChoiceBase = types.model("PollChoiceBase", {
  id: types.identifier,
  value: types.optional(types.string, "")
})

const PollBase = types.model("PollBase", {
  question: "",
  choices: types.optional(types.array(PollChoiceBase), [])
})

Use composition to create domain stores

A poll that is being edited (let's call it a draft poll) and not yet published will have the same properties as PollBase, but also actions to edit those properties. Similar, a choice of a draft poll will have the same shape as PollChoiceBase with an action to update it:

const PollDraftChoice = PollChoiceBase.actions(self => ({
  setChoice(choice: string) {
    self.value = choice
  }))

const PollDraft = types
  .compose(PollBase,
    types.model({
      choices: types.optional(types.array(PollDraftChoice), [])
    })
  )
  .actions(self => ({
    setQuestion(question: string) {
      self.question = question
    }
}))

A published poll can no longer be edited, so it won't have editing actions but it needs an extra property id to be able to find it or create an external link to it:

const PublishedPoll = types.compose(
  PollBase,
  types.model({
    id: types.identifier
  })
)

CRUD on models in a nested list

A draft poll has a list of choices, that can be added, edited and removed. Currently we have an action to update a choice (setChoice), but no actions to remove an existing choice or add a new one.

Here adding is rather trivial, but removal is a bit tricky. We want to be able to use choice.remove() somewhere in a react component, but actions can only modify the model they belong to or their children, so a choice can't simply remove itself and can only be removed by its parent PollDraft since it "owns" the list of choices. This means PollDraftChoice model will need a remove action which will delegate its removal to PollDraft, which we can retrieve via getParent helper from mobx-state-tree.

Here is the code (I use shortid to generate unique ids):

import { destroy, getParent, Instance, cast } from "mobx-state-tree"

// Instance is a typescript helper that extracts the type of the model instance
type PollDraftChoiceModel = Instance<typeof PollDraftChoice>
type PollDraftModel = Instance<typeof PollDraft>

const PollDraftChoice = PollChoiceBase.actions(self => ({
  ...
  remove() {
    const pollDraftParent = getParent<PollDraftModel>(self, 2)
    pollDraftParent.removeChoice(cast(self))
  }
}))

const PollDraft = types.compose(...)
  .actions(self => ({
    ...
    addChoice(choice: string) {
      self.choices.push({ id: shortid(), value: choice })
    },
    removeChoice(choiceToRemove: PollDraftChoiceModel) {
      destroy(choiceToRemove)
    }
}))

Here is what is happening inside PollDraftChoice:

getParent<PollDraftModel>(self, 2) means fetch parent 2 levels up - one until you reach items property and one more until you reach PollDraft itself, and assume that the returned parent is of type PollDraftModel.
pollDraftParent.removeChoice(cast(self)) uses cast helper to tell typescript that self is indeed of type PollDraftChoiceModel. Why is it necessary? The problem is that self here is of type what was before views and actions are applied, which means at that point self is actually not of type PollDraftChoiceModel, so pollDraftParent.removeChoice(self) won't compile in TS.

Convert between models

Let's create our second domain store to keep track of published polls:

import { types, Instance, getSnapshot } from "mobx-state-tree"

type PublishedPollModel = Instance<typeof PublishedPoll>
type PollDraftModel = Instance<typeof PollDraft>

export const PublishedPolls = types
  .model({
    polls: types.optional(types.array(PublishedPoll), [])
  })
  .actions(self => ({
    publishDraft(pollDraft: SnapshotIn<PollDraftModel>) {
      const pollToPublish = { ...pollDraft, id: shortid() }
      self.polls.push(pollToPublish)
    }
  }))

Here publishDraft takes in a snapshot of a poll draft. Snapshot in mobx-state-tree is a plain object stripped from all type information and actions and can be automatically converted to models.

So why does publishDraft need to take in a snapshot and not just PollDraftModel? That's because an instance of PollDraftModel can't be converted to a published poll since it will have extra actions that aren't compatible with PublishedPollModel, and will cause a runtime exception. So, by specifying SnapshotIn<PollDraftModel> we explicitly say that we want the raw data that exists on PollDraftModel.

Next problem is that publishDraft action has to be called somewhere from outside, either from the PollDraft store or from some kind of RootStore. Let's see how we can make that happen and establish some communication between the two stores.

Root store

Let's create a root store to combine all stores used in the app: PollDraft and PublishedPolls:

type RootStoreModel = Instance<typeof RootStore>

const RootStore = types.model("RootStore", {
  pollDraft: PollDraft,
  publishedPolls: PublishedPolls
})

Communicate between stores

One way of communicating between stores, is to use getRoot from mobx-state-tree to fetch the root store and from there get the necessary store, or use getParent to traverse the tree. This works fine for tightly coupled stores (like PollDraft and PollDraftChoice), but won't scale if used in more decoupled stores.

One way to enable store communication is to make use of getEnv function that can inject environment specific data when creating a state tree (from mobx-state-tree docs). So we can just inject a newly created store into the whole state tree. One caveat here is that the environment can't be passed directly into one of the child stores and needs to be passed into the root store, otherwise you get this error:

Error: [mobx-state-tree] A state tree cannot be made part of another state tree 
as long as their environments are different.

Let's create a function called createStore, similar to redux's configureStore, that would create all individual stores, create the environment and assemble them all together in one root store. The environment will have only one property of PublishedPolls store since it needs to be accessed from PollDraft when publishing a poll draft:

type RootStoreEnv = {
  publishedPolls: PublishedPollsModel
}

const createStore = (): RootStoreModel => {
  const publishedPolls = PublishedPolls.create()
  const pollDraft = PollDraft.create()

  const env: RootStoreEnv = { publishedPolls }

  return RootStore.create({ pollDraft, publishedPolls }, env)
}

Now, PolLDraft store can define a publish action and call publishDraft on publishedPolls:

import { types, getEnv, getSnapshot } from "mobx-state-tree"

const PollDraft = types
  .compose(...)
  .actions(self => ({
    ...
    publish() {
      const snapshot = getSnapshot(self)

      const env = getEnv<RootStoreEnv>(self)
      env.publishedPolls.publishDraft(snapshot)
    }
  }))

Connect to redux devtools

We will use connectReduxDevtools middleware from the package mst-middlewares that will connect the state tree to the redux devtools (more info and configuration options available in the docs). In order to setup the connection we will use a monitoring tool remotedev. Install the packages first:

yarn add --dev remotedev mst-middlewares

and add the following code after the store creation:

import { createStore } from "../stores/createStore"
import { connectReduxDevtools } from "mst-middlewares"

const rootStore = createStore()

connectReduxDevtools(require("remotedev"), rootStore)

Connect react to mobx

The part I struggled most with is how to connect react to mobx and start using stores in my components. The idea here is that react components need to become "reactive" and start tracking observables from the stores.

Why NOT mobx-react

The most common way to achieve this is by using mobx-react which provides observer and inject functions, where observer is wrapped around components to make them react to changes and re-render and inject just injects stores into components. However, I wouldn't recommend using this library because:

when using observer, the component loses the ability to use hooks because it gets converted to a class, more on this here. And the docs recommend in the best practices to use observer around as many components as possible, which means hooks can't be used almost anywhere,
inject function is quite compilcated and doesn't work well with typescript (see github issue), requiring all stores to be marked as optional and then using ! to indicate that they actually exist.

mobx-react-lite to the rescue

Luckily there is another library, mobx-react-lite, which is built with hooks and provides observer wrapper. One thing worth mentioning, observer doesn't support classes, but there is a dedicated component Observer that can be wrapped around parts of jsx in render in class components.

It is easy to get confused with this library since it provides a lot of hooks like useObservable, useComputed etc. that are going to be deprecated according to the docs. Instead here is a recommended way, that we are going to follow:

use react context provider to pass down the store(s),
access the store using useContext hook with a selector, alternatively inject the necessary stores with a custom useInject hook based on the useContext hook,
wrap components with observer from mobx-react-lite to subscribe to changes.

So let's install the library:

yarn add mobx-react-lite

Context provider to pass store

First, let's create context StoreContext, that will later receive the root store as its value, and export provider and a custom hook for accessing the context value:

const StoreContext = createContext<RootStoreModel>({} as RootStoreModel)

export const useStore = () => useContext(StoreContext)
export const StoreProvider = StoreContext.Provider

And then create the root store with createStore and send it into StoreProvider which we wrap around App:

import { StoreProvider } from "./StoreProvider"
import { createStore } from "../stores/createStore"

const rootStore = createStore()

const Root: React.FunctionComponent<{}> = () => (
  <StoreProvider value={rootStore}>
    <App />
  </StoreProvider>
)

Custom hook to inject stores

It is possible to use the useStore hook directly to access the root store and get the necessary data from it, like this:

const { pollDraft } = useStore()

I also implemented a useInject hook that takes in a mapping function and returns a mapped object, similar to how it is done in redux with mapStateToProps. This hook is somewhat close to the idea of custom inject with a mapper function, but with hooks. So if you have a more complicated app with lots of things in your store, you might want to get only the things you want and not care about the rest.

In its simplest form, useInject hook might look like this:

export type MapStore<T> = (store: RootStoreModel) => T

const useInject = <T>(mapStore: MapStore<T>) => {
  const store = useStore()
  return mapStore(store)
}

The PollDraft component would then use useInject to access pollDraft store from the root store:

import { observer } from "mobx-react-lite"
import { RootStoreModel } from "../stores/RootStore"
import useInject from "../hooks/useInject"

const mapStore = (rootStore: RootStoreModel) => ({ pollDraft: rootStore.pollDraft })

const PollDraft: React.FunctionComponent<{}> = observer(() => {
  const { pollDraft } = useInject(mapStore)

  return (
    <div>
      <h1>Create a new poll</h1>
      <input
        value={pollDraft.question}
        onChange={e => pollDraft.setQuestion(e.target.value)}
      />
      <button onClick={pollDraft.publish}>Publish</button>
    </div>
  )
})

This is especially useful if mapStore function is more complicated and involves combining data and actions from several stores.

At this point I felt like I covered the basics and created a setup that I could continue building upon or use it as a boilerplate for projects with a similar stack. The source code can be found on my github.

I hope this walkthrough was useful and you found something that helped you in your projects. Would love to hear your feedback on what you think was helpful or share your own experience with mobx-state-tree and react in typescript!

DEV Community: Margarita Krutikova

Set up Event Store on AWS with CDK

Setup overview

CDK best practices

CDK Infrastructure

Stateful resources

Event store

Creating stacks and dependencies

Enable access to event store

Scientific diagram of how everything hangs together

Access EventStore Admin UI

Bonus: generating certificate

Next steps

Acknowledgments

Why IaC and high-level overview of terraform

What is infrastructure?

IaC goals

Terraform

How it works

Terraform provider

Terraform commands

Conclusion

Modelling domain with state machines in ReasonML

Overview

Modelling task

State machine

State machine visualiser

Transition function

Testing

Summary

What's next

ReasonReact context explained in action

What are we building

Create provider and context

Update value in context

Pass dispatch in context

Use context value via hook

Bonus: optimization techniques

Keyboard accessible dropdown in Elm

Requirements

HTML structure

Model

Attach custom key event

Update function

Focus option on navigation

Handle focus out

Finale

Elm DOM node decoder to detect click outside

Solution outline

Subscribe to global mousedown

Recursive decoding of event target

Naive decoding

Outside-dropdown-decoder

Other applications of the decoder

Modelling remote data in ReasonReact

Remote data states

Modelling states with a variant

Using RemoteData

Transition between states

Custom remote data type

Render remote data

Conclusion

ReasonReact: use DOM API and hooks to detect click outside

Use case

Implementation

Add dependencies

Add event listener in useEffect

Working with refs

Check if element is outside

Example usage

How to: mobx-state-tree + react + typescript

Setup stores in mobx-state-tree

Create a base model

Use composition to create domain stores

CRUD on models in a nested list

Convert between models

Root store

Communicate between stores

Connect to redux devtools

Connect react to mobx

Subscribe to global `mousedown`

Using `RemoteData`