Capabilities instead of divergences?

[mcollina]

In https://github.com/littledan/js-shared-interfaces/blob/master/DIVERGENCES.md, we just list the divergences without getting into a lot of details. Some of those divergences are the result of bad coordination. Some of those divergences are far more fundamental and are related to

I think it would be important to understand and document why there are certain divergences, and to what capability of the runtime they map to. I think the term "Divergences" is a negative, while "Capability map" is a more neutral term, and we should document the differences, not expressing a judgement.

As an example, https://github.com/littledan/js-shared-interfaces/blob/master/DIVERGENCES.md#http-access compares fetch to require('http').request. However the two have very different capabilities and requirements in terms of caching, security and connection reuse. They are not a 1-1 map.

I think something that we should create is a Capability map, and explain why fetch() is hard to implement in Node.js and why require('http').request is impossible to implement in a browser. fetch() is a high-level utility that provide cached, secured http request capability in the browser. require('http').request provides low-level, uncached and unsecured http request capability in Node.js. Having a single, per-process HTTP cache in Node.js is not in the scope of the project.

Another example is that Node.js do not have a builtin DOM.

---

Note that there are some of the listed divergences that do not map to any underlining or required capability, and they are just the result of bad coordination or prior art. Those typically could be solved.

[littledan]

This is a great idea. How about another document in this repo? We can scope DIVERGENCES down to the "miscoordination" cases.

[littledan]

Well, on a second read, I'm not sure how we should treat cases like fetch neutrally. Putting it in either of those two phrasings implies an answer, where the goal should really be to facilitate a conversation. What if we had DIVERGENCES and CAPABILITIES documents, included fetch in neither of them, and used an issue to discuss things?

[mcollina]

I think CAPABILITIES should be listing things like "file system access", or "http requests", "http caching", "ability to parse and process HTML", "Having access to low-level sensors/hw". Those then could be used to explain certain differences between the platforms.

Let's consider the fetch example.
A browser do not offer "unlimited network access" as a capability for security reason, Node.js does because it has a different threat model. A browser needs the CORS capability to protect its user, Node.js does not because it has no concept of origin.

fetch requires "CORS capability", "HTTP cache capability", "HTTP parsing/producing"
require('http').request requires "unlimited network access", "HTTP parsing/producing", "Low-level connection management" (agent/pool model)
require('http2').connect requires "unlimited control over HTTP2 streams", which is not part of the web standards.

This type of map can help in identifying areas of overlap and/if a lower-level primitive can be shared.

---

As another example, EventTarget is spec'ed inside the DOM document, and it refers to a lot of DOM constructs in the spec for the required Event object. That is very hard to match in an environment that it does not have a DOM.