DEV Community: wkrueger

Log from my latest Windows install from scratch

wkrueger — Wed, 31 Aug 2022 22:40:35 +0000

I reinstalled Windows from scratch (manually) on my machine and took notes on the required steps.

Context: I current work with web development - mostly node.js - and use the same machine for personal use (games).

Before cleanup

Move files to a separate partition or storage which won't be erased. Example:
- My repositories (Documents) folder
- Desktop folder
- Steam library
  - Steam has a nice UI where you can set addicional Libraries and transfer games between them!
- I didn't backup any Docker volumes, but that is possible to do;
- Move Blizzard games folders (they are self contained)
- And maybe something else I forgot to take note...
If you only have one storage device, you can partition it by creating a Linux USB, then running GParted; Maybe Windows's Disk Manager suffices, but it has limitations.
Another option is uploading to an online service like Amazon S3;
Create USB media from the provided creation tool at Windows website;
Boot from USB (depends on your computer);

Windows Install

Boot the Windows USB. Format the partition which contains your current Windows install. Select it for the next install.

I had issues, see appendix.

After install

First task: Install updates
- Updates can take a while and are a requisite to running the debloater script;
- After each restart, force checking again until no updates show up;
- Install other items while the updates install;
Remove bloatware from start menu;
Install the latest version of PowerShell;
Disable Windows Defender
- Windows Defender eats a significant amount of CPU and I/O;
- Currently to do this you need an external program - Defender Control;
- Before running Defender Control, you must disable " tamper protection" and add its folder to the exclusions list on Windows Security;
Download your browser or just use Edge.
Install Git
- The Git install prompts dozens of questions. The following ones are important points which I recommend changing from the defaults:
  - Don't use MinTTY, use the default Windows terminals;
  - Commit as-is (don't convert CR/LF). Handle line endings on your editors;
  - Use external OpenSSH client (now Windows comes with one);
- Additional setup
- You can add the git /bin folder to PATH. With that, you can invoke Git Bash (the MINGW terminal) from any console with sh; You usually don't need Git Bash (and should avoid using it as it is an additional layer), but it is useful to run Unix commands or Bash scripts;
Run Sophia Script;
- The Readme is a bit convoluted; You can download the Windows 11 + Powershell 7 version;'
- The script will fail if you dont have the last Windows version;
- Check the "How To Use Section" (dont use wrapper or GUI, just run the main script)
- After running the elevation command, run the script on terminal ./Sophia.ps1
- Make sure your terminal is running PowerShell 7. You can select it on the Windows Terminal new tab;
Install WSL
- wsl --install
- This also installs Ubuntu 20.
- In case you want another distro, browse it on the Store;
- If you install a different distro, make sure to cleanup the default Ubuntu 20
  - wsl --unregister Ubuntu (deletes the distribution)
  - wsl --list
  - wsl -s Ubuntu-22 (set the new default distribution)
- Make sure you don't have the Docker distribution set as default, as that can cause issues;
- To access the default distro you can either:
  - Invoke bash on any Windows console (right-click Start Icon -> Terminal);
  - Open a new tab on Windows Terminal with the desired distro;
  - Search the distro name on the Start Menu
- Install apps on WSL. Ex: nodejs, git etc.
- While Windows already has Linux folders on the Explorer, I also like to install a file manager like Thunar (it is quite a big download, because it installs a lot of other things along). A Linux file manager is quite handy to navigate WSL folders;
Add SSH keys to both Windows and WSL
- On Windows, put the SSH key on <user>/.ssh; Name the default key id_rsa.
- Check this article on setting up a SSH key on the Windows environment. You don't need to follow the last session ("link to git") anymore;
- Same as usual on Linux
  - ~/.ssh folder
  - on Linux we also need chmod 600 <file>
Ativate Windows if that's the case;
UI Tweaks
- Set displays to 144Hz if they are at 60Hz
- Set dark mode
- Add extra buttons to start menu lower bar
  - Settings > Personalization > Start > Folders
- Search "PrintScreen" on Settings, then set to open Screen Capture when pressing this key;
- At Recycle Bin properties, reduce Recycle Bin size on all drives. Disable delete confirmation dialog;
- (optional) You can disable the new context menus with WinAeroTweaker;
- (optional) You can fix the lackluster W11 Taskbar with StartAllBack
Install Docker (desktop). Use WSL2 engine.
Drivers
- Download drivers from OEM website, if notebook;
- Download NVIDIA ou AMD driver;
- Get Intel update tool (optional). Uninstall after running it.
System apps
- OEM apps (ex: laptop power control)
- (optional) Quick CPU: for laptops - finer control on CPU power for quiet laptop. Keep it off as it uses CPU :/
- (optional) Libre Hardware Monitor: Logs CPU and GPU temp on a chart
- Equalizer APO (optional)
- Powertoys (optional). After installing it you should disable most useless tweaks.
Fonts
- Install your coding fonts. On my case, JetBrains mono.
Games
- Steam
  - Setup back the Library folder
- Things from the games you play
Entertainment
- Spotify
- Stremio
- OBS
  - Set up twitch
Install productivity apps
- Notion
- VS Code
- Node.js, Java, Android Studio, etc.
- Insomnia
- Company proxy if applicable
- MS Office
- Screen2Gif
- DBeaver
- Paint.net - basic image editing

Appendix: My Windows Install, and its issues

On Windows install, select the option for custom partitions;
Format and select the current Windows drive
My main drive had a bit messed up partitions due to previous Linux installs;
- First install failed with error;
- Next install complained about my partitions;
- I ended up:
  - Boot into repair mode from the Windows install to open the terminal (SHIFT+F10 probably also works);
  - diskpart list disk select disk <number> clean convert gpt (MBR won't work on UEFI boots)
    - Back on Windows install, create the partition on the partition UI, allocating full space;
    - The install says that it will automatically create an extra system partition. OK.

The rest of the install proceeded OK. Say no to all Microsofts bullshit.

Curious notice
I've also recently installed Windows on a new notebook from a friend. His Windows install was a bit different and didn't prompt for a Microsoft account, it also didn't install bloatware (Netflix/etc). I wonder if it skips the bloat if you enter an activation key.

Guia de Promises do JavaScript

wkrueger — Sun, 07 Aug 2022 22:02:00 +0000

Este é um guia que escrevi pra algum grupo do Facebook em meados de 2017 e que encontrei em meus arquivos. Apesar da idade, continua razoavelmente atual.

~~Pode-se afirmar que no momento Promises são a forma mais "padrão" no momento de se tratar com assincronismo no JS.~~ Para quem trabalha com javascript, conhecê-las é essencial.

Uma dificuldade comum é que esta API tem uma curva de aprendizado um tanto acentuada de início, especialmente se comparado com as alternativas mais antigas: callbacks e a lib async.js. No meu caso, levei ao menos uns 3 meses pra "cair a ficha".

-- na verdade promises ainda são um remendo para o problema do assincronismo do JS. Elas ainda possuem certa dificuldade
na adoção (se comparado a código síncrono) e ainda comem tempo de processamento de seu cérebro (se comparado a código síncrono).
Mas são o mínimo necessário para levar a escrita de código JS a um nível são, já que callbacks facilmente levam a "spaghetti code". --

Tentarei aqui fazer uma introdução ao assunto, com foco em passar muitos exemplos. Algumas vezes posso sacrificar a precisão acadêmica propositalmente em nome de uma explicação mais simples. Em alguns casos trago opiniões pessoais.

Pré-definições

Uma função que retorna uma informação de "forma síncrona":

try {
  var cinco = somar(2, 3)
  console.log(cinco)
} catch(err) {
  //erro na soma
}

Uma função que retorna uma informação de forma ASSÍNCRONA via pattern de CALLBACK.

somar(2, 3, (err, cinco) => {
  if (err) {
    //erro na soma
    return
  }
  console.log(cinco)
})

Uma função que retorna uma informação de forma ASSÍNCRONA via pattern de PROMISE.

somar(2, 3).then( cinco => {
  console.log(cinco)
}).catch( err => {
  //erro na soma
})

Apresentação

A principal motivação por trás das Promises é resolver problemas trazidos pelo "pattern" de callbacks. Um desses problemas é a identação excessiva (A.K.A. callback hell). Outra função importante das promises é cuidar (e padronizar) o tratamento de erro.

Quando uma chamada assíncrona é "encapsulada" dentro de uma promise, torna-se possível dar a ela um tratamento mais "funcional" -- uma caixinha com entrada e saída definidas. Já uma função "callback" não trás a sua resposta no seu retorno de função, mas sim em um de seus parâmetros. Comportamento este que facilmente leva a complicações no código e dificuldade de leitura e reaproveitamento.

Exemplo besta de callback hell:

const soma = (a, b, callback) => callback( null, a + b )
//somar 1 + 2 + 3 + 4 + 5
function somarTudo( callback ) {
  soma(1, 2, (err, r) => {
    soma( r, 3, (err, r) => {
      soma( r, 4, (err, r) => {
        soma( r, 5, (err, r) => {
          callback(null, r)
        })
      })
    })
  })
}
somarTudo( (err, result) => console.log(result) )

O mesmo exemplo usando promises:

const soma = (a, b) => Promise.resolve(a + b)
function somarTudo() {
  return soma(1, 2)
    .then( r => soma(r, 3) )
    .then( r => soma(r, 4) )
    .then( r => soma(r, 5) )
}
somarTudo().then( result => console.log(result) )

Veja que promises ainda estão longe de ser "o mundo perfeito". Chamemos de "mundo perfeito" um código cuja leitura claramente identifica a regra de negócio com um mínimo de "sujeira". Por exemplo, se você for escrever uma mesma regra do javascript em um código PHP, o código PHP possivelmente será mais simples, terá menos linhas. Isto porque o código PHP é "síncrono": ele é mais simples porque faz menos coisas. A assincronia acaba trazendo uma carga adicional de sujeira ao código, ou seja, linhas adicionais que não estão relacionadas à regra de negócio, mas a detalhes técnicos.

Comparado a um código síncrono um código com promises é um tanto "sujo".

Comparado a um código de callbacks, um código com promises ainda é "sujo", porém um pouco menos.

Uma evolução do pattern de promises é o uso de async/await, que abstrai ainda mais o tratamento de assincronismo em uma linguagem muito similar a um código síncrono. (Pesquise depois no github pela biblioteca "tj/co", uma das raízes do async/await do javascript.) Mas ANTES de você usar async/await, é interessante entender primeiro como se usam promises.

Usando

O objeto (classe) promise

Um objeto de promise encapsula

uma informação qualquer
um estado (pendente/concluído/falha)
uma ação pra obter essa informação

Você nunca vai acessar os estados e informações diretamente via propriedades, mas sempre pelos métodos .then() e
.catch().

construtor

O construtor é usado pra converter um código de callback/evento em um código de promise.

SE O QUE PRETENDES FAZER
NÃO É CONVERTER DE CALLBACK -> PROMISE, ENTÃO VOCÊ NÃO DEVERIA ESTAR USANDO ESTE CONSTRUTOR.

No exemplo abaixo convertemos o $.ajax em um formato de Promise (*)

(*) apenas para exemplo. O jQuery na verdade já expõe uma interface promise-ish nesse método

var ajaxPromise = function(url) {
    return new Promise( function CallbackDoContrutor(completar,falhar) {
        $.ajax({{
            url : url , 
            success : function(data) {
                return completar(data)
            } , 
            error : function(jqXhr, status, error) {
                return falhar(error)
            }
        }})
    }
})

ajaxPromise('some-url').then( function(response) {
    fazerCoisas(response)
}).catch( function(err) {
    //exibir erro na tela
})

completar e falhar recebidos ali pelo CallbackDoConstrutor, são funções a ser chamadas pra indicar que a promessa foi "concluída"
ou "falha". Aceitam um (e apenas um) parâmetro o qual é repassado para a próxima etapa da cadeia (o then ou o catch).
Tome cuidado pra não chamá-los mais de uma vez. Pessoalmente adoto como prática sempre usá-los junto com return.

(Observação) Observe que o retorno de CallbackDoConstrutor não é utilizado pra nada. Apenas o completar e o falhar.

(Recomendação) Mantenha funções conversoras Callback -> Promise separadas da sua regra de negócio, preferencialmente as defina como funções puras.

Promise.resolve( [valor] )

Faz iniciar uma cadeia de promises com determinado valor inicial. Encapsula um valor em uma Promise.

É exatamente igual a se fazer:

var imitaçãoDoResolve = function( value ) {
    return new Promise( function(completar) {
        completar(value)
    })
}
imitaçãoDoResolve(3).then( function(result) {
    console.log(result) // exibe 3
})
Promise.resolve(3).then( function(result) {
    console.log(result) // exibe 3
})

Promise.reject( [valor] )

Faz iniciar uma cadeia de promises com status de falha.

A mesma coisa do Promise.resolve, só que desta vez chamando um falhar ao invés do completar.

NOTA

Uma cadeia de promises SEMPRE nascerá a partir de um construtor, de um Promise.resolve ou de um Promise.reject.

Promise#then( sequenceFn , [failFn] )

(parêntese ilustrativo. favor ignorar se confuso)

class Promise {
    then<K,V>( sequenceFn : (prevResult?) => Promise<K>|K , failFn? : (prevResult?) => Promise<V>|V ) 
        : Promise<K>|Promise<V>
}

É um método do objeto Promise usado pra encadear eventos assíncronos subsequentes.

Caso a etapa anterior tenha sucesso, sequenceFn() é executado, caso contrário roda a failFn().

Os callbacks sequenceFn e failFn recebem como argumento a resposta passada na etapa anterior da sequência de eventos.

Promise.resolve('legal').then(function(prev){
    return prev + ' mesmo'
}).then(function(prev) {
    console.log(prev) // legal mesmo
})

UMA PAUSA: Agora que você já sabe que o segundo argumento (failFn) existe, pode ignorá-lo. Você nunca vai usá-lo, isso porque existe o Promise#catch.

O callback sequenceFn é beeem diferente do callback do construtor que vimos lá em cima.
Pra repassar dados para as próximas etapas da sequência utilizamos o RETORNO da função (ou o throw).
Este retorno de função pode ser um valor qualquer, ou OUTRA promise.

Se o retorno de fnSequencia fror uma Promise, a próxima etapa da cadeia apenas é chamada quando esta Promise concluir
(seja com sucesso ou falha). Esta próxima etapa receberá o valor com o qual a promise sucedeu ou falhou.

numeroEntreZeroE100.then( function(numero) {
    if (numero < 50) return numero
    return ajaxPromise(ENDERECO + '?numero=' + numero)
}).then( function(resultado) {
    mostraNaTela(resultado)
})

No exemplo acima, temos um bloco que pode ter um resultado síncrono ou assíncrono dependendo do caso.

Promise#catch( fn )

Quando você dá um throw dentro do sequenceFn ou quando o retorno desse é uma Promise falha,
o fluxo é encaminhado para o próximo .catch da sequência.

Observe que esse throw não "propagará" para o resto do programa (nem o interromperá), apenas para a sequência de Promise em questão.
Em plataformas recentes (com Promise nativa do es6) aparece uma mensagem no console sobre o erro (uncaught rejection), mas em algumas mais antigas ou em bibliotecas um erro pode não deixar aviso nenhum se não tratado com uma etapa .catch() e um log.

Quando há uma falha em uma sequência de Promises, o erro varre a sequência até encontrar o primeiro .catch(). Para que o erro não seja "engolido", não se esqueça de repassá-lo para o resto da cadeia usando throw novamente. Usar return dentro de um .catch() fará o status mudar pra "sucesso" e a sequência cair no
.then() seguinte.

Promise.resolve()
    .then( etapa1 )
    .then( etapa2 )  //falhou aqui
    .then( etapa3 )  // pulou este
    .catch( function(err) { // caiu aqui
        console.log(err)
        // não engolir o erro
        throw err
    })
    .then( etapa4 )
    .catch( catch2 )

Se tudo for feito certinho, pra receber um erro e exibí-lo na tela você só precisara de 1 catch pra tripa toda de código.
Nada de inúmeras chamadas à função que mostra o erro na tela.

Promise.all( entradas )

(parêntese ilustrativo. favor ignorar se confuso)

class Promise {
    static all( promises : Promise<T>[] ) : Promise<T[]>
}

Recebe Promise[] como entrada.

Promise.all só seguirá para a próxima etapa da cadeia depois que todas as suas entradas finalizarem, ou na primeira falha.

A próxima etapa recebe como resultado um array com as respostas das entradas.

var clientesP = [264,735,335,999 277].map( function(id) {
    return lerDoBanco({
        tabela : 'cliente' ,
        id : id
    })
}) // tipo Promise<Cliente>[]
Promise.all(clientesP).then( function(clientes) {
    // clientes tem tipo Cliente[]
    mostrar(clientes)
}).catch( function(err) {
    mostrarErro(err.message)
    //repassar o erro, caso contrário seguirá a cadeia como se não houvesse erro
    throw err
}) //...

Geralmente você estará utilizando Promise.all e, conjunção com Array#map para criar fluxos "paralelos". (*)

           |
        [1,2,3]
  Array#map + Promise
    /      |      \
 [ p(1),  p(2),   p(3)]
   \       |      /
      Promise.all
           |
    [r(1),r(2),r(3)]

(*) Paralelo entre aspas. Se você entende do event loop sabe do que estou falando.

Padrões, exemplos

Basicão array#map e array#reduce

Eu ainda não sou o guru da programação funcional, mas uma das partes importantes (e mais fáceis) dela é pensar em termos de fluxos de dados e transformações.

Por exemplo, se no início tenho uma lista com 15 ids, e ao final terei 15 ~qualquer coisa~, então certamente esta transformação pode ser feita com o map (exceto se esses 15 ids tiverem interdependências/não linearidades).

number[15] => Array#map => Promise<Cliente>[15] => Promise.all => Promise<Cliente[15]> => Promise#then => Cliente[15]

Por outro lado, se de 15 números, ao final quero obter apenas um objeto/estatística, então certamente terei de usar o reduce.

number[15] => Array#reduce => string

Pedidos assíncronos em paralelo

Cria-se um array de promises, depois usa-se o Promise.all para verificar que todas estão prontas e coletar os dados.

Caso a fonte de dados pras promises seja um array, certamente você usará o Array#map.

var clientesP = [264,735,335,999 277].map( function(id) {
    return lerDoBanco({
        tabela : 'cliente' ,
        id : id
    })
}) // tipo Promise<Cliente>[]
Promise.all(clientesP).then( function(clientes) {
    // clientes tem tipo Cliente[]
    mostrar(clientes)
})

Pedidos assíncronos em sequência

Este é complicadinho. A partir de um array, usa-se o array#reduce iniciado com um Promise.resolve()
para criar um encadeamento com um .then(...) para cada item do array.

Antes

chamada(1)().then( chamada(2) ).then( chamada(3) ).then( chamada(4) )

Equivale a

Promise.resolve().then( chamada(1) ).then( chamada(2) ).then( chamada(3) ).then( chamada(4) )

Equivale a

[1,2,3,4].reduce( function(chain,currentItem) {
    return chain.then( chamada(currentItem) )
}, Promise.resolve())

Mais um exemplo:

var estados = ['SP', 'RJ', 'MG']
var $listaDados = $('.lista')
return estados.reduce( (sequencia, estado) => {
    return sequencia.then(() => {
        return ajaxRequest('/dadosEstado/' + estado)
    }).then( dados => {
        $listaDados.append( TEMPLATE(dados) )
        return
    })
} , Promise.resolve())

Aninhamento

O código em promise tem a característica de poder funcionar com aninhamento.
Se fôssemos pensar de forma gráfica, a informação na parte mais profunda da "cascata" parece que vai "subindo" até a raiz, em uma espécie de árvore.

// -- todas as funções personalizadas aqui retornam promises
obterCliente().then( function(cliente) {
    // escopo 1
    return obterCidadeDoCliente(cliente).then( function(cidade) {
        // escopo 2
        cliente.cidade = cidade
        return obterTemplate(cliente).then( function(template) {
            // escopo 3
            return '<div>' + template + '</div>'
        })
    })
}).then( function(templateClienteComDiv) {
    //recebe o resultado do escopo 3
    mostrar(templateClienteComDiv)
})

Otimização

Lembre-se que um dos principais motivos do uso de Promises é cortar as identações. Embora às vezes seja necessário criar mais níveis porque variáveis podem estar fora de escopo, em muitos casos o código pode ser otimizado de modo a cortar identações. Por exemplo, o caso anterior poderia ser simplificado para:

obterCliente().then( function(cliente) {
    //este bloco aqui ainda depende de "cliente" da closure, então não dá pra cortar identação dele
    return obterCidadeDoCliente(cliente).then( function(cidade) {
        cliente.cidade = cidade
        return cliente
    })
})
.then( obterTemplate ) //"escopo 2"
.then( function(template) { //"escopo 3"
    return '<div>' + template + '</div>'
}).then( function(templateClienteComDiv) {
    mostrar(templateClienteComDiv)
})

Você pode tornar as coisas mais lineares jogando as variáveis comuns entre os blocos para o escopo superior. Aqui jogamos " cliente" pra cima.

var cliente
obterCliente().then( function(_cliente) {
    cliente = _cliente
    return obterCidadeDoCliente(cliente)
})
.then( function(cidade) { //"escopo 1"
    cliente.cidade = cidade
    return cliente
})
.then( obterTemplate ) //"escopo 2"
.then( function(template) { //"escopo 3"
    return '<div>' + template + '</div>'
}).then( function(templateClienteComDiv) {
    mostrar(templateClienteComDiv)
})

Mostrando erros com 1 catch só

Da mesma forma que em código síncrono podemos usar um try para pegar um erro de um grande bloco de código, em um código de Promise um .catch no final de uma sequência faz o mesmo trabalho.

É importante, porém, que o formato dos erros seja padronizado no programa todo. Ou seja, que os objetos de erro não tenham diversos formatos.

Outro erro bem comum é esquecer de usar return dentro de .then()'s. Um return não dado é um fio perdido, tome cuidado.

efetuarRequisicao('https://...') // volta HTTP 400 "O cliente solicitado não foi encontrado"
    .then( logicaDoApp ) //pula aqui
    .catch( function mostrarErro(err) {
        popup(err.message, err.code, err.title)
    }) // mostra na tela "O cliente solicitado não foi encontrado"

Fuja do this

Promises não costumam gostar do uso do this e de classes. Utilize o escopo léxico para guardar estado ao invés de classes.

function Greeter(message) {
    this.greeting = message;
}
Greeter.prototype.greet = function () {
    return "Hello, " + this.greeting;
};

var greeter = new Greeter("world");
Promise.resolve()
    .then( greeter.greet ) // hello, undefined!
    .then(function (resp) {
        console.log(resp);
    });

Solução

    .then( () => greeter.greet() )

async / await (rascunho)

Permite escrever código assíncrono de forma tão limpa como um código síncrono; Porque mesmo
que promises sejam melhores que callbacks, elas ainda sujam o código;
Não disponíveis em browsers mais antigos que 2017.
Ao adicionar o nome async a uma função, essa passa a sempre retornar uma promise e a aceitar
a decoração await;
Com o await, ao invés the escrever fn().then( x => ... ), você escreve var x = await fn().
"promise unwrap transform" seria um bom nome descritivo para ele;
O uso do async/await, mais notavelmente, evita a necessidade de mover variáveis comuns entre
vários blocos .then para um escopo superior.
Se você esquecer de colocar o await em var x = fn(), x agora será uma Promise, nâo o valor retornado
por ela.

Melhor mostrado com um exemplo:

Promise:

api.post('/password-reset-request', (req, res, next) => {
    let _bytes = uuid(), _userName, _userId
    //variávies criadas pra "linearizar" a sequência de promises
    Promise.resolve().then(() => {
        $checkParams(req.body, 'email')
        return connection
        .execute(
            `SELECT u.id AS userId , u.name AS userName, ev.token AS token
                FROM 
                users u LEFT JOIN event_tokens ev ON u.id = ev.user
                WHERE u.email = ?`, 
            [req.body.email])
    })
    .then(([rows]) => {
        if (!rows.length) throw 'SKIP'
        if (rows[0].token) throw Error('Já existe um pedido pendente para este usuário.')
        _userName = rows[0].userName
        _userId = rows[0].userId    
        return connection
        .execute('INSERT INTO event_tokens(user, event, token) VALUES (?, ?, ?)',
            [_userId, 'password-reset-confirm', _bytes])
    }).then(() => {
        return mailer({
            email : req.body.email ,
            subject : 'Redefinição de senha' ,
            content : PWD_RESET_CONTENT(_userName, _bytes)
        })
    })
    .catch( err => {
        if (err === 'SKIP') return
        throw err
    })
    .then(() => {
        res.status(200).send({ token : _bytes })
    })
    .catch(next)
})

Async/await

api.post('/password-reset-request', async (req, res, next) => {
    try {
        //aqui não precisamos "jogar variáveis pra cima"
        $checkParams(req.body, 'email')
        var bytes = uuid()             
        var [rows] = await connection.execute(
            `SELECT u.id AS userId , u.name AS userName, ev.token AS token
                FROM 
                users u LEFT JOIN event_tokens ev ON u.id = ev.user
                WHERE u.email = ?`, 
            [req.body.email]
        )
        if (!rows.length) throw 'SKIP'
        if (rows[0].token) throw Error('Já existe um pedido pendente para este usuário.')
        var { userName, userId } = rows[0]
        await connection.execute('INSERT INTO event_tokens(user, event, token) VALUES (?, ?, ?)',
            [userId, 'password-reset-confirm', _bytes])
        await mailer({
            email : req.body.email ,
            subject : 'Redefinição de senha' ,
            content : PWD_RESET_CONTENT(userName, bytes)
        })        
        return res.status(200).send({ token : bytes })
    }
    catch (err) {
        if (err === 'SKIP') return res.status(200).send({ token : bytes })
        next(err)
    }
})

Concluindo

Espero ter ajudado! Abraço!

Post-review: Migrating Create-React-App to Vite

wkrueger — Tue, 19 Jul 2022 07:07:23 +0000

Previous state

Create-react-app application takes around 3 minutes to build, requiring around 3GB of RAM.

Why Vite

We wanted a quick frictionless migration (so picking a framework like Next is out of scope);
We wanted to avoid low level tools. We want something well-mantained with a good preset out of the box;
It looks like Vite achieved these goals, other similar tooling might have too;

Migration tweaks

This might change a bit depending on what kind of stuff you have in your project. Here's what we had:

Initial setup

Vite's docs doesn't have any article about "migrating from an existing project"; So I have launched a starter project and copied the following files:
- vite.config.ts
- tsconfig.json (adapt accordingly)
- tsconfig.node.json
Review the package.json and remove anything related to Create React App, Babel or Webpack. For instance:
- react-scripts
Also replace the package.json's scripts accordingly. Ex:

    "vite": "vite",
    "start": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "test": "vitest --run",
    "test:watch": "vitest",

Add Vite (yarn add vite). Update TS to the latest version since you don't have CRA locking you to an ancient version anymore;

React plugin

One of the first things to add is the React plugin in the Vite Config. (@vitejs/plugin/react).

Below is shown the final version of the vite config:

/// <reference types="vitest" />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { resolve, parse } from 'path';
import * as fs from 'fs';
import svgr from 'vite-plugin-svgr';

const rootPaths = fs.readdirSync('src').reduce((out, item) => {
  const parsed = parse(item);
  return { ...out, [parsed.name]: resolve('src', item) };
}, {});

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [svgr(), react()],
  resolve: {
    alias: rootPaths,
  },
  envPrefix: 'REACT_APP',
  test: {
    globals: true,
    environment: 'happy-dom',
  },
});

Path mapping

In CRA, folders at the source root can be acessed as absolute paths.

I.e. /src/ListComponent/Somefile.ts can be imported as
import Somefile from 'ListComponent/Somefile'

This special handling doesn't exist on Vite. I have then manually stitched this mapping on vite config's resolve.alias setting.

const rootPaths = fs.readdirSync('src').reduce((out, item) => {
  const parsed = parse(item);
  return { ...out, [parsed.name]: resolve('src', item) };
}, {});

export default defineConfig({
  // ..
  resolve: {
    alias: rootPaths,
  },
});

SVG Imports

Create React App embeds the "SVGR" library. If you use any import like...

import { ReactComponent as MySvg } from './file.svg'

...then this won't work anymore.

A frictionless fix was to add the vite-plugin-svgr shown above (found in a Stack Overflow reply).

Vite is based on Rollup, and SVGR provides its own Rollup plugin, @svgr/rollup. Unfortunately this seemed not to work properly here because Vite already embeds a static file URL plugin, which takes higher precedence. Even following the provided steps to use it alongside the URL plugin didn't work well.

Environment variables

Vite doesnt read environment variables from process.env, but rather from import.meta.env; Also, the NODE_ENV variable is found on the import.meta.env.mode, which is set according to the build environment used (Vite dev server, Vite build or vitest);

Some badly tasting environment variables like BROWSER=none or PORT won't be needed anymore (Vite's server accepts a --port argument like 99% of other software in the world).

The default environment variable safe prefix is VITE_APP instead of REACT_APP. This can be changed on the envPrefix setting (as shown above), as to avoid some refactoring.

Type defs

If you previously had written a strictly typed process.env, you may need to move those types to the corresponding global interfaces ImportMetaEnv and ImportMeta, as shown on the environment variable docs.;

We also need to replace the build tool types. On react.app-env.d.ts, replace:

- /// <reference types="react-scripts" />
+ /// <reference types="vite/client" />

The index.html

The index.html now lives in the root folder. It also requires a new script tag on its body, pointing to the project root:

  <body>
    <div id="root"></div>
    <script type="module" src="/src/index.tsx"></script>    
  </body>

Also, any %PUBLIC_URL% tags must be removed.

<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />

Refactor sync require()'s

On webpack you could still get away with writing a synchronous CommonJS require() anywhere. On Vite this simply won't work out (unless maybe with a plugin);

Default build folder

The default build folder on Vite is dist instead of build. This can be tweaked with build.outDir.

Testing

The quickest way around testing is probably swithing to Vitest, as the Jest test runner kinda relies on Babel/Webpack;

We still kept Jest on the project, we're just not using its test runner anymore. Other parts of Jest like assertions or mocks are still there.

Vitest reads from the same config file (vite.config.ts). You need to add its type directive for TS not to complain:

// on vite.config.ts:
/// <reference types="vitest" />

As shown before, we needed a couple extra settings on the "test" key.

  test: {
    globals: true,
    environment: 'happy-dom',
  },

globals adds the mocha-like globals (describe, test, etc) to the context;
environment allows you to enable JSDOM or other;
When you set an environment, the CLI will suggest you to separately install it.

ESLint

Many ESLint plugins that were previously bundled with CRA had to be manually installed and added.

@typescript-eslint/eslint-plugin
@typescript-eslint/parser
eslint-plugin-jsx-a11y
eslint-plugin-react
eslint-plugin-react-hooks

We ended up with something like this on the eslint.config:

{
  "root": true,
  "parser": "@typescript-eslint/parser",
  "plugins": [
    "@typescript-eslint",
    "jsx-a11y"
  ],
  "extends": [
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:import/recommended",
    "plugin:import/typescript",
  ],
  "settings": {
    "react": {
      "version": "17.0"
    }
  }
}

Build and development

The Vite Dev server does not automatically include TS checking. It suggests you to run tsc on the build task (tsc && vite build). The tsconfig is already suggested with a noEmit.

While you may probably add tsc to the build through a plugin, in the end I think it is better not to, since VSCode already runs its own TS Server. Running tsc on the development server creates a duplicate TS Server.

In case you'd like to check errors project-wide:

you may still run tsc -w
or use a VS Code Task: F1 > Run Build Task > tsc - watch

Since type checking and building are now separate tasks, you may run them on parallel on the CI.

Performance feelings

Build time went to around 25 seconds down from 3 min (could be lower if I hadn't disabled SMT on my processor); While Webpack uses only a single core during most of the build, Vite displays some average activity on all cores.

Peak memory usage went to 1,2GB, down from ~3GB.

The development server starts right away, since it actually didn't compile anything. Pages are compiled as you load them (similar to what happens on Next.js). The development mode may not feel THAT fast on a first page load, since every dependency is served individually. If you look at the requests pane, you can see an enormous number of files being served;
Nonetheless, it is orders faster than Webpacks 3-minute build-of-everything;
Only the files required by a specific page are compiled and served;
This also means that when performing HMR, only the changed files are re-served. HMR feels more responsive;
This may also mean that once the first load is done, the browser may leverage caching of individual files on its side;
On the production mode, the files are bundled more like it happens on other traditional tools. Development and production builds are considerably different from each other. The differences are explained right on the first page of the docs.

Resumo do resumo: Atomic Habits

wkrueger — Sun, 17 Jul 2022 23:23:29 +0000

O resumo de origem: https://www.chrisbehan.ca/posts/atomic-habits. Muito obrigado, Chris Behan (autor do resumo) e James Clear (autor do livro).

Idéias básicas

O que é um habito

Um comportamento ou rotina que, de tanto que repetido, se torna automático, sendo processado pelo subconsciente;
Hábitos podem ser usados positivamente pra te fazer tornar o que quiser na vida. Usados negativamente, se tornam vícios;
Resultados extraordinários são resultados de longos investimentos (os "juros compostos de pequenos resultados"), de centenas de horas de repetição e treino; Não são resultados imediatos;
O mais importante para atingir um resultado é a trajetória;

O funcionamento do cérebro

Seu cérebro funciona contra os seus desejos de resultados. Seu cérebro quer conservar energia e seguir o caminho mais curto; Seu cérebro quer resultados e feedbacks imediatos; Mas grandes feitos não vêm de resultados imediatos, mas sim como resultado de um longo e constante investimento;

As 3 camadas da mudança de comportamento

Identidade, processo, resultado.
Não adianta você repetir na sua cabeça que "quer emagrecer", ou que "quer ser um bom programador"; Não adianta focar no resultado.
Para que se mude um comportamento de forma consistente, você tem que incorporar uma identidade. Seu comportamento é função de sua identidade e de seu ambiente. Se você quer correr, você tem que incorporar "o cara saudável"; Se você quer parar de fumar, incarne o "não fumante";
A partir do momento da incarnação da identidade, as ações ocorrem como consequência de seus princípios, não como tarefas a fazer ("chores");
O processo é um ciclo contínuo. Mesmo após atingir aos objetivos, o processo continua. Você precisa continuar constantemente se reavaliando. Atingir um bom processo é muito importante pois, como anteriormente mencionado, a trajetória é a parte mais importante para atingir a resultados;

A função comportamento

O comportamento é uma função de uma pessoa (e sua identidade) e de seu ambiente;
Disto também segue a idéia que é bom possuir um ambiente dedicado ao seu trabalho, ao invés de compartilhá-lo com o ambiente onde você dorme ou você joga;
"Força de vontade" é um recurso extremamente limitado. Para manipular seu cérebro, além da incorporação de uma identidade, é também eficiente a mudança de ambiente; Ex: se você não comprar chocolate, você não vai comer chocolate;
O ambiente é mais importante do que a disciplina

As 4 etapas da formação de hábito

Estímulo (cue)

Ânsia (craving)

Ação (response)

Recompensa (reward)

Estímulo: Vejo a barra de chocolate;
Ânsia: Imagino o gosto do chocolate
Ação: Como o chocolate
Resultado: Um caminhão de açúcar vai pro meu estômago

Se uma dessas 4 etapas é ausente, o hábito não é estabelecido.

Sobre o Estímulo - Torne óbvio

Crie estímulos óbvios. Sugestões:
- Detalhe a implementação: Crie uma lista de tarefas detalhando as etapas; Programe suas tarefas. "Vou correr às 9 da manhã."
- Agregamento de hábitos: Agregue um hábito que deseja desenvolver a um que você já possua. Ex: Ler um artigo após tomar café;
- Avaliação dos hábitos: Preste atenção em cada pequeno hábito seu e anote em um papel quais são eles e se são bons, neutros ou ruins; Seus hábitos contribuem para você se tornar a pessoa que quer ser?
- Regra inversa: Para remover um hábito, procure esconder seus estímulos. Por ex: desinstale o Twitter do celular;
- O poder da visão: Dicas visuais são as mais efetivas para influenciar nosso comportamento. Deixe dicas para bons hábitos visíveis, esconda dicas para maus hábitos. Ex: Coloque um livro sobre a sua cama para te incentivar a ler antes de dormir;

Sobre a Ânsia - Torne atrativo

Dopamina nos tempos atuais

O sentimento de prazer providenciado pela dopamina para atividades como a alimentação e o sexo traziam motivação para o ser humano pré-histórico para a tomada de ações. Hoje com a vida em sociedade estes estímulos continuam sendo providenciados mesmo que os recursos não sejam mais escassos, o que pode levar a interações não desejadas como a obesidade;
Diversos produtos estimulam reações exageradas de dopamina, como alimentos doces ou jogos eletrônicos. O ambiente moderno é lotado de estímulos exagerados;
A dopamina atua em dois momentos no ciclo do hábito: Na ânsia e na recompensa. A ânsia é o que nos leva à tomada de ação. O efeito de dopamina na recompensa, por outro lado, é mais fraco.

Alguns desejos básicos humanos

Conservar energia
Encontrar um amor e reproduzir (Tinder)
Conectar-se com outros (Twitter)
Ganhar aprovação social (Instagram)
Reduzir incertezas (Google)
Atingir status e prestígio (Jogos eletrônicos)

O Desejo de Pertencimento

O ser humano tende a imitar três grupos de pessoas. Pessoas próximas, a maioria, e os poderosos. As imitações devidas ao desejo de pertencimento pode mudar nossas decisões e comportamentos.

De acordo com as pessoas próximas e com os poderosos que admiramos, podemos tender a imitar coisas diferentes.

A ânsia é preditiva

Duas pessoas podem tomar ações diferentes de acordo com as suas previsões para os atos. Enquanto um fumante prevê o efeito da nicotina, um não-fumante prevê o odor do cigarro em sua roupa.

Tática: Acúmulo de tentações

Unir um hábito que você gosta a um hábito que você precisa, mas que talvez não tenha tanta recompensa imediata. Desta forma a injeção de dopamina de um é associada também a outro. Por ex: Malhar ouvindo uma música que se gosta. Tomar café depois de começar a ler;

Tática: Para gostar de hábitos difíceis

Ao invés de pensar no hábito como uma "chore", pense nele como uma oportunidade única de melhoria. "Vou à academia" ao invés de "tenho que ir à academia".

Atacando maus hábitos na perspectiva da Ânsia

Analizar os desejos que originam o mau hábito;
Notar como o mau hábito na verdade não atende aos desejos básicos;
Substituir o mau hábito por um bom hábito que atende melhor àqueles desejos básicos;

Sobre a Ação - Torne fácil

Quantidade leva à Qualidade

Um professor de fotografia pediu que metade de sua classe focasse em tirar mais fotos, e que a outra metade focasse em tirar melhores fotos.

No final do termo, as melhores fotos foram dos alunos que tiraram mais fotos, pois passaram mais tempo praticando e menos tempo teorizando.

Fazer é melhor do que teorizar;
A repetição leva aos melhores resultados;
Neuroplasticidade: Com as repetições, o cérebro se adapta em áreas relacionadas àquela atividade e acaba criando novas conexões físicas;
Tempo vs. nr. de repetições: O patamar de automaticidade é atingido a partir do número de repetições, não do tempo praticando uma tarefa;

O caminho é um obstáculo

O caminho para se atingir um objetivo pode ser visto como um obstáculo. "Malhar" é o obstáculo para "ficar em forma".

Podemos reduzir a fricção para seguir o processo ajustando o ambiente de acordo. Aqui seguimos lógica similar ao apresentado na seção de estímulos: faça com que seu ambiente incentive e facilite a execução da tarefa. Ex:

Malhar em uma academia no caminho do trabalho;
Comprar alimentos saudáveis;
Disponha objetos de uma forma que crie incentivos pra execução da tarefa;

Atenção às pequenas decisões

Uma pequena decisão aparentemente inofensiva em um momento do dia pode trazer uma grande mudança nas horas subsequentes e dificultar a conclusão de tarefas que tínhamos em mente;

Comece logo

A parte mais difícil de executar uma tarefa é iniciá-la. Comece logo de uma vez; Otimize pra começar mais facilmente;

Evite inicialmente realizar grandes promessas que tornem tarefa cansativa ou mais difícil de concluir. Comece pequeno. Otimize para ter mais repetições.

Atacando maus hábitos na perspectiva da ação

Torne a execução difícil;
"Commitment device"

Lista de ações simples com grande impacto

Usar pratos menores
Instalar cortinas que melhor bloqueiem a luz, para melhorar o sono
Desligar notificações no celular
Comprar uma cadeira de qualidade
Adotar um animal de estimação

Sobre a recompensa - Torne satisfatório

Enquanto os três pontos anteriores aumentam a probabilidade de uma ação ser executada, o ponto da recompensa torna mais provável a repetição da tarefa;

Reitera-se que:

O cérebro é programado pra buscar recompensas instantâneas;
No entanto as melhores recompensas não são aquelas instantâneas, mas aquelas que vêm com atraso (delayed gratification). É necessário algum grau de tolerância e perseverança para trabalhar com recompensas atrasadas;

Táticas

Você pode usar a tática do agregamento para associar uma recompensa rápida a um investimento que não dá recompensa instantânea. Por ex: tomar um suco depois de correr; Esta recompensa, no entanto, tem que aderir com a sua identidade desejada (não adianta se recompensar com cerveja depois de correr);
Use alguma forma de acompanhar seu progresso - como anotações ou um aplicativo. Com isto têm-se pitadas de recompensas no meio do processo, e o foco é alterado para o processo, não para o resultado final;
Nunca falhe duas vezes um hábito programado;
É muito melhor ter uma sessão ruim do que não haver sessão nenhuma. Em certos dias, é mais difícil cumprir um hábito. (ex: Ir à academia em dia de chuva). Estes dias são mais importantes do que os demais, pois neles você tem a oportunidade de superar uma barreira mais difícil e de fortalecer sua identidade;
Não se perca nas métricas: Apesar de o uso de métricas de acompanhamento ser eficiente, não esquecer do cenário e do objetivo maior;

Interesses naturais

Escute a você, não aos outros. Talvez um hábito que você esteja forçando pra si mesmo não seja bem digerido por causa de algum detalhe dele que você não gosta. Ao adaptar o hábito pra uma forma mais compatível você tem mais chances de sucesso;
Hábitos mais alinhados a suas "inclinações naturais" têm mais chances de sucesso; Se você gosta mais do hábito do que a pessoa média, é um grande sinal;
Combine suas habilidades medianas (e que todo mundo sabe fazer) pra criar uma habilidade única e sem competição. Ex: Dilbert (desenho bom + comédia boa = peça excelente);

Acomodação

Puxe progressivamente seus limites, ou você se sentirá desmotivado;
Cuidado com a complacência com hábitos que já estão no automático. Mesmo estes hábitos devem ser eventualmente revisados e aperfeiçoados;
Mantenha a sua identidade mais genérica, de modo que ela possa se adaptar a mudanças mais drásticas na sua vida;

The exhaustive-deps rule has to be treated seriously

wkrueger — Fri, 19 Nov 2021 22:19:54 +0000

(caption: Mrs. Tedesco writing a Todo Application in React with hooks)

It happens when we write useEffect hooks. We intend to just run some code when X changes, but then ESLint tells us to add Y and Z to the dependency list.

useEffect(() => {
  setCount(count + 1)
  // eslint-disable-next-line
}, [])

Ignoring this rule is very bad. It opens up our code to a class of weird bugs (ex: count gets a value from the past). But most importantly, it hides bad design in other parts of the component.

I can strongly claim that EVERY useEffect can be made compliant with the ESLint rule while still mantaining the desired behavior. The solutions might not be straightforward, but it is always better to change other parts of the code than to add the rule. The overal benefit will be more consistent code.

Reviewing what useEffect is for

useEffect is mostly about updating derived state.

We have C that depends on A and B.
When either A or B changes, update C.
This update may be asynchronous.

function Page({ id, mode }: { id: number; mode: 'read' | 'edit' }) {
  const [formData, setFormData] = useState<null|FormData>(null)
  const handleError = useErrorHandler()
  useEffect(() => {
    loadFormContents(id, mode)
      .then(setFormData)
      .catch(handleError)
  }, [id, mode])

  if (!formData) return null;
  return <TheForm formData={formData} />
}

Sometimes we may not straight notice the existence of derived state. The dependency array and the ESLint rule are there to help us. In the example above, the form contents depend on id. What if the page route changes, bringing in a new id? We need to handle the prop change.

useEffect can also happen with an empty dependency array, which showcases that we also need it for async behavior, even when there's no derived state.

Identifying stable references

The ESLint plugin is not able to define every variable's lifecycle. It does the basic work of checking if the variable is defined inside of the component (it is not a constant) and if it is one of the known React stable variables.

If you know that a variable is stable (it won't change between renders), you can just safely keep it in the dependency array knowing that it will never trigger an effect.

Dispatchers have stable reference

The most notable examples of stable variables are setState from useState() and dispatch from Redux. Dispatchers from other React libs are usually expected to be stable.

useCallback and useMemo

When you feed the dependency array with variables you have created, you can double-check if those variables just change their references when their underlying data changes. Check opportunities of making your variables' references more stable with the help of useCallback and useMemo. Forgetting to use useCallback on a function and then feeding it to useEffect can lead to a disaster.

Depend on primitives

Even if an object might have changed its reference, one specific property might have stayed the same. So, when possible, it is interesting to depend on specific properties instead of on a whole object.

Use setState's callback form

We can get rid of dependencies by using the callback form from setState.

const [state, setState] = useState({ id: 2, label: 'Jessica' })

// good
useEffect(() => {
  setState(previous => ({ ...previous, name: 'Jenn' }))
}, [])

// bad
useEffect(() => {
  setState({ ...state, name: 'Jenn' })
}, [state])

In this particular case, we were able to remove the state variable from the array (setState is already recognized as stable by the plugin).

Split into smaller effects

We previously said that useEffect is made to handle derived state.

Let's say we have an effect which updates A and B based on 1 and 2.

1, 2 <-- A, B

Maybe A depends on 1 but not on 2? In this case, we can split a big useEffect into smaller ones.

1 <-- A
2 <-- B

Intermediary dependencies

Effect splitting can also be achieved by identifying intermediary dependencies.

Example before refactoring:

function Component({ userId, event }: { userId: number, event: Event }) {
  const [subscriptionIsExpired, setSubscriptionExpired] = useState(false)
  useEffect(() => {
    const userSettings: { validUntil: string } = await getUserSettings(userId)
    const isExpired = event.startDate > userSettings.validUntil
    setSubscriptionExpired(isExpired)
  }, [userId, event])
  return (...)
}

In the code above, the getUserSettings() request will be called when event changes. But it actually has nothing to do with the event. We may refactor that to:

function Component({ userId, event }: { userId: number, event: Event }) {
  const [userSettings, setUserSettings] = useState<null|UserSettings>(null)
  const [subscriptionIsExpired, setSubscriptionExpired] = useState<null|boolean>(null)

  useEffect(() => {
    const userSettings: { validUntil: string } = await getUserSettings(userId)
    setUserSettings(userSettings)
  }, [userId])

  useEffect(() => {
    if (!userSettings) {
      return
    }
    const isExpired = event.startDate > userSettings.validUntil
    setSubscriptionExpired(isExpired)
  }, [userSettings, event])

  return (...)
}

Now the async request only depends on userId. The second effect continues to depend on both userId (through userSettings) and event.

from:
userId, event <-async-- isExpired

to:
userId <-async- userSettings
event, userSettings <-- isExpired

Offtopic: Loading states

When data is fetched asynchronously, an extra state type arises: the "loading" state. In the example above, the loading state is represented by null. By aknowledging that some state can be null (see the useState line), TypeScript can help us handle edge cases with its null checks.

If we feel that one component became way complex because of multiple loading states, we can choose it to only render when everything is ready; For instance:

Split the component into a parent and a child;
Specify that the child receives the data as non-nullable props. Effectively this removes loading states handling from the child;
Do prior data-fetching in the parent component, which will have the nullable state; Return a loading widget until everything has loaded;
Return the child component when everything is ready;

I actually want to only run an effect once, even if I receive new values

This can still be done without the need for the eslint-disable by copying the dependency to a state or to a ref.

function Component({ id }) {
  // gets the value from the first render
  const [initialId] = useState(id) // or useState(() => id)
  useEffect(() => {
    // ...
  }, [initialId])
  return (...)
}

While this is ugly, it is better than manually picking the dependencies because it is explicit. You are explicitly freezing the value of the variable to the one which came on the first render. Attention: acknowledge the the component won't respond to prop changes, which may cause bugs.

Avoiding useEffects

(new section added as of 2022/10)

Better than optimizing useEffects is avoiding them at all, when possible.

Sometimes this can be achieved by calculating the dependencies on dispatch time.

For instance, let's say document depends on name, one could write:


function handleChange(event) {
  const { name, value } = event.target

  setState(previous => {
    const result = { ...previous, [name]: value }
    if (name === 'name') {
      result.document = getDocumentFromName(name)
    }
    return result
  })
}

The case for useRef

React Refs behave a bit differently from React states:

A state is tied to a render through lexical scope. Each render can reference a different state object from a different slice of time; This may have impact on future concurrent render modes?
A ref is just a property tied to the component. ref.current will always point to the same thing and will always be current, regardless of where you call it;

It is a bit dangerous to talk abour refs without giving possibly wrong advice. Refs are analogous to setting a property in a class component (instead of setting a state), and doing that was considered anti-pattern at the time.

Disclaimers being said, refs are not counted as dependencies for useEffect, so you could get rid of a dependency by turning it into a ref. I'd pin out the following properties of something that can likely be turned into a ref:

It is a value that it is not directly used in the rendered content;
Thus, when you change it, you don't want a re-render;
It is used as a bridge between multiple events on the same component, for instance: communication between multiple effects, outbound and inbound events;

Refs are also used to read values from previous renders and to write advanced memoing hooks as present in popular hooks collections.

Extra: The force render and force effect hacks

An effect can programatically be triggered by receiving a "signal reference".

const [trigger, forceEffect] = useState({})
useEffect(() => {

}, [trigger])

return <button onClick={() => forceEffect({})}>
  Force effect
</button>

References

Nick Scialli - You probably shouldn't ignore react-hooks/exhaustive-deps linting warnings (prev google research)

React daily ramblings: Encapsulated list items

wkrueger — Mon, 01 Nov 2021 17:06:07 +0000

So this is something that should be simple but actually hit me for a while yesterday.

Let's say I want to create a To Do App. Or anything else with a list.

Since we have a list, the task list data would be a state stored in a parent component, and then spread to the children. Something like this:

function Root() {
  const [tasks, setTasks] = useState([INITIAL_TASK])

  return <main>
    <h1>my to do</h1>
    <ul>
      {tasks.map(task => (<TaskView value={task} setValue={...}/>))}
    </ul>
  </main>
}

I have two main goals here:

<TaskView /> must be properly encapsulated. It should not care about WHERE it is put in the application. Thus, it should not know about its index in the array;
In order to improve performance, <TaskView /> will be wrapped in a memo(). In order for memo() to work, we must ensure that its props do not change if its underlying data didnt change.

Approach 1: Setter callback

We write TaskView like this:

(PS: code in this article not tested or linted)

const TaskView = memo((
  { value, setValue }:
  { value: Task, setValue: (cb: (arg: (old: Task) => Task) => void }
) => {
  const handleChangeName = useCallback((event) => {
    const newName = event.target.value
    setValue(old => ({ ...old, name: newName }))
  }, [setValue])
  return ...
})

This is properly encapsulated but brings some challenges when writing the consumer.

function Root() {
  const [tasks, setTasks] = useState([INITIAL_TASK])

  const setTaskAtIndex = useCallback((value: Task, index: number) => {
    setTasks(previous => {
      // ...
    })
  }, [])

  return <main>
    <h1>my to do</h1>
    <ul>
      {tasks.map((task, idx) => {
        const setValue = callback => {
          const newValue = callback(task)
          setTaskAtIndex(newValue, idx)
        }
        return <TaskView value={task} setValue={setValue}/>
      })}
    </ul>
  </main>
}

So the problem here is that setValue will always have a new reference on every render, "rendering" the memo() useless. Since it resides inside a loop with dynamic size, I can't apply useCallback on it.

A naive approach would be adding an extra prop index to the TaskView, but this would be a hack as encapsulation would be broken.

I've tackled this by creating an "adapter component", so that useCallback could be used. Now TaskView should only re-render when its data changes.

function TaskViewAdapter(props: {
  value: Task,
  setValueAtIndex: (value: Task, index: number) => void ,
  index: number
}) {
  const setValue = useCallback((callback) => {
    const newValue = callback(value)
    setValueAtIndex(newValue, index)
  }, [value, setValueAtIndex, index])
  return <TaskView value={props.value} setValue={setValue} />
}

What is different with HTML Events?

An old and common approach on handling lists is the use of data-tags (or other attributes). With this approach, we can reach efficient rendering without the help of an intermediate component.

function Main() {
  const handleClick = useCallback((ev) => {
    console.log('index', ev.target.dataset.index)
  }, [])
  return <ul>
    <li><button data-index="1" onClick={handleClick}>Button 1</button></li>
    <li><button data-index="2" onClick={handleClick}>Button 2</button></li>
  </ul>
}

This only works because the data is being emitted from an HTML event.

What has changed here? Differently from our setValue callback, the HTML event brings context along with the data. It brings the whole element instead of simply the value;

This means the parent can attach data to the element, end then read that data back when handling the event. And the internal implementation of <button> still doesn't need to know that what extra info has the parent attached.

We can attempt to replicate that by, instead of simply emitting data, emitting an event-ish which has extra contextual data about the component. Since custom event emitting is not inside any React "standard", we'd have to pinpoint a standard event format for the particular project.

const event = createEvent({
  component: getSelfRef(),
  data,
})
onChange(event)

Also, (when using Hook Components) there is no way to get the current component reference without involving the creation of a wrapper "Adapter" component. So in the end we fall again into the same case of needing an Adapter.

Brave vs. Edge vs. Opera

wkrueger — Mon, 17 May 2021 21:38:01 +0000

What do they all share

They are all Chromium-Based browsers.

Opera

Opera has performance features, marketed to a gamer audience. You do not need to worry if some tab is eating your CPU. You don't need to install an extra ad-blocker to block potentially crypto-mining websites;
Opera has built-in interface for social media like Twitter; As a developer, I'm completely not a fan as it adds bloat. But might be useful for someone who works heavily with social media;
Opera doesn't have profiles, which is a big NO. For my use cases, profiles are interesting if you have multiple Google, Bitbucket etc accounts for personal and work use. Very useful if you need to log in with non-personal enterprise accounts too.

Brave

The biggest plus in Brave is that it has built in blockers, which help with performance; Brave wants to fight the ad and tracking economy.
Brave wants to promote its "Attention Token" (BAT), which aims to be a monetization alternative;
BAT is a cryptocurrency, and does some fair usage of your CPU to work (EDIT: not anymore. BAT is now farmed with browser ads);
Brave makes compromises for privacy. Some behaviours are limited. For instance, they don't have an internal PDF reader, their dev tools also has features cut from the original Chrome Dev Tools. Some files had no syntax coloring, for instance;
(edit) Brave shows its own ads in notifications (can be disabled) and on its new tab. A bit weird.

(new) Firefox

Firefox feels considerably faster than any other Chromium Browser, since its a different revamped engine;
Font rendering is a bit different;
IMHO: The main downside on Firefox are its Dev Tools. They used to be considerably worse then Chromium's, but now are much closer.

Edge

Edge is my main browser since launch. I have tried both Brave and Opera before in order to replace Chrome, but they didn't stick.

Edge is faster than Chrome. I don't really use side tabs, share, or collections but they are interesting and non invasive; Its reader mode and screen capture work well;
I didn't miss anything from Chrome's DevTools. And they actually add more things on top of it;
Addon compatibility is great. If you can't find the addon you want in the Edge store, you can install it from the Chrome store;
It sleeps inactive tabs and it shows tabs separately on alt+tab (can be disabled);
Although Edge is clean, it seems it walks in the way of feature bloat. It has added a "detect store coupons" feature that didn't catch well for me;

My main goal with replacing the main browser was to have the same featureset Chrome had, but with higher performance, and maybe slightly better UX. So Edge won me.

The second contender to me, very close, is Firefox.

If you don't need to use profiles, Opera might be interesting.

Brave might be your case if you prioritize leaner website loading (less tracker requests) and you want to help fighting the surveillance economy.

Edge is a straightforward replacement for Chrome, its unlikely that you will miss anything from Chrome on Edge, especially on the DevTools department.

React e Redux e gestão de estado em 2021

wkrueger — Mon, 26 Apr 2021 15:53:27 +0000

OBS: Este artigo está desatualizado, uma versão mais refinada encontra-se no meu wannabe blog https://github.com/wkrueger/wkrueger.github.io/blob/master/md/2021-04-redux-state-mgmt/index.md

Uma revisão de porquê e como usar o Redux moderno.

Alguns anos se passaram, o Typescript se popularizou e o Redux tornou-se de uso mais palatável com a introdução do redux-toolkit. O intuito aqui é passar uma revisão (/opinião) de porque o Redux é necessário e como usá-lo, além de passar pontos geralmente ausentes em outros guias.

Sobre o alvo

Embora eu passe conceitos introdutórios, não vou entrar muito neles, pois não pretendo me estender muito. A leitura pode ser complementada com a consulta na documentação do redux, react-redux e redux-toolkit.

Como os dados trafegam entre componentes?

A divisão da interface de usuário em componentes implica a necessidade de tráfego de informação entre estes. Existem 2 principais formas de tráfego de dados.

Props

Props são portas de entrada (e saída) de dados de um componente.

O fluxo ocorre entre um componente e seu pai direto. Para que um componente acesse estado presente em um pai indireto (o pai do pai) via props, o dado tem que trafegar pelo componente intermediário. É como se fosse uma autoestrada passando no meio de uma cidade.

Abaixo exemplos em código representando a imagem acima:

React:

function ComponentWithState() {
  const [productInfo, setProductInfo] = useState('Product')
  return <Intermediary 
    productInfo={productInfo}
    productInfoChange={ev => setProductInfo(ev.target.value)}
  />
}

function Intermediary({ productInfo, productInfoChange }) {
  return <ChildDesiresData
    productInfo={productInfo}
    productInfoChange={productInfoChange}
  />
}

function ChildDesiresData({ productInfo, productInfoChange}) {
  return <input
    type="text"
    value={productInfo}
    onChange={productInfoChange}
  />
}

Injeção de dependências / estado contextual

A comunicação entre o dono do estado e o consumidor é realizada por intermédio de um "portal de dados" (termo livre). Com isso, o dado não precisa trafegar em componentes intermediários.

O filho, consumidor, se registra para receber dados do "Portal";
O detentor do estado se registra para fornecer dados ao "Portal";

No React este "portal" é representado pelo tipo Context. O portal de entrada é o context.Provider, o portal de saída é o hook useContext() (ou o componente context.Consumer).

const thePortal = createContext(null)

function ComponentWithState() {
  const [productInfo, setProductInfo] = useState('Product')
  const payload = {
    productInfo,
    productInfoChange: ev => setProductInfo(ev.target.value)
  }
  // entrada -->
  return <thePortal.Provider value={payload}>
    <Intermediary />
  </thePortal>;
}

function Intermediary() {
  return <div>
    <p>I am intermediary.</p>
    <ChildDesiresData/>
  </div>
}

function ChildDesiresData() {
  // saída <--
  const { productInfo, productInfoChange } = useContext(thePortal)
  return <input
    type="text"
    value={productInfo}
    onChange={productInfoChange}
  />
}

Quando usar props ou estado contextual?

O caso de uso comum para props são componentes reutilizáveis. Componentes que possuirão múltiplas instâncias no documento.

Componentes do sistema de design. Ex: Botão, Bloco, Select, Tabela...
Componentes que serão repetidos em um loop. Ex: Card de Pessoa, Linha de Tabela;

Se o componente não é reutilizado, é interessante acessar os dados via contexto.

Digamos que temos um grande formulário de CRUD, que se colocado todo em um único componente, daria um arquivo com 3000 linhas;
De modo a separar as responsabilidades e organizar o desenvolvimento, esta grande formulário é dividido em muitos componentes menores, com poucas linhas, em múltiplos níveis de aninhamento;
Estes componentes filhos requisitam todos do mesmo componente "pai", que fica na raiz da estrutura. O pai guarda o estado do CRUD e controla suas modificações;
Um componente pode simultaneamente requisitar dados de diferentes "portais" DI.

É um erro comum usar-se mais Props do que deveria. Vamos enfatizar melhor, se o componente não é reutilizável, ele deveria estar obtendo suas fontes via dado contextual.

Onde mora o estado de uma aplicação

O estado é atrelado a componentes. Posiciona-se o estado em um componente pai ou filho dependendo da visibilidade desejada.

Uma peça de estado é geralmente visível (*) aos componentes filho, privada aos componentes pais.

Embora próprio guia do React recomende que você "mova estado para cima", em determinados casos você quer que ele fique "embaixo". Posiciona-se o estado no componente filho quando não interessa ao componente pai saber de sua existência. É tipo como se fosse uma propriedade private.

Exemplo:

function Host() {
  const [value] = useState(2)
  // ...
  return <Autocomplete 
    value={value}
    onChange={handleChange}
    queryOptions={...}
  />
}

function Autocomplete(
  props: { value, onChange, queryOptions: (...) => Promise<Option[]> }
) {
  const [inputText, setInputText] = useState('')
  const [currentOptions, setCurrentOptions] = useState([] as Option[])
  // controla internamente a lista de opções de acordo com os eventos
  // ...
  return <div>
    <InputText value={inputText} onChange={handleTextChange}/>
    <PopperList list={currentOptions}/>
  </div>
}

No exemplo acima

Não interessa ao pai de um componente de Autocomplete saber do conteúdo que o usuário está digitando na caixa de texto (inputText, currentOptions). Interessa a ele apenas o id da opção selecionada;
Desta forma, o ID selecionado não é armazenado no estado do Autocomplete, mas entra via props; Já o valor da caixa de texto é armazenado como estado no autocomplete, tornando-se assim privado ao componente pai;

Redux

É prática recomendada o uso do Redux para armazenar e trafegar dados contextuais (ao invés do Context). No Redux moderno, utilizamos a biblioteca @reduxjs/tookit, quer trás alguns padrões e facilidades.

O que é, como funciona?

A classe abaixo é um container de estado. Ela possui dados e funções (métodos) para a sua alteração;

class StateContainer {
  // estado
  readonly addresses: Address[] = []
  // função
  addAddress(address: Address) { }
}

const instance = new StateContainer()

O Redux também é um container de estado como a classe acima; No exemplo abaixo temos um container redux com propriedades similares;

const slice = createSlice({
  name: 'main',
  initialState: {
    // estado
    adresses: [] as Address[]
  },
  reducers: {
    // função
    addAddress(state, payload: Address) {
      state.addresses.push(payload) // immer
    },
  },
});

const store = configureStore({
  reducer: slice.reducer,
});

O isolamento do estado e de sua manipulação fora dos componentes auxilia na organização de código e escrita de testes;
As funções do container do Redux (addAddress) são invocadas via passagem de mensagens;

// plain class - direct call
instance.addAddress(address)
// redux store - message passing
const action = slice.actions.addAddress(address) // { type: 'addAddress', payload: '...' }
store.dispatch(action);

A característica passagem de mensagens permite a adição de middlewares a chamadas de função, ("chain of responsability");
Funções do redux (reducers) não podem fazer mutações no estado anterior. Retorna-se um novo objeto imutavelmente criado a partir do estado anterior; Isso segue a necessidade do React de termos alterações de estado imutáveis (dentre outras razões);
O redux-toolkit embute a biblioteca immer em suas APIs de reducer. O immer "cria o próximo estado imutável a partir da mutação do atual". Se você retornar undefined em um reducer, o tookit entenderá que você quer usar o immer. Neste caso, você pode fazer mutações à vontade, apenas não retorne nada no reducer.

react-redux

É a biblioteca que integra o Redux ao React (duh);

Principais APIs:

<Provider store={store}>

Passa a store redux no "portal de entrada" do react-redux. Usado na raiz da aplicação. As demais APIs do react-redux exigem e consomem desse portal.

useSelector(selector)

Lê algo da store e passa para o componente. O parâmetro passado para a função é chamado de seletor.

Abaixo um caso de uso correto, e um errado:

// exemplo correto
function Component() {
  const person = useSelector(storeState => storeState.card?.person)
  return <Person person={person} />
}

// uso errado
function Component() {
  const person = useSelector(storeState => storeState).card?.person
  return <Person person={person} />
}

O que muda do exemplo correto pro exemplo errado? Embora em ambos os casos os componentes recebam os dados desejados, no segundo caso o componente fará re-render para qualquer alteração da store. No primeiro caso, apenas quando o dado relevante for alterado.

A sacada aqui então é que o useSelector() permite melhorar a performance da aplicação reduzindo renders desnecessários.

Note que se meramente usássemos a API Context para trazer dados, como foi feito no exemplo lá em cima, teríamos um problema similar ao do "uso errado": Todos os consumidores do contexto dariam re-render para qualquer alteração do valor:

// não ideal também!
function ChildDesiresData() {
  const { productInfo, productInfoChange } = useContext(thePortal)
  return <input
    type="text"
    value={productInfo}
    onChange={productInfoChange}
  />
}

O uso de Context sozinho não é performático, teríamos que implementar um mecanismo de seletores para torná-lo mais eficiente. O react-redux já trás isso.

useDispatch()

As funções do nosso container de estado são chamadas pelo useDispatch.

function Component() {
  const dispatch = useDispatch()
  return <button onClick={() => dispatch(incrementAction())}>
}

reselect

O reselect é utilizado para trabalharmos com "dados derivados". É uma biblioteca que faz composição de seletores, memoizando seus resultados.

import { createSelector, useSelector } from '@reduxjs/toolkit'

const selectPerson = state => state.person;

function calculateHash(person) {
  // some complex calc...
}

const selectPersonHash = createSelector(
  [selectPerson],
  person => calculateHash(person)
)

function Component() {
  const personHash = useSelector(selectPersonHash)
}

No exemplo acima a função calculateHash é computacionalmente intensiva.

Quando Component renderiza, o selectPersonHash retorna uma versão memoizada do hash. O hash só é recalculado quando person muda.

Infelizmente não dá pra usar seletores memoizados pra retornar Promises, pois quando a Promise finaliza isto não ativará num novo render.

Estado global

O Redux quer que você armazene o estado em uma única store global. Você até pode criar múltiplas stores e amarrá-las a componentes mas isto não é recomendado e deve ser usado apenas em casos raros.

Embora você tenha liberade para desenhar o seu estado como quiser, o Redux sugere que você o divida via slices. Na imagem acima temos um exemplo de uma estrutura de projeto e de seu estado global correspondente.

Embora as páginas (Person, Company...) só possam existir 1 por vez, na estrutura do Redux sugerida cada uma delas possui um slot no objeto. Devemos prestar atenção para que o Redux limpe o estado das páginas não abertas, caso contrário teremos bugs;

Correto:

{
  "personPage": { },
  "companyPage": null,
  "invoicePage": null,
  "productPage": null,
}

Errado:

{
  "personPage": { },
  "companyPage": { },
  "invoicePage": { },
  "productPage": null,
}

Uma forma de atingirmos isso é pelo hook useEffect(). Solicite a limpeza do slice relacionado quando o componente for desmontado.

function PersonPage() {
  const dispatch = useDispatch()
  const person = useSelector(state => state.personPage)
  useEffect(() => {
    dispatch(initPersonPage())
    return () => {
      dispatch(unmountPersonPage())
    }
  }, [])

  if (!person) return <Loading/>
  return <Something person={person}/>
}

Construindo o estado

Existem infinitas maneiras de construirmos e manipularmos o estado no redux, e isto é um problema. Para que a comunidade siga um padrão e para que o desenvolvedor tenha um norte, o @reduxjs/toolkit expõe práticas recomendadas na forma de APIs.

Aqui vai um bloco de código grande. Declaramos todo o esqueleto base de uma aplicação. Leia os comentários!

import { configureStore, createSlice } from "@reduxjs/toolkit"
import { Provider, useDispatch, useSelector } from "react-redux"
import { useEffect } from "react"
import { BrowserRouter, Switch, Route } from 'react-router-dom'

/**
 * -- Person slice
 */

interface PersonPageState {}

/**
 * Criamos aqui um bloco de estado para a página "person".
 * Esta definição é encapsulada, não definimos ainda ONDE 
 * este estado vai morar. 
 */
const personPageSlice = createSlice({
  /**
   * este "nome" determina um prefixo a ser adicionado às
   * mensagens das ações.
   * Por ex: o reducer "init" vai gerar uma mensagem com nome 
   * "personPage/init"
   */
  name: "personPage",
  /**
   * deixamos claro que o estado inicial pode ser TAMBÉM nulo, 
   * pois a página pode não estar aberta, ou não estar
   * inicializada.
   * Mas não APENAS nulo. É necessário um cast para que o 
   * typescript entenda todas as possibilidades que esse estado
   * abriga.
   */
  initialState: null as null | PersonPageState,
  reducers: {
    init: (state) => {
      // do something...
      return {}
    },
    unmount: (state) => null,
  },
})

/**
 * -- Product slice
 */

interface ProductPageState {}

const productPageSlice = createSlice({
  name: "productPage",
  initialState: null as null | ProductPageState,
  reducers: {
    init: (state) => {
      // do something...
      return {}
    },
    unmount: (state) => null,
  },
})

/**
 * -- Building the store
 */

const store = configureStore({
  /**
   * aqui definimos onde cada "slice" declarado acima vai morar no
   * estado global
   */
  reducer: {
    personPage: personPageSlice.reducer,
    productPage: productPageSlice.reducer,
  },
  devTools: true,
})

/**
 * -- Wire up redux and TS.
 */

/** 
 * O TS inicialmente não sabe qual é o tipo da sua store. Abaixo segue
 * uma forma recomendada de informá-lo, presente na documentação do redux-toolkit.
 */

type RootState = ReturnType<typeof store.getState>
type AppDispatch = typeof store.dispatch
const useAppDispatch = () => useDispatch<AppDispatch>()

declare module "react-redux" {
  // allow `useSelector` to recognize our app state
  interface DefaultRootState extends RootState {}
}

/**
 * --  Wire up react and redux
 */

function AppRoot() {
  return (
    <BrowserRouter>
      <Provider store={store}>
        <Switch>
          <Route path="/person" component={PersonPage}></Route>
          <Route path="/product" component={ProductPage}></Route>
        </Switch>
      </Provider>
    </BrowserRouter>
  )
}

/**
 * -- Our☭ consumer component
 */

function PersonPage() {
  const dispatch = useAppDispatch()
  const person = useSelector((state) => state.personPage)
  useEffect(() => {
    dispatch(initPersonPage())
    return () => {
      dispatch(personPageSlice.actions.unmount())
    }
  }, [])

  if (!person) return <Loading />
  return <Something person={person} />
}

Conforme comentamos antes, cada página da aplicação tem o seu estado isolado em um createSlice. Estes estados são então combinados na definição da store redux, configureStore. Estes estados podem ser nulos, pois eles correspondem a instâncias de páginas que podem não existir no momento!

Algumas práticas também são recomendadas para que o typescript possa entender melhor o seu estado e assim realizar melhores validações.

Operações assíncronas

As funções de atualização de estado (reducers) presentes no redux são todas síncronas. Existem inúmeras opiniões de como tratar operações assíncronas no redux (por exemplo: thunks ou sagas). O redux-toolkit sugere o uso do createAsyncThunk. Esta escolha não foi tomada levianamente, então vamos seguí-la!

Uma store redux, por padrão, apenas aceita mensagens na forma de um objeto { type: string, payload: any }. O redux-tookit adiciona a opção de passarmos um thunk, que é uma espécie de função iteradora como a abaixo:

const aThunk = async (dispatch, getState) => {
  const data = await readSomething()
  dispatch(syncAction({ data }))
}

Porém, como existem mil formas de tratar erros, o simples uso de um thunk acaba sendo uma opção muito "solta", muito baixo nível. Desta forma, é recomendado o uso do createAsyncThunk, o qual:

Isola a regra de negócio das regras de tratamento de Promise;
Deixa explícito que temos que tratar as alterações de estado da Promise ('idle' | 'pending' | 'succeeded' | 'failed');

Replicarei aqui parte da documentação do createAsyncThunk. O uso básico dele é assim:

const fetchUserById = createAsyncThunk(
  'users/fetchById',
  // if you type your function argument here
  async (userId: number) => {
    const response = await fetch(`https://reqres.in/api/users/${userId}`)
    return (await response.json()) as Returned
  }
)

interface UsersState {
  entities: []
  loading: 'idle' | 'pending' | 'succeeded' | 'failed'
}

const initialState = {
  entities: [],
  loading: 'idle',
} as UsersState

const usersSlice = createSlice({
  name: 'users',
  initialState,
  reducers: {
    // fill in primary logic here
  },
  extraReducers: (builder) => {
    builder.addCase(fetchUserById.pending, (state, action) => {
      // both `state` and `action` are now correctly typed
      // based on the slice state and the `pending` action creator
    })
  },
})

No asyncThunk apenas tratamos de regra de negócio. No extraReducers pegamos o dado de resposta (ou o erro) e determinamos onde que ele vai ficar no estado.

Onde Angular é melhor que React. Parte 1 - A Terceirização

wkrueger — Wed, 24 Mar 2021 21:44:34 +0000

este é um "texto rápido" e incompleto, acabei postando ao invés de deixar abandonado no meu computador...

O React de certa forma me lembra o Express (do node.js) com relação ao escopo da biblioteca. O React foca em uma parte importante, porém incompleta, de uma proposta de criação de interface de usuário. As partes faltantes são completadas por bibliotecas de terceiros ou sugeridas.

Um ponto positivo para essa abordagem é que a comunidade propôe novas e melhores formas de resolver os problemas de uma forma bem dinâmica.

Faço a comparação com o Express porque criar uma aplicação com uma escala e qualidade razoável a partir de apenas Express, e então ir adicionando as partes de terceiros uma a uma, é um tanto improdutivo. Usar um pacote mais integrado, a partir de uma framework bem desenvolvida (Rails, Laravel, Spring Boot, escolha a sua...) trás resultados mais consistentes e padronizados.

O desenvolvimento "terceirizado" também trás mais armadilhas e um caminho menos claro a um novo desenvolvedor. É especialmente fácil errar ou perder algum ponto essencial, quando este não faz parte do núcleo da ferramenta. Isto significa que equipes "reais" são bastante impactadas negativamente pela escolha do React, pois raras equipes são formadas apenas por "sêniors com 5 anos em experiência de React". Mesmo desenvolvedores experientes aprendendo React podem facilmente cair nas pegadinhas.

Um exemplo claro de um ponto essencial ausente no núcleo do React é a funcionalidade suprida pelo redux. O react-redux faz -- de uma forma piorada -- , aquilo que os serviços do Angular fazem: providenciar estado contextual, de modo a evitarmos o "prop-drilling". 3 anos depois a comunidade já sabe que Redux é ruim, mas ainda não tem lá muita certeza de qual das 30 libs disponíveis escolher para resolver o problema que o react-redux se propõe a resolver. Algumas dessas 30 já estão até desatualizadas -- por exemplo ontem fui conferir as docs do MobX e eles não parecem aceitar hooks.

A bagunça é tão grande que o React passou anos sem mesmo ter uma API estável de injeção de dependências, um recurso absolutamente essencial. Mesmo a API atual de contexto é um tanto de baixo nível pra ser usada diretamente, servido mais como bloco de construção para soluções mais elaboradas. Mas tem muita gente já caindo na pegadinha de usá-la em substituição a uma solução decente de gestão de estado.

E finalmente, temos as consequências de um ecossistema que "move rápido e quebra coisas". Cada projeto React de um ano diferente e de um gosto diferente usará libs diferentes para gestão de estado, CSS-in-JS, formulários, roteamento, build, etc. Talvez após alguns anos algumas dessas se tornem legados, ou tenham mudado radicalmente. Não é lá a coisa mais prazerosa de se fazer manutenção. Acabam se criando camadas extras de complexidade sobre algo que inicialmente teria a função de simplificar o desenvolvimento.

Onde o Angular é melhor neste aspecto

O Angular (2+) trás uma gestão de estado poderosa e simples de usar desde o dia 1; Você não precisa de uma lib diferente de gestão de estado para o Angular todo ano, você não precisa engolir todas as limitações do Redux, porque a injeção de dependências resolve o problema, desde o dia 1;
O Angular trás consigo um sistema de build mais completo do que o CRA, com uma forma clara de fazer code splitting, e de organizar a codebase para isso. Já quem pega pra fazer projeto React descobre que tem que fazer code-splitting 2 anos depois, e se não tiver sorte vai ter que refatorar o projeto pois ele não foi planejado pra isso;
O sistema de CSS do Angular busca seguir padrões de propostas da web (CSS com escopo) e é familiar a qualquer desenvolvedor web; No React, bem, já começa que tem que escolher entre umas 5 opções entre CSS global e CSS-IN-JS. Algumas com sintaxe bem criativa;
No Angular você raramente precisa ficar se preocupando com imutabilidade de código, ou fazendo micro-managing de renders. Uma carga cognitiva significativa a menos;
O sistema de roteamento do Angular funciona bem. É estável. Integra com code splitting. Por outro lado o React Router muda todo ano...
Apesar da framework estar em constante atualização, atualizações do Angular são, sem sombra de dúvidas, menos disruptivas do que atualização de umas das 50 libs de React em seu projeto. Ou do próprio React;
Nem tudo é perfeito no Angular. Ninguém é lá muito fã dos formulários reativos. E eles continuarão lá. Não que as pessoas tenham decidido em 2021 como fazer formulário no React (mas no Vue sim).

Uma introdução rápida ao Angular

wkrueger — Sun, 04 Oct 2020 12:36:17 +0000

OBS: Este texto está desatualizado, a versão mais refinada está publicada em: https://wkrueger.gitbook.io/angular/

Angular é a última framework de frontend que aprendi. Antes de trabalhar com ela, eu tinha um pouco de receio de aprendê-la pois a documentação inicial parecia um tanto assustadora. Por outro lado, após começar a trabalhar com ela, vi que não é tão complicada assim, a documentação é que não ajuda...

Neste texto, tento trazer um apanhado BEM resumido de como fazer algumas tarefas comuns no Angular, adicionando links para as fatias relevantes da documentação oficial.

O texto presume conhecimento prévio de desenvolvimento web (HTML/CSS e JS). Também não explico aqui conceitos do Typescript, mas tendo conhecimento em JS dá pra entender o texto.

Ferramentas Recomendadas

Node.js
VS Code
Plugin "Angular Language Service" para o VS Code
Plugin "angular inline 2"

Comparação

Onde o Angular pode parecer mais fácil, se comparado ao React

(alguns comentários daqui são voltados a quem já lidou com React)

O uso de templates HTML e folhas de estilo (ao invés de JSX e CSS-in-JS) é algo mais familiar a pessoas com experiência prévia de web;
(afirmo aqui que) O uso do padrão de injeção de dependências é mais simples e eficiente no gerenciamento de estado e na escrita de mocks para testes se comparado a alternativas populares do React (Redux);
Não é necessário se preocupar em fazer alterações imutáveis de estado (na maioria das situações); O re-render é mais "automágico";
A framework abstrai para si a complexa configuração de build e "code splitting", você geralmente não toca em configuração de webpack;
Módulos sugeridos de formulários e roteador podem não ter a melhor experiência, mas são estáveis;

Iniciando

Instale o Angular CLI npm install -g @angular/cli
Crie um esqueleto de projeto ng new <projeto>
Inicie a aplicação com npm start

Estrutura

Terminologia

Sempre quando falo em template Angular, me refiro a quando se escreve sintaxe de layout (similar ao HTML).

Esta sintaxe é parecida mas não é exatamente HTML pois possui recursos adicionais. O navegador não reconheceria.

Módulos

O ponto de entrada de uma aplicação Angular é o arquivo main.ts (gerado pelo CLI). Esta aponta para o módulo raiz (no caso abaixo, AppModule).

// main.ts
// ...
platformBrowserDynamic()
  .bootstrapModule(AppModule) // <-- AppModule é o módulo de entrada
  .catch((err) => console.error(err))

O módulo raiz aponta que o componente raiz será o AppComponent, via propriedade bootstrap:

// app/app.module.ts
// ...
import { AppComponent } from "./app.component"

@NgModule({
  declarations: [AppComponent], //Componentes e diretivas aqui
  imports: [BrowserModule, AppRoutingModule], // Outros módulos aqui
  providers: [], // Serviços aqui
  bootstrap: [AppComponent], // AppComponent é o módulo de entrada
})
export class AppModule {}

Componentes do Angular devem ser registrados na propriedade declarations para estarem disponíveis em templates.
A aplicação pode ser dividida em submódulos para podermos configurar o code splitting (não é o intuito desse texto). O code splitting é usado pra dividir sua aplicação em partes menores e evitar que o browser fique 1 minuto parado em uma tela branca pra carregar um JS de 15MB.

Docs: introduction to modules.

Componentes

No Angular, um componente é um bloco que une:

Um template "Angular HTML";
Uma folha de estilos com escopo isolado (CSS ou SCSS);
Um arquivo TS para os metadados, estado e a lógica do componente.

O template "Angular HTML" aceita sintaxes específicas do Angular, dentre elas:

Outros componentes podem ser incluídos a partir de suas tags ex: <meu-componente></meu-componente>;
Diretivas do Angular podem criar propriedades personalizadas de elementos. Ex: <div tooltipText="Hello world"></div>

Um componente é iniciado a partir de uma classe anotada com @Component. As propriedades selector e template(Url) são obrigatórias.

import { Component } from "@angular/core"

@Component({
  selector: "app-root",
  template /* ou templateUrl */: `<p>Olá mundo</p>`,
  styleUrls /* ou styles */: ["./app.component.scss"],
})
export class AppComponent {
  algumValor = "Olá mundo"
  umaLista = ["um", "dois", "três"]
}

O atributo selector indica como este componente será chamado dentro do template.
No arquivo de módulo, este componente deve ser registrado na chave declarations;
O template e os estilos podem ser declarados ou "em linha" (template) ou em outro arquivo (templateUrl).

Docs: introduction to components;

Sintaxe do template Angular

Alguns dos recursos suportados pelo template Angular:

Interpolação de variáveis

Qualquer propriedade da classe de componente é disponível no template.
Para interpolação usam-se chaves duplas.

<p>Interpola: {{ algumValor }}</p>

Passando atributos

<!-- 1 -->
<componente entrada="algumValor"></componente>
<!-- 2 -->
<componente [entrada]="umaLista"></componente>
<!-- 3 -->
<componente (saida)="algumaFuncao($event)"></componente>
<!-- 4 -->
<componente [(twoWay)]="variavel"></componente>

Passa a string literal "algumValor" para o parâmetro;
Passa a propriedade declarada na classe para o parâmetro (no caso, umaLista= ["um", "dois", "três"])
Quando componentes emitem eventos, usam-se parênteses. Ex: (click), (hover), (submit);
A sintaxe [(twoWay)] é um atalho para [twoWay]="variavel" (twoWayChange)="variavel = $event";

Ver property binding;

Loops

<div *ngFor="let item of lista">{{ item }}</div>

Condicionais

<div *ngIf="algumValor"></div>

Ver structural directives;

CSS condicional

<div [class.active]="isActive"></div>

Adiciona a classe active se a variável for verdadeira.

Mais informações em attribute, class and style bindings;

Referências

Elementos em um template podem ser referenciados na respectiva classe com a anotação @ViewChild();
Anotações com # são usadas pra auxiliar referências.

// date-picker.component.ts
@Component({ selector: 'date-picker', ... })
export class DatePickerComponent {

  pickDate() {
    console.log('date picked')
  }

}

// app.component.ts
@Component({
  template: `
    <date-picker #datePicker></date-picker>
    <div #theDiv>Hello</div>
  `,
})
export class AppComponent {
  @ViewChild("datePicker") datePickerElement1!: DatePickerComponent
  // ou
  @ViewChild(DatePickerComponent) datePickerElement2!: DatePickerComponent

  @ViewChild("theDiv") divElement!: ElementRef

  ngAfterViewInit() {
    this.datePickerElement1.pickDate()
  }
}

Observe que, para a anotação de tipo (que é opcional) usa-se:

A própria classe do componente (DatePickerComponent), quando o elemento referenciado é um componente Angular;
ElementRef quando é um elemento HTML qualquer;
TemplateRef quando é uma tag <ng-template>

ng-container

Se deseja aplicar *ngIf ou *ngFor sem criar uma div para isso, use ng-container.

<ng-container *ngFor="let num of umaLista">{{ num }}</ng-container>

ng-template

Os elementos dentro de um ng-template não são diretamente renderizados. Ele é usado para passar um bloco de HTML como variável a um componente ou função (exemplo: um modal). Você verá ele sendo usado em bibliotecas de interface de usuário (ex: Material, Bootstrap, etc).

Exemplo (abaixo): Uma biblioteca especifica a diretiva hoverPopup que recebe como entrada uma seção de template. Ao passar o mouse por cima deste componente, um popup com este HTML é exibido.

<ng-template #popup>
  <p>Bem vindo</p>
</ng-template>

<label [hoverPopup]="popup">Exibir</label>

Mais informações na documentação do template Angular.

Notas sobre estilos

Estilos de componentes possuem escopo restrito e isolado a esses componentes. Isto significa que componentes filho, por padrão, não recebem o estilo do componente pai;
Este comportamento pode ser burlado com o seletor ::ng-deep *;

(*) O seletor ng-deep é deprecado mas não tende a ser substituído até que um equivalente seja oficialmente publicado nas especificações do CSS.

.componente-filho ::ng-deep svg {
  stroke: black;
}

:host {
  /* estilos *deste* componente */
  display: block;
}

O seletor :host é usado pra aplicar estilos à raiz do componente;
Além dos estilos isolados de componente, o projeto também conta com estilos globais, que são os presentes na raiz src/styles.scss.

Fluxo de dados

Duas das principais formas de trasmitir dados por uma aplicação Angular são:

Propriedades de entrada e saída de componentes;
Injeção de dependência (serviços);

Propriedades de entrada e saída

Entrada

Anote uma propriedade com @Input() para amarrá-la a uma entrada do componente.

@Component({
  selector: "app-some-component",
  template: `<button type="button">{{ texto }}</button>`,
})
export class SomeComponent implements OnChanges {
  @Input() texto = ""

  ngOnChanges(changes) {
    // fazer algo
  }
}

@Component({
  selector: "app-consumer",
  template: `<app-some-component texto="Clique aqui"></some-component>`,
})
export class ConsumerComponent {}

No exemplo acima, um botão é desenhado com o conteúdo "Clique aqui".
O método opcional ngOnChanges é chamado sempre que uma @Input() sofrer alteração.
A interface (também opcional) implements OnChanges trás ajuda de tipos para o método ngOnChanges.

Saída

Um componente envia sinais de saída a partir de EventEmitters anotados com @Output();

Ao escrever EventEmitter, o editor dará várias sugestões. Selecione a pertencente ao @angular/core.

Emissor:

@Component({
  selector: "app-output",
  template: `<button type="button" (click)="processarClique($event)">Click me</button>`,
})
class OutputComponent {
  @Output() fuiClicado = new EventEmitter<Date>()

  processarClique(ev) {
    this.fuiClicado.emit(new Date())
  }
}

Consumidor

@Component({
  selector: "app-consumer",
  template: `<app-output (fuiClicado)="tratar($event)"></app-output>`,
})
class ConsumerComponent {
  tratar(ev) {
    console.log(ev) // irá logar a Data atual
  }
}

Ver inputs and outputs.

Serviços e injeção de dependência

Uma classe anotada com @Injectable() pode ser atrelada a um módulo ou componente;

Você define a quem o "injetável" está atrelado passando a classe ao atributo providers do componente ou módulo;
Por exemplo, se você passar o serviço MeuServico ao providers do componente MeuComponente, uma instância desse serviço (new MeuServico()) será criada para cada MeuComponente. Quando MeuComponente for destruído, a instância do serviço também é destruída e é invocado o método ngOnDestroy();
Se você passar um serviço ao módulo raiz, este serviço efetivamente será um Singleton (instância global).

@Injectable()
class MeuServico {
  dizerAlgo() {
    console.log('algo')
  }
}

@Module({ 
  ...,
  providers: [MeuServico]
})
class MeuModulo {}

@Component({ 
  ...,
  providers /* ou viewProviders */: [MeuServico]
})
class MeuComponente {}

Consumindo o serviço

Acesse o serviço o passando como parâmetro no contrutor da classe.

@Component(...)
class MeuComponente {

  constructor(private meuServico: MeuServico) {}

  aoClicar() {
    this.meuServico.dizerAlgo()
  }
}

Diz-se aqui que uma instância de MeuServico foi "injetada" em MeuComponente;
Caso o serviço não tenha sido especificado em nenhuma chave providers, o Angular vai reclamar;
Caso o serviço tenha sido providenciado em vários lugares (no módulo e no componente), a instância mais local (a do componente) é fornecida;

providers vs. viewProviders

Serviços fornecidos pela chave providers de um módulo são acessíveis em todos os componentes deste módulo.

Por outro lado, quando um serviço é passado na chave providers de um componente, ele não é acessível para injeção nos componentes filho.

Quando o serviço é fornecido em um componente pela chave viewProviders, este é também acessível nos componentes filhos.

Serviços fornecidos a módulos e a viewProviders trazem funcionalidade paralela ao que faz o "context" no React.

Qual é a utilidade desta complicação

Além da funcionalidade de delimitação de contexto, a injeção de dependências é de grande utilidade em mocks para testes.

Quando uma classe especifica que quer consumir ServicoA, ela não necessariamente recebe a classe exata ServicoA. Você pode passar qualquer outra classe ao providers que atenda ao mesmo contrato. Ex: As ferramentas de teste permitem que se instanciem módulos injetando serviços "dublês".

Documentação: introduction to services and dependency injection;

Roteador

O Angular gera uma aplicação "single page", e o roteador é um componente importantíssimo neste contexto. O roteador permite com que a aplicação não seja totalmente recarregada quando se troca de página.

O que o roteador faz? Em resumo:

Providencia um componente <router-outlet>;

Exemplo: No boilerplate padrão do Angular, o <router-outlet> é elemento único do componente raiz.

@Component({
  selector: "app-root",
  template: ` <router-outlet></router-outlet> `,
  styles: [],
})
export class AppComponent {}

Solicita a configuração de um mapeamento entre URLs e:
- Componentes ou
- Módulos com subroteadores ou
- Redirecionamentos

Exemplo

const routing = RouterModule.forRoot([
  { path: "", component: IntroComponent },
  { path: "gato/:id", component: GatoComponent },
  {
    path: "cachorro",
    loadChildren: () => import("./Cachorro/Cachorro.module").then((m) => m.CachorroModule), // usado para "code splitting"
  },
  { path: "capivara", children: [...] },
  { path: "**", redirectTo: '' }
])

@Module({
  ...
  imports: [routing, ...]
  ...
})
export class AppModule {}

Sempre que um URL é alterado (ou no carregamento inicial de uma página), o componente correspondente é carregado no "outlet";
Fornece os serviços a seguir que podem ser injetados:
- ActivatedRoute pra determinarmos informações sobre o estado do roteador. Como: qual rota está ativada? Quais os parâmetros de URL?
- Router, que é usado pra controlar o roteador (ir para...);

@Component({ ... })
class AlgumComponente {

  constructor(private route: ActivatedRoute, private router: Router) {}

  async ngOnInit() {
    const queryParams = await this.route.queryParams.pipe(take(1)).toPromise()
    console.log(queryParams)
  }

  goto() {
    this.router.navigate('/someroute', { queryParams: { hello: 'world' } })
  }

}

O uso de links padrão do HTML (<a href="/page"/>) não é amigável pra SPA's pois fazem recarregar a página toda; Deve ser usada ao invés disso a diretiva routerLink fornecida pelo roteador.

<a [routerLink]="['/hero', hero.id]">Goto hero</a>

Subroteadores e múltiplos outlets: Conforme apontado anteriormente, é possível haver "roteadores filho". Neste caso haverá no HTML um <router-outlet> dentro de outro. Há também funcionalidade avançada onde um roteador pode controlar múltiplos outlets.

Mais informações no (extenso) guia do roteador.

O que mais falta

A idéia deste artigo é dar uma introdução rápida ao mais importante da framework, já que a documentação oficial pode ser um tanto intimidadora ao iniciante. Por este ser um breve resumo, muita coisa foi deixada de fora pra não tornar o artigo muito extenso. Alguns dos principais pontos adicionais para consultar futuramente (e seus respectivos links pra doc oficial):

Módulo de formulários;
Publicando a aplicação;
Ciclo de vida do componente;
Testes e2e e unitários
Usando (ou fugindo do) RxJS;
Usando (ou fugindo do) cliente HTTP do Angular;
Dentre outros...

(Doguinho aleatório da capa by Alexandru Rotariu from Pexels)

Muito obrigado!

(yet another) Introduction to Typescript

wkrueger — Mon, 11 Nov 2019 07:35:59 +0000

OBS: This article is outdated. Most recent versions live in https://wkrueger.gitbook.io/typescript/

This aims a reader who already has some modern JS experience and is curious about TS. Special focus is given on presenting how the type system works.

What will we go through:

What is typescript for? What typescript isn't. Why. Why not;
Set it up as simply as possible;
Type system overview;
Caveats from someone used to JavaScript;

Index:

1. What does TypeScript do?
2. What TS is NOT for
3. The simplest build possible
4. Types are spooky (how types work)
5. Mutable code and types
- Productive use of loose types and any
6. Primitive types
7. Interfaces vs. Type Aliases
8. Class'es particularities
9. Structural typing and you
11. Control flow analysis
11. Other more advanced type syntaxes
12. Generics
13. Modules
14. 3rd party types

(PS: This ended up being a quite lengthy text, but splitting it didn't really seem a cool idea).

Asterisks (*) scattered around the text indicate parts where I admit I may be sacrificing canonical correctness in favor of prose terseness.

1. What does TypeScript do?

Type checking, works like a linter

TypeScript is used as sort of an advanced linter, as it points errors in your code based on the coherence of the data structures present in it. I emphasize the term linter here because type-check errors really don't block your code from being compiled. The errors are just there to provide you hints.

In order to collect those data structures, TS uses inference in your code. TS already knows a lot of type data from plain JS alone, but you can also complement those with extra type annotations.

JavaScript compilation

As type annotations are not understood by JS parsers, source .ts files must be compiled to .js in order to remove those. Typescript itself includes a compiler and nowadays this can also be done with Babel.

The TS language aims to keep aligned with JS and proposals that had reached stage 3 ("surely coming to JS"). TS aims NOT to include extraneous features that are not or won't be part of JS.

So, by writing TS, you are mostly writing a near future version of JS with types. As with Babel, you can then choose which target to compile (how old is the browser or node.js version you wish to support).

Language services

Language service support is a big focus and differential of TypeScript. A language service is a layer which aims to provide editor goodies like tooltips, navigations, completions, refactors, and suggestions, a dozen of small features which actually bring big improvements in developer experience. The opposite case would be a language in which you only get the compiler feedback when you save a file.

As the TS team works in tandem with the VSCode team to provide its JS language service, its editor experience is very refined.

2. What TS is NOT for

Writing OOP-styled code like C# or Java;

As TS is mostly "JS with types", you should just write TS as you would write JS, whatever code style you prefer. As classes are a JS feature, you could already write classy code in plain JS.

Making my code verbose, littered with type annotations;
Force me into writing in OOP style;

Since it is made to fit already existing JS patterns, TS's type system is quite flexible. The type system does not strongly dictate what patterns you should use. This, paired with the heavy use of inference allows for the usual TS code to have a small amount of type annotations.

Due to the nature of static typing, you will eventually need to adapt some dynamic patterns or lean to more functional patterns, but those will be tiny and beneficial changes. More info on that ahead.

Real cons of using TypeScript

Setting up TS in modern frontend projects (webpack-based) used to be a pain. This has changed drastically since the Babel integration came, along with support on popular templates like create-react-app. Community support in this area has now raised a lot, bringing goodies like better library typings.

3. The simplest build possible

Using the TypeScript compiler (tsc) is the most simple way to get started. Probably simpler than any Babel-related setup you've ever used. tsc can be added to your PATH by globally installing TypeScript (npm i -g typescript).

tsc -w main.ts

... generates a main.js file in the same folder with default compiler settings. -w toggles the watch mode.

A simple project

For a project, it is recommended that you install TypeScript locally so that your project is tied to a specific TS version. In VSCode, tsc can be invoked through F1 > Run Build Task. You should also include a link for it in the package.json scripts.

tsc looks for a tsconfig.json file in the same folder. This also allows it to be called without arguments. The tsconfig accepts an overwhelming set of compiler options -- since it mixes compiling and type checking options. Below I'll go through a set of recommended settings.

{
  "compilerOptions": {
    ...
  },
  "include: ["src"]
}

include filters which files to compile. This can be a folder or an entry point (every file referenced by that entry point will also be compiled);

I will usually split input and output files in different folders:

|__ built
| |__ index.js
|__ src
| |__ index.ts
|__ tsconfig.json

By default tsc outputs to the same folder the source files are. Use "outDir": "built" to fix that;

  "sourceMap": true

Sourcemaps allow you to debug directly in the source .ts files.

  "target": "es2017",
  "module": "esnext",
  "esModuleInterop": true

Those 3 are output settings:

target dictates how old is the runtime you want to support;
module allows for import/export syntax conversion; You'd usually use "esnext" (no conversion*) when using a bundler, or "commonjs" for node;
esModuleInterop is an es-modules "quirk" fix;

  "strict": true,
  "noImplicitAny": false,

Type-checking options:

strict turns on all of the latest type-checking features (very important);
noImplicitAny disables one specially annoying feature with a good trade-off (personal opinion);

  "lib": ["dom", "es2015", "es2017"],

libis entirely optional and allows tuning of which global-environment types are available; For instance, the default setting includes "dom", but you'd like to disable "dom" types in a node.js project.

Concluding it, we got:

{
  "compilerOptions": {
    "target": "es2017",
    "module": "esnext",
    "esModuleInterop": true,
    "strict": true,
    "noImplicitAny": false,
    "lib": ["dom", "es2015", "es2017"],
    "outDir": "dist",
    "sourceMap": true
  },
  "include": ["src/index.ts"]
}

4. Types are Spooky (or: How Types Work)

Types live in a separate world set apart from the "concrete variables" world. Think of it as the "upside-down" of types.

If you try to declare both a concrete variable and a type with the same name, they won't clash, since they live in separate worlds.

const x = 0;
type x = number; //this is ok!

Types are declared by either the type or the interface statements. While those constructs may have peculiarities in syntax, just consider they are just ways to declare types. In the end a type will just represent some structure, regardless of which of the 2 statements you used to declare it*.

interface Animal {
  weight: number;
}
// the word "interface" may be misleading.
// In TS, "interface" just means representing a JS object type
// since it is just a JS object, any property type is allowed, not just methods

Types are immutable

You can't ever modify a type, but you can always create a new type based on another existing one;

interface Cat extends Animal {
  isCatnipped: boolean;
}
type MeowingCat = Cat & { meow(): void };
// We have
// - created new types based on existing ones
// - both "extends" and "type intersection (&)" syntaxes ended up performing the
//   same structural operation: adding a new property the type

A purpose in life

The final purpose of a type is to be linked to a concrete "living" variable, so its sins can be checked by the compiler.

const myFatCat: MeowingCat = {
  weight: 2.4,
  iscatnipped: false, //error!!
  meow() {
    performMeow();
  }
};

What if I don't assign a type to a variable?

Every variable will always have a type. If I don't explicitly assign a type, the compiler will then infer one from the initial assignment; On VSCode, one can easily check the type of anything by mouse-overing.

const barkingFatCat = {
  ...myFatCat,
  bark() {
    throw Error("bark not found");
  }
};
// will have weight, iscatnipped, meow and bark properties

An important advice about working with typescript: **mouseover everything**. Every variable. Every time. Extensively.

Seriously, you can do a big bit of "debugging" just by carefully inspecting every variable's inferred type.

A lifelong link

One variable can only have one type during its whole lifespan. However, you can still create new variables and do casts;

Going the other way

The inverse operation -- retrieving a type from a variable -- is possible with the typeof statement. type StrangeCat = typeof barkingFatCat.

5. Mutable code and types

Because of the properties listed above, some patterns that you might be used to in JS may not work well on a static type system. For instance, let's say one would create an object like this:

const person = {};
person.name = "John"; // error!
person.lastName = "Wick";

TS will complain since person is declared by inference to be of type "empty object". Therefore, person can't accept any properties.

There are many ways we could adapt our code to tackle this problem. The most recommended one is: build the final object in one step, composing its parts.

const person2 = {
  name: "John",
  lastName: "Wick"
}; // OK!

Other more verbose way is pre-declaring the object type. This is not ideal though, since we are repeating ourselves.

interface Person {
  name?: string;
  lastName?: string;
}
const person3: Person = {};
person3.name = "John";
person3.lastName = "Wick";

If you are having a hard time typing something, you can always assign a variable to any, disabling all type-checking on it.

const person4: any = {};
person4.name = "John";
person4.last.name = "Wick"; // this won't type-error, even if wrong

On the productive use of `any` and other loose types

Every time a developer assigns any to a variable, it acknowledges that TS will stop checking it, facing all the consequences this may bring.

While it's not advisable to use any, sometimes it can be hard to correctly set the type of a variable, especially when learning the language - or even when facing its limitations. Using any is not a crime and sometimes is necessary and productive. One should balance between not using any excessively but also not to spend much time trying to fix a type error.

6. Syntax primer: Primitive types

All primitive types are referenced in lowercase. number, string, boolean, undefined, null...
TS adds a couple of extra lowercase types solely related to its type-checking job: any, unknown, void, never...
Arrays can be declared either by something[] or Array<something>;

Be careful: There also exists an uppercase Number type, which is a different thing from lowercase number! Types like Number, String, Boolean refer to the javascript functions that have those names.

Be careful: Both types {} and object refer to an empty object. To declare an object that can receive any property, use Record<string, any>.

Strict nulls

Unlike some other languages, types do not implicitly include null;
Ex: in Java, any variable can always also be null;
In TypeScript a type is declared as nullable through a type union: type X = Something | null | undefined
A type can be narrowed as "not null" through control flow analysis. Ex:

const x = 2 as number | null
if (x) {
    console.log(x) // x cannot be null inside this block
}

You can tell the compiler to assume a variable is not null with the ! operator;

interface X {
    optional?: { value: number }
}
const instance: X = {}
console.log(instance.optional.value) // TS will show error
console.log(instance.optional!.value) // assume "optional" exists

7. Interfaces vs. Type Aliases

Which one to use? Whatever... both declare types! It is complicated.
Type aliases can receive other things than objects; Most noticeable exclusive to those are:
- Type unions and intersections;
- Conditional types;
Interfaces work exclusively with objects (functions are also objects!). Exclusive to interfaces are:
- The OOPish extends clause, which is somewhat similar to the type intersection of two objects;
- Declaration merging. When you declare 2 interfaces with the same name, instead of clashing, their properties will merge. (They can still clash if their properties are incompatible, of course);
- Common use of declaration merging: Add another property to the global DOM's Window declaration.

interface Animal {
    name: string
    isDomestic?: boolean  // optional property, receives type boolean|undefined
    readonly sciName: string  // forbids mutation. Notable sample: react's state
    yell(volume: 1 | 2 | 3 ): void
      //  - types can receive constants (1 | 2 | 3)
      //  - the "void" type is mostly only used in function returns, and
      //    has subtle differences from undefined
    (): void
      // declare this object as "callable" - this is hardly ever used.
    new (): Animal
      // declare this object as "newable" - this is hardly ever used.
}

interface Cat extends Animal {
    isDomestic: true   // narrows down parent's `isDomestic`
    meow(): void;      // additional property
}

// merges with the interface above
interface Cat extends Animal {
    purr(): void
}

Type alias sample below. Almost the same capabilities and syntax.

type SomeCallback = (i: string) => number
type DiscriminatedUnion = { type: 'a', data: number } | { type: 'b', data: string }

type Animal = {
    name: string
    isDomestic?: boolean
    readOnly sciName: string
    yell(volume: 1 | 2 | 3 ): void
    (): void
    new (): Animal
}

type Cat = Animal & {
    isDomestic: true
    meow(): void
}

// declaration merging not possible

8. Class: a creature that spans both worlds

Classes in TypeScript have a few extra features compared to JS classes, mostly related to type-checking.

You can declare uninitialized properties on the class body; Those don't generate JS code, they just declare types for checking.
If a property is not initialized on the constructor, or directly, TS will complain. You can either declare a property as optional (append ?) or assume it is not null (append !).

class Foo {
    constructor(name: string) {
        this.name = name
    }
    name: string
    hasBar?: string
    certainlyNotNull!: number
}

Access modifiers (private, protected and public) are a thing; Yet again, they only serve as hints to the type-checker. A private declared property will still be emitted and visible in JS code.
Class fields can be initialized in-body (same as JS, recent-y proposal);

class Foo {
    // ...
    private handleBar() {
        return this.name + (this.hasBar || '')
    }
    init = 2;
}

Unique to TS, you can add modifiers to constructor parameters. This will act as a shorthand that copies them to a class property.

class Foo {
    constructor(private name: string) {} // declares a private property "name"
}

Both worlds

The class statement differs from most others are it declares both a variable and a type. This is due to the dual nature of JS/OOP classes (a class actually packs 2 objects inside one definition).

class Foo {}
type X = Foo          // "Foo - the type" will have the INSTANCE type
type Y = typeof Foo   // Y will have the PROTOTYPE type
                      // (when writing typeof, "Foo" refers to the "living foo",
                      // which in turn is the prototype)
type Z = InstanceType<Y>  // the inverse operation
var foo = new Foo()   // "Foo" exists in both worlds;

9. Structural typing and you

In order to determine if two types are assignable, the compiler exhaustively compares all their properties.

This contrasts with nominal typing, which works like:

Two types only are assignable if they were created from the same constructor OR from an explicitly related constructor. (explicitly related usually means: extends or implements).

Given two classes A and B:

class A {
    name
    lastName
}

class B {
    name
    lastName
    age
}

Now let a function require A as input.

function requireA(person: A) {}
requireA(new A()) //ok
requireA(new B()) //ok
requireA({ name: 'Barbra', lastName: 'Streisand' }) //ok
requireA({ name: 'Barbra', lastName: 'Streisand', age: 77 }) //error

The function accepted B as input since its properties were considered assignable;
This would not be allowed on nominal typing, since it would require B to explicitly extend or implement A;
Since we are just comparing properties, just directly passing a conforming object also works;
The last line errors because TS applies a special rule which enforces exact properties if the argument is a literal;

10. Control flow analysis

At each instruction, a variable's type may be narrowed according to the current context.

function cfaSample(x: number|string) {
  console.log(x)  // : number|string
  if (typeof x === 'string') {
    console.log(x) // : string
    return x
  }
  return [x] // [number]
} // inferred return type: string|[number]

Some expressions (typeof x === 'string') act as "type guards", narrowing the possible types of a variable inside a context (the if statement);
x is narrowed from number|string to string inside the if block;
x only can by number at the last line, since the if block returns;
The function gets an inferred return type corresponding to an union of all return paths;

Discriminated union

The type Actions below is called a discriminated union . The property type is used as a tag to filter out which of the union options is valid at the context;
At each case line below, action.data has its type narrowed down;

type Actions =
  | { type: "create"; data: { name: string } }
  | { type: "delete"; data: { id: number } }
  | { type: "read"; data: number }

function reducer(action: Actions) {
  switch(action.type) {
    case 'create':
      return createFoo(action.data) // data: {name: string}
    case 'delete':
      return deleteFoo(action.data) // data: {id: number}
    case 'read':
      return readFoo(action.data)   // data: number
  }
}

11. More advanced type syntaxes for another day

(A veryfast reference overview below. Don't worry if you don't understand something, just know that those exist, so you can research later.)

Mapped types is a syntax used to declare generic objects.

type GenericObject = {
    requireMe: number
    [k: string]: any
}
// GenericObject CAN have any property and MUST have `requireMe`

Mapped types can be used to remap one object type to another, by iterating over its keys.
keyof lists all possible keys of an object type as a type union;

type Dummy = {
    a: string
    b: number
}
type Mapped = {
    [k in keyof dummy]: { value: dummy[k] }
}
// wraps Dummy's values into a { value: x } object

Properties may me accessed with [""]

type X = Dummy['a'] //will return `string`

Conditional types were created to solve a dozen of the type system's limitations. Its name may be misleading. One of the dozen things conditional types can do is to "pick" a type from inside another type expression. For instance:

type Unwrap<T> = T extends Promise<infer R> ? R : never
type X = Unwrap<Promise<number>>  // X will be 'number'
// this sample also uses generics, which we will cover soon

The standard type lib includes some auxiliary type aliases like Record and Omit. All of those type aliases are made by composing the features previously shown. You can check all available helpers and its implementation by CTRL+Clicking any of them.

type DummyWithoutA = Omit<Dummy, 'a'>

When you want to dig deeper, I'd strongly recommend checking the Typescript playground samples session.

12.Generics

Roughly saying, generics are types which can receive type parameters. Like every other type related feature shown, it does not emit any extra JavaScript output.

interface GenericInterface<Data> {
    content: Data
}

type FunctionOf<X, Y> = (i: X) => Y

// functions and classes can also receive type parameters.
function makeData<Input>(i: Input) {
    return { data: i }
}

function cantInfer<Output>(i: any): Output {
    return i
}

class GenericClass<Input> {
    constructor(public data: Input) { }
}

A type parameter can receive a default type, making it optional.

function hello<X = string>() {
    return {} as any as X
}

Argument inference

A generic function will, at first, require that you supply its type parameters;

cantInfer(2) // error
cantInfer<string>(2) //okay

If the type parameter has a default value, it is not required;

hello() //ok
hello<Promise>() //ok

If type parameters are referenced in function arguments and NO type parameters are passed on call, TS will try to infer them from the arguments;

function makeData<Input>(i: Input) {
    return { data: i }
}
makeData(2) // Input gets inferred to `number`
            // return type is inferred to { data: number }
makeData<string>(2)  // will raise an error since type parameter
                     // and argument are incoherent

Bounded type parameters

A type argument can have constraints;

function acceptObject<Input extends { x: number }>(i: Input) {
    return i
}
acceptObject({}) // error, must at least have x
acceptObject({ x: 2, y: 3 }) // ok, and returns { x, y }

13. Modules

TypeScript is made to adapt to JavaScript. And JavaScript itself has had many module systems for different environments and times. Most notably:

The browser console "vanilla" environment is module-less. Every imported file lives in the global scope;
node.js traditionally uses the "commonjs" module syntax;
Modern front-end code built with module bundlers usually use the "es-modules" syntax;

Module-less typescript

A TypeScript file is considered module-less if it has no imports or exports;
All typescript source files share the same global context. Which is defined at the include entry of the tsconfig;
A file can manually include a reference through the addition of the "triple slash directive" at the first line. Shivers from the good-ol-triple-slash-directive-times?

///<reference path=“./path/to/file”/>

Moduleful typescript

The TS import syntax comes from the es-module syntax;
You can also write some additional syntax not covered by the es-modules:

import express = require("express") // enforce commonjs import
const express = require("express")  // this works BUT 3rd party types won't get imported
import * as express from 'express'
import express from 'express' // only works with "esModuleInterop"
export = { something: 'x' } // "module.exports =" syntax from commonjs

14. 3rd party types

One can usually obtain types from 3rd party libraries through the following means:

The library itself publishes .d.ts definitions along with the package, referencing it on the typings key of package.json;
Someone publishes types for the library at the DefinitelyTyped repository, available through npm @types/<lib>;
There are methods for manually declaring a 3rd party library's types inside the consumer project;

What if the library does not have types?

The library will be imported as any but you can continue to use it as-is;
If noImplicitAnyis turned on, a declare "library" entry must be declared in a global file;

3rd party typescript types are also used to power JS type completion in VS Code.

Thats it!

And that was only supposed to be an introduction! Thank you!

Integrating APIs to a TypeScript frontend with OpenAPI/Swagger

wkrueger — Thu, 07 Nov 2019 02:08:47 +0000

Http-served REST and HTTP + JSON has became popular with great human readability, we can fairly easily call remote functions with a curl line on console.

While it is great to have an highly readable exchange format, I also strongly lean to the opinion that calling an API through HTTP should ideally feel as integrated as calling a function from an imported library.

If you use web frameworks like Django, Rails, Spring or Nest.js you can easily produce OpenAPI definitions through your application code, since those gather information enough to collect not just which routes are exposed, but also which data types they use to communicate. OpenAPI serves as a solid exchange format to help API metadata traverse between different languages.

Objectives

Given some REST API and its OpenAPI definition, I'd like to invoke this API's methods from my TypeScript front-end codebase in a type-safe way, just as functions, abstracting away details from the (http) protocol.

We will be using SendGrid's REST API as an example here. The link includes an OpenAPI representation as both json or yaml. While they have a custom render for this API on their website, you could also paste the .yaml into the swagger editor.

Let's take as a sample a random method:

OpenAPI includes a decent handful of information about that API, such as:

Which methods are available;
Which input parematers they take;
What is the data type of its response;
Documentation comments;

I'd like to call this interface on my code as simply as



const updatedAlert = await updateAlert({
  alert_id: 123,
  data: { email_to: "example@example.com" },
  "on-behalf-of": "someuser"
})

The way the API definition maps to code may vary according to the tool we use for the integration. Nonetheless I'd like to point out a couple of features I desire for this API call:

It should abstract out the protocol; An HTTP call has parameters split between path, query, headers and body parameters. That body can be JSON or URL-encoded. And we also have a verb. On the other hand, when writing code, our tools are just function names and input parameters. How each parameter is sent over HTTP is not part of the API intent, but mostly a protocol detail;
It should bring types along. Which means:
- The function parameters are validated with typescript. The response updatedAlert has a defined type without the need of extra type annotations. All of this embeds editor completions, hints and even documentation on tooltips.
The funcion names are predictable and dictated by the API authors.

Making it happen

Since type information is static, it is quite hard to escape having a code generation step. Most of the drawbacks of integrating API's this way come from the need to use code generation.

A chosen code generation tool will populate a folder with generated code. That code is locked in place, static. If that code doesn't fit you, you will probably need to edit the template and/or the logic from the tool, or choose another tool;
The generated code style may vary wildly depending on the template authors' tastes;
A good code generator can make things a bit more flexible by providing extension points, either on the code generation process or on the generated code;

Now it doesn't seem that using OpenAPI generated code is a fairly common practice, as most code generators found on google are not really popular. Some alternatives I researched are:

OpenAPI client seems quite decent with good extensibility; Best impressions from the time I wrote this article.
OpenAPI generator is the oficial one with templates for multiple languages and setups; I'm personally not a fan since the templates are usually verbose non-extensible boilerplates;
sw2dts is focused on generating just the type definitions. Seems quite mature;

I'll be using my own-rolled swagger-ts-template for this sample, but you could try any other. This lib's code generator is invoked through a javascript API, here it is a sample.



// put this on your scripts folder
// invoke directly with node or add to package.json > scripts
const generator = require('@proerd/swagger-ts-template')
const fetch = require('node-fetch')

async function run() {
  const apiDef = await fetch('https://some.api/swagger.json').then(r => r.json())
  await generator.genPaths(apiDef, { output: "../src/common/api/swagger" })
  console.log('okay')
}
run()

It generates code on a defined folder, using the following structure: (you can also see a sample on the github repo)



|__ modules
| |__ TagOne.ts       -- API methods are split by tag
| |__ TagTwo.ts
|__ api-common.ts     -- runtime for processing and extending the calls
|__ api-types.ts      -- all types present in "declarations" key

Below an example of the generated code:



export type GET_contactdb_lists_list_id_recipients_Type = {
  list_id: number
  "on-behalf-of"?: string
  page?: number
  page_size?: number
}
export type GET_contactdb_lists_list_id_recipients_Response = {
  recipients?: Types.contactdb_recipient[]
}
/**
 * GET /contactdb/lists/{list_id}/recipients
 *
 * **This endpoint allows you to retrieve all recipients on the list with the given ID.**
 *
 * The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
 **/
export const GET_contactdb_lists_list_id_recipients = ApiCommon.requestMaker<
  GET_contactdb_lists_list_id_recipients_Type,
  GET_contactdb_lists_list_id_recipients_Response
>({
  id: "GET_contactdb_lists_list_id_recipients",
  path: "/contactdb/lists/{list_id}/recipients",
  verb: "GET",
  parameters: [
    { name: "list_id", required: true, in: "query" },
    { name: "on-behalf-of", in: "header" },
    { name: "page", required: false, in: "query" },
    { name: "page_size", required: false, in: "query" }
  ]
})

Wiring up the request

The boilerplate tries to impose not much opinion on how you should perform the requests. You need to write the "protocol bridge" yourself.



  operation metadata
  request parameters     -->  Request Handler  -->  APIResponse
  extra custom parameters                           Custom added data

Here's a sample using fetch and assuming all requests work with JSON:



import { SwaggerRequester, IRequest, IOperation, settings } from "./swagger/api-common";
import { authToken_Response } from "./swagger/modules/Auth";

const BACKEND_URL = process.env.BACKEND_URL!;

class RestRequester extends SwaggerRequester {
  getCurrentToken(): authToken_Response {
    const stored = localStorage.get("auth_info") || "{}";
    return JSON.parse(stored);
  }

  async handler(
    request: IRequest & GApiCommon.MergeToRequest,
    input: Record<string, any>,
    operation: IOperation
  ) {
    const url = new URL(BACKEND_URL);
    const params = request.query || {};
    Object.keys(params).forEach(key =>
      url.searchParams.append(key, params[key])
    );
    const token = this.getCurrentToken().access;
    const body = ["GET", "DELETE"].includes(request.verb!)
      ? undefined
      : JSON.stringify(request.body);
    const fetchResp = await fetch(url.toString(), {
      method: request.verb,
      body,
      headers: {
        "Content-Type": "application/json",
        Authorization: token ? `Bearer ${token}` : (undefined as any)
      }
    });
    if (fetchResp.status === 204) return {};
    return fetchResp.json();
  }
}

const requester = new RestRequester()
settings.getRequester = () => requester

Goodies

Function names are indexed by operationId. Typing the operationId in the editor kicks in the auto-import completion.

Input parameters are autocompleted and type-checked;

The response type is type-checked

Customizing request and response input

This boilerplate includes global empty interfaces MergeToRequest and MergeToResponse which can be extended through typescript's interface augmenting in order to provide a bit of extra flexibility for edge cases or custom handling.



declare global {
  namespace GApiCommon {
    interface MergeToRequest {
      _allowCache?: boolean
      _forceBody?: Record<string, any>
    }

    interface MergeToResponse {
      timeToFetch: number
    }
  }
}

MergeToRequest is merged into every request arguments type;
MergeToResponse is merged into every response type.

Customizing the code generation

The code generation step has a couple of options which may be useful to provide a bit more flexibility on the usage of the template. You usually won't need to tweak tweak here. Special mention to mapOperation, which may be used to tweak the swagger.json input for things like changing the operationIds.



type genPathsOpts = {

  output: string

  moduleStyle: "commonjs" | "esm"

  failOnMissingOperationId?: boolean

  typesOpts?: genTypesOpts

  mapOperation?: (operation: Operation) => Operation

  templateString?: string

  prettierOpts?: prettier.Options

}

export interface genTypesOpts {

  external?: any

  hideComments?: boolean

  mapVariableName?: (s: string) => string

  prettierOpts?: prettier.Options

}

Pros and cons

Pros

Call API's in a type-safe way, like if they were a part of the current codebase;
Integrate with code completion, auto imports and tooltip docs;
Reuse already existing data types from the back-end;
Propagate API changes to the front-end codebase, possibly catching errors just by updating the response types;

Cons

Must use a code generation step;
Your backend's swagger generation may be not very accurate sometimes, which would require some any casts or fallback to more manual methods;
Some VERY creative API designs may not integrate well.

Conclusion

This was a quick sample on how to get better integration between an API and the web frontend. It has been serving me great for some years now. I hope you did enjoy!