Node.js v26.0.0 Dokumentation

Util#

Das node:util-Modul unterstützt die Anforderungen der internen APIs von Node.js. Viele der Dienstprogramme sind auch für Anwendungs- und Modulentwickler nützlich. Zugriff darauf:

import util from 'node:util';
const util = require('node:util');
copy

util.callbackify(original)#

• original <Function> Eine async-Funktion
• Rückgabe: <Function> eine Funktion im Callback-Stil

Nimmt eine async-Funktion (oder eine Funktion, die ein Promise zurückgibt) und gibt eine Funktion zurück, die dem Error-First-Callback-Stil folgt, d. h. sie akzeptiert ein (err, value) => ...-Callback als letztes Argument. Im Callback ist das erste Argument der Grund für die Ablehnung (oder null, wenn das Promise erfolgreich aufgelöst wurde) und das zweite Argument ist der aufgelöste Wert.

import { callbackify } from 'node:util';

async function fn() {
  return 'hello world';
}
const callbackFunction = callbackify(fn);

callbackFunction((err, ret) => {
  if (err) throw err;
  console.log(ret);
});
const { callbackify } = require('node:util');

async function fn() {
  return 'hello world';
}
const callbackFunction = callbackify(fn);

callbackFunction((err, ret) => {
  if (err) throw err;
  console.log(ret);
});
copy

Wird ausgeben

hello world
copy

Der Callback wird asynchron ausgeführt und hat einen begrenzten Stack-Trace. Wenn der Callback eine Ausnahme wirft, sendet der Prozess ein 'uncaughtException'-Ereignis; wenn dieses nicht behandelt wird, beendet sich der Prozess.

Da null eine besondere Bedeutung als erstes Argument eines Callbacks hat, wird der Wert in einen Error eingepackt, falls eine eingepackte Funktion ein Promise mit einem falsy Wert ablehnt. Der ursprüngliche Wert wird in einem Feld namens reason gespeichert.

function fn() {
  return Promise.reject(null);
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  // When the Promise was rejected with `null` it is wrapped with an Error and
  // the original value is stored in `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null;  // true
});
copy

util.convertProcessSignalToExitCode(signal)#

• signal <string> Ein Signalname (z. B. 'SIGTERM')
• Rückgabe: <number> Der dem signal entsprechende Exit-Code

Die Methode util.convertProcessSignalToExitCode() wandelt einen Signalnamen in den entsprechenden POSIX-Exit-Code um. Gemäß dem POSIX-Standard wird der Exit-Code für einen Prozess, der durch ein Signal beendet wurde, als 128 + Signalnummer berechnet.

Wenn signal kein gültiger Signalname ist, wird ein Fehler geworfen. Siehe signal(7) für eine Liste gültiger Signale.

import { convertProcessSignalToExitCode } from 'node:util';

console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
const { convertProcessSignalToExitCode } = require('node:util');

console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
copy

Dies ist besonders nützlich, wenn mit Prozessen gearbeitet wird, um den Exit-Code basierend auf dem Signal zu bestimmen, das den Prozess beendet hat.

util.debuglog(section[, callback])#

• section <string> Eine Zeichenfolge, die den Teil der Anwendung identifiziert, für den die debuglog-Funktion erstellt wird.
• callback <Function> Ein Callback, der beim ersten Aufruf der Logging-Funktion mit einem Funktionsargument aufgerufen wird, das eine optimiertere Logging-Funktion darstellt.
• Rückgabe: <Function> die Logging-Funktion

Die Methode util.debuglog() wird verwendet, um eine Funktion zu erstellen, die bedingt Debug-Nachrichten in stderr schreibt, basierend auf dem Vorhandensein der Umgebungsvariablen NODE_DEBUG. Wenn der section-Name innerhalb des Wertes dieser Umgebungsvariable erscheint, arbeitet die zurückgegebene Funktion ähnlich wie console.error(). Falls nicht, ist die zurückgegebene Funktion ein No-Op.

import { debuglog } from 'node:util';
const log = debuglog('foo');

log('hello from foo [%d]', 123);
const { debuglog } = require('node:util');
const log = debuglog('foo');

log('hello from foo [%d]', 123);
copy

Wenn dieses Programm mit NODE_DEBUG=foo in der Umgebung ausgeführt wird, gibt es etwa Folgendes aus:

FOO 3245: hello from foo [123]
copy

wobei 3245 die Prozess-ID ist. Wenn es ohne diese gesetzte Umgebungsvariable ausgeführt wird, druckt es nichts.

Die section unterstützt auch Wildcards:

import { debuglog } from 'node:util';
const log = debuglog('foo-bar');

log('hi there, it\'s foo-bar [%d]', 2333);
const { debuglog } = require('node:util');
const log = debuglog('foo-bar');

log('hi there, it\'s foo-bar [%d]', 2333);
copy

Wenn es mit NODE_DEBUG=foo* in der Umgebung ausgeführt wird, gibt es etwa Folgendes aus:

FOO-BAR 3257: hi there, it's foo-bar [2333]
copy

Mehrere durch Kommas getrennte section-Namen können in der Umgebungsvariablen NODE_DEBUG angegeben werden: NODE_DEBUG=fs,net,tls.

Das optionale callback-Argument kann verwendet werden, um die Logging-Funktion durch eine andere Funktion zu ersetzen, die keine Initialisierung oder unnötiges Wrapping erfordert.

import { debuglog } from 'node:util';
let log = debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  log = debug;
});
const { debuglog } = require('node:util');
let log = debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  log = debug;
});
copy

debuglog().enabled#

• Typ: <boolean>

Der Getter util.debuglog().enabled wird verwendet, um einen Test zu erstellen, der in Bedingungen basierend auf dem Vorhandensein der Umgebungsvariablen NODE_DEBUG verwendet werden kann. Wenn der section-Name im Wert dieser Umgebungsvariable erscheint, ist der Rückgabewert true. Wenn nicht, ist der Rückgabewert false.

import { debuglog } from 'node:util';
const enabled = debuglog('foo').enabled;
if (enabled) {
  console.log('hello from foo [%d]', 123);
}
const { debuglog } = require('node:util');
const enabled = debuglog('foo').enabled;
if (enabled) {
  console.log('hello from foo [%d]', 123);
}
copy

Wenn dieses Programm mit NODE_DEBUG=foo in der Umgebung ausgeführt wird, gibt es etwa Folgendes aus:

hello from foo [123]
copy

util.debug(section)#

Alias für util.debuglog. Die Verwendung ermöglicht eine bessere Lesbarkeit, die kein Logging impliziert, wenn nur util.debuglog().enabled verwendet wird.

util.deprecate(fn, msg[, code[, options]])#

• fn <Function> Die Funktion, die als veraltet markiert wird.
• msg <string> Eine Warnmeldung, die angezeigt wird, wenn die veraltete Funktion aufgerufen wird.
• code <string> Ein Veraltungscode. Siehe die Liste veralteter APIs für eine Liste der Codes.
• options <Object>
  • modifyPrototype <boolean> Wenn false, wird der Prototyp des Objekts beim Ausgeben der Veraltungswarnung nicht geändert. Standard: true.
• Rückgabe: <Function> Die veraltete Funktion, verpackt, um eine Warnung auszugeben.

Die Methode util.deprecate() umschließt fn (was eine Funktion oder Klasse sein kann) auf eine Weise, dass sie als veraltet markiert ist.

import { deprecate } from 'node:util';

export const obsoleteFunction = deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');
const { deprecate } = require('node:util');

exports.obsoleteFunction = deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');
copy

Beim Aufruf gibt util.deprecate() eine Funktion zurück, die eine DeprecationWarning über das 'warning'-Ereignis ausgibt. Die Warnung wird beim ersten Aufruf der zurückgegebenen Funktion ausgegeben und an stderr gedruckt. Nach der Ausgabe der Warnung wird die umschlossene Funktion aufgerufen, ohne eine weitere Warnung auszugeben.

Wenn derselbe optionale code in mehreren Aufrufen von util.deprecate() angegeben wird, wird die Warnung nur einmal für diesen code ausgegeben.

import { deprecate } from 'node:util';

const fn1 = deprecate(
  () => 'a value',
  'deprecation message',
  'DEP0001',
);
const fn2 = deprecate(
  () => 'a  different value',
  'other dep message',
  'DEP0001',
);
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code
const { deprecate } = require('node:util');

const fn1 = deprecate(
  function() {
    return 'a value';
  },
  'deprecation message',
  'DEP0001',
);
const fn2 = deprecate(
  function() {
    return 'a  different value';
  },
  'other dep message',
  'DEP0001',
);
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code
copy

Wenn entweder die Befehlszeilen-Flags --no-deprecation oder --no-warnings verwendet werden oder wenn die Eigenschaft process.noDeprecation vor der ersten Veraltungswarnung auf true gesetzt wird, bewirkt die Methode util.deprecate() nichts.

Wenn die Befehlszeilen-Flags --trace-deprecation oder --trace-warnings gesetzt sind oder die Eigenschaft process.traceDeprecation auf true gesetzt ist, werden beim ersten Aufruf der veralteten Funktion eine Warnung und ein Stack-Trace an stderr gedruckt.

Wenn das Befehlszeilen-Flag --throw-deprecation gesetzt ist oder die Eigenschaft process.throwDeprecation auf true gesetzt ist, wird beim Aufruf der veralteten Funktion eine Ausnahme ausgelöst.

Das Befehlszeilen-Flag --throw-deprecation und die Eigenschaft process.throwDeprecation haben Vorrang vor --trace-deprecation und process.traceDeprecation.

util.diff(actual, expected)#

• actual <Array> | <string> Der erste zu vergleichende Wert

• expected <Array> | <string> Der zweite zu vergleichende Wert

• Rückgabe: <Array> Ein Array von Differenzeinträgen. Jeder Eintrag ist ein Array mit zwei Elementen

  • 0 <number> Operationscode: -1 für Löschen, 0 für No-Op/Unverändert, 1 für Einfügen
  • 1 <string> Der mit der Operation verbundene Wert

• Algorithmus-Komplexität: O(N*D), wobei

• N die Gesamtlänge der beiden Sequenzen kombiniert ist (N = actual.length + expected.length)

• D die Editierdistanz ist (die minimale Anzahl von Operationen, die erforderlich sind, um eine Sequenz in die andere umzuwandeln).

util.diff() vergleicht zwei Zeichenfolgen- oder Array-Werte und gibt ein Array von Differenzeinträgen zurück. Es verwendet den Myers-Diff-Algorithmus, um minimale Unterschiede zu berechnen, denselben Algorithmus, der intern von Fehlermeldungen bei Assertionen verwendet wird.

Wenn die Werte gleich sind, wird ein leeres Array zurückgegeben.

const { diff } = require('node:util');

// Comparing strings
const actualString = '12345678';
const expectedString = '12!!5!7!';
console.log(diff(actualString, expectedString));
// [
//   [0, '1'],
//   [0, '2'],
//   [1, '3'],
//   [1, '4'],
//   [-1, '!'],
//   [-1, '!'],
//   [0, '5'],
//   [1, '6'],
//   [-1, '!'],
//   [0, '7'],
//   [1, '8'],
//   [-1, '!'],
// ]
// Comparing arrays
const actualArray = ['1', '2', '3'];
const expectedArray = ['1', '3', '4'];
console.log(diff(actualArray, expectedArray));
// [
//   [0, '1'],
//   [1, '2'],
//   [0, '3'],
//   [-1, '4'],
// ]
// Equal values return empty array
console.log(diff('same', 'same'));
// []
copy

util.format(format[, ...args])#

• format <string> Eine printf-ähnliche Formatzeichenfolge.

Die Methode util.format() gibt eine formatierte Zeichenfolge zurück, wobei das erste Argument als printf-ähnliche Formatzeichenfolge verwendet wird, die null oder mehr Format-Spezifikatoren enthalten kann. Jeder Spezifikator wird durch den konvertierten Wert aus dem entsprechenden Argument ersetzt. Unterstützte Spezifikatoren sind:

• %s: String wird verwendet, um alle Werte außer BigInt, Object und -0 zu konvertieren. BigInt-Werte werden mit einem n dargestellt, und Objekte, die weder eine benutzerdefinierte toString-Funktion noch eine Symbol.toPrimitive-Funktion haben, werden mit util.inspect() mit den Optionen { depth: 0, colors: false, compact: 3 } inspiziert.
• %d: Number wird verwendet, um alle Werte außer BigInt und Symbol zu konvertieren.
• %i: parseInt(value, 10) wird für alle Werte außer BigInt und Symbol verwendet.
• %f: parseFloat(value) wird für alle Werte außer Symbol verwendet.
• %j: JSON. Ersetzt durch die Zeichenfolge '[Circular]', falls das Argument zirkuläre Referenzen enthält.
• %o: Object. Eine Zeichenfolgenrepräsentation eines Objekts mit generischer JavaScript-Objektformatierung. Ähnlich wie util.inspect() mit den Optionen { showHidden: true, showProxy: true }. Dies zeigt das vollständige Objekt einschließlich nicht aufzählbarer Eigenschaften und Proxys.
• %O: Object. Eine Zeichenfolgenrepräsentation eines Objekts mit generischer JavaScript-Objektformatierung. Ähnlich wie util.inspect() ohne Optionen. Dies zeigt das vollständige Objekt, ohne nicht aufzählbare Eigenschaften und Proxys.
• %c: CSS. Dieser Spezifikator wird ignoriert und überspringt jegliches CSS, das übergeben wird.
• %%: einzelnes Prozentzeichen ('%'). Dies verbraucht kein Argument.
• Rückgabe: <string> Die formatierte Zeichenfolge

Wenn ein Spezifikator kein entsprechendes Argument hat, wird er nicht ersetzt.

util.format('%s:%s', 'foo');
// Returns: 'foo:%s'
copy

Werte, die nicht Teil der Formatzeichenfolge sind, werden mit util.inspect() formatiert, sofern ihr Typ nicht string ist.

Wenn mehr Argumente an die Methode util.format() übergeben werden als die Anzahl der Spezifikatoren, werden die zusätzlichen Argumente an die zurückgegebene Zeichenfolge angehängt, getrennt durch Leerzeichen.

util.format('%s:%s', 'foo', 'bar', 'baz');
// Returns: 'foo:bar baz'
copy

Wenn das erste Argument keinen gültigen Format-Spezifikator enthält, gibt util.format() eine Zeichenfolge zurück, die die Verkettung aller Argumente getrennt durch Leerzeichen ist.

util.format(1, 2, 3);
// Returns: '1 2 3'
copy

Wenn nur ein Argument an util.format() übergeben wird, wird es ohne jegliche Formatierung zurückgegeben.

util.format('%% %s');
// Returns: '%% %s'
copy

util.format() ist eine synchrone Methode, die als Debugging-Werkzeug gedacht ist. Einige Eingabewerte können einen erheblichen Leistungsaufwand verursachen, der die Event-Loop blockieren kann. Verwenden Sie diese Funktion mit Vorsicht und niemals in einem Hot-Code-Pfad.

util.formatWithOptions(inspectOptions, format[, ...args])#

• inspectOptions <Object>
• format <string>

Diese Funktion ist identisch mit util.format(), außer dass sie ein inspectOptions-Argument akzeptiert, das Optionen angibt, die an util.inspect() weitergegeben werden.

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
// Returns 'See object { foo: 42 }', where `42` is colored as a number
// when printed to a terminal.
copy

util.getCallSites([frameCount][, options])#

• frameCount <integer> Optionale Anzahl von Frames, die als Call-Site-Objekte erfasst werden sollen. Standard: 10. Der zulässige Bereich liegt zwischen 1 und 200.
• options <Object> Optional.
• sourceMap <boolean> Rekonstruiert den ursprünglichen Speicherort im Stack-Trace aus der Source-Map. Standardmäßig aktiviert mit dem Flag --enable-source-maps.

Gibt ein Array von Call-Site-Objekten zurück, die den Stack der aufrufenden Funktion enthalten.

Im Gegensatz zum Zugriff auf error.stack wird das von dieser API zurückgegebene Ergebnis nicht durch Error.prepareStackTrace gestört.

import { getCallSites } from 'node:util';

function exampleFunction() {
  const callSites = getCallSites();

  console.log('Call Sites:');
  callSites.forEach((callSite, index) => {
    console.log(`CallSite ${index + 1}:`);
    console.log(`Function Name: ${callSite.functionName}`);
    console.log(`Script Name: ${callSite.scriptName}`);
    console.log(`Line Number: ${callSite.lineNumber}`);
    console.log(`Column Number: ${callSite.columnNumber}`);
  });
  // CallSite 1:
  // Function Name: exampleFunction
  // Script Name: /home/example.js
  // Line Number: 5
  // Column Number: 26

  // CallSite 2:
  // Function Name: anotherFunction
  // Script Name: /home/example.js
  // Line Number: 22
  // Column Number: 3

  // ...
}

// A function to simulate another stack layer
function anotherFunction() {
  exampleFunction();
}

anotherFunction();
const { getCallSites } = require('node:util');

function exampleFunction() {
  const callSites = getCallSites();

  console.log('Call Sites:');
  callSites.forEach((callSite, index) => {
    console.log(`CallSite ${index + 1}:`);
    console.log(`Function Name: ${callSite.functionName}`);
    console.log(`Script Name: ${callSite.scriptName}`);
    console.log(`Line Number: ${callSite.lineNumber}`);
    console.log(`Column Number: ${callSite.columnNumber}`);
  });
  // CallSite 1:
  // Function Name: exampleFunction
  // Script Name: /home/example.js
  // Line Number: 5
  // Column Number: 26

  // CallSite 2:
  // Function Name: anotherFunction
  // Script Name: /home/example.js
  // Line Number: 22
  // Column Number: 3

  // ...
}

// A function to simulate another stack layer
function anotherFunction() {
  exampleFunction();
}

anotherFunction();
copy

Es ist möglich, die ursprünglichen Speicherorte zu rekonstruieren, indem die Option sourceMap auf true gesetzt wird. Wenn die Source-Map nicht verfügbar ist, entspricht der ursprüngliche Speicherort dem aktuellen Speicherort. Wenn das Flag --enable-source-maps aktiviert ist, ist sourceMap standardmäßig true.

import { getCallSites } from 'node:util';

interface Foo {
  foo: string;
}

const callSites = getCallSites({ sourceMap: true });

// With sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 7
// Column Number: 26

// Without sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26
copy

const { getCallSites } = require('node:util');

const callSites = getCallSites({ sourceMap: true });

// With sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 7
// Column Number: 26

// Without sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26
copy

util.getSystemErrorName(err)#

• err <number>
• Rückgabe: <string>

Gibt den Namen als Zeichenfolge für einen numerischen Fehlercode zurück, der von einer Node.js-API stammt. Die Zuordnung zwischen Fehlercodes und Fehlernamen ist plattformabhängig. Siehe Häufige Systemfehler für die Namen häufiger Fehler.

fs.access('file/that/does/not/exist', (err) => {
  const name = util.getSystemErrorName(err.errno);
  console.error(name);  // ENOENT
});
copy

util.getSystemErrorMap()#

• Rückgabe: <Map>

Gibt eine Map aller Systemfehlercodes zurück, die von der Node.js-API verfügbar sind. Die Zuordnung zwischen Fehlercodes und Fehlernamen ist plattformabhängig. Siehe Häufige Systemfehler für die Namen häufiger Fehler.

fs.access('file/that/does/not/exist', (err) => {
  const errorMap = util.getSystemErrorMap();
  const name = errorMap.get(err.errno);
  console.error(name);  // ENOENT
});
copy

util.getSystemErrorMessage(err)#

• err <number>
• Rückgabe: <string>

Gibt die Nachricht als Zeichenfolge für einen numerischen Fehlercode zurück, der von einer Node.js-API stammt. Die Zuordnung zwischen Fehlercodes und Fehlernachrichten ist plattformabhängig.

fs.access('file/that/does/not/exist', (err) => {
  const message = util.getSystemErrorMessage(err.errno);
  console.error(message);  // No such file or directory
});
copy

util.setTraceSigInt(enable)#

• enable <boolean>

Aktiviert oder deaktiviert das Drucken eines Stack-Trace bei SIGINT. Die API ist nur im Haupt-Thread verfügbar.

util.inherits(constructor, superConstructor)#

• constructor <Function>
• superConstructor <Function>

Die Verwendung von util.inherits() wird nicht empfohlen. Bitte verwenden Sie die ES6-Schlüsselwörter class und extends, um eine Vererbung auf Sprachebene zu erhalten. Beachten Sie auch, dass die beiden Stile semantisch inkompatibel sind.

Vererben Sie die Prototypmethoden von einem Konstruktor an einen anderen. Der Prototyp von constructor wird auf ein neues Objekt gesetzt, das von superConstructor erstellt wurde.

Dies fügt hauptsächlich eine Eingabevalidierung zusätzlich zu Object.setPrototypeOf(constructor.prototype, superConstructor.prototype) hinzu. Als zusätzlichen Komfort ist superConstructor über die Eigenschaft constructor.super_ zugänglich.

const util = require('node:util');
const EventEmitter = require('node:events');

function MyStream() {
  EventEmitter.call(this);
}

util.inherits(MyStream, EventEmitter);

MyStream.prototype.write = function(data) {
  this.emit('data', data);
};

const stream = new MyStream();

console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('It works!'); // Received data: "It works!"
copy

ES6-Beispiel mit class und extends

import EventEmitter from 'node:events';

class MyStream extends EventEmitter {
  write(data) {
    this.emit('data', data);
  }
}

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6');
const EventEmitter = require('node:events');

class MyStream extends EventEmitter {
  write(data) {
    this.emit('data', data);
  }
}

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6');
copy

util.inspect(object[, options])#

util.inspect(object[, showHidden[, depth[, colors]]])#

• object <any> Jedes JavaScript-Primitiv oder Object.
• options <Object>
  • showHidden <boolean> Wenn true, werden die nicht aufzählbaren Symbole und Eigenschaften des object im formatierten Ergebnis enthalten sein. Auch Einträge von <WeakMap> und <WeakSet> sind enthalten, sowie benutzerdefinierte Prototyp-Eigenschaften (ausgenommen Methoden-Eigenschaften). Standard: false.
  • depth <number> Gibt an, wie oft beim Formatieren von object rekursiv vorgegangen werden soll. Dies ist nützlich für die Inspektion großer Objekte. Um bis zur maximalen Call-Stack-Größe zu rekursieren, übergeben Sie Infinity oder null. Standard: 2.
  • colors <boolean> Wenn true, wird die Ausgabe mit ANSI-Farbcodes formatiert. Farben sind anpassbar. Siehe Anpassen von util.inspect-Farben. Standard: false.
  • customInspect <boolean> Wenn false, werden [util.inspect.custom](depth, opts, inspect)-Funktionen nicht aufgerufen. Standard: true.
  • showProxy <boolean> Wenn true, beinhaltet die Proxy-Inspektion die target- und handler-Objekte. Standard: false.
  • maxArrayLength <integer> Gibt die maximale Anzahl von Array-, <TypedArray>-, <Map>-, <WeakMap>- und <WeakSet>-Elementen an, die beim Formatieren enthalten sein sollen. Setzen Sie auf null oder Infinity, um alle Elemente anzuzeigen. Setzen Sie auf 0 oder negativ, um keine Elemente anzuzeigen. Standard: 100.
  • maxStringLength <integer> Gibt die maximale Anzahl von Zeichen an, die beim Formatieren enthalten sein sollen. Setzen Sie auf null oder Infinity, um alle Elemente anzuzeigen. Setzen Sie auf 0 oder negativ, um keine Zeichen anzuzeigen. Standard: 10000.
  • breakLength <integer> Die Länge, bei der Eingabewerte auf mehrere Zeilen aufgeteilt werden. Setzen Sie auf Infinity, um die Eingabe als einzelne Zeile zu formatieren (in Kombination mit compact auf true oder einer beliebigen Zahl >= 1). Standard: 80.
  • compact <boolean> | <integer> Wenn dies auf false gesetzt wird, wird jeder Objektschlüssel in einer neuen Zeile angezeigt. Es wird bei neuen Zeilen in Text umgebrochen, der länger als breakLength ist. Wenn es auf eine Zahl gesetzt ist, werden die inneren n Elemente in einer einzigen Zeile vereint, solange alle Eigenschaften in breakLength passen. Kurze Array-Elemente werden ebenfalls gruppiert. Weitere Informationen finden Sie im Beispiel unten. Standard: 3.
  • sorted <boolean> | <Function> Wenn auf true oder eine Funktion gesetzt, werden alle Eigenschaften eines Objekts sowie Set- und Map-Einträge im resultierenden String sortiert. Wenn auf true gesetzt, wird die Standardsortierung verwendet. Wenn auf eine Funktion gesetzt, wird sie als Vergleichsfunktion verwendet.
  • getters <boolean> | <string> Wenn auf true gesetzt, werden Getter inspiziert. Wenn auf 'get' gesetzt, werden nur Getter ohne entsprechenden Setter inspiziert. Wenn auf 'set' gesetzt, werden nur Getter mit entsprechendem Setter inspiziert. Dies kann je nach Getter-Funktion zu Nebeneffekten führen. Standard: false.
  • numericSeparator <boolean> Wenn auf true gesetzt, wird ein Unterstrich verwendet, um alle drei Ziffern in allen Bigints und Zahlen zu trennen. Standard: false.
• Rückgabe: <string> Die Repräsentation des object.

Die Methode util.inspect() gibt eine Zeichenfolgenrepräsentation von object zurück, die für das Debugging vorgesehen ist. Die Ausgabe von util.inspect kann sich jederzeit ändern und sollte nicht programmatisch davon abhängig gemacht werden. Zusätzliche options können übergeben werden, die das Ergebnis beeinflussen. util.inspect() verwendet den Namen des Konstruktors und/oder die Symbol.toStringTag-Eigenschaft, um ein identifizierbares Tag für einen inspizierten Wert zu erstellen.

class Foo {
  get [Symbol.toStringTag]() {
    return 'bar';
  }
}

class Bar {}

const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });

util.inspect(new Foo()); // 'Foo [bar] {}'
util.inspect(new Bar()); // 'Bar {}'
util.inspect(baz);       // '[foo] {}'
copy

Zirkuläre Referenzen zeigen mit einem Referenzindex auf ihren Anker.

import { inspect } from 'node:util';

const obj = {};
obj.a = [obj];
obj.b = {};
obj.b.inner = obj.b;
obj.b.obj = obj;

console.log(inspect(obj));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// }
const { inspect } = require('node:util');

const obj = {};
obj.a = [obj];
obj.b = {};
obj.b.inner = obj.b;
obj.b.obj = obj;

console.log(inspect(obj));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// }
copy

Das folgende Beispiel inspiziert alle Eigenschaften des util-Objekts:

import util from 'node:util';

console.log(util.inspect(util, { showHidden: true, depth: null }));
const util = require('node:util');

console.log(util.inspect(util, { showHidden: true, depth: null }));
copy

Das folgende Beispiel hebt die Wirkung der compact-Option hervor:

import { inspect } from 'node:util';

const o = {
  a: [1, 2, [[
    'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +
      'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',
    'test',
    'foo']], 4],
  b: new Map([['za', 1], ['zb', 'test']]),
};
console.log(inspect(o, { compact: true, depth: 5, breakLength: 80 }));

// { a:
//   [ 1,
//     2,
//     [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Setting `compact` to false or an integer creates more reader friendly output.
console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 }));

// {
//   a: [
//     1,
//     2,
//     [
//       [
//         'Lorem ipsum dolor sit amet,\n' +
//           'consectetur adipiscing elit, sed do eiusmod \n' +
//           'tempor incididunt ut labore et dolore magna aliqua.',
//         'test',
//         'foo'
//       ]
//     ],
//     4
//   ],
//   b: Map(2) {
//     'za' => 1,
//     'zb' => 'test'
//   }
// }

// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
// single line.
const { inspect } = require('node:util');

const o = {
  a: [1, 2, [[
    'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +
      'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',
    'test',
    'foo']], 4],
  b: new Map([['za', 1], ['zb', 'test']]),
};
console.log(inspect(o, { compact: true, depth: 5, breakLength: 80 }));

// { a:
//   [ 1,
//     2,
//     [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Setting `compact` to false or an integer creates more reader friendly output.
console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 }));

// {
//   a: [
//     1,
//     2,
//     [
//       [
//         'Lorem ipsum dolor sit amet,\n' +
//           'consectetur adipiscing elit, sed do eiusmod \n' +
//           'tempor incididunt ut labore et dolore magna aliqua.',
//         'test',
//         'foo'
//       ]
//     ],
//     4
//   ],
//   b: Map(2) {
//     'za' => 1,
//     'zb' => 'test'
//   }
// }

// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
// single line.
copy

Die showHidden-Option ermöglicht es, Einträge von <WeakMap> und <WeakSet> zu inspizieren. Wenn es mehr Einträge als maxArrayLength gibt, gibt es keine Garantie, welche Einträge angezeigt werden. Das bedeutet, dass der zweimalige Abruf derselben <WeakSet>-Einträge zu unterschiedlichen Ausgaben führen kann. Außerdem können Einträge ohne verbleibende starke Referenzen jederzeit vom Garbage Collector gelöscht werden.

import { inspect } from 'node:util';

const obj = { a: 1 };
const obj2 = { b: 2 };
const weakSet = new WeakSet([obj, obj2]);

console.log(inspect(weakSet, { showHidden: true }));
// WeakSet { { a: 1 }, { b: 2 } }
const { inspect } = require('node:util');

const obj = { a: 1 };
const obj2 = { b: 2 };
const weakSet = new WeakSet([obj, obj2]);

console.log(inspect(weakSet, { showHidden: true }));
// WeakSet { { a: 1 }, { b: 2 } }
copy

Die sorted-Option stellt sicher, dass die Einfügereihenfolge der Eigenschaften eines Objekts das Ergebnis von util.inspect() nicht beeinflusst.

import { inspect } from 'node:util';
import assert from 'node:assert';

const o1 = {
  b: [2, 3, 1],
  a: '`a` comes before `b`',
  c: new Set([2, 3, 1]),
};
console.log(inspect(o1, { sorted: true }));
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

const o2 = {
  c: new Set([2, 1, 3]),
  a: '`a` comes before `b`',
  b: [2, 3, 1],
};
assert.strict.equal(
  inspect(o1, { sorted: true }),
  inspect(o2, { sorted: true }),
);
const { inspect } = require('node:util');
const assert = require('node:assert');

const o1 = {
  b: [2, 3, 1],
  a: '`a` comes before `b`',
  c: new Set([2, 3, 1]),
};
console.log(inspect(o1, { sorted: true }));
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

const o2 = {
  c: new Set([2, 1, 3]),
  a: '`a` comes before `b`',
  b: [2, 3, 1],
};
assert.strict.equal(
  inspect(o1, { sorted: true }),
  inspect(o2, { sorted: true }),
);
copy

Die numericSeparator-Option fügt allen Zahlen alle drei Ziffern einen Unterstrich hinzu.

import { inspect } from 'node:util';

const thousand = 1000;
const million = 1000000;
const bigNumber = 123456789n;
const bigDecimal = 1234.12345;

console.log(inspect(thousand, { numericSeparator: true }));
// 1_000
console.log(inspect(million, { numericSeparator: true }));
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }));
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }));
// 1_234.123_45
const { inspect } = require('node:util');

const thousand = 1000;
const million = 1000000;
const bigNumber = 123456789n;
const bigDecimal = 1234.12345;

console.log(inspect(thousand, { numericSeparator: true }));
// 1_000
console.log(inspect(million, { numericSeparator: true }));
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }));
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }));
// 1_234.123_45
copy

util.inspect() ist eine synchrone Methode, die für das Debugging vorgesehen ist. Ihre maximale Ausgabelänge beträgt etwa 128 MiB. Eingaben, die zu einer längeren Ausgabe führen, werden abgeschnitten.

Anpassen von util.inspect-Farben#

Die Farbausgabe (falls aktiviert) von util.inspect ist global über die Eigenschaften util.inspect.styles und util.inspect.colors anpassbar.

util.inspect.styles ist eine Map, die einen Stilnamen einer Farbe aus util.inspect.colors zuordnet.

Die Standardstile und die zugehörigen Farben sind:

• bigint: yellow
• boolean: yellow
• date: magenta
• module: underline
• name: (keine Formatierung)
• null: bold
• number: yellow
• regexp: Eine Methode, die Zeichenklassen, Gruppen, Assertionen und andere Teile für eine verbesserte Lesbarkeit färbt. Um die Färbung anzupassen, ändern Sie die colors-Eigenschaft. Sie ist standardmäßig auf ['red', 'green', 'yellow', 'cyan', 'magenta'] gesetzt und kann nach Bedarf angepasst werden. Das Array wird je nach "Tiefe" wiederholt durchlaufen.
• special: cyan (z. B. Proxies)
• string: green
• symbol: green
• undefined: grey

Die Farbdarstellung verwendet ANSI-Steuercodes, die möglicherweise nicht auf allen Terminals unterstützt werden. Überprüfen Sie die Farbunterstützung mit tty.hasColors().

Vordefinierte Steuercodes sind unten aufgeführt (gruppiert als "Modifikatoren", "Vordergrundfarben" und "Hintergrundfarben").

Komplexe benutzerdefinierte Färbung#

Es ist möglich, eine Methode als Stil zu definieren. Sie empfängt den in einen String umgewandelten Wert der Eingabe. Sie wird aufgerufen, wenn die Färbung aktiv ist und der Typ inspiziert wird.

Beispiel: util.inspect.styles.regexp(value)

• value <string> Die Zeichenfolgenrepräsentation des Eingabetyps.
• Rückgabe: <string> Die angepasste Repräsentation des object.

Modifikatoren#

Die Unterstützung für Modifikatoren variiert je nach Terminal. Sie werden größtenteils ignoriert, wenn sie nicht unterstützt werden.

• reset - Setzt alle (Farb-)Modifikatoren auf ihre Standardwerte zurück
• bold - Macht den Text fett
• italic - Macht den Text kursiv
• underline - Unterstreicht den Text
• strikethrough - Zieht eine horizontale Linie durch die Mitte des Textes (Alias: strikeThrough, crossedout, crossedOut)
• hidden - Druckt den Text, macht ihn aber unsichtbar (Alias: conceal)
• dim - Verringerte Farbintensität (Alias: faint)
• overlined - Macht den Text überstrichen
• blink - Blendet den Text in einem Intervall ein und aus
• inverse - Tauscht Vorder- und Hintergrundfarben (Alias: swapcolors, swapColors)
• doubleunderline - Macht den Text doppelt unterstrichen (Alias: doubleUnderline)
• framed - Zeichnet einen Rahmen um den Text

Vordergrundfarben#

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• gray (Alias: grey, blackBright)
• redBright
• greenBright
• yellowBright
• blueBright
• magentaBright
• cyanBright
• whiteBright

Hintergrundfarben#

• bgBlack
• bgRed
• bgGreen
• bgYellow
• bgBlue
• bgMagenta
• bgCyan
• bgWhite
• bgGray (Alias: bgGrey, bgBlackBright)
• bgRedBright
• bgGreenBright
• bgYellowBright
• bgBlueBright
• bgMagentaBright
• bgCyanBright
• bgWhiteBright

Benutzerdefinierte Inspektionsfunktionen für Objekte#

Objekte können auch ihre eigene [util.inspect.custom](depth, opts, inspect)-Funktion definieren, die util.inspect() aufruft und deren Ergebnis bei der Inspektion des Objekts verwendet.

import { inspect } from 'node:util';

class Box {
  constructor(value) {
    this.value = value;
  }

  [inspect.custom](depth, options, inspect) {
    if (depth < 0) {
      return options.stylize('[Box]', 'special');
    }

    const newOptions = Object.assign({}, options, {
      depth: options.depth === null ? null : options.depth - 1,
    });

    // Five space padding because that's the size of "Box< ".
    const padding = ' '.repeat(5);
    const inner = inspect(this.value, newOptions)
                  .replace(/\n/g, `\n${padding}`);
    return `${options.stylize('Box', 'special')}< ${inner} >`;
  }
}

const box = new Box(true);

console.log(inspect(box));
// "Box< true >"
const { inspect } = require('node:util');

class Box {
  constructor(value) {
    this.value = value;
  }

  [inspect.custom](depth, options, inspect) {
    if (depth < 0) {
      return options.stylize('[Box]', 'special');
    }

    const newOptions = Object.assign({}, options, {
      depth: options.depth === null ? null : options.depth - 1,
    });

    // Five space padding because that's the size of "Box< ".
    const padding = ' '.repeat(5);
    const inner = inspect(this.value, newOptions)
                  .replace(/\n/g, `\n${padding}`);
    return `${options.stylize('Box', 'special')}< ${inner} >`;
  }
}

const box = new Box(true);

console.log(inspect(box));
// "Box< true >"
copy

Benutzerdefinierte [util.inspect.custom](depth, opts, inspect)-Funktionen geben typischerweise eine Zeichenfolge zurück, können aber einen Wert eines beliebigen Typs zurückgeben, der dann von util.inspect() entsprechend formatiert wird.

import { inspect } from 'node:util';

const obj = { foo: 'this will not show up in the inspect() output' };
obj[inspect.custom] = (depth) => {
  return { bar: 'baz' };
};

console.log(inspect(obj));
// "{ bar: 'baz' }"
const { inspect } = require('node:util');

const obj = { foo: 'this will not show up in the inspect() output' };
obj[inspect.custom] = (depth) => {
  return { bar: 'baz' };
};

console.log(inspect(obj));
// "{ bar: 'baz' }"
copy

util.inspect.custom#

• Typ: <symbol>, das zur Deklaration benutzerdefinierter Inspektionsfunktionen verwendet werden kann.

Neben der Zugänglichkeit über util.inspect.custom ist dieses Symbol global registriert und kann in jeder Umgebung als Symbol.for('nodejs.util.inspect.custom') aufgerufen werden.

Dies ermöglicht eine portable Code-Schreibweise, sodass die benutzerdefinierte Inspektionsfunktion in einer Node.js-Umgebung verwendet und im Browser ignoriert wird. Die util.inspect()-Funktion selbst wird als drittes Argument an die benutzerdefinierte Inspektionsfunktion übergeben, um weitere Portabilität zu ermöglichen.

const customInspectSymbol = Symbol.for('nodejs.util.inspect.custom');

class Password {
  constructor(value) {
    this.value = value;
  }

  toString() {
    return 'xxxxxxxx';
  }

  [customInspectSymbol](depth, inspectOptions, inspect) {
    return `Password <${this.toString()}>`;
  }
}

const password = new Password('r0sebud');
console.log(password);
// Prints Password <xxxxxxxx>
copy

Siehe Benutzerdefinierte Inspektionsfunktionen für Objekte für weitere Details.

util.inspect.defaultOptions#

Der Wert defaultOptions ermöglicht die Anpassung der Standardoptionen, die von util.inspect verwendet werden. Dies ist nützlich für Funktionen wie console.log oder util.format, die implizit util.inspect aufrufen. Er sollte auf ein Objekt gesetzt werden, das eine oder mehrere gültige util.inspect()-Optionen enthält. Das direkte Setzen von Eigenschaften der Option wird ebenfalls unterstützt.

import { inspect } from 'node:util';
const arr = Array(156).fill(0);

console.log(arr); // Logs the truncated array
inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full array
const { inspect } = require('node:util');
const arr = Array(156).fill(0);

console.log(arr); // Logs the truncated array
inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full array
copy

util.isDeepStrictEqual(val1, val2[, options])#

• val1 <any>
• val2 <any>
• skipPrototype <boolean> Wenn true, werden der Prototyp- und Konstruktorvergleich während der tiefen strikten Gleichheitsprüfung übersprungen. Standard: false.
• Rückgabewert: <boolean>

Gibt true zurück, wenn eine tiefe strikte Gleichheit zwischen val1 und val2 besteht. Andernfalls wird false zurückgegeben.

Standardmäßig beinhaltet die tiefe strikte Gleichheit den Vergleich von Objektprototypen und Konstruktoren. Wenn skipPrototype true ist, können Objekte mit unterschiedlichen Prototypen oder Konstruktoren dennoch als gleich betrachtet werden, wenn ihre aufzählbaren Eigenschaften tief strikt gleich sind.

const util = require('node:util');

class Foo {
  constructor(a) {
    this.a = a;
  }
}

class Bar {
  constructor(a) {
    this.a = a;
  }
}

const foo = new Foo(1);
const bar = new Bar(1);

// Different constructors, same properties
console.log(util.isDeepStrictEqual(foo, bar));
// false

console.log(util.isDeepStrictEqual(foo, bar, true));
// true
copy

Siehe assert.deepStrictEqual() für weitere Informationen über tiefe strikte Gleichheit.

Klasse: util.MIMEType#

Eine Implementierung der MIMEType-Klasse.

In Übereinstimmung mit Browser-Konventionen werden alle Eigenschaften von MIMEType-Objekten als Getter und Setter auf dem Klassenprototyp implementiert, anstatt als Dateneigenschaften auf dem Objekt selbst.

Eine MIME-Zeichenfolge ist eine strukturierte Zeichenfolge, die mehrere aussagekräftige Komponenten enthält. Beim Parsen wird ein MIMEType-Objekt zurückgegeben, das Eigenschaften für jede dieser Komponenten enthält.

new MIMEType(input)#

• input <string> Die zu parsende MIME-Eingabe

Erstellt ein neues MIMEType-Objekt durch Parsen der input.

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/plain');
const { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/plain');
copy

Ein TypeError wird geworfen, wenn die input keine gültige MIME ist. Beachten Sie, dass versucht wird, die angegebenen Werte in Zeichenfolgen zu konvertieren. Zum Beispiel:

import { MIMEType } from 'node:util';
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plain
const { MIMEType } = require('node:util');
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plain
copy

mime.type#

• Typ: <string>

Ruft den Typ-Teil der MIME ab und setzt ihn.

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascript
const { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascript
copy

mime.subtype#

• Typ: <string>

Ruft den Subtyp-Teil der MIME ab und setzt ihn.

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascript
const { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascript
copy

mime.essence#

• Typ: <string>

Ruft die Essenz der MIME ab. Diese Eigenschaft ist schreibgeschützt. Verwenden Sie mime.type oder mime.subtype, um die MIME zu ändern.

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=value
const { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=value
copy

mime.params#

• Typ: <MIMEParams>

Ruft das MIMEParams-Objekt ab, das die Parameter der MIME repräsentiert. Diese Eigenschaft ist schreibgeschützt. Siehe die MIMEParams-Dokumentation für Details.

mime.toString()#

• Rückgabe: <string>

Die toString()-Methode auf dem MIMEType-Objekt gibt die serialisierte MIME zurück.

Aufgrund der Notwendigkeit der Standardkonformität erlaubt diese Methode Benutzern nicht, den Serialisierungsprozess der MIME anzupassen.

mime.toJSON()#

• Rückgabe: <string>

Alias für mime.toString().

Diese Methode wird automatisch aufgerufen, wenn ein MIMEType-Objekt mit JSON.stringify() serialisiert wird.

import { MIMEType } from 'node:util';

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]
const { MIMEType } = require('node:util');

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]
copy

Klasse: util.MIMEParams#

Die MIMEParams-API bietet Lese- und Schreibzugriff auf die Parameter eines MIMEType.

new MIMEParams()#

Erstellt ein neues MIMEParams-Objekt mit leeren Parametern.

import { MIMEParams } from 'node:util';

const myParams = new MIMEParams();
const { MIMEParams } = require('node:util');

const myParams = new MIMEParams();
copy

mimeParams.delete(name)#

• name <string>

Entfernt alle Name-Wert-Paare, deren Name name ist.

mimeParams.entries()#

• Gibt zurück: <Iterator>

Gibt einen Iterator über jedes der Name-Wert-Paare in den Parametern zurück. Jedes Element des Iterators ist ein JavaScript-Array. Das erste Element des Arrays ist der name, das zweite Element des Arrays ist der value.

mimeParams.get(name)#

• name <string>
• Gibt zurück: <string> | <null> Einen String oder null, wenn kein Schlüssel-Wert-Paar mit dem gegebenen name existiert.

Gibt den Wert des ersten Schlüssel-Wert-Paares zurück, dessen Schlüssel name ist. Wenn keine solchen Paare vorhanden sind, wird null zurückgegeben.

mimeParams.has(name)#

• name <string>
• Rückgabewert: <boolean>

Gibt true zurück, wenn mindestens ein Name-Wert-Paar existiert, dessen Name name ist.

mimeParams.keys()#

• Gibt zurück: <Iterator>

Gibt einen Iterator über die Namen jedes Name-Wert-Paares zurück.

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   bar
const { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   bar
copy

mimeParams.set(name, value)#

• name <string>
• value <string>

Setzt den Wert im MIMEParams-Objekt, der mit name assoziiert ist, auf value. Wenn bereits Name-Wert-Paare vorhanden sind, deren Name name ist, wird der Wert des ersten solchen Paares auf value gesetzt.

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=0;bar=1');
params.set('foo', 'def');
params.set('baz', 'xyz');
console.log(params.toString());
// Prints: foo=def;bar=1;baz=xyz
const { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=0;bar=1');
params.set('foo', 'def');
params.set('baz', 'xyz');
console.log(params.toString());
// Prints: foo=def;bar=1;baz=xyz
copy

mimeParams.values()#

• Gibt zurück: <Iterator>

Gibt einen Iterator über die Werte jedes Name-Wert-Paares zurück.

mimeParams[Symbol.iterator]()#

• Gibt zurück: <Iterator>

Alias für mimeParams.entries().

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz baz
const { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz baz
copy

util.parseArgs([config])#

• config <Object> Wird verwendet, um Argumente zum Parsen bereitzustellen und den Parser zu konfigurieren. config unterstützt die folgenden Eigenschaften:

  • args <string[]> Array von Argument-Zeichenfolgen. Standard: process.argv, wobei execPath und filename entfernt wurden.
  • options <Object> Wird verwendet, um dem Parser bekannte Argumente zu beschreiben. Schlüssel von options sind die langen Namen der Optionen, und Werte sind ein <Object>, das die folgenden Eigenschaften akzeptiert:
    • type <string> Typ des Arguments, das entweder boolean oder string sein muss.
    • multiple <boolean> Ob diese Option mehrfach angegeben werden kann. Wenn true, werden alle Werte in einem Array gesammelt. Wenn false, gewinnt der letzte Wert für die Option. Standard: false.
    • short <string> Ein einstelliger Alias für die Option.
    • default <string> | <boolean> | <string[]> | <boolean[]> Der Wert, der der Option zugewiesen werden soll, wenn sie in den zu parsenden Argumenten nicht erscheint. Der Wert muss mit dem Typ übereinstimmen, der durch die type-Eigenschaft angegeben ist. Wenn multiple true ist, muss es ein Array sein. Es wird kein Standardwert angewendet, wenn die Option in den zu parsenden Argumenten erscheint, selbst wenn der angegebene Wert falsy ist.
  • strict <boolean> Soll ein Fehler geworfen werden, wenn unbekannte Argumente gefunden werden oder wenn Argumente übergeben werden, die nicht mit dem in options konfigurierten type übereinstimmen? Standard: true.
  • allowPositionals <boolean> Ob dieser Befehl positionelle Argumente akzeptiert. Standard: false, wenn strict true ist, ansonsten true.
  • allowNegative <boolean> Wenn true, erlaubt es, boolesche Optionen explizit auf false zu setzen, indem der Optionsname mit --no- präfigiert wird. Standard: false.
  • tokens <boolean> Gibt die geparsten Tokens zurück. Dies ist nützlich, um das integrierte Verhalten zu erweitern, von der Hinzufügung zusätzlicher Prüfungen bis hin zur Neuverarbeitung der Tokens auf unterschiedliche Weise. Standard: false.

• Rückgabe: <Object> Die geparsten Befehlszeilenargumente

  • values <Object> Eine Zuordnung von geparsten Optionsnamen mit ihren <string>- oder <boolean>-Werten.
  • positionals <string[]> Positionelle Argumente.
  • tokens <Object[]> | <undefined> Siehe Abschnitt parseArgs tokens. Nur zurückgegeben, wenn config tokens: true enthält.

Bietet eine API auf höherer Ebene für das Parsen von Befehlszeilenargumenten als die direkte Interaktion mit process.argv. Nimmt eine Spezifikation für die erwarteten Argumente entgegen und gibt ein strukturiertes Objekt mit den geparsten Optionen und Positionals zurück.

import { parseArgs } from 'node:util';
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []
const { parseArgs } = require('node:util');
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []
copy

parseArgs tokens#

Detaillierte Parse-Informationen sind verfügbar, um benutzerdefinierte Verhalten durch Angabe von tokens: true in der Konfiguration hinzuzufügen. Die zurückgegebenen Tokens haben Eigenschaften, die Folgendes beschreiben:

• Alle Tokens
  • kind <string> Einer der Werte 'option', 'positional' oder 'option-terminator'.
  • index <number> Index des Elements in args, das das Token enthält. Das Quellargument für ein Token ist also args[token.index].
• Option-Tokens
  • name <string> Langer Name der Option.
  • rawName <string> Wie die Option in args verwendet wurde, z. B. -f oder --foo.
  • value <string> | <undefined> Optionswert, der in args angegeben wurde. Undefiniert für boolesche Optionen.
  • inlineValue <boolean> | <undefined> Ob der Optionswert inline angegeben wurde, wie z. B. --foo=bar.
• Positionelle Tokens
  • value <string> Der Wert des positionellen Arguments in args (d. h. args[index]).
• Option-Terminator-Token

Die zurückgegebenen Tokens sind in der Reihenfolge ihres Auftretens in den Eingabe-args. Optionen, die mehr als einmal in args erscheinen, erzeugen ein Token für jede Verwendung. Kurze Optionsgruppen wie -xy erweitern sich zu einem Token für jede Option. Also erzeugt -xxx drei Tokens.

Um beispielsweise Unterstützung für eine negierte Option wie --no-color hinzuzufügen (die allowNegative unterstützt, wenn die Option vom Typ boolean ist), können die zurückgegebenen Tokens neu verarbeitet werden, um den für die negierte Option gespeicherten Wert zu ändern.

import { parseArgs } from 'node:util';

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });
const { parseArgs } = require('node:util');

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });
copy

Beispielnutzung, die negierte Optionen zeigt und wann eine Option auf mehrere Arten verwendet wird, wobei die letzte gewinnt.

$ node negate.js
{ logfile: 'default.log', color: undefined }
$ node negate.js --no-logfile --no-color
{ logfile: false, color: false }
$ node negate.js --logfile=test.log --color
{ logfile: 'test.log', color: true }
$ node negate.js --no-logfile --logfile=test.log --color --no-color
{ logfile: 'test.log', color: false }
copy

util.parseEnv(content)#

• content <string>

Der Rohinhalt einer .env-Datei.

• Rückgabewert: <Object>

Gegeben eine Beispiel-.env-Datei:

const { parseEnv } = require('node:util');

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }
import { parseEnv } from 'node:util';

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }
copy

util.promisify(original)#

• original <Function>
• Rückgabe: <Function>

Nimmt eine Funktion, die dem üblichen Error-First-Callback-Stil folgt, d. h. sie akzeptiert ein (err, value) => ...-Callback als letztes Argument, und gibt eine Version zurück, die Promises zurückgibt.

import { promisify } from 'node:util';
import { stat } from 'node:fs';

const promisifiedStat = promisify(stat);
promisifiedStat('.').then((stats) => {
  // Do something with `stats`
}).catch((error) => {
  // Handle the error.
});
const { promisify } = require('node:util');
const { stat } = require('node:fs');

const promisifiedStat = promisify(stat);
promisifiedStat('.').then((stats) => {
  // Do something with `stats`
}).catch((error) => {
  // Handle the error.
});
copy

Oder äquivalent unter Verwendung von async functions:

import { promisify } from 'node:util';
import { stat } from 'node:fs';

const promisifiedStat = promisify(stat);

async function callStat() {
  const stats = await promisifiedStat('.');
  console.log(`This directory is owned by ${stats.uid}`);
}

callStat();
const { promisify } = require('node:util');
const { stat } = require('node:fs');

const promisifiedStat = promisify(stat);

async function callStat() {
  const stats = await promisifiedStat('.');
  console.log(`This directory is owned by ${stats.uid}`);
}

callStat();
copy

Wenn eine original[util.promisify.custom]-Eigenschaft vorhanden ist, gibt promisify deren Wert zurück, siehe Benutzerdefinierte promisifizierte Funktionen.

promisify() geht davon aus, dass original eine Funktion ist, die in allen Fällen einen Callback als letztes Argument akzeptiert. Wenn original keine Funktion ist, wirft promisify() einen Fehler. Wenn original eine Funktion ist, aber ihr letztes Argument kein Error-First-Callback ist, wird ihr dennoch ein Error-First-Callback als letztes Argument übergeben.

Die Verwendung von promisify() auf Klassenmethoden oder anderen Methoden, die this verwenden, funktioniert möglicherweise nicht wie erwartet, sofern sie nicht speziell behandelt wird.

import { promisify } from 'node:util';

class Foo {
  constructor() {
    this.a = 42;
  }

  bar(callback) {
    callback(null, this.a);
  }
}

const foo = new Foo();

const naiveBar = promisify(foo.bar);
// TypeError: Cannot read properties of undefined (reading 'a')
// naiveBar().then(a => console.log(a));

naiveBar.call(foo).then((a) => console.log(a)); // '42'

const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); // '42'
const { promisify } = require('node:util');

class Foo {
  constructor() {
    this.a = 42;
  }

  bar(callback) {
    callback(null, this.a);
  }
}

const foo = new Foo();

const naiveBar = promisify(foo.bar);
// TypeError: Cannot read properties of undefined (reading 'a')
// naiveBar().then(a => console.log(a));

naiveBar.call(foo).then((a) => console.log(a)); // '42'

const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); // '42'
copy

Benutzerdefinierte promisifizierte Funktionen#

Unter Verwendung des util.promisify.custom-Symbols kann man den Rückgabewert von util.promisify() überschreiben.

import { promisify } from 'node:util';

function doSomething(foo, callback) {
  // ...
}

doSomething[promisify.custom] = (foo) => {
  return getPromiseSomehow();
};

const promisified = promisify(doSomething);
console.log(promisified === doSomething[promisify.custom]);
// prints 'true'
const { promisify } = require('node:util');

function doSomething(foo, callback) {
  // ...
}

doSomething[promisify.custom] = (foo) => {
  return getPromiseSomehow();
};

const promisified = promisify(doSomething);
console.log(promisified === doSomething[promisify.custom]);
// prints 'true'
copy