Minuteurs

[Stable: 2 - Stable]

Le module timer expose une API globale pour planifier l’appel de fonctions à un moment futur. Puisque les fonctions de minuterie sont globales, il n’est pas nécessaire d’appeler require('node:timers') pour utiliser l’API.

Les fonctions de minuterie dans Node.js implémentent une API similaire à l’API de minuterie fournie par les navigateurs Web, mais utilisent une implémentation interne différente qui est construite autour de la boucle d’événement de Node.js.

Classe : `Immediate`

Cet objet est créé en interne et est renvoyé par setImmediate(). Il peut être transmis à clearImmediate() afin d’annuler les actions planifiées.

Par défaut, lorsqu’une action immédiate est planifiée, la boucle d’événement Node.js continue de s’exécuter tant que l’action immédiate est active. L’objet Immediate renvoyé par setImmediate() exporte les fonctions immediate.ref() et immediate.unref() qui peuvent être utilisées pour contrôler ce comportement par défaut.

`immediate.hasRef()`

Ajouté dans : v11.0.0

Renvoie : <boolean>

Si la valeur est vraie, l’objet Immediate maintiendra la boucle d’événement Node.js active.

`immediate.ref()`

Ajouté dans : v9.7.0

Renvoie : <Immediate> une référence à immediate

Lorsqu’elle est appelée, cette fonction demande à la boucle d’événement Node.js de ne pas se fermer tant que l’action Immediate est active. L’appel de immediate.ref() plusieurs fois n’aura aucun effet.

Par défaut, tous les objets Immediate sont « ref’ed », ce qui rend normalement inutile l’appel de immediate.ref() à moins que immediate.unref() n’ait été appelé auparavant.

`immediate.unref()`

Ajouté dans : v9.7.0

Renvoie : <Immediate> une référence à immediate

Lorsqu’elle est appelée, demande à la boucle d’événement Node.js de ne pas maintenir active l’action Immediate. L’appel de immediate.unref() plusieurs fois n’aura aucun effet.

Par défaut, tous les objets Immediate sont « ref’ed », et il est normalement nécessaire d’appeler immediate.unref() s’il est souhaité que le comportement par défaut soit abandonné et que la boucle d’événement de Node.js soit autorisée à sortir si l’action Immediate est la seule à être active.

`immediate.unref()`

Ajouté dans : v9.7.0

Retourne : <Immediate> une référence à immediate

Lorsqu'elle est appelée, l'objet Immediate actif n'exigera pas que la boucle d'événements Node.js reste active. S'il n'y a aucune autre activité qui maintient la boucle d'événements en cours d'exécution, le processus peut se terminer avant que le rappel de l'objet Immediate ne soit invoqué. Appeler immediate.unref() plusieurs fois n'aura aucun effet.

`immediate[Symbol.dispose]()`

Ajouté dans : v20.5.0, v18.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Annule l'opération immediate. C'est similaire à l'appel de clearImmediate().

Classe : `Timeout`

Cet objet est créé en interne et est renvoyé par setTimeout() et setInterval(). Il peut être transmis à clearTimeout() ou à clearInterval() afin d'annuler les actions planifiées.

Par défaut, lorsqu'un minuteur est planifié à l'aide de setTimeout() ou de setInterval(), la boucle d'événements Node.js continuera de fonctionner tant que le minuteur est actif. Chacun des objets Timeout renvoyés par ces fonctions exporte les fonctions timeout.ref() et timeout.unref() qui peuvent être utilisées pour contrôler ce comportement par défaut.

`timeout.close()`

Ajouté dans : v0.9.1

[Stable : 3 - Hérité]

Stable : 3 Stabilité : 3 - Hérité : utilisez plutôt clearTimeout().

Retourne : <Timeout> une référence à timeout

Annule le timeout.

`timeout.hasRef()`

Ajouté dans : v11.0.0

Retourne : <boolean>

Si la valeur est true, l'objet Timeout maintiendra la boucle d'événements Node.js active.

`timeout.ref()`

Ajouté dans : v0.9.1

Retourne : <Timeout> une référence à timeout

Lorsqu'elle est appelée, demande à la boucle d'événements de Node.js de ne pas se terminer tant que le Timeout est actif. Appeler timeout.ref() plusieurs fois n'aura aucun effet.

Par défaut, tous les objets Timeout sont "référencés", il est donc généralement inutile d'appeler timeout.ref() sauf si timeout.unref() a été appelé précédemment.

`timeout.refresh()`

Ajouté dans : v10.2.0

Retourne : <Timeout> une référence à timeout

Définit l'heure de début du minuteur sur l'heure actuelle et reprogramme le minuteur pour appeler son rappel à la durée spécifiée précédemment, ajustée à l'heure actuelle. Ceci est utile pour actualiser un minuteur sans allouer un nouvel objet JavaScript.

L'utilisation de cette méthode sur un minuteur qui a déjà appelé son rappel réactivera le minuteur.

`timeout.unref()`

Ajouté dans : v0.9.1

Retourne : <Timeout> une référence à timeout

Lorsqu'il est appelé, l'objet Timeout actif n'exigera pas que la boucle d'événements de Node.js reste active. S'il n'y a aucune autre activité qui maintient la boucle d'événements en cours d'exécution, le processus peut se terminer avant que le rappel de l'objet Timeout ne soit invoqué. Appeler timeout.unref() plusieurs fois n'aura aucun effet.

`timeout[Symbol.toPrimitive]()`

Ajouté dans : v14.9.0, v12.19.0

Retourne : <integer> un nombre qui peut être utilisé pour faire référence à ce timeout

Force un Timeout à une primitive. La primitive peut être utilisée pour effacer le Timeout. La primitive ne peut être utilisée que dans le même thread où le délai d'expiration a été créé. Par conséquent, pour l'utiliser dans les worker_threads, il faut d'abord le transmettre au thread approprié. Cela permet une compatibilité améliorée avec les implémentations setTimeout() et setInterval() du navigateur.

`timeout[Symbol.dispose]()`

Ajouté dans : v20.5.0, v18.18.0

[Stable: 1 - Expérimental]

Stable: 1 Stabilité: 1 - Expérimental

Annule le délai d'attente.

Planification des temporisateurs

Un temporisateur dans Node.js est une construction interne qui appelle une fonction donnée après un certain laps de temps. Le moment où la fonction d'un temporisateur est appelée varie en fonction de la méthode utilisée pour créer le temporisateur et du travail effectué par la boucle d'événements de Node.js.

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

[Historique]

Version	Changements
v18.0.0	Le passage d'un rappel invalide à l'argument `callback` lève désormais `ERR_INVALID_ARG_TYPE` au lieu de `ERR_INVALID_CALLBACK`.
v0.9.1	Ajouté dans : v0.9.1

callback <Function> La fonction à appeler à la fin de ce tour de la boucle d'événements Node.js.
...args <any> Arguments optionnels à passer lorsque la callback est appelée.
Retourne : <Immediate> à utiliser avec clearImmediate()

Planifie l'exécution "immédiate" de la callback après les rappels des événements d'E/S.

Lorsque plusieurs appels à setImmediate() sont effectués, les fonctions callback sont mises en file d'attente pour être exécutées dans l'ordre dans lequel elles sont créées. La file d'attente de rappels complète est traitée à chaque itération de la boucle d'événements. Si un temporisateur immédiat est mis en file d'attente à partir d'un rappel en cours d'exécution, ce temporisateur ne sera pas déclenché avant la prochaine itération de la boucle d'événements.

Si callback n'est pas une fonction, un TypeError sera levé.

Cette méthode a une variante personnalisée pour les promesses qui est disponible en utilisant timersPromises.setImmediate().

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

[Historique]

Version	Changements
v18.0.0	Le passage d'un rappel invalide à l'argument `callback` lève désormais `ERR_INVALID_ARG_TYPE` au lieu de `ERR_INVALID_CALLBACK`.
v0.0.1	Ajouté dans : v0.0.1

callback <Function> La fonction à appeler lorsque le temporisateur expire.
delay <number> Le nombre de millisecondes à attendre avant d'appeler la callback. Par défaut : 1.
...args <any> Arguments optionnels à passer lorsque la callback est appelée.
Retourne : <Timeout> à utiliser avec clearInterval()

Planifie l'exécution répétée de la callback toutes les delay millisecondes.

Lorsque delay est supérieur à 2147483647 ou inférieur à 1 ou NaN, la delay sera définie sur 1. Les délais non entiers sont tronqués en un entier.

Si callback n'est pas une fonction, un TypeError sera levé.

Cette méthode a une variante personnalisée pour les promesses qui est disponible en utilisant timersPromises.setInterval().

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

[Historique]

Version	Modifications
v18.0.0	Le passage d'un rappel invalide à l'argument `callback` lève désormais `ERR_INVALID_ARG_TYPE` au lieu de `ERR_INVALID_CALLBACK`.
v0.0.1	Ajouté dans : v0.0.1

callback <Function> La fonction à appeler lorsque le minuteur expire.
delay <number> Le nombre de millisecondes à attendre avant d'appeler le callback. Par défaut : 1.
...args <any> Arguments facultatifs à passer lors de l'appel du callback.
Renvoie : <Timeout> à utiliser avec clearTimeout()

Planifie l'exécution d'un callback unique après delay millisecondes.

Il est probable que le callback ne soit pas invoqué précisément dans delay millisecondes. Node.js ne garantit pas le moment exact où les rappels seront déclenchés, ni leur ordre. Le rappel sera appelé aussi près que possible de l'heure spécifiée.

Lorsque delay est supérieur à 2147483647 ou inférieur à 1 ou NaN, le delay sera défini à 1. Les délais non entiers sont tronqués en un entier.

Si callback n'est pas une fonction, une erreur TypeError sera levée.

Cette méthode possède une variante personnalisée pour les promesses qui est disponible en utilisant timersPromises.setTimeout().

Annulation des minuteurs

Les méthodes setImmediate(), setInterval() et setTimeout() renvoient chacune des objets qui représentent les minuteurs planifiés. Ceux-ci peuvent être utilisés pour annuler le minuteur et l'empêcher de se déclencher.

Pour les variantes promifiées de setImmediate() et setTimeout(), un AbortController peut être utilisé pour annuler le minuteur. Lorsqu'elles sont annulées, les promesses renvoyées seront rejetées avec une 'AbortError'.

Pour setImmediate() :

ESMCJS

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

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

// Nous n'attendons pas la promesse, donc `ac.abort()` est appelé en parallèle.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('L’immédiat a été interrompu')
  })

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('L’immédiat a été interrompu')
  })

ac.abort()

Pour setTimeout() :

ESMCJS

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

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

// Nous n'attendons pas la promesse, donc `ac.abort()` est appelé en parallèle.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('Le délai a été interrompu')
  })

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('Le délai a été interrompu')
  })

ac.abort()

`clearImmediate(immediate)`

Ajouté dans : v0.9.1

immediate <Immediate> Un objet Immediate tel que retourné par setImmediate().

Annule un objet Immediate créé par setImmediate().

`clearInterval(timeout)`

Ajouté dans : v0.0.1

timeout <Timeout> | <string> | <number> Un objet Timeout tel que retourné par setInterval() ou le primitif de l’objet Timeout sous forme de chaîne ou de nombre.

Annule un objet Timeout créé par setInterval().

`clearTimeout(timeout)`

Ajouté dans : v0.0.1

timeout <Timeout> | <string> | <number> Un objet Timeout tel que retourné par setTimeout() ou le primitif de l’objet Timeout sous forme de chaîne ou de nombre.

Annule un objet Timeout créé par setTimeout().

API Timers Promises

[Historique]

Version	Modifications
v16.0.0	Sortie du statut expérimental.
v15.0.0	Ajouté dans : v15.0.0

L’API timers/promises fournit un ensemble alternatif de fonctions de temporisation qui retournent des objets Promise. L’API est accessible via 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]]])`

Ajouté dans : v15.0.0

delay <number> Le nombre de millisecondes à attendre avant de tenir la promesse. Par défaut : 1.
value <any> Une valeur avec laquelle la promesse est tenue.
options <Object>
- ref <boolean> Définir sur false pour indiquer que le Timeout planifié ne doit pas exiger que la boucle d’événements Node.js reste active. Par défaut : true.
- signal <AbortSignal> Un AbortSignal facultatif qui peut être utilisé pour annuler le Timeout planifié.

ESMCJS

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

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

console.log(res) // Affiche 'result'

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

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

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

Ajouté dans : v15.0.0

value <any> Une valeur avec laquelle la promesse est tenue.
options <Object>
- ref <boolean> Définir sur false pour indiquer que le Immediate planifié ne doit pas exiger que la boucle d’événements Node.js reste active. Par défaut : true.
- signal <AbortSignal> Un AbortSignal facultatif qui peut être utilisé pour annuler le Immediate planifié.

ESMCJS

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

const res = await setImmediate('result')

console.log(res) // Affiche 'result'

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

setImmediate('result').then(res => {
  console.log(res) // Affiche 'result'
})

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

Ajouté dans : v15.9.0

Renvoie un itérateur asynchrone qui génère des valeurs à un intervalle de delay ms. Si ref est true, vous devez appeler next() de l'itérateur asynchrone explicitement ou implicitement pour maintenir la boucle d'événement active.

delay <number> Le nombre de millisecondes à attendre entre les itérations. Par défaut : 1.
value <any> Une valeur avec laquelle l'itérateur renvoie.
options <Object>
- ref <boolean> Définissez sur false pour indiquer que le Timeout planifié entre les itérations ne doit pas exiger que la boucle d'événement Node.js reste active. Par défaut : true.
- signal <AbortSignal> Un AbortSignal facultatif qui peut être utilisé pour annuler le Timeout planifié entre les opérations.

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

Ajouté dans : v17.3.0, v16.14.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

delay <number> Le nombre de millisecondes à attendre avant de résoudre la promesse.
options <Object>
- ref <boolean> Définissez sur false pour indiquer que le Timeout planifié ne doit pas exiger que la boucle d'événement Node.js reste active. Par défaut : true.
- signal <AbortSignal> Un AbortSignal facultatif qui peut être utilisé pour annuler l'attente.
Renvoie : <Promise>

Une API expérimentale définie par la spécification provisoire des API de planification en cours d'élaboration en tant qu'API de plateforme Web standard.

L'appel de timersPromises.scheduler.wait(delay, options) équivaut à l'appel de timersPromises.setTimeout(delay, undefined, options).

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

await scheduler.wait(1000) // Attendre une seconde avant de continuer

`timersPromises.scheduler.yield()`

Ajouté dans : v17.3.0, v16.14.0

[Stable: 1 - Expérimental]

Stable: 1 Stable: 1 - Expérimental

Retourne : <Promise>

Une API expérimentale définie par le projet de spécification des API de planification en cours de développement comme API standard de la plateforme Web.

L'appel de timersPromises.scheduler.yield() équivaut à l'appel de timersPromises.setImmediate() sans arguments.

Minuteurs ​

Classe : Immediate ​

immediate.hasRef() ​

immediate.ref() ​

immediate.unref() ​

immediate.unref() ​

immediate[Symbol.dispose]() ​

Classe : Timeout ​

timeout.close() ​

timeout.hasRef() ​

timeout.ref() ​

timeout.refresh() ​

timeout.unref() ​

timeout[Symbol.toPrimitive]() ​

timeout[Symbol.dispose]() ​

Planification des temporisateurs ​

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

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

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

Annulation des minuteurs ​

clearImmediate(immediate) ​

clearInterval(timeout) ​

clearTimeout(timeout) ​

API Timers Promises ​

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

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

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

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

timersPromises.scheduler.yield() ​

Minuteurs

Classe : `Immediate`

`immediate.hasRef()`

`immediate.ref()`

`immediate.unref()`

`immediate.unref()`

`immediate[Symbol.dispose]()`

Classe : `Timeout`

`timeout.close()`

`timeout.hasRef()`

`timeout.ref()`

`timeout.refresh()`

`timeout.unref()`

`timeout[Symbol.toPrimitive]()`

`timeout[Symbol.dispose]()`

Planification des temporisateurs

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

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

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

Annulation des minuteurs

`clearImmediate(immediate)`

`clearInterval(timeout)`

`clearTimeout(timeout)`

API Timers Promises

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

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

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

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

`timersPromises.scheduler.yield()`