myeochil-js

myeochil-js is a versatile npm library designed to facilitate handling of holidays, dates, times and schedules.

There are date and time-related functions such as national holiday information, date/time conversion and calculation, positive/sound conversion, leap year confirmation, and schedule management

Whether you're developing a web application that requires accurate public holiday data, or a project management tool that needs comprehensive date handling capabilities, myeochil-js has you covered.

Features

myeochil-js offers a wide range of functionalities including:

Country-specific public holiday information: Provide fixed public holiday information for various countries.

Solar - lunar calendar conversion: Easily convert dates between solar and lunar calendars.

Time zone conversion and calculation: Convert and calculates time differences between time zones.

Date format conversion: Convert dates between different formats.

Leap year verification: Check whether a given year is a leap year.

Date calculation: Calculate the number of days between dates or arranges dates.

Age calculation: Determine a person's age based on their date of birth.

Date validity verification: Check that a given date is valid.

Future date calculation: Calculate the day of the week for future dates or the date for future days of the week.

Project schedule management: Manage the schedules of project.

Installation

Install myeochil-js using npm:

npm install myeochil-js

Usage

It supports both CommonJS and ES Modules, making it easily integrateable into a wide range of JavaScript projects.

//CommonJS
const { name } = require("myeochil-js");

//ES Module
import { name } from "myeochil-js";

Docs

Country-specific public holiday information

supported country code

Countries: 4
├── korea
├── china
├── us
│   ├── us-califonia
│   ├── us-massachusetts
│   ├── us-kansas
│   └── us-newyork
└── japan

getHolidays

Returns public holiday information by country. If only the country is entered, a list of public holidays for that country is returned. If country,year is provided, the dates and names of public holidays for that specific year are returned. Furthermore, if both country,year and month are inserted, public holiday information for that particular year and month is returned.

Type

function getHolidays(
    country: string,
    year?: number,
    month?: number
): HolidayInfo[] | string[]

HolidayInfo

Name	Type	Description
date	string	The holiday date
weekday	string	The day of the week as a string
name	string	The name of the holiday

Arguments

Name	Type	Description
country	string	Country code to search
year?	number	Year to search
month?	number	Month to search

Returns

Type	Description
Array<HolidayInfo>	An array containing all the public holidays' info.

Examples

console.log(getHolidays('korea', 2024));
// =>
 [
  { date: '2024-01-01', weekday: 'Monday', name: '신정' },
  { date: '2024-03-01', weekday: 'Friday', name: '삼일절' },
  { date: '2024-05-05', weekday: 'Sunday', name: '어린이날' },
  { date: '2024-06-06', weekday: 'Thursday', name: '현충일' },
  { date: '2024-08-15', weekday: 'Thursday', name: '광복절' },
  ...
]

isHoliday

Determines if a specific date is a public holiday. It takes the country (or state), date, and an optional description parameter that specifies whether to include information about the holiday. If the description option is set to true, it returns the name of the holiday as a string.

type

function isHoliday(
    country: string,
    date: TargetDate | string,
    description?: boolean
): boolean | string

TargetDate

Name	Type	Description
year	number	Year like YYYY
month	number	Month like MM
day	number	Day like DD

Arguments

Name	Type	Description
country	string	Country code to search
date	TargetDate \| string	Holiday's date
description?	boolean	Description inclusion

Returns

Type	Description
boolean	The date is holiday
string	Description of the holiday

Examples

console.log(isHoliday('korea', '2024-08-15', true));
// => 광복절

console.log(isHoliday('korea', '2024-08-15'));
// => true

console.log(isHoliday('korea', '2024-07-16'));
// => false

Solar - lunar calendar conversion

toLunar

converts a solar date to a lunar date.

type

function toLunar(
    date: TargetDate | string
): TargetDate | undefined

TargetDate

Name	Type	Description
year	number	Year like YYYY
month	number	Month like MM
day	number	Day like DD

Arguments

Name	Type	Description
date	TargetDate \| string	Date to convert into lunar date

Returns

Type	Description
TargetDate \| string	Lunar Date

Examples

console.log(toLunar('2023-06-01'));
// => { year: 2024, month: 4, day: 25 }

toSolar

converts a lunar date to a solar date.

type

function toSolar(
    date: TargetDate | string
): TargetDate | undefined

TargetDate

Name	Type	Description
year	number	Year like YYYY
month	number	Month like MM
day	number	Day like DD

Arguments

Name	Type	Description
date	TargetDate \| string	Date to convert into solar date

Returns

Type	Description
TargetDate \| string	Solar Date

Examples

console.log(toSolar('2024-04-25'));
// => { year: 2024, month: 6, day: 1 }

Time zone conversion and calculation

supported country code

├── Coordinated Universal Time
├── Korea
├── Argentina
|   └── Buenos Aires
├── Australia
|   ├── Australia(East)
|   └── Midway Island
├── American Samoa
├── Austria
├── Bangladesh
├── Bahrain
├── Belgium
├── Bhutan
├── Brazil
|   ├── Fernando de Noronha
|   └── São Paulo
├── Bulgaria
├── Canada
|   ├── Alberta
|   ├── Canada Atlantic
|   ├── Manitoba
|   ├── Montreal
|   ├── Quebec
|   └── Vancouver
├── Cambodia
├── Cape Verde
├── Chile
├── China
├── Hong Kong
├── Colombia
├── Cuba
├── Czech Republic
├── Denmark
|   ├── Denmark
|   └── Greenland
├── East Timor
├── Ecuador
├── Egypt
├── Fiji
├── Finland
├── France
├── Tahiti
├── Germany
├── Georgia
├── Greece
├── Guam
├── Iceland
├── Indonesia
|   ├── Indonesia(Central)
|   └── Indonesia(West)
├── Iraq
├── Italy
├── Japan
├── Kazakhstan
├── Kiribati
├── Kuwait
├── Kyrgyzstan
├── Laos
├── Libya
├── Malaysia
├── Maldives
├── Marshall Islands
├── Mexico
|   └── Mexico City
├── Micronesia
├── Mongolia
├── Nauru
├── New Caledonia
├── New Zealand
├── Oman
├── Palau
├── Papua New Guinea
├── Paraguay
├── Peru
├── Philippines
├── Poland
├── Portugal
|   ├── Azores
|   └── Lisbon
├── Puerto Rico
├── Qatar
├── Russia
├── Saipan
├── Saudi Arabia
├── Singapore
├── Solomon Island
├── South Georgia Island
├── Thailand
├── Turkey
├── UAE
├── United Kingdom
|   └── London
├── United States
|   ├── Arizona
|   ├── California
|   ├── Honolulu
|   ├── Illinois
|   ├── New York
|   ├── Utah
|   ├── USA Alaska
|   ├── USA Central
|   ├── USA Eastern
|   ├── USA Mountain
|   ├── USA Pacific
|   ├── Washington
|   └── Wisconsin
├── Uruguay
├── Uzbekistan
├── Vietnam
├── West African
└── Yemen

convertTimezone

Converts the time from the fromTimezone to the time of the toTimezone country. It takes a datetime in the format 'YYYY-MM-DD' as an argument and returns the converted time by applying the UTC offset difference between the two countries.

type

function convertTimezone(
    datetime: string,
    fromTimezone: string,
    toTimezone: string
): string

Arguments

Name	Type	Description
datetime	string	Date to convert like 'YYYY-MM-DD'
fromTimezone	string	Reference country
toTimezone	string	Target country

Returns

Type	Description
string	Converted Datetime

Examples

console.log(convertTimezone('2024-06-01 00:00:00', 'Korea', 'California'));
// => 2024-06-30 07:00:00

calTimezone

Returns the time difference between two countries. It takes the names of the specified countries as arguments and provides the time difference by subtracting the UTC offsets of the given countries.

type

function calTimezone(
    fromCity: string,
    toCity: string
): number

Arguments

Name	Type	Description
fromCity	string	Reference city
toCity	string	Target City

Returns

Type	Description
number	Time difference between fromCity and toCity

Examples

console.log(calTimezone('Korea', 'California'));
// => 17

Date format conversion

formatDate

Converts the format of a given date string. It splits the date argument based on the '-' delimiter. If the user specifies a desired output format, it returns the date in that format (MM-DD-YYYY, DD-MM-YYYY). If no format is specified, it returns an object literal containing all three formats.

type

function formatDate(
    date: string,
    format?: string
): string | { [key: string]: string }

Arguments

Name	Type	Description
date	string	Date to convert like 'YYYY-MM-DD'
format?	string	Target Format 'MM-DD-YYYY' \| 'DD-MM-YYYY'

Returns

Type	Description
string	Converted Datetime
Array<object>	An array containing Converted Datetime string.

Examples

console.log(formatDate(date1, 'MM-DD-YYYY'));
// => 06-01-2024

console.log(formatDate(date1, 'DD-MM-YYYY'));
// => 01-06-2024

console.log(formatDate(date1));
// =>
{
  'YYYY-MM-DD': '2024-06-01',
  'MM-DD-YYYY': '06-01-2024',
  'DD-MM-YYYY': '01-06-2024'
}

Leap year verification

isLeapYear

Check whether a given year is a leap year. If year is a leap yaer, then true will be returend.

type

function isLeapYear(
    year: number
): string | Boolean

Arguments

Name	Type	Description
year	number	Year to check for a leap year

Returns

Type	Description
boolean	The yaer is a leap year

Examples

console.log(isLeapYear(2024));
// => true

console.log(isLeapYear(2023));
// => false

Date calculation

calDaysBetween

Calculates the number of days between two input dates. dateStr1 and dateStr2 should be strings in the 'YYYY-MM-DD' format, and it returns the number of days between the two dates as a positive integer. Regardless of the order of dateStr1 and dateStr2, it calculates and returns the absolute difference in days between the two dates. Only two arguments can be entered. If more than two are entered, it calculates the difference in days using only the first two dates.

type

function calDaysBetween(
    dateStr1: string,
    dateStr2: string
): number

Arguments

Name	Type	Description
dateStr1	string	Date string like 'YYYY-MM-DD'
dateStr2	string	Date string like 'YYYY-MM-DD'

Returns

Type	Description
number	the number of days between the two dates

Examples

console.log(calDaysBetween('2024-05-07', '2024-05-20'));
// => 13

sortDate

Sorts a list of dates, which are strings in the 'YYYY-MM-DD' format, according to the specified option and returns the sorted list. If dates is empty, it returns an empty list. The default value for option is 'asce'. When option is 'asce', the dates are sorted in ascending (earliest to latest) order. When option is 'desc', the dates are sorted in descending (latest to earliest) order. If option contains any value other than these two, it defaults to 'asce' and returns the list sorted in ascending order.

type

function sortDates(
    dates: string[],
    option?: string
): string[]

Arguments

Name	Type	Description
dates	Arrary<string<	An array containing dates to sort
option?	string	sort criterion

Returns

Type	Description
Arrary<string<	A sorted array containing dates

Examples

const date1 = '2024-05-07'
const date2 = '2024-05-20'
const date3 = '2023-06-01'

console.log(sortDates([date1, date2, date3]));
// => [ '2023-06-01', '2024-05-07', '2024-05-20' ]

console.log(sortDates([date1, date2, date3], 'asce'));
// => [ '2024-05-07', '2024-05-20', '2023-06-01' ]

console.log(sortDates([date1, date2, date3], 'desc'));
// => [ '2024-05-20', '2024-05-07', '2023-06-01' ]

Age calculation

calAge

Calculates the age as a positive integer based on the difference from a referenceDate, using the birthDate. Both dates are in the 'YYYY-MM-DD' format. Age is calculated by considering the time of birth as 0 years old and increasing by 1 year with each birthday, so the age returned can vary depending on the birthday. If the referenceDate is earlier than the birthDate, it's not possible to calculate the age, and an error message is returned.

type

function calAge(
    birthDate: string,
    referenceDate: string
): number | string

Arguments

Name	Type	Description
birthDate	string	Date string like 'YYYY-MM-DD'
referenceDate	string	Date string like 'YYYY-MM-DD'

Returns

Type	Description
number	the age from birth date to reference date

Examples

console.log(calAge('2000-04-11', '2024-04-13'));
//=> 24

console.log(calAge('2000-04-11', '2024-04-11'));
// => 24

console.log(calAge('2000-04-11', '2024-04-12'));
// => 23

console.log(calAge('2024-04-30', '2000-04-11'));
// => Error: ReferenceDate is earlier than birthDate.

Date validity verification

isValidDate

Determines whether the given date sDate is a valid calendar date and returns a Boolean value. The parameter sDate is a string in the 'YYYY-MM-DD' format for which the validity needs to be checked. If sDate is a valid calendar date, it returns true, otherwise, it returns false.

type

function isValidDate(
    sDate: string
): string | Boolean

Arguments

Name	Type	Description
sDate	string	Date to check if it's valid

Returns

Type	Description
boolean	The date is valid

Examples

console.log(isValidDate("2024-03-31"));
// => true

console.log(isValidDate("2024-04-31"));
// => false

console.log(isValidDate(20240424));
// => Error: Invalid Date Argument. please input correct date. ex) YYYY-MM-DD

Future date calculation

getFutureDate

Finds the date corresponding to the given parameters and returns it in the 'YYYY-MM-DD' format. The parameters are: year, month, week and weekday. If weekday is not one of 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', or 'Saturday', it returns an error message 'Invalid weekday'. If all parameters are input correctly, it calculates and returns the corresponding date as a string in the 'YYYY-MM-DD' format.

type

function getFutureDate(
    year: number,
    month: number,
    week: number,
    weekday: string
): string

Arguments

Name	Type	Description
year	number	Year of Date
month	number	Month of Date
week	number	Week of Date
weekday	string	Weekday of Date : Sunday to Saturday

Returns

Type	Description
string	Date like 'YYYY-MM-DD'

Examples

console.log(getFutureDate(2024, 6, 1, "Wednesday"));
// => 2024-06-05

console.log(getFutureDate(2024, 6, 1, "Wen"));
// => Error: Invalid weekday

getFutureWeekday

Determines the day of the week for a given date and returns the day as a string. The parameter date is a string in the 'YYYY-MM-DD' format, and description is a boolean indicating whether to include additional information about the date. If date is a valid calendar date and description is true, it returns the day of the week in the format '{year} year {month} month {n}th week's {weekday}'. Additionally, if date is a valid calendar date and description is false, it returns the day of the week as 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', or 'Saturday', corresponding to the given date.

type

function getFutureWeekday(
    date: string,
    description?: string
): boolean

Arguments

Name	Type	Description
date	string	Date for getting weekday
description?	boolean	Detail inclusion

Returns

Type	Description
string	The weekday of date

Examples

console.log(getFutureWeekday("2024-06-01", true));
// => 2024 year 6 month 1th week's Saturday

console.log(getFutureWeekday("2024-06-01", false));
// => Saturday

console.log(getFutureWeekday("2024-06-01"));
// => Saturday

Project schedule management

getSchedules

Provides a functionality to query the schedules registered in the project. date is a string in 'YYYY-MM-DD' format. If the date is not provided, it returns all the schedules registered in the project. If the date is provided, it returns the schedules registered for that specific date. It returns a list of objects containing the name (name) and the next invocation date (nextInvocation) of each registered schedule. The next invocation date information includes time, zone, and locale. If there are no schedules registered, an empty list is returned.

type

function getSchedules(
  date?:string
): NamedJob[]

NamedJob NamedJob extends Job from node-schedule.

Name	Type	Description
name	string	Name of a Job

Arguments

Name	Type	Description
date?	string	Date to search shedules

Returns

Type	Description
Array<NamedJob>	An array containing jobs of project

Examples

console.log(getSchedules());
// => 
[
  {
    name: 'test1',
    nextInvocation: CronDate {
      _date: DateTime { ts: 2024-05-29T16:47:00.000+09:00, zone: Asia/Seoul, locale: ko-KR }
    }
  },
  {
    name: 'test2',
    nextInvocation: CronDate {
      _date: DateTime { ts: 2024-06-24T17:47:10.000+09:00, zone: Asia/Seoul, locale: ko-KR }
    }
  }
]

console.log(getSchedules('2024-05-29'));
// => 
[
  {
    name: 'test1',
    nextInvocation: CronDate {
      _date: DateTime { ts: 2024-05-29T16:47:00.000+09:00, zone: Asia/Seoul, locale: ko-KR }
    }
  }
]

printSchedules

Prints all schedules registered in the project. Unlike getSchedules(), it only retrieves the entire list of schedules and outputs a list containing only the names of each schedule. If there are no registered schedules, an empty list is output.

type

function printSchedules()

Examples

printSchedules();
// => [test1, test2, test3, test4]

addSchedule

Add annual or monthly schedules to the project. date parameter is a string in the format 'MM-DD HH:mm:ss' or 'DD HH:mm:ss', and name parameter is the name of the schedule to be registered. isRepeated parameter is a boolean that indicates whether the schedule is recurring, with a default value set to true. If the date is in the 'MM-DD HH:mm:ss' format, an annual schedule is registered for the specified date and time. If the date is in the 'DD HH:mm:ss' format, a monthly schedule is registered for the specified date and time. When the schedule is triggered, it outputs the schedule name and execution time to the console as an alert. If the alarm is successfully registered, the string 'add Schedule' is returned. If a schedule with the same name already exists in the project, a warning message indicating that the schedule already exists is returned.

An example where the name of the schedule is 'test1' and it is called.

test1 is called: Sat Jun 01 2024 00:30:00 GMT+0900 (대한민국 표준시)

type

function addSchedule (
    date: string,
    name: string,
    isRepeated?: boolean = true
): string

Arguments

Name	Type	Description
date	string	Date of schedule like 'MM-DD HH:mm:ss' or 'DD HH:mm:ss'
name	string	Name of schedule
isRepeated?	boolean	Repeating

Returns

Type	Description
string	`add Schedule`: A new schedule is registered successfully

Examples

console.log(addSchedule('05-29 16:47:00', 'test1', false));
// => add Schedule

addSchedule('24 17:00:10', 'test2', true);
addSchedule('24 20:00:10', 'test2', true);
//=> Error: Job test1 already exists.

addWeekSchedule

Add a weekly schedule to the project, differing from addSchedule() by accepting a day of the week. dayOfWeek parameter specifies the day of the week on which the schedule will be executed each week and is input as a string. time parameter specifies the time at which the schedule will be triggered on the given day, formatted as 'HH:mm:ss'. name parameter is the name of the schedule to be registered and must not duplicate any existing schedule names. isRepeated parameter is a boolean indicating whether the schedule is recurring, with a default value set to true. If the schedule is successfully registered, the string 'add Weekly Schedule' is returned. The schedule will be logged with its name and execution time at the specified time on the specified day of the week.

An example where the name of the schedule is 'test1' and it is called.

test1 is called: Sat Jun 01 2024 00:30:00 GMT+0900 (대한민국 표준시)

type

function addWeekSchedule(
    dayOfWeek: string,
    time: string,
    name: string,
    isRepeated?: boolean = true
): string

Arguments

Name	Type	Description
dayOfWeek	string	dayOfWeek of schedule : Sunday to Saturday
time	string	Time of schedule like 'HH:mm:ss'
name	string	Name of schedule
isRepeated?	boolean	Repeating

Returns

Type	Description
string	`add Weekly Schedule`: A new schedule is registered successfully

Examples

console.log(addWeekSchedule('Saturday', '17:00:00', 'test1'));
// => add Weekly Schedule

addSchedule('24 17:00:10', 'test2', true);
addWeeklySchedule('24 20:00:10', 'test2', true);
//=> Error: Job test1 already exists.

addIntervalSchedule

Add a schedule to be called at specified intervals of weeks. Unlike addWeekSchedule(), which calls a schedule every week, addIntervalSchedule() allows setting the interval of weeks for the recurring schedule. The parameters dayOfWeek, time, name, and isRepeated are the same as those for addWeekSchedule(). The weekInterval parameter is a positive integer that represents the interval of weeks for the schedule to repeat. For example, if the weekInterval is 2, the schedule will be called every 2 weeks. Like addWeekSchedule(), if the schedule is successfully registered, the string 'add Weekly Schedule' is returned. The schedule will be logged with its name and execution time at the specified time on the specified day of the week

An example where the name of the schedule is 'test1' and it is called.

test1 is called: Sat Jun 01 2024 00:30:00 GMT+0900 (대한민국 표준시)

type

function addIntervalSchedule(
    dayOfWeek: string,
    time: string,
    name: string, 
    weekInterval: number,
    isRepeated?: boolean = true
): string

Arguments

Name	Type	Description
dayOfWeek	string	dayOfWeek of schedule : Sunday to Saturday
time	string	Time of schedule like 'HH:mm:ss'
name	string	Name of schedule
weekInterval	number	Week Interval number
isRepeated?	boolean	Repeating

Returns

Type	Description
string	`add Weekly Schedule`: A new schedule is registered successfully

Examples

console.log(addIntervalSchedule('Saturday', '17:00:30', 'test4', 5));
// => add Weekly Schedule

deleteSchedule

Deletes a schedule from the project by its registered name. If the name of an unregistered schedule is provided, an error message is returned. If the schedule is successfully deleted, nothing is returned.

type

function deleteSchedule(
    name: string
): None | string

Arguments

Name	Type	Description
name	string	Name of schedule to delete

Examples

deleteSchedule('test3');

deleteSchedule('test3');
// => Schedule test3 is not found.

Dependencies

date-fns node-shcedule @types/node-schedule

NoEnemyTeam/myeochil-js

myeochil-js

Features

Installation

Usage

Docs

Country-specific public holiday information

getHolidays

isHoliday

Solar - lunar calendar conversion

toLunar

toSolar

Time zone conversion and calculation

convertTimezone

calTimezone

Date format conversion

formatDate

Leap year verification

isLeapYear

Date calculation

calDaysBetween

sortDate

Age calculation

calAge

Date validity verification

isValidDate

Future date calculation

getFutureDate

getFutureWeekday

Project schedule management

getSchedules

printSchedules

addSchedule

addWeekSchedule

addIntervalSchedule

deleteSchedule

Dependencies

License