Pinsave/counterstrike
1
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 * ```js258 * import { getCallSites } from 'node:util';259 *260 * function exampleFunction() {261 * const callSites = getCallSites();262 *263 * console.log('Call Sites:');264 * callSites.forEach((callSite, index) => {265 * console.log(`CallSite ${index + 1}:`);266 * console.log(`Function Name: ${callSite.functionName}`);267 * console.log(`Script Name: ${callSite.scriptName}`);268 * console.log(`Line Number: ${callSite.lineNumber}`);269 * console.log(`Column Number: ${callSite.column}`);270 * });271 * // CallSite 1:272 * // Function Name: exampleFunction273 * // Script Name: /home/example.js274 * // Line Number: 5275 * // Column Number: 26276 *277 * // CallSite 2:278 * // Function Name: anotherFunction279 * // Script Name: /home/example.js280 * // Line Number: 22281 * // Column Number: 3282 *283 * // ...284 * }285 *286 * // A function to simulate another stack layer287 * function anotherFunction() {288 * exampleFunction();289 * }290 *291 * anotherFunction();292 * ```293 *294 * It is possible to reconstruct the original locations by setting the option `sourceMap` to `true`.295 * If the source map is not available, the original location will be the same as the current location.296 * When the `--enable-source-maps` flag is enabled, for example when using `--experimental-transform-types`,297 * `sourceMap` will be true by default.298 *299 * ```ts300 * import { getCallSites } from 'node:util';301 *302 * interface Foo {303 * foo: string;304 * }305 *306 * const callSites = getCallSites({ sourceMap: true });307 *308 * // With sourceMap:309 * // Function Name: ''310 * // Script Name: example.js311 * // Line Number: 7312 * // Column Number: 26313 *314 * // Without sourceMap:315 * // Function Name: ''316 * // Script Name: example.js317 * // Line Number: 2318 * // Column Number: 26319 * ```320 * @param frameCount Number of frames to capture as call site objects.321 * **Default:** `10`. Allowable range is between 1 and 200.322 * @return An array of call site objects323 * @since v22.9.0324 */325 export function getCallSites(frameCount?: number, options?: GetCallSitesOptions): CallSiteObject[];326 export function getCallSites(options: GetCallSitesOptions): CallSiteObject[];327 /**328 * Returns the string name for a numeric error code that comes from a Node.js API.329 * The mapping between error codes and error names is platform-dependent.330 * See `Common System Errors` for the names of common errors.331 *332 * ```js333 * fs.access('file/that/does/not/exist', (err) => {334 * const name = util.getSystemErrorName(err.errno);335 * console.error(name); // ENOENT336 * });337 * ```338 * @since v9.7.0339 */340 export function getSystemErrorName(err: number): string;341 /**342 * Returns a Map of all system error codes available from the Node.js API.343 * The mapping between error codes and error names is platform-dependent.344 * See `Common System Errors` for the names of common errors.345 *346 * ```js347 * fs.access('file/that/does/not/exist', (err) => {348 * const errorMap = util.getSystemErrorMap();349 * const name = errorMap.get(err.errno);350 * console.error(name); // ENOENT351 * });352 * ```353 * @since v16.0.0, v14.17.0354 */355 export function getSystemErrorMap(): Map<number, [string, string]>;356 /**357 * Returns the string message for a numeric error code that comes from a Node.js358 * API.359 * The mapping between error codes and string messages is platform-dependent.360 *361 * ```js362 * fs.access('file/that/does/not/exist', (err) => {363 * const message = util.getSystemErrorMessage(err.errno);364 * console.error(message); // no such file or directory365 * });366 * ```367 * @since v22.12.0368 */369 export function getSystemErrorMessage(err: number): string;370 /**371 * Returns the `string` after replacing any surrogate code points372 * (or equivalently, any unpaired surrogate code units) with the373 * Unicode "replacement character" U+FFFD.374 * @since v16.8.0, v14.18.0375 */376 export function toUSVString(string: string): string;377 /**378 * Creates and returns an `AbortController` instance whose `AbortSignal` is marked379 * as transferable and can be used with `structuredClone()` or `postMessage()`.380 * @since v18.11.0381 * @returns A transferable AbortController382 */383 export function transferableAbortController(): AbortController;384 /**385 * Marks the given `AbortSignal` as transferable so that it can be used with`structuredClone()` and `postMessage()`.386 *387 * ```js388 * const signal = transferableAbortSignal(AbortSignal.timeout(100));389 * const channel = new MessageChannel();390 * channel.port2.postMessage(signal, [signal]);391 * ```392 * @since v18.11.0393 * @param signal The AbortSignal394 * @returns The same AbortSignal395 */396 export function transferableAbortSignal(signal: AbortSignal): AbortSignal;397 /**398 * Listens to abort event on the provided `signal` and returns a promise that resolves when the `signal` is aborted.399 * If `resource` is provided, it weakly references the operation's associated object,400 * so if `resource` is garbage collected before the `signal` aborts,401 * then returned promise shall remain pending.402 * This prevents memory leaks in long-running or non-cancelable operations.403 *404 * ```js405 * import { aborted } from 'node:util';406 *407 * // Obtain an object with an abortable signal, like a custom resource or operation.408 * const dependent = obtainSomethingAbortable();409 *410 * // Pass `dependent` as the resource, indicating the promise should only resolve411 * // if `dependent` is still in memory when the signal is aborted.412 * aborted(dependent.signal, dependent).then(() => {413 * // This code runs when `dependent` is aborted.414 * console.log('Dependent resource was aborted.');415 * });416 *417 * // Simulate an event that triggers the abort.418 * dependent.on('event', () => {419 * dependent.abort(); // This will cause the `aborted` promise to resolve.420 * });421 * ```422 * @since v19.7.0423 * @param resource Any non-null object tied to the abortable operation and held weakly.424 * If `resource` is garbage collected before the `signal` aborts, the promise remains pending,425 * allowing Node.js to stop tracking it.426 * This helps prevent memory leaks in long-running or non-cancelable operations.427 */428 export function aborted(signal: AbortSignal, resource: any): Promise<void>;429 /**430 * The `util.inspect()` method returns a string representation of `object` that is431 * intended for debugging. The output of `util.inspect` may change at any time432 * and should not be depended upon programmatically. Additional `options` may be433 * passed that alter the result.434 * `util.inspect()` will use the constructor's name and/or `@@toStringTag` to make435 * an identifiable tag for an inspected value.436 *437 * ```js438 * class Foo {439 * get [Symbol.toStringTag]() {440 * return 'bar';441 * }442 * }443 *444 * class Bar {}445 *446 * const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });447 *448 * util.inspect(new Foo()); // 'Foo [bar] {}'449 * util.inspect(new Bar()); // 'Bar {}'450 * util.inspect(baz); // '[foo] {}'451 * ```452 *453 * Circular references point to their anchor by using a reference index:454 *455 * ```js456 * import { inspect } from 'node:util';457 *458 * const obj = {};459 * obj.a = [obj];460 * obj.b = {};461 * obj.b.inner = obj.b;462 * obj.b.obj = obj;463 *464 * console.log(inspect(obj));465 * // <ref *1> {466 * // a: [ [Circular *1] ],467 * // b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }468 * // }469 * ```470 *471 * The following example inspects all properties of the `util` object:472 *473 * ```js474 * import util from 'node:util';475 *476 * console.log(util.inspect(util, { showHidden: true, depth: null }));477 * ```478 *479 * The following example highlights the effect of the `compact` option:480 *481 * ```js482 * import { inspect } from 'node:util';483 *484 * const o = {485 * a: [1, 2, [[486 * 'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +487 * 'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',488 * 'test',489 * 'foo']], 4],490 * b: new Map([['za', 1], ['zb', 'test']]),491 * };492 * console.log(inspect(o, { compact: true, depth: 5, breakLength: 80 }));493 *494 * // { a:495 * // [ 1,496 * // 2,497 * // [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line498 * // 'test',499 * // 'foo' ] ],500 * // 4 ],501 * // b: Map(2) { 'za' => 1, 'zb' => 'test' } }502 *503 * // Setting `compact` to false or an integer creates more reader friendly output.504 * console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 }));505 *506 * // {507 * // a: [508 * // 1,509 * // 2,510 * // [511 * // [512 * // 'Lorem ipsum dolor sit amet,\n' +513 * // 'consectetur adipiscing elit, sed do eiusmod \n' +514 * // 'tempor incididunt ut labore et dolore magna aliqua.',515 * // 'test',516 * // 'foo'517 * // ]518 * // ],519 * // 4520 * // ],521 * // b: Map(2) {522 * // 'za' => 1,523 * // 'zb' => 'test'524 * // }525 * // }526 *527 * // Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a528 * // single line.529 * ```530 *531 * The `showHidden` option allows `WeakMap` and `WeakSet` entries to be532 * inspected. If there are more entries than `maxArrayLength`, there is no533 * guarantee which entries are displayed. That means retrieving the same534 * `WeakSet` entries twice may result in different output. Furthermore, entries535 * with no remaining strong references may be garbage collected at any time.536 *537 * ```js538 * import { inspect } from 'node:util';539 *540 * const obj = { a: 1 };541 * const obj2 = { b: 2 };542 * const weakSet = new WeakSet([obj, obj2]);543 *544 * console.log(inspect(weakSet, { showHidden: true }));545 * // WeakSet { { a: 1 }, { b: 2 } }546 * ```547 *548 * The `sorted` option ensures that an object's property insertion order does not549 * impact the result of `util.inspect()`.550 *551 * ```js552 * import { inspect } from 'node:util';553 * import assert from 'node:assert';554 *555 * const o1 = {556 * b: [2, 3, 1],557 * a: '`a` comes before `b`',558 * c: new Set([2, 3, 1]),559 * };560 * console.log(inspect(o1, { sorted: true }));561 * // { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }562 * console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));563 * // { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }564 *565 * const o2 = {566 * c: new Set([2, 1, 3]),567 * a: '`a` comes before `b`',568 * b: [2, 3, 1],569 * };570 * assert.strict.equal(571 * inspect(o1, { sorted: true }),572 * inspect(o2, { sorted: true }),573 * );574 * ```575 *576 * The `numericSeparator` option adds an underscore every three digits to all577 * numbers.578 *579 * ```js580 * import { inspect } from 'node:util';581 *582 * const thousand = 1000;583 * const million = 1000000;584 * const bigNumber = 123456789n;585 * const bigDecimal = 1234.12345;586 *587 * console.log(inspect(thousand, { numericSeparator: true }));588 * // 1_000589 * console.log(inspect(million, { numericSeparator: true }));590 * // 1_000_000591 * console.log(inspect(bigNumber, { numericSeparator: true }));592 * // 123_456_789n593 * console.log(inspect(bigDecimal, { numericSeparator: true }));594 * // 1_234.123_45595 * ```596 *597 * `util.inspect()` is a synchronous method intended for debugging. Its maximum598 * output length is approximately 128 MiB. Inputs that result in longer output will599 * be truncated.600 * @since v0.3.0601 * @param object Any JavaScript primitive or `Object`.602 * @return The representation of `object`.603 */604 export function inspect(object: any, showHidden?: boolean, depth?: number | null, color?: boolean): string;605 export function inspect(object: any, options?: InspectOptions): string;606 export namespace inspect {607 let colors: NodeJS.Dict<[number, number]>;608 let styles: {609 [K in Style]: string;610 };611 let defaultOptions: InspectOptions;612 /**613 * Allows changing inspect settings from the repl.614 */615 let replDefaults: InspectOptions;616 /**617 * That can be used to declare custom inspect functions.618 */619 const custom: unique symbol;620 }621 /**622 * Alias for [`Array.isArray()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray).623 *624 * Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`.625 *626 * ```js627 * import util from 'node:util';628 *629 * util.isArray([]);630 * // Returns: true631 * util.isArray(new Array());632 * // Returns: true633 * util.isArray({});634 * // Returns: false635 * ```636 * @since v0.6.0637 * @deprecated Since v4.0.0 - Use `isArray` instead.638 */639 export function isArray(object: unknown): object is unknown[];640 /**641 * Usage of `util.inherits()` is discouraged. Please use the ES6 `class` and642 * `extends` keywords to get language level inheritance support. Also note643 * that the two styles are [semantically incompatible](https://github.com/nodejs/node/issues/4179).644 *645 * Inherit the prototype methods from one646 * [constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) into another. The647 * prototype of `constructor` will be set to a new object created from648 * `superConstructor`.649 *650 * This mainly adds some input validation on top of651 * `Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)`.652 * As an additional convenience, `superConstructor` will be accessible653 * through the `constructor.super_` property.654 *655 * ```js656 * const util = require('node:util');657 * const EventEmitter = require('node:events');658 *659 * function MyStream() {660 * EventEmitter.call(this);661 * }662 *663 * util.inherits(MyStream, EventEmitter);664 *665 * MyStream.prototype.write = function(data) {666 * this.emit('data', data);667 * };668 *669 * const stream = new MyStream();670 *671 * console.log(stream instanceof EventEmitter); // true672 * console.log(MyStream.super_ === EventEmitter); // true673 *674 * stream.on('data', (data) => {675 * console.log(`Received data: "${data}"`);676 * });677 * stream.write('It works!'); // Received data: "It works!"678 * ```679 *680 * ES6 example using `class` and `extends`:681 *682 * ```js683 * import EventEmitter from 'node:events';684 *685 * class MyStream extends EventEmitter {686 * write(data) {687 * this.emit('data', data);688 * }689 * }690 *691 * const stream = new MyStream();692 *693 * stream.on('data', (data) => {694 * console.log(`Received data: "${data}"`);695 * });696 * stream.write('With ES6');697 * ```698 * @since v0.3.0699 * @legacy Use ES2015 class syntax and `extends` keyword instead.700 */701 export function inherits(constructor: unknown, superConstructor: unknown): void;702 export type DebugLoggerFunction = (msg: string, ...param: unknown[]) => void;703 export interface DebugLogger extends DebugLoggerFunction {704 /**705 * The `util.debuglog().enabled` getter is used to create a test that can be used706 * in conditionals based on the existence of the `NODE_DEBUG` environment variable.707 * If the `section` name appears within the value of that environment variable,708 * then the returned value will be `true`. If not, then the returned value will be709 * `false`.710 *711 * ```js712 * import { debuglog } from 'node:util';713 * const enabled = debuglog('foo').enabled;714 * if (enabled) {715 * console.log('hello from foo [%d]', 123);716 * }717 * ```718 *719 * If this program is run with `NODE_DEBUG=foo` in the environment, then it will720 * output something like:721 *722 * ```console723 * hello from foo [123]724 * ```725 */726 enabled: boolean;727 }728 /**729 * The `util.debuglog()` method is used to create a function that conditionally730 * writes debug messages to `stderr` based on the existence of the `NODE_DEBUG`731 * environment variable. If the `section` name appears within the value of that732 * environment variable, then the returned function operates similar to733 * `console.error()`. If not, then the returned function is a no-op.734 *735 * ```js736 * import { debuglog } from 'node:util';737 * const log = debuglog('foo');738 *739 * log('hello from foo [%d]', 123);740 * ```741 *742 * If this program is run with `NODE_DEBUG=foo` in the environment, then743 * it will output something like:744 *745 * ```console746 * FOO 3245: hello from foo [123]747 * ```748 *749 * where `3245` is the process id. If it is not run with that750 * environment variable set, then it will not print anything.751 *752 * The `section` supports wildcard also:753 *754 * ```js755 * import { debuglog } from 'node:util';756 * const log = debuglog('foo');757 *758 * log('hi there, it\'s foo-bar [%d]', 2333);759 * ```760 *761 * if it is run with `NODE_DEBUG=foo*` in the environment, then it will output762 * something like:763 *764 * ```console765 * FOO-BAR 3257: hi there, it's foo-bar [2333]766 * ```767 *768 * Multiple comma-separated `section` names may be specified in the `NODE_DEBUG`769 * environment variable: `NODE_DEBUG=fs,net,tls`.770 *771 * The optional `callback` argument can be used to replace the logging function772 * with a different function that doesn't have any initialization or773 * unnecessary wrapping.774 *775 * ```js776 * import { debuglog } from 'node:util';777 * let log = debuglog('internals', (debug) => {778 * // Replace with a logging function that optimizes out779 * // testing if the section is enabled780 * log = debug;781 * });782 * ```783 * @since v0.11.3784 * @param section A string identifying the portion of the application for which the `debuglog` function is being created.785 * @param callback A callback invoked the first time the logging function is called with a function argument that is a more optimized logging function.786 * @return The logging function787 */788 export function debuglog(section: string, callback?: (fn: DebugLoggerFunction) => void): DebugLogger;789 export { debuglog as debug };790 /**791 * The `util.deprecate()` method wraps `fn` (which may be a function or class) in792 * such a way that it is marked as deprecated.793 *794 * ```js795 * import { deprecate } from 'node:util';796 *797 * export const obsoleteFunction = deprecate(() => {798 * // Do something here.799 * }, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');800 * ```801 *802 * When called, `util.deprecate()` will return a function that will emit a803 * `DeprecationWarning` using the `'warning'` event. The warning will804 * be emitted and printed to `stderr` the first time the returned function is805 * called. After the warning is emitted, the wrapped function is called without806 * emitting a warning.807 *808 * If the same optional `code` is supplied in multiple calls to `util.deprecate()`,809 * the warning will be emitted only once for that `code`.810 *811 * ```js812 * import { deprecate } from 'node:util';813 *814 * const fn1 = deprecate(815 * () => 'a value',816 * 'deprecation message',817 * 'DEP0001',818 * );819 * const fn2 = deprecate(820 * () => 'a different value',821 * 'other dep message',822 * 'DEP0001',823 * );824 * fn1(); // Emits a deprecation warning with code DEP0001825 * fn2(); // Does not emit a deprecation warning because it has the same code826 * ```827 *828 * If either the `--no-deprecation` or `--no-warnings` command-line flags are829 * used, or if the `process.noDeprecation` property is set to `true` _prior_ to830 * the first deprecation warning, the `util.deprecate()` method does nothing.831 *832 * If the `--trace-deprecation` or `--trace-warnings` command-line flags are set,833 * or the `process.traceDeprecation` property is set to `true`, a warning and a834 * stack trace are printed to `stderr` the first time the deprecated function is835 * called.836 *837 * If the `--throw-deprecation` command-line flag is set, or the838 * `process.throwDeprecation` property is set to `true`, then an exception will be839 * thrown when the deprecated function is called.840 *841 * The `--throw-deprecation` command-line flag and `process.throwDeprecation`842 * property take precedence over `--trace-deprecation` and843 * `process.traceDeprecation`.844 * @since v0.8.0845 * @param fn The function that is being deprecated.846 * @param msg A warning message to display when the deprecated function is invoked.847 * @param code A deprecation code. See the `list of deprecated APIs` for a list of codes.848 * @return The deprecated function wrapped to emit a warning.849 */850 export function deprecate<T extends Function>(fn: T, msg: string, code?: string): T;851 /**852 * Returns `true` if there is deep strict equality between `val1` and `val2`.853 * Otherwise, returns `false`.854 *855 * See `assert.deepStrictEqual()` for more information about deep strict856 * equality.857 * @since v9.0.0858 */859 export function isDeepStrictEqual(val1: unknown, val2: unknown): boolean;860 /**861 * Returns `str` with any ANSI escape codes removed.862 *863 * ```js864 * console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));865 * // Prints "value"866 * ```867 * @since v16.11.0868 */869 export function stripVTControlCharacters(str: string): string;870 /**871 * Takes an `async` function (or a function that returns a `Promise`) and returns a872 * function following the error-first callback style, i.e. taking873 * an `(err, value) => ...` callback as the last argument. In the callback, the874 * first argument will be the rejection reason (or `null` if the `Promise`875 * resolved), and the second argument will be the resolved value.876 *877 * ```js878 * import { callbackify } from 'node:util';879 *880 * async function fn() {881 * return 'hello world';882 * }883 * const callbackFunction = callbackify(fn);884 *885 * callbackFunction((err, ret) => {886 * if (err) throw err;887 * console.log(ret);888 * });889 * ```890 *891 * Will print:892 *893 * ```text894 * hello world895 * ```896 *897 * The callback is executed asynchronously, and will have a limited stack trace.898 * If the callback throws, the process will emit an `'uncaughtException'`899 * event, and if not handled will exit.900 *901 * Since `null` has a special meaning as the first argument to a callback, if a902 * wrapped function rejects a `Promise` with a falsy value as a reason, the value903 * is wrapped in an `Error` with the original value stored in a field named904 * `reason`.905 *906 * ```js907 * function fn() {908 * return Promise.reject(null);909 * }910 * const callbackFunction = util.callbackify(fn);911 *912 * callbackFunction((err, ret) => {913 * // When the Promise was rejected with `null` it is wrapped with an Error and914 * // the original value is stored in `reason`.915 * err && Object.hasOwn(err, 'reason') && err.reason === null; // true916 * });917 * ```918 * @since v8.2.0919 * @param fn An `async` function920 * @return a callback style function921 */922 export function callbackify(fn: () => Promise<void>): (callback: (err: NodeJS.ErrnoException) => void) => void;923 export function callbackify<TResult>(924 fn: () => Promise<TResult>,925 ): (callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void;926 export function callbackify<T1>(927 fn: (arg1: T1) => Promise<void>,928 ): (arg1: T1, callback: (err: NodeJS.ErrnoException) => void) => void;929 export function callbackify<T1, TResult>(930 fn: (arg1: T1) => Promise<TResult>,931 ): (arg1: T1, callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void;932 export function callbackify<T1, T2>(933 fn: (arg1: T1, arg2: T2) => Promise<void>,934 ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException) => void) => void;935 export function callbackify<T1, T2, TResult>(936 fn: (arg1: T1, arg2: T2) => Promise<TResult>,937 ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void;938 export function callbackify<T1, T2, T3>(939 fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<void>,940 ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException) => void) => void;941 export function callbackify<T1, T2, T3, TResult>(942 fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<TResult>,943 ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void;944 export function callbackify<T1, T2, T3, T4>(945 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>,946 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException) => void) => void;947 export function callbackify<T1, T2, T3, T4, TResult>(948 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<TResult>,949 ): (950 arg1: T1,951 arg2: T2,952 arg3: T3,953 arg4: T4,954 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void,955 ) => void;956 export function callbackify<T1, T2, T3, T4, T5>(957 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>,958 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException) => void) => void;959 export function callbackify<T1, T2, T3, T4, T5, TResult>(960 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<TResult>,961 ): (962 arg1: T1,963 arg2: T2,964 arg3: T3,965 arg4: T4,966 arg5: T5,967 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void,968 ) => void;969 export function callbackify<T1, T2, T3, T4, T5, T6>(970 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<void>,971 ): (972 arg1: T1,973 arg2: T2,974 arg3: T3,975 arg4: T4,976 arg5: T5,977 arg6: T6,978 callback: (err: NodeJS.ErrnoException) => void,979 ) => void;980 export function callbackify<T1, T2, T3, T4, T5, T6, TResult>(981 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<TResult>,982 ): (983 arg1: T1,984 arg2: T2,985 arg3: T3,986 arg4: T4,987 arg5: T5,988 arg6: T6,989 callback: (err: NodeJS.ErrnoException | null, result: TResult) => void,990 ) => void;991 export interface CustomPromisifyLegacy<TCustom extends Function> extends Function {992 __promisify__: TCustom;993 }994 export interface CustomPromisifySymbol<TCustom extends Function> extends Function {995 [promisify.custom]: TCustom;996 }997 export type CustomPromisify<TCustom extends Function> =998 | CustomPromisifySymbol<TCustom>999 | CustomPromisifyLegacy<TCustom>;1000 /**1001 * Takes a function following the common error-first callback style, i.e. taking1002 * an `(err, value) => ...` callback as the last argument, and returns a version1003 * that returns promises.1004 *1005 * ```js1006 * import { promisify } from 'node:util';1007 * import { stat } from 'node:fs';1008 *1009 * const promisifiedStat = promisify(stat);1010 * promisifiedStat('.').then((stats) => {1011 * // Do something with `stats`1012 * }).catch((error) => {1013 * // Handle the error.1014 * });1015 * ```1016 *1017 * Or, equivalently using `async function`s:1018 *1019 * ```js1020 * import { promisify } from 'node:util';1021 * import { stat } from 'node:fs';1022 *1023 * const promisifiedStat = promisify(stat);1024 *1025 * async function callStat() {1026 * const stats = await promisifiedStat('.');1027 * console.log(`This directory is owned by ${stats.uid}`);1028 * }1029 *1030 * callStat();1031 * ```1032 *1033 * If there is an `original[util.promisify.custom]` property present, `promisify`1034 * will return its value, see [Custom promisified functions](https://nodejs.org/docs/latest-v24.x/api/util.html#custom-promisified-functions).1035 *1036 * `promisify()` assumes that `original` is a function taking a callback as its1037 * final argument in all cases. If `original` is not a function, `promisify()`1038 * will throw an error. If `original` is a function but its last argument is not1039 * an error-first callback, it will still be passed an error-first1040 * callback as its last argument.1041 *1042 * Using `promisify()` on class methods or other methods that use `this` may not1043 * work as expected unless handled specially:1044 *1045 * ```js1046 * import { promisify } from 'node:util';1047 *1048 * class Foo {1049 * constructor() {1050 * this.a = 42;1051 * }1052 *1053 * bar(callback) {1054 * callback(null, this.a);1055 * }1056 * }1057 *1058 * const foo = new Foo();1059 *1060 * const naiveBar = promisify(foo.bar);1061 * // TypeError: Cannot read properties of undefined (reading 'a')1062 * // naiveBar().then(a => console.log(a));1063 *1064 * naiveBar.call(foo).then((a) => console.log(a)); // '42'1065 *1066 * const bindBar = naiveBar.bind(foo);1067 * bindBar().then((a) => console.log(a)); // '42'1068 * ```1069 * @since v8.0.01070 */1071 export function promisify<TCustom extends Function>(fn: CustomPromisify<TCustom>): TCustom;1072 export function promisify<TResult>(1073 fn: (callback: (err: any, result: TResult) => void) => void,1074 ): () => Promise<TResult>;1075 export function promisify(fn: (callback: (err?: any) => void) => void): () => Promise<void>;1076 export function promisify<T1, TResult>(1077 fn: (arg1: T1, callback: (err: any, result: TResult) => void) => void,1078 ): (arg1: T1) => Promise<TResult>;1079 export function promisify<T1>(fn: (arg1: T1, callback: (err?: any) => void) => void): (arg1: T1) => Promise<void>;1080 export function promisify<T1, T2, TResult>(1081 fn: (arg1: T1, arg2: T2, callback: (err: any, result: TResult) => void) => void,1082 ): (arg1: T1, arg2: T2) => Promise<TResult>;1083 export function promisify<T1, T2>(1084 fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void,1085 ): (arg1: T1, arg2: T2) => Promise<void>;1086 export function promisify<T1, T2, T3, TResult>(1087 fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err: any, result: TResult) => void) => void,1088 ): (arg1: T1, arg2: T2, arg3: T3) => Promise<TResult>;1089 export function promisify<T1, T2, T3>(1090 fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void,1091 ): (arg1: T1, arg2: T2, arg3: T3) => Promise<void>;1092 export function promisify<T1, T2, T3, T4, TResult>(1093 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: any, result: TResult) => void) => void,1094 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<TResult>;1095 export function promisify<T1, T2, T3, T4>(1096 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err?: any) => void) => void,1097 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>;1098 export function promisify<T1, T2, T3, T4, T5, TResult>(1099 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: any, result: TResult) => void) => void,1100 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<TResult>;1101 export function promisify<T1, T2, T3, T4, T5>(1102 fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err?: any) => void) => void,1103 ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>;1104 export function promisify(fn: Function): Function;1105 export namespace promisify {1106 /**1107 * That can be used to declare custom promisified variants of functions.1108 */1109 const custom: unique symbol;1110 }1111 /**1112 * Stability: 1.1 - Active development1113 * Given an example `.env` file:1114 *1115 * ```js1116 * import { parseEnv } from 'node:util';1117 *1118 * parseEnv('HELLO=world\nHELLO=oh my\n');1119 * // Returns: { HELLO: 'oh my' }1120 * ```1121 * @param content The raw contents of a `.env` file.1122 * @since v20.12.01123 */1124 export function parseEnv(content: string): NodeJS.Dict<string>;1125 // https://nodejs.org/docs/latest/api/util.html#foreground-colors1126 type ForegroundColors =1127 | "black"1128 | "blackBright"1129 | "blue"1130 | "blueBright"1131 | "cyan"1132 | "cyanBright"1133 | "gray"1134 | "green"1135 | "greenBright"1136 | "grey"1137 | "magenta"1138 | "magentaBright"1139 | "red"1140 | "redBright"1141 | "white"1142 | "whiteBright"1143 | "yellow"1144 | "yellowBright";1145 // https://nodejs.org/docs/latest/api/util.html#background-colors1146 type BackgroundColors =1147 | "bgBlack"1148 | "bgBlackBright"1149 | "bgBlue"1150 | "bgBlueBright"1151 | "bgCyan"1152 | "bgCyanBright"1153 | "bgGray"1154 | "bgGreen"1155 | "bgGreenBright"1156 | "bgGrey"1157 | "bgMagenta"1158 | "bgMagentaBright"1159 | "bgRed"1160 | "bgRedBright"1161 | "bgWhite"1162 | "bgWhiteBright"1163 | "bgYellow"1164 | "bgYellowBright";1165 // https://nodejs.org/docs/latest/api/util.html#modifiers1166 type Modifiers =1167 | "blink"1168 | "bold"1169 | "dim"1170 | "doubleunderline"1171 | "framed"1172 | "hidden"1173 | "inverse"1174 | "italic"1175 | "overlined"1176 | "reset"1177 | "strikethrough"1178 | "underline";1179 export interface StyleTextOptions {1180 /**1181 * When true, `stream` is checked to see if it can handle colors.1182 * @default true1183 */1184 validateStream?: boolean | undefined;1185 /**1186 * A stream that will be validated if it can be colored.1187 * @default process.stdout1188 */1189 stream?: NodeJS.WritableStream | undefined;1190 }1191 /**1192 * This function returns a formatted text considering the `format` passed1193 * for printing in a terminal. It is aware of the terminal's capabilities1194 * and acts according to the configuration set via `NO_COLOR`,1195 * `NODE_DISABLE_COLORS` and `FORCE_COLOR` environment variables.1196 *1197 * ```js1198 * import { styleText } from 'node:util';1199 * import { stderr } from 'node:process';1200 *