using

Une déclaration de ressource libérée automatiquement à la sortie du bloc, même après une erreur.

Sur cette page

Exemple

#
TypeScript
// Polyfill : nécessaire uniquement là où Symbol.dispose natif est absent
(Symbol as { dispose?: symbol }).dispose ??= Symbol('Symbol.dispose')

class DbConnection implements Disposable {
  constructor(private name: string) {
    console.log(`Ouverture de ${name}`)
  }

  query(sql: string) {
    console.log(`${this.name} : ${sql}`)
  }

  [Symbol.dispose]() {
    console.log(`Fermeture de ${this.name}`)
  }
}

function saveProgress() {
  using db = new DbConnection('progress-db')
  db.query('UPDATE progress SET exp = exp + 20')
  console.log('Fin de la fonction')
}

saveProgress()
Résultat
Ouverture de progress-db
progress-db : UPDATE progress SET exp = exp + 20
Fin de la fonction
Fermeture de progress-db

Définition et utilisation

#

Une déclaration using fonctionne comme const, mais elle fait aussi le ménage derrière elle. Lorsque le programme quitte le bloc qui contient une telle déclaration, qu’il atteigne la fin, sorte par return ou par une exception, la méthode [Symbol.dispose]() de l’objet stocké est appelée. Vous fermez ainsi une connexion à une base de données, un fichier ou un verrou sans écrire try...finally à la main.

Un objet fonctionne avec using s’il possède une méthode [Symbol.dispose](), c’est-à-dire s’il satisfait l’interface Disposable. Les valeurs null et undefined sont autorisées et ignorées. Plusieurs ressources dans un même bloc sont libérées dans l’ordre inverse de leur création. La version await using attend le nettoyage asynchrone dans la méthode [Symbol.asyncDispose]() et fonctionne partout où await est autorisé.

TypeScript prend en charge cette syntaxe depuis la version 5.2. Dans lib, il faut les types esnext.disposable (ou tout esnext). Avec un target inférieur à ESNext, le compilateur transforme using en code auxiliaire qui s’appuie sur Symbol.dispose. Node.js 22 intègre ce symbole, mais tous les environnements ne le connaissent pas, c’est pourquoi le premier exemple commence par un polyfill d’une ligne.

Syntaxe

#
Syntaxe
using resource = createResource()
await using connection = await connect()

class Resource implements Disposable {
  [Symbol.dispose]() { … }
}

Plus d’exemples

#
Plusieurs ressources et une exception
TypeScript
function lock(name: string): Disposable {
  console.log(`+ ${name}`)
  return { [Symbol.dispose]: () => console.log(`- ${name}`) }
}

function gradeExam() {
  using sheet = lock('sheet')
  using results = lock('results')
  throw new Error('aucune réponse')
}

try {
  gradeExam()
} catch (error) {
  console.log((error as Error).message)
}
Résultat
+ sheet
+ results
- results
- sheet
aucune réponse
await using
TypeScript
// await using s’appuie sur Symbol.asyncDispose, il reçoit donc aussi un polyfill
(Symbol as { asyncDispose?: symbol }).asyncDispose ??= Symbol('Symbol.asyncDispose')

async function connect(name: string): Promise<AsyncDisposable> {
  console.log(`Connexion à ${name}`)
  return {
    async [Symbol.asyncDispose]() {
      console.log(`Déconnexion de ${name}`)
    }
  }
}

async function syncProgress() {
  await using api = await connect('progress-api')
  console.log('Envoi de la progression')
}

await syncProgress()
console.log('Terminé')
Résultat
Connexion à progress-api
Envoi de la progression
Déconnexion de progress-api
Terminé

Bonnes pratiques

#
  • L’erreur d’exécution « Symbol.dispose is not defined » signifie que l’environnement ne connaît pas encore ce symbole. Placez le polyfill du premier exemple tout au début de votre programme, avant la définition de toute classe qui l’utilise.
  • Une variable déclarée avec using ne peut pas être réassignée. Essayer de le faire échoue avec l’erreur « Cannot assign to 'db' because it is a constant ».
  • Si une ressource n’est nécessaire que brièvement, ouvrez-lui un bloc { … } séparé. Elle sera libérée à l’accolade fermante, et pas seulement à la fin de la fonction.

Entrées associées

#

Pratiquer dans les leçons

#

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.