Support for TypeScript

[axelpale]

The lib could be more friendly for TypeScript users.

@lsps9150414 Could you share a rough insight on how should it be done? Is it enough to have one index.d.ts file in the root of the project, or should lib/ and each directory under it, like lib/point/ and lib/transform/ also have their own index.d.ts files? Thanks for any guidance on this.

[lsps9150414]

No problem, I will get back to this when I'm done with my project.

[janne-slamcore]

Any progress on this or shall I take a look?

This guide appears to generate some types from the existing js: https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html but there are a lot of any fields that could use filling in.

https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html#testing-your-types has steps on how to publish types on DefinitelyTyped, but I'm not sure if that's preferred over including the types in this repo.

[axelpale]

@janne-slamcore Moro! Type definitions would definitely be a nice thing to have. Feel free to give it a go, I can appreciate a PR. I would prefer index.d.ts approach in order to keep things simple.

[janne-slamcore]

@axelpale Are you ok with me modifying the js to include jsdoc type declarations so the auto-generation handles most of the work?

[axelpale]

@janne-slamcore Thanks for asking. Well, I can see the benefit of declaring the types in JSDoc comment blocks near the actual code. However, that likely implies that we need to migrate all the documentation from the current inhouse-ish Yamdog syntax to JSDoc. While valuable, that is asking quite lot of work, more than I can deal right now.

Of course, you could add the JSDoc without touching the current Yamdog docs. However, it is not preferable for me to need to maintain two kinds of documentation schemes side-by-side in the long term. For a transition period, it is okay, but I think the outcome should be either JSDoc-only or Yamdog-only.

Personally, I am not a big fan of JSDoc for its limitations in documenting complex nested structures and for the use of non-nesting /** for the comment blocks. Still, I acknowledge it has a mature ecosystem and a plethora of tools. Also, my opinion on the downsides can be short-sighted and based on too little experience with JSDoc.

In case you have good experiences with JSDoc and are willing to do the work of migrating the docs to JSDoc and update the "build:docs" script, I will gladly show a green light (and buy you a beer if you reside in or visit Tampere).

Alternatively, I am cautiously okay to the suggestion of including JSDoc type declarations (without touching Yamdog-flavoured docs) but in that case I think I can decide only after I see how the outcome looks like. I fear the outcome is a codebase with 90% of documentation syntax and 10% of actual code somewhere between.

Finally, reconsider the option of manually constructed index.d.ts. It is far for perfect and carries its own maintenance problems but it is simple and standalone. Also, think it as a stepping stone to discover if the above-mentioned heavier options are truly needed.

Feel free to share any further thoughts and opinions.

[axelpale]

Hi @janne-slamcore and @lsps9150414 and sorry for the delay! I was finally able to gather some time to work further on Nudged. I wanted to let you know I plan to publish Janne's type declarations with [email protected] in upcoming week or two. Janne, your contribution looks great. Thank you so much. I will let you know here once the 2.1.0 is out.

[axelpale]

I am happy to tell that the type declarations are now published and available in [email protected]. It was a bit struggle to get the package structure right to make the declarations work as intended. I had to remove the "declare module" closure from nudged.d.ts and rename the file to index.d.ts. Also, I had to adjust the way to test the declarations. The struggle was worth it. Thank you again for the great work, this has been a major quality improvement for the package!