AK-21/Graphite-Industrial-Intelligence
0
1/**2 * The `node:util` module supports the needs of Node.js internal APIs. Many of the3 * utilities are useful for application and module developers as well. To access4 * it:5 *6 * ```js7 * import util from 'node:util';8 * ```9 * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/util.js)10 */11declare module "util" {12 import * as types from "node:util/types";13 export interface InspectOptions {14 /**15 * If `true`, object's non-enumerable symbols and properties are included in the formatted result.16 * `WeakMap` and `WeakSet` entries are also included as well as user defined prototype properties (excluding method properties).17 * @default false18 */19 showHidden?: boolean | undefined;20 /**21 * Specifies the number of times to recurse while formatting object.22 * This is useful for inspecting large objects.23 * To recurse up to the maximum call stack size pass `Infinity` or `null`.24 * @default 225 */26 depth?: number | null | undefined;27 /**28 * If `true`, the output is styled with ANSI color codes. Colors are customizable.29 */30 colors?: boolean | undefined;31 /**32 * If `false`, `[util.inspect.custom](depth, opts, inspect)` functions are not invoked.33 * @default true34 */35 customInspect?: boolean | undefined;36 /**37 * If `true`, `Proxy` inspection includes the target and handler objects.38 * @default false39 */40 showProxy?: boolean | undefined;41 /**42 * Specifies the maximum number of `Array`, `TypedArray`, `WeakMap`, and `WeakSet` elements43 * to include when formatting. Set to `null` or `Infinity` to show all elements.44 * Set to `0` or negative to show no elements.45 * @default 10046 */47 maxArrayLength?: number | null | undefined;48 /**49 * Specifies the maximum number of characters to50 * include when formatting. Set to `null` or `Infinity` to show all elements.51 * Set to `0` or negative to show no characters.52 * @default 1000053 */54 maxStringLength?: number | null | undefined;55 /**56 * The length at which input values are split across multiple lines.57 * Set to `Infinity` to format the input as a single line58 * (in combination with `compact` set to `true` or any number >= `1`).59 * @default 8060 */61 breakLength?: number | undefined;62 /**63 * Setting this to `false` causes each object key64 * to be displayed on a new line. It will also add new lines to text that is65 * longer than `breakLength`. If set to a number, the most `n` inner elements66 * are united on a single line as long as all properties fit into67 * `breakLength`. Short array elements are also grouped together. Note that no68 * text will be reduced below 16 characters, no matter the `breakLength` size.69 * For more information, see the example below.70 * @default true71 */72 compact?: boolean | number | undefined;73 /**74 * If set to `true` or a function, all properties of an object, and `Set` and `Map`75 * entries are sorted in the resulting string.76 * If set to `true` the default sort is used.77 * If set to a function, it is used as a compare function.78 */79 sorted?: boolean | ((a: string, b: string) => number) | undefined;80 /**81 * If set to `true`, getters are going to be82 * inspected as well. If set to `'get'` only getters without setter are going83 * to be inspected. If set to `'set'` only getters having a corresponding84 * setter are going to be inspected. This might cause side effects depending on85 * the getter function.86 * @default false87 */88 getters?: "get" | "set" | boolean | undefined;89 /**90 * If set to `true`, an underscore is used to separate every three digits in all bigints and numbers.91 * @default false92 */93 numericSeparator?: boolean | undefined;94 }95 export type Style =96 | "special"97 | "number"98 | "bigint"99 | "boolean"100 | "undefined"101 | "null"102 | "string"103 | "symbol"104 | "date"105 | "regexp"106 | "module";107 export type CustomInspectFunction = (depth: number, options: InspectOptionsStylized) => any; // TODO: , inspect: inspect108 export interface InspectOptionsStylized extends InspectOptions {109 stylize(text: string, styleType: Style): string;110 }111 export interface CallSiteObject {112 /**113 * Returns the name of the function associated with this call site.114 */115 functionName: string;116 /**117 * Returns the name of the resource that contains the script for the118 * function for this call site.119 */120 scriptName: string;121 /**122 * Returns the unique id of the script, as in Chrome DevTools protocol123 * [`Runtime.ScriptId`](https://chromedevtools.github.io/devtools-protocol/1-3/Runtime/#type-ScriptId).124 * @since v22.14.0125 */126 scriptId: string;127 /**128 * Returns the number, 1-based, of the line for the associate function call.129 */130 lineNumber: number;131 /**132 * Returns the 1-based column offset on the line for the associated function call.133 */134 columnNumber: number;135 }136 export type DiffEntry = [operation: -1 | 0 | 1, value: string];137 /**138 * `util.diff()` compares two string or array values and returns an array of difference entries.139 * It uses the Myers diff algorithm to compute minimal differences, which is the same algorithm140 * used internally by assertion error messages.141 *142 * If the values are equal, an empty array is returned.143 *144 * ```js145 * const { diff } = require('node:util');146 *147 * // Comparing strings148 * const actualString = '12345678';149 * const expectedString = '12!!5!7!';150 * console.log(diff(actualString, expectedString));151 * // [152 * // [0, '1'],153 * // [0, '2'],154 * // [1, '3'],155 * // [1, '4'],156 * // [-1, '!'],157 * // [-1, '!'],158 * // [0, '5'],159 * // [1, '6'],160 * // [-1, '!'],161 * // [0, '7'],162 * // [1, '8'],163 * // [-1, '!'],164 * // ]165 * // Comparing arrays166 * const actualArray = ['1', '2', '3'];167 * const expectedArray = ['1', '3', '4'];168 * console.log(diff(actualArray, expectedArray));169 * // [170 * // [0, '1'],171 * // [1, '2'],172 * // [0, '3'],173 * // [-1, '4'],174 * // ]175 * // Equal values return empty array176 * console.log(diff('same', 'same'));177 * // []178 * ```179 * @since v22.15.0180 * @experimental181 * @param actual The first value to compare182 * @param expected The second value to compare183 * @returns An array of difference entries. Each entry is an array with two elements:184 * * Index 0: `number` Operation code: `-1` for delete, `0` for no-op/unchanged, `1` for insert185 * * Index 1: `string` The value associated with the operation186 */187 export function diff(actual: string | readonly string[], expected: string | readonly string[]): DiffEntry[];188 /**189 * The `util.format()` method returns a formatted string using the first argument190 * as a `printf`-like format string which can contain zero or more format191 * specifiers. Each specifier is replaced with the converted value from the192 * corresponding argument. Supported specifiers are:193 *194 * If a specifier does not have a corresponding argument, it is not replaced:195 *196 * ```js197 * util.format('%s:%s', 'foo');198 * // Returns: 'foo:%s'199 * ```200 *201 * Values that are not part of the format string are formatted using `util.inspect()` if their type is not `string`.202 *203 * If there are more arguments passed to the `util.format()` method than the204 * number of specifiers, the extra arguments are concatenated to the returned205 * string, separated by spaces:206 *207 * ```js208 * util.format('%s:%s', 'foo', 'bar', 'baz');209 * // Returns: 'foo:bar baz'210 * ```211 *212 * 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:213 *214 * ```js215 * util.format(1, 2, 3);216 * // Returns: '1 2 3'217 * ```218 *219 * If only one argument is passed to `util.format()`, it is returned as it is220 * without any formatting:221 *222 * ```js223 * util.format('%% %s');224 * // Returns: '%% %s'225 * ```226 *227 * `util.format()` is a synchronous method that is intended as a debugging tool.228 * Some input values can have a significant performance overhead that can block the229 * event loop. Use this function with care and never in a hot code path.230 * @since v0.5.3231 * @param format A `printf`-like format string.232 */233 export function format(format?: any, ...param: any[]): string;234 /**235 * This function is identical to {@link format}, except in that it takes236 * an `inspectOptions` argument which specifies options that are passed along to {@link inspect}.237 *238 * ```js239 * util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });240 * // Returns 'See object { foo: 42 }', where `42` is colored as a number241 * // when printed to a terminal.242 * ```243 * @since v10.0.0244 */245 export function formatWithOptions(inspectOptions: InspectOptions, format?: any, ...param: any[]): string;246 interface GetCallSitesOptions {247 /**248 * Reconstruct the original location in the stacktrace from the source-map.249 * Enabled by default with the flag `--enable-source-maps`.250 */251 sourceMap?: boolean | undefined;252 }253 /**254 * Returns an array of call site objects containing the stack of255 * the caller function.256 *257 * Unlike accessing an `error.stack`, the result returned from this API is not258 * interfered with `Error.prepareStackTrace`.259 *260 * ```js261 * import { getCallSites } from 'node:util';262 *263 * function exampleFunction() {264 * const callSites = getCallSites();265 *266 * console.log('Call Sites:');267 * callSites.forEach((callSite, index) => {268 * console.log(`CallSite ${index + 1}:`);269 * console.log(`Function Name: ${callSite.functionName}`);270 * console.log(`Script Name: ${callSite.scriptName}`);271 * console.log(`Line Number: ${callSite.lineNumber}`);272 * console.log(`Column Number: ${callSite.columnNumber}`);273 * });274 * // CallSite 1:275 * // Function Name: exampleFunction276 * // Script Name: /home/example.js277 * // Line Number: 5278 * // Column Number: 26279 *280 * // CallSite 2:281 * // Function Name: anotherFunction282 * // Script Name: /home/example.js283 * // Line Number: 22284 * // Column Number: 3285 *286 * // ...287 * }288 *289 * // A function to simulate another stack layer290 * function anotherFunction() {291 * exampleFunction();292 * }293 *294 * anotherFunction();295 * ```296 *297 * It is possible to reconstruct the original locations by setting the option `sourceMap` to `true`.298 * If the source map is not available, the original location will be the same as the current location.299 * When the `--enable-source-maps` flag is enabled, for example when using `--experimental-transform-types`,300 * `sourceMap` will be true by default.301 *302 * ```ts303 * import { getCallSites } from 'node:util';304 *305 * interface Foo {306 * foo: string;307 * }308 *309 * const callSites = getCallSites({ sourceMap: true });310 *311 * // With sourceMap:312 * // Function Name: ''313 * // Script Name: example.js314 * // Line Number: 7315 * // Column Number: 26316 *317 * // Without sourceMap:318 * // Function Name: ''319 * // Script Name: example.js320 * // Line Number: 2321 * // Column Number: 26322 * ```323 * @param frameCount Number of frames to capture as call site objects.324 * **Default:** `10`. Allowable range is between 1 and 200.325 * @return An array of call site objects326 * @since v22.9.0327 */328 export function getCallSites(frameCount?: number, options?: GetCallSitesOptions): CallSiteObject[];329 export function getCallSites(options: GetCallSitesOptions): CallSiteObject[];330 /**331 * Returns the string name for a numeric error code that comes from a Node.js API.332 * The mapping between error codes and error names is platform-dependent.333 * See `Common System Errors` for the names of common errors.334 *335 * ```js336 * fs.access('file/that/does/not/exist', (err) => {337 * const name = util.getSystemErrorName(err.errno);338 * console.error(name); // ENOENT339 * });340 * ```341 * @since v9.7.0342 */343 export function getSystemErrorName(err: number): string;344 /**345 * Enable or disable printing a stack trace on `SIGINT`. The API is only available on the main thread.346 * @since 24.6.0347 */348 export function setTraceSigInt(enable: boolean): void;349 /**350 * Returns a Map of all system error codes available from the Node.js API.351 * The mapping between error codes and error names is platform-dependent.352 * See `Common System Errors` for the names of common errors.353 *354 * ```js355 * fs.access('file/that/does/not/exist', (err) => {356 * const errorMap = util.getSystemErrorMap();357 * const name = errorMap.get(err.errno);358 * console.error(name); // ENOENT359 * });360 * ```361 * @since v16.0.0, v14.17.0362 */363 export function getSystemErrorMap(): Map<number, [string, string]>;364 /**365 * Returns the string message for a numeric error code that comes from a Node.js366 * API.367 * The mapping between error codes and string messages is platform-dependent.368 *369 * ```js370 * fs.access('file/that/does/not/exist', (err) => {371 * const message = util.getSystemErrorMessage(err.errno);372 * console.error(message); // no such file or directory373 * });374 * ```375 * @since v22.12.0376 */377 export function getSystemErrorMessage(err: number): string;378 /**379 * Returns the `string` after replacing any surrogate code points380 * (or equivalently, any unpaired surrogate code units) with the381 * Unicode "replacement character" U+FFFD.382 * @since v16.8.0, v14.18.0383 */384 export function toUSVString(string: string): string;385 /**386 * Creates and returns an `AbortController` instance whose `AbortSignal` is marked387 * as transferable and can be used with `structuredClone()` or `postMessage()`.388 * @since v18.11.0389 * @returns A transferable AbortController390 */391 export function transferableAbortController(): AbortController;392 /**393 * Marks the given `AbortSignal` as transferable so that it can be used with`structuredClone()` and `postMessage()`.394 *395 * ```js396 * const signal = transferableAbortSignal(AbortSignal.timeout(100));397 * const channel = new MessageChannel();398 * channel.port2.postMessage(signal, [signal]);399 * ```400 * @since v18.11.0401 * @param signal The AbortSignal402 * @returns The same AbortSignal403 */404 export function transferableAbortSignal(signal: AbortSignal): AbortSignal;405 /**406 * Listens to abort event on the provided `signal` and returns a promise that resolves when the `signal` is aborted.407 * If `resource` is provided, it weakly references the operation's associated object,408 * so if `resource` is garbage collected before the `signal` aborts,409 * then returned promise shall remain pending.410 * This prevents memory leaks in long-running or non-cancelable operations.411 *412 * ```js413 * import { aborted } from 'node:util';414 *415 * // Obtain an object with an abortable signal, like a custom resource or operation.416 * const dependent = obtainSomethingAbortable();417 *418 * // Pass `dependent` as the resource, indicating the promise should only resolve419 * // if `dependent` is still in memory when the signal is aborted.420 * aborted(dependent.signal, dependent).then(() => {421 * // This code runs when `dependent` is aborted.422 * console.log('Dependent resource was aborted.');423 * });424 *425 * // Simulate an event that triggers the abort.426 * dependent.on('event', () => {427 * dependent.abort(); // This will cause the `aborted` promise to resolve.428 * });429 * ```430 * @since v19.7.0431 * @param resource Any non-null object tied to the abortable operation and held weakly.432 * If `resource` is garbage collected before the `signal` aborts, the promise remains pending,433 * allowing Node.js to stop tracking it.434 * This helps prevent memory leaks in long-running or non-cancelable operations.435 */436 export function aborted(signal: AbortSignal, resource: any): Promise<void>;437 /**438 * The `util.inspect()` method returns a string representation of `object` that is439 * intended for debugging. The output of `util.inspect` may change at any time440 * and should not be depended upon programmatically. Additional `options` may be441 * passed that alter the result.442 * `util.inspect()` will use the constructor's name and/or `Symbol.toStringTag`443 * property to make an identifiable tag for an inspected value.444 *445 * ```js446 * class Foo {447 * get [Symbol.toStringTag]() {448 * return 'bar';449 * }450 * }451 *452 * class Bar {}453 *454 * const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });455 *456 * util.inspect(new Foo()); // 'Foo [bar] {}'457 * util.inspect(new Bar()); // 'Bar {}'458 * util.inspect(baz); // '[foo] {}'459 * ```460 *461 * Circular references point to their anchor by using a reference index:462 *463 * ```js464 * import { inspect } from 'node:util';465 *466 * const obj = {};467 * obj.a = [obj];468 * obj.b = {};469 * obj.b.inner = obj.b;470 * obj.b.obj = obj;471 *472 * console.log(inspect(obj));473 * // <ref *1> {474 * // a: [ [Circular *1] ],475 * // b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }476 * // }477 * ```478 *479 * The following example inspects all properties of the `util` object:480 *481 * ```js482 * import util from 'node:util';483 *484 * console.log(util.inspect(util, { showHidden: true, depth: null }));485 * ```486 *487 * The following example highlights the effect of the `compact` option:488 *489 * ```js490 * import { inspect } from 'node:util';491 *492 * const o = {493 * a: [1, 2, [[494 * 'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +495 * 'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',496 * 'test',497 * 'foo']], 4],498 * b: new Map([['za', 1], ['zb', 'test']]),499 * };500 * console.log(inspect(o, { compact: true, depth: 5, breakLength: 80 }));501 *502 * // { a:503 * // [ 1,504 * // 2,505 * // [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line506 * // 'test',507 * // 'foo' ] ],508 * // 4 ],509 * // b: Map(2) { 'za' => 1, 'zb' => 'test' } }510 *511 * // Setting `compact` to false or an integer creates more reader friendly output.512 * console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 }));513 *514 * // {515 * // a: [516 * // 1,517 * // 2,518 * // [519 * // [520 * // 'Lorem ipsum dolor sit amet,\n' +521 * // 'consectetur adipiscing elit, sed do eiusmod \n' +522 * // 'tempor incididunt ut labore et dolore magna aliqua.',523 * // 'test',524 * // 'foo'525 * // ]526 * // ],527 * // 4528 * // ],529 * // b: Map(2) {530 * // 'za' => 1,531 * // 'zb' => 'test'532 * // }533 * // }534 *535 * // Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a536 * // single line.537 * ```538 *539 * The `showHidden` option allows `WeakMap` and `WeakSet` entries to be540 * inspected. If there are more entries than `maxArrayLength`, there is no541 * guarantee which entries are displayed. That means retrieving the same542 * `WeakSet` entries twice may result in different output. Furthermore, entries543 * with no remaining strong references may be garbage collected at any time.544 *545 * ```js546 * import { inspect } from 'node:util';547 *548 * const obj = { a: 1 };549 * const obj2 = { b: 2 };550 * const weakSet = new WeakSet([obj, obj2]);551 *552 * console.log(inspect(weakSet, { showHidden: true }));553 * // WeakSet { { a: 1 }, { b: 2 } }554 * ```555 *556 * The `sorted` option ensures that an object's property insertion order does not557 * impact the result of `util.inspect()`.558 *559 * ```js560 * import { inspect } from 'node:util';561 * import assert from 'node:assert';562 *563 * const o1 = {564 * b: [2, 3, 1],565 * a: '`a` comes before `b`',566 * c: new Set([2, 3, 1]),567 * };568 * console.log(inspect(o1, { sorted: true }));569 * // { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }570 * console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));571 * // { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }572 *573 * const o2 = {574 * c: new Set([2, 1, 3]),575 * a: '`a` comes before `b`',576 * b: [2, 3, 1],577 * };578 * assert.strict.equal(579 * inspect(o1, { sorted: true }),580 * inspect(o2, { sorted: true }),581 * );582 * ```583 *584 * The `numericSeparator` option adds an underscore every three digits to all585 * numbers.586 *587 * ```js588 * import { inspect } from 'node:util';589 *590 * const thousand = 1000;591 * const million = 1000000;592 * const bigNumber = 123456789n;593 * const bigDecimal = 1234.12345;594 *595 * console.log(inspect(thousand, { numericSeparator: true }));596 * // 1_000597 * console.log(inspect(million, { numericSeparator: true }));598 * // 1_000_000599 * console.log(inspect(bigNumber, { numericSeparator: true }));600 * // 123_456_789n601 * console.log(inspect(bigDecimal, { numericSeparator: true }));602 * // 1_234.123_45603 * ```604 *605 * `util.inspect()` is a synchronous method intended for debugging. Its maximum606 * output length is approximately 128 MiB. Inputs that result in longer output will607 * be truncated.608 * @since v0.3.0609 * @param object Any JavaScript primitive or `Object`.610 * @return The representation of `object`.611 */612 export function inspect(object: any, showHidden?: boolean, depth?: number | null, color?: boolean): string;613 export function inspect(object: any, options?: InspectOptions): string;614 export namespace inspect {615 let colors: NodeJS.Dict<[number, number]>;616 let styles: {617 [K in Style]: string;618 };619 let defaultOptions: InspectOptions;620 /**621 * Allows changing inspect settings from the repl.622 */623 let replDefaults: InspectOptions;624 /**625 * That can be used to declare custom inspect functions.626 */627 const custom: unique symbol;628 }629 /**630 * Alias for [`Array.isArray()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray).631 *632 * Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`.633 *634 * ```js635 * import util from 'node:util';636 *637 * util.isArray([]);638 * // Returns: true639 * util.isArray(new Array());640 * // Returns: true641 * util.isArray({});642 * // Returns: false643 * ```644 * @since v0.6.0645 * @deprecated Since v4.0.0 - Use `isArray` instead.646 */647 export function isArray(object: unknown): object is unknown[];648 /**649 * Usage of `util.inherits()` is discouraged. Please use the ES6 `class` and650 * `extends` keywords to get language level inheritance support. Also note651 * that the two styles are [semantically incompatible](https://github.com/nodejs/node/issues/4179).652 *653 * Inherit the prototype methods from one654 * [constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) into another. The655 * prototype of `constructor` will be set to a new object created from656 * `superConstructor`.657 *658 * This mainly adds some input validation on top of659 * `Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)`.660 * As an additional convenience, `superConstructor` will be accessible661 * through the `constructor.super_` property.662 *663 * ```js664 * const util = require('node:util');665 * const EventEmitter = require('node:events');666 *667 * function MyStream() {668 * EventEmitter.call(this);669 * }670 *671 * util.inherits(MyStream, EventEmitter);672 *673 * MyStream.prototype.write = function(data) {674 * this.emit('data', data);675 * };676 *677 * const stream = new MyStream();678 *679 * console.log(stream instanceof EventEmitter); // true680 * console.log(MyStream.super_ === EventEmitter); // true681 *682 * stream.on('data', (data) => {683 * console.log(`Received data: "${data}"`);684 * });685 * stream.write('It works!'); // Received data: "It works!"686 * ```687 *688 * ES6 example using `class` and `extends`:689 *690 * ```js691 * import EventEmitter from 'node:events';692 *693 * class MyStream extends EventEmitter {694 * write(data) {695 * this.emit('data', data);696 * }697 * }698 *699 * const stream = new MyStream();700 *701 * stream.on('data', (data) => {702 * console.log(`Received data: "${data}"`);703 * });704 * stream.write('With ES6');705 * ```706 * @since v0.3.0707 * @legacy Use ES2015 class syntax and `extends` keyword instead.708 */709 export function inherits(constructor: unknown, superConstructor: unknown): void;710 export type DebugLoggerFunction = (msg: string, ...param: unknown[]) => void;711 export interface DebugLogger extends DebugLoggerFunction {712 /**713 * The `util.debuglog().enabled` getter is used to create a test that can be used714 * in conditionals based on the existence of the `NODE_DEBUG` environment variable.715 * If the `section` name appears within the value of that environment variable,716 * then the returned value will be `true`. If not, then the returned value will be717 * `false`.718 *719 * ```js720 * import { debuglog } from 'node:util';721 * const enabled = debuglog('foo').enabled;722 * if (enabled) {723 * console.log('hello from foo [%d]', 123);724 * }725 * ```726 *727 * If this program is run with `NODE_DEBUG=foo` in the environment, then it will728 * output something like:729 *730 * ```console731 * hello from foo [123]732 * ```733 */734 enabled: boolean;735 }736 /**737 * The `util.debuglog()` method is used to create a function that conditionally738 * writes debug messages to `stderr` based on the existence of the `NODE_DEBUG`739 * environment variable. If the `section` name appears within the value of that740 * environment variable, then the returned function operates similar to741 * `console.error()`. If not, then the returned function is a no-op.742 *743 * ```js744 * import { debuglog } from 'node:util';745 * const log = debuglog('foo');746 *747 * log('hello from foo [%d]', 123);748 * ```749 *750 * If this program is run with `NODE_DEBUG=foo` in the environment, then751 * it will output something like:752 *753 * ```console754 * FOO 3245: hello from foo [123]755 * ```756 *757 * where `3245` is the process id. If it is not run with that758 * environment variable set, then it will not print anything.759 *760 * The `section` supports wildcard also:761 *762 * ```js763 * import { debuglog } from 'node:util';764 * const log = debuglog('foo-bar');765 *766 * log('hi there, it\'s foo-bar [%d]', 2333);767 * ```768 *769 * if it is run with `NODE_DEBUG=foo*` in the environment, then it will output770 * something like:771 *772 * ```console773 * FOO-BAR 3257: hi there, it's foo-bar [2333]774 * ```775 *776 * Multiple comma-separated `section` names may be specified in the `NODE_DEBUG`777 * environment variable: `NODE_DEBUG=fs,net,tls`.778 *779 * The optional `callback` argument can be used to replace the logging function780 * with a different function that doesn't have any initialization or781 * unnecessary wrapping.782 *783 * ```js784 * import { debuglog } from 'node:util';785 * let log = debuglog('internals', (debug) => {786 * // Replace with a logging function that optimizes out787 * // testing if the section is enabled788 * log = debug;789 * });790 * ```791 * @since v0.11.3792 * @param section A string identifying the portion of the application for which the `debuglog` function is being created.793 * @param callback A callback invoked the first time the logging function is called with a function argument that is a more optimized logging function.794 * @return The logging function795 */796 export function debuglog(section: string, callback?: (fn: DebugLoggerFunction) => void): DebugLogger;797 export { debuglog as debug };798 export interface DeprecateOptions {799 /**800 * When false do not change the prototype of object while emitting the deprecation warning.801 * @since v24.12.0802 * @default true803 */804 modifyPrototype?: boolean | undefined;805 }806 /**807 * The `util.deprecate()` method wraps `fn` (which may be a function or class) in808 * such a way that it is marked as deprecated.809 *810 * ```js811 * import { deprecate } from 'node:util';812 *813 * export const obsoleteFunction = deprecate(() => {814 * // Do something here.815 * }, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');816 * ```817 *818 * When called, `util.deprecate()` will return a function that will emit a819 * `DeprecationWarning` using the `'warning'` event. The warning will820 * be emitted and printed to `stderr` the first time the returned function is821 * called. After the warning is emitted, the wrapped function is called without822 * emitting a warning.823 *824 * If the same optional `code` is supplied in multiple calls to `util.deprecate()`,825 * the warning will be emitted only once for that `code`.826 *827 * ```js828 * import { deprecate } from 'node:util';829 *830 * const fn1 = deprecate(831 * () => 'a value',832 * 'deprecation message',833 * 'DEP0001',834 * );835 * const fn2 = deprecate(836 * () => 'a different value',837 * 'other dep message',838 * 'DEP0001',839 * );840 * fn1(); // Emits a deprecation warning with code DEP0001841 * fn2(); // Does not emit a deprecation warning because it has the same code842 * ```843 *844 * If either the `--no-deprecation` or `--no-warnings` command-line flags are845 * used, or if the `process.noDeprecation` property is set to `true` _prior_ to846 * the first deprecation warning, the `util.deprecate()` method does nothing.847 *848 * If the `--trace-deprecation` or `--trace-warnings` command-line flags are set,849 * or the `process.traceDeprecation` property is set to `true`, a warning and a850 * stack trace are printed to `stderr` the first time the deprecated function is851 * called.852 *853 * If the `--throw-deprecation` command-line flag is set, or the854 * `process.throwDeprecation` property is set to `true`, then an exception will be855 * thrown when the deprecated function is called.856 *857 * The `--throw-deprecation` command-line flag and `process.throwDeprecation`858 * property take precedence over `--trace-deprecation` and859 * `process.traceDeprecation`.860 * @since v0.8.0861 * @param fn The function that is being deprecated.862 * @param msg A warning message to display when the deprecated function is invoked.863 * @param code A deprecation code. See the `list of deprecated APIs` for a list of codes.864 * @return The deprecated function wrapped to emit a warning.865 */866 export function deprecate<T extends Function>(fn: T, msg: string, code?: string, options?: DeprecateOptions): T;867 export interface IsDeepStrictEqualOptions {868 /**869 * If `true`, prototype and constructor870 * comparison is skipped during deep strict equality check.871 * @since v24.9.0872 * @default false873 */874 skipPrototype?: boolean | undefined;875 }876 /**877 * Returns `true` if there is deep strict equality between `val1` and `val2`.878 * Otherwise, returns `false`.879 *880 * See `assert.deepStrictEqual()` for more information about deep strict881 * equality.882 * @since v9.0.0883 */884 export function isDeepStrictEqual(val1: unknown, val2: unknown, options?: IsDeepStrictEqualOptions): boolean;885 /**886 * Returns `str` with any ANSI escape codes removed.887 *888 * ```js889 * console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));890 * // Prints "value"891 * ```892 * @since v16.11.0893 */894 export function stripVTControlCharacters(str: string): string;895 /**896 * Takes an `async` function (or a function that returns a `Promise`) and returns a897 * function following the error-first callback style, i.e. taking898 * an `(err, value) => ...` callback as the last argument. In the callback, the899 * first argument will be the rejection reason (or `null` if the `Promise`900 * resolved), and the second argument will be the resolved value.901 *902 * ```js903 * import { callbackify } from 'node:util';904 *905 * async function fn() {906 * return 'hello world';907 * }908 * const callbackFunction = callbackify(fn);909 *910 * callbackFunction((err, ret) => {911 * if (err) throw err;912 * console.log(ret);913 * });914 * ```915 *916 * Will print:917 *918 * ```text919 * hello world920 * ```921 *922 * The callback is executed asynchronously, and will have a limited stack trace.923 * If the callback throws, the process will emit an `'uncaughtException'`924 * event, and if not handled will exit.925 *926 * Since `null` has a special meaning as the first argument to a callback, if a927 * wrapped function rejects a `Promise` with a falsy value as a reason, the value928 * is wrapped in an `Error` with the original value stored in a field named929 * `reason`.930 *931 * ```js932 * function fn() {933 * return Promise.reject(null);934 * }935 * const callbackFunction = util.callbackify(fn);936 *937 * callbackFunction((err, ret) => {938 * // When the Promise was rejected with `null` it is wrapped with an Error and939 * // the original value is stored in `reason`.940 * err && Object.hasOwn(err, 'reason') && err.reason === null; // true941 * });942 * ```943 * @since v8.2.0944 * @param fn An `async` function945 * @return a callback style function946 */947 export function callbackify(fn: () => Promise<void>): (callback: (err: NodeJS.ErrnoException) => void) => void;948 export function callbackify<TResult>(949 fn: () => Promise<TResult>,950 ): (callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void;951 export function callbackify<T1>(952 fn: (arg1: T1) => Promise<void>,953 ): (arg1: T1, callback: (err: NodeJS.ErrnoException) => void) => void;954 export function callbackify<T1, TResult>(955 fn: (arg1: T1) => Promise<TResult>,956 ): (arg1: T1, callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void;957 export function callbackify<T1, T2>(958 fn: (arg1: T1, arg2: T2) => Promise<void>,959 ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException) => void) => void;960 export function callbackify<T1, T2, TResult>(961 fn: (arg1: T1, arg2: T2) => Promise<TResult>,962 ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void;963 export function callbackify<T1, T2, T3>(964 fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<void>,965 ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException) => void) => void;966 export function callbackify<T1, T2, T3, TResult>(967 fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<TResult>,968 ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void;969 export function callbackify<T1, T2, T3, T4>(970 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>,971 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException) => void) => void;972 export function callbackify<T1, T2, T3, T4, TResult>(973 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<TResult>,974 ): (975 arg1: T1,976 arg2: T2,977 arg3: T3,978 arg4: T4,979 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void,980 ) => void;981 export function callbackify<T1, T2, T3, T4, T5>(982 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>,983 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException) => void) => void;984 export function callbackify<T1, T2, T3, T4, T5, TResult>(985 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<TResult>,986 ): (987 arg1: T1,988 arg2: T2,989 arg3: T3,990 arg4: T4,991 arg5: T5,992 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void,993 ) => void;994 export function callbackify<T1, T2, T3, T4, T5, T6>(995 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<void>,996 ): (997 arg1: T1,998 arg2: T2,999 arg3: T3,1000 arg4: T4,1001 arg5: T5,1002 arg6: T6,1003 callback: (err: NodeJS.ErrnoException) => void,1004 ) => void;1005 export function callbackify<T1, T2, T3, T4, T5, T6, TResult>(1006 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<TResult>,1007 ): (1008 arg1: T1,1009 arg2: T2,1010 arg3: T3,1011 arg4: T4,1012 arg5: T5,1013 arg6: T6,1014 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void,1015 ) => void;1016 export interface CustomPromisifyLegacy<TCustom extends Function> extends Function {1017 __promisify__: TCustom;1018 }1019 export interface CustomPromisifySymbol<TCustom extends Function> extends Function {1020 [promisify.custom]: TCustom;1021 }1022 export type CustomPromisify<TCustom extends Function> =1023 | CustomPromisifySymbol<TCustom>1024 | CustomPromisifyLegacy<TCustom>;1025 /**1026 * Takes a function following the common error-first callback style, i.e. taking1027 * an `(err, value) => ...` callback as the last argument, and returns a version1028 * that returns promises.1029 *1030 * ```js1031 * import { promisify } from 'node:util';1032 * import { stat } from 'node:fs';1033 *1034 * const promisifiedStat = promisify(stat);1035 * promisifiedStat('.').then((stats) => {1036 * // Do something with `stats`1037 * }).catch((error) => {1038 * // Handle the error.1039 * });1040 * ```1041 *1042 * Or, equivalently using `async function`s:1043 *1044 * ```js1045 * import { promisify } from 'node:util';1046 * import { stat } from 'node:fs';1047 *1048 * const promisifiedStat = promisify(stat);1049 *1050 * async function callStat() {1051 * const stats = await promisifiedStat('.');1052 * console.log(`This directory is owned by ${stats.uid}`);1053 * }1054 *1055 * callStat();1056 * ```1057 *1058 * If there is an `original[util.promisify.custom]` property present, `promisify`1059 * will return its value, see [Custom promisified functions](https://nodejs.org/docs/latest-v24.x/api/util.html#custom-promisified-functions).1060 *1061 * `promisify()` assumes that `original` is a function taking a callback as its1062 * final argument in all cases. If `original` is not a function, `promisify()`1063 * will throw an error. If `original` is a function but its last argument is not1064 * an error-first callback, it will still be passed an error-first1065 * callback as its last argument.1066 *1067 * Using `promisify()` on class methods or other methods that use `this` may not1068 * work as expected unless handled specially:1069 *1070 * ```js1071 * import { promisify } from 'node:util';1072 *1073 * class Foo {1074 * constructor() {1075 * this.a = 42;1076 * }1077 *1078 * bar(callback) {1079 * callback(null, this.a);1080 * }1081 * }1082 *1083 * const foo = new Foo();1084 *1085 * const naiveBar = promisify(foo.bar);1086 * // TypeError: Cannot read properties of undefined (reading 'a')1087 * // naiveBar().then(a => console.log(a));1088 *1089 * naiveBar.call(foo).then((a) => console.log(a)); // '42'1090 *1091 * const bindBar = naiveBar.bind(foo);1092 * bindBar().then((a) => console.log(a)); // '42'1093 * ```1094 * @since v8.0.01095 */1096 export function promisify<TCustom extends Function>(fn: CustomPromisify<TCustom>): TCustom;1097 export function promisify<TResult>(1098 fn: (callback: (err: any, result: TResult) => void) => void,1099 ): () => Promise<TResult>;1100 export function promisify(fn: (callback: (err?: any) => void) => void): () => Promise<void>;1101 export function promisify<T1, TResult>(1102 fn: (arg1: T1, callback: (err: any, result: TResult) => void) => void,1103 ): (arg1: T1) => Promise<TResult>;1104 export function promisify<T1>(fn: (arg1: T1, callback: (err?: any) => void) => void): (arg1: T1) => Promise<void>;1105 export function promisify<T1, T2, TResult>(1106 fn: (arg1: T1, arg2: T2, callback: (err: any, result: TResult) => void) => void,1107 ): (arg1: T1, arg2: T2) => Promise<TResult>;1108 export function promisify<T1, T2>(1109 fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void,1110 ): (arg1: T1, arg2: T2) => Promise<void>;1111 export function promisify<T1, T2, T3, TResult>(1112 fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err: any, result: TResult) => void) => void,1113 ): (arg1: T1, arg2: T2, arg3: T3) => Promise<TResult>;1114 export function promisify<T1, T2, T3>(1115 fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void,1116 ): (arg1: T1, arg2: T2, arg3: T3) => Promise<void>;1117 export function promisify<T1, T2, T3, T4, TResult>(1118 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: any, result: TResult) => void) => void,1119 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<TResult>;1120 export function promisify<T1, T2, T3, T4>(1121 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err?: any) => void) => void,1122 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>;1123 export function promisify<T1, T2, T3, T4, T5, TResult>(1124 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: any, result: TResult) => void) => void,1125 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<TResult>;1126 export function promisify<T1, T2, T3, T4, T5>(1127 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err?: any) => void) => void,1128 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>;1129 export function promisify(fn: Function): Function;1130 export namespace promisify {1131 /**1132 * That can be used to declare custom promisified variants of functions.1133 */1134 const custom: unique symbol;1135 }1136 /**1137 * Stability: 1.1 - Active development1138 * Given an example `.env` file:1139 *1140 * ```js1141 * import { parseEnv } from 'node:util';1142 *1143 * parseEnv('HELLO=world\nHELLO=oh my\n');1144 * // Returns: { HELLO: 'oh my' }1145 * ```1146 * @param content The raw contents of a `.env` file.1147 * @since v20.12.01148 */1149 export function parseEnv(content: string): NodeJS.Dict<string>;1150 // https://nodejs.org/docs/latest/api/util.html#foreground-colors1151 type ForegroundColors =1152 | "black"1153 | "blackBright"1154 | "blue"1155 | "blueBright"1156 | "cyan"1157 | "cyanBright"1158 | "gray"1159 | "green"1160 | "greenBright"1161 | "grey"1162 | "magenta"1163 | "magentaBright"1164 | "red"1165 | "redBright"1166 | "white"1167 | "whiteBright"1168 | "yellow"1169 | "yellowBright";1170 // https://nodejs.org/docs/latest/api/util.html#background-colors1171 type BackgroundColors =1172 | "bgBlack"1173 | "bgBlackBright"1174 | "bgBlue"1175 | "bgBlueBright"1176 | "bgCyan"1177 | "bgCyanBright"1178 | "bgGray"1179 | "bgGreen"1180 | "bgGreenBright"1181 | "bgGrey"1182 | "bgMagenta"1183 | "bgMagentaBright"1184 | "bgRed"1185 | "bgRedBright"1186 | "bgWhite"1187 | "bgWhiteBright"1188 | "bgYellow"1189 | "bgYellowBright";1190 // https://nodejs.org/docs/latest/api/util.html#modifiers1191 type Modifiers =1192 | "blink"1193 | "bold"1194 | "dim"1195 | "doubleunderline"1196 | "framed"1197 | "hidden"1198 | "inverse"1199 | "italic"1200 | "none"