Typescript migration proposal

[sroucheray]

Hi @mrin9,

First I would like to say that Rapidoc is a great project. I made a benchmark and among other similar libraries, it is one of the most featured, well integrated and easy to use. Furthermore you accept contributions which is great and not always the case for other projects. So I would like to thank you for your work.

Its all natural that, at my company, we decided to integrate RapiDoc in our projects. I would like to add some feedback from the point of view of the recent contributor I am. First your choice to use Lit is great because it comes with its documentation which make it much easier to contribute. I would like to contribute more in the future, if you will, but I think the project might be able to gain some robustness.

When I contributed I had to understand the shape of objects which are manipulated in the codebase to be sure not to include regressions while delivering a new feature or fixing a bug. I made a lot of inferences, which is not good. As a Typescript developer I am convinced that moving the project from JS based files to Typescript would be a game changer. The code would be more robust, simpler to understand, easier to contribute, more self documented. The shape of objects while could be inferred in a first place would later improve by being explicit. It would also catch a lot of small bugs, non handled little edge cases (and I am sure there are a lot with the OpenAPI format).

So I would like to suggest migrating the project to Typescript. Lit already handle this very well and even provides some tooling https://lit.dev/docs/tools/development/#typescript.

It would involved a number of steps:

• Installing typescript and necessary @types/* dev dependencies
• Swapping the jsconfig to a tsconfig file (there is a Lit starter kit as an example https://lit.dev/docs/tools/starter-kits/)
• Updating webpack to handle Typescript files
• Incrementally changing .js files to .ts files
  • This point is crucial and this is great because you don't have to migrate all at once, you can keep compiling with a mix of JS and TS files (https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)

I already did early work and it seems to start well. I would like to make a PR, not to be merged ASAP but that could hold progressive commits for this migration. But before doing this I wanted to get your feedback about the idea as it's better to keep ideas and discussions in an issue than in a PR.

Thanks,

Stephane

[mrin9]

There was an attempt to convert into typescript sometime back but gave it up we got into few maintenance issues.

RapiDoc has attain a lot of maturity the only major feature pending is Localization, may be after that we can attempt porting to TypeScript. I am gonna be little busy till end of jan next year. If you are up for it then I would suggest to do the localization first and then porting to TypeScript to have minimal interference

[sroucheray]

Actually I have already made some work. There are only a couple of files remaining to migrate. It's not perfect, I had to guess a lot of typings (along with open api typings delivered by an external de library) but I think it might be a good start. I understand that Localization is an important feature but it requires more thinking (i18n + l10n) than Typescript migration. I have good experience in Angular i18n, not yet with WebComponents, I could help for that (while its not a priority internally for us). Anyway I plan to push my branch in couple of days. You may or may not look at it depending on your workload !

[mrin9]

yep put up the PR , as and when I get time I can look it through.

for localization, we wont be bundling up any translation as it may increase our bundle size instead allow user to specify those translation. For some context checkout https://mrin9.github.io/RapiPdf/api.html#localize

[sroucheray]

PR #862

[sroucheray]

FYI @mrin9 I maintain the TS branch in sync with master.