country-date

Description

country-date is a simple and easy-to-use library to get date information based on country and timeZone. The main goal is to retrieve numerical data and formatted strings (YYYY-MM-DD and HH:MM:SS) for a specific country, with automatic timeZone assignment per country. It also provides manual timeZone specification.

The current version includes a getCountryDate function that handles all core functionality.

The basic lightweight version supports:

• Getting current UTC date/time information
• Getting current date/time information by country
• Getting current date/time information by timeZone
• Getting information from a specific object by country
• Getting information from a specific object by timeZone
• Adding/subtracting minutes, hours, days, months, and years to a date with country-specific results

Usage Examples:

const { getCountryDate } = require("country-date")

Get current UTC date/time

console.log(getCountryDate());
// countryDate value
{
  dateTime: 2025-03-10T01:55:44.216Z,
  date: '2025-03-09',
  hour: '22:55:44',
  segment: 'PM',
  timestamp: 1741571744216,
  country: '',
  numYear: 2025,
  numDay: 3,
  numMonth: 9,
  numHour: 22,
  numMin: 55,
  numSec: 44,
  timeZone: 'UTC',
  addDelta: [Function: addDelta]
}

Get current date/time by country

countryDate = getCountryDate({ country: "AR" });

// countryDate value
{
  dateTime: 2025-03-10T01:55:44.243Z,
  date: '2025-03-09',
  hour: '22:55:44',
  segment: 'PM',
  timestamp: 1741571744243,
  country: 'AR',
  numYear: 2025,
  numDay: 3,
  numMonth: 9,
  numHour: 22,
  numMin: 55,
  numSec: 44,
  timeZone: 'America/Argentina/Buenos_Aires',
  addDelta: [Function: addDelta]
}

Get current date/time by timeZone

Example for "America/Argentina/Mendoza". Will auto-complete the country.

countryDate = getCountryDate({ timeZone: "America/Argentina/Mendoza" })

// countryDate value
{
  dateTime: 2025-03-10T01:55:44.244Z,
  date: '2025-03-09',
  hour: '22:55:44',
  segment: 'PM',
  timestamp: 1741571744244,
  country: 'AR',
  numYear: 2025,
  numDay: 3,
  numMonth: 9,
  numHour: 22,
  numMin: 55,
  numSec: 44,
  timeZone: 'America/Argentina/Mendoza',
  addDelta: [Function: addDelta]
}

Get information from specific by country

countryDate = getCountryDate({
  date: new Date(1741569493719),
  country: "RU"
})

// countryDate value
{
  dateTime: 2025-03-10T01:18:13.719Z,
  date: '2025-03-09',
  hour: '22:18:13',
  segment: 'PM',
  timestamp: 1741569493719,
  country: 'RU',
  numYear: 2025,
  numDay: 3,
  numMonth: 9,
  numHour: 22,
  numMin: 18,
  numSec: 13,
  timeZone: 'Europe/Moscow',
  addDelta: [Function: addDelta]
}

Get information from specific by timeZone

countryDate = getCountryDate({
  date: new Date(1741569493719),
  timeZone: "Europe/Moscow",
});

// countryDate value
{
  dateTime: 2025-03-10T01:18:13.719Z,
  date: '2025-03-10',
  hour: '04:18:13',
  segment: 'AM',
  timestamp: 1741569493719,
  country: 'RU',
  numYear: 2025,
  numDay: 3,
  numMonth: 10,
  numHour: 4,
  numMin: 18,
  numSec: 13,
  timeZone: 'Europe/Moscow',
  addDelta: [Function: addDelta]
}

Get information with custom locales (see Date locales)

countryDate = getCountryDate({
  date: new Date(1741569493719),
  country: "AR",
  locales: "su"
})

// countryDate value
{
  dateTime: 2025-03-10T01:18:13.719Z,
  date: '9/3/2025',  //--> custom LocaleString date format
  hour: '22.18.13',  //--> custom LocaleString date format
  segment: 'PM',
  timestamp: 1741569493719,
  country: 'AR',
  numYear: 2025,
  numDay: 3,
  numMonth: 9,
  numHour: 22,
  numMin: 18,
  numSec: 13,
  timeZone: 'America/Argentina/Buenos_Aires', // *Auto with country incoming in options
  addDelta: [Function: addDelta]
}

addDelta function - Add/subtract time deltas

Allows adding minutes, hours, days, months, and years to a date and getting country-specific results. Returns a new countryDate with the operation applied to the original countryDate.

countryDate = getCountryDate({
date: new Date(1741569493719),
timeZone: "Europe/Moscow",
});
//countryDate value
{
  dateTime: 2025-03-10T01:18:13.719Z,
  date: '2025-03-10',
  hour: '04:18:13',
  segment: 'AM',
  timestamp: 1741569493719,
  country: 'RU',
  numYear: 2025,
  numDay: 3,
  numMonth: 10,
  numHour: 4,
  numMin: 18,
  numSec: 13,
  timeZone: 'Europe/Moscow',
  addDelta: [Function: addDelta]
}


console.log(dateCountryDate.addDelta(10, "minutes"));
//OUTPUT:
{
  dateTime: 2025-03-10T01:28:13.719Z,
  date: '2025-03-10',
  hour: '04:28:13',
  segment: 'AM',
  timestamp: 1741570093719,
  country: 'RU',
  numYear: 2025,
  numDay: 3,
  numMonth: 10,
  numHour: 4,
  numMin: 28,
  numSec: 13,
  timeZone: 'Europe/Moscow',
  addDelta: [Function: addDelta]
}


console.log(dateCountryDate.addDelta(10, "h"));
//OUTPUT
{
  dateTime: 2025-03-10T11:18:13.719Z,
  date: '2025-03-10',
  hour: '14:18:13',
  segment: 'PM',
  timestamp: 1741605493719,
  country: 'RU',
  numYear: 2025,
  numDay: 3,
  numMonth: 10,
  numHour: 14,
  numMin: 18,
  numSec: 13,
  timeZone: 'Europe/Moscow',
  addDelta: [Function: addDelta]
}

console.log(dateCountryDate.addDelta(10, "d"));
//OUTPUT
{
  dateTime: 2025-03-20T01:18:13.719Z,
  date: '2025-03-20',
  hour: '04:18:13',
  segment: 'AM',
  timestamp: 1742433493719,
  country: 'RU',
  numYear: 2025,
  numDay: 3,
  numMonth: 20,
  numHour: 4,
  numMin: 18,
  numSec: 13,
  timeZone: 'Europe/Moscow',
  addDelta: [Function: addDelta]
}

console.log(dateCountryDate.addDelta(10, "mon"));
//OUTPUT
{
  dateTime: 2026-01-10T01:18:13.719Z,
  date: '2026-01-10',
  hour: '04:18:13',
  segment: 'AM',
  timestamp: 1768007893719,
  country: 'RU',
  numYear: 2026,
  numDay: 1,
  numMonth: 10,
  numHour: 4,
  numMin: 18,
  numSec: 13,
  timeZone: 'Europe/Moscow',
  addDelta: [Function: addDelta]
}

console.log(dateCountryDate.addDelta(10, "y"));
//OUTPUT
{
  dateTime: 2035-03-10T01:18:13.719Z,
  date: '2035-03-10',
  hour: '04:18:13',
  segment: 'AM',
  timestamp: 2057102293719,
  country: 'RU',
  numYear: 2035,
  numDay: 3,
  numMonth: 10,
  numHour: 4,
  numMin: 18,
  numSec: 13,
  timeZone: 'Europe/Moscow',
  addDelta: [Function: addDelta]
}

References

https://en.wikipedia.org/wiki/List_of_tz_database_time_zones