Typescript errors related to when not conforming to the Promise standard

[hpinkos]

Our documentation for functions like KmlDataSource.load says it returns a Promise
https://cesium.com/docs/cesiumjs-ref-doc/KmlDataSource.html?classFilter=kmldata#.load

However, when promises don't conform to the browser Promise standard, so using otherwise and finally on these promises causes Typescript to think there's an error when there isn't one.

Do we need to create a typedef for when promises until we can replace then with native promises? (cc #8525)

[thw0rted]

The existing typings for when export a Promise interface which you can use. I started to put together a PR for this but ran into a couple of issues.

Simply adding a devDependency on @types/when applies type information for the bare module specifier "when", i.e. import when from "when". But Matt's overhaul to ES6 imports did not use any bare module specifiers -- everything is still relative paths, and library code is still loaded with e.g. import when from "../ThirdParty/when.js". I didn't want to just replace these imports since I don't know why it's done this way, though of course I'd make a strong argument in favor of nuking ThirdParty and using modern NPM deps instead. This would allow you to use the types from DefinitelyTyped directly.

For Typescript purposes only, you could reference these types with @returns {import("when").Promise}, but until jsdoc/jsdoc#1645 is resolved this will cause a parsing error for vanilla JSDoc. (I actually don't see a path forward for that, because in your case there isn't even a real "when" bare module to consult, it's a fictional construct defined by Typescript-only mechanisms.)

The practical upshot is that you have a few choices:

• Scrap ThirdParty and use Node module resolution for library imports, import when from "when". Including a devDependency on @types/when will correctly type when.Promise so you can use that in your return declaration.
• Use the TS-specific @returns {import("when").Promise} syntax and try to make JSDoc work around it. I can't figure out how to do this and am not sure it's actually possible.
• Modify your ThirdParty version of when to export its existing Promise interface and reference that. (I don't have enough experience with vanilla JSDoc to know how myself -- I think the JSDoc in that file is broken?)

[thw0rted]

Hi @hpinkos , I came across this while searching for other KML issues, and realized that maybe it's OBE now that you're switching to native Promises everywhere, in which case you'd appreciate a poke so this can be closed out. (If I'm wrong, ignore me.)

[hpinkos]

Yep, makes sense to me. Thanks for the heads up!