[jasnell]

Stemming from discussions in #58516 , this seeks to add guidance for introducing explicit resource management support into existing Node.js APIs. This is mean to be discussed and evolved so please weigh in.

/cc @nodejs/tsc @nodejs/collaborators @bakkot

[nodejs-github-bot]

Review requested:

• @nodejs/tsc

[Renegade334]

Looks good on the whole, but it's worth pointing out that the role of disposability as stated here – basically a "sweeper" that avoids having to manually perform any last-ditch teardown (such as would occur in a finally block), but which still puts the onus on the user to explicitly invoke graceful disposal under normal execution – doesn't tally with the indicative cases from the tc39 proposal, which imply an environment wherein one doesn't need to explicitly close one's own disposable resources at all, and can just defer to the ERM disposer under both normal and abnormal conditions.

I don't have any strong feelings here, but probably warrants discussion.

@Renegade334 I think the way I would put it is that very few resources care about whether you are cleaning up because of a thrown exception or not. Those which do require special handling, but it's not something most APIs should need to think about.

Unless I missed it, this document doesn't really cover creating handles like in #58453, i.e. these:

  return {
    [SymbolDispose]: () => this.removeListener(type, listener),
  };

Since we don't have using void yet and disposables are not always grouped by DisposableStacks, these objects usually will be exposed in userspace and have some user-defined names.
Should such objects be just this? Maybe they should be instances of some DisposableEntity class, implementing disposable interface? Or maybe they should be null-prototyped? Or maybe they should have Symbol.toPrimitive or kInspect that would help identifying what this object is? Or we should also add non-symbol dispose function (if so, we probably should come up with a generic name for all such objects)?

Should such objects be just this? Maybe they should be instances of some DisposableEntity class, implementing disposable interface?

Personally I am happy with anonymous objects.

Or maybe they should be null-prototyped?

Don't see any reason for this - null prototypes make sense when you might have unknown keys (like groupBy or parseArgs), or more rarely when it's important that users be able to rely on absence of properties which might be inherited from Object.prototype in the presence of malicious code, but neither is the case here.

Or maybe they should have Symbol.toPrimitive or kInspect that would help identifying what this object is?

Definitely not toPrimitive; almost nothing should have toPrimitive except like Date. They could have a toStringTag or a kInspect, maybe, but only if you'd do that with every other kind of object.

Or we should also add non-symbol dispose function (if so, we probably should come up with a generic name for all such objects)?

I do think there should be a string named dispose function. I don't think it should have a generic name - the disposal action is fundamentally different for different kinds of things (sometimes it's close, sometimes it's release, sometimes it's remove, whatever). The name should be chosen to be informative to the reader.

Note: following the discussion at #58526 (comment), the filename still stands at erm-guidelines.md, which may hinder accessibility.

This document is very informative. Excited to see more of this implemented throughout core

I'll give this a couple more days for feedback. If there are no unresolved comments by end of the day Thursday, I will get this merged.

lgtm but you might want to consider changing the setTimeout examples.

A few final copyedits and minor suggestions.

Looks good in general, certainly as a base to iterate on with experience. I do think that attempting graceful disposal in a could-have-errored context isn't necessarily as scary as these guidelines currently make out, but I imagine that more familiarity will lend a better sense of which paradigm is more useful.

Minor stuff

After rereading the whole thing, a few more suggestions below.

Additionally, I think this document should cover two more things:

1. According to the description of the Disposable Interface, ERM disposer should return undefined, and async disposer should return a Promise that resolves with undefined. So, roughly speaking,

[SymbolDispose]() {
-  return this.dispose();
-  return this;
-  return this.#statusCode;
-  return true;
+  return void this.dispose();
+  this.dispose();
+  return;
+  // no return
}

2. To improve debugging experience, [Symbol.dispose] function must not be a direct alias of named disposer function. This way, it would be possible to actually tell from stack traces if we're dealing with using or conventional method.

- MyObject.prototype[SymbolDispose] = MyObject.prototype.dispose;
- MyObject.prototype[SymbolDispose] = MyObjectDisposeImpl;
- MyObject.prototype[SymbolDispose] = function dispose() { this.close(); }

+ MyObject.prototype[SymbolDispose] = assignFunctionName(SymbolDispose, function() {
+   this.idempotentDispose();
+ });

LGTM with suppressing the linter

Landed in ebe7dad