DEV Community: Renato Rodrigues

Creating your own Remote Cache Server for Nx and Lerna with Cacheiro

Renato Rodrigues — Sun, 14 Jun 2026 01:40:35 +0000

🌐 Este artigo também está disponível em Português.

If you work with monorepos using Nx or Lerna, you already know that remote caching is practically a superpower. The ability to run a build, test, or lint in your CI pipeline (or on a colleague's machine) and share that result instantly with the rest of the team saves precious hours of pipeline and processing time.

To get this benefit, the default and official solution is Nx Cloud. It is a fantastic service, but it can weigh on the budget of smaller teams or run into strict data security policies at companies that require strict self-hosted solutions.

If you have tried to bypass Nx Cloud costs recently, you most likely faced a chaotic scenario.

The Rollercoaster of Self-Hosted Caching in Nx

The history of hosting your own cache in Nx feels like a soap opera. In the beginning, the community relied on third-party tools. Then, Nx (formerly NRWL) removed free open-source support, centralizing everything into their paid tier. Later, they backtracked and released official, free packages for self-hosting (featuring plugins for File System, AWS S3, Google Cloud Storage, and Azure).

And then came the recent cold shower: Nx abruptly deprecated all official self-hosted cache packages due to security concerns (you can check the details in the official Nx deprecation documentation).

The remote caching capability still natively exists within the Nx core, but the community was left stranded without official, secure tools to bridge the connection to storage providers. To deeply understand this rollercoaster, Emily Xiong's Medium article does an incredible job of detailing this history of caching solutions.

And it was precisely while dealing with this situation, as I was studying ways to optimize my CI, that I decided to build a solution to fill this gap.

Author's note: Despite the shifts in strategy, a huge shout-out goes to the Nx team for keeping the architecture open enough to allow the community to build alternative solutions.

Introducing Cacheiro

The Cacheiro project was born to give the community back the freedom to host their own remote cache securely, modernly, and completely for free.

And before you ask: yes, the name is a play on words! It merges Cache with the Portuguese suffix -eiro (used to describe a profession, like a craftsman). "Cacheiro" is the one who takes care of your cache.

Unlike other opinionated and rigid alternatives, Cacheiro was designed as a modular library, published in individual packages. You pick and plug only what you actually need. It is:

100% Free and Open Source.
Highly extensible: you can easily customize the logic according to your infrastructure needs.
100% Complete Ecosystem: It ships with production-ready plugins for File System (FS), Amazon S3, Azure Blob Storage, and Google Cloud Storage (GCS), covering with full parity the gap left by the deprecated packages.

🔒 Security First: Since the deprecation of the official Nx plugins happened due to security reasons, Cacheiro was built with double the attention to this aspect. The project strictly utilizes the latest versions of its underlying libraries (free of known vulnerabilities), underwent code auditing to mitigate common loopholes, and implements a robust encryption layer resilient against injection or artifact leaks.

How to test it in less than 2 minutes (Practical Example)

Even though Cacheiro is a library meant for building your custom server, the main repository already comes with a fully working example ready to run locally at 127.0.0.1:3000.

If you want to see the magic happen right now on your machine using the File System (FS) plugin, just follow these quick steps:

1. Spin up the example server

Clone the repository, install the dependencies at the root, configure the local runner environment, and start the development server:

git clone https://github.com/rerodrigues/nx-remote-cache-server.git
cd nx-remote-cache-server
npm install

# Navigate to the runner package and set up the environment
cd packages/cacheiro-runner
cp config/local.jsonc.example config/local.jsonc

# Start the server
npm run dev

That's it! Your remote cache server is up and running at http://127.0.0.1:3000.

2. Connect your Nx or Lerna project

Nx can identify and consume a remote cache directly via native environment variables.

For a production or daily development setup, the ideal approach is to save these variables in your terminal configuration file (like .bashrc or .zshrc) or inject them directly into your CI secrets / environment variables (GitHub Actions, GitLab CI, etc.).

For our local example, configure it using the default token (change-me):

export NX_REMOTE_CACHE_URL="http://127.0.0.1:3000"
export NX_REMOTE_CACHE_TOKEN="change-me"

With these variables defined in your monorepo's terminal, just run your project's standard commands:

# **If you are using Nx:**
npx nx run-many -t build

# **If you are using Lerna:**
npx lerna run build

Run the command once to generate and upload the cache to your local server. Run it a second time and witness the performance boost with the cache being served remotely by Cacheiro. Simple as that.

If you are dealing with this infrastructure gap today, feel free to check out the project, drop a star, and contribute with feedback or Pull Requests!

👉 Access the GitHub Repository: rerodrigues/nx-remote-cache-server

What's Next?

This is just the starting point. In the upcoming posts of this series, I will share practical, step-by-step guides on how to configure and use the plugins for each storage provider to get Cacheiro up and running in your cloud environment.

How about your team?

How do you handle Nx caching today? Are you using Nx Cloud, did you migrate to another alternative, or were you stuck without knowing what to do after the official packages were deprecated?

Leave a comment below, share your experience, and let's talk about it! See you in the next post!

Criando seu próprio Servidor de Cache Remoto para Nx e Lerna com o Cacheiro

Renato Rodrigues — Sun, 14 Jun 2026 01:32:13 +0000

🌐 This article is also available in English.

Se você trabalha com monorepos usando Nx ou Lerna, sabe que o cache remoto é praticamente um superpoder. A capacidade de rodar um build, teste ou lint no CI (ou na máquina de um colega) e compartilhar esse resultado instantaneamente com o resto do time economiza horas preciosas de pipeline e processamento.

Para ter esse benefício, a solução padrão e oficial é o Nx Cloud. É um serviço fantástico, mas que pode pesar no orçamento de times menores ou esbarrar em políticas estritas de segurança de dados de algumas empresas que exigem soluções self-hosted (auto-hospedadas).

Se você tentou fugir dos custos do Nx Cloud recentemente, provavelmente se deparou com um cenário caótico.

A Montanha-Russa do Cache Self-Hosted no Nx

O histórico de quem tenta hospedar o próprio cache no Nx parece uma novela. No início, a comunidade dependia de ferramentas próprias. Depois, a Nx (antiga NRWL) removeu o suporte gratuito open-source, centralizando tudo no plano pago. Mais tarde, voltaram atrás e lançaram pacotes oficiais e gratuitos para self-hosting (com plugins para File System, AWS S3, Google Cloud Storage e Azure).

E então veio o balde de água fria recente: a Nx descontinuou abruptamente todos os pacotes oficiais de self-hosted cache devido a problemas de segurança (você pode conferir os detalhes na documentação oficial de depreciação do Nx).

A funcionalidade de cache remoto ainda existe nativamente no core do Nx, mas a comunidade ficou órfã de ferramentas oficiais e seguras para fazer a ponte com os storages. Para entender a fundo essa novela, o artigo da Emily Xiong no Medium detalha incrivelmente bem esse histórico das soluções de cache.

E foi exatamente passando por essa situação enquanto estudava maneiras de otimizar meu CI que decidi criar uma solução para cobrir essa lacuna.

Nota de reconhecimento: Apesar das mudanças de diretrizes, fica aqui um agradecimento ao time da Nx por manter a arquitetura aberta o suficiente para permitir que a comunidade desenvolva soluções alternativas.

Apresentando o Cacheiro

O Cacheiro nasceu para devolver à comunidade a liberdade de hospedar seu próprio cache remoto de forma segura, moderna e totalmente gratuita.

E antes que você pergunte: sim, o nome é uma brincadeira! É a junção de Cache com o sufixo -eiro (como em pedreiro ou carpinteiro). O "Cacheiro" é, literalmente, aquele que cuida do seu cache.

Diferente de outras soluções engessadas (opinionated), o Cacheiro foi desenhado como uma biblioteca modular, disponibilizada em pacotes individuais. Você escolhe e acopla apenas o que precisa. Ele é:

100% Livre e Open Source.
Altamente extensível: você pode personalizar a lógica conforme a necessidade da sua infraestrutura.
Ecossistema 100% completo: Já conta com plugins oficiais e prontos para Sistema de Arquivos (FS), Amazon S3, Azure Blob Storage e Google Cloud Storage (GCS), cobrindo com total paridade a lacuna deixada pelos pacotes descontinuados.

🔒 Segurança em Primeiro Lugar: Como a descontinuação dos plugins da Nx aconteceu por motivos de segurança, o Cacheiro foi construído com atenção redobrada nesse aspecto. O projeto utiliza estritamente as versões mais recentes de suas bibliotecas base (sem vulnerabilidades conhecidas), passou por auditoria de código para mitigar brechas comuns e implementa uma camada de criptografia robusta e resiliente contra falhas de injeção ou vazamento de artefatos.

Como testar em menos de 2 minutos (Exemplo Prático)

Embora o Cacheiro seja uma biblioteca para você construir o seu servidor customizado, o repositório principal já vem com um exemplo funcional pronto para rodar localmente no endereço 127.0.0.1:3000.

Se você quer ver a mágica acontecer agora mesmo na sua máquina usando o plugin de File System (FS), basta seguir estes passos rápidos:

1. Suba o servidor de exemplo

Clone o repositório, instale as dependências na raiz, configure o arquivo local do runner e inicie o servidor de desenvolvimento:

git clone https://github.com/rerodrigues/nx-remote-cache-server.git
cd nx-remote-cache-server
npm install

# Navegue até o pacote do runner e configure o ambiente
cd packages/cacheiro-runner
cp config/local.jsonc.example config/local.jsonc

# Inicie o servidor
npm run dev

Pronto! Seu servidor de cache remoto está rodando no endereço http://127.0.0.1:3000.

2. Conecte o seu projeto Nx ou Lerna

O Nx consegue identificar e usar o cache remoto diretamente através de variáveis de ambiente nativas.

Para o ambiente de produção ou desenvolvimento diário, o ideal é salvar essas variáveis no arquivo de configuração do seu terminal (como .bashrc ou .zshrc) ou configurá-las diretamente nos Secrets / Environment Variables do seu CI (GitHub Actions, GitLab CI, etc.).

Para o nosso exemplo local, configure com o token padrão (change-me):

export NX_REMOTE_CACHE_URL="http://127.0.0.1:3000"
export NX_REMOTE_CACHE_TOKEN="change-me"

Com as variáveis definidas no terminal do seu monorepositório, basta rodar os comandos padrão do seu projeto:

# **Se você usa Nx:**
npx nx run-many -t build

# **Se você usa Lerna:**
npx lerna run build

Execute o comando uma vez para gerar e enviar o cache para o servidor local. Rode uma segunda vez e veja o ganho de performance com o cache sendo servido remotamente pelo Cacheiro. Simples assim.

Se você está enfrentando esse desafio hoje, convido você a conhecer o projeto, deixar sua estrela e contribuir com feedbacks ou Pull Requests!

👉 Acesse o repositório no GitHub: rerodrigues/nx-remote-cache-server

O que vem a seguir?

Este é apenas o ponto de partida. Nos próximos posts desta série, trarei tutoriais práticos demonstrando detalhadamente como configurar e usar os plugins de cada storage para colocar o Cacheiro em produção no seu ambiente de nuvem.

E no seu time?

Como vocês lidam com o cache do Nx hoje? Usam o Nx Cloud, migraram para outra alternativa ou estavam travados sem saber o que fazer após a descontinuação dos pacotes oficiais?

Deixe seu comentário abaixo, conte sua experiência e vamos trocar uma ideia! Nos vemos no próximo post!

Typescript scripts in the command line: The Conclusion

Renato Rodrigues — Mon, 24 Feb 2025 23:21:09 +0000

Conclusion and Final thoughts

In the previous articles in this series, we introduced an example Typescript script and implemented it in Deno 2.0 and Node.JS. The idea was to show how to achieve the same results using the two different technologies, enumerate the pros and cons of each implementation, and hopefully help you decide which one suits you better.

Adoption

Node.JS is the industry standard and has been around for over 15 years. Deno, on the other hand, is a more recent technology, especially the version 2.0. Using Deno in a more critical, conservative, or controlled environment could be difficult or even not allowed at all. In those cases, Node.JS could be a more suitable choice.

Deno 2.0 Implementation

Pros

No setup required
Native Typescript support
No transpilation required
Native support for NPM dependencies
Single-file script
No project file, lock file, or node_modules folder

Cons

Not widely available in existing Docker images and containers
Minimal, yet existing, learning curve
May face resistance or opposition to the adoption
May not be approved and allowed in highly controlled corporate environments

Node.JS Implementation

Pros

Familiar to developers and sys-admins, no learning curve
Widely available in the most commonly used images and containers
Approved for use in most environments

Cons

Doesn't run Typescript natively
Transpilation will be needed
Requires a project file, a lock file, and a node_modules
Your script is actually a multi-file project, not a single-file script
Has problems mixing CommonJS and ESM modules

The verdict

The Pros and Cons above can be of great help when choosing which technology to use. While I cannot assert which one is better for your scenario, I can say that in an environment where none of the cons are a concern, I personally would choose Deno 2.0 and advise you to do the same. However, if one of the cons is a no-go for you, it's better to stay safe in the Node.JS ship.

This concludes this series of articles on Typescript scripts on the Command Line. I hope you enjoyed it.

Stay tuned for more content like this.

Typescript scripts in the command line: Using Node.JS

Renato Rodrigues — Thu, 06 Feb 2025 23:06:54 +0000

In the previous article in this series, we saw how to implement an example Typescript script in Deno 2.0 and run it from the command line. In this article, for the sake of comparison, we will see how to achieve the same using Node.JS

Node.JS and Typescript support

Before starting, let's demystify one thing. Node.JS, at the time of writing, DOES NOT support Typescript. You may have seen some headlines recently stating that, but actually, what Node has is something called Typescript type stripping, which, as the name implies, just strips the Typescript portion of the code and interprets the remaining as regular Javascript code, ignoring any TS feature on it.

Type stripping was implemented first as an experimental flag on Node 22 and will be enabled by default on Node 23. It is also currently not complete and lacks support for some Typescript features, like ENUMS and Namespaces.

For these reasons, I like to think that Node.JS, in its current state, more likely tolerates (and ignores) Typescript than actually supports it.

Implementing the Script Using Node.JS

Initializing the project

First of all, we need to create a new folder and then initialize a Node.JS project there. For this, type in a Terminal window

mkdir sayHello
cd sayHello
npm init -y

Installing the external dependencies

To use external dependencies (NPM modules) in Node.JS, we must first install them and then add them to our script.

Install chalk, yosay and inquirer and its types from NPM by typing in the Terminal window

npm install chalk yosay inquirer
npm install --save-dev @types/yosay

Creating the script

Inside the sayHello folder, create a new folder called src, and inside it, a file called sayHello.ts.

mkdir src
touch src/sayHello.ts

Importing the external dependencies

Import the dependencies to the script by opening src/sayHello.ts in your editor and add the following lines

// src/sayHello.ts

import chalk from 'chalk';
import yosay from 'yosay';
import inquirer, { Answers } from 'inquirer';

Implementing the script body

With the dependencies added, it's time to implement the script body. For this, add the following lines to src/sayHello.ts after the import block

// src/sayHello.ts
// import ...

console.log(chalk.blue('\nHello visitor, please enter you details:\n'));

const questions: Answers = [
  {
    type: 'input',
    name: 'name',
    message: "What's your name?",
    required: true,
  },
  {
    type: 'list',
    name: 'salutation',
    message: 'How should I refer to you?',
    choices: ['Mr.', 'Mrs.', 'none'],
  }
];

inquirer.prompt(questions).then((answers) => {
  const { salutation, name } = answers ;

  console.log(`\n${chalk.green('[SUCCESS]:')} information entered was correct`);

  const person: string[] = [ name ];
  if(salutation !== 'none') person.unshift(salutation);

  console.log(yosay(`Hallo ${person.join(' ')}!`));
});

Save the changes, and next, we will run the script.

Running the script from source

OK, now we have the script ready, but how do we run it? That's where things get a bit more complicated. In Node.JS, the short answer is that we cannot run it directly. You need to transpile it before running or use a dedicated tool to do it transparently for us. (again, ignore Node's type stripping feature)

So how do we run it then?

First of all, install the TSX dependency. In the terminal window, do

npm install --save-dev tsx

Then, we have three ways of running the script from source.

Method 1: Using NPX

On the sayHello folder, do

npx tsx src/sayHello.ts

It will use a tool called TSX to transpile and run the TS code transparently

Method 2: Adding an alias to package.json

Open the package.json file in your editor and add this line into the scripts section.

{
    "scripts": {
        "test": "...", // existing script
        "start": "tsx src/sayHello.ts"
    }
}

then, on sayHello folder, just do

npm start

Method 3: Making the script executable (Linux/MacOS)

Add this line at the top of src/sayHello.ts

#!/usr/bin/env -S npx tsx

// src/sayHello.ts
// ...

open a Terminal window and run

chmod +x src/sayHello.ts

and then, every time you need to run the script, in the sayHello folder, do

./src/sayHello.ts

Run the script using the desired method, answer the questions, and check the output.

Going Further

Following the above steps, we were able to implement and run the same script we had in Deno 2.0. But there is one major difference. While Deno is truly running the script as-is, Node.JS, runs a transformed version of it that TSX generates. Let's say we have two versions of the script, the one we developed (in TS) and the other that Node runs natively (converted from TS to JS by TSX).

What are the implications? For big and complex projects, it could make things slower and require more resources, but for a small command line script, I would say none, if any at all.

What if I want to run the "translated" version of the script in Node and run it natively? Is it possible? Yes, it is, and this process we call transpilation, it's a bit complex topic and out of the scope of this article, so we are not covering it now. We may have it covered in an appendix after finishing this series. Stay tuned for more information.

Wrapping up

That's it. That's all we need to know to run a Typescript script with external dependencies, on the command line, using Node.JS

You can check the complete source code of the Node.JS version of the script here as well the source code of the Deno 2.0 version.

In the next article in this series, we will summarize both implementations and wrap up our findings with thoughtful conclusions.

Typescript scripts in the command line: Using Deno 2.0

Renato Rodrigues — Sun, 19 Jan 2025 20:25:27 +0000

This article is part of a series comparing Deno 2.0 and Node.JS's capabilities for running Typescript scripts with external dependencies from the command line. For a broader overview, refer to the first page of the series. This is the Deno 2.0 implementation; stay tuned for the Node.JS implementation of the same script.

Implementing the Script Using Deno 2.0

Since the beginning, Deno was able to run Typescript scripts natively, without the need for transpilation or any extra step. What was changed in Deno 2.0 was the ability to import and run NPM dependencies in your script without needing initialization steps, a project file, transpilation, or bundle steps.

Environment setup

Before starting, make sure you have Deno, at least at version 2.0 installed on your machine. For that, in a terminal window, run

deno -v

If you get an error, or a version older than 2.0, check this page for instructions on how to install/update Deno

VS Code

If you are using VS Code, which I recommend, you may want to install the official VS Code Deno extension

Creating the script

In a folder of your choice create a file called sayHello.ts and open it in your editor.

Importing external dependencies

To use external dependencies, such as NPM modules, in Deno, all you need to do is import it in your script file, following the syntax registry_type:package_name@package_version as illustrated below.

Add chalk, yosay and inquirer from NPM

// sayHello.ts

import chalk from 'npm:chalk@5.3.0';
import yosay from 'npm:yosay@3.0.0';
import inquirer, { Answers } from 'npm:inquirer@12.0.0';

If you are using VS Code, hover over the red error lines, click on Quick fix, and choose Cache all dependencies of this module

Implementing the script body

Add the following lines to sayHello.ts after the import block

// sayHello.ts
// ...

console.log(chalk.blue('\nHello visitor, please enter you details:\n'));

const questions: Answers = [
  {
    type: 'input',
    name: 'name',
    message: "What's your name?",
    required: true,
  },
  {
    type: 'list',
    name: 'salutation',
    message: 'How should I refer to you?',
    choices: ['Mr.', 'Mrs.', 'none'],
  }
];

inquirer.prompt(questions).then((answers) => {
  const { salutation, name } = answers ;

  console.log(`\n${chalk.green('[SUCCESS]:')} information entered was correct`);

  const person: string[] = [ name ];
  if(salutation !== 'none') person.unshift(salutation);

  console.log(yosay(`Hallo ${person.join(' ')}!`));
});

Running the script

Method 1: Using deno command

Open a terminal window and run

deno -A sayHello.ts

The -A option gives Deno all the permissions needed to download the external dependencies and run the code locally.

Method 2: Making the script executable (Linux/MacOS)

Add this line at the top of sayHello.ts

#!/usr/bin/env -S deno -A

// sayHello.ts
// ...

open a terminal window and run

chmod +x sayHello.ts

and then, every time you need to run the script, in the script folder, do

./sayHello.ts

Run your script using the desired method, answer the questions, and check the output.

Wrapping up

That's it. That's all you need to do to run a Typescript script with external dependencies on the command line using Deno 2.0

You can check the complete source code of the Deno version of the script here.

In the next article in this series, we will explore how to achieve the same functionality using Node.JS instead of Deno. Check it out!

(and yes, I know that Node >= 22 has primitive support for TypeScript, but it's so primitive that I'd say it tolerates (and ignores) TS more than it actually supports it. More on that in the next article)

Typescript scripts in the command line: Deno 2.0 vs Node.JS

Renato Rodrigues — Sun, 19 Jan 2025 20:24:40 +0000

Whether you are new to the development world or a seasoned developer, scripts make life easier. They automate repetitive tasks, streamline complex processes, and produce predictable output, phasing out the human factor that could lead to errors. Everyone loves a well-written script.

Historically, scripts have been written mostly in Shell Script, Python, or Ruby languages. In recent years, however, Javascript started making its way into this universe. A good reason to use Javascript for this is the familiarity that most developers have with this language. However, a reason not to use it is that Javascript, in its purest form, is limited and inferior to the aforementioned languages, and it´s not easy to extend its functionality using external dependencies. Typescript can be seen as an evolution to Javascript, and it is even more complicated to create a Typescript script and run it from the command line.

This scenario changed forever with the release of Deno 2.0 which makes running Javascript AND Typescript scripts natively, with support for external dependencies, a breeze.

In this series of articles, we will explore the possibilities of creating Typescript scripts that use external libraries, such as those from Node's NPM or Deno's JSR, and running them using Deno 2. Then, for the sake of comparison, we will see how to achieve the same using Node.JS.

The sample script

The sample script is a simple command line interface (CLI) script that asks you some questions and then prints them formatted to the terminal, based on your input. Its purpose is to show you how to run a Typescript script that uses external dependencies from the command line.

Head to the next page to see how to implement it using Deno 2.0

Programação Funcional em JS, Imutabilidade e Reducers com Immer

Renato Rodrigues — Thu, 11 Nov 2021 13:06:56 +0000

Programação Funcional

Resumidamente podemos dizer que as linguagens que trabalham com o paradigma de programação funcional seguem alguns preceitos básicos:

Funções puras: Recebem as informações que precisam por parâmetros e retornam sempre o mesmo resultado se chamadas com os mesmos parâmetros;
Sem efeitos colaterais: As funções não mutam informações fora de seus escopos;
Stateless: As funções não possuem e não dependem de estados internos ou externos;
Idempotentes: As funções podem ser chamadas um número infinito de vezes e em diferentes contexto que resultado vai ser sempre o mesmo se os argumentos forem os mesmos, não gerando side-effects nem persistindo nenhuma alteração.

Programação Funcional em Javascript

Javascript por padrão não é uma linguagem funcional, porém por ser uma linguagem altamente flexível, adaptável e independente de paradigmas, os padrões de Programação Funcional podem ser utilizados em JS. É importante observar no entanto, que por ser uma linguagem extremamente permissiva e não te obrigar a praticamente nada, o Javascript não vai garantir que seu código siga todos os preceitos da PF. Fica a cargo do desenvolvedor aplicar esses preceitos corretamente.

Função não pura e com side effect em JS

var externalCount = 0;

function plus1() {
  externalCount = externalCount + 1;
  return externalCount;
}

console.log('External count:', externalCount); // External count: 0
var internalCount = plus1();
console.log('Internal count:', internalCount); // Internal count: 1
console.log('External count:', externalCount); // External count: 1

Programação Funcional em JS antes do ES5

Antes do ES5 (ECMAScript 5th Edition) os conceitos de Programação Funcional praticamente não existiam em JS e só poderiam ser obtidos replicando manualmente esses comportamentos em seu código ou utilizando libs externas que faziam exatamente isso (ex, Underscore.js).

Programação Funcional em JS com ES5 (~ 2012*)

O ES5 trouxe para o mundo do JS alguns conceitos e funcionalidades de Programação Funcional, como por exemplo as funções map, filter e reduce, possibilitando aplicar esse novo paradigma onde antes não era possível. As revisões futuras do ES vieram a reforçar esse suporte.

* O ES5 foi oficialmente criado em 2009, mas só começou mesmo a ser utilizado por volta de 2012 devido à incompatibilidade com a base instalada de navegadores antigos.

Filtrando antes do ES5

var allNumbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

var evenNumbers = [];

for(var i = 0; i < allNumbers.length; i++) {
  if(allNumbers[i] % 2 === 0) {
    evenNumbers.push(allNumbers[i]);
  }
}

// evenNumbers = 0, 2, 4, 6, 8

Filtrando com o ES5

var allNumbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

var evenNumbers = allNumbers.filter(function(number) {
  return number % 2 === 0
});

// evenNumbers = 0, 2, 4, 6, 8

Imutabilidade

Imutabilidade em seu conceito mais básico diz que uma informação após ser definida não pode ser mais alterada.
Em programação isso traz algumas vantagens, como por exemplo garantir a consistência da informação durante todo o fluxo de dados, não gerar efeitos colaterais em funções, poder fazer referências à informação original ao invés de copiá-la, poder usar essa informação como índice ou chave, passá-la pra múltiplos threads e funções assíncronas, etc.

Imutabilidade em JS

Valor x referência

Em Javascript a maioria dos parâmetros são passados por referência, ou seja, ao invés de serem copiados, uma referência à informações original será criada. Isso significa que qualquer alteração feita nesse parâmetro refletirá também na informação original em si e vice-versa.

Tipos primitivos

A exceção à essa regra são os tipos primitivos da linguagem Javascript, que sempre são passados como valor, sem nenhuma referência à informação original. São eles:
Boolean, Number, String, Null, Undefined e Symbol.

Tipos Object

Tudo que não for um tipo primitivo em JS é do tipo Object e esse tipo sempre é passado por referência, portanto NÃO é imutável.

Tipos primitivos não mutam

var externalCount = 0;

function plus1(count) {
  count = count + 1;
  return count;
}

console.log('External count:', externalCount); // External count: 0
var internalCount = plus1(externalCount);
console.log('Internal count:', internalCount); // Internal count: 1
console.log('External count:', externalCount); // External count: 0

Já os tipos não primitivos (Object) mutam

var externalCount = { 
  value: 0,
};

function plus1(count) {
  count.value = count.value + 1;
  return count;
}

console.log('External count:', externalCount.value); // External count: 0
var internalCount = plus1(externalCount);
console.log('Internal count:', internalCount.value); // Internal count: 1
console.log('External count:', externalCount.value); // External count: 1

Então como obter imutabilidade em JS?

Pré ES5

Até o advento do ES5 era praticamente inexistente o conceito de imutabilidade em JS, pelo menos de forma nativa, tendo que recorrer a libs externas que de alguma maneira tentavam emular esse comportamento.

ES5

Object.assign

O ES5 introduziu o método assign aos objetos JS, que permite copiar o conteúdo de um número N de objetos à direita ao objeto mais à esquerda, mutando o mesmo e retornando o resultado. Note que somente o objeto mais à esquerda é mutado, os demais não.

Object.assign mutando o objeto mais à esquerda

var nameOnly = {
  name: 'Renato',
};

var lastNameOnly = {
  lastName: 'Rodrigues',
}

var emailOnly = {
  email: 'renato.rodrigues@renatorodrigues.com',
}

var myInfo = Object.assign(nameOnly, lastNameOnly, emailOnly);

// nameOnly = { name: 'Renato', lastName: 'Rodrigues', email: 'renato.rodrigues@renatorodrigues.com' }
// myInfo = { name: 'Renato', lastName: 'Rodrigues', email: 'renato.rodrigues@renatorodrigues.com' }

Tá, mas e a imutabilidade? Lembrando que quando falamos de JS, a linguagem nos permite fazer praticamente qualquer coisa, temos então um pulo do gato aí. Em nenhum lugar é dito que o objeto mais à esquerda precisa ser uma referência a um objeto previamente criado. Ele pode ser simplesmente um objeto vazio, recém criado, que vai receber todos os valores à direita. Logo, se não existe uma referência pra ele, não existe o que mutar. ¯\(ツ)/¯

Object.assign NÃO mutando o objeto mais à esquerda

var myInfo = Object.assign({}, nameOnly, lastNameOnly, emailOnly);

// nameOnly = { name: 'Renato' }
// myInfo = { name: 'Renato', lastName: 'Rodrigues', email: 'renato.rodrigues@renatorodrigues.com' }

Importante: O Object.assign somente copia as propriedades de primeiro nível dos objetos em si, caso uma propriedade seja um objeto nested ou faça uma referência a um objeto externo elas poderão ser mutadas, pois continuarão a apontar para o objeto original.

ES6 (2015)

O ES6 (ECMAScript 6th Edition, a.k.a ES2015) trouxe mais algumas funções e funcionalidades relacionadas à imutabilidade, apesar de *spoiler* nenhuma delas garantir uma imutabilidade 100%.

Const

O ES6 trouxe ao JS o conceito de constantes, que em teoria são variáveis imutáveis, mas não se deixe enganar, o const só funciona assim com tipos primitivos. Com tipos Object ele não permite que você reatribua um novo valor à variável, mas continua permitindo que as propriedades de um objeto já atribuído a ela sejam alteradas.

Imutabilidade com Const

const name = 'Renato';

const person = {
  name: 'Renato',
}

name = 'Roberto'; // Error: Assignment to constant variable. 
person = { name: 'Roberto' }; // Error: Assignment to constant variable. 

person.name = 'Roberto' // person = { name: 'Roberto' }

Object.seal

O Object.seal "sela" um objeto, não permitindo que nenhuma propriedade seja removida e nenhuma nova seja adicionada a ele, porém permite que suas propriedades já existentes sejam modificadas.

Importante: nenhum erro ou warning é retornado quando se tenta mutar um objeto selado.

const myInfo = {
  name: 'Renato',
  lastName: 'Rodrigues',
  email: 'renato.rodrigues@renatorodrigues.com',
};

Object.seal(myInfo);

delete myInfo.email;
myInfo.age = 90;
myInfo.name = "Roberto";

Resultado quando não selado

myInfo = {
  name: 'Roberto',
  lastName: 'Rodrigues',
  age: 90,
}

Resultado quando selado

myInfo = {
  name: 'Roberto',
  lastName: 'Rodrigues',
  email: 'renato.rodrigues@renatorodrigues.com',
}

Object.freeze

O Object.freeze "congela" um objeto, não permitindo que nenhuma propriedade seja removida, nenhuma nova seja adicionada a ele e nem que suas propriedades já existentes sejam modificadas.

Importante: nenhum erro ou warning é retornado quando se tenta mutar um objeto congelado.

const myInfo = {
  name: 'Renato',
  lastName: 'Rodrigues',
  email: 'renato.rodrigues@renatorodrigues.com',
};

Object.freeze(myInfo);

delete myInfo.email;
myInfo.age = 90;
myInfo.name = "Roberto";

Resultado quando congelado

const myInfo = {
  name: 'Renato',
  lastName: 'Rodrigues',
  email: 'renato.rodrigues@renatorodrigues.com',
}

"Ah mas então isso é imutabilidade!"

Assim como no Object.assign (e no Object.seal), o Object.freeze também só vale para as propriedades de primeiro nível do objeto em si, caso uma propriedade seja um objeto nested ou faça uma referência a um objeto externo seus filhos poderão ser mutados, pois esse objeto não estará congelado.

Objetos congelados com propriedades nested

const myInfo = {
  name: 'Renato',
  lastName: 'Rodrigues',
  email: 'renato.rodrigues@renatorodrigues.com',
  job: {
    title: "Self Employed",
    email: "renato@renatorodrigues.com",
  }
};

const jobAtSpaceX = {
  title: "VP of Mars Colonization",
  email: "renato.rodrigues@wearecoming.mars",
};

Object.freeze(myInfo);

myInfo.job = jobAtSpaceX;
myInfo.job.wage = undefined;

Resultado obtido

myInfo = { 
  name: 'Renato', 
  lastName: 'Rodrigues', 
  email: 'renato.rodrigues@renatorodrigues.com', 
  job: { 
    title: 'Self Employed', 
    email: 'renato.sp@gmail.com', 
    wage: undefined 
  } 
}

Objetos congelados com referência externa

const jobAtSpaceX = {
  title: "VP of Mars Colonization",
  email: "renato.rodrigues@wearecoming.mars",
};

const myInfo = {
  name: 'Renato',
  lastName: 'Rodrigues',
  email: 'renato.rodrigues@renatorodrigues.com',
  job: jobAtSpaceX,
};

Object.freeze(myInfo);

jobAtSpaceX.wage = Infinity;

Resultado obtido

myInfo = { 
  name: 'Renato', 
  lastName: 'Rodrigues', 
  email: 'renato.rodrigues@renatorodrigues.com', 
  job: { 
    title: 'VP of Mars Colonization', 
    email: 'renato.rodrigues@wearecoming.mars', 
    wage: Infinity,
  } 
}

ES6 (para Arrays) e E2018 (para Objetos)

Spread operator

O Spread operador se tornou o meio padrão de conseguir imutabilidade em JS, pois ao "espalhar" as propriedades de um array (ES6) ou objeto (ES2018) em um novo array ou objeto, uma cópia é feita, se tornando assim independente do original.

Mergeando objetos com o Spread

var nameOnly = {
  name: 'Renato',
};

var lastNameOnly = {
  lastName: 'Rodrigues',
}

var emailOnly = {
  email: 'renato.rodrigues@renatorodrigues.com',
}

var myInfo = { ...nameOnly, ...lastNameOnly, ...emailOnly };

// nameOnly = { name: 'Renato' }
// myInfo = { name: 'Renato', lastName: 'Rodrigues', email: 'renato.rodrigues@renatorodrigues.com' }

"Ah, mas então está aí a imutabilidade 100% em JS"

O Spread Operator é como se fosse uma "versão moderna" do Object.assign({}, N). A mesma situação com propriedades nested e referências externas citadas anteriormente também ocorre com o spread.

Proxies

Uma das novidades mais interessantes (e menos utilizadas) do ES6 foram os proxies. Podemos dizer que quando se faz proxy de um objeto, ele fica "protegido" por um proxy que tem acesso à leitura e à gravação de suas propriedades e pode manipular como fazê-los. Resumindo, o proxy "esconde" o objeto original e qualquer acesso à ele é feito via métodos especiais chamados de traps. Isso pode ser utilizado juntamente com um padrão que favoreça a imutabilidade do objeto original, como por exemplo o copy-on-write.

Funcionamento prático do Proxy

Exemplo Proxy

const personObj = {
  firstName: 'Renato',
  lastName: 'Rodrigues',
}

const handler = {
  set(target, property, value) { // set Trap
    if (Array.isArray(value)) {
      target[property] = value.join(', ');
    } else {
      target[property] = value;
    }
  },
  get(target, property) { // get Trap
    if (typeof target[property] === 'string' && target[property].match(/, /)) {
      return target[property].split(', ');
    } else {
      return target[property];
    }
  }
}

const personProxy = new Proxy(personObj, handler);

personObj.hobbies = "video games, running";
personProxy.pets = ["Mario", "Luigi"];

// personObj.hobbies = "video games, running"
// personObj.pets = "Mario, Luigi"

// personProxy.hobbies = ["video games", "running"]
// personProxy.pets = ["Mario", "Luigi"]

Immer

Fazendo o uso massivo de proxies, a biblioteca Immer surgiu como uma maneira mais simples e direta de garantir a imutabilidade de objetos em JS. Basicamente o que ela faz é proteger o objeto original (olha o Proxy aí \o/) e persistir cada alteração feita nele num objeto intermediário, chamado de Draft, para depois no final da operação produzir um novo objeto com o resultado das alterações do draft aplicadas ao objeto original.

Funcionamento prático da Immer

Mas como a Immer funciona?

Exemplo sem Immer (muta o objeto original)

const person = {
  firstName: 'Renato',
  lastName: 'Rodrigues',
}

const withCobli = (collaborator) => {
  collaborator.company = 'Cobli';
  return collaborator;
}

const employee = withCobli(person);

// person: { firstName: 'Renato', lastName: 'Rodrigues', company: 'Cobli' } 
// employee: { firstName: 'Renato', lastName: 'Rodrigues', company: 'Cobli' }

Exemplo com Spread (não muta o objeto original)

const person = {
  firstName: 'Renato',
  lastName: 'Rodrigues',
}

const withCobli = (collaborator) => {
  return {
    ...collaborator,
    company: 'Cobli',
  };
];

const employee = withCobli(person);

// person: { firstName: 'Renato', lastName: 'Rodrigues' } 
// employee: { firstName: 'Renato', lastName: 'Rodrigues', company: 'Cobli' }

Exemplo com Immer

const person = {
  firstName: 'Renato',
  lastName: 'Rodrigues',
}

const withCobli = produce(collaborator, draftCollaborator => {
  draftCollaborator.company = 'Cobli';
});

const employee = withCobli(person);

// person: { firstName: 'Renato', lastName: 'Rodrigues' } 
// employee: { firstName: 'Renato', lastName: 'Rodrigues', company: 'Cobli' }

Porque Immer?

De acordo com o artigo de introdução à Immer, somente na listagem do Redux-ecosystem-links existem outras 67 bibliotecas de imutabilidade em JS. Então porque usar a Immer?

Pequena: Somente 3kb e com ZERO dependências;
Rápida: Utiliza funções nativas de JS, como os proxies, ao invés de loops e condicionais;
Simples: Pode ser implementada em uma linhas e não requer nenhuma configuração;
Versátil: Suporta propriedades nested de infinitos níveis e mantem a tipagem correta das propriedades!
Fácil: Curva de aprendizagem praticamente zero, somente sintaxe nativa de JS, nenhuma outra sintaxe ou padrão é necessário;
Transparente: Uma vez implementada, você mal percebe que está usando;
Estruturalmente Equivalente: Partes não mutadas do novo objeto vão continuar fazendo referência ao objeto original. Mantendo eles assim equivalentes e evitando a duplicação de informações idênticas na memória.

Reducers

No mundo React existe um fluxo obrigatório de como as informações devem ser persistidas e lidas na Store (state). Esse fluxo é uni-direcional, com passos bem definidos e sempre trabalhando com imutabilidade (viu a chance aí?). Ele se aplica tanto ao estado da aplicação (usando Redux), quanto ao estado interno dos componentes (usando useReducer)

Um reducer nada mais é que uma função que recebe dois parâmetros, o estado atual e uma ação que contém um tipo e pode ou não conter um payload. A partir do tipo da ação é decidido quais mudanças serão aplicadas ao estado da aplicação/componente. Como este estado é imutável, esta função deve retornar uma nova cópia dele já com as diferenças aplicadas. Este então será o novo estado.

Hoje em dia, grande maioria dos devs utiliza o spread operator para fazer essa cópia do estado atual e modificá-lo sem mutá-lo

Reducer usando spread

const demoReducer = (state: demoState, action: demoActions): demoState => {
  switch (action.type) {
    case ActionTypes.INCREMENT_COUNTER:
      return {
        ...state,
        count: state.count + 1
      };
    case ActionTypes.DECREMENT_COUNTER:
      return {
        ...state,
        decrementCount: state.decrementCount - 1
      };
    case ActionTypes.SET_AMOUNT:
      return {
        ...state,
        amount: action.payload
      };
    default:
      return state;
  }
};

Reducer usando spread (erro)

const demoReducer = (state: demoState, action: demoActions): demoState => {
  switch (action.type) {
    case ActionTypes.INCREMENT_COUNTER:
      return {
        ...state,
        count: state.count++
      };
  }
};

Currying

Currying é o processo de transformar uma função que espera vários argumentos em uma função que espera um único argumento e retorna outra função que recebe um argumento e assim sucessivamente até o final dos argumentos. Por exemplo, uma função que recebe três argumentos, vai resultar em uma função que recebe um argumento e retorna uma função que recebe um argumento, que por sua vez retorna uma função que recebe um argumento e retorna o resultado da função original.

As funções curried podem tanto receber parâmetros das funções acima quanto os valores retidos nessas funções (closures)

Exemplo Currying

function sayTo(who) {
  const person = who.toString().toUpperCase();

  return function say(what) {
    console.log(`Say ${what} to ${person}`)
  }
}

const sayToRenato = sayTo('Renato');
sayToRenato('Wasuuuup!'); 
// Say Wasuuuup! to RENATO 

const sayToCaio = sayTo('Caio');
sayToCaio('Yo Bro!')
sayToCaio('Whats going on?');
// Say Yo Bro! to CAIO
// Say Whats going on? to CAIO

Curried Reducer

Aproveitando as vantagens do currying, os desenvolvedores da Immer criaram o modo curried do método produce, que cai como uma luva quando usado em um Reducer. Ele recebe como o único parâmetro uma função de callback que vai receber um state e uma action. O curried reducer irá retornar uma função que ao receber o state original irá criar um draft dele e chamará o callback passando esse draft junto com a action passada pelo Redux/useReducer, criando assim um reducer 100% compatível e completamente transparente para quem o chama.

Exemplo Curried Reducer

import produce, { Draft } from "immer";

const demoReducer = produce((draft: Draft<DemoState>, action: DemoActions) => {
  switch (action.type) {
    case ActionTypes.INCREMENT_COUNTER:
      draft.count++;
      break;
    case ActionTypes.DECREMENT_COUNTER:
      draft.decrementCount--;
      break;
    case ActionTypes.SET_AMOUNT:
      draft.amount = action.payload;
      break;
  }
});

(Sim, é só isso que precisa pra usar, não tem mais nada mesmo)

Como migrar para Immer

1) Importe a função produce da Immer;
2) Adicione-a no modo curried ao seu reducer ja existente;
3) Remova todos os returns;
4) Remova todos os spreads;
5) Mute as propriedades diretamente;
6) Remova o case default.

Desafios

1) Esquecer o padrão spread;
2) (Re-)aprender a mutar propriedades de um objeto usando JS básico.

Na dúvida sempre lembre-se

Bonus: Mutações básicas

// Alterar propriedade
draft.property = newValue;

// Criar propriedade
draft.newProperty = value;

// Excluir propriedade
delete draft.uselessProperty;

// Alterar/criar propriedade nested
draft.nestedObject.nestedProperty = value; 

// Excluir propriedade nested
delete draft.nestedObject.uselessNestedProperty;

// Alterar/criar propriedade nested em um array
draft.nestedArray[i].nestedProperty = value;

// Adicionar um item ao um array
draft.nestedArray.push(newObj);

// Excluir propriedade nested em um array
delete draft.nestedArray[i].uselessNestedProperty;

// Excluir um item ao um array
draft.nestedArray.splice(i, 1);

Referência completa de mutação em objetos e arrays

FAQ

Preciso migrar tudo?

Nop. A menos que queira.

Qual o melhor momento para migrar então?

Considerando que a migração é bem simples, eu usaria a seguinte regra: Tem que modificar algo num Reducer? já aproveita a chance e migra.

Exemplos de reducers migrados

Sandbox Demo: Antes, Depois

Apêndice 1: Questões sobre Igualdade de valores e referências

Igualdade de valores e referências

var allNumbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

var evenNumbers = [];

for (var i = 0; i < allNumbers.length; i++) {
  if (allNumbers[i] % 2 === 0) {
    evenNumbers.push(allNumbers[i]);
  }
}

evenNumbers == allNumbers; // false
evenNumbers[0] === allNumbers[0]; // true
evenNumbers[1] === allNumbers[2]; // true

Igualdade de valores e referências usando filter

var allNumbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

var evenNumbers = allNumbers.filter(function (number) {
  return number % 2 === 0
});

evenNumbers == allNumbers; // false
evenNumbers[0] === allNumbers[0]; // true
evenNumbers[1] === allNumbers[2]; // true

Igualdade de valores e referências em objetos

  var allNumbers = [ 
    { v : 0 }, { v : 1 }, { v : 2 }, { v : 3 }, { v : 4 }, 
    { v : 5 }, { v : 6 }, { v : 7 }, { v : 8 }, { v : 9 }
  ];

  var evenNumbers = allNumbers.filter(function (item) {
      return item.v % 2 === 0
  });

  evenNumbers == allNumbers; // false
  evenNumbers[0] === allNumbers[0]; // true
  evenNumbers[0].v === allNumbers[0].v; // true
  evenNumbers[1] === allNumbers[2]; // true
  evenNumbers[1].v === allNumbers[2].v; // true

Igualdade de valores e referências com Object.assign

var nameOnly = {
  name: 'Renato',
};

var lastNameOnly = {
  lastName: 'Rodrigues',
}

var emailOnly = {
  email: 'renato.rodrigues@renatorodrigues.com',
}

var myInfo = Object.assign(nameOnly, lastNameOnly, emailOnly);

myInfo.name === nameOnly.name; // true
myInfo.email === nameOnly.email; // true
myInfo === nameOnly; // true

Igualdade de valores e referências com Object.assign({})

var nameOnly = {
  name: 'Renato',
};

var lastNameOnly = {
  lastName: 'Rodrigues',
}

var emailOnly = {
  email: 'renato.rodrigues@renatorodrigues.com',
}

var myInfo = Object.assign({}, nameOnly, lastNameOnly, emailOnly);

myInfo.name === nameOnly.name; // true
myInfo.email === nameOnly.email; // false
myInfo === nameOnly; // false

Igualdade de valores e referências com o spread operator

var nameOnly = {
  name: 'Renato',
};

var lastNameOnly = {
  lastName: 'Rodrigues',
}

var emailOnly = {
  email: 'renato.rodrigues@renatorodrigues.com',
}

var myInfo = { ...nameOnly, ...lastNameOnly, ...emailOnly };

myInfo.name === nameOnly.name; // true
myInfo.email === nameOnly.email; // false
myInfo === nameOnly; // false

Equality Operator (==) e Strict Equality Operador (===)

Para tipos primitivos

== Compara igualdade de valores (faz conversões)

=== Compara igualdade de valores e tipo (não faz conversões)

"1" == 1; // true
"1" === 1; // false
1 == true); // true
1 === true); // false
"" == false); // true
"" === false); // false
[] == false); // true
[] === false); // false
undefined == null); // true
undefined === null); // false
"" == undefined); // false
"" === undefined); // false

Para tipos Object

== Compara referência (ignora estrutura e valores)

=== Compara referência (ignora estrutura e valores)

var person = {
  name: 'Renato',
}

var person2 = {
    name: 'Renato',
}

var person3 = person;

person == person2; // false
person === person2; // false
person == person3; // true
person === person3; // true

Bonus: Igualdade de NaN

const a = NaN;
const b = NaN;

a == NaN; // false
b == NaN; // false
a == b; // false
NaN == NaN; // false

Object.is(a, b); // true
Object.is(NaN, NaN); // true