Skip to content

Commit 37fdb86

Browse files
hkleungaihkleungai
committed
doc(node): Fix jsdoc for HRTime, modify test
1 parent 61576c3 commit 37fdb86

File tree

8 files changed

+198
-8
lines changed

8 files changed

+198
-8
lines changed

‎types/node/process.d.ts

+35-2
Original file line numberDiff line numberDiff line change
@@ -333,11 +333,43 @@ declare module "process" {
333333
TZ?: string;
334334
}
335335
interface HRTime {
336+
/**
337+
* This is the legacy version of {@link process.hrtime.bigint()}
338+
* before bigint was introduced in JavaScript.
339+
*
340+
* The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`,
341+
* where `nanoseconds` is the remaining part of the real time that can't be represented in second precision.
342+
*
343+
* `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time.
344+
* If the parameter passed in is not a tuple `Array`, a TypeError will be thrown.
345+
* Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior.
346+
*
347+
* These times are relative to an arbitrary time in the past,
348+
* and not related to the time of day and therefore not subject to clock drift.
349+
* The primary use is for measuring performance between intervals:
350+
* ```js
351+
* const { hrtime } = require('node:process');
352+
* const NS_PER_SEC = 1e9;
353+
* const time = hrtime();
354+
* // [ 1800216, 25 ]
355+
*
356+
* setTimeout(() => {
357+
* const diff = hrtime(time);
358+
* // [ 1, 552 ]
359+
*
360+
* console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
361+
* // Benchmark took 1000000552 nanoseconds
362+
* }, 1000);
363+
* ```
364+
* @since 0.7.6
365+
* @legacy Use {@link process.hrtime.bigint()} instead.
366+
* @param time The result of a previous call to `process.hrtime()`
367+
*/
336368
(time?: [number, number]): [number, number];
337369
/**
338-
* The `bigint` version of the `{@link hrtime()}` method returning the current high-resolution real time in nanoseconds as a `bigint`.
370+
* The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`.
339371
*
340-
* Unlike `{@link hrtime()}`, it does not support an additional time argument since the difference can just be computed directly by subtraction of the two `bigint`s.
372+
* Unlike {@link process.hrtime()}, it does not support an additional time argument since the difference can just be computed directly by subtraction of the two `bigint`s.
341373
* ```js
342374
* import { hrtime } from 'node:process';
343375
*
@@ -352,6 +384,7 @@ declare module "process" {
352384
* // Benchmark took 1154389282 nanoseconds
353385
* }, 1000);
354386
* ```
387+
* @since v10.7.0
355388
*/
356389
bigint(): bigint;
357390
}

‎types/node/test/process.ts

+6-1
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,12 @@ import { fileURLToPath } from "node:url";
129129
// This is some additional information
130130
}
131131

132-
const hrtimeBigint: bigint = process.hrtime.bigint();
132+
// $ExpectType [number, number]
133+
process.hrtime();
134+
// $ExpectType [number, number]
135+
process.hrtime([0, 0]);
136+
// $ExpectType bigint
137+
process.hrtime.bigint();
133138

134139
process.allowedNodeEnvironmentFlags.has("asdf");
135140

‎types/node/v16/process.d.ts

+52
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,59 @@ declare module "process" {
130130
TZ?: string;
131131
}
132132
interface HRTime {
133+
/**
134+
* This is the legacy version of {@link process.hrtime.bigint()}
135+
* before bigint was introduced in JavaScript.
136+
*
137+
* The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`,
138+
* where `nanoseconds` is the remaining part of the real time that can't be represented in second precision.
139+
*
140+
* `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time.
141+
* If the parameter passed in is not a tuple `Array`, a TypeError will be thrown.
142+
* Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior.
143+
*
144+
* These times are relative to an arbitrary time in the past,
145+
* and not related to the time of day and therefore not subject to clock drift.
146+
* The primary use is for measuring performance between intervals:
147+
* ```js
148+
* const { hrtime } = require('node:process');
149+
* const NS_PER_SEC = 1e9;
150+
* const time = hrtime();
151+
* // [ 1800216, 25 ]
152+
*
153+
* setTimeout(() => {
154+
* const diff = hrtime(time);
155+
* // [ 1, 552 ]
156+
*
157+
* console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
158+
* // Benchmark took 1000000552 nanoseconds
159+
* }, 1000);
160+
* ```
161+
* @since 0.7.6
162+
* @legacy Use {@link process.hrtime.bigint()} instead.
163+
* @param time The result of a previous call to `process.hrtime()`
164+
*/
133165
(time?: [number, number]): [number, number];
166+
/**
167+
* The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`.
168+
*
169+
* Unlike {@link process.hrtime()}, it does not support an additional time argument since the difference can just be computed directly by subtraction of the two `bigint`s.
170+
* ```js
171+
* import { hrtime } from 'node:process';
172+
*
173+
* const start = hrtime.bigint();
174+
* // 191051479007711n
175+
*
176+
* setTimeout(() => {
177+
* const end = hrtime.bigint();
178+
* // 191052633396993n
179+
*
180+
* console.log(`Benchmark took ${end - start} nanoseconds`);
181+
* // Benchmark took 1154389282 nanoseconds
182+
* }, 1000);
183+
* ```
184+
* @since v10.7.0
185+
*/
134186
bigint(): bigint;
135187
}
136188
interface ProcessReport {

‎types/node/v16/test/process.ts

+6-1
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,12 @@ import EventEmitter = require("node:events");
119119
// This is some additional information
120120
}
121121

122-
const hrtimeBigint: bigint = process.hrtime.bigint();
122+
// $ExpectType [number, number]
123+
process.hrtime();
124+
// $ExpectType [number, number]
125+
process.hrtime([0, 0]);
126+
// $ExpectType bigint
127+
process.hrtime.bigint();
123128

124129
process.allowedNodeEnvironmentFlags.has("asdf");
125130

‎types/node/v18/process.d.ts

+52
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,59 @@ declare module "process" {
141141
TZ?: string;
142142
}
143143
interface HRTime {
144+
/**
145+
* This is the legacy version of {@link process.hrtime.bigint()}
146+
* before bigint was introduced in JavaScript.
147+
*
148+
* The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`,
149+
* where `nanoseconds` is the remaining part of the real time that can't be represented in second precision.
150+
*
151+
* `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time.
152+
* If the parameter passed in is not a tuple `Array`, a TypeError will be thrown.
153+
* Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior.
154+
*
155+
* These times are relative to an arbitrary time in the past,
156+
* and not related to the time of day and therefore not subject to clock drift.
157+
* The primary use is for measuring performance between intervals:
158+
* ```js
159+
* const { hrtime } = require('node:process');
160+
* const NS_PER_SEC = 1e9;
161+
* const time = hrtime();
162+
* // [ 1800216, 25 ]
163+
*
164+
* setTimeout(() => {
165+
* const diff = hrtime(time);
166+
* // [ 1, 552 ]
167+
*
168+
* console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
169+
* // Benchmark took 1000000552 nanoseconds
170+
* }, 1000);
171+
* ```
172+
* @since 0.7.6
173+
* @legacy Use {@link process.hrtime.bigint()} instead.
174+
* @param time The result of a previous call to `process.hrtime()`
175+
*/
144176
(time?: [number, number]): [number, number];
177+
/**
178+
* The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`.
179+
*
180+
* Unlike {@link process.hrtime()}, it does not support an additional time argument since the difference can just be computed directly by subtraction of the two `bigint`s.
181+
* ```js
182+
* import { hrtime } from 'node:process';
183+
*
184+
* const start = hrtime.bigint();
185+
* // 191051479007711n
186+
*
187+
* setTimeout(() => {
188+
* const end = hrtime.bigint();
189+
* // 191052633396993n
190+
*
191+
* console.log(`Benchmark took ${end - start} nanoseconds`);
192+
* // Benchmark took 1154389282 nanoseconds
193+
* }, 1000);
194+
* ```
195+
* @since v10.7.0
196+
*/
145197
bigint(): bigint;
146198
}
147199
interface ProcessReport {

‎types/node/v18/test/process.ts

+6-1
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,12 @@ import EventEmitter = require("node:events");
121121
// This is some additional information
122122
}
123123

124-
const hrtimeBigint: bigint = process.hrtime.bigint();
124+
// $ExpectType [number, number]
125+
process.hrtime();
126+
// $ExpectType [number, number]
127+
process.hrtime([0, 0]);
128+
// $ExpectType bigint
129+
process.hrtime.bigint();
125130

126131
process.allowedNodeEnvironmentFlags.has("asdf");
127132

‎types/node/v20/process.d.ts

+35-2
Original file line numberDiff line numberDiff line change
@@ -273,11 +273,43 @@ declare module "process" {
273273
TZ?: string;
274274
}
275275
interface HRTime {
276+
/**
277+
* This is the legacy version of {@link process.hrtime.bigint()}
278+
* before bigint was introduced in JavaScript.
279+
*
280+
* The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`,
281+
* where `nanoseconds` is the remaining part of the real time that can't be represented in second precision.
282+
*
283+
* `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time.
284+
* If the parameter passed in is not a tuple `Array`, a TypeError will be thrown.
285+
* Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior.
286+
*
287+
* These times are relative to an arbitrary time in the past,
288+
* and not related to the time of day and therefore not subject to clock drift.
289+
* The primary use is for measuring performance between intervals:
290+
* ```js
291+
* const { hrtime } = require('node:process');
292+
* const NS_PER_SEC = 1e9;
293+
* const time = hrtime();
294+
* // [ 1800216, 25 ]
295+
*
296+
* setTimeout(() => {
297+
* const diff = hrtime(time);
298+
* // [ 1, 552 ]
299+
*
300+
* console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
301+
* // Benchmark took 1000000552 nanoseconds
302+
* }, 1000);
303+
* ```
304+
* @since 0.7.6
305+
* @legacy Use {@link process.hrtime.bigint()} instead.
306+
* @param time The result of a previous call to `process.hrtime()`
307+
*/
276308
(time?: [number, number]): [number, number];
277309
/**
278-
* The `bigint` version of the `{@link hrtime()}` method returning the current high-resolution real time in nanoseconds as a `bigint`.
310+
* The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`.
279311
*
280-
* Unlike `{@link hrtime()}`, it does not support an additional time argument since the difference can just be computed directly by subtraction of the two `bigint`s.
312+
* Unlike {@link process.hrtime()}, it does not support an additional time argument since the difference can just be computed directly by subtraction of the two `bigint`s.
281313
* ```js
282314
* import { hrtime } from 'node:process';
283315
*
@@ -292,6 +324,7 @@ declare module "process" {
292324
* // Benchmark took 1154389282 nanoseconds
293325
* }, 1000);
294326
* ```
327+
* @since v10.7.0
295328
*/
296329
bigint(): bigint;
297330
}

‎types/node/v20/test/process.ts

+6-1
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,12 @@ import { fileURLToPath } from "node:url";
128128
// This is some additional information
129129
}
130130

131-
const hrtimeBigint: bigint = process.hrtime.bigint();
131+
// $ExpectType [number, number]
132+
process.hrtime();
133+
// $ExpectType [number, number]
134+
process.hrtime([0, 0]);
135+
// $ExpectType bigint
136+
process.hrtime.bigint();
132137

133138
process.allowedNodeEnvironmentFlags.has("asdf");
134139

0 commit comments

Comments
 (0)