ndfdTime.ts

Purpose

This module computes the inclusive local-time begin/end window sent to the NDFD XML API. NDFD requires local (non-UTC) datetime strings, and the window must be aligned to the anchor hour to produce consistent cache-compatible results.

Its responsibilities include:

• Validating the hours argument as a positive integer
• Validating the anchor date input
• Flooring the anchor to the nearest local hour boundary
• Computing the end time as begin + (hours − 1) hours
• Formatting both bounds as NDFD-compatible local datetime strings without timezone offset

Invariants

Hour Alignment

The begin time is always the anchor date floored to the nearest local hour (setMinutes(0, 0, 0)).

This guarantees that two calls with the same hour produce the same window regardless of the minute or second within that hour.

Inclusive End Bound

NDFD’s end parameter is inclusive. The end time is computed as:

end = begin + (hours − 1) × 3,600,000 ms

A request for hours = 24 produces a window spanning hour 0 through hour 23 inclusive (24 entries).

NDFD Local Format

Output strings use the format YYYY-MM-DDTHH:MM:SS with no timezone indicator, matching the NDFD API’s expected local-time format.

Input Validation

• hours must be a finite positive integer; otherwise throws Error("ndfdLocalWindow: hours must be a positive integer")
• anchor must parse to a finite timestamp; otherwise throws Error("ndfdLocalWindow: anchor time is invalid")

Exports

NdfdTimeWindow

type NdfdTimeWindow = {
	begin: string;
	end: string;
	beginDate: Date;
	endDate: Date;
};

ndfdLocalWindow(...)

function ndfdLocalWindow(
	hours: number,
	anchor?: Date | string,
): NdfdTimeWindow

Builds an inclusive local-time NDFD request window aligned to the anchor hour.

Parameters

Throws

Throws when hours is not a positive integer or anchor is not a valid date.