Cangaceiro JavaScript

Rxjs: lidando com eventos elegantemente

2018-12-23T23:00:00+00:00

Neste artigo especial de natal será demonstrado como o Rxjs pode ajudar o desenvolvedor a lidar elegantemente com eventos do DOM.

Contexto

Temos uma aplicação hipotética construída com HTML, CSS e JavaScript. Ela alerta o usuário que estiver inativo por mais de cinco minutos que sua sessão vai expirar. Neste contexto, a aplicação precisa monitorar o clique, mover do mouse e o pressionar de qualquer tecla, detectando assim atividade por parte do usuário e consequentemente reiniciando o timer de inatividade.

Vamos começar pelo trecho de código responsável por reiniciar o timer de inatividade:

const startWatching = () => {
    document.addEventListener('click', resetTimer);
    document.addEventListener('mousemove', resetTimer);
    document.addEventListener('keypress', resetTimer);
}
const resetTimer = () => { /* reseta o timer da sessão, código omitido */ };
startWatching();

Um olhar atento no código que acabamos de ver verificará que ele possui um problema de performance. Cada coordenada alterada do mouse na tela dispara a chamada de resetTimer, isto é, desligará o timer atual criando um novo logo em seguida. A mesma coisa para cada tecla pressionada pelo usuário, assim como cliques. Uma solução é aplicar o debounce pattern. Porém, em vez de implementarmos nossa própria função debounce, utilizaremos o operador debounceTime do Rxjs.

Lidando com elementos do DOM através do Rxjs

Primeiro, precisamos tratar os eventos que vimos até agora através da função fromEvent do Rxjs. Esta função criará um Observable que emitirá valores toda vez que um evento for disparado:

// importando fromEvent do pacote rxjs
import { fromEvent } from 'rxjs';

const startWatching = () => {
    fromEvent(document, 'click')
        .subscribe(resetTimer);
    fromEvent(document, 'mousemove')
        .subscribe(resetTimer);
    fromEvent(document, 'keypress')
        .subscribe(resetTimer);
}
const resetTimer = () => /* reseta o timer da sessão */
startWatching();

A função fromEvent recebe como primeiro parâmetro o elemento que desejamos associar um handler para um evento e o segundo é o tipo de evento em si. Como o método retorna um Observable, nos inscrevemos nele através do método subscribe, que recebe o handler do evento. Quando cada um dos eventos for disparado, a função resetTimer passada para subscribe será executada. Excelente, mas até agora trocamos seis por meia dúzia. O maior benefício vem com a aplicação do operador debounceTime:

import { fromEvent } from 'rxjs';
import { debounceTime } from 'rxjs/operators';

const startWatching = () => {
    fromEvent(document, 'click')
        .pipe(debounceTime(200))
        .subscribe(resetTimer);
    fromEvent(document, 'mousemove')
        .pipe(debounceTime(200))    
        .subscribe(resetTimer);
    fromEvent(document, 'keypress')
        .pipe(debounceTime(200))    
        .subscribe(resetTimer);
}
const resetTimer = () => /* reseta o timer da sessão */
startWatching();

Perfeito, mas se não quisermos mais responder aos eventos que acabamos de nos inscrever? Precisaremos guardar o retorno de cada chamada à função fromEvent em uma variável. O retorno nada mais é do que um objeto do tipo Subscription, aquele que nos permitirá cancelar nosso registro ao Observable:

import { fromEvent } from 'rxjs';
import { debounceTime } from 'rxjs/operators';
// variáveis que guardaram cada Subscription
let clickSubscription = null;
let mouseMoveSubscription = null;
let keyPressSubscription = null

const startWatching = () => {
    clickSubscription = fromEvent(document, 'click')
        .pipe(debounceTime(200))
        .subscribe(resetTimer);
    mouseMoveSubscription = fromEvent(document, 'mousemove')
        .pipe(debounceTime(200))    
        .subscribe(resetTimer);
    keyPressSubscription = fromEvent(document, 'keypress')
        .pipe(debounceTime(200))    
        .subscribe(resetTimer);
}

// alterou o método stopWatching também!
const stopWatching = () => {
    clickSubscription.unsubscribe();
    mouseMoveSubscription.unsubscribe();
    keyPressSubscription.unsubscribe();
}
const resetTimer = () => /* reseta o timer da sessão */
startWatching();

Nossa solução funciona, mais não é nada elegante. Primeiro, estamos repetindo a mesma chamada de resetTimer em cada uma das inscrições dos observables. Além disso, foi necessário declararmos variáveis mutáveis para guardarem as inscrições de cada Observable. São essas variáveis que serão utilizadas pela função stopWatching. Com certeza podemos melhorar o código escrito até agora.

Primeiro, vamos tentar evitar a repetição da chamada de subscribe:

import { fromEvent } from 'rxjs';
import { debounceTime } from 'rxjs/operators';

const startWatching = () => {
    ['click', 'mousemove', 'keypress']
        .forEach(event => 
            fromEvent(document, event)
                .pipe(debounceTime(200))
                .subscribe(resetTimer)
        );
}
const stopWatching = () => {
    /* como implementar ? */;
}
const resetTimer = () => /* reseta o timer da sessão */
startWatching();

Criamos um array com três elementos no qual cada um de seus elementos é o tipo do evento que desejamos escutar. Através de forEach, criamos um Observable para cada evento, aplicando o operador debounceTime e a chamada de subscribe uma única vez. Porém, temos um problema. Precisamos ter a capacidade de remover a inscrição de cada um dos três observables criados e da maneira que organizamos nosso código, isso não será possível. Como proceder?

A função merge

Uma solução para o problema é continuar criando um Observable para cada um dos eventos, mas tratando-os como um único Observable. Em outras palavras, o que queremos realizar é o merge de três observables. Conseguimos isso através da função merge do Rxjs:

import { fromEvent, merge } from 'rxjs';
// importou merge 
import { debounceTime } from 'rxjs/operators';

const startWatching = () => {
    const subscription = merge(
            // através do spread operador, passamos três 
            // observales para o métdo merge, em vez do array
            ...['click', 'mousemove', 'keypress']
                .map(event => fromEvent(document, event))
         )
         // neste ponto, temos três Observables mergeados
        .pipe(debounceTime(200))
        // o debounceTime será aplicado na emissão de cada Observable
        .subscribe(resetTimer);
    return subscription;
}
const resetTimer = () => { /* reseta o timer da sessão */ };
// guarda o retorno, a inscricão
const eventsSubscription = startWatching();
// utiliza a inscrição para cancelar a própria inscrição
const stopWatching = () => eventsSubscription.unsubscribe();

A função merge recebe um ou mais observables que no final serão tratados como um apenas. Isto é, independente de qual Observable emita um valor, seu resultado será disponibilizado para quem se inscrever no Observable gerado por merge. Através do spread operador garantimos que a função merge receberá três parâmetros em vez de um array de observables. Reparem teremos apenas uma Subscription que nos permitirá cancelar a inscrição dos três observables de uma só vez:

Podemos simplicar nosso código um pouco mais omitindo a declaração da variável subscription retornando diretamente o resultado de merge:

import { fromEvent, merge } from 'rxjs';
import { debounceTime,} from 'rxjs/operators';

const startWatching = () => 
    merge(
        ...['click', 'mousemove', 'keypress']
        .map(event => fromEvent(document, event))
    )
    .pipe(debounceTime(200))
    .subscribe(resetTimer);

const resetTimer = () => { /* reseta o timer da sessão */ };
const eventSubscriptions = startWatching();
const stopWatching = () => eventSubscriptions.unsubscribe();

Mas o que acontecerá se alguém chamar a função stopWatching mais de uma vez? Um erro, com certeza, pois não podemos chamar o método unsubscribe de uma Subscription mais de uma vez.

Podemos solucionar o problema citado no parágrafo anterior retornando uma função no lugar da Subscription. Esta função ao ser chamada garantirá que a inscrição será cancelada apenas uma vez:

import { fromEvent, merge } from 'rxjs';
import { debounceTime } from 'rxjs/operators';

const startWatching = () => {
    let subscription = merge(
        ...['click', 'mousemove', 'keypress']
            .map(event => fromEvent(document, event))
    )
    .pipe(debounceTime(200))
    .subscribe(resetTimer);

    return () => {
        // evita erro caso seja chamado duas vezes
        if(subscription) {
            subscription.unsubscribe();
            subscription = null;
        }
    }
}
const resetTimer = () => { /* reseta o timer da sessão */ }
const stopWatching = startWatching();
/* ... */
stopWatching(); // cancela as inscrições

Agora não temos mais variáveis mutáveis fora do escopo da função startWatching e garantimos que o cancelamento da inscrição não será realizado mais de uma vez.

Conclusão

A biblioteca Rxjs é muito poderosa, não é à toa que as extensões reativas estão presentes em diversas linguagens, não apenas em JavaScript.

O retorno do Cangaceiro JavaScript, meu novo livro

2018-09-03T15:00:00+00:00

É com muito entusiasmo que venho comunicar o lançamento do meu terceiro livro, “O Retorno do Cangaceiro JavaScript: de padrões a uma abordagem funcional”. Quero agradecer à comunidade pelo feedback extremamente positivo do livro anterior que foi fundamental para que eu desse continuidade aos trabalhos que resultaram neste novo livro.

Um livro com uma pegada mais funcional, mas acessível para um amplo espectro de desenvolvedores

Nas mais de 500 páginas do meu livro anterior, dei maior ênfase ao paradigma da orientação a objetos. Desta vez, “O Retorno do Cangaceiro Javascript” foca no paradigma funcional. Assim como no primeiro livro, utilizo uma abordagem evolutiva começando de problemas mais simples até os mais complexos, tudo dentro de um único projeto com início, meio e fim.

Em vez de bombardear o leitor com todo o jargão da programação funcional, elaborei o conteúdo de uma maneira que permitisse que conceitos emergissem a partir de problemas práticos. Em suma, trabalhei conceitos e técnicas que o desenvolvedor poderá aplicar assim que adquirí-los. Temos aqui um livro prático!

Mais padrões de projetos

Abordei padrões de projetos aplicáveis tanto ao paradigma da orientação a objeto quanto ao funcional, dando subsídios para que o leitor utilize-os conscientemente e não meramente por uma questão de estilo ou modinha.

Subsídios para que o leitor aprenda bibliotecas e frameworks famosos do mercado.

Meu novo manuscrito ajudará tanto o desenvolvedor experiente que deseja aplicar técnicas avançadas quanto aqueles que já possuem uma base tímida em JavaScript, mas que desejam avançar. O livro também preparará o mindset do leitor para trabalhar com bibliotecas utilizadas pela comunidade, pois perceberão com mais clareza suas vantagens e motivações quando comparadas ao uso de vanilla JavaScript.

Considerações finais

A jornada do cangaceiro ainda não terminou! Aguardem notícias!

Preview de imagens antes do upload

2018-04-06T11:00:00+00:00

Realizar o upload de arquivos é uma tarefa corriqueira do desenvolvedor web. Em se tratando do upload de imagens, realizar o preview antes do envio pode evitar que o usuário selecione a imagem errada. Neste artigo aprenderemos como realizar o preview da imagem escolhida.

Sobre upload de arquivos o leitor pode consultar o artigo Express, realizando upload com multer deste mesmo autor.

O problema

Temos o arquivo index.html que define um simples <form> com as tags <input type="file"> e <input type="submit">:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Preview</title>
</head>

<body>
    <form action='api-url-here' method='post' encType="multipart/form-data">
        <input class="file-chooser" type="file" accept="image/*">
        <input type="submit" value="upload">
    </form>  
</body>
</html>

Quando selecionamos uma imagem apenas seu nome será exibido ao lado do <input type="file">. Veremos a seguir como realizar o preview da imagem selecionada.

Solução

Vamos adicionar uma tag <img> com a classe preview-img entre a escolha do arquivo e o botão de submissão. É este elemento que fará o preview da imagem selecionada:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Preview</title>
</head>

<body>
    <form action='api-url-here' method='post' encType="multipart/form-data">
        <input class="file-chooser" type="file" accept="image/*">
        <img class="preview-img">
        <input type="submit" value="upload">
    </form>
    <script>
    // nosso script fica aqui!
    </script>    
</body>
</html>

Para darmos continuidade à solução precisamos obter do DOM os elementos de input da seleção do arquivo e a da imagem. Para o input de seleção planejaremos uma resposta para o evento onchange, aquele disparado quando um arquivo qualquer for selecionado:

const $ = document.querySelector.bind(document);
const previewImg = $('.preview-img');
const fileChooser = $('.file-chooser');
fileChooser.onchange = e => { /* falta implementar */};

Excelente! O evento onchange de um <input type="file"> nos dá acesso ao arquivo selecionado através de e.target.files.item(0):

const $ = document.querySelector.bind(document);
const previewImg = $('.preview-I=img');
const fileChooser = $('.file-chooser');

fileChooser.onchange = e => {
    // arquivo que faremos o upload
    const fileToUpload = e.target.files.item(0);
};

Não podemos simplesmente atribuir fileToUpload à previewImg.src, pois o primeiro é um binário (blob). Precisamos converter o arquivo para DataURL que nada mais é do que a representação do binário como uma string que é automaticamente decodificada pelo navegador. Faremos essa conversão através de um FileReader:

const $ = document.querySelector.bind(document);
const previewImg = $('.preview-img');
const fileChooser = $('.file-chooser');

fileChooser.onchange = e => {
    const fileToUpload = e.target.files.item(0);
    const reader = new FileReader();

    // evento disparado quando o reader terminar de ler 
    reader.onload = e => previewImg.src = e.target.result;

    // solicita ao reader que leia o arquivo 
    // transformando-o para DataURL. 
    // Isso disparará o evento reader.onload.
    reader.readAsDataURL(fileToUpload);
};

Quando reader.readAsDataURL terminar, o evento reader.onload será disparado. Através do parâmetro do evento temos acesso ao resultado da conversão através de e.target.result. É importante perceber que esta é uma operação assíncrona.

Pronto! Ao selecionarmos uma imagem ela será exibida para o usuário permitindo-o verificar se ela é a que ele realmente deseja subir.

Bônus: alterando a label do botão de seleção de arquivo

Uma coisa bem incômoda do <input type="file"> é que ele não permite mudar o texto do botão. Inclusive quem utiliza Bootstrap pode ter alguma dificuldade em estilizá-lo.

Uma das soluções é escondermos o <input type="file"> e dispará-lo através do clique de um <input type="button">. Vejamos a solução.

Primeiro, vamos adicionar o <input type="button"> e tornar o <input type="file"> invisível através do atributo hidden:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Preview</title>
</head>

<body>
    <form action='image/upload' method='post' encType="multipart/form-data">
        
        <!-- novo elemento! -->
        <input class="file-button" type="button" value="Choose your beautiful image">

        <!-- invisível -->

        <input class="file-chooser" type="file" accept="image/*" hidden>
        <img class="preview-img">
        <input type="submit" value="upload">
    </form>
    <script>
    // nosso script fica aqui!
    </script>    
</body>
</html>

Agora, vamos obter o novo botão para em seguida adicionarmos o evento onclick. É neste evento que chamaremos fileChooser.click(), forçando assim o click e como resultado a seleção do arquivo:

const $ = document.querySelector.bind(document);

const previewImg = $('.preview-img');
const fileChooser = $('.file-chooser');
const fileButton = $('.file-button');

fileButton.onclick = () => fileChooser.click();

fileChooser.onchange = e => {
    const fileToUpload = e.target.files.item(0);
    const reader = new FileReader();
    reader.onload = e => previewImg.src = e.target.result;
    reader.readAsDataURL(fileToUpload);
};

Perfeito. Agora temos maior liberdade para estilizar nosso botão.

Conclusão

Muitas vezes a tecnologia vigente não traz uma resposta direta para determinado problema de usabilidade e com isso força o desenvolvedor a elaborar soluções utilizando os recursos que tem. E você? Já precisou realizar o preview de imagens antes? Deixe sua opinião.

Evitando a serialização de propriedades dinâmicas de objetos

2018-03-12T11:00:00+00:00

O problema

Existem várias maneiras de adicionarmos flags de controle em objetos JavaScript. Uma delas é modificando o objeto diretamente:

// dados que podem vir de uma API web
const photo = {
    title: 'Cangaceiro JavaScript',
    author: 'Flávio Almeida'
}
// propriedade de controle que define um identificador único
photo._key = 1;

Todavia, ao serializarmos o dado para ser enviado para uma API, a propriedade _key estará presente:

const serializedPhoto = JSON.stringify(photo);
console.log(serializedPhoto);
/* 
{
    title: 'Cangaceiro JavaScript', 
    author: 'Flávio Almeida', 
    _key: 1
}
*/

Isso não seria um problema caso a API seguisse a boa prática de pinçar (pluck) apenas as propriedades que espera receber. Mas caso a API não siga esse caminho, fica evidente que não podemos enviar a propriedade _key.

Serializar o JSON em disco na plataforma Node.js também seria um problema, pois a propriedade também faria parte do dado serializado.

Uma solução é apagarmos a propriedade adicionada dinamicamente antes da serialização:

// código anterior omitido
delete photo._key; // apagando a propriedade
const serializedPhoto = JSON.stringify(photo);
delete serializedPhoto._key;
console.log(serializedPhoto);

A motivação para o post veio do problema enfrentado por um colega em sua aplicação feita com Ionic 3. Uma das bibliotecas utilizadas por ele modificava diretamente o modelo associado ao componente o que acabava lhe causando problemas na arquitetura definida por ele.

O exemplo acima não causaria grandes problemas de performance, mas o cenário seria diferente caso tivéssemos que iterar em um grande lista de objetos para então deletarmos a propriedade _key de cada um deles. A boa notícia é que há outra solução.

Definindo propriedades não iteráveis

Uma solução para o problema anterior é adicionarmos no objeto a propriedade _key como não enumerável. Uma propriedade não enumerável não será enxergada por repetições for...in ou pelo método Object.keys(). Como a função JSON.stringify() utiliza alguma estrutura de iteração para construir o JSON resultante, propriedades não enumeráveis serão ignoradas.

Um pouco sobre Object.defineProperty

Criamos propriedades não iteráveis com auxílio da função Object.defineProperty. Ela recebe como primeiro parâmetro o objeto que desejamos modificar e como segundo o nome da propriedade que será adicionada. Por fim, um objeto descritor (descriptor) é passado como último parâmetro. É nele que indicamos que a propriedade é não enumerável através de enumerable: false, inclusive seu valor através de value: 1:

Modificando nosso código:

const photo = {
    title: 'Cangaceiro JavaScript',
    author: 'Flávio Almeida'
}

Object.defineProperty(photo, '_key', { 
    enumerable: false, 
    value: 1
});

const serializedPhoto = JSON.stringify(photo);
console.log(serializedPhoto);
/* 
{
    title: 'Cangaceiro JavaScript', 
    author: 'Flávio Almeida', 
}
*/

O JSON resultante não contém mais a propriedade _key, excelente.

Conclusão

Podemos adicionar dinamicamente em objetoa propriedades não enumeráveis através de Object.defineProperty. Uma consequência dessas propriedades é que elas não farão parte do JSON criado através da função JSON.stringify.

A função Object.defineProperty permite definir ainda outras características da propriedade adicionada dinamicamente. E você? Já precisou utilizar essa função antes? Qual problema você tentou resolver? Deixe sua opinião.

Entendendo Redux com vanilla JavaScript

2018-03-02T11:00:00+00:00

Existe um número considerável de soluções no mercado para construção de Single Page Applications e cada uma delas resolve questões arquiteturais de sua maneira. Todavia, Redux é um padrão para gerenciamento centralizado de estado da aplicação que vem ganhando muita atenção da comunidade. Esse padrão se tornou tão popular que foram criadas diversas bibliotecas para integrá-lo com frameworks SPA. Vejamos algumas delas:

nxStore, Angular
react-redux, React
vuex, Vuejs
ember-redux, Emberjs

Neste artigo aplicaremos na prática Redux com vanilla JavaScript. Essa abordagem minimalista nos ajudará a focar nos seus principais conceitos sem termos o peso cognitivo de bibliotecas que fazem a ponte entre Redux e determinado framework.

Vejamos a seguir a infraestrutura mínina que o leitor precisará para colocar em prática o que aprenderá.

Infraestrutura

A única infraestrutura necessária para que o leitor possa colocar em prática o código deste artigo é ter instalado em sua máquina a plataforma Node.js. A versão 8.9.4 foi utilizada por este autor.

Preparando um pequeno projeto

Para que possamos ver a arquitetura Redux em ação, criaremos um pequeno projeto que utilizará o básico do Webpack para que possamos carregar módulos baixados através do npm, o gerenciador de módulos do Node.js.

Primeiro, criaremos a pasta project e dentro dela o arquivo index.html:

<!-- project/index.html -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width">
    <title>Redux with vanilla JavaScript</title>
</head>
<body>
    <input class="userName" placeholder="user name">
    <p class="status"></p>
    <script src="dist/bundle.js"></script>
</body>
</html>

É uma página simples que possui apenas um <input> no qual o usuário informará seu nome e um <p> que exibirá em tempo real uma mensagem de status contendo o nome informado. Por fim, a tag <script> carregará o bundle.js gerado através do Webpack. Esse bundle, além do nosso código, conterá a biblioteca padrão do Redux que utilizaremos.

Agora, dentro da pasta project/app vamos criar o módulo app.js com o script necessário para que o <p> seja atualizado a cada dígito do usuário em <input>:

// app/app.js
const statusParagraph = document.querySelector('.status');

document
.querySelector('.userName')
.oninput = e => {
    const userName = e.target.value;
    statusParagraph.textContent = userName 
        ? `${e.target.value} is typing` 
        : '';
};

Agora que já temos a estrutura mínima do projeto, vamos instalar e configurar rapidamente o Webpack para que possamos ver a aplicação em ação:

Instalando o Webpack e o Webpack Dev Server

No terminal e dentro da pasta project, vamos criar o arquivo package.json através do comando:

npm init -y

Com o package.json criado, baixaremos os módulos do Webpack e do Webpack Dev Server de uma só vez:

npm install webpack@3.11.0 webpack-dev-server@2.11.1 -D

Por fim, vamos criar o arquivo project/webpack.config.js com a configuração mínima que gerará o bundle.js:

// project/webpack.config.js
const path = require('path');

module.exports = {
    entry: './app/app.js',
    output: {
        filename: 'bundle.js',
        path: path.resolve(__dirname, 'dist'),
        publicPath: 'dist'
    }
}; 

Para terminar a configuração, adicionaremos em project/package.json o script "start", o responsável pela execução do webpack-dev-server que carregará as configurações definidas em webpack.config.js:

{
  "name": "project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "webpack-dev-server"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "webpack": "^3.11.0",
    "webpack-dev-server": "^2.11.1"
  }
}

Ainda dentro da pasta project, iniciamos nosso servidor através do comando:

npm start

Acessamos nossa aplicação através do endereço http://localhost:8080. Depois de carregada, experimente digitar no único <input> da página. Instantaneamente o valor digitado será exibido no <p> logo abaixo.

Alterações nos módulos da aplicação dispararão a geração de um novo bundle.js sem que o desenvolvedor tenha que se preocupar.

Antes de modificarmos nosso projeto para utilizar Redux, veremos brevemente seus principais princípios.

Sobre Redux

O próprio site do Redux o define como um container de estado previsível. Ele se baseia em três princípios:

SSOT (Single Source of Truth): o estado de toda a aplicação é armazenado em uma árvore de objetos dentro de uma única store. Ela é a única fonte de verdade sobre o estado da aplicação.
O estado é somente leitura: a única maneira de mudar o estado é emitindo uma action, um objeto que descreve o que aconteceu.
Mudanças são realizadas através de funções puras: essas funções puras são chamadas reducers. A partir de actions os reducers especificam como a árvore de estado deve ser transformada.

Uma função pura (pure function) é aquela que ao receber os mesmos argumentos retornará sempre o mesmo valor. Esse termo faz parte do jargão da programação funcional, inclusive funções desse tipo são fáceis de testar.

Não nos aprofundaremos nas definições, pois elas emergirão ao longo do nosso projeto. O autor entende que para compreender Redux é necessário conciliar teoria e prática. Aliás, chegou a hora de realizarmos a integração com Redux.

Instalando o módulo redux

Com o servidor parado, ainda na pasta project, vamos instalar o módulo redux:

npm install redux@3.7.2 -S

Lembre-se que ao utilizarmos Redux, teremos uma única store que armazenará o estado de toda a aplicação. Não poderia ser diferente, já que ela será nossa única fonte de verdade sobre seu estado. Vamos criar nossa store no módulo app/store.js:

app/store.js
// vazio, por enquanto

Por enquanto nosso módulo não terá qualquer código, porque seu estado inicial será definido através do único reducer que nossa simples aplicação terá. Aliás, uma aplicação pode ter um ou mais reducers que no final são combinados para criar a única store da aplicação. Vamos criar nosso primeiro reducer.

O papel do reducer

O reducer é o responsável em especificar como o estado da aplicação deve ser alterado em resposta às actions recebidas pela store. Vamos criar nosso primeiro reducer:

// app/reducers/statusReducer.js
const initialState = { status: '' };

export const statusReducer = (state = initialState, action) => {
    // ainda falta implementar
};

Devido à forte relação com reducers, a única store da aplicação é criada a partir da combinação de todos os reducers, pois cada um é o responsável por atualizar parte do estado da aplicação. Isso ficará mais claro quando criarmos nossa store.

A variável initialState é um objeto que representa o estado incial da aplicação sob a jurisdição do reducer. Esse objeto pode ter uma ou mais propriedades, em nosso caso, ele possui apenas a propriedade status, aquela que guardará a mensagem de status da aplicação. Seu valor inicial é uma string em branco.

Em seguida, definimos nossa função pura, isto é, nosso reducer que recebe sempre como parâmetro o estado da aplicação e a action recebida. Através de default parameter indicamos que o valor padrão do parâmetro state será initialState, aquele objeto que define o estado inicial da aplicação.

// app/reducers/statusReducer.js
const initialState = { status: '' };

export const statusReducer = (state = initialState, action) => {
    // Nova mensagem de status para ser atualizada 
    // no estado da aplicação, isto é, na store
    const status = action.payload;
};

Ainda não criamos actions em nossa aplicação, mas o mais importante nesse momento é entender que uma action nada mais é do que um objeto JavaScript com as propriedades type e payload. O primeiro guarda uma string que identifica o seu tipo, já o segundo o valor associado, isto é, aquele que desejamos que seja atualizado no estado da aplicação. É por isso que o valor de action.payload será a nova mensagem de status que desejamos atualizar na store.

Em breve, quando digitarmos no <input> da página, despacharemos para nossa store a action com o type ‘CHANGE_STATUS’ e que terá como payload o valor digitado. Todavia, lembre-se que é papel do reducer realizar a atualização do estado na store e não da action.

Como um reducer potencialmente pode lidar com uma ou mais actions, faremos um switch que decidirá qual lógica executar com base no tipo da action recebida:

// app/reducers/statusReducer.js
const initialState = { status: '' };

export const statusReducer = (state = initialState, action) => {
    
    const status = action.payload;

    switch (action.type) {
        case 'CHANGE_STATUS':
            // modificar o estado aqui
        default:
            return state;
    }
};

É importante que nosso reducer retorne o estado atual da aplicação caso a action disparada não tenha sido definida, por isso adicionamos a cláusula default em nosso switch.

Imutabilidade do estado da aplicação

Excelente, todavia chegamos a uma das partes mais importantes do Redux. O estado da aplicação deve ser imutável, isto é, não deve mudar. Para quem esta começando com Redux essa questão da imutabilidade pode dar um nó na cabeça. Quando dizemos imutável, significa que para modificarmos o estado da aplicação precisaremos criar um novo object state com base no state anterior.

Nesse sentido, uma abordagem imprópria na hora de atualizar o estado da aplicação é a seguinte:

// app/reducers/statusReducer.js
const initialState = { status: '' };

export const statusReducer = (state = initialState, action) => {
    
    const status = action.payload;

    switch (action.type) {
        case 'CHANGE_STATUS':
            // NÃO FAÇAM ISSO!
            state.status = status;
        default:
            return state;
    }
};

No código anterior, ocorreu a mutação do state da aplicação. Isto é, aproveitamos o mesmo objeto (referência) e modificamos sua propriedade status. Uma abordagem imutável é a seguinte:

// app/reducers/statusReducer.js
const initialState = { status: '' };

export const statusReducer = (state = initialState, action) => {
    
    const status = action.payload;

    switch (action.type) {
        case 'CHANGE_STATUS':
            return Object.assign({}, state, { status });
        default:
            return state;
    }
};

Se temos um artefato imutável, como realizamos alterações? Criamos um novo artefato e copiamos os valores do artefato atual, inclusive definindo novos valores para as propriedades que desejamos que sejam diferentes no artefato final.

A função Object.assign() é usada para copiar os valores de todas as propriedades próprias enumeráveis de um ou mais objetos de origem para um objeto destino. Este método irá retornar o objeto destino.

Em nosso caso, o primeiro parâmetro {} é o objeto destino, isto é, um novo objeto sem qualquer propriedade. Já os demais parâmetros são os objetos cujas propriedades serão copiadas para o objeto destino. Se um ou mais desses objetos tiverem a mesma propriedade, será o valor do último objeto passado como parâmetro que fará parte do objeto destino. É por isso que passamos { status } como último parâmetro.

A partir do ES2018 podemos usar o Spread Operator com propriedades de objeto. Isso nos permitirá substituir o verboso Object.assign({}, state, { status }) por { ...state, status }.

Construindo nossa store

Agora que já temos nosso reducer implementado, construiremos nossa store que o utilizará durante sua criação.

Vamos alterar o módulo app/store.js importando a função createStore do módulo redux e nosso statusReducer.

// app/store.js
import { createStore } from 'redux';
import { statusReducer } from './reducers/statusReducer';

export const store = createStore(statusReducer);

A função createStore recebeu como parâmetro o statusReducer para criar a nossa store. É a store criada que será exportada pelo módulo. Lembre-se, em Redux podemos ter vários reducers responsáveis em lidar com ações e atualizar determinados estados da aplicação, mas os estados ficam centralizados em um único lugar, a store.

Se tivéssemos mais de um reducer precisaríamos combiná-los para então passar o resultado da combinação para a função createStore. Esse processo de combinar reducers é feito através da função combineStores, também definida no módulo redux.

Agora que já temos a store pronta, partiremos para a implementação da única action da aplicação.

Implementando uma action

Já falamos um pouco sobre action, ela descreve o fato de que algo aconteceu, mas não define como o estado da aplicação deve ser alterado. A mudança do estado é feita sincronamente através de reducers. Chegou a hora de implementá-la em nossa aplicação.

Estruturalmente, uma action é definida através de um objeto com as propriedades type e payload. Por fim, elas são despachadas através da função dispatch da nossa store. Vejamos um exemplo isolado, que não entra em nossa aplicação:

// EXEMPLO apenas, não entra em nossa aplicação
// importa a store da aplicação
import { store } from './store.js';
// Solicita a store o depacho da action,
// pode ser disparado a partir de alguma 
// ação do usuário
store.dispatch({
    type: 'CHANGE_STATUS',
    payload: 'Calopsita is typing'
})

No código anterior, nosso reducer responderá à ação CHANGE_STATUS recebendo o valor do payload. É com base nesse valor que a store será atualizada. Um ponto a destacar é que efeitos colaterais (side effects) são realizados em actions e não em nossos reducers. Exemplos de side effects são chamadas a console.log() e requisições ajax. Ainda veremos como lidar com efeitos colaterais em nossas actions.

Todavia, a abordagem que adotamos deixa um pouco a desejar. Se uma action deste tipo é usada em diversos lugares da aplicação e de uma hora para outra precisarmos mudar seu tipo, teremos que alterar em diversos lugares. Uma solução para o problema é criarmos action creators.

Flexibilidade com Action Creators

Action creators são funções que ao serem invocadas retornam uma action. Vamos criar o módulo app/actions/status.js e dentro dele definir um action creator para a ação ‘CHANGE_STATUS’:

// app/actions/status.js
export const changeStatus = userName => {
    return {
        type: 'CHANGE_STATUS',
        payload: `${userName} is typing`
    }
};

O módulo app/actions/status.js exporta apenas um action creator que declaramos na função changeStatus. Essa função recebe como parâmetro um userName e ao ser chamada retorná uma action. Podemos simplificar ainda mais o código desta maneira:

// app/actions/status.js
export const changeStatus = userName => ({
    type: 'CHANGE_STATUS',
    payload: `${userName} is typing`
});

Agora, voltando ao exemplo isolado exibido anteriormente e fazendo uso do nosso action creator:

// EXEMPLO apenas, não entra em nossa aplicação
import { store } from './store.js';
// importou o action creator
import { changeStatus } from './actions/status.js';
// não sabemos mais os detalhes da action!
store.dispatch(changeStatus('Calopsita is typing'));

Excelente, escondemos os detalhes da action 'CHANGE_STATUS'. Todavia, nosso código pode ficar ainda melhor.

Action Types como constantes

Se analisarmos os módulos app/reducers/statusReducer.js e app/actions/status.js veremos que cada um deles define a string CHANGE_STATUS. Além de termos o nome duplicado, nada impede o programador de acidentalmente escrever o tipo da action errado.

Para solucionar o problema que acabamos de ver, vamos declarar os tipos das actions como constantes em um módulo em separado chamado app/constants/actionTypes.js e usar esse módulo em todos os lugares que os tipos forem necessários:

// app/constants/actionTypes.js
export const actionTypes = {
    CHANGE_STATUS: 'CHANGE_STATUS'
};

Utilizando a constante em app/actions/status.js:

// app/actions/status.js
// importa as constantes
import { actionTypes } from '../constants/actionTypes.js';

export const changeStatus = userName => ({
    // utiliza a constante
    type: actionTypes.CHANGE_STATUS,
    payload: `${userName} is typing`
});

E também no módulo app/reducers/statusReducer.js:

// app/reducers/statusReducer.js
// importa as constantes
import { actionTypes } from '../constants/actionTypes';

const initialState = { status: '' };

export const statusReducer = (state = initialState, action) => {
    
    const status = action.payload;

    switch (action.type) {
        // utiliza a constante
        case actionTypes.CHANGE_STATUS:
            return Object.assign({}, state, { status });
        default:
            return state;
    }
};

Nosso código ficou mais organizado e menos sujeito a erro.

A criação das pastas reducers, actions e constants segue o padrão Rails-Style. Você pode consultar outras formas de estruturar um projeto na própria documentação do Redux.

Temos nossa store (criada a partir de statusReducer) e nosso action creator changeStatus utilizando uma constante em comun definida em actionTypes. Chegou a hora de realizamos mudanças no estado da aplicação despachando ações através das ações do usuário.

Despachando actions

Vamos importar nossa store e o action creator changeStatus no módulo app/app.js. Despachamos atualizações no estado da aplicação através da função store.dispatch(). Ela recebe a action retornada pelo action creator changestatus. Lembre-se que isso chegará na cláusula switch de statusReducer, o reducer que foi utilizado para criar nossa store:

// app/app.js
import { store } from './store';
import { changeStatus } from './actions/status';

const statusParagraph = document.querySelector('.status');
document
.querySelector('.userName')
.oninput = e => {
    const userName = e.target.value;
    // changeStatus retorna uma action 
    // que é passada para store.dispatch
    store.dispatch(changeStatus(userName));
};

Excelente, mas como saberemos que o estado da aplicação mudou? Precisamos dessa informação para que possamos atualizar nossa página. Fazemos isso através da função store.subscribe(). Ela será chamada toda vez que a nossa store mudar:

// app/app.js
import { store } from './store';
import { changeStatus } from './actions/status';

const statusParagraph = document.querySelector('.status');
document
.querySelector('.userName')
.oninput = e => {
    const userName = e.target.value;
    store.dispatch(changeStatus(userName));
};

store.subscribe(() => {
    // obtemos o estado atual, depois da modificação
    const state = store.getState();
    // atualizamos o elemento com o novo valor
    statusParagraph.textContent = state.status;
});

Em uma aplicação com React, os componentes são conectados à store através da função connect do módulo react-redux, aquele que realiza uma ponte entre o Redux e o React, dispensando o uso de store.subscribe.

Quando o estado da aplicação for alterado, o callback passado para store.subscribe() será chamado. Nele, acessamos o estado atual da aplicação através de store.getState() para que possamos atualizar o elemento do DOM com valor atualizado de state.status.

Trabalhando com middlewares

Nosso código é funcional, inclusive podemos testar no navegador, mas para transcendermos nosso entendimento sobre o que esta acontecendo podemos ativar o middleware redux-logger. O redux-logger nos permitirá visualizar as actions que chegam aos reducers, inclusive o estado da aplicação antes e depois de modificado.

Ainda sobre middleware, seu conceito é o mesmo empregado no framework web Express.js. Nele, adicionamos um ou mais middlewares em sua pilha de middlewares e cada um deles lidará com a requisição passando o controle para o próximo middleware da pilha.

No caso do Redux, seus middlewares permitem adicionar um código específico entre o despacho da action e o momento que ela chega ao reducer.

Dentro da pasta project, vamos instalar o middleware:

npm install redux-logger@3.0.6 -S

Agora, em app/store.js vamos importar a função applyMiddeware do módulo redux. Essa função recebe uma quantidade indeterminada de middlewares que desejamos adicionar em uma pilha. Em seguida, vamos importar createLogger do módulo redux-logger para então ativá-lo em nossa store:

import { createStore, applyMiddleware } from 'redux';
import { statusReducer } from './reducers/statusReducer';
import { createLogger  } from 'redux-logger';

const middlewares = applyMiddleware(createLogger());
export const store = createStore(statusReducer, middlewares);

O segundo parâmetro de createStore é a pilha de middlewares que desejamos aplicar. Em nosso caso, teremos um niddleware apenas, o createLogger.

Agora, no navegador, com o aba do console aberta, podemos verificar que a cada dígito no <input> é exibida informações valiosas sobre o que esta ocorrendo com o estado da aplicação.

Lidando com o operações assíncronas

Vimos que side effects devem ser realizados em nossas actions e nunca dentro dos nossos reducers. Todavia, como faremos para lidar com operações assíncronas, por exemplo, requisições ajax? Nesse caso, nossos actions creator precisarão ser declarados de uma maneira especial.

Vamos simular uma operação assíncrona através de um setTimeout facilitando assim nosso teste sem dependermos de uma API para tal tarefa.

Nosso módulo app/actions/status.js ficará assim:

import * as types from '../constants/actionTypes.js';

export const changeStatus = text => {

    return dispatch => {

        setTimeout(() => dispatch(
            {
                type: types.CHANGE_STATUS,
                payload: text
            }
        ), 1000);
    };
};

O mesmo código pode ser reescrito dessa forma:

import * as types from '../constants/actionTypes.js';

export const changeStatus = text => 
    dispatch =>
        setTimeout(() => 
            dispatch({
                type: types.CHANGE_STATUS,
                payload: text
            })
        , 1000);

Nosso action creator não retornará mais um objeto, ele retornará uma função que ao ser chamada nos dará acesso ao dispatch. Sendo assim, como estamos retornando uma função, podemos executar dentro dela uma operação assíncrona. Quando ela terminar, despachamos a ação. No entanto, para que o código acima funcione, precisamos de um middleware especial. No caso, utilizaremos o redux-thunk.

Vamos instalá-lo através do terminal, ainda dentro da pasta project:

npm install redux-thunk@2.2.0 -S

Como todo middleware, ele precisa ser registrado em nossa store:

// project/store.js
import { createStore, applyMiddleware } from 'redux';
import { statusReducer } from './reducers/statusReducer';
import { createLogger  } from 'redux-logger';
// importou o novo middleware
import thunk from 'redux-thunk';
// adicionou o middleware thunk
const middlewares = applyMiddleware(thunk, createLogger());
export const store = createStore(statusReducer, middlewares);

Pronto. Basta recarregarmos nossa aplicação para verificarmos que tudo continua funcionando. Ao digitarmos no <input>, depois de um intervalo de tempo o username digitado será exibido no <p> como antes.

Time travel debugging

Através do Redux DevTools, uma extensão do Chrome, podemos gravar actions despachadas e o estado da store. Nessa linha de tempo, podemos verificar o estado da aplicação e viajar de volta no tempo para um estado anterior sem recarregarmos a página. Esse técnica de depuração é chamada de time travel debugging.

Não basta termos instalado o Redux DevTools no Google Chrome, precisamos realizar uma pequena configuração em nossa store para ligá-la à ferramenta de depuração.

Vamos alterar o módulo app/store.js:

// importou a função compose
import { createStore, applyMiddleware, compose } from 'redux';
import { statusReducer } from './reducers/statusReducer';
import { createLogger  } from 'redux-logger';
import thunk from 'redux-thunk';

// configuração especial
const middlewares = compose(
    applyMiddleware(thunk, createLogger()),
    window.devToolsExtension ? window.devToolsExtension() : f => f
);

export const store = createStore(statusReducer, middlewares);

A função compose é um utilitário para programação funcional e foi adicionada no módulo redux para facilitar a vida do desenvolvedor. O autor já falou sobre composição no artigo “Compondo funções em JavaScript”.

No código anterior, realizamos a composição do resultado da função applyMiddleware com um trecho de código que se conectará ao React DevTools caso ele tenha sido instalado como extensão do Chrome.

Vamos reduzir a tela do Chrome e reservar um espaço à esquerda. É nesse espaço que trabalharemos com o console do Redux DevTools. Para ativá-lo, vamos clicar com o botão direito na página e escolher a opção Redux DevTools->to Left.

Vamos digar duas letras no <input> da página. Inspecionando o console vemos as seguintes informações:

Visualizamos as actions disparadas em ordem cronológica, inclusive podemos verificar a mudança de estado da aplicação. Clicando na action a opção jump será exibida e, quando clicada, fará com que o estado da aplicação volte para o estado de quando aquela action foi executada:

É um recurso incrível que permite depurar a aplicação sem termos que reiniciá-la ou repetirmos determinada action manualmente através da interface da aplicação.

Dan Abramovich e uma proposta para substituir o Redux, o Future-Fetcher

Durante a JSConf 2018, Dan Abramovich, o criador do Redux, anunciou um substituto para Redux chamado Future-Fetcher. Pouco se sabe sobre sua implementação, a não ser que foi motivada pela debanda de desenvolvedores do Redux para soluções menos complexas como MobX. O objetivo de Dan com o Future-Fetcher é trazer de volta a simplicidade no gerenciamento de estado na plataforma JavaScript. Com certeza é algo que o leitor deve ficar de olho e que não esta muito longe de se concretizar.

Código no Github

Você encontra o código completo deste artigo no meu github.

Conclusão

O conceito do Redux é simples, o que pode complicar seu entendimento é a quantidade de artefatos envolvidos durante sua implementação e a relação entre eles. Frameworks do mercado oferecem módulos especializados para realizar a ponte entre eles e o módulo redux. E você? Já utiliza Redux em suas aplicações? Ele trouxe benefícios? Tornou mais complexo o projeto? Deixe sua opinião.

Suportando Decorators com vanilla JavaScript

2018-02-26T11:00:00+00:00

Não há suporte nativo a decorators na linguagem JavaScript (ano base 2018), apesar de existir formalmente uma proposta em andamento. Neste artigo Implementaremos uma solução padronizada para que possamos utilizar decorators com vanilla JavaScript hoje.

O problema

Temos a seguinte classe Person:

// app/models/person.js;
export class Person {

    constructor(name, surname) {
        this._name = name;
        this._surname = surname;
    }

    speak(phrase) {
        return `${this._name} is speaking... ${phrase}`
    }

    getFullName() {
        return `${this._name} ${this._surname}`;
    }
}

Queremos logar o tempo de execução dos métodos speak e getFullName. Uma solução é alterarmos os métodos adicionando todo o código necessário para cronometrar o tempo:

// app/models/person.js;
export class Person {

    constructor(name, surname) {
        this._name = name;
        this._surname = surname;
    }

    speak(phrase) {
        console.time('speak');
        const result = `${this._name} is speaking... ${phrase}`;
        console.timeEnd('speak');
        return result;
    }

    getFullName() {
        console.time('speak');
        const result = `${this._name} ${this._surname}`;
        console.timeEnd('speak');
        return result;
    }
}

Não precisamos meditar muito para verificarmos que duplicamos nosso código. Aliás, teríamos ainda mais código duplicado se outras classes da nossa aplicação precisassem cronometrar também a execução de seus métodos.

Uma solução é isolar o código duplicado em um único lugar e aplicá-lo aos métodos da classe. Aliás, outras linguagem já resolveram essa questão adicionando em sua sintaxe o suporte a decorators.

Decorators

Decorators são suportados nativamente em linguagens como Python, Java, C# e por outras linguagens, inclusive TypeScript. Em suma, um decorator nada mais é do que um trecho de código isolado aplicável em uma ou mais funções, inclusive em métodos de classe. A lógica a ser aplicada depende do problema a ser resolvido, mas o mais importante é que teremos essa lógica em um lugar apenas, evitando assim duplicação de código.

Vejamos a seguir um exemplo do uso de decorators na linguagem TypeScript.

TypeScript e decorators

Em TypeScript, podemos isolar um código e aplicá-lo em métodos de classes através da sintaxe @nomeDoDecorator:

// app/models/person.js;
export class Person {

    constructor(name, surname) {
        this._name = name;
        this._surname = surname;
    }

    @logExecutionTime
    speak(phrase) {
        return `${this._name} is speaking... ${phrase}`
    }

    @logExecutionTime
    getFullName() {
        return `${this._name} ${this._surname}`;
    }
}

A implementação da função logExecutionTime em TypeScript foi omitida, pois focaremos na implementação da nossa solução.

Será que podemos chegar a um resultado semelhante diretamente na linguagem JavaScript, inclusive sem o uso de um transcompilador como Babel? Vamos tentar.

Primeira solução

Pela característica dinâmica da linguagem JavaScript, podemos alterar diretamente no prototype de Person o método speak. Para isso, precisamos guardar o método original para então chamá-lo na nova função que o substituirá:

// app/app.js
import { Person } from './models/person.js';

// guardou o método original
const method = Person.prototype.speak;

// substitui o método por uma função
Person.prototype.speak = function (...args) {
    console.log(`Argumentos do método: ${args}`);
    console.time('speak');
    // executa o código original
    const result = method.bind(this)(...args);
    console.log(`Resultado do método: ${result}`);
    console.timeEnd('speak');
    return result;
};

const person = new Person('Flávio', 'Almeida');
person.speak('Canganceiro JavaScript');

Foi utilizada a sintaxe de carregamento nativo de módulos suportado pelo Google Chrome. Saiba mais no artigo “Importação nativa de módulos no browser”, deste mesmo autor.

Vamos analisar o código. Guardarmos uma referência para o método definido no prototype da classe Person na variável method.

Não esqueça que ao declararmos uma classe com a sintaxe class as definições de seus métodos são adicionadas em seu prototype. É por isso que acessarmos Person.prototype.speak e não Person.speak.

Com o método original guardado, substituímos Person.prototype.speak por uma função que redefiná o método. Ela recebe um número indeterminado de parâmetros através do Rest operator, pois não sabemos quantos parâmetros o método original recebe.

Vale ressaltar que utilizamos uma função no lugar de uma arrow function pois necessitamos de um escopo dinâmico, isto é, precisamos que o this seja a instância que invoca o método naquele momento.

Dentro da função que define o novo método, executamos um código arbitrário antes e depois da chamada do método original, todavia, um trecho de código merece destaque:

const result = method.bind(this)(...args);

Através de method.bind(this) criamos uma nova referência para o método original que tem como contexto o this da nova função. Lembre-se que esse this referenciará a instância que estiver invocando o novo método. Em seguida, passamos através do spread operator cada parâmetro recebido no array args como parâmetros individuais para a função.

Executando nosso código, a saída do console será:

Método chamado com os parâmetros: Canganceiro JavaScript
Resultado do método: Flávio is speaking... Canganceiro JavaScript
speak: 0.494873046875ms

Excelente, mas essa estratégia deixa a desejar. Lembrem-se que precisamos aplicar a mesma lógica ao método getFullName e em outras classes quando necessário. Sendo assim, precisamos padronizar nossa solução em algo que seja fácil de usar pelos demais desenvolvedores da equipe.

Isolando decorators e definindo uma API

Para facilitar a vida do desenvolvedor, queremos a seguinte solução:

// app/app.js
import { Person } from './models/person.js';
// as demais funções ainda não existem!
import { decorate } from './utils/decorate.js';
import { logExecutionTime } from './models/decorators.js';

decorate(Person, {
    speak: logExecutionTime, 
    getFullName: logExecutionTime
});

const person = new Person('Flávio', 'Almeida');
person.speak('Canganceiro JavaScript');

Na solução que acabamos de ver temos a função utilitária decorate receberá dois parâmetros. O primeiro é a classe que desejamos decorar seus métodos. O segundo é o objeto handler. As propriedades do objeto handler equivalem aos nomes dos métodos que desejamos decorar na classe. Seu valor será o decorator que desejamos aplicar.

Vamos dar uma olhada na implementação do decorator logExecutionTime:

// app/models/decorators.js 
export const logExecutionTime = (method, property, args) => {
    console.log(`Método decorado: ${property}`);
    console.log(`Argumentos do método ${args}`);
    console.time(property);
    const result = method(...args);
    console.timeEnd(property);
    console.log(`resultado do método: ${result}`)
    return result;
};

É a função utilitária decorate que passará os parâmetros que nosso decorator precisa. Em ordem, esses parâmetros são:

O método original a ser decorado, com seu contexto já modificado
O nome do método
Os parâmetros que o método recebe (ou não)

O mais interessante é que definimos uma API para criação de decorators. Essa padronização é importante, pois permitirá que a solução seja utilizada por outros desenvolvedores mais facilmente. Sabendo o que cada parâmetro representa, fica fácil entender a lógica do nosso decorator.

A grande questão agora é a implementação da função utilitária decorate, centro nervoso da nossa solução.

Implementando a função decorate

Vamos criar o módulo app/utils/decorate.js. Nele declararemos a função decorate que receberá a clazz e o handler:

// app/utils/decorate.js
export const decorate = (clazz, handler) => // falta o resto

A primeira coisa que faremos é listar todas as chaves do objeto handler, pois são elas que indicam qual método decorar da classe.

Todavia, só podemos iterar nas propriedades do próprio objeto handler (aquelas que adicionamos ao criá-lo) e não do seu prototype, no caso Object. Se iteramos nas propriedades do prototype acabaremos encontrando outras chaves que não dizem respeito aos métodos que desejamos decorar. A função Object.keys() nos atende muito bem:

// app/utils/decorate.js
export const decorate = (target, handler) => 
    // retorna todas as propriedades enumeráveis do objeto
    Object.keys(handler).forEach(property => {
        // falta implementar     
    });

Em cada iteração precisaremos guardar o método original, um dos parâmetros que nossos decorators dependem:

// app/utils/decorate.js
export const decorate = (target, handler) => 
    Object.keys(handler).forEach(property => {
        const method = clazz.prototype[property];
    });

Armazenamos na variável method uma referência para o método que será decorado. Agora precisamos fazer a mesma coisa, mas dessa vez para armazenar o decorator do método:

// app/utils/decorate.js
export const decorate = (target, handler) => 
    Object.keys(handler).forEach(property => {
        const method = clazz.prototype[property];
        const decorator = handler[property];
    });

Ótimo! Só precisamos modificar o método original da classe para que invoque nosso decorator. Lembrando que o decorator receberá como parâmetro uma referência para o método original, inclusive já associado ao this da função que substituiu o método na classe:

// app/utils/decorate.js
export const decorate = (clazz, handler) => {
    Object.keys(handler).forEach(property => {
        const method = clazz.prototype[property];
        const decorator = handler[property];
        // Adiciona novo método que ao ser chamado 
        // chamará o decorator por debaixo dos panos
        clazz.prototype[property] = function (...args) {
            return decorator(method.bind(this), property, args);
        };  
    });    
};

Excelente, o código que escrevemos até agora é suficiente para que nosso decorator seja aplicado. Mas se quisermos aplicar mais de um decorator por método?

Métodos com mais de um decorator

O decorator logExecutionTime esta com muita responsabilidade. Extrairemos dele o código que loga os dados da função como o seu nome, parâmetros recebidos e seu retorno em um novo decorator que chamaremos de inspectMethod:

Alterando app/models/decorators.js:

// app/models/decorators.js
export const logExecutionTime = (method, property, args) => {
    console.time(property);
    const result = method(...args);
    console.timeEnd(property);
    return result;
};

export const inspectMethod = (method, property, args) => {
    console.log(`Método decorado: ${property}`);
    console.log(`Argumentos do método ${args}`);
    const result = method(...args);
    console.log(`resultado do método: ${result}`)
    return result;
};

Reparem que nossos decorators seguem a mesma API, fantástico!

Agora, alterando app/app.js para fazer uso do nosso novo decorator:

import { Person } from './models/person.js';
import { decorate } from './utils/decorate.js';
import { logExecutionTime, inspectMethod } from './models/decorators.js';

// passando um array de decorators
decorate(Person, {
    speak: [inspectMethod, logExecutionTime],
    getFullName: [logExecutionTime]
});

const person = new Person('Flávio', 'Almeida');
person.speak('Canganceiro JavaScript');

Recebemos um erro no console:

Uncaught TypeError: decorator is not a function
    at Person.clazz.(anonymous function)

Infelizmente a função decorate não esta preparada para lidar com um Array de decorators. Precisamos alterá-la para que funcione:

// app/utils/decorate.js
export const decorate = (clazz, handler) => {
    Object.keys(handler).forEach(property => {
        const decorators = handler[property];
        decorators.forEach(decorator => {
            // o método já pode ter sido decorado antes
            const method = clazz.prototype[property];
            clazz.prototype[property] = function (...args) {
                return decorator(method.bind(this), property, args);
            };  
        });
    });    
};

Excelente, agora podemos combinar decorators em um mesmo método.

Ordem dos decorators

Se analisarmos atentamente a aplicação dos decorators, veremos que são aplicados da direita para a esquerda. Para facilitar o entendimento, vamos alterar nosso código para que o primeiro decorator da lista seja o primeiro a ser aplicado e assim por diante.

// app/util/decorate.js
export const decorate = (clazz, handler) => {

    Object.keys(handler).forEach(property => {
        // faz reverse
        const decorators = handler[property].reverse();
        decorators.forEach(decorator => {
            const method = clazz.prototype[property];
            clazz.prototype[property] = function (...args) {
                return decorator(method.bind(this), property, args);
            };  
        });
    });    
};

Agora, vamos alterar a ordem dos decorators em app/app.js:

// app/app.js
// código anterior omitido 
// agora aplicará da esquerda para a direita
decorate(Person, {
    speak: [logExecutionTime, inspectMethod],
    getFullName: [logExecutionTime]
});
// código posterior omitido

Agora fica mais fácil para quem lê o código entender a ordem de aplicação dos decorators.

Tudo excelente, mas se nosso decorator precisar receber uma configuração incial?

Decorators que recebem parâmetros

Criamos o decorator inspectMethod, mas nem sempre queremos logar o resultado do método, apenas seus parâmetros. Podemos atender a este requisito facilmente. Primeiro, vamos alterar o decorator inspectMethod:

export const inspectMethod = ({ excludeReturn } = {}) => 
    (method, property, args) => {
        console.log(`Método decorado: ${property}`);
        console.log(`Argumentos do método ${args}`);
        const result = method(...args);
        if(!excludeReturn) console.log(`resultado do método: ${result}`)
        return result;
    };

Vejam que nosso decorator recebe como parâmetro um objeto JavaScript que ao sofrer o destructuring disponibilizará a variável excludeReturn, utilizada para controlar a exibição da variável result. Por fim, o retorno do decorator será a função que adere à API que define nossos decorators.

Alterando o módulo app/app.js:

import { Person } from './models/person.js';
import { decorate } from './utils/decorate.js';
import { logExecutionTime, inspectMethod } from './models/decorators.js';

decorate(Person, {
    speak: [inspectMethod({ excludeReturn: true }), logExecutionTime],
    getFullName: [logExecutionTime]
});

const person = new Person('Flávio', 'Almeida');
person.speak('Canganceiro JavaScript');
person.getFullName();

Se não passarmos parâmetro nenhum para inspectMethod o padrão continuará sendo inspecionar o retorno do método.

Podemos tornar ainda melhor a maneira pela qual aplicamos nossos decorators.

Aplicando o decorator diretamente na definição da classe:

É possível decorar a classe diretamente no módulo no qual foi declarada. Vamos alterar app/models/person.js:

import { decorate } from '../utils/decorate.js';
import { logExecutionTime, inspectMethod } from './decorators.js';

export class Person {

    constructor(name, surname) {
        this._name = name;
        this._surname = surname;
    }

    speak(phrase) {
        return `${this._name} is speaking... ${phrase}`
    }

    getFullName() {
        return `${this._name} ${this._surname}`;
    }
}

decorate(Person, {
    speak: [inspectMethod({ excludeReturn: true }), logExecutionTime],
    getFullName: [logExecutionTime]
});

Por fim, nosso nódulo app/app.js ficará dessa forma:

// app/app.js
import { Person } from './models/person.js';

const person = new Person('Flávio', 'Almeida');
person.speak('Canganceiro JavaScript');
person.getFullName();

Nosso módulo dependerá dos decorators e da função decorate. Se o JavaScript suportasse nativamente decorators, dependeríamos apenas dos decorators, além de podermos aplicá-los com a sintaxe @, aliás, muito sexy.

Código no Github

Você encontra o código completo deste artigo no meu github.

Conclusão

Apesar de o suporte a decorator ter sido especificado na linguagem JavaScript, ainda não há um consenso sobre sua implementação. Alguns frameworks do mercado, inclusive a linguagem TypeScript suportam este recurso com sintaxe @, a mesma utilizada na linguagem Python que há anos suporta nativamente este recurso. Todavia, nada nos impede de implementá-lo em vanilla JavaScript. E você? Deixe sua opnião!

IndexedDB, implementando a persistência com o pattern Active Record

2018-02-19T11:00:00+00:00

No artigo “IndexedDB, implementando a persistência com o pattern Data Mapper” implementamos o padrão de projeto Data Mapper para persistir objetos com o IndexedDB. Desta vez, implementaremos a solução de persistência com o pattern Active Record.

O problema

Nossa aplicação define as classes Person e Animal:

// app/person.js
export class Person {
    constructor(name) {
        this._name = name;
    }

    get name() {
        return this._name;
    }
}
// app/animal.js
export class Animal {
    constructor(name) {
        this._name = name;
    }

    get name() {
        return this._name
    }
}

Precisamos persistir instâncias dessas classes no IndexedDB, um banco de dados presente nos navegadores do mercado:

// app/app.js
import { Person } from './Person.js';
import { Animal } from './Animal.js';

const person = new Person('Flávio Almeida');
const animal = new Animal('Calopsita');
// como realizar a persistência no banco IndexedDB?

Podemos obter uma conexão do banco, criar transações e lidar com a persistência no módulo app/app.js, mas queremos uma solução que facilite a vida do desenvolvedor e que também possa ser reutilizada pela aplicação. Nesse sentido, podemos aplicar o padrão de projeto Active Record.

O padrão de projeto Active Record

Segundo Martin Fowler:

“Um objeto traz dados e comportamento. Grande parte desses dados é persistente e precisa ser armazenado em um banco de dados. O Active Record usa a abordagem mais óbvia, colocando lógica de acesso a dados no objeto de domínio. Desta forma, todas as pessoas sabem como ler e escrever seus dados de e para o banco de dados”. - Patterns of Enterprise Application Architecture.

Vamos criar uma API que implemente o pattern Active Record com a finalidade de isolar a complexidade de persistência com o IndexedDB. Depois de pronta, ela funcionará dessa maneira:

// app/app.js
import { activeRecord } from './active-record.js';
import { Person } from './Person.js';
import { Animal } from './Animal.js';

(async () => {
    await activeRecord({
        name: 'cangaceiro',
        version: 2, 
        mappers: [
            { 
                clazz: Person,
                converter: data => new Person(data._name)
            },
            { 
                clazz: Animal,
                converter: data => new Animal(data._name)
            }
        ]
    });
        
    const person = new Person('Flávio Almeida');
    const animal = new Animal('Calopsita');
    // As instâncias sabem se persistir
    await person.save();
    await animal.save();
    // Operações que não operam diretamente em instâncias 
    // são invocadas através de métodos estáticos da classe
    const persons = await Person.list();
    persons.forEach(console.log);

    const animals = await Animal.list();
    animals.forEach(console.log);

})().catch(console.log);

O padrão Active Record tem uma forte relação com bancos relacionais. Todavia, nada nos impede de ampliarmos seu uso para bancos noSQL ou orientados a documentos. Por mais que a estrutura de dados desses bancos seja semelhante ao JSON, ainda há impedância (discrepância) entre os dados armazenados no banco (dado) e os mesmos dados em memória (dado e comportamento).

A função activeRecord receberá um objeto com as configurações necessárias para nossa solução de persistência e retornará uma Promise. Sobre as propriedades de configuração temos:

name: define o nome do banco. Quando omitida será adotado como nome a string “default”.
version: define a versão do banco. Quando omitida será adotado 1 como versão.
mappers: contém uma lista de objetos de mapeamento com as propriedades clazz e converter. A primeira recebe a classe que terá uma store criada no banco. A segunda é a lógica de mapeamento dos dados retornados do banco para sua respectiva classe que será utilizada pelo método list().

Internamente, activeRecord criará as stores do banco, inclusive é durante a chamada desta função que o prototype das classes definidas na lista de mappers será modificado para incluir a operação de persistência save(). Já o método list() será adicionado como método estático na própria classe.

Diferente do post deste mesmo autor sobre a implementação de uma solução de persistência através do pattern Data Mapper, o autor decidiu abdicar do pattern Builder utilizado para atribuir as configurações de persistência. O motivo é que passar um objeto como configuração é muito menos verboso e cumpre seu papel indicando as propriedades de configuração.

Sobre os métodos de persistências temos:

save: persiste a instância do objeto no qual o método foi invocado. Internamente identifica a classe a qual o objeto pertence para decidir em qual store deve ser salvo. Retorna uma Promise.
list: método estático da classe que internamente identifica sua respectiva store retornando os dados persistidos. Faz uso do converter para guiar o processo de transformação dos dados armazenados em instâncias da classe.

Um ponto a se destacar é que podemos usar a mesma conexão durante toda a aplicação sem que seja necessário fechá-la.

Agora que já sabemos até onde queremos chegar, vamos dar início a nossa implementação.

Implementando a função activeRecord

Vamos criar o módulo app/active-record.js que terá em seu escopo o objeto dbConfig. Suas propriedades serão inicializadas com valores padrões. Em seguida, definiremos a função activeRecord que terá acesso ao objeto dbConfig. A função activeRecord será o único artefato exportado pelo módulo active-record.js:

// app/active-record.js
// configuração do banco encapsuladas no módulo
const dbConfig = {
    name: 'default',
    version: 1,
    stores: new Map()
};

export const activeRecord = ({ name, version, mappers }) => {
    // passou as configurações para o objeto dbConfig
    dbConfig.version = version;
    dbConfig.name = name;
    // processa a lista de mappers
    mappers.forEach(mapper => 
        dbConfig.stores.set(mapper.clazz.name, mapper.converter)
    );
};

Atribuímos às propriedades dbConfig.version e dbConfig.name a versão do banco e seu nome respectivamente. Por fim, para cada item da lista de mappers recebida utilizaremos o valor da propriedade clazz.name como key e o valor da propriedade converter como seu valor no Map dbConfig.stores. Esse dado é importante, pois é através dele que saberemos quais stores serão criadas e qual lógica de conversão será utilizada ao obter seus dados.

Objetos recuperados da store só possuem propriedades e nenhum método, por isso é importante definir a lógica de conversão dos dados trazidos do banco para sua respectiva classe.

Vamos criar a página index.html que importará o módulo app/app.js utilizando o sistema de importação de módulos nativo do Chrome:

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Active Record</title>
</head>
<body>
<!-- importou o módulo -->
<script type="module" src="app/app.js"></script>
</body>
</html>

É necessário servir a página através de um servidor Web de sua escolha, caso contrário o carregamento dos módulos não funcionará.

Vejamos como fica o uso inicial da função activeRecord no módulo app/app.js:

// app/app.js
import { activeRecord } from './active-record.js';

activeRecord({
    name: 'cangaceiro',
    version: 2, 
    mappers: [
        { 
            clazz: Person,
            converter: data => new Person(data._name)
        },
        { 
            clazz: Animal,
            converter: data => new Animal(data._name)
        }
    ]
});

Todos os módulos que importarem nosso activeRecord trabalharão com a mesma instância.

Excelente, mas no ato de passarmos as configurações para a função activeRecord precisamos criar a conexão com o banco.

Obtendo uma conexão

Vamos criar uma função responsável pela criação da conexão. Ela viverá no escopo do módulo active-record.js e apenas o objeto activeRecord poderá acessá-la.

Como a obtenção de uma conexão é uma operação assíncrona, retornaremos uma Promise como resposta, reduzindo assim a complexidade de termos que trabalhar com callbacks.

Vamos criar a propriedade conn no objeto dbConfig. Ela guardará uma referência para a conexão criada. Seu valor será atribuído através da função createConnection:

// app/active-record.js
const dbConfig = {
    name: 'default',
    version: 1,
    stores: new Map(), 
    conn: null // nova propriedade
};

const createConnection = () => 
    new Promise((resolve, reject) => {
    
    });

// definição da função activeRecord omitida

Vamos solicitar à função indexedDB.open() a abertura da conexão com o banco usando as configurações definidas em dbConfig.name e dbConfig.version. Porém, não temos a garantia de que a conexão foi efetuada, motivo pelo qual precisamos lidar com os eventos onupgradeneeded, onsuccess e onerror:

// app/active-record.js
const dbConfig = {
    name: 'default',
    version: 1,
    stores: new Map(), 
    conn: null
};

const createConnection = () => 
    new Promise((resolve, reject) => {
        // requisitamos a abertura, um evento assíncrono!
        const request = indexedDB.open(dbConfig.name, dbConfig.version);

        request.onupgradeneeded = e => {};

        request.onsuccess = e => {};

        request.onerror = e => {};
    });

// código posterior omitido

O evento onupgradeneeded disponibiliza uma conexão transacional que nos permite criar todas as stores do banco. Utilizaremos as chaves do nosso Map stores como nome das stores:

//app/active-record.js
const dbConfig = {
    name: 'default',
    version: 1,
    stores: new Map(), 
    conn: null
};

const createConnection = () => 
    new Promise((resolve, reject) => {

        const request = indexedDB.open(dbConfig.name, dbConfig.version);

        request.onupgradeneeded = e => {

            const transactionalConn = e.target.result;
            // utilizando for...of e destructuring ao mesmo tempo
            // para ter acesso facilitado à key do Map
            for (let [classKey] of dbConfig.stores) {
                const store = classKey;
                // se já existe, apagamos a store
                if(transactionalConn.objectStoreNames.contains(store)) 
                    transactionalConn.deleteObjectStore(store);
                transactionalConn.createObjectStore(store, { autoIncrement: true });
            }     
        };

        request.onsuccess = e => {
            dbConfig.conn = e.target.result; // guarda uma referência para a conexão
            resolve(); // tudo certo, resolve a Promise!
        }
        // lida com erros, retornando uma mensagem de alto nível
        request.onerror = e => {
            console.log(e.target.error);
            reject('Não foi possível obter a conexão com o banco');
        }; 
    });
// código posterior omitido

A estratégia utilizada durante um eventual upgrade do banco é derrubar todas as stores para em seguida criá-las novamente.

Excelente, agora precisamos chamar a função createConnection através da função ActiveRecord. Vamos tornar a função async para que possamos utilizar a instrução await com a Promise retornada por createConnection:

// app/active-record.js

// código anterior omitido

// tornou a função async
export const activeRecord = async ({ name, version, mappers }) => {
 
    dbConfig.version = version;
    dbConfig.vame = name;
    
    mappers.forEach(mapper => 
        dbConfig.stores.set(mapper.clazz.name, mapper.converter)
    );
    // awaitter na função createConnection
    await createConnection();
}

Agora, em app/app.js, criaremos um wrapper async para que possamos utilizar a instrução await com o método register:

// app/app.js
import { activeRecord } from './active-record.js';
import { Person } from './Person.js';
import { Animal } from './Animal.js';
// wrapper async
import { activeRecord } from './active-record.js';
import { Person } from './Person.js';
import { Animal } from './Animal.js';

(async () => {
    await activeRecord({
        name: 'cangaceiro',
        version: 2, 
        mappers: [
            { 
                clazz: Person,
                converter: data => new Person(data._name)
            },
            { 
                clazz: Animal,
                converter: data => new Animal(data._name)
            }
        ]
    });

})().catch(console.log);

Recarregando a página index.html no Chrome, na aba Application -> Storage -> IndexedDB podemos constatar a criação do banco.

Abra outra aba no Chrome para que possa verificar os dados mais atualizados, pois este autor constatou que o Chrome não realiza o refresh automático da aba Application -> Storage -> IndexedDB.

Agora vamos implementar o método save.

Implementando a função save

A função save da nossa classe ActiveRecord também retornará uma Promise, pois a operação de persistência também é uma operação assíncrona:

// app/active-record.js
const dbConfig = {
    name: 'default',
    version: 1,
    stores: new Map(), 
    conn: null
};

const createConnection = () => 
    // código omitido
);

const save = async function() {

    return new Promise((resolve, reject) => {

        if(!dbConfig.conn) return reject('Você precisa registrar o banco antes de utilizá-lo');

        const object = this;
        const store = this.constructor.name;
        
        const request = dbConfig.conn
            .transaction([store],"readwrite")
            .objectStore(store)
            .add(object);
    
        request.onsuccess = () => resolve();

        request.onerror = e => {
            console.log(e.target.error);
            reject('Não foi possível persistir o objeto');
        };
    });
};

// função activeRecord omitida

Vamos analisar o código anterior. A Promise retornada verifica se a variável dbConfig.conn possui algum valor e caso não possua, rejeitamos a Promise imediatamente. Esse fail fast é importante, pois sinalizará para o desenvolvedor que ele deve realizar antes o registro do banco. O restante do código é padrão da API do IndexedDB.

Agora chegou a hora de implementarmos a função list(), aquela que retornará os dados persistidos.

Implementando o método list

Assim como a função save(), a função list() retornará uma Promise. Ele receberá como parâmetro uma classe e, a partir dela, extrairá o nome da sua respectiva store. Sabemos que o nome da store é a key do Map stores. É através dessa key que temos acesso a lógica de conversão, aquela que sabe converter os dados retornados da store para uma instância da sua respectiva classe.

// app/active-record.js
// código anterior omitido 

const list = async function() {
        
    return new Promise((resolve, reject) => {
    
        const store = this.name;
        
        const transaction = dbConfig.conn
            .transaction([store],'readwrite')
            .objectStore(store); 
        
        const cursor = transaction.openCursor();
    
        const converter = dbConfig.stores.get(store);
    
        const list = [];
    
        cursor.onsuccess = e => {

            const current = e.target.result;

                if(current) {
                    list.push(converter(current.value));
                    current.continue();
            } else resolve(list);
        };

        cursor.onerror = e => {
            console.log(target.error);
            reject(`Não foi possível lista os dados da store ${store}.`);
        };  
    });    
}

Ótimo, para concluirmos o módulo active-record.js, precisamos adicionar a função save como método no prototype das classes que representarão nossas stores para que esteja disponível em todas as instâncias dessas classes. Já o a função list() será adicionada na própria classe, como método estático. Realizamos os passos que faltam na função activeRecord:

// app/active-record.js
// código anterior omitido 
export const activeRecord = async ({ name, version, mappers }) => {
 
    dbConfig.version = version;
    dbConfig.name = name;
    
    mappers.forEach(mapper => {
        dbConfig.stores.set(mapper.clazz.name, mapper.converter);
        // Adiciona save ao proprotype da classe para 
        // que esteja disponível em todas as instâncias
        // da classe.
        mapper.clazz.prototype.save = save;
        // Adiciona list diretamente na classe como método estático
        mapper.clazz.list = list;
    });

    await createConnection();
}

Excelente, nosso módulo app/app.js ficará assim:

import { activeRecord } from './active-record.js';
import { Person } from './Person.js';
import { Animal } from './Animal.js';

(async () => {
    await activeRecord({
        name: 'cangaceiro',
        version: 2, 
        mappers: [
            { 
                clazz: Person,
                converter: data => new Person(data._name)
            },
            { 
                clazz: Animal,
                converter: data => new Animal(data._name)
            }
        ]
    });
        
    const person = new Person('Flávio Almeida');
    const animal = new Animal('Calopsita');

    // salva o método da instância
    await person.save();
    await animal.save();

    // chama o método estático
    const persons = await Person.list();
    persons.forEach(console.log);

    const animals = await Animal.list();
    animals.forEach(console.log);

})().catch(console.log);

Melhor organizado do que se tivéssemos utilizado diretamente a API do IndexedDB. Você pode conferir o código completo deste artigo no meu github.

Conclusão

O padrão de projeto Active Record pode ser aplicado não apenas com o IndexedDB, mas qualquer meio de persistência, inclusive banco de dados utilizados por API.

E você? Já utilizou alguma biblioteca que faz uso desse padrão? Como lidava com persistência no IndexedDB? Deixe sua opinião.

Suportando Method Chaining em uma API já existente

2018-02-12T11:00:00+00:00

Neste artigo aprendemos a suportar Method Chaining em uma API sem suporte a esse recurso.

O Problema

O IndexedDB disponibiliza uma API para que possamos persistir objetos. Vejamos um trecho desta API em ação:

// conexão criada com o banco antes
const store = 'books';
object = { name: 'Cangaceiro JavaScript', isbn: 9788594188014 };

const request = connection
    .transaction([store],"readwrite")
    .objectStore(store)
    .add(object);
        
request.onsuccess = () => console.log('persistiu com sucesso');

request.onerror = e => console.log(e.target.error);

Queremos encadear as chamadas de onsuccess e onerror. Em outras palavras, queremos o suporte à Method Chaining. Mas para que isso seja possível, precisamos criar uma requisição encadeável. Por padrão, o IndexedDB não suporta requisições que suportem chaining, no entanto, podemos criar um wrapper que encapsule a requisição e permita utilizar o recurso desejado:

// conexão criada com o banco antes
const store = 'books';
object = { name: 'Cangaceiro JavaScript', isbn: 9788594188014 };

// cria um wrapper a partir da requisição
ChainableRequest.of(connection
    .transaction([store],"readwrite")
    .objectStore(store)
    .add(object)
).success(() => console.log('persistiu com sucesso'))
).error(e => console.log(e.target.error))

No código anterior temos a chamada de ChainableRequest.of(), mas a classe ChainableRequest não existe. Precisamos implementá-la.

Implementando a classe ChainableRequest.

A classe ChainableRequest receberá em seu constructor o objeto request que encapsulará:

class ChainableRequest {

    constructor(request) {
        this._request = request;
    }
}

A classe ChainableRequest é um wrapper que encapsula o objeto original.

Excelente, mas do jeito que construímos nossa classe, precisaremos utilizar o operador new para criar instâncias de ChainableRequest. Podemos evitar o uso do operador através do método estático of:

class ChainableRequest {

    constructor(request) {
        this._request = request;
    }

    static of(request) {
        return new ChainableRequest(request);
    }
}

Da maneira que organizamos o código é o próprio método of() que se encarregará de criar a instância de ChainableRequest lidando com o operador new. Vamos continuar nossa implementação.

Criando métodos que retornam a própria instância

Vamos criar um método para cada propriedade de uma requisição do IndexedDB:

class ChainableRequest {

    constructor(request) {
        this._request = request;
    }

    static of(request) {
        return new ChainableRequest(request);
    },

    success(fn) {
        this._request.onsuccess = fn;
        return this;
    }

    error(fn) {
        this._request.onerror = fn;
        return this;
    }
}

Vejam que os métodos success e error recebem a lógica que será aplicada nas respectivas propriedades _request.onsuccess e _request.onerror. Todavia, o retorno de ambos é a própria instância de ChainableRequest. É esse retorno que permitirá as chamadas encadeadas. Com a classe completa, o código proposto no início deste artigo funcionará:

// conexão criada com o banco antes
const store = 'books';
object = { name: 'Cangaceiro JavaScript', isbn: 9788594188014 };
ChainableRequest.of(connection
    .transaction([store],"readwrite")
    .objectStore(store)
    .add(object)
).success(() => console.log('persistiu com sucesso'))
).error(e => console.log(e.target.error))

O ganho na legibilidade pode ser ainda maior dependendo da quantidade de métodos encadeáveis utilizados para resolver o problema em questão.

Conclusão

Não é pelo fato de uma API não ser encadeável que ela nos privará desse recurso. Com um pouco de código podemos criar uma pequena camada sob a API já existente possibilitando chamadas encadeáveis.

E você? Já aplicou essa estratégia antes? Tem algum exemplo de outra API no qual essa estratégia se torna ainda mais interessante. Deixe seu comentário.

IndexedDB, implementando a persistência com o pattern Data Mapper

2018-02-05T12:00:00+00:00

Os navegadores do mercado suportam o banco de dados IndexedDB, especificado pela W3C. Todavia, realizar operações de persistência através de sua API é uma tarefa um tanto árdua. Neste artigo implementaremos o padrão de projeto Data Mapper para reduzir bastante a complexidade da API do IndexedDB. É necessário que o leitor tenha algum conhecimento desta API para que aproveite melhor este artigo.

Prólogo

A motivação para a escrita deste artigo veio de um coding dojo no qual o autor foi questionado por um dos participantes o motivo de não ter abordado o pattern Data Mapper em seu livro Cangaceiro JavaScript, uma aventura no sertão da programação. Como resposta lhe foi dito que nas mais de 500 páginas do livro inevitavelmente algum assunto teria que ficar de fora. Foi então que o participante perguntou se era possível implementá-lo durante o dojo, tarefa que foi aceita por este autor e implementada em 7 minutos.

É importante frisar que a implementação foi realizada em 7 minutos, porém as discussões sobre a API a ser criada levaram aproximadamente 20 minutos. Outro ponto é que apenas as operações de persistência save() e list() foram implementadas.

Agora que já sabemos os eventos que antecederam a escrita deste artigo, vamos ao problema a ser resolvido.

O problema

Nossa aplicação define as classes Person e Animal:

// app/person.js
export class Person {
    constructor(name) {
        this._name = name;
    }

    get name() {
        return this._name;
    }
}
// app/animal.js
export class Animal {
    constructor(name) {
        this._name = name;
    }

    get name() {
        return this._name
    }
}

Precisamos persistir instâncias dessas classes no IndexedDB, um banco de dados presente nos navegadores do mercado:

// app/app.js
import { Person } from './Person.js';
import { Animal } from './Animal.js';

const person = new Person('Flávio Almeida');
const animal = new Animal('Calopsita');
// como realizar a persistência no banco IndexedDB?

O padrão de projeto Data Mapper

Segundo a Wikipedia um Data Mapper é uma camada de acesso a dados que executa transferência bidirecional de dados entre um armazenamento de dados persistente e uma representação de dados na memória. Quanto maior a impedância entre esses dois mundos, maior trabalho o Data Mapper terá que realizar.

Impedância é a discrepância entre os dados em memória e os mesmos dados armazenados no banco.

Vamos criar uma API que isole a complexidade de persistência com o IndexedDB. Depois de pronta, ela funcionará dessa maneira:

// app/app.js
import { manager } from './manager.js';
import { Person } from './Person.js';
import { Animal } from './Animal.js';

(async () => {
    // configuração mínima
    await manager
        .setDbName('cangaceiro')
        .setDbVersion(2) 
        .register(
            { 
                clazz: Person,
                converter: data => new Person(data._name)
            },
            { 
                clazz: Animal,
                converter: data => new Animal(data._name)
            }
        );

    // criando instâncias
    const person = new Person('Flávio Almeida');
    const animal = new Animal('Calopsita');

    // persistindo dados
    await manager.save(person);
    await manager.save(animal);

    // buscando dados persistidos
    const persons = await manager.list(Person);
    persons.forEach(console.log);
    const animals = await manager.list(Animal);
    animals.forEach(console.log);

})().catch(console.log);

Sobre os métodos do objeto manager, nosso Data Mapper, temos:

setDbName: define o nome do banco de dados. Quando omitido, será adotado o nome “default”. Seu retorno será uma referência para a própria instância de manager.
setDbVersion: define a versão o banco. Quando informado uma versão superior a vigente, todas as stores serão destruídas e criadas novamente. Quando não informado, o valor 1 será o padrão utilizado. Seu retorno será uma referência para a própria instância de manager.
register: recebe uma lista de objetos de mapeamento com as propriedades clazz e converter. A primeira recebe a classe que terá uma store criada no banco. A segunda é a lógica de mapeamento dos dados retornados do banco para sua respectiva classe que será utilizado pelo método list(). As stores serão criadas apenas quando o banco for criado pela primeira vez ou quando a versão informada por setDbVersion for superior a versão vigente do banco. Seu retorno será uma Promise.
save: recebe a instância do objeto que desejamos persistir. Internamente identifica a classe a qual o objeto pertence para decidir em qual store deve ser salvo. Retorna uma Promise.
list: recebe como primeiro parâmetro a classe que representa a store que desejarmos obter todos os seus dados armazenados.

Um ponto a se destacar é que podemos usar a mesma conexão durante toda a aplicação sem que seja necessário fechá-la.

Agora que já sabemos até onde queremos chegar, vamos dar início a nossa implementação.

Implementando nosso manager

Vamos criar o módulo app/manager.js que terá em seu escopo as variáveis dbName e dbVersion, ambas inicializadas com valores padrões. Em seguida, definiremos a classe Manager com métodos acessadores para essas variáveis encapsuladas pelo módulo. No lugar de exportarmos a classe Manager, vamos exportar uma instância dessa classe:

// app/manager.js
// variáveis encapsuladas pelo módulo

let dbName = 'default';
let dbVersion = 1;

class Manager {

    setDbName(name) {
        dbName = name;
        // retorna a própria instância
        return this; 
    }

    setDbVersion(version) {
        dbVersion = version;
        // retorna a própria instância
        return this; 
    }
}
// exporta a instância da classe
export const manager = new Manager();

Declarar uma variável no escopo do módulo sem exportá-la com a instrução export torna sua visibilidade privada, desta forma, apenas a instância de manager exportada pelo módulo terá acesso à variável, como é o caso das variáveis dbName e dbVersion.

Um ponto a destacar é o return this dos métodos da classe que criamos até agora. É esse retorno que permitirá o encadeamento das chamadas desses métodos.

Vamos criar a página index.html que importará o módulo app/app.js utilizando o sistema de importação de módulos nativo do Chrome:

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Manager</title>
</head>
<body>
<!-- importou o módulo -->
<script type="module" src="app/app.js"></script>
</body>
</html>

É necessário servir a página através de um servidor Web de sua escolha, caso contrário o carregamento dos módulos não funcionará.

Vejamos como fica o uso inicial do nosso manager no módulo app/app.js:

// app/app.js
import { manager } from './manager.js';
// encadeando as chamadas de métodos
manager
.setDbName('cangaceiro')
.setDbVersion(2)

Todos os módulos que importarem nosso manager trabalharão com a mesma instância. Isso é importante, pois precisamos ter centralizado em um único local sua configuração. Nesse sentido, podemos dizer que manager implementa o padrão de projeto Singleton, porém, utilizando os próprios recursos da linguagem sem grandes mistérios como no pattern original.

Agora vamos partir para a implementação de um dos métodos mais importante da nossa API de persistência, o método register.

Implementando o método register

Vamos implementar agora a função register, uma dos mais importantes métodos do nosso manager:

// app/manager.js
let dbName = 'default';
let dbVersion = 1;
// novo dado!
const stores = new Map(); 

class Manager {

    setDbName(name) {
        dbName = name;
        return this;
    }

    setDbVersion(version) {
        dbVersion = version;
        return this;
    }
    // novo método
    register(...mappers) {
        mappers.forEach(mapper => 
            stores.set(
                mapper.clazz.name, 
                mapper.converter
            )
        );
    }
}

export const manager = new Manager();

É necessário que o leitor tenha algum conhecimento da API do IndexedDB, por mais ínfimo que seja para que compreenda com mais clareza as vantagens da abordagem aqui utilizada.

A função register, através do Rest Operator, recebe uma quantidade indefinida de objetos que chamaremos de mappers (mapeadores). Cada objeto identifica a classe e a lógica de conversão a ser aplicada toda vez que objetos dessa classe forem obtidos de uma store.

Objetos recuperados da store só possuem propriedades e nenhum método, por isso é importante definir a lógica de conversão dos dados trazidos do banco para sua respectiva classe.

Para cada item da lista de mappers recebida utilizaremos o valor da propriedade clazz como key e o valor da propriedade converter como seu valor no Map batizado de stores. Esse dado é importante, pois é através dele que saberemos quais stores serão criadas e qual lógica de conversão será utilizada ao obter seus dados.

Nosso app/app.js por enquanto estará assim:

// app/app.js
import { manager } from './manager.js';
import { Person } from './Person.js';
import { Animal } from './Animal.js';

manager
.setDbName('cangaceiro')
.setDbVersion(2) 
.register(
    { 
        clazz: Person,
        converter: data => new Person(data._name)
    },
    { 
        clazz: Animal,
        converter: data => new Animal(data._name)
    }
);

Excelente, mas no ato de realizarmos o registro precisamos criar a conexão com o banco.

Obtendo uma conexão

Vamos criar uma função responsável pela criação da conexão. Ela viverá no escopo do módulo manager.js e apenas a instância de Manager poderá acessá-la.

Como a obtenção de uma conexão é uma operação assíncrona, retornaremos uma Promise como resposta, reduzindo assim a complexidade de termos que trabalhar com callbacks.

Vamos criar a variável conn, também encapsulada pelo módulo manager.js. Ela guardará uma referência para a conexão criada. Seu valor será atribuído através da função createConnection:

let dbName = 'default';
let dbVersion = 1;
const stores = new Map(); 
// nova variável
let conn = null;

const createConnection = () => 
    new Promise((resolve, reject) => {
    
    });

// definição da classe omitido

Vamos solicitar à função indexedDB.open() a abertura da conexão com o banco usando as configurações definidas em dbName e dbVersion. Porém, não temos a garantia de que a conexão foi efetuada, motivo pelo qual precisamos lidar com os eventos onupgradeneeded, onsuccess e onerror:

let dbName = 'default';
let dbVersion = 1;
const stores = new Map(); 
let conn = null;

const createConnection = () => 
    new Promise((resolve, reject) => {
        // requisitamos a abertura, um evento assíncrono!
        const request = indexedDB.open(dbName, dbVersion);

        request.onupgradeneeded = e => {};

        request.onsuccess = e => {};

        request.onerror = e => {};
    });

// código posterior omitido

O evento onupgradeneeded disponibiliza uma conexão transacional que nos permite criar todas as stores do banco. Utilizaremos as chaves do nosso Map stores como nome das stores:

let dbName = 'default';
let dbVersion = 1;
const stores = new Map(); 
let conn = null;

const createConnection = () => 
    new Promise((resolve, reject) => {

        const request = indexedDB.open(dbName, dbVersion);

        request.onupgradeneeded = e => {

            const transactionalConn = e.target.result;
            // utilizando for...of e destructuring ao mesmo tempo
            // para ter acesso ao valor da key
            for (let [key, value] of stores) {
                const store = key;
                // se já existe, apagamos
                if(transactionalConn.objectStoreNames.contains(store)) 
                    transactionalConn.deleteObjectStore(store);
                transactionalConn.createObjectStore(store, { autoIncrement: true });
            }     
        };

        request.onsuccess = e => {
            conn = e.target.result; // guarda uma referência para a conexão
            resolve(); // tudo certo, resolve a Promise!
        }
        // lida com erros, retornando uma mensagem de alto nível
        request.onerror = e => {
            console.log(e.target.error);
            reject('Não foi possível obter a conexão com o banco');
        }; 
    });
// código posterior omitido

A estratégia utilizada durante um eventual upgrade do banco é derrubar todas as stores para em seguida criá-las novamente.

Excelente, agora precisamos chamar a função createConnection através do método register de Manager. Vamos tornar o método async para que possamos utilizar a instrução await com a Promise retornada por createConnection:

// app/manager.js
// código anterior omitido

class Manager {

    setDbName(name) {
        dbName = name;
        return this;
    }

    setDbVersion(version) {
        dbVersion = version;
        return this;
    }
    // tornou o método async
    async register(...mappers) {
        mappers.forEach(mapper => 
            stores.set(mapper.clazz.name, mapper.converter));
        // utilizou a instrução await, só é possível porque
        // register é um método async
        await createConnection();
    }
}

export const manager = new Manager();

Agora, em app/app.js, criaremos um wrapper async para que possamos utilizar a instrução await com o método register:

// app/app.js
import { manager } from './manager.js';
import { Person } from './Person.js';
import { Animal } from './Animal.js';
// wrapper async
(async () => {
    // instrução await!
    await manager
        .setDbName('cangaceiro')
        .setDbVersion(2) 
        .register(
            { 
                clazz: Person,
                converter: data => new Person(data._name)
            },
            { 
                clazz: Animal,
                converter: data => new Animal(data._name)
            }
        );

})().catch(console.log); // captura possíveis erros

Toda função async retorna uma Promise, independente se retornamos uma ou não. É por isso que precisamos usar await na chamada de manager.register. Além disso, lidamos com qualquer exceção através ().catch(console.log);. Outra alternativa era usarmos a instrução try/catch no bloco do código, porém o autor preferiu a primeira abordagem por ser menos verbosa, além do tempo do dojo ter sido curto!

Recarregando a página index.html no Chrome, na aba Application -> Storage -> IndexedDB podemos constatar a criação do banco.

Abra outra aba no Chrome para que possa verificar os dados mais atualizados, pois este autor constatou que o Chrome não realiza o refresh automático da aba Application -> Storage -> IndexedDB.

Agora vamos implementar o método save.

Implementando o método save

O método save da nossa classe Manager também retornará uma Promise, pois a operação de persistência também é uma operação assíncrona:

// app/manager.js
// código anterior omitido 
class Manager {
    // métodos anteriores omitidos
    save(object) {
        
        return new Promise((resolve, reject) => {

            // falhando rapidamente, "fail fast"
            if(!conn) return reject('Você precisa registrar o banco antes de utilizá-lo');
            
            // obtem o nome da store através do nome da classe
            const store = object.constructor.name;
            
            const request = conn
                .transaction([store],"readwrite")
                .objectStore(store)
                .add(object);
            
            // resolve a Promise no sucesso
            request.onsuccess = () => resolve();

            request.onerror = e => {
                console.log(e.target.error);
                reject('Não foi possível persistir o objeto');
            };
        });
    }
} 

Vamos analisar o código anterior. A Promise retornada verifica se a variável conn possui algum valor e caso não possua, rejeitamos a Promise imediatamente. Esse fail fast é importante, pois sinalizará para o desenvolvedor que ele deve realizar antes o registro do banco.

O restante do código é padrão da API do IndexedDB, todavia vale lembrar que precisamos solicitar uma transação de escrita para a store que desejamos armazenar nosso objeto. Aliás, obtemos o nome da store do objeto a ser persistido através de object.constructor.name:

Agora chegou a hora de implementarmos o método list(), aquele que retornará os dados persistidos.

Implementando o método list

Assim como o método save(), o método list() retornará uma Promise. Ele receberá como parâmetro uma classe e, a partir dela, extrairá o nome da sua respectiva store. Sabemos que o nome da store é a key do Map stores. É através dessa key que temos acesso a lógica de conversão, aquela que sabe converter os dados retornados da store para uma instância da sua respectiva classe.

// app/manager.js
// código anterior omitido 
class Manager {
    // métodos anterior omitidos
    list(clazz) {
        
        return new Promise((resolve, reject) => {
            // Identifica a store
            const store = clazz.name;
            // Cria uma transação de escrita
            const transaction = conn
                .transaction([store],'readwrite')
                .objectStore(store); 
            
            const cursor = transaction.openCursor();
            // Converter da store
            const converter = stores.get(store);
            // Array que receberá os dados convertidos
            // com auxílio do nosso converter
            const list = [];
            // Será chamado uma vez para cada 
            // objeto armazenado no banco
            cursor.onsuccess = e => {
    
                const current = e.target.result;
                // Se for null, não há mais dados
                 if(current) {
                     list.push(converter(current.value));
                     // vai para o próximo registro
                     current.continue();
                } else resolve(list);
            };
    
            cursor.onerror = e => {
                console.log(target.error);
                reject(`Não foi possível lista os dados da store ${store}.`);
            };  
        });    
    }
}

Excelente, nosso módulo app/app.js ficará assim:

import { manager } from './manager.js';
import { Person } from './Person.js';
import { Animal } from './Animal.js';

(async () => {
    await manager
        .setDbName('cangaceiro')
        .setDbVersion(2) 
        .register(
            { 
                clazz: Person,
                converter: data => new Person(data._name)
            },
            { 
                clazz: Animal,
                converter: data => new Animal(data._name)
            }
        );
        
    const person = new Person('Flávio Almeida');
    const animal = new Animal('Calopsita');

    await manager.save(person);
    await manager.save(animal);

    const persons = await manager.list(Person);
    persons.forEach(console.log);

    const animals = await manager.list(Animal);
    animals.forEach(console.log);

})().catch(console.log);

Melhor organizado do que se tivéssemos utilizado diretamente a API do IndexedDB. Você pode conferir o código completo deste artigo no meu github.

Conclusão

O padrão de projeto Data Mapper pode ser aplicado não apenas com o IndexedDB, mas qualquer meio de persistência, inclusive banco de dados utilizados por API.

E você? Já utilizou alguma biblioteca que faz uso desse padrão? Como lidava com persistência no IndexedDB? Deixe sua opinião.

Revisitando Set, pegadinha e truques para colocar em prática hoje

2018-01-29T15:00:00+00:00

O ES2015 (ES6) introduziu a estrutura de dados Set facilitando a vida dos desenvolvedores que antes precisavam empregar subterfúfios para emular características de conjuntos. Neste post revisitaremos essa estrutura tão útil para o desenvolvedor e também veremos pegadinhas e truques a respeito do seu uso.

O problema

Precisamos criar um conjunto com 20 números aleatórios de um a 100. Primeiro, vamos declarar a função generateRandomInt que será a responsável pela geração de números aleatórios na faixa que indicarmos:

const generateRandomInt = (min, max) => 
    Math.floor(Math.random() * (max - min + 1)) + min;

Agora, através de Array.from, criaremos um novo array já preenchido com números aleatórios:

const generateRandomInt = (min, max) => 
    Math.floor(Math.random() * (max - min + 1)) + min;

const numbers = Array.from(new Array(20), () => 
    generateRandomInt(1, 100));

console.log(numbers);

O código anterior só foi possível porque o segundo parâmetro da função Array.from é uma função de mapeamento, isto é, será aplicada em todos os elementos undefined do Array criado por new Array(20) resultando em um array com apenas números aleatórios. Todavia, se escrutinarmos o valor de numbers, veremos que pode haver números duplicados:

54,70,27,86,29,80,68,21,25,81
49,93,49,39,77,86,47,9,87,95

Essa duplicação não faz sentido pois um conjunto possui elementos distintos.

“In mathematics, a set is a collection of distinct objects”

Precisamos alterar nosso código para que se coadune com a teoria dos conjuntos!

Primeira solução

Uma solução clássica é verificar se o número existe no array antes de ser adicionado:

const generateRandomInt = (min, max) => 
    Math.floor(Math.random() * (max - min + 1)) + min;

let counter = 10;
const numbers = [];

while(counter > 0) {
    const randomNumber = generateRandomInt(1, 100);
    if(!numbers.some(number => number === randomNumber)) {
        numbers.push(randomNumber);
        counter--;
    } 
}   

Nossa solução funciona, todavia nada disso precisaria ser feito se tivéssemos utilizado a estrutura de dados Set (conjunto) introduzida no ES2015 (ES6).

Utilizando Set

Vamos alterar o código anterior para que faça uso do Set. Criamos um conjunto através da instrução new Set() e através do método add da instância retornada adicionamos novos elementos. Todavia, caso o elemento já exista no conjunto, ele não será adicionado novamente:

const generateRandomInt = (min, max) => 
    Math.floor(Math.random() * (max - min + 1)) + min;

const numbers = new Set();
while(numbers.size < 20) 
    numbers.add(generateRandomInt(1, 100));
console.log(numbers);

A condição numbers.size < 20 é necessária para que tenhamos 20 elementos, pois o número gerado já pode ter sido incluído e, como vimos, o método add() não permitirá sua inclusão.

Consultar a propriedade numbers.size pode não ser tão performático caso a lista tenha um tamanho considerável, nesse sentido vamos utilizar outra estratégia.

Dessa vez, verificaremos se o elemento existe antes de incluído, pois precisamos dessa informação para saber se incrementamos ou não nosso contador. Verificamos a existência através do método has() que retorna true ou false caso o elemento exista ou não:

Vamos ao código:

const generateRandomInt = (min, max) => 
    Math.floor(Math.random() * (max - min + 1)) + min;

const numbers = new Set();
let counter = 1;
while(counter <= 20) {
    const randomNumbers = generateRandomInt(1, 100);
    if(!numbers.has(randomNumbers)) {
        numbers.add(randomNumbers);
        ++counter;
    }  
}  
console.log(numbers);

Opcionalmente, podemos omitir a instrução if da seguinte forma:

const generateRandomInt = (min, max) => 
    Math.floor(Math.random() * (max - min + 1)) + min;

const numbers = new Set();
let counter = 1;
while(counter <= 20) {
    const randomNumbers = generateRandomInt(1, 100);
    !numbers.has(randomNumbers)
    && numbers.add(randomNumbers) 
    && ++counter;
}  
console.log(numbers);

A estrutura Set possui outros métodos, porém vale destacar forEach e clear. O primeiro itera no conjunto na ordem de inclusão e o segundo remove todos os seus elementos:

// código anterior omitido
numbers.forEach(number => console.log(number)); // imprime cada item 
numbers.clear(); // esvaziou o conjunto
console.log(numbers); // Set(0) {}

Realizamos um overview sobre Set em JavaScript, no entanto, há uma pegadinha que pode pregar uma peça no programador desavisado.

Pegadinha no uso de Set

Temos um conjunto com dois elementos:

const livros = new Set([
    { nome: 'Cangaceiro JavaScript', isbn: '9788594188014' },
    { nome: 'MEAN', isbn: '9788555190469' },
]);

Vamos adicionar um livro repetido para logo em seguida verificarmos o tamanho do Set:

const livros = new Set([
    { nome: 'Cangaceiro JavaScript', isbn: '9788594188014' },
    { nome: 'MEAN', isbn: '9788555190469' },
]);

const livro = { nome: 'MEAN', isbn: '9788555190469'})
livros.add(livro);

console.log(livros.size); // 3!!!

Para a supressa de alguns, o método add() adicionou um livro duplicado! Mesmo se tivéssemos utilizado o método has() para verificar se o livro já existe ou não ele retornaria false. Por que isso acontece?

A explicação é a mesma que este autor utilizou para explicar o comportamento do método Array.includes no artigo “Array.includes vs Array.some”. Vamos recordar.

Internamente os métodos has e add utilizam o operador === para comparar o novo elemento com os já existentes. Essa comparação será feita com base no valor primitivo dos seguintes tipos:

Boolean
Null
Undefined
Number
String
Symbol (ES2015)

Todavia, quando ocorre uma comparação com um elemento do tipo Object, o interpretador verificará se ambos apontam para o mesmo endereço de memória. Sendo assim, por mais que tenhamos criado um novo objeto com estrutura idêntica ao objeto do nosso conjunto, eles serão diferentes.

Voltando ao exemplo anterior, se tentarmos adicionar o mesmo livro que acabamos de adicionar, não conseguiremos, pois a variável de referência livro aponta para o mesmo objeto que inserimos em nosso conjunto:

const livros = new Set([
    { nome: 'Cangaceiro JavaScript', isbn: '9788594188014' },
    { nome: 'MEAN', isbn: '9788555190469' },
]);

const livro = { nome: 'MEAN', isbn: '9788555190469'})

livros.add(livro);
console.log(livros.size); // 3!!! Incluiu!

livros.has(livro); // true, existe no conjunto
livros.add(livro); // não adiciona novamente
console.log(livros.size); // continua 3

Agora que passamos pela pegadinha que o Set pode nos pregar, que tal aprendermos dois truques que podemos utilizar no dia a dia?

Truque 1: transformando uma lista em conjunto

Precisamos do total de ID’s não duplicados de um Array. Uma maneira de resolver o problema é criando um novo Array com elementos não duplicados:

const ids = [100, 110, 100, 200, 300, 100];
const uniqueIds = [];

ids.forEach(id => 
    !uniqueIds.some(uniqueId => 
        uniqueId === id) && uniqueIds.push(id));

console.log(uniqueIds).length;

Todavia, podemos criar um Set a partir de um array passando-o diretamente para seu constructor:

const ids = [100, 105, 100, 200, 300, 110];
const uniqueIds = new Set(ids); // recebe um array como parâmetro
console.log(uniqueIds.size); // 5

Um código muito mais enxuto.

Truque 2: transformando um conjunto em uma lista

Vimos como descobrir a quantidade de elementos únicos dentro de uma lista convertendo-a para um conjunto. Mas se precisarmos filtrar ou realizar algum mapeamento nos valores do conjunto? Essas operações existem apenas no tipo Array. E agora?

A boa notícia é que através do Spread Operator podemos transformar facilmente um conjunto (Set) em uma lista (Array):

const ids = [100, 105, 100, 200, 300, 110];
const filteredIds = [...new Set(ids)]
    .filter(uniqueId => uniqueId > 100);

console.log(filteredIds); 
// [105, 200, 300, 110]

Essa dica e a anterior simplificam demais a transformação de um conjunto para uma lista e de uma lista para conjunto.

Conclusão

A introdução tipo Set no ES2015 (ES6) ajudou a reduzir drásticamente a quantidade de código necessária para realizarmos determinadas tarefas do dia a dia.

E você? Já utilizava Set antes? Conhecia os truques apresentados? Deixe a sua opnião!