globalizejs / globalizejs/globalize

Relative time: Additional features

Open
#391 2 comments 0 reactions 0 assignees View on GitHub
new feature
Dominant language
JavaScript
Stars
4.8k
Forks
585
PR merge metrics
No merged PRs in 30d

Description

- PR #395 (implementation using `value` as number unit)

Support relative times:
- in the past , eg "5 days ago";
- in the future, eg "in 5 days";
#### API

``` javascript
Globalize.formatRelativeTime( value[, unit][, options] )
```

Examples:

``` javascript
.formatRelativeTime( inTwoDays ); // in 2 days
.formatRelativeTime( twoDaysAgo ); // 2 days ago
.formatRelativeTime( 2, "day" ); // in 2 days
.formatRelativeTime( twoDaysAgo, "hour" ); // 48 hours ago
.formatRelativeTime( -48, "hour" ); // 48 hours ago
.formatRelativeTime( twoDaysAgo, "hour", { form: "short" } ); // 48 hr. ago
.formatRelativeTime({ from: christmas2001, to: newyear2002 }, "day" ); // in 7 days
```

Value: Object with `from` and `to` keys and Date instance values, or a Date instance (considered to be the `to` value and `from` defaults to now (`new Date()`)), or a Number (positive numbers represent future, negative numbers represent past).

Unit: Optional when `value` is a Date instance or an object of Date instances. Required when `value` is a Number. Possible values are (year, quarter, month, week, day, hour, minute, and second), e.g., "in 30 days", "in 4 weeks", or "in 1 month", ... Defaults to automatic detection when using Date instances, therefore implementing a simple approximation algorithm [1]. But, delegating any more complex things to a specific date manipulation library such as moment.js.

Options:
- form (short, narrow), eg. "in 30 days", "in 4 wk.", or "in 1 mo."...

1:
- "1 second ago" .. "59 seconds ago"; (1 .. 59 s)
- "1 minute ago" .. "59 minutes ago"; (60 .. 60*60 s)
- "1 hour ago" .. "59 hours ago";
- "1 day ago" .. "59 days ago";
- "1 week ago" .. "59 weeks ago";
- "1 month ago" .. "59 months ago";
- "1 year ago" .. "59 years ago";

(analogous for future)
#### CLDR

Relative time fields can be found on /[dateFields.json](http://www.unicode.org/repos/cldr-aux/json/26/main/en/dateFields.json).
- http://www.unicode.org/reports/tr35/tr35-dates.html#Calendar_Fields
- http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
#### Other

References:
- Ecma proposal https://github.com/tc39/ecma402/issues/35
- [twitter-cldr](https://github.com/twitter/twitter-cldr-js/)
- [Rails](http://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html#method-i-distance_of_time_in_words);
- Wikipedia [[1]](https://github.com/wikimedia/mediawiki-core/blob/master/includes/MWTimestamp.php#L179) [[2]](https://github.com/wikimedia/mediawiki-core/blob/master/languages/Language.php#L2269);
##

This issue succeeds #205 (discussion to get to the API above). For absolute durations, see `.formatUnit()` in #252.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.