Split overloaded 'use' method into multiple methods.

[rbuckton]

Per the September 2022 plenary discussion, the DisposableStack.prototype.use method should not be overloaded and instead split into multiple methods:

• use(disposable) to add a disposable resource to be disposed when the stack is disposed.
• adopt(value, onDispose) to add a non-disposable resource (value), such that onDispose(value) is called when the stack is disposed.
• defer(onDispose) to add a callback to execute when the stack is disposed.

[ljharb]

so "adopt" is like "use and defer"?

[bakkot]

adopt doesn't call the Symbol.dispose method on its first argument, whereas use would, so it is not quite like "use and defer".

[ljharb]

hmm - so is adopt(x, y) just defer(y => x(y))?

[bakkot]

Not quite: adopt returns its first argument.

I had the same question on Wednesday, and if I understood @rbuckton correctly, it's intended for cases like this

let resource = stack.adopt(getResource(), handleResourceDisposal);

Rewriting that to use defer would require

let resource = getResource();
stack.defer(() => handleResourceDisposal(resource));

which has the problem that there is now a place you can insert code between where the resource is acquired and the place where it is registered for disposal (i.e. between the first and the second lines). Using adopt avoids that risk.

[ljharb]

defer(y => { x(y); return y; }) then? Maybe I'm still not understanding.

[bakkot]

The argument to defer isn't invoked until scope exit, so no, not like that.

[ljharb]

ahhh i see, because it allows "defer" but with eager evaluation of the expression. thanks.

[bakkot]

Yeah.

Also, to be clear, the function passed to defer isn't passed any arguments: in your defer(y => x(y)) , snippet, y is always going to be undefined.

[rbuckton]

• use(value) registers a disposable and returns value.
• adopt(value, onDispose) registers something like { [Symbol.dispose]() { onDispose(value); } }, and returns value.
• defer(onDispose) registers something like { [Symbol.dispose]() { onDispose(); } }, and returns undefined.

[ljharb]

Ok, so why isn’t defer and adopt the same method, with the value as a second optional argument?

[rbuckton]

Ok, so why isn’t defer and adopt the same method, with the value as a second optional argument?

For several reasons:

• defer(onDispose, value?) feels too reminiscent of filter(callback, thisArg?), and I'd rather not confuse users.
• Having the callback last is reminiscent of NodeJS's continuation-passing style.
• adopt(value, v => v.close()) works better for type inference purposes since the type of v can be determined from the type of value; the other way around requires you to write defer(v => |, value) first and then jump back to | to get completions.

[ljharb]

I don't agree with the first point at all - there's tons of APIs, array or not, that aren't filter that don't take an optional thisArg (reduce, split, join, etc), nor do I see a problem with the second - this isn't a continuation, it's basically an event handler. I'm also not persuaded by type inference arguments.

It seems silly to me to have two separate methods (even if they had names that actually seemed related, and that actually conveyed what they do, which "defer" kind of does but "adopt" doesn't at all) when the only difference is the value argument's presence.

[rbuckton]

It seems silly to me to have two separate methods (even if they had names that actually seemed related, and that actually conveyed what they do, which "defer" kind of does but "adopt" doesn't at all) when the only difference is the value argument's presence.

It seemed silly to me to have three, which is why they were overloaded. Regardless, I'm not in favor of (callback, value?) because of the mess it causes for inference when using an editor with type information (be that TS or JSDoc types). reduce is a perfect example of the issue with inference:

["a", "b", "c"].reduce((memo, value) => ¦

As you type and reach the ¦ a type system would infer memo to be a string. But if you're planning to aggregate it into a Map it won't infer that type until you write the rest of the call:

["a", "b", "c"].reduce((memo, value) => ¦, new Map())

split and join are poor examples as they don't accept callbacks. There are many built-ins that do take callbacks, and the majority take the callback last:

• new Proxy(obj, handlers) (the handlers are essentially a collection of callbacks)
• JSON.parse(text, reviver)
• JSON.stringify(value, replacer)
• Array.from(items, mapfn) (if you ignore the thisArg)

Aside from reduce/reduceRight, the only other functions in the standard library that take a value following the callback take a thisArg (map, filter, find, etc.).

[ljharb]

If you're making a consistency argument, then the thisArg pattern is exactly what you'd want to follow. I don't think a type inference argument should be valid since ecmascript doesn't have types in that sense - if that mattered, the order of import/from would have been reversed, and a precedent might have existed to follow. I understand the issue with inference, I'm saying that may be an unavoidable cost.