Łukasz Makuch

What are portals in frameworks like React and Vue?

Sat, 17 Feb 2024 15:37:20 GMT

After working with different incarnations of the concept of portals in React and Vue I came to understand them as a way to differentiate the tree of UI components from the tree of logic components.

I know this definition may sound cryptic, but I promise you that it'll click if you read this post.

You see, components are a neat way to keep our code coherent. They encourage the delivery of vertical slices by grouping those pieces of state, logic, styles, and UI controls that work and change together.

That's why there's often a direct, one-to-one correlation between framework components and DOM nodes:

However, sometimes that's not what we want. The way we layout UI elements doesn't always align with the way how ownership, data and behavior are grouped.

Let me provide an example that illustrates this well. It's an example which we've all seen. It's a widget that opens a modal.

And yes, I am aware there are both third-party and built-in solutions that allow us to achieve something like that without thinking about it too much. I consider it to be a good example exactly because it's so common. We're all familiar with the end result, and that makes it easier to think about what's actually going on under the hood.

As far as ownership is concerned, the widget "owns" that modal. It decides when to show it and the modal doesn't have any other reason to exist than to serve the widget. Yet, the modal renders above everything else. It's one of those situations when the tree of components that render things on the screen doesn't align with the tree of components that define data and behavior.

So how can we code it?

We could reverse the invert hierarchy. The modal could become the parent of the widget. The modal would live in the root node of the entire application, and it'd pass the widget that opens it down. It could work, but it'd obscure what's more important - the widget - by placing some detail - the modal - above everything else. It'd also become harder for the widget to change what's inside of the modal.

What we're wrangling with here is that we clearly want the modal to render outside of the widget, yet the logical hierarchy should be such that the widget is the more important component that controls its modal.

That's exactly what portals are for! They enable us to decouple the DOM tree from the component tree. With portals we can teleport things from one place to another. Have a look:

The Widget can still own and control the Modal, but through the means of portals the Modal renders outside of the Widget.

Portals allow us to have the cake and eat it too. We can keep the hierarchy of components as readable and as predictable as possible, while still rendering UI elements that don't necessarily correspond to it one-to-one.

What are some differences between various portal implementations?

Sat, 17 Feb 2024 15:37:20 GMT

In the previous post on portals we've covered what portals are in general. But did you know there are some important differences between various implementations of portals? Those differences can significantly change the way how you use portals to develop software!

While all portal engines provide a way to move some piece of some tree somewhere else, they go about it in different ways. In today's entry we'll focus on what's actually being teleported and what does it mean for the developers.

Some portals, like the portals from React, work by moving DOM nodes:

From the framework's perspective, components don't move at all. It's just the DOM that moves.

If we recall that at Facebook React was used to augument server-side PHP applications it's easy to understand why React portals work that way. They can be used to render components controlled by React even outside of the root node of any particular React app!

Other libraries, like PortalVue, teleport components even before they become DOM nodes:

This library was born in the userland before Vue had built-in portals. Maybe that's why it's so unique.

But why does it matter, you may ask?

In both React and Vue there are tools for working with component subtrees instead of just individual components, such as Dependency Injection in Vue and its React counterpart - Context.

If we move only DOM nodes, dependency injection won't be affected. But if we move framework components, the teleported components will be injected with different values, potentially altering the behavior of the app, not just its appearance.

That's why it's important to know the details of the portal engine you're using. This applies even to folks who've already worked with portals because there're significant differences in what do portals actually do, even between different versions of the same framework, such as between Vue 2 and 3.

The 14 reasons why engineers write automated tests

Sun, 11 Feb 2024 15:37:20 GMT

If you've ever asked yourself the question "Why did they write these tests?" then this blog post is for you. Over the last decade, I've observed a multitude of reasons as to why IT professionals automate tests. Some of them are purely technical, and some are rather social. Some bring a lot of value to the company, while others benefit only individual engineers. Revealing them here will ruffle some feathers, but it can also serve as a nudge to abandon some practices while doubling down on others.

The 14 reasons to automate tests

1. Spotting regression as soon as possible

One of the most common reasons to automate tests is to spot regression. Once a system grows big, making sure everything still works as expected requires a lot of manual work. Hiring manual testers is also expensive, and even an entire team of manual testers may still need a significant amount of time to thoroughly test a big system. This is the reason why testing tickets pile up before releases. That's also why developers become hesitant to introduce changes that would pay off in the future but could introduce bugs the QA wouldn't find. Such decisions provide short-term stability and faster release cycles but lead to the accumulation of technical debt, which slows the development process down in the long run. Cheap and fast automated tests enable teams to release more often and stay away from technical debt. Also, the whole process feels much calmer without all that fear about breaking who knows what without even knowing about it.

2. Verifying properties, broadly speaking, not just some cases

Imagine we're creating an algorithm that should output a number between 0 and 1. If it produces a result beyond that range, it means there's an error. How do we go about testing this? An easy way to increase our confidence in this algorithm is to use property testing. While it's oftentimes not feasible to manually create thousands or millions of inputs, computers can do it just fine. It means that instead of writing a scenario like "Given 42 and 7, it returns 0.3", we can write a scenario like "Given 2 numbers, it returns a number between 0 and 1" and the computer will generate and run tons of concrete test cases to ensure that's true.

3. Testing what's hard to test manually

It's relatively straightforward to manually test happy path scenarios. However, testing becomes increasingly more challenging if we need to check if the system works as expected when something goes wrong. Think a dependency service being down or concurrent processes executing in an unusual order. Fortunately, in a scripted test environment we can have total control over all the moving pieces and it becomes easy to simulate all the edge cases.

4. Testing what nobody wants to test manually

Some things are worth keeping in check, but it's really mundane to manually enforce them. Examples of such things include the right letter capitalization or the right number of spaces. While a human can certainly look for white space violations, there are probably better ways for them to make good use of their time. Automating this aspect of product development frees people to do things that are more valuable for the business.

5. Meeting contractual obligations

Many kinds of tests, when done right, prove invaluable in increasing the confidence we can have in our products, which leads to faster time to market. That's why a requirement to have automated tests may be found in various contracts, for example, when a company is looking for investors. Such contractual obligations may even serve as the primary incentive for teams to embrace automated testing.

6. Social pressure

Contrary to what some may believe, engineers are social creatures too, and that makes them susceptible to social pressure. So even if an individual contributor doesn't find the practice of test automation beneficial, they may still be tempted to automate them in an environment that favours those who do. Being accepted by one's peers or getting that life-changing promotion is worth doing things that seem pointless.

7. Learning how to automate tests

To err is human, but humans also learn by doing. So even if we don't know how to effectively automate tests, it may still be a good idea to at least try to do it. There's a chance that after enough attempts we'll start seeing a return on investment.

8. Spotting security vulnerabilities before the bad actors do

Nowadays, it's rare for any big product to be built entirely from scratch. Most of the time, there are countless prefabricated components, such as libraries, compilers, and even operating systems. It means that even if the code of our product is perfectly secure, it may still be compromised if a security vulnerability is discovered in one of its underpinning technologies. That's why it's important to continuously monitor the codebase for known security issues. An automatic security check can be scheduled to run on weekends and during the night just fine. That way, we can react to threats faster. And because a human is alerted only if needed, it helps to keep the cost low.

9. Measuring performance

Modern multi-tenant web apps are no stangers to handling tens of thousands of requests per second. Let's say we're about to launch a new feature. How can we measure its performance, so that we have at least some idea about how much the infrastructure will cost? If you've ever tried clicking very fast to see how an app perfroms under heavy load, you know that it may be quite a challenge! That's where automated stress testing comes into play. Being able to repeadetly generate the same amount of traffic and measure various parameters such as CPU load and memory usage proves invaluable in making fact-driven decisions.

10. Seeing how different variants perform

Let's say there are two variants of the same thing in our product: variant A and variant B. Will our users like the variant A more than the variant B? It may be hard to predict. Instead of trying to predict it, we can deploy both variants, measure their key performance indicators, and automatically switch to the variant that performs better.

11. Making use of the byproducts of design to speed up the development process

While in many ways it's true that building software is like building a plane in the air, some products or pieces of thereof are still designed upfront. It may help us if we ask ourselves the question "So what is it supposed to do, again?". The outcome of answering it may be a set of precise preconditions, actions and expectations, akin to the components of an automated test suite. If these descriptions are so precise, then we're just one step away from automating the process of verifying them. And if we can easily shave off hours, if not days, of mundane manual labour, why not do that?

12. Recreating scenarios

Automated tests often consist of 3 phases, namely arranging, acting, and asserting. Even if we want to manually test some scenario, we may not be keen on arranging all the test data and navigating through the app to reach the testing point. In such situation, a hybrid approach may emerge, where the first phase - arranging - is automated, while the 2 remaining ones are done manually.

13. Fostering communication

Sometimes it's easier to talk about a product through the lens of its tests. A language like Gherkin encourages the formulation of human-readable yet specific and actionable examples. Even failed tests can help us communicate with others, especially when using frontend-testing-tools. In such tools, each failed test generates a before-and-after picture, visually highlighting the difference between the reference image and the current state of the app.

14. Supporting individuals with disabilities

There are many reasons why the selectors from Testing Library took the community by storm. One of them is the fact that they are accessible by default. For many people, it's enough for a rectangle to appear on the screen to be considered a button. However, others may benefit from that rectangle having a specific button role, properly attached label text, and support for keyboard-driven interactions. Although the selectors provided by today's state-of-the-art libraries still don't give us a guarantee that the app is fully inclusive, they're certainly a step in the right direction that can eliminate the most common barriers troubling people who rely on accessible web applications.

Summary

In an industry where new ways to develop software emerge more often than new ways to test that software, testing is a delicate topic. There's still a lot to learn and invent. I believe that what's even more important than learning particular tools is to understand the real outcomes of introducing some testing regimes, as well as being honest about our motivation.

How to mock POST requests using Nock in JavaScript

Wed, 07 Feb 2024 17:37:20 GMT

Nock is a popular JavaScript library used for server mocking.

Getting started with Nock is as easy as it gets. Do you want to mock a GET request? Simply write

nock('https://example.com')
  .get('/name').reply(200, "John")

It couldn't be easier to mock a GET request.

You can even mock multiple endpoints:

nock('https://example.com')
  .get('/name').reply(200, "John")
  .get('/surname').reply(200, "Doe")

Where it gets more tricky is mocking requests that are supposed to alter the state of the server, such as POST requests. It's very tempting, and in fact very common, to write a mock like this:

nock('https://example.com')
  .get('/name').reply(200, "John")
  .post('/name', { name: 'Johnny' }).reply(200)
  .get('/name').reply(200, "Johnny")

At the first glance, evertyhing works as expected:

console.log((await client.get('/name')).data) // John
await client.post('/name', { name: 'Johnny' }); // 200
console.log((await client.get('/name')).data) // Johnny

However, if we take a closer look, we may notice some discrepancies between our mock and how a real endpoint would behave. For instance, we'll get the updated name even if we don't actually update it!

console.log((await client.get('/name')).data) // John
// No POST request whatsoever
console.log((await client.get('/name')).data) // Johnny

It's because Nock doesn't have the notion of state. I'd even go as far as saying that Nock doesn't have a built-in support for POST requests. I know it may sound wrong, but hear me out.

When we register 3 mocks like that:

nock('https://example.com')
  .get('/name').reply(200, "John")
  .post('/name', { name: 'Johnny' }).reply(200)
  .get('/name').reply(200, "Johnny")

there are two unique requests: GET /name and POST /name. There are two responses associated with the GET /name request. They form a kind of First In First Out queue. And this queue is completely separate from the queue of POST /name!. It means that POST requests don't have any impact on what's returned in response to GET requests. The mock currently behaves in the same was as if we wrote it like this:

nock('https://example.com')
  .post('/name', { name: 'Johnny' }).reply(200) // queue A
  .get('/name').reply(200, "John") // queue B
  .get('/name').reply(200, "Johnny") // queue B

or like that:

nock('https://example.com')
  .get('/name').reply(200, "John") // queue B
  .get('/name').reply(200, "Johnny") // queue B
  .post('/name', { name: 'Johnny' }).reply(200)  // queue A

If we focus on just the GET request, there are 2 and only 2 responses queued for it: "John" and "Johnny". That's why calling this mocked GET endpoint 3 times will give us consecutively: "John", "Johnny", and an error. That's unlike a real API, which in the same circumstances would return "John" three times.

It may let bugs slip in, if the system under test refetches the data before it updates it. Tests will pass, but only because the mock naively returns the updated data, even if it hasn't been updated. It will also make tests more fragile, as a relatively harmless superfluous GET request will significantly change the mocked data by shifting the queue associated with it.

Is all hope lost and we can forget about mocking POST requests in Nock? Fortunately, there IS a way to make Nock mimic a real server, so that we can write more reliable and robust tests! It can be accomplished through the means of functions:

// Define the state of the mocked server.
// In this example it's a name.
let name = 'John';

scope.persist()
    // In response to GET, return the name.
    .get('/name').reply(() => [200, name])
    // When we get a POST request
    .post('/name').reply((uri, body) => {
        // Change the state of the "server" 
        name = body.name;
        // Return 200.
        return [200];
    })

If you're familiar with express, it's kinda like writing mini express apps. And what advantages does it have over the naive solution with queues?

If we just call GET multiple times, we'll always get the same result:

console.log((await client.get('/name')).data) // John
console.log((await client.get('/name')).data) // John
console.log((await client.get('/name')).data) // John

But as soon as we fire up a POST request, the name changes:

console.log((await client.get('/name')).data) // John
console.log((await client.get('/name')).data) // John
console.log((await client.get('/name')).data) // John

await client.post('/name', { name: 'Johnny' });

console.log((await client.get('/name')).data) // Johnny
console.log((await client.get('/name')).data) // Johnny

Writing mocks in a way that closely resembles real APIs helps to catch bugs that could otherwise go unnoticed, i.e. if some component refetches data too early. It's also a pragmatic choice, because even if the component under test fires up some redundant requests, the tests won't fail as long as the observed behavior of the app is correct.

And if you're anything like me and you find this imperative style rather primitive and you're yearning for a more elegant solution, then have a look at HTTP mocking libraries with first-class support for state, such as WireMock or Endpoint Imposter.

Scoped styles don't get applied to functional components in Vue 2

Fri, 02 Feb 2024 17:37:20 GMT

Having your CSS scoped to the component it applies to helps in maintaining encapsulation. That's exactly what Scoped CSS was designed for. It's pretty straightforward most of the time, but there are some controversial edge cases. One of them is the fact that these scoped styles defined by the parent component don't get applied to the root node of functional child components the same way they get applied to stateful child components. Here's an example of a parent component with scoped styles and a stateful child:

<template>
  <div class="layout">
    <Stateful class="child" />
  </div>
</template>
<script>
import Stateful from "./components/SomeStatefulComponent.vue";

export default {
  components: { Stateful },
};
</script>
<style scoped>
.layout {
  display: grid;
  grid-template:
    ". ...... ." 40px
    ". center ." 40px
    ". ...... ." 40px / 1fr 1fr 1fr;
  border: 1px solid black;
}

.child {
  grid-area: center;
}
</style>

It works as expected - the child is placed in the center of the layout:

However, it breaks as soon as we make the child component a functional component:

<template>
  <div class="layout">
    <Functional class="child" />
  </div>
</template>

Now the child component doesn't get the styles from its parent:

Why don't scoped styles apply to a functional child component?

If you've ever inspected the actual CSS of a component which uses scoped styles, you've probably noticed an attribute like data-v-80d8c89c. It's there to limit the scope of CSS selectors.

When styles are unscoped, there isn't much going on. We write templates like this:

<Stateful class="child" />

and styles like this:

.child {
  grid-area: center;
}

The generated DOM looks like this:

<div class="stateful">I am a stateful component!</div>

and the CSS stays exactly how we wrote it.

However, as soon as we make the styles scoped by changing <style> to <style scoped>, something happens. The generated HTML looks like this:

<div data-v-7ba5bd90="" class="stateful">I am a stateful component!</div>

and the styles have an extra attribute selector:

.child[data-v-7ba5bd90] {
    grid-area: center;
}

That's how the scope of the stylesheet is narrowed down so that it doesn't get applied to all .child nodes all over the app.

While this mechanism aims to scope all kinds of styles, what we're doing here is precisely styling child component root elements. It's this one special scenario in which scoped CSS is actually applied to some other components - the children. According to the documentation it should be used sparingly - just for layout purposes. Maybe that's why issues living in the junction of styling child component root elements and functional components don't arise too often - because as long as we keep our code idiomatic, it simply doesn't occur that often.

So, why does it break break when we make the child functional?

The CSS stays the same, that is scoped:

.child[data-v-7ba5bd90] {
  grid-area: center;
}

However, if the child has its own scoped stylesheet, it doesn't inherit the data-v attribute from its parent. In fact, it doesn't even accept the class the parent passes to it!

If the parent has

data-v-7ba5bd90

and tries to render

<Functional class="child" />

, we get:

<div data-v-064b6fca="" class="functional">...

Notice the different data-v and no "child".

How to style functional child components the same way stateful child components are styled?

The most straightforward way to address this issue would be to make this functional component behave the same way stateful components behave. We can bring back all the familiar bindings with 2 lines of code:

<template functional>
  <div
    class="functional"
    :class="[data.staticClass, data.class]"
    v-bind:[parent.$options._scopeId]="''"
  >
    I am a functional component!
  </div>
</template>

It works as expected - the child is centered:

But is it a good scoped styles apply to child components?

This is a good moment to stop and think about the wise words of Dr. Ian Malcolm:

Dr. Ian Malcolm : Yeah, yeah, but your scientists were so preoccupied with whether or not they could that they didn't stop to think if they should.

If scoped styles are meant to be limited to the component they are defined in, is the fact that they are also applied to roots of children helpful or confusing? I believe it's the latter. Judging from my experience, most often than not this capability is used in a non-idiomatic way, for instance to style borders.

What are some alternative ways to style children components?

The most obvious way to style a child component is to use props. Props define a clear, obvious API.

And when we're actually defining a layout, pure CSS may be more than enough. For instance, a CSS grid container may define the align-items property which, according to MDN, sets the align-self value on all direct children. And if we need more control over how the direct children are styled, the child combinator > comes in handy:

<style scoped>
.layout /deep/ > * {
  align-self: flex-end;
}
</style>

Note the usage of a deep selector.

The resulting CSS is:

.layout[data-v-7ba5bd90] > * {

The deep selector disables scoping for this rule and that's why it's important that we narrow the selector down to the direct children of .layout ourselves throught he means of the child combinator >.

Portals in Vue 2 don't work with Slot Props from Scoped Slots

Sat, 27 Jan 2024 17:37:20 GMT

There's a caveat worth keeping in mind when using portals through the means of portal-vue in Vue 2. You may notice that adding slot props prevents the view from updating, even if you don't actually use them. If there's a v-slot, the template doesn't refresh.

✅ How to make sure the teleported content reacts to changes?

I believe that the only way to guarantee components update properly when they are sent through <portal> in Vue 2 is to use render functions instead of templates. To simplify writing render functions, consider enabling JSX.

You might have seen this comment by Thorsten Lünborg (the author of portal-vue) in which he proposes a couple of interesting workarounds. Sadly, none of them worked reliably in my testing.

❌ What won't work?

There are steps that, when taken, may trick us into thinking we've solved the bug. However, in reality the bug is still there and may reoccurr in any time. The following steps do not guarantee that that the problem will be solved once for good:

adding v-if="true"
adding keys
extracting more components
using different scoped slots syntax in templates

But why do slot props break portals in Vue 2 in the first place?

Vue 2 doesn't have native portals; instead, they're provided by a third party library called portal-vue. In a nutshell, it works by sending a piece of the render function from one component to another.

Vue 2.6 introduced a performance optimization of scoped slots. That's why slot-scope has been deprecated. But implementing this optimization proved to be a challenging task.

What we can observe is that as soon as we go from this:

<portal to="destination">
    <with-slot-props>
      hello world
    </with-slot-props>
</portal>

to this:

<portal to="destination">
    <with-slot-props v-slot="props">
      hello world
    </with-slot-props>
</portal>

it breaks.

Why?

I found vue-compiler-online by Jack Chi extremely helpful in understanding what exactly happened.

This is the actual render function created by the template compiler when we don't use slot props:

return _c('portal', {
    attrs: {
        "to": "destination"
    }
}, [_c('with-slot-props', [_v("hello world")])], 1)

It changes quite drastically as soon as we add v-slot or slot-scope:

return _c('portal', {
    attrs: {
        "to": "destination"
    }
}, [_c('with-slot-props', {
    // a mysterious _u function
    scopedSlots: _u([{
        key: "default",
        // a new function
        fn: function(props) {
            return [_v(
                "hello world"
            )]
        }
    }])
})], 1)

There's a new function and it's not your typical scopedSlots function.

_u stands for resolveScopedSlots and when called like this, it produces a result with { $stable: true }, which caches the output and thus prevents it from being re-rendered in portals.

How does writing the render function ourselves fix the problem?

If we write this render function ourselves, it won't be incorrectly cached by resolveScopedSlots:

return h('portal', { attrs: { to: 'destination' } }, [
  h('with-slot-props', {
    scopedSlots: {
      default: props => h('div', 'hello world')
    }
  })
]);

How to write render functions and not go crazy?

I don't know about you, but I don't usually write my HTML in raw render functions, and because I'm not exposed to them, I don't find them readable. Fortunately, JSX can make render functions with scoped slots prettier:

<portal to="destination">
  <with-slot-props scopedSlots={{
    default: (props) => <div> hello world </div>
  }} />
</portal>

Back to the familiar syntax, yay!

If you want, you can play with JSX more in the JSX-Vue2 Playground.

Why don't workarounds like `v-if="true"`, `key`, and `slot-scope` work?

Using the old slot-scope syntax compiles to exactly the same output as using v-slot.

Adding unique keys is possible only when we can predict what will end up in the portal upfront.

Exctacting the content of the portal into a separate component works only when all the props we pass to it are the slot props. Other values, like props from the parent component, will become stale.

Assigning v-if="true" is the most interesting trap. This is what it compiles to:

return _c('portal', {
  attrs: {
      "to": "destination"
  }
}, [(true) ? _c('base-layout', {
  scopedSlots: _u([{
      key: "default",
      fn: function(props) {
          return [_c('div', [_v(
              "hello world"
          )])]
      }
                   // A mysterious hash
  }], null, false, 2480752568)
}) : _e()], 1)

Now the result is still cached, but this time under the 2480752568 key. It's derived from the template inside of the scoped slot. So if we change "hello world" to "hello code", it becomes 212219543 instead of 2480752568. The good news is that it often prevents the template from going stale! The bad news is that it ignores variables. So if we have the following template:

<button>hello {{name}}</button>

and we swap it for an identical template with a different name value, it won't refresh.

Summary

I know that some people choose Vue solely because they are not big fans of JSX. However, JSX in render functions is the closest to reliable templates we have if we want to use Vue 2, portal-vue and slot props.

(React) Old state when the user navigates back

Thu, 04 Aug 2022 10:37:20 GMT

Let's say you're developing a React app that consists of a component that has some side effects. Perhaps it does something very important when it's mounted. Perhaps it matters that on the initial render it's in the right state.

It all works well in the development mode, but the production build renders stale components when the user navigates back to the app after leaving it for another web page. In other words, when the user clicks the //back// button, the functions passed to useEffect don't run. After navigating back to the app, React doesn't notice the component being mounted. Moreover, it holds the old state that was there before the page was left! And it happens only in production builds! It never happens in the development mode. So, what exactly happens?

It's the doing of a mechanism known as bfcache (or Back-Forward Cache). It's a cache that sometimes holds your entire page in memory. It even includes the state of your JavaScript app. When the user navigates back, it's as if they never left the page. What's good is that it's a tremendous boost in performance. What's bad is that it may lead to some unexpected behavior and it happens just sometimes, not all the time.

You may expect your React app to be re-mounted when the user navigates back to it, but it won't happen. Instead, they will land on a page which is in the very same state it was the moment they left it.

What makes it even more tricky is that if you use Create React App you may never observe such behavior in the the development mode, because in this mode bfcache doesn't really work.

The good news is that you can register an event listener and be notified when the page is restored from the cache! Here's how you can use JavaScript to notice that the page is restored from the Back-Forward Cache:

window.addEventListener('pageshow', event => {
  if (event.persisted) {
    console.log("restored")
  }
});

Equipped with that information, you can decide to re-render your component or restore the desired state in some other way.

Alternatively, if you'd like to prevent the pages from being cached in the first place, for instance because they contain some sensitive information you would prefer not to leak, you may deliver the SPA with the following header:

cache-control: no-store

Resources:

Sure, I can start working on it right now! But is it a wise thing to do?

Sat, 21 May 2022 16:37:20 GMT

At some point I realized I had way too many pairs of flip-flops, so I proceeded to build software to solve this problem for good. I’m a software developer, after all, building software is what I do.

Wait, what? Let’s start from the beginning.

I love traveling and whenever I can, I travel lightly. It feels great to be able to leave the airport carrying just a backpack instead of a big suitcase which I’d have to lug around.

Even though one-bagging has a lot of benefits, there are also some drawbacks. One of them is this minimalistic, additive packing model. Because of the fairly limited volume of a single backpack, I have to deliberately choose what to take with me instead of deciding what to leave at home. When there’s no room for any just in case items, it’s easy to forget about some useful yet not absolutely necessary stuff. For instance, for some reason I used to forget about flip-flops and ended up buying multiple extra pairs. Had I traveled with all my worldly possessions, I wouldn’t have to worry about it. But as you can guess, that’s not a feasible solution. Whenever possible, I want to be able to quickly pack all I need into a single bag, so that I can travel lightly without depriving myself.

I tried making packing lists in Apple Notes, but they didn’t cut it. Depending on the nature of my trip, the list had to vary, so I found myself creating an entirely new list before each trip, what was time-consuming and error-prone.

Then I searched for an app that would enable me to create custom, reusable packing lists.

It turned out there wasn’t any app that’d satisfy my requirements. It seemed that I found a niche. So the obvious next step was to build an app to serve it, right? I’m a software engineer, I can do it.

Fortunately, before diving deep into coding I asked myself a very important question - “Do I really need to build a custom app for that?”.

I knew what kind of experience I wanted. I wanted to feel prepared for my trips. I wanted to feel calm while packing. And I wanted all that to be quick and hassle-free.

Nowhere on my list was “I wanted that to be provided by a custom app”.

So I created a Google Sheets spreadsheet. If you’re interested, you can watch a video introduction to my Reusable Packing List on YouTube.

Does it mean I overlooked the User Experience? By no means! I carefully designed, prototyped, and tested it. And how did it go? Better than I’d have imagined! Below are some of the things people said about it:

“That spreadsheet is a work of art!”

“It’s insanely amazing.”

“Awesome! It is quite beautiful!”

“I love the spreadsheet!”

“What a fantastic spreadsheet!”

“I’d like to marry that spreadsheet.”

It turns out people love it a ton. And building it didn’t cost a ton.

Just because I was able to get myself busy with building a custom piece of software didn’t mean it was a wise thing to do. It could even be detrimental! It’d mean slower prototyping, slower testing, much later release and a greater risk of abandonment. Or, as Timothy Ferriss writes it in his book titled The 4-Hour Work Week:

“Doing something unimportant well does not make it important.”

Your XML security library is sabotaging your work. Here's what you can do about it.

Sun, 12 Dec 2021 10:30:20 GMT

Dear developer,

Have you ever had the need to verify the signature of an XML document? Yes? Then I have bad news for you - the library you used to accomplish that task is sabotaging your work!

Doing all that cryptography is hard, and that's why you're offloading it to a library. It's a wise move! Sadly, that library is not helping you.

Just look at its documentation! The examples span across tens of lines, and the README (hopefully) mentions at least a couple of things like this:

"If you want to be sure that the data you're consuming has been signed, don't forget to call the method that validates the reference."

"If you want to be sure that the data you're consuming has been signed, don't forget to make sure that the node you're consuming equals the referenced node."

"If you want to be sure that the data you're consuming has been signed, don't forget to call the method that validates the signature."

"If you want to be sure that the data you're consuming has been signed, don't use the method we for some reason provide and which reads the public key from the payload."

"If you want to be sure that the data you're consuming has been signed, make sure your XPath queries are not reaching nodes that were removed in the canonicalization phase just before the digest was calculated."

Whoa! 😱 What?! 🤯

If you're like me when I first stumbled upon XML signatures years ago, you may be asking yourself questions along the lines of:

"Isn't checking the signature enough? Why do I have to additionally check the validity some reference?"

"How do I compare some node to the referenced node?"

"What does reference even mean in this context?"

"So you're giving me some method and then telling me it's not safe to call it?"

"Canonica... What? What digest? Where? What should I do with it? Why do I even have to think about it myself?! Wasn't this library supposed to help me?"

Not only are the examples convoluted, but they're incomplete and can make your app vulnerable!

You. Deserve. Better!

You don’t have to simply accept the fact that the library you’re using is working against you.

Just imagine how much easier your life as a developer would be if you could simply write:

node = getTheOnlySignedNodeOrNull(xml, publicKey)

Imagine node being either null or an XML node that's for sure entirely signed with the given public key.

Imagine not worrying anymore about things like:

Are both the reference and signature validated?
Is this what was referenced?
Is this part of the signed node actually signed, or is this something that's been stripped in the canonicalization phase?
Is the public key trusted, or was it supplied by the attacker?

It'd be so much easier! So much safer!

And if you needed to read a couple of signed nodes, you could simply call:

nodesArray = getSignedNodes(xml, publicKey)

I know, your library doesn't like look like that. But you can do something to fix it, even if you’re not a security expert yourself! If it’s on GitHub, simply open an issue describing the problem and propose adding the safer API described above. Feel free to link to this blog post.

You don’t have to invest too much time to get the discussion going. And once people are talking about it, someone will implement the fix. Maybe it will even be you!

Let’s make the internet more secure!

Are XML Signatures secure?

Fri, 17 Sep 2021 13:37:20 GMT

The short answer is that in practice XML signatures are insecure and shouldn't be relied upon.

Now, I know that's quite a statement, but please hear me out.

What are digital signatures, again?

Digital signatures are a way to ensure that a piece of data has been released by a particular party and that it hasn't been modified by a third party.

The premise is simple: if we have the public key of the sender, we can check if some data has been signed by that sender. To sign data, you need to be in possession of the private key and that's why only the legitimate sender can sign documents.

It's a wonderfully simple concept.

For example, you can sign a document and pass it from one system to another through some front channel, such as a web browser, and if the data is correctly signed, you can be sure that no malicious actor modified it.

What makes signing XML tricky?

As I mentioned earlier, signatures are simple. But add XML to the equation and you get an incredibly complex, tricky and practically insecure mechanism.

Just have a look at this XML document describing a classic pizza:

<pizza Id="_0">
  <name>Margherita</name>
  <details>
    <ingredients>
      <ingredient>mozzarella</ingredient>
      <ingredient>tomatoes</ingredient>
      <ingredient>basil</ingredient>
    </ingredients>
  </details>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><Reference URI="#_0"><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><DigestValue>IaSUjZiQc6CtB9EjeSS6R96bIWo=</DigestValue></Reference></SignedInfo><SignatureValue>ReJkW/mCaIbX+UZBoZRl+uoqXFQeN7/Tm4gGG9tpqVtvIHTkZTFk7/K/EG9IS6dmqM46qCNRq+yymm8MvLJu2/Iey4A0ZGyZ5etY4jHiIju2L5gfF/orHjfXkhbpT7qbJ3+5rtKed/p3hrX1wdY8gikCC6XgNC3LKsi9C1NhkQ4YhyFnGrnXKoGeEkBFsyaJWiRY7CFVm5aMDzSF+bO7WrdF0wtuayIBR0+fz6bbt7PVWWypEPhOzu8DsZnSXocy51ASY7LW2f7HyPVhsui9XMMcdTT4mGIJnGJeM8wVmCi40QWrQuIEXtAfISDjFz2U7eiP2jLKPQg88Wxhao0ymQ==</SignatureValue></Signature></pizza>

The goal of the code consuming this document is simple: verify the signature and read the list of ingredients.

I decided to use JavaScript to illustrate the examples just because it's popular, but judging from my experience in the security industry you can run into such errors in any language.

Here's an implementation based on the documentation of the library used to verify the signature:

// Imports:
const select = require('xml-crypto').xpath
const dom = require('@xmldom/xmldom').DOMParser;
const SignedXml = require('xml-crypto').SignedXml;
const FileKeyInfo = require('xml-crypto').FileKeyInfo;
const fs = require('fs');

// Loading data:
const xml = fs.readFileSync("signed.xml").toString();
const doc = new dom().parseFromString(xml);
const signature = select(doc, "//*[local-name(.)='Signature' and namespace-uri(.)='http://www.w3.org/2000/09/xmldsig#']")[0]
const sig = new SignedXml()
sig.keyInfoProvider = new FileKeyInfo("cert.pem")
sig.loadSignature(signature)

// Verifying the signature:
const correctlySigned = sig.checkSignature(xml);
if (correctlySigned) {
  // Making sure the element we work with is signed. Based on the docs.
  const pizza = select(doc, "/pizza")[0];
  const uri = sig.references[0].uri;
  const id = (uri[0] === '#') ? uri.substring(1) : uri;
  if (pizza.getAttribute('ID') != id && pizza.getAttribute('Id') != id && pizza.getAttribute('id') != id)
    throw new Error('the interesting element was not the one verified by the signature')
  // Reading ingredients:
  const ingredients = select(pizza, "//ingredient").map(node => node.textContent);
  console.log(ingredients);
} else {
  console.error(sig.validationErrors) 
}

This is what we get if we run it:

➜  node read.js
[ 'mozzarella', 'tomatoes', 'basil' ]

Let's see what happens when we change basil to oregano:

<pizza Id="_0">
  <name>Margherita</name>
  <details>
    <ingredients>
      <ingredient>mozzarella</ingredient>
      <ingredient>tomatoes</ingredient>
      <ingredient>oregano</ingredient>
    </ingredients>
  </details>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><Reference URI="#_0"><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><DigestValue>IaSUjZiQc6CtB9EjeSS6R96bIWo=</DigestValue></Reference></SignedInfo><SignatureValue>ReJkW/mCaIbX+UZBoZRl+uoqXFQeN7/Tm4gGG9tpqVtvIHTkZTFk7/K/EG9IS6dmqM46qCNRq+yymm8MvLJu2/Iey4A0ZGyZ5etY4jHiIju2L5gfF/orHjfXkhbpT7qbJ3+5rtKed/p3hrX1wdY8gikCC6XgNC3LKsi9C1NhkQ4YhyFnGrnXKoGeEkBFsyaJWiRY7CFVm5aMDzSF+bO7WrdF0wtuayIBR0+fz6bbt7PVWWypEPhOzu8DsZnSXocy51ASY7LW2f7HyPVhsui9XMMcdTT4mGIJnGJeM8wVmCi40QWrQuIEXtAfISDjFz2U7eiP2jLKPQg88Wxhao0ymQ==</SignatureValue></Signature></pizza>

➜  node read.js
[ 'invalid signature: for uri #_0 calculated digest is kK2GwWhLPYK/zAa8MoEJ3FPIkGk= but the xml to validate supplies digest IaSUjZiQc6CtB9EjeSS6R96bIWo=' ]

We've got a validation error. That's good, right? Right! It means nobody can manipulate this data, right? Wrong!

You see, there are so many complex operations going on that it's really hard to fully understand it. The underlying signing algorithm is solid and libraries make it easy to use. It takes the data, the signature, and the key and tells us whether this key was used to generate this signature for this data. But our case is inherently more complex! We have an XML document which is a tree structure. The signature isn't provided as a separate argument, but is placed inside the signed document instead. And in order to read data, we use a query language (XPath) to query for <ingredient /> nodes. Moreover, we don't even query the same document that has been signed! More on that below.

When the document was being signed, it didn't have a signature. The signature is derived from the unsigned document and only then placed inside it. That's why before verifying it, the document is reverted to its initial form. It means removing the <Signature /> node from the tree. That's what the http://www.w3.org/2000/09/xmldsig#enveloped-signature transformation does. There are also other operations going on, like canonicalization, which helps to ignore the differences between things like <Node /> and <Node></Node>.

That's why even thought we're loading something like this:

<pizza>
  <field param="value"></field>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">...</Signature>
</pizza>

we may be calculating the signature of something more like this:

<pizza><field param="value"/></pizza>

The fact that a huge chunk of the tree disappears is interesting from an attacker's perspective and terrifying from a developer's perspective.

When we're looking for <ingredient /> nodes, we're querying the signed document. It means that in it still has the <Signature /> subtree in it. But because the signature itself isn't signed, we can add there anything we want, even another <ingredient /> node:

<pizza Id="_0">
  <name>Margherita</name>
  <details>
    <ingredients>
      <ingredient>mozzarella</ingredient>
      <ingredient>tomatoes</ingredient>
      <ingredient>basil</ingredient>
    </ingredients>
  </details>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <ingredient xmlns="">pineapple</ingredient>
  <SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><Reference URI="#_0"><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><DigestValue>IaSUjZiQc6CtB9EjeSS6R96bIWo=</DigestValue></Reference></SignedInfo><SignatureValue>ReJkW/mCaIbX+UZBoZRl+uoqXFQeN7/Tm4gGG9tpqVtvIHTkZTFk7/K/EG9IS6dmqM46qCNRq+yymm8MvLJu2/Iey4A0ZGyZ5etY4jHiIju2L5gfF/orHjfXkhbpT7qbJ3+5rtKed/p3hrX1wdY8gikCC6XgNC3LKsi9C1NhkQ4YhyFnGrnXKoGeEkBFsyaJWiRY7CFVm5aMDzSF+bO7WrdF0wtuayIBR0+fz6bbt7PVWWypEPhOzu8DsZnSXocy51ASY7LW2f7HyPVhsui9XMMcdTT4mGIJnGJeM8wVmCi40QWrQuIEXtAfISDjFz2U7eiP2jLKPQg88Wxhao0ymQ==</SignatureValue></Signature></pizza>

Even though we weren't able to forge the signature, when we run the code again, we get a little surprise:

➜ node read.js
[ 'mozzarella', 'tomatoes', 'basil', 'pineapple' ]

We've got pineapple on our pizza!

What happened is that even though the data was properly signed, this signed data was just a subset of the queried data. The malicious payload was placed in the unsigned yet queried portion of the document, which is the surprisingly hard to avoid root cause of attacks aimed at XML signatures.

How to make XML signatures more secure?

Does this mean it's impossible to properly validate an XML signature? No, it's technically possible. Some of the steps that may be taken in order to increase the trust in XML signatures include:

Applying strict XML schemas, even for the signature node.
Avoiding enveloped signatures by placing signatures outside the signed node.
Using precise selectors such as /pizza/details/ingredients/ingredient instead of relaxed queries like //ingredient.
Considering the library used to work with XML documents high-risk and always, and I mean always, keeping it up to date.

Should you rely on XML signatures?

In reality, thought, it's very hard to expect all these criteria to be met as it requires niche knowledge. And even if you have great specialists, they may still make mistakes, as did people at Microsoft and Atlassian. Similar issues were found in popular Java and PHP libraries.

I must say that when I first worked with XML signatures a couple of years ago it was a humbling experience. I don't know how big my ego would have to be for me to think that I can certainly get it right even though so many smart people got it wrong.

Even some protocols that started as dependent on XML signatures, such as SAML 2.0, later introduced solutions that don't require pristine signature validation. For example, SAML used to rely on signed XMLs being transmitted via the browser from one server to another but now it uses a kind of server to server communication (HTTP Artifact binding) where the sensitive data is sent in the response to the server and not in the request. Doing it this way significantly reduces the attack surface.

That's why even though in theory it's possible to securely verify an XML signature, I believe it's worth keeping in mind that the risk of failing to do so is very high.

How to merge the composer.lock file?

Fri, 14 May 2021 18:37:20 GMT

So you're working on a PHP project using Composer and a merge conflict occurs on the composer.lock file. How do you merge it? Well, it may sound a bit strange, but the short answer is: You don't.

The composer.lock file is meant to be generated by Composer. It must not be modified in any other way, or it'll become corrupted, and you'll end up installing random stuff. Sometimes. On some machines. Yeah, I know, it sounds horrible, doesn't it?

Composer should be the only tool used to change the composer.lock file. It means it cannot be altered in PhpStorm or Sublime Text. Moreover, even Git should not be used to merge changes into it! Even though it looks like yet another text file, Composer relies on its integrity. And to Git it's, well, just another collection of lines. That's why it makes sense to mark it as a binary file in Git's .gitattributes file:

composer.lock binary

But then what do you do when a conflict does occur? There are two ways to tackle that.

Assuming that you have amazing tests you can completely rely on, then your first option is to accept the changes to the composer.json file, completely remove the composer.lock file, and regenerate it from scratch by running the composer install command. It'll "work", but frankly, that's not why we have the lock file in the first place. It'll result in all the dependencies being updated. And I mean all of them. Of course, they'll be updated only within the constraints set by the composer.json file, but still.

The more down-to-earth approach is to look at what changed in the commit you want to merge and reapply those changes by running commands such as composer require and composer remove. It'll give Composer a chance to protect the integrity of the dependencies and it won't automatically bump the version of everything else.

To sum it up: treat the composer.lock file as if it were an image. You wouldn't use a line-based merging tool to merge different images. And you wouldn't manually edit them in a text editor either (unless you're a 10x developer, of course 😉).

If you'd like to read more about it, there's a great chapter of the docs that touches upon the topic of resolving merge conflicts.

React hooks... Oops! Part 4 - API responses get out of sync with the state

Sun, 28 Mar 2021 10:37:20 GMT

In the previous post from the React hooks... Oops! series we made it clear that placing values in the dependency list of useEffect doesn't turn them into observables.

Today we'll examine why the state may get out of sync.

React made working with the DOM API a breeze! Thanks to its simple, declarative nature, it is no longer a challenge to correctly synchronize the DOM with the state of the application. It simply works, and that's awesome! 🎉

But the DOM API is not the only API there is. In fact, many React apps end up fetching data from some other APIs, like a REST API. React itself doesn't provide us with any tools designed specifically for data fetching. But hey! It's nothing new! So it shouldn't be a problem, right? 🤔 Sadly, if we're not careful enough, API responses may get out of sync with the state of the app! 😨

Let's maybe have a look at a concrete example. This is the app we're building.

There are tabs representing different characters. Clicking a tab fetches the surname of the selected character from a backend API.

This is the code of the card component:

function CharacterCard({ characterId }) {
  const [character, setCharacter] = React.useState(null);
  React.useEffect(
    function () {
      fetchCharacter(characterId).then(setCharacter)
    },
    [characterId]
  );
  return character && (
    <article>
      <h1>
        It's {character.firstname} {character.lastname}
      </h1>
    </article>
  );
}

You might have already seen plenty of examples like that. useEffect is responsible for actually calling the fetchCharacter function and then useState holds the received data.

The good news is that it works most of the times. The bad news is that it works only most of the times.

This is what happens when the network connectivity is unstable and the user clicks quickly.

The selected tab is the one for Murl, but the user sees Milan's data. It's buggy! 🐛 Why?

useEffect's dependency array makes it possible to synchronize triggering the effect with some state. In our example, every time the characterId changes (and the component re-renders), it calls fetchCharacter. What happens next happens outside of React. The results of async functions triggered inside useEffect are not synchronized with the effect's dependency array. For us it means that React will call fetchCharacter and then receive the data through setCharacter, but when and in what order it happens depends on the network.

The app is buggy because even though the user first clicked the tab for Milan and only then the one for Murl, the HTTP response for Milan came after the one for Murl. The effects are triggered in the right order, but the results come in an unpredictable order. And because we simply update the state of the card when we get a response, making the wrong assumption that it'll be in sync with the state of the tab, there's a bug in the app.

How to fix it?

One way would be to use the useRef hook and place the current characterId in that ref, so that in the .then callback of the Promise returned by the fetchCharacter function we can check if we're still interested in the response for that particular character. So many moving pieces! 🤯

Lucky us, there's a better way. It's true making API requests is nothing new and that it shouldn't be hard. It's just that the built-in hooks are low-level building blocks, designed to build on top of them, and not something optimized for specific use cases. That's why if we want to query the backend, we're better off using hooks designed specifically for that.

React query is a library that makes this and many other problems go away.

The same component refactored to use a high-level hook designed specifically for working with APIs looks like this:

function CharacterCard({ characterId }) {
  const character = useQuery(["character", characterId], fetchCharacter).data;
  return (
    <article>
      <h1>
        It's {character.firstname} {character.lastname}
      </h1>
    </article>
  );
}

One hook. One line. Zero bugs.

Judging from my professional experience, react query dramatically decreases the amount of code you have to write, makes apps less buggy and even faster!

A friend of mine once put it that way:

Where has this been my whole life?

I hope you'll give react query a go!

Stay tuned for the next post!

It's 2020. Why is testing front-end applications so hard?

Fri, 15 May 2020 08:37:20 GMT

In his book "Thinking, Fast and Slow", the Nobel Prize-winning psychologist Daniel Kahneman writes about the idea of substitution. It's a mechanism that enables us to quickly answer difficult questions by replacing them with similar, but easier questions. For example, when asked if it makes sense to invest in Apple stock, we may say whether we like Apple products, without even noticing that we didn't answer the original question. Recently it occurred to me that this phenomenon may be observed in testing front-end applications as well.

The front-end world is evolving rapidly. We can see people from various backgrounds getting into it. Some of them, including myself, used to be back-end developers. When facing a serious challenge, such as "How do I test this application?", having some experience in a similar field puts us at risk of unconsciously answering a different question, like "Which parts of this application do I know how to test?".

If we know how to test a method returning an integer, we may try to interact with a front-end application as if it were an object with a method returning an integer. For example, we may count the number of table row nodes in the DOM, without even checking that they are rendered one after another instead of on top of each other. Or if we are no strangers to string comparison, we may settle for checking if the value of a DOM Text node matches our expectations, without verifying that the font is readable.

Does that make the tests we write useless? Not necessarily. They may be testing something after all. When in doubt, I ask myself whether I'd still write similar assertions even if the code I think I'm testing didn't run in a browser. Looking from 30 000 feet, would the tests still look the same, even if the app was a command-line utility or a REST API? If yes, then I may be testing everything but the very front end of my front end. And if that question doesn't help, I use the font-weight benchmark for front-end tests.

What does the font-weight property tell us about automated testing in the front-end world?

Mon, 09 Mar 2020 08:37:20 GMT

I've been lucky enough to start my career as a software developer in the era when automated testing was already a thing. If not always the reality, then at least a thing people talked about. And that's why since my very first year as a professional developer, inspired by Kent Beck's and Uncle Bob's books, I've been trying to automate testing the systems I worked on, with varying degrees of success.

After a couple of years of working as a back-end developer, I often knew which testing strategies would pay off, and which ones would bite me. I didn't feel overwhelmed or lost on a daily basis anymore. Actually, I felt pretty proficient at my job. I knew how to leverage automated tests to fill me with confidence that the software I was building actually did what I expected it to do. But then I grew interested in front-end web development, with all its quirks and wonders. The period when I handed a ThinkPad back, got a Mac, and tasted the famous Starbucks coffee marked the beginning of me as a professional front-end developer.

But something wasn't right. I didn't feel as safe as I used to. Initially, I blamed it on various non-technical aspects of my new job, such as joining a new company or moving to a new country. Or maybe it was the coffee? However, soon I realized that the real issue was an industry-wide lack of a quality safety net. And by the industry, I mean the front-end industry. We are the people tasked with getting some data, presenting it to the user, responding to their input and possibly sending some data back to the back end. Yet, the most popular testing approaches closely resemble what we developed to test back-end systems, with just a hint of the front end.

To help me differentiate front-end testing tools from some sort of back-end testing tools or half-baked front-end testing tools, I developed a little benchmark, and I think you may find it helpful as well. Before I reveal it to you, I'd really like to highlight the fact that it relies on the assumption that the purpose of automated tests is to tell us when the behavior of the system changes and in the same time let us change the implementation, as long as the behavior stays intact, without any need of touching the tests.

Here comes the font-weight benchmark for front-end testing tooling.

Imagine that as part of your job you wrote the following CSS code:

font-weight: bold;

What would happen if you refactored it to use a number instead of a word?

font-weight: 700;

It's good if your tests still pass. It proves that they are not tightly coupled to the implementation details. In the end, both bold and 700 lead to the same behavior of your app. But if your tests fail, then it means they are tightly coupled to the implementation and will, in fact, make any refactoring harder.

Finally, what would happen if you made a mistake when refactoring the code above and instead wrote this?

font-weight: 800;

It's good if your tests fail now. It means they are actually testing what the front-end development is all about, which is rendering the right pixels in the right order and at the right time. But if they keep passing, then it is a sign that the front end of your front end may have 0% test coverage.

The new CSS Grid will change the way you think about layouts. Here's why.

Tue, 21 Jan 2020 10:37:20 GMT

The first CSS Grid Layout made it possible to divide the area of an element with horizontal and vertical lines. These lines dictated the size and position of its children.

But this is going to change.

To understand why, and most importantly, how, let's recap the way things worked in the first version of the grid.

For instance, this card could be one grid:

The HTML code looks simple. It's just one parent with two children:

<div class="card">
  <img class="avatar" src="https://picsum.photos/id/10/200/200"/>
  <h2 class="card__text">Lorem Ipsum</h2>
</div>

The CSS code makes the parent element a grid:

.card {
  display: grid;
  grid-template-columns: max-content 1fr;
  grid-gap: 10px;
  align-items: center;
}

The grid lines are as follows:

Another card could be another isolated grid:

And the header could be yet another grid, built in the same way:

Let's put the previously discussed components together, just like that:

The parent element is yet another grid, just to define the spacing among the cards and the header:

.grid {
  display: grid;
  grid-gap: 20px;
}

It doesn't look bad.

However, it's quite optimistic to assume that in real life all the cards will have identical content. So let's make it a bit more realistic:

That's the problem I wanted to show you. As we can see, the texts are not really aligned with each other:

Luckily for us, the new CSS Grid Layout provides an elegant solution to this ugly problem!

We can define a single grid line that will be used to divide all the cards and the header together, on a higher level, above the individual elements:

First, let's define one grid at the parent's level instead of defining multiple grids for each child:

.grid {
  display: grid;
  grid-template-columns: max-content 1fr;
}

Then it's enough that we use the new subgrid option. It means that both the .header and the .card elements don't define their own grid lines, but instead, they inherit them from their parent element:

.header {
  /* 1 / -1 to make it span across the whole container. */
  grid-column: 1 / -1;
  grid-template-columns: subgrid;
}

.card {
  grid-column: 1 / -1;
  grid-template-columns: subgrid;
}

And... that'd be it!

The complete code of this example may be found on CodePen.

Subgrids from CSS Grid Level 2 enabled us to define cross-component alignment rules that work well even for dynamic content.

Just to be fair, I got to say that designers have been talking about it for ages! Maybe they called it differently, like keylines in Material Design, but anyway, it's nothing new to them!

So is the new specification a spacing nirvana? Not yet. By looking at some ongoing discussions about possible extensions of the subgrid we can tell that there's still some room for improvement. But it's already a big step towards unifying the ways designers and developers think. Now when somebody says "We need to align these components to this line." we can actually code "this line".

How to prevent intermittent test failures

Sun, 03 Nov 2019 18:37:20 GMT

Imagine a warm summer afternoon. You're chilling out, enjoying a glass of refreshing lemonade. All you can hear are distant chatter and birds singing.

Suddenly, there's a buzzing sound! A fly passes right next to your head. Focus on that insect! Try not to lose sight of it as long as you can.

What was its trajectory? Did it fly straight from point A to point B? Of course not! No insect ever does it! Observing it for as little as a couple of seconds was enough to witness it flying all over the place.

Why does it do it? Is the fly having problems with flying? No, quite the opposite!

In fact, it exhibits extraordinary maneuverability! And it literally uses it to fight for its life! How? Random changes in direction make the fly harder to catch, effectively deceiving predators.

But what's a fly's gain is a bird's loss.

Coping with unpredictability isn't a challenge that only birds face. It also affects us, the IT professionals. We've all seen automated tests failing, just to pass correctly after nothing but a restart. Even when everything works fine on our machine, we can never know if it will work in the CI environment. Once we spot the problem, we may discover that the issue is somehow related to a statement like "wait 100 ms". How do we solve it? Well, changing "100 ms" to "200 ms" may temporarily fix it, but it doesn't guarantee that it won't happen again. More importantly, it doesn't silence our inner voice telling us that this may not be the most professional thing to do. In the end, we want our test suite to tell us when something is broken. We don't want the tests to be the thing that breaks. When they fail, our reaction should be "Oh no, the app broke!" and not "Oh no, the tests broke!".

Let's say that we have an app that fetches a list of items. Before the list is ready, the user can see a spinner. It takes some time for the list to load, and we can use that time to verify if the spinner meets the requirements. Is it displayed? Is some button disabled when the list is being loaded? Are the previous results hidden?

The idea of such a test is simple. However, in reality, it tends to be more than trivial to build. One thing, in particular, may pose a challenge - timing. How can we make sure that the test case has enough time to perform all the necessary assertions before the data is loaded and the screen changes? A common workaround to that problem is to delay the response from the mocked service for some number of milliseconds and hope that it will be enough. Unfortunately, we can never know what's the right delay. 100 ms? 84 ms? 1 second maybe? It depends on plenty of things we cannot control, such as the machine the tests run on and even the current load of that machine. A little slowdown of the test runner may be enough for the mocked service to respond and make the app transition to a different state before the test finishes making assertions about the loading state.

A term to describe our problem was already coined over half of a century ago. It's a race condition. It happens when the correctness of a process depends on the order of events we cannot control. And similarly to betting on horse racing, relying on tests waiting an arbitrary number of milliseconds is more like gambling than a profession.

Imagine how much easier our lives would be if the test and the mocked service communicated instead of competing with each other. There would be no race conditions if the test suite could just tell the mock "Hey, I finished all the assertions for now and I'm ready for you to give the app the data it asked for.”. We could see an increase in multiple areas spanning from the stability of individual test cases, through the performance of the whole pipeline, to our - developers - wellbeing. Just think about how comfortable would it be if no unexpected build failure would ever delay a deployment again!

I got something that may give you relief. In Endpoint Imposter you can assign what's called a release key to any mocked response.

{
  request: { path: '/todos' },
  releaseOn: 'todos',
  response: { json: ['a','b','c'] }
}

The mocked service won't give the app the items it asked for unless the test gives it permission to do so by issuing a request to http://mock/admin/release?session=sessid&key=todos.

That way you will always have enough time to make all the necessary assertions about the loading state before the screen changes.

It's that simple.

If there's one thing I'd like you to take away from this post, it's to let Endpoint Imposter make it easy for you to catch bugs.

React hooks... Oops! Part 3 - an effect doesn't run again when its dependencies change

Mon, 21 Oct 2019 10:37:20 GMT

In the previous post from the React hooks... Oops! series we talked about a case where an effect is re-applied, even though the dependencies are still "the same". We expected it to run again only if the dependencies changed, but it ended up running multiple times with the same values. Fortunately, it was enough to learn a little bit about how dependencies are compared, and it became clear what made React re-apply it. 🥳

If you're reading this post, you might have already discovered that the array of dependencies is tricky. It seems to be pretty simple on the surface. After all, it just tells React to "re-run this function when one of these values change", right? Well, that's not exactly what happens. The truth is that changing a value in the dependency list is not enough for React to re-run the effect!

How come? 😰

Let's have a look at a very simple example, where everything works as expected:

function App() {
  // Just some local state:
  const [typed, setTyped] = useState("");

  // An effect synchronized with that local state:
  useEffect(
    () => console.log("an effect of", typed),
    [typed]
  );

  // The view:
  return (
    <div>
      You typed: {typed}
      <br />
      <input
        type="text"
        value={typed}
        onChange={(e) => setTyped(e.target.value)}
      />
    </div>
  );
}

Looking at this component, it's tempting to say that the () => console.log("an effect of", typed) fragment re-runs when typed changes. But that's a simplification.

Why? 🤔

Before I present you with an example that illustrates the problem, I'd like to show you an alternative version that happens to work, even though there's already a bug waiting to surface.

Here we still use state to control the input field, but the effect is synchronized with a value read directly from a reference to the DOM element.

function App() {
  // Nothing changed here,
  // it's still just some local state:
  const [typed, setTyped] = useState("");

  // A ref to the input element:
  const inputRef = useRef();
  // The value read directly from the DOM node:
  const inputValue = inputRef.current
    ? inputRef.current.value
    : "";
  // An effect synchronized with the value
  // read from the DOM node:
  useEffect(
    () => console.log("an effect of", inputValue),
    [inputValue]
  );

  return (
    <div>
      You typed: {typed}
      <br />
      <input
        type="text"
        {/* The value of the input comes from the state: */}
        value={typed}
        {/* Typing updates the state: */}
        onChange={e => setTyped(e.target.value)}
        {/* We also set the ref: */}
        ref={inputRef}
      />
    </div>
  );
}

Everything "works", but that's just a happy accident!

What's the problem with this code?

Imagine we don't want to that funny You typed: ... message. It seems like we can just remove it together with the state used to hold its value, right?

function App() {
  // This fragment stays the same:
  const inputRef = useRef();
  const inputValue = inputRef.current ? inputRef.current.value : "";
  useEffect(
    () => console.log("an effect of", inputValue),
    [inputValue]
  );

  // No more local state:
  return <input type="text" ref={inputRef} />;
}

Whoa, the effect doesn't work anymore, even though we haven't changed any code that'd be directly related to it! 😲

Why did it work before, but doesn't work now? It's because putting values in the dependency list doesn't turn them into any sort of observables. React won't be notified when they get mutated. Thus even when the value changes, the effect is not re-applied. Previously it worked only because the component was re-rendered due to the local state update.

To make it even more clear, let's try to bring back the You typed: ... message, but this time it won't be done correctly:

function App() {
  // This fragment stays the same:
  const inputRef = useRef();
  const inputValue = inputRef.current ? inputRef.current.value : "";
  useEffect(
    () => console.log("an effect of", inputValue),
    [inputValue]
  );

  return (
    <div>
      {/* We try to render the current value of the input: */}
      You typed: {inputValue}
      <br />
      <input type="text" ref={inputRef} />
    </div>
  );
}

Nothing works. It's now clear that React is unaware of changes that happen outside of its lifecycle and neither the DOM nor the effect is synchronized with them.

Of course, the example shown above is rather simple. In real life, bugs like that may span over more lines. Judging from my experience, they tend to arise around refs and other mutable bags of data that make it easy to forget that if we want React to react to a change, that change must happen within React.

You may find the snippets used in the writing of this post here:

That's all for today, I hope you enjoyed it! 🙂

Stay tuned for the next post!

React hooks... Oops! Part 2 - why does my effect run multiple times with the same dependencies?

Sun, 06 Oct 2019 10:37:20 GMT

The Effect hook enables us to perform side effects, that is to run some imperative, effectful code. For example, we may want to fire a HTTP request after the component appears on the screen.

As we can see in the React documentation, the way we use the effect hook looks like this:

useEffect(fn, deps);

fn is the effectful function, and deps is an array of values it depends on. Every time the component renders, React checks if all the values in the deps array are still the same. If any of them has changed since the last render, fn is run again.

Even though it sounds pretty simple, there are some nuances to it that may lead to bugs or even crashing the browser (tab).

In this post from the React hooks... Oops! series, we'll focus on how the values in the deps array are compared. We'll also have a look at the way how values are compared in a totally different programming language.

Let's start with a simple example:

function App() {
  // Define a little state,
  // just a letter and a flag telling whether it's been updated.
  const [{ letter, updated }, setLetterObj] = useState({
    letter: "A",
    updated: false
  });

  // This function updates the letter.
  const setLetter = letter => setLetterObj({ letter, updated: true });

  // For the sake of clarity we declare
  // that the letter is what the effect depends on.
  const effectDependency = letter;

  // Run a dummy effect that simply logs the effectDependency.
  useEffect(() => console.log("effect of", effectDependency), [
    effectDependency
  ]);

  return (
    <>
      {updated && "New"} {letter}
      {/* Buttons that call setLetter every time they are clicked. */}
      <button onClick={() => setLetter("A")}>A</button>
      <button onClick={() => setLetter("B")}>B</button>
    </>
  );
}

This is how it works:

Please note that even though we click each button, and consequently alter the letter value, multiple times, the effect is re-applied only if the value actually differs from the previous one.

To make it even more clear, let's add a simple counter to our example. The rest of the code remains intact:

function App() {
  // Nothing fancy here, just a number.
  const [counter, setCounter] = useState(0);

  const [{ letter, updated }, setLetterObj] = useState({
    letter: "A",
    updated: false
  });
  const setLetter = letter => setLetterObj({ letter, updated: true });
  const effectDependency = letter;
  useEffect(() => console.log("effect of", effectDependency), [
    effectDependency
  ]);

  return (
    <>
      {updated && "New"} {letter}
      <button onClick={() => setLetter("A")}>A</button>
      <button onClick={() => setLetter("B")}>B</button>
      {counter}
      {/* Clicking this button will increment the counter by 1. */}
      <button onClick={() => setCounter(counter + 1)}>+ 1</button>
    </>
  );
}

Now we can clearly see, that even thought the component is being re-rendered, the effect doesn't run unless the value it depends on changes:

You might have been wondering what's the point of explicitly declaring that letter is the effectDependency. The reason behind it is that now we're going to derive some other value from letter, make it our new effectDependency, and see what happens.

Here we turned a boring dependency like "A" into something much more fun, like "The letter A":

function App() {
  const [counter, setCounter] = useState(0);

  const [{ letter, updated }, setLetterObj] = useState({
    letter: "A",
    updated: false
  });
  const setLetter = letter => setLetterObj({ letter, updated: true });
  // This is the only line that has changed.
  // We build a new string based on the letter string
  // and it's that new string
  // that becomes the effect's dependency.
  const effectDependency = `The letter ${letter}`;
  useEffect(() => console.log("effect of", effectDependency), [
    effectDependency
  ]);

  return (
    <>
      {updated && "New"} {letter}
      <button onClick={() => setLetter("A")}>A</button>
      <button onClick={() => setLetter("B")}>B</button>
      {counter}
      <button onClick={() => setCounter(counter + 1)}>+ 1</button>
    </>
  );
}

The overall behavior hasn't changed. The effect is re-run only when the value of the dependency changes:

All right, so far all the examples exhibit the same behavior. The effect simply doesn't run again if the dependency value doesn't change.

Let's take a look at one more example of a derived effect dependency and see if it follows the same rule:

function App() {
  const [counter, setCounter] = useState(0);

  const [{ letter, updated }, setLetterObj] = useState({
    letter: "A",
    updated: false
  });
  const setLetter = letter => setLetterObj({ letter, updated: true });
  // This time instead of deriving a string, we derive an object.
  const effectDependency = { payload: letter };
  useEffect(() => console.log("effect of", effectDependency), [
    effectDependency
  ]);

  return (
    <>
      {updated && "New"} {letter}
      <button onClick={() => setLetter("A")}>A</button>
      <button onClick={() => setLetter("B")}>B</button>
      {counter}
      <button onClick={() => setCounter(counter + 1)}>+ 1</button>
    </>
  );
}

Here's how it behaves in the browser:

That's something new! Now the effect is re-applied on every render, even when the "value" of the payload stays the same.

Why?

The answer lies in the way how equality is understood. Depending on the data type, it's either value equality or reference equality.

Primitive data types, like strings, are always compared in terms of the value their represent. They may be two different strings, living in two separate parts of the computer memory, yet, if their values are equal, they are considered equal. Here's an example:

> let left = "A"
undefined
> let right = "B"
undefined
> left === right
false
> right = "A"
'A'
> left === right
true

If these were not variables but sticky notes, they would be considered equal if they had the same text written on them.

However, the same rule doesn't apply to objects. Comparing objects is all about the place in the computer memory where they are stored, not about the value they represent. Let's have a look:

> let left = { payload: "A" }
undefined
> let right = { payload: "B" }
undefined
> left === right
false
> right.payload = "A"
'A'
> left === right
false
> left = right
{ payload: 'A' }
> left === right
true

Only after making both references - left and right - point at the very same object, they were considered equal. Imagine left and right are your hands. If you used both of your hands to point at sticky notes, the question would be "Are both of your hands pointing at the very same note?" and not "Do the notes you're pointing at have the same text written on them?".

So how can we trigger an effect that needs an object and not a primitive value?

In this case it's quite easy to build the object inside the effect function. Instead of deriving an object from the primitive letter value outside of the effect function, we simply do it inside it. That way the dependency stays a primitive value and it's compared, well, based on it's value.

function App() {
  const [counter, setCounter] = useState(0);

  const [{ letter, updated }, setLetterObj] = useState({
    letter: "A",
    updated: false
  });
  const setLetter = letter => setLetterObj({ letter, updated: true });
  // It's not effectDependency = { payload: letter } anymore.
  // Instead, the dependency is a primitive value.
  const effectDependency = letter;
  useEffect(
    // Please note how we build { payload: effectDependency }
    // inside the effect function.
    () => console.log("effect of", { payload: effectDependency }),
    [effectDependency]
  );

  return (
    <>
      {updated && "New"} {letter}
      <button onClick={() => setLetter("A")}>A</button>
      <button onClick={() => setLetter("B")}>B</button>
      {counter}
      <button onClick={() => setCounter(counter + 1)}>+ 1</button>
    </>
  );
}

This time the effect 😉 is what we expected:

Alternatively, when deriving the object from a couple of primitive values is not trivial, you may want to consider using Kent C. Dodds's useDeepCompareEffect hook.

It's similar to useEffect, but compares objects in terms of values, not references. That way effectDependency may be a new object with every render and the effect won't be unnecessarily re-applied. Have a look:

function App() {
  const [counter, setCounter] = useState(0);

  const [{ letter, updated }, setLetterObj] = useState({
    letter: "A",
    updated: false
  });
  const setLetter = letter => setLetterObj({ letter, updated: true });
  // We have an object as a dependency again.
  const effectDependency = { payload: letter };
  // Like useEffect, but compares values, not references.
  useDeepCompareEffect(
    () => console.log("effect of", effectDependency),
    [effectDependency]
  );

  return (
    <>
      {updated && "New"} {letter}
      <button onClick={() => setLetter("A")}>A</button>
      <button onClick={() => setLetter("B")}>B</button>
      {counter}
      <button onClick={() => setCounter(counter + 1)}>+ 1</button>
    </>
  );
}

With useDeepCompareEffect, the dependency may be an object and still be compared in terms of its value:

To sum it up, when declaring effect dependencies, you should remember that only primitive data types are compared in terms of values and that's why it's safer to stick to them. However, if you really need an object (or an array, which is actually an object as well), then you may consider one of these 3 solutions:

deriving it from some primitive values inside the effect function
swapping useEffect for the useDeepCompareEffect hook
ensuring that the reference to the dependency object changes only when its value changes

I don't know how about you, but I feel like the meaning of equality is pretty tangled in JavaScript. Interestingly, there are some programming languages that make it a whole lot simpler. Let's try to define and compare two strings in ClojureScript:

;; like let left = "A" in JS
(def left "A")
;; like let right = "A" in JS
(def right "A")

;; like left === right in JS
(= left right) ;; true

left and right have been compared in terms of their values. Now, let's try comparing a key-value map:

;; like let left = { payload: "A" } in JS
(def left {:payload "A"})
;; like let right = { payload: "A" } in JS
(def right {:payload "A"})

;; like left === right in JS
(= left right) ;; true

Yay! That's like comparing objects by value, and built into the language! Let's try something even more crazy, that is comparing sets (which are unordered collections of unique elements):

;; like let left = new Set(["A", "B", "C"]) in JS
(def left #{"A" "B" "C"})
;; like let right = new Set(["C", "B", "A"]) in JS
(def right #{"C" "B" "A"})

;; like left === right in JS
(= left right) ;; true

Wow! 😲 It supports comparing sets by value without the need of using any extra libraries!

You may find the snippets used in the writing of this post here:

Stay tuned for the next post!

React hooks... Oops! Part 1 - Introduction

Mon, 30 Sep 2019 10:37:20 GMT

Familiarity makes us feel safe and confident. Yet, what's just familiar isn't exactly equal.

I believe that's the very reason why it's both so tempting and dangerous to start relying on a new tool, regardless how familiar does it seem to be, without first understanding what makes it different from what we already know.

React hooks are one of these new, shiny tools. Not only they are hip, but also some of them look pretty familiar and easy to use, like the useState hook.

But there's a catch to it - they are more of low-level building blocks that enable us to construct our own abstractions than something designed to directly solve everyday problems.

They are intended to be a way for the community to build and share cohesive fragments of logic, not a drop-in replacement for effectful methods in classes.

Of course that doesn't mean that the built-in hooks cannot be useful on their own. If using a handful of them actually solves the problem, that's great! But if I learned anything important about hooks, it's that as soon as I get plenty of them in a single component, I should stop and think whether that's the way to go.

More often than not, multiple interconnected hooks are a sign that there's an abstraction waiting to be extracted. Sometimes it may be possible to use an off-the-shelf hook, and other times, we may need to extract one ourselves.

You known what they say about mistakes. We can learn from them. And I must admit that I learned plenty of lessons that way. In this series, I'm going to tell you about mistakes made when building custom hooks, so that you can avoid them.

The next post from this serise: React hooks... Oops! Part 2 - why does my effect run multiple times with the same dependencies?

What a decent API mocking tool looks like to me

Sun, 29 Sep 2019 15:37:20 GMT

When I worked as a back-end developer, my tasks often included integrating our systems with third-party services. All I needed to do was to communicate with some other server over HTTP(S) and consume the responses.

Now, when my day to day job is being a front-end developer, I often need to fetch and update data on the back-end. All I need to do is to communicate with the server over HTTP(S) and consume the responses.

As you can see, when it comes to consuming APIs, the back end and front end world are pretty similar. It's all about sending requests and receiving responses. But it doesn't mean it's not challenging.

Setting our app to communicate with the real API may be a good way to start, but things get tricky pretty fast. We may soon want to handle not only the happy path but also all the loading and various error states. Because we cannot control the external service, even a manual QA tester may struggle a lot or be unable to reproduce some of these cases. Having reliable, reproducible automated tests is simply impossible.

The will of building robust solutions made me look for a tool that would allow me to create test doubles of APIs. That way I could not only test all the cases that are usually hard to reproduce, but also automate that process.

So, what makes a decent mocking tool?

One of the aspects I was looking for was the scalability of mocks. I didn't want the shortcomings of a mocking utility to ever force me to switch to a totally different tool in the middle of the development process.

Another thing I care about is actually running the code I write. The API specification may be thought as of a contract and assume that it's what the third party is going to deliver. That's why it's relatively safe to mock the API and test our code against that mocked API. However, mocking any sort of a higher-order API client is rather risky. We may ensure that our app communicates with that mocked client properly, but in the end, it's nothing but yet another piece of code we wrote. There's still no way to tell whether it sends the right requests and correctly reacts to the responses it gets.

Then, only the most trivial applications just read data and never update it. Even our beloved To-Do app alters the current list of items. The same request sent twice may produce two different responses and it may depend on a request issued in the meantime. It's a clear sign that a good mocking utility should enable us to mimic stateful behavior. Some test scenarios, especially those involving many components, may fire multiple HTTP requests. If that's how the app works when the users interact with it, then it's totally fine. Modifying the system under the test to fire fewer requests by swapping some internal components for test doubles makes it drift away from what the users actually use, what decreases the real-world test coverage and increases the risk of making wrong assumptions about how things actually work. On the other hand, mocking many endpoints for every test may be tedious. The good thing is that it doesn't have to. Similarly to how we can reuse the implementation of a button, we should also be able to write a mock once and then reuse it in multiple test cases. That way the coverage is high, test-related changes to the app are kept low, and the mocking process is not painful.

It's better to have slow tests instead of no tests, no doubt about that, but it's even better to have fast tests. And that becomes a challenge when asynchronous communication is involved. Some responses may need to be delayed to let the test code make assertions about how does the app behave while loading data. It's then important that they don't slow down all the other tests. To achieve good performance, we should be able to run both the test code and the mock code in parallel.

And last but not least, I wanted a platform-agnostic tool. I don't want to have to learn a new mocking tool just to test an app written in a different language.

I didn't find a tool matching these criteria. So I built one. And today I'd like to share it with you.

It's called Endpoint Imposter and it's a Node.js app.

You define your mocks in a JavaScript file.

module.exports = [
  {
    request: { path: '/todos' },
    response: { json: ['a', 'b', 'c'] },
  }
]

Then, assuming you have npm installed, you run one command in your terminal.

npx endpoint-imposter --port 3000 --mocks ~/my-mocks.js

And now you have a mocked server your system under the test can communicate with!

$ curl http://localhost:3000/sessionId/todos     
["a","b","c"]%

At first glance, it doesn't look much different from other popular solutions. But as soon as your tests grow, you'll notice that it scales pretty well. You can use it to mock your whole back end, including requests modifying data. All that without the need of writing a single function to handle the state. And because mocks are nothing but a JavaScript module, you can reuse them like any other module. Are you like me, that is a bit impatient when waiting for the tests to finish, but still willing to build robust apps? Then you may want to check out Endpoint Imposter's parallel sessions and the manual response release mechanism.

You can find more information in the documentation of Endpoint Imposter.

What do they mean by memoized callbacks and what does useCallback actually do?

Sat, 03 Aug 2019 10:30:20 GMT

When I first read that useCallback returns a "memoized callback" I thought I knew what it meant.

I used both callback functions and memoized functions before so I was like "Ah, okay, it's just memoization.".

Well, it turns out that seeing the word "memoization" and immediately assuming that it means what it usually does was a mistake.

Much to my surprise, useCallback does NOT return a memoized function.

According to Wikipedia, memoization is about limiting the number of expensive function calls by using some sort of a cache.

For example, this is how we can use _.memoize from lodash to memoize a function.

First, we obtain a memoized version of a potentially expensive function (here it's just the double function).

The first time we call memoizedDouble(42), it calls the original double function under the hood and returns its result, which is also stored in the cache.

The next time we call memoizedDouble(42), the result is obtained from the cache. The original double function is not called at all.

We can keep calling memoizedDouble(42), but double will never be called again. Unless the cache is cleared, the results will be fetched from there.

If there's no cached result for some input, the original function will be called once, and then the result will be added to the map.

To sum it up, two functions were created the original double function and the memoizedDouble function. Calling memoizedDouble 4 times with 2 different inputs resulted in only 2 calls of the original double function.

This was memoization. The useCallback hook does something else. Let's see what's that.

Here we have a callback cb that calls the double function. We use useCallback to get a memoized version of the cb callback. The first time the component renders, a new cb is created and the very same cb function is returned by useCallback.

When memoizedCb is called, it calls the original cb callback, which eventually calls the double function.

The next time the component renders, another cb is created. However, because the dependencies passed to useCallback haven't changed, it's thrown away and memoizedCb stays the same cb it was during the first render.

The third time the component is rendered with the same dependencies, yet another cb is created and then thrown away. Calling the memoizedCb results in calling the same, old cb, which then calls the original double function again.

Unless the dependencies change, every render will create a new unused callback, and every call to the memoized callback, which is the old one, will actually call the original double function.

When the dependencies finally change, the memoizedCb also changes.

And similarly to how the previous memoizedCb was calling the first cb, this one also calls the first cb it got since the dependencies changed.

To sum it up, 6 new callbacks were created during the 6 renders. Calling the memoized callback 4 times caused 4 calls of the original callback.

So, if useCallback does neither limit the number of function calls nor functions being created, what is the value it provides?

What helped me to finally wrap my head around it it was to ignore the meaning of memoization. Let's pretend this word doesn't even occur in the documentation.

So far we've focused almost solely on the "memoized" adjective, but we haven't talked about "callbacks" yet. So, what's the purpose of a callback? It's a function that we pass down to some other function and we expect it to be called once something happens, like a query finished or an error occurs. It is a way to establish communication between various pieces of code. The module that calls the callback is not consuming the result, but the code passing the callback down expects to receive a call when an event occurs.

As we can see, side effects are the most important thing when it comes to callbacks. The results usually don't matter that much. What's crucial is that when one piece of code calls the callback, the other one receives the call. We don't want to lose any calls. That's why memoizing a callback would actually cut the communication link between modules in our application!

What useCallback does is limit the number of identical callbacks floating around. As we can see in the picture visible above, across the first 4 renders, when the dependency was the number 42, memoizedCb stayed exactly the same cb function it was during the first render. It wasn't wrapped in anything. The results weren't returned from any cache. All what useCallback ensured was that memoizedCb equaled the first cb since the last time the dependencies changed.

Does it improve the performance? Not on its own. It may actually decrease it a bit, if no other code relies on referential equality of such callbacks.

The common language used by business people, designers, writers, and developers

Tue, 30 Apr 2019 10:37:20 GMT

When business people were explaining their ideas to me, they were often using slides with various boxes and arrows. These diagrams were high-level illustrations of how to complete various business processes and how things may go.

It's easy to understand. The language of boxes and arrows is great to explain ideas.

When UX people were providing me with user flows, they were using the language of boxed and arrows as well. Their work looked like a map, where each screen was an island that might be connected with other islands by bridges named after the interactions leading to the transitions.

It's easy to understand. It worked for them, because it's a great way to capture how the UI changes as the user interacts with the application.

When technical writers were showing me their work, it wasn't all just text. Complex processes were described using drawings of boxed and arrows.

It's easy to understand. Such a documentation is clear to people with different backgrounds.

When I was about to implement a new feature, I loved to grab a pen and a piece of paper and quickly sketch how the data flows and how the behavior changes.

It's easy to understand. Seeing all the important steps and states is a great framework for thinking. It helps to understand what are we supposed to build.

When I was delivering the requirements, the implementation was made solely of text. The desired behavior was achieved by utilising consitions checking if some values are true or not.

It's not easy to understand. Especially taking into consideration the fact that all these boxes and arrows may be thought of as a visualisation of one of the fundamental concepts in computer science - a state machine.

Maybe state machines are purely theoretical or not really useful in practice? By no means! They are already being used in various branches of software development, spanning from video game development to space exploration.

I wish we, the web developers, could leverage the power of this common language.

Dynamic orthogonal regions in state machines

Sat, 13 Apr 2019 10:37:20 GMT

Sometimes just one sub-machine is not enough.

That's why orthogonal regions are so important when it comes to composing state machines. They let us say: here are my 2 sub-machines and I want both of them to be active simultaneously.

For exampe, let's consider a screen with two buttons:

Each button is a graph:

The code associated with the nodes of this graph simply displays a button with the proper text and makes it follow the toggled arrow:

const makeButton = ({text}) => ({dispatch}) => ({handler: makeHandler({
  TOGGLED: () => ({arrow: 'toggled'}),

  RENDER: ({toNode}) => h('button', {
    // Please note that the `toNode` function makes
    // this action target this specific subtree.
    // Otherwise, clicking a button
    // could toggle more than just one button.
    on: {click: () => dispatch(toNode({type: 'TOGGLED'}))}
  }, text)
})});
const Button_On = makeButton({text: 'On'});
const Button_Off = makeButton({text: 'Off'});

const Button = {handler: defaultHandler};

The buttons then become orthogonal regions:

It means both nodes are active and equaly important.

The code associated with this dynamic composite may consume the results produced by its children. Here we are placing what they rendered in a div:

const main = {
  handler: makeHandler({
    RENDER: alterResult(res =>
      h('div', [
        res.Lights,
        res.Temperature,
      ])
    ),
  }),
};

// Usually you want this part to be automatically generated
// with rosmaro-tools.
// Here it's been left to highlight the issue
// with a static list of orthogonal regions.
const bindings = (opts) => ({
  'main': main,
  'main:Lights': Button,
  'main:Lights:On': Button_On(opts),
  'main:Lights:Off': Button_Off(opts),
  'main:Temperature': Button,
  'main:Temperature:On': Button_On(opts),
  'main:Temperature:Off': Button_Off(opts),
});

This technique is very helpful in avoiding state explosion.

But it's limited. It's static. We need to declare in the graph that there are exactly two orthogonal regions: Lights and Temperature. This cannot be changed while the machine is running. Imagine a multiplayer game suitable only for just 2 people, or even worse, a ToDo app that always shows exactly 2 items. It wouldn't be helpful at all!

To overcome this limitation when using a state machine library that's not flexible enough, developers often create many completely separated state machines and then rely on some other machanism to wire them up to the main machine. This may do the job, but it has its cons, for example:

The need of manually creating and destroying extra instances of state machines.
Switching between automata-based programming and some other programming paradigm, like object oriented programming or a framework, like React.
No more tools to easily share and update the external state of the parent node.
Working with a dynamic list of orthogonal regions becomes a lot harder that working with a static list of orthogonal regions.

Good for us, an elegant solution has already been described in the famous paper on statecharts by Prof. David Harel. It's all about dynamically repeating a single orthogonal region based on a value read from the external state:

Let's see how this feature is implemented in Rosmaro.

Instead of manually drawing a fixed number of orthogonal regions, we create a dynamic composite and select the node we want to repeat:

Then, we define a function of the context that returns a dynamic list of children:

const main = {
  // This function returns the list of orthogonal regions.
  nodes: ({context}) => context.switches,

  handler: makeHandler({
    RENDER: alterResult(res =>
      // Instead of manually picking `Lights` and `Temperature`,
      // we just render all the results.
      h('div', values(res))
    ),
  }),

  // For the purpose of this presentation,
  // we put two values in the context.
  // In real life applications,
  // the context may be populated as a result of user interaction.
  lens: () => initialValueLens({switches: [
    'Lights',
    'Temperature',
  ]}),
};

const bindings = (opts) => ({
  'main': main,
  // 'main:child' is the node that is going to be repeated.
  'main:child': Button,
  'main:child:On': Button_On(opts),
  'main:child:Off': Button_Off(opts),
});

Dynamic composites have many benefits when compared to statically defined orthogonal regions, for instance:

The framework creates and scraps sub-machines for us in the correct moment.
There's no need to switch between different mental models.
The external state may be consumed and altered in the same way like when the list is static.
We don't need to build any custom plumbing to communicate between machines. We still have just one statechart and all the rules that apply to following arrows and working with the context stay intact.

The difference is huge. If it were a template language, a static list of orthogonal regions could be compared to a static HTML file:

<ul>
  <li>Carrot</li>
  <li>Pepper</li>
</ul>

While a dynamic one looks more like this:

<ul>
  {veggies.map(({name, id}) => (
    <li key={id}>{name}</li>
  )}
</ul>

Thank you for reading this brief introduction to dynamic composites! It was my pleasure to share this with you, because I do really find this technique amazing! When combined with other powerful tools, like lenses and a dispatch mechanism based on state machines, it makes things like building a ToDo app without a single boolean value or even a variable totally doable!

What did we lose when we moved to Redux?

Mon, 08 Apr 2019 13:37:20 GMT

In simple procedural programming we used IFs to choose between code blocks operating on data structures.

That's how a data structure could look:

let shape = {
  type: 'circle',
  r: 100
}

And this could be a procedure operating on it:

function makeBigger(shape) {
  if (shape.type === 'circle') {
    shape.r = shape.r * 2;
  } else if (shape.type === 'rectangle') {
    shape.a = shape.a * 2;
    shape.b = shape.b * 2;
  }
}

Such a little piece of code was so straightforward that it was possible to understand it even without knowing JavaScript. That was a big plus!

However, experience showed that IFs like the one visible within the body of the makeBigger procedure were repeated multiple times in other areas of the codebase. For instance, in a procedure meant to draw a shape:

function draw(shape) {
  if (shape.type === 'circle') {
    // The logic responsible for drawing a circle.
  } else if (shape.type === 'rectangle') {
    // The logic responsible for drawing a rectangle.
  }
}

This is where object oriented programming came to the rescue. It provided a dispatch mechanism that associated procedures with data structures.

For instance, there could be classes representing circles and rectangles:

class Rectangle {
  constructor(a, b) {
    this.a = a;
    this.b = b;
  }

  makeBigger() {
    this.a = this.a * 2;
    this.b = this.b * 2;
  }

  draw() {
    // The logic responsible for drawing a rectangle.
  }
}

class Circle {
  constructor(r) {
    this.r = r;
  }

  makeBigger() {
    this.r = this.r * 2;
  }

  draw() {
    // The logic responsible for drawing a circle.
  }
}

This approach not only made the code more coherent by grouping procedures that were closely related to each other, but also saved us from constantly examining the type of structures we were working with. It meant no more if (type === 'cicle') nor if (type === 'rectangle'). We simply put the code related to circles into the Circle class and the one that was all about rectangles into the Reactangle class. Then it was enought to call someShape.draw() and the proper implementation of draw was selected for us based on the type of someShape. Neat!

But it wasn't all roses. It was soon that we discovered how difficult it was to synchronize local state changes with other state changes and with updating the user interface.

Looking for a way to solve this issue resulted in a shift to more declarative and functional programming.

The popular React Redux architecture defined views in a declarative manner, so that developers didn't need to manually trigger updates of the UI when the state changed. Also, state updates were happening in a more controlled way.

Unfortunately, in terms of function dispatch, Redux didn't offer more than the procedural approach. The subscribe method left us with a data structure we needed to manually inspect in order to select the proper branch of code. It was quite common to see IFs like this one repeated over and over again both in the reducers and in the render function:

if (isFriend) {
  if (hasEaten) {
    // What to do when it's your friend and it has already eaten.
  } else {
    // What to do when it's your friend but it hasn't eaten yet.
  }
} else {
  // What to do when you're not a friend. 
}

Putting great emphasis on declarative views and immutable data structures proved to be beneficial, no doubt about that. Nevertheless, I believe that there are still some valuable techniques we can learn from object oriented programming when it comes to function dispatch. That's especially true when the decision depends not only on the data type, what's usually indicated by some sort of a type* property, but also on events that occurred in the past, which like to hide behind boolean flags such as has* or is*.

I'd like to present a dispatch mechanism that identifies the ability to respond differently to the same action as one of its key purposes. And all that without a single boolean value!

When is it useful? Just think of a RENDER action. It's always the same action, and yet, depending on the actions consumed in the past, we may want it to return different results.

In this system, functions are assigned to nodes of a state machine, what is somehow similar to how methods are associated with types of objects.

It's heavily inspired by both the state design pattern we know from object-oriented programming and functional front end architectures, like The Elm Architecture.

The current behavior of a model is defined by the currently active node.

To alter it, the active node returns an arrow describing what has just happened:

PIZZA: () => ({
  result: `Tasty`,
  arrow: `ate`,
}),

It makes the state machine transition to the node this arrow is pointing at.

The control flow reflects the hierarchical structure of the state machine. Parent nodes are capable of changing the way their children are called. They may also modify the result:

PIZZA: alterResult(r => `${r}, my friend!`),

Wrapping the result of calling the child node turns out especially helpful when composing UI components.

Speaking of user interfaces, recently I released a screencast showing the complete process of using automata-based programming to build a wizard application. If you like this form, you may find it a nice introduction to this dispatch mechanism.

Consuming and updating the state object with Ramda lenses

Sun, 03 Feb 2019 10:37:20 GMT

When I was designing a new major release of Rosmaro, I wanted to make it as modular as possible. I totally understood why component composition in React was so important and that's why I strived to make Rosmaro models easy to compose as well. Another aspect I cared a lot when I was building the most modular Rosmaro so far was high cohesion. In order to avoid jumping from one place to another, I wanted to group things that change together and separate those that are not related to each other. So I had two, very ambitious goals: modularity (what means decoupling) and cohesion (what means smart decoupling).

Such a task was challenging, but it somehow felt like a breath of fresh air, because it was nothing like my day to day work. Instead of just making use of the knowledge and skills I already had, I needed to come up with an idea that was at this point unknown to me.

The Internet, and computers in general, are wonderful. I love to use them and I owe some of the most wonderful memories and feelings to them. But sometimes, when I need to simply think about a hard problem, I like to escape from them. My thoughts often tend to be visual and I find it somehow inspiring and pleasant to sketch things on paper or on a whiteboard, if I happen to have one around.

That day, when I wanted to find an answer to the question how to make Rosmaro models easy to compose and coherent in the same time, I decided to grab a pen and a couple of sheets of paper and go to the garden. Back then, I was living in the sunny city of Santa Cruz de la Sierra. Sitting under a palm tree, apparently inspired by the beauty of it, I had one of these aha moments! I got the idea to use a pair of symmetrical functions - one would map from form A to form B, and the other one would map from form B to form A. Unfortunately, I didn't know I just reinvented the concept of lenses. If I knew, it would save me some time. On the other hand, it was really nice to spend some time in that garden.

For a short period of time, Rosmaro shipped with its own implementation of lenses. It was like that until I discovered Ramda which is a wonderful functional JavaScript library that provides a tooling for working with lenses. In this post, I'll do my best to share with you all the reasons why I find (Ramda) lenses so appealing.

Regardless our framework of choice, it's quite common nowadays that there's some object representing the data-related state of the application. For example, it may look like this:

const state = {
  type: 'flat',
  area: 42,
  tenant: {
    name: 'Łukasz',
    pet: {
      type: 'Small animal',
      name: 'Kubuś',
    },
  },
};

If you're wondering whether I was recently looking for a flat, then you must know you're right. Ah, and when I was a kid, I had a guinea pig named Kubuś.

Let's get started! We're gonna start with something simple, that is a lens that will allow us to see the tenant property.

This is how we build the lens with Ramda:

const tenantLens = lensProp('tenant');

And this is how we "view" the state through this lens:

view(tenantLens, state)

It gives us the value of the tenant property:

{ name: 'Łukasz', pet: { type: 'Small animal', name: 'Kubuś' } }

The illustration visible below is my attempt of visualizing this process of zooming in with a lens:

There's some big picture with many things, but when we look at it through this particular lens, all we can see is a small portion of it, magnified.

If the big picture changes and we look at it through the lens again, the magnified portion reflects this change:

So far what we've seen is very much like a property selector. That's totally true that we could do something like state.tenant as well and get the same result. However, the power of lenses lies in their bidirectional nature. What it means is that they don't only reflect changes in the source, but also apply changes in the magnified portion to the source. Visually, it would look like this:

In the code, it looks like this:

  set(
    tenantLens,
    {
      name: 'Łukasz',
      pet: {
        type: 'Small animal',
        name: 'Kubuś'
      }
    },
    state
  )

It gives us a new, updated object:

{
  type: 'flat',
  area: 42,
  tenant:     {
      name: 'Łukasz',
      pet: {
        type: 'Small animal',
        name: 'Kubuś'
      }
    }
  }

As we can see, it's possible to modify the zoomed in part and have this change applied to the source. The difference when compared to, let's say, mutable object-oriented programming, is that in the functional approach we aren't actually modifying any existing structure. Instead of that, a new, slightly different variant is created. However, the similarity to getter and setter methods clearly stands out and that's why lenses are often called functional getters and setters.

To illustrate how multiple lenses may be put together to create a telescope, we're gonna focus on the type of my pet. Even though it's technically possible, at least in the world of computers, to create a single lens that does it, we're gonna benefit more from building a telescope, that is a construct made of multiple lenses, because each of these lenses may be then reused in another telescope.

Let's start by creating a three lenses:

// Focuses on the `tenant` property.
const tenantLens = lensProp('tenant');
// Focuses on the `pet` property.
const petLens = lensProp('pet');
// Focuses on the `type` property.
const typeLens = lensProp('type');

Yay! Now we have everything what's needed to put together a telescope! 🔭

const tenantPetTypeTelescope = compose(tenantLens, petLens, typeLens);

We use the telescope in the same way we use an ordinary lens.

Both for reading:

view(tenantPetTypeTelescope, state)

that gives:

'Small animal'

and for writing:

set(tenantPetTypeTelescope, 'Guinea pig', state)

that updated only the very property the telescope is directed at:

{
  type: 'flat',
  area: 42,
  tenant: {
    name: 'Łukasz',
    pet: {
      type: 'Guinea pig',
      name: 'Kubuś'
    }
  }
}

Trying to discover what are lenses made of, we're gonna manually construct a lens that focuses on the area of the flat. Using the lensProp factory function, it's trivial to build it:

const areaLens = lensProp('area');

It's trivial, yet cryptic. Let's decompose it one level down:

const areaLens = lens(
  prop('area'),
  assoc('area'),
);

In the snippet visible above we're using the lens factory function. We pass it two functions:

the area property "getter" function, that simply reads the value of the area property
the area property "setter" function, that creates a new version of an object with the area property set to the value we pass to it

To be honest, I must admit, that when I first saw such an example it was still a bit enigmatic to me. It was only when I implemented both the getter and the setter functions myself that I really understood how to construct lenses. Going deeper, let's do the same with our areaLens example:

const areaLens = lens(
  wholeObject => wholeObject.area,
  (smallPiece, wholeObject) => ({ ...wholeObject, area: smallPiece })
);

The first function, that is the getter, takes one argument, that is the whole state object, and simply returns the area property. Very straightforward. The second function, which is the setter, is a bit more complex, as it gets two arguments: a small piece and the whole object. The whole object is meant to be the very same thing we passed to the getter function, which in our case is the whole state object (wholeObject). The small piece is supposed to be an updated version of the value returned by the getter (wholeObject.area). Only then the change to the wholeObject.area property may be applied to the wholeObject.

This is how this lens works, regardless the way it's constructed:

view(areaLens, state);
// output:
42

set(areaLens, 52, state);
// output:
{
  type: 'flat',
  area: 52,
  tenant: {
    name: 'Łukasz',
    pet: {
      type: 'Small animal',
      name: 'Kubuś'
    }
  }
}

Now, that we know lenses are not magic, but just two functions to map in and map out, let's try to do some even more interesting. So far we've been just zooming in and zooming out, but the cool thing is that we're not limited to just this. In the same way mirrors in a hall of mirrors don't need to reflect the reality, our lenses don't need to be symmetrical. They may cast a projection that's different than the fragment of the source image we're looking at. Please note that little bump on the surface of the lens. It's making the triangle shape in the source image being projected as a spherical one. And because our lenses are bidirectional, an update to the "distorted" projection will be reflected in the source.

For a more concrete example, let's try to enhance our areaLens in such a way it changes the unit from square meters to square centimeters.

const areaLens = lens(
  wholeObject => wholeObject.area * 10000,
  (smallPiece, wholeObject) => ({ ...wholeObject, area: smallPiece / 10000 })
);

Now we can treat the area like it were in square centimeters, both when reading and when writing, and in the whole state it will always be represented in square meters.

view(areaLens, state);
// output:
420000 // square centimeters

set(areaLens, 520000, state); // square centimeters
// output:
{
  type: 'flat',
  area: 52, // square meters
  tenant: {
    name: 'Łukasz',
    pet: {
      type: 'Small animal',
      name: 'Kubuś'
    }
  }
}

That's pretty neat! The little pieces of code that operate on the area are totally unaware that it's actually in a different unit and that there are some other fields as well. Thanks to the lens they are totally decoupled from the shape and size of the state object.

Another cool thing about Ramda lenses is how easy it is to use them with the pipe function. Because all Ramda functions are curried, what's returned by the set function when called with only two arguments (the lens and the value to set) is a function that takes the remaining argument, that is the object where the value is supposed to be set, and returns the updated version of this object.

Let's suppose that we want to update two fields in our global state object: the area (provided in square centimeters) and the type of the pet. Doing it using the spread operator would look like this:

{
  ...state,
  area: 450000 / 10000,
  tenant: {
    ...state.tenant,
    pet: {
      ...state.tenant.pet,
      type: 'Guinea pig'
    }
  }
}

This is heavily coupled to the structure of the state and quite error prone, because every time we update an object field, we need to remember to spread the rest of the properties, otherwise we're gonna lose some data. Also, all key names must be exactly the same. Usually it's not a problem, because within one project it's a good idea to keep the terminology consistent, but as soon as we want to share a piece of code that operates on the global state it becomes a challenge, because then the structure and key names must be consistent among all its clients, what makes it not so reusable.

With lenses, this is a lot cleaner, less coupled and reusable:

pipe(
  set(areaLens, 450000),
  set(tenantPetTypeTelescope, 'Guinea pig'),
)(state)

The next time we want to update the type of the pet, we can use exactly the same lens (or telescope):

set(tenantPetTypeTelescope, 'rodent', state)

We can use this telescope to read it as well:

view(tenantPetTypeTelescope, 'state') // 'rodent'

And if the name of the field changes, there's just one place that really requires a change - the telescope. For example, if the global state doesn't use type anymore, because it's been renamed to kind, the client code doesn't really need to know about it. This is how the updated telescope may look like:

const tenantPetTypeTelescope = lensPath(['tenant', 'pet', 'kind']);

Lenses turn out to be so useful, that they became first-class citizens in Rosmaro. For example, here's the code associated with a child node of the TodoMVC app implemented in Rosmaro:

// Child node (component)
export const ADD = ({ context: { content } }) => ({
  context: { content: '' },
  arrow: 'cleared',
  effect: [
    {
      type: 'DISPATCH',
      action: { type: 'TODO_ADD', content: trim(content) },
    },
  ],
});

As we can see, it treats the context, which is the Rosmaro's term for the global state, like it were an object with just one propety - content. It uses destructing to read it directly from the context: ({ context: { content } }) and when it needs to clear it, it just provides an object that consists of nothing but a single property: context: { content: '' }.

From the child node's perspective, the context is very simple and doesn't have any data it doesn't need to have. However, the whole context is a lot bigger:

{
  newTodoForm: {
    content: 'What I am typing'
  },
  list: {
    todos: [
      {
        id: 2,
        content: 'zc'
      },
      {
        id: 1,
        content: 'asdf'
      }
    ],
    lastId: 2
  }
}

It's only thanks to a proper lens associated with the parent node that the child node may stay focused solely on its own teeny tiny part of the context:

// Parent node (component)
export default opts => ({
  lens: () =>
    compose(
      sliceLens('newTodoForm'),
      initialValueLens({ content: '' })
    ),
  handler: transparentHandler,
});

Personally, I love lenses for their cohesion (keeping the code related to property access together) and the freedom they give (may be used to adapt an incompatible otherwise piece of code). They are one of those very intuitive constructs, that like state machines, may be reinvented and appear under various names (like adapters or user flows).

Testing the TodoMVC app

Sun, 27 Jan 2019 10:37:20 GMT

We've already covered two important parts of building the TodoMVC app: state diagrams drawn in the editor and the code associated with nodes. These things are crucial in the development process, because without them there would be no app at all. However, if we want to make sure the development process is sustainable, we need to have an automatic test suite. Without such a thing we can't really know if a little change to the codebase we've just introduced doesn't break any important functionality without testing the whole thing manually. And because humans are not the best test runners, at least compared to computers, manual tests tend to be not so repetitive and quite error prone.

I'm pretty sure you also love that feeling of freedom that a good automatic test suite brings. There's no fear of refactoring, no fear of regression. So why are we even talking about automatic tests, if it's so obvious that they are beneficial? It's because they are not trivial to introduce. Many frameworks have their own testing framework, testing philosophy etc. So does Rosmaro. It only shows that test automation is still kind of an uncharted territory.

Before we dive deep into the details of how the tests in our codebase are implemented, I'd like to show you a snippet from the test of adding a new item:

// __tests__/adding_a_todo.js

test('adding a todo', () =>
  testFlow([
    assertFooterInvisible,
    assertMainInvisible,
    assertNewTodoFormFocused,
    assertMarkAllAsCompletedInvisible,
    addTodo({ value: 'new todo' }),
    assertTodoPresent({ value: 'new todo' }),
    assertTodoActive({ value: 'new todo' }),
    assertMarkAllAsCompletedUnchecked,
    assertFooterVisible,
    assertMainVisible,
  ]));

A test is a high-level description of the required behavior, without going deep into any implementation details of the application, like what does it exactly mean that the footer is invisible or how to add a todo.

Every test is made of a series of little steps that can either make assertions, like assertFooterInvisible or "perform" an action, like addTodo. Steps are reusable and may be composed in various way to create different tests.

Even though there are multiple wonderful testing libraries under the hood, like dom-testing-library which is the framework-agnostic core of react-testing-library, which in our case of a snabbdom-based implementation is used via snabbdom-testing-library or jest, the testing framework itself, it's the functional approach that makes tests simple. The Virtual DOM enables us to narrow down the whole DOM-related code to a bunch of pure functions of the application state (state => UI). Rosmaro's side-effect model, heavily inspired by Elm, where effects are simply values returned by pure functions, is usually implemented by running the Rosmaro model function in a Redux store with Redux-Saga. It's quite straightforward to achieve, as the Rosmaro ecosystem provides the glue necessary to make all these pieces work together. Standing on the shoulders of giants, it took just a little bit of code to create rosmaro-testing-library which main purpose is to reduce the tests to a series of steps looking like this:

{
  feed: { type: '...'},
  consume: ({ result }) => {
    expect(/* ... */)// ...
  }
}

Because a Rosmaro model is nothing but a pure function of state and action that returns an updated version of the state and some result, that is ({ state, action }) => ({ state, result }), there are no moving parts we need to keep track of when testing it. As long as we provide the same state and action values, it will always return the exact same new state and result. We don't need to think about asynchronous calls, unexpected side effects run in the test suite or unhandled promise rejections, because there are not things like that at all.

We could say that the rosmaro-testing-library is a "fake", manually "increased" runtime environment for the Rosmaro model under test. It's actually very similar to Redux, in terms of reducing the list of steps using the model function. The testing-related part is the consume function that allows us to make assertions about the result of consuming an action.

Please don't worry, if some of the things above are not totally clear. They will certainly make sense after we go through the code.

Let's then take a look at the complete test file, not just a snippet extracted from it:

// __tests__/adding_a_todo.js

import testFlow from '~/testUtils/testFlow';
import assertFooterInvisible from '~/testSteps/assert_footer_invisible';
import assertFooterVisible from '~/testSteps/assert_footer_visible';
import assertMainInvisible from '~/testSteps/assert_main_invisible';
import assertMainVisible from '~/testSteps/assert_main_visible';
import addTodo from '~/testSteps/add_todo';
import assertNewTodoFormFocused from '~/testSteps/assert_new_todo_form_focused';
import assertMarkAllAsCompletedInvisible from '~/testSteps/assert_mark_all_as_completed_invisible';
import assertMarkAllAsCompletedUnchecked from '~/testSteps/assert_mark_all_as_completed_unchecked';
import assertTodoPresent from '~/testSteps/assert_todo_present';
import assertTodoActive from '~/testSteps/assert_todo_active';

test('adding a todo', () =>
  testFlow([
    assertFooterInvisible,
    assertMainInvisible,
    assertNewTodoFormFocused,
    assertMarkAllAsCompletedInvisible,
    addTodo({ value: 'new todo' }),
    assertTodoPresent({ value: 'new todo' }),
    assertTodoActive({ value: 'new todo' }),
    assertMarkAllAsCompletedUnchecked,
    assertFooterVisible,
    assertMainVisible,
  ]));

The file lives in the __tests__ directory, what denotes that it will be picked by jest and run when we run npm t in our terminal.

As we can see, there isn't much more code than what we've already seen. Actually there are only imports. Starting from the very top of the file, we import the testFlow helper function from a project-specific setup file ~/testUtils/testFlow, which main goal is to wrap the testFlow utility from rosmaro-testing-library. All the other imports are test steps, that is { feed, consume } objects or collections of these objects (they may be nested).

The difference between a test and a test step is that a test is the final, complete scenario the test runner picks and runs, while a test step is just a building block that may be reused in multiple tests, or even within the same test.

The complete code of the step asserting that the footer is invisible is just a couple of lines long:

// testSteps/assert_footer_invisible.js

export default ({ testContext }) => ({
  feed: { type: 'RENDER' },
  consume: ({ result }) => {
    const { queryByTestId } = testContext.render(result.data);
    expect(queryByTestId('footer')).toBeNull();
  },
});

What's returned by the function of testContext is the actual test step. We'll go back to the testContext soon, but for now, I think it's a better idea to focus on feed and consume.

The feed value is the action that's passed to the model. In this case, we want to ensure that the footer is not rendered, so we're giving the model a { type: 'RENDER' } action, expecting it to render the UI.

The consume function takes the result of calling the Rosmaro model with the recent state and the action from the feed property. Let's focus on this function for a moment, as it plays a very important role in testing Rosmaro models. Because we're using rosmaro-binding-utils, the result always has the following structure: { data, effect }. The RENDER action is not supposed to have any side effects, and that's why we may totally ignore the effect property and focus solely on the data, which in this case is a Snabbdom VDOM node. We're using the render function from the testContext. It comes from snabbdom-testing-library and gives us all the selectors and utilities provided by dom-testing-library. Due to the fact that the template of the TodoMVC app doesn't really help us with label-based selectors, we're using a little bit less nice (when it comes to test coverage), but well functioning selector function queryByTestId. It matches the element based on the data-testid attribute we're setting on it:

// components/root/bindings/main/Layout/WholeApp/index.js
h('footer.footer', { attrs: { 'data-testid': 'footer' } }, [
  list.counter,
  controls.Navigation.ui,
  controls.ClearCompleted,
]),

After querying for the element, we can use the expect function from jest to make sure that no footer is rendered:

// testSteps/assert_footer_invisible.js

expect(queryByTestId('footer')).toBeNull();

The testContext object comes from rosmaro-testing-library and is used to store things that may be useful during the test. In our setup file, testUtils/testFlow.js, we put there the render function from snabbdom-testing-library. This object may be updated in a very similar way the state is updated, that is by returning its new version. If there's something in the result of consuming an action that we would like to make available for further test steps, we can add it to the context. You can find more on this in the README of rosmaro-testing-library.

In the test, there's an interesting, parameterized step to add a new item - addTodo:

// __tests__/adding_a_todo.js

test('adding a todo', () =>
  testFlow([
    // ...
    addTodo({ value: 'new todo' }),
    // ...
  ]));

Let's take a closer look at its source code:

// testSteps/add_todo.js
import typeInNewTodo from '~/testSteps/type_in_new_todo';
import enterInNewTodoInput from '~/testSteps/enter_in_new_todo_input';

export default ({ value }) => [typeInNewTodo({ value }), enterInNewTodoInput];

As we can see, this step consists of two smaller steps: typeInNewTodo and enterInNewTodoInput. The first one simulates writing something in the input field and looks like this:

// testSteps/type_in_new_todo.js
import { fireEvent } from 'snabbdom-testing-library';
import { consumeActionsWithEffects } from 'rosmaro-testing-library';

export default ({ value }) => ({ testContext }) => ({
  feed: { type: 'RENDER' },
  consume: ({ result }) => {
    testContext.store.clearActions();
    const { getByPlaceholderText } = testContext.render(result.data);
    const input = getByPlaceholderText('What needs to be done?');
    fireEvent.input(input, { target: { value } });
    const actions = testContext.store.getActions();
    return { step: consumeActionsWithEffects(actions) };
  },
});

We're using a factory function, that is a function of value, in order to build a test step (a function of testContext) that simulates typing the value in the input field. In order to examine the input field and its behavior, we're rendering the UI in the same way we did it previously, that is by passing a RENDER action to the model. This time, however, we need to do something more sophisticated - we need to simulate user interaction. That's why after querying for the input field, here using the getByPlaceholderText function, we're simulating input event using the fireEvent function from snabbdom-testing-library. Because all the UI does is dispatching actions to the redux store, we're using the redux-mock-store package to simulate a store and get all the actions that have been dispatched to it. Aadding an item and reacting to it is quite complex and takes a few events, and that's why we're making use of the consumeActionsWithEffects helper from rosmaro-testing-library in order to emulate DISPATCH effects. It will generate further test steps, that is { feed, consume } objects necessary to fully handle the process of adding an item. As mentioned in the previous post with the code of the TodoMVC app, the list of items dispatches events that the rest of the app may react to, for example:

// main/Components/List/View/index.js

return [{type: 'DISPATCH', action: {type: 'SOME_TODOS_COMPLETED'}}];

Sometimes, when we do really care about every single iteration, we may want to manually "execute" effects by storying them in the testContext and passing them as actions in the feed property, for example to make sure that there's no race condition, if our Rosmaro model is used to handle some network communication or another time sensitive process.

Below you can see some other tests, taken directly from the tests directory, just without all the imports (for the sake of brevity):

// __tests__/counter_for_1_active_todo.js
test('the counter shows "1 item left"', () =>
  testFlow([
    addTodo({ value: 'todo A' }),
    addTodo({ value: 'todo B' }),
    toggleTodo({ value: 'todo A' }),
    assertCounterValue({ expectedValue: '1 item left' }),
  ]));

// __tests__/marking_a_todo_as_completed.js
test('marking a todo as completed', () =>
  testFlow([
    addTodo({ value: 'first todo' }),
    addTodo({ value: 'second todo' }),
    toggleTodo({ value: 'second todo' }),
    assertTodoCompleted({ value: 'second todo' }),
    assertTodoActive({ value: 'first todo' }),
  ]));

// __tests__/removing_a_todo.js

test('removing a todo', () =>
  testFlow([
    addTodo({ value: 'todo A' }),
    toggleTodo({ value: 'todo A' }),

    addTodo({ value: 'todo B' }),

    addTodo({ value: 'todo C' }),

    assertTodoPresent({ value: 'todo A' }),
    assertTodoCompleted({ value: 'todo A' }),

    clickDestroy({ todo: 'todo B' }),

    assertTodoNotPresent({ value: 'todo B' }),

    assertTodoPresent({ value: 'todo C' }),
    assertTodoActive({ value: 'todo C' }),
  ]));

I hope you enjoyed this post and that it gave you a broad idea how Rosmaro models may be tested. If you're willing to learn more, you may find the following resources helpful:

rosmaro-testing-library on GitHub
testUtils, testSteps and the test files from the repository of the Rosmaro TodoMVC app

An overview of the Rosmaro-TodoMVC app codebase

Sun, 20 Jan 2019 10:37:20 GMT

In the previous post about decomposing the TodoMVC app with state diagrams I showed you the state diagrams I used to build this TodoMVC app, but no code at all. Even though the diagrams are a crucial part of the implementation, as they define when and how does the behavior of the app change, they don't specify the very details of any particular behavior. It's the code's job. That's why today we're gonna take a look at the written part of the implementation. It's gonna be a broad overview of the important pieces, what should give you an idea what it is like to build a Rosmaro application, without going through all the boring details.

Directory structure

Due to the fact that the graph-code connection is managed with rosmaro-tools, the directory structure serves as a good starting point.

The model-specific part of the directory tree, that is where the behavior of the application lives, looks like this:

.
├── index.js
├── Layout
│   ├── index.js
│   ├── WholeApp
│   │   └── index.js
│   └── JustForm
│       └── index.js
└── Components
    ├── index.js
    ├── NewTodoForm
    │   ├── index.js
    │   ├── FilledIn
    │   │   └── index.js
    │   ├── Empty
    │   │   └── index.js
    │   └── lib
    │       └── form.js
    ├── List
    │   ├── index.js
    │   └── View
    │       ├── index.js
    │       └── child
    │           ├── index.js
    │           ├── Active
    │           │   ├── index.js
    │           │   ├── Editing
    │           │   │   ├── index.js
    │           │   │   ├── FilledIn
    │           │   │   │   └── index.js
    │           │   │   └── Empty
    │           │   │       └── index.js
    │           │   └── Displaying
    │           │       └── index.js
    │           ├── Completed
    │           │   ├── index.js
    │           │   ├── Editing
    │           │   │   ├── index.js
    │           │   │   ├── FilledIn
    │           │   │   │   └── index.js
    │           │   │   └── Empty
    │           │   │       └── index.js
    │           │   └── Displaying
    │           │       └── index.js
    │           └── lib
    │               ├── filtering.js
    │               ├── editing.js
    │               └── displaying.js
    └── Controls
        ├── index.js
        ├── Navigation
        │   ├── index.js
        │   └── Buttons
        │       ├── index.js
        │       ├── Completed
        │       │   └── index.js
        │       ├── All
        │       │   └── index.js
        │       ├── Active
        │       │   └── index.js
        │       └── lib
        │           └── templates.js
        ├── MarkAll
        │   ├── index.js
        │   ├── Unchecked
        │   │   └── index.js
        │   ├── Checked
        │   │   └── index.js
        │   └── lib
        │       └── view.js
        └── ClearCompleted
            ├── index.js
            ├── Visible
            │   └── index.js
            └── Hidden
                └── index.js

Please don't let the number of files scare you, as most of them are just a couple of lines long.

Their main purpose is to enable automatic graph-code bindings. Instead of manually specifying that a particular node is bound to a particular piece of code and then importing the code from its own file, with this directory-based approach we can just place the code under a path coresponding to its node and the binding is going to be built for us. We're killing two birds with one stone here!

The utility is registered as one of the npm scripts in the package.json file, so that we can re-build the automatically generated code by simply running npm run rosmaro-bindings in the terminal:

{
  "scripts": {
    "rosmaro-bindings": "rosmaro-tools bindings:build js/components/root/bindings"
  },
}

Simple handlers

The "Clear completed" button is one of the simplest subgraphs in the application. It's either hidden or visible, and when it's visible, then clicking it dispatches the CLEAR_COMPLETED action that is consumed by the list items.

The code assigned to the Visible node handles rendering the button (with an event listener) and follows the none are completed arrow when the list of items dispatches either NO_TODOS_COMPLETED or NO_TODOS:

// Visible/index.js

const noneCompleted = () => ({arrow: 'none are completed'});

export default ({dispatch}) => ({

  handler: makeHandler({

    NO_TODOS_COMPLETED: noneCompleted,
    NO_TODOS: noneCompleted,

    RENDER: () =>
      h('button.clear-completed', {
        on: {click: () => dispatch({type: 'CLEAR_COMPLETED'})}
      }, 'Clear completed')

  })

});

When the button is hidden, it renders as an empty string. As soon as the list dispatches an event like SOME_TODOS_COMPLETED or ALL_TODOS_COMPLETED, it follows the some are completed arrow in order to transition to the Visible state. Of course, the graph code is not aware of the target node, as it's specified in the graph. The graph code is concerned only about things directly related to its functions, like when should it follow one of its arrows:

// Hidden/index.js

const someCompleted = () => ({arrow: 'some are completed'});

export default ({dispatch}) => ({

  handler: makeHandler({

    ALL_TODOS_COMPLETED: someCompleted,
    SOME_TODOS_COMPLETED: someCompleted,

    RENDER: () => ''

  })

});

Coding similar behaviors

The nodes we've seen above are quite distinctive, because they react to different events and render in a totally different way. They don't really share any code. But it's not always the case. For example, the form used to add new items may also be in two differnet states: FilledIn and Empty, but the only difference between these two states is that an Empty form doesn't allow to add a new item.

To avoid code duplication and make this difference clear, the code of makes use of a shared library. This is the code of the FilledIn state:

// main/Components/NewTodoForm/FilledIn/index.js

import {makeBinding, ADD} from './../lib/form';

export default makeBinding({ADD});

It imports both the binding factory and a handler of the ADD action from the library located on the same level as the FilledIn and Empty directories.

The code of the FilledIn state puts both of these pieces together to get a form that is capable of ADDing a new item. However, because the Empty is not supposed to support adding new items, it simply skips the ADD action handler:

// main/Components/NewTodoForm/Empty/index.js
import {makeBinding} from './../lib/form';

export default makeBinding({});

The makeBinding factory looks almost like a regular node binding, except for the ({ADD}) part. It's a higher order function that takes the ADD action handler so that it may be placed in the binding:

// main/Components/NewTodoForm/lib/form.js

export const makeBinding = ({ADD}) => ({dispatch}) => ({

  handler: makeHandler({

    RENDER: ({toNode, context}) =>
      h('input.new-todo', {
        props: {
          placeholder: 'What needs to be done?',
          value: context.content,
        },
        hook: {
          insert: ({elm}) => elm.focus()
        },
        on: {
          keydown: ({key}) => key === "Enter"
            ? dispatch(toNode({type: 'ADD'}))
            : undefined,
          input: ({target: {value}}) => dispatch(toNode({type: 'TYPE', value}))
        }
      }),

    TYPE: ({action: {value: content}, context}) => {
      const arrow = trim(content) ? 'changed' : 'cleared';
      return {
        arrow: arrow,
        context: {...context, content}
      };
    },

    ADD,

  })

});

The handler of the ADD action is placed in the library as well:

// main/Components/NewTodoForm/lib/form.js

export const ADD = ({context: {content}}) => ({
  context: {content: ''},
  arrow: 'cleared',
  effect: [{
    type: 'DISPATCH',
    action: {type: 'TODO_ADD', content: trim(content)}
  }],
});

It clears the input by setting the context to {content: ''}, follows an arrow called cleared and dispatches a {type: 'TODO_ADD', content} action. This action is then consumed by the subgraph responsible for handling the list of items.

Working with a big context object

Every Rosmaro model uses one big, global context object. It's very much like the global store in Redux (and that's why Redux is such a great environment to run Rosmaro models!). As we've seen, from the form's perspective the context looks like this:

{
    content: 'What I am typing'
}

Does it mean there's no other data in the context? No, of course there is more data! The whole context looks actually like this:

{
  newTodoForm: {
    content: 'What I am typing'
  },
  list: {
    todos: [
      {
        id: 2,
        content: 'zc'
      },
      {
        id: 1,
        content: 'asdf'
      }
    ],
    lastId: 2
  }
}

The form may focus solely on its tiny part thanks to a lens attached to the NewTodoForm state. It selects a small slice of the whole object (newTodoForm) and in case there's no such property, it provides an initial value ({content: ''}):

// main/Components/NewTodoForm/index.js

export default opts => ({
  lens: () => compose(
    sliceLens('newTodoForm'),
    initialValueLens({content: ''}
  )),
  handler: transparentHandler,
});

What sets lenses apart from Redux selector is that they work in both ways, not only zooming in to focus on a small part, but also zooming out to allow updates of the original, big object. This is how the form may not only read context.content, but also update context.content without being aware it's actually context.newTodoForm.content.

If you'd like to learn more about Ramda lenses, I strongly recommend checking out the chapter on lenses in the official Ramda documentation.

List filtering

Another aspect that in my opinion deserves attention is how does the filter work. Usually todo apps relay on some form of a filter function that discards all the entries that don't match the current filter status. There's nothing wrong with this approach! However, in order to demonstrate that there are also other ways, this implementation uses map instead of filter. Both Completed and Active items are difned with a list of states in which they should be rendered:

// main/Components/List/View/child/Active/index.js

export default makeBindings({
  state: 'active',
  renderWhen: ['all', 'active'],
});

Their RENDER handler is a bit different than in the case of the other nodes. Instead of simply returning a VDOM node, it returns an object with keys corresponding to all the possible states of the filter. For example, the Active node renders in the following way:

{
    completed: ''
    all: renderedItem,
    active: renderedItem
}

Navigation states don't only render a bunch of buttons, but also pick a specific key from the object returned by each item. In this case, it's active:

// main/Components/Controls/Navigation/Buttons/Active/index.js

export default makeBinding({
  selected: 'active',
  buttons: {
    allTodosButton: allTodosButton.notSelected,
    completedTodosButton: completedTodosButton.notSelected,
    activeTodosButton: activeTodosButton.selected,
  }
});

The makeBinding factory looks like this:

// main/Components/Controls/Navigation/Buttons/lib/templates.js

export const makeBinding = ({selected, buttons: {allTodosButton, completedTodosButton, activeTodosButton}}) => () => ({

  handler: makeHandler({

    NAVIGATE_TO_ALL: () => ({arrow: 'navigated to all'}),
    NAVIGATE_TO_COMPLETED: () => ({arrow: 'navigated to completed'}),
    NAVIGATE_TO_ACTIVE: () => ({arrow: 'navigated to active'}),

    RENDER: ({context, action, children}) => ({
      ui: h('ul.filters', [
        allTodosButton,
        completedTodosButton,
        activeTodosButton
      ]),
      selectTodos: map(prop(selected))
    })

  })
});

What's important to note is that the RENDER handler returns both the ui and a selectTodos function that selects one particular key from every object on the list. That way, when both Navigation and List are rendered, the map fuction provided by Navigation is applied to the list of items returned by List.

List events

So far we've seen how various parts of the application react to events related to the list of items. For example, the "Clear completed" button disappears, when there are no completed items. But where do messages like this come from?

Events like ALL_TODOS_COMPLETED, SOME_TODOS_COMPLETED, NO_TODOS_COMPLETED, and NO_TODOS are dispatched by the List node. Every time an action that may cause a transition reaches one of the item nodes, the parent of all of them asks its children their current state. It does it by dispatching a GET_STATE action to its children. It doesn't directly read their state, because it's considered an implementation detail and may be actually quite complex. In fact, an item may not only be Active, but also in the Editing state with the form being FilledIn. All these detail don't really matter from the point of view of the List, which expects either just active or completed. It's a bit like in Java where it's a good practice to use a getter method instead of directly accessing object properties, because the internal property may change, be calculated on the fly or the read operation may be delegated to some other object:

// main/Components/List/View/index.js
const getStateAction = {type: 'GET_STATE'};

const readStats = ({context, children}) => {
  const childrenResults = callChildren({context, children, action: getStateAction});
  return pipe(
    values,
    map(prop('data')),
    reduce((soFar, state) => ({
      ...soFar,
      [state]: soFar[state] + 1
    }), {active: 0, completed: 0})
  )(childrenResults.result);
};

const buildEffects = stats => {
  if (stats.completed && !stats.active) {
    return [{type: 'DISPATCH', action: {type: 'ALL_TODOS_COMPLETED'}}];
  }

  if (stats.completed) {
    return [{type: 'DISPATCH', action: {type: 'SOME_TODOS_COMPLETED'}}];
  }

  if (stats.active) {
    return [{type: 'DISPATCH', action: {type: 'NO_TODOS_COMPLETED'}}];
  }

  return [{type: 'DISPATCH', action: {type: 'NO_TODOS'}}];
};

// ...

DISPATCH_EVENTS: ({context, action, children}) => {
  const stats = readStats({context, children});
  const effect = buildEffects(stats);
  return {effect};
},

The DISPATCH_EVENTS handler uses the readStats function to call the children, get stats in the form of an object like {active: 3, completed: 8} and pass them to the buildEffects function in order to get effect objects describing the current state of the list, like SOME_TODOS_COMPLETED.

Routing

The last part I'd like to show you is the routing. It uses Navigo to associate callback functions with routes. Every time a route is visited, it dispatches an action:

// app.js
router
  .on('/', () => dispatchFn({type: 'NAVIGATE_TO_ALL'}))
  .on('/active', () => dispatchFn({type: 'NAVIGATE_TO_ACTIVE'}))
  .on('/completed', () => dispatchFn({type: 'NAVIGATE_TO_COMPLETED'}))

The UI renders ordinary links:

// main/Components/Controls/Navigation/Buttons/lib/templates.js

const notSelectedButton = ({path, name}) =>
  h('li',
    h('a', {props: {href: path}}, name)
  );

Because in this simple app every filter may be accessed at any time, all three navigation actions are supported in every state of the app:

// main/Components/Controls/Navigation/Buttons/lib/templates.js

NAVIGATE_TO_ALL: () => ({arrow: 'navigated to all'}),
NAVIGATE_TO_COMPLETED: () => ({arrow: 'navigated to completed'}),
NAVIGATE_TO_ACTIVE: () => ({arrow: 'navigated to active'}),

As mentioned in the previous post, entry points are used to mitigate state explosion. You can read more about entry points in the documentation of Rosmaro.

Coming soon

Thank you for reading this post! In the next part we're gonna focus on the test suite powered by rosmaro-testing-library, redux-mock-store, and snabbdom-testing-library.

You can find the complete code of this app on GitHub.

Decomposing the TodoMVC app with state diagrams

Sun, 13 Jan 2019 10:37:20 GMT

Most probably you've already heard about TodoMVC. Its purpose is to demonstrate how a to-do list may be implemented in various frameworks and languages.

In this post, we'll identify verious states of this famous demo app. As it turns out, they are not only helpful to understand the requirements, but may also be used to actually implement the application!

Let's start!

When there are no items, only the form is visible. But as soon as there's at least one item, the list and the controls become visible. We can recognize different layouts and components. Here's what it looks like:

There are two layouts:

just the form
the whole app

They are represented as a graph:

We have three main components:

the new todo form
the list of todos
all the various controls

Because they are simultaneously active and we never switch from one component to another, they are represented as three orthogonal regions:

In our implementation, on the highest level, the TodoMVC app consists of two orthogonal regions, that is a layout and a bunch of components.

In the editor, they look similar to the components, because they are also orthogonal regions:

This is the form used to add a new todo:

We are not allowed to add a new, empty todo. In other words, the behavior of an empty form differs from the behavior of a filled-in form. In order to be able to assign adding a todo only to a filled-in form, we model this form as a graph with two states:

Only the FilledIn one actually adds todo items, while the Empty one never does it.

There's a checkbox on the left side of the form:

When all items are completed, it's checked and clickig it marks all the items as active.

When not all items are completed, it's unchecked and clicking it marks all the items as completed.

It's something that may be expressed as a graph:

In the bottom right corner of the app there's a button that appears only when there's at least one completed item.

Clicking it removes all the completed items.

In the Rosmaro editor it looks like this:

Below are all the possible states of the filter:

Because it's totally possible to navigate from any of the states to any other state, the graph uses entry points in order to avoid state explosion:

Finally, we're getting closer to the most important part of the TodoMVC app, that is a todo.

It may be either active or completed:

Both active and completed items may be edited.

It indicates that they both have a subgraph saying that they are either being disaplyed or edited:

An attempt to change the content of an item to an empty value actually removes this item instead of just updating its content:

This difference in behavior is visible in the graph represending an item that's being edited.

These are all the states that matter from the point of our implementation!

Check out the next part to see the code associated with the nodes visible above.

If you'd like to simply browse the whole code, just visit the GitHub repository of the Rosmaro-TodoMVC app.

A comparison of dispatch management solutions: if, switch, object, automaton, multimethod

Sun, 25 Nov 2018 10:37:20 GMT

Conditions are hard to implement. Fortunately, nowadays we have multiple ways of telling the computer which piece of code should be used. Some of these techniques are more appealing than the others, because they reflect the way we think about a particular problem.

In this post, I'd like to talk a bit about my favorite ways of picking the proper piece of code. These are the techniques that turned out to be extremely helpful over the course of my career. I'll focus on runtime polymorphism, that is the decisions made during the execution of a program, as opposed to the compile time polymorphism, that is the decisions made by the compiler or any other tool before the program is run. Because the thing I'd mainly like to focus on is the mental model and not the details, for each dispatch management solution I'll use the language, library or framework that I think illustrates it best.

IF

IFs are about picking one of two predefined paths: the one for true or the one for false.

We can define what's at the end of each path, but we can neither define more paths nor rename them.

The decision regarding the path to follow is made based on a Boolean value.

In an editor, it may look like this:

const a = 3;
const myBool = a > 3;
if (myBool) {
  // Executed if myBool is truthy.
} else {
  // Executed if myBool is falsy.
}

As we can see, the developer can associate some behavior with true and a different behavior with false, but they can't associate different behaviors with, let's say, 4, 2, and 5 using just one IF.

There are multiple ways to avoid IFs. Some of them are covered in previous blog posts like Programming without boolean values: To-Do App and Unnecessary IF statements.

Switch

I believe that the difference between IF and Switch is so subtle, yet important, that it deserves a separate blog post - If vs. Switch. Long story short, Switch is about matching the control value against multiple programmer-supplied values, as opposed to always matching against just true and false.

This is how it looks in an editor:

switch (state) {
  case "loading":
    // ...
    break;
  case "error":
    // ...
    break;
  case "loaded":
    // ...
    break;
}

Instead of casting state to either true or false, we match it against a set of possible options: loading, error, and loaded.

We can add and remove custom branches with ease.

A Switch may be simulated using multiple if else constructions, like this:

if (state === "loading") {
  // ...
} else if (state === "error") {
  // ...
} else if (state === "loaded") {
  // ...
}

A Switch is degraded when it can be replaced by just one IF:

switch (myValue) {
  case "a":
    // ...
    break;
  default:
    // ...
}

if (myValue === "a") {
  // ...
} else {
  // ...
}

Object-oriented dispatch

Even though languages like Python or JavaScript prove that classes and interfaces are not necessary to benefit from object-oriented programming, the illustration visible above depicts a language featuring both classes and interfaces in order to explain the benefits of inversion of control. I strongly believe it's going to make the example easier to understand, as the concepts of interfaces and concrete implementations always exist in our heads, regardless of whether our language of choice requires their explicit declaration.

An interface is a type of contract the user of a black-box object may relay on in order to know what are the available methods and what are they supposed to do.

One interface may have multiple implementations.

The caller, that is the client of the object, calls a method through the interface. It doesn't really know what exact implementation is going to handle the method call. It relays on the contract that such a method is going to do such a thing.

What's going to happen (assuming that it's a language with dynamic dispatch), is that the method call is going to be redirected to a concrete implementation hidden behind this interface. The caller will get the result of calling the concrete method. What's very important is that in order to benefit from this indirection the client is allowed to relay on nothing but the interface. It must not make any assumptions about the concrete implementation that's going to handle the method calls. Otherwise, it becomes tightly coupled to the callee.

This indirection is so powerful, because it allows to easily write code encapsulating high-level ideas that is not dependent on details. The place where a concrete implementation is defined may be completely separated from the place where it's used through an interface.

For example, a service may need to use a cache. Instead of using a particular implementation like this:

class MyService {
  private cache;
  constructor() {
    this.cache = new RedisCache();
  }
  // ...
}

It may use it through an interface:

class MyService {
  constructor(private cache: MyCacheInterface) { }
  // ...
}

That way MyService doesn't depend on any particular implementation of the cache. It's less likely to change when the cache implementation changes. It may be reused, even with a totally different cache implementation. It's easier to unit test. It's simpler.

Depending on the programming language, objects may be simulated with first-class functions or pointers.

Automata-based dispatch

Automata-based dispatch is great at addressing cases where the concrete implementation we want to use changes during the program execution.

When compared to object-oriented programming, the biggest difference is that instead of always dispatching methods to the same concrete class, it allows to jump from one set of concrete implementations to another.

Different sets of implementations are connected by named arrows. They make a state machine.

For instance, in the illustration visible above, A returns both A's result and an arrow called x. Following this arrow changes the current state of the state machine from A to B, so the next time there's an action to handle, it's B that's going to handle it, not A.

Let's take a look at an example of a model of a cursed prince. Below we can see that as soon as he eats a pizza, he turns into a frog.

[
  {type: 'INTRODUCE_YOURSELF'}, // 'I am The Prince of Rosmaro!'
  {type: 'EAT', dish: 'yakisoba'}, // undefined
  {type: 'INTRODUCE_YOURSELF'}, // 'I am The Prince of Rosmaro!'
  {type: 'EAT', dish: 'pizza'}, // undefined
  {type: 'INTRODUCE_YOURSELF'} // 'Ribbit! Ribbit!'
].forEach(action => console.log(
  ({state} = model({state, action})).result.data
));

The high level part of the model, that is the state machine, looks like this when opened in the editor:

The concrete implementations, which are the details, are coded:

const Prince = handler({
  INTRODUCE_YOURSELF: () => "I am The Prince of Rosmaro!",
  EAT: ({action}) => action.dish === 'pizza'
    ? { arrow: 'ate a pizza' }
    : undefined
});

const Frog = handler({
  INTRODUCE_YOURSELF: () => "Ribbit! Ribbit!",
});

As we can see, the current behavior is altered by following an arrow. Automata-based programming enables thinking in terms of possible states and their behaviors as opposed to toggling Boolean flags. In this example, there's an IF, so is there a Boolean value. The thing is that this Boolean is calculated solely based on the input value, without referring to any historical value set in the past. This plays an important role in writing decoupled code, because it makes the code independent from the past.

The very idea of automata-based programming is nothing new. Personally, as someone coming from the object-oriented background, I first stumbled upon this paradigm when reading about the State design pattern in the "Design Patterns: Elements of Reusable Object-Oriented Software" book. This object-oriented pattern may be summed up as a way to change an object's class on the fly, so that conditional behavior may be modeled in a cohesive manner without IFs and Switches being scattered all around the codebase just to check the value of previously set member variables.

Multiple dispatch

So far, we've been talking about deciding how X does Y. The challenge was to select the proper Y depending on X. But what about X doing Y to Z? What if we can tell what's the correct Y only after considering the state or type of both X and Z? This time it's not just one argument that needs to be taken into account, but two. We call function dispatch based on multiple arguments multiple dispatch.

In order to illustrate the problem multimethods solve I decided to use Python due to its explicitly passed self argument. That way we can clearly see that self (or this in other languages) is nothing but a method argument. What the language does for us is automatically selecting the method implementation based on the class of self, so that we don't need to do it manually.

class Dog:
  def __init__(self, name):
      self.name = name

  def scareOff(self, anotherCreature):
    if isinstance(anotherCreature, Dog):
      print("Grrr!")
    elif isinstance(anotherCreature, Human):
      print("Woof! Woof!")

class Human:
  def __init__(self, name):
      self.name = name

  def scareOff(self, anotherCreature):
    if isinstance(anotherCreature, Dog):
      print(f"GO AWAY {anotherCreature.name}!")
    elif isinstance(anotherCreature, Human):
      print(f"I'm {self.name} and I'd like to tell you a programming joke!")

rex = Dog("Rex")
rocky = Dog("Rocky")
john = Human("John")
anna = Human("Anna")

rex.scareOff(rocky) # "Grrr!"
rex.scareOff(john) # "Woof! Woof!"
john.scareOff(rex) # "GO AWAY Rex!"
john.scareOff(anna) # "I'm John and I'd like to tell you a programming joke!"

As we can see, the scareOff implementation is selected based upon the class of the object. So it's either Dog's scareOff or Human's scareOff. Vanilla Python doesn't give us a way to select the proper method implementation based on any other argument than self and that's why there are IFs checking the class of the second argument.

Below is the same example implemented in Clojure. It makes use of multimethods.

; A multimethod selecting the proper implementation
; based on the species of the creatures.
(defmulti scare-off (fn [self another-creature]
                      [(:species self) (:species another-creature)]))

; When a Dog wants to scare off another Dog.
(defmethod scare-off [:Dog :Dog]
  [self another-creature]
  "Grrr!")

; When a Dog wants to scare off a Human.
(defmethod scare-off [:Dog :Human]
  [self another-creature]
  "Woof! Woof!")

; When a Human wants to scare off a Dog.
(defmethod scare-off [:Human :Dog]
  [self another-creature]
  (str "GO AWAY " (:name another-creature) "!"))

; When a Human wants to scare off another Human.
(defmethod scare-off [:Human :Human]
  [self another-creature]
  (str "I'm " (:name self) " and I'd like to tell you a programming joke!"))

; Defining Rex, Rocky, John, and Anna.
(def rex {:species :Dog :name "Rex"})
(def rocky {:species :Dog :name "Rocky"})
(def john {:species :Human :name "John"})
(def anna {:species :Human :name "Anna"})

; Function calls.
(scare-off rex rocky) ; "Grrr!"
(scare-off rex john) ; "Woof! Woof!"
(scare-off john rex) ; "GO AWAY Rex!"
(scare-off john anna) ; "I'm John and I'd like to tell you a programming joke!"

This piece of code consists of two important parts crucial to understand multimethods. The first one is the dispatching function. It takes function arguments and returns a dispatching value. The proper method is picked based on this value. In this case, the dispatching value is [(:species self) (:species another-creature)]. The second important part is where a concrete function is associated with a dispatching value. For example, when a Dog wants to scare off a Human, it does it like this: (defmethod scare-off [:Dog :Human] [self another-creature] "Woof! Woof!"). scare-off is the function name, [:Dog :Human] is the dispatching value, [self another-creature] are the function arguments and "Woof! Woof!" is the body of the function.

There are multiple ways to implement multimethods in languages that don't support them out of the box. One of the most popular ones (for double dispatch, that is multiple dispatch based on just two arguments) is the Visitor design pattern. Another way is to use a library that encapsulates all the manual argument inspections. If you're interested in this topic, please take a look at the Multiple dispatch in Java post.

Multiple dispatch may seem exotic, but in fact, it's quite popular. We can find it with ease even in PHP, where it's used to build things like message buses. For example, the EventDispatcher Symfony component allows to define what a polymorphic dispatch method should do when called with a particular dispatcher and a particular event.

Summary

The described techniques differ in many ways. While some are about very simple choices, like yes or no (IF), some allow to define multiple paths (Switch). Both IFs and Switches require manual inspection of the arguments every time a function is called, while the other described constructions pick the proper implementation under the hood once they are declared (an object instance in Java, a complete Rosmaro model with bindings in JavaScript or a multimethod with methods installed via defmethod). An object doesn't change its class during the execution of a program, while a Rosmaro model is all about changing the implementation after consuming an action. Sometimes the concrete implementation is picked based on only one argument (objects in Java), other times multiple values are taken into account (multimethods in Clojure).

A real life application will usually make use of multiple techniques. For example, a web application may use double dispatch to route events to event handlers. Event handlers may be objects using other objects through their interfaces. Within these objects there may be Switch statements handling a finite set of states (automata-based programming is sometimes called "Switch technology"). While some mechanisms are implemented in the language, other paradigms are supported through libraries. After all, I believe that the decision how to select the piece of code to run shouldn't be based solely on the mechanisms natively supported by our language of choice. Instead, we should strive for our implementation to reflect the problem model we have in our heads.

Thank you for reading this post.

A JavaScript framework for functions of state and action

Fri, 21 Sep 2018 20:37:20 GMT

A function of state and action is a function that takes two arguments: state and action.

Functions like that are very common in the JavaScript ecosystem. For example, the reducer function used to build a Redux store is a function that takes the current state and some action and returns nothing but a new state. The render function from React can also be considered a function of state and an implicit RENDER action that returns a view and doesn't change the state. Thus, the fundamentals of React and Redux may be summed up as writing functions of state and action that return a new state and some result.

Writing such functions is easy when the state is always interpreted in the same way. That is, when the reducer never checks the contents of the state before applying a transformation to it and the render function is free of conditionals. An example reducer could always append an item to an array, regardless its previous contents. An example render function could always map over some array items, even when there are none. However, transforming the state becomes a great challenge as soon as events from the past must be taken into account. It's usually manifested in numerous Boolean flags and if statements or expressions.

Rosmaro is a JavaScript framework for writing functions of state and action. Instead of using just one model (like key-value pairs) to express the whole state, it draws a line between data-related state and behavior-related state by making use of finite state machines.

It leverages the power of the automata-based programming paradigm in order to remove the dependency of code on events from the past and provide a graph-based dispatch mechanism.

The graph file is a human readable JSON, thus it may be written by hand. However, it's a lot more fun to use the Rosmaro visual editor that makes Rosmaro a visual programming framework.

The framework is functional and stands on the shoulders of giants like Redux Saga and Redux, what gives access to all the tools we know and love. Time travel debugging is a breeze even when asynchronous actions are involved.

Keeping the reducer, the render function and the code that returns an effect close to each other makes the node code cohesive. Rosmaro doesn't just output a bunch of data. It decides which function should handle the current state. Yet, thanks to the graph-based dispatch nodes are totally decoupled from each other and even from the past!

The CLI tool can automatically associate the nodes you draw with the code you write. Additionally, if you decide to use it, it provides a nice hierarchical directory convention.

Selectors we know from Redux are a wonderful way to consume narrow pieces of the state. The code working with it can assume that it is going to be given exactly what it expects in the exact format it expects. Rosmaro takes it one step further and by utilizing Ramda lenses allows not only to consume, but also alter a narrow slice of the data-related state.

Even though Rosmaro opts for the smallest number of building blocks, its state machines support multiple techniques of dealing with composition and state explosion, like subgraphs, node multiplication, orthogonal regions and entry points.

Don't fight with Boolean flags! Draw changes of behavior!

FB versus RSS

Sun, 26 Aug 2018 20:37:20 GMT

Open web feed standards such as RSS are declining in popularity in favor of centralised social media sites like Facebook, which are no longer just a source of entertainment, but also major content publishing platforms. I strongly believe that their centralised architecture and advertising-based business model are an increasing concern for independent creators and free speech in general.

Due to the fact that what generates profit for all popular social networks is manipulation of public opinion, from adverts to political campaigns, they are built to provide addictive rather than user-friendly experience, in the same way as tobacco products are not user-friendly diet supplements. They successfully created an illusion of freedom to follow whoever you want, while the reality is that their feeds are carefully curated and users' subscriptions are nothing for them but loose hints upon how to achieve their marketing goals. Some users may not be aware that their friends' personal data, including names and pictures, is used to generate personalised adverts which are hard to distinguish from content that actually comes from them. The high effectiveness of advertising through spreading untrue stories about people's friends is certainly a desirable marketing result, but there is no doubt in my mind that such measures are immoral.

The monopolistic nature of centralised social networks also has a detrimental effect on publishers, for whom the cost of reaching their subscribers is an arbitrary price set by that one company that is entitled to control content distribution on their website. Because this website is a walled garden, the only way to reach people gathered there is through agreeing to the owners' conditions. There is no way how Facebook users could see post published on MySpace on their Facebook walls. Not only this, the form of the content being published is strictly limited to what a particular platform can support.

Those looking for a convenient way to keep track of content from multiple sources may use one of the well established open web feed standards such as RSS and its countless clients. All what content consumers need to do in order to get started with it is to set up a news aggregator and because the standard is open, there is a great variety of implementations to pick from: open source, proprietary, for mobile devices, for desktop computers and even web based. Even thought at the first glance a news feed in a news aggregator may look similar to a social network feed, the mechanics under the hood differ significantly, as there is no centralised entity to decide who should see what and when. Instead of that, users pull the feeds directly from the creators. There is no way how a third party company could intervene in this process and stop the feed unless the creator pays them.

The open nature of RSS makes it the most viable solution for creators who want to be sure that what they publish reaches their subscribers, because they are the ones in control of the feed. What is more, the cost of running an RSS feed is not an artificially set price, but simply the cost of various software and hardware solutions involved in the process which can be provided by one or more independent companies operating in a competitive environment. The fact of the matter is that plenty of the popular blogging and content management systems do already support generating RSS feeds.

To sum up, I am of the opinion that centralised social media feeds turned out to be a dead end for creative individuals and that it is only through open standards and decentralisation that we can provide a healthy environment for valuable content to rise.

Are injection attacks still a problem in JavaScript?

Sat, 30 Jun 2018 07:37:20 GMT

Back in the days when web development was all about server-side applications querying relational databases and outputting HTML, we saw many examples of code like this:

// CAUTION: Bad example!
function popup(msg: string): string {
    return "<p class=\"popup\">" + msg + "</p>";
}

or like this:

// CAUTION: Bad example!
function getName(login: string): string {
    return "SELECT name FROM users WHERE login = \"" + login + "\""
}

Since then we learned that there are safer ways to do this.

Template engines and parameter binding are commonly used tools. It's rare nowadays to see dangerous string concatenation.

In this post I'd like to share my observation on injection attacks. It seems they are still a problem in JavaScript!

To understand why let's break one of the bad examples down into more basic forms. Here it is:

function f(userInput: A): A {
    const firstCommand: A = ...;
    const secondCommand: A = ...;
    return firstCommand.concat(userInput.concat(secondCommand));
}

As we can see, the root cause of injection attacks is that for the computer there's no difference between a command and the user input! That's why a malicious user is able to enter data which is treated as code.

Of course, as I mentioned earlier, there are well known ways to protect against that type of attacks. Instead of writing this:

"SELECT name FROM users WHERE login = \"" + login + "\""

we would write something like this:

query("SELECT name FROM users WHERE login = :login", {login})

That way the command SELECT name FROM users WHERE login = :login is clearly separated from the data {login}. In the same time the underlaying mechanism makes sure that the data is prepared to be used in an SQL query. There's no way to escape the quotes and inject any malicious code.

However, the web development train is moving fast. What we can see more and more often is not only this:

{
  paramA: "the value of the A parameter",
  paramB: "the value of the B parameter",
}

but also this:

{
  paramA: "the value of the A parameter",
  paramB: {$in: [
    "the value of the B parameter",
    "the value of the C parameter",
  ]},
}

The huge difference between these two is that the parameter value is an object which consists of a command!

Let's say the values are read from the userInput:

{
  paramA: userInput.paramA,
  paramB: {$in: [
    userInput.paramB[0],
    userInput.paramB[1],
  ]},
}

We don't need to worry about the user providing a malicious string. It will all be safely handled.

The problem is that the parameter value doesn't need to be a simple value like the value of the A parameter but it also may be a command like {$in: ["B", "C"]}. Taking into consideration the fact that there are at least few ways how the user may send a request which when decoded gives us an object (a form, JSON or XML payload), the code is vulnerable to injection attacks.

Let's say userInput.paramA equals {$empty: false}. It makes the query look like this:

{
  paramA: {$empty: false},
  paramB: {$in: [
    userInput.paramB[0],
    userInput.paramB[1],
  ]},
}

Again, there's no way the computer can distinguish trusted commands from untrusted user input. Just instead of mixing trusted and untrusted strings, we're mixing trusted and untrusted objects.

The solution is to always write commands in such a way that they cannot be received from the user. One possible way to achieve this is the approach used by React and Snabbdom-Signature (a tiny library to protect against virtual DOM injection attacks) - to mark every command object with a Symbol, so it cannot be send over the network.

I must admit that I caught myself at least a couple of times thinking that if there's no SQL database or because I'm using some virtual DOM I'm not vulnerable to injection attacks. Oh how wrong I was!

If vs. Switch

Tue, 05 Jun 2018 07:37:20 GMT

Both ifs and switches are about picking one among few possible pieces of code.

In the case of an expression, the picked piece of code is evaluated and becomes the result of the expression. When it's a statement, it's expected to have some side effects, as the code is simply run.

Some languages, like Elm, are very strict. When there's an if, there must be an else. When there's a case (the Elm's name for a switch expression), it must list all of the possible values. Other languages, like JavaScript, don't require that.

There are also times when switch is faster than if.

I must admit that I don't even remember when did I write my first ifs and switches. So it's even more embarrassing to say that I discovered the most important difference between these two not so long ago. And it's none of the things I mentioned above.

If picks one piece of code when a value is true (or truthy) and another when it's false (or falsey). There are always only two inspected values: true and false.

Switch associates different pieces of code with different values. There may be many values and they are user defined.

Let's take a look at a very simple example. It's about loading something over the network. This is the code ifs encourage me to write:

if (state.isLoaded) {
  // ...
} else {
  // ...
  if (state.errorOccurred) {
    // ...
  } else {
    // ...
  }
  // ...
}

If I were writing this in TypeScript, it would be very tempting to define the state's type like this:

let state: {isLoaded: boolean, errorOccurred: boolean};

Even though it may look legit at the first glance, it's not.

The compiler will never notice that the following state is incorrect:

state = {isLoaded: true, errorOccurred: true};

The correct type looks more like this:

let state:
    {isLoaded: true, errorOccurred: false}
    | {isLoaded: false, errorOccurred: true}
    | {isLoaded: false, errorOccurred: false}
;

As we can see, what our application logic really cares about are not two boolean values, but three possible states.

let state: "loading" | "loaded" | "error";

As soon as we discover all the possible states, we can assign them different behaviors using a switch. There's no need to inspect boolean values anymore.

switch (state) {
  case "loading":
    // ...
    break;
  case "error":
    // ...
    break;
  case "loaded":
    // ...
    break;
}

As little sense as it makes, we can bend an if to look like a switch, and vice versa:

if (state === "loading") {
  // ...
} else if (state === "error") {
  // ...
} else if (state === "loaded") {
  // ...
}

switch (state.isLoaded) {
  case true:
    // ...
    break;
  case false:
    // ...
    switch (state.errorOccurred) {
      case true:
        // ...
        break;
      case false:
        // ...
        break;
    }
    // ...
    break;
}

At this point it becomes clear that the difference between if and switch isn't about the syntax. It's about the mental model. Do I want to make decisions based on whether some expression evaluates to true, or do I want to discover all the possible states and assign them different behaviors?

What's really fascinating is that the state discovery process is just the first step. Even though switches clearly present all the states, they hide state changes.

If we add the list of possible events which cause state transitions to the list of possible states, we get a state machine. And if we base our programming on a state machine, we are automata-based programmers!

How exceptions broke my middleware

Mon, 30 Apr 2018 10:37:20 GMT

Recently I work a lot with a web framework called Laravel. It's something like the Java ecosystem and Ruby on Rails had a child in the PHP land.

A couple of weeks ago I was writing some ordinary, boring code. Much to my surprise, it didn't always work as expected. After quite a long debugging session (shame on me) I managed to track the problem down. My middleware was broken. It didn't run completely. Just the beginning was executed, but not the rest. How was that possible?

There was an exception which broke the control flow. It was a great reminder why do some new programming languages (like Elm) have no exceptions.

Let's visualize how Laravel middlewares work when there's a controller Ctrl and two middlewares MidA and MidB.

The simplified flow goes like this. The request is first passed to MidA. It's then passed to MidB, which finally passes it to Ctrl. The controller produces some response and returns it to MidB, which then returns it to MidA, which finally sends it to the browser. Easy-peasy!

Unfortunately, it gets a lot more complicated, not to say unmanageable, as soon as exceptions come into play. It's because they are often used to control how the application behaves in situations which are not so exceptional. We're actually talking here about expected, supported events like what happens when the user is not authenticated or when some entity doesn't exist.

Let's consider a case where Ctrl throws an exception.

The beginning of MidA is executed all the way to the moment when it calls the next middleware, that is MidB. MidB is executed all the way to the moment when it calls Ctrl. Ctrl then throws an exception none of the middlewares knows about. The execution never comes back to the middlewares. They are never finished.

After I faced this problem I decided to take a look at other people's code in the hope of finding a solution which wouldn't require rewriting the existing code. The only thing I found was to register an event handler (with the proper priority) and finish the broken control flow within this event handler. To be honest, I find this unbelievably complicated. The flow of control is broken into implicitly connected tiny pieces of code which are scattered all over the codebase. It's very hard to answer questions which seem to be trivial, like "is the second line of this method going to be executed?" or "which piece of code will run next?".

I used to be a big fan of exceptions. I read about them in Java books, learnt how to catch them. But with time I grew to dislike them. I've noticed the hidden GOTO. When I'm writing a function which may return 3 different values, I simply make it return 3 different values. I don't pick my favorite type just to make the two remaining ones jump somewhere else dressed as exceptions.

I value the explicit, clean control flow exception-less code gives me. It's simple.

State management in JavaScript: data-related state and behavior-related state

Sat, 24 Mar 2018 10:37:20 GMT

State management is a hot topic in the JavaScript world.

Some libraries promote the use of immutable data structures, while other allow mutations.

Sometimes the whole state is stored in one place, other times it's distributed among many objects.

Not every state container is about pulling things out of it. There are also Hollywood-like (push) solutions which actually call us.

We have various ways to transform events into state changes as well.

And what's nice is that it's not just a theoretical thing. It's not uncommon to find at least few implementations of each combination of these characteristics!

This wide choice of state management techniques gives us the possibility to pick the one we feel comfortable with. If there's a tool which helps us turn business requirements into working software without too much struggle, it's a good tool. It doesn't necessary need to be the exact same thing other people use.

I do really love the richness of the JavaScript ecosystem!

However, all the popular state management solutions I know about, in all their richness, focus solely on dealing with key-value pairs.

Let's have a quick look at some key-value pairs. I wrote them on a whiteboard, because the whiteboard doesn't put many restrictions on the syntax.

Making it part of a JavaScript program isn't hard.

{
  name: 'Łukasz',
  favDish: 'pizza'
}

That's it! Isn't it a wonderful example of a readable, easy to understand part of a program?

I have that feeling that due to their commonness key-value pairs may be underappreciated. All we need to do to leverage their power is to write a bunch of values with their corresponding keys and then refer to them using those keys.

Let's say there's a person. Discovering the favorite dish is that simple:

const favDish = person.favDish;

There's no need to work with pointers, not even numeric indexes! The beginning and the end of data is held under the hood in such a convenient way that in the vast majority of cases we don't even need to think where exactly the actual data ends and garbage memory starts. So many hardware-related aspects of data access are abstracted away! The actual programming looks very much like taking human-readable notes on a whiteboard!

It all makes key-value pairs a model suitable for data-related state, that is state which may usually be consumed without using conditionals. As we can see, it plays well with other declarative techniques such as JSX.

<p>My name is {person.name} and my favorite dish is {person.favDish}.</p>

Even though I do really enjoy using key-value pairs to model data, I must admit that every time I try to use them to describe changes of behavior, they make me struggle.

In order to illustrate my concerns, I'd like show you yet another whiteboard drawing. In this picture I captured all the main screens of a wizard-like application as well as the events which make one screen change to another. To put it another way, it's about behavior-related state.

It's nothing but a directed graph.

An attempt to express it with key-value pairs shows that the graph is completely lost.

//...
const someState = {
  //...
  isABunnyOwner: true,
  enteredTheWholeName: true,
  hasACarrot: false,
  finishedFeeding: true
};
//...
const repeat = (prevState) => ({
  //...
  isABunnyOwner: undefined,
  enteredTheWholeName: false,
  hasACarrot: prevState.hasACarrot,
  finishedFeeding: false,
});
//...
if (isABunnyOwner && enteredTheWholeName && !finishedFeeding) {
  //...
}
//...

What we can see here are not boxes and arrows, but boolean flags and IF statements.

Listing all the possible screens or discovering how the user may go from one screen to another becomes a challenge. It's not so easy anymore like it was when key-value pairs were used to model just data. Now there are boolean flags and IFs to think about.

Some of these problems may be mitigated by extracting functions and grouping them together so they are easier to find. But is it the way to go, or maybe just an attempt to bend an inappropriate model to our needs?

They say that if all you have is a hammer, everything looks like a nail. It seems that it applies to state management as well. If all we have are key-value pairs, everything looks like a value or a key.

Let's step back and try to find a more suitable model. How can we make the drawing visible below part of the program?

What if we could just open an editor and draw it like this?

The code could then forget about the past. There would be no boolean flags at all! IF statements would be unnecessary. This approach could make the complicated code we've seen totally disappear.

Well, it's actually possible! A directed graph like that is a representation of a finite automaton, that is one of the fundamental concepts in computer science. Method calls may be dispatched based upon the current state of the state machine. Thanks to the development of Graphical User Interfaces, we're not tied to text-based interfaces. We can simply draw our graph using a visual editor. This is how we get into the world of visual automata-based programming, where drawings of graphs are not less important than key-value pairs.

The editor screenshot visible above comes from an article about React and visual automata-based programming.

An introduction to visual automata-based programming in Rosmaro

Fri, 02 Mar 2018 10:37:20 GMT

To do automata-based programming is to program with states and transitions. States correspond to different behaviors. Transitions are named after events and describe how those behaviors change. The easiest way to think about this is a directed graph. Here’s an example of a cursed prince:

It may be either a Prince or a Frog. The Prince eating a pizza is an event which causes a transition from the Prince state to the Frog state.

I’m going to show you how to do (visual) automata-based programming in Rosmaro.

Rosmaro is a JavaScript library which allows you to build stateful objects.

An object is stateful when two identical method calls may produce different results.

Here’s an example:

> model.introduceYourself(); 
'I am The Prince of Rosmaro!'
> model.eat({dish: 'yakisoba'}); 
undefined
> model.introduceYourself();
'I am The Prince of Rosmaro!'
> model.eat({dish: 'pizza'});
undefined
> model.introduceYourself();
'Ribbit! Ribbit!'

Another great example of stateful objects is a Graphical User Interface. Think of an ATM. You can look twice at its screen and see different messages and fields. Your eyes are the same. The way you look at the screen hasn’t changed. It’s the state of the ATM that changed. Maybe you selected some option by clicking a button, or maybe some timer kicked in. Something caused a transition from one state to another.

Below are few examples of front-end applications built using visual automata-based programming.

The codebase of this To-Do application consists of no boolean values.

This wizard has two paths. There’s no IF for that.

The Rosmaro way of building stateful objects is to combine a drawn graph with some written code.

The graph shows all the possible behaviors and what makes them change. The fact that it’s drawn using a visual editor makes it a visual programming tool.

Each behavior is expressed as a bunch of pure functions. A function may return some result as well as a request to follow an arrow.

Rosmaro stores the whole state of a model in a pluggable storage mechanism. It may be everything from a plain-old JavaScript object to a NoSQL database. It also uses pessimistic locking to prevent going into an inconsistent state.

The example I want to show you concerns a prince who turns into a frog when he eats a pizza.

First, open the Rosmaro editor. Then, click the LOAD button to start a new project.

Add the main graph.

Click NEW NODE.

Add a local node called Prince.

Then, add a local node called Frog.

Put your mouse cursor over the start entry point and draw an arrow to the Prince node. Then, draw an arrow from the Prince to the Frog and call it ate pizza. Finally, click ADD NODE.

Add a leaf called Prince.

Then, add a leaf called Frog.

To complete the main graph, associate local nodes with the recently added leaves.

The graph is ready. Click the button called GENERATE CODE.

It’s time to write some JavaScript. First, you need to get all the dependencies.

npm i rosmaro rosmaro-in-memory-storage rosmaro-process-wide-lock --save

Then, you need to import and call them.

import makeStorage from 'rosmaro-in-memory-storage';
import makeLock from 'rosmaro-process-wide-lock';
import rosmaro from 'rosmaro';

// The model is going to be built here.

const storage = makeStorage();
const lock = makeLock();
const model = rosmaro({graph, handlers, storage, lock});

// The model is going to be used here.

The generated graph may be either imported as a JSON file, or pasted directly into the code. To keep this example as simple as possible, I suggest pasting it into the code.

const graph = {
  "main": {
    "type": "graph",
    "nodes": {
      "Prince": "Prince",
      "Frog": "Frog"
    },
    "arrows": {
      "Prince": {
        "ate pizza": {
          "target": "Frog",
          "entryPoint": "start"
        }
      }
    },
    "entryPoints": {
      "start": {
        "target": "Prince",
        "entryPoint": "start"
      }
    }
  },
  "Prince": {
    "type": "leaf"
  },
  "Frog": {
    "type": "leaf"
  }
};

A frog is certainly a simpler creature than a prince. Implementing its behavior is easy. Every time we ask the frog to introduce itself, it says “Ribbit! Ribbit!”.

const Frog = {
  introduceYourself: () => "Ribbit! Ribbit!"
};

The prince not only introduces himself, but also pays attention to the things he eats. He may eat a yakisoba and everything is fine. But as soon as he eats a pizza, he follows the arrow called ate pizza.

const Prince = {
  introduceYourself: () => "I am The Prince of Rosmaro!",
  eat: ({dish}) => {
    if (dish === 'pizza') return {arrow: 'ate pizza'};
  }
};

It’s time to put the handlers all together.

const handlers = {Frog, Prince};

The model is ready. Here’s the complete code:

import makeStorage from 'rosmaro-in-memory-storage';
import makeLock from 'rosmaro-process-wide-lock';
import rosmaro from 'rosmaro';

const graph = {
  "main": {
    "type": "graph",
    "nodes": {
      "Prince": "Prince",
      "Frog": "Frog"
    },
    "arrows": {
      "Prince": {
        "ate pizza": {
          "target": "Frog",
          "entryPoint": "start"
        }
      }
    },
    "entryPoints": {
      "start": {
        "target": "Prince",
        "entryPoint": "start"
      }
    }
  },
  "Prince": {
    "type": "leaf"
  },
  "Frog": {
    "type": "leaf"
  }
};

const Frog = {
  introduceYourself: () => "Ribbit! Ribbit!"
};

const Prince = {
  introduceYourself: () => "I am The Prince of Rosmaro!",
  eat: ({dish}) => {
    if (dish === 'pizza') return {arrow: 'ate pizza'};
  }
};

const handlers = {Frog, Prince};

const storage = makeStorage();
const lock = makeLock();
const model = rosmaro({graph, handlers, storage, lock});

Identical calls to the introduceYourself method return different values. The returned value depends on events which occurred in the past. It proves that the model object is stateful.

console.log(model.introduceYourself()); // I am The Prince of Rosmaro!
console.log(model.eat({dish: 'yakisoba'})); // undefined
console.log(model.introduceYourself()); // I am The Prince of Rosmaro!
console.log(model.eat({dish: 'pizza'})); // undefined
console.log(model.introduceYourself()); // Ribbit! Ribbit!

The code of The Cursed Prince is on GitHub. It makes use of only basic Rosmaro features. When working on real apps, you’ll want to use more advanced techniques. Some of them include subgraphs, dynamic orthogonal regions, and the context object.

You can learn more about Rosmaro from its official documentation.

Programming without boolean values: To-Do App

Sun, 25 Feb 2018 10:37:20 GMT

Since I discovered functional programming, I knew I could build a To-Do app without writing my own variables. I did some tutorials and got a working app.

Since I discovered automata-based programming, I knew I could build a To-Do app without writing my own IFs or booleans. Well, theoretically. I hadn't done it before.

I started to wonder if I could actually build a To-Do app not only without variables, but also without writing any code resembling the fragments visible below.

if (isDone)
isDone ? ... : ...
value || defaultValue
showIf="model.isDone"
selected === "all"

It turns out that with Rosmaro it's possible!

In this post I'm going to present the solutions to some of the challenges I faced. To keep this post short, I'm not going to cover basics of Rosmaro. If you would like to learn more about it, please take a look at the official documentation or my other posts, like the one about react and visual automata-based programming.

The whole code of the bool-less To-Do app is on GitHub. You'll also find there a demo.

The main node - graph

There are some things that never change. At the top of the screen, there's always the form. It's followed by the list of items to do. The navigation comes last. That's what makes a composite a perfect candidate for the main node. It reflects the intended behavior - few simultaneously working areas which never change from one to another.

We'll come back to the code handling the main node at the end, because it's necessary to know how do Items and Navigation render.

The form - graph and code

The form is simple. It doesn't differ from the one described in the react and visual automata-based programming post.

It's built using two nodes:

a graph called NewItemForm
a leaf called NewItemFormView

The NewItemForm graph exists only to handle loops from NewItemFormView back to NewItemFormView. It makes it possible to update the context when the user types the content of a new item or adds a new item.

Here's the code of the view:

const NewItemFormView = {
  type: ({ctx, newItemText}) => ({
    arrow: 'typed',
    ctx: {...ctx, newItemText}
  }),
  addItem: ({ctx}) => ({
    arrow: 'item added',
    ctx: {
      ...ctx,
      newItemText: '',
      items: [...ctx.items, ctx.newItemText]
    }
  }),
  render: ({ctx, thisModel}) => 
    <form>
      <input
        type="text"
        className="item-form-field"
        value={ctx.newItemText}
        onChange={e => thisModel.type({newItemText: e.target.value})}
        />
      <input
        type="button"
        className="item-form-button"
        value="Add"
        onClick={() => thisModel.addItem()}
        />
    </form>
};

As we can see, this handler works with a context shaped like this:

{
  newItemText: 'what is the user typing',
  items: ['the first thing to do', 'the second thing to do']
}

What's very important to notice is that new items are always added at the end of the array. That way the index of an item never changes. If it was added at the third position, it stays at the third position. I promise you that soon it will become clear why does it matter.

How does the navigation work without booleans?

There are no IFs. There are no filters. How does it work then?

It involves three nodes:

Navigation
Items
main

When Items are rendered, they produce an array like this:

[
  {
    all: somehowRenderedItem,
    done: somehowRenderedItem,
    undone: somehowRenderedItem,
  },
  {
    all: somehowRenderedItem,
    done: somehowRenderedItem,
    undone: somehowRenderedItem,
  },
  //...
]

Each element of this array corresponds to one item to do.

Keys all, done, and undone correspond to filter settings. Values are views. When the current navigation settings indicate that the user wants to see just undone items, the proper way to display the list of items is to display the values stored under undone keys. Some values will be fully rendered views, and some will be nulls (so they simply won't show).

But how do we know which key should be displayed?

When the Navigation is rendered, it doesn't return just the view. It returns a structure shaped like this:

{UI, show}

Under the UI key, there's the view. The value under the show key is a map function.

show([
  {
    all: somehowRenderedItem,
    done: somehowRenderedItem,
    undone: somehowRenderedItem,
  },
  {
    all: somehowRenderedItem,
    done: somehowRenderedItem,
    undone: somehowRenderedItem,
  }
]) // => [somehowRenderedItem, somehowRenderedItem]

The common ancestor of Items and Navigation, that is the main node, passes the result of the Items' render function to the show function returned by the Navigation node.

const main = {
  initCtx: {newItemText: '', items: []},
  afterRender: ({res}) => 
    <div className="container">
      {res.NewItemForm}
      <ul className="todos">
        // Here the *show* function picks proper views.
        {res.Navigation.show(res.Items)}
      </ul>
      {res.Navigation.UI}
    </div>
};

How do navigation buttons change?

The navigation may be in one of the following states:

showing all items
showing only done items
showing only undone items

They all may be the children of one graph. The only problematic thing are the transitions. Each node must be connected with every other node. In order to limit the number of required arrows, I used custom entry points and loops.

This is what does the Navigation node look like: And here's the view:

Every time the user clicks the Undone button, it makes the current node of the view (either All, Done or Undone) follow the navigating to undone arrow.

Because there's no such arrow within the NavigationView graph, it makes the Navigation's View local node follow this arrow. It's similar to event bubbling.

When the View node follows the arrow called navigating to undone, it makes a loop entering through the undone entry point.

When the View graph is entered through the undone entry point, the Undone child becomes the active node.

That way we can avoid transition explosion when we're adding another navigation state. It will always require no more than 2 arrows.

Each handler is coded like that:

const NavigationUndone = {
  ...navigationHandlers,
  render: ({thisModel}) => ({
    // How does it *look*.
    UI: <div>
      {inactiveButton({thisModel, text: 'All', method: 'navigateToAll'})}
      {inactiveButton({thisModel, text: 'Done', method: 'navigateToDone'})}
      {activeButton({text: 'Undone'})}
    </div>,
    // This is the map function described above. It's built using Ramda.
    show: map(prop('undone'))
  })
};

Is this done? The graph will tell!

There's no boolean value indicating whether an item is done. Instead, it's expressed by a drawn graph. We can clearly see that a new item is not done. Clicking it marks it as done. Clicking it again marks it as undone.

Handlers of the leaves make use of a feature which hasn't been mentioned yet - calling methods of a single node instead of the whole model.

const UndoneItem = {
  render: ({ctx: {title, id}, thisModelNode}) => {
    const view = <li className="undone" onClick={() => thisModelNode.clickItem()} key={id}>
      {title}
    </li>;
    return {
      all: view,
      done: null,
      undone: view,
    };
  },
  clickItem: () => ({'arrow': 'clicked'})
};

By using thisModelNode instead of thisModel we make sure that clicking an item calls the clickItem method of this very item and not its siblings.

Here we can also see that when the navigation asks for done items, an undone item doesn't render (it returns null instead of its view).

How is the list of items created?

We saw above that a single item is a graph. It also expects a context like this:

{title, id}

But there may be many items to do, not just one. And the context of the whole model doesn't look like this.

How does it work? It makes use of dynamic composites and context lenses. You can find more information about dynamic composites in the documentation of Rosmaro.

The Items node is a dynamic composite which uses the Item graph as a template.

The handler of Items provides a function of the context which returns the list of its children. In this case, they are named after indexes of the array which stores all the items to do. For the purposes of this simple To-Do app, those indexes serve as unique identifiers of the items. That's why it's so important to always add new items at the end of the array - otherwise their identifiers would change.

const Items = {
  nodes: ({ctx}) => keys(ctx.items),
  afterRender: ({res}) => reverse(values(res))
};

Because we want see the recent items at the top of the list, we reverse the result of rendering all the items.

OK, so that's how the list is created. But what about the context? It's shaped by a lens attached to the handler of the Item graph.

const Item = {
  ctxLens: ({localNodeName}) => lens(
    (ctx) => ({
      id: localNodeName,
      title: ctx.items[localNodeName]
    }),
    ({title}, ctx) => ({
      ...ctx, 
      items: update(parseInt(localNodeName, 10), title, ctx.items)
    })
  )
};

Under the ctxLens key there's a factory function of a Ramda lens. The factory takes the local name of the node. In this case is an index of an item. We know this, because that's what does the nodes function of the Items node handler do.

Because Item nodes only read the context and never cause transitions which could update it, the only part of the lens which really matters is the one which zooms the context in. It's this one:

(ctx) => ({
  id: localNodeName,
  title: ctx.items[localNodeName]
})

So when the localNodeName equals "1" and the context looks like this:

{
  items: ['first', 'second', 'third']
}

The Item node is going to see context like this:

{
  id: "1", // because node names are always strings based on array indexes starting at 0
  title: "second"
}

Conclusion

In many situations boolean values are not the only way to program conditional logic. With visual automata-based programming it's possible to replace them with drawings of boxes connected with arrows and boolean-free code.

Thank you for reading this!

React and visual automata-based programming

Tue, 16 Jan 2018 15:37:20 GMT

Introduction

This post consists of three parts. In the first one I'm telling about my journey to visual automata-based programming. The second one shows the process of building a GUI using visual automata-based programming. The code is written in JavaScript and React is used to render the view. The last part is a summary of my experience with state machines where I explain how did they change the way I think about state management.

The problem I had

There's something that used to make me struggle a lot every time I was working on a GUI. It's the fact that views change. The user clicks a button and BAM! Sometimes just a small part of the view changes, sometimes the whole view is replaced with a new one. Moreover, they not only change, but also depend on each other! It's not anymore like in the good old days, when we had few static HTML files linking to each other. Every time we visited a particular document, it looked the same (I know, I know, maybe some links were purple and not blue, that's it). Nowadays in web-applications views often depend on events which occurred in the past. Sometimes they display data entered few steps before. Sometimes clicking the same button causes totally different actions depending on what happened earlier.

How was I dealing with it?

There was always some map structure, like a database record, a session object or a plain old JavaScript object that was representing the state of the application. I was then putting conditional statements here and there to compute boolean values based on the state and decide which tiny part of the whole code should actually run.

This approach was good enough, when there were just few screens and they were always changing in the same order, like from A to B and then to C.

When things were getting out of control

Sadly, every time when the number of views was increasing or there was more than just one path the user could take, I was loosing control of all the IFs. When implementing a new feature, I was constantly asking myself:

Is there any other IF I need to update after this change?

Answering this question wasn't so easy, especially when I was working on server-side applications, where forgetting to limit access to some view can potentially lead to insecure direct object references. My development process felt like a dirty hack. In the end what I was doing was using IFs to tell which part of the code should run and which shouldn't.

Moreover, it wasn't just me who was asking questions about the system. Except the case when I was working on my personal projects, there were always some people I was working for. They were also asking questions like the following two.

What are all the ways a user can go from the screen A to the screen B?

Can we add an intermediate step between A and B?

Very often, even though I had the project opened in the editor, I couldn't quickly answer those questions. In order to reach the IFs responsible for the behavior, I needed to dig deep into the code. It was giving me a headache.

From sketching to the discovery of automata-based programming

I became a big fan of sketching. Nothing fancy, just some pictures representing the overall behavior of the code I was working on. Like here's a screen like this, something happens and we get that different screen. Very much like user flows we get from UX experts or... one of the fundamental concepts in computer science - state machines. This is the time when I started wondering if I could make use of state machines in my day to day job. I knew that they could be useful if I were about to do things like parsing a language or drawing a representation of a turnstile. But could they help me to program web applications?

There's a wide term called automata-based programming. The Wikipedia definition of automata-based programming goes like this.

Automata-based programming is a programming paradigm in which the program or part of it is thought of as a model of a finite state machine (FSM) or any other (often more complicated) formal automaton (see automata theory).

The idea of making a set of boxes connected with arrows the skeleton of an application always sounds great to me! It's like bringing my sketches to life, or at least making the gap between the language used to program and the language used to design a lot smaller. So I started with a data structure representing the graph and possible transitions. It was very much like transition tables. Soon it turned out that a simple state machine function, which takes the current state and an event and returns a new state, wasn't sufficient, because I still needed to use some conditional statements to determine what to do based on its result. So the very next thing I did was using this graph description as a recipe for a stateful object, which responsibility was to call functions based on the current node of the graph. Since then I experimented a lot and changed many details, but this is one of the things I haven't changed. I really wanted to run away from IFs and method dispatch based on the state of a state machine finally allowed me to do it. It felt like a relief! I got hooked on automata-based programming.

I missed drawing

It became clear to me that many of the problems I used to consider hard to code can be easily solved using elegant graphs. I do really enjoy expressing logic as graphs! But I must say that when it comes to transition tables, I like them a lot less. To me, it's harder to wrap my head around a transition table. When I take a look at simple graph, I can immediately get basic understanding of what's going on. But when I look at a transition table, it takes me a while. Most of the time I try to imagine a graph in my head. When it's too complicated, I grab a pen and draw the graph, so I can look at it. I think you already know what I am going to say. Programming by coding graphs is fun, but not that much fun as programming by drawing graphs! That's why I decided to build a graphical editor that would generate the graph code based on a drawing. This way I could code just what I find handy to code and draw the rest. And that's how I got into visual automata-based programming.

This is how I was programming a simple graph, when I started playing with the idea of automata-based programming in 2016.

'locked',
[
    'locked' => [
        'still_fine' => 'locked',
        'hit_too_many_times' => 'broken'
    ],
    'broken' => []
]

And this is how I prefer to program it nowadays.

In this post I'd like to show you the whole process of building a GUI, which illustrates all the things I like about state machines applied to web applications.

What we're going to build

We're going to build a client-side application with few screens. At the home screen the user is asked whether she is a bunny owner. The next step is always about entering the user name. Then, bunny owners need to feed their bunnies before they can see the "thank you" message. Those who have no bunnies see "thank you" right after entering their names. It's important to note that the bunny is hungry every time we see it and that we need to first find a carrot before we can give it to the bunny.

Here are few whiteboard drawings showing how screens change.

The toolbox

The two most important libraries used to implement the application are:

React to render the UI
Rosmaro to model changes of the UI

For testing purposes we're going to use the following tools:

Enzyme (to make assertions easier)
Jest (it allows to run our tests and ships with useful matchers)
Sinon (to make sure the UI makes proper function calls)

All the packages are going to be installed using npm and the project is going to be bootstrapped with Create React App.

React is going to be used mostly as a Virtual DOM library and a convenient starter kit thanks to Create React App, while both the data-related state and behavior-related state are going to be managed using Rosmaro.

Setting up the environment

Let's fire up the terminal and use Create React App to bootstrap our project.

create-react-app bunny-app
cd bunny-app

Please bear in mind that in order for this command to work, you'll need to have node, npm and create-react-app installed.

The generated index.js file looks like this.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import registerServiceWorker from './registerServiceWorker';

ReactDOM.render(<App />, document.getElementById('root'));
registerServiceWorker();

Now we're going to install packages related to Rosmaro.

npm install --save rosmaro rosmaro-in-memory-storage rosmaro-process-wide-lock rosmaro-react

Then, the App element is going to be replaced with the RosmaroReact element. Because we won't need App.css, App.js, App.test.js, we can safely remove those files together with their imports.

The index.js file should now look like this.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import makeStorage from 'rosmaro-in-memory-storage';
import makeLock from 'rosmaro-process-wide-lock';
import RosmaroReact from 'rosmaro-react';
import graph from './graph.json'; // The generated graph
import handlers from './handlers/all';
import registerServiceWorker from './registerServiceWorker';

const rosmaroOpts = {
  graph,
  handlers,
  storage: makeStorage(),
  lock: makeLock()
};

ReactDOM.render(<RosmaroReact {...rosmaroOpts} />, document.getElementById('root'));
registerServiceWorker();

Let's go step by step through the modified file.

Rosmaro-related packages are imported.

import makeStorage from 'rosmaro-in-memory-storage';
import makeLock from 'rosmaro-process-wide-lock';
import RosmaroReact from 'rosmaro-react';

The rosmaro package itself is not being imported, because it's already a peer dependency of rosmaro-react

We've replaced the App element with the RosmaroReact element.

const rosmaroOpts = {
  graph,
  handlers,
  storage: makeStorage(),
  lock: makeLock()
};

ReactDOM.render(<RosmaroReact {...rosmaroOpts} />, document.getElementById('root'));

For better understanding of rosmaroOpts please take a look at the Building a model chapter of the Rosmaro documentation.

As you may have noticed, there are two extra imports.

import graph from './graph.json'; // The generated graph
import handlers from './handlers/all';

They are the two main ingredients of a Rosmaro model we haven't created yet:

a graph describing changes of behavior
pieces of code handling different behaviors

Let's start by creating empty files:

mkdir src/handlers && touch src/handlers/all.js && touch src/graph.json

At this point only test libraries are missing.

npm install --save sinon enzyme enzyme-adapter-react-16 react-test-renderer

According to the documentation of Enzyme this is how we setup the tests.

// src/setupTests.js
import { configure } from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';

configure({ adapter: new Adapter() });

That's pretty much it! The environment is ready.

This command, provided by Create React App, starts a dev server.

npm run start

And this is how we run the tests

npm run test

Modeling changes of behavior using the Rosmaro Editor

It's time to fire up the Rosmaro editor. Because our graph.json file is empty, there's nothing to import. We can simply click LOAD to start drawing a new graph.

Every Rosmaro model must have a main node. In our case it's the following graph.

We add it by clicking ADD NODE and typing its name.

Now we're going to add the first graph child.

In order to make binding handlers convenient, we're going to use CamelCase node names. That's why we're adding a local node called IsABunnyOwner.

Local nodes are what we draw as children of composites and graphs. Handlers cannot be associated with local nodes. Actual nodes are used as underlaying nodes for local nodes. They may be associated with handlers.

In the whiteboard drawing there are two nodes called ENTERING THE NAME. Because Rosmaro local nodes must have unique names, we're simply going to call them EnteringTheName #1 and EnteringTheName #2.

Then, we add the remaining local nodes: FeedingTheBunny and Thanks in the same way.

Now it's time to add arrows. In order to do it, we need to put the cursor over some node, aim the square handler displayed on it and drag a line from it to another node.

At this point, the newly created arrow can be customized. All we need to do is to click it and then enter its new name. This one is going to be called has a bunny and will tell us what happens when the user has a bunny - she goes from the home screen to the screen where she's supposed to enter her name.

Let's draw all the remaining arrows and call them after events which cause behavior changes.

This graph isn't finished yet. The whiteboard drawing wasn't perfectly detailed. There are at least two missing elements:

the initial node
underlaying nodes

We need to specify that this graph starts from the IsABunnyOwner node. All we need to do is to draw an arrow from the start entry point to the IsABunnyOwner node.

Selecting underlaying nodes means specifying which graph node actually lays under a local graph node. For example, there's the IsABunnyOwner local node. But what's its type? Is this a leaf? Or maybe it's a subgraph? In order to make it clear, we need to add an actual node and wire it with the local node. It may sound a bit complicated, but it's actually pretty simple. Here's how we do it.

First, we need to create the actual node. We do it exactly in the same way the main node was created, because main is an actual node as well.

Then, we go back to the main node, select the IsABunnyOwner local node and select the IsABunnyOwner actual node as its underlaying node. That's it!

The Thanks node is a leaf as well. We add and wire it in the same way as we did it with the IsABunnyOwner node.

Nodes EnteringTheName #1 and EnteringTheName #2 are a bit more interesting, because even though they are two separated local nodes from the point of view of the main node, they utilize the exact same actual node as their underlaying nodes. That's why we add just one actual node EnteringTheName.

Then we pick it as the underlaying node for both EnteringTheName #1 and EnteringTheName #2.

FeedingTheBunny is going to be far more complicated. Here's how we decided that it has two regions:

the bunny itself
controls for carrots (looking for carrots and giving them to the bunny)

It makes it a composite with two children.

Let's start from the most important part - the bunny. It can be:

hungry
eating
full

Here's how does TheBunny look.

We cannot forget about underlaying nodes. There are three of them:

AHungryBunny
AnEatingBunny
AFullBunny

They are simple enough to be leaves. We add them in the same way how we added other leaves.

This is how CarrotControls look in the editor.

Both LookingForACarrot and GivingTheCarrot are leaves. They must be added and have their underlaying nodes selected.

At this point, all nodes and arrows are drawn. We're one click away from generating the src/graph.json file! All we need to do is to click the GENERATE CODE button.

The generated code should be saved as src/graph.json.

If for some reason you get an error saying that the code cannot be generated, please make sure that all local nodes have their underlaying nodes selected.

Coding different behaviors

After having some (I hope) good time drawing, it's time to code a bit. We're going to start from the handler of the IsABunnyOwner node. The first step is to create a handler file, which in this case is called IsABunnyOwner.js and it's located in the handlers directory.

// src/handlers/IsABunnyOwner.js

import React from 'react';

export default {

  render: () => <div>
    <p>Do you have a bunny?</p>
    <input
      type="button"
      value="Yes, I have a bunny!"
      />
    <input
      type="button"
      value="No, I don't have a bunny."
      />
  </div>

};

A quick look at its render method reveals that it gives the user a choice by displaying two buttons. Let's make sure it actually renders without crashing. We will need a test for this handler. All we need to do is to create a file called IsABunnyOwner.test.js which is located in the same directory.

// src/handlers/IsABunnyOwner.test.js

import React from 'react';
import IsABunnyOwner from './IsABunnyOwner';
import {shallow} from 'enzyme';

describe('IsABunnyOwner', () => {
  let wrapper;
  beforeEach(() => {
    wrapper = shallow(IsABunnyOwner.render());
  })

  it('renders two buttons', () => {
    expect(wrapper.find('input[type="button"]').length).toEqual(2);
  });

});

Now, when we run the following command, we can make sure that it actually renders two buttons.

npm test

The graph tells us that we expect the IsABunnyOwner node to follow either has no bunny or has a bunny arrow. Here's the complete handler code.

// src/handlers/IsABunnyOwner.js

import React from 'react';

export default {

  hasABunny: () => ({arrow: 'has a bunny'}),

  hasNoBunny: () => ({arrow: 'has no bunny'}),

  render: ({thisModel}) => <div>
    <p>Do you have a bunny?</p>
    <input
      type="button"
      value="Yes, I have a bunny!"
      onClick={() => thisModel.hasABunny()}
      />
    <input
      type="button"
      value="No, I don't have a bunny."
      onClick={() => thisModel.hasNoBunny()}
      />
  </div>

};

The render method takes a reference to the model object. It can be used to build event handlers which call methods of the Rosmaro model. In this case, the same handler that renders the UI, also handles method calls. That's why there are functions hasABunny and hasNoBunny. All they need to do is to return the arrow we want the model to follow when they're called. If you want, you can find more about this in the documentation chapter about method handlers.

And here is the test case. Please notice how Sinon spy objects are used to make sure that clicking a button actually triggers a model method.

// src/handlers/IsABunnyOwner.test.js

import React from 'react';
import IsABunnyOwner from './IsABunnyOwner';
import {shallow} from 'enzyme';
import sinon from 'sinon';

describe('IsABunnyOwner', () => {
  let wrapper, thisModel;
  beforeEach(() => {
    thisModel = {
      hasABunny: sinon.spy(),
      hasNoBunny: sinon.spy()
    };
    wrapper = shallow(IsABunnyOwner.render({thisModel}));
  })

  it('renders two buttons', () => {
    expect(wrapper.find('input[type="button"]').length).toEqual(2);
  });

  it('calls .hasABunny when "Yes, I have a bunny!" is clicked', () => {
    wrapper.find('input[value="Yes, I have a bunny!"]').simulate('click');
    expect(thisModel.hasABunny.called).toBeTruthy();
  });

  it('calls .hasNoBunny when "No, I don\'t have a bunny." is clicked', () => {
    wrapper.find('input[value="No, I don\'t have a bunny."]').simulate('click');
    expect(thisModel.hasNoBunny.called).toBeTruthy();
  });

  it('simply follows an arrow when .hasNoBunny is called', () => {
    expect(IsABunnyOwner.hasNoBunny()).toEqual({arrow: 'has no bunny'});
  });

  it('simply follows an arrow when .hasABunny is called', () => {
    expect(IsABunnyOwner.hasABunny()).toEqual({arrow: 'has a bunny'});
  });

});

When it comes to the home screen of our application, the only thing left to do is to wire the handler with the graph node. At the beginning of this article we created the src/handlers/all.js file. All it's responsible for is to provide a map connecting graph nodes with their handlers. This is how does it look with the first handler.

// src/handlers/all.js

import IsABunnyOwner from './IsABunnyOwner';

export default {
  IsABunnyOwner,
};

And that's how we finished the home screen of our app.

The node meant to enter the name, that is EnteringTheName, behaves slightly different. It not only follows arrows, but also alters the context of the Rosmaro model.

You can think of context as of something similar to state from React or store from Redux.

In order to set the default value of the user name, we're going to wire a simple handler to the main node.

// src/handlers/main.js

export default {

  initCtx: {
    name: 'Unknown person'
  }
  
};

The list of all handlers must be updated.

// src/handlers/all.js

// ... previously imported handlers
import main from './main';

export default {
  // ... previously exported handlers
  main,
};

Since now, every time a child of the main node reads ctx.name before the context is set to any non-empty value, it's going to read Unknown person.

The EnteringTheName handler renders a text field and a button.

// src/handlers/EnteringTheName.js

import React from 'react';

export default {

  render: ({ctx}) => <div>
    <p>Please, enter your name.</p>
    <input
      type="text"
      value={ctx.name}
      />
    <input
      type="button"
      value="Done"
      />
  </div>

};

// src/handlers/all.js

// ... previously imported handlers
import EnteringTheName from './EnteringTheName';

export default {
  // ... previously exported handlers
  EnteringTheName,
};

Please note how we read the name property of the context. The method is called with an object. It has a property called ctx, which is the context. We read it using object destructing.

We want to make sure the view renders without crashing and that it sets the value of the text field to the name read from the context.

// src/handlers/EnteringTheName.test.js

import React from 'react';
import EnteringTheName from './EnteringTheName';
import {shallow} from 'enzyme';
import sinon from 'sinon';

describe('EnteringTheName', () => {
  const initCtx = {name: 'Joh', another: 123};
  let wrapper, thisModel;
  beforeEach(() => {
    thisModel = {};
    wrapper = shallow(EnteringTheName.render({thisModel, ctx: initCtx}));
  })

  it('renders a text field and a button', () => {
    const field = wrapper.find('input[type="text"]');
    expect(field.length).toEqual(1);
    expect(field.props().value).toEqual('Joh');
    expect(wrapper.find('input[type="button"][value="Done"]').length).toEqual(1);
  });

});

Adding the behavior responsible for handling the Done button is very similar to what we did in order to handle buttons rendered by the IsABunnyOwner node.

// src/handlers/EnteringTheName.js

import React from 'react';

export default {

  finishEnteringTheName: () => ({arrow: 'done'}),

  render: ({thisModel, ctx}) => <div>
    <p>Please, enter your name.</p>
    <input
      type="text"
      value={ctx.name}
      />
    <input
      type="button"
      value="Done"
      onClick={() => thisModel.finishEnteringTheName()}
      />
  </div>

};

To sum it up, in order to handle a button click that makes the model follow an arrow, we need to:

register an event listener that calls a model method
create a model method that follows an arrow

The thing that makes the EnteringTheName node more interesting than other nodes with buttons is that it handles typing on the keyboard as well. We want to let the user type her name, what means altering the name context parameter. The only way to update the context is by doing a transition. That's why we're going to need an extra arrow - to handle a situation when the name is being typed but it's not ready yet so we don't want to change the screen.

Now we can register an event listener that will call a model method meant to do a transition and set the new value of the name.

// src/handlers/EnteringTheName.js

import React from 'react';

export default {

  typeName: ({ctx, name}) => ({
    arrow: 'typed',
    ctx: {...ctx, name}
  }),

  finishEnteringTheName: () => ({arrow: 'done'}),

  render: ({thisModel, ctx}) => <div>
    <p>Please, enter your name.</p>
    <input
      type="text"
      value={ctx.name}
      onChange={e => thisModel.typeName({name: e.target.value})}
      />
    <input
      type="button"
      value="Done"
      onClick={() => thisModel.finishEnteringTheName()}
      />
  </div>

};

The most common mistake I make writing handlers like this is to replace the whole context instead of updating just one field. Let's take a look at its test case.

// src/handlers/EnteringTheName.test.js

import React from 'react';
import EnteringTheName from './EnteringTheName';
import {shallow} from 'enzyme';
import sinon from 'sinon';

describe('EnteringTheName', () => {
  const initCtx = {name: 'Joh', another: 123};
  let wrapper, thisModel;
  beforeEach(() => {
    thisModel = {
      // ...
    };
    wrapper = shallow(EnteringTheName.render({thisModel, ctx: initCtx}));
  })

  // ...

  it('updates the name when .typeName is called', () => {
    expect(EnteringTheName.typeName({ctx: initCtx, name: 'John'})).toEqual({
      arrow: 'typed',
      ctx: {name: 'John', another: 123}
    });
  });

});

If you were wondering what's the point of the {another: 123} part of the context, this is the answer - to make sure it's not accidentally removed. This handler is meant to update the name property. It shouldn't touch other properties. There's one more thing about the EnteringTheName node I'd like to mention about. Let's have a look at the main graph one more time.

As we can see, when the name is entered, the user lands on either the FeedingTheBunny screen or the Thanks screen. What's cool is that the code responsible for handling the Done button always does the same - it makes the model follow an arrow called done. There is no IF for that. It's not parametrized using a boolean flag neither. It's all about where is the arrow pointing at.

We're getting closer to the most complicated part which is the FeedingTheBunny node and its children. The node itself is a composite of two nodes: TheBunny and CarrotControls. Both of those nodes handle the render method in their own ways. In order to make the composite render correctly, we need to make its render method return a merged result of the render method of TheBunny and the render method of CarrotControls. This is how we can use altering results to achieve this.

// src/handlers/FeedingTheBunny.js

import React from 'react';

export default {

  afterRender: ({res}) => <div>
    {res.TheBunny}
    <hr/>
    {res.CarrotControls}
  </div>

};

// src/handlers/all.js

// ... previously imported handlers
import FeedingTheBunny from './FeedingTheBunny';

export default {
  // ... previously exported handlers
  FeedingTheBunny,
};

This is its test case.

// src/handlers/FeedingTheBunny.test.js

import React from 'react';
import FeedingTheBunny from './FeedingTheBunny';
import {shallow} from 'enzyme';
import sinon from 'sinon';

describe('FeedingTheBunny', () => {

  it('renders the bunny and carrot controls', () => {
    const wrapper = shallow(FeedingTheBunny.afterRender({
      res: {
        TheBunny: <span id="the-bunny" />,
        CarrotControls: <span id="carrot-controls" />,
      }
    }));
    expect(wrapper.find('#the-bunny').length).toEqual(1);
    expect(wrapper.find('#carrot-controls').length).toEqual(1);
  });

});

We're going to start from the CarrotControls graph. What makes it special is that it calls model methods which are handled by two handlers:

the controls themselves (when we give a carrot away, we don't have it anymore)
the bunny (when the bunny is given a carrot, it's not hungry anymore) First, let's do the controls.

// src/handlers/LookingForACarrot.js

import React from 'react';

export default {

  lookForACarrot: () => ({arrow: 'found a carrot'}),

  render: ({thisModel}) => <div>
    <p>You don not have a carrot to give to your bunny.</p>
    <input
      type="button"
      value="Look for a carrot"
      onClick={() => thisModel.lookForACarrot()}
      />
  </div>

};

// src/handlers/GivingTheCarrot.js

import React from 'react';

export default {

  giveTheCarrot: () => ({arrow: 'gave the carrot'}),

  render: ({thisModel}) => <div>
    <p>You have a carrot. You can give it to your bunny.</p>
    <input
      type="button"
      value="Give the carrot"
      onClick={() => thisModel.giveTheCarrot()}
      />
  </div>

};

// src/handlers/all.js

// ... previously imported handlers
import LookingForACarrot from './LookingForACarrot';
import GivingTheCarrot from './GivingTheCarrot';

export default {
  // ... previously exported handlers
  LookingForACarrot,
  GivingTheCarrot,
};

These buttons simply change between Look for a carrot and Give the carrot. They do it by calling model methods like giveTheCarrot. And I must tell you a secret - TheBunny is especially interested in getting a carrot.

To make TheBunny children a bit simpler, we're going to give them just a slice of the whole context. The whole context looks like this.

{
  name: 'Łukasz',
  bunny: {ateCarrots: 3}
}

But we want TheBunny and its children to see just this.

{
  ateCarrots: 3
}

It turns out to be very easy with context slices. All we need to do is to write a simple handler for TheBunny.

// src/handlers/TheBunny.js

export default {
  ctxSlice: 'bunny'
};

// src/handlers/all.js

// ... previously imported handlers
import TheBunny from './TheBunny';

export default {
  // ... previously exported handlers
  TheBunny,
};

Now we can create AHungryBunny. It will handle the same method call which makes the controls change from GiveTheCarrot to LookingForACarrot, that is giveTheCarrot.

// src/handlers/AHungryBunny.js

import React from 'react';

export default {

  giveTheCarrot: ({ctx}) => ({
    arrow: 'ate a carrot',
    ctx: {
      ...ctx,
      ateCarrots: 1
    }
  }),

  render: () => <p>
    <span role="img" aria-label="A hungry bunny">🐰</span> 
    This is a hungry bunny.
  </p>

};

// src/handlers/all.js

// ... previously imported handlers
import AHungryBunny from './AHungryBunny';

export default {
  // ... previously exported handlers
  AHungryBunny,
};

Every time we call the giveTheCarrot method, the node called GivingTheCarrot follows the arrow called gave the carrot and the node called AHungryBunny follows the arrow called ate a carrot (and sets the number of ate carrots to 1).

When AHungryBunny eats a carrot it becomes AnEatingBunny.

// src/handlers/AnEatingBunny.js

import React from 'react';

export default {

  giveTheCarrot: ({ctx}) => {
    const ateCarrots = ctx.ateCarrots + 1;
    const arrow = ateCarrots >= 5 
      ? 'ate 5 carrots' 
      : 'ate a carrot';
    return {
      arrow,
      ctx: {
        ...ctx,
        ateCarrots
      }
    };
  },

  render: () => <p>
    <span role="img" aria-label="A bunny">🐰</span>
    <span role="img" aria-label="A carrot">🥕</span>
    This is an eating bunny.
  </p>

};

// src/handlers/all.js

// ... previously imported handlers
import AnEatingBunny from './AnEatingBunny';

export default {
  // ... previously exported handlers
  AnEatingBunny,
};

Every time it's given a carrot, it increments the number of ate carrots by 1 (what's actually done by returning a new version of the context, very much like in Redux). What makes it different than any other handler we implemented is that it picks the arrow to follow based upon the context of the model. If the bunny has eaten at least 5 carrots, it follows the ate 5 carrots arrow. However, if the bunny ate less than 5 carrots, it just updates the number of ate carrots. It accomplishes this by following a different arrow called ate a carrot. It is very much like the EnteringTheName node which follows the typed arrow in order to update the context. That's why we need to add this arrow to the graph.

Finally, AFullBunny is happy and allows us to go back to what we were doing.

// src/handlers/AFullBunny.js

import React from 'react';

export default {

  go: () => ({arrow: 'fed the bunny'}),

  render: ({thisModel}) => <div>
    <p>
      <span role="img" aria-label="A full bunny">🐰</span> 
      <span role="img" aria-label="Fireworks">🎆</span>
      The bunny is full. You can go.
    </p>
    <input
      type="button"
      value="Go!"
      onClick={() => thisModel.go()}
      />
  </div>

};

// src/handlers/all.js

// ... previously imported handlers
import AFullBunny from './AFullBunny';

export default {
  // ... previously exported handlers
  AFullBunny,
};

The last screen is called Thanks and it simply says "thank you" and lets us to start the whole process one more time.

// src/handlers/Thanks.js

import React from 'react';

export default {

  repeat: () => ({arrow: 'repeated'}),

  render: ({ctx, thisModel}) => <div>
    <p>Thanks, {ctx.name}!</p>
    <input
      type="button"
      value="One more time!"
      onClick={() => thisModel.repeat()}
      />
  </div>

};

// src/handlers/all.js

// ... previously imported handlers
import Thanks from './Thanks';

export default {
  // ... previously exported handlers
  Thanks,
};

The application is almost ready. The missing functionality is about TheBunny being hungry every time we see it, while the state of CarrotControls should never change without user interaction. It means that if we leave the bunny full and we have a carrot (let's imagine we're carrying it in a bag), then the bunny is hungry when we meet it again but we don't need to look for another carrot because we already have one (the one we found previously). Implementing this feature is actually quite easy and can be done just by editing the graph. First, let's use a special entry point to FeedingTheBunny. We're going to call it feeding. All we need to do is to open the main graph, click the fed the bunny arrow and change its entry point from start to feeding.

Since now, every subgraph of the FeedingTheBunny must have an entry point called feeding. So let's start with TheBunny, which is always hungry when it comes to feeding it.

Open TheBunny
Click NEW ENTRY POINT
Type feeding as its name
Click ADD
Draw an arrow from the newly created feeding entry point to AHungryBunny

In order to make the CarrotControls remember the recently active node, we're going to make use of the special recent node. It symbolizes the node which was active before the graph has been left, or if it has never been active, then it's the node the arrow from the start entry point is pointing at. Long story short - we need to add the feeding entry point and connect it with the special recent node.

And that's pretty much it! The application works as expected and consists of just one IF statement. What's worth noticing, this IF statement is not mandatory. It could be totally removed, what would make the codebase free of any IF statements, if the whole memory of the Rosmaro model was expressed using graph nodes. However, it would lead to a phenomenon called state explosion. This single IF statement turns out to be surprisingly helpful! It's one of the the tools which allow us to mitigate the risk of ending up with an enormous number of nodes and arrows, together with:

composites (orthogonal regions)
subgraphs (state machines in state machines)
context (a piece of data usually in the form of a map structure) Depending on our needs, we can balance the number of nodes and IFs. There may be just one node and many IFs, or many nodes and no IFs at all.

The full source code of the application we've just built is available on GitHub - Rosmaro-React-example-Bunny-App.

Modifications worth trying out

Here are few modifications which I think are worth trying out. It doesn't mean that they represent a better approach. They're simply interesting exercises:

removing all IF statements from method handlers (hint: it will increase the number of graph nodes)
making the typed arrow disappear from the main graph (hint: a new subgraph will be necessary)
adding a back button from Thanks (hint: depending on the destination screen, new nodes may be necessary)

Does it scale?

I often hear, that finite state-machines don't scale. I totally agree on that, when it comes to simple, pure FSM-based solutions. When the graph is the only memory and when every single event needs to be explicitly represented by its own arrow, even trivial tasks may lead to an enormous number of nodes and arrows.

A great example to illustrate this problem is a Hello YourName! application, which has one screen with a text input and a button and another screen to display greetings. Even if we limit the length of the name to 2 characters and allow only two letters: a and b, the graph will still look like this.

This doesn't look good.

However, there's no reason why we need to limit ourselves to just one-level graphs or even graphs at all. Thanks to the fact that Rosmaro is not a pure FSM-based solution, we can use some of the techniques described above to make the graph look exactly how we want it to look. We could even reduce the number of nodes to exactly one by replacing other nodes with IFs. Of course, it wouldn't make to much sense to use Rosmaro if we needed just one node. It simply illustrates the possibility of balancing between nodes and IFs in order to achieve a structure that represents the intended behavior of the application in a clear, documentation-like manner.

Here's the Hello YourName! application modeled using method handlers, context and subgraphs.

It doesn't look so scary, does it?

And when it comes to a bit more complex examples, here's an application with 13 different screens which depend on each other and many paths the user may take.

In the code, there are 3 IF statements. The graph consists of 29 nodes.

The main node opened in the editor looks like this.

Conclusions

To me, visual automata-based programming turned out to be a really great discovery. For a long time, I considered state machines something almost purely theoretical. Or at least not directly applicable to the field I was working on. But then I imagined the code structured like there would be islands of clearly defined behavior. These islands are handlers from Rosmaro. There are also bridges connecting these islands. They are arrows representing events. The current behavior of the system is changed by going from one island to another. It all clicked. Now I can design and implement changes of behavior in an elegant, organized way, where previously I would just scatter IF statements.

I can also see how I benefited from automata-based programming in two different ways. It's not only easier to program by drawing boxes and arrows instead of inspecting boolean flags. It also makes it necessary to discover and name all the important states of the application, what's a great framework for thoughts.

And when it comes to application state, it showed me that there's state management beyond map structures (which are key-value pairs, like method-less JavaScript objects). A new tool appeared in my toolbox. It's the state machine based dispatch mechanism. Instead of just accepting the fact that I have some boolean values to check using IFs, I can consider replacing them with nodes. After playing a bit with this approach, I started noticing the difference between data-related state and behavior-related state. Data-related state is something like information about a user. It may be as simple as name and surname. Most of the time, we don't need to use IFs to deal with state like this. It's simply there. We can display or save it without conditional statements. A set of key-value pairs is a perfect model for state like this. On the other hand, behavior-related state determines how should the application work according to events which occurred in the past. Sometimes key-value pairs topped with a few IFs do the job very well, other times state machines feel a lot more natural and easy to understand.

If you haven't tried yet, I hope you'll give state machines a go. Maybe you'll also find them valuable in your day to day job?

State management beyond the map

Fri, 06 Oct 2017 22:37:20 GMT

There's a way of building web applications where views are declarative. They say what to render and not how exactly should it be done. Data flow is unidirectional, what means it just receives data but never changes it directly. Instead of that, it sends back commands describing what should be done. Then it's rendered again. I used this stack to create a simple ToDo App.

It looks like that.

Here goes the code.

<?php
require_once __DIR__ . "/common.php";
$viewData = [];
if (!isset($_SESSION['todos'])) {
  $_SESSION['todos'] = [];
}
if (isset($_POST['add']) && isset($_POST['newContent'])) {
  $_SESSION['todos'][] = [
    'done' => false,
    'content' => $_POST['newContent']
  ];
}
if (isset($_POST['mark_done'])) {
  foreach (array_keys($_POST['mark_done']) as $id) {
    if (isset($_SESSION['todos'][$id])) {
      $_SESSION['todos'][$id]['done'] = true;
    }
  }
}
$e = 'htmlspecialchars';
$viewData = [
  'todos' => $_SESSION['todos'],
  'newContent' => isset($_POST['newContent']) && !isset($_POST['add'])
    ? $_POST['newContent']
    : ''
];
?>
<form method="POST">
  <ul>
    <?php foreach ($viewData['todos'] as $id => $todo): ?>
      <li>
        <?php if ($todo['done']): ?>
          <s><?= $e($todo['content']) ?></s>
        <?php else: ?>
          <?= $e($todo['content']) ?>
          <input
            type="submit"
            name="mark_done[<?= (int)$id ?>]"
            value="Mark as done"
            />
        <?php endif; ?>
      </li>
    <?php endforeach; ?>
  </ul>
  <input
    type="text"
    name="newContent"
    value="<?= $e($viewData['newContent']) ?>"
    />
  <input type="submit" name="add" value="Add a ToDo" />
  <input type="hidden" name="_csrf" value="<?= $e(csrfToken()) ?>" />
</form>

Yup. It's an old-fashioned, server side PHP script.

Don't get me wrong, I fully admit that many things have changed since then. We’ve got wonderful auto-escaping mechanisms which greatly improved security (JSX was born as one of them). Protection against CSRF attacks has become a common thing (at least in mature back-end frameworks). And we have finally moved a vast part of user interfaces to the front-end (JS is not anymore a tool to embed dancing hamsters on a website). It all provides more beautiful and responsive user interfaces.

But there's something that hasn't changed at all. It's the way how we manage changes of behavior. In the above example there's exactly one set of bahavior. There are always the same controls and they always to the same. The form is always there and it always adds a new ToDo. The list is also visible all the time and it just displays all the ToDos.

But what if there are different screens? What if the user may take different paths? What if the app looks list this?

The state of the art in web interfaces is to save some values within the state and then use conditional statements to pick the appropriate behavior. There may be some boolean values stating that the user has performed some actions, some integers (or enums) representing the current step etc. And then we use if statements (or ternary operators, switch statements or table lookup techniques) to decide what to do. The whole architecture may be summed up as spreading conditional statements over a map (or a session, a database, a dumb object - you name it). We may avoid duplication of if statements, but we can't avoid them completely even if we wanted to.

Once I was asked if I could introduce "few little changes" to an app I was maintaining. When I realised what kind of variables would I need to check and how many complicated conditional statements would be necessary, it terrified me! It seemed barbaric!

What's interesting is that the description of those changes wasn't so tangled. It consisted few scenarios like "if the user does this, then she's finally going to land on this screen" etc. It made me wonder why was it so hard to code it, if it was so easy to talk about. Soon I understood that the high level architecture I had was suitable only for simple screens which never change, but it by no means reflected the domain of the problem.

Actually the "non-technical people", as we like to call them, came to me with a much more suitable and elegant architecture. Even though they didn't use that exact word, what they described was one of the fundamental concepts in computer science - a state machine. It was me who didn't see that and instead tried to utilize maps and if statements. Such a shame!

If I would be about to chose one experience, which made me willing to explore practical application of state machines in web development, it would be this one. Some time after that, I published the first version of Rosmaro. I actually used it to create the second application presented in this post. You can find a detailed description of its architecture in the post describing how state machines come to the rescue of complex forms. Oh, and let me share something with you. It made me really happy when I recently stumbled upon a great talk given by David Khourshid - Infinitely Better UIs with Finite Automata. If you're interested in how state machines may improve the architecture of user interfaces, definitively check it out. I bet you won't regret it!

State machines to the rescue of API mocks

Sat, 23 Sep 2017 22:37:20 GMT

Let me tell you the story of one of the most valuable test suites I have ever written.

I was working on an application communicating with a web API. I did similar things before. I wrote plenty of methods making HTTP calls, processing the output and handling errors. But this was a different story. There wasn’t a single domain. There were few. Moreover, in order to perform one operation, I needed to send many HTTP requests. They were strictly correlated — each request contained some data from the previous response. And did I mention a single business process was distributed among many processes of a task queue? It already seemed hard, but the worst was yet to come. During the development phase I wrote many unit tests. I used the mocking tool provided by the test framework to create test doubles of objects communicating with the external world. I was checking if correct methods were called, what was the result of method calls if the API returned some particular response etc.

I did it. It worked perfectly on my dev machine. Great! But it miserably failed in production. Great… Most of the time the user saw nothing but a message saying that an error occurred while trying to communicate with the external system. How was that possible? I wrote automated tests. I did some manual testing as well. Never saw anything like this.

A quick investigation revealed there was a race condition problem. The API was responding with some IDs. Right after receiving those IDs, I was sending them back in order to ask for more details. It turned out that the production environment was fast enough to get a 404 Not Found response for resources which, according to the API, have just been created. There were also few very similar problems. And just one solution — to repeat the request.

I got concerned. How was I supposed to test this? I already knew it would never occur on my machine. Pretty soon I realised that really good, isolated and automated tests were not my support. They were my only hope. There was simply no other way. I needed to somehow create a test double of the whole, stateful web API!

The HTTP client I was using was a piece of object oriented software. I could easily use the mocking tool to create its test double which would always respond with some particular response to some particular request. But such a simple, stateless behavior was not even close to how the actual service behaved. I seriously needed a test double which would work (and fail) like the real API.

The very first idea I got was to write some imperative code that would mimic the stateful behavior. It didn’t feel correct. If I can make mistakes writing simple imperative code making some calls, how can I know another imperative code responding to these calls is free of bugs? I faced this problem around the time when I got interested in practical application of state machines in web applications (which few years later led to the creation of Rosmaro). I recalled the State design pattern and implemented the interface of the HTTP client around the idea of a graph where every leaf was a response and every arrow was a request. It allowed me to mimic some pretty complex behavior in a way that was easy on the brain and closely reflected how did the API behave in production.

For the purpose of this article, I’d like to focus on a simple yet stateful interaction with a web API. Because we’re talking about web applications, it’s natural to choose a ToDo App as the example. Our task is to add a ToDo and then mark it as done. There are two endpoints: one to add a ToDo and another one to mark a ToDo as done. After adding a ToDo we’re given its ID. We can then use it to mark it as done. I solved the problem I faced by implementing my own mocking tool using the State design pattern. But I wouldn’t do it again. The only reason I did it was because I didn’t know a great tool called WireMock. Let me quote the official documentation to explain what sets it apart from other mocking tools.

WireMock supports state via the notion of scenarios. A scenario is essentially a state machine whose states can be arbitrarily assigned.

It had me at behavior modeled as state machines.

Let’s run it as a standalone process and configure it using a bunch of JSON files in order to mimic the behavior shown in the picture below. This WireMock process will simply behave like an HTTP server. We can then configure our system under the test to send requests to an address like localhost:8888 instead of example.com/api.

Here comes the first arrow connecting the initial node (which is always called Started) with the Added node:

{
  "scenarioName" : "Add and mark as done",
  "requiredScenarioState": "Started",
  "newScenarioState": "Added",
  "request" : {
    "url" : "/todos/add",
    "method" : "POST",
    "bodyPatterns" : [ {
      "equalToJson" : "{ \"todo\": \"make a test double\" }"
    } ]
  },
  "response" : {
    "status" : 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "jsonBody" : {
      "id": 123
    }
  }
}

The request key tells us that we expect it to be a request to add a ToDo. We will then get a response described under the response key. It contains the ID our ToDo was given. Following this arrow will lead us to the Added node. All our mock supports is to mark the added ToDo as done. The arrow between Added and Marked as done is defined in the following way:

{
  "scenarioName" : "Add and mark as done",
  "requiredScenarioState": "Added",
  "newScenarioState": "Marked as done",
  "request" : {
    "url" : "/todos/markDone/123",
    "method" : "POST"
  },
  "response" : {
    "status" : 200
  }
}

The requiredScenarioState key is very important. It states that this is an arrow from the Added node. It means that even if we send a request that matches while the current state is different (let’s say we’ve just Started and we’re in the the Started node), it’s not going to be followed. It forces us to first add a ToDo and only then mark it as done. The ID within the request is also worth noticing. It’s the exact same ID the server responded with when we added a ToDo.

{
  "scenarioName" : "Add and mark as done",
  "requiredScenarioState": "Marked as done",
  "request" : {
    "url" : "/passed",
    "method" : "GET"
  },
  "response" : {
    "status" : 200
  }
}

The last node of this simple graph makes the server respond with the 200 HTTP code only if the ToDo has been successfully added and marked as done. This will allow us to verify if the code worked correctly. Let’s see how does our mock API work.

We’re adding a ToDo and its given an ID.

$ curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"todo": "make a test double"}' \
    http://localhost:8888/todos/add
{"id":123}

Now we can mark it as done.

$ curl -i -X POST http://localhost:8888/todos/markDone/123
HTTP/1.1 200 OK

And finally we’re making sure the ToDo was marked as done.

$ curl -i http://localhost:8888/passed
HTTP/1.1 200 OK

If you are like me and you got worried that it may be tedious work to properly mimic all the real endpoints, let me tell you about another WireMock feature I find amazing. Instead of describing how does the mock behave in the first place, we can order WireMock to record the traffic between our machine and the real API. All we need to do is to fire up the browser and enter http://whereiswiremocklistening/_admin/recorder, enter the address of the real API and press the Record button. Now we can make requests to localhost:8888 like it would be example.com/api. All the requests and responses are going to be saved as JSON files for us.

Of course it’s still the happy path. We could probably test it using the real API, even though it would be slower, less repeatable and dependent on the internet connection. But the real power of mocking APIs lies in the capability of testing how does our code behave in situations which are quite hard or even impossible to reproduce, like getting some specific errors or experiencing long delays. In order to do it, we can simply tweak a bit the graph representing the happy path by putting some 500 Internal Server Errors here and there. That’s exactly what I did to make sure my application was handling situations where the 5th request of out 8 fails three times.

Another thing worth noticing is that having a mock of the API we can test code interacting with endpoints which don’t exist yet. Both the API client and the API server can be developed simultaneously, because the team responsible for the client doesn’t need to wait for the team working on the server to deliver a testing environment. They just need to agree on the API contract, what’s necessary anyways.

WireMock has many other features, like: powerful request matchers, response templates and transformers, custom recording settings etc. This post is by no means an attempt to describe them all. I just wanted to encourage you to apply state machines to HTTP testing, because as you already know, it worked wonders with my test suite. It was literally the only way I found to deliver a working solution in a reasonable amount of time. If you’re willing to learn more about this amazing tool, I recommend the official documentation of WireMock.

Happy testing to all of you!

JavaScript is like a big city

Sat, 29 Jul 2017 14:37:20 GMT

Let’s meet Adam. Adam enjoys hanging out dressed as a cartoon character. In the big city he lives in, he can find all the costumes he likes. Sure, some people don’t understand him. One of them is Brian. These two meet each other quite often waiting for the subway. Brian then looks at Adam and thinks to himself, ‘I bet he wears a big green dog costume only because he hasn’t learn how to wear a suit correctly!’. But he forgets about him as soon as he notices the perfect cufflinks on a store window. They both are able to enjoy their own ways of dressing up in the same way how JavaScript programmers may see lists everywhere (ClojureScript) or add types almost everywhere (TypeScript).

It’s obvious that a city of millions of people cannot be served by one hairdresser. And it’s not only about the number of potential customers. Different people have different needs. Some want to just shorten the hair, while others look for a fancy hairstyle. From time to time Adam has his hair cut. But he doesn’t go to the same place Brian does. In the end it’s all about having your hair cut, but they expect it to be done in very different ways. And it’s totally fine to have different ways of getting your hair done, so is to have few libraries handling HTTP requests.

Sometimes when it’s the lunch time, they see each other again. Brian is waiting for his meal to be served. He’s looking through the window of a fully vegetarian restaurant. Then he spots Adam running to the kebab place located next door. They both are grateful that they can have the exact dish they want. Because big cities are full of life, they attract people of all kinds. Those who love to cook can make their living by running a restaurant. They don’t need to offer food that will be accepted by everyone in the town. They can specialize in some narrow field and they can do it well. It’s not a rare case to see a JavaScript programmer who works mostly on back-end systems. Another JavaScript programmer may focus on rich front-end experience. Somebody else can use JavaScript to develop mobile applications.

After living in that big city for a while, both Adam and Brian know which districts should be avoided. They know the city is not perfect, but they stay there because of all those possibilities they would never have in a small town. They create the city.

JavaScript is very much like a big city. That was one of the reasons why I decided to re-write Rosmaro in JavaScript.

Programming books on Kindle

Wed, 12 Jul 2017 14:37:20 GMT

Recently I stumbled upon a Facebook pool asking whether I read programming books on Kindle. I voted yes. Definitely yes. I felt it didn't express my experience well enough, so I wrote a comment. What you're reading right now is the English version of this comment.

I started reading programming books when I was a student. I was lucky enough that the public library in the city where I used to live offered access to many valuable books on software engineering. Some of the titles include Design Patterns: Elements of Reusable Object-Oriented Software and Extreme Programming Explained: Embrace Change. I also managed to buy books like Thinking in Java and PHP Objects, Patterns and Practice. And it was all paper.

It didn't last long before I read all the paper books I was interested in I could borrow or buy easily. Happily, around that time, I got a job. It made me able to shop for any book I wanted without worrying about running short of pocket money. Well, sort of. Paying tons of money for a book shipped from a different continent didn't seem sane.

I've found a solution! Now I read exclusively on Kindle. When I was a commuter, I used to carry a book with me. Before I got my e-book reader, I read a blog post praising the possibility to read controversial e-books in public. I didn't quite believe in that. Would somebody notice the cover of my book? Soon I figured it out. I remember once when I was reading the previously mentioned Java book, one guy looked at me. "Java..." he said, in a voice full of disgust. I'm pretty sure he was a Modern Language Programmer or one of those macho guys who always consider things like a garbage collector or operating system an unnecessary overhead. If I had my Kindle, I'd avoid all the shame! But who knows, maybe I'd never check out Ruby.

There's another reason why I prefer electronic versions of books over paper when I read in means of public transport. They weight nothing. Compared to huge hardcover books, I can easily hold the reader in one hand. When I don't read, I can put it into the pocket of my jacket. My whole library in my pocket. Isn't this amazing? It doesn't matter if I'm going to a nearby city or different continent. It's always that easy!

By today's standards, e-book readers are not impressive computers. But they're computers, after all! Every time I recall that I read about something in some book, the built-in search function turns out to be a lot more convenient than the index at the end of a book. And did I mention that all the books fit into my pocket?

I don't like messy notes in margins. That's why I hesitate to take them on paper. But with the on-screen keyboard it's a totally different story! They don't make the main text messy. They don't force me to write tiny letters. Great!

Because English is the lingua franca of computing, I prefer to read in English. Unfortunately, it's not my mother tongue. Thus, some words are unknown to me. But it doesn't worry me, as all I need to do is to hold a word on the screen it and its definition pops up! So I not only carry the whole library with me. I carry the English dictionary as well!

But the most important thing is that there are countless books to read. Shopping for books abroad can't be easier! And it takes seconds to deliver a book! If I couldn't buy some of the e-books I read, I'd never read them. It's simply too hard to get some paper books. From time to time we can even get a book for free. For example, O’Reilly Media publishes many e-books for free.

The E-ink screen is one of the biggest advantages of an e-book reader. It's also one of its downsides. The relatively small, gray-scale screen works great most of the time, but sometimes it's just too small and too gray. Recently I read a book describing a lot of color theory. There were big, colorful diagrams. I mean, I think there were. I haven't seen them. To me they were small and gray. Fortunately, it doesn't happen too often. If I'd be consuming more content of this kind, I'd consider trading great battery life and sunlight visibility for great colors and get a tablet.

I'm not a Kindle fanboy. The reason why I got it is that I hoped it would be a simple and problem-free product. I was right. It does everything I expect it to do and I can honestly recommend it. However, I try to avoid shopping exclusively for it. I prefer to buy e-books not only in the .mobi format, but also .pdf and .epub. That way if I decide to change my device, I don't lose the books I paid for.

I believe the things I mentioned sum up my experience with Kindle quite well. If you are considering getting one, please bear in mind that your needs may differ. I want to travel light and read in a foreign language. If you can easily get all the paper books you want and you don't mind carrying them, you may not need an e-book reader. Or maybe you already have one?

How secure are old sessions?

Fri, 02 Jun 2017 22:37:20 GMT

There are plenty of places where people can access the Internet using computers shared among many users: public libraries, schools or Internet cafés.

Different people can get there. Unfortunately, some of them may be malicious. Usually we can expect that the user will have very limited rights and there will be some type of anti-malware software. Sadly, if our app keeps the same session ID after logging the user in, our users are in danger.

The action of this story takes place in a fictional public library.

A malicious person visits the login page, presses F12 to open the developer tools and takes a picture of the session ID with his phone. Then he closes the tab and sits somewhere else, where he enters the session ID stolen from himself. The trap is set.

Somebody takes the seat previously taken by the attacker. The computer is not infected, the connection is encrypted and the victim is totally unaware of the threat. He authenticates.

This is the moment the attacker has been waiting for! Because the app doesn't regenerate the session ID before putting there the data of the authenticated user, now both the victim and the attacker share the same session. The attacker can do everything he could do as he would be sitting in front of the victim's computer.

How can we protect our users against that kind of attacks? We should never put their data into "old" sessions. Before we log the user in, we regenerate the session and get a new ID.

If we write node and the authentication middleware we use doesn't regenerate the session, we can use the express-new-session middleware:

const newSession = require("express-new-session");

//...

app.post("/login", newSession(), tryToLogin, (req, res) => {
  //...
});

If you work with different technologies, the easiest way to figure out whether the system is vulnerable to this type of attacks, is to check whether the session ID changes after an user logs in.

State machines to the rescue of complex forms

Sat, 06 May 2017 22:37:20 GMT

Complex forms may have many names, like wizards or creators, but they are always a challenge to implement and even a greater challenge to modify. A little change in the drawing on the whiteboard may lead to plenty of changes of if statements, session variables and routes.

The hidden machine

Very often during the process of development the whiteboard gets full of drawings representing different looks and behaviors connected with arrows named after some events. It helps us to understand the complex nature of the system we're building by taking away all of those constructions like assignments or conditional statements. Unfortunately the actual code rarely reminds of those drawings, even though they often look exactly like one of the fundamental concepts in computer science - state machines.

Sadly, state machines seem to be an underestimated idea in the world of web applications. Why is that? One of the reasons may be the fact that all the examples we can easily find differ a lot from the reality of back-end programming. A wonderful model of a vending machine or a turnstile may look appealing, but in the end it's nothing we need in our web app. A function that given a string gives another string still isn't a ready to use solution. Of course there are also different reasons, like open questions about storage mechanisms or solving the problem of state explosion.

When nodes and arrows become first-class citizens

In this article we're going to take a look at a wizard implemented around the idea of state machines, where things like methods, variables or conditionals are implementation details.

The goal and the toolchain

The goal of that wizard is to take orders for things to drink. It's implemented in node with express and rosmaro. I'll skip the process of building it, because it's intentionally not the simplest example. I'd like to focus on what does the code look like when things get complicated.

The scary part is the wall of text that could be called "requirements". The wizard visible above is relatively complex, and so is the description. To save you the pain I removed the boring parts and left only what indicates the complexity:

At the beginning [...] then we display a screen [...] it may be skipped [...] consists of few steps [...] First we see [...] If we picked a cold drink [...] Otherwise under the select field [...] if we previously entered the correct promo code [...] From that final screen we go back [...] then before picking the drink [...]

Understanding that endless stream of ifs is very hard.

From the drawing into the code

After reading the whole description (what you luckily don't need to do) it becomes clear that it always begins with a promo code screen and then we enter the path for either a valid or invalid promo code.

So the drawing of the main graph would look like this:

What can be directly reflected in the code:

const main = () => ({
  type: "graph",
  start: "promo_code",
  arrows: {

    promo_code: {
      ok: "ordering_with_promo_code",
      wrong: "ordering_without_promo_code",
      skipped: "ordering_without_promo_code"
    },

    ordering_without_promo_code: {
      go_back: "promo_code"
    }

  },
  nodes: {
    promo_code: promo_code(),
    ordering_with_promo_code: ordering_with_promo_code(),
    ordering_without_promo_code: ordering_without_promo_code()
  }
})

Those factory functions like promocode, _orderingwithpromocode_ and orderingwithoutpromocode_ return other graphs built in the same way.

The screen responsible for picking the drink has a finite number of variants. Great! Here goes the sketch:

And here's the code:

const pick_drink = () => ({
  type: "graph",
  start: "nothing_configured",
  arrows: {

    nothing_configured: {
      picked_hot_drink: "pick_cooler",
      picked_cold_drink: "cold_drink_configured"
    },

    pick_cooler: {
      picked_cooler: "hot_drink_configured",
      picked_cold_drink: "cold_drink_configured"
    },

    hot_drink_configured: {
      picked_hot_drink: "hot_drink_configured",
      picked_cooler: "hot_drink_configured",
      picked_cold_drink: "cold_drink_configured"
    },

    cold_drink_configured: {
      picked_hot_drink: "pick_cooler",
      picked_cold_drink: "cold_drink_configured"
    }

  },
  nodes: {
    nothing_configured: nothing_configured(),
    cold_drink_configured: cold_drink_configured(),
    pick_cooler: pick_cooler(),
    hot_drink_configured: hot_drink_configured()
  }
})

We can clearly see 4 nodes connected with arrows. Let's take a closer look at the factory of the screen called "cold drink configured":

const cold_drink_configured = () => ({
  type: "composite",
  nodes: [
    ["type", change_drink_type()],
    ["sugar", set_sugar()],
    ["nav", pick_cold_button()]
  ]
})

Again, it closely reflects the sketch. It has a separated way to change the drink type, set the sugar and a button that finally picks the configured cold drink.

So far there have been no if statements. Is that approach totally free of them? No, it's not. There are some, just deeper. Let's dig then. That's the code of the changedrinktype factory:

const change_drink_type = view(() => ({

  render() {
    const picked = this.context.drink

    return html`
      <select class="auto-submit" name="${safeHtml`${this.pname('drink')}`}">
        ${["coffee", "tea", "lemonade"].map(drink => safeHtml`
          <option value="${drink}" ${picked == drink ? "selected" : ""}>${drink}</option>
        `)}
      </select>
    `
  },

  handle(params) {
    const picked = params['drink']
    if (picked) {
      const is_hot = ["coffee", "tea"].includes(picked)
      const arrow = is_hot ? "picked_hot_drink" : "picked_cold_drink"
      this.follow(arrow, {...this.context, ...{drink: picked}})
    }
  }

}))

What does this object do? It renders a list of all drinks and selects the currently picked one. It also handles the form data. How does it do it? It has a few if statements! One to check whether a drink is selected, another one to check whether we picked some drink and yet another one to determine whether that drink is hot! But aren't if statements definitely harmful? I don't think so. I'd rather say they are very much like cakes - it's a great thing to have a piece of cake, but eating the whole cake could make us sick. Those little if statements actually turn out to be very helpful, because they save us from facing a problem called state explosion. Imagine how messy would it be if we needed a separate node for each drink just to display the selected one! So instead of sticking to the idea of pure FSM, we add some if statements where it's handy to make the graph more descriptive and less bloated. The important part is that the code is free of if statements that would just introduce some noise.

It's a lot harder to make unwanted elements appear on the screen out of nowhere, because we made a mistake in an if statement, when there's no if statement to decide if they should be visible or hidden. Their placement within the graph tells enough.

No more /step1, /step2a, /step2b, /step2bfinal, /step3...

A pattern that may be often seen is to create a bunch of GET endpoints for every step of the wizard. Unfortunately, things get very complicated when it comes to access control. Let's say the user hasn't entered the valid promo code, but she's trying to open the /order-wizard/ordering-with-promo-code address. We don't want any insecure direct access like that. So we put a bunch of if statements in front of every single view. That's some additional work to do and another opportunity to introduce bugs.

The good thing is that a model with a state machine under the hood, where the current state is not a public and mutable property (like the request path), can completely eliminate this problem. We don't expose all the possible states, just to later limit the access with if statements. Instead of that, we relay on the fact that there's always only one current node and we have one endpoint like /wizard. Here's the whole express-specific code:

app.get('/wizard', async (req, res) => {
  res.send(await render_wizard(wizard))
})

app.post('/wizard', async (req, res) => {
  await wizard.handle(req)
  res.redirect('/')
})

The "go back" button just goes back

A very simple example of node reuasbility is the "go back" button. What does it do? It goes back. But where? The graph will tell us.

That's the code of the button:

const go_back = view(() => ({

  render() {
    return safeHtml`<input
      type="submit"
      name="${this.pname('back')}"
      value="Back">`
  },

  handle(params) {
    if(params['back']) this.follow("go_back")
  }

}))

When clicked, it follows the go_back arrow. That's it. It doesn't tell where exactly does it go. It just express the intention to go back.

Here if we click the "back" button we are redirected to the screen where we can enter the name.

But here clicking the same button will take us to the screen where we can enter the promo code. And there are no ifs for that. The same button may be reused wherever we want. We just connect the arrow to a different node.

We should give state machines a go

It seems that in web development, compared to areas like game development, we don’t utilize the full power of state machines. If you haven’t tried yet, I strongly encourage you to identify state machines hidden in your code. Extracting them into a readable structure often leads to a surprisingly clear, declarative model of our domain.

When to cut carrots in half?

Tue, 21 Feb 2017 22:37:20 GMT

A long time ago I heard a joke that I recalled recently while thinking about programming.

I don't remember it in details, but the overall meaning is preserved. Here it goes:

Two friends were talking about carrots:

- Jim, why do you always cut carrots in half, when you want to boil them?

- That's simple, Tim. I do it because my mom was always doing that.

Tim got a bit confused, so he decided to ask Jim's mom about that:

- Jim always cuts carrots in half. He told me you always do it. Why is that?

- I don't know why does Jim do it, but I was doing it because the pot I had was too small.

When I was doing my very first steps in software development, I didn't have too much experience with different programming languages. The vast majority of my code was written in PHP. I was lucky enough to read books that improved my skills a lot. That great literature on programming was mostly based on Java or similar languages. Some of those fantastic books were released more than 10 years ago.

I find neat solutions valuable, so when I was facing a problem I read about in a book, I was doing my best to apply that clever solution I found in the book. It all looked right and most of the time it was the best thing I could do. However, sometimes that solution was addressing a problem I didn't have. I didn't know about it, because I didn't know any alternative solution.

If I needed to check whether a person meets some requirement, I'd look at something like the following example.

public interface PersonTester {
    public boolean metBy(Person p);
}

public class ThreeLettersName implements PersonTester
{
    @Override
    public boolean metBy(Person p)
    {
        return p.getName().length() == 3;
    }
}

PersonTester requirement = new ThreeLettersName();

Then I'd write something similar in PHP. I would not consider anything like this.

$meetsRequirement = function ($person) { return mb_strlen($person->name) == 3; };

Why? Because I didn't see it in those books written by people a lot smarter than me. Why wasn't it mentioned? Does it mean it's a bad solution? I don't think so. There's an explanation that makes much more sense. Their pots were too small. When those books were written, Java didn't support code like this:

Predicate<Person> requirement = p -> p.getName().length() == 3;

Something like this wouldn't look serious to me.

$person = (Object)[
  'name' => 'Jim',
  'email' => 'jim@domain_of_jim.com',
]

The correct way I knew was something like this.

class Person {
  private String name;
  private String email;

  public Person(String name, String email) {
    this.name = name;
    this.email = email;
  }

  public String getName() {
    return this.name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public String getEmail() {
    return this.email;
  }

  public void setEmail(String email) {
    this.email = email;
  }
}

Using objects as mutable, dumb bags of data, when there are no constructions that act like bags of data provided by the language, is understandable. Sticking to this solution as the only one available in PHP, which has array literals and magic methods, is sometimes harder to justify.

Avoiding heavy builds every time we change a configuration detail and letting applications written in different languages read from the same config file is a great thing. Fortunately there's no such thing as heavy builds in the PHP world. It's quite uncommon to share all the config files with a totally different application neither. That's why associative arrays often turn out to be a faster and better solution.

I'm aware of the fact that some of the alternative solutions I presented here mean degradation of PHP tooling support (like autocomplete functions of IDEs). However, the "static vs. dynamic" conflict is a topic for another entry.

Long story short - the most important lesson I learned from working with different technologies is to always check what's the problem some solution solves before applying it.

Singletons are often misused but easy to test

Sun, 13 Nov 2016 22:37:20 GMT

A discussion on singletons:

Why are singletons so nice?

Because they are easy to use.

Why are they easy to use?

Because they provide us a way of getting an object we need.

Why are singletons bad?

Because they make testing hard.

Why do they make testing hard?

Because it's impossible to use their test doubles while testing code which depends on them.

Judging from my experience, none of those answers is correct.

Let's start from testing.

public class FloristShop {
  public void placeOrder() {
    //...
    DeliveryGuy.getInstance().deliver(flowers, address);
  }
}

It's not so rare to hear that now every time the test suite runs, some poor guy delivers some flowers... somewhere. It happens in real life, because it's a real delivery service and not a test double, thus we're charged for that! Sounds awful! Fortunately that's not true. We don't even need a special mocking framework in order to use a test double of the DeliveryGuy. If our singleton has the following method:

public IDeliveryGuy getInstance()

there may be one like this as well:

public void setInstance(IDeliveryGuy instance)

so in the setup method of the test class we can simply write:

DeliveryGuy.setInstance(new DeliveryGuyTestDouble());

In the same way the main method of our application could set the real delivery service instance, so running the test suite without passing a fake IDeliveryGuy implementation to the setInstance method will cause an exception and won't accidentally send the real delivery guy to the address used in the test suite.

But what about the ease of use? Don't singletons make it easier to write the code? Sometimes they do, but only in languages without global variables, as they are nothing but global variables. Otherwise a global variable can be used, what's even easier. The main source of problems with singletons I've seen is using them for a totally different purpose than they are created for. Their main job isn't to address the question "How do I get this object?" but to limit the number of instances of some class to exactly one. In other words, making writing any code easier isn't what are they created for. It's making writing some code impossible. And they do it well. Unconsciously putting this restriction on our code often leads to a situation when we would like to use composition, but we can't. Take a look the following example which doesn't use the Singleton design pattern:

FloristShop mainShop = new FloristShop(new RegularDeliveryGuy());

Let's imagine we want to add support of a premium florist shop, which delivers orders faster. We can easily avoid duplication and changes of the already existing code by constructing the premium shop this way:

FloristShop mainShop = new FloristShop(
    new RegularDeliveryGuy()
);
FloristShop premiumShop = new FloristShop(
    new MotorDrivingDeliveryGuy()
);

As we can see, it would be impossible with singletons, because there could be just one delivery guy.

Multiple dispatch in Java

Sun, 25 Sep 2016 22:37:20 GMT

In this article I'd like to show few examples of code beyond the world of single dispatch. I'll show why method overloading isn't enough, how things may be done in Clojure and that it's quite easy to write a similar code in Java. I hope you'll find this valuable.

Animal sounds

Let's tart with an interface of Animals:

public interface Animal
{
    public String doSound();
}

Just by looking at it we know that every single Animal is able to do a sound.

There are two classes of Animals: Cats and Cows respectively:

public class Cat implements Animal
{
    public String doSound()
    {
        return "Meow";
    }
}

public class Cow implements Animal
{
    public String doSound()
    {
        return "Mooo";
    }
}

Thanks to polymorphism we can take any Animal and make it do a sound:

Animal meower = new Cat("Mr. Meower", 7);
Animal mooer = new Cow("Lady Mooer", 500);

System.out.println(meower.doSound()); // "Meow"
System.out.println(mooer.doSound()); // "Mooo"

It doesn't matter if it's a Cow or a Cat, as the way of asking it to do a sound is the same. Please notice that in this example the compile time type of both the meower and the mooer is an Animal and not a Cat and a Cow. It works as expected only because the actual method that's being called is selected upon the runtime type of the Animal we call the method on.

Cats differ from cows

Let's admit that cats slightly differ from cows:

public class Cat implements Animal
{
    public final String name;
    public final int remainingLifes;

    public Cat(String name, int remainingLifes)
    {
        this.name = name;
        this.remainingLifes = remainingLifes;
    }

    public String doSound()
    {
        return "Meow";
    }
}

public class Cow implements Animal
{
    public final String name;
    public final int weight;

    public Cow(String name, int weight)
    {
        this.name = name;
        this.weight = weight;
    }

    public String doSound()
    {
        return "Mooo";
    }
}

Mr. Presenter who introduces animals

What if we would like to introduce Animals to the audience, but we don't want to make them responsible for that? Then we would need a presenter we could ask for introducing them.

Method overloading

The simplest, but not always working solution, could be method overloading.

class Presenter
{
    public String introduce(Cat c)
    {
        return "A kitty called " + c.name + " with " + c.remainingLifes + " lifes.";
    }

    public String introduce(Cow c)
    {
        return "A " + c.weight + " kg milk producer named " + c.name + ".";
    }
}

Unfortunately method overloading isn't based on runtime types, but on compile time types. It means that even though this works as expected:

Presenter presenter = new Presenter();

Cat meower = new Cat("Mr. Meower", 7);
Cow mooer = new Cow("Lady Mooer", 500);

System.out.println(presenter.introduce(meower));
System.out.println(presenter.introduce(mooer));

This doesn't even compile:

Presenter presenter = new Presenter();

Animal meower = new Cat("Mr. Meower", 7);
Animal mooer = new Cow("Lady Mooer", 500);

System.out.println(presenter.introduce(meower));
System.out.println(presenter.introduce(mooer));

It happens because Java supports only single dispatch. The method that's actually called is selected upon the runtime type of just one variable - the object it is called on. Runtime types of other arguments aren't taken into account.

The visitor pattern

One of the possible solutions is the visitor pattern. We define its interface:

public interface AnimalVisitor<T>
{
    public T visit(Cow c);
    public T visit(Cat c);
}

And we let it visit animals by modifying the Animal interface to accept a visitor:

public interface Animal
{
    public String doSound();
    public <T> T accept(AnimalVisitor<T> visitor);
}

Now we need to add the following method to both the Cat and Cow classes:

public <T> T accept(AnimalVisitor<T> visitor)
{
    return visitor.visit(this);
}

We're ready to write a presenting visitor:

public class PresentingVisitor implements AnimalVisitor<String>
{
    public String visit(Cow c)
    {
        return "A " + c.weight + " kg milk producer named " + c.name + ".";
    }

    public String visit(Cat c)
    {
        return "A kitty called " + c.name + " with " + c.remainingLifes + " lifes.";
    }
}

This allows us to forget about differences between cats and cows when we just want to ask a presenter to introduce some animals:

AnimalVisitor<String> presenter = new PresentingVisitor();

Animal meower = new Cat("Mr. Meower", 7);
Animal mooer = new Cow("Lady Mooer", 500);

System.out.println(meower.accept(presenter));
System.out.println(mooer.accept(presenter));

Thanks to applying the visitor pattern, it works as expected. Both Mr. Meower and Lady Mooer are considered simply Animals, not a Cat and a Cow. Because the visit method is actually called by both the Cat and the Cow, the compiler knows which of the AnimalVisitor's methods should be called - the one accepting a Cat and the one accepting a Cow, respectively. We can now write code that is far more generic, for example we can iterate over a collection of Animals and introduce each of them in appropriate way:

AnimalVisitor<String> presenter = new PresentingVisitor();

Animal[] animals = new Animal[]{
    new Cat("Mr. Meower", 7),
    new Cow("Lady Mooer", 500),
};

for(Animal oneAnimal: animals) {
    System.out.println(oneAnimal.accept(presenter));
}

The fact that now every animal must know how to accept a visitor isn't nice, because we need the visitor interface and its support since the very beginning (the first animal implementation). But it's not a high price for that flexibility, as it's always just one method regardless the number of implementations of the visitor interface. However, there's a more serious problem we face when we add or remove Animals.

The visitor pattern is meant to make it easy to add new functions to existing types, but not to add new types. It means that when it comes to adding new types, it doesn't allow us to follow the Open/Closed principle, because we're eventually forced to modify the code of already existing visitors as we keep adding new types.

Try Clojure

Let's try to do something similar in the Clojure programming language. First we define our animals:

(defrecord Cow [name weight])
(defrecord Cat [name remaining-lifes])

(def animals [
  (Cow. "Lady Mooer" 500)
  (Cat. "Mr. Meower" 7)
])

Now we add a multimethod based on the class of the given object:

(defmulti introduce class)

That allows us to add independent functions that introduce different animals. We can start with cats. It means nothing but adding a method that's called when a Cat is given:

(defmethod introduce Cat [c]
  (str "A kitty called " (:name c) " with " (:remaining-lifes c) " lifes.")
)

And then we add support of Cows. There's no need of modifying the code responsible for introducing Cats or Cows themselves:

(defmethod introduce Cow [c]
  (str "A " (:weight c) " kg milk producer named " (:name c) ".")
)

Now even if we want to introduce two different animals, we can use the same function. Thanks to polymorphism, the introduce function is able to introduce both types of animals and doesn't require us to think which exact function to pick:

(println (map introduce animals))

Modularity - that's why it's so awesome

But why is it nicer than the visitor pattern? The answer is very simple - modularity!

Adding new types doesn't force us to add new functions

When we add a new type of animal, let's say a Bird, we're not forced to immediately add support of introducing it. Maybe we won't need it at all in our app? Maybe a bird will just be fed, but never introduced? It doesn't matter if the Bird is the first of added animals, or there are already 10 more, if we want to add it's type we can simply write:

(defrecord Bird [name can-fly])

That's all! We've just added a new type without modifying anything and without a need of thinking about already existing types. We can now use Birds. Let's say we want to introduce them. The great thing is there's no need of changing the code that already exists to introduce other animals like Cows, Cats or some other types added in the meantime. We simply add:

(defmethod introduce Bird [b]
  (str "A bird named " (:name b) " that " (if (:can-fly b) "can" "can't") " fly.")
)

Perfect! After the need of introducing Birds appeared, not before, we added an independent new function that introduces them. A Bird may be now added to the list of animals to introduce:

(def animals [
  (Cow. "Lady Mooer" 500)
  (Cat. "Mr. Meower" 7)
  (Bird. "Sparrow" true)
])

The final code

(defrecord Cow [name weight])
(defrecord Cat [name remaining-lifes])
(defrecord Bird [name can-fly])

(defmulti introduce class)
(defmethod introduce Cat [c]
  (str "A kitty called " (:name c) " with " (:remaining-lifes c) " lifes.")
)
(defmethod introduce Cow [c]
  (str "A " (:weight c) " kg milk producer named " (:name c) ".")
)
(defmethod introduce Bird [b]
  (str "A bird named " (:name b) " that " (if (:can-fly b) "can" "can't") " fly.")
)

(def animals [
  (Cow. "Lady Mooer" 500)
  (Cat. "Mr. Meower" 7)
  (Bird. "Sparrow" true)
])

(println (map introduce animals))

It all looks great, doesn't it? I've decided to show a Clojure example, because it's really clean in that language. Does it mean that in languages that support only single dispatch, like Java, it cannot be achieved? Of course it can!

One more attempt in Java

Once again - what's our goal?

Just to sum it up - our goal is to have a presenter capable of introducing animals. We don't expect animals themselves to do that job well.

No need of visitors

If there will be a fully separated presenter, we don't need Animals to accept any visitors. We can go back to a very simple Animal interface:

public interface Animal
{
    public String doSound();
}

Cats may be now implemented without thinking about any visitors. No need of the accept method.

How to talk to a presenter?

Let's write its interface this way:

public interface Presenter
{
    public String introduce(Animal a) throws UnableToIntroduce;
}

An important detail is the fact that it may throw a checked exception, when for some reason it's unable to introduce the given animal. To give you an example from the real world, let's imagine you're asking somebody the way. What if that person is not able to answer? Does the world end? Hopefully not! Can you make it on time? Maybe, maybe not. In the end it depends on you, not only on one person you asked.

So because of this interface, we must be prepared for a situation when Mr. Presenter isn't able to introduce some animal. This exception may be then handled gracefully or cause an application crash. It's the client responsibility to make this decision.

An alternative solution could be to return some default value in case of failure, but from my experience I can tell you that it's easier to add it later than to add proper exception handling if there has been a default value since the very beginning. For example, if there's a suitable default value, we can write a decorator that catches some specified exceptions and returns that value.

Let's write the first presenter - the one that introduces cats:

public class CatPresenter implements Presenter
{
    public String introduce(Animal a) throws UnableToIntroduce
    {
        if (!(a instanceof Cat)) {
            throw new UnableToIntroduce();
        }

        Cat c = (Cat)a;
        return "A kitty called " + c.name + " with " + c.remainingLifes + " lifes.";
    }
}

Why do we have type checking and casting here? Because even though the interface lets us to introduce any Animal, it also provides us a way of saying "Sorry, I don't know how to do it!". That's why this particular implementation may support only Cats. The interface forces its clients to support both cases - when a presenter is able to introduce an animal and when it's not able to do it. This way we don't break any code that uses the presenter when we change it's implementation, because it's prepared for the fact that sometimes an animal may not be introduced.

Needs from the future don't influence the code now

Even if we know that in the future there will be Cows, we may not need them now. We can already test and deliver part of the functionality, which is full support of Cats or anything that uses Animals and Presenters. Let's use the first presenter.

Presenter presenter = new CatPresenter();

//--------------------

Animal[] animals = new Animal[]{ new Cat("Mr. Meower", 7) };

for(Animal oneAnimal: animals) {
    try {
        System.out.println(presenter.introduce(oneAnimal));
    } catch (UnableToIntroduce e) {
        //failure handling code goes here
    }
}

The line I drew in the comment represents a very important concept - separation of the code that creates the presenter from the code that uses it. For the sake of simplicity, I'm not showing here a separated object that uses a presenter passed to it as a constructor parameter (or in some special cases, using a setter). However, if we want to achieve modularity, the user of a service cannot be its creator in the same time.

With Cows (sometimes) comes their presenter

We knew this day would come. There are Cows. Moreover, we want to introduce them! So we need a Cow presenter. In order to get more verbose exception messages from the presenter and keep the code simple, we can move the common part into a template method like this:

public abstract class ClassSupportingPresenter implements Presenter
{
    public String introduce(Animal a) throws UnableToIntroduce
    {
        throwExceptionIfUnsupported(a);
        return actuallyIntroduce(a);
    }

    protected void throwExceptionIfUnsupported(Animal a) throws UnableToIntroduce
    {
        if (!getClassOfSupportedAnimals().isInstance(a)) {
            throw new UnableToIntroduce(String.format(
                "%s supports only %s, but %s was given",
                this.getClass().getCanonicalName(),
                getClassOfSupportedAnimals().getCanonicalName(),
                a.getClass().getCanonicalName()
            ));
        }
    }

    protected abstract Class getClassOfSupportedAnimals();
    protected abstract String actuallyIntroduce(Animal raw) throws UnableToIntroduce;
}

Extending this abstract class, the CowPresenter looks like this:

public class CowPresenter extends ClassSupportingPresenter
{
    @Override
    protected Class getClassOfSupportedAnimals()
    {
        return Cow.class;
    }

    @Override
    protected String actuallyIntroduce(Animal raw) throws UnableToIntroduce
    {
        Cow c = (Cow)raw;
        return "A " + c.weight + " kg milk producer named " + c.name + ".";
    }
}

An instance of this class may be used to introduce Cows and only Cows. The problem of having one polymorphic method introduce capable of introducing Animals of any kind hasn't been solved yet.

Dispatcher

We need a construction similar to the previously mentioned Clojure introduce multimethod, that is a connection between a class of Animals and its Presenter.

The Container library

In this example I'm going to use a simple map between classes and objects from the Container library. I do it to avoid writing the same container logic over and over again, what allows to keep the domain specific code simpler. The ObjectToObjectMap fits our needs perfectly:

public interface ObjectToObjectMap<K, V>
{
    public V getValueBy(K keyObject) throws UnableToGetValue;
}

Given an object, gives another based on some logic. If nothing is found, a checked exception is thrown.

Presenter composed of many presenters

The complete implementation of the class we need in order to be able to use the CatPresenter, the CowPresenter and any other Presenter in the future is:

public class ComposedPresenter implements Presenter
{
    ObjectToObjectMap<Animal, Presenter> actualPresenters;

    public ComposedPresenter(ObjectToObjectMap<Animal, Presenter> actualPresenters)
    {
        this.actualPresenters = actualPresenters;
    }

    public String introduce(Animal a) throws UnableToIntroduce
    {
        try {
            return this.actualPresenters.getValueBy(a).introduce(a);
        } catch (UnableToGetValue e) {
            throw new UnableToIntroduce(String.format(
                "%s doesn't contain any presenter for %s",
                getClass().getCanonicalName(),
                a.getClass().getCanonicalName()
            ));
        }
    }
}

Let me explain what's going on here. First of all, while building the ComposedPresenter, we provide an ObjectToObjectMap which given an Animal gives a Presenter supposed to introduce it.

Then, when the introduce method is called, we try to call it on the actual presenter fetched from the actualPresenters map. If nothing is found, a suitable exception matching the Presenter interface is thrown.

Now instead of limiting ourselves to just this:

Presenter presenter = new CatPresenter();

Or this:

Presenter presenter = new CowPresenter();

We can get both:

Presenter presenter = new ComposedPresenter(new ExactClassBasedMap<Animal, Presenter>()
    .associate(Cat.class, new CatPresenter())
    .associate(Cow.class, new CowPresenter())
);

Now the code that uses the Presenter may pass a different Animal to it without using a separated method like introduceCow.

The final code

Presenter presenter = new ComposedPresenter(new ExactClassBasedMap<Animal, Presenter>()
    .associate(Cat.class, new CatPresenter())
    .associate(Cow.class, new CowPresenter())
);

Animal[] animals = new Animal[]{
    new Cat("Mr. Meower", 7),
    new Cow("Lady Mooer", 500),
};

for(Animal oneAnimal: animals) {
    try {
        System.out.println(presenter.introduce(oneAnimal));
    } catch (UnableToIntroduce e) {
        //failure handling code goes here
    }
}

Getting closer to the deadly diamond of death

We've connected the CatPresenter with objects of the Cat class. If there were DomesticCats, they wouldn't be introduced, because the ObjectToObjectMap implementation used in this example - ExactClassBasedMap - doesn't support inheritance. When picking some that does, we need to answer a very important question - which Presenter should be used, if there are few matching the given Animal? The recently associated one? Or maybe the one somehow considered the closest one in the inheritance hierarchy? What if the introduce method looked like this:

public String introduce(
    Animal newAnimal,
    Animal toAnimal
) throws UnableToIntroduce;

And we had two dispatchers: one for introducing a Cat to a DomesticCat and another for introducing a DomesticCat to a Cat? If we pass two DomesticCats to it, two Presenters match. There's no one correct answer to this question. How do we solve this problem depends on the logic of our application. For example, in Clojure we could use the prefer-method function to tell that the function introducing Cats to DomesticCats is preferred over the one introducing DomesticCats to Cats.

It's not a free lunch

Introducing additional dispatch logic, often based on many parameters, comes with a price in performance. Depending on the exact implementation of the dispatching function, the performance may vary, but it will always be a little bit slower. However, before avoiding this approach in the name of performance, a measurement should be done. Maybe greater modularity and simpler code are worth it?

Unnecessary IF statements

Sat, 17 Sep 2016 22:37:20 GMT

Making decisions is important. We cannot run from them. What we can is to don't make decisions that have already been made by us or others.

In this very short article I'd like to share with you three ways, how can we avoid writing unnecessary IF statements. Those hints are so simple that it's even hard to believe how helpful they may be.

But why actually is it a good idea to avoid IF statements? Like many other things, they introduce some complexity and increase the risk of making a mistake. Even though it's very easy to write and understand them, when done hundreds of times, may be done incorrectly. Believe me or not, I've seen a security issue caused by an unnecessary IF statement that could be totally removed without any further changes in the code!

(boolean? true : false) == boolean

Let's assume we need a method that tells us whether something weights more than the given value. The craziest example I can think of looks like that:

public boolean isHeavierThan(int kilos)
{
    boolean result = false;
    if (weightInKilos > kilos) {
        result = true;
    }

    if (weightInKilos <= kilos) {
        result = false;
    }

    return result;
}

Of course most of the time in a real code it doesn't look that bad. What may be seen definitely more often is:

public boolean isHeavierThan(int kilos)
{
    if (weightInKilos > kilos) {
        return true;
    } else {
        return false;
    }
}

or it's shorter version:

public boolean isHeavierThan(int kilos)
{
    return (weightInKilos > kilos) ? true : false;
}

Now this IF is much shorter, but still present. It means that it may still be written incorrectly, like that:

public boolean isHeavierThan(int kilos)
{
    return (weightInKilos > kilos) ? false : false;
}

Fortunately the way to get rid of it completely is dead simple, as all what we do here is returning the exact result of a comparison:

public boolean isHeavierThan(int kilos)
{
    return weightInKilos > kilos;
}

It still does exactly what the first version does, but without a variable with 3 assignments and 2 conditional statements.

Null is not an empty collection

A name displaying screen sounds like a great thing!

Collection<String> names = new ArrayList<>();
names.add("Katie");
names.add("John");

screen.display(names);

Perfect! We've just displayed two names. But how do we tell the screen that we don't want to display anything without modifying the code that actually makes the call to the "display" method? Can it be a null value?

Collection<String> names = null;

screen.display(names);

It may work, but what's the cost? Now in the "display" method, right before actually printing our names, we must check if the given parameter is not a null value.

public void display(Collection<String> names)
{
    if (null != names) {
        for (String singleName: names) {
            System.out.println(singleName);
        }
    }
}

If we try to remove this null checking...

public void display(Collection<String> names)
{
    for (String singleName: names) {
        System.out.println(singleName);
    }
}

... it looks much nicer, but then: NullPointerException! Isn't there a way to escape that hell? Of course there is and it's actually quite simple. Before we write the final solution, let's think about something. If we want to display 3 names, we pass a collection of 3 names as the parameter. If we want to display 2 names, we pass a collection of 2 names. How does that differ, then, from displaying 1 or 0 names? Well, it doesn't.

Collection<String> names = Collections.emptyList();

screen.display(names);

Passing an empty list when we expect no names to be printed saves the screen from checking if the given collection is actually a collection and not a null.

Unfortunately Java doesn't stop us from passing there a null, but the good thing is that there're great tools like the Checker Framework which are extremely helpful in eliminating null pointers, as they make them appear during the compile time.

Let's meet Mr. Unknown - Null Object

In this example we're going to ask people their name. Our model of a person is very simple:

public interface Person
{
    public String getName();
}

We can also look for somebody using the repository of people:

public interface PersonRepository
{
    public Person getBy(int id);
}

For presentation purposes, the fake repository may be written this way:

public class FakePersonRepo implements PersonRepository
{
    private Map<Integer, Person> people = new HashMap<>();

    public FakePersonRepo()
    {
        people.put(2, new PersonImpl("Katie"));
        people.put(7, new PersonImpl("John"));
    }

    @Override
    public Person getBy(int id)
    {
        return people.containsKey(id)
            ? people.get(id)
            : null;
    }
}

It holds two people with id 2 and 7 and returns a null value if nobody is found. Now if we want to use this repository to display somebody's name or some default text in case a person like that doesn't exist, we can write it this way:

Person foundPerson = people.getBy(3);
String foundPersonName = (null != foundPerson)
    ? foundPerson.getName()
    : "Mr. Unknown";

Depending on our application, it may soon turn out that this fragment of code is repeated over and over again. It's a good moment to consider introducing the Special Case/Null Object design pattern. One thing we cannot forget about is that the previous two examples were about removing IF statements that were unnecessary at all, while this one is about moving it to a different place and avoiding repetition.

If every single time, when nobody is found, "Mr. Unknown" becomes the name that is actually used later in our app, it looks like there's a hidden object representing nobody.

public class NullPerson implements Person
{
    @Override
    public String getName()
    {
        return "Mr. Unknown";
    }
}

What in the case of our very simple model doesn't even need to be a separated class, as we can use an instance built this way:

new PersonImpl("Mr. Unknown");

Then our repository, when nobody is found, returns this special object instead of a null value.

@Override
public Person getBy(int id)
{
    return people.containsKey(id)
        ? people.get(id)
        : new PersonImpl("Mr. Unknown");
}

Now when writing some code that uses the repository of people we can write the following fragment and be sure that it's going to work regardless somebody is actually found:

String foundPersonName = people.getBy(3).getName();

By doing that, we moved some logic from the client code into the repository and made the client code unaware of somebody's presence. Sometimes it may be a great idea, but it's definitely nothing that may be applied everywhere without considering pros and cons of using it in some particular application. If there are 20 places in the code where a person is read from the repository and then the same action is performed if nobody is found, it's a job for the Special Case pattern. On the other hand, if sometimes "Mr. Unknown" is displayed, sometimes no table row is rendered and sometimes an error message pops up, this pattern is useless, because the client code needs to know whether somebody is found. However, if there are tens of cases it matches and just one when we really need to know whether somebody is found, an interesting solution is to make the special case object a Singleton and then check if the returned person is exactly that instance. Even though it's probably the only use case of the Singleton pattern that doesn't seem to be a terrible crime, I suggest being very careful with that, especially if the special case object is not very simple or if there's a chance we will need more than one null object.

I hope you liked this article. It makes me very happy if you find some of those hints useful! It's almost a direct transcription of my youtube video "One less IF" so if you're interested in a video version, feel free to check it out!

Łukasz Makuch

What are portals in frameworks like React and Vue?

What are some differences between various portal implementations?

The 14 reasons why engineers write automated tests

The 14 reasons to automate tests

1. Spotting regression as soon as possible

2. Verifying properties, broadly speaking, not just some cases

3. Testing what's hard to test manually

4. Testing what nobody wants to test manually

5. Meeting contractual obligations

6. Social pressure

7. Learning how to automate tests

8. Spotting security vulnerabilities before the bad actors do

9. Measuring performance

10. Seeing how different variants perform

11. Making use of the byproducts of design to speed up the development process

12. Recreating scenarios

13. Fostering communication

14. Supporting individuals with disabilities

Summary

How to mock POST requests using Nock in JavaScript

Scoped styles don't get applied to functional components in Vue 2

Why don't scoped styles apply to a functional child component?

How to style functional child components the same way stateful child components are styled?

But is it a good scoped styles apply to child components?

What are some alternative ways to style children components?

Portals in Vue 2 don't work with Slot Props from Scoped Slots

✅ How to make sure the teleported content reacts to changes?

❌ What won't work?

But why do slot props break portals in Vue 2 in the first place?

How does writing the render function ourselves fix the problem?

How to write render functions and not go crazy?

Why don't workarounds like v-if="true", key, and slot-scope work?

Summary

(React) Old state when the user navigates back

Sure, I can start working on it right now! But is it a wise thing to do?

Your XML security library is sabotaging your work. Here's what you can do about it.

Are XML Signatures secure?

What are digital signatures, again?

What makes signing XML tricky?

How to make XML signatures more secure?

Should you rely on XML signatures?

How to merge the composer.lock file?

React hooks... Oops! Part 4 - API responses get out of sync with the state

It's 2020. Why is testing front-end applications so hard?

What does the font-weight property tell us about automated testing in the front-end world?

The new CSS Grid will change the way you think about layouts. Here's why.

How to prevent intermittent test failures

React hooks... Oops! Part 3 - an effect doesn't run again when its dependencies change

React hooks... Oops! Part 2 - why does my effect run multiple times with the same dependencies?

React hooks... Oops! Part 1 - Introduction

What a decent API mocking tool looks like to me

What do they mean by memoized callbacks and what does useCallback actually do?

The common language used by business people, designers, writers, and developers

Dynamic orthogonal regions in state machines

What did we lose when we moved to Redux?

Consuming and updating the state object with Ramda lenses

Testing the TodoMVC app

An overview of the Rosmaro-TodoMVC app codebase

Directory structure

Simple handlers

Coding similar behaviors

Working with a big context object

List filtering

List events

Routing

Coming soon

Decomposing the TodoMVC app with state diagrams

A comparison of dispatch management solutions: if, switch, object, automaton, multimethod

IF

Switch

Object-oriented dispatch

Automata-based dispatch

Multiple dispatch

Summary

A JavaScript framework for functions of state and action

FB versus RSS

Are injection attacks still a problem in JavaScript?

If vs. Switch

How exceptions broke my middleware

Why don't workarounds like `v-if="true"`, `key`, and `slot-scope` work?