utils-datetime

Easily handle and work with dates and times in your project. This library provides useful functions for working with dates and times in an easy and flexible way.

Installation

To install utils-datetime, simply run the following command in your terminal:

npm install utils-datetime

Import

import {
    getCurrentDate,
    timeTransform,
    dateTimeFormat,
    dateDiff,
    isLeapYear,
    currentWeekNumber,
    formatMilliseconds,
} from "utils-datetime";

Available Functions

• dateDiff = (dates: DateInterface, timePeriod: TimePeriod): is a function that calculates the time difference between two dates in milliseconds, seconds, minutes, hours, days, weeks, months, or years, depending on the specified time period.

interface DateInterface {
    start: Date | string;
    end: Date | string;
}

type TimePeriod =
    | "milliseconds"
    | "seconds"
    | "minutes"
    | "hours"
    | "days"
    | "weeks"
    | "months"
    | "years";

const dates = {
    start: new Date("2022-01-01"),
    end: new Date("2023-01-01"),
};

const result = dateDiff(dates, "days");
console.log(result);
// 365

• getCurrentDate(timezone: string = 'UTC', offset: string = '+0'): Returns the current date in the specified time zone, with optional time offset adjustment.

const now = getCurrentDate("America/Asuncion");
console.log(now);
// 2023-10-23T22:14:49.876Z

const later = getCurrentDate("America/Asuncion", "1h");
console.log(later);
// 2023-10-23T23:14:49.876Z

Supported offset formats:

Milliseconds: "+1000", "-2000" Seconds: "30s", "-45s" Minutes: "15m", "-10m" Hours: "1h", "-3h"

• timeTransform = (date: Date, timeDelta: ITimeDelta): Performs addition or subtraction operations on a date according to the provided options.

interface ITimeDelta {
    year?: number;
    month?: number;
    day?: number;
    hour?: number;
    minute?: number;
    second?: number;
}

const options = {
    year: -1,
    day: 1,
    hour: 1,
    minute: -3,
    second: 120,
    month: -1,
};
const now = getCurrentDate("America/Asuncion");
const transform = timeTransform(now, options);
console.log(transform);
// 2022-09-25T00:26:06.078Z

• dateTimeFormat = (date: Date, template: string, language: string = 'en-EN'): Formats the date according to the specified template and language.

const now = getCurrentDate("America/Asuncion");
const template =
    "Today is %DAY%, %MONTH% %DD%rd of the year %YYYY%, the time is %H%:%MI% %A%";
const format = dateTimeFormat(now, template, "es-EN");
console.log(format);
// Today is Monday, October 23rd of the year 2023, the time is 10:20 PM.

const now = getCurrentDate("America/Asuncion");
const template =
    "Today is %DAY%, %MONTH% %DD%rd of the year %YYYY%, the time is %HH%:%MI%:%SS% with %MS% milliseconds";
const format = dateTimeFormat(now, template, "es-EN");
console.log(format);
// Today is Monday, October 23rd of the year 2023, the time is 22:20:20 with 345 milliseconds.

const now = getCurrentDate("America/Asuncion");
const template = "%DD%/%MM%/%YYYY% %HH%:%MI%";
const format = dateTimeFormat(now, template);
console.log(format);
// 23/10/2023 22:20
// %HH% 23h format

const now = getCurrentDate("America/Asuncion");
const template = "%DD%/%MM%/%YYYY% %H%:%MI% %A%";
const format = dateTimeFormat(now, template);
console.log(format);
// 23/10/2023 10:20 PM
// %H% 12h format

• const isLeapYear = (yearInterface: YearInterface): checks if a given year (after 1582) is a leap year according to the Gregorian calendar.

type YearInterface = number | string;

const leapYear = isLeapYear(2024);
console.log(leapYear);
// true

• const currentWeekNumber = (date: Date | string): takes a Date or date string, calculates and returns the ISO week number, assuming a Monday start.

const result = currentWeekNumber("2023-02-27");
console.log(result);
// 9

• const formatMilliseconds = (milliseconds: number | string, includeMS: boolean = false): takes a time value in milliseconds (as a string or number) and returns it as HH:MM:SS. If includeMS is true, it adds milliseconds as HH:MM:SS.MS

const result = formatMilliseconds(3661000);
console.log(result);
// 01:01:01