1 | import { CanBeInvalid, DefaultValidity, IfValid } from "./_util";
|
2 |
|
3 | export interface ZoneOffsetOptions {
|
4 | /**
|
5 | * What style of offset to return.
|
6 | */
|
7 | format?: "short" | "long" | undefined;
|
8 | /**
|
9 | * What locale to return the offset name in.
|
10 | */
|
11 | locale?: string | undefined;
|
12 | }
|
13 |
|
14 | /**
|
15 | * What style of offset to return.
|
16 | * Returning '+6', '+06:00', or '+0600' respectively
|
17 | */
|
18 | export type ZoneOffsetFormat = "narrow" | "short" | "techie";
|
19 |
|
20 | export type ZoneMaybeValid = CanBeInvalid extends true ? Zone<true> | Zone<false> : Zone;
|
21 |
|
22 | export abstract class Zone<IsValid extends boolean = DefaultValidity> {
|
23 | /**
|
24 | * The type of zone
|
25 | */
|
26 | get type(): IfValid<string, "invalid", IsValid>;
|
27 |
|
28 | /**
|
29 | * The name of this zone.
|
30 | */
|
31 | get name(): string;
|
32 |
|
33 | /**
|
34 | * Returns whether the offset is known to be fixed for the whole year.
|
35 | */
|
36 | get isUniversal(): IfValid<boolean, false, IsValid>;
|
37 |
|
38 | /**
|
39 | * Returns the offset's common name (such as EST) at the specified timestamp
|
40 | *
|
41 | * @param ts - Epoch milliseconds for which to get the name
|
42 | * @param options - Options to affect the format
|
43 | * @param options.format - What style of offset to return.
|
44 | * @param options.locale - What locale to return the offset name in.
|
45 | */
|
46 | offsetName(ts: number, options: ZoneOffsetOptions): IfValid<string, null, IsValid>;
|
47 |
|
48 | /**
|
49 | * Returns the offset's value as a string
|
50 | *
|
51 | * @param ts - Epoch milliseconds for which to get the offset
|
52 | * @param format - What style of offset to return.
|
53 | * Accepts 'narrow', 'short', or 'techie'. Returning '+6', '+06:00', or '+0600' respectively
|
54 | */
|
55 | formatOffset(ts: number, format: ZoneOffsetFormat): IfValid<string, "", IsValid>;
|
56 |
|
57 | /**
|
58 | * Return the offset in minutes for this zone at the specified timestamp.
|
59 | *
|
60 | * @param ts - Epoch milliseconds for which to compute the offset
|
61 | */
|
62 | offset(ts: number): IfValid<number, typeof NaN, IsValid>;
|
63 |
|
64 | /**
|
65 | * Return whether this Zone is equal to another zone
|
66 | *
|
67 | * @param other - the zone to compare
|
68 | */
|
69 | equals(other: Zone): IfValid<boolean, false, IsValid>;
|
70 |
|
71 | /**
|
72 | * Return whether this Zone is valid.
|
73 | */
|
74 | get isValid(): IfValid<true, false, IsValid>;
|
75 | }
|
76 |
|
77 | /**
|
78 | * A zone identified by an IANA identifier, like America/New_York
|
79 | */
|
80 | export class IANAZone<IsValid extends boolean = DefaultValidity> extends Zone<IsValid> {
|
81 | /**
|
82 | * Same as constructor but has caching.
|
83 | */
|
84 | static create(name: string): CanBeInvalid extends true ? (IANAZone<true> | IANAZone<false>) : IANAZone;
|
85 |
|
86 | /**
|
87 | * Reset local caches. Should only be necessary in testing scenarios.
|
88 | */
|
89 | static resetCache(): void;
|
90 |
|
91 | /**
|
92 | * Returns whether the provided string is a valid specifier.
|
93 | * This only checks the string's format, not that the specifier
|
94 | * identifies a known zone; see {@link isValidZone} for that.
|
95 | *
|
96 | * @param s - The string to check validity on
|
97 | *
|
98 | * @example
|
99 | * IANAZone.isValidSpecifier("America/New_York") //=> true
|
100 | * @example
|
101 | * IANAZone.isValidSpecifier("Fantasia/Castle") //=> true
|
102 | * @example
|
103 | * IANAZone.isValidSpecifier("Sport~~blorp") //=> false
|
104 | */
|
105 | static isValidSpecifier(s: string): boolean;
|
106 |
|
107 | /**
|
108 | * Returns whether the provided string identifies a real zone
|
109 | *
|
110 | * @param zone - The string to check
|
111 | *
|
112 | * @example
|
113 | * IANAZone.isValidZone("America/New_York") //=> true
|
114 | * @example
|
115 | * IANAZone.isValidZone("Fantasia/Castle") //=> false
|
116 | * @example
|
117 | * IANAZone.isValidZone("Sport~~blorp") //=> false
|
118 | */
|
119 | static isValidZone(zone: string): boolean;
|
120 |
|
121 | constructor(name: string);
|
122 | }
|
123 |
|
124 | /**
|
125 | * A zone with a fixed offset (meaning no DST)
|
126 | */
|
127 | export class FixedOffsetZone extends Zone<true> {
|
128 | /**
|
129 | * Get a singleton instance of UTC
|
130 | */
|
131 | static get utcInstance(): FixedOffsetZone;
|
132 |
|
133 | /**
|
134 | * Get an instance with a specified offset
|
135 | *
|
136 | * @param offset - The offset in minutes
|
137 | */
|
138 | static instance(offset: number): FixedOffsetZone;
|
139 |
|
140 | /**
|
141 | * Get an instance of FixedOffsetZone from a UTC offset string, like "UTC+6"
|
142 | *
|
143 | * @param s - The offset string to parse
|
144 | *
|
145 | * @example
|
146 | * FixedOffsetZone.parseSpecifier("UTC+6")
|
147 | * @example
|
148 | * FixedOffsetZone.parseSpecifier("UTC+06")
|
149 | * @example
|
150 | * FixedOffsetZone.parseSpecifier("UTC-6:00")
|
151 | */
|
152 | static parseSpecifier(s: string): FixedOffsetZone;
|
153 | }
|
154 |
|
155 | /**
|
156 | * A zone that failed to parse. You should never need to instantiate this.
|
157 | */
|
158 | export class InvalidZone extends Zone<false> {
|
159 | get type(): "invalid";
|
160 | get isUniversal(): false;
|
161 | get offsetFormat(): "";
|
162 | }
|
163 |
|
164 | /**
|
165 | * Represents the system zone for this JavaScript environment.
|
166 | */
|
167 | export class SystemZone extends Zone<true> {
|
168 | /**
|
169 | * Get a singleton instance of the system zone
|
170 | */
|
171 | static get instance(): SystemZone;
|
172 | }
|