chrono-node 2.6.2 → 2.6.4

package/src/locales/uk/parsers/UKRelativeDateFormatParser.ts

@@ -0,0 +1,85 @@
+import { REGEX_PARTS, TIME_UNIT_DICTIONARY } from "../constants";
+import { ParsingContext } from "../../../chrono";
+import { ParsingComponents } from "../../../results";
+import dayjs from "dayjs";
+import { AbstractParserWithWordBoundaryChecking } from "../../../common/parsers/AbstractParserWithWordBoundary";
+import { matchAnyPattern } from "../../../utils/pattern";
+
+const PATTERN = new RegExp(
+    `(в минулому|у минулому|на минулому|минулого|на наступному|в наступному|у наступному|наступного|на цьому|в цьому|у цьому|цього)\\s*(${matchAnyPattern(
+        TIME_UNIT_DICTIONARY
+    )})(?=\\s*)${REGEX_PARTS.rightBoundary}`,
+    REGEX_PARTS.flags
+);
+
+const MODIFIER_WORD_GROUP = 1;
+const RELATIVE_WORD_GROUP = 2;
+
+export default class UKRelativeDateFormatParser extends AbstractParserWithWordBoundaryChecking {
+    patternLeftBoundary(): string {
+        return REGEX_PARTS.leftBoundary;
+    }
+
+    innerPattern(): RegExp {
+        return PATTERN;
+    }
+
+    innerExtract(context: ParsingContext, match: RegExpMatchArray): ParsingComponents {
+        const modifier = match[MODIFIER_WORD_GROUP].toLowerCase();
+        const unitWord = match[RELATIVE_WORD_GROUP].toLowerCase();
+        const timeunit = TIME_UNIT_DICTIONARY[unitWord];
+
+        if (
+            modifier == "на наступному" ||
+            modifier == "в наступному" ||
+            modifier == "у наступному" ||
+            modifier == "наступного"
+        ) {
+            const timeUnits = {};
+            timeUnits[timeunit] = 1;
+            return ParsingComponents.createRelativeFromReference(context.reference, timeUnits);
+        }
+
+        if (
+            modifier == "на минулому" ||
+            modifier == "в минулому" ||
+            modifier == "у минулому" ||
+            modifier == "минулого"
+        ) {
+            const timeUnits = {};
+            timeUnits[timeunit] = -1;
+            return ParsingComponents.createRelativeFromReference(context.reference, timeUnits);
+        }
+
+        const components = context.createParsingComponents();
+        let date = dayjs(context.reference.instant);
+
+        // This week
+        if (timeunit.match(/week/i)) {
+            date = date.add(-date.get("d"), "d");
+            components.imply("day", date.date());
+            components.imply("month", date.month() + 1);
+            components.imply("year", date.year());
+        }
+
+        // This month
+        else if (timeunit.match(/month/i)) {
+            date = date.add(-date.date() + 1, "d");
+            components.imply("day", date.date());
+            components.assign("year", date.year());
+            components.assign("month", date.month() + 1);
+        }
+
+        // This year
+        else if (timeunit.match(/year/i)) {
+            date = date.add(-date.date() + 1, "d");
+            date = date.add(-date.month(), "month");
+
+            components.imply("day", date.date());
+            components.imply("month", date.month() + 1);
+            components.assign("year", date.year());
+        }
+
+        return components;
+    }
+}

package/src/locales/uk/parsers/UKTimeExpressionParser.ts

@@ -0,0 +1,64 @@
+import { ParsingContext } from "../../../chrono";
+import { ParsingComponents } from "../../../results";
+import { Meridiem } from "../../../types";
+import { AbstractTimeExpressionParser } from "../../../common/parsers/AbstractTimeExpressionParser";
+import { REGEX_PARTS } from "../constants";
+
+export default class UKTimeExpressionParser extends AbstractTimeExpressionParser {
+    constructor(strictMode) {
+        super(strictMode);
+    }
+
+    patternFlags(): string {
+        return REGEX_PARTS.flags;
+    }
+
+    primaryPatternLeftBoundary(): string {
+        return `(^|\\s|T|(?:[^\\p{L}\\p{N}_]))`;
+    }
+
+    followingPhase(): string {
+        return `\\s*(?:\\-|\\–|\\~|\\〜|до|і|по|\\?)\\s*`;
+    }
+
+    primaryPrefix(): string {
+        return `(?:(?:в|у|о|об|з|із|від)\\s*)??`;
+    }
+
+    primarySuffix(): string {
+        return `(?:\\s*(?:ранку|вечора|по обіді|після обіду))?(?!\\/)${REGEX_PARTS.rightBoundary}`;
+    }
+
+    extractPrimaryTimeComponents(context: ParsingContext, match: RegExpMatchArray): null | ParsingComponents {
+        const components = super.extractPrimaryTimeComponents(context, match);
+        if (components) {
+            if (match[0].endsWith("вечора")) {
+                const hour = components.get("hour");
+                if (hour >= 6 && hour < 12) {
+                    components.assign("hour", components.get("hour") + 12);
+                    components.assign("meridiem", Meridiem.PM);
+                } else if (hour < 6) {
+                    components.assign("meridiem", Meridiem.AM);
+                }
+            }
+
+            if (match[0].endsWith("по обіді") || match[0].endsWith("після обіду")) {
+                components.assign("meridiem", Meridiem.PM);
+                const hour = components.get("hour");
+                if (hour >= 0 && hour <= 6) {
+                    components.assign("hour", components.get("hour") + 12);
+                }
+            }
+
+            if (match[0].endsWith("ранку")) {
+                components.assign("meridiem", Meridiem.AM);
+                const hour = components.get("hour");
+                if (hour < 12) {
+                    components.assign("hour", components.get("hour"));
+                }
+            }
+        }
+
+        return components;
+    }
+}

package/src/locales/uk/parsers/UKTimeUnitAgoFormatParser.ts

@@ -0,0 +1,24 @@
+import { ParsingContext } from "../../../chrono";
+import { parseTimeUnits, REGEX_PARTS, TIME_UNITS_PATTERN } from "../constants";
+import { ParsingComponents } from "../../../results";
+import { AbstractParserWithWordBoundaryChecking } from "../../../common/parsers/AbstractParserWithWordBoundary";
+import { reverseTimeUnits } from "../../../utils/timeunits";
+
+const PATTERN = new RegExp(`(${TIME_UNITS_PATTERN})\\s{0,5}тому(?=(?:\\W|$))`, REGEX_PARTS.flags);
+
+export default class UKTimeUnitAgoFormatParser extends AbstractParserWithWordBoundaryChecking {
+    patternLeftBoundary(): string {
+        return REGEX_PARTS.leftBoundary;
+    }
+
+    innerPattern(): RegExp {
+        return PATTERN;
+    }
+
+    innerExtract(context: ParsingContext, match: RegExpMatchArray) {
+        const timeUnits = parseTimeUnits(match[1]);
+        const outputTimeUnits = reverseTimeUnits(timeUnits);
+
+        return ParsingComponents.createRelativeFromReference(context.reference, outputTimeUnits);
+    }
+}

package/src/locales/uk/parsers/UKTimeUnitCasualRelativeFormatParser.ts

@@ -0,0 +1,34 @@
+import { TIME_UNITS_PATTERN, parseTimeUnits, REGEX_PARTS } from "../constants";
+import { ParsingContext } from "../../../chrono";
+import { ParsingComponents } from "../../../results";
+import { AbstractParserWithWordBoundaryChecking } from "../../../common/parsers/AbstractParserWithWordBoundary";
+import { reverseTimeUnits } from "../../../utils/timeunits";
+
+const PATTERN = new RegExp(
+    `(ці|останні|минулі|майбутні|наступні|після|через|\\+|-)\\s*(${TIME_UNITS_PATTERN})${REGEX_PARTS.rightBoundary}`,
+    REGEX_PARTS.flags
+);
+
+export default class UKTimeUnitCasualRelativeFormatParser extends AbstractParserWithWordBoundaryChecking {
+    patternLeftBoundary(): string {
+        return REGEX_PARTS.leftBoundary;
+    }
+
+    innerPattern(): RegExp {
+        return PATTERN;
+    }
+
+    innerExtract(context: ParsingContext, match: RegExpMatchArray): ParsingComponents {
+        const prefix = match[1].toLowerCase();
+        let timeUnits = parseTimeUnits(match[3]);
+        switch (prefix) {
+            case "останні":
+            case "минулі":
+            case "-":
+                timeUnits = reverseTimeUnits(timeUnits);
+                break;
+        }
+
+        return ParsingComponents.createRelativeFromReference(context.reference, timeUnits);
+    }
+}

package/src/locales/uk/parsers/UKTimeUnitWithinFormatParser.ts

@@ -0,0 +1,27 @@
+import { TIME_UNITS_PATTERN, parseTimeUnits, REGEX_PARTS } from "../constants";
+import { ParsingContext } from "../../../chrono";
+import { ParsingComponents } from "../../../results";
+import { AbstractParserWithWordBoundaryChecking } from "../../../common/parsers/AbstractParserWithWordBoundary";
+
+const PATTERN = `(?:(?:приблизно|орієнтовно)\\s*(?:~\\s*)?)?(${TIME_UNITS_PATTERN})${REGEX_PARTS.rightBoundary}`;
+const PATTERN_WITH_PREFIX = new RegExp(
+    `(?:протягом|на протязі|протягом|упродовж|впродовж)\\s*${PATTERN}`,
+    REGEX_PARTS.flags
+);
+
+const PATTERN_WITHOUT_PREFIX = new RegExp(PATTERN, "i");
+
+export default class UKTimeUnitWithinFormatParser extends AbstractParserWithWordBoundaryChecking {
+    patternLeftBoundary(): string {
+        return REGEX_PARTS.leftBoundary;
+    }
+
+    innerPattern(context: ParsingContext): RegExp {
+        return context.option.forwardDate ? PATTERN_WITHOUT_PREFIX : PATTERN_WITH_PREFIX;
+    }
+
+    innerExtract(context: ParsingContext, match: RegExpMatchArray): ParsingComponents {
+        const timeUnits = parseTimeUnits(match[1]);
+        return ParsingComponents.createRelativeFromReference(context.reference, timeUnits);
+    }
+}

package/src/locales/uk/parsers/UKWeekdayParser.ts

@@ -0,0 +1,59 @@
+import { ParsingContext } from "../../../chrono";
+import { ParsingComponents } from "../../../results";
+// TODO: ADD REGEX_PARTS below
+import { REGEX_PARTS, WEEKDAY_DICTIONARY } from "../constants";
+import { matchAnyPattern } from "../../../utils/pattern";
+import { AbstractParserWithWordBoundaryChecking } from "../../../common/parsers/AbstractParserWithWordBoundary";
+import { createParsingComponentsAtWeekday } from "../../../common/calculation/weekdays";
+
+const PATTERN = new RegExp(
+    `(?:(?:,|\\(|（)\\s*)?` +
+        `(?:в\\s*?)?` +
+        `(?:у\\s*?)?` +
+        `(?:(цей|минулого|минулий|попередній|попереднього|наступного|наступний|наступному)\\s*)?` +
+        `(${matchAnyPattern(WEEKDAY_DICTIONARY)})` +
+        `(?:\\s*(?:,|\\)|）))?` +
+        `(?:\\s*(на|у|в)\\s*(цьому|минулому|наступному)\\s*тижні)?` +
+        `${REGEX_PARTS.rightBoundary}`,
+    REGEX_PARTS.flags
+);
+
+const PREFIX_GROUP = 1;
+const WEEKDAY_GROUP = 2;
+const POSTFIX_GROUP = 3;
+
+export default class UKWeekdayParser extends AbstractParserWithWordBoundaryChecking {
+    innerPattern(): RegExp {
+        return PATTERN;
+    }
+
+    patternLeftBoundary(): string {
+        return REGEX_PARTS.leftBoundary;
+    }
+
+    innerExtract(context: ParsingContext, match: RegExpMatchArray): ParsingComponents {
+        const dayOfWeek = match[WEEKDAY_GROUP].toLocaleLowerCase();
+        const weekday = WEEKDAY_DICTIONARY[dayOfWeek];
+        const prefix = match[PREFIX_GROUP];
+        const postfix = match[POSTFIX_GROUP];
+        let modifierWord = prefix || postfix;
+        modifierWord = modifierWord || "";
+        modifierWord = modifierWord.toLocaleLowerCase();
+
+        let modifier = null;
+        if (
+            modifierWord == "минулого" ||
+            modifierWord == "минулий" ||
+            modifierWord == "попередній" ||
+            modifierWord == "попереднього"
+        ) {
+            modifier = "last";
+        } else if (modifierWord == "наступного" || modifierWord == "наступний") {
+            modifier = "next";
+        } else if (modifierWord == "цей" || modifierWord == "цього" || modifierWord == "цьому") {
+            modifier = "this";
+        }
+
+        return createParsingComponentsAtWeekday(context.reference, weekday, modifier);
+    }
+}

package/src/locales/uk/refiners/UKMergeDateRangeRefiner.ts

@@ -0,0 +1,13 @@
+import AbstractMergeDateRangeRefiner from "../../../common/refiners/AbstractMergeDateRangeRefiner";
+
+/**
+ * Merging before and after results (see. AbstractMergeDateRangeRefiner)
+ * This implementation should provide Russian connecting phases
+ * - [з|із] 06.09.1989 [до|по] 11.12.1996
+ * - [з|із] п'ятниці і до середи
+ */
+export default class UKMergeDateRangeRefiner extends AbstractMergeDateRangeRefiner {
+    patternBetween(): RegExp {
+        return /^\s*(і до|і по|до|по|-)\s*$/i;
+    }
+}

package/src/locales/uk/refiners/UKMergeDateTimeRefiner.ts

@@ -0,0 +1,13 @@
+import AbstractMergeDateTimeRefiner from "../../../common/refiners/AbstractMergeDateTimeRefiner";
+
+/**
+ * Merging date-only result and time-only result (see. AbstractMergeDateTimeRefiner).
+ * This implementation should provide Ukrainian connecting phases
+ * - 2020-02-13 [в/у/о] 6:00
+ * - Завтра [,] 7:00
+ */
+export default class UKMergeDateTimeRefiner extends AbstractMergeDateTimeRefiner {
+    patternBetween(): RegExp {
+        return new RegExp(`^\\s*(T|в|у|о|,|-)?\\s*$`);
+    }
+}

package/src/locales/zh/hans/index.ts

@@ -2,10 +2,11 @@
  * Chrono components for zh support
  */
 
-import { Chrono, Configuration } from "../../../chrono";
 import ExtractTimezoneOffsetRefiner from "../../../common/refiners/ExtractTimezoneOffsetRefiner";
 import { includeCommonConfiguration } from "../../../configurations";
-import { ParsedResult, ParsingOption } from "../../../index";
+import { Chrono, Configuration, Parser, Refiner } from "../../../chrono";
+import { ParsingResult } from "../../../results";
+import { Component, ParsedResult, ParsingOption, ParsingReference, Meridiem, Weekday } from "../../../types";
 import ZHHansCasualDateParser from "./parsers/ZHHansCasualDateParser";
 import ZHHansDateParser from "./parsers/ZHHansDateParser";
 import ZHHansDeadlineFormatParser from "./parsers/ZHHansDeadlineFormatParser";
@@ -15,6 +16,9 @@ import ZHHansWeekdayParser from "./parsers/ZHHansWeekdayParser";
 import ZHHansMergeDateRangeRefiner from "./refiners/ZHHansMergeDateRangeRefiner";
 import ZHHansMergeDateTimeRefiner from "./refiners/ZHHansMergeDateTimeRefiner";
 
+export { Chrono, Parser, Refiner, ParsingResult };
+export { Component, ParsedResult, ParsingOption, ParsingReference, Meridiem, Weekday };
+
 // Shortcuts
 export const hans = new Chrono(createCasualConfiguration());
 

package/src/locales/zh/hant/index.ts

@@ -3,10 +3,11 @@
  * TODO: Complete general zh support (current support only zh-Hant)
  */
 
-import { Chrono, Configuration } from "../../../chrono";
 import ExtractTimezoneOffsetRefiner from "../../../common/refiners/ExtractTimezoneOffsetRefiner";
 import { includeCommonConfiguration } from "../../../configurations";
-import { ParsedResult, ParsingOption } from "../../../index";
+import { Chrono, Configuration, Parser, Refiner } from "../../../chrono";
+import { ParsingResult } from "../../../results";
+import { Component, ParsedResult, ParsingOption, ParsingReference, Meridiem, Weekday } from "../../../types";
 import ZHHantCasualDateParser from "./parsers/ZHHantCasualDateParser";
 import ZHHantDateParser from "./parsers/ZHHantDateParser";
 import ZHHantDeadlineFormatParser from "./parsers/ZHHantDeadlineFormatParser";
@@ -16,6 +17,9 @@ import ZHHantWeekdayParser from "./parsers/ZHHantWeekdayParser";
 import ZHHantMergeDateRangeRefiner from "./refiners/ZHHantMergeDateRangeRefiner";
 import ZHHantMergeDateTimeRefiner from "./refiners/ZHHantMergeDateTimeRefiner";
 
+export { Chrono, Parser, Refiner, ParsingResult };
+export { Component, ParsedResult, ParsingOption, ParsingReference, Meridiem, Weekday };
+
 // Shortcuts
 export const hant = new Chrono(createCasualConfiguration());
 

package/src/results.ts

@@ -1,4 +1,4 @@
-import { Component, ParsedComponents, ParsedResult, ParsingReference } from "./index";
+import { Component, ParsedComponents, ParsedResult, ParsingReference } from "./types";
 
 import quarterOfYear from "dayjs/plugin/quarterOfYear";
 import dayjs, { QUnitType } from "dayjs";
@@ -16,7 +16,7 @@ export class ReferenceWithTimezone {
             this.instant = input;
         } else {
             this.instant = input.instant ?? new Date();
-            this.timezoneOffset = toTimezoneOffset(input.timezone);
+            this.timezoneOffset = toTimezoneOffset(input.timezone, this.instant);
         }
     }
 
@@ -138,8 +138,8 @@ export class ParsingComponents implements ParsedComponents {
         return this.isCertain("weekday") && !this.isCertain("day") && !this.isCertain("month");
     }
 
-    isOnlyDayMonthComponent(): boolean {
-        return this.isCertain("day") && this.isCertain("month") && !this.isCertain("year");
+    isDateWithUnknownYear(): boolean {
+        return this.isCertain("month") && !this.isCertain("year");
     }
 
     isValidDate(): boolean {

package/src/timezone.ts

@@ -1,4 +1,7 @@
-export const TIMEZONE_ABBR_MAP = {
+import dayjs from "dayjs";
+import { TimezoneAbbrMap, Weekday, Month } from "./types";
+
+export const TIMEZONE_ABBR_MAP: TimezoneAbbrMap = {
     ACDT: 630,
     ACST: 570,
     ADT: -180,
@@ -32,7 +35,14 @@ export const TIMEZONE_ABBR_MAP = {
     CCT: 390,
     CDT: -300,
     CEST: 120,
-    CET: 60,
+    // Note: Many sources define CET as a constant UTC+1. In common usage, however,
+    // CET usually refers to the time observed in most of Europe, be it standard time or daylight saving time.
+    CET: {
+        timezoneOffsetDuringDst: 2 * 60,
+        timezoneOffsetNonDst: 60,
+        dstStart: (year: number) => getLastWeekdayOfMonth(year, Month.MARCH, Weekday.SUNDAY, 2),
+        dstEnd: (year: number) => getLastWeekdayOfMonth(year, Month.OCTOBER, Weekday.SUNDAY, 3),
+    },
     CHADT: 825,
     CHAST: 765,
     CKT: -600,
@@ -40,6 +50,12 @@ export const TIMEZONE_ABBR_MAP = {
     CLT: -240,
     COT: -300,
     CST: -360,
+    CT: {
+        timezoneOffsetDuringDst: -5 * 60,
+        timezoneOffsetNonDst: -6 * 60,
+        dstStart: (year: number) => getNthWeekdayOfMonth(year, Month.MARCH, Weekday.SUNDAY, 2, 2),
+        dstEnd: (year: number) => getNthWeekdayOfMonth(year, Month.NOVEMBER, Weekday.SUNDAY, 1, 2),
+    },
     CVT: -60,
     CXT: 420,
     ChST: 600,
@@ -54,7 +70,12 @@ export const TIMEZONE_ABBR_MAP = {
     EGST: 0,
     EGT: -60,
     EST: -300,
-    ET: -300,
+    ET: {
+        timezoneOffsetDuringDst: -4 * 60,
+        timezoneOffsetNonDst: -5 * 60,
+        dstStart: (year: number) => getNthWeekdayOfMonth(year, Month.MARCH, Weekday.SUNDAY, 2, 2),
+        dstEnd: (year: number) => getNthWeekdayOfMonth(year, Month.NOVEMBER, Weekday.SUNDAY, 1, 2),
+    },
     FJST: 780,
     FJT: 720,
     FKST: -180,
@@ -116,6 +137,12 @@ export const TIMEZONE_ABBR_MAP = {
     MSD: 240,
     MSK: 180,
     MST: -420,
+    MT: {
+        timezoneOffsetDuringDst: -6 * 60,
+        timezoneOffsetNonDst: -7 * 60,
+        dstStart: (year: number) => getNthWeekdayOfMonth(year, Month.MARCH, Weekday.SUNDAY, 2, 2),
+        dstEnd: (year: number) => getNthWeekdayOfMonth(year, Month.NOVEMBER, Weekday.SUNDAY, 1, 2),
+    },
     MUT: 240,
     MVT: 300,
     MYT: 480,
@@ -143,7 +170,12 @@ export const TIMEZONE_ABBR_MAP = {
     PMST: -180,
     PONT: 660,
     PST: -480,
-    PT: -480,
+    PT: {
+        timezoneOffsetDuringDst: -7 * 60,
+        timezoneOffsetNonDst: -8 * 60,
+        dstStart: (year: number) => getNthWeekdayOfMonth(year, Month.MARCH, Weekday.SUNDAY, 2, 2),
+        dstEnd: (year: number) => getNthWeekdayOfMonth(year, Month.NOVEMBER, Weekday.SUNDAY, 1, 2),
+    },
     PWT: 540,
     PYST: -180,
     PYT: -240,
@@ -192,8 +224,67 @@ export const TIMEZONE_ABBR_MAP = {
     YEKT: 360,
 };
 
-export function toTimezoneOffset(timezoneInput?: string | number): number | null {
-    if (timezoneInput === null || timezoneInput === undefined) {
+/**
+ * Get the date which is the nth occurence of a given weekday in a given month and year.
+ *
+ * @param year The year for which to find the date
+ * @param month The month in which the date occurs
+ * @param weekday The weekday on which the date occurs
+ * @param n The nth occurence of the given weekday on the month to return
+ * @param hour The hour of day which should be set on the returned date
+ * @return The date which is the nth occurence of a given weekday in a given
+ *         month and year, at the given hour of day
+ */
+export function getNthWeekdayOfMonth(year: number, month: Month, weekday: Weekday, n: 1 | 2 | 3 | 4, hour = 0): Date {
+    let dayOfMonth = 0;
+    let i = 0;
+    while (i < n) {
+        dayOfMonth++;
+        const date = new Date(year, month - 1, dayOfMonth);
+        if (date.getDay() === weekday) i++;
+    }
+    return new Date(year, month - 1, dayOfMonth, hour);
+}
+
+/**
+ * Get the date which is the last occurence of a given weekday in a given month and year.
+ *
+ * @param year The year for which to find the date
+ * @param month The month in which the date occurs
+ * @param weekday The weekday on which the date occurs
+ * @param hour The hour of day which should be set on the returned date
+ * @return The date which is the last occurence of a given weekday in a given
+ *         month and year, at the given hour of day
+ */
+export function getLastWeekdayOfMonth(year: number, month: Month, weekday: Weekday, hour = 0): Date {
+    // Procedure: Find the first weekday of the next month, compare with the given weekday,
+    // and use the difference to determine how many days to subtract from the first of the next month.
+    const oneIndexedWeekday = weekday === 0 ? 7 : weekday;
+    const date = new Date(year, month - 1 + 1, 1, 12);
+    const firstWeekdayNextMonth = date.getDay() === 0 ? 7 : date.getDay();
+    let dayDiff;
+    if (firstWeekdayNextMonth === oneIndexedWeekday) dayDiff = 7;
+    else if (firstWeekdayNextMonth < oneIndexedWeekday) dayDiff = 7 + firstWeekdayNextMonth - oneIndexedWeekday;
+    else dayDiff = firstWeekdayNextMonth - oneIndexedWeekday;
+    date.setDate(date.getDate() - dayDiff);
+    return new Date(year, month - 1, date.getDate(), hour);
+}
+
+/**
+ * Finds and returns timezone offset. If timezoneInput is numeric, it is returned. Otherwise, look for timezone offsets
+ * in the following order: timezoneOverrides -> {@link TIMEZONE_ABBR_MAP}.
+ *
+ * @param timezoneInput Uppercase timezone abbreviation or numeric offset in minutes
+ * @param date The date to use to determine whether to return DST offsets for ambiguous timezones
+ * @param timezoneOverrides Overrides for timezones
+ * @return timezone offset in minutes
+ */
+export function toTimezoneOffset(
+    timezoneInput?: string | number,
+    date?: Date,
+    timezoneOverrides: TimezoneAbbrMap = {}
+): number | null {
+    if (timezoneInput == null) {
         return null;
     }
 
@@ -201,5 +292,31 @@ export function toTimezoneOffset(timezoneInput?: string | number): number | null
         return timezoneInput;
     }
 
-    return TIMEZONE_ABBR_MAP[timezoneInput] ?? null;
+    const matchedTimezone = timezoneOverrides[timezoneInput] ?? TIMEZONE_ABBR_MAP[timezoneInput];
+    if (matchedTimezone == null) {
+        return null;
+    }
+    // This means that we have matched an unambiguous timezone
+    if (typeof matchedTimezone == "number") {
+        return matchedTimezone;
+    }
+
+    // The matched timezone is an ambiguous timezone, where the offset depends on whether the context (refDate)
+    // is during daylight savings or not.
+
+    // Without refDate as context, there's no way to know if DST or non-DST offset should be used. Return null instead.
+    if (date == null) {
+        return null;
+    }
+
+    // Return DST offset if the refDate is during daylight savings
+    if (
+        dayjs(date).isAfter(matchedTimezone.dstStart(date.getFullYear())) &&
+        !dayjs(date).isAfter(matchedTimezone.dstEnd(date.getFullYear()))
+    ) {
+        return matchedTimezone.timezoneOffsetDuringDst;
+    }
+
+    // refDate is not during DST => return non-DST offset
+    return matchedTimezone.timezoneOffsetNonDst;
 }