timezonecomplete
Version:
DateTime, TimeZone, Duration and Period library aimed at providing a consistent and complete date-time interface, away from the original JavaScript Date class.
659 lines (658 loc) • 25.9 kB
TypeScript
/**
* Copyright(c) 2014 ABB Switzerland Ltd.
*
* Date+time+timezone representation
*/
import { TimeStruct, TimeUnit, WeekDay } from "./basics";
import { Duration } from "./duration";
import { DateFunctions } from "./javascript";
import { PartialLocale } from "./locale";
import { TimeSource } from "./timesource";
import { TimeZone } from "./timezone";
/**
* Current date+time in local time
* @throws nothing
*/
export declare function nowLocal(): DateTime;
/**
* Current date+time in UTC time
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
export declare function nowUtc(): DateTime;
/**
* Current date+time in the given time zone
* @param timeZone The desired time zone (optional, defaults to UTC).
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
export declare function now(timeZone?: TimeZone | undefined | null): DateTime;
/**
* DateTime class which is time zone-aware
* and which can be mocked for testing purposes.
*/
export declare class DateTime {
/**
* Allow not using instanceof
*/
kind: string;
/**
* UTC timestamp (lazily calculated, use getter for utcDate instead)
*/
private _utcDate?;
/**
* UTC timestamp (lazily calculated)
* @throws nothing
*/
private get utcDate();
private set utcDate(value);
/**
* Local timestamp (lazily calculated)
*/
private _zoneDate?;
/**
* Local timestamp (lazily calculated)
* @throws nothing
*/
private get zoneDate();
private set zoneDate(value);
/**
* Original time zone this instance was created for.
* Can be undefined for unaware timestamps
*/
private _zone?;
/**
* Actual time source in use. Setting this property allows to
* fake time in tests. DateTime.nowLocal() and DateTime.nowUtc()
* use this property for obtaining the current time.
*/
static timeSource: TimeSource;
/**
* Current date+time in local time
* @throws nothing
*/
static nowLocal(): DateTime;
/**
* Current date+time in UTC time
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
static nowUtc(): DateTime;
/**
* Current date+time in the given time zone
* @param timeZone The desired time zone (optional, defaults to UTC).
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
static now(timeZone?: TimeZone | null | undefined): DateTime;
/**
* Create a DateTime from a Lotus 123 / Microsoft Excel date-time value
* i.e. a double representing days since 1-1-1900 where 1900 is incorrectly seen as leap year
* Does not work for dates < 1900
* @param n excel date/time number
* @param timeZone Time zone to assume that the excel value is in
* @returns a DateTime
* @throws timezonecomplete.Argument.N if n is not a finite number
* @throws timezonecomplete.Argument.TimeZone if the given time zone is invalid
*/
static fromExcel(n: number, timeZone?: TimeZone | null | undefined): DateTime;
/**
* Check whether a given date exists in the given time zone.
* E.g. 2015-02-29 returns false (not a leap year)
* and 2015-03-29T02:30:00 returns false (daylight saving time missing hour)
* and 2015-04-31 returns false (April has 30 days).
* By default, pre-1970 dates also return false since the time zone database does not contain accurate info
* before that. You can change that with the allowPre1970 flag.
*
* @param allowPre1970 (optional, default false): return true for pre-1970 dates
* @throws nothing
*/
static exists(year: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, millisecond?: number, zone?: TimeZone | null | undefined, allowPre1970?: boolean): boolean;
/**
* Constructor. Creates current time in local timezone.
* @throws nothing
*/
constructor();
/**
* Constructor. Parses ISO timestamp string.
* Non-existing local times are normalized by rounding up to the next DST offset.
*
* @param isoString String in ISO 8601 format. Instead of ISO time zone,
* it may include a space and then and IANA time zone.
* e.g. "2007-04-05T12:30:40.500" (no time zone, naive date)
* e.g. "2007-04-05T12:30:40.500+01:00" (UTC offset without daylight saving time)
* or "2007-04-05T12:30:40.500Z" (UTC)
* or "2007-04-05T12:30:40.500 Europe/Amsterdam" (IANA time zone, with daylight saving time if applicable)
* @param timeZone if given, the date in the string is assumed to be in this time zone.
* Note that it is NOT CONVERTED to the time zone. Useful
* for strings without a time zone
* @throws timezonecomplete.Argument.S if the given string is invalid
* @throws timezonecomplete.Argument.TimeZone if the given time zone is invalid
*/
constructor(isoString: string, timeZone?: TimeZone | null | undefined);
/**
* Constructor. Parses string in given LDML format.
* NOTE: does not handle eras/quarters/weeks/weekdays.
* Non-existing local times are normalized by rounding up to the next DST offset.
*
* @param dateString Date+Time string.
* @param formatString The LDML format that the string is assumed to be in
* @param timeZone if given, the date in the string is assumed to be in this time zone.
* Note that it is NOT CONVERTED to the time zone. Useful
* for strings without a time zone
* @throws timezonecomplete.ParseError if the given dateTimeString is wrong or not according to the pattern
* @throws timezonecomplete.Argument.FormatString if the given format string is invalid
* @throws timezonecomplete.Argument.Timezone if the given time zone is invalid
*/
constructor(dateString: string, formatString: string, timeZone?: TimeZone | null | undefined);
/**
* Constructor. You provide a date, then you say whether to take the
* date.getYear()/getXxx methods or the date.getUTCYear()/date.getUTCXxx methods,
* and then you state which time zone that date is in.
* Non-existing local times are normalized by rounding up to the next DST offset.
* Note that the Date class has bugs and inconsistencies when constructing them with times around
* DST changes.
*
* @param date A date object.
* @param getters Specifies which set of Date getters contains the date in the given time zone: the
* Date.getXxx() methods or the Date.getUTCXxx() methods.
* @param timeZone The time zone that the given date is assumed to be in (may be undefined or null for unaware dates)
* @throws timezonecomplete.Argument.GetFuncs if the getFuncs argument is invalid
* @throws timezonecomplete.Argument.TimeZone if the time zone argument is invalid
*/
constructor(date: Date, getFuncs: DateFunctions, timeZone?: TimeZone | null | undefined);
/**
* Get a date from a TimeStruct
* @throws timezonecomplete.Argument.TimeZone if the given time zone argument is invalid
*/
constructor(tm: TimeStruct, timeZone?: TimeZone | null | undefined);
/**
* Constructor. Note that unlike JavaScript dates we require fields to be in normal ranges.
* Use the add(duration) or sub(duration) for arithmetic.
* @param year The full year (e.g. 2014)
* @param month The month [1-12] (note this deviates from JavaScript Date)
* @param day The day of the month [1-31]
* @param hour The hour of the day [0-24)
* @param minute The minute of the hour [0-59]
* @param second The second of the minute [0-59]
* @param millisecond The millisecond of the second [0-999]
* @param timeZone The time zone, or null/undefined (for unaware dates)
* @throws timezonecomplete.Argument.Year if year invalid
* @throws timezonecomplete.Argument.Month if month invalid
* @throws timezonecomplete.Argument.Day if day invalid
* @throws timezonecomplete.Argument.Hour if hour invalid
* @throws timezonecomplete.Argument.Minute if minute invalid
* @throws timezonecomplete.Argument.Second if second invalid
* @throws timezonecomplete.Argument.Milli if milliseconds invalid
*/
constructor(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number, timeZone?: TimeZone | null | undefined);
/**
* Constructor
* @param unixTimestamp milliseconds since 1970-01-01T00:00:00.000
* @param timeZone the time zone that the timestamp is assumed to be in (usually UTC).
* @throws timezonecomplete.Argument.TimeZone if the given time zone is invalid
* @throws timezonecomplete.Argument.UnixMillis if the given unix timestamp is not finite
*/
constructor(unixTimestamp: number, timeZone?: TimeZone | null | undefined);
/**
* @return a copy of this object
* @throws nothing
*/
clone(): DateTime;
/**
* @return The time zone that the date is in. May be undefined for unaware dates.
* @throws nothing
*/
zone(): TimeZone | undefined;
/**
* Zone name abbreviation at this time
* @param dstDependent (default true) set to false for a DST-agnostic abbreviation
* @return The abbreviation
* @throws nothing
*/
zoneAbbreviation(dstDependent?: boolean): string;
/**
* @return the offset including DST w.r.t. UTC in minutes. Returns 0 for unaware dates and for UTC dates.
* @throws nothing
*/
offset(): number;
/**
* @return the offset including DST w.r.t. UTC as a Duration.
* @throws nothing
*/
offsetDuration(): Duration;
/**
* @return the standard offset WITHOUT DST w.r.t. UTC as a Duration.
* @throws nothing
*/
standardOffsetDuration(): Duration;
/**
* @return The full year e.g. 2014
* @throws nothing
*/
year(): number;
/**
* @return The month 1-12 (note this deviates from JavaScript Date)
* @throws nothing
*/
month(): number;
/**
* @return The day of the month 1-31
* @throws nothing
*/
day(): number;
/**
* @return The hour 0-23
* @throws nothing
*/
hour(): number;
/**
* @return the minutes 0-59
* @throws nothing
*/
minute(): number;
/**
* @return the seconds 0-59
* @throws nothing
*/
second(): number;
/**
* @return the milliseconds 0-999
* @throws nothing
*/
millisecond(): number;
/**
* @return the day-of-week (the enum values correspond to JavaScript
* week day numbers)
* @throws nothing
*/
weekDay(): WeekDay;
/**
* Returns the day number within the year: Jan 1st has number 0,
* Jan 2nd has number 1 etc.
*
* @return the day-of-year [0-366]
* @throws nothing
*/
dayOfYear(): number;
/**
* The ISO 8601 week number. Week 1 is the week
* that has January 4th in it, and it starts on Monday.
* See https://en.wikipedia.org/wiki/ISO_week_date
*
* @return Week number [1-53]
* @throws nothing
*/
weekNumber(): number;
/**
* The week of this month. There is no official standard for this,
* but we assume the same rules for the weekNumber (i.e.
* week 1 is the week that has the 4th day of the month in it)
*
* @return Week number [1-5]
* @throws nothing
*/
weekOfMonth(): number;
/**
* Returns the number of seconds that have passed on the current day
* Does not consider leap seconds
*
* @return seconds [0-86399]
* @throws nothing
*/
secondOfDay(): number;
/**
* @return Milliseconds since 1970-01-01T00:00:00.000Z
* @throws nothing
*/
unixUtcMillis(): number;
/**
* @return The full year e.g. 2014
* @throws nothing
*/
utcYear(): number;
/**
* @return The UTC month 1-12 (note this deviates from JavaScript Date)
* @throws nothing
*/
utcMonth(): number;
/**
* @return The UTC day of the month 1-31
* @throws nothing
*/
utcDay(): number;
/**
* @return The UTC hour 0-23
* @throws nothing
*/
utcHour(): number;
/**
* @return The UTC minutes 0-59
* @throws nothing
*/
utcMinute(): number;
/**
* @return The UTC seconds 0-59
* @throws nothing
*/
utcSecond(): number;
/**
* Returns the UTC day number within the year: Jan 1st has number 0,
* Jan 2nd has number 1 etc.
*
* @return the day-of-year [0-366]
* @throws nothing
*/
utcDayOfYear(): number;
/**
* @return The UTC milliseconds 0-999
* @throws nothing
*/
utcMillisecond(): number;
/**
* @return the UTC day-of-week (the enum values correspond to JavaScript
* week day numbers)
* @throws nothing
*/
utcWeekDay(): WeekDay;
/**
* The ISO 8601 UTC week number. Week 1 is the week
* that has January 4th in it, and it starts on Monday.
* See https://en.wikipedia.org/wiki/ISO_week_date
*
* @return Week number [1-53]
* @throws nothing
*/
utcWeekNumber(): number;
/**
* The week of this month. There is no official standard for this,
* but we assume the same rules for the weekNumber (i.e.
* week 1 is the week that has the 4th day of the month in it)
*
* @return Week number [1-5]
* @throws nothing
*/
utcWeekOfMonth(): number;
/**
* Returns the number of seconds that have passed on the current day
* Does not consider leap seconds
*
* @return seconds [0-86399]
* @throws nothing
*/
utcSecondOfDay(): number;
/**
* Returns a new DateTime which is the date+time reinterpreted as
* in the new zone. So e.g. 08:00 America/Chicago can be set to 08:00 Europe/Brussels.
* No conversion is done, the value is just assumed to be in a different zone.
* Works for naive and aware dates. The new zone may be null.
*
* @param zone The new time zone
* @return A new DateTime with the original timestamp and the new zone.
* @throws nothing
*/
withZone(zone?: TimeZone | null | undefined): DateTime;
/**
* Convert this date to the given time zone (in-place).
* @return this (for chaining)
* @throws timezonecomplete.UnawareToAwareConversion if you try to convert a datetime without a zone to a datetime with a zone
*/
convert(zone?: TimeZone | null | undefined): DateTime;
/**
* Returns this date converted to the given time zone.
* Unaware dates can only be converted to unaware dates (clone)
* Converting an unaware date to an aware date throws an exception. Use the constructor
* if you really need to do that.
*
* @param zone The new time zone. This may be null or undefined to create unaware date.
* @return The converted date
* @throws timezonecomplete.UnawareToAwareConversion if you try to convert a naive datetime to an aware one.
*/
toZone(zone?: TimeZone | null | undefined): DateTime;
/**
* Convert to JavaScript date with the zone time in the getX() methods.
* Unless the timezone is local, the Date.getUTCX() methods will NOT be correct.
* This is because Date calculates getUTCX() from getX() applying local time zone.
* @throws nothing
*/
toDate(): Date;
/**
* Create an Excel timestamp for this datetime converted to the given zone.
* Does not work for dates < 1900
* @param timeZone Optional. Zone to convert to, default the zone the datetime is already in.
* @return an Excel date/time number i.e. days since 1-1-1900 where 1900 is incorrectly seen as leap year
* @throws timezonecomplete.UnawareToAwareConversion if you try to convert a naive datetime to an aware one.
*/
toExcel(timeZone?: TimeZone | null | undefined): number;
/**
* Create an Excel timestamp for this datetime converted to UTC
* Does not work for dates < 1900
* @return an Excel date/time number i.e. days since 1-1-1900 where 1900 is incorrectly seen as leap year
* @throws nothing
*/
toUtcExcel(): number;
/**
*
* @param n
* @throws nothing
*/
private _unixTimeStampToExcel;
/**
* Add a time duration relative to UTC. Returns a new DateTime
* @return this + duration
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
add(duration: Duration): DateTime;
/**
* Add an amount of time relative to UTC, as regularly as possible. Returns a new DateTime
*
* Adding e.g. 1 hour will increment the utcHour() field, adding 1 month
* increments the utcMonth() field.
* Adding an amount of units leaves lower units intact. E.g.
* adding a month will leave the day() field untouched if possible.
*
* Note adding Months or Years will clamp the date to the end-of-month if
* the start date was at the end of a month, i.e. contrary to JavaScript
* Date#setUTCMonth() it will not overflow into the next month
*
* In case of DST changes, the utc time fields are still untouched but local
* time fields may shift.
* @throws Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months
* @throws Argument.Unit for invalid time unit
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
add(amount: number, unit: TimeUnit): DateTime;
/**
* Add an amount of time to the zone time, as regularly as possible. Returns a new DateTime
*
* Adding e.g. 1 hour will increment the hour() field of the zone
* date by one. In case of DST changes, the time fields may additionally
* increase by the DST offset, if a non-existing local time would
* be reached otherwise.
*
* Adding a unit of time will leave lower-unit fields intact, unless the result
* would be a non-existing time. Then an extra DST offset is added.
*
* Note adding Months or Years will clamp the date to the end-of-month if
* the start date was at the end of a month, i.e. contrary to JavaScript
* Date#setUTCMonth() it will not overflow into the next month
* @throws nothing
*/
addLocal(duration: Duration): DateTime;
/**
* Add an amount of time to the zone time, as regularly as possible. Returns a new DateTime
*
* Adding e.g. 1 hour will increment the hour() field of the zone
* date by one. In case of DST changes, the time fields may additionally
* increase by the DST offset, if a non-existing local time would
* be reached otherwise.
*
* Adding a unit of time will leave lower-unit fields intact, unless the result
* would be a non-existing time. Then an extra DST offset is added.
*
* Note adding Months or Years will clamp the date to the end-of-month if
* the start date was at the end of a month, i.e. contrary to JavaScript
* Date#setUTCMonth() it will not overflow into the next month
* @param amount
* @param unit
* @throws Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months
* @throws Argument.Unit for invalid time unit
*/
addLocal(amount: number, unit: TimeUnit): DateTime;
/**
* Add an amount of time to the given time struct. Note: does not normalize.
* Keeps lower unit fields the same where possible, clamps day to end-of-month if
* necessary.
* @throws Argument.Amount if amount is not finite or if it's not an integer and you're adding months or years
* @throws Argument.Unit for invalid time unit
*/
private _addToTimeStruct;
/**
* Same as add(-1*duration); Returns a new DateTime
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
sub(duration: Duration): DateTime;
/**
* Same as add(-1*amount, unit); Returns a new DateTime
* @throws Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months
* @throws Argument.Unit for invalid time unit
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
sub(amount: number, unit: TimeUnit): DateTime;
/**
* Same as addLocal(-1*amount, unit); Returns a new DateTime
* @throws nothing
*/
subLocal(duration: Duration): DateTime;
/**
* Same as addLocal(-1*amount, unit); Returns a new DateTime
* @param amount
* @param unit
* @throws Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months
* @throws Argument.Unit for invalid time unit
*/
subLocal(amount: number, unit: TimeUnit): DateTime;
/**
* Time difference between two DateTimes
* @return this - other
* @throws nothing
*/
diff(other: DateTime): Duration;
/**
* Chops off the time part, yields the same date at 00:00:00.000
* @return a new DateTime
* @throws nothing
*/
startOfDay(): DateTime;
/**
* Returns the first day of the month at 00:00:00
* @return a new DateTime
* @throws nothing
*/
startOfMonth(): DateTime;
/**
* Returns the first day of the year at 00:00:00
* @return a new DateTime
* @throws nothing
*/
startOfYear(): DateTime;
/**
* @return True iff (this < other)
* @throws nothing
*/
lessThan(other: DateTime): boolean;
/**
* @return True iff (this <= other)
* @throws nothing
*/
lessEqual(other: DateTime): boolean;
/**
* @return True iff this and other represent the same moment in time in UTC
* @throws nothing
*/
equals(other: DateTime): boolean;
/**
* @return True iff this and other represent the same time and the same zone
* @throws nothing
*/
identical(other: DateTime): boolean;
/**
* @return True iff this > other
* @throws nothing
*/
greaterThan(other: DateTime): boolean;
/**
* @return True iff this >= other
* @throws nothing
*/
greaterEqual(other: DateTime): boolean;
/**
* @return The minimum of this and other
* @throws nothing
*/
min(other: DateTime): DateTime;
/**
* @return The maximum of this and other
* @throws nothing
*/
max(other: DateTime): DateTime;
/**
* Proper ISO 8601 format string with any IANA zone converted to ISO offset
* E.g. "2014-01-01T23:15:33+01:00" for Europe/Amsterdam
* Unaware dates have no zone information at the end.
* @throws nothing
*/
toIsoString(): string;
/**
* Convert to UTC and then return ISO string ending in 'Z'. This is equivalent to Date#toISOString()
* e.g. "2014-01-01T23:15:33 Europe/Amsterdam" becomes "2014-01-01T22:15:33Z".
* Unaware dates are assumed to be in UTC
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
toUtcIsoString(): string;
/**
* Return a string representation of the DateTime according to the
* specified format. See LDML.md for supported formats.
*
* @param formatString The format specification (e.g. "dd/MM/yyyy HH:mm:ss")
* @param locale Optional, non-english format month names etc.
* @return The string representation of this DateTime
* @throws timezonecomplete.Argument.FormatString for invalid format pattern
*/
format(formatString: string, locale?: PartialLocale): string;
/**
* Parse a date in a given format
* @param s the string to parse
* @param format the format the string is in. See LDML.md for supported formats.
* @param zone Optional, the zone to add (if no zone is given in the string)
* @param locale Optional, different settings for constants like 'AM' etc
* @param allowTrailing Allow trailing characters in the source string
* @throws timezonecomplete.ParseError if the given dateTimeString is wrong or not according to the pattern
* @throws timezonecomplete.Argument.FormatString if the given format string is invalid
*/
static parse(s: string, format: string, zone?: TimeZone, locale?: PartialLocale, allowTrailing?: boolean): DateTime;
/**
* Modified ISO 8601 format string with IANA name if applicable.
* E.g. "2014-01-01T23:15:33.000 Europe/Amsterdam"
* @throws nothing
*/
toString(): string;
/**
* The valueOf() method returns the primitive value of the specified object.
* @throws nothing
*/
valueOf(): number;
/**
* Modified ISO 8601 format string in UTC without time zone info
* @throws nothing
*/
toUtcString(): string;
/**
* Split a combined ISO datetime and timezone into datetime and timezone
* @throws nothing
*/
private static _splitDateFromTimeZone;
}
/**
* Checks if a given object is of type DateTime. Note that it does not work for sub classes. However, use this to be robust
* against different versions of the library in one process instead of instanceof
* @param value Value to check
* @throws nothing
*/
export declare function isDateTime(value: any): value is DateTime;