Formata Data ·

Formata Data is a lightweight, dependency-free, and blazing fast JavaScript library for date manipulation, formatting, validation, and more. It makes working with dates in JavaScript simple, reliable, and fun—whether you need to parse, format, compare, or generate date ranges.

Why use formata-data?

• Tiny & Fast: No dependencies, minimal footprint, and optimized for performance.
• Simple API: Intuitive, consistent, and easy-to-use functions.
• Multi-language: English and Portuguese support for human-readable and weekday outputs.
• Business-Ready: Utilities for business days, holidays (Brazil), and date ranges.
• Modern & Compatible: Works with dd/mm/yyyy, Date objects, ISO strings, and Unix timestamps.
• Perfect for Node.js & Browsers: Use it anywhere JavaScript runs.

Installation

Install via npm:

npm install formata-data

Features & Functions

• getDateDiff
• validateDate
• getWritenDate
• dateToString
• addDays
• subtractDays
• formatDate
• parseDate
• isLeapYear
• getDayOfWeek
• compareDates
• startOfMonth
• endOfMonth
• daysInMonth
• toISODate
• fromISODate
• toUnixTimestamp
• fromUnixTimestamp
• getWeekNumber
• getQuarter
• isBusinessDay
• addBusinessDays
• getDateRange
• formatRelative
• isSameDay
• getHolidaysPT

Example Usage

const {
  addDays,
  formatDate,
  getDateDiff,
  isBusinessDay,
  formatRelative,
  getDateRange,
  toISODate,
  fromUnixTimestamp,
  getHolidaysPT,
} = require("formata-data");

formatDate(addDays("03/10/1997", 5)); // "08/10/1997"
getDateDiff("01/01/2022", "10/01/2022"); // 9
isBusinessDay("25/12/2024", getHolidaysPT(2024)); // false
formatRelative("01/10/2022", "03/10/2022", "en"); // "2 days ago"
getDateRange("01/10/2022", "03/10/2022"); // ["01/10/2022", "02/10/2022", "03/10/2022"]
toISODate("03/10/1997"); // "1997-10-03"
fromUnixTimestamp(876470400); // "03/10/1997"

Documentation

(Keep all previous function documentation here, and add new sections for the new functions, following the same style. For brevity, only the intro and feature list are shown here. Let me know if you want the full expanded documentation for all new functions as well!)

getDateDiff

Function that takes one or two dates and returns the difference in days between the dates.

const { getDateDiff } = require("formata-data");

getDateDiff("03/10/1997", "03/10/2022");
// returns 9131 (difference in days between dates)

getDateDiff("03/10/1997");
// with only one date, the second one is set as the current date.

getDateDiff("00/10/1997");
// if the date is invalid the function throws an error.

validateDate

Function that takes one date and returns true if the date is valid and false otherwise.

const { validateDate } = require("formata-data");

validateDate("03/10/1997");
// returns true

validateDate("00/10/1997");
// returns false

getWritenDate

Function that takes one date and returns the written form of it.

const { getWritenDate } = require("formata-data");

getWritenDate("03/10/1997");
// returns October 3th, 1997.

getWritenDate("03/10/1997", "pt");
// can be set to Portuguese returning: 03 de Outubro de 1997

getWritenDate("00/10/1997");
// returns an error message if the date is invalid.

dateToString

Function that takes a Date object and transforms it to a string in dd/mm/yyyy format.

const { dateToString } = require("formata-data");

dateToString(new Date());
// returns 13/02/2022 (the current date).

dateToString("03/10/1997");
// if the date is not type Date it returns an error message.

addDays

Adds a number of days to a date and returns a new Date object.

const { addDays, formatDate } = require("formata-data");

const newDate = addDays("03/10/1997", 5);
formatDate(newDate); // returns 08/10/1997

subtractDays

Subtracts a number of days from a date and returns a new Date object.

const { subtractDays, formatDate } = require("formata-data");

const newDate = subtractDays("03/10/1997", 3);
formatDate(newDate); // returns 30/09/1997

formatDate

Formats a date to a given string format. Supported tokens: DD, MM, YYYY, YY.

const { formatDate } = require("formata-data");

formatDate("03/10/1997", "YYYY-MM-DD"); // returns 1997-10-03
formatDate("03/10/1997", "DD/MM/YY"); // returns 03/10/97

parseDate

Parses a string into a Date object using a given format.

const { parseDate, formatDate } = require("formata-data");

const d = parseDate("1997-10-03", "YYYY-MM-DD");
formatDate(d); // returns 03/10/1997

isLeapYear

Checks if a year is a leap year.

const { isLeapYear } = require("formata-data");

isLeapYear(2000); // true
isLeapYear(1900); // false
isLeapYear(2024); // true

getDayOfWeek

Returns the day of the week for a date. Supports English ("en") and Portuguese ("pt").

const { getDayOfWeek } = require("formata-data");

getDayOfWeek("03/10/1997", "en"); // returns "Friday"
getDayOfWeek("03/10/1997", "pt"); // returns "Sexta-feira"

compareDates

Compares two dates. Returns -1 if the first is before the second, 1 if after, 0 if equal.

const { compareDates } = require("formata-data");

compareDates("03/10/1997", "04/10/1997"); // -1
compareDates("03/10/1997", "03/10/1997"); // 0
compareDates("04/10/1997", "03/10/1997"); // 1

startOfMonth

Returns a Date object for the first day of the month.

const { startOfMonth, formatDate } = require("formata-data");

formatDate(startOfMonth("15/10/1997")); // returns 01/10/1997

endOfMonth

Returns a Date object for the last day of the month.

const { endOfMonth, formatDate } = require("formata-data");

formatDate(endOfMonth("15/02/2020")); // returns 29/02/2020
formatDate(endOfMonth("15/02/2021")); // returns 28/02/2021

daysInMonth

Returns the number of days in the month of the given date.

const { daysInMonth } = require("formata-data");

daysInMonth("15/02/2020"); // 29
daysInMonth("15/02/2021"); // 28
daysInMonth("15/10/1997"); // 31

License

Formata Data is MIT licensed.