Formations — 1 037 leçons en français

Accueil › Node.js › Écrire une transformation

Écrire une transformation

Les fluxintermediaire

Un Transform est un flux dont la sortie dérive de l'entrée. C'est le point d'extension d'un traitement en flux.

Le squelette

import { Transform } from "node:stream";

const enMajuscules = new Transform({
  transform(morceau, _encodage, suite) {
    suite(null, morceau.toString().toUpperCase());
  },
});

suite(null, valeur) pousse un morceau et signale qu'on est prêt pour le suivant. suite() sans valeur ne pousse rien — c'est ainsi qu'on filtre. this.push(a); this.push(b); suite(); pousse plusieurs morceaux pour un seul morceau entrant.

Le reste, et flush

const enLignes = new Transform({
  readableObjectMode: true,
  transform(morceau, _e, suite) {
    this.reste = (this.reste ?? "") + morceau.toString();
    const parts = this.reste.split("\n");
    this.reste = parts.pop();          // peut-être une ligne coupée
    for (const l of parts) this.push(l);
    suite();
  },
  flush(suite) {
    if (this.reste) this.push(this.reste);   // la dernière ligne sans \n
    suite();
  },
});

Deux erreurs se cachent ici, et elles sont très fréquentes. Un morceau coupe au milieu d'une ligne : il faut garder le reste. Et le fichier peut ne pas finir par un retour à la ligne : sans flush, la dernière ligne est silencieusement perdue.

Le mode objet

new Transform({ objectMode: true, transform(ligne, _e, suite) { … } });

En mode objet, les morceaux sont des valeurs JavaScript quelconques. C'est ce qui permet de faire circuler des enregistrements au lieu d'octets — et de composer un traitement en étapes lisibles.

Les termes à connaître

Transform

Un flux lisible et inscriptible dont la sortie dérive de l'entrée. Le point d'extension normal d'un traitement en flux.

transform(morceau, encodage, suite)

La méthode appelée pour chaque morceau entrant. On pousse zéro, un ou plusieurs morceaux en sortie, puis on appelle suite.

flush(suite)

Appelée une fois, après le dernier morceau. C'est là qu'on émet ce qu'on avait gardé en réserve — sinon la dernière ligne est perdue.

Mode objet

objectMode: true : les morceaux sont des valeurs JavaScript quelconques au lieu de Buffer. Le seuil compte alors des morceaux, pas des octets.

Reste

La fin de morceau incomplète conservée pour être recollée au morceau suivant. Indispensable dès qu'il existe une notion d'enregistrement.

Accumulateur

Le seul état qu'une agrégation en flux conserve. Sa taille dépend du nombre de clés, pas du nombre de lignes.

readline

Le module node:readline lit un flux ligne par ligne et gère les restes. Inutile d'écrire un découpeur pour ce cas précis.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.