Util

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Codice sorgente: lib/util.js

Il modulo node:util supporta le esigenze delle API interne di Node.js. Molte delle utility sono utili anche per gli sviluppatori di applicazioni e moduli. Per accedervi:

const util = require('node:util')

util.callbackify(original)

Aggiunto in: v8.2.0

• original <Funzione> Una funzione async
• Restituisce: <Funzione> una funzione in stile callback

Prende una funzione async (o una funzione che restituisce una Promise) e restituisce una funzione che segue lo stile di callback error-first, ovvero che accetta un callback (err, value) =\> ... come ultimo argomento. Nel callback, il primo argomento sarà la ragione del rifiuto (o null se la Promise è stata risolta), e il secondo argomento sarà il valore risolto.

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

Stamperà:

hello world

Il callback viene eseguito in modo asincrono e avrà una traccia dello stack limitata. Se il callback genera un'eccezione, il processo emetterà un evento 'uncaughtException' e, se non gestito, terminerà.

Dato che null ha un significato speciale come primo argomento di un callback, se una funzione avvolta rifiuta una Promise con un valore falsy come ragione, il valore viene avvolto in un Error con il valore originale memorizzato in un campo chiamato reason.

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

callbackFunction((err, ret) => {
  // Quando la Promise è stata rifiutata con `null` viene avvolta con un Error e
  // il valore originale è memorizzato in `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null // true
})

util.debuglog(section[, callback])

Aggiunto in: v0.11.3

• section <string> Una stringa che identifica la parte dell'applicazione per cui viene creata la funzione debuglog.
• callback <Function> Una callback invocata la prima volta che la funzione di logging viene chiamata con un argomento funzione che è una funzione di logging più ottimizzata.
• Restituisce: <Function> La funzione di logging

Il metodo util.debuglog() viene utilizzato per creare una funzione che scrive condizionalmente messaggi di debug su stderr in base all'esistenza della variabile di ambiente NODE_DEBUG. Se il nome della section appare nel valore di quella variabile di ambiente, la funzione restituita funziona in modo simile a console.error(). In caso contrario, la funzione restituita è una no-op.

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

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

Se questo programma viene eseguito con NODE_DEBUG=foo nell'ambiente, verrà visualizzato un output simile a:

FOO 3245: hello from foo [123]

dove 3245 è l'ID del processo. Se non viene eseguito con quella variabile di ambiente impostata, non verrà stampato nulla.

La section supporta anche i caratteri jolly:

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

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

se viene eseguito con NODE_DEBUG=foo* nell'ambiente, verrà visualizzato un output simile a:

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

È possibile specificare più nomi di section separati da virgole nella variabile di ambiente NODE_DEBUG: NODE_DEBUG=fs,net,tls.

L'argomento callback opzionale può essere utilizzato per sostituire la funzione di logging con una funzione diversa che non ha alcuna inizializzazione o wrapping non necessario.

const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
  // Sostituisci con una funzione di logging che ottimizza
  // il test se la sezione è abilitata
  debuglog = debug
})

debuglog().enabled

Aggiunto in: v14.9.0

• <boolean>

Il getter util.debuglog().enabled viene utilizzato per creare un test che può essere usato nelle condizioni basate sull'esistenza della variabile di ambiente NODE_DEBUG. Se il nome della section appare nel valore di tale variabile di ambiente, il valore restituito sarà true. Altrimenti, il valore restituito sarà false.

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

Se questo programma viene eseguito con NODE_DEBUG=foo nell'ambiente, allora produrrà un output simile a:

hello from foo [123]

util.debug(section)

Aggiunto in: v14.9.0

Alias per util.debuglog. L'utilizzo permette una leggibilità che non implica la registrazione quando si usa solo util.debuglog().enabled.

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

[Cronologia]

Versione	Cambiamenti
v10.0.0	Gli avvisi di deprecazione vengono emessi solo una volta per ogni codice.
v0.8.0	Aggiunto in: v0.8.0

• fn <Function> La funzione che sta per essere deprecata.
• msg <string> Un messaggio di avviso da visualizzare quando viene invocata la funzione deprecata.
• code <string> Un codice di deprecazione. Vedi l'elenco delle API deprecate per un elenco di codici.
• Restituisce: <Function> La funzione deprecata racchiusa per emettere un avviso.

Il metodo util.deprecate() racchiude fn (che può essere una funzione o una classe) in modo tale che sia contrassegnata come deprecata.

const util = require('node:util')

exports.obsoleteFunction = util.deprecate(() => {
  // Fai qualcosa qui.
}, 'obsoleteFunction() è deprecata. Usa newShinyFunction() invece.')

Quando viene chiamato, util.deprecate() restituirà una funzione che emetterà un DeprecationWarning usando l'evento 'warning'. L'avviso verrà emesso e stampato su stderr la prima volta che viene chiamata la funzione restituita. Dopo che l'avviso è stato emesso, la funzione racchiusa viene chiamata senza emettere un avviso.

Se lo stesso code opzionale viene fornito in più chiamate a util.deprecate(), l'avviso verrà emesso solo una volta per quel code.

const util = require('node:util')

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001')
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001')
fn1() // Emette un avviso di deprecazione con codice DEP0001
fn2() // Non emette un avviso di deprecazione perché ha lo stesso codice

Se vengono utilizzati i flag della riga di comando --no-deprecation o --no-warnings, o se la proprietà process.noDeprecation è impostata su true prima del primo avviso di deprecazione, il metodo util.deprecate() non fa nulla.

Se i flag della riga di comando --trace-deprecation o --trace-warnings sono impostati, o la proprietà process.traceDeprecation è impostata su true, un avviso e una traccia dello stack vengono stampati su stderr la prima volta che viene chiamata la funzione deprecata.

Se il flag della riga di comando --throw-deprecation è impostato, o la proprietà process.throwDeprecation è impostata su true, verrà sollevata un'eccezione quando viene chiamata la funzione deprecata.

Il flag della riga di comando --throw-deprecation e la proprietà process.throwDeprecation hanno la precedenza su --trace-deprecation e process.traceDeprecation.

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

[Cronologia]

Versione	Modifiche
v12.11.0	Lo specificatore %c ora viene ignorato.
v12.0.0	L'argomento format viene ora considerato come tale solo se contiene effettivamente specificatori di formato.
v12.0.0	Se l'argomento format non è una stringa di formato, la formattazione della stringa di output non dipende più dal tipo del primo argomento. Questa modifica rimuove le virgolette precedentemente presenti nelle stringhe in output quando il primo argomento non era una stringa.
v11.4.0	Gli specificatori %d, %f e %i ora supportano correttamente i Simboli.
v11.4.0	La profondità di depth dello specificatore %o ha di nuovo la profondità predefinita di 4.
v11.0.0	L'opzione depth dello specificatore %o ora ritornerà alla profondità predefinita.
v10.12.0	Gli specificatori %d e %i ora supportano BigInt.
v8.4.0	Gli specificatori %o e %O sono ora supportati.
v0.5.3	Aggiunto in: v0.5.3

• format <stringa> Una stringa di formato di tipo printf.

Il metodo util.format() restituisce una stringa formattata usando il primo argomento come stringa di formato di tipo printf, che può contenere zero o più specificatori di formato. Ogni specificatore viene sostituito con il valore convertito dall'argomento corrispondente. Gli specificatori supportati sono:

• %s: String verrà utilizzato per convertire tutti i valori tranne BigInt, Object e -0. I valori BigInt saranno rappresentati con una n e gli oggetti che non hanno una funzione toString definita dall'utente vengono ispezionati usando util.inspect() con le opzioni { depth: 0, colors: false, compact: 3 }.
• %d: Number verrà utilizzato per convertire tutti i valori tranne BigInt e Symbol.
• %i: parseInt(value, 10) viene utilizzato per tutti i valori tranne BigInt e Symbol.
• %f: parseFloat(value) viene utilizzato per tutti i valori tranne Symbol.
• %j: JSON. Sostituito con la stringa '[Circular]' se l'argomento contiene riferimenti circolari.
• %o: Object. Una rappresentazione di stringa di un oggetto con formattazione generica di oggetti JavaScript. Simile a util.inspect() con le opzioni { showHidden: true, showProxy: true }. Questo mostrerà l'oggetto completo, comprese le proprietà non enumerabili e i proxy.
• %O: Object. Una rappresentazione di stringa di un oggetto con formattazione generica di oggetti JavaScript. Simile a util.inspect() senza opzioni. Questo mostrerà l'oggetto completo, non comprese le proprietà non enumerabili e i proxy.
• %c: CSS. Questo specificatore viene ignorato e ignorerà qualsiasi CSS passato.
• %%: segno di percentuale singolo ('%'). Questo non consuma alcun argomento.
• Restituisce: <stringa> La stringa formattata

Se uno specificatore non ha un argomento corrispondente, non viene sostituito:

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

I valori che non fanno parte della stringa di formato vengono formattati usando util.inspect() se il loro tipo non è string.

Se vengono passati più argomenti al metodo util.format() rispetto al numero di specificatori, gli argomenti extra vengono concatenati alla stringa restituita, separati da spazi:

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

Se il primo argomento non contiene uno specificatore di formato valido, util.format() restituisce una stringa che è la concatenazione di tutti gli argomenti separati da spazi:

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

Se viene passato un solo argomento a util.format(), viene restituito così com'è senza alcuna formattazione:

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

util.format() è un metodo sincrono destinato come strumento di debug. Alcuni valori di input possono avere un significativo overhead di prestazioni che possono bloccare il loop degli eventi. Utilizzare questa funzione con cautela e mai in un percorso di codice critico.

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

Aggiunto in: v10.0.0

• inspectOptions <Object>
• format <string>

Questa funzione è identica a util.format(), eccetto per il fatto che accetta un argomento inspectOptions che specifica le opzioni passate a util.inspect().

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 })
// Restituisce 'See object { foo: 42 }', dove `42` è colorato come un numero
// quando stampato su un terminale.

util.getCallSites(frameCountOrOptions, [options])

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1.1 - Sviluppo attivo

[Cronologia]

Versione	Modifiche
v23.3.0	L'API è rinominata da util.getCallSite a util.getCallSites().
v22.9.0	Aggiunto in: v22.9.0

• frameCount <number> Numero opzionale di frame da acquisire come oggetti del sito di chiamata. Predefinito: 10. L'intervallo consentito è compreso tra 1 e 200.

• options <Object> Opzionale

  • sourceMap <boolean> Ricostruisce la posizione originale nella traccia dello stack dalla source-map. Abilitato per impostazione predefinita con il flag --enable-source-maps.

• Restituisce: <Object[]> Una matrice di oggetti del sito di chiamata

  • functionName <string> Restituisce il nome della funzione associata a questo sito di chiamata.
  • scriptName <string> Restituisce il nome della risorsa che contiene lo script per la funzione di questo sito di chiamata.
  • lineNumber <number> Restituisce il numero, a partire da 1, della riga per la chiamata di funzione associata.
  • column <number> Restituisce l'offset di colonna, a partire da 1, sulla riga per la chiamata di funzione associata.

Restituisce una matrice di oggetti del sito di chiamata contenenti lo stack della funzione chiamante.

const util = require('node:util')

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

  console.log('Siti di chiamata:')
  callSites.forEach((callSite, index) => {
    console.log(`Sito di chiamata ${index + 1}:`)
    console.log(`Nome funzione: ${callSite.functionName}`)
    console.log(`Nome script: ${callSite.scriptName}`)
    console.log(`Numero riga: ${callSite.lineNumber}`)
    console.log(`Numero colonna: ${callSite.column}`)
  })
  // Sito di chiamata 1:
  // Nome funzione: exampleFunction
  // Nome script: /home/example.js
  // Numero riga: 5
  // Numero colonna: 26

  // Sito di chiamata 2:
  // Nome funzione: anotherFunction
  // Nome script: /home/example.js
  // Numero riga: 22
  // Numero colonna: 3

  // ...
}

// Una funzione per simulare un altro livello di stack
function anotherFunction() {
  exampleFunction()
}

anotherFunction()

È possibile ricostruire le posizioni originali impostando l'opzione sourceMap su true. Se la source map non è disponibile, la posizione originale sarà la stessa della posizione corrente. Quando il flag --enable-source-maps è abilitato, ad esempio quando si usa --experimental-transform-types, sourceMap sarà true per impostazione predefinita.

import util from 'node:util'

interface Foo {
  foo: string
}

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

// Con sourceMap:
// Nome funzione: ''
// Nome script: example.js
// Numero riga: 7
// Numero colonna: 26

// Senza sourceMap:
// Nome funzione: ''
// Nome script: example.js
// Numero riga: 2
// Numero colonna: 26

util.getSystemErrorName(err)

Aggiunto in: v9.7.0

• err <number>
• Restituisce: <string>

Restituisce il nome stringa per un codice di errore numerico proveniente da un'API Node.js. La mappatura tra codici di errore e nomi di errore dipende dalla piattaforma. Vedere Errori di sistema comuni per i nomi degli errori comuni.

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

util.getSystemErrorMap()

Aggiunto in: v16.0.0, v14.17.0

• Restituisce: <Map>

Restituisce una Mappa di tutti i codici di errore di sistema disponibili dall'API Node.js. La mappatura tra codici di errore e nomi di errore dipende dalla piattaforma. Vedere Errori di sistema comuni per i nomi degli errori comuni.

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)

Aggiunto in: v23.1.0

• err <number>
• Restituisce: <string>

Restituisce il messaggio di stringa per un codice di errore numerico proveniente da un'API Node.js. La mappatura tra codici di errore e messaggi di stringa dipende dalla piattaforma.

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)

[Cronologia]

Versione	Modifiche
v5.0.0	Il parametro constructor può ora riferirsi a una classe ES6.
v0.3.0	Aggiunto in: v0.3.0

[Stabile: 3 - Eredità]

Stabile: 3 Stabilità: 3 - Eredità: Utilizzare la sintassi delle classi ES2015 e la parola chiave extends invece.

• constructor <Function>
• superConstructor <Function>

L'utilizzo di util.inherits() è sconsigliato. Si prega di utilizzare le parole chiave ES6 class ed extends per ottenere il supporto dell'ereditarietà a livello di linguaggio. Si noti inoltre che i due stili sono semanticamente incompatibili.

Ereditare i metodi del prototipo da un costruttore in un altro. Il prototipo di constructor sarà impostato su un nuovo oggetto creato da superConstructor.

Questo aggiunge principalmente una convalida dell'input in cima a Object.setPrototypeOf(constructor.prototype, superConstructor.prototype). Come ulteriore comodità, superConstructor sarà accessibile tramite la proprietà 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(`Dati ricevuti: "${data}"`)
})
stream.write('Funziona!') // Dati ricevuti: "Funziona!"

Esempio ES6 usando class ed 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(`Dati ricevuti: "${data}"`)
})
stream.write('Con ES6')

util.inspect(oggetto[, opzioni])

util.inspect(oggetto[, showHidden[, profondità[, colori]]])

[Cronologia]

Versione	Modifiche
v16.18.0	Aggiunto supporto per maxArrayLength durante l'ispezione di Set e Map.
v17.3.0, v16.14.0	L'opzione numericSeparator è ora supportata.
v13.0.0	I riferimenti circolari ora includono un marcatore per il riferimento.
v14.6.0, v12.19.0	Se oggetto proviene da un diverso vm.Context, una funzione di ispezione personalizzata su di esso non riceverà più argomenti specifici del contesto.
v13.13.0, v12.17.0	L'opzione maxStringLength è ora supportata.
v13.5.0, v12.16.0	Le proprietà del prototipo definite dall'utente vengono ispezionate nel caso in cui showHidden sia true.
v12.0.0	Il valore predefinito delle opzioni compact è cambiato in 3 e il valore predefinito delle opzioni breakLength è cambiato in 80.
v12.0.0	Le proprietà interne non appaiono più nell'argomento di contesto di una funzione di ispezione personalizzata.
v11.11.0	L'opzione compact accetta numeri per una nuova modalità di output.
v11.7.0	Gli ArrayBuffer ora mostrano anche i loro contenuti binari.
v11.5.0	L'opzione getters è ora supportata.
v11.4.0	Il valore predefinito di depth è tornato a 2.
v11.0.0	Il valore predefinito di depth è cambiato in 20.
v11.0.0	L'output dell'ispezione è ora limitato a circa 128 MiB. I dati superiori a tale dimensione non saranno completamente ispezionati.
v10.12.0	L'opzione sorted è ora supportata.
v10.6.0	L'ispezione di liste concatenate e oggetti simili è ora possibile fino alla dimensione massima dello stack di chiamate.
v10.0.0	Le voci WeakMap e WeakSet possono ora essere ispezionate.
v9.9.0	L'opzione compact è ora supportata.
v6.6.0	Le funzioni di ispezione personalizzate possono ora restituire this.
v6.3.0	L'opzione breakLength è ora supportata.
v6.1.0	L'opzione maxArrayLength è ora supportata; in particolare, le array lunghe vengono troncate per impostazione predefinita.
v6.1.0	L'opzione showProxy è ora supportata.
v0.3.0	Aggiunto in: v0.3.0

• oggetto <qualsiasi> Qualsiasi primitivo JavaScript o Oggetto.

• opzioni <Oggetto>

  • showHidden <booleano> Se true, i simboli e le proprietà non enumerabili di oggetto sono inclusi nel risultato formattato. Le voci WeakMap e WeakSet sono anche incluse, così come le proprietà del prototipo definite dall'utente (escludendo le proprietà del metodo). Predefinito: false.
  • profondità <numero> Specifica il numero di volte in cui eseguire la ricorsione durante la formattazione di oggetto. Questo è utile per ispezionare oggetti di grandi dimensioni. Per eseguire la ricorsione fino alla dimensione massima dello stack di chiamate, passare Infinity o null. Predefinito: 2.
  • colori <booleano> Se true, l'output è stilizzato con codici di colore ANSI. I colori sono personalizzabili. Vedere Personalizzazione dei colori di util.inspect. Predefinito: false.
  • customInspect <booleano> Se false, le funzioni [util.inspect.custom](profondità, opts, inspect) non vengono invocate. Predefinito: true.
  • showProxy <booleano> Se true, l'ispezione di Proxy include gli oggetti target e handler. Predefinito: false.
  • maxArrayLength <intero> Specifica il numero massimo di elementi Array, TypedArray, Map, Set, WeakMap e WeakSet da includere durante la formattazione. Impostare su null o Infinity per mostrare tutti gli elementi. Impostare su 0 o un valore negativo per non mostrare alcun elemento. Predefinito: 100.
  • maxStringLength <intero> Specifica il numero massimo di caratteri da includere durante la formattazione. Impostare su null o Infinity per mostrare tutti gli elementi. Impostare su 0 o un valore negativo per non mostrare alcun carattere. Predefinito: 10000.
  • breakLength <intero> La lunghezza alla quale i valori di input vengono suddivisi su più righe. Impostare su Infinity per formattare l'input come una singola riga (in combinazione con compact impostato su true o qualsiasi numero >= 1). Predefinito: 80.
  • compact <booleano> | <intero> Impostando questo valore su false, ogni chiave dell'oggetto viene visualizzata su una nuova riga. Verrà interrotto su nuove righe nel testo più lungo di breakLength. Se impostato su un numero, gli elementi interni più n vengono uniti su una singola riga a condizione che tutte le proprietà rientrino in breakLength. Anche gli elementi di array corti vengono raggruppati insieme. Per maggiori informazioni, vedere l'esempio seguente. Predefinito: 3.
  • sorted <booleano> | <Funzione> Se impostato su true o su una funzione, tutte le proprietà di un oggetto e le voci Set e Map vengono ordinate nella stringa risultante. Se impostato su true, viene utilizzata l'ordinamento predefinito. Se impostato su una funzione, viene utilizzato come funzione di confronto.
  • getters <booleano> | <stringa> Se impostato su true, i getter vengono ispezionati. Se impostato su 'get', vengono ispezionati solo i getter senza un setter corrispondente. Se impostato su 'set', vengono ispezionati solo i getter con un setter corrispondente. Questo potrebbe causare effetti collaterali a seconda della funzione getter. Predefinito: false.
  • numericSeparator <booleano> Se impostato su true, viene utilizzato un trattino basso per separare ogni tre cifre in tutti i bigint e i numeri. Predefinito: false.

• Restituisce: <stringa> La rappresentazione di oggetto.

Il metodo util.inspect() restituisce una rappresentazione di stringa di oggetto destinata al debug. L'output di util.inspect può cambiare in qualsiasi momento e non dovrebbe essere considerato programmaticamente. È possibile passare ulteriori opzioni che modificano il risultato. util.inspect() utilizzerà il nome del costruttore e/o @@toStringTag per creare un tag identificativo per un valore ispezionato.

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

I riferimenti circolari puntano al loro ancoraggio utilizzando un indice di riferimento:

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'esempio seguente ispeziona tutte le proprietà dell'oggetto util:

const util = require('node:util')

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

L'esempio seguente evidenzia l'effetto dell'opzione 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 [...]', // Una riga lunga
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Impostare `compact` su false o su un intero crea un output più leggibile.
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'
//   }
// }

// Impostare `breakLength` ad esempio a 150 stamperà il testo "Lorem ipsum" su una
// singola riga.

L'opzione showHidden consente di ispezionare le voci WeakMap e WeakSet. Se ci sono più voci di maxArrayLength, non vi è alcuna garanzia su quali voci vengono visualizzate. Ciò significa che il recupero delle stesse voci WeakSet due volte potrebbe comportare un output diverso. Inoltre, le voci senza rimanenti riferimenti forti possono essere eliminate dalla garbage collection in qualsiasi momento.

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'opzione sorted garantisce che l'ordine di inserimento delle proprietà di un oggetto non influisca sul risultato di util.inspect().

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

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

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

L'opzione numericSeparator aggiunge un trattino basso ogni tre cifre a tutti i numeri.

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() è un metodo sincrono destinato al debug. La sua lunghezza di output massima è di circa 128 MiB. Gli input che generano un output più lungo verranno troncati.

Personalizzazione dei colori di util.inspect

L'output a colori (se abilitato) di util.inspect è personalizzabile globalmente tramite le proprietà util.inspect.styles e util.inspect.colors.

util.inspect.styles è una mappa che associa un nome di stile a un colore da util.inspect.colors.

Gli stili predefiniti e i colori associati sono:

• bigint: yellow
• boolean: yellow
• date: magenta
• module: underline
• name: (nessuna formattazione)
• null: bold
• number: yellow
• regexp: red
• special: cyan (es., Proxies)
• string: green
• symbol: green
• undefined: grey

La formattazione a colori utilizza codici di controllo ANSI che potrebbero non essere supportati su tutti i terminali. Per verificare il supporto del colore utilizzare tty.hasColors().

I codici di controllo predefiniti sono elencati di seguito (raggruppati come "Modificatori", "Colori di primo piano" e "Colori di sfondo").

Modificatori

Il supporto dei modificatori varia a seconda dei terminali. Verranno per lo più ignorati, se non supportati.

• reset - Regola tutti i modificatori (colore) sui loro valori predefiniti
• bold - Rende il testo in grassetto
• italic - Rende il testo corsivo
• underline - Sottolinea il testo
• strikethrough - Mette una linea orizzontale al centro del testo (Alias: strikeThrough, crossedout, crossedOut)
• hidden - Stampa il testo, ma lo rende invisibile (Alias: conceal)
• dim - Intensità del colore ridotta (Alias: faint)
• overlined - Rende il testo con una linea sopra
• blink - Nasconde e mostra il testo a intervalli
• inverse - Scambia i colori di primo piano e di sfondo (Alias: swapcolors, swapColors)
• doubleunderline - Rende il testo sottolineato doppio (Alias: doubleUnderline)
• framed - Disegna un riquadro attorno al testo

Colori di primo piano

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

Colori di sfondo

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

Funzioni di ispezione personalizzate sugli oggetti

[Cronologia]

Versione	Modifiche
v17.3.0, v16.14.0	L'argomento inspect è stato aggiunto per una maggiore interoperabilità.
v0.1.97	Aggiunto in: v0.1.97

Gli oggetti possono anche definire la propria funzione [util.inspect.custom](depth, opts, inspect), che util.inspect() invocherà e utilizzerà il risultato di quando ispeziona l'oggetto.

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

    // Imbottitura di cinque spazi perché questa è la dimensione di "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)
// Restituisce: "Box< true >"

Le funzioni [util.inspect.custom](depth, opts, inspect) personalizzate restituiscono in genere una stringa, ma possono restituire un valore di qualsiasi tipo che verrà formattato di conseguenza da 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)
// Restituisce: "{ bar: 'baz' }"

util.inspect.custom

[Cronologia]

Versione	Modifiche
v10.12.0	Questo è ora definito come un simbolo condiviso.
v6.6.0	Aggiunto in: v6.6.0

• <symbol> che può essere utilizzato per dichiarare funzioni di ispezione personalizzate.

Oltre ad essere accessibile tramite util.inspect.custom, questo simbolo è registrato globalmente e può essere accesso in qualsiasi ambiente come Symbol.for('nodejs.util.inspect.custom').

L'utilizzo di questo consente di scrivere codice in modo portatile, in modo che la funzione di ispezione personalizzata venga utilizzata in un ambiente Node.js e ignorata nel browser. La funzione util.inspect() stessa viene passata come terzo argomento alla funzione di ispezione personalizzata per consentire una maggiore portabilità.

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

Vedi Funzioni di ispezione personalizzate sugli oggetti per maggiori dettagli.

util.inspect.defaultOptions

Aggiunto in: v6.4.0

Il valore defaultOptions consente la personalizzazione delle opzioni predefinite utilizzate da util.inspect. Questo è utile per funzioni come console.log o util.format che chiamano implicitamente util.inspect. Deve essere impostato su un oggetto contenente una o più opzioni valide util.inspect(). È supportato anche l'impostazione diretta delle proprietà delle opzioni.

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

console.log(arr) // Stampa la matrice troncata
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // Stampa la matrice completa

util.isDeepStrictEqual(val1, val2)

Aggiunto in: v9.0.0

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

Restituisce true se esiste una profonda uguaglianza stretta tra val1 e val2. Altrimenti, restituisce false.

Vedere assert.deepStrictEqual() per maggiori informazioni sulla profonda uguaglianza stretta.

Classe: util.MIMEType

Aggiunto in: v19.1.0, v18.13.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Un'implementazione della classe MIMEType.

In conformità con le convenzioni del browser, tutte le proprietà degli oggetti MIMEType sono implementate come getter e setter sul prototipo della classe, anziché come proprietà dati sull'oggetto stesso.

Una stringa MIME è una stringa strutturata contenente più componenti significative. Quando analizzata, viene restituito un oggetto MIMEType contenente proprietà per ciascuna di queste componenti.

Costruttore: new MIMEType(input)

• input <string> Il MIME di input da analizzare

Crea un nuovo oggetto MIMEType analizzando 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')

Verranno generate eccezioni TypeError se l'input non è un MIME valido. Si noti che verrà fatto uno sforzo per forzare i valori forniti in stringhe. Per esempio:

ESM

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

CJS

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

mime.type

• <string>

Ottiene e imposta la parte di tipo del MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

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

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

mime.subtype

• <string>

Ottiene e imposta la parte di sottotipo del MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

const { MIMEType } from require('node:util');

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

mime.essence

• <string>

Ottiene l'essenza del MIME. Questa proprietà è di sola lettura. Utilizzare mime.type o mime.subtype per modificare il MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

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

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

mime.params

• <MIMEParams>

Ottiene l'oggetto MIMEParams che rappresenta i parametri del MIME. Questa proprietà è di sola lettura. Vedere la documentazione di MIMEParams per i dettagli.

mime.toString()

• Restituisce: <string>

Il metodo toString() sull'oggetto MIMEType restituisce il MIME serializzato.

A causa della necessità di conformità agli standard, questo metodo non consente agli utenti di personalizzare il processo di serializzazione del MIME.

mime.toJSON()

• Restituisce: <string>

Alias di mime.toString().

Questo metodo viene chiamato automaticamente quando un oggetto MIMEType viene serializzato con JSON.stringify().

ESM

import { MIMEType } from 'node:util'

const myMIMES = [new MIMEType('image/png'), new MIMEType('image/gif')]
console.log(JSON.stringify(myMIMES))
// Stampa: ["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))
// Stampa: ["image/png", "image/gif"]

Classe: util.MIMEParams

Aggiunto in: v19.1.0, v18.13.0

L'API MIMEParams fornisce accesso in lettura e scrittura ai parametri di un MIMEType.

Costruttore: new MIMEParams()

Crea un nuovo oggetto MIMEParams con parametri vuoti

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>

Rimuovi tutte le coppie nome-valore il cui nome è name.

mimeParams.entries()

• Restituisce: <Iterator>

Restituisce un iteratore su ciascuna delle coppie nome-valore nei parametri. Ogni elemento dell'iteratore è un array JavaScript. Il primo elemento dell'array è il nome, il secondo elemento dell'array è il valore.

mimeParams.get(name)

• name <string>
• Restituisce: <string> | <null> Una stringa o null se non esiste una coppia nome-valore con il name dato.

Restituisce il valore della prima coppia nome-valore il cui nome è name. Se non esistono tali coppie, viene restituito null.

mimeParams.has(name)

• name <string>
• Restituisce: <boolean>

Restituisce true se esiste almeno una coppia nome-valore il cui nome è name.

mimeParams.keys()

• Restituisce: <Iterator>

Restituisce un iteratore sui nomi di ogni coppia nome-valore.

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)
}
// Stampa:
//   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)
}
// Stampa:
//   foo
//   bar

mimeParams.set(name, value)

• name <string>
• value <string>

Imposta il valore nell'oggetto MIMEParams associato a name su value. Se esistono coppie nome-valore preesistenti i cui nomi sono name, imposta il valore della prima di tali coppie su 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())
// Stampa: 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())
// Stampa: foo=def;bar=1;baz=xyz

mimeParams.values()

• Restituisce: <Iterator>

Restituisce un iteratore sui valori di ogni coppia nome-valore.

mimeParams[@@iterator]()

• Restituisce: <Iterator>

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

util.parseArgs([config])

[Cronologia]

Versione	Modifiche
v22.4.0, v20.16.0	Aggiunto supporto per consentire opzioni negative nell'input config.
v20.0.0	L'API non è più sperimentale.
v18.11.0, v16.19.0	Aggiunto supporto per i valori predefiniti nell'input config.
v18.7.0, v16.17.0	Aggiunto supporto per la restituzione di informazioni di analisi dettagliate utilizzando tokens nell'input config e nelle proprietà restituite.
v18.3.0, v16.17.0	Aggiunto in: v18.3.0, v16.17.0

• config <Object> Utilizzato per fornire argomenti per l'analisi e per configurare l'analizzatore. config supporta le seguenti proprietà:

  • args <string[]> array di stringhe di argomento. Predefinito: process.argv con execPath e filename rimossi.

  • options <Object> Utilizzato per descrivere gli argomenti noti all'analizzatore. Le chiavi di options sono i nomi lunghi delle opzioni e i valori sono un <Object> che accetta le seguenti proprietà:

  • type <string> Tipo di argomento, che deve essere boolean o string.

  • multiple <boolean> Se questa opzione può essere fornita più volte. Se true, tutti i valori verranno raccolti in un array. Se false, i valori dell'opzione sono last-wins. Predefinito: false.

  • short <string> Un alias a singolo carattere per l'opzione.

  • default <string> | <boolean> | <string[]> | <boolean[]> Il valore predefinito dell'opzione quando non è impostato da args. Deve essere dello stesso tipo della proprietà type. Quando multiple è true, deve essere un array.

  • strict <boolean> Dovrebbe essere generato un errore quando vengono rilevati argomenti sconosciuti o quando vengono passati argomenti che non corrispondono al tipo configurato in options. Predefinito: true.

  • allowPositionals <boolean> Se questo comando accetta argomenti posizionali. Predefinito: false se strict è true, altrimenti true.

  • allowNegative <boolean> Se true, consente di impostare esplicitamente le opzioni booleane su false anteponendo il nome dell'opzione con --no-. Predefinito: false.

  • tokens <boolean> Restituisce i token analizzati. Questo è utile per estendere il comportamento predefinito, dall'aggiunta di controlli aggiuntivi alla rielaborazione dei token in modi diversi. Predefinito: false.

• Restituisce: <Object> Gli argomenti della riga di comando analizzati:

  • values <Object> Una mappatura dei nomi delle opzioni analizzate con i loro valori <string> o <boolean>.
  • positionals <string[]> Argomenti posizionali.
  • tokens <Object[]> | <undefined> Vedere la sezione token parseArgs. Restituito solo se config include tokens: true.

Fornisce un'API di livello superiore per l'analisi degli argomenti della riga di comando rispetto all'interazione diretta con process.argv. Accetta una specifica per gli argomenti previsti e restituisce un oggetto strutturato con le opzioni e i posizionali analizzati.

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

parseArgs tokens

Informazioni dettagliate sull'analisi sono disponibili per aggiungere comportamenti personalizzati specificando tokens: true nella configurazione. I token restituiti hanno proprietà che descrivono:

• tutti i token

  • kind <string> Uno tra 'option', 'positional', o 'option-terminator'.
  • index <number> Indice dell'elemento in args contenente il token. Quindi l'argomento sorgente per un token è args[token.index].

• token di opzione

  • name <string> Nome lungo dell'opzione.
  • rawName <string> Come viene utilizzata l'opzione negli argomenti, come -f di --foo.
  • value <string> | <undefined> Valore dell'opzione specificato negli argomenti. Non definito per le opzioni booleane.
  • inlineValue <boolean> | <undefined> Se il valore dell'opzione è specificato in linea, come --foo=bar.

• token posizionali

  • value <string> Il valore dell'argomento posizionale in args (cioè args[index]).

• token di terminazione opzione

I token restituiti sono nell'ordine in cui sono stati incontrati negli argomenti di input. Le opzioni che compaiono più di una volta negli argomenti producono un token per ogni utilizzo. I gruppi di opzioni brevi come -xy si espandono in un token per ogni opzione. Quindi -xxx produce tre token.

Ad esempio, per aggiungere supporto per un'opzione negata come --no-color (che allowNegative supporta quando l'opzione è di tipo boolean), i token restituiti possono essere rielaborati per modificare il valore memorizzato per l'opzione negata.

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

// Rielaborazione dei token di opzione e sovrascrittura dei valori restituiti.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Memorizza foo:false per --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Riserva il valore in modo che l'ultimo vinca se sia --foo che --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 })

// Rielaborazione dei token di opzione e sovrascrittura dei valori restituiti.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Memorizza foo:false per --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Riserva il valore in modo che l'ultimo vinca se sia --foo che --no-foo.
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })

Esempio di utilizzo che mostra opzioni negate e quando un'opzione viene utilizzata in modi multipli, l'ultima vince.

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

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1.1 - Sviluppo attivo

Aggiunto in: v21.7.0, v20.12.0

• content <string>

Il contenuto grezzo di un file .env.

• Restituisce: <Object>

Dato un esempio di file .env:

CJS

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

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

ESM

import { parseEnv } from 'node:util'

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

util.promisify(original)

[Cronologia]

Versione	Modifiche
v20.8.0	La chiamata a promisify su una funzione che restituisce una Promise è deprecata.
v8.0.0	Aggiunto in: v8.0.0

• original <Function>
• Restituisce: <Function>

Prende una funzione che segue lo stile comune di callback con errore in primo luogo, ovvero che accetta una callback (err, value) =\> ... come ultimo argomento, e restituisce una versione che restituisce promise.

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

const stat = util.promisify(fs.stat)
stat('.')
  .then(stats => {
    // Fai qualcosa con `stats`
  })
  .catch(error => {
    // Gestisci l'errore.
  })

Oppure, equivalentemente usando le funzioni async function:

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(`Questa directory è di proprietà di ${stats.uid}`)
}

callStat()

Se è presente una proprietà original[util.promisify.custom], promisify restituirà il suo valore, vedi Funzioni promisificate personalizzate.

promisify() presuppone che original sia una funzione che accetta una callback come suo ultimo argomento in tutti i casi. Se original non è una funzione, promisify() genererà un errore. Se original è una funzione, ma il suo ultimo argomento non è una callback con errore in primo luogo, gli verrà comunque passata una callback con errore in primo luogo come suo ultimo argomento.

L'utilizzo di promisify() sui metodi di classe o altri metodi che utilizzano this potrebbe non funzionare come previsto a meno che non venga gestito in modo speciale:

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'

Funzioni promisificate personalizzate

Usando il simbolo util.promisify.custom è possibile sovrascrivere il valore restituito da 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])
// stampa 'true'

Questo può essere utile nei casi in cui la funzione originale non segue il formato standard di accettare un callback error-first come ultimo argomento.

Ad esempio, con una funzione che accetta (foo, onSuccessCallback, onErrorCallback):

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

Se promisify.custom è definito ma non è una funzione, promisify() lancerà un errore.

util.promisify.custom

[Cronologia]

Versione	Modifiche
v13.12.0, v12.16.2	Ora definito come simbolo condiviso.
v8.0.0	Aggiunto in: v8.0.0

• <simbolo> che può essere usato per dichiarare varianti promisificate personalizzate di funzioni, vedi Funzioni promisificate personalizzate.

Oltre ad essere accessibile tramite util.promisify.custom, questo simbolo è registrato globalmente e può essere accessibile in qualsiasi ambiente come Symbol.for('nodejs.util.promisify.custom').

Ad esempio, con una funzione che accetta (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)

Aggiunto in: v16.11.0

• str <string>
• Restituisce: <string>

Restituisce str con tutti i codici di escape ANSI rimossi.

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

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

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile.

[Cronologia]

Versione	Modifiche
v23.5.0	styleText è ora stabile.
v22.8.0, v20.18.0	Rispetta isTTY e variabili ambientali come NO_COLORS, NODE_DISABLE_COLORS e FORCE_COLOR.
v21.7.0, v20.12.0	Aggiunto in: v21.7.0, v20.12.0

• format <string> | <Array> Un formato di testo o una matrice di formati di testo definiti in util.inspect.colors.
• text <string> Il testo da formattare.
• options <Object>
  • validateStream <boolean> Quando è true, stream viene controllato per vedere se può gestire i colori. Predefinito: true.
  • stream <Stream> Un flusso che verrà validato se può essere colorato. Predefinito: process.stdout.

Questa funzione restituisce un testo formattato considerando il format passato per la stampa in un terminale. È consapevole delle capacità del terminale e agisce in base alla configurazione impostata tramite le variabili di ambiente NO_COLORS, NODE_DISABLE_COLORS e FORCE_COLOR.

ESM

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

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

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Convalida se process.stderr ha TTY
  { stream: stderr }
)
console.error(successMessage)

CJS

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

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

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Convalida se process.stderr ha TTY
  { stream: stderr }
)
console.error(successMessage)

util.inspect.colors fornisce anche formati di testo come italic e underline ed è possibile combinarli entrambi:

console.log(util.styleText(['underline', 'italic'], 'Il mio messaggio sottolineato in corsivo'))

Quando si passa una matrice di formati, l'ordine del formato applicato è da sinistra a destra, quindi lo stile seguente potrebbe sovrascrivere quello precedente.

console.log(
  util.styleText(['red', 'green'], 'testo') // verde
)

L'elenco completo dei formati si trova in modificatori.

Classe: util.TextDecoder

[Cronologia]

Versione	Modifiche
v11.0.0	La classe è ora disponibile sull'oggetto globale.
v8.3.0	Aggiunta in: v8.3.0

Un'implementazione dell'Standard di codifica WHATWG dell'API TextDecoder.

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

Codifiche supportate da WHATWG

Secondo lo Standard di codifica WHATWG, le codifiche supportate dall'API TextDecoder sono descritte nelle tabelle seguenti. Per ogni codifica, è possibile utilizzare uno o più alias.

Diverse configurazioni di build di Node.js supportano diversi set di codifiche. (vedi Internazionalizzazione)

Codifiche supportate di default (con dati ICU completi)

Codifica	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'

Codifiche supportate quando Node.js è compilato con l'opzione small-icu

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

Codifiche supportate quando ICU è disabilitato

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

La codifica 'iso-8859-16' elencata nello standard WHATWG Encoding Standard non è supportata.

new TextDecoder([encoding[, options]])

• encoding <string> Identifica la codifica supportata da questa istanza di TextDecoder. Default: 'utf-8'.
• options <Object>
  • fatal <boolean> true se gli errori di decodifica sono fatali. Questa opzione non è supportata quando ICU è disabilitato (vedi Internationalizzazione). Default: false.
  • ignoreBOM <boolean> Quando true, TextDecoder includerà il byte order mark nel risultato decodificato. Quando false, il byte order mark verrà rimosso dall'output. Questa opzione viene utilizzata solo quando encoding è 'utf-8', 'utf-16be' o 'utf-16le'. Default: false.

Crea una nuova istanza TextDecoder. encoding può specificare una delle codifiche supportate o un alias.

La classe TextDecoder è anche disponibile sull'oggetto globale.

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

• input <ArrayBuffer> | <DataView> | <TypedArray> Un'istanza ArrayBuffer, DataView o TypedArray contenente i dati codificati.

• options <Object>

  • stream <boolean> true se sono attesi chunk di dati aggiuntivi. Default: false.

• Restituisce: <string>

Decodifica l'input e restituisce una stringa. Se options.stream è true, le sequenze di byte incomplete che si verificano alla fine dell'input vengono memorizzate nella cache internamente e emesse dopo la successiva chiamata a textDecoder.decode().

Se textDecoder.fatal è true, gli errori di decodifica che si verificano provocheranno il lancio di un TypeError.

textDecoder.encoding

• <string>

La codifica supportata dall'istanza TextDecoder.

textDecoder.fatal

• <boolean>

Il valore sarà true se gli errori di decodifica causano il lancio di un TypeError.

textDecoder.ignoreBOM

• <boolean>

Il valore sarà true se il risultato della decodifica includerà il byte order mark.

Classe: util.TextEncoder

[Cronologia]

Versione	Modifiche
v11.0.0	La classe è ora disponibile sull'oggetto globale.
v8.3.0	Aggiunta in: v8.3.0

Un'implementazione dell'WHATWG Encoding Standard API TextEncoder. Tutte le istanze di TextEncoder supportano solo la codifica UTF-8.

const encoder = new TextEncoder()
const uint8array = encoder.encode('questi sono alcuni dati')

La classe TextEncoder è anche disponibile sull'oggetto globale.

textEncoder.encode([input])

• input <string> Il testo da codificare. Default: una stringa vuota.
• Restituisce: <Uint8Array>

Codifica in UTF-8 la stringa input e restituisce un Uint8Array contenente i byte codificati.

textEncoder.encodeInto(src, dest)

Aggiunto in: v12.11.0

• src <string> Il testo da codificare.
• dest <Uint8Array> L'array che conterrà il risultato della codifica.
• Restituisce: <Object>
  • read <number> Le unità di codice Unicode lette di src.
  • written <number> I byte UTF-8 scritti di dest.

Codifica in UTF-8 la stringa src nel dest Uint8Array e restituisce un oggetto contenente le unità di codice Unicode lette e i byte UTF-8 scritti.

const encoder = new TextEncoder()
const src = 'questi sono alcuni dati'
const dest = new Uint8Array(10)
const { read, written } = encoder.encodeInto(src, dest)

textEncoder.encoding

• <string>

Codifica supportata dall'istanza TextEncoder. Sempre impostata su 'utf-8'.

util.toUSVString(string)

Aggiunto in: v16.8.0, v14.18.0

• string <string>

Restituisce la stringa dopo aver sostituito eventuali punti codice surrogate (o equivalentemente, qualsiasi unità di codice surrogate spaiata) con il carattere di "sostituzione" Unicode U+FFFD.

util.transferableAbortController()

Aggiunto in: v18.11.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Crea e restituisce un'istanza <AbortController> il cui <AbortSignal> è contrassegnato come trasferibile e può essere utilizzato con structuredClone() o postMessage().

util.transferableAbortSignal(signal)

Aggiunto in: v18.11.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• signal <AbortSignal>
• Restituisce: <AbortSignal>

Contrassegna il <AbortSignal> fornito come trasferibile in modo che possa essere utilizzato con structuredClone() e postMessage().

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

util.aborted(signal, resource)

Aggiunto in: v19.7.0, v18.16.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• signal <AbortSignal>
• resource <Object> Qualsiasi oggetto non nullo legato all'operazione annullabile e mantenuto debolmente. Se resource viene raccolto come garbage prima che signal venga annullato, la promise rimane in sospeso, consentendo a Node.js di smettere di tracciarla. Ciò aiuta a prevenire perdite di memoria in operazioni di lunga durata o non annullabili.
• Restituisce: <Promise>

Ascolta l'evento di annullamento sul signal fornito e restituisce una promise che si risolve quando il signal viene annullato. Se viene fornito resource, fa riferimento debolmente all'oggetto associato all'operazione, quindi se resource viene raccolto come garbage prima che signal venga annullato, la promise restituita rimarrà in sospeso. Ciò previene perdite di memoria in operazioni di lunga durata o non annullabili.

CJS

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

// Ottieni un oggetto con un segnale annullabile, come una risorsa o un'operazione personalizzata.
const dependent = obtainSomethingAbortable()

// Passa `dependent` come risorsa, indicando che la promise dovrebbe risolversi solo
// se `dependent` è ancora in memoria quando il segnale viene annullato.
aborted(dependent.signal, dependent).then(() => {
  // Questo codice viene eseguito quando `dependent` viene annullato.
  console.log('La risorsa dipendente è stata annullata.')
})

// Simula un evento che innesca l'annullamento.
dependent.on('event', () => {
  dependent.abort() // Questo farà sì che la promise `aborted` venga risolta.
})

ESM

import { aborted } from 'node:util'

// Ottieni un oggetto con un segnale annullabile, come una risorsa o un'operazione personalizzata.
const dependent = obtainSomethingAbortable()

// Passa `dependent` come risorsa, indicando che la promise dovrebbe risolversi solo
// se `dependent` è ancora in memoria quando il segnale viene annullato.
aborted(dependent.signal, dependent).then(() => {
  // Questo codice viene eseguito quando `dependent` viene annullato.
  console.log('La risorsa dipendente è stata annullata.')
})

// Simula un evento che innesca l'annullamento.
dependent.on('event', () => {
  dependent.abort() // Questo farà sì che la promise `aborted` venga risolta.
})

util.types

[Cronologia]

Versione	Modifiche
v15.3.0	Esposto come require('util/types').
v10.0.0	Aggiunto in: v10.0.0

util.types fornisce controlli di tipo per diversi tipi di oggetti built-in. A differenza di instanceof o Object.prototype.toString.call(value), questi controlli non ispezionano le proprietà dell'oggetto accessibili da JavaScript (come il loro prototipo), e di solito hanno l'overhead di chiamare in C++.

Il risultato generalmente non fornisce garanzie sui tipi di proprietà o comportamento che un valore espone in JavaScript. Sono principalmente utili per gli sviluppatori di addon che preferiscono eseguire il controllo del tipo in JavaScript.

L'API è accessibile tramite require('node:util').types o require('node:util/types').

util.types.isAnyArrayBuffer(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza di ArrayBuffer o SharedArrayBuffer built-in.

Vedi anche util.types.isArrayBuffer() e util.types.isSharedArrayBuffer().

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

util.types.isArrayBufferView(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza di una delle viste ArrayBuffer, come gli oggetti array tipizzati o DataView. Equivalente a 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)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un oggetto arguments.

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

util.types.isArrayBuffer(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza ArrayBuffer integrata. Questo non include le istanze SharedArrayBuffer. Di solito, è preferibile testare entrambi; vedere util.types.isAnyArrayBuffer() per questo.

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

util.types.isAsyncFunction(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è una funzione asincrona. Questo riporta solo ciò che il motore JavaScript sta vedendo; in particolare, il valore restituito potrebbe non corrispondere al codice sorgente originale se è stato utilizzato uno strumento di trascrizione.

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

util.types.isBigInt64Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza di BigInt64Array.

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

util.types.isBigIntObject(value)

Aggiunto in: v10.4.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un oggetto BigInt, ad esempio creato da Object(BigInt(123)).

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

util.types.isBigUint64Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza di BigUint64Array.

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

util.types.isBooleanObject(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un oggetto booleano, ad esempio creato da new Boolean().

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

util.types.isBoxedPrimitive(value)

Aggiunto in: v10.11.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un qualsiasi oggetto primitivo boxed, ad esempio creato da new Boolean(), new String() o Object(Symbol()).

Ad esempio:

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

util.types.isCryptoKey(value)

Aggiunto in: v16.2.0

• value <Object>
• Restituisce: <boolean>

Restituisce true se value è un <CryptoKey>, false altrimenti.

util.types.isDataView(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza DataView built-in.

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

Vedi anche ArrayBuffer.isView().

util.types.isDate(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Date built-in.

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

util.types.isExternal(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un valore External nativo.

Un valore External nativo è un tipo speciale di oggetto che contiene un puntatore C++ raw (void*) per l'accesso dal codice nativo, e non ha altre proprietà. Tali oggetti sono creati o dagli interni di Node.js o da addon nativi. In JavaScript, sono oggetti congelati con un prototipo 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) // restituisce true
util.types.isExternal(0) // restituisce false
util.types.isExternal(new String('foo')) // restituisce false

Per ulteriori informazioni su napi_create_external, fare riferimento a napi_create_external().

util.types.isFloat32Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Float32Array built-in.

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

util.types.isFloat64Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Float64Array integrata.

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

util.types.isGeneratorFunction(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è una funzione generatore. Questo riporta solo ciò che il motore JavaScript sta vedendo; in particolare, il valore restituito potrebbe non corrispondere al codice sorgente originale se è stato utilizzato uno strumento di transpilazione.

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

util.types.isGeneratorObject(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un oggetto generatore come restituito da una funzione generatore integrata. Questo riporta solo ciò che il motore JavaScript sta vedendo; in particolare, il valore restituito potrebbe non corrispondere al codice sorgente originale se è stato utilizzato uno strumento di transpilazione.

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

util.types.isInt8Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Int8Array integrata.

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

util.types.isInt16Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Int16Array integrata.

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

util.types.isInt32Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Int32Array integrata.

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

util.types.isKeyObject(value)

Aggiunto in: v16.2.0

• value <Object>
• Restituisce: <boolean>

Restituisce true se value è un <KeyObject>, false altrimenti.

util.types.isMap(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Map integrata.

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

util.types.isMapIterator(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un iteratore restituito per un'istanza di Map integrata.

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

util.types.isModuleNamespaceObject(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza di un Oggetto spazio dei nomi del modulo.

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

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

util.types.isNativeError(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è stato restituito dal costruttore di un tipo Error integrato.

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

Anche le sottoclassi dei tipi di errore nativi sono errori nativi:

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

Un valore che è instanceof una classe di errore nativa non è equivalente a isNativeError() che restituisce true per quel valore. isNativeError() restituisce true per gli errori provenienti da un realm diverso, mentre instanceof Error restituisce false per questi errori:

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

Al contrario, isNativeError() restituisce false per tutti gli oggetti che non sono stati restituiti dal costruttore di un errore nativo. Ciò include i valori che sono instanceof errori nativi:

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

util.types.isNumberObject(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un oggetto numerico, ad esempio creato da new Number().

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

util.types.isPromise(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un Promise integrato.

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

util.types.isProxy(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza di Proxy.

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

util.types.isRegExp(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un oggetto espressione regolare.

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

util.types.isSet(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Set integrata.

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

util.types.isSetIterator(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un iteratore restituito per un'istanza Set integrata.

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

util.types.isSharedArrayBuffer(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza SharedArrayBuffer integrata. Questo non include le istanze ArrayBuffer. Di solito, è preferibile testare entrambi; vedere util.types.isAnyArrayBuffer() per questo.

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

util.types.isStringObject(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un oggetto stringa, ad esempio creato da new String().

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

util.types.isSymbolObject(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un oggetto simbolo, creato chiamando Object() su un primitivo Symbol.

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

util.types.isTypedArray(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza TypedArray integrata.

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

Vedi anche ArrayBuffer.isView().

util.types.isUint8Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Uint8Array integrata.

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

util.types.isUint8ClampedArray(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Uint8ClampedArray built-in.

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

util.types.isUint16Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Uint16Array built-in.

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

util.types.isUint32Array(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza Uint32Array built-in.

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

util.types.isWeakMap(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza WeakMap built-in.

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

util.types.isWeakSet(value)

Aggiunto in: v10.0.0

• value <any>
• Restituisce: <boolean>

Restituisce true se il valore è un'istanza di WeakSet integrata.

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

API deprecate

Le seguenti API sono deprecate e non dovrebbero più essere utilizzate. Le applicazioni e i moduli esistenti dovrebbero essere aggiornati per trovare approcci alternativi.

util._extend(target, source)

Aggiunto in: v0.7.5

Deprecato da: v6.0.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Utilizzare Object.assign() invece.

• target <Object>
• source <Object>

Il metodo util._extend() non era destinato all'utilizzo al di fuori dei moduli Node.js interni. La community lo ha comunque trovato e utilizzato.

È deprecato e non dovrebbe essere utilizzato nel nuovo codice. JavaScript include funzionalità integrate molto simili tramite Object.assign().

util.isArray(object)

Aggiunto in: v0.6.0

Deprecato da: v4.0.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Utilizzare Array.isArray() invece.

• object <any>
• Restituisce: <boolean>

Alias per Array.isArray().

Restituisce true se l'oggetto dato è un Array. Altrimenti, restituisce false.

const util = require('node:util')

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