Suggestions for improving Duration support in date-fns

DurationProposal.md

Duration: Suggestions for improvements

1. duration.years/months/days/hours/... => duration.X

• Right now what is returned by Duration(months: 13) for these attributes seems to be what the user has defined. Some other suggestions:
• trailingX: Trailing number of X in the duration after normalization (eg. 1 month instead of 13 months)
  • Issues with normalization: How do we consider months which have variable lengths? Normalize months & years together and all the other units together
• totalX: Total number of X in the duration in a single unit (eg. 13 months or 1 year)

2. formatDuration()

• Support more formats by allowing a formatString, for example:
  • 10y 2m
  • 23:08.456
  • About 8 hours
• Normalization preferred, can have an optional boolean if user prefers to normalize (add up) or not
• Other options:
  • trim: Trim zero-value tokens
  • largest: Show n largest-magnitude tokens
  • trunc: Truncate final token value instead of round to closest
  • minValue: Duration below minimum will be shown as < minimum
  • maxValue: Duration above maximum will be shown as > maximum

3. intervalToDuration()

Just a note: The type definition for Duration is not found in the intervalToDuration docs

4.compareDurations(leftDuration, rightDuration)

Normalize, compare and return -1, 0 or 1 according to leftDuration > rightDuration

5. d.addDuration(Duration)

Add durations (may need normalization).

6. d.subtractDuration(Duration)

Subtract durations (should need normalization).

7. parseDuration(String)

Convert string to Duration. Depending on how format duration is implemented (or improved), we could also add the ability to parse strings to return a Duration. For example,

var result = parseDuration(durationString: "2 days 3 hours")
//=> { days: 2, hours: 3 }

var result = parseDuration(durationString: "10y 2m", formatString: "y'y' M'm'")
//=> { years: 10, months: 2 }

8. parseISODuration(String)

Convert ISO 8601 string to Duration.

9. d.locale('en')

Change locale of formatted string. From the functions we have discussed now, we could do:

Duration({ minutes: 481 }).locale("en").format(type: "distance") // about 8 hours
Duration({ minutes: 481 }).locale("fr").format(type: "distance") // environ 8 heures

This is a code example from moment.js:

moment.duration(1, "minutes").locale("en").humanize(); // a minute
moment.duration(1, "minutes").locale("fr").humanize(); // une minute

Other suggestions

1. Temporal proposal

Looking into the official Temporal.Duration experimental proposal for ECMAScript may help.

2. ExtendedDuration

We can support ExtendedDuration which includes milli/micro/nanoseconds to satisfy certain use cases without changing the standard Duration object. Some use cases mentioned include:

• validating a Duration parsed using another language on the backend (Go's duration supports different time units)
• formatting Duration for subtitle files using milliseconds