{"id":10390,"library":"date-fns","title":"date-fns","description":"date-fns is a modern, modular JavaScript utility library providing over 200 functions for manipulating dates in browsers and Node.js. It operates on native `Date` objects, ensuring immutability and purity, and offers full TypeScript support and internationalization. The current stable version is 4.1.0, which includes first-class time zone support (introduced in v4.0.0), and the project maintains a faster release cadence compared to earlier major versions.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/date-fns/date-fns","tags":["javascript","typescript"],"install":[{"cmd":"npm install date-fns","lang":"bash","label":"npm"},{"cmd":"yarn add date-fns","lang":"bash","label":"yarn"},{"cmd":"pnpm add date-fns","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"date-fns is ESM-only since v3.","wrong":"const { format } = require('date-fns')","symbol":"format","correct":"import { format } from 'date-fns'"}],"quickstart":{"code":"import { compareAsc, format } from \"date-fns\";\n\n// Format a specific date\nconsole.log(format(new Date(2014, 1, 11), \"yyyy-MM-dd\"));\n//=> '2014-02-11'\n\n// Sort an array of dates\nconst dates = [\n  new Date(1995, 6, 2),\n  new Date(1987, 1, 11),\n  new Date(1989, 6, 10),\n];\ndates.sort(compareAsc);\nconsole.log(dates);\n//=> [\n//   Wed Feb 11 1987 00:00:00 GMT+...,\n//   Mon Jul 10 1989 00:00:00 GMT+...,\n//   Sun Jul 02 1995 00:00:00 GMT+...\n// ]","lang":"typescript","description":"This quickstart demonstrates how to use `format` to reformat a date string and `compareAsc` to sort an array of `Date` objects."},"warnings":[{"fix":"Upgrade `@date-fns/tz` to v1.0.2 or higher alongside date-fns v4.1.0+.","message":"Time zone functions (introduced in v4.0) require `@date-fns/tz` v1.0.2 for critical bug fixes and full functionality.","severity":"breaking","affected_versions":">=4.0.0 (date-fns) with <1.0.2 (@date-fns/tz)"},{"fix":"Review type definitions when upgrading to v4.0.0 if your codebase interacts with internal date-fns types.","message":"v4.0.0 introduced type-related breaking changes that primarily affect users explicitly relying on date-fns internal types.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to v3.3.1 or higher to resolve incorrect calculations in affected functions.","message":"Functions like `differenceInCalendarDays`, `getISOWeek`, and `getWeek` in v3.3.0 had calculation bugs due to incorrectly using `trunc` instead of `round`.","severity":"gotcha","affected_versions":"3.3.0"},{"fix":"Upgrade to v3.3.1 or higher for correct DST handling in `getOverlappingDaysInIntervals`.","message":"DST (Daylight Saving Time) issues in `getOverlappingDaysInIntervals` in v3.3.0 and prior could lead to inconsistent day counts.","severity":"gotcha","affected_versions":"<3.3.1"},{"fix":"Consult the documentation for `format` to use correct tokens or provide necessary options to avoid unintended behavior with protected tokens.","message":"Using protected tokens (e.g., `Y`, `D`) in `format` strings without passing a corresponding option can lead to unexpected behavior.","severity":"gotcha","affected_versions":">=3.1.0"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Upgrade to date-fns v4.1.0 or later. Ensure only valid `Date` objects or parseable date strings are passed to date-fns functions.","cause":"Internal `constructFrom` function throwing an exception when `null` (which is not allowed) is passed to date-fns functions.","error":"TypeError: date-fns function received null or undefined argument"},{"fix":"Upgrade to date-fns v3.3.0 or later to fix the sorting issue.","cause":"A bug in `getOverlappingDaysInIntervals` caused by incorrect sorting of interval components leading to an incorrect result of 0.","error":"getOverlappingDaysInIntervals returns 0 unexpectedly"},{"fix":"Upgrade to date-fns v3.0.6 or later to ensure correct interval comparisons.","cause":"A bug in `areIntervalsOverlapping` caused by incorrect sorting of the input intervals.","error":"areIntervalsOverlapping returns false for clearly overlapping intervals"},{"fix":"Upgrade to date-fns v3.3.1 or later to resolve the calculation errors.","cause":"Functions like `differenceInCalendarDays`, `getISOWeek`, `getWeek` in v3.3.0 incorrectly used `trunc` instead of `round` for calculations.","error":"Incorrect day count from differenceInCalendarDays or similar date-fns functions"},{"fix":"Upgrade to date-fns v3.2.0 or later to get improved type compatibility.","cause":"Type compatibility issues with higher-order functions from utility libraries like Lodash's `flow` or fp-ts's `pipe`.","error":"TypeScript types for date-fns not compatible with Lodash flow or fp-ts pipe"}],"ecosystem":"npm"}