util.d.ts (65677B)
1 /** 2 * The `util` module supports the needs of Node.js internal APIs. Many of the 3 * utilities are useful for application and module developers as well. To access 4 * it: 5 * 6 * ```js 7 * import util from 'node:util'; 8 * ``` 9 * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/util.js) 10 */ 11 declare module "util" { 12 import * as types from "node:util/types"; 13 export interface InspectOptions { 14 /** 15 * If set to `true`, getters are going to be 16 * inspected as well. If set to `'get'` only getters without setter are going 17 * to be inspected. If set to `'set'` only getters having a corresponding 18 * setter are going to be inspected. This might cause side effects depending on 19 * the getter function. 20 * @default `false` 21 */ 22 getters?: "get" | "set" | boolean | undefined; 23 showHidden?: boolean | undefined; 24 /** 25 * @default 2 26 */ 27 depth?: number | null | undefined; 28 colors?: boolean | undefined; 29 customInspect?: boolean | undefined; 30 showProxy?: boolean | undefined; 31 maxArrayLength?: number | null | undefined; 32 /** 33 * Specifies the maximum number of characters to 34 * include when formatting. Set to `null` or `Infinity` to show all elements. 35 * Set to `0` or negative to show no characters. 36 * @default 10000 37 */ 38 maxStringLength?: number | null | undefined; 39 breakLength?: number | undefined; 40 /** 41 * Setting this to `false` causes each object key 42 * to be displayed on a new line. It will also add new lines to text that is 43 * longer than `breakLength`. If set to a number, the most `n` inner elements 44 * are united on a single line as long as all properties fit into 45 * `breakLength`. Short array elements are also grouped together. Note that no 46 * text will be reduced below 16 characters, no matter the `breakLength` size. 47 * For more information, see the example below. 48 * @default `true` 49 */ 50 compact?: boolean | number | undefined; 51 sorted?: boolean | ((a: string, b: string) => number) | undefined; 52 } 53 export type Style = 54 | "special" 55 | "number" 56 | "bigint" 57 | "boolean" 58 | "undefined" 59 | "null" 60 | "string" 61 | "symbol" 62 | "date" 63 | "regexp" 64 | "module"; 65 export type CustomInspectFunction = (depth: number, options: InspectOptionsStylized) => string; 66 export interface InspectOptionsStylized extends InspectOptions { 67 stylize(text: string, styleType: Style): string; 68 } 69 /** 70 * The `util.format()` method returns a formatted string using the first argument 71 * as a `printf`\-like format string which can contain zero or more format 72 * specifiers. Each specifier is replaced with the converted value from the 73 * corresponding argument. Supported specifiers are: 74 * 75 * If a specifier does not have a corresponding argument, it is not replaced: 76 * 77 * ```js 78 * util.format('%s:%s', 'foo'); 79 * // Returns: 'foo:%s' 80 * ``` 81 * 82 * Values that are not part of the format string are formatted using`util.inspect()` if their type is not `string`. 83 * 84 * If there are more arguments passed to the `util.format()` method than the 85 * number of specifiers, the extra arguments are concatenated to the returned 86 * string, separated by spaces: 87 * 88 * ```js 89 * util.format('%s:%s', 'foo', 'bar', 'baz'); 90 * // Returns: 'foo:bar baz' 91 * ``` 92 * 93 * If the first argument does not contain a valid format specifier, `util.format()`returns a string that is the concatenation of all arguments separated by spaces: 94 * 95 * ```js 96 * util.format(1, 2, 3); 97 * // Returns: '1 2 3' 98 * ``` 99 * 100 * If only one argument is passed to `util.format()`, it is returned as it is 101 * without any formatting: 102 * 103 * ```js 104 * util.format('%% %s'); 105 * // Returns: '%% %s' 106 * ``` 107 * 108 * `util.format()` is a synchronous method that is intended as a debugging tool. 109 * Some input values can have a significant performance overhead that can block the 110 * event loop. Use this function with care and never in a hot code path. 111 * @since v0.5.3 112 * @param format A `printf`-like format string. 113 */ 114 export function format(format?: any, ...param: any[]): string; 115 /** 116 * This function is identical to {@link format}, except in that it takes 117 * an `inspectOptions` argument which specifies options that are passed along to {@link inspect}. 118 * 119 * ```js 120 * util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 }); 121 * // Returns 'See object { foo: 42 }', where `42` is colored as a number 122 * // when printed to a terminal. 123 * ``` 124 * @since v10.0.0 125 */ 126 export function formatWithOptions(inspectOptions: InspectOptions, format?: any, ...param: any[]): string; 127 /** 128 * Returns the string name for a numeric error code that comes from a Node.js API. 129 * The mapping between error codes and error names is platform-dependent. 130 * See `Common System Errors` for the names of common errors. 131 * 132 * ```js 133 * fs.access('file/that/does/not/exist', (err) => { 134 * const name = util.getSystemErrorName(err.errno); 135 * console.error(name); // ENOENT 136 * }); 137 * ``` 138 * @since v9.7.0 139 */ 140 export function getSystemErrorName(err: number): string; 141 /** 142 * Returns a Map of all system error codes available from the Node.js API. 143 * The mapping between error codes and error names is platform-dependent. 144 * See `Common System Errors` for the names of common errors. 145 * 146 * ```js 147 * fs.access('file/that/does/not/exist', (err) => { 148 * const errorMap = util.getSystemErrorMap(); 149 * const name = errorMap.get(err.errno); 150 * console.error(name); // ENOENT 151 * }); 152 * ``` 153 * @since v16.0.0 154 */ 155 export function getSystemErrorMap(): Map<number, [string, string]>; 156 /** 157 * The `util.log()` method prints the given `string` to `stdout` with an included 158 * timestamp. 159 * 160 * ```js 161 * import util from 'node:util'; 162 * 163 * util.log('Timestamped message.'); 164 * ``` 165 * @since v0.3.0 166 * @deprecated Since v6.0.0 - Use a third party module instead. 167 */ 168 export function log(string: string): void; 169 /** 170 * Returns the `string` after replacing any surrogate code points 171 * (or equivalently, any unpaired surrogate code units) with the 172 * Unicode "replacement character" U+FFFD. 173 * @since v16.8.0 174 */ 175 export function toUSVString(string: string): string; 176 /** 177 * The `util.inspect()` method returns a string representation of `object` that is 178 * intended for debugging. The output of `util.inspect` may change at any time 179 * and should not be depended upon programmatically. Additional `options` may be 180 * passed that alter the result.`util.inspect()` will use the constructor's name and/or `@@toStringTag` to make 181 * an identifiable tag for an inspected value. 182 * 183 * ```js 184 * class Foo { 185 * get [Symbol.toStringTag]() { 186 * return 'bar'; 187 * } 188 * } 189 * 190 * class Bar {} 191 * 192 * const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } }); 193 * 194 * util.inspect(new Foo()); // 'Foo [bar] {}' 195 * util.inspect(new Bar()); // 'Bar {}' 196 * util.inspect(baz); // '[foo] {}' 197 * ``` 198 * 199 * Circular references point to their anchor by using a reference index: 200 * 201 * ```js 202 * import { inspect } from 'node:util'; 203 * 204 * const obj = {}; 205 * obj.a = [obj]; 206 * obj.b = {}; 207 * obj.b.inner = obj.b; 208 * obj.b.obj = obj; 209 * 210 * console.log(inspect(obj)); 211 * // <ref *1> { 212 * // a: [ [Circular *1] ], 213 * // b: <ref *2> { inner: [Circular *2], obj: [Circular *1] } 214 * // } 215 * ``` 216 * 217 * The following example inspects all properties of the `util` object: 218 * 219 * ```js 220 * import util from 'node:util'; 221 * 222 * console.log(util.inspect(util, { showHidden: true, depth: null })); 223 * ``` 224 * 225 * The following example highlights the effect of the `compact` option: 226 * 227 * ```js 228 * import util from 'node:util'; 229 * 230 * const o = { 231 * a: [1, 2, [[ 232 * 'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' + 233 * 'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.', 234 * 'test', 235 * 'foo']], 4], 236 * b: new Map([['za', 1], ['zb', 'test']]) 237 * }; 238 * console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 })); 239 * 240 * // { a: 241 * // [ 1, 242 * // 2, 243 * // [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line 244 * // 'test', 245 * // 'foo' ] ], 246 * // 4 ], 247 * // b: Map(2) { 'za' => 1, 'zb' => 'test' } } 248 * 249 * // Setting `compact` to false or an integer creates more reader friendly output. 250 * console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 })); 251 * 252 * // { 253 * // a: [ 254 * // 1, 255 * // 2, 256 * // [ 257 * // [ 258 * // 'Lorem ipsum dolor sit amet,\n' + 259 * // 'consectetur adipiscing elit, sed do eiusmod \n' + 260 * // 'tempor incididunt ut labore et dolore magna aliqua.', 261 * // 'test', 262 * // 'foo' 263 * // ] 264 * // ], 265 * // 4 266 * // ], 267 * // b: Map(2) { 268 * // 'za' => 1, 269 * // 'zb' => 'test' 270 * // } 271 * // } 272 * 273 * // Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a 274 * // single line. 275 * ``` 276 * 277 * The `showHidden` option allows [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) and 278 * [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) entries to be 279 * inspected. If there are more entries than `maxArrayLength`, there is no 280 * guarantee which entries are displayed. That means retrieving the same [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) entries twice may 281 * result in different output. Furthermore, entries 282 * with no remaining strong references may be garbage collected at any time. 283 * 284 * ```js 285 * import { inspect } from 'node:util'; 286 * 287 * const obj = { a: 1 }; 288 * const obj2 = { b: 2 }; 289 * const weakSet = new WeakSet([obj, obj2]); 290 * 291 * console.log(inspect(weakSet, { showHidden: true })); 292 * // WeakSet { { a: 1 }, { b: 2 } } 293 * ``` 294 * 295 * The `sorted` option ensures that an object's property insertion order does not 296 * impact the result of `util.inspect()`. 297 * 298 * ```js 299 * import { inspect } from 'node:util'; 300 * import assert from 'node:assert'; 301 * 302 * const o1 = { 303 * b: [2, 3, 1], 304 * a: '`a` comes before `b`', 305 * c: new Set([2, 3, 1]) 306 * }; 307 * console.log(inspect(o1, { sorted: true })); 308 * // { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } } 309 * console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) })); 310 * // { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' } 311 * 312 * const o2 = { 313 * c: new Set([2, 1, 3]), 314 * a: '`a` comes before `b`', 315 * b: [2, 3, 1] 316 * }; 317 * assert.strict.equal( 318 * inspect(o1, { sorted: true }), 319 * inspect(o2, { sorted: true }) 320 * ); 321 * ``` 322 * 323 * `util.inspect()` is a synchronous method intended for debugging. Its maximum 324 * output length is approximately 128 MB. Inputs that result in longer output will 325 * be truncated. 326 * @since v0.3.0 327 * @param object Any JavaScript primitive or `Object`. 328 * @return The representation of `object`. 329 */ 330 export function inspect(object: any, showHidden?: boolean, depth?: number | null, color?: boolean): string; 331 export function inspect(object: any, options?: InspectOptions): string; 332 export namespace inspect { 333 let colors: NodeJS.Dict<[number, number]>; 334 let styles: { 335 [K in Style]: string; 336 }; 337 let defaultOptions: InspectOptions; 338 /** 339 * Allows changing inspect settings from the repl. 340 */ 341 let replDefaults: InspectOptions; 342 /** 343 * That can be used to declare custom inspect functions. 344 */ 345 const custom: unique symbol; 346 } 347 /** 348 * Alias for [`Array.isArray()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray). 349 * 350 * Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`. 351 * 352 * ```js 353 * import util from 'node:util'; 354 * 355 * util.isArray([]); 356 * // Returns: true 357 * util.isArray(new Array()); 358 * // Returns: true 359 * util.isArray({}); 360 * // Returns: false 361 * ``` 362 * @since v0.6.0 363 * @deprecated Since v4.0.0 - Use `isArray` instead. 364 */ 365 export function isArray(object: unknown): object is unknown[]; 366 /** 367 * Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`. 368 * 369 * ```js 370 * import util from 'node:util'; 371 * 372 * util.isRegExp(/some regexp/); 373 * // Returns: true 374 * util.isRegExp(new RegExp('another regexp')); 375 * // Returns: true 376 * util.isRegExp({}); 377 * // Returns: false 378 * ``` 379 * @since v0.6.0 380 * @deprecated Since v4.0.0 - Deprecated 381 */ 382 export function isRegExp(object: unknown): object is RegExp; 383 /** 384 * Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`. 385 * 386 * ```js 387 * import util from 'node:util'; 388 * 389 * util.isDate(new Date()); 390 * // Returns: true 391 * util.isDate(Date()); 392 * // false (without 'new' returns a String) 393 * util.isDate({}); 394 * // Returns: false 395 * ``` 396 * @since v0.6.0 397 * @deprecated Since v4.0.0 - Use {@link types.isDate} instead. 398 */ 399 export function isDate(object: unknown): object is Date; 400 /** 401 * Returns `true` if the given `object` is an `Error`. Otherwise, returns`false`. 402 * 403 * ```js 404 * import util from 'node:util'; 405 * 406 * util.isError(new Error()); 407 * // Returns: true 408 * util.isError(new TypeError()); 409 * // Returns: true 410 * util.isError({ name: 'Error', message: 'an error occurred' }); 411 * // Returns: false 412 * ``` 413 * 414 * This method relies on `Object.prototype.toString()` behavior. It is 415 * possible to obtain an incorrect result when the `object` argument manipulates`@@toStringTag`. 416 * 417 * ```js 418 * import util from 'node:util'; 419 * const obj = { name: 'Error', message: 'an error occurred' }; 420 * 421 * util.isError(obj); 422 * // Returns: false 423 * obj[Symbol.toStringTag] = 'Error'; 424 * util.isError(obj); 425 * // Returns: true 426 * ``` 427 * @since v0.6.0 428 * @deprecated Since v4.0.0 - Use {@link types.isNativeError} instead. 429 */ 430 export function isError(object: unknown): object is Error; 431 /** 432 * Usage of `util.inherits()` is discouraged. Please use the ES6 `class` and `extends` keywords to get language level inheritance support. Also note 433 * that the two styles are [semantically incompatible](https://github.com/nodejs/node/issues/4179). 434 * 435 * Inherit the prototype methods from one [constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) into another. The 436 * prototype of `constructor` will be set to a new object created from`superConstructor`. 437 * 438 * This mainly adds some input validation on top of`Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)`. 439 * As an additional convenience, `superConstructor` will be accessible 440 * through the `constructor.super_` property. 441 * 442 * ```js 443 * import util from 'node:util'; 444 * import EventEmitter from 'node:events'; 445 * 446 * function MyStream() { 447 * EventEmitter.call(this); 448 * } 449 * 450 * util.inherits(MyStream, EventEmitter); 451 * 452 * MyStream.prototype.write = function(data) { 453 * this.emit('data', data); 454 * }; 455 * 456 * const stream = new MyStream(); 457 * 458 * console.log(stream instanceof EventEmitter); // true 459 * console.log(MyStream.super_ === EventEmitter); // true 460 * 461 * stream.on('data', (data) => { 462 * console.log(`Received data: "${data}"`); 463 * }); 464 * stream.write('It works!'); // Received data: "It works!" 465 * ``` 466 * 467 * ES6 example using `class` and `extends`: 468 * 469 * ```js 470 * import EventEmitter from 'node:events'; 471 * 472 * class MyStream extends EventEmitter { 473 * write(data) { 474 * this.emit('data', data); 475 * } 476 * } 477 * 478 * const stream = new MyStream(); 479 * 480 * stream.on('data', (data) => { 481 * console.log(`Received data: "${data}"`); 482 * }); 483 * stream.write('With ES6'); 484 * ``` 485 * @since v0.3.0 486 * @legacy Use ES2015 class syntax and `extends` keyword instead. 487 */ 488 export function inherits(constructor: unknown, superConstructor: unknown): void; 489 export type DebugLoggerFunction = (msg: string, ...param: unknown[]) => void; 490 export interface DebugLogger extends DebugLoggerFunction { 491 enabled: boolean; 492 } 493 /** 494 * The `util.debuglog()` method is used to create a function that conditionally 495 * writes debug messages to `stderr` based on the existence of the `NODE_DEBUG`environment variable. If the `section` name appears within the value of that 496 * environment variable, then the returned function operates similar to `console.error()`. If not, then the returned function is a no-op. 497 * 498 * ```js 499 * import util from 'node:util'; 500 * const debuglog = util.debuglog('foo'); 501 * 502 * debuglog('hello from foo [%d]', 123); 503 * ``` 504 * 505 * If this program is run with `NODE_DEBUG=foo` in the environment, then 506 * it will output something like: 507 * 508 * ```console 509 * FOO 3245: hello from foo [123] 510 * ``` 511 * 512 * where `3245` is the process id. If it is not run with that 513 * environment variable set, then it will not print anything. 514 * 515 * The `section` supports wildcard also: 516 * 517 * ```js 518 * import util from 'node:util'; 519 * const debuglog = util.debuglog('foo-bar'); 520 * 521 * debuglog('hi there, it\'s foo-bar [%d]', 2333); 522 * ``` 523 * 524 * if it is run with `NODE_DEBUG=foo*` in the environment, then it will output 525 * something like: 526 * 527 * ```console 528 * FOO-BAR 3257: hi there, it's foo-bar [2333] 529 * ``` 530 * 531 * Multiple comma-separated `section` names may be specified in the `NODE_DEBUG`environment variable: `NODE_DEBUG=fs,net,tls`. 532 * 533 * The optional `callback` argument can be used to replace the logging function 534 * with a different function that doesn't have any initialization or 535 * unnecessary wrapping. 536 * 537 * ```js 538 * import util from 'node:util'; 539 * let debuglog = util.debuglog('internals', (debug) => { 540 * // Replace with a logging function that optimizes out 541 * // testing if the section is enabled 542 * debuglog = debug; 543 * }); 544 * ``` 545 * @since v0.11.3 546 * @param section A string identifying the portion of the application for which the `debuglog` function is being created. 547 * @param callback A callback invoked the first time the logging function is called with a function argument that is a more optimized logging function. 548 * @return The logging function 549 */ 550 export function debuglog(section: string, callback?: (fn: DebugLoggerFunction) => void): DebugLogger; 551 export const debug: typeof debuglog; 552 /** 553 * Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`. 554 * 555 * ```js 556 * import util from 'node:util'; 557 * 558 * util.isBoolean(1); 559 * // Returns: false 560 * util.isBoolean(0); 561 * // Returns: false 562 * util.isBoolean(false); 563 * // Returns: true 564 * ``` 565 * @since v0.11.5 566 * @deprecated Since v4.0.0 - Use `typeof value === 'boolean'` instead. 567 */ 568 export function isBoolean(object: unknown): object is boolean; 569 /** 570 * Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`. 571 * 572 * ```js 573 * import util from 'node:util'; 574 * 575 * util.isBuffer({ length: 0 }); 576 * // Returns: false 577 * util.isBuffer([]); 578 * // Returns: false 579 * util.isBuffer(Buffer.from('hello world')); 580 * // Returns: true 581 * ``` 582 * @since v0.11.5 583 * @deprecated Since v4.0.0 - Use `isBuffer` instead. 584 */ 585 export function isBuffer(object: unknown): object is Buffer; 586 /** 587 * Returns `true` if the given `object` is a `Function`. Otherwise, returns`false`. 588 * 589 * ```js 590 * import util from 'node:util'; 591 * 592 * function Foo() {} 593 * const Bar = () => {}; 594 * 595 * util.isFunction({}); 596 * // Returns: false 597 * util.isFunction(Foo); 598 * // Returns: true 599 * util.isFunction(Bar); 600 * // Returns: true 601 * ``` 602 * @since v0.11.5 603 * @deprecated Since v4.0.0 - Use `typeof value === 'function'` instead. 604 */ 605 export function isFunction(object: unknown): boolean; 606 /** 607 * Returns `true` if the given `object` is strictly `null`. Otherwise, returns`false`. 608 * 609 * ```js 610 * import util from 'node:util'; 611 * 612 * util.isNull(0); 613 * // Returns: false 614 * util.isNull(undefined); 615 * // Returns: false 616 * util.isNull(null); 617 * // Returns: true 618 * ``` 619 * @since v0.11.5 620 * @deprecated Since v4.0.0 - Use `value === null` instead. 621 */ 622 export function isNull(object: unknown): object is null; 623 /** 624 * Returns `true` if the given `object` is `null` or `undefined`. Otherwise, 625 * returns `false`. 626 * 627 * ```js 628 * import util from 'node:util'; 629 * 630 * util.isNullOrUndefined(0); 631 * // Returns: false 632 * util.isNullOrUndefined(undefined); 633 * // Returns: true 634 * util.isNullOrUndefined(null); 635 * // Returns: true 636 * ``` 637 * @since v0.11.5 638 * @deprecated Since v4.0.0 - Use `value === undefined || value === null` instead. 639 */ 640 export function isNullOrUndefined(object: unknown): object is null | undefined; 641 /** 642 * Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`. 643 * 644 * ```js 645 * import util from 'node:util'; 646 * 647 * util.isNumber(false); 648 * // Returns: false 649 * util.isNumber(Infinity); 650 * // Returns: true 651 * util.isNumber(0); 652 * // Returns: true 653 * util.isNumber(NaN); 654 * // Returns: true 655 * ``` 656 * @since v0.11.5 657 * @deprecated Since v4.0.0 - Use `typeof value === 'number'` instead. 658 */ 659 export function isNumber(object: unknown): object is number; 660 /** 661 * Returns `true` if the given `object` is strictly an `Object`**and** not a`Function` (even though functions are objects in JavaScript). 662 * Otherwise, returns `false`. 663 * 664 * ```js 665 * import util from 'node:util'; 666 * 667 * util.isObject(5); 668 * // Returns: false 669 * util.isObject(null); 670 * // Returns: false 671 * util.isObject({}); 672 * // Returns: true 673 * util.isObject(() => {}); 674 * // Returns: false 675 * ``` 676 * @since v0.11.5 677 * @deprecated Since v4.0.0 - Deprecated: Use `value !== null && typeof value === 'object'` instead. 678 */ 679 export function isObject(object: unknown): boolean; 680 /** 681 * Returns `true` if the given `object` is a primitive type. Otherwise, returns`false`. 682 * 683 * ```js 684 * import util from 'node:util'; 685 * 686 * util.isPrimitive(5); 687 * // Returns: true 688 * util.isPrimitive('foo'); 689 * // Returns: true 690 * util.isPrimitive(false); 691 * // Returns: true 692 * util.isPrimitive(null); 693 * // Returns: true 694 * util.isPrimitive(undefined); 695 * // Returns: true 696 * util.isPrimitive({}); 697 * // Returns: false 698 * util.isPrimitive(() => {}); 699 * // Returns: false 700 * util.isPrimitive(/^$/); 701 * // Returns: false 702 * util.isPrimitive(new Date()); 703 * // Returns: false 704 * ``` 705 * @since v0.11.5 706 * @deprecated Since v4.0.0 - Use `(typeof value !== 'object' && typeof value !== 'function') || value === null` instead. 707 */ 708 export function isPrimitive(object: unknown): boolean; 709 /** 710 * Returns `true` if the given `object` is a `string`. Otherwise, returns `false`. 711 * 712 * ```js 713 * import util from 'node:util'; 714 * 715 * util.isString(''); 716 * // Returns: true 717 * util.isString('foo'); 718 * // Returns: true 719 * util.isString(String('foo')); 720 * // Returns: true 721 * util.isString(5); 722 * // Returns: false 723 * ``` 724 * @since v0.11.5 725 * @deprecated Since v4.0.0 - Use `typeof value === 'string'` instead. 726 */ 727 export function isString(object: unknown): object is string; 728 /** 729 * Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`. 730 * 731 * ```js 732 * import util from 'node:util'; 733 * 734 * util.isSymbol(5); 735 * // Returns: false 736 * util.isSymbol('foo'); 737 * // Returns: false 738 * util.isSymbol(Symbol('foo')); 739 * // Returns: true 740 * ``` 741 * @since v0.11.5 742 * @deprecated Since v4.0.0 - Use `typeof value === 'symbol'` instead. 743 */ 744 export function isSymbol(object: unknown): object is symbol; 745 /** 746 * Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`. 747 * 748 * ```js 749 * import util from 'node:util'; 750 * 751 * const foo = undefined; 752 * util.isUndefined(5); 753 * // Returns: false 754 * util.isUndefined(foo); 755 * // Returns: true 756 * util.isUndefined(null); 757 * // Returns: false 758 * ``` 759 * @since v0.11.5 760 * @deprecated Since v4.0.0 - Use `value === undefined` instead. 761 */ 762 export function isUndefined(object: unknown): object is undefined; 763 /** 764 * The `util.deprecate()` method wraps `fn` (which may be a function or class) in 765 * such a way that it is marked as deprecated. 766 * 767 * ```js 768 * import util from 'node:util'; 769 * 770 * exports.obsoleteFunction = util.deprecate(() => { 771 * // Do something here. 772 * }, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.'); 773 * ``` 774 * 775 * When called, `util.deprecate()` will return a function that will emit a`DeprecationWarning` using the `'warning'` event. The warning will 776 * be emitted and printed to `stderr` the first time the returned function is 777 * called. After the warning is emitted, the wrapped function is called without 778 * emitting a warning. 779 * 780 * If the same optional `code` is supplied in multiple calls to `util.deprecate()`, 781 * the warning will be emitted only once for that `code`. 782 * 783 * ```js 784 * import util from 'node:util'; 785 * 786 * const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001'); 787 * const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001'); 788 * fn1(); // Emits a deprecation warning with code DEP0001 789 * fn2(); // Does not emit a deprecation warning because it has the same code 790 * ``` 791 * 792 * If either the `--no-deprecation` or `--no-warnings` command-line flags are 793 * used, or if the `process.noDeprecation` property is set to `true`_prior_ to 794 * the first deprecation warning, the `util.deprecate()` method does nothing. 795 * 796 * If the `--trace-deprecation` or `--trace-warnings` command-line flags are set, 797 * or the `process.traceDeprecation` property is set to `true`, a warning and a 798 * stack trace are printed to `stderr` the first time the deprecated function is 799 * called. 800 * 801 * If the `--throw-deprecation` command-line flag is set, or the`process.throwDeprecation` property is set to `true`, then an exception will be 802 * thrown when the deprecated function is called. 803 * 804 * The `--throw-deprecation` command-line flag and `process.throwDeprecation` property take precedence over `--trace-deprecation` and `process.traceDeprecation`. 805 * @since v0.8.0 806 * @param fn The function that is being deprecated. 807 * @param msg A warning message to display when the deprecated function is invoked. 808 * @param code A deprecation code. See the `list of deprecated APIs` for a list of codes. 809 * @return The deprecated function wrapped to emit a warning. 810 */ 811 export function deprecate<T extends Function>(fn: T, msg: string, code?: string): T; 812 /** 813 * Returns `true` if there is deep strict equality between `val1` and `val2`. 814 * Otherwise, returns `false`. 815 * 816 * See `assert.deepStrictEqual()` for more information about deep strict 817 * equality. 818 * @since v9.0.0 819 */ 820 export function isDeepStrictEqual(val1: unknown, val2: unknown): boolean; 821 /** 822 * Returns `str` with any ANSI escape codes removed. 823 * 824 * ```js 825 * console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m')); 826 * // Prints "value" 827 * ``` 828 * @since v16.11.0 829 */ 830 export function stripVTControlCharacters(str: string): string; 831 /** 832 * Takes an `async` function (or a function that returns a `Promise`) and returns a 833 * function following the error-first callback style, i.e. taking 834 * an `(err, value) => ...` callback as the last argument. In the callback, the 835 * first argument will be the rejection reason (or `null` if the `Promise`resolved), and the second argument will be the resolved value. 836 * 837 * ```js 838 * import util from 'node:util'; 839 * 840 * async function fn() { 841 * return 'hello world'; 842 * } 843 * const callbackFunction = util.callbackify(fn); 844 * 845 * callbackFunction((err, ret) => { 846 * if (err) throw err; 847 * console.log(ret); 848 * }); 849 * ``` 850 * 851 * Will print: 852 * 853 * ```text 854 * hello world 855 * ``` 856 * 857 * The callback is executed asynchronously, and will have a limited stack trace. 858 * If the callback throws, the process will emit an `'uncaughtException'` event, and if not handled will exit. 859 * 860 * Since `null` has a special meaning as the first argument to a callback, if a 861 * wrapped function rejects a `Promise` with a falsy value as a reason, the value 862 * is wrapped in an `Error` with the original value stored in a field named`reason`. 863 * 864 * ```js 865 * function fn() { 866 * return Promise.reject(null); 867 * } 868 * const callbackFunction = util.callbackify(fn); 869 * 870 * callbackFunction((err, ret) => { 871 * // When the Promise was rejected with `null` it is wrapped with an Error and 872 * // the original value is stored in `reason`. 873 * err && err.hasOwnProperty('reason') && err.reason === null; // true 874 * }); 875 * ``` 876 * @since v8.2.0 877 * @param original An `async` function 878 * @return a callback style function 879 */ 880 export function callbackify(fn: () => Promise<void>): (callback: (err: NodeJS.ErrnoException) => void) => void; 881 export function callbackify<TResult>( 882 fn: () => Promise<TResult>, 883 ): (callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; 884 export function callbackify<T1>( 885 fn: (arg1: T1) => Promise<void>, 886 ): (arg1: T1, callback: (err: NodeJS.ErrnoException) => void) => void; 887 export function callbackify<T1, TResult>( 888 fn: (arg1: T1) => Promise<TResult>, 889 ): (arg1: T1, callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; 890 export function callbackify<T1, T2>( 891 fn: (arg1: T1, arg2: T2) => Promise<void>, 892 ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException) => void) => void; 893 export function callbackify<T1, T2, TResult>( 894 fn: (arg1: T1, arg2: T2) => Promise<TResult>, 895 ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; 896 export function callbackify<T1, T2, T3>( 897 fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<void>, 898 ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException) => void) => void; 899 export function callbackify<T1, T2, T3, TResult>( 900 fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<TResult>, 901 ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; 902 export function callbackify<T1, T2, T3, T4>( 903 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>, 904 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException) => void) => void; 905 export function callbackify<T1, T2, T3, T4, TResult>( 906 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<TResult>, 907 ): ( 908 arg1: T1, 909 arg2: T2, 910 arg3: T3, 911 arg4: T4, 912 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, 913 ) => void; 914 export function callbackify<T1, T2, T3, T4, T5>( 915 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>, 916 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException) => void) => void; 917 export function callbackify<T1, T2, T3, T4, T5, TResult>( 918 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<TResult>, 919 ): ( 920 arg1: T1, 921 arg2: T2, 922 arg3: T3, 923 arg4: T4, 924 arg5: T5, 925 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, 926 ) => void; 927 export function callbackify<T1, T2, T3, T4, T5, T6>( 928 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<void>, 929 ): ( 930 arg1: T1, 931 arg2: T2, 932 arg3: T3, 933 arg4: T4, 934 arg5: T5, 935 arg6: T6, 936 callback: (err: NodeJS.ErrnoException) => void, 937 ) => void; 938 export function callbackify<T1, T2, T3, T4, T5, T6, TResult>( 939 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<TResult>, 940 ): ( 941 arg1: T1, 942 arg2: T2, 943 arg3: T3, 944 arg4: T4, 945 arg5: T5, 946 arg6: T6, 947 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, 948 ) => void; 949 export interface CustomPromisifyLegacy<TCustom extends Function> extends Function { 950 __promisify__: TCustom; 951 } 952 export interface CustomPromisifySymbol<TCustom extends Function> extends Function { 953 [promisify.custom]: TCustom; 954 } 955 export type CustomPromisify<TCustom extends Function> = 956 | CustomPromisifySymbol<TCustom> 957 | CustomPromisifyLegacy<TCustom>; 958 /** 959 * Takes a function following the common error-first callback style, i.e. taking 960 * an `(err, value) => ...` callback as the last argument, and returns a version 961 * that returns promises. 962 * 963 * ```js 964 * import util from 'node:util'; 965 * import fs from 'node:fs'; 966 * 967 * const stat = util.promisify(fs.stat); 968 * stat('.').then((stats) => { 969 * // Do something with `stats` 970 * }).catch((error) => { 971 * // Handle the error. 972 * }); 973 * ``` 974 * 975 * Or, equivalently using `async function`s: 976 * 977 * ```js 978 * import util from 'node:util'; 979 * import fs from 'node:fs'; 980 * 981 * const stat = util.promisify(fs.stat); 982 * 983 * async function callStat() { 984 * const stats = await stat('.'); 985 * console.log(`This directory is owned by ${stats.uid}`); 986 * } 987 * ``` 988 * 989 * If there is an `original[util.promisify.custom]` property present, `promisify`will return its value, see `Custom promisified functions`. 990 * 991 * `promisify()` assumes that `original` is a function taking a callback as its 992 * final argument in all cases. If `original` is not a function, `promisify()`will throw an error. If `original` is a function but its last argument is not 993 * an error-first callback, it will still be passed an error-first 994 * callback as its last argument. 995 * 996 * Using `promisify()` on class methods or other methods that use `this` may not 997 * work as expected unless handled specially: 998 * 999 * ```js 1000 * import util from 'node:util'; 1001 * 1002 * class Foo { 1003 * constructor() { 1004 * this.a = 42; 1005 * } 1006 * 1007 * bar(callback) { 1008 * callback(null, this.a); 1009 * } 1010 * } 1011 * 1012 * const foo = new Foo(); 1013 * 1014 * const naiveBar = util.promisify(foo.bar); 1015 * // TypeError: Cannot read property 'a' of undefined 1016 * // naiveBar().then(a => console.log(a)); 1017 * 1018 * naiveBar.call(foo).then((a) => console.log(a)); // '42' 1019 * 1020 * const bindBar = naiveBar.bind(foo); 1021 * bindBar().then((a) => console.log(a)); // '42' 1022 * ``` 1023 * @since v8.0.0 1024 */ 1025 export function promisify<TCustom extends Function>(fn: CustomPromisify<TCustom>): TCustom; 1026 export function promisify<TResult>( 1027 fn: (callback: (err: any, result: TResult) => void) => void, 1028 ): () => Promise<TResult>; 1029 export function promisify(fn: (callback: (err?: any) => void) => void): () => Promise<void>; 1030 export function promisify<T1, TResult>( 1031 fn: (arg1: T1, callback: (err: any, result: TResult) => void) => void, 1032 ): (arg1: T1) => Promise<TResult>; 1033 export function promisify<T1>(fn: (arg1: T1, callback: (err?: any) => void) => void): (arg1: T1) => Promise<void>; 1034 export function promisify<T1, T2, TResult>( 1035 fn: (arg1: T1, arg2: T2, callback: (err: any, result: TResult) => void) => void, 1036 ): (arg1: T1, arg2: T2) => Promise<TResult>; 1037 export function promisify<T1, T2>( 1038 fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void, 1039 ): (arg1: T1, arg2: T2) => Promise<void>; 1040 export function promisify<T1, T2, T3, TResult>( 1041 fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err: any, result: TResult) => void) => void, 1042 ): (arg1: T1, arg2: T2, arg3: T3) => Promise<TResult>; 1043 export function promisify<T1, T2, T3>( 1044 fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void, 1045 ): (arg1: T1, arg2: T2, arg3: T3) => Promise<void>; 1046 export function promisify<T1, T2, T3, T4, TResult>( 1047 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: any, result: TResult) => void) => void, 1048 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<TResult>; 1049 export function promisify<T1, T2, T3, T4>( 1050 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err?: any) => void) => void, 1051 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>; 1052 export function promisify<T1, T2, T3, T4, T5, TResult>( 1053 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: any, result: TResult) => void) => void, 1054 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<TResult>; 1055 export function promisify<T1, T2, T3, T4, T5>( 1056 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err?: any) => void) => void, 1057 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>; 1058 export function promisify(fn: Function): Function; 1059 export namespace promisify { 1060 /** 1061 * That can be used to declare custom promisified variants of functions. 1062 */ 1063 const custom: unique symbol; 1064 } 1065 /** 1066 * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextDecoder` API. 1067 * 1068 * ```js 1069 * const decoder = new TextDecoder('shift_jis'); 1070 * let string = ''; 1071 * let buffer; 1072 * while (buffer = getNextChunkSomehow()) { 1073 * string += decoder.decode(buffer, { stream: true }); 1074 * } 1075 * string += decoder.decode(); // end-of-stream 1076 * ``` 1077 * @since v8.3.0 1078 */ 1079 export class TextDecoder { 1080 /** 1081 * The encoding supported by the `TextDecoder` instance. 1082 */ 1083 readonly encoding: string; 1084 /** 1085 * The value will be `true` if decoding errors result in a `TypeError` being 1086 * thrown. 1087 */ 1088 readonly fatal: boolean; 1089 /** 1090 * The value will be `true` if the decoding result will include the byte order 1091 * mark. 1092 */ 1093 readonly ignoreBOM: boolean; 1094 constructor( 1095 encoding?: string, 1096 options?: { 1097 fatal?: boolean | undefined; 1098 ignoreBOM?: boolean | undefined; 1099 }, 1100 ); 1101 /** 1102 * Decodes the `input` and returns a string. If `options.stream` is `true`, any 1103 * incomplete byte sequences occurring at the end of the `input` are buffered 1104 * internally and emitted after the next call to `textDecoder.decode()`. 1105 * 1106 * If `textDecoder.fatal` is `true`, decoding errors that occur will result in a`TypeError` being thrown. 1107 * @param input An `ArrayBuffer`, `DataView` or `TypedArray` instance containing the encoded data. 1108 */ 1109 decode( 1110 input?: NodeJS.ArrayBufferView | ArrayBuffer | null, 1111 options?: { 1112 stream?: boolean | undefined; 1113 }, 1114 ): string; 1115 } 1116 export interface EncodeIntoResult { 1117 /** 1118 * The read Unicode code units of input. 1119 */ 1120 read: number; 1121 /** 1122 * The written UTF-8 bytes of output. 1123 */ 1124 written: number; 1125 } 1126 export { types }; 1127 /** 1128 * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextEncoder` API. All 1129 * instances of `TextEncoder` only support UTF-8 encoding. 1130 * 1131 * ```js 1132 * const encoder = new TextEncoder(); 1133 * const uint8array = encoder.encode('this is some data'); 1134 * ``` 1135 * 1136 * The `TextEncoder` class is also available on the global object. 1137 * @since v8.3.0 1138 */ 1139 export class TextEncoder { 1140 /** 1141 * The encoding supported by the `TextEncoder` instance. Always set to `'utf-8'`. 1142 */ 1143 readonly encoding: string; 1144 /** 1145 * UTF-8 encodes the `input` string and returns a `Uint8Array` containing the 1146 * encoded bytes. 1147 * @param [input='an empty string'] The text to encode. 1148 */ 1149 encode(input?: string): Uint8Array; 1150 /** 1151 * UTF-8 encodes the `src` string to the `dest` Uint8Array and returns an object 1152 * containing the read Unicode code units and written UTF-8 bytes. 1153 * 1154 * ```js 1155 * const encoder = new TextEncoder(); 1156 * const src = 'this is some data'; 1157 * const dest = new Uint8Array(10); 1158 * const { read, written } = encoder.encodeInto(src, dest); 1159 * ``` 1160 * @param src The text to encode. 1161 * @param dest The array to hold the encode result. 1162 */ 1163 encodeInto(src: string, dest: Uint8Array): EncodeIntoResult; 1164 } 1165 1166 import { TextDecoder as _TextDecoder, TextEncoder as _TextEncoder } from "util"; 1167 global { 1168 /** 1169 * `TextDecoder` class is a global reference for `import { TextDecoder } from 'node:util'` 1170 * https://nodejs.org/api/globals.html#textdecoder 1171 * @since v11.0.0 1172 */ 1173 var TextDecoder: typeof globalThis extends { 1174 onmessage: any; 1175 TextDecoder: infer TextDecoder; 1176 } ? TextDecoder 1177 : typeof _TextDecoder; 1178 1179 /** 1180 * `TextEncoder` class is a global reference for `import { TextEncoder } from 'node:util'` 1181 * https://nodejs.org/api/globals.html#textencoder 1182 * @since v11.0.0 1183 */ 1184 var TextEncoder: typeof globalThis extends { 1185 onmessage: any; 1186 TextEncoder: infer TextEncoder; 1187 } ? TextEncoder 1188 : typeof _TextEncoder; 1189 } 1190 } 1191 declare module "util/types" { 1192 import { KeyObject, webcrypto } from "node:crypto"; 1193 /** 1194 * Returns `true` if the value is a built-in [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or 1195 * [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) instance. 1196 * 1197 * See also `util.types.isArrayBuffer()` and `util.types.isSharedArrayBuffer()`. 1198 * 1199 * ```js 1200 * util.types.isAnyArrayBuffer(new ArrayBuffer()); // Returns true 1201 * util.types.isAnyArrayBuffer(new SharedArrayBuffer()); // Returns true 1202 * ``` 1203 * @since v10.0.0 1204 */ 1205 function isAnyArrayBuffer(object: unknown): object is ArrayBufferLike; 1206 /** 1207 * Returns `true` if the value is an `arguments` object. 1208 * 1209 * ```js 1210 * function foo() { 1211 * util.types.isArgumentsObject(arguments); // Returns true 1212 * } 1213 * ``` 1214 * @since v10.0.0 1215 */ 1216 function isArgumentsObject(object: unknown): object is IArguments; 1217 /** 1218 * Returns `true` if the value is a built-in [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) instance. 1219 * This does _not_ include [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) instances. Usually, it is 1220 * desirable to test for both; See `util.types.isAnyArrayBuffer()` for that. 1221 * 1222 * ```js 1223 * util.types.isArrayBuffer(new ArrayBuffer()); // Returns true 1224 * util.types.isArrayBuffer(new SharedArrayBuffer()); // Returns false 1225 * ``` 1226 * @since v10.0.0 1227 */ 1228 function isArrayBuffer(object: unknown): object is ArrayBuffer; 1229 /** 1230 * Returns `true` if the value is an instance of one of the [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) views, such as typed 1231 * array objects or [`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView). Equivalent to 1232 * [`ArrayBuffer.isView()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView). 1233 * 1234 * ```js 1235 * util.types.isArrayBufferView(new Int8Array()); // true 1236 * util.types.isArrayBufferView(Buffer.from('hello world')); // true 1237 * util.types.isArrayBufferView(new DataView(new ArrayBuffer(16))); // true 1238 * util.types.isArrayBufferView(new ArrayBuffer()); // false 1239 * ``` 1240 * @since v10.0.0 1241 */ 1242 function isArrayBufferView(object: unknown): object is NodeJS.ArrayBufferView; 1243 /** 1244 * Returns `true` if the value is an [async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function). 1245 * This only reports back what the JavaScript engine is seeing; 1246 * in particular, the return value may not match the original source code if 1247 * a transpilation tool was used. 1248 * 1249 * ```js 1250 * util.types.isAsyncFunction(function foo() {}); // Returns false 1251 * util.types.isAsyncFunction(async function foo() {}); // Returns true 1252 * ``` 1253 * @since v10.0.0 1254 */ 1255 function isAsyncFunction(object: unknown): boolean; 1256 /** 1257 * Returns `true` if the value is a `BigInt64Array` instance. 1258 * 1259 * ```js 1260 * util.types.isBigInt64Array(new BigInt64Array()); // Returns true 1261 * util.types.isBigInt64Array(new BigUint64Array()); // Returns false 1262 * ``` 1263 * @since v10.0.0 1264 */ 1265 function isBigInt64Array(value: unknown): value is BigInt64Array; 1266 /** 1267 * Returns `true` if the value is a `BigUint64Array` instance. 1268 * 1269 * ```js 1270 * util.types.isBigUint64Array(new BigInt64Array()); // Returns false 1271 * util.types.isBigUint64Array(new BigUint64Array()); // Returns true 1272 * ``` 1273 * @since v10.0.0 1274 */ 1275 function isBigUint64Array(value: unknown): value is BigUint64Array; 1276 /** 1277 * Returns `true` if the value is a boolean object, e.g. created 1278 * by `new Boolean()`. 1279 * 1280 * ```js 1281 * util.types.isBooleanObject(false); // Returns false 1282 * util.types.isBooleanObject(true); // Returns false 1283 * util.types.isBooleanObject(new Boolean(false)); // Returns true 1284 * util.types.isBooleanObject(new Boolean(true)); // Returns true 1285 * util.types.isBooleanObject(Boolean(false)); // Returns false 1286 * util.types.isBooleanObject(Boolean(true)); // Returns false 1287 * ``` 1288 * @since v10.0.0 1289 */ 1290 function isBooleanObject(object: unknown): object is Boolean; 1291 /** 1292 * Returns `true` if the value is any boxed primitive object, e.g. created 1293 * by `new Boolean()`, `new String()` or `Object(Symbol())`. 1294 * 1295 * For example: 1296 * 1297 * ```js 1298 * util.types.isBoxedPrimitive(false); // Returns false 1299 * util.types.isBoxedPrimitive(new Boolean(false)); // Returns true 1300 * util.types.isBoxedPrimitive(Symbol('foo')); // Returns false 1301 * util.types.isBoxedPrimitive(Object(Symbol('foo'))); // Returns true 1302 * util.types.isBoxedPrimitive(Object(BigInt(5))); // Returns true 1303 * ``` 1304 * @since v10.11.0 1305 */ 1306 function isBoxedPrimitive(object: unknown): object is String | Number | BigInt | Boolean | Symbol; 1307 /** 1308 * Returns `true` if the value is a built-in [`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) instance. 1309 * 1310 * ```js 1311 * const ab = new ArrayBuffer(20); 1312 * util.types.isDataView(new DataView(ab)); // Returns true 1313 * util.types.isDataView(new Float64Array()); // Returns false 1314 * ``` 1315 * 1316 * See also [`ArrayBuffer.isView()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView). 1317 * @since v10.0.0 1318 */ 1319 function isDataView(object: unknown): object is DataView; 1320 /** 1321 * Returns `true` if the value is a built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) instance. 1322 * 1323 * ```js 1324 * util.types.isDate(new Date()); // Returns true 1325 * ``` 1326 * @since v10.0.0 1327 */ 1328 function isDate(object: unknown): object is Date; 1329 /** 1330 * Returns `true` if the value is a native `External` value. 1331 * 1332 * A native `External` value is a special type of object that contains a 1333 * raw C++ pointer (`void*`) for access from native code, and has no other 1334 * properties. Such objects are created either by Node.js internals or native 1335 * addons. In JavaScript, they are [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) objects with a`null` prototype. 1336 * 1337 * ```c 1338 * #include <js_native_api.h> 1339 * #include <stdlib.h> 1340 * napi_value result; 1341 * static napi_value MyNapi(napi_env env, napi_callback_info info) { 1342 * int* raw = (int*) malloc(1024); 1343 * napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result); 1344 * if (status != napi_ok) { 1345 * napi_throw_error(env, NULL, "napi_create_external failed"); 1346 * return NULL; 1347 * } 1348 * return result; 1349 * } 1350 * ... 1351 * DECLARE_NAPI_PROPERTY("myNapi", MyNapi) 1352 * ... 1353 * ``` 1354 * 1355 * ```js 1356 * const native = require('napi_addon.node'); 1357 * const data = native.myNapi(); 1358 * util.types.isExternal(data); // returns true 1359 * util.types.isExternal(0); // returns false 1360 * util.types.isExternal(new String('foo')); // returns false 1361 * ``` 1362 * 1363 * For further information on `napi_create_external`, refer to `napi_create_external()`. 1364 * @since v10.0.0 1365 */ 1366 function isExternal(object: unknown): boolean; 1367 /** 1368 * Returns `true` if the value is a built-in [`Float32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array) instance. 1369 * 1370 * ```js 1371 * util.types.isFloat32Array(new ArrayBuffer()); // Returns false 1372 * util.types.isFloat32Array(new Float32Array()); // Returns true 1373 * util.types.isFloat32Array(new Float64Array()); // Returns false 1374 * ``` 1375 * @since v10.0.0 1376 */ 1377 function isFloat32Array(object: unknown): object is Float32Array; 1378 /** 1379 * Returns `true` if the value is a built-in [`Float64Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array) instance. 1380 * 1381 * ```js 1382 * util.types.isFloat64Array(new ArrayBuffer()); // Returns false 1383 * util.types.isFloat64Array(new Uint8Array()); // Returns false 1384 * util.types.isFloat64Array(new Float64Array()); // Returns true 1385 * ``` 1386 * @since v10.0.0 1387 */ 1388 function isFloat64Array(object: unknown): object is Float64Array; 1389 /** 1390 * Returns `true` if the value is a generator function. 1391 * This only reports back what the JavaScript engine is seeing; 1392 * in particular, the return value may not match the original source code if 1393 * a transpilation tool was used. 1394 * 1395 * ```js 1396 * util.types.isGeneratorFunction(function foo() {}); // Returns false 1397 * util.types.isGeneratorFunction(function* foo() {}); // Returns true 1398 * ``` 1399 * @since v10.0.0 1400 */ 1401 function isGeneratorFunction(object: unknown): object is GeneratorFunction; 1402 /** 1403 * Returns `true` if the value is a generator object as returned from a 1404 * built-in generator function. 1405 * This only reports back what the JavaScript engine is seeing; 1406 * in particular, the return value may not match the original source code if 1407 * a transpilation tool was used. 1408 * 1409 * ```js 1410 * function* foo() {} 1411 * const generator = foo(); 1412 * util.types.isGeneratorObject(generator); // Returns true 1413 * ``` 1414 * @since v10.0.0 1415 */ 1416 function isGeneratorObject(object: unknown): object is Generator; 1417 /** 1418 * Returns `true` if the value is a built-in [`Int8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int8Array) instance. 1419 * 1420 * ```js 1421 * util.types.isInt8Array(new ArrayBuffer()); // Returns false 1422 * util.types.isInt8Array(new Int8Array()); // Returns true 1423 * util.types.isInt8Array(new Float64Array()); // Returns false 1424 * ``` 1425 * @since v10.0.0 1426 */ 1427 function isInt8Array(object: unknown): object is Int8Array; 1428 /** 1429 * Returns `true` if the value is a built-in [`Int16Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int16Array) instance. 1430 * 1431 * ```js 1432 * util.types.isInt16Array(new ArrayBuffer()); // Returns false 1433 * util.types.isInt16Array(new Int16Array()); // Returns true 1434 * util.types.isInt16Array(new Float64Array()); // Returns false 1435 * ``` 1436 * @since v10.0.0 1437 */ 1438 function isInt16Array(object: unknown): object is Int16Array; 1439 /** 1440 * Returns `true` if the value is a built-in [`Int32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int32Array) instance. 1441 * 1442 * ```js 1443 * util.types.isInt32Array(new ArrayBuffer()); // Returns false 1444 * util.types.isInt32Array(new Int32Array()); // Returns true 1445 * util.types.isInt32Array(new Float64Array()); // Returns false 1446 * ``` 1447 * @since v10.0.0 1448 */ 1449 function isInt32Array(object: unknown): object is Int32Array; 1450 /** 1451 * Returns `true` if the value is a built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) instance. 1452 * 1453 * ```js 1454 * util.types.isMap(new Map()); // Returns true 1455 * ``` 1456 * @since v10.0.0 1457 */ 1458 function isMap<T>( 1459 object: T | {}, 1460 ): object is T extends ReadonlyMap<any, any> ? (unknown extends T ? never : ReadonlyMap<any, any>) 1461 : Map<unknown, unknown>; 1462 /** 1463 * Returns `true` if the value is an iterator returned for a built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) instance. 1464 * 1465 * ```js 1466 * const map = new Map(); 1467 * util.types.isMapIterator(map.keys()); // Returns true 1468 * util.types.isMapIterator(map.values()); // Returns true 1469 * util.types.isMapIterator(map.entries()); // Returns true 1470 * util.types.isMapIterator(map[Symbol.iterator]()); // Returns true 1471 * ``` 1472 * @since v10.0.0 1473 */ 1474 function isMapIterator(object: unknown): boolean; 1475 /** 1476 * Returns `true` if the value is an instance of a [Module Namespace Object](https://tc39.github.io/ecma262/#sec-module-namespace-exotic-objects). 1477 * 1478 * ```js 1479 * import * as ns from './a.js'; 1480 * 1481 * util.types.isModuleNamespaceObject(ns); // Returns true 1482 * ``` 1483 * @since v10.0.0 1484 */ 1485 function isModuleNamespaceObject(value: unknown): boolean; 1486 /** 1487 * Returns `true` if the value is an instance of a built-in `Error` type. 1488 * 1489 * ```js 1490 * util.types.isNativeError(new Error()); // Returns true 1491 * util.types.isNativeError(new TypeError()); // Returns true 1492 * util.types.isNativeError(new RangeError()); // Returns true 1493 * ``` 1494 * @since v10.0.0 1495 */ 1496 function isNativeError(object: unknown): object is Error; 1497 /** 1498 * Returns `true` if the value is a number object, e.g. created 1499 * by `new Number()`. 1500 * 1501 * ```js 1502 * util.types.isNumberObject(0); // Returns false 1503 * util.types.isNumberObject(new Number(0)); // Returns true 1504 * ``` 1505 * @since v10.0.0 1506 */ 1507 function isNumberObject(object: unknown): object is Number; 1508 /** 1509 * Returns `true` if the value is a built-in [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). 1510 * 1511 * ```js 1512 * util.types.isPromise(Promise.resolve(42)); // Returns true 1513 * ``` 1514 * @since v10.0.0 1515 */ 1516 function isPromise(object: unknown): object is Promise<unknown>; 1517 /** 1518 * Returns `true` if the value is a [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) instance. 1519 * 1520 * ```js 1521 * const target = {}; 1522 * const proxy = new Proxy(target, {}); 1523 * util.types.isProxy(target); // Returns false 1524 * util.types.isProxy(proxy); // Returns true 1525 * ``` 1526 * @since v10.0.0 1527 */ 1528 function isProxy(object: unknown): boolean; 1529 /** 1530 * Returns `true` if the value is a regular expression object. 1531 * 1532 * ```js 1533 * util.types.isRegExp(/abc/); // Returns true 1534 * util.types.isRegExp(new RegExp('abc')); // Returns true 1535 * ``` 1536 * @since v10.0.0 1537 */ 1538 function isRegExp(object: unknown): object is RegExp; 1539 /** 1540 * Returns `true` if the value is a built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) instance. 1541 * 1542 * ```js 1543 * util.types.isSet(new Set()); // Returns true 1544 * ``` 1545 * @since v10.0.0 1546 */ 1547 function isSet<T>( 1548 object: T | {}, 1549 ): object is T extends ReadonlySet<any> ? (unknown extends T ? never : ReadonlySet<any>) : Set<unknown>; 1550 /** 1551 * Returns `true` if the value is an iterator returned for a built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) instance. 1552 * 1553 * ```js 1554 * const set = new Set(); 1555 * util.types.isSetIterator(set.keys()); // Returns true 1556 * util.types.isSetIterator(set.values()); // Returns true 1557 * util.types.isSetIterator(set.entries()); // Returns true 1558 * util.types.isSetIterator(set[Symbol.iterator]()); // Returns true 1559 * ``` 1560 * @since v10.0.0 1561 */ 1562 function isSetIterator(object: unknown): boolean; 1563 /** 1564 * Returns `true` if the value is a built-in [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) instance. 1565 * This does _not_ include [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) instances. Usually, it is 1566 * desirable to test for both; See `util.types.isAnyArrayBuffer()` for that. 1567 * 1568 * ```js 1569 * util.types.isSharedArrayBuffer(new ArrayBuffer()); // Returns false 1570 * util.types.isSharedArrayBuffer(new SharedArrayBuffer()); // Returns true 1571 * ``` 1572 * @since v10.0.0 1573 */ 1574 function isSharedArrayBuffer(object: unknown): object is SharedArrayBuffer; 1575 /** 1576 * Returns `true` if the value is a string object, e.g. created 1577 * by `new String()`. 1578 * 1579 * ```js 1580 * util.types.isStringObject('foo'); // Returns false 1581 * util.types.isStringObject(new String('foo')); // Returns true 1582 * ``` 1583 * @since v10.0.0 1584 */ 1585 function isStringObject(object: unknown): object is String; 1586 /** 1587 * Returns `true` if the value is a symbol object, created 1588 * by calling `Object()` on a `Symbol` primitive. 1589 * 1590 * ```js 1591 * const symbol = Symbol('foo'); 1592 * util.types.isSymbolObject(symbol); // Returns false 1593 * util.types.isSymbolObject(Object(symbol)); // Returns true 1594 * ``` 1595 * @since v10.0.0 1596 */ 1597 function isSymbolObject(object: unknown): object is Symbol; 1598 /** 1599 * Returns `true` if the value is a built-in [`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) instance. 1600 * 1601 * ```js 1602 * util.types.isTypedArray(new ArrayBuffer()); // Returns false 1603 * util.types.isTypedArray(new Uint8Array()); // Returns true 1604 * util.types.isTypedArray(new Float64Array()); // Returns true 1605 * ``` 1606 * 1607 * See also [`ArrayBuffer.isView()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView). 1608 * @since v10.0.0 1609 */ 1610 function isTypedArray(object: unknown): object is NodeJS.TypedArray; 1611 /** 1612 * Returns `true` if the value is a built-in [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instance. 1613 * 1614 * ```js 1615 * util.types.isUint8Array(new ArrayBuffer()); // Returns false 1616 * util.types.isUint8Array(new Uint8Array()); // Returns true 1617 * util.types.isUint8Array(new Float64Array()); // Returns false 1618 * ``` 1619 * @since v10.0.0 1620 */ 1621 function isUint8Array(object: unknown): object is Uint8Array; 1622 /** 1623 * Returns `true` if the value is a built-in [`Uint8ClampedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8ClampedArray) instance. 1624 * 1625 * ```js 1626 * util.types.isUint8ClampedArray(new ArrayBuffer()); // Returns false 1627 * util.types.isUint8ClampedArray(new Uint8ClampedArray()); // Returns true 1628 * util.types.isUint8ClampedArray(new Float64Array()); // Returns false 1629 * ``` 1630 * @since v10.0.0 1631 */ 1632 function isUint8ClampedArray(object: unknown): object is Uint8ClampedArray; 1633 /** 1634 * Returns `true` if the value is a built-in [`Uint16Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint16Array) instance. 1635 * 1636 * ```js 1637 * util.types.isUint16Array(new ArrayBuffer()); // Returns false 1638 * util.types.isUint16Array(new Uint16Array()); // Returns true 1639 * util.types.isUint16Array(new Float64Array()); // Returns false 1640 * ``` 1641 * @since v10.0.0 1642 */ 1643 function isUint16Array(object: unknown): object is Uint16Array; 1644 /** 1645 * Returns `true` if the value is a built-in [`Uint32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint32Array) instance. 1646 * 1647 * ```js 1648 * util.types.isUint32Array(new ArrayBuffer()); // Returns false 1649 * util.types.isUint32Array(new Uint32Array()); // Returns true 1650 * util.types.isUint32Array(new Float64Array()); // Returns false 1651 * ``` 1652 * @since v10.0.0 1653 */ 1654 function isUint32Array(object: unknown): object is Uint32Array; 1655 /** 1656 * Returns `true` if the value is a built-in [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) instance. 1657 * 1658 * ```js 1659 * util.types.isWeakMap(new WeakMap()); // Returns true 1660 * ``` 1661 * @since v10.0.0 1662 */ 1663 function isWeakMap(object: unknown): object is WeakMap<object, unknown>; 1664 /** 1665 * Returns `true` if the value is a built-in [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) instance. 1666 * 1667 * ```js 1668 * util.types.isWeakSet(new WeakSet()); // Returns true 1669 * ``` 1670 * @since v10.0.0 1671 */ 1672 function isWeakSet(object: unknown): object is WeakSet<object>; 1673 /** 1674 * Returns `true` if `value` is a `KeyObject`, `false` otherwise. 1675 * @since v16.2.0 1676 */ 1677 function isKeyObject(object: unknown): object is KeyObject; 1678 /** 1679 * Returns `true` if `value` is a `CryptoKey`, `false` otherwise. 1680 * @since v16.2.0 1681 */ 1682 function isCryptoKey(object: unknown): object is webcrypto.CryptoKey; 1683 } 1684 declare module "node:util" { 1685 export * from "util"; 1686 } 1687 declare module "node:util/types" { 1688 export * from "util/types"; 1689 }