DEV Community: Carlos Cuesta

Writing RFCs

Carlos Cuesta — Wed, 06 Mar 2024 14:00:00 +0000

A Request For Comments also known as RFC, is a process that captures ideas and proposals about a specific topic to discuss and find consensus 🤝.

An RFC involves a document or a series of documents 📑, which are drafted, reviewed and eventually approved or rejected by a group of people.

What are the benefits?

Planning

Writing down your idea into a document will clarify your thoughts and will help organizing them in a structured manner.

Anticipating 🔮 the problem you aim to solve and envisioning potential solutions is key to identifying issues and edge cases.

Alignment

As a team, it's important that decisions 🎙️ are made by reaching a consensus 🤝. It's very common that as humans we have different opinions and points of view.

RFCs are an effective process to include everyone's opinions 💭 and reach a decision everyone agrees with.

Documentation

The document 📑 itself is a valuable piece of documentation as it captures the context, the problem, the solution, and the decision-making process.

It will serve as a reference for future team members and will help them understand the context and the reasoning behind the decisions made ❣️

An RFC is usually the initial step in the decision-making process before creating Architecture Decision Record which I previously wrote about ✍️

Better decision-making

One of the steps of the process is to share the RFC with the team to collect feedback and review the context and the proposed solution.

Involving multiple people 🧠 in the decision-making process is key to achieve high quality decisions, as it will bring different perspectives and solutions to the table reducing the chances of overlooking important details.

You can think of it as a code review, but for ideas and proposals.

When you should write an RFC?

It depends 🙈 but generally I would recommend writing them when dealing with high-impact decisions and major changes that require consensus and alignment such as:

Introducing a new service in your company 🚀
Major changes in the architecture 🏗️
Big features that have an overarching impact 🆕

It's up to you to decide when to write them, but in my opinion you should weight ⚖️ the effort 🥵 and the impact 💥 since it's a time-consuming process that involves many people.

How to write an RFC

Define a template

When writing them, a common practice is to have a template to write ✍🏼 all the documents in the same way.

You'll find a lot of templates online, but this is the one I use 👈

❗️ Use a tool that allows collaborative features (comments, suggestions etc) to make it easier for the team to review and provide feedback such as Google Docs or Notion.

Share document for review

Once you have the document ready, share it with the team for them to review 👀 and provide feedback.

Address feedback

After the reviews come in, you should address the comments, questions and concerns and incorporate any suggestions if appropriate 🖊️.

Make a decision

Finally, after the document has been reviewed and the feedback has been addressed and collected, it's time to make a decision.

The team should either approve ✅ the RFC and move forward with the proposal or reject ❌ it.

Examples

In case you're looking for inspiration, there are many organizations and communities that use RFCs to propose and discuss new ideas, here are some examples:

Conclusion

RFCs are a powerful process to gather feedback, align the team and document decision-making. They're a great way to reach consensus as a team representing everyone's opinion.

I encourage you to give them a try and see how they can help you and your team to make better decisions! 🫰

Effective Refactoring with Codemods

Carlos Cuesta — Mon, 30 Jan 2023 17:58:36 +0000

Metaprogramming is a technique where we write code to manipulate other code. I know this sounds a bit intimidating and confusing 😱, but actually I'm sure you've already used it in your daily work.

Have you ever used a transpiler, a linter or a code formatter, such as: Babel, ESLint or Prettier? If the answer is yes, then you've already used metaprogramming! 👏

In this article I'm going to explain how you can use codemods (metaprogramming) to perform large-scale refactors to a codebase. Let's dive into it! 🤿

What is a codemod?

A codemod is a tool that helps you with large-scale refactors by running transformations on your codebase programatically.

This automated transformations will allow you to change large amount of files without having to go through them manually, saving a lot of time and increasing confidence! 🙌

How do they work?

On a general level codemods perform the following steps:

Read the code input 📖
Generate an Abstract Syntax Tree (AST) 🌳
Transform the AST 🔄
Generate the new source code 📦

Abstract Syntax Trees is what makes all of this magic 🪄 possible. Let's understand what they are and how they work 👇

Abstract Syntax Trees

An Abstract Syntax Tree (AST) is a tree data structure that represents a piece of code.

Let's understand it with an example 🖼️:

function sayHello(name) {
  return `Hello ${name}! 👋`
}

To inspect and visualize the AST for the snippet of code 👆, we will use the AST Explorer. This is an online tool that allows you to explore and play with abstract syntax trees.

The entire snippet is represented by a Program node. Inside of this node we can find different children, each of which represents a different part of the code:

As you can see on the image the code is represented as a tree. There are different types of nodes and we can navigate through them 🚢:

The nodes shown in the image, will be the ones we'll traverse when writing codemods! You can explore the AST using this link 👈

That's pretty cool right? 🤓. Now that we understand how we can navigate AST, let's see how we can combine them with codemods to perform large-scale refactors 🚀.

Refactoring with codemods

Time to put knowledge into 👨‍💻 practice. I'm going to use JavaScript for the sake of example, but the fundamentals and concepts are the same for any other language.

I will use the following tools to perform the refactor:

AST Explorer: The online tool we saw before to explore and visualize AST.
JSCodeshift: A toolkit for running and writing codemods.

Understanding the transformation

Input

Image that in our codebase we are using the lodash/get helper to safely extract values from objects, like this:

import { get } from 'lodash/object' // get(object, path, [defaultValue])

const cartTotal = get(cart, 'attributes.items.total', 0)

Output

Now, we decide that we want to stop using the lodash helper in favour of the native JavaScript operator to safely extract values from objects: optional chaining, in this way:

const cartTotal = cart?.attributes?.items?.total ?? 0

As you can see on the code 👆 our transformation needs to perform a few changes:

Remove the import statement.
Replace the get helper with optional chaining.
Provide a default value if the value is undefined.

Writing the Codemod

With the transformation clear in mind, it's time write the codemod! 👨‍💻. Go ahead and open the AST Explorer and select:

Language: JavaScript
Parser: @babel/parser
Transform: jscodeshift

You can also use this link to open the explorer 🕵️‍♀️ with the correct settings and code 👈. You should end up with a screen similar to this one:

Generating the AST

The first thing we need to do is transforming the source code into an Abstract Syntax Tree, so we can traverse it.

To transform code into an AST we will invoke the j function from the jscodeshift library, passing the code as a parameter:

export const parser = 'babel'

export default function transformer(file, api) {
  const j = api.jscodeshift
  const ast = j(file.source)
}

Traversing the AST

With the AST 🌳 already in place, we can start traversing it. Use the explorer panel to find the nodes that represents the import statement and the get() helper calls. Did you find them? 👇

These are the two nodes we will need to transform to refactor our code: ImportDeclaration and CallExpression.
Now, let's transform the nodes ♻️

Transforming the nodes

As we saw before, we need to transform two nodes from the AST:

CallExpression: Remove lodash get helper with optional chaining.
ImportDeclaration: Remove the get import statement.

Once the AST is completely transformed, we will convert it back to source code.
Let's break this down into steps ✅:

1. Find `get` helper usages

To find get calls we will have to traverse the AST, finding nodes with the type CallExpression containing a callee.name of get 🔎

ast.find(j.CallExpression, { callee: { name: 'get' }})

2. Replace `get` with optional chaining and default value

For every match, we will replace the AST object to use optional chaining and the default value ♻️
For that, we will use the replaceWith function, passing the new AST object as a parameter.

I know the AST transformation might look a bit complex 😨, but it's just a combination of:

ExpressionStatement: To replace the function call with an expression.
LogicalExpression: To provide a default value.
OptionalMemberExpression: To build the optional chaining.
Identifier: To represent the source object.

.forEach(node => {
  const [source, path, fallback] = node.value.arguments
  const pathItems = path.value.split('.')
  const lastPathItem = pathItems.at(-1)

  j(node).replaceWith(
    j.expressionStatement(
      j.logicalExpression(
        '??', 
        j.optionalMemberExpression(
          pathItems.slice(0, -1).reduce(
            (node, param) => j.optionalMemberExpression(
              node, 
              j.identifier(param)
            ),
            source
          ),
          j.identifier(lastPathItem)
        ), 
        fallback
      )
    )
  )
})

3. Find lodash/get import statements

Once get is removed, we can safely delete the import statements. But first, we will need to find nodes with the type ImportDeclaration containing a source.value of lodash/object 🔎

ast.find(j.ImportDeclaration, { source: { value: 'lodash/object' }})

4. Prune import statements

To remove get from the import statement, we will iterate over the matches filtering the specifiers array to remove the get import. In case there are no more imports, we will remove the complete statement.

.forEach((node) => {
  const importedModules = node.value.specifiers.filter(
    ({ imported }) => imported.name !== 'get'
  )

  if (importedModules.length) {
    node.value.specifiers = importedModules
  } else {
    j(node).remove()
  }
})

5. Convert AST back to source code

Once all the transformations are applied, we need to convert the AST 🌳 object back to source code 🪄.
For that we will use the following method:

ast.toSource()

Putting it all together

Now it's time to put all the pieces together 🧩, so we can transform our code to the output we described before:

Click here to see the snippet 👈

  export const parser = 'babel'

  export default function transformer(file, api) {
    const j = api.jscodeshift;
    const ast = j(file.source)

    ast
      .find(j.CallExpression, { callee: { name: 'get' }})
      .forEach(node =&gt; {
        const [source, path, fallback] = node.value.arguments
        const pathItems = path.value.split('.')
        const lastPathItem = pathItems.at(-1)

        j(node).replaceWith(
          j.expressionStatement(
            j.logicalExpression(
              '??', 
              j.optionalMemberExpression(
                pathItems.slice(0, -1).reduce(
                  (node, param) =&gt; j.optionalMemberExpression(
                    node, 
                    j.identifier(param)
                  ),
                  source
                ),
                j.identifier(lastPathItem)
              ), 
              fallback
            )
          )
        )
      })

    ast
      .find(j.ImportDeclaration, { source: { value: 'lodash/object' } })
      .forEach((node) =&gt; {
        const importedModules = node.value.specifiers.filter(
          ({ imported }) =&gt; imported.name !== 'get'
        )

        if (importedModules.length) {
          node.value.specifiers = importedModules
        } else {
          j(node).remove()
        }
      })

    return ast.toSource()
  }

Finally we can see the codemod in in action 💖

Testing codemods

Codemods can be potentially dangerous and they can break your code 🐛. Luckily, you can write unit tests for them to ensure everything works as expected ✅ before running them on the codebase.

The library I used on this article provides some utilities to test codemods. You can find more information about them here.

In case you're using a different tool with no testing utilities, you can always test codemods by running them over a mock file asserting the output.

Conclusion

Automating codebase changes can be difficult the first time you do it, but it's totally worth it.
It will save you a lot of time 🚀 and it will prevent you from introducing bugs 🐛.

Automate all the things! 🙌

Using generators to improve developer productivity

Carlos Cuesta — Sat, 28 May 2022 15:22:38 +0000

A few weeks ago at N26, we did get stuff done week, during this time the product and engineering teams have the opportunity to try or build anything we like.

I decided to spend the week adding a code generation tool to the Web project
automating a bit of the coding work while improving the developer experience.

In this article, I'll walk through the experience and the outcome of implementing a tool to generate code 👨‍💻

What is a code generator?

A code generator is a tool that given a set of rules and inputs creates code, files, and folders.

To name a few popular ones 👇

All of them will create code based on specific rules taking into account the inputs provided by the user. Here's a simple example 👇

What's the problem?

Imagine, you start the day working on a new task and you need to create a feature, before writing any code you will need to consider a few things:

Folder structure and architecture 📂
Naming files convention 📑
Where to put the feature 🗂
How you should write the tests 🧪

I'm sure the project you're working on has a list of conventions and patterns defined that explains how you should work in the codebase.

However, every time you are going through this process it requires you to think 🤔 about those conventions to make the decision.

Where is the source of truth? 🧐

Documentation 📝
Architecture Decision Records 🏗
Similar files on the codebase 🕵️
A teammate 🧑‍💻

As software engineers we work very hard to not repeat code building abstractions, automating manual workflows...

What about writing code? In the same way, we advocate for automating processes such as deployments, we should also make an effort to the non-creative part of coding such as scaffolding.

Why you should use them?

Generating code will save you time ⏰ and will increase the productivity of the team 📈

Developer experience

In a team that is constantly growing it is important to make sure that everyone is aligned and able to build things efficiently.

Having a great Developer Experience will boost the confidence a developer has with the codebase.

Trust, empowers people to be more productive and agile ⚡️, to name a few of the many benefits you'll get by using generators:

Ensure everyone is doing things "as expected" according to the project conventions 💖
Reduce friction when working with the codebase 🤔
Ease the onboarding of new joiners 🆕
Decrease the development time 🚀

Decision fatigue

The most important thing is that your teammates will not have to spend time on low-value decisions, such as deciding how a component is structured.

Turns out our decision-making process gets worse the more decisions we make.

This is called decision fatigue. For example, Steve Jobs, limited his everyday clothing down to one outfit to avoid making a decision.

Using code generators

Sounds good right 😍? Let's take a look at how we can implement code generators in our project 👀

Choosing the right tool

I didn't want to reinvent the wheel, my focus was set on the outcome of generating code, not building a tool that solves this problem.

There are a lot of Open Source projects that will do an awesome job generating code. Here's the list of the ones I considered:

I decided to go with Hygen at N26 because:

Great monorepo support
Easy to maintain. You'll only need to care about .EJS template files and prompts.
No configuration required
High value with low effort, writing a generator is very simple.

Plop is also a great tool but creating a generator is more complex since you need to spend more time writing code and the tool demands extra time on the configuration part compared to Hygen.

Yeoman is another valid option, but maintaining generators requires you to manage and publish packages to a registry and I would say the use-case of this tool is more suited to scaffolding projects instead of smaller parts of a codebase.

Getting started

It's time to create our code generator 🥳. First, install Hygen as a devDependency in your project:

$ npm install -D hygen

Define a script inside the package.json to use the script binary:

{
  "scripts": {
    "generators": "hygen"
  }
}

Now we can run Hygen through the generators script:

$ npm run generators

After running the command, you'll see that Hygen is telling us we don't have any generators.

Error: please specify a generator.
Hygen v6.2.0

By default, hygen will read the generator files from a folder named _templates.

If you want to change this behavior, create a file named .hygen.js at the root level of your project, like this:

const path = require('path')

module.exports = {
  templates: path.join(__dirname, 'generators'),
}

Creating a generator

A generator is composed of one or more actions, every action contains two items:

Templates: *.ejs 🧩
Prompts: prompt.js ⁉️

Let's build a simple generator that creates a React component 🤓. At the end of the post, you'll find a GitHub repository with a lot of different examples 👏

The first thing we need to create is the generator folder that will contain the action:

Generator: component
Action: react

$ mkdir -p generators/component/react

Templates

Template files define the code that will be created after running the generator, these files are written using a template language called Embedded JavaScript templates.

Every template starts with a frontmatter header. On this header, you will define the metadata of the template using the following properties 🔍

Property	Type	Usage
to	String	The destination of the file once compiled.
from	String	Use an external file as template.
force	Boolean	Overwrite existing files
unless_exists	Boolean	Execute the generator unless file already exists.
inject	Boolean	Inject the contents into an existing file instead of creating a new one.
after	Regex	Inject the template after the regex
before	Regex	Inject the template before the regex
prepend	Boolean	Inject the template at the start of the file
append	Boolean	Inject the template at the end of the file
at_line	Regex	Inject the template at the specified line number
skip_if	Regex	Skip injection if regex matches.
eof_last	Boolean	Trim the newline from the end of the injection.
sh	String	Trigger a shell command after compiling the template

Now, let's add a template file named index.ejs inside the react action folder we created previously:

$ touch generators/component/react/index.ejs

As I mentioned before, we want to create a React component, so we need to specify the location of the file where the component is going to be created.

We can do that using the to property.

---
to: src/components/<%= h.changeCase.pascalCase(name) %>/index.js
---

As you can see, we're using a variable called name on the header. This value will be provided by the prompts of the generator ⁉️

Then, we need to write the body of the template, where we define the code that will be generated once the template is compiled. I'm reusing the name variable in the body as well to create the name and export of the component ✨

---
to: src/components/<%= h.changeCase.pascalCase(name) %>/index.js
---

const <%= h.changeCase.pascalCase(name) %> = () => (
  <section>
    <h1>Hey! 👋</h1>
    <h2><code><%= h.changeCase.pascalCase(name) %></code></h2>
  </section>
)

export default <%= h.changeCase.pascalCase(name) %>

Prompts

In case you need to ask for user input, optionally you can use a prompt file. This is very useful to customize the output of the generator. Prompts are defined using a library named Enquirer.

Inside of the same react 📁, we will create a prompt.js file to ask for the variable defined as name in the template:

module.exports = [
  {
    type: 'input',
    name: 'name',
    message: 'Write the name of your component'
  }
]

There are a ton of different input types available 🔡, take a look at this link to get the complete list.

Now it's time to finally run our generator 🥳 using the script along with the name and the action:

$ npm run generators component react

You'll be asked for the prompts and finally the magic will happen! 🦄

Demo

Take a look at carloscuesta/codegenerators-demo 🕹 if you want to play and see more complex examples!

Automate all the things!

It's time for you to find out repetitive tasks and patterns to extract them into a generator! 🚀

I'm very happy with the productivity boost and the consistency that a tool like this can bring to a team ❤️

Writing Architecture Decision Records

Carlos Cuesta — Sat, 12 Mar 2022 11:58:05 +0000

An architecture decision record also known as ADR, is a document that captures an important architecture decision, including the context of how the decision was made and the consequences of that change.

What are the benefits?

Sharing context

ADRs capture a decision at the time it's being made. They're the outcome of all of those asynchronous discussions in Slack that'll be lost over time ⏰

When you materialize them into docs, you're allowing your future teammates, to get the context for this specific change. So they'll be able to understand the issues, the decision that was taken and the impact it had on the project.

Writing docs will help you and your future peers in the long run! 🚀

Alignment

Writing decisions leads the team to consensus and ensures that all the assumptions of a change are clear 📏.

This will have a positive impact after the architecture decision has been implemented. Everyone on the team will have a deep understanding which will help on moving forward faster with the new approach.

Writing ADRs

Define a template

When writing them, a common practice is to have a template to write ✍🏼 all the documents in the same way.

You'll find a lot of templates online, but here's the one I use it's very simple but easy to write.

# Title

- Status: <!-- PENDING/APPROVED/DEPRECATED -->
- Date: DD/MM/YYYY
- RFC: <!-- Link to the RFC that ended up into the ADR -->

## Context

<!-- What is the issue that is motivating the decision or change? -->

## Decision

<!-- What is the change we're doing? -->

## Consequences

<!-- What becomes easier or more difficult because of this change? -->

Store them next to the code

I believe that documentation should be next to the code to make it easy to contribute to it. Whenever you add an external tool you're increasing the complexity to contribute and reducing the visibility of the docs 👀.

The solution is simple, check out the ADRs into your project repository and keep things simple and clean ✨

I recommend you to create a folder 📁 where you store all the decision records, for example: docs/adrs/.

Use a naming convention

When saving the files use a naming convention title-of-the-adr-DD-MM-YYYY.md

Conclusion

Write more ADRs 😜, if you're not doing it yet, it's never too late to start!

In my experience as a team grows larger and a codebase becomes more complex, architecture decision records are a great tool to help your current and future team ❤️

Composing UIs with Finite State Machines

Carlos Cuesta — Tue, 04 May 2021 16:13:26 +0000

Finite State Machines, often abbreviated as FSM is a mathematical computation model that could be useful for building user interfaces, especially nowadays that front-end apps are becoming much more complex due to the nature of the problems that they solve. Did you know that 🧑‍🚀 SpaceX used JavaScript for the spaceship flight interface? 🤯.

In this article, I'm going to explain the benefits of composing user interfaces using finite state machines. Let's dive in! 🤿

What is a finite state machine?

A finite state machine is an abstract machine that can be in exactly one of a finite number of states at any given time. The FSM can change from one state to another, this change is called a transition.

A FSM is defined by:

Σ: The input alphabet.
S : A finite, non-empty set of states.
δ : The state-transition function (δ: S x Σ -> S).
s0 : The initial state, an element of S.
F : The set of accepting states.

Now you're probably like wtf 🤯, this sounds scary 😱 and academic, right? Let's try to illustrate this definition with a real world example to understand it better.

Understanding a FSM

The world is full of finite state machines, in fact, you are using them every day, but probably you didn't think of them as such. I'm sure that after reading the post you'll start pointing them in the real world, trust me I'm doing it right now 😂

A traffic light 🚦 is a simple example to understand FSM. For the sake of this consider that our traffic light has 3 colors.

At any point in time, the traffic light will be on one of the following scenarios:

🟢 Green
🟡 Yellow
🔴 Red

Those scenarios are called states and because the set is limited to 3 states we can say that is finite.

The initial state of the machine is 🟢 green and whenever one of the lights is on the output of the other ones is off.

The state will change in response to an input, that in our case is a timer, through a transition. The transition is a mapping that defines the path of our state.

Let's represent the traffic light FSM on a graphic, so we can visualize the state transitions and understand how the machine works. Usually, you'll see the FSM represented like this 📸:

Try to link this example with the mathematical definition we introduced before! Seems easier right? ☺️

Ok 🆒! I explained how a traffic light works, but now what? How can we use this model to compose better UIs? 🤔. Now that we understand how FSM works, we're going to code a JavaScript application to see the advantages and benefits! 👀

Implementing a FSM with JavaScript

The traffic light is a simple example to understand the concept of FSM. However, to showcase all the benefits and the potential of this concept, we're going to build something a little bit more complex. Such as a UI that could potentially fail due to external circumstances.

The application that we're going to build is a UI with a button, whenever the button is pressed we're going to call an external API and we're going to render the response of the API in our app.

Defining the state machine

Before starting to code, as we've seen in our previous example, the first thing we need to do is defining our state machine.

This is actually the first benefit. Why? Because from the first moment you have to define the FSM and this process helps you to plan and contemplate all the possible states of your UI. So basically you won't miss any edge case.

This way of approaching a problem is called 🔝 ⬇️ top-down approach. Instead of trying to solve a specific part of the problem without understanding it fully ⬇️ 🆙 bottom-up, first, you define the whole model of your application.

This would be the statechart of the application we're going to build:

As you can see, we defined all the possible states of the user interface and also the transitions between them.

Idle: The initial state.
Fetching: The state where the UI is fetching the API.
Fulfilled: The state when the API fetch succeeds.
Rejected: The state when the API fetch fails.

Now, we can define for each state, the output and behaviour of our application. This makes our UI deterministic and what this means is that given the current state and an input you'll know what the next state is going to be all the time. When you control every state, you are free of bugs 🐛.

Let's build the wireframes 🎨 to define the output of the application:

Our wireframes, implement all the states that are defined by our FSM. We're ready to move on with coding! 👏.

Implementing the FSM

I'm going to build the FSM using plain JavaScript only. Why? I'll answer this question after the implementation 👀.

The first thing we're going to define is our input alphabet Σ. Based on the statechart we designed before. Inputs are events that will cause a state transition in our FSM. Our Σ will look like this:

const EVENTS = {
  FETCH: 'FETCH',
  RESOLVE: 'RESOLVE',
  REJECT: 'REJECT'
};

Next, we are going to define our set of states S. Also, as we defined, we should set the initial state to Idle as S0.

const STATE = {
  IDLE: 'IDLE',
  FETCHING: 'FETCHING',
  FULFILLED: 'FULFILLED',
  REJECTED: 'REJECTED',
}

const initialState = STATE.IDLE

Finally we're going to combine all those pieces into the FSM. Defining the transitions δ between every state in response to the inputs.

const stateMachine = {
  initial: initialState,
  states: {
    [STATE.IDLE]: { on: { [EVENTS.FETCH]: STATE.FETCHING } },
    [STATE.FETCHING]: {
      on: {
        [EVENTS.RESOLVE]: STATE.FULFILLED,
        [EVENTS.REJECT]: STATE.REJECTED,
      }
    },
    [STATE.FULFILLED]: { on: { [EVENTS.FETCH]: STATE.FETCHING } },
    [STATE.REJECTED]: { on: { [EVENTS.FETCH]: STATE.FETCHING } },
  }
}

The FSM is ready to be used! 🥳.

Why did I implement the FSM using plain JavaScript?

Because I want to show how simple it is to create one. As well as to show that FSM is totally decoupled from any library or framework 💯. They don't know anything about rendering, instead, they define the application state flow. This is one of the best things about composing UIs with FSM 😍.

You can abstract and decouple the whole flow from any framework 🙌. You can use this FSM with any library, such as React, React-Native, Vue, Svelte, Preact, Angular...

Demo time 🕹

To see our FSM in action I built a demo app with React so I can show you how our application works! The example is a dummy app that calls a Pokemon API and renders the result, a common task in front-end development nowadays.

Take a look at the CodeSandbox below 👇 and try to break the UI:

Disable your Internet connection and try to click the button 🔌
Try to click the button multiple times 👈
Simulate a slow network connection 🐌

The first thing I did was to define all the UI for every state in our machine. Using a simple switch statement to do the conditional rendering:

const App = () => {
  switch (state) {
    case STATES.IDLE: return (...)
    case STATES.FETCHING: return (...)
    case STATES.FULFILLED: return (...)
    case STATES.REJECTED: return (...)
    default: return null
  }
}

Once our app knows how to render every state of the machine, we need to define the transitions between the states in response to events (inputs). Remember that our FSM has the following inputs: Fetch, Resolve and Reject.

In this case, I'm using a useStateMachine hook from a library, just to avoid having to implement the not-so-relevant React part of the state handling. This hook receives the state machine we defined before as a configuration argument.

const [pokemon, setPokemon] = React.useState(null);
const [state, send] = useStateMachine()(stateMachine);

The hook exposes the state that is an object which contains the current state of the machine we defined and the send function which is the state transition function (δ: S x Σ -> S). Also, we have a pokemon state variable to save the API response.

So, to transition from a state to another, we will call the send Function passing an Input as an argument.

As you can see we have a onFetchPokemon function to make the API request. As soon as you click the Button, we will send a FETCH input and as a result of this, we will transition the state to Fetching.

If there's an error, we're going to catch it and send a REJECT input to transition the state to Rejected.

If everything works well we will save the response into the pokemon state variable and then send a RESOLVE input to transition the state to Resolved.

const App = () => {
  const onFetchPokemon = async () => {
    try {
      send(EVENTS.FETCH);
      const pokedexRandomNumber = Math.floor(Math.random() * 151) + 1;
      const pokemon = await fetchPokemon(pokedexRandomNumber);

      setPokemon(pokemon);
      send(EVENTS.RESOLVE);
    } catch (ex) {
      send(EVENTS.REJECT);
    }
  };
}

The UI already knows what they need to render on every state, so basically, we've got all the possible cases covered 🎉. We're 100% free of bugs! 💯

Benefits

Let's do a quick summary of the benefits of composing user interfaces with FSM:

Contemplate and plan all the possible states of the application 🧠
Document the application flow, to make it more accessible to non-dev people 📝
Predictable and declarative UIs 📖
Makes code bases easier to maintain 💖
No unexpected bugs 🐛

Libraries

I didn't use any library on purpose to build the FSM, but I would really recommend looking at the following tools If you plan to incorporate them into production:

Xstate
Robot

Functional programming in JavaScript

Carlos Cuesta — Wed, 24 Mar 2021 16:06:16 +0000

Functional programming, often abbreviated as FP has become a 🔥 popular trend over the last years in the JavaScript community, but it was created on the 1950s, long way before JavaScript 😅

As soon as you start searching "functional programming" on the internet, you're going to hit a brick wall of academic terms that are really intimidating 😱 for someone who is learning, don't be scared by those concepts, it's not as hard as it seems.

In this article I'm going to explain in a friendly and simple way, the basics of this paradigm applied to JavaScript. Let's get started 🤓

What is Functional programming?

Functional programming is a programming paradigm, a way of thinking about code, that consists of building software by composing functions. Functions are the center of FP, hence its name.

Does that mean functional is about just programming with the function keyword? Absolutely no! It's how we use those functions what makes our code functional.

The functional paradigm is based on the following principles:

Immutability 🧊: The state of not changing, or being unable to be changed. Immutability makes our code predictable and free of side effects 🐛
Declarative 📖: Declarative programming is code that is focused on describing what the code does, outcome.
Pure functions 🦄: Functions that given the same input always return the same output and have no side effects.
Function composition 🍱: The process of combining two or more functions to produce new functions or perform some operations.

Why Functional programming?

Confidence

One of the best things about the functional paradigm is that it helps you to create predictable code.

How? With immutable values and pure functions. Those principles create software free of side effects, so it's easy to understand and predict what a piece of code will do just by reading it 🍰, without executing the code.

"Code that you don’t understand is code you can’t trust”

This mindset helps you to boost your confidence 🔝 because you won't have to worry about anything else than the piece of code you're focusing on 🎯

Predictable code is easier to maintain and debug. In the long term, this reduces the number of bugs you may ship into production 🐛

Communication

I believe that coding is about communication, the role of code itself is communicating with other humans before instructing the computer. This sounds a little bit philosophical right 🔮?

But think about your own experience as a developer; you probably spent much more time reading and understanding code than actually programming it 🧑‍💻.

Writing declarative code, which is another principle of the functional paradigm will help you to focus on describing what the code does, instead of how it works, so code will be much more understandable for humans.

Functional JavaScript

Immutable

Immutability is what keeps us safe 😊 from side effects and unexpected bugs 🐛. I wrote a post reasoning about Immutability in JavaScript 📝. Take a look at it if you want to understand the whole concept.

Imagine that we have a shoppingCart that has two properties, id and total. Let's say we want to update the total property of our shopping cart, how can we achieve this?

const shoppingCart = { id: '69zd841', total: 0 }

Immutable ✅

Clone the shoppingCart object and update the total property value.

{ ...shoppingCart, total: 15 }

Mutable ❌

Perform a modification through the object property accessor to our original object.

cart.total = 15

Declarative

Declarative programming consists on describing what the code does and making the outcome predictable without explicitly describing how the control flow works.

This definition may sound a bit abstract 🤨. But let's understand this with an example by comparing declarative to imperative code.

We're going to build, a code that given an array of numbers returns the even ones 🔢:

Declarative ✅

Focused on describing what the code does and the outcome of it.

Example

To solve the example using a declarative approach, we create a Function that receives an array of numbers.

As we want to get all the even numbers, we are going to make use of Array.filter function:

const getEvenNumbers = (numbers) => numbers.filter((n) => n % 2 === 0)

getEvenNumbers([2, 5, 8, 10, 15]) // => [2, 8, 10]

Imperative ❌

Focused on how it works.

Example

To solve the example using an imperative approach, we create a function that receives an array of numbers. Inside the function, we initialize an empty array variable called evenNumbers, to store the numbers that met the condition.

After that, we iterate our array using a for loop with an if statement to push the even numbers to the empty array in order to return them at the end of the iteration.

function getEvenNumbers (numbers) {
  let evenNumbers = []
  for (i = 0; i < numbers.length; i++) {
    if (numbers[i] % 2 === 0) evenNumbers.push(numbers[i])
  }
  return evenNumbers
}

getEvenNumbers([2, 5, 8, 10, 15]) // => [2, 8, 10]

Declarative 🆚 Imperative

As you can see in both examples on declarative approach there are no explicit conditionals, loops, side effects, reassignments, or mutations. Instead, it employs well-known trustable patterns like filtering and composition.

With the imperative approach, we are forced to store through assignment each intermediate result of the iteration. Certainly, this increases the complexity of the code, as a result of this, understanding and finding bugs becomes a harder task.

The focus shifts from low-level how to higher level what outcomes.

On both examples, you can certainly trace and predict the outcome of the code just by reading it. However the declarative approach is much more clear and straightforward ✨. Simply because you're abstracting all the iteration and filter logic.

Familiarity has a big influence on your judgments of clearness and readability. Meaning that if you're more used to work with an imperative approach you'll probably find those snippets easier to understand.

But as soon as you get on the same level of familiarity with the declarative approach your mindset will click and you'll start to see the benefits 🥳

Functions over procedures

If you plan to do FP you should be using functions as much as possible, trying to avoid procedures wherever possible. All your functions should take input(s) and return output(s).

Function ✅

const sayHello = (name) => `Hello ${name} 👋`

sayHello('Carlos') // => Hello Carlos 👋

Procedure ❌

const name = 'Carlos'
const message = `Hello ${name} 👋`

console.log(message) // => Hello Carlos 👋

Pure functions

A pure function is a function which:

Given the same input, will always return the same output.
Has no side effects.

Pure functions ✅

This function given the same x and y inputs will always return the same output. Has no side effects.

const add = (x, y) => x + y

add(5, 10) // => 15

Impure functions ❌

This incrementCount function has a side effect, because it's depending on state that it's outside of his own scope.

let count = 0

const incrementCount = () => {
  count = count + 1
}

Another example of built in JavaScript impure functions would be:

// Who knows what will return! 😜
Math.random() // => ?

// Always returns the same output, but writing to the console is a side effect
console.log('Hello! 👋')

Composing functions

Another important concept on the functional paradigm is composing functions and using higher-order functions. In JavaScript, functions are values, this means that we can assign them into variables and pass them to other functions.

Think about the even numbers example we used before 🔢;

As you can see, we can assign a function to the isEven variable, because functions are values:

const isEven = (number) => number % 2 === 0

isEven(10) // => true
isEven(5) // => false

This allows us to compose and build our code by combining smaller functions and pass the isEven function to the Array.filter higher-order function:

const getEvenNumbers = (numbers) => numbers.filter(isEven)

getEvenNumbers([5, 10, 20]) // => [10, 20]

See how we broke up the problem of determining if a number is even with the isEven function and then how we found the even numbers from the array composing the filter function with the utility one.

Composing functions is a great technique to broke up a problem into smaller isolated pieces. In a way that we can reason about those problems separately, which makes our functions:

Reusable
Easier to maintain
Easier to debug

List operations

Working with lists, also known as Arrays, is something that we do daily, let's examine the most common operations and how we can do them with a functional approach.

Map

A mapping 🗺 is a transformation from one value to another. We can apply a transformation to a list using the Array.map function.

For example, imagine that as a result of calling to an API we've got the following JSON:

{
  "data": [
    {
      "description": "An emoji guide for your commit messages.",
      "id": 1,
      "language": "javascript",
      "name":  "gitmoji",
      "stargazers_count": 9500
    }
  ]
}

Let's say that want to render the data on our application, but we don't want to couple to the data schema the API uses, as it could potentially change and we don't need all the data.

How we can solve that? Easy by making a mapping with the Array.map function:

response.data.map((repository) => ({
  description: repository.description,
  name: repository.name,
  stars: repository.stargazers_count
}))

This mapping would transform the JSON to something like this:

[
  {
    description: 'An emoji guide for your commit messages',
    name: 'gitmoji',
    stars: 9500
  }
]

Filter

The filtering 🔎 process consists on including or excluding certain elements from a list based on a certain condition using the Array.filter function.

The process could be inclusive or exclusive. This sometimes causes confusion, because you have to twist your brain when you're applying an excluding filter.

Let's illustrate this operation with our shoppingBasket object.

const shoppingBasket = [
  { name: '🍏', type: 'fruit' },
  { name: '🍌', type: 'fruit' },
  { name: '🥕', type: 'vegetable' },
  { name: '🍔', type: 'meat' },
  { name: '🥔', type: 'vegetable' }
]

We want to perform two operations:

Inclusive: Get every product that is a fruit
Exclusive: Get every product that is not a fruit

Let's understand the difference with a quick example:

Inclusive filter

Let's filter our shoppingBasket to get the fruits

shoppingBasket.filter((item) => item.type === 'fruit')

This returns a new list:

[{ name: '🍏', type: 'fruit' }, { name: '🍌', type: 'fruit' }]

Excluding filter

Now we're going to do the opposite, get everything that is not a fruit.

shoppingBasket.filter((item) => item.type !== 'fruit')

This returns a new list:

[
  { name: '🥕', type: 'vegetable' },
  { name: '🍔', type: 'meat' },
  { name: '🥔', type: 'vegetable' }
]

Reduce

A reduction ♻️ is a transformation from two or more values into a single one. Hence the name of the Array.reduce function 🌝

Suppose that we want to transform our shoppingBasket list to an object, that groups the products by the type property, something like this:

{
  "fruit": [],
  "vegetable": [],
  "meat": []
}

Easy! Let's apply a reduction to the original list that contains N items to transform it to an object:

const shoppingBasket = [
  { name: '🍏', type: 'fruit' },
  { name: '🍌', type: 'fruit' },
  { name: '🥕', type: 'vegetable' },
  { name: '🍔', type: 'meat' },
  { name: '🥔', type: 'vegetable' }
]

shoppingBasket.reduce((accumulator, value) => ({
  ...accumulator,
  [value.type]: [...accumulator[value.type] || []].concat(value)
}), {})

The outcome of this reduction is an Object that looks like this:

{
  fruit: [
    { name: '🍏', type: 'fruit' },
    { name: '🍌', type: 'fruit' }
  ],
  vegetable: [
    { name: '🥕', type: 'vegetable' },
    { name: '🥔', type: 'vegetable' }
  ],
  meat: [{ name: '🍔', type: 'meat' }]
}

Recursion

Recursion is a technique that happens when a function calls itself until it satisfies a base condition. Is a way to avoid imperative looping and reassignments. When used properly, it helps you to solve complex problems in a declarative way.

☢️ Recursion should be used carefully because it relies a lot on memory, so the performance of your application could be affected.

Let's see a silly example to understand what recursion looks like:

const countDownFrom = (number) => {
  if (!number || number === 0) return number
  console.log(number)
  countDownFrom(number - 1)
}

Note that since the function calls itself, you'll need to specify a stop condition.

Learning resources

Do you want to learn more about functional programming in JavaScript? Here's an awesome list 🤩:

FP libraries

Here's a list of functional programming libraries you can check:

Ramda
Lodash

The frontend tooling guide to improve Developer Experience

Carlos Cuesta — Mon, 22 Feb 2021 16:03:20 +0000

Let's talk about how we can use frontend tooling to improve the developer experience in our team and how these tools impact the reliability of shipping value into production safer and faster.

Have you ever been on a situation where your team had to quickly fix a bug on production or struggled to deploy a new feature reliably?

Keep reading then! All those problems usually indicate that you don't have the proper tools. In this article I'll give you the tools your team needs to create a high-velocity development environment for frontend applications.

What is Developer Experience ?

Developer Experience in this context, is everything that happens in between programming and the outcome of the code.

Starting from the first line of code that is written on the editor and ending when the code is shipped and available to our users. Is the literal feeling a developer has when coding.

Think about all those little things that help you to code better without having to put any attention on them.

A few examples and common use cases of DX would be:

An engineer writes code that it's not typed and a tool warns about it.
An application that is hot reloaded every time the code changes.
An automation that deploys your changes into production.

The impact of having a great DX

Having a great DX has a significant influence in your development speed. How? It's simple, as soon as you rely on automated proceses and tools, the people on your team will start to feel more confident.

Trust, empowers developers to be more productive and agile 🧠, forgetting about the fear of change. So you will be able to bring value much more faster to your users.

Automation is the key to build a high-velocity development team.

Think of it as giving superpowers 🦸‍♂️ to people. With the proper tools your team will be able to:

Deliver value to production fast ⚡️
Anticipate and fix bugs 🐛
Optimise the development time of engineers ⌚️
Build consistent and high quality codebases 🥇
Leave fear of change behind 😍

Sounds awesome right? Let's dive into it! 🛠

A tool for every problem

Before starting to analyze what we are going to use, is important to understand that the election of a tool depends totally on the problem that needs to be addressed.

As Abraham Maslow said, on the law of the instrument:

"I suppose it is tempting, if the only tool you have is a hammer, to treat everything as if it were a nail."

The following quote 👆 is highly relevant on the programming context. Many times as software engineers we tend to use the same known tools for any new project, no matter what the constraints and requirements are.

This is a comfort zone bias. We decide to not change or even consider a new tool to avoid risk.

The problem is that we're limiting our knowledge and the ability to discover more efficient instruments, because we can't compare them against anything.

Tools

Let's start exploring the tools that will help us to build an awesome DX on our team. We will start from the ones that require less effort and provide more impact.

I've made up a little graphic to represent the impact every tool is going to have on the DX of your team against the effort it requires to be used.

Linters and formatters

Linters and formatters are essential to maintain a consistent codebase. When it comes to writing code every team member should follow the same style, rules and conventions. Consistency is key in a project.

You don't want to have different code styles depending on who's writing the code. It's better to agree on a style to avoid confusion. Think about onboarding a new team member, it's will be much easier if the coding convention is well defined with clear rules.

What's the difference then between a linter and a formatter?

Most of the time, you can use both of them for the same purpose, which is to find code errors, bugs and automatically format the code based on the given style guide. However there's a subtle difference:

Linters: Find and catch unexpected coding errors.
Formatters: Format and structure the code with the given style.

Recommended tools

This is the list of linters and formatters I use that I would recommend:

ESLint: Pluggable JavaScript linter.
Prettier: An opinionated code formatter. Works with .css files too! 🎉
StandardJS: JavaScript style guide, linter, and formatter

💡 Protip: Run linters and formatters on a pre-commit git hook using Husky + lint-staged to make sure that the code is readable and formated before the code review process 😍

Static typing

JavaScript is a weakly typed programming language. Due to it's nature this can cause unexpected bugs and errors. A static type checker will help your team to write code faster and more confidently.

Since we started to use static type checkers on the team, we began to code and refactor a lot faster while feeling much more safer.

Recommended tools

This is the list of static type checkers I use that I would recommend:

Flow: A static type checker for JavaScript.

💡 Protip: You can also run flow type checks on a pre-commit hook basis, as suggested on linters and formatters.

Performance and accessibility audits

Performance and accessibility are two important values we should be accountable for as Software Engineers. Although this does not have a big impact on DX, the outcome is part of our programming process, so we should measure and improve our a11y and performance constantly.

These are the most relevant values for your users. Keep in mind, that whenever a user enters your site or application, the first thing they will feel is the overall performance of the site, how fast it loads, how fast is to navigate through, the way it works and integrates with screen readers etc.

So for me, makes a lot of sense using a tool to audit and monitor performance and a11y to ensure they met the standard requirements.

Recommended tools

This is the list of tools I use for auditing performance and accessibility I would recommend:

Lighthouse-CI: Automate running Lighthouse for every commit, viewing the changes, and preventing regressions.

💡 Protip: It's a great idea to include this audit as a step of your Pull-Request checks. We will introduce this concept on the next section.

Unit testing

The aim for unit tests is to ensure that individual and isolated pieces of your codebase work properly. Also they act as a layer of protection against the passage of time. As long as the test exists the behaviour of those units will be guaranteed.

So then it's impossible break those individual pieces by accident on a refactor or when introducing some changes.

Unit tests should be fast to run. Some examples and use cases where I use unit tests:

Components: Ensure that isolated components are working as expected on their own.
Utility functions: We usually build a lot of helpers and wrappers to create abstractions in our projects. To ensure they work as expected with all the uses cases, you should be unit testing them.
Sagas: Audit the steps and behaviour of your asynchronous flows in your application.

Recommended tools

This is the list of tools I use for unit testing I would recommend:

Jest: A delightful JavaScript Testing Framework with a focus on simplicity.
Jest-Extended: Additional Jest matchers

Integration testing

Integration testing is about checking the behaviour of unit pieces grouped together. In my opinion, this is where most of your focus should be when writing tests.

Why? Considering the time and effort it takes to write tests compared to the level of confidence they give back to you, integration tests are merely the best.

Unit tests are great but they give you low confidence results, think about the umbrella example 🌂

Some examples and use cases where I use integration tests:

User interactions: Simulate user interactions through events as if you were a user. For example, on an e-commerce site add a product to the cart and assert that an API request has been made and the product items count has been increased.
Forms: Fill forms in different ways, simulate a form submit and validate the data, make the form fail and assert the errors.
Navigation: When the user clicks on something, are we navigating to the expected screen?

Recommended tools

This is the list of tools I use for integration testing I would recommend:

Jest: A delightful JavaScript Testing Framework with a focus on simplicity.
Testing-Library: Simple and complete testing utilities that encourage good testing practices.
React-Test-Renderer

End to end testing

When it comes the time to guarantee the behaviour of key user flows on a product, for example on an E-commerce would be; an add to cart or a checkout process. E2E testing is crucial. Because you're testing on a real browser and a real device against external APIs, as if you were an genuine user.

Finally! With E2E your team would be able to sleep properly 😴, with the safety that nothing is going to brake suddenly due to a weird bug or something that hasn't been tested properly 🎉.

Be aware that since those type of tests run on real devices, you should only test the most important things for what you're building, specifically user flows and paths. Building an E2E could be a little bit time consuming at first, but the effort pays off. Luckily at the moment there are a lot of tools that makes this process a lot easier!

Recommended tools

This is the list of tools I use for E2E I would recommend:

Cypress: Fast, easy and reliable testing for anything that runs in a browser.
Detox: Gray box end-to-end testing and automation framework for mobile apps.

Integrating tools on the development workflow

Now that we understand what is each tool for, I'm sure you asked yourself; How I'm going to integrate those tools on my team development workflow?

Automate all the things with a continuous integration and a continuous delivery pipeline.

As we've seen previously, we can simply run some tools automatically using git hooks and that's totally fine, but this approach has a few problems:

Certain tools can't run on a git hook, because they could be really slow.
Something that runs on a local machine could be skipped.

Pipelines

A pipeline is a way to unify all your tools into a process that does not relies on any local machine and not depends on human interaction.

This process runs on every Pull-Request and your main branch, in order to ensure any change that wants to be deployed into production, meets the quality standards and works as expected.

Based on the tools we've seen here's a representation of how our pipeline would be:

Note that tools that run and fail faster are the first ones that run on our pipeline.

💡 Proptip: When building a web project, I use something called deployment previews. This is probably one of my favorite features of the whole pipeline. You can get a standalone deployment with a unique URL for each PR.

This allows you to test your changes on a safe and isolated environment. Previews speed up code reviews and help you to validate implementations and features. There are a couple of platforms that provide this feature such as Netlify and Vercel. If you're not using them you can try to build something on your own!

Here's a list of platforms you can use to build your pipelines:

Demo time

Right now I'm using GitHub Actions to build my pipelines 😍. If you want to see an implementation like the one we described, you can take a look at my website pipeline. Find the implementation on the following link.

You can see that whenever I open a Pull-Request, there's a list of checks that need to be ✅ before being able to merge the changes to master:

The checks ensure that the quality standards are passed and everything works perfect 🚀.

Wrapping up

This article is a brain dump of the concepts and knowledge I use daily on personal and professional projects, to ship software.

I know it's a lot of information to understand but I can ensure you that if you implement a similar workflow and you put attention into Developer Experience it will make a huge difference on your team.

Immutability in JavaScript

Carlos Cuesta — Tue, 26 Jan 2021 16:28:52 +0000

Have you ever heard something about immutability? I'm mostly sure the answer is yes!, particularly on the programming ecosystem. Despite being a popular term, there are some misconceptions about the importance and principles of it. Let's dive in into it!

What does it mean?

Immutability is the state of not changing, or being unable to be changed.

On a programming context, means that when we need to change the state in our program, we must create and track a new value rather than mutating the existing one.

🚨 This does not mean we can't have values that change over the lifecycle of our program. That's a common misconception about immutability 🖐

Immutable 🆚 Mutable

To understand the difference between both, take a look at the following example. Imagine that we have a shopping cart 🛒 object, that contains two properties, id and total.

const shoppingCart = { id: '69zd841', total: 0 }

Let's say that we want to update the total property of our shoppingCart, how can we achieve this?

Clone and update

Using the spread operator we can create a new object cloning the previous cart and updating the total property, while preserving our original object in a pristine condition.

{ ...shoppingCart, total: 15 }

Mutate

Through the object property accessor we can perform a modification to our original object.

cart.total = 15

The difference between those two examples is that on the first one we preserved our original shopping cart and we created a new one and on the second one we overwrited the value of the total property.

The benefits

Now that we understood the concept of immutability and the difference between mutable 🆚 immutable data, let's see the benefits of applying it.

Immutability is like a seatbelt, it won't prevent an accident but it saves your life when it does

Predictability

Predictable code is code where you can anticipate the outcome with a single read. Mutation hides change, as we've seen before, the source is lost. Hidden change creates unexpected side effects that can cause complex bugs 🐛.

When we can predict the outcome, we start to feel more confident with our code simplifying our thought process. This helps us reason easier about our program.

Tracking mutations

When you mutate data, you're overwriting the same reference every time that you update something as we've pointed on the first example. Then it's impossible to have a track of the changes you've done to the program state.

Immutable data gives you a clear history of state to the program, because you're creating a new reference based on the source.

The drawbacks

Whenever we start creating new values such as Array, Object etc, instead of mutating existing ones the next question always is is: What kind of impact has this for performance?.

Performance

Avoiding mutations has a cost that's correct, every time we have to reallocate a new value, that's consuming CPU time and memory, including the garbage collection process for values that are no longer referenced.

Is that an acceptable trade-off? It depends. We need some context to answer that question, for example:

If you have a single state change, that happens a few times on the lifecycle of your program, creating a new object, is certainly not a problem. It won't have no practical impact on the performance of the app. Compared to the time you will save not having to track and fix bugs caused by side effects, the winner clearly is immutability 🎉

Again, if that state change is going to occur frequently, or it happens in a critical path of your app, then performance is a totally valid concern 👍

Thankfully, there are some libraries out there that will provide performance optimizations such as Immutable.js and seamless-immutable.

Immutable data in JS

Constants

A constant is a variable that cannot be reassigned and redeclared. This is an important concept to understand, because it does not mean the value it holds is immutable.

The use of const tells the human being who's reading your code that the following variable won't be reassigned or redeclared. It's a great improvement in code readability because we're intentionally communicating that.

const fruits = ['🍌','🍓', '🥥']

// We can't reassign the constant
// ❌ TypeError: Assignment to constant variable.
fruits = ['🍏']

// We can't redeclare the constant
// ❌ SyntaxError: Identifier 'fruits' has already been declared
const fruits = ['🥝']

// ✅ We can mutate the value as we want
// fruits -> ['🍌','🍓', '🥥', '🍍']
fruits.push('🍍')

Spread syntax

Also known as ..., it's a useful operator for cloning iterables such as Array or Object.

const fruits = ['🍌','🍓', '🥥']
const shoppingCart = { id: '69zd841', total: 0 }

// Add a some fruits to the end of the array
const fruitsCollection = [...fruits, '🍍', '🥝']

// Update the shoppingCart total and clone all the other properties
const shoppingCartWithTotal = {...shoppingCart, total: 15 }

Object.freeze

The Object.freeze function is a simple way to turn a mutable Object or Array into an "immutable value". This function freezes the object 🥶 you pass as argument.

But what does frozen object means? A frozen object is an Object whose properties/indices has been marked as read-only and non-reconfigurable, so they can't be reassigned and the Object itself is marked as non-extensible, so no new properties can be added.

The freezing process ❄️ is only made at the top level of the object. If you want to make your whole object immutable, make sure you deep freeze each sub Object or Array 🤓.

const fruits = Object.freeze(['🍌','🍓', '🥥'])
const shoppingCart = Object.freeze({ id: '69zd841', total: 0, products: [] })

// We can't extend the fruits Array
// ❌ TypeError: Cannot add property N, object is not extensible
fruits.push('🍏')

// ❌ We can't mutate shoppingCart top-level properties
// shoppingCart -> { id: '69zd841', total: 0, products: [] }
shoppingCart.total = 123

// 🚨 We can mutate shoppingCart objects
// shoppingCart -> { id: '69zd841', total: 0, products: [{ name: 'Beer' }] }
shoppingCart.products.push({ name: 'Beer' })

Working remotely as a Software Engineer

Carlos Cuesta — Fri, 21 Aug 2020 13:45:42 +0000

Since March due to the COVID-19 🦠, the company I work for, decided to ditch the office and go full remote 🌍.
Within a day everyone moved his workspace from the office to elsewhere 🏠. Actually we do not own a physical space and there's no intention to have it anymore.

I'm going to give you some tips based on my remote working experience as a Software Engineer on a team that is on the same timezone ⏰.

Communication

The communication environment at the office is usually synchronous and face to face 🗣. It's really easy to reach anyone, you just need to approach to his table, and that's all right ?

However working remote means you can work anywhere you want in the world. So you don't have the possibility to reach your colleague table and talk with them.

This leads to the most essential part of remote work the asynchronous isolated communication 💬. From this point you should understand that you'll be communicating through a screen. This introduces a layer of complexity to the communication process.

Why? You might ask, we can use video conference software! Yes but, it's not the same for the reason that we are not used to it, because humans by nature are social animals and we are made to interact physically.

Keep in mind that a video conference is a synchronous process, so you won't be able to use it anytime, it will depend on the momentum of the coworker you want to contact. Luckily text communication comes to the rescue! ⛑️

Assume positive intent and be kind

Always begin with a position of positivity 😊, the communication will flow a lot easier as a result of how our brain 🧠 processes positive intent ❤️

Before sending a message read it a couple of times and think about this: Would I say this exactly word by word to the person's face ? — If the answer is no, don't send the message ✋

When you are on a situation where you are not understanding a colleague, jump on a video call. You will find that a long discussion could be closed on a 10 minutes talk.

Use public channels

When using your company's internal communication tool always try to communicate on public channels avoid group chats or direct messages as possible. For the simple reason that private communication discourages collaboration.

I'm pretty sure that anyone on your team could benefit from reading certain discussions to stay informed on whatever you are working on. This will help to embrace team work and collaboration 💪

If you feel that the topic/resolution is important, you should document it somewhere else outside the communication tool. Otherwise you'll be losing essential information that could be shared and will be lost on the history of the chat.

Connect with the team frequently

Do video calls with your team mates frequently to make them feel connected. Working with nobody next to you could be tough and depressing sometimes. I found that proposing a 10 minutes daily meeting from the beginning of our remote situation helped people to feel better.

Add a social aspect to those meetings, talk about trivial things, sports, news, personal stuff... You'll maintain and improve the relationship with your colleagues 🙏

Organization

As a distributed team it's essential that everyone on the squad knows the company roadmap. As a Software Engineer being aware of the objectives will provide us a comfortable habitat to work on. Because we won't like to feel as machines 🤖 who write code without any clear purpose 👎

Personally, I feel much more motivated with the product and problems If I understand the background of what I'm working on.

Knowing what person is working on is really valuable for the team. It will help to avoid blocks between engineers and provide them a clear picture of the status of any task.

Use a software development methodology

Choose a system to distribute the workload on the team. Try the different frameworks that exist out there and pick the one who works best for your team. We use Kanban flow and we're pretty happy with it.

With a methodology like Kanban you'll reduce the overhead of organizing tasks remotely and you'll make visible the work that every member is doing on a daily basis to the rest of the team 👀

Manage your working hours properly

The first two months of going remote I made a ton of overtime hours. We had a critical situation at the company and we had to make an effort. I spent a big time on my home office / bedroom coding. Since our whole country was on lockdown 🔒 due to pandemic, I had nothing else to do 👨‍💻

You should be very careful with your working hours on remote, because our body needs rest time 😴 sport 🏊‍♂️ and entertainment 🎮. A situation like this could end up with a burn-out 🔥, make sure you protect your time 💖

Adjust your schedule flexibly to your daily routine, that's one of the best perks of working remote!. You can code whenever you feel most focused, need a break? Go for a walk and grab a cup of tea 🍵

Documentation

Writing documentation is an essential process on a remote based company. Have you ever hired someone remotely? What an onboarding should be to a new engineer?. How our business model works?. All those questions and more should be documented on a knowledge base.

This is something really important because you won't be at the office anymore so it's not that easier to communicate with people, specially with someone you don't know.

You will repeat and explain the same information to every new employee, so you have a great opportunity to write it down ✍️ saving you some time on the future.

There are multiples documentation tools you can use, I'll list some of them as an example: Confluence, Notion, Dropbox Paper, Google Docs etc.

Workspace

Setup a comfortable and ergonomic workspace. Design your space as the home office you would be proud to have. You'll spend a lot of hours everyday inside them. Create your space, here's a list of things to consider when designing your setup:

Lighting ☀️: Pick up a place with good lighting, a space that have a great amount of sunlight if possible.
Office furniture 🪑: Get a good & ergonomic chair and desk your body will thank you later.
Ventilation 💨: Ensure that you have a decent airflow.

More resources and tips

Here's a list of useful links about remote work companies! Hope you find them interesting 👇

JavaScript monorepos with Lerna and Yarn Workspaces

Carlos Cuesta — Tue, 01 Oct 2019 20:16:20 +0000

Originally posted at carloscuesta's blog

What is a monorepo ?

The monorepo term is a compound word between "mono", from Ancient Greek "mónos", that means "single" and "repo" as a shorthand of "repository".

A monorepo is a strategy for storing code and projects in a single repository.

What are they useful for ?

♻️ Reusing isolated pieces of code

Monorepos allow you to reuse packages and code from another modules while keeping them independent and isolated. This is particularly useful when you have a ton of code that you're constantly repeating on different projects.

🧰 Simplifying dependencies management

Dependencies are hoisted to the root level of the project, that means you can share dependencies across all the packages that you have in your monorepo. This reduces the overhead from updating and managing multiple versions of the same dependency.

🛠 Refactoring cross-project changes

Making cross-repo changes within different repositories is painful. Typically involves manual coordination between teams and repos. For example let's say you have an API that is used by many clients and you want to make a breaking change into the contract. It's not trivial to apply the update to all the clients and then coordinate the deploy of the projects and so on. With a monorepo it's easier since everything is contained in a single unit.

Before considering to implement a monorepo architecture, make sure you have the problems that this concept solves ⚠️. There's no need to overengineer a project. Remember keep it simple ✨

The tools

🐉 Lerna: The tool for managing the monorepo packages.
📦 Yarn Workspaces: Multiple packages architecture.

Now that we know what is a monorepo, the tools that we're going to use and what are they useful for, let's create a real example to see how it works.

Creating the monorepo

Setup

Let's begin creating our monorepo 👏. The first thing we need to do is define the structure of the project. In this example I created two directories:

📁 packages/: This directory will contain the isolated modules that we are going to reuse on all the applications.
📁 applications/: This directory will contain all the applications of our monorepo.

.
└── src
    ├── applications
    └── packages

After that, we're going to create package.json to define the workspaces and dependencies of our monorepo.

The workspaces field is what Yarn uses to symlink our code to the node_modules in order to reuse and import the code, we'll see this later on.

Finally we install lerna as a devDependency to manage the monorepo.

{
  "private": true,
  "engines": {
    "yarn": ">=1.17.3"
  },
  "name": "monorepo-example",
  "workspaces": [
    "src/applications/*",
    "src/packages/*"
  ],
  "scripts": {},
  "devDependencies": {
    "lerna": "latest"
  }
}

Now, let's define how Lerna is going to manage our monorepo in a lerna.json configuration file.

packages: The directories that we defined as workspaces in the package.json.
npmClient: The client used to run the commands.
useWorkspaces: This flag tells lerna that we're going to use yarn workspaces.

{
  "lerna": "latest",
  "packages": [
    "src/applications/*",
    "src/packages/*"
  ],
  "version": "1.0.0",
  "npmClient": "yarn",
  "useWorkspaces": true
}

We finished our setup 🙌! Let's add some simple code to see how we can manage and reuse packages on our monorepo.

Creating packages

A package inside our monorepo context, is an isolated and reusable piece of code. That means, every time we want to create a new package, we're going to create a new independent directory.

.
└── packages
    └── sayHello
        ├── index.js
        └── package.json

Each package needs to have a package.json with the name and version fields defined. This is important because this describes how we're going to import and use this package on the code base. You can also have dependencies in your package if you need them. On this example I'm writing a simple package called sayHello.

{
  "name": "@packages/sayHello",
  "version": "1.0.0",
}

Think of every directory inside the packages/ folder as an isolated module, with his own tests, dependencies and code.

const sayHello = (name) => {
  console.log(`Hello ${name} 👋🏼`)

  return name
}

module.exports = sayHello

Using packages

This was pretty simple right? Now let's say that we have an application that it's called cli. In order to use sayHello package we should add it as a dependency on the package.json file. To do that we have a fancy yarn command 🎉

$ yarn workspace @applications/cli add @packages/sayHello@1.0.0

Now from our cli application we can import and use the package! 💯

const sayHello = require('@packages/sayHello')

sayHello('Carlos')

Finally, we run our cli application from the command line using Lerna 🚀

You can find the example explained on the post on this GitHub repository 👀. I know this was pretty simple, but there are a ton of things you can do with monorepos! For example you can share react components in different applications while keeping them isolated. But take a look below 👇 to see monorepos on big open source projects!

Opensource monorepo projects

Here's a list of well known open source projects that are using the monorepo architecture:

Managing React-Native crashes with Error Boundaries

Carlos Cuesta — Thu, 12 Sep 2019 15:04:53 +0000

Originally posted at carloscuesta's blog

React 16 released a new concept called Error Boundary. This concept introduces a new way to catch JavaScript errors 🐛 in a React project.

In this post I'm going to explain why it's important and how you can use error boundaries in a React-Native application to improve error resiliency, so let's get into it! 👨‍💻

Why you should use them ?

According to the official React docs 📘:

As of React 16, errors that were not caught by any error boundary will result in unmounting of the whole React component tree 😱.

Unmounting the whole React component tree, means that if you don't catch errors at all the user will see an empty white screen 💥. Most of the time without having any feedback. This is not a great UX ❌, fortunately you can fix this by using Error Boundaries ✅.

How to use Error Boundaries

To benefit from Error Boundaries, we'll have to create a stateful component that will use the following lifecycle methods ♻️:

getDerivedStateFromError: This method is going to update the component state to display a fallback UI.
componentDidCatch: This method should be used to log the error to an external service.

So let's create the component that will catch errors in our application:

class ErrorBoundary extends React.Component {
  state = { hasError: false }

  static getDerivedStateFromError (error) {
    return { hasError: true }
  }

  componentDidCatch (error, info) {
    logErrorToService(error, info.componentStack)
  }

  render () {
    return this.state.hasError
      ? <FallbackComponent />
      : this.props.children
  }
}

Pretty simple right? With a few lines of code, you can catch errors on your React-Native app 🎉

To use it, all you need to do now is to wrap it around any component that could throw an error.

const App = () => (
  <ErrorBoundary>
    <Children />
  </ErrorBoundary>
)

This component will catch all the errors that are thrown by any of his children. A common thing is to use it at the top level of your application 🔝 to catch anything without having to use it on every screen or route 👏

That's how our FallbackComponent looks whenever an error is thrown by our application 😍

⚠️ Error Boundaries only catch JavaScript errors, all the native crashes that your application might have are not handled.

Introducing `react-native-error-boundary`

Few months ago, I created a simple, flexible and reusable React-Native error boundary component. Take a look into it 👀 if you're thinking about adding error boundaries to your app!

Scalable React Components architecture

Carlos Cuesta — Tue, 16 Oct 2018 15:30:21 +0000

Originally posted at carloscuesta's blog

It's been a while since I've started working with React and React-Native in production. One of the greatest things about React is the flexibility the library gives to you. Meaning that you are free to decide how do you want to implement almost every detail of your project for example the architecture and structure.

However this freedom on the long term, could lead to a complex and messy codebase, specially if you don't follow a pattern. In this post I'll explain a simple way to organize and structure React Components.

A Component is a JavaScript function or class that returns a piece of UI.

We're going to create an EmojiList component and then we are going to refactor it breaking it up into smaller isolated pieces applying the folder pattern. Here's how our component looks like:

EmojiList

As I mentioned before, we can start really simple and small, without following any pattern. This is our EmojiList component contained in a single function.

Open Demo on CodeSandbox

If you open the CodeSandbox sidebar you'll see that our file tree looks like this:

.
├── components
│   ├── EmojiList.js
│   └── styles.js
└── index.js

There's nothing wrong with this approach. But on larger codebases that kind of component becomes hard to maintain, because there a lot of things in it: state, ui, data... Take a look at our component code below 👇

EmojiList.js

import React from "react"

import styles from "./styles"

class EmojiList extends React.Component {
  state = {
    searchInput: "",
    emojis: []
  }

  render() {
    const emojis = this.state.emojis.filter(emoji =>
      emoji.code.includes(this.state.searchInput.toLowerCase())
    )

    return (
      <ul style={styles.list}>
        <input
          style={styles.searchInput}
          placeholder="Search by name"
          type="text"
          value={this.state.searchInput}
          onChange={event => this.setState({ searchInput: event.target.value })}
        />
        {emojis.map((emoji, index) => (
          <li key={index} style={styles.item}>
            <div style={styles.icon}>{emoji.emoji}</div>
            <div style={styles.content}>
              <code style={styles.code}>{emoji.code}</code>
              <p style={styles.description}>{emoji.description}</p>
            </div>
          </li>
        ))}
      </ul>
    )
  }
}

export default EmojiList

A step to improve this code, would be to create separate components into the same file and then using them at the main component. However, you'll be sharing styles among other things and that could be confusing.

Refactor

Let's start refactoring the single component into multiple ones by breaking up the UI into a component hierarchy.

If we take a look at the image, it's easy to identify that we can break up our UI in three different components: 🛠

EmojiList: Combines the smaller components and shares the state down.
- SearchInput: Receives user input and displays the search bar.
- EmojiListItem: Displays the List Item for each emoji, with the icon, name and description.

We're going to create a folder for each component, with two files, an index.js that is going to hold all the code for the component and the styles.js. That's one of the good things about this pattern. Every component defines his own UI and styles, isolating this piece of code from another components that doesn't need to know anything about them.

Open Demo on CodeSandbox

Notice that inside the EmojiList folder, (that is a component), we add two nested components that only will be used within the EmojiList component. Again, that's because these two components aren't going to be used out of that context. This helps reducing the visual clutter a lot.

.
├── EmojiList
│   ├── EmojiListItem
│   │   ├── index.js
│   │   └── styles.js
│   ├── SearchInput
│   │   ├── index.js
│   │   └── styles.js
│   ├── index.js
│   └── styles.js
└── index.js

Now let's isolate and separate the code into the three components from the smallest to the biggest one:

EmojiListItem/

This component renders every emoji item that will appear on the list.

import React from "react"

import styles from "./styles"

const EmojiListItem = (props) => (
  <li style={styles.item}>
    <div style={styles.icon}>{props.emoji}</div>
    <div style={styles.content}>
      <code style={styles.code}>{props.code}</code>
      <p style={styles.description}>{props.description}</p>
    </div>
  </li>
)

export default EmojiListItem

SearchInput/

This component receives the user input and updates the state of the parent component.

import React from "react"

import styles from "./styles"

const SearchInput = (props) => (
  <input
    style={styles.searchInput}
    placeholder="Search by name"
    type="text"
    value={props.value}
    onChange={props.onChange}
  />
)

export default SearchInput

EmojiList/

This is the top level component, holds the state and data of our example and imports the other components to recreate the whole UI of our tiny application. Isolating components makes the render method more readable and easier to understand ✨.

import React from "react"

import SearchInput from "./SearchInput"
import EmojiListItem from "./EmojiListItem"
import styles from "./styles"

class EmojiList extends React.Component {
  state = {
    searchInput: "",
    emojis: []
  }

  render() {
    const emojis = this.state.emojis.filter(emoji =>
      emoji.code.includes(this.state.searchInput.toLowerCase())
    )

    return (
      <ul style={styles.list}>
        <SearchInput
          onChange={(event) => this.setState({ searchInput: event.target.value })}
          value={this.state.searchInput}
        />
        {emojis.map((emoji, index) => (
          <EmojiListItem
            key={index}
            code={emoji.code}
            description={emoji.description}
            emoji={emoji.emoji}
          />
        ))}
      </ul>
    )
  }
}

export default EmojiList

That's basically the architecture that I use at the company I'm working on. I'm pretty satisfied with the experience of using this pattern. Our components turned out a lot easier to maintain and use. Anyway there are no silver bullets on Software Engineering, so figure what works best for you or your team!

DEV Community: Carlos Cuesta

Writing RFCs

What are the benefits?

Planning

Alignment

Documentation

Better decision-making

When you should write an RFC?

How to write an RFC

Define a template

Share document for review

Address feedback

Make a decision

Examples

Conclusion

Effective Refactoring with Codemods

What is a codemod?

How do they work?

Abstract Syntax Trees

Refactoring with codemods

Understanding the transformation

Input

Output

Writing the Codemod

Generating the AST

Traversing the AST

Transforming the nodes

1. Find get helper usages

2. Replace get with optional chaining and default value

3. Find lodash/get import statements

4. Prune import statements

5. Convert AST back to source code

Putting it all together

Testing codemods

Conclusion

Using generators to improve developer productivity

What is a code generator?

What's the problem?

Why you should use them?

Developer experience

Decision fatigue

Using code generators

Choosing the right tool

Getting started

Creating a generator

Templates

Prompts

Demo

Automate all the things!

Writing Architecture Decision Records

What are the benefits?

Sharing context

Alignment

Writing ADRs

Define a template

Store them next to the code

Use a naming convention

Conclusion

Composing UIs with Finite State Machines

What is a finite state machine?

Understanding a FSM

Implementing a FSM with JavaScript

Defining the state machine

Implementing the FSM

Demo time 🕹

Benefits

Libraries

Functional programming in JavaScript

What is Functional programming?

Why Functional programming?

Confidence

Communication

Functional JavaScript

Immutable

Immutable ✅

Mutable ❌

Declarative

Declarative ✅

Imperative ❌

Declarative 🆚 Imperative

1. Find `get` helper usages

2. Replace `get` with optional chaining and default value