fromNtpTimestamp

Signature

fromNtpTimestamp(value: bigint, eraArg?: number): string

Convert a 64-bit NTP timestamp (RFC 5905) back to an ISO 8601 instant string.

• value is unsigned: the whole 64-bit timestamp, seconds since 1900-01-01 in the high 32 bits and 2^-32 s units in the low 32. Values outside 0n–2^64 − 1 are rejected.
• era is required information the value does not carry. The seconds field wraps every 2^32 seconds (~136.19 years), so one timestamp names one instant per era: era 0 is 1900-01-01 to 2036-02-07T06:28:15Z, era 1 starts at 2036-02-07T06:28:16Z, era -1 starts at 1763-11-24T17:31:44Z. It defaults to 0; undefined is the same as omitting it, as TC39 treats an undefined argument as absent.
• Rounds to the nearest nanosecond. One NTP unit is ~233 ps, finer than an ISO string can express, so rounding — not truncation — is what makes fromNtpTimestamp(toNtpTimestamp(iso)) return iso exactly rather than one nanosecond early.
• The top two values of an era round onto the next era’s first instant. 2^64 − 1 and 2^64 − 2 in era 0 both render as "2036-02-07T06:28:16Z", which is where era 1 starts: the last 0.47 ns of an era has no nanosecond of its own, and the nearest one is the era boundary. toNtpTimestamp cannot produce either value from a nanosecond-precision instant — its largest era-0 output is 18446744073709551611n — so this does not affect the round trip.
• 0n is two things on the wire. RFC 5905 §6 defines the prime epoch as the instant “when all bits are zero”, and also says “a value of zero is a special case representing unknown or unsynchronized time” — for example a reference timestamp sent before the first sync. This function decodes 0n as the era’s first instant; a caller reading packet fields should test for 0n first when “unsynchronized” must not become a 1900 date.
• Returns "" when the resulting instant is outside the range Temporal.Instant can represent, which a large era will reach.
• Returns "" on invalid input.

Parameters

Parameter	Type	Description
value	bigint	64-bit NTP timestamp (bigint, 0n to 2^64 − 1)
eraArg	number	optional 136-year era selector; omitted or undefined is era 0

Returns

ISO 8601 instant string (UTC), or "" on invalid input

Examples

import { fromNtpTimestamp } from "@northguild/gmt/precision/convert";

fromNtpTimestamp(0n) // "1900-01-01T00:00:00Z" — the NTP epoch, and also RFC 5905's unknown or unsynchronized marker

valueeraArg ?

output

 

Source

precision/convert/fromNtpTimestamp.ts