# spanSeconds

:::caution[Unreleased]
Not in `@northguild/gmt` 1.20.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
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

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

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

## Source

[span/calculate/spanSeconds.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/span/calculate/spanSeconds.ts)