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. Check the isLocaleLoaded value to see if the multilingual file has finished loading.

If the language code is invalid or the language file load fails, 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.

Name		Name	Last commit message	Last commit date
Latest commit History 158 Commits
spec		spec
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.mocharc.json		.mocharc.json
LICENSE		LICENSE
README-KR.md		README-KR.md
README.md		README.md
package.json		package.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.esm.json		tsconfig.esm.json
tsconfig.json		tsconfig.json

License

han41858/date-ex

Folders and files

Latest commit

History

Repository files navigation

date-ex

DateTime

Getter - Basic fields

Getter - Extended fields

UTC fields

With another type

Setter - Each fields

set(): DateTime

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

with DateTimeParam

with Duration

with DurationParam

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

format(): string

Internationalization

Warning

DateTime.locale(): string

locale(): string

Language supports

Compare methods

DateTimeParam, DateTimeParamEx

DateTimeUnit

Calendar

DateTime.getYearCalendar(): YearCalendar

DateTime.getMonthCalendar(): MonthCalendar

Duration

Getter & Setter - Each fields

add()

add (param : Duration | DurationParam) : Duration

add (param : DateTime | DateTimeParam) : DateTime

divide(count : number) : Duration[]

DurationParam

DurationUnit

About

Resources