Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc(node): Fix jsdoc for HRTime, modify test #71370

Merged
merged 1 commit into from
Jan 16, 2025
Merged

doc(node): Fix jsdoc for HRTime, modify test #71370

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions types/node/process.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -333,11 +333,43 @@ declare module "process" {
TZ?: string;
}
interface HRTime {
/**
* This is the legacy version of {@link process.hrtime.bigint()}
* before bigint was introduced in JavaScript.
*
* The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`,
* where `nanoseconds` is the remaining part of the real time that can't be represented in second precision.
*
* `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time.
* If the parameter passed in is not a tuple `Array`, a TypeError will be thrown.
* Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior.
*
* These times are relative to an arbitrary time in the past,
* and not related to the time of day and therefore not subject to clock drift.
* The primary use is for measuring performance between intervals:
* ```js
* const { hrtime } = require('node:process');
* const NS_PER_SEC = 1e9;
* const time = hrtime();
* // [ 1800216, 25 ]
*
* setTimeout(() => {
* const diff = hrtime(time);
* // [ 1, 552 ]
*
* console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
* // Benchmark took 1000000552 nanoseconds
* }, 1000);
* ```
* @since 0.7.6
* @legacy Use {@link process.hrtime.bigint()} instead.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@legacy is not a known jsdoc tag. It should be written as @deprecated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the late response. @legacy is used due to @Renegade334's suggestion on previous review comment. I think I am not gonna change it.

* @param time The result of a previous call to `process.hrtime()`
*/
(time?: [number, number]): [number, number];
/**
* The `bigint` version of the `{@link hrtime()}` method returning the current high-resolution real time in nanoseconds as a `bigint`.
* The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`.
*
* 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.
* 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.
* ```js
* import { hrtime } from 'node:process';
*
Expand All @@ -352,6 +384,7 @@ declare module "process" {
* // Benchmark took 1154389282 nanoseconds
* }, 1000);
* ```
* @since v10.7.0
*/
bigint(): bigint;
}
Expand Down
7 changes: 6 additions & 1 deletion types/node/test/process.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,12 @@ import { fileURLToPath } from "node:url";
// This is some additional information
}

const hrtimeBigint: bigint = process.hrtime.bigint();
// $ExpectType [number, number]
process.hrtime();
// $ExpectType [number, number]
process.hrtime([0, 0]);
// $ExpectType bigint
process.hrtime.bigint();

process.allowedNodeEnvironmentFlags.has("asdf");

Expand Down
52 changes: 52 additions & 0 deletions types/node/v16/process.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,59 @@ declare module "process" {
TZ?: string;
}
interface HRTime {
/**
* This is the legacy version of {@link process.hrtime.bigint()}
* before bigint was introduced in JavaScript.
*
* The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`,
* where `nanoseconds` is the remaining part of the real time that can't be represented in second precision.
*
* `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time.
* If the parameter passed in is not a tuple `Array`, a TypeError will be thrown.
* Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior.
*
* These times are relative to an arbitrary time in the past,
* and not related to the time of day and therefore not subject to clock drift.
* The primary use is for measuring performance between intervals:
* ```js
* const { hrtime } = require('node:process');
* const NS_PER_SEC = 1e9;
* const time = hrtime();
* // [ 1800216, 25 ]
*
* setTimeout(() => {
* const diff = hrtime(time);
* // [ 1, 552 ]
*
* console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
* // Benchmark took 1000000552 nanoseconds
* }, 1000);
* ```
* @since 0.7.6
* @legacy Use {@link process.hrtime.bigint()} instead.
* @param time The result of a previous call to `process.hrtime()`
*/
(time?: [number, number]): [number, number];
/**
* The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`.
*
* 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.
* ```js
* import { hrtime } from 'node:process';
*
* const start = hrtime.bigint();
* // 191051479007711n
*
* setTimeout(() => {
* const end = hrtime.bigint();
* // 191052633396993n
*
* console.log(`Benchmark took ${end - start} nanoseconds`);
* // Benchmark took 1154389282 nanoseconds
* }, 1000);
* ```
* @since v10.7.0
*/
bigint(): bigint;
}
interface ProcessReport {
Expand Down
7 changes: 6 additions & 1 deletion types/node/v16/test/process.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,12 @@ import EventEmitter = require("node:events");
// This is some additional information
}

const hrtimeBigint: bigint = process.hrtime.bigint();
// $ExpectType [number, number]
process.hrtime();
// $ExpectType [number, number]
process.hrtime([0, 0]);
// $ExpectType bigint
process.hrtime.bigint();

process.allowedNodeEnvironmentFlags.has("asdf");

Expand Down
52 changes: 52 additions & 0 deletions types/node/v18/process.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,59 @@ declare module "process" {
TZ?: string;
}
interface HRTime {
/**
* This is the legacy version of {@link process.hrtime.bigint()}
* before bigint was introduced in JavaScript.
*
* The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`,
* where `nanoseconds` is the remaining part of the real time that can't be represented in second precision.
*
* `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time.
* If the parameter passed in is not a tuple `Array`, a TypeError will be thrown.
* Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior.
*
* These times are relative to an arbitrary time in the past,
* and not related to the time of day and therefore not subject to clock drift.
* The primary use is for measuring performance between intervals:
* ```js
* const { hrtime } = require('node:process');
* const NS_PER_SEC = 1e9;
* const time = hrtime();
* // [ 1800216, 25 ]
*
* setTimeout(() => {
* const diff = hrtime(time);
* // [ 1, 552 ]
*
* console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
* // Benchmark took 1000000552 nanoseconds
* }, 1000);
* ```
* @since 0.7.6
* @legacy Use {@link process.hrtime.bigint()} instead.
* @param time The result of a previous call to `process.hrtime()`
*/
(time?: [number, number]): [number, number];
/**
* The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`.
*
* 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.
* ```js
* import { hrtime } from 'node:process';
*
* const start = hrtime.bigint();
* // 191051479007711n
*
* setTimeout(() => {
* const end = hrtime.bigint();
* // 191052633396993n
*
* console.log(`Benchmark took ${end - start} nanoseconds`);
* // Benchmark took 1154389282 nanoseconds
* }, 1000);
* ```
* @since v10.7.0
*/
bigint(): bigint;
}
interface ProcessReport {
Expand Down
7 changes: 6 additions & 1 deletion types/node/v18/test/process.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,12 @@ import EventEmitter = require("node:events");
// This is some additional information
}

const hrtimeBigint: bigint = process.hrtime.bigint();
// $ExpectType [number, number]
process.hrtime();
// $ExpectType [number, number]
process.hrtime([0, 0]);
// $ExpectType bigint
process.hrtime.bigint();

process.allowedNodeEnvironmentFlags.has("asdf");

Expand Down
37 changes: 35 additions & 2 deletions types/node/v20/process.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,11 +273,43 @@ declare module "process" {
TZ?: string;
}
interface HRTime {
/**
* This is the legacy version of {@link process.hrtime.bigint()}
* before bigint was introduced in JavaScript.
*
* The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`,
* where `nanoseconds` is the remaining part of the real time that can't be represented in second precision.
*
* `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time.
* If the parameter passed in is not a tuple `Array`, a TypeError will be thrown.
* Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior.
*
* These times are relative to an arbitrary time in the past,
* and not related to the time of day and therefore not subject to clock drift.
* The primary use is for measuring performance between intervals:
* ```js
* const { hrtime } = require('node:process');
* const NS_PER_SEC = 1e9;
* const time = hrtime();
* // [ 1800216, 25 ]
*
* setTimeout(() => {
* const diff = hrtime(time);
* // [ 1, 552 ]
*
* console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
* // Benchmark took 1000000552 nanoseconds
* }, 1000);
* ```
* @since 0.7.6
* @legacy Use {@link process.hrtime.bigint()} instead.
* @param time The result of a previous call to `process.hrtime()`
*/
(time?: [number, number]): [number, number];
/**
* The `bigint` version of the `{@link hrtime()}` method returning the current high-resolution real time in nanoseconds as a `bigint`.
* The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`.
*
* 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.
* 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.
* ```js
* import { hrtime } from 'node:process';
*
Expand All @@ -292,6 +324,7 @@ declare module "process" {
* // Benchmark took 1154389282 nanoseconds
* }, 1000);
* ```
* @since v10.7.0
*/
bigint(): bigint;
}
Expand Down
7 changes: 6 additions & 1 deletion types/node/v20/test/process.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,12 @@ import { fileURLToPath } from "node:url";
// This is some additional information
}

const hrtimeBigint: bigint = process.hrtime.bigint();
// $ExpectType [number, number]
process.hrtime();
// $ExpectType [number, number]
process.hrtime([0, 0]);
// $ExpectType bigint
process.hrtime.bigint();

process.allowedNodeEnvironmentFlags.has("asdf");

Expand Down
Loading