Skip to content

Util

[Stable: 2 - Stable]

Stable: 2 Stabilität: 2 - Stabil

Quellcode: lib/util.js

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

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

util.callbackify(original)

Hinzugefügt in: v8.2.0

Nimmt eine async-Funktion (oder eine Funktion, die ein Promise zurückgibt) und gibt eine Funktion zurück, die dem Fehler-zuerst-Callback-Stil folgt, d.h. einen (err, value) => ...-Callback als letztes Argument nimmt. Im Callback ist das erste Argument der Ablehnungsgrund (oder null, wenn das Promise aufgelöst wurde), und das zweite Argument ist der aufgelöste Wert.

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

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

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

Gibt aus:

text
hello world

Der Callback wird asynchron ausgeführt und hat eine eingeschränkte Stack-Trace. Wenn der Callback eine Exception wirft, sendet der Prozess ein ['uncaughtException']-Ereignis(/api/process#event-uncaughtexception), und wenn es nicht behandelt wird, wird das Programm beendet.

Da null als erstes Argument eines Callbacks eine besondere Bedeutung hat, wird, wenn eine umschlossene Funktion ein Promise mit einem Falsy-Wert als Grund ablehnt, der Wert in ein Error mit dem ursprünglichen Wert in einem Feld namens reason gespeichert.

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

callbackFunction((err, ret) => {
  // Wenn das Promise mit `null` abgelehnt wurde, wird es mit einem Error umschlossen und
  // der ursprüngliche Wert in `reason` gespeichert.
  err && Object.hasOwn(err, 'reason') && err.reason === null // true
})

util.debuglog(section[, callback])

Hinzugefügt in: v0.11.3

  • section <string> Eine Zeichenkette, die den Teil der Anwendung identifiziert, für den die debuglog-Funktion erstellt wird.
  • callback <Funktion> Ein Callback, der beim ersten Aufruf der Protokollierungsfunktion mit einem Funktionsargument aufgerufen wird, das eine optimiertere Protokollierungsfunktion ist.
  • Gibt zurück: <Funktion> Die Protokollierungsfunktion

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

js
const util = require('node:util')
const debuglog = util.debuglog('foo')

debuglog('Hallo von foo [%d]', 123)

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

bash
FOO 3245: Hallo von foo [123]

wobei 3245 die Prozess-ID ist. Wenn es nicht mit dieser gesetzten Umgebungsvariable ausgeführt wird, wird nichts ausgegeben.

Der section unterstützt auch Wildcards:

js
const util = require('node:util')
const debuglog = util.debuglog('foo-bar')

debuglog('Hallo, es ist foo-bar [%d]', 2333)

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

bash
FOO-BAR 3257: Hallo, es ist foo-bar [2333]

In der Umgebungsvariable NODE_DEBUG können mehrere, durch Komma getrennte section-Namen angegeben werden: NODE_DEBUG=fs,net,tls.

Das optionale Argument callback kann verwendet werden, um die Protokollierungsfunktion durch eine andere Funktion zu ersetzen, die keine Initialisierung oder unnötige Umhüllung hat.

js
const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
  // Ersetzen durch eine Protokollierungsfunktion, die optimiert
  // die Prüfung, ob der Abschnitt aktiviert ist, entfernt
  debuglog = debug
})

debuglog().enabled

Hinzugefügt in: v14.9.0

Der Getter util.debuglog().enabled wird verwendet, um einen Test zu erstellen, der in Bedingungen basierend auf der Existenz der Umgebungsvariablen NODE_DEBUG verwendet werden kann. Wenn der section-Name im Wert dieser Umgebungsvariablen vorkommt, ist der zurückgegebene Wert true. Andernfalls ist der zurückgegebene Wert false.

js
const util = require('node:util')
const enabled = util.debuglog('foo').enabled
if (enabled) {
  console.log('hallo von foo [%d]', 123)
}

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

bash
hallo von foo [123]

util.debug(section)

Hinzugefügt in: v14.9.0

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

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

[Verlauf]

VersionÄnderungen
v10.0.0Veraltungswarnungen werden nur einmal für jeden Code ausgegeben.
v0.8.0Hinzugefügt in: v0.8.0
  • fn <Funktion> Die Funktion, die als veraltet markiert wird.
  • msg <string> Eine Warnmeldung, die angezeigt wird, wenn die veraltete Funktion aufgerufen wird.
  • code <string> Ein Veraltungscode. Eine Liste der Codes finden Sie in der Liste der veralteten APIs.
  • Gibt zurück: <Funktion> Die veraltete Funktion, die umhüllt ist, um eine Warnung auszugeben.

Die Methode util.deprecate() umhüllt fn (was eine Funktion oder Klasse sein kann) auf eine Weise, dass sie als veraltet markiert wird.

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

exports.obsoleteFunction = util.deprecate(() => {
  // Hier etwas tun.
}, 'obsoleteFunction() ist veraltet. Verwenden Sie stattdessen newShinyFunction().')

Wenn util.deprecate() aufgerufen wird, gibt es eine Funktion zurück, die ein DeprecationWarning mit dem Ereignis 'warning' ausgibt. Die Warnung wird ausgegeben und das erste Mal, wenn die zurückgegebene Funktion aufgerufen wird, auf stderr gedruckt. Nachdem die Warnung ausgegeben wurde, wird die umhüllte Funktion aufgerufen, ohne eine Warnung auszugeben.

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

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

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001')
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001')
fn1() // Gibt eine Veraltungswarnung mit dem Code DEP0001 aus
fn2() // Gibt keine Veraltungswarnung aus, da sie denselben Code hat

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

Wenn die Befehlszeilenflags --trace-deprecation oder --trace-warnings gesetzt sind oder die Eigenschaft process.traceDeprecation auf true gesetzt ist, werden eine Warnung und ein Stack-Trace das erste Mal, wenn die veraltete Funktion aufgerufen wird, auf stderr gedruckt.

Wenn das Befehlszeilenflag --throw-deprecation gesetzt ist oder die Eigenschaft process.throwDeprecation auf true gesetzt ist, wird eine Ausnahme ausgelöst, wenn die veraltete Funktion aufgerufen wird.

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

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

[Historie]

VersionÄnderungen
v12.11.0Der %c-Bezeichner wird jetzt ignoriert.
v12.0.0Das format-Argument wird jetzt nur als solches betrachtet, wenn es tatsächlich Formatbezeichner enthält.
v12.0.0Wenn das format-Argument keine Formatzeichenkette ist, hängt die Formatierung der Ausgabestring nicht mehr vom Typ des ersten Arguments ab. Diese Änderung entfernt zuvor vorhandene Anführungszeichen von Strings, die ausgegeben wurden, wenn das erste Argument kein String war.
v11.4.0Die %d-, %f- und %i-Bezeichner unterstützen jetzt Symbole korrekt.
v11.4.0Die Tiefe des %o-Bezeichners hat wieder eine Standardtiefe von 4.
v11.0.0Die depth-Option des %o-Bezeichners wird jetzt auf die Standardtiefe zurückgreifen.
v10.12.0Die %d- und %i-Bezeichner unterstützen jetzt BigInt.
v8.4.0Die %o- und %O-Bezeichner werden jetzt unterstützt.
v0.5.3Hinzugefügt in: v0.5.3
  • format <string> Eine printf-ähnliche Formatzeichenkette.

Die Methode util.format() gibt eine formatierte Zeichenkette zurück, wobei das erste Argument als printf-ähnliche Formatzeichenkette verwendet wird, die null oder mehr Formatbezeichner enthalten kann. Jeder Bezeichner wird durch den konvertierten Wert des entsprechenden Arguments ersetzt. Unterstützte Bezeichner 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 keine benutzerdefinierte toString-Funktion haben, werden mit util.inspect() mit den Optionen { depth: 0, colors: false, compact: 3 } untersucht.
  • %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. Wird durch den String '[Circular]' ersetzt, wenn das Argument zirkuläre Referenzen enthält.
  • %o: Object. Eine Stringdarstellung 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 Stringdarstellung 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 Bezeichner wird ignoriert und überspringt jegliches übergebenes CSS.
  • %%: einzelnes Prozentzeichen ('%'). Dies verbraucht kein Argument.
  • Gibt zurück: <string> Die formatierte Zeichenkette

Wenn ein Bezeichner kein entsprechendes Argument hat, wird er nicht ersetzt:

js
util.format('%s:%s', 'foo')
// Gibt zurück: 'foo:%s'

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

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

js
util.format('%s:%s', 'foo', 'bar', 'baz')
// Gibt zurück: 'foo:bar baz'

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

js
util.format(1, 2, 3)
// Gibt zurück: '1 2 3'

Wenn nur ein Argument an util.format() übergeben wird, wird es unverändert ohne Formatierung zurückgegeben:

js
util.format('%% %s')
// Gibt zurück: '%% %s'

util.format() ist eine synchrone Methode, die als Debugging-Tool gedacht ist. Einige Eingabewerte können einen erheblichen Leistungsaufwand verursachen, der die Ereignisschleife blockieren kann. Verwenden Sie diese Funktion mit Vorsicht und niemals in einem kritischen Codepfad.

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

Hinzugefügt in: v10.0.0

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

js
util.formatWithOptions({ colors: true }, 'Siehe Objekt %O', { foo: 42 })
// Gibt 'Siehe Objekt { foo: 42 }' zurück, wobei `42` als Zahl farbig
// dargestellt wird, wenn sie auf einem Terminal ausgegeben wird.

util.getCallSites(frameCountOrOptions, [options])

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.1 - Aktive Entwicklung

[Verlauf]

VersionÄnderungen
v23.3.0Die API wird von util.getCallSite in util.getCallSites() umbenannt.
v22.9.0Hinzugefügt in: v22.9.0
  • frameCount <number> 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 Stacktrace aus der Source-Map. Standardmäßig mit dem Flag --enable-source-maps aktiviert.
  • Gibt zurück: <Object[]> Ein Array von Call-Site-Objekten

    • functionName <string> Gibt den Namen der Funktion zurück, die dieser Call-Site zugeordnet ist.
    • scriptName <string> Gibt den Namen der Ressource zurück, die das Skript für die Funktion für diese Call-Site enthält.
    • lineNumber <number> Gibt die Nummer, beginnend mit 1, der Zeile für den zugehörigen Funktionsaufruf zurück.
    • column <number> Gibt den 1-basierten Spaltenoffset in der Zeile für den zugehörigen Funktionsaufruf zurück.

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

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

function exampleFunction() {
  const callSites = util.getCallSites()

  console.log('Call Sites:')
  callSites.forEach((callSite, index) => {
    console.log(`CallSite ${index + 1}:`)
    console.log(`Funktionsname: ${callSite.functionName}`)
    console.log(`Skriptname: ${callSite.scriptName}`)
    console.log(`Zeilennummer: ${callSite.lineNumber}`)
    console.log(`Spaltennummer: ${callSite.column}`)
  })
  // CallSite 1:
  // Funktionsname: exampleFunction
  // Skriptname: /home/example.js
  // Zeilennummer: 5
  // Spaltennummer: 26

  // CallSite 2:
  // Funktionsname: anotherFunction
  // Skriptname: /home/example.js
  // Zeilennummer: 22
  // Spaltennummer: 3

  // ...
}

// Eine Funktion, um eine weitere Stackebene zu simulieren
function anotherFunction() {
  exampleFunction()
}

anotherFunction()

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, ist der ursprüngliche Speicherort derselbe wie der aktuelle Speicherort. Wenn das Flag --enable-source-maps aktiviert ist, z. B. bei Verwendung von --experimental-transform-types, ist sourceMap standardmäßig true.

ts
import util from 'node:util'

interface Foo {
  foo: string
}

const callSites = util.getCallSites({ sourceMap: true })

// Mit SourceMap:
// Funktionsname: ''
// Skriptname: example.js
// Zeilennummer: 7
// Spaltennummer: 26

// Ohne SourceMap:
// Funktionsname: ''
// Skriptname: example.js
// Zeilennummer: 2
// Spaltennummer: 26

util.getSystemErrorName(err)

Hinzugefügt in: v9.7.0

Gibt den Stringnamen für einen numerischen Fehlercode zurück, der von einer Node.js-API stammt. Die Zuordnung zwischen Fehlercodes und Fehlernamen ist plattformabhängig. Siehe Allgemeine Systemfehler für die Namen allgemeiner Fehler.

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

util.getSystemErrorMap()

Hinzugefügt in: v16.0.0, v14.17.0

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 Allgemeine Systemfehler für die Namen allgemeiner Fehler.

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

util.getSystemErrorMessage(err)

Hinzugefügt in: v23.1.0

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

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

util.inherits(constructor, superConstructor)

[Verlauf]

VersionÄnderungen
v5.0.0Der constructor-Parameter kann sich jetzt auf eine ES6-Klasse beziehen.
v0.3.0Hinzugefügt in: v0.3.0

[Stabil: 3 - Legacy]

Stabil: 3 Stabilität: 3 - Legacy: Verwenden Sie stattdessen die ES2015-Klassensyntax und das extends-Schlüsselwort.

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

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

Dies fügt hauptsächlich einige Eingabevalidierungen zusätzlich zu Object.setPrototypeOf(constructor.prototype, superConstructor.prototype) hinzu. Als zusätzliche Bequemlichkeit ist superConstructor über die Eigenschaft constructor.super_ zugänglich.

js
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!"

ES6-Beispiel mit class und extends:

js
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')

util.inspect(object[, options])

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

[Verlauf]

VersionÄnderungen
v16.18.0Unterstützung für maxArrayLength beim Untersuchen von Set und Map hinzugefügt.
v17.3.0, v16.14.0Die Option numericSeparator wird jetzt unterstützt.
v13.0.0Zirkuläre Referenzen enthalten jetzt eine Markierung für die Referenz.
v14.6.0, v12.19.0Wenn object aus einem anderen vm.Context stammt, empfängt eine benutzerdefinierte Inspektionsfunktion dafür keine kontextspezifischen Argumente mehr.
v13.13.0, v12.17.0Die Option maxStringLength wird jetzt unterstützt.
v13.5.0, v12.16.0Benutzerdefinierte Prototyp-Eigenschaften werden untersucht, falls showHidden true ist.
v12.0.0Der Standardwert der Option compact wurde auf 3 geändert und der Standardwert der Option breakLength wurde auf 80 geändert.
v12.0.0Interne Eigenschaften erscheinen nicht mehr im Kontextargument einer benutzerdefinierten Inspektionsfunktion.
v11.11.0Die Option compact akzeptiert Zahlen für einen neuen Ausgabemodus.
v11.7.0ArrayBuffers zeigen jetzt auch ihren binären Inhalt an.
v11.5.0Die Option getters wird jetzt unterstützt.
v11.4.0Der Standardwert für depth wurde wieder auf 2 geändert.
v11.0.0Der Standardwert für depth wurde auf 20 geändert.
v11.0.0Die Inspektionsausgabe ist jetzt auf etwa 128 MiB begrenzt. Daten über dieser Größe werden nicht vollständig inspiziert.
v10.12.0Die Option sorted wird jetzt unterstützt.
v10.6.0Die Inspektion von verketteten Listen und ähnlichen Objekten ist jetzt bis zur maximalen Aufrufstapelgröße möglich.
v10.0.0Die Einträge von WeakMap und WeakSet können jetzt ebenfalls inspiziert werden.
v9.9.0Die Option compact wird jetzt unterstützt.
v6.6.0Benutzerdefinierte Inspektionsfunktionen können jetzt this zurückgeben.
v6.3.0Die Option breakLength wird jetzt unterstützt.
v6.1.0Die Option maxArrayLength wird jetzt unterstützt; insbesondere werden lange Arrays standardmäßig abgeschnitten.
v6.1.0Die Option showProxy wird jetzt unterstützt.
v0.3.0Hinzugefügt in: v0.3.0
  • object <any> Ein beliebiger JavaScript-Primitiv oder ein Object.

  • options <Object>

    • showHidden <boolean> Wenn true, werden nicht aufzählbare Symbole und Eigenschaften von object in das formatierte Ergebnis aufgenommen. Einträge von WeakMap und WeakSet werden ebenfalls aufgenommen, ebenso wie benutzerdefinierte Prototyp-Eigenschaften (ausgenommen Methodeneigenschaften). Standard: false.
    • depth <number> Gibt die Anzahl der Rekursionen beim Formatieren von object an. Dies ist nützlich, um große Objekte zu untersuchen. Um bis zur maximalen Aufrufstapelgröß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, enthält die Proxy-Inspektion die target- und handler-Objekte. Standard: false.
    • maxArrayLength <integer> Gibt die maximale Anzahl von Elementen von Array, TypedArray, Map, Set, WeakMap und WeakSet an, die beim Formatieren aufgenommen werden sollen. Setzen Sie dies auf null oder Infinity, um alle Elemente anzuzeigen. Setzen Sie dies auf 0 oder einen negativen Wert, um keine Elemente anzuzeigen. Standard: 100.
    • maxStringLength <integer> Gibt die maximale Anzahl von Zeichen an, die beim Formatieren aufgenommen werden sollen. Setzen Sie dies auf null oder Infinity, um alle Elemente anzuzeigen. Setzen Sie dies auf 0 oder einen negativen Wert, um keine Zeichen anzuzeigen. Standard: 10000.
    • breakLength <integer> Die Länge, bei der Eingabewerte auf mehrere Zeilen aufgeteilt werden. Setzen Sie dies auf Infinity, um die Eingabe als einzelne Zeile zu formatieren (in Kombination mit compact, das auf true oder eine beliebige Zahl >= 1 gesetzt ist). Standard: 80.
    • compact <boolean> | <integer> Wenn dies auf false gesetzt ist, wird jeder Objektschlüssel in einer neuen Zeile angezeigt. Es wird bei neuen Zeilen in Text, der länger als breakLength ist, umgebrochen. Wenn es auf eine Zahl gesetzt ist, werden die n innersten Elemente auf einer einzigen Zeile zusammengefasst, solange alle Eigenschaften in breakLength passen. Kurze Array-Elemente werden ebenfalls zusammengefasst. Weitere Informationen finden Sie im folgenden Beispiel. Standard: 3.
    • sorted <boolean> | <Function> Wenn dies auf true oder eine Funktion gesetzt ist, werden alle Eigenschaften eines Objekts sowie Set- und Map-Einträge im resultierenden String sortiert. Wenn dies auf true gesetzt ist, wird die Standard-Sortierung verwendet. Wenn dies auf eine Funktion gesetzt ist, wird sie als Vergleichsfunktion verwendet.
    • getters <boolean> | <string> Wenn dies auf true gesetzt ist, werden Getter untersucht. Wenn dies auf 'get' gesetzt ist, werden nur Getter ohne einen entsprechenden Setter untersucht. Wenn dies auf 'set' gesetzt ist, werden nur Getter mit einem entsprechenden Setter untersucht. Dies kann je nach Getter-Funktion zu Seiteneffekten führen. Standard: false.
    • numericSeparator <boolean> Wenn dies auf true gesetzt ist, wird ein Unterstrich verwendet, um alle drei Ziffern in allen Bigints und Zahlen zu trennen. Standard: false.
  • Rückgabe: <string> Die Darstellung von object.

Die Methode util.inspect() gibt eine String-Darstellung von object zurück, die für das Debuggen gedacht ist. Die Ausgabe von util.inspect kann sich jederzeit ändern und sollte nicht programmatisch verwendet werden. Es können zusätzliche options übergeben werden, die das Ergebnis verändern. util.inspect() verwendet den Namen des Konstruktors und/oder @@toStringTag, um ein identifizierbares Tag für einen inspizierten Wert zu erstellen.

js
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] {}'

Zirkuläre Referenzen verweisen mit einem Referenzindex auf ihren Anker:

js
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] }
// }

Das folgende Beispiel untersucht alle Eigenschaften des util-Objekts:

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

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

Das folgende Beispiel verdeutlicht die Auswirkung der Option compact:

js
const util = 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(util.inspect(o, { compact: true, depth: 5, breakLength: 80 }))

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

// Wenn `compact` auf false oder eine ganze Zahl gesetzt wird, wird eine lesefreundlichere Ausgabe erzeugt.
console.log(util.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'
//   }
// }

// Wenn `breakLength` auf z. B. 150 gesetzt wird, wird der Text "Lorem ipsum" in einer
// einzigen Zeile ausgegeben.

Die Option showHidden ermöglicht das Untersuchen von WeakMap- und WeakSet-Einträgen. Wenn mehr Einträge als maxArrayLength vorhanden sind, gibt es keine Garantie, welche Einträge angezeigt werden. Das bedeutet, dass das zweimalige Abrufen derselben WeakSet-Einträge zu unterschiedlichen Ausgaben führen kann. Darüber hinaus können Einträge ohne verbleibende starke Referenzen jederzeit durch die Garbage Collection entfernt werden.

js
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 } }

Die Option sorted stellt sicher, dass die Reihenfolge des Einfügens von Eigenschaften eines Objekts das Ergebnis von util.inspect() nicht beeinflusst.

js
const { inspect } = require('node:util')
const assert = require('node:assert')

const o1 = {
  b: [2, 3, 1],
  a: '`a` kommt vor `b`',
  c: new Set([2, 3, 1]),
}
console.log(inspect(o1, { sorted: true }))
// { a: '`a` kommt vor `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` kommt vor `b`' }

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

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

js
const { inspect } = require('node:util')

const thousand = 1_000
const million = 1_000_000
const bigNumber = 123_456_789n
const bigDecimal = 1_234.123_45

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

util.inspect() ist eine synchrone Methode, die zum Debuggen gedacht ist. Die maximale Ausgabelänge beträgt ca. 128 MiB. Eingaben, die zu einer längeren Ausgabe führen, werden abgeschnitten.

Anpassen der 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 Zuordnung, die einen Stilnamen mit einer Farbe aus util.inspect.colors verknüpft.

Die Standardstile und zugehörigen Farben sind:

  • bigint: yellow
  • boolean: yellow
  • date: magenta
  • module: underline
  • name: (keine Formatierung)
  • null: bold
  • number: yellow
  • regexp: red
  • special: cyan (z. B. Proxies)
  • string: green
  • symbol: green
  • undefined: grey

Die Farbgestaltung verwendet ANSI-Steuercodes, die möglicherweise nicht von allen Terminals unterstützt werden. Um die Farbsupport zu überprüfen, verwenden Sie tty.hasColors().

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

Modifizierer

Die Unterstützung von Modifizierern ist in verschiedenen Terminals unterschiedlich. Sie werden meist ignoriert, wenn sie nicht unterstützt werden.

  • reset - Setzt alle (Farb-)Modifizierer auf ihre Standardwerte zurück
  • bold - Macht Text fett
  • italic - Macht Text kursiv
  • underline - Macht Text unterstrichen
  • strikethrough - Zieht eine horizontale Linie durch die Mitte des Textes (Alias: strikeThrough, crossedout, crossedOut)
  • hidden - Gibt den Text aus, macht ihn aber unsichtbar (Alias: conceal)
  • dim - Verringerte Farbintensität (Alias: faint)
  • overlined - Macht Text überstrichen
  • blink - Verbirgt und zeigt den Text in einem Intervall
  • inverse - Tauscht Vorder- und Hintergrundfarben (Alias: swapcolors, swapColors)
  • doubleunderline - Macht 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

[Historie]

VersionÄnderungen
v17.3.0, v16.14.0Das Argument inspect wurde für mehr Interoperabilität hinzugefügt.
v0.1.97Hinzugefügt in: v0.1.97

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

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

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

  [util.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,
    })

    // Fünf Leerzeichen Padding, weil das die Größe von "Box< " ist.
    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)

util.inspect(box)
// Gibt zurück: "Box< true >"

Benutzerdefinierte [util.inspect.custom](depth, opts, inspect) Funktionen geben typischerweise einen String zurück, können aber einen Wert von jedem Typ zurückgeben, der von util.inspect() entsprechend formatiert wird.

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

const obj = { foo: 'dies wird in der inspect() Ausgabe nicht angezeigt' }
obj[util.inspect.custom] = depth => {
  return { bar: 'baz' }
}

util.inspect(obj)
// Gibt zurück: "{ bar: 'baz' }"

util.inspect.custom

[Historie]

VersionÄnderungen
v10.12.0Dies ist nun als gemeinsames Symbol definiert.
v6.6.0Hinzugefügt in: v6.6.0
  • <symbol>, das verwendet werden kann, um benutzerdefinierte Inspektionsfunktionen zu deklarieren.

Zusätzlich dazu, dass dieses Symbol über util.inspect.custom zugänglich ist, ist es global registriert und kann in jeder Umgebung als Symbol.for('nodejs.util.inspect.custom') aufgerufen werden.

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

js
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)
// Gibt Password <xxxxxxxx> aus

Weitere Informationen finden Sie unter Benutzerdefinierte Inspektionsfunktionen für Objekte.

util.inspect.defaultOptions

Hinzugefügt in: v6.4.0

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 muss auf ein Objekt gesetzt werden, das eine oder mehrere gültige util.inspect()-Optionen enthält. Das direkte Setzen von Optionen-Eigenschaften wird ebenfalls unterstützt.

js
const util = require('node:util')
const arr = Array(101).fill(0)

console.log(arr) // Protokolliert das gekürzte Array
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // Protokolliert das vollständige Array

util.isDeepStrictEqual(val1, val2)

Hinzugefügt in: v9.0.0

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

Weitere Informationen zur tiefen strikten Gleichheit finden Sie unter assert.deepStrictEqual().

Klasse: util.MIMEType

Hinzugefügt in: v19.1.0, v18.13.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Eine Implementierung der MIMEType-Klasse.

In Übereinstimmung mit den Browserkonventionen werden alle Eigenschaften von MIMEType-Objekten als Getter und Setter auf dem Klassenprototyp implementiert und nicht als Dateneigenschaften auf dem Objekt selbst.

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

Konstruktor: new MIMEType(input)

  • input <string> Die zu parsenden Eingabe-MIME

Erstellt ein neues MIMEType-Objekt durch Parsen der input.

js
import { MIMEType } from 'node:util'

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

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

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

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

mime.type

Ruft den Typteil des MIME ab und legt ihn fest.

js
import { MIMEType } from 'node:util'

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

const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// Gibt aus: text
myMIME.type = 'application'
console.log(myMIME.type)
// Gibt aus: application
console.log(String(myMIME))
// Gibt aus: application/javascript

mime.subtype

Ruft den Subtyppteil des MIME ab und legt ihn fest.

js
import { MIMEType } from 'node:util'

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

const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// Gibt aus: ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// Gibt aus: javascript
console.log(String(myMIME))
// Gibt aus: text/javascript

mime.essence

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

js
import { MIMEType } from 'node:util'

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

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

mime.params

Ruft das MIMEParams-Objekt ab, das die Parameter des MIME darstellt. Diese Eigenschaft ist schreibgeschützt. Weitere Informationen finden Sie in der MIMEParams-Dokumentation.

mime.toString()

Die toString()-Methode des MIMEType-Objekts gibt den serialisierten MIME zurück.

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

mime.toJSON()

Alias für mime.toString().

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

js
import { MIMEType } from 'node:util'

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

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

Klasse: util.MIMEParams

Hinzugefügt in: v19.1.0, v18.13.0

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

Konstruktor: new MIMEParams()

Erstellt ein neues MIMEParams-Objekt mit leeren Parametern.

js
import { MIMEParams } from 'node:util'

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

const myParams = new MIMEParams()

mimeParams.delete(name)

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

mimeParams.entries()

Gibt einen Iterator über jedes Name-Wert-Paar 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 Wert.

mimeParams.get(name)

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

Gibt den Wert des ersten Name-Wert-Paares zurück, dessen Name name ist. Wenn es keine solchen Paare gibt, wird null zurückgegeben.

mimeParams.has(name)

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

mimeParams.keys()

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

js
import { MIMEType } from 'node:util'

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

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

mimeParams.set(name, value)

Setzt den Wert im MIMEParams-Objekt, das mit name verknüpft ist, auf value. Wenn es bereits Name-Wert-Paare gibt, deren Namen name sind, setze den Wert des ersten solchen Paares auf value.

js
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())
// Gibt aus: foo=def;bar=1;baz=xyz
js
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())
// Gibt aus: foo=def;bar=1;baz=xyz

mimeParams.values()

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

mimeParams[@@iterator]()

Alias für mimeParams.entries().

js
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)
}
// Gibt aus:
//   foo bar
//   xyz baz
js
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)
}
// Gibt aus:
//   foo bar
//   xyz baz

util.parseArgs([config])

[Verlauf]

VersionÄnderungen
v22.4.0, v20.16.0Unterstützung für negative Optionen in der Eingabe config hinzugefügt.
v20.0.0Die API ist nicht mehr experimentell.
v18.11.0, v16.19.0Unterstützung für Standardwerte in der Eingabe config hinzugefügt.
v18.7.0, v16.17.0Unterstützung für die Rückgabe detaillierter Parsinformationen mithilfe von tokens in der Eingabe config und zurückgegebenen Eigenschaften hinzugefügt.
v18.3.0, v16.17.0Hinzugefügt in: v18.3.0, v16.17.0
  • config <Object> Wird verwendet, um Argumente für das Parsen bereitzustellen und den Parser zu konfigurieren. config unterstützt die folgenden Eigenschaften:
    • args <string[]> Array von Argument-Strings. Standard: process.argv mit execPath und filename entfernt.
    • options <Object> Wird verwendet, um Argumente zu beschreiben, die dem Parser bekannt sind. Die Schlüssel von options sind die langen Namen von Optionen und die Werte sind ein <Object>, das die folgenden Eigenschaften akzeptiert:
    • type <string> Typ des Arguments, der 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, sind die Werte für die Option Last-Wins. Standard: false.
    • short <string> Ein einzelnes Zeichen-Alias für die Option.
    • default <string> | <boolean> | <string[]> | <boolean[]> Der Standardoptionswert, wenn er nicht durch Argumente gesetzt wird. Er muss vom gleichen Typ wie die Eigenschaft type sein. Wenn multiple true ist, muss es ein Array sein.
    • strict <boolean> Soll ein Fehler ausgelöst werden, wenn unbekannte Argumente angetroffen werden oder wenn Argumente übergeben werden, die nicht mit dem in options konfigurierten type übereinstimmen? Standard: true.
    • allowPositionals <boolean> Ob dieser Befehl Positionsargumente akzeptiert. Standard: false, wenn strict true ist, andernfalls true.
    • allowNegative <boolean> Wenn true, erlaubt es, boolesche Optionen explizit auf false zu setzen, indem dem Optionsnamen --no- vorangestellt wird. Standard: false.
    • tokens <boolean> Gibt die geparsten Token zurück. Dies ist nützlich, um das integrierte Verhalten zu erweitern, von zusätzlichen Prüfungen bis hin zur erneuten Verarbeitung der Token auf verschiedene Arten. Standard: false.
  • Gibt zurück: <Object> Die geparsten Befehlszeilenargumente:

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 Positionsargumenten zurück.

js
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)
// Gibt aus: [Object: null prototype] { foo: true, bar: 'b' } []
js
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)
// Gibt aus: [Object: null prototype] { foo: true, bar: 'b' } []

parseArgs tokens

Detaillierte Parsing-Informationen stehen für das Hinzufügen von benutzerdefiniertem Verhalten zur Verfügung, indem tokens: true in der Konfiguration angegeben wird. Die zurückgegebenen Token haben Eigenschaften, die Folgendes beschreiben:

  • Alle Token

    • kind <string> Einer von '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].
  • Options-Token

    • name <string> Langer Name der Option.
    • rawName <string> Wie die Option in args verwendet wird, z. B. -f von --foo.
    • value <string> | <undefined> Optionswert, der in args angegeben ist. Nicht definiert für boolesche Optionen.
    • inlineValue <boolean> | <undefined> Ob der Optionswert inline angegeben wurde, z. B. --foo=bar.
  • Positionale Token

    • value <string> Der Wert des positionalen Arguments in args (d. h. args[index]).
  • Option-Terminator-Token

Die zurückgegebenen Token sind in der Reihenfolge, in der sie in den Eingabe-Args angetroffen werden. Optionen, die mehr als einmal in Args erscheinen, erzeugen für jede Verwendung ein Token. Kurze Optionsgruppen wie -xy werden zu einem Token für jede Option erweitert. So erzeugt -xxx drei Token.

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 Token erneut verarbeitet werden, um den Wert zu ändern, der für die negierte Option gespeichert ist.

js
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 })

// Die Options-Token erneut verarbeiten und die zurückgegebenen Werte überschreiben.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // foo:false für --no-foo speichern
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Wert erneut speichern, sodass der letzte gewinnt, wenn sowohl --foo als auch --no-foo.
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })
js
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 })

// Die Options-Token erneut verarbeiten und die zurückgegebenen Werte überschreiben.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // foo:false für --no-foo speichern
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Wert erneut speichern, sodass der letzte gewinnt, wenn sowohl --foo als auch --no-foo.
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })

Beispielhafte Verwendung, die negierte Optionen zeigt und wann eine Option auf mehrere Arten verwendet wird, dann gewinnt die letzte.

bash
$ 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 }

util.parseEnv(content)

[Stabil: 1 - Experimentell]

Stabil: 1 Stabil: 1.1 - Aktive Entwicklung

Hinzugefügt in: v21.7.0, v20.12.0

Der Rohinhalt einer .env-Datei.

Gegeben eine Beispiel .env-Datei:

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

parseEnv('HELLO=world\nHELLO=oh my\n')
// Gibt zurück: { HELLO: 'oh my' }
js
import { parseEnv } from 'node:util'

parseEnv('HELLO=world\nHELLO=oh my\n')
// Gibt zurück: { HELLO: 'oh my' }

util.promisify(original)

[Geschichte]

VersionÄnderungen
v20.8.0Das Aufrufen von promisify für eine Funktion, die eine Promise zurückgibt, ist veraltet.
v8.0.0Hinzugefügt in: v8.0.0

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

js
const util = require('node:util')
const fs = require('node:fs')

const stat = util.promisify(fs.stat)
stat('.')
  .then(stats => {
    // Tue etwas mit `stats`
  })
  .catch(error => {
    // Behandle den Fehler.
  })

Oder, äquivalent mit async functions:

js
const util = require('node:util')
const fs = require('node:fs')

const stat = util.promisify(fs.stat)

async function callStat() {
  const stats = await stat('.')
  console.log(`Dieses Verzeichnis gehört ${stats.uid}`)
}

callStat()

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

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

Die Verwendung von promisify() auf Klassenmethoden oder anderen Methoden, die this verwenden, funktioniert möglicherweise nicht wie erwartet, es sei denn, sie werden speziell behandelt:

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

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

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

const foo = new Foo()

const naiveBar = util.promisify(foo.bar)
// TypeError: Cannot read property 'a' of undefined
// 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'

Benutzerdefinierte promisifizierte Funktionen

Mit dem Symbol util.promisify.custom kann der Rückgabewert von util.promisify() überschrieben werden:

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

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

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

const promisified = util.promisify(doSomething)
console.log(promisified === doSomething[util.promisify.custom])
// gibt 'true' aus

Dies kann in Fällen nützlich sein, in denen die ursprüngliche Funktion nicht dem Standardformat entspricht, das eine Fehler-First-Callback-Funktion als letztes Argument verwendet.

Zum Beispiel mit einer Funktion, die (foo, onSuccessCallback, onErrorCallback) verwendet:

js
doSomething[util.promisify.custom] = foo => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject)
  })
}

Wenn promisify.custom definiert, aber keine Funktion ist, wirft promisify() einen Fehler.

util.promisify.custom

[Verlauf]

VersionÄnderungen
v13.12.0, v12.16.2Dies ist nun als gemeinsames Symbol definiert.
v8.0.0Hinzugefügt in: v8.0.0

Dieses Symbol ist nicht nur über util.promisify.custom zugänglich, sondern auch global registriert und kann in jeder Umgebung als Symbol.for('nodejs.util.promisify.custom') aufgerufen werden.

Zum Beispiel mit einer Funktion, die (foo, onSuccessCallback, onErrorCallback) verwendet:

js
const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom')

doSomething[kCustomPromisifiedSymbol] = foo => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject)
  })
}

util.stripVTControlCharacters(str)

Hinzugefügt in: v16.11.0

Gibt str zurück, wobei alle ANSI-Escape-Codes entfernt wurden.

js
console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'))
// Gibt "value" aus

util.styleText(format, text[, options])

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil.

[Verlauf]

VersionÄnderungen
v23.5.0styleText ist jetzt stabil.
v22.8.0, v20.18.0Berücksichtigt isTTY und Umgebungsvariablen wie NO_COLORS, NODE_DISABLE_COLORS und FORCE_COLOR.
v21.7.0, v20.12.0Hinzugefügt in: v21.7.0, v20.12.0
  • format <string> | <Array> Ein Textformat oder ein Array von Textformaten, die in util.inspect.colors definiert sind.
  • text <string> Der zu formatierende Text.
  • options <Object>
    • validateStream <boolean> Wenn true, wird stream geprüft, um festzustellen, ob es Farben verarbeiten kann. Standard: true.
    • stream <Stream> Ein Stream, der überprüft wird, ob er gefärbt werden kann. Standard: process.stdout.

Diese Funktion gibt einen formatierten Text unter Berücksichtigung des übergebenen format für die Ausgabe in einem Terminal zurück. Sie ist sich der Fähigkeiten des Terminals bewusst und verhält sich gemäß der Konfiguration, die über die Umgebungsvariablen NO_COLORS, NODE_DISABLE_COLORS und FORCE_COLOR festgelegt wurde.

js
import { styleText } from 'node:util'
import { stderr } from 'node:process'

const successMessage = styleText('green', 'Erfolg!')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  'Fehler! Fehler!',
  // Prüfen, ob process.stderr TTY hat
  { stream: stderr }
)
console.error(successMessage)
js
const { styleText } = require('node:util')
const { stderr } = require('node:process')

const successMessage = styleText('green', 'Erfolg!')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  'Fehler! Fehler!',
  // Prüfen, ob process.stderr TTY hat
  { stream: stderr }
)
console.error(successMessage)

util.inspect.colors bietet auch Textformate wie italic und underline an und Sie können beide kombinieren:

js
console.log(util.styleText(['underline', 'italic'], 'Meine kursive unterstrichene Nachricht'))

Wenn ein Array von Formaten übergeben wird, wird die Reihenfolge der angewendeten Formate von links nach rechts festgelegt, sodass der folgende Stil den vorherigen überschreiben kann.

js
console.log(
  util.styleText(['red', 'green'], 'text') // grün
)

Die vollständige Liste der Formate finden Sie unter Modifikatoren.

Klasse: util.TextDecoder

[Verlauf]

VersionÄnderungen
v11.0.0Die Klasse ist nun im globalen Objekt verfügbar.
v8.3.0Hinzugefügt in: v8.3.0

Eine Implementierung der WHATWG Encoding Standard TextDecoder API.

js
const decoder = new TextDecoder()
const u8arr = new Uint8Array([72, 101, 108, 108, 111])
console.log(decoder.decode(u8arr)) // Hello

Von WHATWG unterstützte Kodierungen

Gemäß dem WHATWG Encoding Standard sind die von der TextDecoder API unterstützten Kodierungen in den nachstehenden Tabellen aufgeführt. Für jede Kodierung können ein oder mehrere Aliase verwendet werden.

Verschiedene Node.js-Build-Konfigurationen unterstützen unterschiedliche Sätze von Kodierungen. (siehe Internationalisierung)

Standardmäßig unterstützte Kodierungen (mit vollständigen ICU-Daten)

KodierungAliase
'ibm866''866' , 'cp866' , 'csibm866'
'iso-8859-2''csisolatin2' , 'iso-ir-101' , 'iso8859-2' , 'iso88592' , 'iso_8859-2' , 'iso_8859-2:1987' , 'l2' , 'latin2'
'iso-8859-3''csisolatin3' , 'iso-ir-109' , 'iso8859-3' , 'iso88593' , 'iso_8859-3' , 'iso_8859-3:1988' , 'l3' , 'latin3'
'iso-8859-4''csisolatin4' , 'iso-ir-110' , 'iso8859-4' , 'iso88594' , 'iso_8859-4' , 'iso_8859-4:1988' , 'l4' , 'latin4'
'iso-8859-5''csisolatincyrillic' , 'cyrillic' , 'iso-ir-144' , 'iso8859-5' , 'iso88595' , 'iso_8859-5' , 'iso_8859-5:1988'
'iso-8859-6''arabic' , 'asmo-708' , 'csiso88596e' , 'csiso88596i' , 'csisolatinarabic' , 'ecma-114' , 'iso-8859-6-e' , 'iso-8859-6-i' , 'iso-ir-127' , 'iso8859-6' , 'iso88596' , 'iso_8859-6' , 'iso_8859-6:1987'
'iso-8859-7''csisolatingreek' , 'ecma-118' , 'elot_928' , 'greek' , 'greek8' , 'iso-ir-126' , 'iso8859-7' , 'iso88597' , 'iso_8859-7' , 'iso_8859-7:1987' , 'sun_eu_greek'
'iso-8859-8''csiso88598e' , 'csisolatinhebrew' , 'hebrew' , 'iso-8859-8-e' , 'iso-ir-138' , 'iso8859-8' , 'iso88598' , 'iso_8859-8' , 'iso_8859-8:1988' , 'visual'
'iso-8859-8-i''csiso88598i' , 'logical'
'iso-8859-10''csisolatin6' , 'iso-ir-157' , 'iso8859-10' , 'iso885910' , 'l6' , 'latin6'
'iso-8859-13''iso8859-13' , 'iso885913'
'iso-8859-14''iso8859-14' , 'iso885914'
'iso-8859-15''csisolatin9' , 'iso8859-15' , 'iso885915' , 'iso_8859-15' , 'l9'
'koi8-r''cskoi8r' , 'koi' , 'koi8' , 'koi8_r'
'koi8-u''koi8-ru'
'macintosh''csmacintosh' , 'mac' , 'x-mac-roman'
'windows-874''dos-874' , 'iso-8859-11' , 'iso8859-11' , 'iso885911' , 'tis-620'
'windows-1250''cp1250' , 'x-cp1250'
'windows-1251''cp1251' , 'x-cp1251'
'windows-1252''ansi_x3.4-1968' , 'ascii' , 'cp1252' , 'cp819' , 'csisolatin1' , 'ibm819' , 'iso-8859-1' , 'iso-ir-100' , 'iso8859-1' , 'iso88591' , 'iso_8859-1' , 'iso_8859-1:1987' , 'l1' , 'latin1' , 'us-ascii' , 'x-cp1252'
'windows-1253''cp1253' , 'x-cp1253'
'windows-1254''cp1254' , 'csisolatin5' , 'iso-8859-9' , 'iso-ir-148' , 'iso8859-9' , 'iso88599' , 'iso_8859-9' , 'iso_8859-9:1989' , 'l5' , 'latin5' , 'x-cp1254'
'windows-1255''cp1255' , 'x-cp1255'
'windows-1256''cp1256' , 'x-cp1256'
'windows-1257''cp1257' , 'x-cp1257'
'windows-1258''cp1258' , 'x-cp1258'
'x-mac-cyrillic''x-mac-ukrainian'
'gbk''chinese' , 'csgb2312' , 'csiso58gb231280' , 'gb2312' , 'gb_2312' , 'gb_2312-80' , 'iso-ir-58' , 'x-gbk'
'gb18030'
'big5''big5-hkscs' , 'cn-big5' , 'csbig5' , 'x-x-big5'
'euc-jp''cseucpkdfmtjapanese' , 'x-euc-jp'
'iso-2022-jp''csiso2022jp'
'shift_jis''csshiftjis' , 'ms932' , 'ms_kanji' , 'shift-jis' , 'sjis' , 'windows-31j' , 'x-sjis'
'euc-kr''cseuckr' , 'csksc56011987' , 'iso-ir-149' , 'korean' , 'ks_c_5601-1987' , 'ks_c_5601-1989' , 'ksc5601' , 'ksc_5601' , 'windows-949'

Kodierungen, die unterstützt werden, wenn Node.js mit der Option small-icu gebaut wird

KodierungAliase
'utf-8''unicode-1-1-utf-8' , 'utf8'
'utf-16le''utf-16'
'utf-16be'

Kodierungen, die unterstützt werden, wenn ICU deaktiviert ist

KodierungAliase
'utf-8''unicode-1-1-utf-8' , 'utf8'
'utf-16le''utf-16'

Die im WHATWG-Kodierungsstandard aufgeführte Kodierung 'iso-8859-16' wird nicht unterstützt.

new TextDecoder([encoding[, options]])

  • encoding <string> Identifiziert die encoding, die diese TextDecoder-Instanz unterstützt. Standard: 'utf-8'.
  • options <Object>
    • fatal <boolean> true, wenn Dekodierungsfehler schwerwiegend sind. Diese Option wird nicht unterstützt, wenn ICU deaktiviert ist (siehe Internationalisierung). Standard: false.
    • ignoreBOM <boolean> Wenn true, enthält der TextDecoder die Byte-Order-Markierung im dekodierten Ergebnis. Wenn false, wird die Byte-Order-Markierung aus der Ausgabe entfernt. Diese Option wird nur verwendet, wenn encoding 'utf-8', 'utf-16be' oder 'utf-16le' ist. Standard: false.

Erstellt eine neue TextDecoder-Instanz. Die encoding kann eine der unterstützten Kodierungen oder einen Alias angeben.

Die TextDecoder-Klasse ist auch im globalen Objekt verfügbar.

textDecoder.decode([input[, options]])

Dekodiert die input und gibt einen String zurück. Wenn options.stream true ist, werden alle unvollständigen Byte-Sequenzen, die am Ende der input auftreten, intern gepuffert und nach dem nächsten Aufruf von textDecoder.decode() ausgegeben.

Wenn textDecoder.fatal true ist, führen auftretende Dekodierungsfehler dazu, dass ein TypeError ausgelöst wird.

textDecoder.encoding

Die von der TextDecoder-Instanz unterstützte Kodierung.

textDecoder.fatal

Der Wert ist true, wenn Dekodierungsfehler dazu führen, dass ein TypeError ausgelöst wird.

textDecoder.ignoreBOM

Der Wert ist true, wenn das Dekodierungsergebnis die Byte Order Mark enthält.

Klasse: util.TextEncoder

[Verlauf]

VersionÄnderungen
v11.0.0Die Klasse ist jetzt im globalen Objekt verfügbar.
v8.3.0Hinzugefügt in: v8.3.0

Eine Implementierung der WHATWG Encoding Standard TextEncoder API. Alle Instanzen von TextEncoder unterstützen nur die UTF-8-Kodierung.

js
const encoder = new TextEncoder()
const uint8array = encoder.encode('this is some data')

Die TextEncoder-Klasse ist auch im globalen Objekt verfügbar.

textEncoder.encode([input])

UTF-8-kodiert die input-Zeichenkette und gibt ein Uint8Array mit den kodierten Bytes zurück.

textEncoder.encodeInto(src, dest)

Hinzugefügt in: v12.11.0

  • src <string> Der zu kodierende Text.
  • dest <Uint8Array> Das Array zur Aufnahme des Kodierungsergebnisses.
  • Gibt zurück: <Object>
    • read <number> Die gelesenen Unicode-Codeeinheiten von src.
    • written <number> Die geschriebenen UTF-8-Bytes von dest.

UTF-8-kodiert die src-Zeichenkette in das dest Uint8Array und gibt ein Objekt mit den gelesenen Unicode-Codeeinheiten und den geschriebenen UTF-8-Bytes zurück.

js
const encoder = new TextEncoder()
const src = 'this is some data'
const dest = new Uint8Array(10)
const { read, written } = encoder.encodeInto(src, dest)

textEncoder.encoding

Die von der TextEncoder-Instanz unterstützte Kodierung. Immer auf 'utf-8' gesetzt.

util.toUSVString(string)

Hinzugefügt in: v16.8.0, v14.18.0

Gibt den string zurück, nachdem alle Ersatzcodepunkte (oder gleichwertig alle ungepaarten Ersatzcodeeinheiten) durch das Unicode "Ersatzzeichen" U+FFFD ersetzt wurden.

util.transferableAbortController()

Hinzugefügt in: v18.11.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Erstellt und gibt eine <AbortController>-Instanz zurück, deren <AbortSignal> als übertragbar markiert ist und mit structuredClone() oder postMessage() verwendet werden kann.

util.transferableAbortSignal(signal)

Hinzugefügt in: v18.11.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Markiert das angegebene <AbortSignal> als übertragbar, sodass es mit structuredClone() und postMessage() verwendet werden kann.

js
const signal = transferableAbortSignal(AbortSignal.timeout(100))
const channel = new MessageChannel()
channel.port2.postMessage(signal, [signal])

util.aborted(signal, resource)

Hinzugefügt in: v19.7.0, v18.16.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

  • signal <AbortSignal>
  • resource <Object> Ein beliebiges nicht-null-Objekt, das an die abbrechbare Operation gebunden und schwach gehalten wird. Wenn resource vom Garbage Collector erfasst wird, bevor signal abbricht, bleibt das Promise ausstehend, wodurch Node.js die Verfolgung beenden kann. Dies hilft, Speicherlecks bei lang andauernden oder nicht abbrechbaren Operationen zu verhindern.
  • Gibt zurück: <Promise>

Lauscht auf das Abort-Ereignis des bereitgestellten signal und gibt ein Promise zurück, das aufgelöst wird, wenn das signal abgebrochen wird. Wenn resource bereitgestellt wird, referenziert es schwach das zugehörige Objekt der Operation. Wenn resource vom Garbage Collector erfasst wird, bevor das signal abbricht, bleibt das zurückgegebene Promise ausstehend. Dies verhindert Speicherlecks bei lang andauernden oder nicht abbrechbaren Operationen.

js
const { aborted } = require('node:util')

// Rufe ein Objekt mit einem abbrechbaren Signal ab, wie eine benutzerdefinierte Ressource oder Operation.
const dependent = obtainSomethingAbortable()

// Übergebe `dependent` als Ressource, die angibt, dass das Promise nur aufgelöst werden soll,
// wenn `dependent` noch im Speicher ist, wenn das Signal abgebrochen wird.
aborted(dependent.signal, dependent).then(() => {
  // Dieser Code wird ausgeführt, wenn `dependent` abgebrochen wird.
  console.log('Die abhängige Ressource wurde abgebrochen.')
})

// Simuliere ein Ereignis, das den Abbruch auslöst.
dependent.on('event', () => {
  dependent.abort() // Dies führt dazu, dass das `aborted`-Promise aufgelöst wird.
})
js
import { aborted } from 'node:util'

// Rufe ein Objekt mit einem abbrechbaren Signal ab, wie eine benutzerdefinierte Ressource oder Operation.
const dependent = obtainSomethingAbortable()

// Übergebe `dependent` als Ressource, die angibt, dass das Promise nur aufgelöst werden soll,
// wenn `dependent` noch im Speicher ist, wenn das Signal abgebrochen wird.
aborted(dependent.signal, dependent).then(() => {
  // Dieser Code wird ausgeführt, wenn `dependent` abgebrochen wird.
  console.log('Die abhängige Ressource wurde abgebrochen.')
})

// Simuliere ein Ereignis, das den Abbruch auslöst.
dependent.on('event', () => {
  dependent.abort() // Dies führt dazu, dass das `aborted`-Promise aufgelöst wird.
})

util.types

[Historie]

VersionÄnderungen
v15.3.0Als require('util/types') verfügbar gemacht.
v10.0.0Hinzugefügt in: v10.0.0

util.types bietet Typüberprüfungen für verschiedene Arten von integrierten Objekten. Im Gegensatz zu instanceof oder Object.prototype.toString.call(value) untersuchen diese Überprüfungen nicht die Eigenschaften des Objekts, die von JavaScript aus zugänglich sind (wie z. B. dessen Prototyp), und haben normalerweise den Overhead, in C++ aufzurufen.

Das Ergebnis macht im Allgemeinen keine Zusicherungen darüber, welche Arten von Eigenschaften oder Verhaltensweisen ein Wert in JavaScript aufweist. Sie sind hauptsächlich für Add-on-Entwickler nützlich, die Typüberprüfungen lieber in JavaScript durchführen möchten.

Die API ist über require('node:util').types oder require('node:util/types') zugänglich.

util.types.isAnyArrayBuffer(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine integrierte ArrayBuffer oder SharedArrayBuffer-Instanz ist.

Siehe auch util.types.isArrayBuffer() und util.types.isSharedArrayBuffer().

js
util.types.isAnyArrayBuffer(new ArrayBuffer()) // Gibt true zurück
util.types.isAnyArrayBuffer(new SharedArrayBuffer()) // Gibt true zurück

util.types.isArrayBufferView(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine Instanz einer der ArrayBuffer-Ansichten ist, wie z. B. typisierte Array-Objekte oder DataView. Entspricht ArrayBuffer.isView().

js
util.types.isArrayBufferView(new Int8Array()) // true
util.types.isArrayBufferView(Buffer.from('hello world')) // true
util.types.isArrayBufferView(new DataView(new ArrayBuffer(16))) // true
util.types.isArrayBufferView(new ArrayBuffer()) // false

util.types.isArgumentsObject(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein arguments-Objekt ist.

js
function foo() {
  util.types.isArgumentsObject(arguments) // Gibt true zurück
}

util.types.isArrayBuffer(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute ArrayBuffer-Instanz ist. Dies schließt nicht SharedArrayBuffer-Instanzen ein. In der Regel ist es wünschenswert, beides zu testen; siehe util.types.isAnyArrayBuffer() dafür.

js
util.types.isArrayBuffer(new ArrayBuffer()) // Gibt true zurück
util.types.isArrayBuffer(new SharedArrayBuffer()) // Gibt false zurück

util.types.isAsyncFunction(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine async function ist. Dies gibt nur das zurück, was die JavaScript-Engine sieht; insbesondere kann der Rückgabewert nicht mit dem ursprünglichen Quellcode übereinstimmen, wenn ein Transpilationswerkzeug verwendet wurde.

js
util.types.isAsyncFunction(function foo() {}) // Gibt false zurück
util.types.isAsyncFunction(async function foo() {}) // Gibt true zurück

util.types.isBigInt64Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine BigInt64Array-Instanz ist.

js
util.types.isBigInt64Array(new BigInt64Array()) // Gibt true zurück
util.types.isBigInt64Array(new BigUint64Array()) // Gibt false zurück

util.types.isBigIntObject(value)

Hinzugefügt in: v10.4.0

Gibt true zurück, wenn der Wert ein BigInt-Objekt ist, z. B. erstellt durch Object(BigInt(123)).

js
util.types.isBigIntObject(Object(BigInt(123))) // Gibt true zurück
util.types.isBigIntObject(BigInt(123)) // Gibt false zurück
util.types.isBigIntObject(123) // Gibt false zurück

util.types.isBigUint64Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine BigUint64Array-Instanz ist.

js
util.types.isBigUint64Array(new BigInt64Array()) // Gibt false zurück
util.types.isBigUint64Array(new BigUint64Array()) // Gibt true zurück

util.types.isBooleanObject(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein Boolesches Objekt ist, z. B. erstellt durch new Boolean().

js
util.types.isBooleanObject(false) // Gibt false zurück
util.types.isBooleanObject(true) // Gibt false zurück
util.types.isBooleanObject(new Boolean(false)) // Gibt true zurück
util.types.isBooleanObject(new Boolean(true)) // Gibt true zurück
util.types.isBooleanObject(Boolean(false)) // Gibt false zurück
util.types.isBooleanObject(Boolean(true)) // Gibt false zurück

util.types.isBoxedPrimitive(value)

Hinzugefügt in: v10.11.0

Gibt true zurück, wenn der Wert ein beliebiger gepackter primitiver Objekt ist, z. B. erstellt durch new Boolean(), new String() oder Object(Symbol()).

Zum Beispiel:

js
util.types.isBoxedPrimitive(false) // Gibt false zurück
util.types.isBoxedPrimitive(new Boolean(false)) // Gibt true zurück
util.types.isBoxedPrimitive(Symbol('foo')) // Gibt false zurück
util.types.isBoxedPrimitive(Object(Symbol('foo'))) // Gibt true zurück
util.types.isBoxedPrimitive(Object(BigInt(5))) // Gibt true zurück

util.types.isCryptoKey(value)

Hinzugefügt in: v16.2.0

Gibt true zurück, wenn value ein <CryptoKey> ist, andernfalls false.

util.types.isDataView(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute DataView-Instanz ist.

js
const ab = new ArrayBuffer(20)
util.types.isDataView(new DataView(ab)) // Gibt true zurück
util.types.isDataView(new Float64Array()) // Gibt false zurück

Siehe auch ArrayBuffer.isView().

util.types.isDate(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute Date-Instanz ist.

js
util.types.isDate(new Date()) // Gibt true zurück

util.types.isExternal(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein nativer External-Wert ist.

Ein nativer External-Wert ist ein spezieller Objekttyp, der einen rohen C++-Zeiger (void*) für den Zugriff aus nativem Code enthält und keine anderen Eigenschaften besitzt. Solche Objekte werden entweder von Node.js-Interna oder nativen Add-ons erstellt. In JavaScript sind sie eingefrorene Objekte mit einem null-Prototyp.

C
#include <js_native_api.h>
#include <stdlib.h>
napi_value result;
static napi_value MyNapi(napi_env env, napi_callback_info info) {
  int* raw = (int*) malloc(1024);
  napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result);
  if (status != napi_ok) {
    napi_throw_error(env, NULL, "napi_create_external failed");
    return NULL;
  }
  return result;
}
...
DECLARE_NAPI_PROPERTY("myNapi", MyNapi)
...
js
const native = require('napi_addon.node')
const data = native.myNapi()
util.types.isExternal(data) // gibt true zurück
util.types.isExternal(0) // gibt false zurück
util.types.isExternal(new String('foo')) // gibt false zurück

Weitere Informationen zu napi_create_external finden Sie unter napi_create_external().

util.types.isFloat32Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine integrierte Float32Array-Instanz ist.

js
util.types.isFloat32Array(new ArrayBuffer()) // Gibt false zurück
util.types.isFloat32Array(new Float32Array()) // Gibt true zurück
util.types.isFloat32Array(new Float64Array()) // Gibt false zurück

util.types.isFloat64Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute Float64Array-Instanz ist.

js
util.types.isFloat64Array(new ArrayBuffer()) // Gibt false zurück
util.types.isFloat64Array(new Uint8Array()) // Gibt false zurück
util.types.isFloat64Array(new Float64Array()) // Gibt true zurück

util.types.isGeneratorFunction(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine Generatorfunktion ist. Dies gibt nur zurück, was die JavaScript-Engine sieht; insbesondere kann der Rückgabewert nicht mit dem ursprünglichen Quellcode übereinstimmen, wenn ein Transpilationswerkzeug verwendet wurde.

js
util.types.isGeneratorFunction(function foo() {}) // Gibt false zurück
util.types.isGeneratorFunction(function* foo() {}) // Gibt true zurück

util.types.isGeneratorObject(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein Generatorobjekt ist, wie von einer eingebauten Generatorfunktion zurückgegeben. Dies gibt nur zurück, was die JavaScript-Engine sieht; insbesondere kann der Rückgabewert nicht mit dem ursprünglichen Quellcode übereinstimmen, wenn ein Transpilationswerkzeug verwendet wurde.

js
function* foo() {}
const generator = foo()
util.types.isGeneratorObject(generator) // Gibt true zurück

util.types.isInt8Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute Int8Array-Instanz ist.

js
util.types.isInt8Array(new ArrayBuffer()) // Gibt false zurück
util.types.isInt8Array(new Int8Array()) // Gibt true zurück
util.types.isInt8Array(new Float64Array()) // Gibt false zurück

util.types.isInt16Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine integrierte Int16Array-Instanz ist.

js
util.types.isInt16Array(new ArrayBuffer()) // Gibt false zurück
util.types.isInt16Array(new Int16Array()) // Gibt true zurück
util.types.isInt16Array(new Float64Array()) // Gibt false zurück

util.types.isInt32Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine integrierte Int32Array-Instanz ist.

js
util.types.isInt32Array(new ArrayBuffer()) // Gibt false zurück
util.types.isInt32Array(new Int32Array()) // Gibt true zurück
util.types.isInt32Array(new Float64Array()) // Gibt false zurück

util.types.isKeyObject(value)

Hinzugefügt in: v16.2.0

Gibt true zurück, wenn value ein <KeyObject> ist, andernfalls false.

util.types.isMap(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine integrierte Map-Instanz ist.

js
util.types.isMap(new Map()) // Gibt true zurück

util.types.isMapIterator(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein Iterator ist, der für eine integrierte Map-Instanz zurückgegeben wurde.

js
const map = new Map()
util.types.isMapIterator(map.keys()) // Gibt true zurück
util.types.isMapIterator(map.values()) // Gibt true zurück
util.types.isMapIterator(map.entries()) // Gibt true zurück
util.types.isMapIterator(map[Symbol.iterator]()) // Gibt true zurück

util.types.isModuleNamespaceObject(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine Instanz eines Modul-Namespace-Objekts ist.

js
import * as ns from './a.js'

util.types.isModuleNamespaceObject(ns) // Gibt true zurück

util.types.isNativeError(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert vom Konstruktor eines integrierten Error-Typs zurückgegeben wurde.

js
console.log(util.types.isNativeError(new Error())) // true
console.log(util.types.isNativeError(new TypeError())) // true
console.log(util.types.isNativeError(new RangeError())) // true

Subklassen der nativen Fehlertypen sind ebenfalls native Fehler:

js
class MyError extends Error {}
console.log(util.types.isNativeError(new MyError())) // true

Ein Wert, der instanceof einer nativen Fehlerklasse ist, ist nicht gleichbedeutend damit, dass isNativeError() für diesen Wert true zurückgibt. isNativeError() gibt true für Fehler zurück, die aus einem anderen Realm stammen, während instanceof Error für diese Fehler false zurückgibt:

js
const vm = require('node:vm')
const context = vm.createContext({})
const myError = vm.runInContext('new Error()', context)
console.log(util.types.isNativeError(myError)) // true
console.log(myError instanceof Error) // false

Umgekehrt gibt isNativeError() für alle Objekte false zurück, die nicht vom Konstruktor eines nativen Fehlers zurückgegeben wurden. Das schließt Werte ein, die instanceof native Fehler sind:

js
const myError = { __proto__: Error.prototype }
console.log(util.types.isNativeError(myError)) // false
console.log(myError instanceof Error) // true

util.types.isNumberObject(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein Zahlenobjekt ist, z. B. erstellt mit new Number().

js
util.types.isNumberObject(0) // Gibt false zurück
util.types.isNumberObject(new Number(0)) // Gibt true zurück

util.types.isPromise(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein eingebautes Promise ist.

js
util.types.isPromise(Promise.resolve(42)) // Gibt true zurück

util.types.isProxy(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine Proxy-Instanz ist.

js
const target = {}
const proxy = new Proxy(target, {})
util.types.isProxy(target) // Gibt false zurück
util.types.isProxy(proxy) // Gibt true zurück

util.types.isRegExp(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein reguläres Ausdrucksobjekt ist.

js
util.types.isRegExp(/abc/) // Gibt true zurück
util.types.isRegExp(new RegExp('abc')) // Gibt true zurück

util.types.isSet(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute Set-Instanz ist.

js
util.types.isSet(new Set()) // Gibt true zurück

util.types.isSetIterator(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein Iterator ist, der für eine eingebaute Set-Instanz zurückgegeben wird.

js
const set = new Set()
util.types.isSetIterator(set.keys()) // Gibt true zurück
util.types.isSetIterator(set.values()) // Gibt true zurück
util.types.isSetIterator(set.entries()) // Gibt true zurück
util.types.isSetIterator(set[Symbol.iterator]()) // Gibt true zurück

util.types.isSharedArrayBuffer(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute SharedArrayBuffer-Instanz ist. Dies schließt nicht ArrayBuffer-Instanzen ein. Normalerweise ist es wünschenswert, auf beides zu testen; Siehe util.types.isAnyArrayBuffer() dafür.

js
util.types.isSharedArrayBuffer(new ArrayBuffer()) // Gibt false zurück
util.types.isSharedArrayBuffer(new SharedArrayBuffer()) // Gibt true zurück

util.types.isStringObject(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein String-Objekt ist, z. B. erstellt durch new String().

js
util.types.isStringObject('foo') // Gibt false zurück
util.types.isStringObject(new String('foo')) // Gibt true zurück

util.types.isSymbolObject(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert ein Symbolobjekt ist, das durch Aufrufen von Object() auf einem Symbol-Primitiv erstellt wurde.

js
const symbol = Symbol('foo')
util.types.isSymbolObject(symbol) // Gibt false zurück
util.types.isSymbolObject(Object(symbol)) // Gibt true zurück

util.types.isTypedArray(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute TypedArray-Instanz ist.

js
util.types.isTypedArray(new ArrayBuffer()) // Gibt false zurück
util.types.isTypedArray(new Uint8Array()) // Gibt true zurück
util.types.isTypedArray(new Float64Array()) // Gibt true zurück

Siehe auch ArrayBuffer.isView().

util.types.isUint8Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute Uint8Array-Instanz ist.

js
util.types.isUint8Array(new ArrayBuffer()) // Gibt false zurück
util.types.isUint8Array(new Uint8Array()) // Gibt true zurück
util.types.isUint8Array(new Float64Array()) // Gibt false zurück

util.types.isUint8ClampedArray(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute Uint8ClampedArray-Instanz ist.

js
util.types.isUint8ClampedArray(new ArrayBuffer()) // Gibt false zurück
util.types.isUint8ClampedArray(new Uint8ClampedArray()) // Gibt true zurück
util.types.isUint8ClampedArray(new Float64Array()) // Gibt false zurück

util.types.isUint16Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute Uint16Array-Instanz ist.

js
util.types.isUint16Array(new ArrayBuffer()) // Gibt false zurück
util.types.isUint16Array(new Uint16Array()) // Gibt true zurück
util.types.isUint16Array(new Float64Array()) // Gibt false zurück

util.types.isUint32Array(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute Uint32Array-Instanz ist.

js
util.types.isUint32Array(new ArrayBuffer()) // Gibt false zurück
util.types.isUint32Array(new Uint32Array()) // Gibt true zurück
util.types.isUint32Array(new Float64Array()) // Gibt false zurück

util.types.isWeakMap(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute WeakMap-Instanz ist.

js
util.types.isWeakMap(new WeakMap()) // Gibt true zurück

util.types.isWeakSet(value)

Hinzugefügt in: v10.0.0

Gibt true zurück, wenn der Wert eine eingebaute WeakSet-Instanz ist.

js
util.types.isWeakSet(new WeakSet()) // Gibt true zurück

Veraltete APIs

Die folgenden APIs sind veraltet und sollten nicht mehr verwendet werden. Vorhandene Anwendungen und Module sollten aktualisiert werden, um alternative Ansätze zu finden.

util._extend(target, source)

Hinzugefügt in: v0.7.5

Veraltet seit: v6.0.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen Object.assign().

Die Methode util._extend() war nie für die Verwendung außerhalb interner Node.js-Module vorgesehen. Die Community hat sie trotzdem gefunden und verwendet.

Sie ist veraltet und sollte nicht in neuem Code verwendet werden. JavaScript verfügt über eine sehr ähnliche integrierte Funktionalität durch Object.assign().

util.isArray(object)

Hinzugefügt in: v0.6.0

Veraltet seit: v4.0.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen Array.isArray().

Alias für Array.isArray().

Gibt true zurück, wenn das gegebene object ein Array ist. Andernfalls wird false zurückgegeben.

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

util.isArray([])
// Gibt zurück: true
util.isArray(new Array())
// Gibt zurück: true
util.isArray({})
// Gibt zurück: false