Change the API

[ngryman]

Currently readingTime returns an object of the form:

{
  text: displayed + ' min read',
  minutes: minutes,
  time: time,
  words: words
}

That's too much and it's not easily composable. Let's decouple things and expose this API:

export const countWords = (text: string, options?: { bound?: string => boolean }): number
export const readingTime = (wordCount: number, options?: { wordsPerMinute?: number }): number
export default function(text, options) {
  return readingTime(countWords(text, options), options)
}

[Xapphire13]

This looks good to me! Will readingTime() return in minutes or ms with this API?

[ngryman]

I think that seconds would be the best time resolution as reading times generally vary from under 1 minute to several minutes. It's easily convertible to ms (if you really need it) or to minutes.

[Xapphire13]

Sounds good!

[ngryman]

I hope you don't mind me pulling you here @Josh-Cena but I'm curious about your opinion on this. As a user, would you like an API similar to the one proposed here for 2.0.0?

[Josh-Cena]

No strong feelings on this, both seem acceptable to me. But considering the utility nature of this lib, I would prefer a simpler API that returns more data (i.e. the current API) so the user has less to maintain on their side. Getting rid of the text field sounds sensible to me, but overall, I would say the current API is good enough

[ngryman]

Got it. I agree that the text field is not very useful, I think we should get rid of it. For the rest let's keep it that way for now.

So the new result would just be:

type Result = {
  minutes: minutes,
  time: time,
  words: words
}

I still kind of like the idea of decoupling word counting from reading time computation in case users want to customize things. It's pretty cheap to achieve so why not 🤷

I think we can do that while not breaking the current API:

type countWords = (text: string, options?: { bound?: string => boolean }): number

type readingTimeWith = (wordCount: number, options?: { wordsPerMinute?: number }): Result
type readingTime = (text: string, options?: { wordsPerMinute?: number }): Result

@Josh-Cena What do you think?

[Josh-Cena]

LGTM, we should allow people to control this process more granularly, while one single convenient API would still be good for normal users👍

[Josh-Cena]

Another thing I noticed when I'm refactoring the test suite: the minutes field is not tested at all, and it's trivially time / 60000. Moreover, in the stream version, floating point errors build up when adding the minutes together, so the final minutes stat can deviate a lot. I think we should export only time (exact time in milliseconds) and displayed (rounded minutes stats), and let the user convert it to other measures if they need.