isValidSpan

Signature

isValidSpan(start: string, end: string): boolean

Validate whether two ISO 8601 instant strings form a measurable span.

• True exactly when spanMs and spanNs will return a value rather than null — the endpoints both parse, so there is an elapsed time between them.
• Accepts what toNanoseconds does on both sides: an offset designator is required, optionally followed by a bracketed IANA zone; no leap seconds. Calendar and elective annotations are ignored, as Temporal.Instant.from ignores them. The two endpoints need not share a zone.
• The offset fixes the instant; a bracketed zone only resolves a rounded one. An offset written to the minute that is the bracketed zone’s sub-minute offset rounded (-00:45[Africa/Monrovia], for −00:44:30) names the instant the zone gives, as Temporal.ZonedDateTime.from reads it, so a zoned string Temporal wrote is read back as the instant it was written for, except a wall time repeated inside a sub-minute offset change, which reads as its first pass (see isValidInstant). Otherwise the bracket is not checked: a zone that does not exist, or that disagrees with the offset, changes nothing. Validity never depends on the bracket.
• Order does not matter. A span is signed, not invalid, when start is after end, so this is symmetric.
• spanMs can still return null on a pair this accepts — a span wider than Number.MAX_SAFE_INTEGER milliseconds has no number to return. That is a range limit on the result, not a defect in the inputs, and spanNs returns the exact bigint for the same pair.
• Does not validate spanWallClock, which needs a bracketed IANA zone on both endpoints rather than a bare offset — that is isValidZonedDateTime.
• Returns false for non-strings and empty strings.

Parameters

Parameter	Type	Description
start	string	candidate ISO 8601 instant string the span would be measured from
end	string	candidate ISO 8601 instant string the span would be measured to

Returns

boolean indicating whether spanMs/spanNs will measure this pair

Examples

import { isValidSpan } from "@northguild/gmt/span/validate";

isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // true

startend

output

 

Source

span/validate/isValidSpan.ts