Need comprehensive review of why libraries use .call/.bind/.apply

[theScottyJam]

This proposal's README states the reason we need this bind operator is because:

.bind, .call, and .apply are very useful and very common in JavaScript codebases.
But .bind, .call, and .apply are clunky and unergonomic.

It goes on to do an excellent job at explaining both of these points.

I was curious as to the reason why the .bind() family of functions was used so often, so I decided to look into each example the proposal presented to figure out why the code authors chose to use a bind function there. Here's my findings:

---

Update: To preserve context for what I'm talking about, here's the code snippets from the README I was originally referring to. It's comparing how current code looks like, and how it would look like if it used the proposed bind syntax.

// kind-of@6.0.2/index.js
type = toString.call(val);
type = val::toString();

// debug@4.1.1/src/common.js
match = formatter.call(self, val);
match = self::formatter(val);

createDebug.formatArgs.call(self, args);
self::(createDebug.formatArgs)(args);

// readable-stream@3.4.0/errors-browser.js
return _Base.call(this, getMessage(arg1, arg2, arg3)) || this;
return this::_Base(getMessage(arg1, arg2, arg3)) || this;

// readable-stream@3.4.0/lib/_stream_readable.js
var res = Stream.prototype.on.call(this, ev, fn);
var res = this::(Stream.prototype.on)(ev, fn);

var res = Stream.prototype.removeAllListeners.apply(this, arguments);
var res = this::(Stream.prototype.removeAllListeners)(...arguments);

// yargs@13.2.4/lib/middleware.js
Array.prototype.push.apply(globalMiddleware, callback)
globalMiddleware::(Array.prototype.push)(...callback)

// yargs@13.2.4/lib/command.js
[].push.apply(positionalKeys, parsed.aliases[key])
positionalKeys::([].push)(parsed.aliases[key])

// pretty-format@24.8.0/build-es5/index.js
var code = fn.apply(colorConvert, arguments);
var code = colorConvert::fn(...arguments);

// q@1.5.1/q.js
return value.apply(thisp, args);
return thisp::value(...args);

// rxjs@6.5.2/src/internal/operators/every.ts
result = this.predicate.call(this.thisArg, value, this.index++, this.source);
result = this.thisArg::(this.predicate)(value, this.index++, this.source);

// bluebird@3.5.5/js/release/synchronous_inspection.js
return isPending.call(this._target());
return this._target()::isPending();

var matchesPredicate = tryCatch(item).call(boundTo, e);
var matchesPredicate = boundTo::(tryCatch(item))(e);

// graceful-fs@4.1.15/polyfills.js
return fs$read.call(fs, fd, buffer, offset, length, position, callback)
return fs::fs$read(fd, buffer, offset, length, position, callback)

The "kind-of" package uses .call() because they want to call Object.prototype.toString() on a passed-in object, and they're following the good practice of not trusting that .toString() will be present and well-behaved on the passed-in object (e.g. the object could have a null prototype).

There were two examples of .call() from the "debug" package. In both scenarios, they're binding "this" to a custom object, in order to provide additional context for that function. In the first scenario, they're binding "this" while calling a user-provided function - this seems to be an undocumented feature. In the second scenario, they're only binding "this" to internal callbacks.

The "readable-stream"'s usage of .call() is actually pretty irrelevant to this proposal. It's the result of a babel transformation, turning class syntax with super calls into functions and prototypes, with .call() being used to help emulate super().

The "yargs" package was just trying to do what we can do today with the spread operator. The code must have been written before the spread operator existed.

It was a little difficult to follow the pretty-format's code. if anyone else wants to give it a shot, feel free. I think ultimately they were trying to do a form of method extraction from one of their third-party libraries, but they were binding the "this" value at a different location from where they were extracting the methods. From my initial impression, it looked like they might even be binding the wrong "this" value to these methods, but the third-party library didn't care, because the third-party library doesn't actually use "this" anywhere in its source code (it was a smaller library, and a grep for "this" returned zero results). I suspect I'm just misinterpreting what was going on, but maybe not.

The "Q" package uses .apply() as part of some internal logic, which seems to mainly be used by publicly exposed functions such as promise.fapply(), promise.fcall(), and promise.fbind(). Ultimately the purpose is to mimic javascript's bind functions, but with some async logic added to them.

In the case of rxjs, they're exposing functions that accept a callback argument, and an optional this-value that will be applied to the supplied callback when it's called. This is mimicking built-in functions like Array.prototype.map(), which also accept both a callback and an optional "this" parameter.

Bluebird was using .call() for two different reasons. In the first scenario, they were wanting to define similar methods on two different classes. They did so by defining them all on one class, then creating a bunch of tiny, one-line methods on the other class that basically did FirstClass.prototype.call(specialThisValue, ...args). Basically, they were using .call() for code reuse purposes. In the second scenario, .call() is being used because they expose their own promise.bind() function, which accepts a "this" value, then applies that "this" to every callback in the promise chain. Part of the reason for this behavior is to allow the end user to keep state around between callbacks by mutating "this". See here for their rational behind this feature.

graceful-fs was simply a case of method extraction. They pulled off fs.read, and instead of binding it on the spot, they supplied the correct "this" value via .call() later on.

---

Ok, I think that's a good sample-size of many different possible use cases for bind functions. I'm going to go ahead and categorize these use cases, so that we can discuss the value a bind syntax provides to these general categories.

Irrelevant

• Readable-stream's use case is irrelevant to this proposal simply because it's not possible to add a new feature to improve the quality of transpiled code. By definition, transpiled code can't use new features.
• Yargs's use case is irrelevant because that code snippet can already be greatly improved by simply using the spread operator.

Customizing the "this" value of callbacks

Both bluebird's second example and the debug package use .call() to customize the "this" value of callbacks. In general, I think a good rule of thumb to follow is "prefer providing explicit parameters over custom, implicit 'this' parameters". In other words, it's generally better to just pass a context object to a callback instead of trying to conveniently set it's "this" value to this context object.

I'm not saying it's always bad to customize the "this" value of callbacks, I'm just saying we probably shouldn't encourage this kind of behavior, which means I would be against adding a bind syntax if this was the only use case for it.

protection from global mutations

This category wasn't found in any of the examples above, but it's still worth discussing. As shown in the README, node has a lot of code that uses .bind() type functions to protect against mutation of global properties. This is a fair point, and a valid use case for this proposal, but it can't be the only driving force. As discussed here, it seems this proposal can't feed off of "global mutation protection" alone, it needs stronger reasons to exist.

Mimicking existing language semantics

Both Q and rxjs mimic existing language semantics related to this-binding. Q provides .apply()/.call()/.bind() equivalents for promises and rxjs provides a parameter to set the "this" value of a callback.

These types of features are only useful if the end user finds it useful to bind custom this values to their callbacks, which is the type of thing we're trying to discuss right now. Perhaps, there's really not a big need for these features, and the API authors didn't really need to include them. But, then again, perhaps there are good use cases, so lets keep exploring.

Language workarounds

It seems a couple of the packages were using .call() simply because the language itself didn't provide what they needed in a direct way.

• kind-of simply needed to stringify an unknown object. This is currently not possible without .call().
• Bluebird was using .call() for code reuse purposes - they wanted to use the logic found within one method inside a method of a different class, so they did so by simply supplying using .call() with a custom "this" value. This particular solution seems to be pretty unidiomatic - if they ever switched to class syntax and private state, they would find that they couldn't keep using this code-reuse pattern. Perhaps there's better solutions to their problems that are more idiomatic that can be done in JavaScript today, or maybe in some future version of JavaScript after features have been added to help them in their use case.

For items that fall into this category, it's probably best to analyze each situation independently and figure out what really needs to be added to the language. Sure, a this-binding shorthand could provide some minor benefits to the readability of these workarounds, but what they really need is a way to do what they're trying to do without resorting to funky workarounds. We're already actively fixing a number of problems in this category, for example, there's the mixin proposal, and there's also the recently added Object.hasOwn() function which is basically a more direct way of doing Object.prototype.hasOwnProperty.call().

Method extraction

Both pretty-format and graceful-fs are basically doing a form a method extraction, except in both cases they're choosing to supply the "this" value at the call location instead of the extract location.

This proposal stated that it doesn't wish to focus on method extraction, but ironically, I think this use case might be the most important one among the ones that have been analyzed.

Others?

Looking at the above categories of use cases, it seems that many uses of .call()/.bind()/.apply() don't actually benefit much from a this-binding syntax, however, what's been presented is not an exhaustive list of possible use cases. So I want to pose the following question:

What specific uses of .call()/.bind()/.apply() does this proposal hope to help out with? Are there use cases beyond the ones listed above that this proposal seeks to make more user-friendly? If so, what are they? This might be a good thing to eventually document in the README as well. The README explains clearly that .call() gets used everywhere, but it doesn't dig deeper to find out why it's getting used all over the place - I think those underlying use cases are the real gold mine we're trying to hit. The uses of ".call()" seems to more-often-than-not be a symptom of a deeper problem that needs addressing.

[js-choi]

Excellent review.

Good catch on readable-stream; I should have recognized what was going on. Although Gzemnid does not usually include transpiled build code in its dataset, it cannot distinguish code that was transpiled in the past and then subsequently used as base source code, as what appears to be happening with readable-stream.

---

The original use case was motivated by @ljharb’s desire for syntax to change the this receiver of functions—he manages call-bind and the many polyfills that depend on it for protection from prototype pollution and other global mutation. He is also involved in Node, which as you may know uses an elaborate primordials system, also for protection from global mutation.

But based on feedback from some TC39 representatives (see #6 (comment), #8, and some discussion on Matrix), I had become a little reluctant to emphasize specific use cases. I’m afraid that associating this proposal with certain use cases—such as individually importable, tree-shakable “extension methods” or the security use case—would make several representatives colder toward this proposal. Instead, I have tried to focus attention on the sheer magnitude of general bind/call/apply usage, while keeping in mind their clunkiness.

Having said that, you are right: in order to strengthen the proposal, we must investigate specifically why libraries (and in particular the most popular libraries) use bind/call/apply. And we have to take any historical use of apply with healthy skepticism, of course, because spread syntax now exists. So we should do an analysis over as much of the open-source JavaScript corpus as possible, like in tc39/proposal-change-array-by-copy#37.

---

So next actionable items I see:

• Remove examples from readable-stream and yargs.
• Review Gzemnid’s text dumps for patterns in why libraries specifically use call etc.
• Maybe write a paragraph or two summarizing these patterns.
• Add a warning about .apply’s statistics—or maybe even remove mentions of .apply altogether.

I invite you to download and run the Gzemnid dataset and script yourself.
I’ve also dumped the first 10,000 lines of the .call results, sorted by library popularity, in a Gist.
I’d love your further help in exploring and strengthening this proposal’s use cases based on these real-world data. We’re all volunteers here, after all.

Thanks again for the excellent review.

[theScottyJam]

Yeah, I'll scour around and see what other use cases I can find 👍️

[ljharb]

it's generally better to just pass a context object to a callback instead of trying to conveniently set it's "this" value to this context object.

This is a highly subjective opinion; one that jQuery (arguably the most popular JS library ever) uses heavily; and community opinion on things like this has shifted over time. I don't think it's the committee's place to pass judgement on the use of a fundamental pattern of the language, especially one that every prototype method relies on.

[js-choi]

Both pretty-format and graceful-fs are basically doing a form a method extraction, except in both cases they're choosing to supply the "this" value at the call location instead of the extract location.

This proposal stated that it doesn't wish to focus on method extraction, but ironically, I think this use case might be the most important one among the ones that have been analyzed.

I also want to make it clear that I do consider method extraction (along with the calling of extracted methods) to be a core use case of this proposal. For example, method extraction is essential for security from prototype pollution and other global mutation.

The non-goal of this proposal is what I currently call “tacit” method extraction: a term I made up to refer to when a method is implicitly bound to its original owner, creating a bound function.

// “Explicit” method extraction results in a `this`-dependent ordinary function.
// This is handled by this proposal.
const { slice } = arr;
// The `this` value is supplied in the call.
arr::slice(...args);

// “Tacit” method extraction results in a `this`-independent bound function.
const slice = arr&.slice;
// The `this` value is not supplied in the call, because the function is bound.
slice(...args);

I think these two concepts could use better names. I opened #13 about this.

[js-choi]

For what it’s worth, there are some matching lines in the top-1000-packages dataset that come from various packages’ standalone.js files, but these lines seem to be not very significant in number. For example, there are 745 .calls in standalone.js files, and there are 93 console.logs in standalone.js files. (Compare to 500084 .calls and 271915 console.logs among all files.)

> ./search.topcode.sh '.call' | awk '/standalone.js/' | awk 'END { print NR }'
745
> ./search.topcode.sh 'console.log' | awk '/standalone.js/' | awk 'END { print NR }'
93

To be clear, Gzemnid only includes code added to Git repositories. No transpiled code is included unless it is manually added to the repository. It doesn’t seem like Git-managed standalone.js files are a significant contributor to any of these numbers.

---

There also appear to be 53667 instances of .calls on a super-like object, such as in RxJS:

> ./search.topcode.sh '.call\b' | awk '/super/' | awk 'END { print NR }'
53667

These constitute about 10.7% of all .calls in this dataset, which is more significant but still vastly outnumbered by other uses.

[theScottyJam]

@js-choi - thanks for the clarification on tactic method extraction, that makes sense.

@ljharb - to clarify, I was just talking about callbacks passed to a function, not methods on a prototype, and I wasn't claiming that it's wrong to bind custom "this" value to callbacks. I think there are numerous good, proper use cases for doing so. I've seen plenty of libraries do it for good, valid reasons.

However, I do stand by my opinion that when you're uncertain what to do, it's better to air on the side of explicit parameters over implicit ones. People generally do this naturally - when you use array.map(), you can access the index and original array parameters by simply accepting more parameters. It could have been designed such that you access those values via this.index and this.originalArray, but it wasn't, and for good reason too. The language designers aired on the side of explicit parameters.

If customizing the "this" on callbacks to provide extra context is the only other, good valid use case, and this syntax is provided primarily to support it, then the committee is in fact passing judgment on this use case. They're blessing it with special syntax, telling the world that they want to see more of this done, to the point that they're even willing to provide special syntax to help out.

Now, I don't believe this use case is the only valid one. But, my objective here is to try and decompose the usages of .call/.bind/.apply to their different use cases and see how a bind operator can help each one of them. This means that, yes, we'd need to analyze each use case in isolation and see if it's really a use case we with to promote or not. If we do want to promote it, how much? How much weight do we give to each use case?

Once we've distilled what we see to a list of use cases we want to promote, then we can focus on how to best support these use cases. For example, if we find that 99% of the time people really just want tactic method extraction, then maybe we need to change the focus of this proposal a bit. Or, if we find that 99% of the time people want to supply an implicit "this" paramter to callbacks, and the committee is willing to promote that idea, then maybe the .call() syntax I proposed in #3 of fn@(customThis, arg1, arg2) would arguably be more appropriate, as this use case isn't about trying to supply the correct instance to a method, rather, it's just trying to supply an implicit context argument, something which the .call() syntax better represents.

[ljharb]

I don’t know how it could possibly have been designed that way; mutating the array to provide that info wouldn’t have ever been viable.

[ljharb]

To be clear, this is not a “context”, it’s a receiver. Context can imply access to scoping information, or things based on an environment - it’s one purpose of the receiver, but not the generic term or the universal purpose.

My understanding is that a receiver is a concept from smalltalk, where it represents the object that the a message (that the function represents) is being sent to.

The .call API does not represent providing a receiver well, and never has, precisely because everyone is familiar with a.b(), so they expect the receiver to come first, to the left of the function name. For a calling syntax to be ergonomic, it has to beat .call, which means it must have the receiver come first.

[js-choi]

For what it’s worth, I’m still trying to focus attention on the sheer magnitude of general bind/call/apply usage, rather than specific use cases.

People seem to rebind this for various reasons. Some libraries like jQuery store information in this. Some libraries use this in order to have their functions mimic existing language semantics. Some libraries cache this-using method functions for protection from global mutation.

But whatever the reasons, they are frequent, and they are clunky. A goal of this proposal is to improve the word order’s ergonomics: obj.fn(arg) and obj::fn(arg)—not obj.fn(arg) and the clunky fn.call(obj, arg).

I think the biggest valuable thing that this review is already giving us is making sure we don’t include any irrelevant examples, like readable-stream’s transpilation from super-using code. If we’re going to make an argument of frequency, then we had better make sure that frequency does not include irrelevant cases (e.g., excluding lines containing super-like identifiers)…while pointing at the remaining large numbers.)

At least, that’s my current approach.