time-ago-ts

Zero-dependency TypeScript library with 50+ Date helpers — toTimeAgo, business days, formatting, countdown, and more.

Built with ❤️ by Naresh Kumar Lokrey

Why time-ago-ts?

Raw JS:

const diff = Date.now() - new Date('2026-05-29').getTime()
// messy

With time-ago-ts:

import { toTimeAgo, daysRemaining } from 'time-ago-ts'
toTimeAgo(new Date(Date.now() - 1000 * 60 * 12)) // '12m ago'
daysRemaining(new Date('2026-06-10')) // 'N days left'

Installation

npm install time-ago-ts

yarn add time-ago-ts

pnpm add time-ago-ts

Quick Start

import { toTimeAgo, isBusinessDay, toIsoDateString, daysRemaining, toJulianDay } from 'time-ago-ts'

toTimeAgo(new Date())
isBusinessDay(new Date())
toIsoDateString(new Date())
daysRemaining(new Date(Date.now() + 86400000))
toJulianDay(new Date())

Usage (Node & React)

• Node (CommonJS):

const ds = require('time-ago-ts')
console.log(ds.toTimeAgo(new Date()))

• ESM / React (recommended for bundlers and tree-shaking):

import { toTimeAgo, toIsoDateString } from 'time-ago-ts'
console.log(toTimeAgo(new Date()))
console.log(toIsoDateString(new Date()))

Your package ships both ESM (dist/index.mjs) and CJS (dist/index.js) entries so it works in Node and browser bundlers (Create React App, Vite, Webpack) without extra config.

API Reference

Relative Time

toTimeAgo(date: Date, options?: { short?: boolean }) // '12m ago'

Calendar Flags

isToday(date: Date) // boolean
isYesterday(date: Date)
isTomorrow(date: Date)
isThisWeek(date: Date)

Time of Day

isMorning(date: Date)
isAfternoon(date: Date)
isEvening(date: Date)
isNight(date: Date)

Month & Quarter Flags

isFirstDayOfMonth(date: Date)
isLastDayOfMonth(date: Date)
daysInMonth(date: Date)

Business Days

isBusinessDay(date: Date)
addBusinessDays(date: Date, days: number)

Boundaries

startOfDay(date)
endOfDay(date)
startOfWeek(date)
endOfWeek(date)

Date Math

nextDay(date)
previousDay(date)
copyWith(date, fields)

Comparison

isSameDay(a,b)
isSameWeek(a,b)

Formatting

toDayAndMonth(date)
toFullHumanDate(date)
toTime12Hour(date)

Countdown

daysRemaining(date)
hoursRemaining(date)

Holiday & Fiscal

isPublicHoliday(date, holidays[])
toFiscalYear(date, { fiscalYearStartMonth?: number })

Julian Day

toJulianDay(date)
fromJulianDay(jd)

Zero Dependencies

time-ago-ts is implemented with pure TypeScript and uses no runtime dependencies, making it small and easy to include.

Inspired By

Inspired by the Flutter package date_formatter_codespark by Katayath Sai Kiran

License

MIT