Node.js v21.7.2 ドキュメント

クラス: `Immediate`#

このオブジェクトは内部的に作成され、`setImmediate()`から返されます。これは、スケジュールされたアクションをキャンセルするために`clearImmediate()`に渡すことができます。

デフォルトでは、イミディエイトがスケジュールされると、イミディエイトがアクティブである限り、Node.jsイベントループは実行を続けます。`setImmediate()`によって返される`Immediate`オブジェクトは、このデフォルトの動作を制御するために使用できる`immediate.ref()`と`immediate.unref()`関数の両方をエクスポートします。

`immediate.hasRef()`#

• 戻り値: <boolean>

trueの場合、`Immediate`オブジェクトはNode.jsイベントループをアクティブな状態に保ちます。

`immediate.ref()`#

• 戻り値: <Immediate> `immediate`への参照

呼び出されると、`Immediate`がアクティブである限り、Node.jsイベントループが終了しないように要求します。`immediate.ref()`を複数回呼び出しても効果はありません。

デフォルトでは、すべての`Immediate`オブジェクトは「参照」されているため、以前`immediate.unref()`が呼び出されていなければ、通常`immediate.ref()`を呼び出す必要はありません。

`immediate.unref()`#

• 戻り値: <Immediate> `immediate`への参照

呼び出されると、アクティブな`Immediate`オブジェクトはNode.jsイベントループがアクティブな状態を維持する必要がなくなります。イベントループの実行を維持している他のアクティビティがない場合、`Immediate`オブジェクトのコールバックが呼び出される前にプロセスが終了することがあります。`immediate.unref()`を複数回呼び出しても効果はありません。

`immediate[Symbol.dispose]()`#

イミディエイトをキャンセルします。これは`clearImmediate()`を呼び出すことと同様です。

クラス: `Timeout`#

このオブジェクトは内部的に作成され、`setTimeout()`と`setInterval()`から返されます。これは、スケジュールされたアクションをキャンセルするために`clearTimeout()`または`clearInterval()`のいずれかに渡すことができます。

デフォルトでは、`setTimeout()`または`setInterval()`のいずれかを使用してタイマーがスケジュールされると、タイマーがアクティブである限り、Node.jsイベントループは実行を続けます。これらの関数によって返される`Timeout`オブジェクトのそれぞれは、このデフォルトの動作を制御するために使用できる`timeout.ref()`と`timeout.unref()`関数の両方をエクスポートします。

`timeout.close()`#

• 戻り値: <Timeout> `timeout`への参照

タイムアウトをキャンセルします。

`timeout.hasRef()`#

• 戻り値: <boolean>

trueの場合、`Timeout`オブジェクトはNode.jsイベントループをアクティブな状態に保ちます。

`timeout.ref()`#

• 戻り値: <Timeout> `timeout`への参照

呼び出されると、`Timeout`がアクティブである限り、Node.jsイベントループが終了しないように要求します。`timeout.ref()`を複数回呼び出しても効果はありません。

デフォルトでは、すべての`Timeout`オブジェクトは「参照」されているため、以前`timeout.unref()`が呼び出されていなければ、通常`timeout.ref()`を呼び出す必要はありません。

`timeout.refresh()`#

• 戻り値: <Timeout> `timeout`への参照

タイマーの開始時間を現在時間に設定し、タイマーを再スケジュールして、現在時間に調整された以前に指定された期間でコールバックを呼び出します。これは、新しいJavaScriptオブジェクトを割り当てずにタイマーを更新するのに役立ちます。

すでにコールバックを呼び出しているタイマーで使用すると、タイマーが再びアクティブになります。

`timeout.unref()`#

• 戻り値: <Timeout> `timeout`への参照

呼び出されると、アクティブな`Timeout`オブジェクトはNode.jsイベントループがアクティブな状態を維持する必要がなくなります。イベントループの実行を維持している他のアクティビティがない場合、`Timeout`オブジェクトのコールバックが呼び出される前にプロセスが終了することがあります。`timeout.unref()`を複数回呼び出しても効果はありません。

`timeout[Symbol.toPrimitive]()`#

• 戻り値: <integer> この`timeout`を参照するために使用できる数値

`Timeout`をプリミティブに強制変換します。プリミティブは`Timeout`をクリアするために使用できます。プリミティブは、タイムアウトが作成されたのと同じスレッドでのみ使用できます。したがって、`worker_threads`間で使用するには、最初に正しいスレッドに渡す必要があります。これにより、ブラウザの`setTimeout()`と`setInterval()`実装との互換性が向上します。

`timeout[Symbol.dispose]()`#

タイムアウトをキャンセルします。

タイマーのスケジューリング#

Node.jsのタイマーは、一定時間後に指定された関数を呼び出す内部的な構成要素です。タイマーの関数が呼び出される時期は、タイマーの作成に使用されたメソッドと、Node.jsイベントループが実行している他の作業によって異なります。

`setImmediate(callback[, ...args])`#

• `callback` <Function> Node.js イベントループのこのターン終了時に呼び出す関数
• `...args` <any> `callback`が呼び出されたときに渡すオプションの引数。
• 戻り値: <Immediate> `clearImmediate()`で使用します。

I/Oイベントのコールバックの後で、`callback`の「即時」実行をスケジュールします。

`setImmediate()`への複数の呼び出しが行われると、`callback`関数は作成された順序で実行キューに配置されます。コールバックキュー全体は、イベントループの繰り返しごとに処理されます。実行中のコールバックの中からイミディエイトタイマーがキューに追加された場合、そのタイマーは次のイベントループの繰り返しまでトリガーされません。

`callback`が関数でない場合、`TypeError`がスローされます。

このメソッドには、timersPromises.setImmediate() を使用できるPromise用のカスタムバリアントがあります。

setInterval(callback[, delay[, ...args]])#

• callback <Function> タイマーが経過したときに呼び出す関数。
• delay <number> callback を呼び出す前に待つミリ秒数。デフォルト: 1。
• `...args` <any> `callback`が呼び出されたときに渡すオプションの引数。
• 戻り値: <Timeout> clearInterval() と共に使用します。

callback をdelayミリ秒ごとに繰り返し実行するようにスケジュールします。

delayが2147483647より大きく、または1より小さい場合、delayは1に設定されます。整数でない遅延は整数に切り捨てられます。

`callback`が関数でない場合、`TypeError`がスローされます。

このメソッドには、timersPromises.setInterval() を使用できるPromise用のカスタムバリアントがあります。

setTimeout(callback[, delay[, ...args]])#

• callback <Function> タイマーが経過したときに呼び出す関数。
• delay <number> callback を呼び出す前に待つミリ秒数。デフォルト: 1。
• `...args` <any> `callback`が呼び出されたときに渡すオプションの引数。
• 戻り値: <Timeout> clearTimeout() と共に使用します。

delayミリ秒後に1回限りのcallbackの実行をスケジュールします。

callbackは、正確にdelayミリ秒後に呼び出されるとは限りません。Node.jsは、コールバックがいつ、どのような順序で発火するかについて、正確なタイミングを保証しません。コールバックは、指定された時間にできるだけ近いタイミングで呼び出されます。

delayが2147483647より大きく、または1より小さい場合、delayは1に設定されます。整数でない遅延は整数に切り捨てられます。

`callback`が関数でない場合、`TypeError`がスローされます。

このメソッドには、timersPromises.setTimeout() を使用できるPromise用のカスタムバリアントがあります。

タイマーのキャンセル#

setImmediate()、setInterval()、およびsetTimeout()メソッドはそれぞれ、スケジュールされたタイマーを表すオブジェクトを返します。これらを使用して、タイマーをキャンセルし、トリガーされないようにすることができます。

setImmediate()とsetTimeout()のプロミス化されたバリアントでは、AbortControllerを使用してタイマーをキャンセルできます。キャンセルされると、返されたPromiseは'AbortError'で拒否されます。

setImmediate()の場合

const { setImmediate: setImmediatePromise } = require('node:timers/promises');

const ac = new AbortController();
const signal = ac.signal;

setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

ac.abort(); copy

setTimeout()の場合

const { setTimeout: setTimeoutPromise } = require('node:timers/promises');

const ac = new AbortController();
const signal = ac.signal;

setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

ac.abort(); copy

clearImmediate(immediate)#

• immediate <Immediate> setImmediate()によって返されたImmediateオブジェクト。

setImmediate()によって作成されたImmediateオブジェクトをキャンセルします。

clearInterval(timeout)#

• timeout <Timeout> | <string> | <number> setInterval()によって返されたTimeoutオブジェクト、または文字列または数値としてのTimeoutオブジェクトのプリミティブ。

setInterval()によって作成されたTimeoutオブジェクトをキャンセルします。

clearTimeout(timeout)#

• timeout <Timeout> | <string> | <number> setTimeout()によって返されたTimeoutオブジェクト、または文字列または数値としてのTimeoutオブジェクトのプリミティブ。

setTimeout()によって作成されたTimeoutオブジェクトをキャンセルします。

Timers Promises API#

timers/promises APIは、Promiseオブジェクトを返す代替のタイマー関数を提供します。このAPIは、require('node:timers/promises')を介してアクセスできます。

import {
  setTimeout,
  setImmediate,
  setInterval,
} from 'timers/promises';const {
  setTimeout,
  setImmediate,
  setInterval,
} = require('node:timers/promises');copy

timersPromises.setTimeout([delay[, value[, options]]])#

• delay <number> Promiseが解決されるまで待つミリ秒数。デフォルト: 1。
• value <any> Promiseが解決される値。
• options <Object>
  • ref <boolean> スケジュールされたTimeoutがNode.jsイベントループをアクティブな状態に保つ必要がないことを示すには、falseに設定します。デフォルト: true。
  • signal <AbortSignal> スケジュールされたTimeoutをキャンセルするために使用できるオプションのAbortSignal。

import {
  setTimeout,
} from 'timers/promises';

const res = await setTimeout(100, 'result');

console.log(res);  // Prints 'result'const {
  setTimeout,
} = require('node:timers/promises');

setTimeout(100, 'result').then((res) => {
  console.log(res);  // Prints 'result'
});copy

timersPromises.setImmediate([value[, options]])#

• value <any> Promiseが解決される値。
• options <Object>
  • ref <boolean> スケジュールされたImmediateがNode.jsイベントループをアクティブな状態に保つ必要がないことを示すには、falseに設定します。デフォルト: true。
  • signal <AbortSignal> スケジュールされたImmediateをキャンセルするために使用できるオプションのAbortSignal。

import {
  setImmediate,
} from 'timers/promises';

const res = await setImmediate('result');

console.log(res);  // Prints 'result'const {
  setImmediate,
} = require('node:timers/promises');

setImmediate('result').then((res) => {
  console.log(res);  // Prints 'result'
});copy

timersPromises.setInterval([delay[, value[, options]]])#

delay msの間隔で値を生成する非同期イテレーターを返します。refがtrueの場合、イベントループをアクティブに保つには、非同期イテレーターのnext()を明示的または暗黙的に呼び出す必要があります。

• delay <number> 反復間の待ち時間（ミリ秒）。デフォルト: 1。
• value <any> イテレーターが返す値。
• options <Object>
  • ref <boolean> 反復間のスケジュールされたTimeoutがNode.jsイベントループをアクティブな状態に保つ必要がないことを示すには、falseに設定します。デフォルト: true。
  • signal <AbortSignal> 操作間のスケジュールされたTimeoutをキャンセルするために使用できるオプションのAbortSignal。

import {
  setInterval,
} from 'timers/promises';

const interval = 100;
for await (const startTime of setInterval(interval, Date.now())) {
  const now = Date.now();
  console.log(now);
  if ((now - startTime) > 1000)
    break;
}
console.log(Date.now());const {
  setInterval,
} = require('node:timers/promises');
const interval = 100;

(async function() {
  for await (const startTime of setInterval(interval, Date.now())) {
    const now = Date.now();
    console.log(now);
    if ((now - startTime) > 1000)
      break;
  }
  console.log(Date.now());
})();copy

timersPromises.scheduler.wait(delay[, options])#

• delay <number> Promiseが解決されるまで待つミリ秒数。
• options <Object>
  • signal <AbortSignal> 待機をキャンセルするために使用できるオプションのAbortSignal。
• 戻り値: <Promise>

標準WebプラットフォームAPIとして開発されているScheduling APIsドラフト仕様で定義された実験的なAPI。

timersPromises.scheduler.wait(delay, options)を呼び出すことは、refオプションがサポートされていないことを除いて、timersPromises.setTimeout(delay, undefined, options)を呼び出すこととほぼ同等です。

import { scheduler } from 'node:timers/promises';

await scheduler.wait(1000); // Wait one second before continuing copy

timersPromises.scheduler.yield()#

• 戻り値: <Promise>

標準WebプラットフォームAPIとして開発されているScheduling APIsドラフト仕様で定義された実験的なAPI。

timersPromises.scheduler.yield()を呼び出すことは、引数なしでtimersPromises.setImmediate()を呼び出すことと同等です。