ts-time/Zone

Consumption

import * as Zone from "ts-time/Zone";

ZoneId#

Hierarchy#

Description#

Represents a time zone. All time zone instances get cached in the memory upon initialization, so an attempt to obtain the same time zone twice results in the same instance of an object.

Fields#

id#

readonly id: string

Zone text identifier.

Methods#

offsetAtInstant#

(instant: Instant): ZoneOffset

instant
Instant.
returns
Offset of this time zone at a specified instant.
offsetAtLocalDateTime#

(localDateTime: LocalDateTime): ZoneOffset

localDateTime
Date/time.
returns
Offset of this time zone at a specified date/time. If there are multiple possible values (in case of time overlap caused by offset shift), returns the earlier offset (i.e. one right before the shift).
toString#

(): string

returns
id

Static methods#

of#

(id: string): ZoneId throws TemporalParsingError

id
Zone text identifier.
returns
ZoneId representing this identifier.

This method parses the ID producing a ZoneId or ZoneOffset. ZoneOffset is returned if the id is 'Z', or starts with '+' or '-'.

Parsing matches the zone id step by step as follows.

  1. If the zone id equals 'Z', the result is UTC.
  2. If the zone id consists of a single letter, the zone id is invalid, and Error is thrown.
  3. If the zone id starts with '+' or '-', the id is parsed as a ZoneOffset using ZoneOffset.of.
  4. If the zone id equals 'GMT', 'UTC' or 'UT' then the result is a ZoneId with the same id and rules equivalent to UTC.
  5. If the zone id starts with 'UTC+', 'UTC-', 'GMT+', 'GMT-', 'UT+' or 'UT-' then the id is a prefixed offset-based id. The id is split in two, with a two or three letter prefix and a suffix starting with the sign. The suffix is parsed as a ZoneOffset. The result will be a ZoneId with the specified UTC/GMT/UT prefix and the normalized offset id as per ZoneOffset.id. The rules of the returned ZoneId will be equivalent to the parsed ZoneOffset.
  6. All other id's are parsed as custom zone id's. Their offsets get computed with Intl.DateTimeFormat browser API on demand.
compareById#

(x: ZoneId, y: ZoneId): number

x
One time zone.
y
Another time zone.
returns
  • 0 if this is the same zone;
  • positive value if x.id is higher than y.id;
  • negative value if x.id is lower than y.id.
Null and undefined are considered less than anything, except each other.

Note that a method call on null or undefined always leads to an error. So, if your variable may contain null or undefined, use the respective static method instead.

ZoneOffset#

Hierarchy#

  • abstract class ZoneId
  • class ZoneOffset

Description#

Represents a fixed time zone offset. All offset instances get cached in the memory upon initialization, so an attempt to obtain the same time zone offset twice results in the same instance of an object.

Fields#

id#

readonly id: string

Normalized text identifier of the offset:

  • Z - for UTC (ISO-8601)
  • +hh:mm or -hh:mm - if the seconds are zero (ISO-8601)
  • +hh:mm:ss or -hh:mm:ss - if the seconds are non-zero (not ISO-8601)
totalSeconds#

readonly totalSeconds: number

Total number of seconds.
hours#

readonly hours: number

Number of hours in the offset. Can be positive or negative.
minutes#

readonly minutes: number

Number of minutes in the offset. Always positive.
seconds#

readonly seconds: number

Number of seconds in the offset. Always positive.

Methods#

offsetAtInstant (inherited from ZoneId)#

(instant: Instant): ZoneOffset

instant
Instant.
returns
Offset of this time zone at a specified instant.
offsetAtLocalDateTime (inherited from ZoneId)#

(localDateTime: LocalDateTime): ZoneOffset

localDateTime
Date/time.
returns
Offset of this time zone at a specified date/time. If there are multiple possible values (in case of time overlap caused by offset shift), returns the earlier offset (i.e. one right before the shift).
toString (inherited from ZoneId)#

(): string

returns
id

Static methods#

of#

(id: string): ZoneOffset throws TemporalParsingError

id
Time zone offset identifier.
returns
ZoneOffset representing this identifier.

This method parses the string id of a ZoneOffset to return an instance. The parsing accepts the following formats:

  • Z - for UTC
  • ±h
  • ±hh
  • ±hh:mm
  • ±hhmm
  • ±hh:mm:ss
  • ±hhmmss

Note that ± means either the plus or minus symbol.

The id of the returned offset will be normalized to one of the formats described there.

ofComponents#

(hours: number, minutes: number = 0, seconds: number = 0): ZoneOffset

hours
Hourly part of the offset.
minutes
Minutely part of the offset.
seconds
Secondly part of the offset.
returns
ZoneOffset representation.

In order to obtain a negative offset, all parts must be reversed:

expect(ZoneOffset.ofComponents(-3, -25, -45)).toBe(ZoneOffset.ofTotalSeconds(-12345));
ofTotalSeconds#

(totalSeconds: number): ZoneOffset

totalSeconds
Total number of seconds.
returns
ZoneOffset representation.
compare#

(x: ZoneOffset, y: ZoneOffset): number

x
One offset.
y
Another offset.
returns
Null and undefined are considered less than anything, except each other.

Note that a method call on null or undefined always leads to an error. So, if your variable may contain null or undefined, use the respective static method instead.

compareById (inherited from ZoneId)#

(x: ZoneId, y: ZoneId): number

x
One time zone.
y
Another time zone.
returns
  • 0 if this is the same zone;
  • positive value if x.id is higher than y.id;
  • negative value if x.id is lower than y.id.
Null and undefined are considered less than anything, except each other.

Note that a method call on null or undefined always leads to an error. So, if your variable may contain null or undefined, use the respective static method instead.

UTC#

UTC: ZoneOffset

UTC time zone having a constant 0 offset.

LOCAL_ZONE_ID#

LOCAL_ZONE_ID: ZoneId

Local browser/system time zone.