@han41858/date-ex v0.0.10

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

• 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

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

Setter - Each fields

• 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.

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

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.

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.

• 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.

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

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.

DurationUnit

Represents duration unit.