Time Helper JS

A lightweight TypeScript utility library for date and time formatting operations. This package provides simple and intuitive functions to format dates, convert between time formats, calculate relative times, and perform date utilities.

Installation

npm install time-helper

Usage

Import the functions you need from the package. It works out-of-the-box with both ES Modules and CommonJS/TypeScript environments.

Quick Start Example

import { formatDate, timeAgo, msToSeconds, isWeekend } from 'time-helper';

// 1. Format a date into a custom string
const now = new Date();
console.log(formatDate(now, 'YYYY-MM-DD HH:mm:ss')); 
// Example Output: "2023-10-12 14:30:45"

// 2. Calculate relative times
console.log(timeAgo(Date.now() - 86400000)); 
// Output: "1 day ago"

// 3. Convert duration units
console.log(msToSeconds(5000)); 
// Output: 5

// 4. Easily check dates
console.log(isWeekend(new Date())); 
// Example Output: true or false

You can find all available utilities below in the API documentation.

API

Date Formatting

formatDate(date: Date | string | number, formatStr: string): string

Formats a date into a custom string format using tokens: YYYY, MM, DD, HH, mm, ss.

Example:

formatDate(new Date(), 'DD/MM/YYYY HH:mm:ss'); // '12/10/2023 19:30:00'
formatDate('2023-10-12T19:30:00.000+00:00', 'YYYY-MM-DD'); // '2023-10-12'

Time Conversion

to12Hour(isoTime: Date | string | number): string

Converts a date, ISO string, or timestamp to 12-hour time format (HH:MM AM/PM).

Example:

to12Hour(new Date()); // '07:30 PM'
to12Hour('2023-10-12T19:30:00.000+00:00'); // '07:30 PM'

to24Hour(isoTime: Date | string | number): string

Converts a date, ISO string, or timestamp to 24-hour time format (HH:MM AM/PM). Note: This seems to be a misnomer; it returns HH:MM with AM/PM.

Example:

to24Hour(new Date()); // '19:30 PM'
to24Hour('2023-10-12T19:30:00.000+00:00'); // '19:30 PM'

Current Time

now(): Date

Returns the current date and time.

Example:

now(); // 2023-10-12T19:30:00.000Z

getTime(): number

Returns the current time in milliseconds since Unix epoch.

Example:

getTime(); // 1697139000000

Duration Utilities

msToSeconds(ms: number): number

msToMinutes(ms: number): number

msToHours(ms: number): number

msToDays(ms: number): number

Converts milliseconds into the respective unit.

Example:

msToSeconds(5000); // 5
msToMinutes(120000); // 2

Relative Time

timeAgo(date: string | Date | number): string

Returns a human-readable string representing how long ago the given date was.

Example:

timeAgo('2023-10-11'); // '1 day ago'
timeAgo(new Date(Date.now() - 86400000)); // '1 day ago'

timeFromNow(date: string | Date | number): string

Returns a human-readable string representing how long from now the given date is.

Example:

timeFromNow('2023-10-13T19:30:00.000+00:00'); // 'in 1 day'

timeDiff(d1: string | Date | number, d2: string | Date | number, diff: 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years'): string

Calculates the difference between two dates in the specified unit.

Example:

timeDiff('2023-10-11T19:30:00.000+00:00', '2023-11-11T19:30:00.000+00:00', 'days'); // '31'

Date Utilities

isLeapYear(year: Date | string | number): boolean

Checks if the given year is a leap year.

Example:

isLeapYear(2024); // true
isLeapYear('2024-10-11'); // true

daysInMonth(year: number, month: number): number

Returns the number of days in the specified month and year.

Example:

daysInMonth(2023, 2); // 28
daysInMonth(2024, 2); // 29

isToday(date: string | Date | number): boolean

Checks if the given date is today.

Example:

isToday(new Date()); // true
isToday('2023-10-12'); // true (if today is 2023-10-12)

isYesterday(date: string | Date | number): boolean

Checks if the given date is yesterday.

Example:

isYesterday(new Date(Date.now() - 86400000)); // true

isTomorrow(date: string | Date | number): boolean

Checks if the given date is tomorrow.

Example:

isTomorrow(new Date(Date.now() + 86400000)); // true

isWeekend(date: string | Date | number): boolean

Checks if the given date falls on a weekend (Saturday or Sunday).

Example:

isWeekend(new Date('2023-10-14')); // true (Saturday)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.