タイマー

[安定版: 2 - 安定]

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

timer モジュールは、将来のある時点で呼び出される関数をスケジュールするためのグローバル API を公開します。タイマー関数はグローバルであるため、API を使用するために require('node:timers') を呼び出す必要はありません。

Node.js 内のタイマー関数は、Web ブラウザーによって提供されるタイマー API と同様の API を実装しますが、Node.js のイベントループを中心に構築された異なる内部実装を使用します。

クラス: `Immediate`

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

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

`immediate.hasRef()`

追加: v11.0.0

戻り値: <boolean>

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

`immediate.ref()`

追加: v9.7.0

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

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

デフォルトでは、すべての Immediate オブジェクトは "ref'ed" になっているため、以前に immediate.unref() が呼び出されていない限り、通常は immediate.ref() を呼び出す必要はありません。

`immediate.unref()`

追加: v9.7.0

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

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

`immediate[Symbol.dispose]()`

追加: v20.5.0, v18.18.0

[安定性: 1 - 試験的]

安定性: 1 安定性: 1 - 試験的

immediateをキャンセルします。これはclearImmediate()の呼び出しに似ています。

Class: `Timeout`

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

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

`timeout.close()`

追加: v0.9.1

[安定性: 3 - レガシー]

安定性: 3 安定性: 3 - レガシー: 代わりにclearTimeout()を使用してください。

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

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

`timeout.hasRef()`

追加: v11.0.0

戻り値: <boolean>

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

`timeout.ref()`

追加: v0.9.1

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

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

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

`timeout.refresh()`

追加: v10.2.0

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

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

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

`timeout.unref()`

追加: v0.9.1

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

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

`timeout[Symbol.toPrimitive]()`

追加: v14.9.0, v12.19.0

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

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

`timeout[Symbol.dispose]()`

追加: v20.5.0, v18.18.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 試験的

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

タイマーのスケジュール

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

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

[履歴]

バージョン	変更点
v18.0.0	`callback` 引数に無効なコールバックを渡すと、`ERR_INVALID_CALLBACK` の代わりに `ERR_INVALID_ARG_TYPE` がスローされるようになりました。
v0.9.1	追加: v0.9.1

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

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

setImmediate() への複数の呼び出しが行われた場合、callback 関数は作成された順に実行待ち行列に入れられます。コールバックキュー全体が、イベントループの反復ごとに処理されます。実行中のコールバック内から即時タイマーがキューに入れられた場合、そのタイマーは次のイベントループの反復までトリガーされません。

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

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

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

[履歴]

バージョン	変更点
v18.0.0	`callback` 引数に無効なコールバックを渡すと、`ERR_INVALID_CALLBACK` の代わりに `ERR_INVALID_ARG_TYPE` がスローされるようになりました。
v0.0.1	追加: v0.0.1

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

callback の反復実行を delay ミリ秒ごとにスケジュールします。

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

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

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

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

[履歴]

バージョン	変更点
v18.0.0	`callback`引数に無効なコールバックを渡すと、`ERR_INVALID_CALLBACK`の代わりに`ERR_INVALID_ARG_TYPE`がスローされるようになりました。
v0.0.1	Added in: v0.0.1

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

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

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

delayが2147483647より大きいか、1より小さいか、NaNの場合、delayは1に設定されます。非整数の遅延は整数に切り捨てられます。

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

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

タイマーのキャンセル

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

setImmediate()およびsetTimeout()のPromise化されたバリアントでは、AbortControllerを使用してタイマーをキャンセルできます。キャンセルされると、返されたPromiseは'AbortError'でリジェクトされます。

setImmediate()の場合:

ESMCJS

import { setImmediate as setImmediatePromise } from 'node:timers/promises';

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

// Promiseを`await`しないため、`ac.abort()`は同時に呼び出されます。
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

ac.abort();

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();

setTimeout()の場合:

ESMCJS

import { setTimeout as setTimeoutPromise } from 'node:timers/promises';

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

// Promiseを`await`しないため、`ac.abort()`は同時に呼び出されます。
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

ac.abort();

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();

`clearImmediate(immediate)`

Added in: v0.9.1

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

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

`clearInterval(timeout)`

Added in: v0.0.1

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

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

`clearTimeout(timeout)`

Added in: v0.0.1

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

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

Timers Promises API

[History]

Version	Changes
v16.0.0	Graduated from experimental.
v15.0.0	Added in: v15.0.0

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

ESMCJS

import {
  setTimeout,
  setImmediate,
  setInterval,
} from 'node:timers/promises';

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

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

Added in: v15.0.0

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

ESMCJS

import {
  setTimeout,
} from 'node: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'
});

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

Added in: v15.0.0

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

ESMCJS

import {
  setImmediate,
} from 'node: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'
});

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

Added in: v15.9.0

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

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

ESMCJS

import {
  setInterval,
} from 'node: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());
})();

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

Added in: v17.3.0, v16.14.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 試験的

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

標準ウェブプラットフォーム API として開発されている Scheduling APIs ドラフト仕様によって定義された試験的な API。

timersPromises.scheduler.wait(delay, options) の呼び出しは、timersPromises.setTimeout(delay, undefined, options) の呼び出しと同等です。

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

await scheduler.wait(1000); // 継続する前に 1 秒間待機

`timersPromises.scheduler.yield()`

追加: v17.3.0, v16.14.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 試験的

戻り値: <Promise>

Scheduling APIsドラフト仕様によって定義される試験的なAPIであり、標準WebプラットフォームAPIとして開発されています。

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

タイマー ​

クラス: Immediate ​

immediate.hasRef() ​

immediate.ref() ​

immediate.unref() ​

immediate[Symbol.dispose]() ​

Class: Timeout ​

timeout.close() ​

timeout.hasRef() ​

timeout.ref() ​

timeout.refresh() ​

timeout.unref() ​

timeout[Symbol.toPrimitive]() ​

timeout[Symbol.dispose]() ​

タイマーのスケジュール ​

setImmediate(callback[, ...args]) ​

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

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

タイマーのキャンセル ​

clearImmediate(immediate) ​

clearInterval(timeout) ​

clearTimeout(timeout) ​

Timers Promises API ​

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

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

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

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

timersPromises.scheduler.yield() ​

タイマー

クラス: `Immediate`

`immediate.hasRef()`

`immediate.ref()`

`immediate.unref()`

`immediate[Symbol.dispose]()`

Class: `Timeout`

`timeout.close()`

`timeout.hasRef()`

`timeout.ref()`

`timeout.refresh()`

`timeout.unref()`

`timeout[Symbol.toPrimitive]()`

`timeout[Symbol.dispose]()`

タイマーのスケジュール

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

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

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

タイマーのキャンセル

`clearImmediate(immediate)`

`clearInterval(timeout)`

`clearTimeout(timeout)`

Timers Promises API

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

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

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

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

`timersPromises.scheduler.yield()`