---
title: "using"
description: "Автоматически освобождает ресурсы при выходе из области видимости."
url: "https://doka.guide/js/using/"
section: "JavaScript"
createdAt: "2026-11-22"
updatedAt: "2026-11-22"
baseline: [{"group":"explicit-resource-management","features":["javascript.statements.using","javascript.builtins.Symbol.dispose"]}]
authors: ["vitya-ne"]
related: ["js/var-let", "js/try-catch", "js/async-await"]
source: "https://github.com/doka-guide/content/blob/main/js/using/index.md"
license: "CC BY-NC-SA 4.0"
---

# using

## Кратко

Синтаксис `using` упрощает управление ресурсами, которые требуют явного освобождения после использования (например, сетевые соединения, потоки, подключения к базам данных).

**Синхронный** ресурс — это объект JavaScript с методом `[Symbol.dispose](https://doka.guide/js/using/)`. **Асинхронный** — с методом `[Symbol.asyncDispose](https://doka.guide/js/using/)`.

Объявление переменной с помощью `using` связывает её с **синхронным** ресурсом. При выходе из области видимости переменной автоматически вызывается метод `[Symbol.dispose](https://doka.guide/js/using/)`. Для **асинхронного** освобождения используется `await using`: сначала движок ищет метод `[Symbol.asyncDispose](https://doka.guide/js/using/)`, а если его нет — использует `[Symbol.dispose](https://doka.guide/js/using/)`.

## Пример

Рассмотрим пример с файловым дескриптором Node.js.
Метод `open()` возвращает объект `FileHandle`, у которого есть метод `[Symbol.asyncDispose](https://doka.guide/js/using/)`.

```js
import { open } from 'node:fs/promises'

const processFile = async (filePath) => {
  await using file = await open(filePath, 'r') // Создание ресурса
  const content = await file.readFile({ encoding: 'utf8' }) // Использование
  console.log('Содержимое файла:', content)
} // <-- Файловый дескриптор автоматически закрывается

processFile('./example.txt')
```

При выходе из функции `await using` дождётся закрытия файлового дескриптора.

Демонстрация работы с ресурсом в браузере:

<iframe title="Управление ресурсом с помощью using" src="https://doka.guide/js/using/demos/using-steps/" height="440"></iframe>

## Как пишется

```js
using name = value
```

где:
- `name` — имя переменной, которая будет ссылаться на ресурс;
- `value` — начальное значение переменной. Им может быть `null`, `undefined` или объект с методом `[Symbol.dispose](https://doka.guide/js/using/)`.

Переменная, объявленная с помощью `using`, ведёт себя как `const`: её нужно инициализировать при объявлении, и ей нельзя присвоить новое значение.

Для асинхронного освобождения ресурсов применяется синтаксис `await using`:

```js
await using name = value
```

Значением `value` может быть `null`, `undefined` или объект с методом `[Symbol.asyncDispose](https://doka.guide/js/using/)` либо `[Symbol.dispose](https://doka.guide/js/using/)`.

`using` можно использовать:
- внутри блока кода;
- в теле функции;
- на верхнем уровне ES-модуля;
- внутри статического блока инициализации класса;
- в инициализаторе цикла `for`, а также в заголовке циклов `for...of` и `for await...of`.

`using` нельзя использовать на верхнем уровне обычного скрипта, непосредственно на верхнем уровне `switch` и в заголовке цикла `for...in`.

`await using` можно использовать:
- внутри блока, если он находится в асинхронном контексте;
- в теле асинхронной функции или асинхронного генератора;
- на верхнем уровне ES-модуля;
- в инициализаторе цикла `for` и в заголовке циклов `for...of` и `for await...of`, если цикл находится в асинхронном контексте.

`await using` нельзя использовать в обычной синхронной функции или на верхнем уровне обычного скрипта. Как и `using`, его нельзя объявлять непосредственно на верхнем уровне `switch`.

При попытке присвоить переменной недопустимое значение будет брошена ошибка TypeError.

## Как понять

Чтобы понять, как работает управление ресурсами, рассмотрим пример из жизни.

Представьте: вы заходите в комнату и включаете свет (создаёте ресурс). Вам нужно не забыть выключить его при выходе (освободить ресурс), иначе свет будет гореть без всякой пользы (утечка ресурсов).

Синтаксис `using` — это как элемент «умного дома»: как только вы покидаете комнату, свет автоматически гаснет. Но чтобы это работало, система освещения должна поддерживать «умный дом» — то есть иметь метод освобождения ресурса (например, `[Symbol.dispose](https://doka.guide/js/using/)`).

Автоматическое освобождение ресурсов решает несколько проблем:

- Забывчивость — разработчик может забыть добавить вызов метода освобождения ресурса (например, закрыть соединение с базой данных);
- Возникновение исключений при работе с ресурсом — если произойдёт ошибка, код освобождения может не выполнится;
- Соблюдение порядка освобождения зависящих друг от друга ресурсов.

Посмотрим на абстрактный пример функции работы с ресурсом:

```js
const processResource = () => {
  // Создание ресурса
  const resource = openResource()

  try {
    // Использование ресурса
  } finally {
    // Освобождение ресурса
    closeResource(resource)
  }
}
```

Функция освобождения ресурса `closeResource()` вызывается в блоке `finally`. Это позволяет вызвать её даже в случае возникновения ошибки в блоке `try`. Однако если сама функция `closeResource()` выбросит исключение, оно может заменить исходное исключение из блока `try`.

Синтаксис `using` гарантирует вызов метода освобождения при выходе из области видимости — в том числе при исключении. Но он не гарантирует, что само освобождение завершится успешно: метод `[Symbol.dispose](https://doka.guide/js/using/)` тоже может выбросить ошибку. Если исключение возникло и в основном коде, и при освобождении ресурса, они не теряются: движок выбрасывает `SuppressedError`. В его свойстве `error` находится ошибка, возникшая при освобождении, а в `suppressed` — ошибка, которая уже обрабатывалась. В Chrome и Node.js свойство `message` содержит сообщение «An error was suppressed during disposal».

```js
function openResource() {
  return {
    [Symbol.dispose](https://doka.guide/js/using/) {
      throw new Error('Ошибка при освобождении ресурса')
    }
  }
}

try {
  using resource = openResource()
  throw new Error('Ошибка в теле')
} catch (error) {
  console.log(error instanceof SuppressedError)
  // true
  console.log(error.message)
  // 'An error was suppressed during disposal' в Chrome и Node.js
  console.log(error.error.message)
  // 'Ошибка при освобождении ресурса'
  console.log(error.suppressed.message)
  // 'Ошибка в теле'
}
```

При работе с несколькими ресурсами важно учитывать порядок их освобождения. Это может быть критично, если ресурсы зависят друг от друга. Автоматическое освобождение выполняется в обратном порядке объявления ресурсов (как в стеке). Даже если освобождение одного ресурса завершится ошибкой, движок продолжит освобождать остальные ресурсы.

Например, при работе с базой данных транзакция (tx) зависит от подключения к базе данных (connection). Если соединение закроется до завершения работы с транзакцией, это может привести к ошибке:

```js
const processMultiResources = () => {
  // 1. Создаём соединение
  const connection = new DatabaseConnection()
  // 2. Создаём транзакцию (зависит от соединения с БД)
  const tx = new Transaction(connection)

  // Работаем с объектом транзакции
  // ..

  // Важно указать правильный порядок освобождения
  tx.close()
  connection.close()
}
```

Использование `using` автоматически гарантирует правильный порядок освобождения.

```js
const processMultiResources = () => {
  // 1. Создаём соединение
  using connection = new DatabaseConnection()
  // 2. Создаём транзакцию (зависит от соединения)
  using tx = new Transaction(connection)

  // Работаем с объектом транзакции
  // ..
}
// Порядок автоматического освобождения ресурсов:
// 1. tx[Symbol.dispose](https://doka.guide/js/using/)
// 2. connection[Symbol.dispose](https://doka.guide/js/using/)
```

### Асинхронные ресурсы

Некоторые ресурсы нельзя освободить синхронно: для завершения работы с ними нужно дождаться асинхронной операции, например закрытия соединения или завершения ввода-вывода. Такой ресурс может предоставить метод `[Symbol.asyncDispose](https://doka.guide/js/using/)`. Для автоматического асинхронного освобождения его объявляют с помощью `await using`:

```js
class AsyncResource {
  async [Symbol.asyncDispose](https://doka.guide/js/using/) {
    console.log('Асинхронный ресурс освобождён')
  }

  // Другие методы
  // ..
}

const processAsyncResources = async () => {
  await using resource = new AsyncResource()
  // Работа с ресурсом
  // ..

} // Автоматический вызов `[Symbol.asyncDispose](https://doka.guide/js/using/)`

processAsyncResources()
// Асинхронный ресурс освобождён
```

<aside>

☝️ Обратите внимание: [`await`](/js/async-await/) здесь относится не к объявлению, а к моменту освобождения. При выходе из области видимости движок дождётся завершения промиса, который вернёт метод `[Symbol.asyncDispose](https://doka.guide/js/using/)`, и только потом продолжит выполнение.

</aside>

### Управление ресурсами в цикле

Синтаксис `await using` можно использовать в циклах `for...of` и `for await...of`, чтобы автоматически закрывать каждый файловый дескриптор после обработки соответствующего файла.

```js
import { open } from 'node:fs/promises'

// Обработка массива путей к файлам
async function processFiles(filePaths) {
  const results = []

  for (const filePath of filePaths) {
    try {
      await using file = await open(filePath, 'r')
      const content = await file.readFile({ encoding: 'utf8' })

      results.push({
        path: filePath,
        length: content.length
      })
    } catch (error) {
      // Сюда попадут и ошибки чтения, и ошибки закрытия файла
      console.error(`Ошибка при обработке ${filePath}:`, error)
      results.push({ path: filePath, error: error.message })
    }
    // Файл закрывается перед переходом к следующей итерации
  }

  return results
}

processFiles(['./first.txt', './second.txt'])
```

Преимущества такого подхода:

- Не нужно вручную вызывать `file.close()`;
- файловый дескриптор автоматически закрывается при выходе из блока `try`;
- ошибки чтения и освобождения ресурса можно обработать в одном `catch`.

## Подсказки

💡 При использовании `await using` ресурс может быть освобождён с помощью синхронного метода `[Symbol.dispose](https://doka.guide/js/using/)`, если отсутствует метод `[Symbol.asyncDispose](https://doka.guide/js/using/)`. Освобождение произойдёт синхронно, даже если попытаться вернуть промис:

```js
class Resource {
  [Symbol.dispose](https://doka.guide/js/using/) {
    return new Promise((resolve) => {
      setTimeout(resolve, 1000)
    })
  }
}

async function runTask() {
  await using resource = new Resource()
  // await using не будет ждать завершения Promise
  console.log('Работа завершена')
}
```

💡 Если ошибки возникают при освобождении нескольких ресурсов, движок последовательно формирует вложенные объекты `SuppressedError`. Например, ресурсы объявлены в порядке `resource1`, затем `resource2`, поэтому освобождаются в обратном порядке. Если исходный код и оба метода освобождения выбросят ошибки, структура будет выглядеть примерно так:

```js
new SuppressedError(
  errorFromFirstResource,
  new SuppressedError(
    errorFromSecondResource,
    originalError
  )
)
```

Сначала освобождается `resource2`, затем `resource1`. Поэтому ошибка освобождения `resource1` окажется во внешнем свойстве `error`, а предыдущая ошибка — в `suppressed`. Цепочка позволяет добраться и до исходного исключения, и до ошибок освобождения.

💡 Освобождение ресурса в цикле происходит также при `break`, `continue` и исключениях. При этом `for await...of` отвечает за асинхронную итерацию, а `await using` — за асинхронное освобождение ресурса. Это независимые механизмы: их можно использовать как вместе, так и по отдельности.

💡 Если количество ресурсов заранее неизвестно или они добавляются динамически, можно использовать `DisposableStack` или `AsyncDisposableStack`. Эти объекты собирают ресурсы в стек и освобождают их в обратном порядке:

```js
using stack = new DisposableStack()

const first = stack.use(openResource())
const second = stack.use(openAnotherResource())

// При выходе из области видимости стек освободит second, затем first.
```

Для асинхронных ресурсов используется `AsyncDisposableStack`:

```js
await using stack = new AsyncDisposableStack()

const connection = stack.use(await openConnection())
const session = stack.use(await openSession(connection))

// При выходе из области видимости ресурсы будут асинхронно освобождены
// в обратном порядке.
```

