Add read_rate, incr_rate functions and time_left in milliseconds to the result

[nicksanders]

Add read_rate, incr_rate functions to allow read the current counter without incrementing the counter
Added time_left in milliseconds to the result

Got slightly carried away and added the read_rate, incr_rate functions

Will update the documentation and tests properly if you are happy with the new functions and result

[grempe]

Yes, I think I am OK with this approach. Look forward to seeing it fleshed out. Thanks for the contributions.

[nicksanders]

The 2nd commit is just an idea I was playing around with, happy to remove it if you don't like it

[grempe]

Thinking about this a little more. Your initial intention was to add the remaining time to the check_rate result. So why do we need read_rate and incr_rate new API's to accomplish that in addition to modifying the results of check_rate? As a user I think I would be confused by the difference between those three public API's. I'm also not clear what you are trying to accomplish with the bucket number re-factoring.

After thinking about it a bit more I think I'd prefer the approach of keeping this pull request focused on the initial intention you had and do the minimum required to accomplish that.

Perhaps we should even leave check_rate's results alone (so as to avoid a breaking public API change and necessary 2.0 version bump for semver) and just add a single new side-effect free public API like:

.inspect_bucket("my-bucket", 86400000, 2500)

which could return all of the metadata about that bucket, including the created_at, updated_at, count, count_remaining, ms_to_next_bucket, etc.

Anyone who is interested in this info could call it as often as they like with no side effects.

I'd feel much better about this approach I think. What do you think? I think it addresses your need, provides additional data that is not available right now, and doesn't break any existing code.

Cheers,

Glenn

[nicksanders]

That makes total sense :)

I have updated the pull request, let me know what you think