fix: add disposable methods for TypeScript 5.2 compatibility

[klappradla]

Hi 👋

First off, thanks for you work on this 🙇 It's making my life a lot easier 💜

I recently ran into a problem when updating JSDOM in my project, where the return type wasn't compatible any more:

error TS2322: Type 'typeof Headers$1' is not assignable to type '{ new
  (init?: HeadersInit | undefined): Headers; prototype: Headers; }'.
    The types returned by 'prototype.entries()' are incompatible between these types.
      Property '[Symbol.dispose]' is missing in type 'IterableIterator<[string, string]>' but
  required in type 'HeadersIterator<[string, string]>'.

  6 globalThis.Headers = HeadersPolyfill;
    ~~~~~~~~~~~~~~~~~~

    node_modules/typescript/lib/lib.esnext.disposable.d.ts:36:5
      36     [Symbol.dispose](): void;
             ~~~~~~~~~~~~~~~~~~~~~~~~~
      '[Symbol.dispose]' is declared here.

This PR fixes this and makes makes the polyfill compatible with TypeScript 5.2+ 🎉

Background

TypeScript 5.2 added [Symbol.dispose] to iterator types as part of the Explicit Resource Management proposal.
This property was missing in the polyfills iterators, making them incompatible with e.g. current JSDOM and TypeScript.

Change

This removes the explicit IterableIterator return type annotations from the entries(), keys() and values() generator functions in favor of the Generator type.

[kettanaito]

Hi, @klappradla. Thanks for working on this. This does fix the build, but we still need to implement Symbol.dispose and that's an interesting task. This is also a good time to mention that this project is discontinued and nobody should depend on it anymore. It's here only for extremely edge cases so old projects still running on Jest don't start failing.

I strongly encourage you to migrate away from using this library (and Jest, if you can).

[kettanaito]

Alright, so what makes those generators disposable is Node.js itself. No action needed on our end, only adjust the tests to assert on disposable objects in Node.js v24 and higher, where they were added.

[kettanaito]

Thanks!

[kettanaito]

Released: v5.0.0 🎉

This has been released in v5.0.0.

• 📄 Release notes
• 📦 View on npm

Get these changes by running the following command:

npm i headers-polyfill@latest

---

Predictable release automation by Release.

[klappradla]

Alright, so what makes those generators disposable is Node.js itself. No action needed on our end, only adjust the tests to assert on disposable objects in Node.js v24 and higher, where they were added.

Yes, that was my understanding as well! Sorry, could have written that in the PR description. Thanks for the updates and the quick response 🙏

This is also a good time to mention that this project is discontinued and nobody should depend on it anymore.

Sad but good to know, thanks also for that!