date-ex

한국어

Extensions for Date class.

This library is extensions for JavaScript Date class. If you use this library, you can modify Date class more easily and represent Date in any format.

date-ex is written by TypeScript, and published by JavaScript. So you can use this library in TypeScript code and JavaScript code also.

DateTime

Represent date and time.

DataTime instance is created with new keyword.

const date: DateTime = new DateTime();

If you pass parameter to constructor, you can create instance with specific date. Parameter type supports for undefined, null, number , string, Date, DateTime, json type(DateTimeParam).

const newDateByNumber : DateTime = new DateTime(1603722868252);

const newDateByString : DateTime = new DateTime('2020-10-26');

const newDateByDate : DateTime = new DateTime(new Date());

const newDateByDateTime : DateTime = new DateTime(new DateTime());

const newDateByDateTimeParam : DateTime = new DateTime({
	year : 2020,
	month : 10,
	date : 26
});

Getter - Basic fields

| Getter | Return type | Value Range | Description | Date methods | |---|---|---|---|---| | year | number | - | Returns year. | Date.getFullYear() | | month | number | 1 ~ 12 | Returns month. | Date.getMonth() | | date | number | 1 ~ 31 | Returns date. | Date.getDate() | | day | number | 0 ~ 6 | Returns number of day. | Date.getDay() | | hours | number | 0 ~ 23 | Returns hours. | Date.getHours() | | minutes | number | 0 ~ 59 | Returns minutes. | Date.getMinutes() | | seconds | number | 0 ~ 59 | Returns seconds. | Date.getSeconds() | | ms | number | 0 ~ 999 | Returns milliseconds. | Date.getMilliseconds() | | timezoneOffset | timezone | - | Returns timezone offset in minutes unit. | Date.getTimezoneOffset() |

• Compared to the Date class, get- prefix has been omitted for better convenience, uses the getter method not the function execution form. For the same reason, getMilliseconds() methods is provided as ms.

• month field range is not 0 ~ 11. This field represent the real month value 1 ~ 12

Getter - Extended fields

| Getter | Return type | Value Range | Description | |-------------------------|---|---|---------------------------------------------------------------| | quarter | number | 1 ~ 4 | Returns quarter of the date. | | weekOfYear | number | 1 ~ 53 | Returns the number of week of the date in the year. | | weekOfMonth | number | 1 ~ 5 | Returns the number of week of the date in the month. | | weeksOfYear | number | 52 ~ 53 | Returns the number of week in year. | | weeksOfMonth | number | 4 ~ 6 | Returns the number of week in month. | | dayOfYear | number | 1 ~ 365 | Returns the number of day in the year. | | daysOfYear | number | 1 ~ 366 | Returns the number of date in the year. | | lastDate | number | 28 ~ 31 | Returns the last date of the month. | | timezoneOffsetInHours | number | -12 ~ 14 | Returns the timezone offset in hours unit. | | isAm | boolean | true/false | Returns true for the morning and false for the afternoon. | | hours24 | number | 0 ~ 23 | Returns hours in 24 format. Same with hours. | | hours12 | number | 0 ~ 12 | Returns hours in 12 format. |

UTC fields

Returns date and time in UTC(Coordinated Universal Time). The year, month, date and time may change depending on the timezone. The minutes, seconds and milliseconds is not affected.

The timezoneOffset value in UTC is same with timezoneOffset value in DateTime instance.

const date: DateTime = new DateTime();
const utcDate: DateTime = date.UTC;

With another type

| Getter | Return Type | Description | |---|---|---| | valueOf() | number | Returns with Unix timestamp. Same with +new Date() and +new DateTime() | | toDate() | Date | Returns Date type. | | toISOString() | string | Returns with ISO string. Same with Date.toISOString(). | | toUTCString() | string | Returns with UTC string. Same with Date.toUTCString(). | | toJson() | object | Returns with DateTimeParam. |

Setter - Each fields

| Setter | Value Type | Description | Date Methods | |---|---|---|---| | year | number | Set year. | Date.setFullYear() | | month | number | Set month. | Date.setMonth() | | date | number | Set date. | Date.setDate() | | hours | number | Set hours. | Date.setHours() | | minutes | number | Set minutes. | Date.setMinutes() | | seconds | number | Set seconds. | Date.setSeconds() | | ms | number | Set milliseconds. | Date.setMilliseconds() |

• Compared to the Date class, set- prefix has been omitted for better convenience, uses the setter method not the function execution form. For the same reason, getMilliseconds() methods is provided as ms.

• If you don't change the year, month setter value range is not 0 ~ 11, but 1 ~ 12.

set(): DateTime

Set date and time with DateTimeParam. Each field can be omitted.

const date : DateTime = new DateTime();

// set with 27-Oct-2020
date.set({
	year : 2020,
	month : 10,
	date : 27
});

• If you don't change the year, month setter value range is not 0 ~ 11, but 1 ~ 12.

add(param: DateTimeParam | Duration | DurationParam): DateTime

DateTime type is not supported.

with DateTimeParam

Set to a specific date and time. If a value less than 0 is used, the previous date and time are set.

const date : DateTime = new DateTime();

// set to after 11 months.
date.add({
	year : 1,
	month : -1
});

with Duration

Set to the date and time moved by the duration.

const date : DateTime = new DateTime();
const duration : Duration = new Duration({
	months : 11
});

// set to after 11 months.
date.add(duration);

with DurationParam

Set to the date and time moved by the duration. If a value less than 0 is used, the previous date and time are set.

const date : DateTime = new DateTime();

// set to after 11 months.
date.add({
	months : 11
});

startOf(unit): DateTime, endOf(unit): DateTime

Returns the start/end date and time based on the unit passed as a factor.

unit: year, quarter, month, week, date, hours, minutes, seconds, ms

const date: DateTime = new DateTime();

console.log(date.startOf('year').toISOString()); // 2020-01-01T00:00:00.000Z
console.log(date.endOf('year').toISOString()); // 2020-12-31T23:59:59.999Z

format(): string

Returns string with the format.

| Token | Token string | Getter | Description | Value range | |---|---|---|---|---| | FormatToken.YearShort | YY | - | Converts to a 2-digit year. | 00 ~ 20, ... | | FormatToken.Year | YYYY | year | Converts to a 4-digit year. | 1970 ~ 2020, ... | | FormatToken.Quarter | Q | quarter | Converts to a quarter. | 1 ~ 4 | | FormatToken.Month | M | month | Converts to a month. | 1 ~ 12 | | FormatToken.MonthPadded | MM | - | Converts to a month with 2-digit. | 01 ~ 12 | | FormatToken.MonthStringShort | MMM | - | Converts to a short name month. | Jan ~ Dec | | FormatToken.MonthStringLong | MMMM | - | Converts to a long name month. | January ~ December | | FormatToken.Week | W | weekOfYear | Converts to a number of the week in year. | 1 ~ 53 | | FormatToken.WeekPadded | WW | - | Converts to a number of the week in year in 2-digit. | 01 ~ 53 | | FormatToken.WeekPaddedWithPrefix | Www | - | Converts to a number of the week in year in 2-digit with prefix W. | W01 ~ W53 | | FormatToken.DayOfYear | DDD | dayOfYear | Converts to a numbef of the day in year. | 1 ~ 365 | | FormatToken.DayOfYearPadded | DDDD | - | Converts to a number of the day in year in 3-digit. | 001 ~ 365 | | FormatToken.DayOfMonth | D | dayOfMonth | Converts to a number of the day in month. | 1 ~ 31 | | FormatToken.DayOfMonthPadded | DD | - | Converts to a number of the day in month in 2-digit. | 01 ~ 31 | | FormatToken.DayOfWeek | d | day | Converts to a number of day. | 0 ~ 6 | | FormatToken.DayOfWeekStringShort | dd | - | Converts to a short name day. | Su ~ Sa | | FormatToken.DayOfWeekStringMiddle | ddd | - | Converts to a middle name day. | Sun ~ Sat | | FormatToken.DayOfWeekStringLong | dddd | - | Converts to a long name day. | Sunday ~ Saturday | | FormatToken.MeridiemLower | a | - | Converts to am/pm in lower case. | am, pm | | FormatToken.MeridiemCapital | A | - | Converts to am/pm in upper case. | AM, PM | | FormatToken.Hours24 | H | hours, hours24 | Converts to a hours in 24 format. | 0 ~ 23 | | FormatToken.Hours24Padded | HH | - | Converts to a hours in 24 format in 2-digit. | 00 ~ 23 | | FormatToken.Hours12 | h | hours12 | Converts to a hours in 12 format. | 0 ~ 12 | | FormatToken.Hours12Padded | hh | - | Converts to a hours in 12 format in 2-digit. | 00 ~ 12 | | FormatToken.Minutes | m | minutes | Converts to a minutes. | 0 ~ 59 | | FormatToken.MinutesPadded | mm | - | Converts to a minutes in 2-digit. | 00 ~ 59 | | FormatToken.Seconds | s | seconds | Converts to a seconds. | 0 ~ 59 | | FormatToken.SecondsPadded | ss | - | Converts to a seconds in 2-digit. | 00 ~ 59 | | FormatToken.MilliSeconds | S | ms | Converts to a milliseconds. | 0 ~ 999 | | FormatToken.MilliSecondsPadded2 | SS | - | Converts to a milliseconds in 2-digit. | 00 ~ 99 | | FormatToken.MilliSecondsPadded3 | SSS | - | Converts to a milliseconds in 3-digit. | 000 ~ 999 |

Internationalization

You can set i18n in global context or each instance. If the setting in global and local is different, i18n is working with local setting.

If you set i18n value globally, new instances are set with that value.

console.log(DateTime.locale()); // 'en'

const date1: DateTime = new DateTime();
console.log(date1.locale()); // 'en'

DateTime.locale('ko-kr'); // set globally
console.log(DateTime.locale()); // 'ko-kr'

const date2: DateTime = new DateTime();
console.log(date2.locale()); // 'ko-kr'

const date3: DateTime = new DateTime();
date3.locale('en'); // set i18n locally
console.log(date3.locale()); // 'en'

Global DateTime.locale() and locale() methods in each instance without parameter returns current i18n value. If you want to set i18n value, pass language code to locale() methods.

Default value is en..

Warning

locale() methods uses ES6 import function. import function is working as Promise, so you should wait JavaScript 1 cycle after called locale() to load i18n file.

If the language code is invalid or the language file load fails after 1 cycle, the previous value will be restored.

DateTime.locale(): string

Set language in globally.

locale(): string

Set language in locally.

Language supports

| Language code | Name | |---|---| | en | English | | ko-kr | Korean (Korea) |

Compare methods

All compare methods can be received DateTimeUnit. The accuracy of the calculation is based on this unit, and if the unit is omitted, it is calculated in milliseconds.

| Methods | Return type | Description | |---|---|---| | diff() | number | Returns the difference value. | | isEqual() | boolean | Returns true if the date is same with the parameter. | | isBefore() | boolean | Returns true if the date is before than parameter. | | isBeforeOrEqual() | boolean | Returns true if the date is before than or equal with parameter. | | isAfter() | boolean | Returns true if the date is after than parameter. | | isAfterOrEqual() | boolean | Returns true if the date is after than or equal with parameter. | | isBetween() | boolean | Returns true if the date is between with 2 parameters. | | isAfterOrEqual() | boolean | Returns true if the date is between with 2 parameters or same with one parameter. |

const date1 : DateTime = new DateTime({
	year : 2020,
	month : 10,
	date : 20
});

const date2 : DateTime = new DateTime({
	year : 2020,
	month : 10,
	date : 27
});

console.log(date1.diff(date2, 'date')); // -7

console.log(date1.isEqual(date2, 'month')); // true

console.log(date1.isBefore(date2, 'date')); // true
console.log(date1.isBeforeOrEqual(date2, 'month')); // true

console.log(date1.isAfter(date2, 'date')); // false
console.log(date1.isBeforeOrEqual(date2, 'month')); // true

const date3 : DateTime = new DateTime({
  year : 2020,
  month : 10,
  date : 27
});

console.log(date2.isBetween(date1, date3, 'date')); // true
console.log(date2.isBetweenOrEqual(date1, date2, 'date')); // true

DateTimeParam, DateTimeParamEx

Represent date, time value. This object consists with this fields.

| Field | Field Type | Value Range | Description | |-----------|---|-------------|------------------------------------------------------| | year | number | - | Represents year. | | quarter | number | 1 ~ 4 | Represents quarter. (only for DateTimeParamEx) | | month | number | 1 ~ 12 | Represents month. | | week | number | 1 ~ 42 | Represents week number. (only for DateTimeParamEx) | | date | number | 1 ~ 31 | Represents date. | | hours | number | 0 ~ 23 | Represents hours. | | minutes | number | 0 ~ 59 | Represents minutes. | | seconds | number | 0 ~ 59 | Represents seconds. | | ms | number | 0 ~ 999 | Represents mlliseconds. |

• month field range is not 0 ~ 11. This field represent the real month value 1 ~ 12
• quarter, week are fields of DateTimeParamEx.

DateTimeUnit

Represents date and time unit.

| Token | Field | Type | Description | |---|---|---|---| | DateTimeUnit.Year | year | number | Represents year. | | DateTimeUnit.Quarter | quarter | number | Represents quarter. | | DateTimeUnit.Month | month | number | Represents month. | | DateTimeUnit.Week | week | number | Represents week number. | | DateTimeUnit.Date | date | number | Represents date. | | DateTimeUnit.Hours | hours | number | Represents hours. | | DateTimeUnit.Minutes | minutes | number | Represents minutes. | | DateTimeUnit.Seconds | seconds | number | Represents seconds. | | DateTimeUnit.Ms | ms | number | Represents milliseconds. |

Calendar

DateTime.getYearCalendar(): YearCalendar

Returns the year calendar for that year value of the instance. Time fields are set to 0.

Length of dates array field is same with the number of date in that year.

DateTime.getMonthCalendar(): MonthCalendar

Returns the month calendar for that month value of the instance. Time fields are set to 0.

Length of dates array field is same with the number of date in that month.

Duration

Represents duration.

Duration instance is created with new keyword.

const duration: Duration = new Duration();

If you pass parameter to constructor, you can create instance with specific duration. Parameter type supports for undefined, null, number, string, Duration, json type(DurationParam).

const newDurationByString : Duration = new Duration('PY2');

const newDurationByDuration : Duration = new Duration(new Duration());

const newDurationByDurationParam : Duration = new Duration({
  years : 2
});

Getter & Setter - Each fields

| Token | Field | Type | |---|---|---| | DurationUnit.Years | years | number | | DurationUnit.Months | months | number | | DurationUnit.Dates | dates | number | | DurationUnit.Hours | hours | number | | DurationUnit.Minutes | minutes | number | | DurationUnit.Seconds | seconds | number | | DurationUnit.Ms | ms | number |

const duration: Duration = new Duration(); // value : {}

duration.years = 2; // value : { years : 2 }
duration.ms = 1001; // value : { years : 2, seconds : 1, ms : 1} - with rebalancing

console.log(duration.seconds); // 1

add()

add (param : Duration | DurationParam) : Duration

If param is Duration or DurationParam, returns Duration.

add (param : DateTime | DateTimeParam) : DateTime

If param is DateTime or DateTimeParam, returns DateTime.

divide(count : number) : Duration[]

Divide total duration by count as Duration array.

const duration: Duration = { seconds: 1 };

console.log(duration.divide(4)); // 4 Duration instances with value of { ms : 250 }

DurationParam

Represent duration value. This object consists with this fields.

| Field | Field Type | Value Range | Description | |---|---|---|---| | years | number | - | Represents years. | | months | number | 1 ~ 12 | Represents months. | | dates | number | 1 ~ 31 | Represents dates. | | hours | number | 0 ~ 23 | Represents hours. | | minutes | number | 0 ~ 59 | Represents minutes. | | seconds | number | 0 ~ 59 | Represents seconds. | | ms | number | 0 ~ 999 | Represents milliseconds. |

DurationUnit

Represents duration unit.

| Token | Field | Type | Description | |---|---|---|---| | DurationUnit.Years | years | number | Represents years. | | DurationUnit.Quarters | quarters | number | Represents quarters. | | DurationUnit.Months | months | number | Represents months. | | DurationUnit.Weeks | weeks | number | Represents weeks. | | DurationUnit.Dates | dates | number | Represents dates. | | DurationUnit.Hours | hours | number | Represents hours. | | DurationUnit.Minutes | minutes | number | Represents minutes. | | DurationUnit.Seconds | seconds | number | Represents seconds. | | DurationUnit.Ms | ms | number | Represents milliseconds. |