DEV Community: Gustavo Santos

Refactoring React: Manage page paths through path functions

Gustavo Santos — Wed, 04 May 2022 01:29:30 +0000

In a React web application, it is common to have redirections between pages. And it is common to have React Components that build the URL path pointing to some other page, outside its context. Such as the following example:

// a component used across the app

import { settingsRoute } from 'app/routes'

export cons OrderDescription = () => {
  const order = useOrder()

  return (
    <ul>
      {order.products.map(product => (
        <li key={product.sku}>
          <Link href={`/collections/${product.collectionId}/products/${product.id}`}>
            {product.name}
          </Link>
        </li>
      )}
    </ul>
  )
}

In this case, the OrderDescription component is building the path to the product page and passing as value to Link's
href property.

On the other hand, the product page received both the collection identifier and product identifier from the path.

// /pages/product.js

export const ProductPage = () => {
  const { collectionId, productId } = useParams()
  const product = useProduct(collectionId, productId)

  return (
    <div />
  )
}

The problem here is that OrderDescription needs to know how to build the URL path to the ProductPage component. In fact, any page that create a redirection link to the product page will need to know how to build the path to this page.

This kind of smell is called Shotgun Surgery. It happens when the same knowledge is placed between different locations through the application, where each update requires changing the knowledge spread across the source code.

With this example, if the parameters of a Product Page need to change, every place that creates a link to a product page will have to change.

One way of dealing with this smell is by creating a class or a function that encapsulates this knowledge of building links for products.

The first step is to choose the abstraction. In this post, I'll be using a function to build the page path.

// /pages/product.js

export const productPath = product =>
`/collections/${product.collectionId}/products/${product.id}`

export const ProductPage = () => {
  const { collectionId, productId } = useParams()
  const product = useProduct(collectionId, productId)

  return (
    <div />
  )
}

Now we can update every place that builds the product page path and replace them by calling the function productPath passing the product as argument.

export cons OrderDescription = () => {
  const order = useOrder()

  return (
    <ul>
      {order.products.map(product => (
        <li key={product.sku}>
          <Link href={productPath(product)}>
            {product.name}
          </Link>
        </li>
      )}
    </ul>
  )
}

Remember to be careful and keep the tests running while making the refactoring. It's important to not make behavior changes during a refactoring. If everything is green, commit the code.

Conclusion

By using path functions, we can encapsulate the behavior of creating path links based on external parameters. We leverage on the consumer of those path parameters to describe how to build the path to that page and by doing this, we avoid knowledge leaking across the application.

Even if there is only one place that builds a reference to a page through a URL path, I'd suggest doing this refactoring because reading the function call is way easier for the reader to understand what is going on than building and interpolating strings mentally.

How to do Ping-Pong pair programming in a remote environment

Gustavo Santos — Thu, 28 Apr 2022 15:47:08 +0000

Ping-pong is a pair programming technique where two programmers work together to solve a problem. It could be implementing a new feature, fixing a bug, etc.

The difference from this technique to other common techniques like the driver/navigator through Google Meet is that, in the Ping-Pong pair programming session, a programmer start writing a test. With the test failing, the other programmer write code to pass the test. After getting green, the second programmer write a new failing test that the first programmer need to implement the code to make that test pass.

The cycle then repeat until both programmers achieve the initial goal.

Why ping-pong pair programming is a thing in remote environment?

Personally, I feel more connected with my working partner when working in this way. We can debate about how to implement the code, about how the code will communicate with the system and how well tested the new feature/bug fix is.

Also, writing test first gives you more guides about what you need to do and set clear expectations about the code.

To do that, we need some tools. I think that the most used today is VSCode Live Share, where we can share a coding session that include server tunneling and access to the host terminal. It is very useful to put the tests running in the terminal and just write code together.

JetBrains had a tool integrated to its IDEs called Code with Me. I never used, but it looks spectacular by the outside view.

Alongside those tools, we have a bunch of other shared programming environments like Codesandbox.

Either way, working together with some other person in a remote environment is great! Thoughtbox had an excellent video teaching the hows with a live example.

Also, Tuple guys published a blog post about antipatterns that should be avoided when pairing.

Refactoring React: Applying Tell Don't Ask

Gustavo Santos — Thu, 28 Apr 2022 01:42:39 +0000

Often times we need to conditionally do something. In React land, it is mostly related to rendering stuff. Like conditionally render a component based on some state or prop.

When faced with those kinds of problems, we can use Tell Don't Ask to improve the code readability.

What is "Tell Don't Ask"?

Related with Law of Demeter (but not the same thing), Tell Don't Ask is an object-oriented programming technique (or design principle) where we avoid asking the object about its internal state to tell that object to do something. Instead, we just tell the object and let it rely on its internal state to decide what to do.

Applying Tell Don't Ask, we avoid querying and depending on the internal state of a collaborator object. Instead, the owner of that state -- or behavior, should decide what to do.

Working example

We have a settings page, represented by the SettingsPage component. This page uses many components, need to deal with state revalidation, form submissions and other things related with the settings page of the application.

This is the code (cropped, and many things omitted) of SettingsPage component:

const SettingsPage = () => {
  const settings = useSettings();

  return (
    <article>
      {!settings.isEmailConfirmed && (
        <Banner settings={settings} />
      )}
    </article>
  );
};

The Banner component should display a meaningful message based on the current settings state, alerting the user that it needs to confirm the email.

The Tell Don't Ask violation here is that SettingsPage is conditionally rendering the Banner component. But why this is a problem?

To be clear, in this toy example it is easy to spot what is happening, but rendering or not is a business rule own by the warning banner, not by the settings page.

The role that settings page here is to bring all of its parts together. Each part should have its own role and work together with other components mounted in the same context.

But imagine in a larger application with lots and lots of pages, where each page need to mount components and deal with the communication between them. Quickly become a mess where no one wants to maintain.

Applying the refactoring

The first step is to incorporate the business rule into the banner component, like so:

const Banner = ({ settings }) => {
  if (!settings.isEmailConfirmed)
    return null;

  return (
    <section>
      <p>Bla bla bla</p>
    </section>
  );
};

Now we can run our tests, if we are green, we can proceed and then remove the conditional rendering at the parent component -- the settings page.

const SettingsPage = () => {
  const settings = useSettings();

  return (
    <article>
      <Banner settings={settings} />
    </article>
  );
};

Now, the SettingsPage component doesn't know how the banner will deal with the settings. If the banner needed to show a different message based on a different settings property, it can do that without the settings page asking something.

We can proceed and remove the useSettings call and incorporate it to the Banner component, but personally see this movement as adding too much complexity into the banner component.

I'm using a shared component! I cannot apply this rule

Yes, you are right. You cannot.

But you can create an abstraction layer bounded into your context. If Banner component is using a shared banner element, maybe from an external library. Either way, it's from Banner component business to decide what to use to complete its work.

If our application already had a Banner component that is shared and agnostic by context, we can create an SettingsBanner component.

Better than that, we can talk to our users and ask them about that banner. How do they talk about this banner? Which words they use? Maybe they call by "confirmation email warning". If so, we can create a component bounded inside the settings context called ConfirmationEmailWarning and then implement the business rules owned by this component.

const ConfirmationEmailWarning = ({ settings }) => {
  if (!settings.isEmailConfirmed) return null;

  return (
    <Banner>
      Bla bla bla
    </Banner>
  );
};

Conclusion

By encapsulating business rules inside components and hooks, we can compose them based on contexts. A little coupling behind a domain context is not a big deal, coupling between domains is a problem.

Tell Don't Ask help us to keep the logic behind a door. We should not ask whether we can do or not do something, we just try to do that. In React land, it applies to rendering components, using React hooks and so on.

Learn more

Updates

2022, April 28 - Added more sources and correct typos.

What is your programming font?

Gustavo Santos — Tue, 08 Dec 2020 20:13:06 +0000

Do you believe that a good monospaced font can make you more productive? Maybe more happy while coding?

My favourite font is by far Iosevka variant SS07

What font you use in your editor?

Elixir: use, import ou require, qual a diferença?

Gustavo Santos — Mon, 05 Oct 2020 03:36:42 +0000

Não sei você, mas quando comecei a ir a fundo em Elixir, acabei descobrindo que não entendia corretamente o que algumas palavras-chave faziam.

Essas dúvidas apareceram principalmente após eu começar a estudar e usar o framework Phoenix em projetos pessoais -- todos projetos do tipo throw away. Mesmo assim, me incomodava o fato de não entender o que o framework estava tentando me dizer, parecia que existia algum tipo de mágica desnecessária lá. E eu não gosto de mágica dentro do código.

Se você está passando pelo mesmo caso, talvez esse texto te ajude. Se você está apenas de curioso lendo, que massa! Espero que você aprenda pelo menos alguma coisa nesse texto.

Diretiva `import`

Tudo começa com a definição do schema de algum dado no banco de dados usando o Ecto. Se você por acaso não sabe, o Phoenix usa, por padrão, o Ecto como biblioteca para trabalhar com a persistência de dados. Quando escrevemos (ou geramos) o esquema de alguma tabela, o arquivo geralmente tem essa cara:

defmodule Project.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset # << O que essa linha faz?

  schema "users" do
    field :email, :string
    field :name, :string
    field :password, :string

    timestamps()
  end

  def changeset(user, attrs) do
    user
    |> cast(attrs, [:name, :email, :password])
    |> validate_required([:name, :email, :password])
  end
end

No exemplo acima, a macro schema define os campos de um determinado dado que deverá ser persistido na tabela users. Não quero entrar em detalhes sobre o Ecto nesse artigo, então caso você não entenda o que o código acima faz, imagine que o trecho abaixo define as colunas e os tipos dos dados armazenados em cada coluna da tabela users:

  schema "users" do
    field :email, :string
    field :name, :string
    field :password, :string

    timestamps()
  end

Entretanto, sobre a perspectiva da diretiva import, esse trecho é irrelevante. Concentre-se em:

  def changeset(user, attrs) do
    user
    |> cast(attrs, [:name, :email, :password])
    |> validate_required([:name, :email, :password])
  end

O módulo Project.Accounts.User define uma função chamada changeset que usa outras duas funções que não estão definidas neste módulo: cast e validate_required. De onde essas funções vêm?

A palavra-chave import funciona como um indicativo ao compilador: ei, quando você compilar o módulo *Project.Accounts.User, inclua todas as funções e macros definidas no módulo **Ecto.Changeset, assim o código do módulo User vai poder usar essas funções/macros*. É devido a esse comportamento que conseguimos usar as funções cast e validate_required dentro da função changeset.

Se você quiser um exemplo melhor, veja o seguinte arquivo que define dois módulos:

defmodule Module1 do
  def func do
    IO.puts "rodando Module1.func"
  end

  defmacro meu_unless(clause, do: expression) do
    # fonte: https://elixir-lang.org/getting-started/meta/macros.html
    quote do
      if(!unquote(clause), do: unquote(expression))
    end
  end
end

defmodule Mods do
  import Module1

  def run do
    IO.puts("rodando!")
    func()
    meu_unless false, do: IO.puts "rodei"
  end
end

No módulo Mods foram importadas funções e macros de Module1 e ambos são usados na definição da função Mods.run/1. Ah, a diretiva também possui o mesmo comportamento quando usada dentro do corpo de uma função! Se a linha import Module1 for movida para dentro da definição de run, o código ainda vai funcionar. Por exemplo:

defmodule Mods do
  def run do
    import Module1
    IO.puts("rodando!")
    func()
    meu_unless false, do: IO.puts "rodei"
  end
end

Então, resumindo: a diretiva import importa todas as funções e macros de um **módulo* para o contexto onde a diretiva import está sendo usada*.

Diretiva `require`

Para a sua surpresa, a diretiva require faz o mesmo que a diretiva import, entretanto não importa funções! Se usarmos o mesmo exemplo anterior e trocarmos a palavra import por require, dessa forma:

defmodule Module1 do
  def func do
    IO.puts "rodando Module1.func"
  end

  defmacro meu_unless(clause, do: expression) do
    quote do
      if(!unquote(clause), do: unquote(expression))
    end
  end
end

defmodule Mods do
  require Module1 # <<

  def run do
    IO.puts("rodando!")
    func()
    meu_unless false, do: IO.puts "rodei"
  end
end

Você verá que o compilador do Elixir vai informar o seguinte erro:

== Compilation error in file lib/mods.ex ==
** (CompileError) lib/mods.ex:18: undefined function func/0
    (elixir 1.10.4) src/elixir_locals.erl:114: anonymous fn/3 in :elixir_locals.ensure_no_undefined_local/3    
    (stdlib 3.8) erl_eval.erl:680: :erl_eval.do_apply/6

Meio confuso né? Mas é basicamente o Elixir tentando nos dizer que a função func não está definida dentro do contexto onde é invocada.

Diretiva `use`

Voltando para o primeiro trecho de código que foi mostrado nesse artigo, o que a linha use Ecto.Schema faz? Imagine que o use consegue de alguma forma injetar um comportamento dentro do contexto.

O que é um comportamento? Como funciona essa "injeção"? Veja a definição do módulo Ecto.Schema em https://github.com/elixir-ecto/ecto/blob/master/lib/ecto/schema.ex. Pelo menos na branch master no momento que escrevo esse artigo (noite do dia 4/out/2020), na linha 450 começa a definição de uma macro chamada __using__. Por quê essa macro é importante?

A diretiva use injeta um comportamento no módulo/contexto onde é usada permitindo que o compilador do Elixir insira, edite ou remova código definido dentro do contexto corrente. Lembre-se que trabalhar com macros é como trabalhar com o compilador. Você não está escrevendo código para ser executado em tempo de execução (como todo código que você provavelmente escreve hoje), mas sim, escreve código para ser "executado" durante a compilação.

Segundo a documentação no site oficial do Elixir, o módulo Example que usa um módulo Feature, permite que Feature opere sobre o contexto de Example:

defmodule Feature do
  defmacro __using__(_) do
    quote do
      IO.puts "Feature.__using__/1"

      def some_func do
        IO.puts "oops"
      end
    end
  end
end

defmodule Example do
  use Feature
end

Quando compilado, o módulo Example terá a seguinte cara:

defmodule Example do
  require Feature
  Feature.__using__()
end

O que ganhamos com isso? A função __using__ define uma nova função some_func. Essa função será injetada dentro do contexto onde o use está sendo usado. Por exemplo:

defmodule Example do
  use Feature

  def run do
    some_func()
  end
end

Quando executada a função Example.run/1, o seguinte resultado será mostrado no terminal:

Feature.__using__/1
oops

Conclusão

Propositalmente escolhi não entrar muito em detalhes nesse texto justamente porque o objetivo era entender a diferença entre use, import e require já que essas três palavras aparecem várias vezes em códigos Elixir, principalmente se você estiver usando Phoenix e Ecto.

Existe um mundo a parte só envolvendo o sistema de macros de Elixir, conseguimos desde injetar métodos em contextos como também estender a linguagem como bem entendermos.

O Ecto é uma prova viva. A biblioteca implementa praticamente uma linguagem dentro de Elixir para conseguir lidar de forma eficiente com queries no banco de dados.

Para saber mais

Algumas fontes que eu usei para responder a questão que envolveu a escrita desse texto, talvez seja interessante a leitura:

Testando componentes React

Gustavo Santos — Mon, 10 Aug 2020 01:40:54 +0000

Disclaimer

Cover photo by Ben White on Unsplash

Nesse artigo vamos desenvolver um sistema de login (somente o front-end) com suporte a multi idiomas e testar esse sistema de login usando Jest e Testing Library. Porém esse artigo vai além do básico de testes de componentes, vamos aprender a usar tabelas de dados de testes, vamos fazer mocks do backend usando o Mock Service Worker e iremos usar um pouquinho de testes de propriedade.

Espero que esse artigo seja útil para você. Tentei condensar as principais ferramentas e técnicas que uso no dia a dia para garantir interfaces estáveis e prontas para serem refatoradas a qualquer momento.

O projeto

Não vamos criar um projeto do zero, existem vários artigos por aí que fazem muito bem esse trabalho. Porém vamos começar de um projeto base que deixei preparado nesse repositório. Então faça o clone e instale as dependências.

Você deve ter notado que existe um arquivo pnpm-lock.yaml no repositório. No projeto base eu usei o PNPM, que aconselho que pelo menos você dê uma olhada no projeto. Não vou gastar palavras explicando o PNPM nesse artigo porque a ferramenta merece um artigo próprio. Mas fique livre para deletar o arquivo e instalar as dependências usando NPM ou Yarn.

O projeto base contém 3 arquivos principais, o Login.jsx, seu respectivo arquivo de testes Login.spec.js e um arquivo App.jsx que ainda não é usado.

Adicionando o formulário de login

Formulários são coisas bem complicadas de gerenciar, para evitar complexidade desnecessária, vamos usar a biblioteca React Hook Form para nos ajudar com os formulários.

Vamos instalar o React Hook Form:

$ pnpm install react-hook-form

Para evitar de acoplar o formulário de login na página de login, vamos criar um diretório src/components/forms que vai agrupar todos os formulários da aplicação. Vamos então criar um componente chamado LoginForm dentro do diretório recém criado e implementar um formulário de login simples:

// src/components/forms/LoginForm.jsx

import React from 'react'
import { useTranslation } from 'react-i18next'
import { useForm } from 'react-hook-form'

export default function LoginForm ({ onSubmit }) {
  const { t } = useTranslation()
  const { register, handleSubmit } = useForm()

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label htmlFor="email">{t('email')}</label>
      <input name="email" type="email" ref={register} />

      <label htmlFor="password">{t('password')}</label>
      <input name="password" type="password" ref={register} />

      <button type="submit">{t('login_action')}</button>
    </form>
  )
}

Legal, mas agora precisamos adicionar os testes para esse formulário. Vamos criar um arquivo LoginForm.spec.jsx logo ao lado do arquivo com o código fonte do formulário de login com um teste simples para garantir que o nosso componente está renderizando normalmente.

// src/components/forms/LoginForm.spec.jsx

import React from 'react'
import { render, screen, waitFor } from '@testing-library/react'
import LoginForm from './LoginForm'
import i18n from '../../config/i18n'

describe('LoginForm', () => {
  let t

  beforeAll(async () => {
    t = await i18n
  })

  test('Should render the component', async () => {
    const handleSubmit = jest.fn()
    render(<LoginForm onSubmit={handleSubmit} />)
    await waitFor(() =>
      expect(screen.getByText(t('login_action'))).toBeInTheDocument()
    )
  })
})

Agora no terminal, vamos executar o Jest:

$ pnpm run test

> jest --no-cache

 PASS  src/components/Login.spec.jsx
 PASS  src/components/forms/LoginForm.spec.jsx

Test Suites: 2 passed, 2 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        3.501 s
Ran all test suites.

So far, so good. Mas o nosso formulário de login de fato funciona? Testar se um componente renderiza pode ser útil quando o componente deve ser montado de acordo com algumas condições via props. Porém o nosso caso não é esse. O formulário de login deve ser montado sempre, portanto não faz sentido testar se o componente montou. Mas vamos manter esse teste para fins didáticos.

Antes de escrever qualquer teste um pouco mais avançado, vamos primeiro instalar mais uma dependência para facilitar a nossa vida:

$ pnpm install --save-dev @testing-library/user-event

O @testing-library/user-event contém uma série de utilitários muito úteis! Vale a pena checar o repositório depois de terminar de ler esse artigo: https://github.com/testing-library/user-event.

Pronto, vamos adicionar um novo teste para garantir que, preenchendo os dados do formulário e clicando no botão de login, o callback onSubmit deve ser chamado com os dados corretos.

// src/components/forms/LoginForm.spec.jsx

import React from 'react'
import { render, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import LoginForm from './LoginForm'
import i18n from '../../config/i18n'

describe('LoginForm', () => {
  // ...

  test('Should call the onSubmit callback when confirm', async () => {
    const handleSubmit = jest.fn()
    render(<LoginForm onSubmit={handleSubmit} />)

    userEvent.type(screen.getByLabelText(t('email')), 'user@email.com')
    userEvent.type(screen.getByLabelText(t('password')), '1234567')

    userEvent.click(screen.getByText(t('login_action')))

    await waitFor(() => expect(handleSubmit).toBeCalledTimes(1))
    expect(handleSubmit).toBeCalledWith({
      email: 'user@email.com',
      password: '1234567'
    })
  })
})

Importante: note no código acima que eu omiti parte do código que já existia no arquivo LoginForm.spec.jsx. Isso será feito ao longo do texto para evitar de causar ruído desnecessário no texto.

Se você rodar pnpm run test novamente no terminal, virá que temos 3 testes passando:

$ pnpm run test

> jest --no-cache

 PASS  src/components/Login.spec.jsx
 PASS  src/components/forms/LoginForm.spec.jsx

Test Suites: 2 passed, 2 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        3.751 s
Ran all test suites.

Talvez você esteja se perguntando: o que deve acontecer quando a pessoa clicar no botão de Login sem ter preenchido o E-mail ou a senha? Realmente, há um problema de usabilidade no componente de login. O botão de login só deve disparar o callback onSubmit se o usuário preencher o E-mail e a senha.

Vamos primeiro criar um teste para este comportamento:

// src/components/forms/LoginForm.spec.jsx

import React from 'react'
import { render, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import LoginForm from './LoginForm'
import i18n from '../../config/i18n'

describe('LoginForm', () => {
  // ...

  test('Should call the onSubmit callback only when the email and password is filled', async () => {
    const handleSubmit = jest.fn()
    render(<LoginForm onSubmit={handleSubmit} />)

    userEvent.click(screen.getByText(t('login_action')))
    await waitFor(() => expect(handleSubmit).not.toBeCalled())

    userEvent.type(screen.getByLabelText(t('email')), 'abc@email.com')
    userEvent.click(screen.getByText(t('login_action')))
    await waitFor(() =>
      expect(screen.getByText(t('password_required'))).toBeInTheDocument()
    )
    expect(handleSubmit).not.toBeCalled()

    // clean up
    userEvent.clear(screen.getByLabelText(t('email')))

    userEvent.type(screen.getByLabelText(t('email')), 'abc@email.com')
    userEvent.type(screen.getByLabelText(t('password')), 'some_password')
    userEvent.click(screen.getByText(t('login_action')))

    await waitFor(() => expect(screen.queryAllByRole('alert')).toHaveLength(0))

    expect(handleSubmit).toBeCalledTimes(1)
    expect(handleSubmit).toBeCalledWith({
      email: 'abc@email.com',
      password: 'some_password'
    })
  })
})

Aqui vemos que os testes falham:

    expect(jest.fn()).not.toBeCalled()

    Expected number of calls: 0
    Received number of calls: 1

    1: {"email": "", "password": ""}

      52 |     await userEvent.click(screen.getByText(t('login_action')))
      53 | 
    > 54 |     expect(handleSubmit).not.toBeCalled()
         |                              ^
      55 | 
      56 |     await userEvent.type(screen.getByLabelText(t('email')), 'abc')
      57 |     await userEvent.type(screen.getByLabelText(t('password')), '1234567')

Vamos ajustar nosso formulário para evitar que o callback onSubmit seja chamado caso o usuário não tenha preenchido E-mail ou senha. Em outras palavras, vamos marcar que tanto E-mail quanto a senha são campos obrigatórios.

Felizmente escolhemos usar o React Hook Form como dependência para nos ajudar com formulários. A função register aceita, dentre outras coisas, um parâmetro que indica que o campo é obrigatório. Vamos alterar o formulário de login:

// src/components/forms/LoginForm.jsx

export default function LoginForm({ onSubmit }) {
  const { t } = useTranslation()
  const { register, handleSubmit, errors } = useForm()

  const submit = ({ email, password }) => onSubmit({ email, password })

  return (
    <form onSubmit={handleSubmit(submit)}>
      <label htmlFor="login_email">{t('email')}</label>
      <input
        id="login_email"
        name="email"
        type="email"
        ref={register({ required: true })}
      />
      {errors.email && (
        <span className="form-error" role="alert">
          {t('email_required')}
        </span>
      )}

      <label htmlFor="login_password">{t('password')}</label>
      <input
        id="login_password"
        name="password"
        type="password"
        ref={register({
          required: true
        })}
      />
      {errors.password && (
        <span className="form-error" role="alert">
          {t('password_required')}
        </span>
      )}

      <button type="submit" data-testid="login_submit">
        {t('login_action')}
      </button>
    </form>
  )
}

Agora todos os nossos testes passam.

Atenção! A função userEvent.type retorna uma Promise. Não espere pela Promise ser resolvida. Isso causa uma falha de sincronia com a biblioteca Testing Library.

Integrando com o backend

O funcionamento do formulário de login já está bem coberto por testes, porém nosso trabalho ainda não acabou. Precisamos integrar com uma API rest.

A responsabilidade de integrar com a API é do componente Login. Aqui fica claro o motivo de desacoplar o formulário de login do componente de login. Assim podemos compor ambos os componentes.

Sabemos que a API rest responde no endpoint /auth/login. Precisamos fazer um POST para este endpoint passando as credenciais do usuário no corpo da requisição. Vamos criar um serviço para lidar com essa questão.

Nosso serviço de autenticação vai usar o axios por baixo dos panos. Então vamos instalar o axios no nosso projeto:

$ pnpm install axios

Agora vamos criar o diretório src/services, que vai conter os serviços da aplicação. Dentro do diretório src/services vamos criar um arquivo chamado AuthService.js:

// src/services/AuthService.js

import axios from 'axios'

const AuthService = {
  routes: {
    login: '/auth/login'
  },

  login({ email, password }) {
    return axios.post(this.routes.login, { email, password })
  }
}

export default AuthService

O AuthService é um objeto que contém as rotas que o serviço de autenticação precisa, bem como os métodos que interagem com a API rest.

O método login recebe um objeto que contém email e password como propriedades, executa uma requisição POST no endpoint de login e retorna o resultado.

Agora vamos alterar o componente de login para usar o novo serviço de login:

// src/components/Login.jsx

import React, { useState } from 'react'
import { useTranslation } from 'react-i18next'
import LoginForm from './forms/LoginForm'
import AuthService from '../services/AuthService'

export default function Login() {
  const { t } = useTranslation()
  const [logged, setLogged] = useState(false)
  const [loginError, setLoginError] = useState(undefined)

  const handleSubmit = async ({ email, password }) => {
    try {
      await AuthService.login({ email, password })
      setLogged(true)
    } catch (e) {
      setLoginError(t('user_not_found'))
    }
  }

  return (
    <div>
      <h1>{t('login')}</h1>

      {!logged && <LoginForm onSubmit={handleSubmit} />}
      {logged && <div>{t('login_success')}</div>}
      {!!loginError && <span role="alert">{loginError}</span>}
    </div>
  )
}

Algumas coisas mudaram no componente Login. Primeiro, caso a autenticação do usuário perante o servidor ocorra com sucesso, o formulário de login será substituído por um texto de sucesso. Caso contrário, um aviso de erro de autenticação será mostrado.

Ok, e agora? Não temos uma API rest rodando (digamos que o time de backend ainda não terminou de implementar o endpoint de login). Para devidamente testar o login, vamos precisar fazer um mock do login. Mas antes de fazer qualquer tipo de mock usando jest.spyOn ou mockImplementation, vamos pensar se não há alguma forma um pouco mais esperta de resolver o problema.

Para garantir que estamos testando o comportamento dos componentes React, precisamos nos preocupar com o mínimo possível de características de implementação. Fazer um mock de uma função é como se fosse olhar com um óculos de raio-x para dentro do código do componente. É importante lembrar que o nosso componente deve ser tratado como uma caixa preta.

Um usuário não deve precisar saber o que uma função retorna, se essa função é assíncrona ou não, se é pura ou impura.

Felizmente existe uma ferramenta incrível chamada Mock Service Worker. O objetivo do MSW é iniciar um servidor simples que atua como uma API rest (ou GraphQL). Vamos adicionar o MSW no nosso projeto como uma dependência de desenvolvimento:

$ pnpm install --save-dev msw

Agora vamos criar o diretório src/mocks para escrever as definições desse servidor. Dentro do diretório src/mocks vamos definir os handlers e exemplos de respostas da API rest.

Os exemplos de respostas da API rest vou definir dentro do diretório chamado fixtures. Um exemplo pode deixar as coisas mais claras.

Vamos criar um arquivo que representa a resposta da API rest caso o login aconteça com sucesso:

// src/mocks/fixtures/login-success.json

{
  "token": "the token"
}

Ou seja, se o login ocorreu com sucesso, um token JWT será retornado no corpo da requisição.

Vamos criar também um arquivo que representa a resposta da API rest caso aconteça alguma falha na autenticação:

// src/mocks/fixtures/login-error.json

{
  "message": "User not found"
}

A API retorna uma mensagem avisando que o usuário não foi encontrado. A mensagem não é útil para nós, já que o sistema de login aceita multi idiomas. Por causa disso existem mensagens customizadas de falha de login nos arquivos de traduções (veja o diretório src/locales).

Agora vamos criar uma função que lida com o login. O formato dessa função é bem parecido com os handlers do express. No diretório src/mocks/handlers, crie um arquivo chamado login-handler.js com o seguinte conteúdo:

// src/mocks/handlers/login-handler.js

import { rest } from 'msw'
import AuthService from '../../services/AuthService'

import responseSuccess from '../fixtures/login-success.json'
import responseError from '../fixtures/login-error.json'
import user from '../fixtures/stored-user.json'

const createLoginHandler = () =>
  rest.post(AuthService.routes.login, (req, res, ctx) => {
    if (req.body.email === user.email && req.body.password === user.password) {
      return res(ctx.status(200), ctx.json(responseSuccess))
    } else {
      return res(ctx.status(403), ctx.json(responseError))
    }
  })

export default createLoginHandler

O login handler usa um arquivo que define um usuário para representar um usuário que existe no banco de dados. O conteúdo desse arquivo é:

// src/mocks/fixtures/stored-user.json

{
  "name": "Gustavo",
  "email": "gustavofsantos@outlook.com",
  "password": "123456"
}

A ideia do login handler é simples. Se as credenciais passadas no corpo da requisição POST forem as mesmas armazenadas no arquivo que define um usuário, então o login ocorre com sucesso. Caso contrário, um erro de acesso negado é retornado.

Agora vamos alterar um pouco o arquivo de testes do componente de login para lidar com o fluxo de autenticação:

// src/components/Login.spec.jsx

import React from 'react'
import { render, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import Login from './Login'
import i18n from '../config/i18n'
import user from '../mocks/fixtures/stored-user.json'

describe('Login', () => {
  let t

  beforeAll(async () => {
    t = await i18n
  })

  test('Should render the component', async () => {
    render(<Login />)
    await waitFor(() =>
      expect(screen.getByText(t('login'))).toBeInTheDocument()
    )
  })

  test('Should log in the user', async () => {
    render(<Login />)

    userEvent.type(screen.getByLabelText(t('email')), user.email)
    userEvent.type(screen.getByLabelText(t('password')), user.password)
    userEvent.click(screen.getByText(t('login_action')))

    await waitFor(() =>
      expect(screen.getByText(t('login_success'))).toBeInTheDocument()
    )
  })
})

E voilà, todos os testes passam:

$ pnpm run test

> jest --no-cache

 PASS  src/components/Login.spec.jsx
 PASS  src/components/forms/LoginForm.spec.jsx

Test Suites: 2 passed, 2 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        4.012 s
Ran all test suites.

Agora precisamos cobrir o caso onde o usuário não está cadastrado no banco de dados.

import React from 'react'
import { render, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import Login from './Login'
import i18n from '../config/i18n'
import user from '../mocks/fixtures/stored-user.json'

describe('Login', () => {
  // ...

  test('Should not log in the user that is not registered', async () => {
    render(<Login />)

    userEvent.type(screen.getByLabelText(t('email')), user.email)
    userEvent.type(screen.getByLabelText(t('password')), 'some other password')
    userEvent.click(screen.getByText(t('login_action')))

    await waitFor(() =>
      expect(screen.queryAllByText(t('user_not_found'))).toHaveLength(1)
    )
  })
})

E novamente, todos os nossos testes passam:

$ pnpm run test

> jest --no-cache

 PASS  src/components/forms/LoginForm.spec.jsx
 PASS  src/components/Login.spec.jsx

Test Suites: 2 passed, 2 total
Tests:       6 passed, 6 total
Snapshots:   0 total
Time:        4.155 s
Ran all test suites.

Não sei se você concorda comigo mas é um saco descrever todos os casos de teste. Além disso, quando humanos executam uma tarefa repetitiva muitas vezes, há grandes chances da pessoa cometer algum erro ou esquecer algum caso. Especialmente os casos de borda (edge cases).

Talvez um modelo mais eficiente de testes seja mais interessante.

Usando tabelas de teste

Vamos começar refatorando um pouco o nosso arquivo com os testes do formulário de login.

// src/components/forms/LoginForm.spec.jsx

import React from 'react'
import { render, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import LoginForm from './LoginForm'
import i18n from '../../config/i18n'

describe('LoginForm', () => {
  // ...

  test.each([
    ['a@b.c', '1234567', { email: 'a@b.c', password: '1234567' }],
    ['aaaaa@b.c', '', undefined]
  ])(
    'Should call the onSubmit callback only when the email and password are valid',
    async (email, password, expected) => {
      const handleSubmit = jest.fn()
      render(<LoginForm onSubmit={handleSubmit} />)

      userEvent.type(screen.getByLabelText(t('email')), email)
      userEvent.type(screen.getByLabelText(t('password')), password)
      userEvent.click(screen.getByText(t('login_action')))

      if (!!email && !!password) {
        await waitFor(() => expect(handleSubmit).toBeCalled())
        expect(handleSubmit).toBeCalledWith(expected)
      } else {
        await waitFor(() => expect(handleSubmit).not.toBeCalled())
      }
    }
  )
})

Foi adicionado um novo teste que usa uma tabela de testes. A função test.each aceita uma lista de listas de argumentos para a função que de fato executa os testes. Ou seja

test.each([
  [arg0, arg1, arg2, ...],
  [arg0, arg1, arg2, ...],
  [arg0, arg1, arg2, ...],
])('The test description with %s interpolation', (arg0, arg1, ...) => {
  // test body
})

Os parâmetros da tabela de testes serão mapeados diretamente na função que executa o teste. Além disso, é um padrão que, caso exista o caso de comparação, este caso será o último no array de argumentos.

Na verdade, com esse novo teste podemos deletar todos os testes que já havíamos escrito no arquivo LoginForm.spec.jsx. O arquivo com os testes do formulário de login terá a seguinte cara:

import React from 'react'
import { render, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import LoginForm from './LoginForm'
import i18n from '../../config/i18n'

describe('LoginForm', () => {
  let t

  beforeAll(async () => {
    t = await i18n
  })

  test.each([
    ['a@b.c', '1234567', { email: 'a@b.c', password: '1234567' }],
    ['aaaaa@b.c', '', undefined]
  ])(
    'Should call the onSubmit callback only when the email and password are valid',
    async (email, password, expected) => {
      const handleSubmit = jest.fn()
      render(<LoginForm onSubmit={handleSubmit} />)

      userEvent.type(screen.getByLabelText(t('email')), email)
      userEvent.type(screen.getByLabelText(t('password')), password)
      userEvent.click(screen.getByText(t('login_action')))

      if (!!email && !!password) {
        await waitFor(() => expect(handleSubmit).toBeCalled())
        expect(handleSubmit).toBeCalledWith(expected)
      } else {
        await waitFor(() => expect(handleSubmit).not.toBeCalled())
      }
    }
  )
})

Mais compacto, não acha? Será que podemos fazer melhor?

O modelo de login

Vamos começar criando um pequeno e simples modelo de login. O modelo deve implementar o funcionamento correto do login, porém da forma mais simples possível. O modelo de login não precisa ser performático, precisa implementar da forma correta o funcionamento do formulário de login.

Vamos começar implementando esse modelo no arquivo LoginFormModel.js:

// src/components/forms/LoginFormModel.js

const LoginFormModel = {
  login(email, password) {
    if (
      typeof email === 'string' &&
      email.length > 3 &&
      typeof password === 'string' &&
      password.length >= 6
    ) {
      return true
    }

    return false
  }
}

export default LoginFormModel

O modelo de formulário de login é simples. Se o email e senha cumprem com as regras de login -- email cujo tamanho é maior que 3 caracteres e senha maior que 6 caracteres; então o login é um sucesso e o modelo retorna true. Caso contrário o modelo retorna false. Note que não há problemas quanto a senhas com espaços. O sistema proposto aceita qualquer tipo de caracter como parte da senha.

Agora vamos adicionar mais uma dependência no nosso projeto:

$ pnpm install --save-dev fast-check

Agora vamos criar mais um teste no nosso arquivo de testes do formulário de login. O formato desse teste é um pouco diferente, mas garanto que logo logo tudo fará sentido:

// src/components/forms/LoginForm.spec.jsx

import React from 'react'
import { cleanup, render, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import * as fc from 'fast-check'
import LoginForm from './LoginForm'
import i18n from '../../config/i18n'
import LoginFormModel from './LoginFormModel'

describe('LoginForm', () => {
  // ...

  test(
    'Should call the onSubmit callback when email and password are valid',
    () =>
      fc.assert(
        fc
          .asyncProperty(
            fc.scheduler({ act }),
            fc.emailAddress(),
            fc.string(),
            async (s, email, password) => {
              const handleSubmit = jest.fn()
              const { getByLabelText, getByText } = render(
                <LoginForm onSubmit={handleSubmit} />
              )

              s.scheduleSequence([
                () => userEvent.type(getByLabelText(t('email')), email),
                () => userEvent.type(getByLabelText(t('password')), password),
                async () => userEvent.click(getByText(t('login_action')))
              ])

              await s.waitAll()

              if (LoginFormModel.login(email, password)) {
                expect(handleSubmit).toBeCalledWith({
                  email,
                  password
                })
              } else {
                expect(handleSubmit).not.toBeCalled()
              }
            }
          )
          .beforeEach(async () => {
            await cleanup()
          })
      ),
    15000
  )
})

Wow, muitas coisas acontecendo aqui. O pacote fast-check implementa várias primitivas para testes de propriedade. Não é o objetivo desse artigo ir a fundo em testes de propriedade. O universo de testes de propriedades é muito grande e merece um artigo a parte. Aqui vamos nos concentrar em um espectro bem reduzido de testes de propriedade que são testes contra um modelo.

O objetivo do teste é checar se um código, seja ele uma função, variável ou objeto contém todas as propriedades relacionadas a um determinado modelo. O exemplo mais simples é uma função de adição. A soma de dois números deve ser a mesma independente da ordem dos operandos. Essa é a propriedade associativa da adição.

A mesma ideia é empregada no código anterior, porém checamos se o componente LoginForm implementa as propriedades do modelo LoginFormModel. O modelo de formulário de login só tem uma "propriedade", que é o login. O login é verdadeiro caso email e senha estejam dentro das regras de login.

Note que foi preciso definir um timeout para o teste. Os testes gerados pelo fast-check causam um aumento considerável do tempo que um teste leva para ser executado. Como a asserção das propriedades do formulário de login é uma função assíncrona, caso o teste demore mais do que o timeout padrão do Jest a execução é interrompida. Evitamos esse tipo de comportamento aumentando o timeout.

Note também que a primeira propriedade mapeada no teste é um agendador. O fast-check irá agendar as ações sobre o formulário de login automaticamente para nós, porém precisamos definir a sequência de ações, isso é feito no trecho abaixo:

s.scheduleSequence([
  () => userEvent.type(getByLabelText(t('email')), email),
  () => userEvent.type(getByLabelText(t('password')), password),
  async () => userEvent.click(getByText(t('login_action')))
])

Outro modo de entender o funcionamento do agendador é encarar como o momento da atuação. O fast-check vai agendar e executar uma sequência de atuações assíncronas, cada atuação (função assíncrona) será executada após a anterior terminar. Esse comportamento vai garantir a ordem das chamadas e vai evitar vazamentos de memória.

Voltando ao comportamento do modelo de formulário de login, se o método login retorna verdadeiro, o callback onSubmit deve ser chamado. Caso contrário, o callback não deve ser chamado. Essa é a propriedade do formulário de login.

Vamos rodar nossos testes, crentes de que o nosso componente já está muito bem testado:

$ pnpm run test

  ● LoginForm › Should call the onSubmit callback when email and password are valid

    Property failed after 1 tests
    { seed: -1640604784, path: "0:0:0:0:0:0:0:0:0:1:0:0", endOnFailure: true }
    Counterexample: [schedulerFor()`
    -> [task${1}] sequence resolved
    -> [task${2}] sequence resolved
    -> [task${3}] sequence resolved`,"a@a.ap"," "]
    Shrunk 11 time(s)
    Got error: Error: expect(jest.fn()).not.toBeCalled()

Oops, parece que houve um erro. O fast-check consegue gerar inúmeras combinações de E-mail e senhas. Porém após a primeira combinação, foi encontrada uma combinação de E-mail e senha onde o nosso componente viola o modelo de login -- o contra exemplo onde o E-mail é "a@a.ap" e a senha " ". Isso indica que o nosso formulário de login precisa implementar as validações do modelo.

No código fonte do formulário, vamos aumentar os requisitos dos inputs de E-mail e senha:

// src/components/forms/LoginForm.jsx

export default function LoginForm({ onSubmit }) {
  const { t } = useTranslation()
  const { register, handleSubmit, errors } = useForm()

  const submit = ({ email, password }) => onSubmit({ email, password })

  return (
    <form onSubmit={handleSubmit(submit)}>
      <label htmlFor="login_email">{t('email')}</label>
      <input
        id="login_email"
        name="email"
        type="email"
        ref={register({
          required: true,
          validate: (value) => value.length > 3
        })}
      />
      {errors.email && (
        <span className="form-error" role="alert">
          {t('email_required')}
        </span>
      )}

      <label htmlFor="login_password">{t('password')}</label>
      <input
        id="login_password"
        name="password"
        type="password"
        ref={register({
          required: true,
          validate: (value) => value.length >= 6
        })}
      />
      {errors.password && (
        <span className="form-error" role="alert">
          {t('password_required')}
        </span>
      )}

      <button type="submit" data-testid="login_submit">
        {t('login_action')}
      </button>
    </form>
  )
}

Adicionamos as validações de tamanho de E-mail e senha no formulário de login. Vejamos se os nossos testes voltaram a passar:

$ pnpm run test

> jest --no-cache

 PASS  src/components/Login.spec.jsx
 PASS  src/components/forms/LoginForm.spec.jsx (7.733 s)

Test Suites: 2 passed, 2 total
Tests:       6 passed, 6 total
Snapshots:   0 total
Time:        9.024 s
Ran all test suites.

Considerações finais

Espero ter te ajudado com dicas sobre testes de componentes React. De fato nenhum assunto aqui foi levado a fundo, cada um dos tipos de testes apresentados nesse texto merecem um artigo inteiro dedicado.

Você pode checar o código fonte nesse repositório no GitHub. Ficou com alguma dúvida ou gostaria de contribuir com mais casos de testes? Sinta-se a vontade para mandar uma DM no Twitter ou abrir uma pull request no GitHub.

Ah, antes de terminar essa leitura, você chegou a notar que nenhuma vez checamos a interface? Não usamos o navegador para testar nosso código. Esse repositório nem tem um servidor de desenvolvimento, muito menos um bundler configurado. Talvez seja legal pensar se realmente precisamos sair do editor para testar se o código que estamos escrevendo está funcionando.

FAQ

Porquê esse projeto não foi criado com Create React App? Infelizmente, até o momento onde esse artigo foi escrito o CRA não tinha suporte a abstrações mais modernas do Testing Library, como a função waitFor. Achei mais interessante configurar um projeto para evitar confusões.

Praticando magia azul com Promises e JavaScript

Gustavo Santos — Mon, 24 Feb 2020 13:57:57 +0000

Talvez em algum momento da sua vida, você possa ter se deparado com um problema onde é necessário fazer uma consulta via REST em algum endpoint, usar o resultado dessa requisição em caso de sucesso, e então fazer outra requisição REST em algum outro endpoint e então retornar algum resultado em caso de sucesso, ou talvez retornar um erro em caso de falha, ou disparar uma exceção, ou retornar false ou até retornar nada.

Eu sei, é bastante problemático lidar com operações assíncronas, eu preciso lidar com isso todos os dias. As vezes a gente faz um trabalho legal em gerenciar tudo, as vezes a gente faz um trabalho não tão bom e engloba todas as chamadas assíncronas dentro de um block try/catch e vida que segue. Porém, a bagunça fica grande muito rápido.

Nesse texto, que espero não ficar longo, vou tentar expor os meus dois centavos no assunto de gerência de operações assíncronas com JavaScript, seguindo a abordagem funcional/declarativa.

Promises

Promises são abstrações temporais. São mecanismos de gerência de informações que eventualmente irão existir. São uma caixa que pode, no futuro, conter algum valor.

A parte mais incrível de Promises é que você consegue compor esse tipo de informação através do método then. Por exemplo:

const result = Promise.resolve(1)
    .then(x => x + 1)
    .then(x => x * 3)
    .then(x => x ** 2);

result; // Promise { 36 }

E em qualquer momento durante a cadeia de chamadas ao método then, você pode declarar um callback a ser executado em caso de erro, registrando através do método catch:

const result = Promise.resolve(1)
    .then(x => x + 1)
    .then(x => x * 3)
    .then(x => { throw new Error() })
    .then(x => x ** 2)
    .catch(() => 'oops');

result; // Promise { "oops" }

Mas isso você provavelmente já sabia, então vamos direto ao assunto funcional.

A pureza das funções

Uma função pura é uma função que não extrapola o contexto da sua execução, ou seja, é uma função que para uma entrada do tipo A, uma saída do tipo B sempre existirá e não haverá qualquer tipo de interação com o contexto de fora da função.

Um exemplo de função que não é uma função pura:

const log = (what) => console.log('logging:', what);

O objeto console não faz parte da definição do ECMAScript, além disso, essa função interage com um contexto exterior à função log, escrevendo um texto na saída padrão. A saída padrão é um ambiente hostil, um ambiente que pode falhar, por esses motivos, a função log é uma ação de efeito colateral, onde o efeito colateral é a escrita de um texto no Console.

Ok, mas o que é uma função pura? Esse tópico merece um artigo próprio, mas uma função pura possui seu domínio e contra-domínio bem definidos. Uma função pura não extrapola seu escopo. Uma função pura possui uma saída para qualquer tipo de entrada. Um exemplo de função pura é a função add abaixo:

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

Uma função pura é determinística. Para quaisquer números x e y, existirá um número z que é a soma de x e y. Uma função pura possui tempo de execução constante e determinístico, o runtime sempre executará as mesmas instruções, o uso de memória sempre será o mesmo. Funções puras não acessam o console, não acessam o window, não acessam o espaço de nomes de um módulo. Para um dado valor de entrada, uma função pura sempre possuirá um valor de retorno determinístico.

Programação com efeitos

Efeitos são ações executadas dentro ou fora do contexto do programa que interagem com o sistema que executa o programa, ou seja, um efeito é qualquer tipo de operação de IO. Por exemplo, podemos criar uma ação de efeito colateral ao tentar ler um arquivo do nosso diretório atual no Node.js:

const fs = require('fs');

const readFile = (file) =>
    fs.readFileSync(file, { encoding: 'utf8' });

const file = readFile('.gitignore');
file; // "/node_modules/\n/dist/\n ..."

Se você executar este trecho de código em algum diretório que não contenha o arquivo “.gitignore”, o Node vai disparar uma exceção de arquivo não encontrado e, ao menos que você trate esta exceção, seu programa vai abortar a execução.

Além de acessar um arquivo no diretório atual, é também considerado um efeito colateral a ação de escrever algo na saída padrão, como no caso da função console.log. Qualquer ação que extrapole o contexto da execução de uma função, pode ser considerado um efeito colateral. Por exemplo, o acesso a variáveis globais, variáveis de ambientes, e assim por diante.

Levantamento

O conceito de levantamento significa que, a partir de um pedaço de informação em um determinado contexto, ao levantar esta informação a outro contexto, serão adicionadas funcionalidades do novo contexto ao contexto anterior. Por exemplo, podemos dizer que vamos levantar um valor ao contexto de array fazendo a seguinte operação:

const valor = 2;
const valorArr = [valor];

Consequentemente, adicionamos ao contexto do valor 2, informações do contexto de arrays. Agora podemos aplicar os métodos map, filter, reduce, sort e vários outros presentes no contexto de arrays:

const toArray = (value) => [value];

const value = 2;
const squareValue = toArray(value)
    .map((x) => x * x)

console.log(squareValue); // [4]

No contexto de Promises, podemos fazer o mesmo. A questão é que precisamos abrir nossa mente e pensar de forma a criar uma abstração temporal para um determinado valor.

Vamos definir a função pure, essa função recebe um valor e retorna uma abstração temporal a este valor. Em outras palavras, a função pure recebe um valor e retorna uma Promise que resolve para este valor:

const pure = (value) => Promise.resolve(value)

Agora conseguimos aplicar os métodos then, catch e finally em qualquer valor:

pure(2)
    .then(x => x * x)
    .then(x => x - 1)
    .then(console.log)

Em termos formais, a função pure tem a assinatura: pure :: a → f a, onde o tipo a é convertido em uma estrutura do tipo f a. No nosso caso neste texto, a função pure tem a assinatura pure :: any → Promise<any>. Assim, para qualquer valor, pure levanta este valor para um contexto de Promise.

Sob a ótica da abstração

Conceitos funcionais abstraem padrões que acontecem no código. Na natureza existem diversos padrões que, volta e meia nós, humanos, abraçamos estes padrões e criamos coisas parecidas, as vezes criamos coisas tão melhores que transcendemos os padrões da natureza.

Podemos pensar no contexto de braços. Braços aparecem na natureza em diversas formas e modelos, alguns são mais fortes e longos, outros são mais fracos e curtos. Alguns parecem com pernas, outros são de fato pernas, e até existem alguns que são usados para formar um sistema de voo.

Nós, homo sapiens, também fazemos braços, alguns são desajeitados e baratos, outros são grandes, fortes, precisos e caros. Mas no final das contas, são todos criações e abstrações para um conjunto de objetivos.

No código conseguimos criar abstrações também. Algumas abstrações são tão bem definidas que são conhecidos como design patterns, que são formas muito bem definidas de criar abstrações para resolver problemas.

Programas funcionais, ou, declarativos, também se apoiam sobre abstrações, alguns exemplos são os Functores, Aplicativos, Monadas e diversos outros. Mas no final das contas, são todos abstrações. Alguns são mais eficientes que outros em um determinado contexto. Se nós usarmos os padrões de Aplicativos em programas que são estruturados de forma a seguir diretrizes da Orientação a Objetos, o código simplesmente não vai encaixar bem.

Imagine o problema: é necessário fazer uma busca de usuário baseado em um identificador, em seguida, precisamos descobrir se este usuário é administrador. Existem duas funções, cada função é responsável de uma coisa. A função getUserById recebe um identificador e, em caso de sucesso, retorna uma Promise que resolve para um objeto contendo informações de um usuário, caso contrário retorna uma Promise que resolve para um erro.

A outra função, isUserAdmin, recebe um objeto que representa um usuário e baseado neste objeto, decide se o usuário é admin.

Podemos, então escrever um código parecido com isso:

async function run() {
    const userId = 2;
    const user = await getUserById(userId);

    if (user instanceof Error) {
        console.log(user.message);
        return;
    }

    const isAdmin = await isUserAdmin(user);
    if (isAdmin) {
        console.log('The user is admin!');
    }
}
run();

Ou podemos reescrever este mesmo código usando abstrações:

async function run() {
    const userId = 1;

    const isAdmin = await bind(
        () => pure(userId),
        getUserById,
        isUserAdmin,
    );

    if (isAdmin) {
        console.log('The user is admin!');
    }
}
run();

Levantando funções

Usando o conceito de levantamento, podemos extender para operações mais complexas. Você pode levantar qualquer coisa ao contexto de Promise. Por exemplo, você pode levantar uma função pura ao contexto de Promise e aplicar esta função em um ambiente impuro.

Por exemplo, imagine que você tem uma função que adiciona 1 a um determinado número, por exemplo:

    const plusOne = (n) => n + 1

Para qualquer número n, plusOne retorna este número mais um.

Agora imagine algum ambiente exótico onde você precisa aplicar esta função em um número futuro. Em algum momento do tempo, vai existir um número n e você precisa somar um a esse número assim que ele existir.

Podemos nos apoiar em conceitos funcionais e usar a função lift, que recebe uma função pura e uma função do tipo factory, que retorna uma Promise:

const plusOne = (n) => n + 1;

const getNumber = () =>
    Promise.resolve(Math.floor(Math.random() * 10))

async function run() {
    const result = await lift(plusOne, getNumber);
    console.log(result); // 1, 4, 9, 2, ...
}
run();

A função getNumber é impura. O retorno de getNumber é inconsistente, sua imagem não é mapeável a seu domínio, a imagem de getNumber muda a cada invocação, não é uma função consistente em resultado, tempo de execução e uso de memória. Porém a função plusOne é uma função pura. Funções puras e impuras não se relacionam, a menos que usemos abstrações para relacionar estas funções.

No código anterior, levantamos a função plusOne ao contexto impuro da função getNumber. Uma vez levantada uma função pura a um contexto impuro, o fluxo da computação jamais se tornará puro novamente. Não é possível extrair um valor de dentro do contexto de Promise em um contexto puro. Uma vez posto um valor dentro de uma Promise, é impossível remover o valor de dentro da Promise.

Conseguimos operar com valores de Promises dentro de um contexto assíncrono criado a partir do uso da palavra chave async. Quando criamos funções assíncronas, estamos fazendo um contrato com o runtime do JavaScript de que todas as operações que iremos executar serão impuras, passíveis de erros, não determinísticas. Por esse motivo, é considerado uma boa prática englobar qualquer chamada a uma função usando a palavra chave await em um bloco try/catch.

Controle declarativo

Controlar a execução assíncrona do JavaScript é um desafio a parte. Diariamente lidamos com fluxos de execução assíncronos no JavaScript de forma manual, é natural para qualquer pessoa que desenvolve programas lidar com fluxos assíncronos e funções impuras, pelo simples motivo que programas que não possuem efeitos colaterais, não são úteis.

Jamais conseguiríamos fazer um programa que calcula a soma de dois números se não aceitarmos valores do mundo externo, seja via argumentos da linha de comando ou inputs em alguma interface bonitinha. Também nunca poderíamos mostrar o resultado se não tivermos acesso a saída padrão ou a algum elemento no DOM.

Porém podemos nos apoiar em construções de controle declarativas para, no pior das hipóteses, simplificar a nossa base de código, construindo programas baseado em blocos de construção mais simples, combináveis, fáceis de testar e difíceis de conter erros.

Uma das coisas que mais me chamam a atenção em Haskell é a forma de, dependendo da abstração que usamos, a própria abstração lida com possível problemas que podem ocorrer em tempo de execução. O maquinário de Aplicativos, por exemplo, consegue lidar com a ausência de valores, com computações que podem falhar e diversos outros fatores de programação com efeitos colaterais.

O maquinário de Monadas é mais completo e complexo, lidando não só com problemas que Aplicativos lidam, como acessos a mundo externos, composição de mundos puros e impuros e outras combinações.

Baseado nisso imagine três funções: liftP2, flatMap, bind e exec. Cada uma dessas funções abstraem problemas de controle assíncrono de formas diferentes.

A função liftP2 levanta uma função pura a um contexto impuro e espera por outros dois efeitos colaterais serem resolvidos, então aplica essa função pura aos resultados destes efeitos colaterais e retorna uma Promise contendo o resultado, por exemplo:

const getUser = () => Promise.resolve({ name: 'User', role: 2 })
const getAdminRoles = () => Promise.resolve([1, 2, 3]);
const userHasReadRole = (user, roles) => roles.includes(user.role);

async function main() {
    const canRead = await liftP2(userHasReadRole, getUser, getAdminRoles);
    if (canRead) {
        console.log('user can read this')
        return
    }
    console.log('access deny')
}
main();

Já se você quer aplicar alguma função pura a uma Promise, você pode usar a função flatMap que resolve a Promise, aplica o valor resolvido da Promise na função pura e retorna uma Promise contendo o resultado final:

const getUser = () => Promise.resolve({ name: 'User', role: 2 })
const viewName = (user) => user.name;

async function main() {
    const name = await flatMap(getUser, viewName);
    console.log(name);
}
main();

A função bind recebe uma função factory que retorna uma Promise, e uma lista de funções assíncronas que serão aplicadas sequencialmente. Baseado em uma factory inicial, a função bind vai resolver a primeira Promise e aplicar o resultado na primeira função impura, então vai esperar esta função ser resolvida e o resultado será aplicado na segunda função impura e assim por diante.

const initial = Promise.resolve(1);
const doubleP = (x) => Promise.resolve(x * 2);
const tripleP = (x) => Promise.resolve(x * 3);
const stringifyP = (x) => Promise.resolve(String(x));

bind(initial, doubleP, tripleP, stringifyP);
// Promise { '6' }

Se em algum momento durante a execução alguma das funções impuras emitir uma exceção ou retornar um erro, o fluxo de execução será abortado e uma Promise que resolve para uma instância de erro será retornada. Caso o fluxo de ações chegue ao fim com sucesso, uma Promise que resolve para o retorno da última função impura será retornada.

Nem sempre precisamos construir um pipeline de funções dependentes umas das outras. Se você precisa executar uma sequência de ações, descartando qualquer resultado intermediário gerado, você pode compor a execução dessa forma:

const doSomethingAsync = () => ...
const doOtherThingAfterFirstAsync = () => ...

exec(doSomethingAsync, doOtherThingAfterFirstAsync)

A função exec vai executar as funções em ordem, descartando qualquer resultado intermediário. Em caso de qualquer erro, a execução é abortada e o resultado é resolvido para uma instância de erro.

Conclusões

Independente do seu background profissional, se você chegou até aqui significa que, além de força de vontade, você tem, no mínimo, muita curiosidade em como escrever programas de forma declarativa, mais fáceis de dar manutenção, mais fáceis de entender, mais fáceis de testar e menos suscetíveis a problemas.

Além dessa leitura, eu recomendo outros blogs e livros sobre programação funcional:

Miran Lipovača - Learn You a Haskell for Great Good (http://learnyouahaskell.com/)
Eric Elliot - Blog (https://medium.com/@_ericelliott)

Tsoid

Todas as funções de gerência de operações assíncronas que eu mostrei nesse artigo estão definidas no pacote Tsoid disponível no NPM. O pacote Tsoid define funções transientes, ou seja, estas funções oferecem uma interface imutável ao mesmo tempo que usam construções mutáveis internamente.

O conceito de funções transientes é explorado por outras linguagens, principalmente por Clojure. Funções de auxílio de controle como sequence, bind, map, filter, reduce, flatMap, lift e várias outras estão definidas e disponíveis para o uso. Nenhuma função de controle do pacote Tsoid emite exceções, este padrão segue a minha opinião de não trabalhar com exceções. Portanto, todas funções de controle retornam uma Promise que resolve para o resultado da operação ou para uma instância de erro.

Além da Tsoid, existem outras bibliotecas que auxiliam o programador JavaScript a escrever códigos declarativos, dentre elas eu gosto de destacar:

Um devaneio sobre Classes, Objetos, Funções e organização em JavaScript

Gustavo Santos — Sun, 09 Feb 2020 16:16:37 +0000

Considere os dois trechos de código abaixo:

// trecho 1
const user = new User('Gustavo', 25);
user.name();

// trecho 2
const user = new User('Gustavo', 25);
name(user);

Qual versão você prefere?

Atenção: Este artigo contém, na sua grande maioria, as minhas opiniões pessoais sobre estilos de desenvolvimento de programas de forma sustentável.

Classes em JavaScript

JavaScript não possui suporte a classes. Ok, existe a palavra chave class adicionada no ES2015, que serve justamente para definir classes. Caso você seja novo no mundo JavaScript, esse exemplo pode ser esclarecedor:

class User {
    constructor(name, age) {
        this.name = name;
        this.age = age;
    }
}

let user = new User('Gustavo', 25);
console.log(user.name); // Gustavo

No trecho acima, é criada uma classe chamada User com um método construtor que recebe dois parâmetros, o primeiro será atribuído a name e o segundo, a age. Em seguida é criado uma instância da classe User e o atributo público name é impresso no console.

Porém, é neste momento que começam os problemas. Toda e qualquer classe em JavaScript possuirá todos os atributos e métodos públicos, violando os conceitos de encapsulamento.

E se quisermos que o atributo age seja privado? Ou seja, que este atributo seja acessível somente dentro da classe User. Talvez algo do tipo:

class User {
    let __age;
    constructor(name, age) {
        this.name = name;
        age = age;
    }
}

Infelizmente essa sintaxe não é válida. Porém no ES2019 foi introduzido o indicador de atributo privado e a sintaxe fica bem parecida com a nossa tentativa inválida:

class User {
    #age = null;
    constructor(name, age) {
        this.name = name;
        age = age;
    }
}

Se tentarmos acessar o atributo age, receberemos como resultado undefined:

let user = new User('Gustavo', 25);
console.log(user.name); // Gustavo
console.log(user.age); // undefined

De fato, usando a api de reflexão podemos ter a certeza de que o atributo age não é exposto ao mundo externo:

console.log(Reflect.has(user, 'name')) // true
console.log(Reflect.has(user, 'age')) // false

Legal, porém o suporte de classes em JavaScript é curto. Herança múltipla não é suportada, sobrecarga não existe, polimorfismo é simulado através da natureza dinâmica dos tipos do JavaScript. Ou seja, JavaScript não é uma linguagem que suporte Orientação a Objetos.

A minha crítica ao uso de OOP em JavaScript parte principalmente do pressuposto das pessoas tentarem usar conceitos de OOP em JavaScript sem conhecer muito bem como classes funcionam por de baixo dos panos, culminando em softwares de difícil manutenção e suscetíveis a problemas de herança que surgem após algum tempo de desenvolvimento.

Uma tentativa Funcional

Não pense que JavaScript é uma linguagem funcional, pois não é. JavaScript está num limbo onde a maioria dos principais atrativos da linguagem não dão suporte completo aos paradigmas existentes. JavaScript quase implementa seu próprio paradigma de programação, um verdadeiro monstro de Frankenstein.

Linguagens que implementam o paradigma funcional possuem características únicas. Essas linguagens se apoiam em um sistema de tipos robusto e várias otimizações de performance, já que conceitos como recurção e imutabilidade caminham de mãos dadas ao paradigma funcional.

JavaScript não tem suporte a recursão de cauda, ou seja, o ato de, quando uma função chamar a si mesma e a chamada for a última instrução do corpo da função e o contexto atual não depender do próximo contexto, em vez de ser empilhado mais uma chamada, a função simplesmente “pula” para o início. Portanto é necessário o uso de iteração em JavaScript.

Também não existe um meio não muito verboso de criar dados imutáveis. Existe a palavra chave const que cria uma referência imutável a uma área de memória, porém não cria objetos imutáveis, ou seja:

const u = {
    name: 'Gustavo'
}

u.name = 'Ciclano';
console.log(u); // { name: 'Ciclano' }

Porém, mesmo com todas as deficiências do JavaScript, essa linguagem é incrível. É excepcionalmente performática em lidar com objetos e criar funções. Operar com funções em JavaScript é uma tarefa prazerosa, é possível compor funções, misturar objetos e mesmo assim, se seguirmos as regras corretas, no final do dia ter um software extremamente estável e determinístico.

Uma mistura inusitada

Particularmente, prefiro definir um tipo por módulo (arquivo), junto de funções que operam sobre este tipo. É como criar um protocolo de acesso de informação dentro de um módulo. Mas como podemos criar tipos em JavaScript?

Classes ou funções construtoras são formas de criar novos tipos. Para criar um tipo User poderíamos tomar dois caminhos:

// função construtora
function User(name, age) {
    this.name = () => name;
    this.age = () => age;
}

// Classe
class User {
    constructor(name, age) {
        this.name = () => name;
        this.age = () => age;
    }
}

Em ambos os casos, a instanciação de novos objetos do tipo User ocorre da mesma forma:

let u = new User('Gustavo', 25);
u.name(); // Gustavo
u.age(); // 25

Porém, em qualquer lugar é possível acessar as funções name e age. Existem casos onde pode ser necessário transitar esta instância de usuário por bibliotecas que não são totalmente confiáveis. Também existem casos onde simplesmente não queremos deixar estas informações acessíveis pelo motivo de seguirmos boas práticas de programação.

A forma que encontrei para contornar este problema de forma particularmente “elegante” é usar símbolos e funções construtoras. Porque símbolos? Símbolos são pedaços de informação única, não são copiáveis, tampouco acessíveis caso usados como parâmetros de objetos e é neste caso que usarei os símbolos do JavaScript.

Também prefiro funções construtoras em vez de classes, pelos motivos já citados no início do artigo.

Ok, mas como é possível organizar o software usando funções e símbolos? Primeiro vamos criar um arquivo chamado user.js e definir dois símbolos:

// user.js
const nameAttr = Symbol('user/name');
const ageAttr = Symbol('user/age');

Agora vamos definir uma função construtora que define o tipo User:

// user.js
const nameAttr = Symbol('user/name');
const ageAttr = Symbol('user/age');
export default function User(name, age) {
    this[nameAttr] = () => name;
    this[ageAttr] = () => age;
}

Há um porém no código acima: não queremos criar uma instância de User caso o nome e a idade não sejam atribuídos. Não devem existir instâncias de usuários sem nome ou sem idade. Para isso, podemos definir algumas asserções simples de existência (não vou me preocupar com os tipos dos parâmetros neste artigo):

// user.mjs

const nameAttr = Symbol('user/name');
const ageAttr = Symbol('user/age');

export default function User(name, age) {
    if (!name) {
        throw new Error('Cannot create an User without name.');
    }
    if (!age) {
        throw new Error('Cannot create an User without age.');
    }
    this[nameAttr] = () => name;
    this[ageAttr] = () => age;
}

O que há de especial na função User acima? Vamos criar uma instância e inspecionar:

let u = new User('Gustavo', 25);
// e agora?

Não é possível acessar as funções que retornam o nome e a idade. É simplesmente impossível acessar estas funções sem ter acesso aos símbolos que definem as propriedades que, então, definem estas funções. Foi criado um protocolo de acesso onde somente as funções que têm acesso aos símbolos conseguem invocar as funções definidas no tipo User, a sacada aqui é que os símbolos não são exportados do módulo.

Vamos então definir as funções que operam sobre instâncias de usuários:

function getName(user) {
    return user[nameAttr]();
}

function getAge(user) {
    return user[ageAttr]();
}

Agora é possível acessar o nome e idade de um usuário usando estas funções:

getName(u); // Gustavo
getAge(u); // 25

Legal, mas estas funções somente operam sobre instâncias de usuários. Para prevenir que estas funções sejam invocadas sob a informação incorreta, podemos definir uma asserção de tipo em cada função getter:

function getName(user) {
    if (user instanceof User) {
        return user[nameAttr]();
    }

    throw new TypeError('Provided data is not of the type User');
}

E invocar como:

getName(u); // Gustavo
getName({ name: 'Gustavo' });
// Uncaught TypeError: Provided data is not of the type User

Legal. Mas colocar esta validação de tipo dentro de cada função viola os princípios do DRY. Podemos usar os poderes da abstração e criar uma função que “decora” outras funções e serve como guardiã do argumento. Caso o argumento seja uma informação diferente de uma instância de User a função decorada não deve ser invocada. Podemos definir uma função chamada withGuardUser que vai lidar com o tipo do argumento das funções:

function withGuardUser(fn) {
    return function withUser(user) {
        if (user instanceof User) {
            return fn(user);
        }

        throw new TypeError(
            'Provided data is not of the type User'
        );
    }
}

Agora podemos criar duas novas funções e exportá-las do nosso módulo user.js que vão operar de forma segura sobre instâncias de usuários:

export const name = withGuardUser(getName);
export const age = withGuardUser(getAge);

Em um outro arquivo, por exemplo, user1.js, importe a função construtora User e as funções de projeção name e age:

// user1.js
import User, { name, age } from './user.mjs';

const user = new User('Gustavo', 25);
console.log(name(user)); // Gustavo
console.log(age(user)); // 25

Aviso: para usar a sintaxe de ES Modules no Node.js 13, não esqueça de criar um arquivo package.json no diretório onde os seus arquivos estão armazenados contendo o parâmetro "type" cujo valor é "module". Veja mais sobre isso em https://nodejs.org/api/esm.html.

Um exemplo

Considere que é necessário construir uma interface de histórico de registro de ações de um determinado usuário em um determinado sistema, e gostaríamos de mostrar este registro da seguinte forma:

[Sun, 09 Feb 2020 04:07:11 GMT | GUSTAVO]: Action


...

Podemos começar definindo uma função que recebe um texto e retorna este texto com todas as letras maiúsculas:

const upper = (text) => text.toUpperCase();

Agora precisamos definir uma função que retorna aquele texto de data de ação para um determinado carimbo de tempo:

const utcString = (timestamp) =>
    (new Date(timestamp)).toUTCString();

Certo, agora precisamos gerar esse carimbo de tempo, podemos criar uma função chamada now que faz exatamente isso:

const now = () => Date.now();

A parte crucial é montar a string de prefixo, então podemos definir uma função chamada actionLoggerPrefix, definida como:

const actionLoggerPrefix = (userName) => {
    const ts = now();
    const date = utcString(ts);
    return `[${[date, userName].join(' | ')}]`;
}

Usando uma função de pipeline de dados, por exemplo, a função pipe:

const pipe = (...fns) => (...args) =>
    fns.reduce((acc, fn) => fn(acc), ...args);

Podemos então criar a função prefix que usa as funções name , upper e actionLoggerPrefix para criar uma função que recebe uma instância de um usuário do tipo User e retorna um texto com a formatação adequada:

const prefix = pipe(name, upper, actionLoggerPrefix);
console.log(prefix(user)); // [Sun, 09 Feb 2020 04:24:59 GMT | GUSTAVO]

Veja, criamos uma função complexa que é a junção de três funções bem simples, bem fáceis de dar manutenção e independentes de contexto. A função name opera somente sobre instâncias do tipo User, portanto as chances das funções serem invocadas sobre o tipo de dado incorreto são muito menores.

Confira o código final do módulo que opera sobre o tipo User:

// user.mjs

const nameAttr = Symbol('user/name');
const ageAttr = Symbol('user/age');

export default function User(name, age) {
    if (!name) {
        throw new TypeError('Cannot create an User without name.');
    }
    if (!age) {
        throw new TypeError('Cannot create an User without age');
    }

    this[nameAttr] = () => name;
    this[ageAttr] = () => age;
}


function withGuardUser(fn) {
    return function withUser(user) {
        if (user instanceof User) {
            return fn(user);
        }

        throw new TypeError(
            'Provided data is not of the type User'
        );
    }
}


function getName(user) {
    return user[nameAttr]();
}


function getAge(user) {
    return user[ageAttr]();
}


export const name = withGuardUser(getName);
export const age = withGuardUser(getAge);

E esse é o segundo arquivo contendo as outras funções criadas para solucionar parte do problema de listagem de registro de ações:

// user1.js

import User, { name, age } from './user.mjs';

const user = new User('Gustavo', 25);


const now = () => Date.now();

const utcString = (timestamp) =>
    (new Date(timestamp)).toUTCString();

const upper = (text) => text.toUpperCase();

const actionLoggerPrefix = (userName) => {
    const ts = now();
    const date = utcString(ts);

    return `[${[date, userName].join(' | ')}]`;
}

const pipe = (...fns) => (...args) =>
    fns.reduce((acc, fn) => fn(acc), ...args);


const prefix = pipe(name, upper, actionLoggerPrefix);

console.log(prefix(user));
// [Sun, 09 Feb 2020 14:50:02 GMT | GUSTAVO]

Considerações finais e pessoais

No final do dia, seu software deve funcionar, ser testado, ser estável e não exigir mais energia cognitiva que o necessário para entender como as coisas funcionam. Eu acredito que adotar uma abordagem mais declarativa no dia a dia é de suma importância para desenvolver softwares estáveis e fáceis de testar. Também inibe más práticas de programação. É muito difícil violar o DRY escrevendo funções pequenas.

Mas lembre-se de que as pessoas que trabalham contigo precisam estar dispostas a abrir a mente e adotar abstrações que tornam o código mais declarativo. Isso é de uma importância inimaginável.

Portanto o meu conselho que fica é que, se você que leu este texto até o fim é uma pessoa que se considera pronta para adotar os conceitos funcionais e declarativos no dia a dia, não esqueça de conversar com seu time, saiba a opinião das pessoas quanto a programação funcional, descubra se são pessoas abertas a mudanças, talvez introduzir algumas regras no linter usado nos projetos da empresa. Forçar que todos desenvolvam de uma maneira que não estão acostumados, pode mais trazer problemas do que soluções.

Simplicidade da abstração: throwable

Gustavo Santos — Fri, 08 Nov 2019 01:21:36 +0000

Imagine que você possui o caldeirão do inferno em suas mãos e precisa contê-lo dentro de uma caixa. Como você coloca o inferno dentro de uma caixa?

A abstração pode nos ajudar como desenvolvedores a resolver vários problemas de formas diferentes. Por esse e outros motivos Haskell é uma linguagens considerada tão difícil de ser aprendida, a abstração nos força a exercitar músculos cerebrais que não são trabalhados diariamente pela maioria de nós desenvolvedores.

Neste texto vou usar uma abstração simples, porém poderosa, e um pouquinho de TypeScript para tentar ilustrar que o nosso código de todo dia pode ser melhorado de algumas formas a fim de ser mais seguro.

Throwable é uma função simples, ela recebe uma função que pode disparar uma exceção e retorna uma caixa mágica. Esta caixa possui dois métodos implementados, map que recebe uma função, aplica esta função ao retorno do callback que throwable recebe e retorna uma outra caixa mágica. Outro método implementado é o return, que apenas retorna o valor que existe dentro da caixa. Considere o exemplo a seguir:

const r = throwable(() => 42);
r.return() // 42

O que está acontecendo aqui? throwable recebe uma "factory function", uma função getter que produz um resultado e, este resultado é guardado dentro da caixa mágica. Quando a segunda linha é executada, o valor 42, que até então estava guardado dentro da caixa, é exposto para o mundo externo.

Hum, você, pessoa pensativa, pode estar se perguntando se é só isso mesmo. Bom, considere esse outro exemplo:

const r = throwable(() => 42);

const result = r
    .map(num => num + num)
    .map(num => num * num)
    .return(); // 7056

O que está acontecendo aí em cima??? Imagine que você jogou o número 42 dentro de uma caixa, depois jogou uma função num => num + num dentro dessa caixa e depois ainda jogou outra função num => num * num nessa mesma caixa e no final, misteriosamente tirou o número 7056 da caixa 😱😱😱😱.

Mas no final tudo faz sentido: imagina que na caixa existia o número 42, então você aplicou a função num => num + num no número 42, ou seja você transformou o número 42 que existia dentro da caixa, no número 84. Depois você aplicou a função num => num * num no número 84, o que produziu o número 7056. Agora faz sentido?

Ok, talvez explicar como isso funciona seja mais educativo, então vamos lá!

Lembra da abstração? Fazer algo desse tipo exige um nível de abstração um pouco maior, não estamos mais lidando com bits e bytes, mas sim com caixas. A base da função throwable é uma classe abstrata chamada Optional<A>, dê uma olhada nessa classe:

abstract class Optional<A> {
  protected x: A;
  constructor(x: A) {
    this.x = x;
  }

  abstract map<B>(f: (x: A) => B): Optional<B>;
  abstract return(): A;
}

Conhecer TypeScript é de grande valia neste caso, mas tentarei explicar o que acontece aqui: Optional é uma classe abstrata que possui dois métodos abstratos, map e return, ambos métodos devem ser implementados por todas as classes que estendam de Optional. Também existe o atributo protegido x, do tipo A, este atributo é acessível somente às classes que estendam de Optional<A>. Insight importante: a nossa caixa mágica na verdade é uma instância da classe Optional<A>.

Ok, mas quem estende desta classe? As classes Just<A> e Nothing<A>.

Olhe a implementação da classe Just<A>:

class Just<A> extends Optional<A> {
  constructor(x: A) {
    super(x);
  }

  map<B>(f: (x: A) => B): Optional<B> {
    // olha o throwable aqui
    return throwable(() => f(this.x));
  }

  return() {
    return this.x;
  }
}

Agora olhe a implementação da classe Nothing<A>:

class Nothing<A> extends Optional<A> {
  constructor() {
    super(null);
  }

  map<B>(): Optional<B> {
    return new Nothing();
  }

  return() {
    return this.x;
  }
}

Está conseguindo grudar uma coisa na outra? Talvez? Dê uma olhada na implementação da função throwable então:

const throwable = <B>(factory: () => B): Optional<B> => {
  try {
    const result = factory();
    return new Just(result);
  } catch (err) {
    return new Nothing();
  }
};

A função throwable não se importa se acontecer algum erro durante a avaliação da função factory. Caso aconteça, apenas será retornado uma instância da classe Nothing. Caso a avaliação de factory produza qualquer resultado sem que uma exceção seja disparada, uma instância da classe Just será retornada. Como tanto Just e Nothing estendem de Optional e Optional exige que os métodos base sejam implementados, há total compatibilidade entre as instâncias das duas classes, sendo possível encadear chamadas a map, mesmo em casos onde ocorra um erro.

Agora você possui o inferno dentro de uma caixa. Dê uma olhada neste exemplo de uso desta abstração:

const result = throwable(() => JSON.parse("{ 32"))
  .map(num => num + num)
  .map(num => num * num);

console.log(result); // Nothing { x: null }

Nenhum erro ocorreu. Você jogou uma operação que pode disparar uma exceção, mas tudo bem, você apenas receberá de volta uma instância da classe Nothing, como nesse próximo exemplo:

const deepAccess = (obj: any) => obj.a.b.c;

const result = throwable(() => deepAccess({ a: 1 }))
  .map(num => num + num)
  .map(num => num * num);

if (result instanceof Just) {
  console.log("sucess: ", result.return());
} else {
  console.log("fail"); // fail
}

Mesmo caso, acessar a propriedade a.b.c do objeto { a: 1 } causa um erro de runtime, que será abstraído pela função throwable.

No final das contas, throwable apenas oferece uma camada de abstração para operações síncronas que podem causar erros em tempo de execução do JavaScript. Oferecer essa mesma abstração para funções assíncronas é tema de um próximo post.

Alguns passos simples para melhorar a estabilidade de seu projeto

Gustavo Santos — Fri, 04 Oct 2019 00:20:06 +0000

Seja um projeto novo ou antigo, dar manutenção e adicionar novas funcionalidades de forma rápida e segura é complicado. Rápido é subjetivo, em empresas que trabalham com o método ágil, principalmente statups, parece que você não tem o tempo suficiente para escrever um teste mais bem elaborado, ou algo do tipo. Eu entendo, passo por isso em toda sprint, cada vez entra mais funcionalidades e o débito técnico... ah o velho débito técnico.

Porém existem formas de garantir uma certa estabilidade do código, e foi aplicando estas regras (que você poderá ver em seguida), que conseguimos reduzir para quase nenhum hotfix (correções em produção de algo que não está funcionando) por mês.

Dica 1: Configure bem seu ESLint

Muitos bugs podem ser pegos pelo linter. Usou uma variável que não existe (digitou um 'a' a mais ou a menos na palavra)? O linter vai te mostrar que existe essa falha. Definiu uma função nova e não especificou o que ela vai receber? O linter vai te mostrar que existe essa falha. Hoje usamos Javascript nos nossos projetos, implementar o Typescript exige um esforço que não é a prioridade, mas você pode exigir que os desenvolvedores definam os tipos dos dados através de documentação com JSDoc. Não é tão preciso quanto uma ferramenta que realmente transpila seu código, como o tsc, mas é muito útil e foi peça chave para nos prevenir de fazer cagada.

Dica 2: Use um hook de pré-commit para checar se o código fonte está de acordo com as regras do ESLint.

Usamos Husky e Lint-Staged para prevenir que coisas como console.log(some.very.important.info) vá para produção. Mas como isso funciona?

O Husky é uma ferramenta que, sempre que um hook do git for disparado, vai executar algum comando. Por exemplo:

// package.json

{
  "husky": {
    "hooks": {
      "pre-commit": "npm run test"
    }
  }
}

Ou seja, sempre que você fizer um commit, o Husky irá disparar o comando especificado e se caso o comando terminar com sucesso, o commit será concluído, caso contrário o commit será abortado.

Usamos o Lint-Staged em comjunto com o Husky para verificar, antes de cada commit, se todo o código que está no modo preparado (staged), está de acordo com as regras estabelecidas no nosso arquivo de configuração do ESLint. Esta é a nossa primeira barreira para combater códigos que estejam fora dos padrões da aplicação. Recomendo esta leitura aos curiosos de plantão: Code consistency with ESLint and Husky.

Dica 3: Escreva testes unitários, mas não muitos

Se você ainda não sabe, deixa eu te contar: testar se um monte de componentes eletrônicos estão funcionando corretamente, não significa que a televisão está funcionando corretamente. Inclusive, eu recomendo não escrever testes de snapshot se o produto que você desenvolve estiver em constante mudança.

Mas escrever testes de ponta a ponta é muito demorado, a empresa pode não estar disposta a investir tempo neste nível de confiabilidade do sistema por enquanto, porém é importante pelo menos ter a certeza de que componentes críticos no seu sistema estão funcionando como deveriam funcionar.

Por exemplo, se o seu produto tiver suporte a múltiplas línguas, você gostará de saber que seus arquivos de tradução estão consistentes. Se o seu produto suporta múltiplas moedas, você gostará de saber que seus métodos e componentes que lidam com valores monetários estão funcionando sem erros.

Dica 4: Use o Storybook como ferramenta de desenvolvimento primária

Hoje meu fluxo de desenvolvimento quando preciso criar algo novo é: criar o arquivo que conterá o componente e então criar mais duas pastas: __tests__ e __stories__. Na pasta __tests__ vou escrever os testes, se for algo crítico serão vários, se for algo não crítico serão poucos ou nenhum (volto a dizer, ter a maior cobertura de testes não é a prioridade hoje). Na pasta __stories__ eu defino o componente e acoplo nele vários plugins para fazer testes visuais com o Storybook.

O callback está sendo chamado na hora certa e com os dados certos? Ótimo. O componente está se comportando visualmente da forma correta? Melhor ainda. Pessoas com deficiência visual estão conseguindo distinguir as cores ou está tudo uma bagunça? Tudo isso e mais muitas coisas você consegue testar enquanto desenvolve usando o Storybook. Por fim, você só precisará plugar este componente (que neste ponto estará totalmente desacoplado do restante da aplicação) no restante da aplicação.

O Storybook é uma ferramenta incrível que traz muita velocidade durante o desenvolvimento. Desenvolver e ter um feedback imediato, isolado e testável do que você está fazendo é uma adição incrível ao seu fluxo de trabalho.

Ah, sua equipe de QA pode acessar todas as stories que você já escreveu no Storybook e fazer asserções sobre seu componente de forma isolada, sem precisar procurar o componente novo em algum lugar na aplicação.

Se você trabalha em um produto que está em constante mudança, com melhorias contínuas a cada semana e precisa ter algumas garantias sobre o código ou melhorar a estabilidade mas sem ter muito tempo para escrever testes longos e bastante assertivos, talvez seja interessante testar algumas coisas que escrevi neste artigo.

I've write a VSCode extension to share folders with Dat

Gustavo Santos — Tue, 27 Nov 2018 16:24:32 +0000

Another day I was trying a easy way to share a simple directory with a friend, and store with git, create a github repo, make commit and push it was very expansive because I'm at the ending of my graduation and I'm very tired in the last days.

So, I have write a very simple vscode extension to do this with Dat! Anyone can access with this link and plase, if anyone has time to contribute, do it. My english is not so good to write documentation and only correcting my spelling will help a lot :)

DEV Community: Gustavo Santos

Refactoring React: Manage page paths through path functions

Conclusion

How to do Ping-Pong pair programming in a remote environment

Why ping-pong pair programming is a thing in remote environment?

Refactoring React: Applying Tell Don't Ask

What is "Tell Don't Ask"?

Working example

Applying the refactoring

I'm using a shared component! I cannot apply this rule

Conclusion

Learn more

Updates

What is your programming font?

Elixir: use, import ou require, qual a diferença?

Diretiva import

Diretiva require

Diretiva use

Conclusão

Para saber mais

Testando componentes React

Disclaimer

O projeto

Adicionando o formulário de login

Integrando com o backend

Usando tabelas de teste

O modelo de login

Considerações finais

FAQ

Praticando magia azul com Promises e JavaScript

Promises

A pureza das funções

Programação com efeitos

Levantamento

Sob a ótica da abstração

Levantando funções

Controle declarativo

Conclusões

Tsoid

Um devaneio sobre Classes, Objetos, Funções e organização em JavaScript

Classes em JavaScript

Uma tentativa Funcional

Uma mistura inusitada

Um exemplo

Considerações finais e pessoais

Simplicidade da abstração: throwable

Alguns passos simples para melhorar a estabilidade de seu projeto

Dica 1: Configure bem seu ESLint

Dica 2: Use um hook de pré-commit para checar se o código fonte está de acordo com as regras do ESLint.

Dica 3: Escreva testes unitários, mas não muitos

Dica 4: Use o Storybook como ferramenta de desenvolvimento primária

I've write a VSCode extension to share folders with Dat

Diretiva `import`

Diretiva `require`

Diretiva `use`