README.md
1# Relative Date
2
3[](https://travis-ci.org/wildlyinaccurate/tiny-relative-date)
4
5Tiny function that provides relative, human-readable dates.
6
7## Installation
8
9```
10npm install tiny-relative-date
11```
12
13## Usage
14
15The module returns a `relativeDate` function with English translations by default.
16
17```js
18const relativeDate = require('tiny-relative-date')
19```
20
21The `relativeDate` function accepts date strings or `Date` objects.
22
23```js
24relativeDate('2017-06-25 09:00') // '12 hours ago'
25relativeDate(new Date()) // 'just now'
26```
27
28The value of "now" can also be passed as a second parameter.
29
30```js
31const now = new Date('2017-06-25 08:00:00')
32const date = new Date('2017-06-25 07:00:00')
33
34relativeDate(date, now) // 'an hour ago'
35```
36
37### Using a non-English locale
38
39The tiny-relative-date module can be initialised with a locale. See the [translations directory]('./translations') for a list of available locales.
40
41```js
42const relativeDateFactory = require('tiny-relative-date/lib/factory')
43const deTranslations = require('tiny-relative-date/translations/de')
44const relativeDate = relativeDateFactory(deTranslations)
45
46relativeDate(new Date()) // 'gerade eben'
47```
48
49### Using a custom locale
50
51You can also use a completely custom locale by passing a translations object instead of a locale string. Translations can be plain strings with a `{{time}}` placeholder, or they can be functions. See the **Adding new locales** section below for a list of translation keys.
52
53```js
54const relativeDateFactory = require('tiny-relative-date/lib/factory')
55const relativeDate = relativeDateFactory({
56 hoursAgo: '{{time}}h ago',
57 daysAgo: (days) => `${days * 24}h ago`
58})
59
60relativeDate('2017-06-25 07:00:00') // '2h ago'
61relativeDate('2017-06-24 06:00:00') // '27h ago'
62```
63
64## Contributing
65
66Contributions are welcome! Running this project locally requires Git and Node.js.
67
68```
69git clone git@github.com:wildlyinaccurate/tiny-relative-date.git
70cd tiny-relative-date/
71npm install
72```
73
74Once you are set up, you can make changes to files in the `src/`, `spec/` and `translations/` directories. Build any changes you make by running
75
76```
77npm run build
78```
79
80And run the tests with
81
82```
83npm run test
84```
85
86### Adding new locales
87
88If you would like to add a new locale, please create a JSON file in the `translations` directory and ensure it has the following keys:
89
90| Key | Default value ("en" locale) |
91|------------------------|-----------------------------|
92| `justNow` | just now |
93| `secondsAgo` | {{time}} seconds ago |
94| `aMinuteAgo` | a minute ago |
95| `minutesAgo` | {{time}} minutes ago |
96| `anHourAgo` | an hour ago |
97| `hoursAgo` | {{time}} hours ago |
98| `aDayAgo` | yesterday |
99| `daysAgo` | {{time}} days ago |
100| `aWeekAgo` | a week ago |
101| `weeksAgo` | {{time}} weeks ago |
102| `aMonthAgo` | a month ago |
103| `monthsAgo` | {{time}} months ago |
104| `aYearAgo` | a year ago |
105| `yearsAgo` | {{time}} years ago |
106| `overAYearAgo` | over a year ago |
107| `secondsFromNow` | {{time}} seconds from now |
108| `aMinuteFromNow` | a minute from now |
109| `minutesFromNow` | {{time}} minutes from now |
110| `anHourFromNow` | an hour from now |
111| `hoursFromNow` | {{time}} hours from now |
112| `aDayFromNow` | tomorrow |
113| `daysFromNow` | {{time}} days from now |
114| `aWeekFromNow` | a week from now |
115| `weeksFromNow` | {{time}} weeks from now |
116| `aMonthFromNow` | a month from now |
117| `monthsFromNow` | {{time}} months from now |
118| `aYearFromNow` | a year from now |
119| `yearsFromNow` | {{time}} years from now |
120| `overAYearFromNow` | over a year from now |
121
){kind=link}