es-date-utils

dateUtils

Practical Date handling utilities for ECMAScript/Javascript. Main features include server time synchronizing, date clearing, date adding, age calcuation, date formatting etc.

How to use

Install

npm i es-date-utils

Import

import dateUtils from 'es-date-utils'

// store server time
dateUtils.seed(1470627777230)

// new Date() according to server time
const now = dateUtils.now()

// clear date below date level, i.e. hours/minutes/seconds/milliseconds
dateUtils.clear(now, dateUtils.DATE)

// age calculation
dateUtils.age('1999-02-20')

ESLint

Before building/testing, eslint would run automatically under src and test folder. Building/testing would be interrupt if eslint run failed.

You can run eslint manually with this script:

npm run lint

Unit Test

npm run test

APIs

Date Types

Date types is used as identifiers for dateUtils to operate Date. They can be accessed via dateUtils.*.

• dateUtils.MILLISECOND
• dateUtils.SECOND
• dateUtils.MINUTE
• dateUtils.HOUR
• dateUtils.DATE
• dateUtils.MONTH
• dateUtils.YEAR

clone(param)

Clones and returns a date from given param. A param could be one of the four types:

• Number

  A positive or negative number representing the number of milliseconds passed from 1970-01-01.

• String of [RFC2822 Section 3.3][6]

  A string like Sat Jul 30 2016 18:17:37 GMT+0800 (CST), which can be generated by Date.toString() or Date.toDateString()

• String of [ISO-8601][5]

  A string like 2016-07-30T10:18:43.422Z, which can be generated by Date.toJSON(). Note that Date.toJSON() will return a UTC time.

• Date

  A Javascript Date Object.

seed(seed)

Store the server time and use it as a seed to generate new Date Object later. dateUtils would keep a copy of both server time and system time.

When now() is called, a system time delta will be added based on the server time. The delta should be positive, in case client modifies system time backward.

dateUtils.seed('2016-08-08') // Mon Aug 08 2016 08:00:00 GMT+0800 (CST)

resetSeed()

Reset the seed set by seed().

dateUtils.resetSeed()

now()

Return a new Date Object based on the seed, plussing time elapsed since seed() is called. If no seed is set, system time is used instead.

dateUtils.now() // Mon Aug 08 2016 08:00:10 GMT+0800 (CST)

clear(date, type)

Clear part(s), which is below type, of given date.

e.g. if given type = dateUtils.DATE, the parts below DATE (i.e. hours/minutes/seconds/milliseconds) will be set to zero.

type is arrange by YEAR > MONTH > DATE > HOUR > MINUTE > SECOND > MILLISECOND.

const now = dateUtils.now()
// Mon Aug 08 2016 08:00:10 GMT+0800 (CST)

dateUtils.clear(now, dateUtils.MONTH)
// Mon Aug 01 2016 00:00:00 GMT+0800 (CST)

daysInMonth(year, month)

Return maximum dates of given year and month. Note that month ranges from 1 to 12.

dateUtils.daysInMonth(2012, 1) // 31
dateUtils.daysInMonth(2012, 2) // 29
dateUtils.daysInMonth(2012, 4) // 30
dateUtils.daysInMonth(2011, 2) // 28

isLeapYear(year)

Test whether given year is a leap year or not.

dateUtils.isLeapYear(2010) // false
dateUtils.isLeapYear(2000) // true
dateUtils.isLeapYear(2100) // false

add(date, num, type, excludeEndDate = false)

Add a certain period of a certain date type to date.

num could be either negative of positive.

type is one the seven date types, and dateUtils would handle it automatically.

In some situation, date adding should exclude the last day, excludeEndDate is used to do it. It only works with num > 0 and type = YEAR/MONTH/DATE.

const now = dateUtils.now()
// Mon Aug 08 2016 08:06:52 GMT+0800 (CST)

dateUtils.add(now, 1, dateUtils.DATE)
// Tue Aug 09 2016 08:00:00 GMT+0800 (CST)

dateUtils.add(now, 1, dateUtils.DATE, true)
// Mon Aug 08 2016 08:06:52 GMT+0800 (CST)

dateUtils.add(now, -10, dateUtils.DATE)
// Fri Jul 29 2016 08:00:00 GMT+0800 (CST)

dateUtils.add(now, 2, dateUtils.MONTH)
// Sat Oct 08 2016 08:06:52 GMT+0800 (CST)

dateUtils.add(now, 2, dateUtils.MONTH, true)
// Fri Oct 07 2016 08:06:52 GMT+0800 (CST)

dateUtils.add(now, -5, dateUtils.MONTH)
 // Tue Mar 08 2016 08:06:52 GMT+0800 (CST)

dateUtils.add(now, 16, dateUtils.YEAR)
// Sun Aug 08 2032 08:06:52 GMT+0800 (CST)

dateUtils.add(now, 16, dateUtils.YEAR, true)
// Sat Aug 07 2032 08:06:52 GMT+0800 (CST)

dateUtils.add(now, -7, dateUtils.YEAR)
// Sat Aug 08 2009 08:06:52 GMT+0800 (CST)

age(date, addAgeAfterBirthday = false)

Calculate the age of given date. Note that end date uses dateUtils.now(), thus you can modified seed to test.

In most cases, we add age by 1 on birthday. However, in some situation, you may add age by 1 at the day after the birthday by setting addAgeAfterBirthday = true.

const now = dateUtils.now()
// Mon Aug 08 2016 08:06:52 GMT+0800 (CST)

dateUtils.age('2015-08-09') // 0
dateUtils.age('2015-08-08') // 1
dateUtils.age('2015-08-07') // 1

dateUtils.age('2015-08-09', true) // 0
dateUtils.age('2015-08-08', true) // 0
dateUtils.age('2015-08-07', true) // 1

dateUtils.age('2017-08-08') // 0
dateUtils.age('2000-01-08') // 16
dateUtils.age('2000-10-08') // 15

padZero(number, digits = 2)

Pad a number to specified digits with zero.

dateUtils.padZero(0, 2) // '00'
dateUtils.padZero(1, 2) // '01'
dateUtils.padZero(10, 2) // '10'

dateUtils.padZero(0, 3) // '000'
dateUtils.padZero(1, 3) // '001'
dateUtils.padZero(10, 3) // '010'
dateUtils.padZero(100, 3) // '100'

format(date, format)

Return a string by formatting given date. format() would search below strings in format param and replace them with locale time, such as date.getDate(), date.getHours(), date.Minutes().

• SSS milliseconds with leading 0
• S milliseconds without leading 0
• ss seconds with leading 0
• s seconds without leading 0
• mm minutes with leading 0
• m minutes without leading 0
• hh hours with leading 0 (12-hour time system)
• h hours without leading 0 (12-hour time system)
• HH hours with leading 0 (24-hour time system)
• H hours without leading 0 (24-hour time system)
• dd date with leading 0
• d date without leading 0
• MM month with leading 0
• M month without leading 0
• yyyy full year
• yy two-digit year

dateUtils.seed('2016-08-09')
// Tue Aug 09 2016 08:00:00 GMT+0800 (CST)
const now = dateUtils.now()
// Tue Aug 09 2016 08:00:21 GMT+0800 (CST)

dateUtils.format(now, 'yyyy-MM-dd') // '2016-08-09'
dateUtils.format(now, 'yyyy-MM-dd HH:mm:ss.SSS') // '2016-08-09 08:00:21.942'
dateUtils.format(now, 'M-d-yy') // '8-9-16'
dateUtils.format(now, 'yyyy年M月d日') // '2016年8月9日'
dateUtils.format(now, 'MMdd') // '08/09'
dateUtils.format(now, 'dd/MM HH:mm') // '09/08 08:00'

TODO

• date.format() should consider more about locale setting.