date-fns

What is date-fns?

The date-fns npm package provides a comprehensive, yet simple and consistent toolset for manipulating JavaScript dates in a browser & Node.js. It offers a variety of functions to parse, validate, manipulate, and format dates.

What are date-fns's main functionalities?

Parsing Dates

Parse strings in ISO format to JavaScript Date objects.

const parseISO = require('date-fns/parseISO');
const result = parseISO('2023-04-12');

Formatting Dates

Format Date objects into strings with a given format.

const format = require('date-fns/format');
const result = format(new Date(2023, 3, 12), 'yyyy-MM-dd');

Comparing Dates

Compare two dates to determine if one comes before the other.

const isBefore = require('date-fns/isBefore');
const result = isBefore(new Date(2023, 3, 12), new Date(2023, 3, 13));

Manipulating Dates

Perform date calculations such as adding or subtracting time spans.

const addDays = require('date-fns/addDays');
const result = addDays(new Date(2023, 3, 12), 10);

Validating Dates

Check if a date is valid.

const isValid = require('date-fns/isValid');
const result = isValid(new Date('2023-04-12'));

Other packages similar to date-fns

moment

Moment.js is a legacy project, now in maintenance mode, which provides similar functionalities for parsing, validating, manipulating, and formatting dates. It's more object-oriented and mutable compared to the functional and immutable design of date-fns.

dayjs

Day.js is a lightweight date library that offers a similar API to Moment.js but with a smaller footprint. It is immutable and chainable, like date-fns, but with a different plugin system for extending functionality.

luxon

Luxon is a powerful, modern, and chainable library for working with dates and times. It offers a rich set of features for parsing, formatting, manipulating, and querying dates. It's built on the Intl API and provides time zone support out of the box, which is more comprehensive than date-fns's approach to time zones.

README

⚠️ Warning: the current main represents v3 pre-release version of the library. See v2 branch.

If you're participating in hacktoberfest, please send your PRs to main.

---

date-fns provides the most comprehensive, yet simple and consistent toolset
for manipulating JavaScript dates in a browser & Node.js.

📖  Documentation   |   🧑‍💻  JavaScript Jobs

---

It's like Lodash for dates

• It has 200+ functions for all occasions.
• Modular: Pick what you need. Works with webpack, Browserify, or Rollup and also supports tree-shaking.
• Native dates: Uses existing native type. It doesn't extend core objects for safety's sake.
• Immutable & Pure: Built using pure functions and always returns a new date instance.
• TypeScript & Flow: Supports both Flow and TypeScript
• I18n: Dozens of locales. Include only what you need.
• and many more benefits

import { compareAsc, format } from "date-fns";

format(new Date(2014, 1, 11), "yyyy-MM-dd");
//=> '2014-02-11'

const dates = [
  new Date(1995, 6, 2),
  new Date(1987, 1, 11),
  new Date(1989, 6, 10),
];
dates.sort(compareAsc);
//=> [
//   Wed Feb 11 1987 00:00:00,
//   Mon Jul 10 1989 00:00:00,
//   Sun Jul 02 1995 00:00:00
// ]

The library is available as an npm package. To install the package run:

npm install date-fns --save
# or with yarn
yarn add date-fns

Docs

See date-fns.org for more details, API, and other docs.

License

MIT © Sasha Koss

Changelog

v3.0.0 - 2023-12-18

Changed

• BREAKING: date-fns is now a dual-package with the support of both ESM and CommonJS. The files exports are now explicitly in the package.json. The ESM files now have .mjs extension.

• BREAKING: The package now has a flat structure, meaning functions are now named node_modules/date-fns/add.mjs, locales are node_modules/date-fns/locale/enUS.mjs, etc.

• BREAKING: Now all file content’s exported via named exports instead of export default, which will require change direct imports i.e. const addDays = require(‘date-fns/addDays’) to const { addDays } = require(‘date-fns/addDays’).

• BREAKING: TypeScript types are now completely rewritten, check out the d.ts files for more information.

• BREAKING: constants now is not exported via the index, so to import one use import { daysInYear } from "date-fns/constants";. It improves compatibility with setups that modularize imports like Next.js.

• BREAKING: Functions now don’t check the number of passed arguments, delegating this task to type checkers. The functions are now slimmer because of this.

• BREAKING The arguments are not explicitly converted to the target types. Instead, they are passed as is, delegating this task to type checkers.

• BREAKING: Functions that accept Interval arguments now do not throw an error if the start is before the end and handle it as a negative interval. If one of the properties in an Invalid Date, these functions also do not throw and handle them as invalid intervals.

  • areIntervalsOverlapping normalize intervals before comparison, so { start: a, end: b } is practically equivalent to { start: b, end: a }. When comparing intervals with one of the properties being Invalid Date, the function will return false unless the others are valid and equal, given the inclusive option is passed. Otherwise, and when even one of the intervals has both properties invalid, the function will always return false.

  • getOverlappingDaysInIntervals now normalizes intervals before comparison, so { start: a, end: b } is practically equivalent to { start: b, end: a }. If any of the intervals’ properties is an Invalid Date, the function will always return 0.

  • isWithinInterval now normalizes intervals before comparison, so { start: a, end: b } is practically equivalent to { start: b, end: a }. If any of the intervals’ properties is an Invalid Date, the function will always return false.

  • intervalToDuration now returns negative durations for negative intervals. If one or both of the interval properties are invalid, the function will return an empty object.

  • The eachXOfInterval functions (eachDayOfInterval, eachHourOfInterval, eachMinuteOfInterval, eachMonthOfInterval, eachWeekendOfInterval, eachWeekendOfMonth, eachWeekendOfYear, eachWeekOfInterval, eachYearOfInterval) now return a reversed array if the passed interval’s start is after the end. Invalid properties will result in an empty array. Functions that accept the step option now also allow negative, 0, and NaN values and return reversed results if the step is negative and an empty array otherwise.

• BREAKING: intervalToDuration now skips 0 values in the resulting duration, resulting in more compact objects with only relevant properties.

• BREAKING: roundToNearestMinutes now returns Invalid Date instead of throwing an error when nearestTo option is less than 1 or more than 30.

• BREAKING: IE is no longer supported.

• BREAKING: Now all functions use Math.trunc rounding method where rounding is required. The behavior is configurable on a per-function basis.

• BREAKING: Undocumented onlyNumeric option was removed from nn and sv locales. If you relied on it, please contact me.

• BREAKING: Flow is not supported anymore. If you relied on it, please contact me.

• BREAKING: The locales now use regular functions instead of the UTC version, which should not break any code unless you used locales directly.

Added

• All functions that accept date arguments now also accept strings.

• All functions now export options interfaces.

• Now functions allow passing custom Date extensions like UTCDate. They will detect and use the arguments constructor to generate the result of the same class.

• eachMonthOfInterval, eachQuarterOfInterval, eachWeekOfInterval, and eachYearOfInterval now accept the step option like most of the eachXOfInterval functions.

• A new interval function that validates interval, emulating the v2 interval functions behavior.

• differenceInX functions now accept options and allow setting up roundingMethod that configures how the result is rounded. Math.trunc is the default method.