refactor: major API changes

[Josh-Cena]

Resolve #18.

Breaking changes

• The readingTime now only returns time (milliseconds) and minutes—both are integers. No strings or decimals are returned. You can always convert them to representations you need.
  • Why? Removal of text improves ease of i18n as we are no longer biased towards English. minutes used to return a decimal which is trivially time / 60000 but with a lot of floating point funkiness.
• The ReadingTimeStream now only stores word count as its state—it is the equivalent of countWords(), not the bulk of readingTime(). Users still need to run readingTimeWithCount() to get the result.
  • Why? To improve composability, because a lot of the implementation details that go on under the hood are not controllable to the user, so a granular API is more desirable.

I may be cutting too many features here. Open to discussion.

Features

New functions countWords and readingTimeWithCount. Right now WordCountResults = { total: number }, but in the future we can have whitespace, punctuation, CJK, words, etc., each with its own wordPerMinute setting when passed to readingTimeWithCount!

[ngryman]

Hey @Josh-Cena, thanks a bunch for the PR. I like it 🤘

It mostly LGTM but since we're changing the API, I would go a bit further (cf. ReadingTimeResults) and I would change a few minor things.

ReadingTimeResults

I would even go further. I think we should just return seconds and that's it. Milliseconds don't make sense here and minutes can be derived easily as you mentioned.

So that would give us:

type ReadingTimeResults = {
  time: number;
  words: number;
};

Simple.

Minor changes

1. ReadingTimeResults → ReadingTimeResult since we only returning one result.
2. wordCount → coundWord since it's a function, I prefer if it starts with a verb.
3. Unless you were thinking about adding more properties to WordCountStats in the future, I prefer if we keep things simple and just return the word count.
4. I don't have a super-strong opinion on this, but I generally prefer to use type for concrete types (ie. POJOs) and interface for abstract types (ie. to be inherited by a class).

PS: Could you add yourself to the contributors' section ❤️

[Josh-Cena]

I kept the minutes field because our chief purpose is still to provide a "medium's like reading-time", and I don't want users to invest significantly in making that happen, even if it's simply Math.round(time / 60)🤪 Getting rid of the "1 min read" is already introducing one layer of indirectness, but I think that's worth it for the sake of i18n

Unless you were thinking about adding more properties to WordCountStats in the future,

I am😉 On my plans are whitespace, punctuation, CJK, words, etc., each with its own wordPerMinute setting when passed to readingTimeWithCount. For example Chinese speakers read more CJK characters than English speakers read Latin words, so there should be a nuance

Apart from those, great suggestions, will address those

[Josh-Cena]

Ping for @ngryman if we can settle on the API and merge this, we can release 2.0.0 because this is the last milestone

[ngryman]

Hey @Josh-Cena, sorry again for the delay. I'll be more responsive now I'm finally home 🙂

[Josh-Cena]

No problem😄 Shall we release 2.0.0? Is there any other milestone on your mind?

[ngryman]

Shall we release 2.0.0?

Yes! Out of precaution, I published it as a 2.0.0-0 pre-release with a beta tag.
Here's the GH release: https://github.com/ngryman/reading-time/releases/tag/v2.0.0-0.

That will give us the time to potentially tweak things before the final 2.0.0 release.

Thanks for all the awesome work you did on this and sorry again for my lack of availability 🙏