@Semigradsky what are you thoughts about this suggested change?

Since these globals are only available at runtime when the --experimental-webstorage is passed, I'd say it's confusing to provide them without needing runtime checks.

The convention within @types/node (mostly) is not to type features that live behind flags as possibly undefined.

Not only does this force type checking/assertions on projects that know their own build environment, but for global variables, it's just incorrect: it's not the case that the variable is potentially undefined, it's that it potentially doesn't exist, and those are not equivalent.

declare var localStorage: Storage | undefined;

// TypeScript tells me I should check that this isn't undefined...
if (localStorage) {
  localStorage.clear();
}

The TypeScript compiler is perfectly happy here, which makes it a rather jarring experience when you run this and encounter Uncaught ReferenceError: localStorage is not defined.

Ophf 🤔 You're right. That case is not covered. I wondered if using never would be better, but it doesn't seem to be the case.

At the very least, this could have an experimental tag? Not that I'd expect great IDE support for highlighting that 😔

One thing to note is that you still need to end up in a position where loading the Node types and the DOM types together doesn't fall over; DT should be testing that already, and I would suspect that adding | undefined would probably cause errors.

Another alternative to keep things sane around types for experimental features would be to separate these experimental types into a separate file, such that users can opt into the feature via a simple top-level import:

import type "node/experimental-webstorage";

Is that something which has been discussed already?

I don't think it's a good idea to introduce imports which would crash at runtime; there's no way to enforce that an import is only used as a type import.

IMO this seems like a lot of work for not too much benefit; I'll note that the DOM types have some cases like this already for features that are only enabled in secure contexts, and those aren't even experimental.

I don't think it's a good idea to introduce imports which would crash at runtime;

I agree and that's the point of my initial comment. In its current form the localStorage is declared while most likely not even defined, resulting in the Uncaught ReferenceError: localStorage is not defined for the average user, as @Renegade334 mentioned above. Putting this in a separate file, users would at least have to opt-into getting these experimental types declared on the global namespace.

Should these use the DOM types if available?

Storage is interface, it extends existing DOM type if available.