Kata: Global Meeting Scheduler

Problem Statement

Your company has teams in New York, London, Tokyo, and several other cities. Meeting requests arrive as local date-and-time strings together with their IANA time zones. Your task is to convert each request into a canonical UTC timestamp.

Unfortunately, local times are not always valid or unique:

• During the spring daylight-saving transition, some local times do not exist.
• During the autumn transition, some local times occur twice.
• Time zones may use offsets that are not whole hours.

Implement a function that converts a local date and time into UTC while handling these cases explicitly.

Rules

Given:

• localDateTime: a local date and time in the exact format YYYY-MM-DDTHH:mm:ss
• timeZone: a valid IANA time-zone name, such as "America/New_York"
• disambiguation: how to handle daylight-saving ambiguities

Return the corresponding UTC timestamp in ISO 8601 format.

The disambiguation value has the following behavior:

• "earlier": choose the earlier UTC instant when the local time occurs twice.
• "later": choose the later UTC instant when the local time occurs twice.
• "reject": throw a RangeError if the local time is ambiguous or does not exist.

For a nonexistent local time:

• "earlier" shifts backward across the daylight-saving gap.
• "later" shifts forward across the daylight-saving gap.

Use the ECMAScript Temporal API through the @js-temporal/polyfill package. Do not rely on the machine’s default time zone.

Function Signature

type Disambiguation = "earlier" | "later" | "reject";

export function toUtcIso(
  localDateTime: string,
  timeZone: string,
  disambiguation: Disambiguation
): string;

Test Cases

import { describe, expect, it } from "vitest";
import { toUtcIso } from "./toUtcIso";

describe("toUtcIso", () => {
  it("converts a winter time in New York to UTC", () => {
    expect(
      toUtcIso(
        "2024-01-15T09:30:00",