date-and-time

This JS library is just a collection of functions for manipulating date and time. It’s small, simple, and easy to learn.

Why

Nowadays, JS modules have become huge, complex, and have many dependencies. We think it makes sense to try to keep each module simple and small. Especially for modules that are at the bottom of the dependency chain, such as those dealing with date and time.

Features

• Minimalist. Approximately 2k. (minified and gzipped)
• Extensible. Plugin system support.
• Multi language support.
• Universal / Isomorphic. Works wherever.
• TypeScript support.
• Older browser support. Even works on IE6. 🙂

Install

npm i date-and-time

Recent Changes

• 2.4.2

  • Fixed an issue where the timezone plugin stopped working due to Node.js timezone update.

• 2.4.1

  • Fixed the previous Jest support.

• 2.4.0

  • Support for testing in Jest.

Usage

• ES Modules:

import date from 'date-and-time';

• CommonJS:

const date = require('date-and-time');

• ES Modules for the browser:

• Older browser:

Note

• If you want to use ES Modules in Node.js without the transpiler, you need to add "type": "module" in your package.json or change your file extension from .js to .mjs.

API

• format

  • Formatting date and time objects (Date -> String)

• parse

  • Parsing date and time strings (String -> Date)

• compile

  • Compiling format strings

• preparse

  • Pre-parsing date and time strings

• isValid

  • Date and time string validation

• transform

  • Format transformation of date and time strings (String -> String)

• addYears

  • Adding years

• addMonths

  • Adding months

• addDays

  • Adding days

• addHours

  • Adding hours

• addMinutes

  • Adding minutes

• addSeconds

  • Adding seconds

• addMilliseconds

  • Adding milliseconds

• subtract

  • Subtracting two dates (date1 – date2)

• isLeapYear

  • Whether a year is a leap year

• isSameDay

  • Comparison of two dates

• locale

  • Changing locales

• extend

  • Functional extension

• plugin

  • Importing plugins

format(dateObj, arg[, utc])

• @param {Date} dateObj – A Date object
• @param {string|Array.<string>} arg – A format string or its compiled object
• @param {boolean} [utc] – Output as UTC
• @returns {string} A formatted string

Available tokens and their meanings are as follows:

You can also use the following tokens by importing plugins. See PLUGINS.md for details.

Note 1. Comments

String in parenthese [...] in the formatString will be ignored as comments:

Note 2. Output as UTC

This function usually outputs a local date and time string. Set to true the utc option (the 3rd parameter) if you would like to get a UTC date and time string.

Note 3. More Tokens

You can also define your own tokens. See EXTEND.md for details.

parse(dateString, arg[, utc])

• @param {string} dateString – A date and time string
• @param {string|Array.<string>} arg – A format string or its compiled object
• @param {boolean} [utc] – Input as UTC
• @returns {Date} A Date object

Available tokens and their meanings are as follows:

You can also use the following tokens by importing plugins. See PLUGINS.md for details.

Note 1. Invalid Date

If the function fails to parse, it will return Invalid Date. Notice that the Invalid Date is a Date object, not NaN or null. You can tell whether the Date object is invalid as follows:

const today = date.parse('Jam 1 2017', 'MMM D YYYY');

if (isNaN(today.getTime())) {
    // Failure
}

Note 2. Input as UTC

This function assumes the dateString is a local datea and time unless it contains a time zone offset value. Set to true the utc option (the 3rd parameter) if it is a UTC date and time.

Note 3. Default Date Time

Default date is January 1, 1970, time is 00:00:00.000. Values not passed will be complemented with them:

Note 4. Max Date / Min Date

Parsable maximum date is December 31, 9999, minimum date is January 1, 0001.

Note 5. 12-hour notation and Meridiem

If use hh or h (12-hour) token, use together A (meridiem) token to get the right value.

Note 6. Token disablement

Use square brackets [] if a datea and time string includes some token characters. Tokens inside square brackets in the formatString will be interpreted as normal characters:

Note 7. Wildcard

A white space works as a wildcard token. This token is not interpreted into anything. This means it can be ignored a specific variable string. For example, when you would like to ignore a time part from a date string, you can write as follows:

Note 8. Ellipsis

The parser supports ... (ellipsis) token. The above example can be also written like this:

compile(formatString)

• @param {string} formatString – A format string
• @returns {Array.<string>} A compiled object

If you are going to execute the format(), the parse() or the isValid() so many times with one string format, recommended to precompile and reuse it for performance.

preparse(dateString, arg)

• @param {string} dateString – A date and time string
• @param {string|Array.<string>} arg – A format string or its compiled object
• @returns {Object} A pre-parsed result object

This function takes exactly the same parameters with the parse(), but returns a date structure as follows unlike that:

date.preparse('Fri Jan 2015 02 23:14:05 GMT-0800', '    MMM YYYY DD HH:mm:ss [GMT]Z');

{
    Y: 2015,        // Year
    M: 1,           // Month
    D: 2,           // Day
    H: 23,          // 24-hour
    A: 0,           // Meridiem
    h: 0,           // 12-hour
    m: 14,          // Minute
    s: 5,           // Second
    S: 0,           // Millisecond
    Z: 480,         // Timsezone offset
    _index: 33,     // Pointer offset
    _length: 33,    // Length of the date string
    _match: 7       // Token matching count
}

This date structure provides a parsing result. You will be able to tell from it how the date string was parsed(, or why the parsing was failed).

isValid(arg1[, arg2])

• @param {Object|string} arg1 – A pre-parsed result object or a date and time string
• @param {string|Array.<string>} [arg2] – A format string or its compiled object
• @returns {boolean} Whether the date and time string is a valid date and time

This function takes either exactly the same parameters with the parse() or a date structure which the preparse() returns, evaluates the validity of them.

transform(dateString, arg1, arg2[, utc])

• @param {string} dateString – A date and time string
• @param {string|Array.<string>} arg1 – A format string or its compiled object before transformation
• @param {string|Array.<string>} arg2 – A format string or its compiled object after transformation
• @param {boolean} [utc] – Output as UTC
• @returns {string} A formatted string

This function transforms the format of a date string. The 2nd parameter, arg1, is the format string of it. Available token list is equal to the parse()‘s. The 3rd parameter, arg2, is the transformed format string. Available token list is equal to the format()‘s.

addYears(dateObj, years)

• @param {Date} dateObj – A Date object
• @param {number} years – Number of years to add
• @returns {Date} The Date object after adding the value

const now = new Date();
const next_year = date.addYears(now, 1);

addMonths(dateObj, months)

• @param {Date} dateObj – A Date object
• @param {number} months – Number of months to add
• @returns {Date} The Date object after adding the value

const now = new Date();
const next_month = date.addMonths(now, 1);

addDays(dateObj, days)

• @param {Date} dateObj – A Date object
• @param {number} days – Number of days to add
• @returns {Date} The Date object after adding the value

const now = new Date();
const yesterday = date.addDays(now, -1);

addHours(dateObj, hours)

• @param {Date} dateObj – A Date object
• @param {number} hours – Number of hours to add
• @returns {Date} The Date object after adding the value

const now = new Date();
const an_hour_ago = date.addHours(now, -1);

addMinutes(dateObj, minutes)

• @param {Date} dateObj – A Date object
• @param {number} minutes – Number of minutes to add
• @returns {Date} The Date object after adding the value

const now = new Date();
const two_minutes_later = date.addMinutes(now, 2);

addSeconds(dateObj, seconds)

• @param {Date} dateObj – A Date object
• @param {number} seconds – Number of seconds to add
• @returns {Date} The Date object after adding the value

const now = new Date();
const three_seconds_ago = date.addSeconds(now, -3);

addMilliseconds(dateObj, milliseconds)

• @param {Date} dateObj – A Date object
• @param {number} milliseconds – Number of milliseconds to add
• @returns {Date} The Date object after adding the value

const now = new Date();
const a_millisecond_later = date.addMilliseconds(now, 1);

subtract(date1, date2)

• @param {Date} date1 – A Date object
• @param {Date} date2 – A Date object
• @returns {Object} The result object of subtracting date2 from date1

isLeapYear(y)

• @param {number} y – A year to check
• @returns {boolean} Whether the year is a leap year

isSameDay(date1, date2)

• @param {Date} date1 – A Date object
• @param {Date} date2 – A Date object
• @returns {boolean} Whether the two dates are the same day (time is ignored)

locale([locale])

• @param {Function|string} [locale] – A locale installer or language code
• @returns {string} The current language code

It returns the current language code if called without any parameters.

To switch to any other language, call it with a locale installer or a language code.

import es from 'date-and-time/locale/es';

date.locale(es);  // Switch to Spanish

See LOCALE.md for details.

extend(extension)

• @param {Object} extension – An extension object
• @returns {void}

It extends this library. See EXTEND.md for details.

plugin(plugin)

• @param {Function|string} plugin – A plugin installer or plugin name
• @returns {void}

Plugin is a named extension object. By installing predefined plugins, you can easily extend this library. See PLUGINS.md for details.

Browser Support

Chrome, Firefox, Safari, Edge, and Internet Explorer 6+.

License

MIT