Move to TypeScript

[smhg]

@johnhooks @erikyo

[johnhooks]

@smhg which do you prefer;

1. Complete rewrite of the library into TypeScript.

• Pros:

  • Easier to write types. The TS syntax is much more concise than the JSDoc style.

• Cons:

  • Requires structural changes to the logical code. This is what I consider the biggest downside.
  • Requires a build step to generate the exported files of the package.

2. Make improvements to the existing JSDoc types.

• Pros:

  • Requires no structural changes to the logical code.
  • No build step for logical code, only for type declaration generation.
  • Less intimidating to JavaScript developers.

• Cons:

  • Verbose.
  • Harder to read and write.

[johnhooks]

Requires no structural changes to the logical code.

For JSDocs, eventually we would need to make logical changes, because we discover type errors, but the changes would be informed by the addition of types, not the other way around.

[smhg]

Since I don't have any meaningful TypeScript experience and it doesn't look like that will change in the near future, I can't be involved in approach 1. I am fine with that, but that means any of you need to be in it for the long run.
If not, approach 2 is the only possiblity. Or no type support.

[johnhooks]

@erikyo and I would be in it for the long run. We have pretty deep interests in internationalization and the need for manipulating mo and po files in a predictable way.

[erikyo]

I have two projects that depend on this, in a way it goes without saying that I am interested in this one working well, it is in my interest and decreases the code required in the other projects. so yes I will be there!

[smhg]

Background: I think this library could use some rewriting. There is room for preformance improvements and better code readability among others. All while keeping the API stable, with only incremental breaking changes when absolutely necessary.
This did not require TS in my mind, but if that facilitates changes, then why not.

[johnhooks]

I agree, it doesn't require TS, though I do believe it can help find common errors, especially during refactor.

[erikyo]

All while keeping the API stable

That's why I always thought that if I don't change the tests and the result is always the same, I am not creating any breaking changes.
the problem though is that there is not 100% coverage because (if I remember correctly) the poStream function is not covered (or if it is, not completely)

perhaps it would be good to achieve 100% coverage so that we can be "mathematically" sure that we are not changing the operation of the module while changing the code

[smhg]

100% test coverage would be awesome 👍

[smhg]

Based on the ongoing discussions I suggest we move on with what can be immediately released?

I can pull in those meta changes one of the next days (a PR for those never seems to have worked out?). After that I suggest you send a PR for the JSDoc types?
And then we discuss the next step?

Feel free to disagree of course.

[johnhooks]

@erikyo I'm trying to show an example of what I interpreted from @smhg comment:

I can pull in those meta changes one of the next days (a PR for those never seems to have worked out?). After that I suggest you send a PR for the JSDoc types?

I read that as (and correct me if I am wrong):

Where were the small changes, unrelated to the JSDocs types PR?

[erikyo]

In this case we just checkout the pr we want and merge to the master (assuming we want to do so immediately), this way we can continue the flow of development without breaking it

[johnhooks]

Okay I guess I don't totally understand this process either.

[erikyo]

It follows the common workflow, but instead of working directly on the master branch (the public-facing branch), you work on the development branch. After completing all changes and ensuring that tests and builds pass successfully, you can then merge the changes into the master branch, possibly creating a tag for the release.

this is another good article from gitkraken that explains how to:
https://www.gitkraken.com/learn/git/best-practices/git-branch-strategy#git-flow-branch-strategy

[johnhooks]

To be clear I only made #94 and #95 as examples of the types of PRs I thought were expected by the discussion.