spanSeconds

Unreleased

Not in @northguild/gmt 1.20.0 on npm yet. It is on main and ships in the next release.

Signature

spanSeconds(start: string, end: string): number | null

Return the exact elapsed seconds between two ISO 8601 instant strings.

• The same contract as spanMs, in seconds: signed, fractional and unrounded.
• Signed: negative when start is after end, so spanSeconds(b, a) is exactly -spanSeconds(a, b).
• Measures exact elapsed time, never calendar distance, as spanMs does. A wall-clock day containing a DST transition is 23 or 25 hours, and the hours that elapsed are reported. spanWallClock answers the calendar question.
• Fractional and unrounded. For a wait that must not fall short, write Math.ceil(n).
• Accepts the instant strings spanMs accepts: an offset designator (Z, ±HH:MM) is required, optionally followed by a bracketed IANA zone.
• Returns null on invalid input, not 0, which is the span between an instant and itself.
• Needs no safe-range guard: the widest possible span, 17_280_000_000_000 seconds, is well inside 2^53.
• Leap seconds are not counted (RFC 7519 section 2), as in spanMs.
• For the seconds left until a stored moment, use secondsUntilHttpDate or secondsUntilUnix.

Parameters

Parameter	Type	Description
start	string	ISO 8601 instant string the span is measured from
end	string	ISO 8601 instant string the span is measured to

Returns

exact elapsed seconds, negative when start is after end, or null on invalid input

Examples

import { spanSeconds } from "@northguild/gmt/span/calculate";

spanSeconds("2027-06-15T12:00:00Z", "2027-06-15T12:01:30Z") // 90

start

end

output

 

Source

span/calculate/spanSeconds.ts