Proposal: Resource Management Scopes for Node.js

[polRk]

What is the problem this feature will solve?

Problem

Node.js applications frequently suffer from resource leaks when developers forget to properly close files, sockets, timers, or other native resources. This is especially problematic when exceptions occur before cleanup code executes.

// Current problematic pattern
function processFile(filename) {
    let fd = fs.openSync(filename, 'r')
    let timer = setInterval(() => console.log('processing'), 1000)
    
    // If exception occurs here, resources leak
    if (someCondition) {
        throw new Error('Processing failed')
    }
    
    // Cleanup code may never execute
    fs.closeSync(fd)
    clearInterval(timer)
}

What is the feature you are proposing to solve the problem?

Add a built-in ResourceScope API that automatically cleans up registered resources when the scope is disposed, even during exception.

{
    using scope = new ResourceScope()
    
    // Auto cleanup well-known nodejs objects.

    let timer = setTimeout(() => console.log('tick'), 1000)  // auto clearTimeout
    let interval = setInterval(() => console.log('interval'), 500)  // auto clearInterval

    let fd = fs.openSync('file.txt', 'r')  // auto fs.closeSync
    let stream = fs.createReadStream('data.txt')  // auto stream.close()
    
    let server = http.createServer()  // auto server.close()
    let child = spawn('node', ['script.js'])  // auto child.kill()
}

What alternatives have you considered?

import { ResourceScope } from 'node:resource'

function processFile(filename) {
    using scope = new ResourceScope()
    
    let fd = scope.register(fs.openSync(filename, 'r'), fs.closeSync)
    let timer = scope.register(
        setInterval(() => console.log('processing'), 1000),
        clearInterval
    )
    
    // Process file...
    // Resources automatically cleaned up on scope exit
}

[jasnell]

Clarifying question: What's the difference between ResourceSource and DisposableStack?

[bakkot]

I gather the idea is that such built-in APIs would be modified so that they'd see if the call frame they were invoked has a ResourceScope declared and automatically add themselves, instead of the user needing to remember to do add using declaration or stack.use() call.

I don't think that's feasible given how JS works. It might technically be possible with some V8 wizardry but I think it's a pretty bad idea to introduce that much magic.

[jasnell]

Yeah, that's what I was assuming but didn't want to assume ;-) ... If that's the actual behavior being proposed here then I think I'm definitely -1. It's going to be rather error prone, I think.

[Renegade334]

Additionally, the bring-your-own-disposer approach (ie. the alternative example) already has built-in availability, via DisposableStack.prototype.adopt().

[polRk]

Thank you for the detailed proposal and discussion! The problem of resource leaks in Node.js due to unhandled exceptions or forgotten cleanup is indeed a critical issue, and exploring solutions like ResourceScope is valuable.

Difference Between ResourceScope and DisposableStack:

• DisposableStack requires explicit registration of resources and their cleanup functions (e.g., stack.use(resource, disposer)). This is reliable but shifts the burden to the developer to remember to register every resource.

• ResourceScope (as proposed) aims to automate cleanup for well-known Node.js resources (e.g., timers, file descriptors, streams) by integrating with their creation APIs. For example:

using scope = new ResourceScope();
const timer = setTimeout(...); // Automatically registered with `clearTimeout`
const fd = fs.openSync(...);   // Automatically registered with `fs.closeSync`

• This reduces human error but requires Node.js core to modify standard APIs (e.g., fs.openSync, setTimeout) to detect the active ResourceScope and auto-register resources.

Pros of ResourceScope:

• Reduces boilerplate for common resources.
• Mitigates human error (e.g., forgetting to call register).
• Aligns with modern JS patterns like async/await and structured concurrency.

Cons:

• Requires core API changes and potential performance overhead.
• May introduce edge cases (e.g., nested scopes, async cleanup order).

Implementation Feasibility

Regarding the "V8 wizardry" concern - this doesn't actually require deep engine changes. The implementation could work by:

• Node.js APIs checking for an active ResourceScope in the current execution context
• Using AsyncLocalStorage or similar mechanisms to track the active scope
• Standard library functions automatically registering themselves when a scope is active

Real-World Impact

Languages with automatic resource management (C#'s using, Python's with, Rust's RAII) have significantly fewer resource leak issues. The key insight is that the compiler/runtime handles it automatically - not the developer.

The manual approach with DisposableStack is certainly better than nothing, but it doesn't solve the fundamental problem of human error in resource management.

[ljharb]

That explicitness is intentional and much preferred - explicit > implicit, in all things.

Separately, it's not possible for anyone but the language itself to implicitly read everything in scope, so it's simply not technically possible for node to solve this. You'd need to make a JS language proposal, but given the discussion during using, I suspect the committee will continue to be opposed to this kind of "magic"/implicit registration.

[polRk]

@ljharb

1. The explicit scope creation here is explicit — the user knows what they're doing and why.
2. I don't think it's impossible: features like async context and async storage were added and work fine. If there is enough interest, something similar could be made.

[ljharb]

@polRk right, but only the language can "know" things about the scope. node can't implement anything like that.

As for AsyncContext, it's not using lexical scopes, it's using function scopes, so that's different.

[github-actions]

There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-stale Mark issue so that it is never considered stale label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.

[github-actions]

There has been no activity on this feature request and it is being closed. If you feel closing this issue is not the right thing to do, please leave a comment.

For more information on how the project manages feature requests, please consult the feature request management document.