@innostes/date-helper

A collection of utility functions for date and time formatting, including support for different time zones and custom date formats.

Features

• Date and Time Formatting:
  • Format dates and times based on specific time zones.
  • Custom date formats.
  • Human-readable date formats.
  • Calculate the difference between two dates.
  • Add or subtract days from a date.
  • Check if a year is a leap year.
  • Get the start and end of a day.

Installation

You can install the package from npm by running:

npm install @innostes/date-helper

Usage

Once the package is installed, you can import and use the date and time utility functions in your project.

Example of using date and time utilities

import DateTimeUtils from '@innostes/date-helper';

// Initialize with default country code (India)
const dateTimeUtils = new DateTimeUtils();

// Format date
const formattedDate = dateTimeUtils.formatDate(new Date());
console.log(formattedDate); // Output: '7/3/2025' (for India)

// Format time
const formattedTime = dateTimeUtils.formatTime(new Date());
console.log(formattedTime); // Output: '14:30:00' (for India)

// Format date and time
const formattedDateTime = dateTimeUtils.formatDateTime(new Date());
console.log(formattedDateTime); // Output: '7/3/2025 14:30:00' (for India)

// Convert to human-readable date
const readableDate = dateTimeUtils.formatToReadableDate(new Date());
console.log(readableDate); // Output: 'Friday, March 7, 2025' (for India)

// Get time difference
const timeDiff = dateTimeUtils.getTimeDifference('2025-03-07T00:00:00Z', '2025-03-08T00:00:00Z');
console.log(timeDiff); // Output: '1 day'

// Add days to date
const newDate = dateTimeUtils.addDaysToDate(new Date(), 5);
console.log(newDate); // Output: Date object with date 5 days later

// Check if a year is a leap year
const isLeap = dateTimeUtils.isLeapYear(2024);
console.log(isLeap); // Output: true

// Get start of the day
const startOfDay = dateTimeUtils.getStartOfDay(new Date());
console.log(startOfDay); // Output: Date object with time set to 00:00:00

// Get end of the day
const endOfDay = dateTimeUtils.getEndOfDay(new Date());
console.log(endOfDay); // Output: Date object with time set to 23:59:59.999

// Format with custom format
const customFormattedDate = dateTimeUtils.formatWithCustomFormat(new Date(), 'dd-MM-yyyy HH:mm:ss');
console.log(customFormattedDate); // Output: '07-03-2025 14:30:00' (for India)

API Reference

constructor(countryCode: string = 'IN', customDateFormat?: string)

Initializes the DateTimeUtils with a specific country code and optional custom date format.

• Parameters:
  • countryCode (string): The country code to use for date formatting.
  • customDateFormat (string, optional): Custom date format string.

formatDate(date: Date | string): string

Formats a date based on the country's specific date format and time zone.

• Parameters:
  • date (Date | string): The date to format.
• Returns:
  • string: The formatted date string.

formatTime(date: Date | string): string

Formats time based on the country's time zone.

• Parameters:
  • date (Date | string): The date to format.
• Returns:
  • string: The formatted time string.

formatDateTime(date: Date | string): string

Formats date and time to 'YYYY-MM-DD HH:mm:ss' based on the time zone and locale.

• Parameters:
  • date (Date | string): The date to format.
• Returns:
  • string: The formatted date and time string.

formatToReadableDate(date: Date | string): string

Converts a date to a human-readable format (e.g., "March 7, 2025") based on the time zone and locale.

• Parameters:
  • date (Date | string): The date to format.
• Returns:
  • string: The human-readable date string.

getTimeDifference(date1: Date | string, date2: Date | string): string

Gets the difference between two dates in days, hours, minutes, etc., considering time zones and locale.

• Parameters:
  • date1 (Date | string): The first date.
  • date2 (Date | string): The second date.
• Returns:
  • string: The difference between the two dates.

getCurrentDateTime(): string

Gets the current date and time in the format based on the country's time zone.

• Returns:
  • string: The current date and time string.

formatUnixTimestampToDate(timestamp: number): string

Converts a Unix timestamp to a formatted date based on the country's time zone.

• Parameters:
  • timestamp (number): The Unix timestamp to convert.
• Returns:
  • string: The formatted date string.

addDaysToDate(date: Date | string, days: number): Date

Adds or subtracts days from a given date, considering the time zone.

• Parameters:
  • date (Date | string): The date to modify.
  • days (number): The number of days to add (or subtract if negative).
• Returns:
  • Date: The new date with the added/subtracted days.

isLeapYear(year: number): boolean

Checks if a year is a leap year, based on the calendar.

• Parameters:
  • year (number): The year to check.
• Returns:
  • boolean: true if the year is a leap year, false otherwise.

getStartOfDay(date: Date | string): Date

Gets the start of the day (midnight) for a given date, considering the time zone.

• Parameters:
  • date (Date | string): The date to get the start of the day for.
• Returns:
  • Date: The start of the day.

getEndOfDay(date: Date | string): Date

Gets the end of the day (11:59:59.999) for a given date, considering the time zone.

• Parameters:
  • date (Date | string): The date to get the end of the day for.
• Returns:
  • Date: The end of the day.

formatWithCustomFormat(date: Date | string, customFormat: string): string

Formats date with a custom format passed as input.

• Parameters:
  • date (Date | string): The date to format.
  • customFormat (string): The custom format string.
• Returns:
  • string: The formatted date string.

License

This project is licensed under the MIT License by Innostes Solutions.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contact

For any inquiries or support, please contact us at:

• Email: [email protected]
• Website: https://www.innostes.com