intl-date-utils

Lightweight date utilities powered by the modern JavaScript Intl API.

Features:

• Zero dependencies
• Intl-based formatting
• Timezone aware
• Relative time utilities
• Small bundle size
• Works in Node.js and modern browsers
• Types enabled to work with TypeScript Projects

Installation

Using NPM

npm install @creowis/intl-date-utils

Using Yarn

yarn add @creowis/intl-date-utils

Using Pnpm

pnpm install @creowis/intl-date-utils

Usage

import { formatDate, timeAgo } from '@creowis/intl-date-utils'

formatDate(new Date())
timeAgo(new Date(Date.now() - 86400000))

Available Methods

Method	Description	Example
formatDate(date, locale?, style?)	Formats a date using locale-aware Intl date styles (full, long, medium, short).	formatDate(new Date(), "en-US", "long")
formatTime(date, locale?, style?)	Formats only the time portion of a date using Intl time styles.	formatTime(new Date(), "en-US")
formatDateTime(date, locale?, options?)	Formats date and time together with optional timezone support.	formatDateTime(new Date(), "en-US", { timeZone: "Asia/Tokyo" })
formatInTimezone(date, timeZone, locale?)	Formats a date in a specific timezone regardless of system timezone.	formatInTimezone(new Date(), "Asia/Tokyo")
toLocaleDateISO(date, timeZone?)	Returns a timezone-aware ISO calendar date string (YYYY-MM-DD). Useful for comparing dates across timezones.	toLocaleDateISO(new Date(), "UTC")
timeAgo(date, locale?)	Returns human-readable relative time like "3 days ago" or "in 2 hours".	timeAgo(new Date(Date.now() - 86400000))
getMonthNames(locale?, style?)	Returns an array of localized month names.	getMonthNames("en-US")
getDayNames(locale?, style?, startDay?)	Returns localized weekday names with optional start day (0 = Sunday, 1 = Monday).	getDayNames("en-US", "long", 1)
formatRange(start, end, locale?, style?)	Formats a date range using Intl range formatting.	formatRange(new Date("2026-03-10"), new Date("2026-03-15"))
isToday(date)	Returns true if the provided date is today.	isToday(new Date())
isYesterday(date)	Returns true if the date is yesterday.	isYesterday(new Date(Date.now() - 86400000))
isTomorrow(date)	Returns true if the date is tomorrow.	isTomorrow(addDays(new Date(), 1))
startOfDay(date)	Returns a new Date representing the start of the day (00:00:00).	startOfDay(new Date())
endOfDay(date)	Returns a new Date representing the end of the day (23:59:59.999).	endOfDay(new Date())
addDays(date, amount)	Adds or subtracts days from a date.	addDays(new Date(), 5)
addMonths(date, amount)	Adds or subtracts months from a date.	addMonths(new Date(), 2)
differenceInDays(a, b)	Returns the number of calendar days between two dates.	differenceInDays(new Date("2026-03-15"), new Date("2026-03-10"))
parseISO(value)	Parses an ISO date string and returns a Date object with validation.	parseISO("2026-03-15")
formatSmartDate(date, locale?)	Smart UI formatting (Today, Yesterday, relative time, or formatted date).	formatSmartDate(new Date())

Development

Install dependencies

npm install

Run tests

npm test

Build library

npm run build

Test Package Locally

Create npm tarball

npm pack

This generates:

intl-date-utils-1.0.0.tgz

You can test install locally:

npm install ./intl-date-utils-1.0.0.tgz

Publish to npm

Login

npm login

Publish

npm publish --access public

License

MIT

Change Log

CHANGE LOG

🤝 Contributing

Contributions are always welcome!

See CONTRIBUTING.md for ways to get started.

Please adhere to this project's code of conduct.

🙏 Support Us

This is an OSS project maintained by CreoWis. We need all the support we can get. Please give this project a ⭐️ to encourage and show that you liked it.

If you found the project helpful, consider supporting us with a ☕

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Tapas Adhikary 💻

Ajay Yadav 💻

This project follows the all-contributors specification. Contributions of any kind welcome!