An implementation of the W3C High Resolution Time Level 2 specification. 

timothygu

tmpvar

domenic

sebmaster

joris-van-der-wel

zirro

w3c-hr-time

* Do not allow infinite loops when calculating `hrtime()`'s offset relative to UNIX time. ([#9])

* Add Tidelift sponsorship link to README.

* Make `performance.toJSON()` return an object with `timeOrigin` property, per [clarifications from specification authors][heycam/webidl#505].

[heycam/webidl#505]: https://github.com/heycam/webidl/pull/505

[#3]: https://github.com/jsdom/w3c-hr-time/issues/3

[#9]: https://github.com/jsdom/w3c-hr-time/issues/9

// This files implements the calculation of the offset between the global monotonic clock and UNIX time. This value is

// known as |t1| in the calculation of "time origin timestamp" in the spec. This value needs to be calculated once and

// can be used in all subsequent Performance instances.

// However, if the clock is not fast enough, the export is undefined to signify that we should use Date.now() to get the

// time origin timestamp with millisecond accuracy, per spec.

const { getGlobalMonotonicClockMS } = require("./global-monotonic-clock");

const clockIsAccurate = require("./clock-is-accurate");

// This function assumes the clock is accurate.

  // Limit the iterations, just in case we're running in an environment where Date.now() has been mocked and is

  for (let i = 0; i < 1e6 && cur === start; i++) {

  // At this point |cur| "just" became equal to the next millisecond -- the unseen digits after |cur| are approximately

  // all 0, and |cur| is the closest to the actual value of the UNIX time. Now, get the current global monotonic clock

  // value and do the remaining calculations.

  return cur - getGlobalMonotonicClockMS();

  "description": "An implementation of the W3C High Resolution Time Level 2 specification.",

  "repository": "https://github.com/jsdom/w3c-hr-time",

  "author": "Timothy Gu <timothygu99@gmail.com>",

This module implements the W3C [High Resolution Time Level 2][HR-TIME] specification. It provides exactly three exports:

In all APIs, a "high-resolution timestamp" means a number in milliseconds that may have a fractional part, if the system clock is accurate enough (see "Clock accuracy" section below). It is identical to the [`DOMHighResTimeStamp`][] type in the High Resolution Time spec.

Portability is paramount to this module. It uses only APIs exposed from Node.js core like `Date.now()` and `process.hrtime()` and does not use or require any native modules. It also employs the [browser-process-hrtime][] module for graceful degrades for platforms that do not have `process.hrtime()` (such as browsers).

const { Performance } = require("w3c-hr-time");

// Prints a number close to Date.now() but that may have fractional parts, like

console.log(new Date(performance.timeOrigin));

// Prints a date close to new Date(), like 2018-01-02T10:22:43.819Z.

  // Prints a number close to 5000, like 5008.023059.

Perhaps the most interesting export is the [`Performance`][] class. By constructing the class, you can get an instance quite similar to the `window.performance` object in browsers. Specifically, the following APIs are implemented:

* [`performance.now(): number`][`Performance#now()`] returns the high-resolution duration since the construction of the `Performance` object.

* [`performance.timeOrigin: number`][`Performance#timeOrigin`] is a high-resolution timestamp of the `Performance` object's construction, expressed in [Unix time][].

* [`performance.toJSON(): object`][`Performance#toJSON()`] returns an object with `timeOrigin` property set to the corresponding value of this object. This allows serializing the `Performance` object with `JSON.stringify()`. In browsers, the returned object may contain additional properties such as `navigation` and `timing`. However, those properties are specific to browser navigation and are unsuitable for a Node.js implementation. Furthermore, they are specified not in the High Resolution Time spec but in [Navigation Timing][NAVIGATION-TIMING], and are thereby outside the scope of this module.

This module does not aim for full [Web IDL][WEBIDL] conformance, so things like `performance.toJSON.call({})` will not throw `TypeError`s like it does in browsers. If you need full Web IDL conformance, you may be interested in the [webidl2js][] module.

The `Performance` class provided also does not have `mark()`, `measure()`, `getEntries()`, and such functions. They are specified in other specs than High Resolution Timing, such as [User Timing][USER-TIMING] (marks and measures) and [Performance Timeline][PERFORMANCE-TIMELINE] (entries management). Those specs extend the definition of the `Performance` class defined in High Resolution Timing, and to implement those specs you can extend the `Performance` class exported by this module.

Due to the limitations of the APIs exposed through Node.js, the construction of a `Performance` object may take up to 1 millisecond to gather information for high-resolution `timeOrigin`.

The High Resolution Time spec defines a [global monotonic clock][] that is "shared by time origin's *[sic]*, is monotonically increasing and not subject to system clock adjustments or system clock skew, and whose reference point is the Unix time."

This module exports a function `getGlobalMonotonicClockMS()` that is the basis of all timing functions used my this module when a monotonic time is required. It returns a high-resolution timestamp whose zero value is at some arbitrary point in the past. (For the current high-resolution timestamp based on the Unix epoch, use `new Performance().timeOrigin` instead.)

const { getGlobalMonotonicClockMS } = require("w3c-hr-time");

const start = getGlobalMonotonicClockMS();

// Prints a millisecond timestamp based on an arbitrary point in the past, like

  console.log(getGlobalMonotonicClockMS() - a);

  // Prints a number close to 5000, like 5006.156536.

Unlike other functions that return only integer timestamps if the system clock does not provide enough resolution, this function may still return timestamps with fractional parts on those systems with less accurate clocks. See "Clock accuracy" section below for more information.

The High Resolution Time spec [states][HR-TIME §4] that

> A [`DOMHighResTimeStamp`][] *SHOULD* represent a time in milliseconds accurate to 5 microseconds - see [8. Privacy and Security][HR-TIME §8].

> If the User Agent is unable to provide a time value accurate to 5 microseconds due to hardware or software constraints, the User Agent can represent a [`DOMHighResTimeStamp`][] as a time in milliseconds accurate to a millisecond.

This module implements this suggestion faithfully. It executes a test at `require()`-time to determine if the system clock (both `Date.now()` and `process.hrtime()`) is accurate enough to 5 microseconds. The result of this test can be accessed through the exported `clockIsAccurate` boolean value.

const { Performance, clockIsAccurate } = require("w3c-hr-time");

  console.assert(Number.isInteger(performance.timeOrigin));

  console.assert(Number.isInteger(performance.now()));

If `clockIsAccurate` is false, `performance.timeOrigin` and `performance.now()` are always rounded to millisecond accuracy. `getGlobalMonotonicClockMS()` however is exempt from this requirement due to its best-effort nature, and the fact that it is not an API exposed by the High Resolution Time spec.

[Clock drift][clock drift] can be observed through system or user clock adjustments -- that is, the speed at which `Date.now()` changes may be faster or slower than real time if there is a pending adjustment to the system clock, for example through NTP synchronizing.

In the spec, the [global monotonic clock][] is defined to be immune to such drifts. Correspondingly, the APIs exposed through this module that are defined using the global monotonic clock such as `performance.now()` and `getGlobalMonotonicClockMS()` are also guaranteed to reflect real time.

For example, if `performance.now()` returns 1000, it is guaranteed that the time of this call is exactly one second since the construction of the `Performance` object. But the difference in `Date.now()`'s value from the construction of the `Performance` object to when `performance.now()` returns 1000 may not be exactly 1000. You may also see `performance.now() - Date.now()` diverge over time as a result of clock drifts.

On the other hand, `performance.timeOrigin` returns the *[Unix time][]* at which the `Performance` object is constructed and relies on the current time exposed through `Date.now()`. That means that it is susceptible to clock drifts that has occurred before the `Performance` object was constructed.

The jsdom project (including w3c-hr-time) is a community-driven project maintained by a team of [volunteers](https://github.com/orgs/jsdom/people). You could support us by:

- [Getting professional support for w3c-hr-time](https://tidelift.com/subscription/pkg/npm-w3c-hr-time?utm_source=npm-w3c-hr-time&utm_medium=referral&utm_campaign=readme) as part of a Tidelift subscription. Tidelift helps making open source sustainable for us while giving teams assurances for maintenance, licensing, and security.

This software is licensed under the MIT license. See LICENSE.md file for more detail.

[HR-TIME]: https://w3c.github.io/hr-time/

[NAVIGATION-TIMING]: https://w3c.github.io/navigation-timing/

[PERFORMANCE-TIMELINE]: https://w3c.github.io/performance-timeline/

[USER-TIMING]: https://w3c.github.io/user-timing/

[WEBIDL]: https://heycam.github.io/webidl/

[HR-TIME §4]: https://w3c.github.io/hr-time/#dom-domhighrestimestamp

[HR-TIME §8]: https://w3c.github.io/hr-time/#privacy-security

[`DOMHighResTimeStamp`]: https://w3c.github.io/hr-time/#dom-domhighrestimestamp

[`Performance`]: https://w3c.github.io/hr-time/#dfn-performance

[`Performance#now()`]: https://w3c.github.io/hr-time/#dom-performance-now

[`Performance#timeOrigin`]: https://w3c.github.io/hr-time/#dom-performance-timeorigin

[`Performance#toJSON()`]: https://w3c.github.io/hr-time/#dom-performance-tojson

[browser-process-hrtime]: https://www.npmjs.com/package/browser-process-hrtime

[clock drift]: https://en.wikipedia.org/wiki/Clock_drift

[global monotonic clock]: https://w3c.github.io/hr-time/#dfn-global-monotonic-clock

[Unix time]: https://en.wikipedia.org/wiki/Unix_time

[webidl2js]: https://github.com/jsdom/webidl2js

		@@ -17,3 +17,5 @@ "use strict";
		let cur = start;
		while (cur === start) {
		// Limit the iterations, just in case we're running in an environment where Date.now() has been mocked and is
		// constant.
		for (let i = 0; i < 1e6 && cur === start; i++) {
		cur = Date.now();
		@@ -20,0 +22,0 @@ }

		{
		"name": "w3c-hr-time",
		"version": "1.0.1",
		"version": "1.0.2",
		"description": "An implementation of the W3C High Resolution Time Level 2 specification.",
		@@ -11,3 +11,3 @@ "main": "index.js",
		"dependencies": {
		"browser-process-hrtime": "^0.1.2"
		"browser-process-hrtime": "^1.0.0"
		},
		@@ -17,3 +17,3 @@ "devDependencies": {
		"eslint-plugin-jest": "^21.5.0",
		"jest": "^22.0.4"
		"jest": "^24.1.0"
		},
		@@ -20,0 +20,0 @@ "scripts": {

		@@ -101,2 +101,13 @@ # w3c-hr-time

		## Supporting w3c-hr-time

		The jsdom project (including w3c-hr-time) is a community-driven project maintained by a team of [volunteers](https://github.com/orgs/jsdom/people). You could support us by:

		- [Getting professional support for w3c-hr-time](https://tidelift.com/subscription/pkg/npm-w3c-hr-time?utm_source=npm-w3c-hr-time&utm_medium=referral&utm_campaign=readme) as part of a Tidelift subscription. Tidelift helps making open source sustainable for us while giving teams assurances for maintenance, licensing, and security.
		- Contributing directly to the project.

		## License

		This software is licensed under the MIT license. See LICENSE.md file for more detail.

		[HR-TIME]: https://w3c.github.io/hr-time/
		@@ -103,0 +114,0 @@ [NAVIGATION-TIMING]: https://w3c.github.io/navigation-timing/

Improved metrics

Dependency changes

		# Change log

		## 1.0.2 (2020-03-05)

		* Do not allow infinite loops when calculating `hrtime()`'s offset relative to UNIX time. ([#9])
		* Add a LICENSE file. ([#3])
		* Add Tidelift sponsorship link to README.

		## 1.0.1 (2018-01-03)
		@@ -12,1 +18,3 @@
		[heycam/webidl#505]: https://github.com/heycam/webidl/pull/505
		[#3]: https://github.com/jsdom/w3c-hr-time/issues/3
		[#9]: https://github.com/jsdom/w3c-hr-time/issues/9