Temporisateurs

[Stable: 2 - Stable]

Le module timer expose une API globale pour planifier des fonctions à appeler dans un certain laps de temps. Étant donné que les fonctions de temporisation sont globales, il n'est pas nécessaire d'appeler require('node:timers') pour utiliser l'API.

Les fonctions de temporisation dans Node.js implémentent une API similaire à l'API de temporisation fournie par les navigateurs Web, mais utilisent une implémentation interne différente qui est construite autour de la boucle d'événements 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'un immédiat est planifié, la boucle d'événements Node.js continue de s'exécuter tant que l'immédiat est actif. 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ée dans : v11.0.0

Retourne : <boolean>

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

`immediate.ref()`

Ajoutée dans : v9.7.0

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

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

Par défaut, tous les objets Immediate sont "ref'ed", ce qui rend normalement inutile d'appeler immediate.ref() sauf si immediate.unref() a été appelé précédemment.

`immediate.unref()`

Ajouté dans : v9.7.0

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

Lorsqu'il est appelé, l'objet Immediate actif n'exigera pas que la boucle d'événements Node.js reste active. S'il n'y a pas d'autre activité maintenant la boucle d'événements en cours d'exécution, le processus peut se terminer avant que le callback 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 - Experimental]

Stable: 1 Stability: 1 - Expérimental

Annule l’immédiat. Ceci est similaire à appeler clearImmediate().

Class: `Timeout`

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

Par défaut, lorsqu'un minuteur est planifié en utilisant soit setTimeout() soit setInterval(), la boucle d'événements Node.js continuera à s'exécuter tant que le minuteur est actif. Chacun des objets Timeout retourné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 - Legacy]

Stable: 3 Stability: 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 au timeout

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

Par défaut, tous les objets Timeout sont "ref'ed", ce qui rend normalement inutile l'appel à 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 au timeout

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

Utiliser ceci sur un timer qui a déjà appelé son callback réactivera le timer.

`timeout.unref()`

Ajouté dans : v0.9.1

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

Lorsqu'il est appelé, l'objet Timeout actif n'exigera pas que la boucle d'événements Node.js reste active. S'il n'y a aucune autre activité maintenant la boucle d'événements en cours d'exécution, le processus peut se fermer avant que le callback 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 référencer ce timeout

Force un Timeout à être 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 timeout a été créé. Par conséquent, pour l'utiliser dans les worker_threads, il doit d'abord être passé au thread correct. Ceci 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 - Experimental]

Stable: 1 Stability: 1 - Expérimental

Annule le délai d'attente.

Programmation de temporisateurs

Un temporisateur dans Node.js est une construction interne qui appelle une fonction donnée après une certaine période 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 Node.js.

`setImmediate(callback[, ...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.9.1	Ajoutée dans : v0.9.1

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

Planifie l'exécution "immédiate" du 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 totalité de la file d'attente des rappels est traitée à chaque itération de la boucle d'événements. Si un temporisateur immédiat est mis en file d'attente depuis l'intérieur 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, une TypeError sera levée.

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

`setInterval(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ée dans : v0.0.1

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

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

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

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

Cette méthode possède 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 callback invalide à l'argument `callback` lève maintenant une erreur `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 délai est écoulé.
delay <number> Le nombre de millisecondes à attendre avant d'appeler le callback. Par défaut : 1.
...args <any> Arguments optionnels à passer lorsque le callback est appelé.
Retourne : <Timeout> à utiliser avec clearTimeout()

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

Le callback ne sera probablement pas invoqué précisément dans delay millisecondes. Node.js ne donne aucune garantie quant au moment exact où les callbacks seront déclenchés, ni quant à leur ordre. Le callback sera appelé aussi près que possible du moment spécifié.

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

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

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

Annulation des temporisateurs

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

Pour les variantes promissifiées de setImmediate() et setTimeout(), un AbortController peut être utilisé pour annuler le temporisateur. En cas d'annulation, 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 afin que `ac.abort()` soit appelé simultanément.
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();

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 afin que `ac.abort()` soit appelé simultanément.
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)`

Ajouté dans: v0.9.1

immediate <Immediate> Un objet Immediate tel que renvoyé 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 renvoyé par setInterval() ou la primitive de l'objet Timeout sous forme de chaîne de caractères 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 renvoyé par setTimeout() ou la primitive de l'objet Timeout sous forme de chaîne de caractères ou de nombre.

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

API de promesses des timers

[Historique]

Version	Modifications
v16.0.0	Sortie de l'état expérimental.
v15.0.0	Ajouté dans: v15.0.0

L'API timers/promises fournit un ensemble alternatif de fonctions de timer qui renvoient 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 réaliser la promesse. Par défaut : 1.
value <any> Une valeur avec laquelle la promesse est réalisée.
options <Object>
- ref <boolean> Définir sur false pour indiquer que le Timeout planifié ne doit pas nécessiter que la boucle d’événement Node.js reste active. Par défaut : true.
- signal <AbortSignal> Un AbortSignal optionnel 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 réalisée.
options <Object>
- ref <boolean> Définir sur false pour indiquer que l' Immediate planifié ne doit pas nécessiter que la boucle d’événement Node.js reste active. Par défaut : true.
- signal <AbortSignal> Un AbortSignal optionnel qui peut être utilisé pour annuler l' 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

Retourne un itérateur asynchrone qui génère des valeurs à un intervalle de delay ms. Si ref vaut true, vous devez appeler explicitement ou implicitement next() de l'itérateur asynchrone pour maintenir la boucle d'événements 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éfinir sur false pour indiquer que le Timeout planifié entre les itérations ne doit pas exiger que la boucle d'événements Node.js reste active. Par défaut : true.
- signal <AbortSignal> Un AbortSignal optionnel 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 - Experimental]

Stable: 1 Stabilité : 1 - Expérimental

delay <number> Le nombre de millisecondes à attendre avant de résoudre la promesse.
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 optionnel qui peut être utilisé pour annuler l'attente.
Retourne : <Promise>

Une API expérimentale définie par le projet de spécification Scheduling APIs en cours de développement en tant qu'API Web Platform standard.

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

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

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

`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 brouillon de spécification des API de planification en cours de développement en tant qu’API de plateforme Web standard.

L’appel de timersPromises.scheduler.yield() équivaut à appeler timersPromises.setImmediate() sans arguments.

Temporisateurs ​

Classe : 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]() ​

Programmation de temporisateurs ​

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

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

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

Annulation des temporisateurs ​

clearImmediate(immediate) ​

clearInterval(timeout) ​

clearTimeout(timeout) ​

API de promesses des timers ​

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

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

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

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

timersPromises.scheduler.yield() ​

Temporisateurs

Classe : `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]()`

Programmation de temporisateurs

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

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

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

Annulation des temporisateurs

`clearImmediate(immediate)`

`clearInterval(timeout)`

`clearTimeout(timeout)`

API de promesses des timers

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

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

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

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

`timersPromises.scheduler.yield()`