import { resolveWallToInstant } from "./materialize.js";
import { canonicalTimezone } from "./timezone.js";
import { parseNominal } from "./nominal.js";
import type { NominalLocal } from "./timezone.js";

/**
 * Materialize one nominal local date-time (e.g. `2024-03-10T02:30`) in an
 * explicit IANA zone to its UTC fire instant in epoch milliseconds.
 *
 * Gap -> first valid instant after the gap; fold -> single firing at the
 * earlier instant. Throws on a malformed nominal string or an invalid zone.
 */
export function materializeOccurrence(nominalLocal: NominalLocal, timezone: string): number {
  const zone = canonicalTimezone(timezone);
  return resolveWallToInstant(parseNominal(nominalLocal), zone);
}