forecastTime.ts

Normalizes date inputs to the UTC hour key used throughout the weather cache

Purpose

This module provides a single conversion function that reduces any date-like value to the canonical UTC hour-boundary string used as the time dimension of weather cache keys.

Its responsibilities include:

  • Accepting either a Date object or an ISO string
  • Parsing the input to a millisecond epoch
  • Flooring to the nearest whole UTC hour
  • Returning an ISO 8601 string representing that UTC hour

Invariants

UTC Hour Flooring

The output always represents a UTC hour boundary with zero minutes, seconds, and milliseconds.

toHourKey(new Date("2024-07-01T14:37:22Z")) → "2024-07-01T14:00:00.000Z"

Invalid Input Throws

If Date.parse returns a non-finite value (malformed or non-date string), the function throws Error("Invalid forecast time").

Exports

toHourKey(...)

function toHourKey(input: Date | string): string

Returns the UTC hour-boundary ISO string for the given date input.

Parameters

ParameterDescription
inputA Date object or a parseable ISO date string

Throws

Throws Error("Invalid forecast time") when the input cannot be parsed to a finite timestamp.