feat: add rescale option to Duration.normalize method

[NGPixel]

The Problem

There's a use case right now where you have a duration from a set of units but want them to be displayed to the user in a more "human readable" format.

For example, you might want to display the duration between various 2 datetimes, which can defer in hours or just a few seconds:

const dur = Interval.fromDateTimes(start, end).toDuration(['hours', 'minutes', 'seconds', 'milliseconds'])
console.log(dur.toHuman())

// example outputs:
// 4 hours, 0 minutes, 12 seconds and 0 milliseconds
// 0 hours, 0 minutes, 5 seconds and 0 milliseconds
// 0 hours, 54 minutes, 0 seconds and 0 milliseconds

Because the duration can vary greatly between just a few seconds and many hours, the current output is completely useless.
One would expect the normalize() method to solve this problem but unfortunately, the current implementation only adjust the units currently in use.

const dur = Duration.fromObject({ milliseconds: 90000 })
console.log(dur.normalize().toHuman())

// output: 90000 milliseconds

In this example, normalizing 90000 milliseconds will still get you... 90000 milliseconds. Not useful at all. Again, because the duration can vary greatly, using shiftTo() is not a viable option.

The Solution

This PR adds a rescale option to the normalize() method which also shifts units to their largest representation, on top of the current normalization. This basically remove any units with values of 0, giving you a clean output.

const dur = Interval.fromDateTimes(start, end).toDuration(['hours', 'minutes', 'seconds', 'milliseconds'])
console.log(dur.normalize({ rescale: true }).toHuman())

// example outputs:
// 4 hours and 12 seconds
// 5 seconds
// 54 minutes

const dur = Duration.fromObject({ milliseconds: 90000 })
console.log(dur.normalize({ rescale: true }).toHuman())

// output: 1 minute and 30 seconds

Notes

This could possibly be its own method (e.g. rescale()), but in my opinion, this is what you would expect the normalize() method to do. Therefore, I think it makes more sense to simply add an optional flag to the current normalize() method.

Thanks!

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: NGPixel / name: Nicolas Giard (724b57f, 8aa2e11, 2ff70c1, c660799, 350aa71)

[icambron]

Ok, so this makes sense, but here are some changes I'd like. Essentially, I'd like to decompose this.

1. Let's add removeZeros() as a top-level method. It just removes all the zeroed -.
2. Let's add a shiftToAll() method defined as shiftTo("years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds")
3. Let's not add other features to normalize but instead just add a new method called rescale(). Rescale is implemented as this.normalize().shiftToAll().removeZeros()

Does that make sense?

[NGPixel]

@icambron I refactored the code as requested.

[icambron]

Thanks! I'll release this soon

[NGPixel]

@icambron Any ETA for the next release?

[icambron]

@NGPixel it's released now

[NGPixel]

Thanks!

[drc-gcoakley]

For the most part this looks great! It even handles negative numbers. Unfortunately, it does not handle zero.
Duration.fromObject({milliseconds: ms}).rescale().toHuman(); returns an empty string.