Util

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código fuente: lib/util.js

El módulo node:util soporta las necesidades de las APIs internas de Node.js. Muchas de las utilidades también son útiles para los desarrolladores de aplicaciones y módulos. Para acceder a él:

const util = require('node:util')

util.callbackify(original)

Agregado en: v8.2.0

• original <Function> Una función async
• Devuelve: <Function> una función estilo callback

Toma una función async (o una función que devuelve una Promise) y devuelve una función que sigue el estilo de callback primero con error, es decir, tomando un callback (err, value) => ... como el último argumento. En el callback, el primer argumento será el motivo del rechazo (o null si la Promise se resolvió) y el segundo argumento será el valor resuelto.

const util = require('node:util')

async function fn() {
  return 'hola mundo'
}
const callbackFunction = util.callbackify(fn)

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

Imprimirá:

hola mundo

El callback se ejecuta asíncronamente y tendrá un rastreo de pila limitado. Si el callback lanza una excepción, el proceso emitirá un evento 'uncaughtException' y, si no se maneja, se cerrará.

Dado que null tiene un significado especial como el primer argumento de un callback, si una función envuelta rechaza una Promise con un valor falsy como motivo, el valor se envuelve en un Error con el valor original almacenado en un campo llamado reason.

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

callbackFunction((err, ret) => {
  // Cuando la Promise fue rechazada con `null`, se envuelve con un Error y
  // el valor original se almacena en `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null // true
})

util.debuglog(section[, callback])

Agregado en: v0.11.3

• section <string> Una cadena que identifica la parte de la aplicación para la que se está creando la función debuglog.
• callback <Function> Una retrollamada invocada la primera vez que se llama a la función de registro con un argumento de función que es una función de registro más optimizada.
• Devuelve: <Function> La función de registro

El método util.debuglog() se utiliza para crear una función que escribe condicionalmente mensajes de depuración en stderr basándose en la existencia de la variable de entorno NODE_DEBUG. Si el nombre de la section aparece dentro del valor de esa variable de entorno, entonces la función devuelta funciona de forma similar a console.error(). Si no, entonces la función devuelta es una operación nula.

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

debuglog('hola desde foo [%d]', 123)

Si este programa se ejecuta con NODE_DEBUG=foo en el entorno, entonces mostrará algo como:

FOO 3245: hola desde foo [123]

donde 3245 es el id del proceso. Si no se ejecuta con esa variable de entorno establecida, entonces no imprimirá nada.

La section también soporta comodines:

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

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

si se ejecuta con NODE_DEBUG=foo* en el entorno, entonces mostrará algo como:

FOO-BAR 3257: hola, es foo-bar [2333]

Se pueden especificar múltiples nombres de section separados por comas en la variable de entorno NODE_DEBUG: NODE_DEBUG=fs,net,tls.

El argumento opcional callback se puede utilizar para reemplazar la función de registro con una función diferente que no tenga ninguna inicialización o encapsulamiento innecesario.

const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
  // Reemplazar con una función de registro que optimice
  // la prueba de si la section está habilitada
  debuglog = debug
})

debuglog().enabled

Agregado en: v14.9.0

• <boolean>

El getter util.debuglog().enabled se utiliza para crear una prueba que se puede usar en condicionales basándose en la existencia de la variable de entorno NODE_DEBUG. Si el nombre de la section aparece dentro del valor de esa variable de entorno, entonces el valor devuelto será true. Si no, entonces el valor devuelto será false.

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

Si este programa se ejecuta con NODE_DEBUG=foo en el entorno, entonces generará algo como:

hola desde foo [123]

util.debug(section)

Agregado en: v14.9.0

Alias para util.debuglog. El uso permite la legibilidad de que no implica el registro cuando solo se usa util.debuglog().enabled.

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

[Historial]

Versión	Cambios
v10.0.0	Las advertencias de obsolescencia solo se emiten una vez para cada código.
v0.8.0	Agregado en: v0.8.0

• fn <Function> La función que está en desuso.
• msg <string> Un mensaje de advertencia para mostrar cuando se invoca la función en desuso.
• code <string> Un código de obsolescencia. Consulte la lista de API en desuso para obtener una lista de códigos.
• Devuelve: <Function> La función en desuso envuelta para emitir una advertencia.

El método util.deprecate() envuelve fn (que puede ser una función o clase) de tal manera que se marca como en desuso.

const util = require('node:util')

exports.obsoleteFunction = util.deprecate(() => {
  // Haz algo aquí.
}, 'obsoleteFunction() está en desuso. Usa newShinyFunction() en su lugar.')

Cuando se llama, util.deprecate() devolverá una función que emitirá una DeprecationWarning usando el evento 'warning'. La advertencia se emitirá e imprimirá en stderr la primera vez que se llame a la función devuelta. Después de que se emita la advertencia, se llama a la función envuelta sin emitir una advertencia.

Si el mismo code opcional se proporciona en varias llamadas a util.deprecate(), la advertencia solo se emitirá una vez para ese code.

const util = require('node:util')

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001')
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001')
fn1() // Emite una advertencia de obsolescencia con el código DEP0001
fn2() // No emite una advertencia de obsolescencia porque tiene el mismo código

Si se utilizan las banderas de línea de comandos --no-deprecation o --no-warnings, o si la propiedad process.noDeprecation se establece en true antes de la primera advertencia de obsolescencia, el método util.deprecate() no hace nada.

Si se establecen las banderas de línea de comandos --trace-deprecation o --trace-warnings, o la propiedad process.traceDeprecation se establece en true, se imprimirá una advertencia y un seguimiento de pila en stderr la primera vez que se llame a la función en desuso.

Si se establece la bandera de línea de comandos --throw-deprecation o la propiedad process.throwDeprecation se establece en true, se lanzará una excepción cuando se llame a la función en desuso.

La bandera de línea de comandos --throw-deprecation y la propiedad process.throwDeprecation tienen prioridad sobre --trace-deprecation y process.traceDeprecation.

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

[Historial]

Versión	Cambios
v12.11.0	El especificador %c ahora se ignora.
v12.0.0	El argumento format ahora solo se toma como tal si realmente contiene especificadores de formato.
v12.0.0	Si el argumento format no es una cadena de formato, el formato de la cadena de salida ya no depende del tipo del primer argumento. Este cambio elimina las comillas previamente presentes en las cadenas que se emitían cuando el primer argumento no era una cadena.
v11.4.0	Los especificadores %d, %f e %i ahora admiten símbolos correctamente.
v11.4.0	La profundidad del especificador %o vuelve a tener una profundidad predeterminada de 4.
v11.0.0	La opción profundidad del especificador %o ahora volverá a la profundidad predeterminada.
v10.12.0	Los especificadores %d e %i ahora admiten BigInt.
v8.4.0	Ahora se admiten los especificadores %o y %O.
v0.5.3	Añadido en: v0.5.3

• format <string> Una cadena de formato similar a printf.

El método util.format() devuelve una cadena formateada utilizando el primer argumento como una cadena de formato similar a printf que puede contener cero o más especificadores de formato. Cada especificador se reemplaza con el valor convertido del argumento correspondiente. Los especificadores admitidos son:

• %s: Se utilizará String para convertir todos los valores excepto BigInt, Object y -0. Los valores BigInt se representarán con una n y los Objetos que no tengan una función toString definida por el usuario se inspeccionarán utilizando util.inspect() con las opciones { depth: 0, colors: false, compact: 3 }.
• %d: Se utilizará Number para convertir todos los valores excepto BigInt y Symbol.
• %i: Se utiliza parseInt(value, 10) para todos los valores excepto BigInt y Symbol.
• %f: Se utiliza parseFloat(value) para todos los valores excepto Symbol.
• %j: JSON. Se reemplaza con la cadena '[Circular]' si el argumento contiene referencias circulares.
• %o: Object. Una representación en cadena de un objeto con formato genérico de objeto JavaScript. Similar a util.inspect() con las opciones { showHidden: true, showProxy: true }. Esto mostrará el objeto completo, incluidas las propiedades no enumerables y los proxies.
• %O: Object. Una representación en cadena de un objeto con formato genérico de objeto JavaScript. Similar a util.inspect() sin opciones. Esto mostrará el objeto completo sin incluir las propiedades no enumerables ni los proxies.
• %c: CSS. Este especificador se ignora y omitirá cualquier CSS que se pase.
• %%: signo de porcentaje único ('%'). Esto no consume un argumento.
• Devuelve: <string> La cadena formateada

Si un especificador no tiene un argumento correspondiente, no se reemplaza:

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

Los valores que no forman parte de la cadena de formato se formatean utilizando util.inspect() si su tipo no es string.

Si se pasan más argumentos al método util.format() que el número de especificadores, los argumentos adicionales se concatenan a la cadena devuelta, separados por espacios:

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

Si el primer argumento no contiene un especificador de formato válido, util.format() devuelve una cadena que es la concatenación de todos los argumentos separados por espacios:

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

Si solo se pasa un argumento a util.format(), se devuelve tal cual sin ningún formato:

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

util.format() es un método síncrono que se concibe como una herramienta de depuración. Algunos valores de entrada pueden tener una sobrecarga de rendimiento significativa que puede bloquear el bucle de eventos. Use esta función con cuidado y nunca en una ruta de código crítica.

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

Agregado en: v10.0.0

• inspectOptions <Object>
• format <string>

Esta función es idéntica a util.format(), excepto que toma un argumento inspectOptions que especifica opciones que se pasan a util.inspect().

util.formatWithOptions({ colors: true }, 'Ver objeto %O', { foo: 42 })
// Devuelve 'Ver objeto { foo: 42 }', donde `42` se colorea como un número
// cuando se imprime en una terminal.

util.getCallSites(frameCountOrOptions, [options])

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1.1 - Desarrollo activo

[Historial]

Versión	Cambios
v23.3.0	La API se renombra de util.getCallSite a util.getCallSites().
v22.9.0	Agregado en: v22.9.0

• frameCount <number> Número opcional de marcos para capturar como objetos de sitio de llamada. Predeterminado: 10. El rango permitido está entre 1 y 200.

• options <Object> Opcional

  • sourceMap <boolean> Reconstruye la ubicación original en el seguimiento de pila desde el mapa de origen. Habilitado por defecto con el indicador --enable-source-maps.

• Devuelve: <Object[]> Un array de objetos de sitio de llamada

  • functionName <string> Devuelve el nombre de la función asociada con este sitio de llamada.
  • scriptName <string> Devuelve el nombre del recurso que contiene el script para la función de este sitio de llamada.
  • lineNumber <number> Devuelve el número, basado en 1, de la línea para la llamada de función asociada.
  • column <number> Devuelve el desplazamiento de columna basado en 1 en la línea para la llamada de función asociada.

Devuelve un array de objetos de sitio de llamada que contiene la pila de la función que llama.

const util = require('node:util')

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

  console.log('Sitios de llamada:')
  callSites.forEach((callSite, index) => {
    console.log(`Sitio de llamada ${index + 1}:`)
    console.log(`Nombre de la función: ${callSite.functionName}`)
    console.log(`Nombre del script: ${callSite.scriptName}`)
    console.log(`Número de línea: ${callSite.lineNumber}`)
    console.log(`Número de columna: ${callSite.column}`)
  })
  // Sitio de llamada 1:
  // Nombre de la función: exampleFunction
  // Nombre del script: /home/ejemplo.js
  // Número de línea: 5
  // Número de columna: 26

  // Sitio de llamada 2:
  // Nombre de la función: anotherFunction
  // Nombre del script: /home/ejemplo.js
  // Número de línea: 22
  // Número de columna: 3

  // ...
}

// Una función para simular otra capa de pila
function anotherFunction() {
  exampleFunction()
}

anotherFunction()

Es posible reconstruir las ubicaciones originales configurando la opción sourceMap en true. Si el mapa de origen no está disponible, la ubicación original será la misma que la ubicación actual. Cuando el indicador --enable-source-maps está habilitado, por ejemplo, cuando se utiliza --experimental-transform-types, sourceMap será verdadero por defecto.

import util from 'node:util'

interface Foo {
  foo: string
}

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

// Con sourceMap:
// Nombre de la función: ''
// Nombre del script: example.js
// Número de línea: 7
// Número de columna: 26

// Sin sourceMap:
// Nombre de la función: ''
// Nombre del script: example.js
// Número de línea: 2
// Número de columna: 26

util.getSystemErrorName(err)

Agregado en: v9.7.0

• err <number>
• Devuelve: <string>

Devuelve el nombre de cadena para un código de error numérico que proviene de una API de Node.js. La asignación entre códigos de error y nombres de error depende de la plataforma. Consulte Errores comunes del sistema para conocer los nombres de los errores comunes.

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

util.getSystemErrorMap()

Agregado en: v16.0.0, v14.17.0

• Devuelve: <Map>

Devuelve un Map de todos los códigos de error del sistema disponibles desde la API de Node.js. La asignación entre códigos de error y nombres de error depende de la plataforma. Consulte Errores comunes del sistema para conocer los nombres de los errores comunes.

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)

Agregado en: v23.1.0

• err <number>
• Devuelve: <string>

Devuelve el mensaje de texto para un código de error numérico que proviene de una API de Node.js. La correspondencia entre los códigos de error y los mensajes de texto depende de la plataforma.

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)

[Historial]

Versión	Cambios
v5.0.0	El parámetro constructor ahora puede referirse a una clase ES6.
v0.3.0	Agregado en: v0.3.0

[Estable: 3 - Heredado]

Estable: 3 Estabilidad: 3 - Heredado: Utilice la sintaxis de clase ES2015 y la palabra clave extends en su lugar.

• constructor <Function>
• superConstructor <Function>

Se desaconseja el uso de util.inherits(). Utilice las palabras clave class y extends de ES6 para obtener compatibilidad con la herencia a nivel de lenguaje. Tenga en cuenta también que los dos estilos son semánticamente incompatibles.

Hereda los métodos del prototipo de un constructor en otro. El prototipo de constructor se establecerá en un nuevo objeto creado a partir de superConstructor.

Esto añade principalmente alguna validación de entrada sobre Object.setPrototypeOf(constructor.prototype, superConstructor.prototype). Como comodidad adicional, se podrá acceder a superConstructor a través de la propiedad 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!"

Ejemplo de ES6 utilizando class y 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(objeto[, opciones])

util.inspect(objeto[, showHidden[, profundidad[, colores]]])

[Historial]

Versión	Cambios
v16.18.0	Se añadió soporte para maxArrayLength al inspeccionar Set y Map.
v17.3.0, v16.14.0	Ahora se soporta la opción numericSeparator.
v13.0.0	Las referencias circulares ahora incluyen un marcador a la referencia.
v14.6.0, v12.19.0	Si el objeto proviene de un vm.Context diferente ahora, una función de inspección personalizada en él ya no recibirá argumentos específicos del contexto.
v13.13.0, v12.17.0	Ahora se soporta la opción maxStringLength.
v13.5.0, v12.16.0	Las propiedades del prototipo definidas por el usuario se inspeccionan en caso de que showHidden sea true.
v12.0.0	El valor predeterminado de las opciones compact se cambió a 3 y el valor predeterminado de las opciones breakLength se cambió a 80.
v12.0.0	Las propiedades internas ya no aparecen en el argumento de contexto de una función de inspección personalizada.
v11.11.0	La opción compact acepta números para un nuevo modo de salida.
v11.7.0	Los ArrayBuffers ahora también muestran su contenido binario.
v11.5.0	Ahora se soporta la opción getters.
v11.4.0	La profundidad predeterminada de depth volvió a ser 2.
v11.0.0	La profundidad predeterminada de depth cambió a 20.
v11.0.0	La salida de la inspección ahora está limitada a unos 128 MiB. Los datos que superen ese tamaño no se inspeccionarán por completo.
v10.12.0	Ahora se soporta la opción sorted.
v10.6.0	Ahora es posible inspeccionar listas enlazadas y objetos similares hasta el tamaño máximo de la pila de llamadas.
v10.0.0	Ahora también se pueden inspeccionar las entradas de WeakMap y WeakSet.
v9.9.0	Ahora se soporta la opción compact.
v6.6.0	Las funciones de inspección personalizadas ahora pueden devolver this.
v6.3.0	Ahora se soporta la opción breakLength.
v6.1.0	Ahora se soporta la opción maxArrayLength; en particular, las matrices largas se truncan de forma predeterminada.
v6.1.0	Ahora se soporta la opción showProxy.
v0.3.0	Añadido en: v0.3.0

• objeto <any> Cualquier primitivo de JavaScript u Object.

• opciones <Object>

  • showHidden <boolean> Si es true, los símbolos y propiedades no enumerables de objeto se incluyen en el resultado formateado. Las entradas de WeakMap y WeakSet también se incluyen, así como las propiedades del prototipo definidas por el usuario (excluidas las propiedades de los métodos). Valor predeterminado: false.
  • depth <number> Especifica el número de veces que se debe aplicar la recursividad al formatear objeto. Esto es útil para inspeccionar objetos grandes. Para aplicar la recursividad hasta el tamaño máximo de la pila de llamadas, pasa Infinity o null. Valor predeterminado: 2.
  • colors <boolean> Si es true, la salida se estiliza con códigos de color ANSI. Los colores son personalizables. Consulta Personalización de los colores de util.inspect. Valor predeterminado: false.
  • customInspect <boolean> Si es false, no se invocan las funciones [util.inspect.custom](depth, opts, inspect). Valor predeterminado: true.
  • showProxy <boolean> Si es true, la inspección de Proxy incluye los objetos target y handler. Valor predeterminado: false.
  • maxArrayLength <integer> Especifica el número máximo de elementos de Array, TypedArray, Map, Set, WeakMap y WeakSet que se deben incluir al formatear. Establece en null o Infinity para mostrar todos los elementos. Establece en 0 o un valor negativo para no mostrar ningún elemento. Valor predeterminado: 100.
  • maxStringLength <integer> Especifica el número máximo de caracteres que se deben incluir al formatear. Establece en null o Infinity para mostrar todos los elementos. Establece en 0 o un valor negativo para no mostrar ningún carácter. Valor predeterminado: 10000.
  • breakLength <integer> La longitud en la que los valores de entrada se dividen en varias líneas. Establece en Infinity para formatear la entrada como una sola línea (en combinación con compact establecido en true o cualquier número >= 1). Valor predeterminado: 80.
  • compact <boolean> | <integer> Establecer esto en false hace que cada clave de objeto se muestre en una nueva línea. Se dividirá en nuevas líneas en el texto que sea más largo que breakLength. Si se establece en un número, los n elementos internos más se unen en una sola línea siempre que todas las propiedades quepan en breakLength. Los elementos de matrices cortas también se agrupan. Para obtener más información, consulta el siguiente ejemplo. Valor predeterminado: 3.
  • sorted <boolean> | <Function> Si se establece en true o una función, todas las propiedades de un objeto, y las entradas de Set y Map se ordenan en la cadena resultante. Si se establece en true, se utiliza la ordenación predeterminada. Si se establece en una función, se utiliza como una función de comparación.
  • getters <boolean> | <string> Si se establece en true, se inspeccionan los getters. Si se establece en 'get', solo se inspeccionan los getters sin un setter correspondiente. Si se establece en 'set', solo se inspeccionan los getters con un setter correspondiente. Esto podría causar efectos secundarios dependiendo de la función getter. Valor predeterminado: false.
  • numericSeparator <boolean> Si se establece en true, se utiliza un guion bajo para separar cada tres dígitos en todos los bigints y números. Valor predeterminado: false.

• Devuelve: <string> La representación de objeto.

El método util.inspect() devuelve una representación de cadena de objeto que está pensada para la depuración. La salida de util.inspect puede cambiar en cualquier momento y no se debe depender de ella mediante programación. Se pueden pasar opciones adicionales que alteren el resultado. util.inspect() utilizará el nombre del constructor y/o @@toStringTag para crear una etiqueta identificable para un valor inspeccionado.

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

Las referencias circulares apuntan a su ancla utilizando un índice de referencia:

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

El siguiente ejemplo inspecciona todas las propiedades del objeto util:

const util = require('node:util')

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

El siguiente ejemplo destaca el efecto de la opción 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 línea larga
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Establecer `compact` en false o un entero crea una salida más fácil de leer.
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'
//   }
// }

// Establecer `breakLength` en, p. ej., 150 imprimirá el texto "Lorem ipsum" en una
// sola línea.

La opción showHidden permite inspeccionar las entradas de WeakMap y WeakSet. Si hay más entradas que maxArrayLength, no hay garantía de qué entradas se muestran. Esto significa que recuperar las mismas entradas de WeakSet dos veces puede resultar en una salida diferente. Además, las entradas sin referencias fuertes restantes pueden ser recogidas por el recolector de basura en cualquier 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 } }

La opción sorted garantiza que el orden de inserción de propiedades de un objeto no afecte el resultado de util.inspect().

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

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

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

La opción numericSeparator añade un guion bajo cada tres dígitos a todos los números.

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() es un método sincrónico diseñado para la depuración. Su longitud máxima de salida es de aproximadamente 128 MiB. Las entradas que resulten en una salida más larga se truncarán.

Personalización de los colores de util.inspect

La salida de color (si está habilitada) de util.inspect se puede personalizar globalmente a través de las propiedades util.inspect.styles y util.inspect.colors.

util.inspect.styles es un mapa que asocia un nombre de estilo a un color de util.inspect.colors.

Los estilos predeterminados y los colores asociados son:

• bigint: yellow
• boolean: yellow
• date: magenta
• module: underline
• name: (sin estilo)
• null: bold
• number: yellow
• regexp: red
• special: cyan (p. ej., Proxies)
• string: green
• symbol: green
• undefined: grey

El estilo de color utiliza códigos de control ANSI que pueden no ser compatibles con todas las terminales. Para verificar la compatibilidad de color, usa tty.hasColors().

Los códigos de control predefinidos se enumeran a continuación (agrupados como "Modificadores", "Colores de primer plano" y "Colores de fondo").

Modificadores

La compatibilidad con los modificadores varía entre las diferentes terminales. En su mayoría, se ignorarán si no son compatibles.

• reset - Restablece todos los modificadores (de color) a sus valores predeterminados
• bold - Pone el texto en negrita
• italic - Pone el texto en cursiva
• underline - Subraya el texto
• strikethrough - Pone una línea horizontal en el centro del texto (Alias: strikeThrough, crossedout, crossedOut)
• hidden - Imprime el texto, pero lo hace invisible (Alias: ocultar)
• dim - Disminuye la intensidad del color (Alias: faint)
• overlined - Pone el texto sobrelineado
• blink - Oculta y muestra el texto en un intervalo
• inverse - Intercambia los colores de primer plano y de fondo (Alias: swapcolors, swapColors)
• doubleunderline - Pone el texto doble subrayado (Alias: doubleUnderline)
• framed - Dibuja un marco alrededor del texto

Colores de primer plano

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

Colores de fondo

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

Funciones de inspección personalizadas en objetos

[Historial]

Versión	Cambios
v17.3.0, v16.14.0	Se añade el argumento inspect para una mayor interoperabilidad.
v0.1.97	Añadido en: v0.1.97

Los objetos también pueden definir su propia función [util.inspect.custom](depth, opts, inspect), que util.inspect() invocará y usará el resultado al inspeccionar el objeto.

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

    // Cinco espacios de relleno porque ese es el tamaño 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)
// Devuelve: "Box< true >"

Las funciones personalizadas [util.inspect.custom](depth, opts, inspect) normalmente devuelven una cadena, pero pueden devolver un valor de cualquier tipo que util.inspect() formateará según corresponda.

const util = require('node:util')

const obj = { foo: 'esto no se mostrará en la salida de inspect()' }
obj[util.inspect.custom] = depth => {
  return { bar: 'baz' }
}

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

util.inspect.custom

[Historial]

Versión	Cambios
v10.12.0	Esto ahora está definido como un símbolo compartido.
v6.6.0	Añadido en: v6.6.0

• <symbol> que puede usarse para declarar funciones de inspección personalizadas.

Además de ser accesible a través de util.inspect.custom, este símbolo está registrado globalmente y puede accederse a él en cualquier entorno como Symbol.for('nodejs.util.inspect.custom').

Usar esto permite que el código se escriba de manera portable, de modo que la función de inspección personalizada se use en un entorno de Node.js y se ignore en el navegador. La función util.inspect() misma se pasa como tercer argumento a la función de inspección personalizada para permitir una mayor portabilidad.

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

Ver Funciones de inspección personalizadas en objetos para más detalles.

util.inspect.defaultOptions

Agregado en: v6.4.0

El valor defaultOptions permite la personalización de las opciones predeterminadas utilizadas por util.inspect. Esto es útil para funciones como console.log o util.format que llaman implícitamente a util.inspect. Debe establecerse en un objeto que contenga una o más opciones válidas de util.inspect(). También se admite la configuración directa de las propiedades de las opciones.

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

console.log(arr) // Muestra el array truncado
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // muestra el array completo

util.isDeepStrictEqual(val1, val2)

Agregado en: v9.0.0

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

Devuelve true si hay una igualdad estricta profunda entre val1 y val2. De lo contrario, devuelve false.

Consulta assert.deepStrictEqual() para obtener más información sobre la igualdad estricta profunda.

Clase: util.MIMEType

Añadido en: v19.1.0, v18.13.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Una implementación de la clase MIMEType.

De acuerdo con las convenciones del navegador, todas las propiedades de los objetos MIMEType se implementan como getters y setters en el prototipo de la clase, en lugar de como propiedades de datos en el propio objeto.

Una cadena MIME es una cadena estructurada que contiene múltiples componentes significativos. Cuando se analiza, se devuelve un objeto MIMEType que contiene propiedades para cada uno de estos componentes.

Constructor: new MIMEType(input)

• input <string> El MIME de entrada para analizar

Crea un nuevo objeto MIMEType analizando la 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')

Se lanzará un TypeError si la input no es un MIME válido. Tenga en cuenta que se hará un esfuerzo para forzar los valores dados a cadenas. Por ejemplo:

ESM

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

CJS

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

mime.type

• <string>

Obtiene y establece la parte del tipo del MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

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

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

mime.subtype

• <string>

Obtiene y establece la parte del subtipo del MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

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

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

mime.essence

• <string>

Obtiene la esencia del MIME. Esta propiedad es de solo lectura. Utilice mime.type o mime.subtype para alterar el MIME.

ESM

import { MIMEType } from 'node:util'

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

CJS

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

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

mime.params

• <MIMEParams>

Obtiene el objeto MIMEParams que representa los parámetros del MIME. Esta propiedad es de solo lectura. Consulte la documentación de MIMEParams para obtener más detalles.

mime.toString()

• Devuelve: <string>

El método toString() del objeto MIMEType devuelve el MIME serializado.

Debido a la necesidad de cumplir con los estándares, este método no permite a los usuarios personalizar el proceso de serialización del MIME.

mime.toJSON()

• Devuelve: <string>

Alias para mime.toString().

Este método se llama automáticamente cuando un objeto MIMEType se serializa con JSON.stringify().

ESM

import { MIMEType } from 'node:util'

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

CJS

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

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

Clase: util.MIMEParams

Añadido en: v19.1.0, v18.13.0

La API MIMEParams proporciona acceso de lectura y escritura a los parámetros de un MIMEType.

Constructor: new MIMEParams()

Crea un nuevo objeto MIMEParams con parámetros vacíos

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>

Elimina todos los pares nombre-valor cuyo nombre sea name.

mimeParams.entries()

• Devuelve: <Iterator>

Devuelve un iterador sobre cada uno de los pares nombre-valor en los parámetros. Cada elemento del iterador es un Array de JavaScript. El primer elemento del array es el name, el segundo elemento del array es el value.

mimeParams.get(name)

• name <string>
• Devuelve: <string> | <null> Una cadena o null si no hay ningún par nombre-valor con el name dado.

Devuelve el valor del primer par nombre-valor cuyo nombre es name. Si no existen tales pares, se devuelve null.

mimeParams.has(name)

• name <string>
• Devuelve: <boolean>

Devuelve true si existe al menos un par nombre-valor cuyo nombre es name.

mimeParams.keys()

• Devuelve: <Iterator>

Devuelve un iterador sobre los nombres de cada par nombre-valor.

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

mimeParams.set(name, value)

• name <string>
• value <string>

Establece el valor en el objeto MIMEParams asociado con name a value. Si hay algún par nombre-valor preexistente cuyos nombres son name, establece el valor del primer par de este tipo a 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())
// Imprime: 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())
// Imprime: foo=def;bar=1;baz=xyz

mimeParams.values()

• Devuelve: <Iterator>

Devuelve un iterador sobre los valores de cada par nombre-valor.

mimeParams[@@iterator]()

• Devuelve: <Iterator>

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

util.parseArgs([config])

[Historial]

Versión	Cambios
v22.4.0, v20.16.0	Se agrega soporte para permitir opciones negativas en la config de entrada.
v20.0.0	La API ya no es experimental.
v18.11.0, v16.19.0	Se agrega soporte para valores predeterminados en la config de entrada.
v18.7.0, v16.17.0	Se agrega soporte para devolver información de análisis detallada usando tokens en la config de entrada y las propiedades devueltas.
v18.3.0, v16.17.0	Agregado en: v18.3.0, v16.17.0

• config <Object> Se usa para proporcionar argumentos para el análisis y para configurar el analizador. config admite las siguientes propiedades:

  • args <string[]> matriz de cadenas de argumentos. Predeterminado: process.argv con execPath y filename eliminados.
  • options <Object> Se usa para describir los argumentos que conoce el analizador. Las claves de options son los nombres largos de las opciones y los valores son un <Object> que acepta las siguientes propiedades:
  • type <string> Tipo de argumento, que debe ser boolean o string.
  • multiple <boolean> Indica si esta opción se puede proporcionar varias veces. Si es true, todos los valores se recopilarán en una matriz. Si es false, los valores de la opción son los últimos en ganar. Predeterminado: false.
  • short <string> Un alias de un solo carácter para la opción.
  • default <string> | <boolean> | <string[]> | <boolean[]> El valor de opción predeterminado cuando no está establecido por args. Debe ser del mismo tipo que la propiedad type. Cuando multiple es true, debe ser una matriz.
  • strict <boolean> Indica si se debe generar un error cuando se encuentran argumentos desconocidos, o cuando se pasan argumentos que no coinciden con el type configurado en options. Predeterminado: true.
  • allowPositionals <boolean> Indica si este comando acepta argumentos posicionales. Predeterminado: false si strict es true, de lo contrario true.
  • allowNegative <boolean> Si es true, permite establecer explícitamente las opciones booleanas en false prefijando el nombre de la opción con --no-. Predeterminado: false.
  • tokens <boolean> Devuelve los tokens analizados. Esto es útil para extender el comportamiento incorporado, desde agregar verificaciones adicionales hasta reprocesar los tokens de diferentes maneras. Predeterminado: false.

• Devuelve: <Object> Los argumentos de la línea de comandos analizados:

  • values <Object> Una asignación de nombres de opción analizados con sus valores <string> o <boolean>.
  • positionals <string[]> Argumentos posicionales.
  • tokens <Object[]> | <undefined> Consulte la sección tokens de parseArgs. Solo se devuelve si config incluye tokens: true.

Proporciona una API de nivel superior para el análisis de argumentos de línea de comandos en lugar de interactuar directamente con process.argv. Toma una especificación para los argumentos esperados y devuelve un objeto estructurado con las opciones y los argumentos posicionales analizados.

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

parseArgs tokens

Se dispone de información detallada de análisis para añadir comportamientos personalizados especificando tokens: true en la configuración. Los tokens devueltos tienen propiedades que describen:

• todos los tokens

  • kind <string> Uno de 'option', 'positional' o 'option-terminator'.
  • index <number> Índice del elemento en args que contiene el token. Por lo tanto, el argumento fuente para un token es args[token.index].

• tokens de opción

  • name <string> Nombre largo de la opción.
  • rawName <string> Cómo se usa la opción en args, como -f o --foo.
  • value <string> | <undefined> Valor de la opción especificado en args. Indefinido para las opciones booleanas.
  • inlineValue <boolean> | <undefined> Si el valor de la opción se especificó en línea, como --foo=bar.

• tokens posicionales

  • value <string> El valor del argumento posicional en args (es decir, args[index]).

• token option-terminator

Los tokens devueltos están en el orden en que se encuentran en los argumentos de entrada. Las opciones que aparecen más de una vez en args producen un token por cada uso. Los grupos de opciones cortas como -xy se expanden a un token por cada opción. Por lo tanto, -xxx produce tres tokens.

Por ejemplo, para añadir soporte para una opción negada como --no-color (que allowNegative admite cuando la opción es de tipo boolean), los tokens devueltos se pueden reprocesar para cambiar el valor almacenado para la opción negada.

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

// Reprocesa los tokens de opción y sobrescribe los valores devueltos.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Almacena foo:false para --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Guarda el valor para que el último gane si hay tanto --foo como --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 })

// Reprocesa los tokens de opción y sobrescribe los valores devueltos.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Almacena foo:false para --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Guarda el valor para que el último gane si hay tanto --foo como --no-foo.
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })

Ejemplo de uso que muestra opciones negadas, y cuando una opción se utiliza de varias maneras, entonces la última gana.

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

[Estable: 1 - Experimental]

Estable: 1 Estable: 1.1 - Desarrollo activo

Añadido en: v21.7.0, v20.12.0

• content <string>

El contenido sin procesar de un archivo .env.

• Devuelve: <Object>

Dado un archivo .env de ejemplo:

CJS

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

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

ESM

import { parseEnv } from 'node:util'

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

util.promisify(original)

[Historial]

Versión	Cambios
v20.8.0	Llamar a promisify en una función que devuelve una Promise está obsoleto.
v8.0.0	Añadido en: v8.0.0

• original <Function>
• Devuelve: <Function>

Toma una función siguiendo el estilo común de callback de primer error, es decir, tomando un callback (err, value) => ... como el último argumento, y devuelve una versión que devuelve promesas.

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

const stat = util.promisify(fs.stat)
stat('.')
  .then(stats => {
    // Haz algo con `stats`
  })
  .catch(error => {
    // Maneja el error.
  })

O, equivalentemente, usando async functions:

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(`Este directorio es propiedad de ${stats.uid}`)
}

callStat()

Si hay una propiedad original[util.promisify.custom] presente, promisify devolverá su valor, ver Funciones con promesa personalizadas.

promisify() asume que original es una función que toma un callback como su argumento final en todos los casos. Si original no es una función, promisify() lanzará un error. Si original es una función pero su último argumento no es un callback de primer error, se le pasará igualmente un callback de primer error como su último argumento.

Usar promisify() en métodos de clase u otros métodos que usan this puede que no funcione como se espera a menos que se maneje de forma especial:

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: No se puede leer la propiedad 'a' de 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'

Funciones personalizadas convertidas a promesa

Usando el símbolo util.promisify.custom, se puede anular el valor de retorno 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])
// imprime 'true'

Esto puede ser útil para los casos en que la función original no sigue el formato estándar de tomar una devolución de llamada con el error como primer argumento.

Por ejemplo, con una función que toma (foo, onSuccessCallback, onErrorCallback):

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

Si promisify.custom está definido pero no es una función, promisify() lanzará un error.

util.promisify.custom

[Historial]

Versión	Cambios
v13.12.0, v12.16.2	Ahora esto se define como un símbolo compartido.
v8.0.0	Añadido en: v8.0.0

• <symbol> que se puede usar para declarar variantes personalizadas convertidas a promesa de funciones, consulte Funciones personalizadas convertidas a promesa.

Además de ser accesible a través de util.promisify.custom, este símbolo está registrado globalmente y se puede acceder a él en cualquier entorno como Symbol.for('nodejs.util.promisify.custom').

Por ejemplo, con una función que toma (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)

Añadido en: v16.11.0

• str <string>
• Devuelve: <string>

Devuelve str con todos los códigos de escape ANSI eliminados.

console.log(util.stripVTControlCharacters('\u001B[4mvalor\u001B[0m'))
// Imprime "valor"

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

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable.

[Historial]

Versión	Cambios
v23.5.0	styleText ahora es estable.
v22.8.0, v20.18.0	Respeta isTTY y variables de entorno como NO_COLORS, NODE_DISABLE_COLORS y FORCE_COLOR.
v21.7.0, v20.12.0	Añadido en: v21.7.0, v20.12.0

• format <string> | <Array> Un formato de texto o un array de formatos de texto definidos en util.inspect.colors.
• text <string> El texto que se va a formatear.
• options <Object>
  • validateStream <boolean> Cuando es true, se comprueba si stream puede manejar colores. Predeterminado: true.
  • stream <Stream> Un stream que se validará para comprobar si se puede colorear. Predeterminado: process.stdout.

Esta función devuelve un texto formateado considerando el format pasado para imprimir en una terminal. Es consciente de las capacidades de la terminal y actúa de acuerdo con la configuración establecida a través de las variables de entorno NO_COLORS, NODE_DISABLE_COLORS y FORCE_COLOR.

ESM

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

const successMessage = styleText('green', '¡Éxito!')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  '¡Error! ¡Error!',
  // Valida si process.stderr tiene TTY
  { stream: stderr }
)
console.error(successMessage)

CJS

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

const successMessage = styleText('green', '¡Éxito!')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  '¡Error! ¡Error!',
  // Valida si process.stderr tiene TTY
  { stream: stderr }
)
console.error(successMessage)

util.inspect.colors también proporciona formatos de texto como italic y underline y puedes combinar ambos:

console.log(util.styleText(['underline', 'italic'], 'Mi mensaje subrayado en cursiva'))

Al pasar un array de formatos, el orden del formato aplicado es de izquierda a derecha, por lo que el siguiente estilo podría sobreescribir el anterior.

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

La lista completa de formatos se puede encontrar en modificadores.

Clase: util.TextDecoder

[Historial]

Versión	Cambios
v11.0.0	La clase ahora está disponible en el objeto global.
v8.3.0	Añadido en: v8.3.0

Una implementación de la API TextDecoder del Estándar de codificación WHATWG.

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

Codificaciones compatibles con WHATWG

Según el Estándar de codificación WHATWG, las codificaciones compatibles con la API TextDecoder se describen en las tablas siguientes. Para cada codificación, se pueden usar uno o más alias.

Diferentes configuraciones de compilación de Node.js admiten diferentes conjuntos de codificaciones. (consulte Internacionalización)

Codificaciones admitidas de forma predeterminada (con datos ICU completos)

Codificación	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'

Codificaciones admitidas cuando Node.js se compila con la opción small-icu

Codificación	Alias
'utf-8'	'unicode-1-1-utf-8' , 'utf8'
'utf-16le'	'utf-16'
'utf-16be'

Codificaciones admitidas cuando ICU está deshabilitado

Codificación	Alias
'utf-8'	'unicode-1-1-utf-8' , 'utf8'
'utf-16le'	'utf-16'

La codificación 'iso-8859-16' que aparece en el Estándar de Codificación WHATWG no es compatible.

new TextDecoder([encoding[, options]])

• encoding <string> Identifica la codificación que admite esta instancia de TextDecoder. Predeterminado: 'utf-8'.
• options <Object>
  • fatal <boolean> true si los fallos de descodificación son fatales. Esta opción no es compatible cuando ICU está deshabilitado (véase Internacionalización). Predeterminado: false.
  • ignoreBOM <boolean> Cuando es true, el TextDecoder incluirá la marca de orden de bytes en el resultado descodificado. Cuando es false, la marca de orden de bytes se eliminará de la salida. Esta opción solo se utiliza cuando la codificación es 'utf-8', 'utf-16be' o 'utf-16le'. Predeterminado: false.

Crea una nueva instancia de TextDecoder. La codificación puede especificar una de las codificaciones admitidas o un alias.

La clase TextDecoder también está disponible en el objeto global.

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

• input <ArrayBuffer> | <DataView> | <TypedArray> Una instancia de ArrayBuffer, DataView o TypedArray que contiene los datos codificados.

• options <Object>

  • stream <boolean> true si se esperan fragmentos adicionales de datos. Predeterminado: false.

• Devuelve: <string>

Decodifica la input y devuelve una cadena. Si options.stream es true, cualquier secuencia de bytes incompleta que ocurra al final de la input se almacena internamente en búfer y se emite después de la siguiente llamada a textDecoder.decode().

Si textDecoder.fatal es true, los errores de decodificación que ocurran resultarán en el lanzamiento de un TypeError.

textDecoder.encoding

• <string>

La codificación admitida por la instancia de TextDecoder.

textDecoder.fatal

• <boolean>

El valor será true si los errores de decodificación resultan en que se arroje un TypeError.

textDecoder.ignoreBOM

• <boolean>

El valor será true si el resultado de la decodificación incluye la marca de orden de bytes.

Clase: util.TextEncoder

[Historial]

Versión	Cambios
v11.0.0	La clase ahora está disponible en el objeto global.
v8.3.0	Añadido en: v8.3.0

Una implementación de la API TextEncoder del Estándar de codificación WHATWG. Todas las instancias de TextEncoder solo admiten la codificación UTF-8.

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

La clase TextEncoder también está disponible en el objeto global.

textEncoder.encode([input])

• input <string> El texto a codificar. Predeterminado: una cadena vacía.
• Devuelve: <Uint8Array>

Codifica en UTF-8 la cadena input y devuelve un Uint8Array que contiene los bytes codificados.

textEncoder.encodeInto(src, dest)

Añadido en: v12.11.0

• src <string> El texto a codificar.
• dest <Uint8Array> El array para guardar el resultado de la codificación.
• Devuelve: <Object>
  • read <number> Las unidades de código Unicode leídas de src.
  • written <number> Los bytes UTF-8 escritos en dest.

Codifica en UTF-8 la cadena src al Uint8Array dest y devuelve un objeto que contiene las unidades de código Unicode leídas y los bytes UTF-8 escritos.

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

textEncoder.encoding

• <string>

La codificación compatible con la instancia TextEncoder. Siempre establecida en 'utf-8'.

util.toUSVString(string)

Agregado en: v16.8.0, v14.18.0

• string <string>

Devuelve la string después de reemplazar cualquier punto de código suplente (o, de manera equivalente, cualquier unidad de código suplente no emparejada) con el "carácter de reemplazo" Unicode U+FFFD.

util.transferableAbortController()

Agregado en: v18.11.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Crea y devuelve una instancia de <AbortController> cuyo <AbortSignal> está marcado como transferible y puede usarse con structuredClone() o postMessage().

util.transferableAbortSignal(signal)

Agregado en: v18.11.0

[Estable: 1 - Experimental]

Estable: 1 Estable: 1 - Experimental

• signal <AbortSignal>
• Devuelve: <AbortSignal>

Marca la <AbortSignal> dada como transferible para que pueda usarse con structuredClone() y postMessage().

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

util.aborted(signal, resource)

Agregado en: v19.7.0, v18.16.0

[Estable: 1 - Experimental]

Estable: 1 Estable: 1 - Experimental

• signal <AbortSignal>
• resource <Object> Cualquier objeto no nulo vinculado a la operación que se puede cancelar y que se mantiene débilmente. Si resource se recolecta como basura antes de que se cancele la signal, la promesa permanece pendiente, lo que permite que Node.js deje de rastrearla. Esto ayuda a prevenir fugas de memoria en operaciones de larga duración o no cancelables.
• Devuelve: <Promise>

Escucha el evento de cancelación en la signal proporcionada y devuelve una promesa que se resuelve cuando se cancela la signal. Si se proporciona resource, hace referencia débilmente al objeto asociado de la operación, por lo que si resource se recolecta como basura antes de que se cancele la signal, la promesa devuelta permanecerá pendiente. Esto evita fugas de memoria en operaciones de larga duración o no cancelables.

CJS

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

// Obtener un objeto con una señal que se puede cancelar, como un recurso u operación personalizada.
const dependent = obtainSomethingAbortable()

// Pasar `dependent` como el recurso, indicando que la promesa solo debe resolverse
// si `dependent` todavía está en memoria cuando se cancela la señal.
aborted(dependent.signal, dependent).then(() => {
  // Este código se ejecuta cuando se cancela `dependent`.
  console.log('El recurso dependiente fue cancelado.')
})

// Simular un evento que activa la cancelación.
dependent.on('event', () => {
  dependent.abort() // Esto hará que la promesa `aborted` se resuelva.
})

ESM

import { aborted } from 'node:util'

// Obtener un objeto con una señal que se puede cancelar, como un recurso u operación personalizada.
const dependent = obtainSomethingAbortable()

// Pasar `dependent` como el recurso, indicando que la promesa solo debe resolverse
// si `dependent` todavía está en memoria cuando se cancela la señal.
aborted(dependent.signal, dependent).then(() => {
  // Este código se ejecuta cuando se cancela `dependent`.
  console.log('El recurso dependiente fue cancelado.')
})

// Simular un evento que activa la cancelación.
dependent.on('event', () => {
  dependent.abort() // Esto hará que la promesa `aborted` se resuelva.
})

util.types

[Historial]

Versión	Cambios
v15.3.0	Expuesto como require('util/types').
v10.0.0	Añadido en: v10.0.0

util.types proporciona verificaciones de tipo para diferentes tipos de objetos incorporados. A diferencia de instanceof o Object.prototype.toString.call(value), estas verificaciones no inspeccionan las propiedades del objeto que son accesibles desde JavaScript (como su prototipo), y usualmente tienen la sobrecarga de llamar a C++.

El resultado generalmente no garantiza qué tipos de propiedades o comportamientos expone un valor en JavaScript. Son principalmente útiles para los desarrolladores de complementos que prefieren realizar la verificación de tipo en JavaScript.

Se puede acceder a la API a través de require('node:util').types o require('node:util/types').

util.types.isAnyArrayBuffer(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de ArrayBuffer o SharedArrayBuffer.

Consulte también util.types.isArrayBuffer() y util.types.isSharedArrayBuffer().

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

util.types.isArrayBufferView(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia de una de las vistas de ArrayBuffer, como objetos de arrays tipados 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)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un objeto arguments.

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

util.types.isArrayBuffer(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia integrada de ArrayBuffer. Esto no incluye instancias de SharedArrayBuffer. Normalmente, es deseable probar ambos; consulte util.types.isAnyArrayBuffer() para ello.

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

util.types.isAsyncFunction(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una función asíncrona. Esto solo reporta lo que el motor de JavaScript está viendo; en particular, el valor de retorno puede no coincidir con el código fuente original si se utilizó una herramienta de transpilación.

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

util.types.isBigInt64Array(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia de BigInt64Array.

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

util.types.isBigIntObject(value)

Añadido en: v10.4.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un objeto BigInt, p. ej. creado por Object(BigInt(123)).

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

util.types.isBigUint64Array(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia de BigUint64Array.

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

util.types.isBooleanObject(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un objeto booleano, p. ej., creado por new Boolean().

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

util.types.isBoxedPrimitive(value)

Agregado en: v10.11.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es cualquier objeto primitivo empaquetado, p. ej., creado por new Boolean(), new String() o Object(Symbol()).

Por ejemplo:

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

util.types.isCryptoKey(value)

Agregado en: v16.2.0

• value <Objeto>
• Devuelve: <boolean>

Devuelve true si value es un <CryptoKey>, false en caso contrario.

util.types.isDataView(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de DataView.

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

Ver también ArrayBuffer.isView().

util.types.isDate(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de Date.

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

util.types.isExternal(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un valor nativo External.

Un valor nativo External es un tipo especial de objeto que contiene un puntero C++ sin formato (void*) para acceso desde código nativo y no tiene otras propiedades. Dichos objetos son creados por internos de Node.js o complementos nativos. En JavaScript, son objetos congelados 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) // devuelve true
util.types.isExternal(0) // devuelve false
util.types.isExternal(new String('foo')) // devuelve false

Para obtener más información sobre napi_create_external, consulte napi_create_external().

util.types.isFloat32Array(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de Float32Array.

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

util.types.isFloat64Array(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de Float64Array.

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

util.types.isGeneratorFunction(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una función generadora. Esto solo informa lo que está viendo el motor de JavaScript; en particular, el valor de retorno puede no coincidir con el código fuente original si se utilizó una herramienta de transpilación.

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

util.types.isGeneratorObject(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un objeto generador como el que devuelve una función generadora incorporada. Esto solo informa lo que está viendo el motor de JavaScript; en particular, el valor de retorno puede no coincidir con el código fuente original si se utilizó una herramienta de transpilación.

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

util.types.isInt8Array(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia integrada de Int8Array.

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

util.types.isInt16Array(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia integrada de Int16Array.

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

util.types.isInt32Array(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia integrada de Int32Array.

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

util.types.isKeyObject(value)

Agregado en: v16.2.0

• value <Object>
• Devuelve: <boolean>

Devuelve true si value es un <KeyObject>, false en caso contrario.

util.types.isMap(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia de Map incorporada.

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

util.types.isMapIterator(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un iterador devuelto para una instancia de Map incorporada.

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

util.types.isModuleNamespaceObject(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia de un Objeto de espacio de nombres de módulo.

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

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

util.types.isNativeError(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor fue devuelto por el constructor de un tipo Error integrado.

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

Las subclases de los tipos de error nativos también son errores nativos:

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

Que un valor sea instanceof una clase de error nativa no es equivalente a que isNativeError() devuelva true para ese valor. isNativeError() devuelve true para errores que provienen de un ámbito diferente, mientras que instanceof Error devuelve false para estos errores:

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

Por el contrario, isNativeError() devuelve false para todos los objetos que no fueron devueltos por el constructor de un error nativo. Eso incluye valores que son instanceof errores nativos:

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

util.types.isNumberObject(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un objeto número, p. ej., creado por new Number().

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

util.types.isPromise(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una Promise incorporada.

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

util.types.isProxy(value)

Añadido en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia de Proxy.

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

util.types.isRegExp(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un objeto de expresión regular.

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

util.types.isSet(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia Set incorporada.

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

util.types.isSetIterator(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un iterador devuelto para una instancia Set incorporada.

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

util.types.isSharedArrayBuffer(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de SharedArrayBuffer. Esto no incluye instancias de ArrayBuffer. Por lo general, es deseable probar ambas; consulte util.types.isAnyArrayBuffer() para eso.

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

util.types.isStringObject(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un objeto string, p. ej. creado por new String().

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

util.types.isSymbolObject(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es un objeto símbolo, creado al llamar a Object() en un primitivo Symbol.

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

util.types.isTypedArray(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia integrada de TypedArray.

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

Ver también ArrayBuffer.isView().

util.types.isUint8Array(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de Uint8Array.

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

util.types.isUint8ClampedArray(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de Uint8ClampedArray.

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

util.types.isUint16Array(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de Uint16Array.

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

util.types.isUint32Array(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de Uint32Array.

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

util.types.isWeakMap(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de WeakMap.

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

util.types.isWeakSet(value)

Agregado en: v10.0.0

• value <any>
• Devuelve: <boolean>

Devuelve true si el valor es una instancia incorporada de WeakSet.

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

APIs en desuso

Las siguientes APIs están en desuso y ya no deberían utilizarse. Las aplicaciones y los módulos existentes deberían actualizarse para encontrar enfoques alternativos.

util._extend(target, source)

Añadido en: v0.7.5

Obsoleto desde: v6.0.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use Object.assign() en su lugar.

• target <Objeto>
• source <Objeto>

El método util._extend() nunca tuvo la intención de ser usado fuera de los módulos internos de Node.js. La comunidad lo encontró y lo usó de todos modos.

Está obsoleto y no debe usarse en código nuevo. JavaScript viene con una funcionalidad integrada muy similar a través de Object.assign().

util.isArray(object)

Añadido en: v0.6.0

Obsoleto desde: v4.0.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use Array.isArray() en su lugar.

• object <any>
• Devuelve: <booleano>

Alias para Array.isArray().

Devuelve true si el objeto dado es un Array. De lo contrario, devuelve false.

const util = require('node:util')

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