Tudo sobre o "using" no TypeScript 5.2 e seus benefícios

Mais uma vez estamos aqui para as novidades do TypeScript! Dessa vez vamos falar de uma que não é só uma novidade do TS mas que também vai estar chegando para o JavaScript logo mais!

Essa é a funcionalidade chamada explicit resource management, ou gerenciamento explícito de recursos. Que é mais definida como uma nova keyword: using

Em outras linguagens como o C#, o using já é uma keyword bem famosa, e ela existe em outras formas, como o try-with-resources do Java ou o with do Python, a ideia dessa proposta é poder atrelar o ciclo de vida de um recurso a ele mesmo, sem que a gente precise chamar outras funções como um finally para poder se desfazer desse recurso.

Gerenciamento de recursos#

Quando estamos falando de programação de mais baixo nível como C ou C++, gerenciamento de recursos é algo essencial, mas quando estamos em linguagens de mais alto nível, esse tipo de funcionalidade acaba se perdendo bastante já que o compilador ou o engine vai tomar conta disso pra gente.

Mas as vezes é necessário fazer uma “limpeza” em alguns recursos que estamos usando depois de criar ou acabar de utilizar esse recurso. O exemplo mais clássico disso tudo é fechar uma conexão de rede ou de banco de dados. Se tivermos algo como:

1
import connection from 'seu-banco'
2

3
export async function fazerQuery (query: string) {
4
  const db = connection.start()
5
    const result = await db.query(query)
6
    connection.close()
7
    return result
8
}

Se a gente, por algum motivo, precisar fazer um early return, vamos ter que duplicar o código que está liberando o nosso recurso com o connection.close():

1
import connection from 'seu-banco'
2

3
export async function fazerQuery (query: string) {
4
  const db = connection.start()
5
    const result = await db.query(query)
6
    if (!result) {
7
      connection.close()
8
        return
9
    }
10
    connection.close()
11
    return result
12
}

Mas não garantimos se um erro acontecer, então a gente precisa de um try/catch, ai é mais fácil jogar tudo isso em um finally para ficar mais simples de ler, certo?

1
import connection from 'seu-banco'
2

3
export async function fazerQuery (query: string) {
4
  try {
5
        const db = connection.start()
6
        const result = await db.query(query)
7
        if (!result) return
8
        return result
9
    } catch (err) {
10
      console.error(err)
11
    } finally {
12
      connection.close()
13
    }
14
}

Enquanto isso é uma solução interessante, a gente escreveu uma quantidade considerável de código para poder fechar uma conexão… E é pra isso que a ideia do gerenciamento explícito existe, para tratar esses casos como algo primário.

Symbol.dispose#

Tudo gira em torno de uma propriedade do arquivo chamada Symbol.dispose, que é um Símbolo interno de todas as classes.

No caso, vamos imaginar que essa seja a nossa classe de conexão (e que exista uma factory em algum lugar que nos retorna a instância que usamos acima):

1
export class Connection {
2
  constructor (options: ConnectionOptions) {
3
      // ...
4
    }
5

6
    start () { }
7
    close () { }
8
}

Para podermos transformar a classe de conexão em uma classe que pode ser recolhida, vamos implementar uma nova propriedade:

1
export class Connection {
2
  constructor (options: ConnectionOptions) {
3
      // ...
4
    }
5

6
    start () { }
7
    close () { }
8

9
    [Symbol.dispose]() {
10
      this.close()
11
    }
12
}

Se você quiser mais conveniência, o TS já tem uma interface global chamada Disposable que você pode implementar para deixar o código mais coeso:

1
export class Connection implements Disposable {
2
  constructor (options: ConnectionOptions) {
3
      // ...
4
    }
5

6
    start () { }
7
    close () { }
8

9
    [Symbol.dispose]() {
10
      this.close()
11
    }
12
}

E ai agora podemos simplesmente chamar essa funcionalidade para poder limpar o nosso arquivo:

1
import connection from 'seu-banco'
2

3
export async function fazerQuery (query: string) {
4
  try {
5
        const db = connection.start()
6
        const result = await db.query(query)
7
        if (!result) return
8
        return result
9
    } catch (err) {
10
      console.error(err)
11
    } finally {
12
      connection[Symbol.dispose]()
13
    }
14
}

Não ajudou muito não é? A gente só moveu de um lado pro outro, apesar de agora termos um lugar específico para chamar toda a lógica, ainda sim é mais fácil do que ficar chamando os métodos específicos.

Using#

Mas, se a gente quiser passar tudo para um lugar só, podemos tirar vantagem da nova keyword using, ela funciona como se fosse um let ou const mas ao invés de só declarar a variável, ela instrui o engine a chamar Symbol.dispose no final do escopo daquela função, então nossa função anterior pode ser reescrita assim:

1
import connection from 'seu-banco'
2

3
export async function fazerQuery (query: string) {
4
  try {
5
        using db = connection.start()
6
        const result = await db.query(query)
7
        if (!result) return
8
        return result
9
    } catch (err) {
10
      console.error(err)
11
    }
12
}

Agora não temos mais a lógica de gerenciamento de recursos dentro do nosso app, o que torna muito mais fácil gerenciar essas conexões e abstrair a funcionalidade de usuários, especialmente para quem cria libs!

Disposals funcionam como uma stack, então eles vão ser chamados da última criação para a primeira. Como esse exemplo da documentação mostra bem:

1
function loggy(id: string): Disposable {
2
    console.log(`Creating ${id}`);
3

4
    return {
5
        [Symbol.dispose]() {
6
            console.log(`Disposing ${id}`);
7
        }
8
    }
9
}
10

11
function func() {
12
    using a = loggy("a");
13
    using b = loggy("b");
14
    {
15
        using c = loggy("c");
16
        using d = loggy("d");
17
    }
18
    using e = loggy("e");
19
    return;
20

21
    // Unreachable.
22
    using f = loggy("f");
23
}
24

25
func();
26
// Creating a
27
// Creating b
28
// Creating c
29
// Creating d
30
// Disposing d
31
// Disposing c
32
// Creating e
33
// Disposing e
34
// Disposing b
35
// Disposing a

Veja que eles são criados na ordem de A até D, mas destruídos de D até A. Inclusive, se você criar um escopo no meio da função, como é o caso de C e D, eles vão ser destruídos primeiro ao saírem do escopo.

Assincronismo com Symbol.asyncDispose#

Além de termos a versão síncrona, também temos a versão assíncrona do dispose. Ela se comporta da mesma forma, porém é uma função assíncrona e precisa ser usada com await using ao invés de using.

1
async function wait () {
2
  await new Promise(resolve => setTimeout(resolve, 500))
3
}
4

5
function loggy(id: string): AsyncDisposable {
6
    console.log(`Creating ${id}`);
7

8
    return {
9
        async [Symbol.asyncDispose]() {
10
            console.log(`Disposing ${id} async`);
11
            await wait()
12
        }
13
    }
14
}
15

16
function func() {
17
    await using a = loggy("a");
18
    await using b = loggy("b");
19
    {
20
        await using c = loggy("c");
21
        await using d = loggy("d");
22
    }
23
    await using e = loggy("e");
24
    return;
25

26
    // Unreachable.
27
    await using f = loggy("f");
28
}
29

30
func();
31
// Creating a
32
// Creating b
33
// Creating c
34
// Creating d
35
// Disposing d async
36
// Disposing c async
37
// Creating e
38
// Disposing e async
39
// Disposing b async
40
// Disposing a async

Tratamento de erros#

O que acontece se a nossa função de dispose tiver um erro? Ou se tivermos um erro durante a função e também na hora de destruir a função? Neste caso temos um novo tipo de erro que é estendido de Error, o SuppressedError.

Erros do tipo SuppressedError tem uma propriedade suppressed que contém o último erro que foi gerado e uma outra propriedade error para o erro mais recente.

Por exemplo, se tivermos um código como esse:

1
class ErrorA extends Error {
2
    name = "ErrorA";
3
}
4
class ErrorB extends Error {
5
    name = "ErrorB";
6
}
7

8
function foo (id: string) {
9
  return {
10
      [Symbol.dispose]() {
11
          throw new ErrorA(`Erro do id ${id}`)
12
         }
13
  }
14
}
15

16
function bar () {
17
  using f = foo("1")
18
    throw new ErrorB("Erro!")
19
}
20

21
try {
22
  bar()
23
} catch (e: any) {
24
  console.log(e.name, e.message) // SuppressedError An error was suppressed during disposal
25
    console.log(e.error.name) // ErrorA
26
    console.log(e.error.message) // Erro do id 1
27
    console.log(e.suppressed.name) // ErrorB
28
    console.log(e.suppressed.message) // Erro!
29
}

Então basicamente o erro mais recente vai ser o erro que foi gerado dentro do symbol, enquando o erro suprimido é o erro que foi gerado dentro da função antes do disposal ser chamado.

DisposableStacks#

Como você pode ter percebido, Symbol.dispose e a sua versão assíncrona podem ser ótimas soluções para códigos mais complexos, porque já estamos usando uma classe e podemos implementar a funcionalidade, mas quando temos um código simples como esse pode parecer meio demais ter que fazer toda essa lógica.

No nosso caso a gente só quer lembrar de chamar o close no final da execução, nada mais. Para isso temos duas novas funcionalidades no TS que são oDisposableStack e AsyncDisposableStack, que basicamente funcionam como ferramentas para poder executar esses symbols manualmente no final da função.

Então se a gente esquecer a nossa classe e assumir que ela não tem nenhum tipo de lógica para recuperar o recurso, voltando a nossa função original, poderíamos ter escrito ela assim:

1
import connection from 'seu-banco'
2

3
export async function fazerQuery (query: string) {
4
  try {
5
        const db = connection.start()
6
        using cleanup = new DisposableStack()
7
        cleanup.defer(() => connection.close())
8

9
        const result = await db.query(query)
10
        if (!result) return
11
        return result
12
    } catch (err) {
13
      console.error(err)
14
    }
15
}

Perceba que estamos usando uma funcionalidade chamada defer que é muito comum em Golang. O que ela faz é justamente empurrar a execução desse bloco para o final do escopo atual.

Imagine que ele é uma classe implementada assim (apenas ilustrativo):

1
export class DisposableStack implements Disposable {
2
    #stack = []
3

4
    defer (fn: (...args: any) => void) {
5
      this.#stack.push(fn)
6
    }
7

8
    [Symbol.dispose]() {
9
      for (const fn of this.#stack) {
10
            fn()
11
        }
12
    }
13
}

A ideia é que você pode definir uma stack e chamar o método defer várias vezes para adicionar uma ou mais funções na stack de reciclagem.

Conclusão#

Para usar o using nas versões mais novas do TS você precisa mudar algumas opções no compilerOptions do tsconfig, essas incluem as opções que vão mudar o alvo da compilação para a versão 2022 e adicionar os polyfills necessários, ficando algo assim:

1
{
2
    "compilerOptions": {
3
      "target": "es2022",
4
        "lib": ["es2022", "esnext.disposable", "dom"]
5
    }
6
}

Você pode ler mais sobre essa nova feature lá no blog do TS e também aprender a usar tudo certinho lá no meu treinamento da Formação TS!.

Se você quiser aprender a usar essa funcionalidade, aproveita e dá uma olhada no meu treinamento completo de TypeScript! ↩