High performance date manipulations


081.1.32 years ago3 years agoMinified + gzip package size for @korbiniankuhn/datetime in KB



Travis Coverage Known Vulnerabilities Dependencies Dev Dependencies npm npm-version code style: prettier license

High performance date manipulations.

This library just provides human readable functions for simple, mostly mathematical date operations. All operations are expecting a valid date object and do not check their input arguments to provide maximum performance. If you want immutability, use the clone function.

There are already a lot of very good libraries like momentjs, date-fns, dayjs or instadate.

Use this library, if you want:

  • the highest performance
  • have a moment like syntax

Don't use this library, if you need:

  • language internationalization
  • date input or output parsing support for various non-standard formats

All functions are tested against momentjs operations.


For installation use the Node Package Manager:

$ npm install --save @korbiniankuhn/datetime

or clone the repository:

$ git clone https://github.com/KorbinianKuhn/datetime

Getting started

const datetime = require('@korbiniankuhn/datetime');

/* Create new date object add two months and return native date object */
  .add(2, 'months')

/* An immutable usage */
  .subtract(1, 'year')

/* Create a new utc date */
  .add(2000, 'ms')

/* Use existing date */
datetime(new Date())


datetime().add(amount, unit): Add interval to date.

datetime().clone(): Create a copy of the date.

datetime().daysInMonth(): Get the number of days in month.

datetime().daysInQuarter(): Get the number of days in quarter.

datetime().daysInYear(): Get the number of days in year.

datetime().diff(date, unit): Get the difference between two dates.

datetime().endOf(unit): Set date to end of given interval.

datetime().getQuarter(): Get quarter of date in year. First quarter starts with 1.

datetime().get(unit): Get value of given unit.

datetime().isAfter(date, unit): Check if date is after another date.

datetime().isBefore(date, unit): Check if date is before another date.

datetime().isLeapYear(): Check if date is a leap year.

datetime().isSame(date, unit): Check if date is same as another date.

datetime().isSameOrAfter(date, unit): Check if date is same as or after another date.

datetime().isSameOrBefore(date, unit): Check if date is same as or after another date.

datetime().isUTC(): Returns if the DateTime object is in UTC mode.

datetime().isValid(): Check if date is valid.

datetime().set(value, unit): Set value of given unit.

datetime().startOf(unit): Set date to end of given interval.

datetime().subtract(amount, unit): Subtract interval from date.

datetime().toUTC(): Convert date to utc timezone.

datetime().unix(): Get a unix timestamp of the date (without milliseconds).


First you have to install all dependencies:

$ npm install

To execute all unit tests once, use:

$ npm test

To get information about the test coverage, use:

$ npm run test:coverage


Get involved and push in your ideas.

Do not forget to add corresponding tests to keep up 100% test coverage.


The MIT License

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.