Why are dom and dom.iterable separate?

Question

In tsconfig.json you can define additional libs, that give you typings for HTML or DOM "libraries"(? I don't know the correct terminology).

I don't understand why dom and dom.iterable are separate. Were they defined in different ecma modules/versions? Can I use them safely?

Surculose

Answer 1

I suspect it's because iteration (iterables and iterators) weren't added to JavaScript until ES2015, long after TypeScript was well-established. When ES2015 was released, the JavaScript engines in many browsers didn't support iteration (yet),¹ and of course at the time Internet Explorer was still a...thing...that was never going to get new features. So some projects had to target environments that didn't have iteration, so the libs are separate.

Even here in 2022, IE survives in corporate and government installations (although thankfully that's finally changing), and some folks have to target their apps and pages to those environments, so they wouldn't want to use dom.iterable.

---

¹ ES2015 was the last version of the specification to include significant features that didn't already have implementations in the field. These days, the process that TC39 follows generally doesn't land features in the spec until there are (ideally) a couple of implementations of the feature shipping in the field. Instead, the proposal stays at Stage 3 until that happens, before being moved to Stage 4 by consensus at a TC39 meeting, being added to the editor's draft, and thus being in the next snapshot specification the following June.

Ridings

Okay, just so I have it right: because this is such a fundamental functionality (without general availability of browsers and engines when it was introduced), it was not added to the dom library. – Surculose

@ManuelMeister - That's my theory. Note that even today, some people have to target environments that don't have iterability (IE11 in big corporate/government deployments). – Ridings

Answer 2

I think worth mentioning. And for some of the people that may land here. And to bring some clarification around other lib options. As the same concept of separation is not applied.

Resume:

dom, dom.iterable are separate. The rest of the libs are inclusive. es2022 includes the rest of all es2022.* variants (except for full. es2022.full includes es2022 + others)

dom and dom.iterable

dom doesn't include dom.iterable. And here is why:

And as it can be shown here [lib.dom.iterable.d.ts#L37, lib.dom.d.ts#L2726] for example:

You can see the iterable extends the dom lib and add iterable implementation.

What about other libs

es2022, es2022.array, ....

The same concept doesn't apply. es2022 includes all the others as shown here:

lib.es2022.d.ts

es2022 file with stripped comments

/// <reference no-default-lib="true"/>


/// <reference lib="es2021" />
/// <reference lib="es2022.array" />
/// <reference lib="es2022.error" />
/// <reference lib="es2022.intl" />
/// <reference lib="es2022.object" />
/// <reference lib="es2022.sharedmemory" />
/// <reference lib="es2022.string" />

And the full version (es2022.full) does even more:

lib.es2022.full.d.ts

It does include even dom, dom.iterable, and more. Meaning if you use the full version. You don't need to include dom nor dom.iterable.

/// <reference no-default-lib="true"/>


/// <reference lib="es2022" />
/// <reference lib="dom" />
/// <reference lib="webworker.importscripts" />
/// <reference lib="scripthost" />
/// <reference lib="dom.iterable" />

Currency