Type errors for `map.d.ts` when importing `typedoc` with TypeScript 5.6.3

[romaricpascal]

Search terms

TypeScript, Map, 5.6

Expected Behavior

import * as typedoc from 'typedoc' (or const typedoc = require('typedoc')) for accessing Typedoc's default options in order to add to them should not cause compilation errors with TypeScript 5.6.x

Actual Behavior

TypeScript raises the following errors:

node_modules/typedoc/dist/lib/utils/map.d.ts:19:5 - error TS2416: Property 'entries' in type 'StableKeyMap<K, V>' is not assignable to the same property in base type 'Map<K, V>'.
  Type '() => IterableIterator<[K, V]>' is not assignable to type '() => MapIterator<[K, V]>'.
    Type 'IterableIterator<[K, V]>' is missing the following properties from type 'MapIterator<[K, V]>': map, filter, take, drop, and 9 more.

19     entries(): IterableIterator<[K, V]>;
       ~~~~~~~

node_modules/typedoc/dist/lib/utils/map.d.ts:20:5 - error TS2416: Property 'keys' in type 'StableKeyMap<K, V>' is not assignable to the same property in base type 'Map<K, V>'.
  Type '() => IterableIterator<K>' is not assignable to type '() => MapIterator<K>'.
    Type 'IterableIterator<K>' is missing the following properties from type 'MapIterator<K>': map, filter, take, drop, and 9 more.

20     keys(): IterableIterator<K>;
       ~~~~

node_modules/typedoc/dist/lib/utils/map.d.ts:21:5 - error TS2416: Property 'values' in type 'StableKeyMap<K, V>' is not assignable to the same property in base type 'Map<K, V>'.
  Type '() => IterableIterator<V>' is not assignable to type '() => MapIterator<V>'.
    Type 'IterableIterator<V>' is missing the following properties from type 'MapIterator<V>': map, filter, take, drop, and 9 more.

21     values(): IterableIterator<V>;
       ~~~~~~

node_modules/typedoc/dist/lib/utils/map.d.ts:22:5 - error TS2416: Property '[Symbol.iterator]' in type 'StableKeyMap<K, V>' is not assignable to the same property in base type 'Map<K, V>'.
  Type '() => IterableIterator<[K, V]>' is not assignable to type '() => MapIterator<[K, V]>'.
    Type 'IterableIterator<[K, V]>' is missing the following properties from type 'MapIterator<[K, V]>': map, filter, take, drop, and 9 more.

22     [Symbol.iterator](): IterableIterator<[K, V]>;
       ~~~~~~~~~~~~~~~~~

Found 4 errors in the same file, starting at: node_modules/typedoc/dist/lib/utils/map.d.ts:19

This could be linked to this change from TypeScript ?

Steps to reproduce the bug

1. In a new folder, run npm install -D typescript typedoc
2. Create an index.ts file with import * as typedoc from 'typedoc';
3. Run npx tsc index.ts -target esnext --moduleResolution node --allowSyntheticDefaultImports (these are the minimal options to get only the errors in map.d.ts)

Environment

• Typedoc version: ^0.26.9
• TypeScript version: 5.6
• Node.js version: v20.18.0
• OS: macOS

[Gerrit0]

https://devblogs.microsoft.com/typescript/announcing-typescript-5-6/#iterator-helper-methods is the cause of this one. Unfortunately switching that return type will cause type errors for anyone using an older version of TS than 5.6, which is still new enough that I don't love making that change, at least without a 0.x release...

I recommend TypeScript's skipLibCheck option for now.

[rbuckton]

Quoting my comment from microsoft/TypeScript#60145:

It's generally a bad idea to use implements Map in user code unless you are writing a polyfill for Map. As evidenced by the recent additions to Set (https://github.com/tc39/proposal-set-methods) and the upcoming additions to Map (https://github.com/tc39/proposal-upsert), as well as the changes to built-in iterators (https://github.com/tc39/proposal-iterator-helpers), these types can change as ECMAScript evolves.

I would recommend removing implements Map from the definition of StableKeyMap.

[Gerrit0]

I hadn't even considered dropping the implements, that's obviously the right solution in hindsight.