@yr/time

An efficient, immutable, utility for working with time/dates.

Usage

const time = require('@yr/time');
const t = time.create('2016-01-01')
  .add(2, 'hours')
  .subtract(1, 'day')
  .format('YYYY-MM-DD HH:mm');
console.log(t); //=> 2015-12-31 02:00

API

init(options): override defaults. Options include:

• dayStartsAt: the hour a day begins at (default 0). Modifies results of diff(), startOf(), isSame(), and format().
• nightStartsAt: the hour night begins (default 18). Modifies results of format() when using ddr or dddr masks

create(timeString): create a Time instance with timeString. The following patterns are valid, with or without offset (+HH:mm):

• YYYY: time.create('2016') => 2016-01-01T00:00:00.000+00:00
• YYYY-MM: time.create('2016-02') => 2016-02-01T00:00:00.000+00:00
• YYYY-MM-DD: time.create('2016-02-02') => 2016-02-02T00:00:00.000+00:00
• YYYY-MM-DDTHH: time.create('2016-02-02T12') => 2016-02-02T12:00:00.000+00:00
• YYYY-MM-DDTHH:mm: time.create('2016-02-02T12:30') => 2016-02-02T12:30:00.000+00:00
• YYYY-MM-DDTHH:mm:ss: time.create('2016-02-02T12:30:30') => 2016-02-02T12:30:30.000+00:00
• YYYY-MM-DDTHH:mm:ss.SSS: time.create('2016-02-02T12:30:30.500') => 2016-02-02T12:30:30.500+00:00

If no offset is specified, the time instance is handled as UTC (+00:00).

If timeString is omitted altogether, an instance is created with time set to current machine time and timezone offset.

now(): create a Time instance based on number of milliseconds elapsed since 1 January 1970 00:00:00 UTC (Date.now() == Time.now().toValue())

isTime(time): determine if time is a Time instance.

Time instances

offset(_value): update an instance's Offset with value (in minutes). Returns a new Time instance.

add(value, unit): add specified value in specified unit to the instance. Returns a new Time instance:

Valid unit include:

• year, years, Y and y
• month, months and M
• day, days, date, dates, D and d
• hour, hours, H and h
• minute, minutes and m
• second, seconds and s
• millisecond, milliseconds and S

time.create('2016-01-01T12:00:00').add(2, 'hours'); 
//=> 2016-01-01T14:00:00.000+00:00

subtract(value, unit): subtract specified value in specified unit from the instance. Returns a new Time instance:

time.create('2016-01-01T12:00:00').subtract(90, 'minutes'); 
//=> 2016-01-01T10:30:00.000+00:00

diff(time, unit, asFloat): calculate difference between another time in specified unit:

time.create('2016-01-01')
  .diff(time.create('2015-01-01'), 'days'); //=> 365

If unit is omitted, returns difference in milliseconds.

If asFloat=true, returns difference with no rounding, otherwise values are rounded towards 0.

If a dayStartsAt value is set via init(), difference values for day units are specially handled:

time.init({ dayStartsAt: 6 });
time.create('2016-01-01T07:00')
  .diff(time.create('2016-01-01T05:00'), 'days'); //=> 1

startOf(unit): reset to start of specified unit. Returns a new Time instance:

time.create('2016-12-01')
  .startOf('year'); //=> 2016-01-01T00:00:00.000+00:00

endOf(unit): reset to end of specified unit. Returns a new Time instance:

time.create('2016-12-01')
  .endOf('year'); //=> 2016-12-31T23:59:59.999+00:00

year(value): get/set year unit. If passed a value, returns a new Time instance.

month(value): get/set month unit (0-11). If passed a value, returns a new Time instance.

date(value): get/set day of month unit (1-31). If passed a value, returns a new Time instance.

day(value): get/set day of week unit (0-6). If passed a value, returns a new Time instance.

hour(value): get/set hour unit (0-23). If passed a value, returns a new Time instance.

minute(value): get/set minute unit (0-59). If passed a value, returns a new Time instance.

second(value): get/set second unit (0-59). If passed a value, returns a new Time instance.

millisecond(value): get/set millisecond unit (0-999). If passed a value, returns a new Time instance.

isSame(time, unit): determine if time is equivalent when evaluated in specified unit:

time.create('2016-12-01')
  .isSame(time.create('2016-12-31'), 'month'); //=> true

isBefore(time, unit): determine if Time instance comes before time when evaluated in specified unit:

time.create('2016-12-31')
  .isBefore(time.create('2017-1-1'), 'day'); //=> true

isAfter(time, unit): determine if Time instance comes after time when evaluated in specified unit:

time.create('2017-1-1')
  .isAfter(time.create('2016-12-31'), 'day'); //=> true

locale(locale): set locale for this instance. Returns a new Time instance. See en.json for an example of expected properties.

format(mask, daysFromNow): retrieve a string representation based on format described in mask. Format masks can contain one or more of the following tokens:

	Token	Output
Year	YY	70 71 ... 29 30
	YYYY	1970 1971 ... 2029 2030
Month	M	1 2 ... 11 12
	MM	01 02 ... 11 12
	MMM*	Jan Feb ... Nov Dec
	MMMM*	January February ... November December
Day of month	D	1 2 ... 30 31
	DD	01 02 ... 30 31
Day of week	d	0 1 ... 5 6
	ddd*	Sun Mon ... Fri Sat
	dddd*	Sunday Monday ... Friday Saturday
	ddr**	Today Tomorrow ... Fri Sat
	dddr**	Today Tomorrow ... Friday Saturday
Hour	H	0 1 ... 22 23
	HH	00 01 ... 22 23
	Hr*	night (0 - 6),
		morning (6 - 12),
		afternoon (12 - 18),
		evening (18 - 24)
Minute	m	0 1 ... 58 59
	mm	00 01 ... 58 59
Second	s	0 1 ... 58 59
	ss	00 01 ... 58 59
Fractional second	S	0 1 ... 8 9
	SS	0 1 ... 98 99
	SSS	0 1 ... 998 999
Offset	ZZ	-07:00 -06:00 ... +06:00 +07:00
* requires locale
** relative day based on daysFromNow

time.create('2016-12-01T12:00:00')
  .format('HH:mm'); //=> 12:00

time.create('2016-12-01T12:00:00')
  .locale(require('@yr/time/locale/en.json'))
  .format('dddr', 0); //=> Today

Escape characters in formatting masks by surrounding them with square brackets:

time.create('2016-12-01T12:00:00')
  .format('[it is now] HH:mm'); //=> it is now 12:00

now(): clone instance and set to current time. Returns a new Time instance.

clone(): clone intance. Returns a new Time instance.