Where's the motivation for adding DisposableStack and AsyncDisposableStack?

https://github.com/tc39/proposal-explicit-resource-management#assist-in-complex-construction. Large-scale projects will often create components that consume multiple resources, the lifetimes of which are bound to the lifetime of the component. In the simplest case, DisposableStack acts as a container for disposables: you can add one or more disposables to the stack, and they will be disposed in reverse order. In the more complex case, when you define a class that acquires multiple disposable resources in the constructor, you need to ensure that:

If no errors are thrown during construction, the container can be safely stored in a field on the class to be disposed later.
If any errors are thrown during construction, resources in the container are properly disposed.

Consider the PluginHost example in the explainer. Both the NodeProcessIpcChannelAdapter and NodePluginHostIpcSocket classes are disposables. You don't want to use using to declare them in the constructor, as their lifetime is intended to outlive the constructor:

class PluginHost {
  #channel;
  #socket;
  constructor() {
    using channel = new NodeProcessIpcChannelAdapter(process);
    using socket = new NodePluginHostIpcSocket(channel);
    // these get disposed as soon as the constructor exits, so assigning them here isn't very useful
    this.#channel = channel;
    this.#socket = socket;
  }
}

If using isn't sufficient here, we might try to track the lifetime manually:

class PluginHost {
  #channel;
  #socket;
  constructor() {
    this.#channel = new NodeProcessIpcChannelAdapter(process);
    this.#socket = new NodePluginHostIpcSocket(this.#channel);
  }
  [Symbol.dispose]() {
    this.#socket[Symbol.dispose]();
    this.#channel[Symbol.dispose]();
  }
}

But there are multiple issues here. If an exception occurs when creating #socket in the constructor, #channel won't be disposed. If an exception occurs when disposing of this.#socket in our dispose method, we also won't dispose this.#channel. So now we have to further complicate our constructor to handle all of these situations:

class PluginHost {
  #channel;
  #socket;
  constructor() {
    this.#channel = new NodeProcessIpcChannelAdapter(process);
    try {
      this.#socket = new NodePluginHostIpcSocket(this.#channel);
    } catch (e) {
      this.#channel[Symbol.dispose]();
      throw e;
    }
  }
  [Symbol.dispose]() {
    try {
      this.#socket[Symbol.dispose]();
    } finally {
      this.#channel[Symbol.dispose]();
    }
  }
}

This kind of boilerplate try..catch and try..finally logic is part of what using hopes to avoid. If we couple using with DisposableStack, we can dramatically simplify this code:

class PluginHost {
  #disposables;
  #channel;
  #socket;
  constructor() {
    using stack = new DisposableStack(); // this is guaranteed to dispose at end of block
    this.#channel = stack.use(new NodeProcessIpcChannelAdapter(process));
    this.#socket = stack.use(new NodePluginHostIpcSocket(this.#channel));
    this.#disposables = stack.move(); // move out of stack that will dispose now and into a stack we can dispose later
  }
  [Symbol.dispose]() {
    this.#disposables[Symbol.dispose]();
  }
}

In this example, we create a DisposableStack that remains local to the constructor, and is guaranteed to be disposed when the constructor exits. We can add each resource we successfully create to the stack, knowing that any exception will result in the stack and its contents being disposed. At the end of the constructor, we move all of the successfully created resources out of the local stack and into a longer-lived stack. This also means we have a much simpler [Symbol.dispose]() method that will handle resource cleanup in reverse order, as well as aggregation of exceptions.

Why is the DisposableStack.prototype.dispose auto-bound?

This was requested feature to better work with factory functions.

Do we really need species on these new constructors?

No. It's my understanding that many on the committee hope that species can eventually be removed, but until that occurs I felt it was best to specify it and possibly just remove it later if necessary.

Waldemar's previously raised concern about AggregateError flattening causing refactoring hazards still stands AFAICT. I agree with his concerns.

An alternative to AggregateError flattening would be to have a bunch of nested AggregateError instances with only one entry in errors:

try {
  using r1 = { [Symbol.dispose]() { throw new Error("c"); };
  using r2 = { [Symbol.dispose]() { throw new Error("b"); };
  throw new Error("a");
} catch (e) {
  e // AggregateError {
    //   cause: AggregateError {
    //     cause: Error { message: "a" },
    //     errors: [Error { message: "b" }]
    //   },
    //   errors: [Error { message: "c" }]
    // }
}

Or a new Error subclass (e.g., SuppressedError) that just has a cause and an error property. That's being discussed in #74, though IIRC @ljharb has favored just using AggregateError.

Stage 3 Specification Review: Shu-yu Guo #93

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions