Util

[安定版: 2 - 安定版]

ソースコード: lib/util.js

node:util モジュールは、Node.js 内部 API のニーズをサポートします。多くのユーティリティは、アプリケーションおよびモジュール開発者にとっても便利です。アクセスするには：

const util = require('node:util')

`util.callbackify(original)`

追加日時: v8.2.0

original <Function> async関数
戻り値: <Function> コールバックスタイル関数

async関数（またはPromiseを返す関数）を受け取り、 (err, value) => ...コールバックを最後の引数として取る、エラーファーストコールバックスタイルに従う関数を返します。コールバックでは、最初の引数は拒否理由（Promiseが解決された場合はnull）、2 番目の引数は解決された値になります。

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

以下が出力されます。

text

hello world

コールバックは非同期的に実行され、スタックトレースは制限されます。コールバックがスローされた場合、プロセスは'uncaughtException'イベントを発行し、処理されない場合は終了します。

nullはコールバックへの最初の引数として特別な意味を持つため、ラップされた関数が偽の値を理由としてPromiseを拒否した場合、その値はreasonという名前のフィールドに元の値を格納したErrorでラップされます。

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

callbackFunction((err, ret) => {
  // Promiseが`null`で拒否された場合、Errorでラップされ、元の値は`reason`に格納されます。
  err && Object.hasOwn(err, 'reason') && err.reason === null // true
})

`util.debuglog(section[, callback])`

追加日: v0.11.3

section <string> debuglog関数が作成されるアプリケーションの部分を識別する文字列。
callback <Function> ログ関数に初めて関数が引数として渡された時に呼び出されるコールバック関数。より最適化されたログ関数が引数として渡されます。
戻り値: <Function> ログ関数

util.debuglog()メソッドは、NODE_DEBUG環境変数の存在に基づいて、デバッグメッセージをstderrに条件付きで書き込む関数を生成するために使用されます。section名がその環境変数の値に含まれている場合、返された関数はconsole.error()と同様に動作します。そうでない場合、返された関数は何もしません。

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

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

このプログラムを環境変数NODE_DEBUG=fooで実行すると、次のような出力が表示されます。

bash

FOO 3245: hello from foo [123]

ここで3245はプロセス ID です。この環境変数が設定されていない状態で実行した場合、何も出力されません。

sectionはワイルドカードもサポートします。

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

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

環境変数NODE_DEBUG=foo*で実行した場合、次のような出力が表示されます。

bash

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

NODE_DEBUG環境変数には、複数のカンマ区切りのsection名を指定できます。NODE_DEBUG=fs,net,tlsのように。

オプションのcallback引数は、初期化や不要なラッピングがない異なる関数でログ関数を置き換えるために使用できます。

const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
  // セクションが有効かどうかをテストする最適化を削除したログ関数に置き換えます。
  debuglog = debug
})

`debuglog().enabled`

追加されたバージョン: v14.9.0

<boolean>

util.debuglog().enabled ゲッターは、NODE_DEBUG 環境変数の存在に基づいて条件分岐で使用できるテストを作成するために使用されます。section名がその環境変数の値に含まれている場合、返される値はtrueになります。そうでない場合、返される値はfalseになります。

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

このプログラムを環境変数にNODE_DEBUG=fooを設定して実行すると、次のような出力が表示されます。

bash

hello from foo [123]

`util.debug(section)`

追加されたバージョン: v14.9.0

util.debuglog のエイリアスです。util.debuglog().enabled のみを使用する場合に、ロギングを意味しない可読性を許容します。

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

[履歴]

バージョン	変更
v10.0.0	非推奨警告は、コードごとに 1 回だけ出力されます。
v0.8.0	追加されたバージョン: v0.8.0

fn <Function> 非推奨となる関数。
msg <string> 非推奨関数が呼び出されたときに表示する警告メッセージ。
code <string> 非推奨コード。コードの一覧については、非推奨 API の一覧を参照してください。
戻り値: <Function> 警告を出力するようにラップされた非推奨関数。

util.deprecate()メソッドは、fn（関数またはクラスのいずれか）を非推奨としてマークされるようにラップします。

const util = require('node:util')

exports.obsoleteFunction = util.deprecate(() => {
  // ここに何か処理を行う。
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.')

呼び出されると、util.deprecate()は'warning'イベントを使用してDeprecationWarningを出力する関数を返します。警告は、返された関数が初めて呼び出されたときに、stderrに出力されます。警告が出力された後、ラップされた関数は警告を出力せずに呼び出されます。

同じオプションのcodeがutil.deprecate()の複数回呼び出しで指定された場合、そのcodeに対しては警告は 1 回だけ出力されます。

const util = require('node:util')

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001')
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001')
fn1() // コードDEP0001で非推奨警告を出力します
fn2() // 同じコードを持つため、非推奨警告を出力しません

--no-deprecationまたは--no-warningsコマンドラインフラグを使用した場合、または最初の非推奨警告の前にprocess.noDeprecationプロパティをtrueに設定した場合、util.deprecate()メソッドは何もしません。

--trace-deprecationまたは--trace-warningsコマンドラインフラグが設定されている場合、またはprocess.traceDeprecationプロパティがtrueに設定されている場合、非推奨関数が初めて呼び出されたときに、警告とスタックトレースがstderrに出力されます。

--throw-deprecationコマンドラインフラグが設定されている場合、またはprocess.throwDeprecationプロパティがtrueに設定されている場合、非推奨関数が呼び出されると例外がスローされます。

--throw-deprecationコマンドラインフラグとprocess.throwDeprecationプロパティは、--trace-deprecationとprocess.traceDeprecationよりも優先されます。

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

[履歴]

バージョン	変更点
v12.11.0	`%c` 指定子が無視されるようになりました。
v12.0.0	`format` 引数は、実際にフォーマット指定子を含む場合のみ、フォーマット文字列として扱われます。
v12.0.0	`format` 引数がフォーマット文字列でない場合、出力文字列のフォーマットは、最初の引数の型に依存しなくなりました。この変更により、最初の引数が文字列でない場合に出力されていた文字列からの引用符が削除されました。
v11.4.0	`%d`、`%f`、`%i` 指定子が、Symbol を適切にサポートするようになりました。
v11.4.0	`%o` 指定子の `depth` のデフォルト深さが再び 4 になりました。
v11.0.0	`%o` 指定子の `depth` オプションは、デフォルトの深さにフォールバックするようになりました。
v10.12.0	`%d` および `%i` 指定子が BigInt をサポートするようになりました。
v8.4.0	`%o` および `%O` 指定子がサポートされるようになりました。
v0.5.3	追加: v0.5.3

format <string> printfライクなフォーマット文字列。

util.format() メソッドは、最初の引数を printf ライクなフォーマット文字列として使用して、フォーマットされた文字列を返します。フォーマット文字列には、ゼロ個以上のフォーマット指定子を含めることができます。各指定子は、対応する引数から変換された値で置き換えられます。サポートされている指定子は次のとおりです。

%s: BigInt、Object、-0 を除くすべての値を変換するために String が使用されます。BigInt の値は n で表され、ユーザー定義の toString 関数を持たないオブジェクトは、{ depth: 0, colors: false, compact: 3 } オプションを使用して util.inspect() で検査されます。
%d: BigInt と Symbol を除くすべての値を変換するために Number が使用されます。
%i: BigInt と Symbol を除くすべての値に対して parseInt(value, 10) が使用されます。
%f: Symbol を除くすべての値に対して parseFloat(value) が使用されます。
%j: JSON。引数に循環参照が含まれる場合、文字列 '[Circular]' で置き換えられます。
%o: Object。汎用的な JavaScript オブジェクトフォーマットによるオブジェクトの文字列表現。{ showHidden: true, showProxy: true } オプションを付けた util.inspect() と同様です。列挙不可能なプロパティとプロキシを含むオブジェクト全体が表示されます。
%O: Object。汎用的な JavaScript オブジェクトフォーマットによるオブジェクトの文字列表現。オプションなしの util.inspect() と同様です。列挙不可能なプロパティとプロキシを含まないオブジェクト全体が表示されます。
%c: CSS。この指定子は無視され、渡された CSS はスキップされます。
%%: パーセント記号単独 ('%')。引数は消費しません。
戻り値: <string> フォーマットされた文字列

指定子に対応する引数がない場合、置き換えられません。

util.format('%s:%s', 'foo')
// 戻り値: 'foo:%s'

フォーマット文字列の一部ではない値は、その型が string でない場合、util.inspect() を使用してフォーマットされます。

util.format() メソッドに渡される引数が指定子の数よりも多い場合、余分な引数は、スペースで区切られて返される文字列に連結されます。

util.format('%s:%s', 'foo', 'bar', 'baz')
// 戻り値: 'foo:bar baz'

最初の引数に有効なフォーマット指定子が含まれていない場合、util.format() は、すべての引数をスペースで区切って連結した文字列を返します。

util.format(1, 2, 3)
// 戻り値: '1 2 3'

util.format() に引数が 1 つだけ渡された場合、フォーマットせずにそのまま返されます。

util.format('%% %s')
// 戻り値: '%% %s'

util.format() は同期メソッドであり、デバッグツールとして意図されています。一部の入力値は、イベントループをブロックする可能性のある大きなパフォーマンスオーバーヘッドを持つ可能性があります。この関数は注意して使用し、ホットコードパスでは決して使用しないでください。

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

追加: v10.0.0

inspectOptions <Object>
format <string>

この関数はutil.format()と同一ですが、util.inspect()に渡されるオプションを指定するinspectOptions引数を取ります。

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 })
// 'See object { foo: 42 }'を返します。ここで`42`はターミナルに出力されるときに数値として色付けされます。

`util.getCallSites(frameCountOrOptions, [options])`

[安定版: 1 - 試験的]

安定版: 1 安定性: 1.1 - アクティブ開発中

[履歴]

バージョン	変更
v23.3.0	API 名が`util.getCallSite`から`util.getCallSites()`に変更されました。
v22.9.0	追加: v22.9.0

frameCount <number> コールサイトオブジェクトとしてキャプチャするフレーム数のオプション。デフォルト: 10。許容範囲は 1 ～ 200 です。
options <Object> オプション
- sourceMap <boolean> ソースマップからスタックトレースの元の場所を再構築します。--enable-source-mapsフラグを有効にするとデフォルトで有効になります。
戻り値: <Object[]> コールサイトオブジェクトの配列
- functionName <string> このコールサイトに関連付けられた関数の名前を返します。
- scriptName <string> このコールサイトの関数のスクリプトを含むリソースの名前を返します。
- lineNumber <number> 関連する関数呼び出しの行番号（1 ベース）を返します。
- column <number> 関連する関数呼び出しの行の 1 ベースの列オフセットを返します。

呼び出し元関数のスタックを含むコールサイトオブジェクトの配列を返します。

const util = require('node:util')

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

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

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

  // ...
}

// 別のスタック層をシミュレートする関数
function anotherFunction() {
  exampleFunction()
}

anotherFunction()

sourceMapオプションをtrueに設定することで、元の場所を再構築できます。ソースマップが利用できない場合、元の場所は現在の場所と同じになります。--enable-source-mapsフラグを有効にすると（例：--experimental-transform-typesを使用する場合）、sourceMapはデフォルトで true になります。

import util from 'node:util'

interface Foo {
  foo: string
}

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

// sourceMapありの場合:
// Function Name: ''
// Script Name: example.js
// Line Number: 7
// Column Number: 26

// sourceMapなしの場合:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26

`util.getSystemErrorName(err)`

追加日: v9.7.0

err <number>
戻り値: <string>

Node.js API から取得した数値エラーコードの文字列名を返します。エラーコードとエラー名のマッピングはプラットフォームに依存します。一般的なエラーの名前については、一般的なシステムエラーを参照してください。

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

`util.getSystemErrorMap()`

追加日: v16.0.0, v14.17.0

戻り値: <Map>

Node.js API で使用可能なすべてのシステムエラーコードの Map を返します。エラーコードとエラー名のマッピングはプラットフォームに依存します。一般的なエラーの名前については、一般的なシステムエラーを参照してください。

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

追加日: v23.1.0

err <number>
戻り値: <string>

Node.js API から取得した数値エラーコードの文字列メッセージを返します。エラーコードと文字列メッセージのマッピングはプラットフォームに依存します。

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

[履歴]

バージョン	変更点
v5.0.0	`constructor` パラメータは、ES6 クラスを参照できるようになりました。
v0.3.0	追加日: v0.3.0

[安定度: 3 - 従来型]

安定度: 3 安定性: 3 - 従来型: 代わりに ES2015 クラス構文とextendsキーワードを使用してください。

constructor <Function>
superConstructor <Function>

util.inherits() の使用は推奨されません。ES6 の class と extends キーワードを使用して、言語レベルの継承サポートを取得してください。また、2 つのスタイルはセマンティックに互換性がないことにも注意してください。

1 つのコンストラクタから別のコンストラクタにプロトタイプメソッドを継承します。constructorのプロトタイプは、superConstructorから作成された新しいオブジェクトに設定されます。

これは主に、Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)の上にいくつかの入力検証を追加します。追加の利便性として、superConstructorは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!"

class と extends を使用する ES6 の例:

const EventEmitter = require('node:events')

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

const stream = new MyStream()

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

`util.inspect(object[, options])`

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

[履歴]

バージョン	変更内容
v16.18.0	`Set`と`Map`を検査する際の`maxArrayLength`のサポートを追加。
v17.3.0, v16.14.0	`numericSeparator`オプションがサポートされました。
v13.0.0	循環参照に、参照へのマーカーが含まれるようになりました。
v14.6.0, v12.19.0	`object`が異なる`vm.Context`からのものである場合、そのオブジェクトのカスタム検査関数は、コンテキスト固有の引数をもう受け取りません。
v13.13.0, v12.17.0	`maxStringLength`オプションがサポートされました。
v13.5.0, v12.16.0	`showHidden`が`true`の場合、ユーザー定義のプロトタイププロパティが検査されます。
v12.0.0	`compact`オプションのデフォルトが`3`に変更され、`breakLength`オプションのデフォルトが`80`に変更されました。
v12.0.0	内部プロパティは、カスタム検査関数のコンテキスト引数に表示されなくなりました。
v11.11.0	`compact`オプションは、新しい出力モードの数値を受け入れるようになりました。
v11.7.0	ArrayBuffer は、バイナリの内容も表示するようになりました。
v11.5.0	`getters`オプションがサポートされました。
v11.4.0	`depth`のデフォルトが`2`に戻りました。
v11.0.0	`depth`のデフォルトが`20`に変更されました。
v11.0.0	検査出力は、約 128 MiB に制限されるようになりました。それ以上のサイズのデータは、完全に検査されません。
v10.12.0	`sorted`オプションがサポートされました。
v10.6.0	リンクリストや同様のオブジェクトの検査が、最大呼び出しスタックサイズまで可能になりました。
v10.0.0	`WeakMap`と`WeakSet`のエントリも検査できるようになりました。
v9.9.0	`compact`オプションがサポートされました。
v6.6.0	カスタム検査関数は、`this`を返すことができるようになりました。
v6.3.0	`breakLength`オプションがサポートされました。
v6.1.0	`maxArrayLength`オプションがサポートされました。特に、長い配列はデフォルトで切り捨てられます。
v6.1.0	`showProxy`オプションがサポートされました。
v0.3.0	追加されました: v0.3.0

object <any> 任意の JavaScript プリミティブまたはObject。
options <Object>
- showHidden <boolean> trueの場合、objectの列挙不可能なシンボルとプロパティがフォーマットされた結果に含まれます。WeakMapとWeakSetのエントリも、ユーザー定義のプロトタイププロパティ（メソッドプロパティを除く）と同様に含まれます。デフォルト: false。
- depth <number> objectをフォーマットする際に再帰する回数を指定します。これは、大きなオブジェクトを検査するのに役立ちます。最大呼び出しスタックサイズまで再帰するには、Infinityまたはnullを渡します。デフォルト: 2。
- colors <boolean> trueの場合、出力は ANSI カラーコードでスタイル設定されます。カラーはカスタマイズ可能です。util.inspectカラーのカスタマイズを参照してください。デフォルト: false。
- customInspect <boolean> falseの場合、[util.inspect.custom](depth, opts, inspect)関数は呼び出されません。デフォルト: true。
- showProxy <boolean> trueの場合、Proxyの検査にはtargetとhandlerオブジェクトが含まれます。デフォルト: false。
- maxArrayLength <integer> フォーマット時に含めるArray、TypedArray、Map、Set、WeakMap、およびWeakSetの要素の最大数を指定します。すべての要素を表示するにはnullまたはInfinityに設定します。要素をまったく表示しないようにするには0または負の値に設定します。デフォルト: 100。
- maxStringLength <integer> フォーマット時に含める文字の最大数を指定します。すべての要素を表示するにはnullまたはInfinityに設定します。文字をまったく表示しないようにするには0または負の値に設定します。デフォルト: 10000。
- breakLength <integer> 入力値が複数行に分割される長さ。入力を 1 行でフォーマットするにはInfinityに設定します（compactをtrueまたは任意の数値（1以上）に設定した場合）。デフォルト: 80。
- compact <boolean> | <integer> これをfalseに設定すると、各オブジェクトキーが新しい行に表示されます。breakLengthより長いテキストでは改行されます。数値に設定すると、最も内側のn個の要素が、すべてのプロパティがbreakLength内に収まる限り、1 行にまとめられます。短い配列要素もまとめて表示されます。詳細は以下の例を参照してください。デフォルト: 3。
- sorted <boolean> | <Function> trueまたは関数に設定すると、オブジェクトのすべてのプロパティとSetおよびMapのエントリが、結果の文字列でソートされます。trueに設定すると、デフォルトのソートが使用されます。関数に設定すると、比較関数として使用されます。
- getters <boolean> | <string> trueに設定すると、ゲッターが検査されます。'get'に設定すると、対応するセッターがないゲッターのみが検査されます。'set'に設定すると、対応するセッターがあるゲッターのみが検査されます。ゲッター関数によっては、副作用が発生する可能性があります。デフォルト: false。
- numericSeparator <boolean> trueに設定すると、すべての bigint と数値で、3 桁ごとにアンダースコアを使用して区切ります。デフォルト: false。
戻り値: <string> objectの表現。

util.inspect()メソッドは、デバッグを目的としたobjectの文字列表現を返します。util.inspectの出力はいつでも変更される可能性があり、プログラムで依存すべきではありません。結果を変更する追加のoptionsを渡すことができます。util.inspect()は、コンストラクターの名前と/または@@toStringTagを使用して、検査された値の識別可能なタグを作成します。

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

循環参照は、参照インデックスを使用してアンカーを指します。

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

次の例では、utilオブジェクトのすべてのプロパティを検査します。

const util = require('node:util')

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

次の例では、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 [...]', // 長い行
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// `compact`をfalseまたは整数に設定すると、より読みやすい出力が作成されます。
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'
//   }
// }

// `breakLength`を例えば150に設定すると、「Lorem ipsum」テキストは1行で表示されます。

showHiddenオプションを使用すると、WeakMapとWeakSetのエントリを検査できます。maxArrayLengthより多くのエントリがある場合、どのエントリが表示されるかの保証はありません。つまり、同じWeakSetのエントリを 2 回取得しても、異なる出力が得られる可能性があります。さらに、強い参照が残っていないエントリは、いつでもガベージコレクションされる可能性があります。

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

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

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

sortedオプションにより、オブジェクトのプロパティの挿入順序がutil.inspect()の結果に影響を与えないことが保証されます。

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

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

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

numericSeparatorオプションは、すべての数値に 3 桁ごとにアンダースコアを追加します。

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()は、デバッグを目的とした同期メソッドです。最大出力長は約 128 MiB です。それ以上の出力になる入力は切り捨てられます。

`util.inspect` の色のカスタマイズ

util.inspect のカラー出力（有効になっている場合）は、util.inspect.styles および util.inspect.colors プロパティを介してグローバルにカスタマイズできます。

util.inspect.styles は、スタイル名と util.inspect.colors からの色を関連付けるマップです。

デフォルトのスタイルと関連付けられた色は次のとおりです。

bigint: yellow
boolean: yellow
date: magenta
module: underline
name: (スタイルなし)
null: bold
number: yellow
regexp: red
special: cyan (例: Proxies)
string: green
symbol: green
undefined: grey

カラーのスタイル設定には ANSI 制御コードを使用しており、すべての端末でサポートされているとは限りません。カラーサポートを確認するには、tty.hasColors() を使用します。

定義済みの制御コードを以下に示します（「修飾子」、「前景の色」、「背景の色」としてグループ化されています）。

修飾子

修飾子のサポートは、端末によって異なります。サポートされていない場合は、ほとんど無視されます。

reset - すべての（色の）修飾子をデフォルトにリセットします
bold - テキストを太字にします
italic - テキストを斜体にします
underline - テキストに下線を引きます
~~strikethrough~~ - テキストの中央に水平線を引きます（別名: strikeThrough, crossedout, crossedOut)
hidden - テキストを出力しますが、非表示にします（別名: conceal）
dim - 色の強度を下げます（別名: faint）
overlined - テキストに上線を引きます
blink - 一定の間隔でテキストを表示および非表示にします
inverse - 前景色と背景色を入れ替えます（別名: swapcolors, swapColors)
doubleunderline - テキストに二重下線を引きます（別名: doubleUnderline)
framed - テキストの周りに枠を描画します

前景色

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

背景色

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

オブジェクトのカスタム検査関数

[履歴]

バージョン	変更
v17.3.0, v16.14.0	より良い相互運用性のために、inspect 引数が追加されました。
v0.1.97	追加: v0.1.97

オブジェクトは独自の[util.inspect.custom](depth, opts, inspect)関数を定義できます。util.inspect()はこの関数を呼び出し、オブジェクトを検査する際にその結果を使用します。

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

    // "Box< "のサイズである5スペースのパディング。
    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)
// 結果: "Box< true >"

カスタム[util.inspect.custom](depth, opts, inspect)関数は通常文字列を返しますが、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)
// 結果: "{ bar: 'baz' }"

`util.inspect.custom`

[履歴]

バージョン	変更
v10.12.0	共有シンボルとして定義されるようになりました。
v6.6.0	追加: v6.6.0

カスタム検査関数を宣言するために使用できる<symbol>

util.inspect.customを通じてアクセスできることに加えて、このシンボルはグローバルに登録されており、Symbol.for('nodejs.util.inspect.custom')としてあらゆる環境でアクセスできます。

これを使用することで、コードをポータブルに記述できます。つまり、カスタム検査関数は Node.js 環境で使用され、ブラウザでは無視されます。util.inspect()関数自体は、さらなる移植性を可能にするために、カスタム検査関数への第 3 引数として渡されます。

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)
// 出力: Password <xxxxxxxx>

詳細はオブジェクトのカスタム検査関数を参照してください。

`util.inspect.defaultOptions`

追加時期: v6.4.0

defaultOptions値により、util.inspectで使用されるデフォルトオプションをカスタマイズできます。これは、暗黙的にutil.inspectを呼び出すconsole.logやutil.formatなどの関数に役立ちます。これは、1 つ以上の有効なutil.inspect()オプションを含むオブジェクトに設定する必要があります。オプションプロパティを直接設定することもサポートされています。

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

console.log(arr) // 切り詰められた配列を出力します
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // 完全な配列を出力します

`util.isDeepStrictEqual(val1, val2)`

追加時期: v9.0.0

val1 <any>
val2 <any>
戻り値: <boolean>

val1とval2の間に厳密な深層等価関係がある場合、trueを返します。そうでない場合はfalseを返します。

厳密な深層等価性に関する詳細については、assert.deepStrictEqual()を参照してください。

クラス: `util.MIMEType`

追加時期: v19.1.0, v18.13.0

[安定版: 1 - 実験的]

安定版: 1 安定性: 1 - 実験的

MIMEType クラスの実装。

ブラウザの慣例に従って、MIMETypeオブジェクトのすべてのプロパティは、オブジェクト自体上のデータプロパティではなく、クラスプロトタイプ上のゲッターとセッターとして実装されています。

MIME 文字列は、複数の意味のあるコンポーネントを含む構造化された文字列です。解析されると、これらのコンポーネントそれぞれにプロパティを含むMIMETypeオブジェクトが返されます。

コンストラクタ: `new MIMEType(input)`

input <string> 解析する入力 MIME

inputを解析して新しいMIMETypeオブジェクトを作成します。

ESMCJS

import { MIMEType } from 'node:util'

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

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

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

inputが有効な MIME でない場合、TypeErrorがスローされます。指定された値を文字列に変換する試みが行われることに注意してください。例えば:

ESMCJS

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

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

`mime.type`

<string>

MIME の type 部分を取得および設定します。

ESMCJS

import { MIMEType } from 'node:util'

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

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

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

`mime.subtype`

<string>

MIME の subtype 部分を取得および設定します。

ESMCJS

import { MIMEType } from 'node:util'

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

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

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

`mime.essence`

<string>

MIME の本質を取得します。このプロパティは読み取り専用です。MIME を変更するにはmime.typeまたはmime.subtypeを使用してください。

ESMCJS

import { MIMEType } from 'node:util'

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

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

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

`mime.params`

<MIMEParams>

MIME のパラメータを表すMIMEParamsオブジェクトを取得します。このプロパティは読み取り専用です。詳細はMIMEParamsのドキュメントを参照してください。

`mime.toString()`

戻り値: <string>

MIMETypeオブジェクトのtoString()メソッドは、シリアライズされた MIME を返します。

標準準拠の必要性から、このメソッドでは MIME のシリアライズ処理をユーザーがカスタマイズすることはできません。

`mime.toJSON()`

戻り値: <string>

mime.toString()のエイリアスです。

このメソッドは、JSON.stringify()でMIMETypeオブジェクトがシリアライズされると自動的に呼び出されます。

ESMCJS

import { MIMEType } from 'node:util'

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

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

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

クラス: `util.MIMEParams`

追加されたバージョン: v19.1.0, v18.13.0

MIMEParams API は、MIMETypeのパラメータへの読み書きアクセスを提供します。

コンストラクタ: `new MIMEParams()`

空のパラメータで新しいMIMEParamsオブジェクトを作成します。

ESMCJS

import { MIMEParams } from 'node:util'

const myParams = new MIMEParams()

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

const myParams = new MIMEParams()

`mimeParams.delete(name)`

name <string>

名前がnameであるすべての名前と値のペアを削除します。

`mimeParams.entries()`

戻り値: <Iterator>

パラメータ内の各名前と値のペアを反復処理するイテレータを返します。イテレータの各項目は JavaScript のArrayです。配列の最初の項目はname、2 番目の項目はvalueです。

`mimeParams.get(name)`

name <string>
戻り値: <string> | <null> 指定されたnameを持つ名前と値のペアがない場合は、文字列またはnull。

nameである名前と値のペアの最初の値を返します。そのようなペアがない場合は、nullを返します。

`mimeParams.has(name)`

name <string>
戻り値: <boolean>

nameである名前と値のペアが少なくとも 1 つ存在する場合はtrueを返します。

`mimeParams.keys()`

戻り値: <Iterator>

各名前と値のペアの名前を反復処理するイテレータを返します。

ESMCJS

import { MIMEType } from 'node:util'

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

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

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

`mimeParams.set(name, value)`

name <string>
value <string>

nameに関連付けられたMIMEParamsオブジェクトの値をvalueに設定します。nameである名前と値のペアが既に存在する場合は、そのようなペアの最初の値をvalueに設定します。

ESMCJS

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

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

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

`mimeParams.values()`

戻り値: <Iterator>

各名前と値のペアの値に対するイテレータを返します。

`mimeParams[@@iterator]()`

戻り値: <Iterator>

mimeParams.entries() のエイリアスです。

ESMCJS

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

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

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

`util.parseArgs([config])`

[履歴]

バージョン	変更
v22.4.0, v20.16.0	入力 `config` で負のオプションを許可するサポートを追加
v20.0.0	この API は実験的ではなくなりました。
v18.11.0, v16.19.0	入力 `config` でのデフォルト値のサポートを追加
v18.7.0, v16.17.0	入力 `config` で `tokens` を使用した詳細な解析情報の返却をサポート
v18.3.0, v16.17.0	追加: v18.3.0, v16.17.0

config <Object> パースのための引数を提供し、パーサーを設定するために使用されます。config は以下のプロパティをサポートします。
- args <string[]> 引数文字列の配列。デフォルト: execPath と filename を削除した process.argv。
- options <Object> パーサーに認識される引数を記述するために使用されます。options のキーはオプションの長い名前であり、値は次のプロパティを受け入れる <Object> です。
- type <string> 引数の型。boolean または string のいずれかでなければなりません。
- multiple <boolean> このオプションを複数回指定できるかどうか。true の場合、すべての値が配列に収集されます。false の場合、オプションの値は最後に指定されたものが優先されます。デフォルト: false。
- short <string> オプションの 1 文字のエイリアス。
- default <string> | <boolean> | <string[]> | <boolean[]> 引数で設定されていない場合のデフォルトのオプション値。type プロパティと同じ型でなければなりません。multiple が true の場合、配列でなければなりません。
- strict <boolean> 不明な引数が検出された場合、または options で設定された type と一致しない引数が渡された場合にエラーをスローするかどうか。デフォルト: true。
- allowPositionals <boolean> このコマンドが位置引数を受け入れるかどうか。デフォルト: strict が true の場合 false、それ以外の場合は true。
- allowNegative <boolean> true の場合、オプション名の前に --no- を付けることで、ブール値オプションを明示的に false に設定できます。デフォルト: false。
- tokens <boolean> パースされたトークンを返します。これは、追加のチェックの追加からさまざまな方法でのトークンの再処理まで、ビルトインの動作を拡張するのに役立ちます。デフォルト: false。
戻り値: <Object> パースされたコマンドライン引数:
- values <Object> パースされたオプション名とその <string> または <boolean> の値のマッピング。
- positionals <string[]> 位置引数。
- tokens <Object[]> | <undefined> parseArgs トークンセクションを参照してください。config に tokens: true が含まれている場合のみ返されます。

process.argv を直接操作するよりも高レベルの API をコマンドライン引数の解析に提供します。予想される引数の仕様を受け取り、パースされたオプションと位置引数を含む構造化されたオブジェクトを返します。

ESMCJS

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

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

`parseArgs` `tokens`

tokens: true を設定することで、カスタム動作を追加するための詳細な解析情報を利用できます。返されるトークンには、以下のプロパティがあります。

全てのトークン
- kind <string> 'option'、'positional'、または 'option-terminator' のいずれか。
- index <number> トークンを含む args 内の要素のインデックス。そのため、トークンのソース引数は args[token.index] となります。
オプショントークン
- name <string> オプションの長い名前。
- rawName <string> args で使用されるオプションの方法（例: -f や --foo）。
- value <string> | <undefined> args で指定されたオプション値。ブール値のオプションの場合は undefined。
- inlineValue <boolean> | <undefined> オプション値がインラインで指定されているかどうか（例: --foo=bar）。
位置指定トークン
- value <string> args 内の位置指定引数の値（つまり args[index]）。
option-terminator トークン

返されるトークンは、入力 args で出会った順序で並んでいます。args に複数回出現するオプションは、使用ごとにトークンが生成されます。-xy のような短いオプショングループは、オプションごとにトークンに展開されます。そのため、-xxx は 3 つのトークンを生成します。

例えば、--no-color のような否定されたオプション（オプションが boolean 型の場合、allowNegative がサポートします）のサポートを追加するには、返されたトークンを再処理して、否定されたオプションに格納されている値を変更できます。

ESMCJS

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

// オプショントークンを再処理し、返された値を上書きします。
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // --no-foo に対して foo:false を格納
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // --foo と --no-foo の両方がある場合、最後に使用されたものが優先されるように値を再保存します。
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })

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

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

// オプショントークンを再処理し、返された値を上書きします。
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // --no-foo に対して foo:false を格納
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // --foo と --no-foo の両方がある場合、最後に使用されたものが優先されるように値を再保存します。
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })

否定されたオプションと、オプションが複数の方法で使用された場合に最後のものが優先されることを示す使用例です。

bash

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

`util.parseEnv(content)`

[安定版: 1 - 試験版]

安定版: 1 安定性: 1.1 - アクティブ開発中

追加バージョン: v21.7.0, v20.12.0

content <string>

.envファイルの生のコンテンツ。

戻り値: <Object>

.envファイルの例：

CJSESM

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

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

import { parseEnv } from 'node:util'

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

`util.promisify(original)`

[履歴]

バージョン	変更
v20.8.0	`Promise`を返す関数に対して`promisify`を呼び出すことは非推奨になりました。
v8.0.0	追加バージョン: v8.0.0

original <Function>
戻り値: <Function>

一般的なエラーファーストコールバックスタイルに従う関数、つまり (err, value) =\> ... コールバックを最後の引数として取る関数を取得し、Promise を返すバージョンを返します。

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

const stat = util.promisify(fs.stat)
stat('.')
  .then(stats => {
    // `stats` を使用して何かを行う
  })
  .catch(error => {
    // エラーを処理する。
  })

または、同等の 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(`このディレクトリは ${stats.uid} が所有しています`)
}

callStat()

original[util.promisify.custom] プロパティが存在する場合、promisify はその値を返します。カスタムプロミス化関数を参照してください。

promisify() は、original がすべてのケースでコールバックを最後の引数として取る関数であると想定しています。original が関数でない場合、promisify() はエラーをスローします。original が関数であるが、最後の引数がエラーファーストコールバックでない場合でも、エラーファーストコールバックが最後の引数として渡されます。

クラスメソッドやthisを使用するその他のメソッドに対してpromisify()を使用すると、特別に処理されない限り、期待通りに動作しない可能性があります。

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'

カスタムプロミス化関数

util.promisify.custom シンボルを使用すると、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])
// 'true'が出力されます

これは、元の関数が最後の引数としてエラー優先コールバックを受け取る標準形式に従わない場合に役立ちます。

たとえば、(foo, onSuccessCallback, onErrorCallback)を受け取る関数の場合：

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

promisify.customが定義されているが関数の場合は、promisify()はエラーをスローします。

`util.promisify.custom`

[履歴]

バージョン	変更
v13.12.0, v12.16.2	共有シンボルとして定義されるようになりました。
v8.0.0	追加: v8.0.0

関数のカスタムプロミス化バリアントを宣言するために使用できる<symbol>。カスタムプロミス化関数を参照してください。

util.promisify.customを通してアクセスできることに加え、このシンボルはグローバルに登録されており、Symbol.for('nodejs.util.promisify.custom')として任意の環境でアクセスできます。

たとえば、(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)`

追加日時: v16.11.0

str <string>
戻り値: <string>

ANSI エスケープコードを削除したstrを返します。

console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'))
// "value" と出力されます

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

[Stable: 2 - Stable]

Stable: 2 Stability: 2 - 安定版。

[履歴]

バージョン	変更内容
v23.5.0	styleText が安定版になりました。
v22.8.0, v20.18.0	isTTY と、NO_COLORS、NODE_DISABLE_COLORS、FORCE_COLOR などの環境変数を尊重するようになりました。
v21.7.0, v20.12.0	追加日時: v21.7.0, v20.12.0

format <string> | <Array> util.inspect.colorsで定義されているテキストフォーマット、またはテキストフォーマットの配列。
text <string> フォーマットするテキスト。
options <Object>
- validateStream <boolean> trueの場合、streamが色を処理できるかどうかがチェックされます。デフォルト: true。
- stream <Stream> 色付けできるかどうか検証されるストリーム。デフォルト: process.stdout。

この関数は、ターミナルへの出力のために渡されたformatを考慮してフォーマットされたテキストを返します。ターミナルの機能を認識し、NO_COLORS、NODE_DISABLE_COLORS、FORCE_COLOR環境変数で設定された設定に従って動作します。

ESMCJS

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

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

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // process.stderr がTTYかどうかを検証
  { stream: stderr }
)
console.error(successMessage)

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

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

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // process.stderr がTTYかどうかを検証
  { stream: stderr }
)
console.error(successMessage)

util.inspect.colorsはitalicやunderlineなどのテキストフォーマットも提供しており、これらを組み合わせることができます。

console.log(util.styleText(['underline', 'italic'], 'My italic underlined message'))

フォーマットの配列を渡す場合、適用されるフォーマットの順序は左から右なので、後続のスタイルが前のスタイルを上書きする可能性があります。

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

フォーマットの完全なリストは修飾子にあります。

クラス: `util.TextDecoder`

[履歴]

バージョン	変更
v11.0.0	このクラスはグローバルオブジェクトで使用できるようになりました。
v8.3.0	追加: v8.3.0

WHATWG Encoding Standard の TextDecoder API の実装です。

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

WHATWG でサポートされているエンコーディング

WHATWG Encoding Standard に従って、TextDecoder API でサポートされているエンコーディングを以下の表に示します。各エンコーディングには、1 つ以上のエイリアスを使用できます。

異なる Node.js ビルド構成では、異なるエンコーディングセットがサポートされます。（国際化を参照）

デフォルトでサポートされるエンコーディング（完全な ICU データ付き）

エンコーディング	エイリアス
`'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'`

`small-icu`オプション付きで Node.js をビルドした場合にサポートされるエンコーディング

エンコーディング	エイリアス
`'utf-8'`	`'unicode-1-1-utf-8'` , `'utf8'`
`'utf-16le'`	`'utf-16'`
`'utf-16be'`

ICU が無効になっている場合にサポートされるエンコーディング

エンコーディング	エイリアス
`'utf-8'`	`'unicode-1-1-utf-8'` , `'utf8'`
`'utf-16le'`	`'utf-16'`

WHATWG Encoding Standardに記載されている'iso-8859-16'エンコーディングはサポートされていません。

`new TextDecoder([encoding[, options]])`

encoding <string> このTextDecoderインスタンスがサポートするencodingを識別します。デフォルト: 'utf-8'。
options <Object>
- fatal <boolean> デコードエラーが致命的である場合true。ICU が無効になっている場合はこのオプションはサポートされていません（国際化を参照）。デフォルト: false。
- ignoreBOM <boolean> trueの場合、TextDecoderはバイトオーダーマークをデコードされた結果に含めます。falseの場合、バイトオーダーマークは出力から削除されます。このオプションは、encodingが'utf-8'、'utf-16be'、または'utf-16le'の場合にのみ使用されます。デフォルト: false。

新しいTextDecoderインスタンスを作成します。encodingには、サポートされているエンコーディングまたはエイリアスのいずれかを指定できます。

TextDecoderクラスはグローバルオブジェクトでも使用できます。

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

input <ArrayBuffer> | <DataView> | <TypedArray> エンコードされたデータを含むArrayBuffer、DataView、またはTypedArrayインスタンス。
options <Object>
- stream <boolean> さらにデータチャンクが期待される場合true。デフォルト: false。
戻り値: <string>

inputをデコードし、文字列を返します。options.streamがtrueの場合、inputの最後に発生する不完全なバイトシーケンスは内部的にバッファリングされ、次回のtextDecoder.decode()呼び出し後に出力されます。

textDecoder.fatalがtrueの場合、発生するデコードエラーによりTypeErrorがスローされます。

`textDecoder.encoding`

<string>

TextDecoderインスタンスでサポートされているエンコーディング。

`textDecoder.fatal`

<boolean>

デコードエラーがTypeErrorの発生を招く場合、trueになります。

`textDecoder.ignoreBOM`

<boolean>

デコード結果にバイトオーダーマークが含まれる場合、trueになります。

クラス: `util.TextEncoder`

[履歴]

バージョン	変更
v11.0.0	このクラスはグローバルオブジェクトで使用可能になりました。
v8.3.0	追加: v8.3.0

WHATWG Encoding StandardのTextEncoder API の実装です。TextEncoderのすべてのインスタンスは UTF-8 エンコーディングのみをサポートします。

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

TextEncoderクラスはグローバルオブジェクトでも使用できます。

`textEncoder.encode([input])`

input <string> エンコードするテキスト。デフォルト: 空文字列。
戻り値: <Uint8Array>

input文字列を UTF-8 でエンコードし、エンコードされたバイトを含むUint8Arrayを返します。

`textEncoder.encodeInto(src, dest)`

追加: v12.11.0

src <string> エンコードするテキスト。
dest <Uint8Array> エンコード結果を保持する配列。
戻り値: <Object>
- read <number> srcの読み取った Unicode コードユニット。
- written <number> destの書き込まれた UTF-8 バイト。

src文字列を UTF-8 でdest Uint8Array にエンコードし、読み取った Unicode コードユニットと書き込まれた UTF-8 バイトを含むオブジェクトを返します。

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>

TextEncoderインスタンスでサポートされているエンコーディング。常に'utf-8'に設定されています。

`util.toUSVString(string)`

追加されたバージョン: v16.8.0, v14.18.0

string <string>

サロゲートコードポイント（または同等に、ペアになっていないサロゲートコードユニット）を Unicode の「置換文字」U+FFFD に置き換えた後のstringを返します。

`util.transferableAbortController()`

追加されたバージョン: v18.11.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

<AbortController>インスタンスを作成し、その <AbortSignal>を転送可能としてマークします。structuredClone()またはpostMessage()で使用できます。

`util.transferableAbortSignal(signal)`

追加されたバージョン: v18.11.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

signal <AbortSignal>
戻り値: <AbortSignal>

指定された <AbortSignal>を転送可能としてマークし、structuredClone()とpostMessage()で使用できるようにします。

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

`util.aborted(signal, resource)`

追加されたバージョン: v19.7.0, v18.16.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

signal <AbortSignal>
resource <Object> 中断可能な操作に関連付けられ、弱参照で保持されている null 以外のオブジェクト。signalが中断する前にresourceがガベージコレクションされると、Promise は保留されたままになり、Node.js はそれの追跡を停止します。これは、長時間実行される操作やキャンセルできない操作でのメモリリークを防ぐのに役立ちます。
戻り値: <Promise>

提供されたsignalの中断イベントをリッスンし、signalが中断されたときに解決される Promise を返します。resourceが提供されている場合、操作に関連付けられたオブジェクトを弱参照するため、signalが中断する前にresourceがガベージコレクションされると、返された Promise は保留されたままになります。これは、長時間実行される操作やキャンセルできない操作でのメモリリークを防ぎます。

CJSESM

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

// 中断可能なシグナルを持つオブジェクトを取得します（カスタムリソースや操作など）。
const dependent = obtainSomethingAbortable()

// `dependent`をリソースとして渡し、シグナルが中断されたときに`dependent`がメモリに残っている場合にのみPromiseが解決されることを示します。
aborted(dependent.signal, dependent).then(() => {
  // これは`dependent`が中断されたときに実行されます。
  console.log('Dependent resource was aborted.')
})

// 中断をトリガーするイベントをシミュレートします。
dependent.on('event', () => {
  dependent.abort() // これにより`aborted` Promiseが解決されます。
})

import { aborted } from 'node:util'

// 中断可能なシグナルを持つオブジェクトを取得します（カスタムリソースや操作など）。
const dependent = obtainSomethingAbortable()

// `dependent`をリソースとして渡し、シグナルが中断されたときに`dependent`がメモリに残っている場合にのみPromiseが解決されることを示します。
aborted(dependent.signal, dependent).then(() => {
  // これは`dependent`が中断されたときに実行されます。
  console.log('Dependent resource was aborted.')
})

// 中断をトリガーするイベントをシミュレートします。
dependent.on('event', () => {
  dependent.abort() // これにより`aborted` Promiseが解決されます。
})

`util.types`

[履歴]

バージョン	変更点
v15.3.0	`require('util/types')`として公開。
v10.0.0	追加: v10.0.0

util.types は、様々な種類の組み込みオブジェクトの型チェックを提供します。instanceof や Object.prototype.toString.call(value) とは異なり、これらのチェックは JavaScript からアクセス可能なオブジェクトのプロパティ（プロトタイプなど）を検査せず、通常は C++への呼び出しのオーバーヘッドがあります。

結果は、一般的に、値が JavaScript で公開するプロパティや動作の種類について何らかの保証を与えません。主に、JavaScript で型チェックを行うことを好むアドオン開発者にとって便利です。

この API は、require('node:util').types または require('node:util/types') を介してアクセスできます。

`util.types.isAnyArrayBuffer(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのArrayBufferまたはSharedArrayBufferインスタンスである場合、trueを返します。

util.types.isArrayBuffer() と util.types.isSharedArrayBuffer()も参照してください。

util.types.isAnyArrayBuffer(new ArrayBuffer()) // trueを返す
util.types.isAnyArrayBuffer(new SharedArrayBuffer()) // trueを返す

`util.types.isArrayBufferView(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値がArrayBufferビュー（型付き配列オブジェクトやDataViewなど）のインスタンスである場合、trueを返します。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)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が arguments オブジェクトの場合、true を返します。

function foo() {
  util.types.isArgumentsObject(arguments) // true を返します
}

`util.types.isArrayBuffer(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みの ArrayBuffer インスタンスの場合、true を返します。SharedArrayBuffer インスタンスは含まれません。通常は両方を確認することが望ましいです。その場合は、util.types.isAnyArrayBuffer() を参照してください。

util.types.isArrayBuffer(new ArrayBuffer()) // true を返します
util.types.isArrayBuffer(new SharedArrayBuffer()) // false を返します

`util.types.isAsyncFunction(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が非同期関数の場合、true を返します。これは JavaScript エンジンが認識しているもののみを報告します。特に、トランスパイルツールが使用された場合、戻り値は元のソースコードと一致しない場合があります。

util.types.isAsyncFunction(function foo() {}) // false を返します
util.types.isAsyncFunction(async function foo() {}) // true を返します

`util.types.isBigInt64Array(value)`

追加日時: v10.0.0

value <any>
戻り値: <boolean>

値がBigInt64Arrayインスタンスの場合、trueを返します。

util.types.isBigInt64Array(new BigInt64Array()) // trueを返します
util.types.isBigInt64Array(new BigUint64Array()) // falseを返します

`util.types.isBigIntObject(value)`

追加日時: v10.4.0

value <any>
戻り値: <boolean>

値が BigInt オブジェクト（例: Object(BigInt(123))で作成されたもの）の場合、trueを返します。

util.types.isBigIntObject(Object(BigInt(123))) // trueを返します
util.types.isBigIntObject(BigInt(123)) // falseを返します
util.types.isBigIntObject(123) // falseを返します

`util.types.isBigUint64Array(value)`

追加日時: v10.0.0

value <any>
戻り値: <boolean>

値がBigUint64Arrayインスタンスの場合、trueを返します。

util.types.isBigUint64Array(new BigInt64Array()) // falseを返します
util.types.isBigUint64Array(new BigUint64Array()) // trueを返します

`util.types.isBooleanObject(value)`

追加日時: v10.0.0

value <any>
戻り値: <boolean>

値がブールオブジェクト（例: new Boolean()で作成されたもの）の場合、trueを返します。

util.types.isBooleanObject(false) // falseを返します
util.types.isBooleanObject(true) // falseを返します
util.types.isBooleanObject(new Boolean(false)) // trueを返します
util.types.isBooleanObject(new Boolean(true)) // trueを返します
util.types.isBooleanObject(Boolean(false)) // falseを返します
util.types.isBooleanObject(Boolean(true)) // falseを返します

`util.types.isBoxedPrimitive(value)`

追加：v10.11.0

value <any>
戻り値: <boolean>

new Boolean()、new String()、またはObject(Symbol())によって作成されたボックス化されたプリミティブオブジェクトであればtrueを返します。

例：

util.types.isBoxedPrimitive(false) // falseを返します
util.types.isBoxedPrimitive(new Boolean(false)) // trueを返します
util.types.isBoxedPrimitive(Symbol('foo')) // falseを返します
util.types.isBoxedPrimitive(Object(Symbol('foo'))) // trueを返します
util.types.isBoxedPrimitive(Object(BigInt(5))) // trueを返します

`util.types.isCryptoKey(value)`

追加：v16.2.0

value <Object>
戻り値: <boolean>

valueが<CryptoKey>であればtrue、そうでなければfalseを返します。

`util.types.isDataView(value)`

追加：v10.0.0

value <any>
戻り値: <boolean>

valueがビルトインのDataViewインスタンスであればtrueを返します。

const ab = new ArrayBuffer(20)
util.types.isDataView(new DataView(ab)) // trueを返します
util.types.isDataView(new Float64Array()) // falseを返します

ArrayBuffer.isView()も参照してください。

`util.types.isDate(value)`

追加：v10.0.0

value <any>
戻り値: <boolean>

valueがビルトインのDateインスタンスであればtrueを返します。

util.types.isDate(new Date()) // trueを返します

`util.types.isExternal(value)`

追加されたバージョン: v10.0.0

value <any>
戻り値: <boolean>

値がネイティブのExternal値の場合、trueを返します。

ネイティブのExternal値は、ネイティブコードからのアクセス用に生の C++ポインタ(void*)を含む特殊なオブジェクトの型であり、他のプロパティを持ちません。このようなオブジェクトは、Node.js 内部またはネイティブアドオンによって作成されます。JavaScript では、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) // trueを返す
util.types.isExternal(0) // falseを返す
util.types.isExternal(new String('foo')) // falseを返す

napi_create_externalに関する詳細は、napi_create_external()を参照してください。

`util.types.isFloat32Array(value)`

追加されたバージョン: v10.0.0

value <any>
戻り値: <boolean>

値がビルトインのFloat32Arrayインスタンスの場合、trueを返します。

util.types.isFloat32Array(new ArrayBuffer()) // falseを返す
util.types.isFloat32Array(new Float32Array()) // trueを返す
util.types.isFloat32Array(new Float64Array()) // falseを返す

`util.types.isFloat64Array(value)`

追加されたバージョン: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのFloat64Arrayインスタンスの場合、trueを返します。

util.types.isFloat64Array(new ArrayBuffer()) // falseを返します
util.types.isFloat64Array(new Uint8Array()) // falseを返します
util.types.isFloat64Array(new Float64Array()) // trueを返します

`util.types.isGeneratorFunction(value)`

追加されたバージョン: v10.0.0

value <any>
戻り値: <boolean>

値がジェネレーター関数の場合、trueを返します。これは JavaScript エンジンが認識しているもののみを報告します。特に、トランスパイルツールが使用された場合、戻り値は元のソースコードと一致しない場合があります。

util.types.isGeneratorFunction(function foo() {}) // falseを返します
util.types.isGeneratorFunction(function* foo() {}) // trueを返します

`util.types.isGeneratorObject(value)`

追加されたバージョン: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みジェネレーター関数から返されたジェネレーターオブジェクトの場合、trueを返します。これは JavaScript エンジンが認識しているもののみを報告します。特に、トランスパイルツールが使用された場合、戻り値は元のソースコードと一致しない場合があります。

function* foo() {}
const generator = foo()
util.types.isGeneratorObject(generator) // trueを返します

`util.types.isInt8Array(value)`

追加されたバージョン: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのInt8Arrayインスタンスの場合、trueを返します。

util.types.isInt8Array(new ArrayBuffer()) // falseを返します
util.types.isInt8Array(new Int8Array()) // trueを返します
util.types.isInt8Array(new Float64Array()) // falseを返します

`util.types.isInt16Array(value)`

追加版: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのInt16Arrayインスタンスの場合、trueを返します。

util.types.isInt16Array(new ArrayBuffer()) // falseを返します
util.types.isInt16Array(new Int16Array()) // trueを返します
util.types.isInt16Array(new Float64Array()) // falseを返します

`util.types.isInt32Array(value)`

追加版: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのInt32Arrayインスタンスの場合、trueを返します。

util.types.isInt32Array(new ArrayBuffer()) // falseを返します
util.types.isInt32Array(new Int32Array()) // trueを返します
util.types.isInt32Array(new Float64Array()) // falseを返します

`util.types.isKeyObject(value)`

追加版: v16.2.0

value <Object>
戻り値: <boolean>

valueが<KeyObject>の場合trueを返し、それ以外の場合はfalseを返します。

`util.types.isMap(value)`

追加版: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのMapインスタンスの場合、trueを返します。

util.types.isMap(new Map()) // trueを返します

`util.types.isMapIterator(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのMapインスタンスに対して返されたイテレータである場合、trueを返します。

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

`util.types.isModuleNamespaceObject(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値がモジュール名前空間オブジェクトのインスタンスである場合、trueを返します。

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

util.types.isModuleNamespaceObject(ns) // trueを返す

`util.types.isNativeError(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのError型のコンストラクタによって返されたものである場合、trueを返します。

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

ネイティブエラー型のサブクラスもネイティブエラーです。

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

ネイティブエラークラスのinstanceofである値は、その値に対してisNativeError()がtrueを返すこととは同等ではありません。isNativeError()は異なるレルムから来たエラーに対してtrueを返し、一方instanceof Errorはこれらのエラーに対してfalseを返します。

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

逆に、isNativeError()は、ネイティブエラーのコンストラクタによって返されなかったすべてのオブジェクトに対してfalseを返します。これには、ネイティブエラーのinstanceofである値も含まれます。

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

`util.types.isNumberObject(value)`

追加日: v10.0.0

value <any>
戻り値: <boolean>

new Number()によって作成された数値オブジェクトの場合、trueを返します。

util.types.isNumberObject(0) // falseを返します
util.types.isNumberObject(new Number(0)) // trueを返します

`util.types.isPromise(value)`

追加日: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのPromiseの場合、trueを返します。

util.types.isPromise(Promise.resolve(42)) // trueを返します

`util.types.isProxy(value)`

追加日: v10.0.0

value <any>
戻り値: <boolean>

値がProxyインスタンスの場合、trueを返します。

const target = {}
const proxy = new Proxy(target, {})
util.types.isProxy(target) // falseを返します
util.types.isProxy(proxy) // trueを返します

`util.types.isRegExp(value)`

追加日: v10.0.0

value <any>
戻り値: <boolean>

値が正規表現オブジェクトの場合、trueを返します。

util.types.isRegExp(/abc/) // trueを返します
util.types.isRegExp(new RegExp('abc')) // trueを返します

`util.types.isSet(value)`

追加日: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのSetインスタンスの場合、trueを返します。

util.types.isSet(new Set()) // trueを返す

`util.types.isSetIterator(value)`

追加日: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのSetインスタンスに対して返されるイテレータの場合、trueを返します。

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

`util.types.isSharedArrayBuffer(value)`

追加日: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのSharedArrayBufferインスタンスの場合、trueを返します。これはArrayBufferインスタンスは含みません。通常、両方をテストすることが望ましいです。その場合はutil.types.isAnyArrayBuffer()を参照してください。

util.types.isSharedArrayBuffer(new ArrayBuffer()) // falseを返す
util.types.isSharedArrayBuffer(new SharedArrayBuffer()) // trueを返す

`util.types.isStringObject(value)`

追加版: v10.0.0

value <any>
戻り値: <boolean>

new String()によって作成された文字列オブジェクトの場合、trueを返します。

util.types.isStringObject('foo') // falseを返します
util.types.isStringObject(new String('foo')) // trueを返します

`util.types.isSymbolObject(value)`

追加版: v10.0.0

value <any>
戻り値: <boolean>

Symbolプリミティブに対してObject()を呼び出して作成されたシンボルオブジェクトの場合、trueを返します。

const symbol = Symbol('foo')
util.types.isSymbolObject(symbol) // falseを返します
util.types.isSymbolObject(Object(symbol)) // trueを返します

`util.types.isTypedArray(value)`

追加版: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのTypedArrayインスタンスの場合、trueを返します。

util.types.isTypedArray(new ArrayBuffer()) // falseを返します
util.types.isTypedArray(new Uint8Array()) // trueを返します
util.types.isTypedArray(new Float64Array()) // trueを返します

ArrayBuffer.isView()も参照してください。

`util.types.isUint8Array(value)`

追加版: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのUint8Arrayインスタンスの場合、trueを返します。

util.types.isUint8Array(new ArrayBuffer()) // falseを返します
util.types.isUint8Array(new Uint8Array()) // trueを返します
util.types.isUint8Array(new Float64Array()) // falseを返します

`util.types.isUint8ClampedArray(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのUint8ClampedArrayインスタンスの場合、trueを返します。

util.types.isUint8ClampedArray(new ArrayBuffer()) // falseを返します
util.types.isUint8ClampedArray(new Uint8ClampedArray()) // trueを返します
util.types.isUint8ClampedArray(new Float64Array()) // falseを返します

`util.types.isUint16Array(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのUint16Arrayインスタンスの場合、trueを返します。

util.types.isUint16Array(new ArrayBuffer()) // falseを返します
util.types.isUint16Array(new Uint16Array()) // trueを返します
util.types.isUint16Array(new Float64Array()) // falseを返します

`util.types.isUint32Array(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのUint32Arrayインスタンスの場合、trueを返します。

util.types.isUint32Array(new ArrayBuffer()) // falseを返します
util.types.isUint32Array(new Uint32Array()) // trueを返します
util.types.isUint32Array(new Float64Array()) // falseを返します

`util.types.isWeakMap(value)`

追加: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのWeakMapインスタンスの場合、trueを返します。

util.types.isWeakMap(new WeakMap()) // trueを返します

`util.types.isWeakSet(value)`

追加日時: v10.0.0

value <any>
戻り値: <boolean>

値が組み込みのWeakSetインスタンスの場合、trueを返します。

util.types.isWeakSet(new WeakSet()) // trueを返す

非推奨 API

以下の API は非推奨であり、使用すべきではありません。既存のアプリケーションとモジュールは、代替アプローチを見つけるように更新する必要があります。

`util._extend(target, source)`

追加日時: v0.7.5

非推奨日時: v6.0.0

[安定性: 0 - 非推奨]

安定性: 0 安定性: 0 - 非推奨: 代わりにObject.assign()を使用してください。

target <Object>
source <Object>

util._extend()メソッドは、内部 Node.js モジュール以外で使用することを意図していませんでした。コミュニティが発見して使用していました。

非推奨であり、新しいコードでは使用しないでください。JavaScript には、Object.assign()を通じて非常に類似した組み込み機能があります。

`util.isArray(object)`

追加日時: v0.6.0

非推奨日時: v4.0.0

[安定性: 0 - 非推奨]

安定性: 0 安定性: 0 - 非推奨: 代わりにArray.isArray()を使用してください。

object <any>
戻り値: <boolean>

Array.isArray()のエイリアスです。

与えられたobjectがArrayの場合、trueを返します。それ以外の場合はfalseを返します。

const util = require('node:util')

util.isArray([])
// 戻り値: true
util.isArray(new Array())
// 戻り値: true
util.isArray({})
// 戻り値: false

Util ​

util.callbackify(original) ​

util.debuglog(section[, callback]) ​

debuglog().enabled ​

util.debug(section) ​

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

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

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

util.getCallSites(frameCountOrOptions, [options]) ​

util.getSystemErrorName(err) ​

util.getSystemErrorMap() ​

util.getSystemErrorMessage(err) ​

util.inherits(constructor, superConstructor) ​

util.inspect(object[, options]) ​

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

util.inspect の色のカスタマイズ ​

修飾子 ​

前景色 ​

背景色 ​

オブジェクトのカスタム検査関数 ​

util.inspect.custom ​

util.inspect.defaultOptions ​

util.isDeepStrictEqual(val1, val2) ​

クラス: util.MIMEType ​

コンストラクタ: new MIMEType(input) ​

mime.type ​

mime.subtype ​

mime.essence ​

mime.params ​

mime.toString() ​

mime.toJSON() ​

クラス: util.MIMEParams ​

コンストラクタ: new MIMEParams() ​

mimeParams.delete(name) ​

mimeParams.entries() ​

mimeParams.get(name) ​

mimeParams.has(name) ​

mimeParams.keys() ​

mimeParams.set(name, value) ​

mimeParams.values() ​

mimeParams[@@iterator]() ​

util.parseArgs([config]) ​

parseArgs tokens ​

util.parseEnv(content) ​

util.promisify(original) ​

カスタムプロミス化関数 ​

util.promisify.custom ​

util.stripVTControlCharacters(str) ​

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

クラス: util.TextDecoder ​

WHATWG でサポートされているエンコーディング ​

デフォルトでサポートされるエンコーディング（完全な ICU データ付き） ​

small-icuオプション付きで Node.js をビルドした場合にサポートされるエンコーディング ​

ICU が無効になっている場合にサポートされるエンコーディング ​

new TextDecoder([encoding[, options]]) ​

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

textDecoder.encoding ​

textDecoder.fatal ​

textDecoder.ignoreBOM ​

クラス: util.TextEncoder ​

textEncoder.encode([input]) ​

textEncoder.encodeInto(src, dest) ​

textEncoder.encoding ​

util.toUSVString(string) ​

util.transferableAbortController() ​

util.transferableAbortSignal(signal) ​

util.aborted(signal, resource) ​

util.types ​

util.types.isAnyArrayBuffer(value) ​

util.types.isArrayBufferView(value) ​

util.types.isArgumentsObject(value) ​

util.types.isArrayBuffer(value) ​

util.types.isAsyncFunction(value) ​

util.types.isBigInt64Array(value) ​

util.types.isBigIntObject(value) ​

util.types.isBigUint64Array(value) ​

util.types.isBooleanObject(value) ​

util.types.isBoxedPrimitive(value) ​

util.types.isCryptoKey(value) ​

util.types.isDataView(value) ​

Util

`util.callbackify(original)`

`util.debuglog(section[, callback])`

`debuglog().enabled`

`util.debug(section)`

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

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

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

`util.getCallSites(frameCountOrOptions, [options])`

`util.getSystemErrorName(err)`

`util.getSystemErrorMap()`

`util.getSystemErrorMessage(err)`

`util.inherits(constructor, superConstructor)`

`util.inspect(object[, options])`

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

`util.inspect` の色のカスタマイズ

修飾子

前景色

背景色

オブジェクトのカスタム検査関数

`util.inspect.custom`

`util.inspect.defaultOptions`

`util.isDeepStrictEqual(val1, val2)`

クラス: `util.MIMEType`

コンストラクタ: `new MIMEType(input)`

`mime.type`

`mime.subtype`

`mime.essence`

`mime.params`

`mime.toString()`

`mime.toJSON()`

クラス: `util.MIMEParams`

コンストラクタ: `new MIMEParams()`

`mimeParams.delete(name)`

`mimeParams.entries()`

`mimeParams.get(name)`

`mimeParams.has(name)`

`mimeParams.keys()`

`mimeParams.set(name, value)`

`mimeParams.values()`

`mimeParams[@@iterator]()`

`util.parseArgs([config])`

`parseArgs` `tokens`

`util.parseEnv(content)`

`util.promisify(original)`

カスタムプロミス化関数

`util.promisify.custom`

`util.stripVTControlCharacters(str)`

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

クラス: `util.TextDecoder`

WHATWG でサポートされているエンコーディング

デフォルトでサポートされるエンコーディング（完全な ICU データ付き）

`small-icu`オプション付きで Node.js をビルドした場合にサポートされるエンコーディング

ICU が無効になっている場合にサポートされるエンコーディング

`new TextDecoder([encoding[, options]])`

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

`textDecoder.encoding`

`textDecoder.fatal`

`textDecoder.ignoreBOM`

クラス: `util.TextEncoder`

`textEncoder.encode([input])`

`textEncoder.encodeInto(src, dest)`

`textEncoder.encoding`

`util.toUSVString(string)`

`util.transferableAbortController()`

`util.transferableAbortSignal(signal)`

`util.aborted(signal, resource)`

`util.types`

`util.types.isAnyArrayBuffer(value)`

`util.types.isArrayBufferView(value)`

`util.types.isArgumentsObject(value)`

`util.types.isArrayBuffer(value)`

`util.types.isAsyncFunction(value)`

`util.types.isBigInt64Array(value)`

`util.types.isBigIntObject(value)`

`util.types.isBigUint64Array(value)`

`util.types.isBooleanObject(value)`

`util.types.isBoxedPrimitive(value)`

`util.types.isCryptoKey(value)`

`util.types.isDataView(value)`