[Typescript] Guidance on resolving a bug I raised in a JS library

I’m currently learning Typescript, and as an exercise, I’d like to help resolve an bug I raised for the php-reflection NPM package and I’m looking for some guidance in terms of good/correct design for Javascript/Typescript APIs.

php-reflection is a Javascript library that provides tools for static analysis of PHP code files: given a set a PHP files, you can extract various information about contents of said PHP files, such as what classes it contains, and what methods said classes have, and so forth. It includes a type definition file for Typescript consumers.

The Big report in question notes a contradiction in the type definition for the return type of Class.getMethods() method with the actual implementation: the type definition states a return type of Method[] (array of Methods), which at run-time, an object is returned with the method names as properties. The simplest solution would be to change the return type in the type definition file to any instead of Method[] but to me this doesn’t seem particular type-safe.

The following questions come to mind:

  1. Supposing we only want to change the type definition to reflect the actual run-time, is there something better (more type safe) than any?
  2. Given that we can change the implementation, is returning an object with the method names as properties referencing Method objects a good/correct API design. Would it be ‘better’ to return an array of Method?
  3. Changing the implementation risks breaking code for existing consumers of library, so we may not wish to make the above change without considering existing consumers. How can we give consumers the means to specify whether to return an object or array (returning object by default for backwards consumers)?

I’ve got some ideas on these, which I’ll post as soon as I’ve more fully explored them. In the meantime, if anyone more experiences than me wants to share their thoughts on this, that would be appreciated.