Util

[Stable : 2 - Stable]

Stable : 2 Stability : 2 - Stable

Source Code : lib/util.js

Le module node:util répond aux besoins des API internes de Node.js. De nombreux utilitaires sont également utiles pour les développeurs d'applications et de modules. Pour y accéder :

const util = require('node:util')

util.callbackify(original)

Ajouté dans : v8.2.0

• original <Function> Une fonction async
• Retourne : <Function> une fonction de style callback

Prend une fonction async (ou une fonction qui retourne une Promise) et retourne une fonction suivant le style de callback error-first, c'est-à-dire prenant un callback (err, value) => ... comme dernier argument. Dans le callback, le premier argument sera la raison du rejet (ou null si la Promise a été résolue), et le second argument sera la valeur résolue.

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

Affichera :

hello world

Le callback est exécuté de manière asynchrone et aura une trace de pile limitée. Si le callback lève une exception, le processus émettra un événement 'uncaughtException', et s'il n'est pas géré, il se terminera.

Puisque null a une signification spéciale comme premier argument d'un callback, si une fonction encapsulée rejette une Promise avec une valeur fausse comme raison, la valeur est encapsulée dans une Error avec la valeur originale stockée dans un champ nommé reason.

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

callbackFunction((err, ret) => {
  // Lorsque la Promise a été rejetée avec `null`, elle est encapsulée dans une Error et
  // la valeur originale est stockée dans `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null // true
})

util.debuglog(section[, callback])

Ajouté dans : v0.11.3

• section <string> Une chaîne de caractères identifiant la partie de l'application pour laquelle la fonction debuglog est créée.
• callback <Function> Une fonction de rappel invoquée la première fois que la fonction de journalisation est appelée avec un argument de fonction qui est une fonction de journalisation plus optimisée.
• Retourne : <Function> La fonction de journalisation

La méthode util.debuglog() est utilisée pour créer une fonction qui écrit conditionnellement des messages de débogage sur stderr en fonction de l'existence de la variable d'environnement NODE_DEBUG. Si le nom de la section apparaît dans la valeur de cette variable d'environnement, alors la fonction retournée fonctionne de manière similaire à console.error(). Sinon, la fonction retournée est une opération sans effet.

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

debuglog('hello from foo [%d]', 123)

Si ce programme est exécuté avec NODE_DEBUG=foo dans l'environnement, il affichera quelque chose comme :

FOO 3245: hello from foo [123]

où 3245 est l'ID du processus. S'il n'est pas exécuté avec cette variable d'environnement définie, il n'affichera rien.

La section prend également en charge les caractères génériques :

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

debuglog("hi there, it's foo-bar [%d]", 2333)

s'il est exécuté avec NODE_DEBUG=foo* dans l'environnement, il affichera quelque chose comme :

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

Plusieurs noms de section séparés par des virgules peuvent être spécifiés dans la variable d'environnement NODE_DEBUG : NODE_DEBUG=fs,net,tls.

L'argument callback facultatif peut être utilisé pour remplacer la fonction de journalisation par une fonction différente qui n'a pas d'initialisation ou d'enveloppement inutile.

const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
  // Remplacer par une fonction de journalisation qui optimise
  // le test si la section est activée
  debuglog = debug
})

debuglog().enabled

Ajouté dans : v14.9.0

• <booléen>

L'accesseur util.debuglog().enabled est utilisé pour créer un test pouvant être utilisé dans des conditionnelles basées sur l'existence de la variable d'environnement NODE_DEBUG. Si le nom de la section apparaît dans la valeur de cette variable d'environnement, la valeur renvoyée sera true. Sinon, la valeur renvoyée sera false.

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

Si ce programme est exécuté avec NODE_DEBUG=foo dans l'environnement, il affichera quelque chose comme :

hello from foo [123]

util.debug(section)

Ajouté dans : v14.9.0

Alias de util.debuglog. L'utilisation permet une lisibilité qui n'implique pas la journalisation lorsque seule util.debuglog().enabled est utilisée.

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

[Historique]

Version	Modifications
v10.0.0	Les avertissements de dépréciation ne sont émis qu'une seule fois pour chaque code.
v0.8.0	Ajouté dans : v0.8.0

• fn <Fonction> La fonction qui est dépréciée.
• msg <chaîne de caractères> Un message d'avertissement à afficher lorsque la fonction dépréciée est invoquée.
• code <chaîne de caractères> Un code de dépréciation. Consultez la liste des API dépréciées pour obtenir une liste des codes.
• Renvoie : <Fonction> La fonction dépréciée encapsulée pour émettre un avertissement.

La méthode util.deprecate() encapsule fn (qui peut être une fonction ou une classe) de manière à ce qu'elle soit marquée comme dépréciée.

const util = require('node:util')

exports.obsoleteFunction = util.deprecate(() => {
  // Faites quelque chose ici.
}, 'obsoleteFunction() est dépréciée. Utilisez newShinyFunction() à la place.')

Lorsqu'elle est appelée, util.deprecate() renverra une fonction qui émettra un DeprecationWarning en utilisant l'événement 'warning'. L'avertissement sera émis et imprimé sur stderr la première fois que la fonction renvoyée sera appelée. Une fois l'avertissement émis, la fonction encapsulée est appelée sans émettre d'avertissement.

Si le même code facultatif est fourni dans plusieurs appels à util.deprecate(), l'avertissement ne sera émis qu'une seule fois pour ce code.

const util = require('node:util')

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001')
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001')
fn1() // Émet un avertissement de dépréciation avec le code DEP0001
fn2() // N'émet pas d'avertissement de dépréciation car il a le même code

Si les indicateurs de ligne de commande --no-deprecation ou --no-warnings sont utilisés, ou si la propriété process.noDeprecation est définie sur true avant le premier avertissement de dépréciation, la méthode util.deprecate() ne fait rien.

Si les indicateurs de ligne de commande --trace-deprecation ou --trace-warnings sont définis, ou si la propriété process.traceDeprecation est définie sur true, un avertissement et une trace de pile sont imprimés sur stderr la première fois que la fonction dépréciée est appelée.

Si l'indicateur de ligne de commande --throw-deprecation est défini, ou si la propriété process.throwDeprecation est définie sur true, une exception sera levée lorsque la fonction dépréciée sera appelée.

L'indicateur de ligne de commande --throw-deprecation et la propriété process.throwDeprecation ont priorité sur --trace-deprecation et process.traceDeprecation.

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

[Historique]

Version	Modifications
v12.11.0	Le spécificateur %c est désormais ignoré.
v12.0.0	L'argument format n'est désormais considéré comme tel que s'il contient réellement des spécificateurs de format.
v12.0.0	Si l'argument format n'est pas une chaîne de format, la mise en forme de la chaîne de sortie ne dépend plus du type du premier argument. Cette modification supprime les guillemets précédemment présents dans les chaînes qui étaient sorties lorsque le premier argument n'était pas une chaîne.
v11.4.0	Les spécificateurs %d, %f et %i prennent désormais correctement en charge les symboles.
v11.4.0	La profondeur de depth du spécificateur %o a de nouveau une profondeur par défaut de 4.
v11.0.0	L'option depth du spécificateur %o utilisera désormais la profondeur par défaut.
v10.12.0	Les spécificateurs %d et %i prennent désormais en charge BigInt.
v8.4.0	Les spécificateurs %o et %O sont désormais pris en charge.
v0.5.3	Ajouté dans : v0.5.3

• format <string> Une chaîne de format de type printf.

La méthode util.format() renvoie une chaîne formatée en utilisant le premier argument comme chaîne de format de type printf, qui peut contenir zéro ou plusieurs spécificateurs de format. Chaque spécificateur est remplacé par la valeur convertie de l'argument correspondant. Les spécificateurs pris en charge sont :

• %s: String sera utilisé pour convertir toutes les valeurs sauf BigInt, Object et -0. Les valeurs BigInt seront représentées avec un n et les objets qui n'ont pas de fonction toString définie par l'utilisateur sont inspectés à l'aide de util.inspect() avec les options { depth: 0, colors: false, compact: 3 }.
• %d: Number sera utilisé pour convertir toutes les valeurs sauf BigInt et Symbol.
• %i: parseInt(value, 10) est utilisé pour toutes les valeurs sauf BigInt et Symbol.
• %f: parseFloat(value) est utilisé pour toutes les valeurs sauf Symbol.
• %j: JSON. Remplacé par la chaîne '[Circular]' si l'argument contient des références circulaires.
• %o: Object. Une représentation sous forme de chaîne d'un objet avec une mise en forme d'objet JavaScript générique. Similaire à util.inspect() avec les options { showHidden: true, showProxy: true }. Cela affichera l'objet complet, y compris les propriétés non énumérables et les proxies.
• %O: Object. Une représentation sous forme de chaîne d'un objet avec une mise en forme d'objet JavaScript générique. Similaire à util.inspect() sans options. Cela affichera l'objet complet, sans inclure les propriétés non énumérables et les proxies.
• %c: CSS. Ce spécificateur est ignoré et sautera tout CSS passé.
• %%: signe de pourcentage unique ('%'). Cela ne consomme pas d'argument.
• Renvoie : <string> La chaîne formatée

Si un spécificateur n'a pas d'argument correspondant, il n'est pas remplacé :

util.format('%s:%s', 'foo')
// Renvoie : 'foo:%s'

Les valeurs qui ne font pas partie de la chaîne de format sont formatées à l'aide de util.inspect() si leur type n'est pas string.

S'il y a plus d'arguments passés à la méthode util.format() que le nombre de spécificateurs, les arguments supplémentaires sont concaténés à la chaîne renvoyée, séparés par des espaces :

util.format('%s:%s', 'foo', 'bar', 'baz')
// Renvoie : 'foo:bar baz'

Si le premier argument ne contient pas de spécificateur de format valide, util.format() renvoie une chaîne qui est la concaténation de tous les arguments séparés par des espaces :

util.format(1, 2, 3)
// Renvoie : '1 2 3'

Si un seul argument est passé à util.format(), il est renvoyé tel quel sans aucune mise en forme :

util.format('%% %s')
// Renvoie : '%% %s'

util.format() est une méthode synchrone destinée à être utilisée comme outil de débogage. Certaines valeurs d'entrée peuvent avoir une surcharge de performances significative qui peut bloquer la boucle d'événements. Utilisez cette fonction avec précaution et jamais dans un chemin d'accès au code critique.

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

Ajouté dans : v10.0.0

• inspectOptions <Objet>
• format <chaîne de caractères>

Cette fonction est identique à util.format(), à la différence qu’elle prend un argument inspectOptions qui spécifie les options transmises à util.inspect().

util.formatWithOptions({ colors: true }, 'Voir objet %O', { foo: 42 })
// Retourne 'Voir objet { foo: 42 }', où `42` est coloré comme un nombre
// lorsqu’il est affiché dans un terminal.

util.getCallSites(frameCountOrOptions, [options])

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1.1 - Développement actif

[Historique]

Version	Modifications
v23.3.0	L’API est renommée de util.getCallSite en util.getCallSites().
v22.9.0	Ajouté dans : v22.9.0

• frameCount <nombre> Nombre optionnel d’images à capturer en tant qu’objets de site d’appel. Valeur par défaut : 10. La plage autorisée est comprise entre 1 et 200.

• options <Objet> Optionnel

  • sourceMap <booléen> Reconstitue l’emplacement d’origine dans la trace de pile à partir de la source-map. Activé par défaut avec l’indicateur --enable-source-maps.

• Retourne : <Objet[]> Un tableau d’objets de site d’appel

  • functionName <chaîne de caractères> Retourne le nom de la fonction associée à ce site d’appel.
  • scriptName <chaîne de caractères> Retourne le nom de la ressource qui contient le script de la fonction pour ce site d’appel.
  • lineNumber <nombre> Retourne le numéro, basé sur 1, de la ligne pour l’appel de fonction associé.
  • column <nombre> Retourne le décalage de colonne basé sur 1 sur la ligne pour l’appel de fonction associé.

Retourne un tableau d’objets de site d’appel contenant la pile de la fonction appelante.

const util = require('node:util')

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

  console.log('Sites d’appel :')
  callSites.forEach((callSite, index) => {
    console.log(`Site d’appel ${index + 1} :`)
    console.log(`Nom de la fonction : ${callSite.functionName}`)
    console.log(`Nom du script : ${callSite.scriptName}`)
    console.log(`Numéro de ligne : ${callSite.lineNumber}`)
    console.log(`Numéro de colonne : ${callSite.column}`)
  })
  // Site d’appel 1 :
  // Nom de la fonction : exampleFunction
  // Nom du script : /home/example.js
  // Numéro de ligne : 5
  // Numéro de colonne : 26

  // Site d’appel 2 :
  // Nom de la fonction : anotherFunction
  // Nom du script : /home/example.js
  // Numéro de ligne : 22
  // Numéro de colonne : 3

  // ...
}

// Une fonction pour simuler une autre couche de pile
function anotherFunction() {
  exampleFunction()
}

anotherFunction()

Il est possible de reconstruire les emplacements d’origine en définissant l’option sourceMap sur true. Si la source map n’est pas disponible, l’emplacement d’origine sera le même que l’emplacement actuel. Lorsque l’indicateur --enable-source-maps est activé, par exemple lors de l’utilisation de --experimental-transform-types, sourceMap sera vrai par défaut.

import util from 'node:util'

interface Foo {
  foo: string
}

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

// Avec sourceMap :
// Nom de la fonction : ''
// Nom du script : example.js
// Numéro de ligne : 7
// Numéro de colonne : 26

// Sans sourceMap :
// Nom de la fonction : ''
// Nom du script : example.js
// Numéro de ligne : 2
// Numéro de colonne : 26

util.getSystemErrorName(err)

Ajouté dans : v9.7.0

• err <nombre>
• Retourne : <chaîne de caractères>

Retourne le nom de chaîne de caractères pour un code d'erreur numérique provenant d'une API Node.js. Le mappage entre les codes d'erreur et les noms d'erreur dépend de la plateforme. Consultez Erreurs système courantes pour connaître les noms des erreurs courantes.

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

util.getSystemErrorMap()

Ajouté dans : v16.0.0, v14.17.0

• Retourne : <Map>

Retourne une Map de tous les codes d'erreur système disponibles depuis l'API Node.js. Le mappage entre les codes d'erreur et les noms d'erreur dépend de la plateforme. Consultez Erreurs système courantes pour connaître les noms des erreurs courantes.

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)

Ajouté dans : v23.1.0

• err <nombre>
• Retourne : <chaîne de caractères>

Retourne le message de chaîne de caractères pour un code d'erreur numérique provenant d'une API Node.js. Le mappage entre les codes d'erreur et les messages de chaîne de caractères dépend de la plateforme.

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)

[Historique]

Version	Modifications
v5.0.0	Le paramètre constructor peut désormais faire référence à une classe ES6.
v0.3.0	Ajouté dans : v0.3.0

[Stable : 3 - Héritage]

Stable : 3 Stabilité : 3 - Héritage : Utilisez la syntaxe de classe ES2015 et le mot-clé extends à la place.

• constructor <Fonction>
• superConstructor <Fonction>

L'utilisation de util.inherits() est déconseillée. Veuillez utiliser les mots clés ES6 class et extends pour obtenir la prise en charge de l'héritage au niveau du langage. Notez également que les deux styles sont sémantiquement incompatibles.

Hérite des méthodes de prototype d'un constructeur dans un autre. Le prototype de constructor sera défini sur un nouvel objet créé à partir de superConstructor.

Cela ajoute principalement une validation d'entrée supplémentaire sur Object.setPrototypeOf(constructor.prototype, superConstructor.prototype). Pour plus de commodité, superConstructor sera accessible via la propriété constructor.super_.

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

Exemple ES6 utilisant class et extends :

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]]])

[Historique]

Version	Modifications
v16.18.0	Ajout de la prise en charge de maxArrayLength lors de l'inspection de Set et Map.
v17.3.0, v16.14.0	L'option numericSeparator est désormais prise en charge.
v13.0.0	Les références circulaires incluent désormais un marqueur vers la référence.
v14.6.0, v12.19.0	Si object provient d'un vm.Context différent, une fonction d'inspection personnalisée sur celui-ci ne recevra plus d'arguments spécifiques au contexte.
v13.13.0, v12.17.0	L'option maxStringLength est désormais prise en charge.
v13.5.0, v12.16.0	Les propriétés de prototype définies par l'utilisateur sont inspectées si showHidden est true.
v12.0.0	La valeur par défaut de l'option compact est passée à 3 et la valeur par défaut de l'option breakLength est passée à 80.
v12.0.0	Les propriétés internes n'apparaissent plus dans l'argument contextuel d'une fonction d'inspection personnalisée.
v11.11.0	L'option compact accepte les nombres pour un nouveau mode de sortie.
v11.7.0	Les ArrayBuffers affichent désormais également leur contenu binaire.
v11.5.0	L'option getters est désormais prise en charge.
v11.4.0	La valeur par défaut de depth est revenue à 2.
v11.0.0	La valeur par défaut de depth est passée à 20.
v11.0.0	La sortie d'inspection est désormais limitée à environ 128 Mio. Les données dépassant cette taille ne seront pas entièrement inspectées.
v10.12.0	L'option sorted est désormais prise en charge.
v10.6.0	L'inspection des listes chaînées et des objets similaires est désormais possible jusqu'à la taille maximale de la pile d'appels.
v10.0.0	Les entrées WeakMap et WeakSet peuvent désormais également être inspectées.
v9.9.0	L'option compact est désormais prise en charge.
v6.6.0	Les fonctions d'inspection personnalisées peuvent désormais renvoyer this.
v6.3.0	L'option breakLength est désormais prise en charge.
v6.1.0	L'option maxArrayLength est désormais prise en charge ; en particulier, les tableaux longs sont tronqués par défaut.
v6.1.0	L'option showProxy est désormais prise en charge.
v0.3.0	Ajouté dans : v0.3.0

• object <any> Toute primitive JavaScript ou Objet.

• options <Object>

  • showHidden <boolean> Si true, les symboles et les propriétés non énumérables de object sont inclus dans le résultat formaté. Les entrées WeakMap et WeakSet sont également incluses, ainsi que les propriétés de prototype définies par l'utilisateur (à l'exclusion des propriétés de méthode). Défaut : false.
  • depth <number> Spécifie le nombre de fois où il faut effectuer une récursion lors du formatage de object. Ceci est utile pour inspecter les grands objets. Pour effectuer une récursion jusqu'à la taille maximale de la pile d'appels, transmettez Infinity ou null. Défaut : 2.
  • colors <boolean> Si true, la sortie est stylisée avec des codes de couleur ANSI. Les couleurs sont personnalisables. Voir Personnalisation des couleurs util.inspect. Défaut : false.
  • customInspect <boolean> Si false, les fonctions [util.inspect.custom](depth, opts, inspect) ne sont pas appelées. Défaut : true.
  • showProxy <boolean> Si true, l'inspection Proxy inclut les objets target et handler. Défaut : false.
  • maxArrayLength <integer> Spécifie le nombre maximal d'éléments Array, TypedArray, Map, Set, WeakMap et WeakSet à inclure lors du formatage. Définissez sur null ou Infinity pour afficher tous les éléments. Définissez sur 0 ou une valeur négative pour ne pas afficher d'éléments. Défaut : 100.
  • maxStringLength <integer> Spécifie le nombre maximal de caractères à inclure lors du formatage. Définissez sur null ou Infinity pour afficher tous les éléments. Définissez sur 0 ou une valeur négative pour ne pas afficher de caractères. Défaut : 10000.
  • breakLength <integer> La longueur à laquelle les valeurs d'entrée sont divisées sur plusieurs lignes. Définissez sur Infinity pour formater l'entrée sur une seule ligne (en combinaison avec compact défini sur true ou tout nombre >= 1). Défaut : 80.
  • compact <boolean> | <integer> Le définir sur false fait que chaque clé d'objet est affichée sur une nouvelle ligne. Il sautera des lignes dans le texte plus long que breakLength. S'il est défini sur un nombre, les n éléments internes les plus proches sont unis sur une seule ligne tant que toutes les propriétés tiennent dans breakLength. Les éléments de tableau courts sont également regroupés. Pour plus d'informations, voir l'exemple ci-dessous. Défaut : 3.
  • sorted <boolean> | <Function> S'il est défini sur true ou une fonction, toutes les propriétés d'un objet et les entrées Set et Map sont triées dans la chaîne résultante. S'il est défini sur true, le tri par défaut est utilisé. S'il est défini sur une fonction, elle est utilisée comme fonction de comparaison.
  • getters <boolean> | <string> S'il est défini sur true, les getters sont inspectés. S'il est défini sur 'get', seuls les getters sans setter correspondant sont inspectés. S'il est défini sur 'set', seuls les getters avec un setter correspondant sont inspectés. Cela peut entraîner des effets secondaires en fonction de la fonction getter. Défaut : false.
  • numericSeparator <boolean> S'il est défini sur true, un trait de soulignement est utilisé pour séparer tous les trois chiffres dans tous les bigints et les nombres. Défaut : false.

• Retourne : <string> La représentation de object.

La méthode util.inspect() renvoie une représentation sous forme de chaîne de object destinée au débogage. La sortie de util.inspect peut changer à tout moment et ne doit pas être utilisée de manière programmatique. Des options supplémentaires peuvent être passées pour modifier le résultat. util.inspect() utilisera le nom du constructeur et/ou @@toStringTag pour créer une balise identifiable pour une valeur inspectée.

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

Les références circulaires pointent vers leur ancre à l'aide d'un index de référence :

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

L'exemple suivant inspecte toutes les propriétés de l'objet util :

const util = require('node:util')

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

L'exemple suivant met en évidence l'effet de l'option compact :

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 [...]', // Une longue ligne
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Définir `compact` sur false ou un entier crée une sortie plus lisible.
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'
//   }
// }

// Définir `breakLength` sur par exemple 150 affichera le texte "Lorem ipsum" sur une
// seule ligne.

L'option showHidden permet d'inspecter les entrées WeakMap et WeakSet. S'il y a plus d'entrées que maxArrayLength, il n'y a aucune garantie que les entrées soient affichées. Cela signifie que la récupération des mêmes entrées WeakSet deux fois peut donner des résultats différents. De plus, les entrées sans références fortes restantes peuvent être collectées par le garbage collector à tout moment.

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

L'option sorted garantit que l'ordre d'insertion des propriétés d'un objet n'a pas d'impact sur le résultat de util.inspect().

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

L'option numericSeparator ajoute un trait de soulignement tous les trois chiffres à tous les nombres.

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() est une méthode synchrone destinée au débogage. Sa longueur de sortie maximale est d'environ 128 Mio. Les entrées qui produisent une sortie plus longue seront tronquées.

Personnalisation des couleurs de util.inspect

La sortie en couleur (si activée) de util.inspect est personnalisable globalement via les propriétés util.inspect.styles et util.inspect.colors.

util.inspect.styles est une map associant un nom de style à une couleur de util.inspect.colors.

Les styles par défaut et les couleurs associées sont :

• bigint : yellow
• boolean : yellow
• date : magenta
• module : underline
• name : (aucun style)
• null : bold
• number : yellow
• regexp : red
• special : cyan (par exemple, Proxies)
• string : green
• symbol : green
• undefined : grey

Le style de couleur utilise des codes de contrôle ANSI qui peuvent ne pas être pris en charge sur tous les terminaux. Pour vérifier la prise en charge des couleurs, utilisez tty.hasColors().

Les codes de contrôle prédéfinis sont listés ci-dessous (regroupés en « modificateurs », « couleurs de premier plan » et « couleurs d’arrière-plan »).

Modificateurs

La prise en charge des modificateurs varie selon les terminaux. Ils seront principalement ignorés s’ils ne sont pas pris en charge.

• reset - Réinitialise tous les modificateurs (de couleur) à leurs valeurs par défaut
• bold - Met le texte en gras
• italic - Met le texte en italique
• underline - Souligne le texte
• strikethrough - Trace une ligne horizontale au centre du texte (Alias : strikeThrough, crossedout, crossedOut)
• hidden - Affiche le texte, mais le rend invisible (Alias : conceal)
• dim - Intensité de couleur diminuée (Alias : faint)
• overlined - Surligne le texte
• blink - Masque et affiche le texte à intervalles réguliers
• inverse - Inverse les couleurs de premier plan et d’arrière-plan (Alias : swapcolors, swapColors)
• doubleunderline - Double soulignement du texte (Alias : doubleUnderline)
• framed - Dessine un cadre autour du texte

Couleurs de premier plan

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

Couleurs d’arrière-plan

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

Fonctions d'inspection personnalisées sur les objets

[Historique]

Version	Modifications
v17.3.0, v16.14.0	L'argument inspect est ajouté pour une meilleure interopérabilité.
v0.1.97	Ajouté dans : v0.1.97

Les objets peuvent également définir leur propre fonction [util.inspect.custom](depth, opts, inspect), que util.inspect() appellera et utilisera le résultat lors de l'inspection de l'objet.

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

    // Marge de cinq espaces car c'est la taille de "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)

util.inspect(box)
// Retourne : "Box< true >"

Les fonctions personnalisées [util.inspect.custom](depth, opts, inspect) retournent généralement une chaîne de caractères, mais peuvent retourner une valeur de n'importe quel type qui sera formatée en conséquence par util.inspect().

const util = require('node:util')

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

util.inspect(obj)
// Retourne : "{ bar: 'baz' }"

util.inspect.custom

[Historique]

Version	Modifications
v10.12.0	Ceci est maintenant défini comme un symbole partagé.
v6.6.0	Ajouté dans : v6.6.0

• <symbole> qui peut être utilisé pour déclarer des fonctions d'inspection personnalisées.

En plus d'être accessible via util.inspect.custom, ce symbole est enregistré globalement et peut être accédé dans n'importe quel environnement sous la forme Symbol.for('nodejs.util.inspect.custom').

Cela permet d'écrire du code de manière portable, de sorte que la fonction d'inspection personnalisée est utilisée dans un environnement Node.js et ignorée dans le navigateur. La fonction util.inspect() elle-même est passée en troisième argument à la fonction d'inspection personnalisée pour permettre une portabilité accrue.

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)
// Affiche Password <xxxxxxxx>

Voir Fonctions d'inspection personnalisées sur les objets pour plus de détails.

util.inspect.defaultOptions

Ajouté dans : v6.4.0

La valeur defaultOptions permet de personnaliser les options par défaut utilisées par util.inspect. Ceci est utile pour les fonctions comme console.log ou util.format qui appellent implicitement util.inspect. Elle doit être définie sur un objet contenant une ou plusieurs options util.inspect() valides. La définition directe des propriétés d'option est également prise en charge.

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

console.log(arr) // Affiche le tableau tronqué
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // Affiche le tableau complet

util.isDeepStrictEqual(val1, val2)

Ajouté dans : v9.0.0

• val1 <any>
• val2 <any>
• Retourne : <boolean>

Retourne true s'il y a une égalité stricte profonde entre val1 et val2. Sinon, retourne false.

Voir assert.deepStrictEqual() pour plus d'informations sur l'égalité stricte profonde.

Classe : util.MIMEType

Ajouté dans : v19.1.0, v18.13.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Une implémentation de la classe MIMEType.

Conformément aux conventions des navigateurs, toutes les propriétés des objets MIMEType sont implémentées comme des accesseurs (getters et setters) sur le prototype de la classe, plutôt que comme des propriétés de données sur l'objet lui-même.

Une chaîne MIME est une chaîne structurée contenant plusieurs composants significatifs. Lorsqu'elle est analysée, un objet MIMEType est retourné contenant des propriétés pour chacun de ces composants.

Constructeur : new MIMEType(input)

• input <string> La chaîne MIME à analyser

Crée un nouvel objet MIMEType en analysant l'input.

ESM

import { MIMEType } from 'node:util'

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

CJS

const { MIMEType } = require('node:util')

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

Une erreur TypeError sera levée si l'input n'est pas un MIME valide. Notez qu'un effort sera fait pour convertir les valeurs données en chaînes de caractères. Par exemple :

ESM

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

CJS

const { MIMEType } = require('node:util')
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// Affiche : text/plain

mime.type

• <string>

Obtient et définit la partie type du MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

const { MIMEType } = require('node:util')

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

mime.subtype

• <string>

Obtient et définit la partie sous-type du MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

const { MIMEType } = require('node:util')

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

mime.essence

• <string>

Obtient l'essence du MIME. Cette propriété est en lecture seule. Utilisez mime.type ou mime.subtype pour modifier le MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

const { MIMEType } = require('node:util')

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

mime.params

• <MIMEParams>

Récupère l'objet MIMEParams représentant les paramètres du MIME. Cette propriété est en lecture seule. Consultez la documentation MIMEParams pour plus de détails.

mime.toString()

• Retourne : <string>

La méthode toString() de l'objet MIMEType renvoie le MIME sérialisé.

En raison de la nécessité de conformité aux normes, cette méthode ne permet pas aux utilisateurs de personnaliser le processus de sérialisation du MIME.

mime.toJSON()

• Retourne : <string>

Alias de mime.toString().

Cette méthode est appelée automatiquement lorsqu'un objet MIMEType est sérialisé avec JSON.stringify().

ESM

import { MIMEType } from 'node:util'

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

CJS

const { MIMEType } = require('node:util')

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

Class: util.MIMEParams

Ajouté dans : v19.1.0, v18.13.0

L'API MIMEParams fournit un accès en lecture et en écriture aux paramètres d'un MIMEType.

Constructeur: new MIMEParams()

Crée un nouvel objet MIMEParams avec des paramètres vides.

ESM

import { MIMEParams } from 'node:util'

const myParams = new MIMEParams()

CJS

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

const myParams = new MIMEParams()

mimeParams.delete(name)

• name <string>

Supprime toutes les paires nom-valeur dont le nom est name.

mimeParams.entries()

• Retourne : <Iterator>

Retourne un itérateur sur chaque paire nom-valeur des paramètres. Chaque élément de l'itérateur est un tableau JavaScript. Le premier élément du tableau est le nom, le second élément du tableau est la valeur.

mimeParams.get(name)

• name <string>
• Retourne : <string> | <null> Une chaîne de caractères ou null s'il n'y a pas de paire nom-valeur avec le name donné.

Retourne la valeur de la première paire nom-valeur dont le nom est name. Si aucune paire ne correspond, null est retourné.

mimeParams.has(name)

• name <string>
• Retourne : <boolean>

Retourne true s'il existe au moins une paire nom-valeur dont le nom est name.

mimeParams.keys()

• Retourne : <Iterator>

Retourne un itérateur sur les noms de chaque paire nom-valeur.

ESM

import { MIMEType } from 'node:util'

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

CJS

const { MIMEType } = require('node:util')

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

mimeParams.set(name, value)

• name <string>
• value <string>

Définit la valeur dans l'objet MIMEParams associé à name à value. S'il existe des paires nom-valeur préexistantes dont les noms sont name, définit la valeur de la première de ces paires à value.

ESM

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

CJS

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

mimeParams.values()

• Retourne : <Iterator>

Retourne un itérateur sur les valeurs de chaque paire nom-valeur.

mimeParams[@@iterator]()

• Retourne : <Iterator>

Alias pour mimeParams.entries().

ESM

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

CJS

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

util.parseArgs([config])

[Historique]

Version	Modifications
v22.4.0, v20.16.0	Ajout de la prise en charge des options négatives dans la configuration d'entrée config.
v20.0.0	L'API n'est plus expérimentale.
v18.11.0, v16.19.0	Ajout de la prise en charge des valeurs par défaut dans la configuration d'entrée config.
v18.7.0, v16.17.0	Ajout de la prise en charge du retour d'informations d'analyse détaillées à l'aide de tokens dans la configuration d'entrée config et des propriétés renvoyées.
v18.3.0, v16.17.0	Ajouté dans : v18.3.0, v16.17.0

• config <Objet> Utilisé pour fournir des arguments d'analyse et pour configurer l'analyseur. config prend en charge les propriétés suivantes :

  • args <string[]> Tableau de chaînes d'arguments. Valeur par défaut : process.argv avec execPath et filename supprimés.

  • options <Objet> Utilisé pour décrire les arguments connus de l'analyseur. Les clés de options sont les noms longs des options et les valeurs sont un <Objet> acceptant les propriétés suivantes :

  • type <string> Type d'argument, qui doit être soit boolean soit string.

  • multiple <boolean> Si cette option peut être fournie plusieurs fois. Si true, toutes les valeurs seront collectées dans un tableau. Si false, les valeurs de l'option sont celles qui gagnent. Valeur par défaut : false.

  • short <string> Un alias à caractère unique pour l'option.

  • default <string> | <boolean> | <string[]> | <boolean[]> La valeur d'option par défaut lorsqu'elle n'est pas définie par les arguments. Elle doit être du même type que la propriété type. Lorsque multiple est true, il doit s'agir d'un tableau.

  • strict <boolean> Une erreur doit-elle être levée lorsque des arguments inconnus sont rencontrés, ou lorsque des arguments qui ne correspondent pas au type configuré dans options sont passés. Valeur par défaut : true.

  • allowPositionals <boolean> Si cette commande accepte des arguments positionnels. Valeur par défaut : false si strict est true, sinon true.

  • allowNegative <boolean> Si true, permet de définir explicitement les options booléennes sur false en préfixant le nom de l'option par --no-. Valeur par défaut : false.

  • tokens <boolean> Retourne les jetons analysés. Ceci est utile pour étendre le comportement intégré, de l'ajout de contrôles supplémentaires au retraitement des jetons de différentes manières. Valeur par défaut : false.

• Retourne : <Objet> Les arguments de ligne de commande analysés :

  • values <Objet> Un mappage des noms d'options analysés avec leurs valeurs <string> ou <boolean>.
  • positionals <string[]> Arguments positionnels.
  • tokens <Objet[]> | <undefined> Voir la section jetons parseArgs. Renvoyé uniquement si config inclut tokens: true.

Fournit une API de niveau supérieur pour l'analyse des arguments de ligne de commande que l'interaction directe avec process.argv. Prend une spécification pour les arguments attendus et retourne un objet structuré avec les options et les positionnels analysés.

ESM

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

CJS

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

parseArgs tokens

Des informations détaillées sur l'analyse sont disponibles pour ajouter des comportements personnalisés en spécifiant tokens: true dans la configuration. Les jetons renvoyés ont des propriétés décrivant :

• tous les jetons

  • kind <string> L'un de : 'option', 'positional', ou 'option-terminator'.
  • index <number> Index de l'élément dans args contenant le jeton. Ainsi, l'argument source pour un jeton est args[token.index].

• jetons d'option

  • name <string> Nom long de l'option.
  • rawName <string> Comment l'option est utilisée dans args, comme -f de --foo.
  • value <string> | <undefined> Valeur de l'option spécifiée dans args. Indéfini pour les options booléennes.
  • inlineValue <boolean> | <undefined> Si la valeur de l'option est spécifiée en ligne, comme --foo=bar.

• jetons positionnels

  • value <string> La valeur de l'argument positionnel dans args (c'est-à-dire args[index]).

• jeton option-terminator

Les jetons renvoyés sont dans l'ordre où ils ont été rencontrés dans les arguments d'entrée. Les options qui apparaissent plus d'une fois dans args produisent un jeton pour chaque utilisation. Les groupes d'options courtes comme -xy se développent en un jeton pour chaque option. Ainsi, -xxx produit trois jetons.

Par exemple, pour ajouter la prise en charge d'une option niée comme --no-color (que allowNegative prend en charge lorsque l'option est de type boolean), les jetons renvoyés peuvent être retraités pour modifier la valeur stockée pour l'option niée.

ESM

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

// Retraitement des jetons d'option et remplacement des valeurs renvoyées.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Stocker foo:false pour --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Enregistrer à nouveau la valeur pour que la dernière gagne si à la fois --foo et --no-foo.
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })

CJS

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

// Retraitement des jetons d'option et remplacement des valeurs renvoyées.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Stocker foo:false pour --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Enregistrer à nouveau la valeur pour que la dernière gagne si à la fois --foo et --no-foo.
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })

Exemple d'utilisation montrant les options niées, et lorsqu'une option est utilisée de plusieurs manières, la dernière gagne.

$ 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)

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1.1 - Développement actif

Ajouté dans : v21.7.0, v20.12.0

• content <string>

Le contenu brut d'un fichier .env.

• Retourne : <Object>

Exemple de fichier .env :

CJS

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

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

ESM

import { parseEnv } from 'node:util'

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

util.promisify(original)

[Historique]

Version	Modifications
v20.8.0	L'appel de promisify sur une fonction qui retourne une Promise est déprécié.
v8.0.0	Ajouté dans : v8.0.0

• original <Function>
• Retourne : <Function>

Prend une fonction suivant le style de rappel courant avec gestion des erreurs, c’est-à-dire prenant un rappel (err, value) =\> ... comme dernier argument, et retourne une version qui retourne des promises.

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

const stat = util.promisify(fs.stat)
stat('.')
  .then(stats => {
    // Faire quelque chose avec `stats`
  })
  .catch(error => {
    // Gérer l'erreur.
  })

Ou, de manière équivalente en utilisant les fonctions async :

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(`Ce répertoire appartient à l'UID ${stats.uid}`)
}

callStat()

Si une propriété original[util.promisify.custom] est présente, promisify retournera sa valeur, voir Fonctions promisifiées personnalisées.

promisify() suppose que original est une fonction prenant un rappel comme dernier argument dans tous les cas. Si original n'est pas une fonction, promisify() lèvera une erreur. Si original est une fonction mais que son dernier argument n'est pas un rappel avec gestion des erreurs, un rappel avec gestion des erreurs lui sera quand même passé comme dernier argument.

L'utilisation de promisify() sur des méthodes de classe ou d'autres méthodes utilisant this peut ne pas fonctionner comme prévu sauf si elle est gérée spécialement :

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'

Fonctions personnalisées promisifiées

En utilisant le symbole util.promisify.custom, on peut outrepasser la valeur de retour de util.promisify() :

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])
// affiche 'true'

Cela peut être utile dans les cas où la fonction originale ne suit pas le format standard consistant à prendre une fonction de rappel avec gestion des erreurs comme dernier argument.

Par exemple, avec une fonction qui prend en entrée (foo, onSuccessCallback, onErrorCallback) :

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

Si promisify.custom est défini mais n'est pas une fonction, promisify() lèvera une erreur.

util.promisify.custom

[Historique]

Version	Modifications
v13.12.0, v12.16.2	Ceci est maintenant défini comme un symbole partagé.
v8.0.0	Ajouté dans : v8.0.0

• <symbole> qui peut être utilisé pour déclarer des variantes personnalisées promisifiées de fonctions, voir Fonctions personnalisées promisifiées.

En plus d'être accessible via util.promisify.custom, ce symbole est enregistré globalement et peut être accédé dans n'importe quel environnement sous la forme Symbol.for('nodejs.util.promisify.custom').

Par exemple, avec une fonction qui prend en entrée (foo, onSuccessCallback, onErrorCallback) :

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

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

util.stripVTControlCharacters(str)

Ajouté dans : v16.11.0

• str <string>
• Retourne : <string>

Retourne str sans les codes d'échappement ANSI.

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

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

[Stable : 2 - Stable]

Stable : 2 Stabilité : 2 - Stable.

[Historique]

Version	Modifications
v23.5.0	styleText est maintenant stable.
v22.8.0, v20.18.0	Respecte isTTY et les variables d'environnement telles que NO_COLORS, NODE_DISABLE_COLORS et FORCE_COLOR.
v21.7.0, v20.12.0	Ajouté dans : v21.7.0, v20.12.0

• format <string> | <Array> Un format de texte ou un tableau de formats de texte définis dans util.inspect.colors.
• text <string> Le texte à formater.
• options <Object>
  • validateStream <boolean> Lorsque true, stream est vérifié pour voir s'il peut gérer les couleurs. Défaut : true.
  • stream <Stream> Un flux qui sera validé pour voir s'il peut être colorié. Défaut : process.stdout.

Cette fonction retourne un texte formaté en tenant compte du format passé pour l'impression dans un terminal. Elle est consciente des capacités du terminal et agit en fonction de la configuration définie via les variables d'environnement NO_COLORS, NODE_DISABLE_COLORS et FORCE_COLOR.

ESM

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

const successMessage = styleText('green', 'Succès !')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  'Erreur ! Erreur !',
  // Valider si process.stderr a TTY
  { stream: stderr }
)
console.error(successMessage)

CJS

const { styleText } = require('node:util')
const { stderr } = require('node:process')

const successMessage = styleText('green', 'Succès !')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  'Erreur ! Erreur !',
  // Valider si process.stderr a TTY
  { stream: stderr }
)
console.error(successMessage)

util.inspect.colors fournit également des formats de texte tels que italic et underline, et vous pouvez les combiner :

console.log(util.styleText(['underline', 'italic'], 'Mon message souligné en italique'))

Lorsqu'un tableau de formats est passé, l'ordre du format appliqué est de gauche à droite, de sorte que le style suivant peut écraser le précédent.

console.log(
  util.styleText(['red', 'green'], 'texte') // vert
)

La liste complète des formats se trouve dans modificateurs.

Classe : util.TextDecoder

[Historique]

Version	Modifications
v11.0.0	La classe est désormais disponible sur l'objet global.
v8.3.0	Ajoutée dans : v8.3.0

Une implémentation de l'API TextDecoder de la norme d'encodage WHATWG.

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

Encodages WHATWG pris en charge

Conformément à la norme d'encodage WHATWG, les encodages pris en charge par l'API TextDecoder sont décrits dans les tableaux ci-dessous. Pour chaque encodage, un ou plusieurs alias peuvent être utilisés.

Différentes configurations de build Node.js prennent en charge différents ensembles d'encodages. (voir Internationalisation)

Encodages pris en charge par défaut (avec données ICU complètes)

Encodage	Alias
'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'

Encodages supportés lorsque Node.js est compilé avec l'option small-icu

Encodage	Alias
'utf-8'	'unicode-1-1-utf-8' , 'utf8'
'utf-16le'	'utf-16'
'utf-16be'

Encodages supportés lorsque ICU est désactivé

Encodage	Alias
'utf-8'	'unicode-1-1-utf-8' , 'utf8'
'utf-16le'	'utf-16'

L'encodage 'iso-8859-16' listé dans la norme d'encodage WHATWG n'est pas supporté.

new TextDecoder([encoding[, options]])

• encoding <string> Identifie l'encodage supporté par cette instance de TextDecoder. Défaut : 'utf-8'.
• options <Object>
  • fatal <boolean> true si les échecs de décodage sont fatals. Cette option n'est pas supportée lorsque ICU est désactivé (voir Internationalisation). Défaut : false.
  • ignoreBOM <boolean> Lorsque true, le TextDecoder inclura la marque d'ordre des octets dans le résultat décodé. Lorsque false, la marque d'ordre des octets sera supprimée de la sortie. Cette option est uniquement utilisée lorsque encoding est 'utf-8', 'utf-16be' ou 'utf-16le'. Défaut : false.

Crée une nouvelle instance TextDecoder. L'encodage peut spécifier l'un des encodages supportés ou un alias.

La classe TextDecoder est également disponible sur l'objet global.

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

• input <ArrayBuffer> | <DataView> | <TypedArray> Une instance ArrayBuffer, DataView ou TypedArray contenant les données encodées.

• options <Object>

  • stream <boolean> true si des blocs de données supplémentaires sont attendus. Défaut : false.

• Retourne : <string>

Décode l'entrée et retourne une chaîne. Si options.stream est true, les séquences d'octets incomplètes se produisant à la fin de l'entrée sont mises en mémoire tampon en interne et émises après l'appel suivant à textDecoder.decode().

Si textDecoder.fatal est true, les erreurs de décodage qui se produisent entraîneront le lancement d'une exception TypeError.

textDecoder.encoding

• <string>

L'encodage supporté par l'instance TextDecoder.

textDecoder.fatal

• <boolean>

La valeur sera true si les erreurs de décodage entraînent le lancement d'une erreur TypeError.

textDecoder.ignoreBOM

• <boolean>

La valeur sera true si le résultat du décodage inclut la marque d'ordre des octets.

Classe : util.TextEncoder

[Historique]

Version	Modifications
v11.0.0	La classe est maintenant disponible sur l'objet global.
v8.3.0	Ajoutée dans : v8.3.0

Une implémentation de l'API TextEncoder de la norme d'encodage WHATWG. Toutes les instances de TextEncoder ne prennent en charge que l'encodage UTF-8.

const encoder = new TextEncoder()
const uint8array = encoder.encode('ceci est une donnée')

La classe TextEncoder est également disponible sur l'objet global.

textEncoder.encode([input])

• input <string> Le texte à encoder. Valeur par défaut : une chaîne vide.
• Retourne : <Uint8Array>

Encode la chaîne input en UTF-8 et retourne un Uint8Array contenant les octets encodés.

textEncoder.encodeInto(src, dest)

Ajouté dans : v12.11.0

• src <string> Le texte à encoder.
• dest <Uint8Array> Le tableau pour contenir le résultat de l'encodage.
• Retourne : <Object>
  • read <number> Les unités de code Unicode lues de src.
  • written <number> Les octets UTF-8 écrits de dest.

Encode la chaîne src en UTF-8 dans le Uint8Array dest et retourne un objet contenant les unités de code Unicode lues et les octets UTF-8 écrits.

const encoder = new TextEncoder()
const src = 'ceci est une donnée'
const dest = new Uint8Array(10)
const { read, written } = encoder.encodeInto(src, dest)

textEncoder.encoding

• <string>

Encodage supporté par l'instance TextEncoder. Toujours réglé sur 'utf-8'.

util.toUSVString(string)

Ajouté dans : v16.8.0, v14.18.0

• string <string>

Retourne la chaîne string après avoir remplacé tous les points de code de substitution (ou de manière équivalente, toutes les unités de code de substitution non appariées) par le caractère de remplacement Unicode U+FFFD.

util.transferableAbortController()

Ajouté dans : v18.11.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Crée et retourne une instance <AbortController> dont le <AbortSignal> est marqué comme transférable et peut être utilisé avec structuredClone() ou postMessage().

util.transferableAbortSignal(signal)

Ajouté dans : v18.11.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

• signal <AbortSignal>
• Retourne : <AbortSignal>

Marque le <AbortSignal> donné comme transférable afin qu'il puisse être utilisé avec structuredClone() et postMessage().

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

util.aborted(signal, resource)

Ajouté dans : v19.7.0, v18.16.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

• signal <AbortSignal>
• resource <Object> Tout objet non nul lié à l'opération annulable et détenu faiblement. Si resource est collecté par le garbage collector avant l'annulation du signal, la promesse reste en attente, permettant à Node.js d'arrêter de la suivre. Cela aide à prévenir les fuites de mémoire dans les opérations longues ou non annulables.
• Retourne : <Promise>

Écoute l'événement d'annulation sur le signal fourni et retourne une promesse qui se résout lorsque le signal est annulé. Si resource est fourni, il référence faiblement l'objet associé à l'opération, donc si resource est collecté par le garbage collector avant l'annulation du signal, la promesse retournée restera en attente. Cela empêche les fuites de mémoire dans les opérations longues ou non annulables.

CJS

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

// Obtenir un objet avec un signal annulable, comme une ressource ou une opération personnalisée.
const dependent = obtainSomethingAbortable()

// Passer `dependent` comme ressource, indiquant que la promesse ne doit se résoudre
// que si `dependent` est toujours en mémoire lorsque le signal est annulé.
aborted(dependent.signal, dependent).then(() => {
  // Ce code s'exécute lorsque `dependent` est annulé.
  console.log('La ressource dépendante a été annulée.')
})

// Simuler un événement qui déclenche l'annulation.
dependent.on('event', () => {
  dependent.abort() // Cela entraînera la résolution de la promesse `aborted`.
})

ESM

import { aborted } from 'node:util'

// Obtenir un objet avec un signal annulable, comme une ressource ou une opération personnalisée.
const dependent = obtainSomethingAbortable()

// Passer `dependent` comme ressource, indiquant que la promesse ne doit se résoudre
// que si `dependent` est toujours en mémoire lorsque le signal est annulé.
aborted(dependent.signal, dependent).then(() => {
  // Ce code s'exécute lorsque `dependent` est annulé.
  console.log('La ressource dépendante a été annulée.')
})

// Simuler un événement qui déclenche l'annulation.
dependent.on('event', () => {
  dependent.abort() // Cela entraînera la résolution de la promesse `aborted`.
})

util.types

[Historique]

Version	Modifications
v15.3.0	Exposé en tant que require('util/types').
v10.0.0	Ajouté dans la version : v10.0.0

util.types fournit des vérifications de type pour différents types d'objets intégrés. Contrairement à instanceof ou Object.prototype.toString.call(value), ces vérifications n'inspectent pas les propriétés de l'objet accessibles depuis JavaScript (comme leur prototype), et ont généralement le coût supplémentaire d'un appel à C++.

Le résultat ne garantit généralement rien quant aux types de propriétés ou de comportement qu'une valeur expose en JavaScript. Elles sont principalement utiles pour les développeurs d'extensions qui préfèrent effectuer des vérifications de type en JavaScript.

L'API est accessible via require('node:util').types ou require('node:util/types').

util.types.isAnyArrayBuffer(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de ArrayBuffer ou SharedArrayBuffer.

Voir aussi util.types.isArrayBuffer() et util.types.isSharedArrayBuffer().

util.types.isAnyArrayBuffer(new ArrayBuffer()) // Retourne true
util.types.isAnyArrayBuffer(new SharedArrayBuffer()) // Retourne true

util.types.isArrayBufferView(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance d'une des vues ArrayBuffer, telles que les objets tableaux typés ou DataView. Équivalent à ArrayBuffer.isView().

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)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet arguments.

function foo() {
  util.types.isArgumentsObject(arguments) // Retourne true
}

util.types.isArrayBuffer(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de ArrayBuffer. Cela n'inclut pas les instances SharedArrayBuffer. Généralement, il est souhaitable de tester les deux ; voir util.types.isAnyArrayBuffer() pour cela.

util.types.isArrayBuffer(new ArrayBuffer()) // Retourne true
util.types.isArrayBuffer(new SharedArrayBuffer()) // Retourne false

util.types.isAsyncFunction(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une fonction asynchrone. Cela ne fait que rapporter ce que le moteur JavaScript voit ; en particulier, la valeur de retour peut ne pas correspondre au code source d'origine si un outil de transpilation a été utilisé.

util.types.isAsyncFunction(function foo() {}) // Retourne false
util.types.isAsyncFunction(async function foo() {}) // Retourne true

util.types.isBigInt64Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance de BigInt64Array.

util.types.isBigInt64Array(new BigInt64Array()) // Retourne true
util.types.isBigInt64Array(new BigUint64Array()) // Retourne false

util.types.isBigIntObject(value)

Ajouté dans : v10.4.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet BigInt, par exemple créé par Object(BigInt(123)).

util.types.isBigIntObject(Object(BigInt(123))) // Retourne true
util.types.isBigIntObject(BigInt(123)) // Retourne false
util.types.isBigIntObject(123) // Retourne false

util.types.isBigUint64Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance de BigUint64Array.

util.types.isBigUint64Array(new BigInt64Array()) // Retourne false
util.types.isBigUint64Array(new BigUint64Array()) // Retourne true

util.types.isBooleanObject(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet booléen, par exemple créé par new Boolean().

util.types.isBooleanObject(false) // Retourne false
util.types.isBooleanObject(true) // Retourne false
util.types.isBooleanObject(new Boolean(false)) // Retourne true
util.types.isBooleanObject(new Boolean(true)) // Retourne true
util.types.isBooleanObject(Boolean(false)) // Retourne false
util.types.isBooleanObject(Boolean(true)) // Retourne false

util.types.isBoxedPrimitive(value)

Ajouté dans : v10.11.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet primitif boxed, par exemple créé par new Boolean(), new String() ou Object(Symbol()).

Par exemple :

util.types.isBoxedPrimitive(false) // Retourne false
util.types.isBoxedPrimitive(new Boolean(false)) // Retourne true
util.types.isBoxedPrimitive(Symbol('foo')) // Retourne false
util.types.isBoxedPrimitive(Object(Symbol('foo'))) // Retourne true
util.types.isBoxedPrimitive(Object(BigInt(5))) // Retourne true

util.types.isCryptoKey(value)

Ajouté dans : v16.2.0

• value <Object>
• Retourne : <boolean>

Retourne true si value est un <CryptoKey>, false sinon.

util.types.isDataView(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de DataView.

const ab = new ArrayBuffer(20)
util.types.isDataView(new DataView(ab)) // Retourne true
util.types.isDataView(new Float64Array()) // Retourne false

Voir aussi ArrayBuffer.isView().

util.types.isDate(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Date.

util.types.isDate(new Date()) // Retourne true

util.types.isExternal(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une valeur External native.

Une valeur External native est un type d'objet spécial qui contient un pointeur C++ brut (void*) pour l'accès depuis le code natif, et n'a pas d'autres propriétés. De tels objets sont créés soit par les éléments internes de Node.js, soit par des modules natifs. En JavaScript, ce sont des objets gelés avec un prototype null.

#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)
...

const native = require('napi_addon.node')
const data = native.myNapi()
util.types.isExternal(data) // retourne true
util.types.isExternal(0) // retourne false
util.types.isExternal(new String('foo')) // retourne false

Pour plus d'informations sur napi_create_external, reportez-vous à napi_create_external().

util.types.isFloat32Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Float32Array.

util.types.isFloat32Array(new ArrayBuffer()) // Retourne false
util.types.isFloat32Array(new Float32Array()) // Retourne true
util.types.isFloat32Array(new Float64Array()) // Retourne false

util.types.isFloat64Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Float64Array.

util.types.isFloat64Array(new ArrayBuffer()) // Retourne false
util.types.isFloat64Array(new Uint8Array()) // Retourne false
util.types.isFloat64Array(new Float64Array()) // Retourne true

util.types.isGeneratorFunction(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une fonction génératrice. Cela ne fait que renvoyer ce que le moteur JavaScript voit ; en particulier, la valeur de retour peut ne pas correspondre au code source d’origine si un outil de transpilation a été utilisé.

util.types.isGeneratorFunction(function foo() {}) // Retourne false
util.types.isGeneratorFunction(function* foo() {}) // Retourne true

util.types.isGeneratorObject(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet générateur tel que renvoyé par une fonction génératrice intégrée. Cela ne fait que renvoyer ce que le moteur JavaScript voit ; en particulier, la valeur de retour peut ne pas correspondre au code source d’origine si un outil de transpilation a été utilisé.

function* foo() {}
const generator = foo()
util.types.isGeneratorObject(generator) // Retourne true

util.types.isInt8Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Int8Array.

util.types.isInt8Array(new ArrayBuffer()) // Retourne false
util.types.isInt8Array(new Int8Array()) // Retourne true
util.types.isInt8Array(new Float64Array()) // Retourne false

util.types.isInt16Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance Int16Array intégrée.

util.types.isInt16Array(new ArrayBuffer()) // Retourne false
util.types.isInt16Array(new Int16Array()) // Retourne true
util.types.isInt16Array(new Float64Array()) // Retourne false

util.types.isInt32Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance Int32Array intégrée.

util.types.isInt32Array(new ArrayBuffer()) // Retourne false
util.types.isInt32Array(new Int32Array()) // Retourne true
util.types.isInt32Array(new Float64Array()) // Retourne false

util.types.isKeyObject(value)

Ajouté dans : v16.2.0

• value <Object>
• Retourne : <boolean>

Retourne true si value est un <KeyObject>, false sinon.

util.types.isMap(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance Map intégrée.

util.types.isMap(new Map()) // Retourne true

util.types.isMapIterator(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un itérateur retourné pour une instance Map intégrée.

const map = new Map()
util.types.isMapIterator(map.keys()) // Retourne true
util.types.isMapIterator(map.values()) // Retourne true
util.types.isMapIterator(map.entries()) // Retourne true
util.types.isMapIterator(map[Symbol.iterator]()) // Retourne true

util.types.isModuleNamespaceObject(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance d'un Objet espace de noms de module.

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

util.types.isModuleNamespaceObject(ns) // Retourne true

util.types.isNativeError(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur a été retournée par le constructeur d'un type Error intégré.

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

Les sous-classes des types d'erreur natifs sont également des erreurs natives :

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

Le fait qu'une valeur soit instanceof une classe d'erreur native n'est pas équivalent à ce que isNativeError() retourne true pour cette valeur. isNativeError() retourne true pour les erreurs provenant d'un realm différent tandis que instanceof Error retourne false pour ces erreurs :

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

Inversement, isNativeError() retourne false pour tous les objets qui n'ont pas été retournés par le constructeur d'une erreur native. Cela inclut les valeurs qui sont instanceof des erreurs natives :

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

util.types.isNumberObject(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet numérique, par exemple créé par new Number().

util.types.isNumberObject(0) // Retourne false
util.types.isNumberObject(new Number(0)) // Retourne true

util.types.isPromise(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance de Promise intégrée.

util.types.isPromise(Promise.resolve(42)) // Retourne true

util.types.isProxy(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance de Proxy.

const target = {}
const proxy = new Proxy(target, {})
util.types.isProxy(target) // Retourne false
util.types.isProxy(proxy) // Retourne true

util.types.isRegExp(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet expression régulière.

util.types.isRegExp(/abc/) // Retourne true
util.types.isRegExp(new RegExp('abc')) // Retourne true

util.types.isSet(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Set.

util.types.isSet(new Set()) // Retourne true

util.types.isSetIterator(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un itérateur renvoyé pour une instance intégrée de Set.

const set = new Set()
util.types.isSetIterator(set.keys()) // Retourne true
util.types.isSetIterator(set.values()) // Retourne true
util.types.isSetIterator(set.entries()) // Retourne true
util.types.isSetIterator(set[Symbol.iterator]()) // Retourne true

util.types.isSharedArrayBuffer(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de SharedArrayBuffer. Cela n'inclut pas les instances ArrayBuffer. Généralement, il est souhaitable de tester les deux ; voir util.types.isAnyArrayBuffer() pour cela.

util.types.isSharedArrayBuffer(new ArrayBuffer()) // Retourne false
util.types.isSharedArrayBuffer(new SharedArrayBuffer()) // Retourne true

util.types.isStringObject(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet chaîne de caractères, par exemple créé par new String().

util.types.isStringObject('foo') // Retourne false
util.types.isStringObject(new String('foo')) // Retourne true

util.types.isSymbolObject(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est un objet symbole, créé en appelant Object() sur une primitive Symbol.

const symbol = Symbol('foo')
util.types.isSymbolObject(symbol) // Retourne false
util.types.isSymbolObject(Object(symbol)) // Retourne true

util.types.isTypedArray(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de TypedArray.

util.types.isTypedArray(new ArrayBuffer()) // Retourne false
util.types.isTypedArray(new Uint8Array()) // Retourne true
util.types.isTypedArray(new Float64Array()) // Retourne true

Voir aussi ArrayBuffer.isView().

util.types.isUint8Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Uint8Array.

util.types.isUint8Array(new ArrayBuffer()) // Retourne false
util.types.isUint8Array(new Uint8Array()) // Retourne true
util.types.isUint8Array(new Float64Array()) // Retourne false

util.types.isUint8ClampedArray(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Uint8ClampedArray.

util.types.isUint8ClampedArray(new ArrayBuffer()) // Retourne false
util.types.isUint8ClampedArray(new Uint8ClampedArray()) // Retourne true
util.types.isUint8ClampedArray(new Float64Array()) // Retourne false

util.types.isUint16Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Uint16Array.

util.types.isUint16Array(new ArrayBuffer()) // Retourne false
util.types.isUint16Array(new Uint16Array()) // Retourne true
util.types.isUint16Array(new Float64Array()) // Retourne false

util.types.isUint32Array(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de Uint32Array.

util.types.isUint32Array(new ArrayBuffer()) // Retourne false
util.types.isUint32Array(new Uint32Array()) // Retourne true
util.types.isUint32Array(new Float64Array()) // Retourne false

util.types.isWeakMap(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance intégrée de WeakMap.

util.types.isWeakMap(new WeakMap()) // Retourne true

util.types.isWeakSet(value)

Ajouté dans : v10.0.0

• value <any>
• Retourne : <boolean>

Retourne true si la valeur est une instance de WeakSet intégré.

util.types.isWeakSet(new WeakSet()) // Retourne true

API obsolètes

Les API suivantes sont obsolètes et ne devraient plus être utilisées. Les applications et modules existants doivent être mis à jour pour trouver des approches alternatives.

util._extend(target, source)

Ajouté dans : v0.7.5

Obsolète depuis : v6.0.0

[Stable : 0 - Obsolete]

Stable : 0 Stabilité : 0 - Obsolete : Utilisez Object.assign() à la place.

• target <Object>
• source <Object>

La méthode util._extend() n'était pas destinée à être utilisée en dehors des modules Node.js internes. La communauté l'a néanmoins trouvée et utilisée.

Elle est obsolète et ne doit pas être utilisée dans le nouveau code. JavaScript possède des fonctionnalités intégrées très similaires grâce à Object.assign().

util.isArray(object)

Ajouté dans : v0.6.0

Obsolète depuis : v4.0.0

[Stable : 0 - Obsolete]

Stable : 0 Stabilité : 0 - Obsolete : Utilisez Array.isArray() à la place.

• object <any>
• Retourne : <boolean>

Alias de Array.isArray().

Retourne true si l'objet donné est un Array. Sinon, retourne false.

const util = require('node:util')

util.isArray([])
// Retourne : true
util.isArray(new Array())
// Retourne : true
util.isArray({})
// Retourne : false