タイマー

[安定版: 2 - 安定版]

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

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

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

クラス: `Immediate`

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

デフォルトでは、イミディエイトがスケジュールされると、イミディエイトがアクティブである限り、Node.js イベントループは実行を続けます。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 オブジェクトは「参照」されているため、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()を呼び出すことと似ています。

クラス: `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オブジェクトは「参照」されているため、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

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

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

`timeout[Symbol.dispose]()`

追加日時: v20.5.0, v18.18.0

[安定版: 1 - 実験的]

安定版: 1 安定性: 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>

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

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	追加: 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()を使用して利用できる、Promise 用のカスタムバリアントがあります。

タイマーのキャンセル

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

追加日時: v0.9.1

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

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

`clearInterval(timeout)`

追加日時: v0.0.1

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

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

`clearTimeout(timeout)`

追加日時: v0.0.1

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

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

タイマー Promise API

[履歴]

バージョン	変更点
v16.0.0	実験段階から卒業
v15.0.0	追加日時: 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]]])`

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

delay <number> Promise が完了するまで待つミリ秒数。デフォルト: 1。
value <any> Promise が完了した際に返される値。
options <Object>
- ref <boolean> スケジュールされたTimeoutが Node.js イベントループの動作を維持する必要がないことを示すにはfalseに設定します。デフォルト: true。
- signal <AbortSignal> スケジュールされたTimeoutをキャンセルするために使用できるオプションのAbortSignal。

ESMCJS

import { setTimeout } from 'node:timers/promises'

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

console.log(res) // 'result'が出力されます

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

setTimeout(100, 'result').then(res => {
  console.log(res) // 'result'が出力されます
})

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

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

value <any> Promise が完了した際に返される値。
options <Object>
- ref <boolean> スケジュールされたImmediateが Node.js イベントループの動作を維持する必要がないことを示すにはfalseに設定します。デフォルト: true。
- signal <AbortSignal> スケジュールされたImmediateをキャンセルするために使用できるオプションのAbortSignal。

ESMCJS

import { setImmediate } from 'node:timers/promises'

const res = await setImmediate('result')

console.log(res) // 'result'が出力されます

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

setImmediate('result').then(res => {
  console.log(res) // 'result'が出力されます
})

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

追加: 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])`

追加: v17.3.0, v16.14.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

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

標準的な Web プラットフォーム API として開発されているスケジューリング APIドラフト仕様によって定義された実験的な 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

[安定版: 1 - 実験的]

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

戻り値: <Promise>

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

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

タイマー ​

クラス: Immediate ​

immediate.hasRef() ​

immediate.ref() ​

immediate.unref() ​

immediate[Symbol.dispose]() ​

クラス: 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) ​

タイマー Promise 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]()`

クラス: `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)`

タイマー Promise API

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

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

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

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

`timersPromises.scheduler.yield()`