DEV Community: Kyrylo Yakymenko

When TypeScript lies... and how to make it honest

Kyrylo Yakymenko — Tue, 30 Jul 2019 17:06:39 +0000

A switch from plain JavaScript to TypeScript at our department about a year ago proved to be one of the most successful technical decisions we've made in a while. Surprisingly, the productivity boost when working with our frontend code exceeded any expectations. In this article, however, I am going to focus on some of the problems that TypeScript does not solve (even though one might think it would), and what we are doing in order to try to mitigate those problems.

When TypeScript lies — API responses

The most obvious challenge when relying on a type system, is to make sure that the guarantees it provides do not break whenever some piece of data comes from an external source, such as a remote server via an API call.

const getUsers = (): Promise<User[]> => {
  const result = axios.get<UserApiResponse>("http://server_url/users");
  return result.data.users;
};

We are happy to "strongly type" both the getUsers function, as well as axios.get via a generic type parameter, but what happens if whatever comes back from the server does not have a field called users? Our IDE will tell us that accessing users is safe, and it will readily help us with intellisense:

The compiler and typechecker will be even more happy to confirm that the types are correct, and it is safe to use the returned Promise wherever the function is called. Moreover, a whole chain of function calls that depends on the initial typing is going to look good all the way down to the UI, where we enthusiastically map over the users array (*cough* undefined *cough*) and get a runtime crash — just like we would with good old JavaScript.

What's even more disturbing is that depending on the journey of the users through the codebase, it might (or might not) be rather tricky to trace the origin of the error once we encounter the runtime crash. For example, in case of an array, the variable can be passed around freely from function call to function call — not just ignoring, but essentially hiding the problem with the incorrect type, until at some point we finally decide to map over it. While this is (*totally*...?) normal for JavaScript, where we're used to this kind of stuff and just patiently wait for it to crash in runtime, with TypeScript it's even more annoying, because of the expectations that the type system is supposed to help deal with exactly such kind of problems.

When TypeScript lies — JSON.parse()

At first glance, since we have full control over what we JSON.stringify and later JSON.parse of the frontend, this shouldn't be as much of a problem as when receiving data from external sources. However, there are certain unpleasant gotchas, one might be unlucky to run into — such as in the example below. Let's say we have a type with a Date field:

type SomeEvent = {
  description: string;
  date: Date;
};

And we want to stringify and later parse the result into another object of type SomeEvent:

const someEvent: SomeEvent = {
  description: "Birthday",
  date: new Date()
};

const serializedEvent: string = JSON.stringify(someEvent);

const deserializedEvent: SomeEvent = JSON.parse(serializedEvent);

This seems like a reasonable operation, and TypeScript will not fight us along the way. However, because the date is stringified into... well... a string, the parsed type is in fact { description: string; date: string; }. Moreover, this would painfully crash at runtime if we try to call e.g. getDate() on this "date": Uncaught TypeError: deserializedEvent.date.getDate is not a function.

This is not really a problem with TypeScript itself, or JavaScript for that matter, rather a consequence of how dates are represented in JSON. This is, however, an example of a situation when TypeScript gives us false confidence in what we can and cannot do at a certain place in the code.

How to make it honest

There are a few ways to mitigate those problems — some requiring more magic, others — more code.

The less magical approach

The most straightforward approach would be to write code that validates the API responses before returning them from the API-calling functions. Validating everything by hand is rather tedious, but there are a few JSON-decoding libraries for TypeScript, such as json-type-validation and io-ts. Those were in turn inspired by JSON Decoders in Elm and bs-json for ReasonML.

This does require writing decoders for all types that mirror API-responses in the application and adds quite a bit of extra code:

type User = {
  id: number;
  name: string;
};

const userDecoder = object({
  id: number(),
  name: string()
});

Existing decoders can be composed together in order to decode composite objects:

type UsersApiResponse = {
  users: Array<User>;
};

const userApiResponseDecoder = object({
  users: array(userDecoder)
});

When getting data from the API we can keep ourselves in check by being extra honest and marking the return type from axios responses as unknown. After all, we don't really know at "compile time" what the server is going to return, do we? 😄

Now TypeScript will not even allow us to freely pass around apiResponse.users and pretend like we are sure it's an array of users. We would have to decode the apiResponse first:

const getUsers = (apiBaseUrl: string) => {
  const apiResponse = axios.get<unknown>(apiBaseUrl);

  return apiResponse.data.users; // Error: Object is of type 'unknown'
};

const getUsers = (apiBaseUrl: string) => {
  const apiResponse = axios.getUsers<unknown>(apiBaseUrl);
  const decodedResponse = usersApiResponseDecoder.runWithException(
    apiResponse.data
  );

  return decodedResponse.users; // Now we can safely access the user array
};

In this case we are still going to crash at runtime, but we're going to fail early and fail with a clear error message: DecoderError: the key 'users' is required but was not present, which means that not only do we get palpable clues as to how to fix the error, but also that TypeScript is not lying any more at any point in the codebase! 😄

The "magical" approach

The approach based on decoders requires writing both API-calling code as well as the decoders themselves by hand. In a perfect world, we would like to avoid this, and instead have everything autogenerated from the API schema/definition. swagger-codegen is one such solution — given a Swagger spec file, it can generate API-calling code in a wide variety of languages, including TypeScript. And if we make the code generation as part of our CI pipeline, we won't even need decoders, since the API calling code will always match the API itself!

For node.js APIs written in TypeScript it is even possible to generate both the swagger spec and code for runtime validation via tsoa (see this comment for more details).

While "magical" solutions might sometimes be tricky to understand or debug, this approach offers some noticeable benefits over writing validation or decoding code by hand. For instance, we don't have to write and maintain lots of extra code that validates API response whenever the API changes. In fact, breaking changes to the API would be (indirectly) caught by the TypeScript compiler, which means we're getting a lot of (automated) help in ensuring that we're not shipping a broken product.

The "crazy-but-fun" approach

Oh, and for the more adventurous kind — it is also possible to implement an API-calling layer in ReasonML, generate TypeScript types via genType and tie everything together with the rest of the codebase via BuckleScript. Seems overkill, but why not learn a new technology and have some fun at the same time? 😄

Adding ReasonML to a React TypeScript codebase

Kyrylo Yakymenko — Sun, 26 May 2019 22:30:54 +0000

The most natural way to introduce ReasonML into an existing React codebase is by writing a few components in ReasonReact. Nowadays, with 0.7.0 and support for react hooks, it's not that different from writing components in JavaScript. In this article, however, we are going to explore an alternative way into an existing codebase — creating an API-calling-and-decoding layer in Reason.

Note: This is the third article in my miniseries about integrating Reason into an existing codebase. For a more basic explanation about how everything hangs together, check out the first article: Adding ReasonML to an existing codebase. Curious about using Reason in a Vue.js codebase? The second article, Adding ReasonML to a Vue application, explains just that 😃

Step 0: Starting point

Our starting point is a React application created via create-react-app. This guide will work equally well for a pure JavaScript codebase, but to make things a bit tricker, let's say this is a TypeScript application — this will require our API-calling functions to generate TypeScript types, rather than plain JavaScript. Good news — genType integration has become much easier with BuckleScript 5.

// Detect dark theme var iframe = document.getElementById('tweet-1109976216969322498-582'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1109976216969322498&theme=dark" }

Step 1: Adding BuckleScript

We are going to need BuckleScript for compiling ReasonML or OCaml code to JavaScript and genType in order to generate TypeScript types. More about this in Part 1 of the mini series.

Let's go ahead and install the packages:

npm install --save-dev bs-platform gentype
npm install -g bs-platform

We're going to need to make sure bucklescript runs before babel, so let's add the command to the start and build scripts in package.json:

"scripts": {
  "start": "bsb -make-world && react-scripts start",
  "build": "bsb -make-world && react-scripts build"
}

The last thing left before we can start writing code is to add bsconfig.json:

{
  "name": "reason-in-react-typescript",
  "sources": [
    {
      "dir": "src/reason",
      "subdirs": true
    }
  ],
  "package-specs": [
    {
      "module": "es6-global",
      "in-source": true
    }
  ],
  "suffix": ".bs.js",
  "namespace": true,
  "refmt": 3,
  "gentypeconfig": {
    "language": "typescript"
  }
}

Step 2: Writing a function in Reason

Note that src/reason is specified as the sources directory, so let's create it and add a TestFunctions.re file so that we can test our setup:

let reasonSum = (a, b) => a + b;

If you're using VS Code with the reason-language-server extension, a TestFunctions.bs.js file will immediately get generated next to the .re file:

function reasonSum(a, b) {
  return (a + b) | 0;
}

Annotating the function with [@genType] would produce a TestFunctions.gen.tsx file next to TestFunctions.bs.js:

[@genType]
let reasonSum = (a, b) => a + b;

// tslint:disable-next-line:no-var-requires
const Curry = require("bs-platform/lib/es6/curry.js");

// tslint:disable-next-line:no-var-requires
const TestFunctionsBS = require("./TestFunctions.bs");

export const reasonSum: (_1: number, _2: number) => number = function(
  Arg1: any,
  Arg2: any
) {
  const result = Curry._2(TestFunctionsBS.reasonSum, Arg1, Arg2);
  return result;
};

At this point we can use the reasonSum function from JavaScript or TypeScript — let's call it from our React component:

import * as React from "react";
import { reasonSum } from "./reason/TestFunctions.gen";

export const TestComponent = () => (
  <div>Result of a ReasonML function call: {reasonSum(1, 2)}</div>
);

It is possible to import reasonSum from TestFunctions.bs.js instead, if we were working with a pure JavaScript codebase. In this case, we won't get any type information.

Note that if you're running from the terminal and would like changes in Reason files to get transpiled and picked up on the fly, your would need to have bsb -make-world -w running in the background:

Step 3: Calling the API and decoding the response in Reason

The next step is adding an API call that will fetch some interesting information about a random number from http://numbersapi.com.

A call to http://numbersapi.com/random/math?json would produce the following response:

{
  "text": "880 is the number of 4×4 magic squares.",
  "number": 880,
  "found": true,
  "type": "math"
}

We're going to make the API call with bs-fetch and decode the response with bs-json:

npm install --save bs-fetch @glennsl/bs-json

An important step that is easy to forget is adding those dependencies to bsconfig.json:

  "bs-dependencies": ["@glennsl/bs-json", "bs-fetch"]

Now we can create a new file NumberFacts.re, model the type and create a decoder:

[@genType]
type numberFact = {
  number: int,
  text: string,
  isFound: bool,
};

module Decode = {
  let fact = json =>
    Json.Decode.{
      number: json |> field("number", int),
      text: json |> field("text", string),
      isFound: json |> field("found", bool),
    };
};

This generates a numberFact type in TypeScript:

export type numberFact = {
  readonly number: number;
  readonly text: string;
  readonly isFound: boolean;
};

The API call itself can be performed this way:

[@genType]
let fetchNumberFact = () =>
  Js.Promise.(
    Fetch.fetch("http://numbersapi.com/random/math?json")
    |> then_(Fetch.Response.json)
    |> then_(json => json |> Decode.fact |> resolve)
  );

The inferred type in Reason is unit => Js.Promise.t(numberFact), as expected. The generated TypeScript function looks like this:

export const fetchNumberFact: (_1: void) => Promise<numberFact> = function(
  Arg1: any
) {
  const result = NumberFactsBS.fetchNumberFact(Arg1);
  return result.then(function _element($promise: any) {
    return { number: $promise[0], text: $promise[1], isFound: $promise[2] };
  });
};

I explain the differences between the code generated by BuckleScript and genType in the first article of this miniseries.

Step 4: Tying it all together

This is all we have to do on the Reason side of things. Now it is time to call our function from the React component and display the result:

import React, { useState, useEffect } from "react";
import {
  numberFact as NumberFact,
  fetchNumberFact
} from "./reason/NumberFacts.gen";

export const App: React.FC = () => {
  const [numberFact, setNumberFact] = useState<NumberFact | null>(null);

  const fetchNewFact = () =>
    fetchNumberFact()
      .then(newFact => setNumberFact(newFact))
      .catch(e => console.log("Error fetching number fact: ", e));

  useEffect(() => {
    fetchNewFact();
  }, []);

  return (
    <div className="App">
      {numberFact === null ? (
        "Loading initial number fact..."
      ) : (
        <div className="number-fact">
          <div>Number: {numberFact.number}</div>
          <div>Fact: "{numberFact.text}"</div>
          <div>{numberFact.isFound ? "Found" : "Not found!"}</div>
          <button onClick={fetchNewFact}>Fetch new fact</button>
        </div>
      )}
    </div>
  );
};

A new fact will be automatically loaded after the component is mounted. Clicking the "Fetch new fact" button would load a fresh random number fact — all done via ReasonML code.

Summary

Adding ReasonML to an existing React codebase can be done in a matter of minutes. After this initial setup, it becomes possible to write logic in ReasonML or OCaml and use it in existing React components. This approach is an alternative to jumping straight into ReasonReact (in case that seems too big of a step). The source code is available on GitHub.

The same approach can be used for adding ReasonML to a Vue.js application, or pretty much any other JavaScript application.

Adding ReasonML to a Vue application

Kyrylo Yakymenko — Sun, 26 May 2019 22:14:08 +0000

Despite the fact that ReasonML is a natural fit for React, thanks to BuckleScript it can easily be used in any JavaScript application. And yes — this includes Vue.js!

If you're working with Vue and like OCaml/ReasonML, or whether you've heard all the hype and are curious to try — in this article I will show how to use code written in Reason from Vue.

Note: This is the second article in my miniseries about integrating Reason into an existing codebase. For a more basic explanation about how everything hangs together, check out the first article: Adding ReasonML to an existing codebase. In Part 3 we're going to integrate Reason into a React TypeScript codebase.

Step 0: Starting point

Our starting point is a freshly created Vue application with the help of the Vue CLI default preset. It is worth noting that thanks to genType, this guide would work equally well for a TypeScript application.

Step 1: Adding BuckleScript

We are going to need BuckleScript for compiling ReasonML or OCaml code to JavaScript and genType in order to simplify interop between Reason and JS. More about this in Part 1 of the mini series.

Let's go ahead and install the packages:

npm install --save-dev bs-platform gentype
npm install -g bs-platform

We're going to need to make sure bucklescript runs before babel, so let's add the command to the start and build scripts in package.json:

"scripts": {
  "serve": "bsb -make-world && vue-cli-service serve",
  "build": "bsb -make-world && vue-cli-service build"
}

The last thing left before we can start writing code is to add bsconfig.json:

{
  "name": "reason-in-vue",
  "sources": [
    {
      "dir": "src/reason",
      "subdirs": true
    }
  ],
  "package-specs": [
    {
      "module": "es6-global",
      "in-source": true
    }
  ],
  "suffix": ".bs.js",
  "namespace": true,
  "refmt": 3,
  "gentypeconfig": {
    "language": "untyped"
  }
}

Step 2: Writing a function in Reason

Note that src/reason is specified as the sources directory, so let's create it and add a TestFunctions.re file so that we can test our setup:

let reasonSum = (a, b) => a + b;

If you're using VS Code with the reason-language-server extension, a TestFunctions.bs.js file will immediately get generated next to the .re file:

function reasonSum(a, b) {
  return (a + b) | 0;
}

Annotating the function with [@genType] would produce a TestFunctions.gen.js file next to TestFunctions.bs.js:

[@genType]
let reasonSum = (a, b) => a + b;

import * as Curry from "bs-platform/lib/es6/curry.js";

import * as TestFunctionsBS from "./TestFunctions.bs";

export const reasonSum = function(Arg1, Arg2) {
  const result = Curry._2(TestFunctionsBS.reasonSum, Arg1, Arg2);
  return result;
};

At this point we can use the reasonSum function from JavaScript — let's call it from our Vue component:

<template>
  <div id="app">
    <div>The result is {{ result }}</div>
  </div>
</template>

<script>
import { reasonSum } from "./reason/TestFunctions.gen";

export default {
  name: "app",
  data() {
    return {
      result: reasonSum(1, 2)
    };
  }
};
</script>

Note that if you're running from the terminal and would like changes in Reason files to get transpiled and picked up on the fly, we would need to have bsb -make-world -w running in the background:

Step 3: Calling the API and decoding the response in Reason

The next step is adding an API call that will fetch some interesting information about a random number from http://numbersapi.com.

A call to http://numbersapi.com/random/math?json would produce the following response:

{
  "text": "880 is the number of 4×4 magic squares.",
  "number": 880,
  "found": true,
  "type": "math"
}

We're going to make the API call with bs-axios and decode the response with bs-json:

npm install --save bs-axios @glennsl/bs-json

An important step that is easy to forget is adding those dependencies to bsconfig.json:

  "bs-dependencies": ["@glennsl/bs-json", "bs-axios"]

Now we can create a new file NumberFacts.re, model the type, and create a decoder:

[@genType]
type numberFact = {
  number: int,
  text: string,
  isFound: bool,
};

module Decode = {
  let fact = json =>
    Json.Decode.{
      number: json |> field("number", int),
      text: json |> field("text", string),
      isFound: json |> field("found", bool),
    };
};

The API call itself can be performed this way:

[@genType]
let fetchNumberFact = () =>
  Js.Promise.(
    Axios.get("http://numbersapi.com/random/math?json")
    |> then_(response => response##data |> Decode.fact |> resolve)
  );

The inferred type in Reason is unit => Js.Promise.t(numberFact), as expected. The generated JavaScript code in NumberFacts.gen.js function looks like this:

import * as NumberFactsBS from "./NumberFacts.bs";

export const fetchNumberFact = function(Arg1) {
  const result = NumberFactsBS.fetchNumberFact(Arg1);
  return result.then(function _element($promise) {
    return { number: $promise[0], text: $promise[1], isFound: $promise[2] };
  });
};

I explain the differences between the code generated by BuckleScript and genType in the first article of this miniseries.

Step 4: Tying it all together

This is all we have to do on the Reason side of things. Now it is time to call our function from the Vue component and display the result:

<template>
  <div id="app">
    <div class="number-fact">
      <div>Number: {{numberFact.number}}</div>
      <div>Fact: "{{numberFact.text}}"</div>
      <div>{{numberFact.isFound ? "Found" : "Not found!"}}</div>
      <button @click="fetchNewFact">Fetch new fact</button>
    </div>
  </div>
</template>

<script>
import { fetchNumberFact } from "./reason/NumberFacts.gen";

export default {
  name: "app",
  data() {
    return {
      numberFact: {
        number: -1,
        text: "-1 is not an interesting number",
        isFound: false
      }
    };
  },
  methods: {
    fetchNewFact: function() {
      fetchNumberFact().then(numberFact => (this.numberFact = numberFact));
    }
  },
  mounted: function() {
    this.fetchNewFact();
  }
};
</script>

A new fact will be automatically loaded after the component is mounted. Clicking the "Fetch new fact" button would load a fresh random number fact — all done via ReasonML code.

Summary

Adding ReasonML to an existing Vue codebase can be done in a matter of minutes. After this initial setup, it becomes possible to write logic in ReasonML or OCaml and use it in existing Vue components. The source code is available on GitHub.

Hopefully this tutorial will inspire Vue.js developers to try ReasonML!

Adding ReasonML to an existing codebase (Part 1)

Kyrylo Yakymenko — Sun, 26 May 2019 22:14:02 +0000

First things first, stating the not-so-obvious: Adding ReasonML to an existing JavaScript application is extremely easy! In fact, it's not that more difficult than adding Flow. So if you've heard about ReasonML and are curious about trying it out, but not sure how to integrate it into an existing codebase — good news — you can be up-and-running within 10 minutes 😃

This is going to be a miniseries about adding ReasonML to an existing codebase. In this part, we're going to look at the basics, by using an example with a vanilla JavaScript setup with webpack:

writing code in ReasonML
calling it from JavaScript
using ReasonML types as JavaScript records (via genType)

In Part 2 we are going to look at how to add some API-calling-and-decoding functions written in ReasonML to a Vue.js application. And in Part 3 we're going to use the same API caller in a React TypeScript application. So let's get started.

Step 0: Starting point

The starting point is an (almost) empty application created by following the Getting Started section from the webpack guide. The index.js file looks like this:

function component() {
  const element = document.createElement("div");

  element.innerHTML = `Placeholder content`;

  return element;
}

document.body.appendChild(component());

We have 2 scripts in package.json:

"scripts": {
  "build": "webpack",
  "start": "webpack-dev-server --open"
}

Step 1: Adding BuckleScript

BuckleScript is used for compiling ReasonML or OCaml code to JavaScript, while genType is going to simplify interop between Reason and JS:

npm install --save-dev bs-platform gentype

In order to make it work, we simply need to run bsb -make-world, which will transpile our ReasonML code to JavaScript first. After that the generated *.bs.js files are going to get picked up by webpack and treated the same way as "normal" JavaScript code. Let's add the bsb -make-world command to the build and start scripts in package.json:

"scripts": {
  "build": "bsb -make-world && webpack",
  "start": "bsb -make-world && webpack-dev-server --open"
}

The last thing left before we can start writing code is to add bsconfig.json:

{
  "name": "reason-in-javascript",
  "sources": [
    {
      "dir": "src",
      "subdirs": true
    }
  ],
  "package-specs": [
    {
      "module": "es6-global",
      "in-source": true
    }
  ],
  "suffix": ".bs.js",
  "namespace": true,
  "refmt": 3
}

Note: If you're using VS Code with the reason-language-server extension, the IDE watches the folders and transpiles Reason and OCaml files on the fly. Otherwise, we would have to run a watcher-process in a terminal window in the background. In this case we would need to install bs-platform globally: npm install -g bs-platform.

Step 2: Calling a ReasonML function from JavaScript

Now it's time to create a TestFunctions.re file so that we can test our setup:

let reasonSum = (a, b) => a + b;

The easiest way to make sure this is transpiled to JavaScript during development is to run bsb -make-world -w in a terminal in the background. The -w flag makes sure bucklescript watches for changes in the folders specified in the sources section in bsconfig.json. As mentioned earlier, VS Code with the reason-language-server, would handle this automatically and everything would work smoothly even without a background-watcher-terminal. A TestFunctions.bs.js file will immediately get generated next to the .re file:

function reasonSum(a, b) {
  return (a + b) | 0;
}

The generated code is simple enough, so let's import the reasonSum function in index.js and call it:

import { reasonSum } from "./TestFunctions.bs";

function component() {
  const element = document.createElement("div");
  element.innerHTML = `The result is ${reasonSum(1, 2)}`;

  return element;
}

document.body.appendChild(component());

Sure enough — we can now run npm start and see the text: "The result is 3" in the browser. If we change the Reason code to a + b + 1; and save, the text in the browser would get updated to "The result is 4" on the fly. This means that the code written in ReasonML is now succesfully transpiled, picked up, and run in our JavaScript codebase!

Step 3: Returning a record from ReasonML

How about returning an object from ReasonML? Let's try this with a simple user object:

type user = {
  id: int,
  name: string,
  isActive: bool,
};

let getUser = (): user =>
  {id: 1, name: "Bob", isActive: true};

The generated JavaScript code looks a bit suspicious, since Reason objects get compiled to JavaScript arrays:

function getUser(param) {
  return /* record */[
          /* id */1,
          /* name */"User1",
          /* isActive */true
        ];
}

If we try calling this "as-is" from our index.js, we would not get what we're expecting:

const user = getUser();
console.log("User: ", user);

// console output shows an array, rather than a JSON object:
User: Array(3)
        0: 1
        1: "User1"
        2: true

This is where genType comes in. It can generate types for TypeScript and Flow, as well as "glue-functions" between ReasonML and JavaScript. More about how it works.

Since genType is now supported "out-of-the-box" with BuckleScript 5, all we have to do is to add a gentypeconfig section to bsconfig.json:

"gentypeconfig": {
  "language": "untyped"
}

Now adding a [@genType] annotation to getUser would produce a new ReasonFunctions.gen.js file next to ours:

/* ReasonFunctions.re */

[@genType]
let getUser = (): user =>
  {id: 1, name: "User1", isActive: true};

/* ReasonFunctions.gen.js */

import * as ReasonFunctionsBS from "./ReasonFunctions.bs";

export const getUser = function(Arg1) {
  const result = ReasonFunctionsBS.getUser(Arg1);
  return { id: result[0], name: result[1], isActive: result[2] };
};

Now before calling this from JavaScript, we need to make sure we import getUser from ReasonFunctions.gen, and NOT from ReasonFunctions.bs:

import { getUser } from "./ReasonFunctions.gen";

const user = getUser();
console.log("User: ", user);
const userGreeting = `Hello, ${user.name}!`;
alert(userGreeting);

Now this code produces a pleasant "greeting" message, as well as an expected log in the console:

User: Object
        id: 1
        isActive: true
        name: "User1"

Summary

This is the first article in this miniseries, which demonstrates (on a relatively low-level) the basics of what happens to code written in ReasonML and how it ends up in a JavaScript codebase. The source code is available on GitHub.

The followup articles will show more practical examples of how to use this approach for including Reason code in an existing Vue.js application, as well as a React TypeScript application, without losing type information along the way.

Seriously - do React hooks replace state containers?

Kyrylo Yakymenko — Thu, 25 Apr 2019 08:00:39 +0000

The question about React hooks replacing state containers has been coming up more and more often in the React community recently.

// Detect dark theme var iframe = document.getElementById('tweet-1118110824676110336-222'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1118110824676110336&theme=dark" }

Nevertheless, the question is not completely out of place. useReducer and useState handle the state management part, while useContext can help with its "global nature".

Moreover, a lot of advice floating around sounds as follows:

start by putting state in your components.
whenever a piece of state needs to be shared, lift state up.
if prop-drilling becomes an issue, throw it onto context for ease of "global" access.

Armed with this advice, and eager to test it out in practice, let's go ahead and build a React app!

The initial specification from the client looks simple enough: a page with a header (containing a Menu and some user information), a footer, and a sortable/pageable/filterable grid in the main content area.

Looks really easy — following the advice above, let's put the state for the grid content and paging close to the grid itself. We also have some state describing what column the grid is sorted by, as well as what filter values have been chosen for each column. So far so good! Development is going really fast and we can quickly iterate on our solution. The component tree looks nice and clean:

At some point we add a toolbar with a settings button, that would open a "settings" dialog and allow to set the number of items per page. Since this state is currently in the "paginator" component, we do not have access to it from the "settings" dialog. No problem, we lift the pagination state one level up and pass it down to both the "paginator", the grid and the settings dialog.

The first Demo to the client is a success! We get some feedback and they would like some improvements — they want to be able to export the grid content to PDF, so we add a new button to the toolbar — it would open a confirmation dialog with some information about the total number of rows to be exported, so let's lift this piece of state up from the grid too, and pass it down to both — the grid itself, as well as the "report generation" dialog. Manageable so far, but getting messy. Time to document the structure. A stateful component with a couple of useState hooks and a useEffect hook would look something like this:

The arrows from state and setState go to and from JSX, since we would probably use and set state from there. The same applies to props. useEffect closes over props too and has access to state, so let's add those arrows too. We end up with a lot of arrows, but everything is nicely encapsulated inside the component, so let's update our Component Tree diagram:

A slack message comes from our UX team — they've convened and decided to have the settings icon down in the footer instead. We've already done some refactoring and lifted the "page size" portion of state up once, but now it would end up right in the root component, since it's the only common ancestor of the components that need it. Prop drilling suddenly becomes real, so it seems like it's time to throw it onto context and access it directly from the components that care. This would add a few more arrows to our component-tree-structure-diagram, but we implement it and move on.

A couple of sprints later an email from the client rattles in our inbox — they've tried the current version of our page and would like some changes:

it should be possible to choose what columns are to be exported to the PDF report.
the report should respect the filters chosen in the view.
the name of the user exporting the report should be displayed in the dialog (remember how this information is now local state in the header?)

Somewhere around this point is where we start slightly hating our life — things are getting really tough to keep track of! We'll have to move some more chunks of state around, namely to lift column-state and filter-state up from the grid, and lift user state up from the header to the root component.
Some of the excitement we felt at the start of the project has now worn off, and the rate of progress has considerably slowed down. But things have not gotten completely out of hand, have they? Let's buckle-up and get to it!

We're diligently following the recipe by lifting state up or putting stuff into context — which adds more and more arrows to our component tree diagram. We discover that the view becomes slow and laggy, so we fire up our profiler and discover that large portions of our component tree get unnecessarily re-rendered too often, so we take a step back and analyze the situation, determine which parts of the view can be memoized and wrap them in React.memo. In some cases we get immediate improvements, but others, however, don't seem to be affected by the change since some lambda functions are passed as props. We solve it with the help of useCallback instead. It feels a bit like a chain reaction: solutions to our previous problems cause new problems, and solutions to those require more solutions, and so on... No matter what, we discover that every one of those problems is solvable as long as we dig deep enough into how React works, so there is no point in complaining. We're done with most of the functionality for now, so let's ship!

Before we do, however, we get one more request from the client that just finished testing the latest version and found the "settings" icon to be difficult to find down in the footer. Since they use it often, they would prefer it to be next to the grid, as in the initial version. Hmm... let's try to remember where we put the state for that one... Right, it ended up on context, since we pulled the components apart after some feedback from the UX team a while ago. Now it's going to be close to the grid... so shall we remove it from the context and put it back into local state close to the components? Nah, just leave it as is, you never know when we're going to have to move it again 😬

A few months later a new dev comes to work on the project and is given the task of adding information about the current page and page size to the PDF report dialog.

— New dev (after some detective work): There is one thing I can't quite wrap my head around... How come pageSize is placed in context?
— Old dev: Can't remember how it ended up there, the dev who did it doesn't work here anymore, but at some point it was probably more convenient, since it was used from the footer or sidebar or something.
— New dev: Really? Isn't it ridiculous that we have to do so much refactoring every time a UI element is moved to a different place?
— Old dev: At least we managed to avoid pulling in a state container! 🤷‍♀️

Somehow this reminds me of the term "coding by coincidence". Stuff ends up the way it is because "it just happened this way".
This approach contrasts starkly to what software architecture is all about — having a flexible way of adapting to changing requirements.
Having said that, not every project requires a flexible architecture. If the application is really small, or if it rarely has to change, structuring and architecting it would not be a reasonable time investment.

Hopefully this little (totally made up) story helps shed some light on the question whether hooks replace a state container. The (slightly elusive) answer is — "with hooks, classes or other mechanisms that React provides, it is indeed possible to achieve most of what a state container offers", but more often than not, the application structure is going to look much more messy than in the image below.

Let's see this again in slow motion: