ts-time/Period

Consumption

import Period, {NULL_PERIOD, DAY_PERIOD, WEEK_PERIOD, MONTH_PERIOD, QUARTER_PERIOD, YEAR_PERIOD} from "ts-time/Period";

Default export#

Hierarchy#

  • abstract class Period

Description#

Comprises a fixed date/time interval in certain units of measurement. As opposed to Duration, it can comprise a variable-length interval such as month. Month duration varies from 28 to 31 days, but in terms of periods, month is a valid unit. Period is mainly involved to manipulate date/time-related objects such as LocalDate, LocalDateTime, OffsetDateTime and ZonedDateTime. In particular, ZonedDateTime.plusPeriod method adds a period to the respective date/time, not instant. It means that if you add DAY_PERIOD to a ZonedDateTime, the real time shift won't be 24 hours if time zone offset changes during this day, while LocalTime will truly stay the same:

const start = ZonedDateTime.parse("2019-10-27T00:00:00.000+02:00[Europe/Berlin]"), // Summer time
  end = start.plusPeriod(DAY_PERIOD);
expect(end.toString()).toBe("2019-10-28T00:00:00.000+01:00[Europe/Berlin]"); // Winter time
expect(end.epochMs - start.epochMs).toBe(25 * MS_PER_HOUR);

To ascertain a predictable fixed real time shift, you are supposed to add a Duration.

Period doesn't support alignment out of the box. For example, WEEK_PERIOD won't automatically snap your dates to MONDAY.

Current API doesn't support complex periods such as 1 month + 1 day, as their application depends on the order, and use cases of such periods are unclear.

Fields#

empty#

readonly empty: boolean

Indicates if this period is empty, i.e. an attempt to add it to any date any number of times always returns the same date.

Methods#

addToDate#

abstract (date: LocalDate, amount: number): LocalDate

date
Date to add the periods to.
amount
Number of period to add.
returns
Date shifted from date onwards by the specified number of these periods.
between#

abstract (start: LocalDate, end: LocalDate): number

start
Start date.
end
End date.
returns
Integer number of periods fitting between the specified dates, with the highest absolute value. If end date stands before start date, the result will not be positive. If this period is empty, the methods always returns NaN.
multiply#

(multiplier: number): Period

multiplier
Multiplier of the period.
returns
This period taken the specified number of times.

Static methods#

ofYears#

(years: number): Period

years
Number of years.
returns
Period representing the specified number of years.
ofQuarters#

(quarters: number): Period

quarters
Number of quarters.
returns
Period representing the specified number of quarters.
ofMonths#

(months: number): Period

months
Number of months.
returns
Period representing the specified number of months.
ofWeeks#

(weeks: number): Period

weeks
Number of weeks.
returns
Period representing the specified number of weeks.
ofDays#

(days: number): Period

days
Number of days.
returns
Period representing the specified number of days.

NULL_PERIOD#

NULL_PERIOD: Period

Null (empty) period. An attempt to add it to any date results in the same date.

DAY_PERIOD#

DAY_PERIOD: Period

Period representing a calendar day.

WEEK_PERIOD#

WEEK_PERIOD: Period

Period representing a calendar week (7 days).

MONTH_PERIOD#

MONTH_PERIOD: Period

Period representing a calendar month.

QUARTER_PERIOD#

QUARTER_PERIOD: Period

Period representing a calendar quarter (3 months).

YEAR_PERIOD#

YEAR_PERIOD: Period

Period representing a calendar year.