carryoverConcurrencyCount docs are vague

[shellscape]

Ahoy 🚢

The carryoverConcurrencyCount option could use some more verbose documentation. In toying with the package, it's not entirely clear what option value produce what behavior.

Perhaps even an examples directory that covered how this works?

[sindresorhus]

Can you be more specific about what's unclear about it? For now, I would recommend looking at its tests at that might clarify how it should be used.

// @Rafael09ED

[Rafael09ED]

carryoverConcurrencyCount is asking whether it should carryover any incomplete promises into the next interval and apply that number against the limit cap. By effect, it determines whether the interval cap limits how many can start or how many can finish in the given time, if respectively set to false or true.
For example, if you can only have 5 connections at a time and are rate limited, you would set carryoverConcurrencyCount to true to make sure you don't go over 5 connections.
Does that help any?

[shellscape]

@Rafael09ED that's the good stuff I was looking for in the readme. Thank you for adding that. Typically for options that are boolean, I recommend (and look for) a format such like:

If true, the thing behaves like one way. If false, thing behaves another way.

The paragraph you replied with above would be an absolute value-add to the readme!

[Rafael09ED]

Thank you for the good advice. How does this look for the new carryoverConcurrencyCount readme section?

carryoverConcurrencyCount

Type: boolean
Default: false

Whether any incomplete promises should be carried over into the new interval and applied against the intervalCap.
If true, intervalCap effectively limits how many can finish. If false, intervalCap limits how many can start.

Useful in preventing rate limit overages.

[shellscape]

intervalCap effectively limits how many can finish

This threw me off, because it doesn't seem to relate (with that verbiage). We'd been talking about tasks/promises starting and this tosses finishing in the mix.

I'd tweak it a bit:

##### carryoverConcurrencyCount

Type: `boolean`\
Default: `false`

If `true`, specifies that an incomplete `Promise` should be carried over into the next interval and counted against the `intervalCap`. If `false`, an incomplete promise will continue to run independent of the next interval and will not count towards the `intervalCap`.

[sindresorhus]

Fixed by #100.

[shellscape]

Thanks for tackling this.