Class TzDatabase

This class is a wrapper around time zone data JSON object from the tzdata NPM module. You usually do not need to use this directly, use TimeZone and DateTime instead.

Methods

abbreviation dstOffsetForRule exists getRuleInfos getTransitionsDstOffsets getTransitionsTotalOffsets getZoneInfo getZoneInfos hasDst letterForRule maxDstSave minDstSave nextDstChange normalizeLocal parseAtType parseOnDay parseOnType parseOnWeekDay parseRuleType parseToType standardOffset standardOffsetLocal totalOffset totalOffsetLocal zoneIsUtc zoneNames init instance

Methods

abbreviation

  • abbreviation(zoneName, utcTime, dstDependent?): string

  • The time zone rule abbreviation, e.g. CEST for Central European Summer Time. Note this is dependent on the time, because with time different rules are in effect and therefore different abbreviations. They also change with DST: e.g. CEST or CET.

    Parameters

    • zoneName: string

      IANA zone name

    • utcTime: number | TimeStruct

      Timestamp in UTC unix milliseconds

    • dstDependent: boolean = true

      (default true) set to false for a DST-agnostic abbreviation

    Returns string

    The abbreviation of the rule that is in effect

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

dstOffsetForRule

  • dstOffsetForRule(ruleName, utcTime, standardOffset): Duration

  • DEPRECATED because DST offset depends on the zone too, not just on the ruleset Returns the DST offset (WITHOUT the standard zone offset) for the given ruleset and the given UTC timestamp

    Parameters

    • ruleName: string

      name of ruleset

    • utcTime: number | TimeStruct

      UTC timestamp

    • standardOffset: Duration

      Standard offset without DST for the time zone

    Returns Duration

    Deprecated

    Throws

    timezonecomplete.NotFound.Rule if ruleName not found

    Throws

    timezonecomplete.InvalidTimeZoneData if an error is discovered in the time zone database

exists

  • exists(zoneName): boolean

  • Returns true iff the given zone name exists

    Parameters

    • zoneName: string

    Returns boolean

    Throws

    nothing

getRuleInfos

  • getRuleInfos(ruleName): RuleInfo[]

  • Returns the rule set with the given rule name, sorted by first effective date (uncompensated for "w" or "s" AtTime)

    Parameters

    • ruleName: string

      Name of rule set

    Returns RuleInfo[]

    RuleInfo array. Do not change, this is a cached value.

    Throws

    timezonecomplete.NotFound.Rule if rule not found

    Throws

    timezonecomplete.InvalidTimeZoneData for invalid values in the time zone database

getTransitionsDstOffsets

  • getTransitionsDstOffsets(ruleName, fromYear, toYear, standardOffset): Transition[]

  • DEPRECATED because DST offset depends on the zone too, not just on the ruleset Return a list of all transitions in [fromYear..toYear] sorted by effective date

    Parameters

    • ruleName: string

      Name of the rule set

    • fromYear: number

      first year to return transitions for

    • toYear: number

      Last year to return transitions for

    • standardOffset: Duration

      Standard offset without DST for the time zone

    Returns Transition[]

    Transitions, with DST offsets (no standard offset included)

    Deprecated

    Throws

    timezonecomplete.Argument.FromYear if fromYear > toYear

    Throws

    timezonecomplete.NotFound.Rule if ruleName not found

    Throws

    timezonecomplete.InvalidTimeZoneData if an error is discovered in the time zone database

getTransitionsTotalOffsets

  • getTransitionsTotalOffsets(zoneName, fromYear, toYear): Transition[]

  • Return both zone and rule changes as total (std + dst) offsets. Adds an initial transition if there is none within the range.

    Parameters

    • zoneName: string

      IANA zone name

    • fromYear: number

      First year to include

    • toYear: number

      Last year to include

    Returns Transition[]

    Throws

    timezonecomplete.Argument.FromYear if fromYear > toYear

    Throws

    timezonecomplete.NotFound.Zone if zoneName not found

    Throws

    timezonecomplete.InvalidTimeZoneData if an error is discovered in the time zone database

getZoneInfo

  • getZoneInfo(zoneName, utcTime): ZoneInfo

  • Get the zone info for the given UTC timestamp. Throws if not found.

    Parameters

    • zoneName: string

      IANA time zone name

    • utcTime: number | TimeStruct

      UTC time stamp as unix milliseconds or as a TimeStruct

    Returns ZoneInfo

    ZoneInfo object. Do not change, we cache this object.

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

getZoneInfos

  • getZoneInfos(zoneName): ZoneInfo[]

  • Return the zone records for a given zone name sorted by UNTIL, after following any links.

    Parameters

    • zoneName: string

      IANA zone name like "Pacific/Efate"

    Returns ZoneInfo[]

    Array of zone infos. Do not change, this is a cached value.

    Throws

    timezonecomplete.NotFound.Zone if zone does not exist or a linked zone does not exit

hasDst

  • hasDst(zoneName): boolean

  • Checks whether the zone has DST at all

    Parameters

    • zoneName: string

    Returns boolean

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

letterForRule

  • letterForRule(ruleName, utcTime, standardOffset): string

  • Returns the time zone letter for the given ruleset and the given UTC timestamp

    Parameters

    • ruleName: string

      name of ruleset

    • utcTime: number | TimeStruct

      UTC timestamp as TimeStruct or unix millis

    • standardOffset: Duration

      Standard offset without DST for the time zone

    Returns string

    Deprecated

    Throws

    timezonecomplete.NotFound.Rule if ruleName not found

    Throws

    timezonecomplete.InvalidTimeZoneData if an error is discovered in the time zone database

maxDstSave

  • maxDstSave(zoneName?): Duration

  • Maximum DST offset (which excludes standard offset) of all rules in the database. Note that DST offsets need not be whole hours.

    Returns 0 if zoneName given and no DST observed.

    Parameters

    • Optional zoneName: string

      (optional) if given, the result for the given zone is returned

    Returns Duration

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

minDstSave

  • minDstSave(zoneName?): Duration

  • Minimum non-zero DST offset (which excludes standard offset) of all rules in the database. Note that DST offsets need not be whole hours.

    Does return zero if a zoneName is given and there is no DST at all for the zone.

    Parameters

    • Optional zoneName: string

      (optional) if given, the result for the given zone is returned

    Returns Duration

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

nextDstChange

  • nextDstChange(zoneName, utcTime): undefined | number

  • First DST change moment AFTER the given UTC date in UTC milliseconds, within one year, returns undefined if no such change

    Parameters

    • zoneName: string
    • utcTime: number

    Returns undefined | number

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

  • nextDstChange(zoneName, utcTime): undefined | number

  • Parameters

    Returns undefined | number

normalizeLocal

  • normalizeLocal(zoneName, localTime, opt?): number

  • Normalizes non-existing local times by adding/subtracting a forward offset change. During a forward standard offset change or DST offset change, some amount of local time is skipped. Therefore, this amount of local time does not exist. This function adds the amount of forward change to any non-existing time. After all, this is probably what the user meant.

    Parameters

    • zoneName: string

      IANA time zone name

    • localTime: number

      A local time as a unix millisecond value

    • Optional opt: NormalizeOption

      (optional) Round up or down? Default: up.

    Returns number

    The normalized time, in the same format as the localTime parameter (TimeStruct or unix millis)

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

  • normalizeLocal(zoneName, localTime, opt?): TimeStruct

  • Normalizes non-existing local times by adding/subtracting a forward offset change. During a forward standard offset change or DST offset change, some amount of local time is skipped. Therefore, this amount of local time does not exist. This function adds the amount of forward change to any non-existing time. After all, this is probably what the user meant.

    Parameters

    • zoneName: string

      IANA time zone name

    • localTime: TimeStruct

      A local time, as a TimeStruct

    • Optional opt: NormalizeOption

      (optional) Round up or down? Default: up.

    Returns TimeStruct

    The normalized time, in the same format as the localTime parameter (TimeStruct or unix millis)

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

parseAtType

  • parseAtType(at): AtType

  • Parse the AT column of a rule info entry and see what kind of entry it is.

    Parameters

    • at: any

    Returns AtType

    Throws

    nothing

parseOnDay

  • parseOnDay(on, onType): number

  • Get the day number from an ON column string, 0 if no day.

    Parameters

    Returns number

    Throws

    nothing

parseOnType

  • parseOnType(on): OnType

  • Parse the ON column of a rule info entry and see what kind of entry it is.

    Parameters

    • on: string

    Returns OnType

    Throws

    nothing

parseOnWeekDay

  • parseOnWeekDay(on): WeekDay

  • Get the day-of-week from an ON column string, Sunday if not present.

    Parameters

    • on: string

    Returns WeekDay

    Throws

    nothing

parseRuleType

  • parseRuleType(rule): RuleType

  • Parse the RULES column of a zone info entry and see what kind of entry it is.

    Parameters

    • rule: string

    Returns RuleType

    Throws

    nothing

parseToType

  • parseToType(to): ToType

  • Parse the TO column of a rule info entry and see what kind of entry it is.

    Parameters

    • to: string

    Returns ToType

    Throws

    timezonecomplete.Argument.To for invalid TO

standardOffset

  • standardOffset(zoneName, utcTime): Duration

  • Returns the standard time zone offset from UTC, without DST. Throws if info not found.

    Parameters

    • zoneName: string

      IANA time zone name

    • utcTime: number | TimeStruct

      Timestamp in UTC, either as TimeStruct or as Unix millisecond value

    Returns Duration

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

standardOffsetLocal

  • standardOffsetLocal(zoneName, localTime): Duration

  • Returns the standard time zone offset from UTC, excluding DST, at the given LOCAL timestamp, again excluding DST.

    If the local timestamp exists twice (as can occur very rarely due to zone changes) then the first occurrence is returned.

    Throws if zone info not found.

    Parameters

    • zoneName: string

      IANA time zone name

    • localTime: number | TimeStruct

      Timestamp in time zone time

    Returns Duration

    Throws

    timezonecomplete.NotFound.Zone if zoneName not found

    Throws

    timezonecomplete.InvalidTimeZoneData if an error is discovered in the time zone database

totalOffset

  • totalOffset(zoneName, utcTime): Duration

  • Returns the total time zone offset from UTC, including DST, at the given UTC timestamp. Throws if zone info not found.

    Parameters

    • zoneName: string

      IANA time zone name

    • utcTime: number | TimeStruct

      Timestamp in UTC, either as TimeStruct or as Unix millisecond value

    Returns Duration

    Throws

    timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found

    Throws

    timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

totalOffsetLocal

  • totalOffsetLocal(zoneName, localTime): Duration

  • Returns the total time zone offset from UTC, including DST, at the given LOCAL timestamp. Non-existing local time is normalized out. There can be multiple UTC times and therefore multiple offsets for a local time namely during a backward DST change. This returns the FIRST such offset. Throws if zone info not found.

    Parameters

    • zoneName: string

      IANA time zone name

    • localTime: number | TimeStruct

      Timestamp in time zone time

    Returns Duration

    Throws

    timezonecomplete.NotFound.Zone if zoneName not found

    Throws

    timezonecomplete.InvalidTimeZoneData if an error is discovered in the time zone database

zoneIsUtc

  • zoneIsUtc(zoneName): boolean

  • Returns true iff the given zone name eventually links to "Etc/UTC", "Etc/GMT" or "Etc/UCT" in the TZ database. This is true e.g. for "UTC", "GMT", "Etc/GMT" etc.

    Parameters

    • zoneName: string

      IANA time zone name.

    Returns boolean

    Throws

    nothing

zoneNames

  • zoneNames(): string[]

  • Returns a sorted list of all zone names

    Returns string[]

    Throws

    nothing

Static init

  • init(data?): void

  • (re-) initialize timezonecomplete with time zone data

    Parameters

    • Optional data: any

      TZ data as JSON object (from one of the tzdata NPM modules). If not given, Timezonecomplete will search for installed modules.

    Returns void

    Throws

    timezonecomplete.InvalidTimeZoneData if data or the global time zone data is invalid

Static instance

Settings

Member Visibility

Theme

On This Page

abbreviationdstOffsetForRuleexistsgetRuleInfosgetTransitionsDstOffsetsgetTransitionsTotalOffsetsgetZoneInfogetZoneInfoshasDstletterForRulemaxDstSaveminDstSavenextDstChangenormalizeLocalparseAtTypeparseOnDayparseOnTypeparseOnWeekDayparseRuleTypeparseToTypestandardOffsetstandardOffsetLocaltotalOffsettotalOffsetLocalzoneIsUtczoneNamesinitinstance