NTP Sync


A basic Network Time Protocol synchronization library.

Table of Contents

1. Usage
2. Compatibility
3. Instance options
4. Methods
* .generateData()
* .sync()
5. License

Usage

If you're not familiar with NTP yet then you'll probably want to read up on what the values mean first.

`` shell


Install package from npm


npm install @codebundlesbyvik/ntp-sync
`

If you're not using a module bundler then:
* Download the latest @codebundlesbyvik/js-helpers release from GitHub or load it directly via jsdelivr.
* Download the latest @codebundlesbyvik/ntp-sync release from GitHub or load it directly via jsdelivr.

For the example below I assume the main JavaScript file is processed by a module bundler.

` javascript
import Ntp, { convertUnixTimeFormatToMs } from "@codebundlesbyvik/ntp-sync";

const ntp = new Ntp({
t1EndpointUrl: "./api/ntp/get-server-time.php",
t1CalcFn: async function (response: Response) {
const fetchedData = (await response.json()) as unknown;

const isValidData = (data: unknown): data is { received_time: number } =>
typeof data === "object" && data !== null && "received_time" in data;

return isValidData(fetchedData)
? convertUnixTimeFormatToMs(fetchedData.received_time)
: null;
},
// Providing a t2CalcFn for greater accuracy is recommended but not required.
t2CalcFn: function (responseHeaders: Headers) {
// Header value example: t=1747777363406069 D=110
const header = responseHeaders.get("Response-Timing");

if (!header) return null;

const reqReceivedTime = /\bt=([0-9]+)\b/.exec(header);
const reqProcessingTime = /\bD=([0-9]+)\b/.exec(header);

if (!reqReceivedTime || !reqProcessingTime) return null;

const respTransmitTime =
Number.parseInt(reqReceivedTime[1]) + Number.parseInt(reqProcessingTime[1]);

return convertUnixTimeFormatToMs(respTransmitTime);
},
});

const values = await this.ntp.sync();
// {
// clientOffset: -296,
// correctedDate: 1747828823908,
// roundTripDelay: 591,
// }
`




Compatibility

Requires an ECMAScript 2022 (ES13) compatible environment. Practically speaking, all browsers released in 2021 and onwards are fully supported.




Instance options

| Property | Type | Default | Description |
| :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| t1EndpointUrl
Required if t1Endpoint not provided. | string | - | URL of the endpoint to retrieve t1 from. |
| t1Endpoint
Required if t1EndpointUrl not provided. | @codebundlesbyvik/js-helpers fetchWithTimeout parameters | - | Parameters for the fetcher used to retrieve t1. |
| t1CalcFn
Required | (response: Response) => Promise | - | Function used to process t1. |
| t2CalcFn | (responseHeaders: Headers) => number \| null | undefined | Function used for calculating t2. Recommended for greater precision. If not provided then t1 = t2. |
| maxSyncAttempts | number | 6 | Maximum amount of t1 fetch requests when .sync() is called (i.e. the amount of times .generateData() is called). |
| requiredOkSyncAttempts | number | 4 | Required amount of successful t1 fetch requests per .sync() call (i.e. the amount of .generateData() calls that must return a HTTP 200 status code). |




Methods

$3

Returns an object containing round-trip delay and client offset.

$3

Calls .generateData() at most maxSyncAttempts times, calculates an average of each value and returns them alongside a corrected Unix timestamp.

A helper function convertUnixTimeFormatToMs()` is also available and can be used to convert any format Unix timestamp dated after September 9th 2001 to one with millisecond precision.

License

MIT © 2025 Viktor Chin-Kon-Sung