Кратко
СкопированоСинтаксис using упрощает управление ресурсами, которые требуют явного освобождения после использования (например, сетевые соединения, потоки, подключения к базам данных).
Синхронный ресурс — это объект JavaScript с методом [Symbol. Асинхронный — с методом [Symbol.
Объявление переменной с помощью using связывает её с синхронным ресурсом. При выходе из области видимости переменной автоматически вызывается метод [Symbol. Для асинхронного освобождения используется await using: сначала движок ищет метод [Symbol, а если его нет — использует [Symbol.
Пример
СкопированоРассмотрим пример с файловым дескриптором Node.js.
Метод open() возвращает объект File, у которого есть метод [Symbol.
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')
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 дождётся закрытия файлового дескриптора.
Демонстрация работы с ресурсом в браузере:
Как пишется
Скопировано
using name = value
using name = value
где:
name— имя переменной, которая будет ссылаться на ресурс;value— начальное значение переменной. Им может бытьnull,undefinedили объект с методом[Symbol..dispose]()
Переменная, объявленная с помощью using, ведёт себя как const: её нужно инициализировать при объявлении, и ей нельзя присвоить новое значение.
Для асинхронного освобождения ресурсов применяется синтаксис await using:
await using name = value
await using name = value
Значением value может быть null, undefined или объект с методом [Symbol либо [Symbol.
using можно использовать:
- внутри блока кода;
- в теле функции;
- на верхнем уровне ES-модуля;
- внутри статического блока инициализации класса;
- в инициализаторе цикла
for, а также в заголовке цикловforи...of for await....of
using нельзя использовать на верхнем уровне обычного скрипта, непосредственно на верхнем уровне switch и в заголовке цикла for.
await using можно использовать:
- внутри блока, если он находится в асинхронном контексте;
- в теле асинхронной функции или асинхронного генератора;
- на верхнем уровне ES-модуля;
- в инициализаторе цикла
forи в заголовке цикловforи...of for await, если цикл находится в асинхронном контексте....of
await using нельзя использовать в обычной синхронной функции или на верхнем уровне обычного скрипта. Как и using, его нельзя объявлять непосредственно на верхнем уровне switch.
При попытке присвоить переменной недопустимое значение будет брошена ошибка TypeError.
Как понять
СкопированоЧтобы понять, как работает управление ресурсами, рассмотрим пример из жизни.
Представьте: вы заходите в комнату и включаете свет (создаёте ресурс). Вам нужно не забыть выключить его при выходе (освободить ресурс), иначе свет будет гореть без всякой пользы (утечка ресурсов).
Синтаксис using — это как элемент «умного дома»: как только вы покидаете комнату, свет автоматически гаснет. Но чтобы это работало, система освещения должна поддерживать «умный дом» — то есть иметь метод освобождения ресурса (например, [Symbol).
Автоматическое освобождение ресурсов решает несколько проблем:
- Забывчивость — разработчик может забыть добавить вызов метода освобождения ресурса (например, закрыть соединение с базой данных);
- Возникновение исключений при работе с ресурсом — если произойдёт ошибка, код освобождения может не выполнится;
- Соблюдение порядка освобождения зависящих друг от друга ресурсов.
Посмотрим на абстрактный пример функции работы с ресурсом:
const processResource = () => { // Создание ресурса const resource = openResource() try { // Использование ресурса } finally { // Освобождение ресурса closeResource(resource) }}
const processResource = () => {
// Создание ресурса
const resource = openResource()
try {
// Использование ресурса
} finally {
// Освобождение ресурса
closeResource(resource)
}
}
Функция освобождения ресурса close вызывается в блоке finally. Это позволяет вызвать её даже в случае возникновения ошибки в блоке try. Однако если сама функция close выбросит исключение, оно может заменить исходное исключение из блока try.
Синтаксис using гарантирует вызов метода освобождения при выходе из области видимости — в том числе при исключении. Но он не гарантирует, что само освобождение завершится успешно: метод [Symbol тоже может выбросить ошибку. Если исключение возникло и в основном коде, и при освобождении ресурса, они не теряются: движок выбрасывает Suppressed. В его свойстве error находится ошибка, возникшая при освобождении, а в suppressed — ошибка, которая уже обрабатывалась. В Chrome и Node.js свойство message содержит сообщение «An error was suppressed during disposal».
function openResource() { return { [Symbol.dispose]() { 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) // 'Ошибка в теле'}
function openResource() {
return {
[Symbol.dispose]() {
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). Если соединение закроется до завершения работы с транзакцией, это может привести к ошибке:
const processMultiResources = () => { // 1. Создаём соединение const connection = new DatabaseConnection() // 2. Создаём транзакцию (зависит от соединения с БД) const tx = new Transaction(connection) // Работаем с объектом транзакции // .. // Важно указать правильный порядок освобождения tx.close() connection.close()}
const processMultiResources = () => {
// 1. Создаём соединение
const connection = new DatabaseConnection()
// 2. Создаём транзакцию (зависит от соединения с БД)
const tx = new Transaction(connection)
// Работаем с объектом транзакции
// ..
// Важно указать правильный порядок освобождения
tx.close()
connection.close()
}
Использование using автоматически гарантирует правильный порядок освобождения.
const processMultiResources = () => { // 1. Создаём соединение using connection = new DatabaseConnection() // 2. Создаём транзакцию (зависит от соединения) using tx = new Transaction(connection) // Работаем с объектом транзакции // ..}// Порядок автоматического освобождения ресурсов:// 1. tx[Symbol.dispose]()// 2. connection[Symbol.dispose]()
const processMultiResources = () => {
// 1. Создаём соединение
using connection = new DatabaseConnection()
// 2. Создаём транзакцию (зависит от соединения)
using tx = new Transaction(connection)
// Работаем с объектом транзакции
// ..
}
// Порядок автоматического освобождения ресурсов:
// 1. tx[Symbol.dispose]()
// 2. connection[Symbol.dispose]()
Асинхронные ресурсы
СкопированоНекоторые ресурсы нельзя освободить синхронно: для завершения работы с ними нужно дождаться асинхронной операции, например закрытия соединения или завершения ввода-вывода. Такой ресурс может предоставить метод [Symbol. Для автоматического асинхронного освобождения его объявляют с помощью await using:
class AsyncResource { async [Symbol.asyncDispose]() { console.log('Асинхронный ресурс освобождён') } // Другие методы // ..}const processAsyncResources = async () => { await using resource = new AsyncResource() // Работа с ресурсом // ..} // Автоматический вызов `[Symbol.asyncDispose]()`processAsyncResources()// Асинхронный ресурс освобождён
class AsyncResource {
async [Symbol.asyncDispose]() {
console.log('Асинхронный ресурс освобождён')
}
// Другие методы
// ..
}
const processAsyncResources = async () => {
await using resource = new AsyncResource()
// Работа с ресурсом
// ..
} // Автоматический вызов `[Symbol.asyncDispose]()`
processAsyncResources()
// Асинхронный ресурс освобождён
Управление ресурсами в цикле
СкопированоСинтаксис await using можно использовать в циклах for и for await, чтобы автоматически закрывать каждый файловый дескриптор после обработки соответствующего файла.
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'])
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, если отсутствует метод [Symbol. Освобождение произойдёт синхронно, даже если попытаться вернуть промис:
class Resource { [Symbol.dispose]() { return new Promise((resolve) => { setTimeout(resolve, 1000) }) }}async function runTask() { await using resource = new Resource() // await using не будет ждать завершения Promise console.log('Работа завершена')}
class Resource {
[Symbol.dispose]() {
return new Promise((resolve) => {
setTimeout(resolve, 1000)
})
}
}
async function runTask() {
await using resource = new Resource()
// await using не будет ждать завершения Promise
console.log('Работа завершена')
}
💡 Если ошибки возникают при освобождении нескольких ресурсов, движок последовательно формирует вложенные объекты Suppressed. Например, ресурсы объявлены в порядке resource1, затем resource2, поэтому освобождаются в обратном порядке. Если исходный код и оба метода освобождения выбросят ошибки, структура будет выглядеть примерно так:
new SuppressedError( errorFromFirstResource, new SuppressedError( errorFromSecondResource, originalError ))
new SuppressedError(
errorFromFirstResource,
new SuppressedError(
errorFromSecondResource,
originalError
)
)
Сначала освобождается resource2, затем resource1. Поэтому ошибка освобождения resource1 окажется во внешнем свойстве error, а предыдущая ошибка — в suppressed. Цепочка позволяет добраться и до исходного исключения, и до ошибок освобождения.
💡 Освобождение ресурса в цикле происходит также при break, continue и исключениях. При этом for await отвечает за асинхронную итерацию, а await using — за асинхронное освобождение ресурса. Это независимые механизмы: их можно использовать как вместе, так и по отдельности.
💡 Если количество ресурсов заранее неизвестно или они добавляются динамически, можно использовать Disposable или Async. Эти объекты собирают ресурсы в стек и освобождают их в обратном порядке:
using stack = new DisposableStack()const first = stack.use(openResource())const second = stack.use(openAnotherResource())// При выходе из области видимости стек освободит second, затем first.
using stack = new DisposableStack()
const first = stack.use(openResource())
const second = stack.use(openAnotherResource())
// При выходе из области видимости стек освободит second, затем first.
Для асинхронных ресурсов используется Async:
await using stack = new AsyncDisposableStack()const connection = stack.use(await openConnection())const session = stack.use(await openSession(connection))// При выходе из области видимости ресурсы будут асинхронно освобождены// в обратном порядке.
await using stack = new AsyncDisposableStack()
const connection = stack.use(await openConnection())
const session = stack.use(await openSession(connection))
// При выходе из области видимости ресурсы будут асинхронно освобождены
// в обратном порядке.
- Chrome 134, поддерживается
- Edge 134, поддерживается
- Firefox 141, поддерживается
- Safari, не поддерживается