TS2416 with typescript 5.6 when using disposable lib

[jameslan]

🔎 Search Terms

disposable ts2416

🕗 Version & Regression Information

• This changed between versions 5.5 and 5.6
• This changed in commit or PR built-in iterators should be disposable #59633

⏯ Playground Link

No response

💻 Code

I am writing a typedoc plugin and needs to import typedoc, in its dist/lib/utils/map.d.ts(https://www.npmjs.com/package/typedoc?activeTab=code), it has the following declaration,

export declare class StableKeyMap<K extends {
    getStableKey(): string;
}, V> implements Map<K, V> {
    [Symbol.toStringTag]: string;
    private impl;
    get size(): number;
    set(key: K, value: V): this;
    get(key: K): V | undefined;
    has(key: K): boolean;
    clear(): void;
    delete(key: K): boolean;
    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
    entries(): IterableIterator<[K, V]>;
    keys(): IterableIterator<K>;
    values(): IterableIterator<V>;
    [Symbol.iterator](): IterableIterator<[K, V]>;
}

🙁 Actual behavior

There are several errors complaining incompatibility between IterableIterator and MapIterator, one of them is like,

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]>'.
    Property '[Symbol.dispose]' is missing in type 'IterableIterator<[K, V]>' but required in type 'MapIterator<[K, V]>'.

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

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

🙂 Expected behavior

typescript 5.5 and 5.4 pass transpilation smoothly.

Additional information about the issue

In the tsconfig.json, I enabled disposable lib otherwise it will complain about Symbol.disposable:

"lib": ["es2015", "dom", "esnext.disposable"],

[rbuckton]

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.

As we must update the lib types to support the evolution of the language, we must sometimes break compatibility from version to version. We have, on occasion, made features available in the language to assist with transitional changes from version to version, such as typesVersions, though typesVersions is a fairly manual process intended for library authors to ship alternate declarations for earlier versions of TypeScript.

In the case of typedoc, they may need to either use typesVersions or update their types to use a compatible return type, such as:

export declare class StableKeyMap<K extends {
    getStableKey(): string;
}, V> implements Map<K, V> {
    [Symbol.toStringTag]: string;
    private impl;
    get size(): number;
    set(key: K, value: V): this;
    get(key: K): V | undefined;
    has(key: K): boolean;
    clear(): void;
    delete(key: K): boolean;
    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
    entries(): ReturnType<Map<K, V>["entries"]>;
    keys(): ReturnType<Map<K, V>["keys"]>;
    values(): ReturnType<Map<K, V>["values"]>;
    [Symbol.iterator](): ReturnType<Map<K, V>[typeof Symbol.iterator]>;
}

In the meantime, you should be able to work around this issue by using "skipLibChecks": true in your tsconfig.json file.

[rbuckton]

You can also work around this by adding a module augmentation to your code that introduces overloads that make the type compatible:

declare module "typedoc/dist/lib/utils/map" {
    interface StableKeyMap<K extends { getStableKey(): string; }, V> {
        entries(): MapIterator<[K, V]>;
        keys(): MapIterator<K>;
        values(): MapIterator<V>;
        [Symbol.iterator](): MapIterator<[K, V]>;
    }
}

Take care, however, that these methods in StableKeyMap actually produce an iterator that has the appropriate Iterator helper methods and [Symbol.dispose](), or that you refrain from using these methods in your code.

[rbuckton]

It looks like this is being tracked by TypeStrong/typedoc#2747.