Add proper localStorage availability checks to support Node v25 in @typescript/vfs

[yamcodes]

The package assumes it's running in a browser environment and directly calls localStorage.getItem("DEBUG"), however:, due to nodejs/node#57666:

Node.js <25: hasLocalStorage is false because localStorage is undefined, so the localStorage check is skipped entirely ✅
Node.js <=25: hasLocalStorage is true because localStorage exists, but it's a mock object that doesn't implement the full API ❌

So in Node.js 25, localStorage exists but localStorage.getItem is not a function.

Node <25, check if localStorage exists

Run:

node -e "console.log('localStorage exists:', typeof localStorage !== 'undefined'); console.log('localStorage type:', typeof localStorage); console.log('localStorage.getItem type:', typeof localStorage?.getItem);"

Prints:

localStorage exists: true
localStorage type: object
localStorage.getItem type: undefined
(node:30907) Warning: `--localstorage-file` was provided without a valid path
(Use `node --trace-warnings ...` to show where the warning was created)

Node 25, check if localStorage exists

Run:

node -e "console.log('localStorage exists:', typeof localStorage !== 'undefined'); console.log('localStorage type:', typeof localStorage); console.log('localStorage.getItem type:', typeof localStorage?.getItem);"

Prints:

localStorage exists: false
localStorage type: undefined
[eval]:1
console.log('localStorage exists:', typeof localStorage !== 'undefined'); console.log('localStorage type:', typeof localStorage); console.log('localStorage.getItem type:', typeof localStorage?.getItem);
                                                                                                                                                                                   ^

ReferenceError: localStorage is not defined
    at [eval]:1:180
    at runScriptInThisContext (node:internal/vm:219:10)
    at node:internal/process/execution:451:12
    at [eval]-wrapper:6:24
    at runScriptInContext (node:internal/process/execution:449:60)
    at evalFunction (node:internal/process/execution:283:30)
    at evalTypeScript (node:internal/process/execution:295:3)
    at node:internal/main/eval_string:71:3

This PR fixes it.

Closes #3449

[jakebailey]

This could be fine but requires a changeset to make a release. Run pnpm changeset and mark it as a patch release.

[jakebailey]

I somewhat expect that we need to detect this another way, though.

[yamcodes]

I somewhat expect that we need to detect this another way, though.

@jakebailey Sure! Let's analyze this.

Consider the following script.js:

console.log('localStorage type:', typeof localStorage);
console.log('localStorage value:', localStorage);
console.log('localStorage keys:', Object.keys(localStorage));
console.log('getItem type:', typeof localStorage.getItem);
console.log('instanceof Storage:', localStorage instanceof Storage);
console.log('prototype methods:', Object.getOwnPropertyNames(Object.getPrototypeOf(localStorage)));

try {
  localStorage.getItem('test');
  console.log('✅ Works');
} catch (e) {
  console.log('❌ Error:', e.message);
}

In Node 25,
We can run this script in two ways:

(1) node --localstorage-file=/tmp/test-storage script.js

localStorage type: object
localStorage value: Storage {}
localStorage keys: []
getItem type: function
instanceof Storage: true
prototype methods: [
  'length',
  'clear',
  'getItem',
  'key',
  'removeItem',
  'setItem',
  'constructor'
]
✅ Works

(2) node script.js

localStorage type: object
localStorage value: {}
localStorage keys: []
getItem type: undefined
instanceof Storage: false
prototype methods: [
  'constructor',
  '__defineGetter__',
  '__defineSetter__',
  'hasOwnProperty',
  '__lookupGetter__',
  '__lookupSetter__',
  'isPrototypeOf',
  'propertyIsEnumerable',
  'toString',
  'valueOf',
  '__proto__',
  'toLocaleString'
]
❌ Error: localStorage.getItem is not a function

Then, in Node 24 via node script.js:

localStorage type: undefined
/Users/yamcodes/code/test.js:7
console.log('localStorage value:', localStorage);
                                   ^

ReferenceError: localStorage is not defined
    at Object.<anonymous> (/Users/yamcodes/code/node.js:7:36)
    at Module._compile (node:internal/modules/cjs/loader:1760:14)
    at Object..js (node:internal/modules/cjs/loader:1893:10)
    at Module.load (node:internal/modules/cjs/loader:1480:32)
    at Module._load (node:internal/modules/cjs/loader:1299:12)
    at TracingChannel.traceSync (node:diagnostics_channel:328:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:244:24)
    at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
    at node:internal/main/run_main_module:33:47

Node.js v24.10.0

This proves that Node 25 introduces a case where localStorage can be a plain empty object! (API) With that in mind we can discuss some solutions.

In this PR I proposed directly checking for the existence of the getItem function right before we use it to access the debug flag. I can guess why you might have an issue with, because localStorage: LocalStorageLike | undefined "lies" to us in that it tells us that it cannot be an empty object. Also, arguably, hasLocalStorage should be false in this case too.

I can think of a few solutions.

1. An inherent fix by checking if the object is of the Storage instance using instanceof:

interface LocalStorageLike {
	getItem(key: string): string | null;
	setItem(key: string, value: string): void;
	removeItem(key: string): void;
}

declare var localStorage: LocalStorageLike | undefined;
declare var fetch: FetchLike | undefined;
declare var Storage: any;
let hasLocalStorage = false;
try {
	hasLocalStorage =
		typeof localStorage !== `undefined` &&
		typeof Storage !== `undefined` &&
		localStorage instanceof Storage;
} catch (error) {}

const hasProcess = typeof process !== `undefined`;
const shouldDebug =
	(hasLocalStorage && localStorage!.getItem("DEBUG")) ||
	(hasProcess && process.env.DEBUG);
const debugLog = shouldDebug
	? console.log
	: (_message?: any, ..._optionalParams: any[]) => "";

This works, but I'm not sure about BC (though I tested it in Node 24 and Node 25 with both flags, and it works in all cases). Also, my suggestion here is not the prettiest since it uses any and it also seemingly introduces some divergence and duplication against the existing LocalStorageLike model.

2. Making localStorage correct from the beginning by changing its type to:

declare var localStorage: LocalStorageLike | undefined | Record<string, never>;

This is a more fair type declaration in Node 25 because it considers the case the object can be empty.:

1. Node.js < 25: localStorage is undefined
2. Node.js 25 without flag: localStorage is {} (empty object with no methods)
3. Node.js 25 with flag: localStorage is proper LocalStorageLike implementation
4. Browser environments: localStorage is proper LocalStorageLike implementation

Then, we can either (2a) directly check for the function(s) we need inside the hasLocalStorage check:

let hasLocalStorage = false;
try {
	hasLocalStorage =
		typeof localStorage !== `undefined` &&
		typeof localStorage.getItem === `function`; // Potentially check for `setItem` and `removeItem` too
} catch (error) {}

I like this solution because it's as tight as we can get which makes it resilient.

However, if you want to avoid direct getItem checks and infer it instead, we can maybe (2b) check that localStorage is not a plain empty object, which if we trust the type means under process of elimination it must be a valid LocalStorageLike object;

let hasLocalStorage = false;
try {
	hasLocalStorage =
		typeof localStorage !== `undefined` && Object.getPrototypeOf(localStorage) !== Object.prototype;
} catch (error) {}

I'm leaning towards (2a) for the reasons stated above, which one sounds better to you?

[jakebailey]

Honestly, what you have in the PR already is probably fine. It just needs the changeset

[jakebailey]

Sigh, the inclusion of the changeset (even though I did that) makes the PR need a CLA due to modifying more than a single line

[yamcodes]

@microsoft-github-policy-service agree

[yamcodes]

Sigh, the inclusion of the changeset (even though I did that) makes the PR need a CLA due to modifying more than a single line

@jakebailey No worries, it's done! Thank you!!!