Skip to content

Node.js Aide-mémoire

Runtime JavaScript construit sur le moteur V8 de Chrome pour le développement côté serveur.

01

Premiers pas

REPL et exécution de scripts

Le REPL (Read-Eval-Print Loop) est un shell interactif pour expérimenter du code Node.js. Utilisez node --watch pour un redémarrage automatique en développement. Les ES modules exigent type:module dans package.json ou l'extension .mjs.

nodejs
# start the REPL (interactive shell)
node

# run a script
node app.js

# run with ES modules (type: module in package.json)
node --input-type=module app.js

# execute inline code
node -e "console.log(process.version)"

# watch mode (auto-restart on change)
node --watch app.js

Version et flags du runtime

node --version affiche la version du runtime. --trace-warnings montre les piles d'appels des warnings du runtime. NODE_OPTIONS est une unique variable d'env contenant des flags CLI, pratique dans les conteneurs ou scripts npm. --inspect ouvre le débogueur Chrome DevTools.

nodejs
# check version
node --version    # v20.11.0
node -p "process.versions.v8"

# enable warning stack traces
node --trace-warnings app.js

# pass NODE_OPTIONS (max ~128KB string)
NODE_OPTIONS="--max-old-space-size=4096" node app.js

# inspect memory usage at runtime
node --inspect app.js

package.json et init de projet

npm init crée le package.json. Le champ "type" décide du système de modules par défaut : "module" active la syntaxe ES module dans les .js, "commonjs" (défaut) garde require/module.exports. "main" est le point d'entrée quand le package est requis.

nodejs
# scaffold a project (answer prompts)
npm init

# non-interactive defaults
npm init -y

# "type" controls module system
# "commonjs" (default) -> require/module.exports
# "module"              -> import/export
{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "scripts": { "start": "node index.js" }
}

CommonJS vs ES Modules

Node supporte deux systèmes de modules. CommonJS (require/module.exports) est synchrone et le défaut historique. Les ES Modules (import/export) sont le standard moderne. L'extension de fichier (.mjs/.cjs) ou le champ "type" du package.json décide quel parseur est utilisé pour les .js.

nodejs
# CommonJS (.cjs or type:commonjs) ----
const fs = require('fs');                 // import
module.exports = { greet: () => 'hi' };   // export

# ES Modules (.mjs or type:module) -------
import fs from 'fs';                      // import
export function greet() { return 'hi'; }  // named export
export default { greet };                 // default export

# .mjs is always ESM, .cjs is always CJS
node file.mjs   # forced ESM
node file.cjs   # forced CJS

Objets globaux

Node fournit des globales comme process, console, Buffer et les timers sans import. __dirname et __filename sont réservés au CommonJS — en ES Modules, utilisez import.meta.url à la place. global est l'objet racine (comme window dans les navigateurs).

nodejs
# available everywhere, no import needed
global;        // global namespace object
process;       // env, argv, stdin/stdout
console;       // log, error, warn, table
setTimeout;    // schedule a callback
setInterval;   // schedule repeating callback
Buffer;        // binary data (Uint8Array)
queueMicrotask;// schedule microtask
structuredClone; // deep clone

# CommonJS-only globals (not in ESM)
__dirname;     // current directory
__filename;    // current file path

Scripts exécutables (shebang)

Une ligne shebang (#!/usr/bin/env node) permet à un fichier de tourner comme commande autonome sur Unix. Après chmod +x, lancez ./cli.js directement. Le champ "bin" du package.json mappe un nom de commande à un script, utilisé par les outils CLI publiés sur npm pour que l'installation globale expose la commande.

nodejs
#!/usr/bin/env node
// cli.js - make a file directly runnable
const name = process.argv[2] || 'world';
console.log(`Hello, ${name}!`);

# make it executable (Unix) and run directly
chmod +x cli.js
./cli.js Alice        # Hello, Alice!

# or wire it up in package.json
{
  "bin": { "mycli": "./cli.js" }
}
02

Système de modules

require et exports CommonJS

require() charge synchroniquement un module CommonJS et retourne son module.exports. require résout les chemins relatifs (./, ../), les built-ins (fs) et node_modules. Affectez toujours à module.exports (pas exports) quand vous remplacez tout l'export, car exports n'est qu'un alias de module.exports au départ.

nodejs
// math.js
function add(a, b) { return a + b; }
const PI = 3.14;

// export via module.exports
module.exports = { add, PI };
// or: exports.add = add; exports.PI = PI;

// app.js
const math = require('./math');      // .js optional
console.log(math.add(1, 2));          // 3
console.log(math.PI);                 // 3.14

// destructuring
const { add } = require('./math');
console.log(add(5, 7));               // 12

import/export des ES Modules

Les ES Modules utilisent import/export statiques — les liaisons sont vivantes et hoistées. L'export par défaut s'importe sous n'importe quel nom (sans accolades) ; les exports nommés exigent des accolades avec les noms correspondants. import * as crée un objet namespace. ESM est asynchrone par conception et le standard moderne.

nodejs
// math.mjs (or type:module)
export function add(a, b) { return a + b; }
export const PI = 3.14;
export default function square(x) { return x * x; }

// app.mjs
import square, { add, PI } from './math.mjs';
console.log(add(1, 2));     // 3
console.log(square(5));     // 25

// import all as namespace
import * as math from './math.mjs';
console.log(math.PI);       // 3.14

import() dynamique

import() est un import dynamique et asynchrone utilisable en CJS comme en ESM. Il retourne une Promise résolvant vers le namespace du module, permettant le lazy-loading et les imports conditionnels — idéal pour réduire le temps de démarrage ou charger des fonctionnalités optionnelles. Sert aussi au code-splitting côté serveur.

nodejs
// dynamic import returns a Promise
async function loadPlugin(name) {
  const mod = await import(`./plugins/${name}.mjs`);
  return mod.default;
}

// lazy-load heavy modules on demand
if (needPdf) {
  const { exportPdf } = await import('./pdf.mjs');
  exportPdf(data);
}

// works in both CommonJS and ESM
import('./optional.mjs')
  .then(mod => mod.run())
  .catch(err => console.error('load failed', err));

Modules intégrés

Node embarque des dizaines de modules intégrés — pas besoin de npm install. La plupart exposent des API à callbacks ; beaucoup offrent aussi des variantes promises sous le chemin 'module/promises' (fs/promises, dns/promises, stream/promises). require('module') (sans ./) résout d'abord vers les built-ins, puis node_modules.

nodejs
// core modules - no install, just require/import
const fs = require('fs');            // file system
const path = require('path');        // path handling
const http = require('http');        // HTTP server/client
const os = require('os');            // OS info
const crypto = require('crypto');    // hashing/encryption
const { EventEmitter } = require('events');
const { Buffer } = require('buffer');
const stream = require('stream');    // streams
const net = require('net');          // TCP
const child_process = require('child_process');

// some are promise-based (Node 10+)
const fsp = require('fs/promises');  // async/await fs

Cache des modules et dépendances circulaires

require() cache les modules par chemin résolu, donc le même code de module s'exécute une fois et les exports sont réutilisés. Les dépendances circulaires fonctionnent mais le premier module chargé voit un objet exports incomplet (partiel) du second — concevez en tenant compte de cela. delete require.cache pour le hot-reload en développement.

nodejs
// modules are cached after first load
// a.js
require('./b');                 // b loads, sets module.exports
const b = require('./b');       // returns cached b (same object)
console.log(b === require('./b')); // true

// circular dependency: a -> b -> a
// a.js: const b = require('./b'); b.f();
// b.js: const a = require('./a'); // a is PARTIAL here!
//       module.exports = { f: () => a.x };

// inspect the cache
console.log(require.cache);     // map of loaded modules
delete require.cache[require.resolve('./b')]; // force reload

__dirname et import.meta.url

__dirname et __filename sont des globales propres au CommonJS donnant le chemin du dossier/fichier courant. Les ES Modules n'ont pas de telles globales — dérivez-les d'import.meta.url via fileURLToPath. import.meta.url est l'URL file:// du module courant et le remplaçant ESM de __filename.

nodejs
// CommonJS - synchronous path globals
console.log(__dirname);   // /app/src
console.log(__filename);  // /app/src/index.js

// ES Modules - no __dirname, use import.meta
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const dataPath = join(__dirname, 'data.json');

// import.meta also carries the module URL
console.log(import.meta.url);  // file:///app/src/index.mjs
03

npm et pnpm

npm init et package.json

npm init génère un package.json. -y saute les prompts avec les défauts. npm set stocke la config dans ~/.npmrc pour les futurs inits. Les packages scoped (@org/name) servent aux organisations et évitent les collisions de noms sur le registry.

nodejs
# create package.json interactively
npm init

# accept all defaults
npm init -y

# pnpm equivalent
pnpm init

# set author/license globally
npm set init-author-name "Alice"
npm set init-license MIT

# scope packages with @username
npm init --scope=@myorg

Installer les dépendances

npm install (sans argument) installe toutes les dépendances listées. Avec un nom, il l'ajoute au package.json. --save-dev le met dans devDependencies (outils de test/build, non livrés). ^ autorise les mises à jour minor+patch, ~ patch seulement. -g installe des outils CLI globalement.

nodejs
# install everything in package.json
npm install            # alias: npm i
pnpm install           # alias: pnpm i

# add a runtime dependency -> dependencies
npm install express
pnpm add express

# add a dev-only dependency -> devDependencies
npm install --save-dev jest     # npm i -D jest
pnpm add -D jest

# install a specific version
npm install [email protected]
npm install lodash@^4.17.0      # caret: 4.x
npm install lodash@~4.17.0      # tilde: 4.17.x

# global install (CLI tools)
npm install -g pm2
pnpm add -g pm2

Scripts npm

Les scripts du package.json se lancent via npm run <nom>. start et test sont spéciaux (npm start / npm test). Les hooks pre/post (pretest, postbuild) s'exécutent automatiquement. Utilisez -- pour transmettre des arguments à la commande sous-jacente. pnpm permet d'omettre le mot « run » pour les scripts custom.

nodejs
// package.json
{
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js",
    "test": "jest",
    "build": "tsc && vite build"
  }
}

# run a script
npm run dev          # npm run-script dev
pnpm dev             # pnpm has no "run" requirement

# "start" and "test" have shortcuts
npm start
npm test

# pre/post hooks run automatically
// "pretest": "npm run lint",
// "postbuild": "npm run deploy"

# pass extra args with --
npm run build -- --mode production

npx et pnpm dlx

npx exécute un binaire de package sans installation globale — il télécharge, exécute puis jette. Parfait pour les scaffolders (create-vite) et pour lancer les outils locaux de node_modules/.bin. --yes saute la confirmation d'installation. pnpm dlx est l'équivalent pnpm.

nodejs
# run a one-off command without installing globally
npx create-vite my-app
npx cowsay "hello"

# pin a version
npx prettier@3 --write .

# pnpm equivalent
pnpm dlx create-vite my-app

# execute a local bin from node_modules
npx jest            # runs ./node_modules/.bin/jest

# never prompt, always download latest
npx --yes create-react-app my-app

Versioning et lockfiles

SemVer : MAJOR pour les ruptures, MINOR pour les fonctionnalités, PATCH pour les correctifs. ^ (caret) est le défaut npm et autorise minor+patch ; ~ (tilde) patch seulement. Les lockfiles (package-lock.json) figent tout l'arbre de dépendances pour des installations reproductibles — utilisez npm ci en CI pour la vitesse et la sûreté.

nodejs
# semantic versioning: MAJOR.MINOR.PATCH
# 1.4.2 -> 1:breaking 4:feature 2:fix
"^1.4.2"  # >=1.4.2 <2.0.0  (caret, default)
"~1.4.2"  # >=1.4.2 <1.5.0  (tilde)
"1.4.2"   # exact 1.4.2
">=1.4.0 <2.0.0" # range

# lockfiles pin the installed tree
npm install       # writes/updates package-lock.json
pnpm install      # writes pnpm-lock.yaml
yarn install      # writes yarn.lock

# install exactly as locked (CI)
npm ci            # clean install from lockfile

# find outdated deps
npm outdated
npm update        # update within ^ ranges

Publication et cycle de vie

npm publish téléverse votre package sur le registry. npm version incrémente la version, crée un tag git et committe. Les hooks de cycle de vie (prepublishOnly, postpublish) automatisent build/test à la sortie. L'unpublish n'est permis que pendant 72 heures — préférez npm deprecate pour les vieilles versions.

nodejs
# login once
npm login

# publish to the registry
npm publish
npm publish --access public   # scoped default restricted

# bump version (updates package.json + tag + commit)
npm version patch   # 1.0.0 -> 1.0.1
npm version minor   # 1.0.0 -> 1.1.0
npm version major   # 1.0.0 -> 2.0.0

# lifecycle scripts (in package.json)
// "prepublishOnly": "npm test && npm run build",
// "prepublish": "npm run build",
// "postpublish": "git push --tags"

# unpublish within 72h
npm unpublish [email protected]
04

Système de fichiers (fs)

Lire des fichiers

fs offre des API sync (readFileSync), callback (readFile) et promise (readFile de fs/promises). Les appels sync bloquent la boucle d'événements — à éviter dans les serveurs. fs/promises est le choix moderne pour async/await. Sans encodage, readFile retourne un Buffer.

nodejs
const fs = require('fs');

// synchronous (blocks the event loop)
const text = fs.readFileSync('data.txt', 'utf8');
const buf = fs.readFileSync('image.png');  // Buffer

// asynchronous with callback (error-first)
fs.readFile('data.txt', 'utf8', (err, data) => {
  if (err) return console.error(err);
  console.log(data);
});

// async with fs/promises (preferred)
const fsp = require('fs/promises');
async function read() {
  const text = await fsp.readFile('data.txt', 'utf8');
  return text;
}

Écrire des fichiers

writeFile remplace tout le fichier par défaut. L'option flag change le comportement : 'a' ajoute, 'wx' échoue (EEXIST) si le fichier existe déjà — utile pour une création atomique. Le JSON doit être stringifié avant écriture. Les écritures sync bloquent ; préférez fs/promises.

nodejs
const fs = require('fs');
const fsp = require('fs/promises');

// sync
fs.writeFileSync('out.txt', 'hello');

// async callback
fs.writeFile('log.txt', 'line1\n', err => {
  if (err) throw err;
});

// promise
await fsp.writeFile('config.json', JSON.stringify(cfg, null, 2));

// flags: 'w' write (default), 'a' append, 'wx' fail if exists
await fsp.writeFile('new.txt', 'x', { flag: 'wx' }); // throws if exists

Répertoires

mkdir avec { recursive: true } imite mkdir -p. readdir liste les entrées ; { withFileTypes: true } retourne des objets Dirent dont isDirectory()/isFile() évitent des appels stat supplémentaires. fsp.rm avec recursive+force remplace rmdir pour les répertoires non vides (Node 14+).

nodejs
const fsp = require('fs/promises');

// create (recursive like mkdir -p)
await fsp.mkdir('a/b/c', { recursive: true });

// list entries
const entries = await fsp.readdir('.');
// ['app.js', 'data', 'package.json']

// list with type info
const detailed = await fsp.readdir('.', { withFileTypes: true });
detailed.forEach(e => console.log(e.name, e.isDirectory()));

// remove
await fsp.rmdir('empty');             // empty dir only
await fsp.rm('folder', { recursive: true, force: true }); // rm -rf

// sync versions exist too: mkdirSync, readdirSync, rmSync

Stats et métadonnées de fichiers

stat() retourne un objet Stats avec size, mtime et des helpers de type. N'utilisez pas fs.exists (déprécié) ; utilisez access() dans un try/catch pour des vérifications d'existence sans course — même si ouvrir le fichier directement est plus sûr. fsWatch émet des événements de changement mais peut être incohérent entre plateformes.

nodejs
const fsp = require('fs/promises');

const stats = await fsp.stat('data.txt');
stats.isFile();          // true
stats.isDirectory();     // false
stats.size;              // bytes
stats.mtime;             // Date modified
stats.birthtime;         // Date created
stats.mode;              // permission bits

// check existence (avoid existsSync for races)
try {
  await fsp.access('config.json');
  console.log('exists');
} catch {
  console.log('missing');
}

// watch for changes
const watcher = fs.watch('.');
watcher.on('change', (eventType, filename) => {});

API fs.promises

fs/promises (Node 10+) fournit des versions promise de toutes les méthodes fs, idéal pour async/await. opendir() retourne un itérateur async pour un parcours de répertoire économe en mémoire. Combinez avec path.join pour des chemins portables. Toutes les méthodes lèvent en erreur — enveloppez dans try/catch.

nodejs
const fsp = require('fs/promises');
const path = require('path');

// full async/await file operations
async function loadConfig() {
  const file = path.join(__dirname, 'config.json');
  const raw = await fsp.readFile(file, 'utf8');
  return JSON.parse(raw);
}

async function saveConfig(cfg) {
  const file = path.join(__dirname, 'config.json');
  await fsp.writeFile(file, JSON.stringify(cfg, null, 2));
}

// iterate directory tree
for await (const entry of await fsp.opendir('.')) {
  console.log(entry.name);
}

Append, rename, delete

appendFile ajoute du contenu à la fin (crée le fichier s'il manque). rename est atomique sur le même filesystem et sert au déplacement de fichiers. unlink supprime un fichier. copyFile copie le contenu ; fsp.cp (Node 16+) gère les répertoires récursivement. truncate redimensionne un fichier à la longueur donnée.

nodejs
const fsp = require('fs/promises');

// append to a file (creates if missing)
await fsp.appendFile('log.txt', new Date() + ' started\n');

// atomic rename (also for moving)
await fsp.rename('old.txt', 'new.txt');
// move across dirs
await fsp.rename('a/x.txt', 'b/x.txt');

// delete a file
await fsp.unlink('temp.txt');

// copy
await fsp.copyFile('src.txt', 'dest.txt');
// or fsp.cp('src', 'dest', { recursive: true })

// truncate to a length
await fsp.truncate('data.bin', 1024);
05

Gestion des chemins (path)

path.join et path.resolve

path.join concatène des segments avec le séparateur de la plateforme et normalise le résultat. path.resolve produit un chemin absolu à partir de process.cwd() ; un segment absolu annule les segments précédents. Utilisez toujours path.join plutôt que la concaténation de chaînes pour que les chemins marchent sur Windows et POSIX.

nodejs
const path = require('path');

// join segments with the OS separator
path.join('src', 'utils', 'file.js');
// 'src/utils/file.js' (Linux)  or 'src\utils\file.js' (Windows)

// resolve to an ABSOLUTE path (from cwd)
path.resolve('src', 'file.js');
// '/current/dir/src/file.js'

// resolve with absolute segment resets
path.resolve('/a', 'b', '/c', 'd');   // '/c/d'

// normalize '..' and '.' segments
path.normalize('a/b/../c/./d');        // 'a/c/d'

// never hardcode '/' — use path.join for portability

dirname, basename, extname

dirname retourne le répertoire, basename le nom de fichier (en rognant optionnellement une extension), et extname la dernière extension (point inclus). Pour des extensions multiples comme .tar.gz, seul le .gz final est retourné. Ce sont des opérations pures de chaînes — aucun accès filesystem.

nodejs
const path = require('path');
const file = '/app/src/utils/helper.js';

path.dirname(file);    // '/app/src/utils'
path.basename(file);   // 'helper.js'
path.basename(file, '.js'); // 'helper' (strip ext)
path.extname(file);    // '.js'
path.extname('archive.tar.gz'); // '.gz' (last ext)

// for the current file (CommonJS)
path.dirname(__filename);  // current dir
path.basename(__filename); // current file name

path.parse et format

path.parse découpe un chemin en root, dir, base, name et ext. path.format les réassemble. path.relative calcule le chemin relatif nécessaire pour aller d'un répertoire à un autre. Ensemble, ils rendent la manipulation de chemins déclarative plutôt qu'un découpage de chaînes laborieux.

nodejs
const path = require('path');

// decompose a path into parts
const p = path.parse('/app/src/helper.test.js');
// { root: '/', dir: '/app/src',
//   base: 'helper.test.js', name: 'helper.test', ext: '.js' }

// rebuild from a parsed object
const rebuilt = path.format({
  dir: '/app/dist',
  name: 'bundle',
  ext: '.min.js'
});
// '/app/dist/bundle.min.js'

// get the relative path from A to B
path.relative('/a/b/c', '/a/x');   // '../../x'

Chemins multiplateformes

path.sep et path.delimiter diffèrent selon l'OS. path.win32 et path.posix forcent un parseur précis quel que soit l'OS hôte — pratique pour traiter des chemins venant d'une autre plateforme. Utilisez path.delimiter pour découper des variables d'env style PATH de façon portable au lieu de coder ':' ou ';' en dur.

nodejs
const path = require('path');

// platform-specific values
path.sep;           // '/' (POSIX) or '\\' (Windows)
path.delimiter;     // ':' (POSIX) or ';' (Windows)

// force a specific platform's behavior
path.win32.join('a', 'b');   // 'a\\b'
path.posix.join('a', 'b');   // 'a/b'

// parse PATH env var portably
process.env.PATH.split(path.delimiter).forEach(dir => {
  console.log(dir);
});

// check if absolute
path.isAbsolute('/etc');     // true
path.isAbsolute('a/b');      // false
path.win32.isAbsolute('C:\\'); // true

URLs de fichiers et pathToFileURL

Les ES Modules s'identifient par des URLs file://. Utilisez url.pathToFileURL pour transformer un chemin normal en URL pour un import() dynamique, et url.fileURLToPath dans l'autre sens. En ESM, import.meta.url est déjà une URL de fichier — convertissez-la en chemin avec fileURLToPath pour reproduire __filename.

nodejs
const path = require('path');
const url = require('url');

// convert a path to a file:// URL (ESM import)
const fileUrl = url.pathToFileURL('/app/src/mod.mjs');
// URL { href: 'file:///app/src/mod.mjs' }

// and back
const p = url.fileURLToPath('file:///app/src/mod.mjs');
// '/app/src/mod.mjs'

// in ESM, import.meta.url is already a file URL
// convert to a normal path:
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
06

Serveur HTTP

Serveur HTTP simple

http.createServer retourne un serveur ; le callback traite chaque requête. res.writeHead règle le code de statut et les en-têtes, res.end envoie le corps et clôt la réponse. listen() commence à accepter les connexions sur le port donné. Un processus Node gère beaucoup de requêtes concurrentes via la boucle d'événements.

nodejs
const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello, World!\n');
});

// listen on a port
server.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

// or with a host and backlog
server.listen(3000, '127.0.0.1', 511, () => {});

Requête et réponse

req expose method, url et headers ; res permet de régler statusCode/headers puis write+end. res.end DOIT être appelé pour terminer la réponse. Pour les gros payloads, streamez via res.write ou pipez un Readable dans res pour éviter de tout bufferiser en mémoire.

nodejs
const http = require('http');

http.createServer((req, res) => {
  // request info
  console.log(req.method);   // 'GET'
  console.log(req.url);      // '/users?id=5'
  console.log(req.headers);  // { host, 'user-agent', ... }

  // response helpers
  res.statusCode = 200;
  res.setHeader('Content-Type', 'application/json');
  res.write('partial chunk\n');
  res.end(JSON.stringify({ ok: true }));
}).listen(3000);

// streaming a large response
res.writeHead(200);
readStream.pipe(res);   // pipe file -> response

Routage et parsing d'URL

Node n'a pas de routeur intégré — implémentez-en un avec if/else sur req.method et req.url, ou utilisez le constructeur URL pour parser pathname et searchParams. Pour de vraies apps, passez à Express ou au routeur d'un framework. Le constructeur URL exige une base pour parser un req.url relatif.

nodejs
const http = require('http');
const { URL } = require('url');

http.createServer((req, res) => {
  const url = new URL(req.url, 'http://localhost');
  const path = url.pathname;
  const q = url.searchParams.get('id');

  if (req.method === 'GET' && path === '/') {
    res.end('home');
  } else if (path === '/users') {
    res.end('users');
  } else {
    res.writeHead(404);
    res.end('not found');
  }
}).listen(3000);

Gérer JSON et corps POST

Les corps de requête arrivent en flux — il faut collecter les chunks avant de parser. Le motif d'itération async (for await of req) est l'approche moderne. Réglez toujours Content-Type: application/json quand vous répondez du JSON. En production, plafonnez la taille du corps pour éviter l'épuisement mémoire.

nodejs
const http = require('http');

http.createServer(async (req, res) => {
  if (req.method === 'POST') {
    // collect the streamed body
    const chunks = [];
    for await (const chunk of req) chunks.push(chunk);
    const body = JSON.parse(Buffer.concat(chunks).toString());

    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ received: body }));
  }
}).listen(3000);

// test: curl -X POST localhost:3000 -d '{"a":1}'

Événements et erreurs du serveur

Le serveur est un EventEmitter. 'error' doit être traité — EADDRINUSE signifie que le port est occupé. 'connection' se déclenche par socket client. Pour un arrêt propre, écoutez SIGTERM/SIGINT et appelez server.close() pour que les requêtes en vol se terminent avant que le processus ne quitte.

nodejs
const server = http.createServer(handler);

server.on('listening', () => console.log('ready'));
server.on('connection', socket => console.log('client connected'));
server.on('error', err => {
  if (err.code === 'EADDRINUSE') {
    console.error('port 3000 already in use');
  }
});
server.on('close', () => console.log('server closed'));

// graceful shutdown
process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
});

server.listen(3000);

HTTPS et client HTTP

https.createServer exige une clé privée et un certificat (ex. de Let's Encrypt). Pour les requêtes sortantes, Node 18+ embarque un fetch() global — préférez-le à l'API brute http.get à callbacks. fetch est basé promise et supporte async/await, en-têtes et streams.

nodejs
// HTTPS server (needs TLS certs)
const https = require('https');
const fs = require('fs');

https.createServer({
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem')
}, handler).listen(443);

// HTTP client: simple GET
http.get('http://example.com', res => {
  let data = '';
  res.on('data', c => data += c);
  res.on('end', () => console.log(data));
});

// modern fetch (Node 18+, global, promise-based)
const res = await fetch('https://api.example.com');
const json = await res.json();
07

Bases d'Express

Mise en place Express et Hello World

Express est le framework web Node le plus populaire. app.get enregistre un handler de route ; res.send envoie une réponse (Content-Type auto-détecté). app.listen démarre le serveur. Express enveloppe le module http de Node avec routage, middleware et helpers pratiques.

nodejs
// install: npm install express
import express from 'express';

const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
  res.send('Hello, World!');
});

app.listen(PORT, () => {
  console.log(`Server on http://localhost:${PORT}`);
});

Routage et paramètres de route

Express matche les méthodes HTTP (get/post/put/delete) aux chemins. :id capture les segments d'URL dans req.params ; req.query contient les valeurs de query string. app.route permet d'enchaîner plusieurs méthodes pour le même chemin. Les routes matchent dans l'ordre d'enregistrement, donc définissez les routes spécifiques avant les génériques.

nodejs
app.get('/users', (req, res) => res.send('list users'));
app.post('/users', (req, res) => res.send('create user'));

// URL parameters
app.get('/users/:id', (req, res) => {
  res.send(`user ${req.params.id}`);
});

// query strings: /search?q=node
app.get('/search', (req, res) => {
  res.send(`searching: ${req.query.q}`);
});

// chain handlers for one path
app.route('/book')
  .get((req, res) => res.send('get book'))
  .post((req, res) => res.send('add book'));

Middleware

Les middleware sont des fonctions exécutées pendant le cycle de requête, recevant req, res et next. Appelez next() pour continuer vers le handler suivant. app.use monte un middleware globalement ou sur un préfixe de chemin. Le middleware de gestion d'erreurs a 4 arguments (err en premier) et doit être enregistré en dernier.

nodejs
// middleware: (req, res, next) => {}
app.use(express.json());          // parse JSON bodies
app.use(express.static('public'));// serve static files
app.use((req, res, next) => {     // custom logger
  console.log(req.method, req.url);
  next();                         // pass control forward
});

// mounted on a path
app.use('/api', (req, res, next) => {
  req.apiCall = true;
  next();
});

// error-handling middleware (4 args)
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Server Error');
});

Données de requête

Express ne parse les corps que si vous montez le bon middleware : express.json() pour le JSON, express.urlencoded() pour les formulaires, multer pour les uploads. req.params (segments d'URL), req.query (query string) et req.body (payload parsé) sont les trois sources principales de données de requête.

nodejs
// JSON body (needs express.json() middleware)
app.post('/api', (req, res) => {
  console.log(req.body);          // parsed JSON object
});

// URL params and query
app.get('/u/:id', (req, res) => {
  const { id } = req.params;
  const { tab } = req.query;
});

// form data (urlencoded)
app.use(express.urlencoded({ extended: true }));
app.post('/form', (req, res) => res.json(req.body));

// file uploads: use multer middleware
// const upload = multer({ dest: 'uploads/' });
// app.post('/upload', upload.single('file'), handler);

// headers & cookies
req.headers['user-agent'];
req.cookies;        // needs cookie-parser

Servir des fichiers statiques

express.static sert des fichiers depuis un répertoire. Montez-le plusieurs fois pour un comportement de fallback, ou préfixez-le d'un chemin. Des options comme maxAge règlent les en-têtes de cache. Il détecte les types MIME et supporte les requêtes par plage pour la vidéo/audio. Utilisez toujours des chemins absolus pour éviter les bugs dépendant du cwd.

nodejs
const path = require('path');

// serve files from /public at /
app.use(express.static('public'));
// GET /style.css -> public/style.css

// mount at a prefix
app.use('/static', express.static('public'));
// GET /static/style.css -> public/style.css

// multiple directories (fallthrough)
app.use(express.static('public'));
app.use(express.static('uploads'));

// absolute path + options
app.use(express.static(path.join(__dirname, 'public'), {
  maxAge: '1d',
  setHeaders: (res, filePath) => {
    if (filePath.endsWith('.html')) res.setHeader('Cache-Control', 'no-cache');
  }
}));

Gestion d'erreurs et Router

Passez une erreur à next(err) ou throwez dans un handler async pour déclencher le middleware d'erreurs. Enregistrez un handler central à 4 arguments en dernier. express.Router() modularise les routes dans des fichiers séparés — montez-les avec app.use('/prefixe', router) pour composer proprement une grande API.

nodejs
// throw to jump to error middleware
app.get('/broken', (req, res, next) => {
  const err = new Error('boom');
  err.status = 400;
  next(err);              // or throw err (Express 4+)
});

// centralized error handler (last middleware)
app.use((err, req, res, next) => {
  const status = err.status || 500;
  res.status(status).json({ error: err.message });
});

// modular routing with express.Router()
const router = express.Router();
router.get('/', (req, res) => res.send('api root'));
router.get('/users', (req, res) => res.send('users'));
app.use('/api', router);  // mount at /api
08

Streams

Streams lisibles (Readable)

Un Readable stream produit des données. En mode flowing, les événements 'data' poussent les chunks automatiquement ; en mode paused, on appelle read() explicitement. Traitez toujours 'error' — les événements d'erreur non gérés crashent le processus. highWaterMark contrôle la taille du buffer interne.

nodejs
const fs = require('fs');

// create a readable stream from a file
const rs = fs.createReadStream('big.log', { highWaterMark: 64 * 1024 });

// 'data' mode (flowing)
rs.on('data', chunk => {
  console.log('got', chunk.length, 'bytes');
});
rs.on('end', () => console.log('done'));
rs.on('error', err => console.error(err));

// paused mode: pull on demand
rs.on('readable', () => {
  let chunk;
  while ((chunk = rs.read()) !== null) {
    process(chunk);
  }
});

Streams inscriptibles (Writable)

Un Writable stream consomme des données. write() retourne false quand le buffer interne est plein — attendez l'événement 'drain' avant d'écrire davantage pour respecter la backpressure. end() signale la fin des données ; 'finish' se déclenche après que tout a été flushé. process.stdout est lui-même un writable stream.

nodejs
const fs = require('fs');
const ws = fs.createWriteStream('out.log');

// write returns false when the buffer is full (backpressure)
const ok = ws.write('line\n');
if (!ok) ws.once('drain', () => writeMore());

// signals completion
ws.end('final line\n');
ws.on('finish', () => console.log('all data flushed'));
ws.on('error', err => console.error(err));

// process.stdout is a writable stream
process.stdout.write('hello');

pipe et pipeline

pipe() transmet un Readable à un Writable avec backpressure automatique. stream.pipeline (préférez la version promises) enchaîne plusieurs streams ET propage correctement les erreurs et nettoie — .pipe() seul fuit des ressources en cas d'erreur en cours de flux. Préférez toujours pipeline aux chaînes .pipe() manuelles.

nodejs
const fs = require('fs');
const { pipeline } = require('stream/promises');

// pipe: readable -> writable (auto backpressure)
fs.createReadStream('in.txt')
  .pipe(fs.createWriteStream('out.txt'));

// pipeline: chain transforms, with error handling
const { Transform } = require('stream');
const upper = new Transform({
  transform(chunk, enc, cb) { cb(null, chunk.toString().toUpperCase()); }
});

await pipeline(
  fs.createReadStream('in.txt'),
  upper,
  fs.createWriteStream('out.txt')
);
// pipeline rejects on error, unlike .pipe()

Transform streams

Un Transform stream lit l'entrée, la traite et émet une sortie transformée — parfait pour parser, compresser ou chiffrer dans un pipeline. Implémentez transform(chunk, enc, cb) et optionnellement flush(cb). objectMode permet de pousser des objets plutôt que des Buffers. zlib et crypto fournissent des transforms prêts à l'emploi.

nodejs
const { Transform } = require('stream');

// a Transform is both Readable and Writable
const csvToJson = new Transform({
  objectMode: false,
  transform(chunk, encoding, callback) {
    // convert each chunk
    const lines = chunk.toString().trim().split('\n');
    const json = lines.map(l => JSON.stringify(l.split(','))).join('\n');
    callback(null, json + '\n');
  },
  flush(callback) {
    callback(null, ']\n'); // finalize
  }
});

process.stdin.pipe(csvToJson).pipe(process.stdout);

// built-in transforms: zlib, crypto streams
const { createGzip } = require('zlib');
fs.createReadStream('log').pipe(createGzip()).pipe(fs.createWriteStream('log.gz'));

Modes de stream et backpressure

Les streams alternent entre modes flowing et paused via pause()/resume(). La backpressure signifie qu'un consommateur lent signale au producteur de ralentir — l'itération async (for await) gère cela automatiquement en attendant chaque chunk, le motif moderne le plus propre. Réglez toujours un encodage pour recevoir des chaînes plutôt que des Buffers.

nodejs
const rs = fs.createReadStream('huge.bin');

// switch between modes
rs.pause();
rs.resume();
rs.setEncoding('utf8');

// respect backpressure manually
function writeChunk(ws, data) {
  if (!ws.write(data)) {
    rs.pause();
    ws.once('drain', () => rs.resume());
  }
}

// async iteration (Node 10+) — cleanest pattern
async function consume() {
  for await (const chunk of rs) {
    await handle(chunk);  // naturally respects backpressure
  }
}
consume();

Streams personnalisés

Sous-classez Readable/Writable/Duplex et implémentez _read/_write, ou utilisez le plus simple Readable.from() pour des données déjà en main. push(null) signale la fin du stream. Les streams Duplex sont lisibles ET inscriptibles indépendamment (comme les sockets TCP) ; Transform est un Duplex dont la sortie dérive de l'entrée.

nodejs
const { Readable, Writable, Duplex } = require('stream');

// custom Readable: generate a counter
const counter = new Readable({
  read() {
    if (++this._n > 10) this.push(null);  // end
    else this.push(String(this._n));
  }
});
counter._n = 0;
counter.pipe(process.stdout);

// from an array / async iterable
Readable.from(['a', 'b', 'c']).pipe(process.stdout);

// a Duplex: both readable and writable (e.g. a socket)
class Echo extends Duplex {
  _read() {}
  _write(chunk, enc, cb) { this.push(chunk); cb(); }
}
09

Buffer

Créer des buffers

Buffer.alloc crée un buffer rempli de zéros (sûr). Buffer.allocUnsafe saute la mise à zéro pour la vitesse mais peut fuiter de la vieille mémoire — ne l'utilisez que si vous écrasez chaque octet. Buffer.from convertit chaînes/tableaux/buffers. Le vieux constructeur 'new Buffer()' est déprécié pour des raisons de sécurité.

nodejs
// allocate zeroed bytes (SAFE)
const b1 = Buffer.alloc(8);            // <Buffer 00 00 00 00 00 00 00 00>

// allocate WITHOUT zeroing (faster, may contain old memory)
const b2 = Buffer.allocUnsafe(8);      // random old data!

// from a string with encoding
const b3 = Buffer.from('hello', 'utf8');
// <Buffer 68 65 6c 6c 6f>

// from an array of bytes
const b4 = Buffer.from([0x48, 0x49]);  // 'HI'

// from another buffer (copy)
const b5 = Buffer.from(b3);

// NEVER use new Buffer() — deprecated and unsafe

Lecture et écriture

Les buffers contiennent des octets bruts. Utilisez les méthodes read/write avec tailles explicites (UInt8/16/32) et boutisme (BE/LE). Le big-endian est l'ordre réseau ; le little-endian est courant sur x86. toString(encoding, start, end) décode des octets en chaîne. Passez toujours un offset pour éviter d'écraser des octets antérieurs.

nodejs
const buf = Buffer.alloc(8);

// write numeric values at an offset
buf.writeUInt8(255, 0);       // 1 byte
buf.writeUInt16BE(0x1234, 1); // 2 bytes, big-endian
buf.writeInt32LE(1000, 3);    // 4 bytes, little-endian

// read them back
buf.readUInt8(0);             // 255
buf.readUInt16BE(1);          // 0x1234
buf.readInt32LE(3);           // 1000

// string read/write
buf.write('Hi', 0, 'utf8');
buf.toString('utf8', 0, 2);   // 'Hi'

Concat et comparaison

Buffer.concat joint un tableau de buffers (un indice de longueur totale optionnel améliore la performance). equals/compare permettent de comparer des séquences d'octets ; indexOf/includes trouvent des sous-buffers — utile dans les protocoles binaires. copy(target, targetStart, sourceStart, sourceEnd) copie une tranche dans un autre buffer.

nodejs
const a = Buffer.from('foo');
const b = Buffer.from('bar');

// concatenate buffers
const c = Buffer.concat([a, b]);   // 'foobar'
Buffer.concat([a, b], 6);          // total length hint

// compare
Buffer.compare(a, b);        // -1 (a < b), 0, or 1
a.equals(b);                  // false

// find a sub-buffer
const big = Buffer.from('hello world');
big.indexOf(Buffer.from('world'));   // 6
big.includes(Buffer.from('hello'));  // true

// copy bytes
const target = Buffer.alloc(5);
big.copy(target, 0, 0, 5);   // copy first 5 bytes

Encodages

Les encodages font le pont entre chaînes et octets. utf8 est le défaut pour le texte. base64/hex sont courants pour le binaire-dans-le-texte (data URLs, hashs, transport). Buffer.byteLength donne la taille en octets (un caractère multi-octets compte plus d'un octet en utf8) — utilisez-la pour dimensionner les buffers, pas string.length.

nodejs
const text = 'Hello, 世界';

// string -> buffer (encode)
const utf8 = Buffer.from(text, 'utf8');
const base64 = Buffer.from(text).toString('base64');
const hex = Buffer.from(text).toString('hex');
const latin1 = Buffer.from(text, 'latin1');

// buffer -> string (decode)
utf8.toString('utf8');     // 'Hello, 世界'
Buffer.from(base64, 'base64').toString('utf8');
Buffer.from(hex, 'hex').toString('utf8');

// common encodings: utf8, utf16le, latin1, ascii,
//   base64, base64url, hex
Buffer.byteLength('世界', 'utf8');  // 6 bytes (not 2)

Buffer et TypedArrays

Buffer étend Uint8Array, donc il fonctionne partout où les TypedArrays le font. Buffer.from(arrayBuffer) partage la mémoire (pas de copie) — mais un Buffer peut découper un ArrayBuffer poolé plus grand, donc respectez toujours byteOffset/byteLength en créant des vues. Cela permet de mêler API Buffer et DataView pour un accès numérique fin.

nodejs
// Buffer is a subclass of Uint8Array
const buf = Buffer.from([1, 2, 3]);
buf instanceof Uint8Array;  // true

// share memory with TypedArrays without copying
const u8 = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
view.getInt32(0);

// Buffer from an ArrayBuffer
const ab = new ArrayBuffer(8);
const buf2 = Buffer.from(ab);

// note: a Buffer's underlying buffer may be larger
// (allocUnsafe pools) -> always use byteOffset

Slice, fill, swap

subarray (ou slice) retourne une vue partageant la mémoire d'origine — les mutations affectent les deux. fill écrit un octet ou une chaîne répétée sur tout le buffer. swap16/swap32 inversent l'ordre des octets en place pour une conversion de boutisme. Les buffers sont itérables, produisant chaque valeur d'octet 0–255.

nodejs
const buf = Buffer.from('abcdef');

// slice shares memory (no copy) — like subarray
const s = buf.subarray(1, 4);   // 'bcd'
s[0] = 88;                      // mutates buf too -> 'aXcdef'

// fill with a value or pattern
Buffer.alloc(4).fill(0xff);            // <Buffer ff ff ff ff>
Buffer.alloc(6).fill('ab');            // 'ababab'

// reverse byte order in place (for endianness swaps)
const n = Buffer.from([0x01, 0x02, 0x03, 0x04]);
n.swap16();  // swaps pairs: <Buffer 02 01 04 03>

// iterate with for...of
for (const byte of buf) console.log(byte);  // 97, 98, ...
10

EventEmitter

Créer et émettre des événements

EventEmitter est le cœur pub/sub de Node. emit(eventName, ...args) déclenche un événement ; on() s'abonne. Beaucoup de classes intégrées (streams, serveur http) l'étendent. Les noms d'événements sont des chaînes arbitraires, mais 'error' est spécial. Les listeners s'appellent synchronément dans l'ordre d'enregistrement.

nodejs
const { EventEmitter } = require('events');

class Clock extends EventEmitter {
  start() {
    this.emit('start', Date.now());          // emit with args
    setInterval(() => this.emit('tick', new Date()), 1000);
  }
}

const clock = new Clock();
clock.on('tick', date => console.log('tick', date));
clock.on('start', ts => console.log('started at', ts));
clock.start();

// on() == addListener; once() fires only once

once et removeListener

once() enregistre un listener qui se retire automatiquement après déclenchement — parfait pour un setup unique. Pour retirer un listener, il faut garder une référence à la fonction exacte (les fonctions fléchées créent une nouvelle référence à chaque fois). removeAllListeners nettoie les listeners d'un ou de tous les événements. off est un alias de removeListener.

nodejs
const ee = new EventEmitter();

// once: auto-removed after first fire
ee.once('init', () => console.log('init fired'));

// remove a specific listener (need the same function ref)
const handler = () => console.log('hi');
ee.on('msg', handler);
ee.off('msg', handler);          // off() == removeListener

// remove all listeners for an event (or all events)
ee.removeAllListeners('msg');
ee.removeAllListeners();         // everything

// inspect
ee.listenerCount('msg');
ee.eventNames();                 // ['msg', 'init']

Événements d'erreur

Si un événement 'error' est émis sans AUCUN listener enregistré, Node throwe et crash le processus. Attachez toujours un handler d'erreur aux EventEmitters — surtout streams et serveurs HTTP. captureRejections (Node 12+) route les promises rejetées des listeners async vers l'événement 'error'.

nodejs
const ee = new EventEmitter();

// 'error' is special: if unhandled, it CRASHES the process
ee.on('error', err => {
  console.error('caught:', err.message);
});

// later, emit an error safely
ee.emit('error', new Error('something broke'));

// guard against crashes from unhandled errors
// (monitor with the static capture)
EventEmitter.captureRejections = true; // for async handlers

// always register an error listener on streams/http

Listeners asynchrones

EventEmitter appelle les listeners synchronement, donc la promise d'un listener async n'est pas attendue — emit() retourne avant qu'elle ne se résolve. Utilisez once(ee, name) pour attendre un événement unique comme promise. Activez captureRejections pour qu'un listener async rejeté déclenche l'événement 'error' au lieu d'être silencieusement perdu.

nodejs
const ee = new EventEmitter();

// listeners run synchronously; await doesn't pause the chain
ee.on('save', async () => {
  await fs.promises.writeFile('x', 'y');
  console.log('saved');
});
ee.emit('save');  // returns before the await finishes

// wait for async listeners in sequence
const { once } = require('events');
async function waitForReady() {
  await once(ee, 'ready');   // promise resolves on first 'ready'
  console.log('now ready');
}

// handle async errors properly
EventEmitter.captureRejections = true;
ee.on('job', async () => { throw new Error('boom'); });
ee.on('error', err => console.error(err));

Nommage d'événements et newListener

newListener et removeListener sont des événements spéciaux émis quand des listeners s'ajoutent/retirent — utiles pour des hooks ou du profiling. setMaxListeners relève le seuil de détection de fuite (défaut 10) ; l'avertissement signifie généralement que vous avez oublié de nettoyer les listeners. Utilisez des Symbols ou constantes pour les noms d'événements pour prévenir les typos.

nodejs
const ee = new EventEmitter();

// special events fired by EventEmitter itself
ee.on('newListener', (event, listener) => {
  console.log('listener added for', event);
});
ee.on('removeListener', (event, listener) => {
  console.log('listener removed for', event);
});

// limit listener count to catch leaks
ee.setMaxListeners(20);
ee.getMaxListeners();          // 20
// MaxListenersExceededWarning fires if exceeded

// convention: camelCase event names, 'error' reserved
// prefer symbols/const strings to avoid typos
const READY = Symbol('ready');
ee.emit(READY);
11

Processus enfants

exec (shell, bufferisé)

exec() lance une commande via un shell et bufferise stdout/stderr — le mieux pour des commandes courtes dont on veut toute la sortie d'un coup. Il spawn un shell, donc il expand les globs et les pipes. N'interpolez JAMAIS une saisie utilisateur dans la chaîne de commande — c'est une vulnérabilité d'injection de commande ; utilisez spawn avec un tableau d'args.

nodejs
const { exec } = require('child_process');

// runs a command in a shell, buffers all output
exec('ls -la', (err, stdout, stderr) => {
  if (err) { console.error('failed:', err); return; }
  console.log(stdout);    // full stdout as a string
  console.error(stderr);
});

// promisified (Node 12+)
const { promisify } = require('util');
const execP = promisify(exec);
const { stdout } = await execP('git rev-parse HEAD');

// WARNING: shell interpolation = injection risk!
// NEVER: exec(`rm ${userInput}`)

spawn (streaming, sans shell)

spawn() lance un processus avec un tableau d'args (pas de shell) et streame stdout/stderr — sûr et économe en mémoire pour des sorties volumineuses ou longues. Comme les args passent directement (pas via un shell), pas d'expansion de glob ni de risque d'injection. Pipez les streams enfants vers d'autres streams pour des pipelines.

nodejs
const { spawn } = require('child_process');

// no shell by default -> safe, stream-based
const child = spawn('ls', ['-la', '/tmp']);

child.stdout.on('data', chunk => process.stdout.write(chunk));
child.stderr.on('data', chunk => process.stderr.write(chunk));
child.on('close', code => console.log('exit code', code));
child.on('error', err => console.error('failed to spawn', err));

// pipe streams directly
const gzip = spawn('gzip');
process.stdin.pipe(gzip.stdin);
gzip.stdout.pipe(process.stdout);

execFile et fork

execFile exécute un binaire sans shell — plus sûr que exec pour lancer un binaire connu avec args. fork() spawn un processus Node et ouvre un canal IPC intégré (send/on('message')), le socle du passage de messages à la cluster et worker_threads entre processus Node.

nodejs
const { execFile, fork } = require('child_process');

// execFile: like exec but no shell (safer, slight overhead saving)
execFile('node', ['--version'], (err, stdout) => {
  console.log(stdout.trim());   // v20.x.x
});

// fork: spawn another Node process with an IPC channel
const worker = fork('./worker.js');
worker.send({ task: 'compute', n: 100 });
worker.on('message', msg => console.log('result:', msg));
worker.on('exit', code => console.log('worker exited', code));

// in worker.js:
// process.on('message', msg => { process.send(result); });

stdio et arguments

stdio contrôle les streams standards de l'enfant : 'inherit' partage le terminal du parent (parfait pour les scripts npm), 'ignore' jette, 'pipe' capture. detached + unref() spawn un processus d'arrière-plan qui survit au parent. Passez les arguments en tableau — spawn les quotte pour vous, donc espaces et caractères spéciaux sont sûrs.

nodejs
const { spawn } = require('child_process');

// control stdio: 'pipe' (default), 'inherit', 'ignore', or fd
const child = spawn('npm', ['test'], {
  stdio: 'inherit'     // child uses parent's stdin/stdout/stderr
});

// per-stream: [stdin, stdout, stderr]
spawn('cat', [], { stdio: ['pipe', process.stdout, 'ignore'] });

// set env, cwd, and detached background process
const bg = spawn('node', ['server.js'], {
  cwd: '/app',
  env: { ...process.env, NODE_ENV: 'production' },
  detached: true          // runs independently of parent
});
bg.unref();               // let parent exit without waiting

// pass arguments safely as array (no shell parsing)
spawn('echo', ['hello world']);  // one arg, no quotes needed

Codes de sortie et signaux

L'événement 'exit' rapporte code (null si tué par un signal) et signal (null pour une sortie normale). 'close' se déclenche après fermeture de tous les streams stdio — utilisez-le quand vous avez pipé la sortie et devez savoir que les streams sont flushés. kill() envoie un signal ; SIGTERM est gracieux, SIGKILL est inattrappable.

nodejs
const child = spawn('sleep', ['60']);

// 'exit' fires with code + signal
child.on('exit', (code, signal) => {
  if (code === 0) console.log('success');
  else if (signal) console.log('killed by', signal);
  else console.log('failed with code', code);
});

// send a signal to the child (SIGTERM by default)
setTimeout(() => child.kill('SIGTERM'), 1000);
child.kill();             // default SIGTERM
child.kill('SIGKILL');    // force-kill (cannot be caught)

// 'close' vs 'exit': 'close' fires after streams are closed
child.on('close', code => console.log('streams closed', code));

// check if process is still running
child.killed;             // true after kill() called
12

Cluster

Clustering de base

cluster permet de forker plusieurs processus Node partageant un port, passant à l'échelle sur les cœurs CPU. Le primaire fork les workers (typiquement os.cpus().length). Chaque worker est un processus Node complet tournant le même script. Redémarrez les workers sur 'exit' pour la résilience. Utilisez cluster.isPrimary (anciennement isMaster) pour brancher la logique.

nodejs
const cluster = require('cluster');
const http = require('http');
const os = require('os');

if (cluster.isPrimary) {            // old: isMaster
  // fork one worker per CPU core
  for (let i = 0; i < os.cpus().length; i++) cluster.fork();

  cluster.on('exit', (worker, code) => {
    console.log(`worker ${worker.process.pid} died`);
    cluster.fork();                 // restart it
  });
} else {
  // workers share the same port
  http.createServer((req, res) => res.end('hi'))
    .listen(3000);
  console.log('worker started', process.pid);
}

Gestion des workers

Le primaire suit les workers via les événements 'online' (processus démarré), 'listening' (serveur lié), 'disconnect' et 'exit'. disconnect() draine les connexions avant de tuer le worker — utilisez-le pour des rechargements sans interruption. cluster.workers mappe les IDs de worker aux objets Worker pour leur envoyer des messages ou les fermer.

nodejs
cluster.on('online', worker => {
  console.log('worker responsive', worker.id);
});

cluster.on('listening', (worker, address) => {
  console.log('worker bound to', address.port);
});

cluster.on('disconnect', worker => {
  console.log('worker disconnected', worker.id);
});

// gracefully shut down a worker
const w = cluster.workers[1];
w.disconnect();            // stop accepting connections, then exit
w.send('shutdown');        // custom message

// iterate all workers
for (const id in cluster.workers) {
  cluster.workers[id].send({ cmd: 'reload' });
}

Port de serveur partagé

Tous les workers écoutent le même port ; le primaire répartit les connexions entrantes. SCHED_RR (round-robin, défaut sur la plupart des plateformes) distribue uniformément ; SCHED_NONE laisse l'OS décider. L'état n'est PAS partagé entre workers — utilisez Redis ou une base pour les sessions/cache partagés.

nodejs
const cluster = require('cluster');
const http = require('http');

if (cluster.isPrimary) {
  cluster.schedulingPolicy = cluster.SCHED_RR;  // round-robin (default on non-Windows)
  cluster.fork();
  cluster.fork();
} else {
  // all workers call listen(3000) — primary load-balances
  http.createServer((req, res) => {
    res.end(`handled by ${process.pid}`);
  }).listen(3000);
}

// SCHED_RR: primary distributes connections (default)
// SCHED_NONE: OS balances (may be uneven)

Cycle de vie des workers et IPC

cluster.fork() ouvre un canal IPC (comme child_process.fork) : worker.send et process.on('message') échangent du JSON entre primaire et workers. Utilisez-le pour dispatcher des tâches ou signaler un arrêt gracieux. Pour du travail CPU lourd, considérez aussi worker_threads, qui partagent la mémoire et évitent l'overhead IPC.

nodejs
// primary -> worker messaging
if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.on('message', msg => console.log('from worker:', msg));
  worker.send({ task: 'heavy-compute' });
} else {
  process.on('message', msg => {
    console.log('from primary:', msg);
    // do work, then report back
    process.send({ done: true, result: 42 });
  });
}

// graceful shutdown signal
process.on('message', msg => {
  if (msg === 'shutdown') {
    server.close(() => process.exit(0));
  }
});

Rechargement gracieux (sans interruption)

Un rolling restart recharge les workers un par un pour que l'app ne s'arrête jamais : déconnectez un worker (il cesse d'accepter de nouvelles connexions), attendez sa sortie après drainage, puis fork un remplaçant. Déclenchez-le avec SIGHUP. Combinez toujours avec un message 'shutdown' par worker pour que chacun ferme son serveur et ne quitte qu'après la fin des requêtes en vol.

nodejs
// rolling restart: reload workers one at a time
function reload() {
  const workers = Object.values(cluster.workers || {});
  let i = 0;
  const next = () => {
    if (i >= workers.length) return;
    const w = workers[i++];
    w.send('shutdown');                 // tell worker to drain
    w.disconnect();                     // stop accepting connections
    w.once('exit', () => {
      cluster.fork();                   // replacement ready
      next();                           // move to the next
    });
  };
  next();
}

// trigger reload on SIGHUP
process.on('SIGHUP', reload);

// in the worker: finish in-flight requests then exit
process.on('message', msg => {
  if (msg === 'shutdown') server.close(() => process.exit(0));
});
13

Programmation asynchrone

Callbacks et convention error-first

Le motif async classique de Node est le callback error-first : le premier argument est une erreur (null en cas de succès), les suivants sont les résultats. Vérifiez toujours err d'abord et retournez tôt en cas d'échec. Ce style passe mal à l'échelle avec l'imbrication — le fameux callback hell — donc le code moderne utilise Promises et async/await.

nodejs
// Node callbacks: (err, result) => {}
const fs = require('fs');

fs.readFile('data.txt', 'utf8', (err, data) => {
  if (err) return console.error('read failed', err);
  console.log(data);
});

// custom error-first function
function divide(a, b, cb) {
  if (b === 0) return cb(new Error('divide by zero'));
  cb(null, a / b);
}

divide(10, 2, (err, result) => {
  if (err) return console.error(err);
  console.log(result);   // 5
});

Promises

Une Promise représente une valeur future. then() gère le succès, catch() le rejet, finally() s'exécute dans tous les cas. Chaînez then() pour transformer les valeurs séquentiellement. util.promisify convertit une fonction à callback error-first en une fonction retournant une Promise — faisant le pont entre API legacy et async/await.

nodejs
// create a promise
const p = new Promise((resolve, reject) => {
  setTimeout(() => resolve('done'), 100);
});

// consume with then/catch/finally
p.then(val => console.log(val))      // 'done'
 .catch(err => console.error(err))
 .finally(() => console.log('settled'));

// chain transforms
fetch(url)
  .then(r => r.json())
  .then(data => render(data));

// convert callback APIs
const { promisify } = require('util');
const readFile = promisify(fs.readFile);
const text = await readFile('x.txt', 'utf8');

async/await

async/await rend le code asynchrone semblable à du synchrone. Une fonction async retourne une Promise ; await suspend jusqu'à résolution. Enveloppez les appels attendus dans try/catch pour gérer les rejets. Le top-level await est permis en ES Modules et (avec un flag) en CommonJS, éliminant le besoin d'un wrapper IIFE async.

nodejs
// async functions always return a Promise
async function loadUser(id) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error('not found');
  return res.json();
}

// consume with try/catch
try {
  const user = await loadUser(5);
  console.log(user);
} catch (err) {
  console.error('failed:', err);
}

// top-level await works in ESM and CommonJS (Node 14.8+)
const config = await loadConfig();

Promise.all et allSettled

Promise.all exécute des promises en parallèle et se résout avec un tableau de résultats, mais rejette immédiatement si UNE SEULE rejette (fast-fail) — à utiliser quand tout doit réussir. Promise.allSettled attend chaque promise quel que soit le résultat, retournant des objets {status, value/reason} — le mieux quand un succès partiel est acceptable.

nodejs
// all: run in parallel, reject fast on first failure
const [a, b, c] = await Promise.all([
  fetch('/a').then(r => r.json()),
  fetch('/b').then(r => r.json()),
  fetch('/c').then(r => r.json())
]);

// allSettled: wait for ALL, never rejects
const results = await Promise.allSettled([
  fetch('/x'),
  fetch('/y'),
  fetch('/z')
]);
results.forEach(r => {
  if (r.status === 'fulfilled') console.log(r.value);
  else console.error(r.reason);   // rejected reason
});

Promise.race et Promise.any

Promise.race se résout OU rejette avec la première promise à se terminer — utile pour les timeouts et les courses entre miroirs. Promise.any se résout avec le premier succès et ne rejette (AggregateError) que si toutes échouent — idéal pour des endpoints redondants où une seule réponse saine suffit.

nodejs
// race: first to SETTLE (resolve or reject) wins
const fastest = await Promise.race([
  fetch('/primary'),
  fetch('/mirror'),
  timeout(5000)
]);

// any: first to FULFILL wins; rejects only if ALL reject
const alive = await Promise.any([
  fetch('/node1'),
  fetch('/node2'),
  fetch('/node3')
]);

// implement a timeout with race
function withTimeout(p, ms) {
  return Promise.race([
    p,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('timeout')), ms))
  ]);
}

Séquentiel vs parallèle

Attendre dans une boucle s'exécute séquentiellement (lent). Mappez vers un tableau de promises et Promise.all-les pour le parallélisme (rapide, mais une concurrence non bornée peut submerger les ressources). Un pool limitant la concurrence réduit le travail parallèle — essentiel quand on appelle des API limitées en débit ou fait de l'I/O lourd sur des milliers d'éléments.

nodejs
// SEQUENTIAL: one after another (slow)
const results = [];
for (const url of urls) {
  results.push(await fetch(url).then(r => r.json()));
}

// PARALLEL: fire all, await together (fast)
const results = await Promise.all(
  urls.map(u => fetch(u).then(r => r.json()))
);

// THROTTLED: limit concurrency with a pool
async function mapLimit(items, limit, fn) {
  const ret = [];
  const executing = [];
  for (const item of items) {
    const p = Promise.resolve().then(() => fn(item));
    ret.push(p);
    if (executing.push(p) >= limit) {
      await Promise.race(executing);
      executing.splice(executing.findIndex(x => x === p), 1);
    }
  }
  return Promise.all(ret);
}
14

Gestion des erreurs

try/catch/finally

try/catch gère les erreurs synchrones et (avec await) les rejets asynchrones. finally s'exécute toujours, même sur return/throw — utilisez-le pour le nettoyage comme fermer des handles. Attrapez les erreurs spécifiques en vérifiant err.code, et relancez tout ce que vous ne reconnaissez pas pour que les bugs inattendus remontent au lieu d'être avalés.

nodejs
function parse(str) {
  try {
    return JSON.parse(str);
  } catch (err) {
    console.error('parse failed:', err.message);
    return null;
  } finally {
    console.log('cleanup always runs');
  }
}

// async errors need async catch
async function load() {
  try {
    const data = await fetchData();
    return data;
  } catch (err) {
    if (err.code === 'ENOENT') return defaultData();
    throw err;              // re-throw unknown errors
  }
}

Callbacks error-first

Dans les callbacks error-first, vérifiez toujours err d'abord et retournez tôt — n'utilisez jamais data quand err est défini. Quand vous enveloppez une API à callback, transmettez l'erreur à votre propre callback plutôt que de thrower (les throws dans les callbacks ne peuvent pas être attrapés par l'appelant). Enveloppez le code sync pouvant thrower (comme JSON.parse) dans try/catch.

nodejs
const fs = require('fs');

// ALWAYS check err first, return early
fs.readFile('missing.txt', 'utf8', (err, data) => {
  if (err) {
    console.error('could not read:', err.message);
    return;            // don't use data
  }
  console.log(data);
});

// propagate the error to your own caller
function readConfig(cb) {
  fs.readFile('config.json', 'utf8', (err, raw) => {
    if (err) return cb(err);
    try { cb(null, JSON.parse(raw)); }
    catch (e) { cb(e); }
  });
}

Exceptions non attrapées

uncaughtException se déclenche pour les exceptions synchrones qui échappent à tous les handlers — le processus est alors corrompu ; loggez, fermez le serveur et quittez (laissez un gestionnaire de processus vous redémarrer). unhandledRejection se déclenche pour les promises oubliées ; depuis Node 15, elles crashent le processus, donc ajoutez toujours .catch() ou awaitez dans try/catch.

nodejs
// last-resort handler for sync exceptions
process.on('uncaughtException', err => {
  console.error('UNCAUGHT:', err);
  // the process is in an unknown state — restart it
  server.close(() => process.exit(1));
});

// rejected promises nobody awaited
process.on('unhandledRejection', (reason, promise) => {
  console.error('UNHANDLED REJECTION:', reason);
});

// Node 15+: unhandled rejections terminate the process
// always add .catch() or wrap in try/await

Classes d'erreur personnalisées

Sous-classez Error pour ajouter des champs structurés (code, field, status) et distinguer les types d'erreurs avec instanceof. Réglez toujours this.name au nom de classe (ce n'est pas automatique sur les vieux targets) et appelez super(message). Les erreurs custom rendent les blocs catch lisibles : branchez sur instanceof plutôt que sur du matching fragile de chaînes.

nodejs
// subclass Error to add context
class ValidationError extends Error {
  constructor(field, message) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
    this.code = 'VALIDATION_FAILED';
  }
}

function validate(email) {
  if (!email.includes('@')) {
    throw new ValidationError('email', 'invalid email');
  }
}

// branch on error type with instanceof
try {
  validate('no-at-sign');
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.field, err.message);
  } else {
    throw err;
  }
}

Propriétés d'erreur et cause

Chaque Error a message, name et stack. Ajoutez une propriété code pour un traitement stable et lisible par machine (les erreurs de Node même utilisent des codes comme ENOENT, EACCES). L'option cause ES2022 (Node 16.9+) chaîne une erreur sous-jacente pour envelopper des échecs de bas niveau en préservant la pile d'origine pour le débogage.

nodejs
// built-in Error props
const e = new Error('something broke');
e.message;    // 'something broke'
e.stack;      // stack trace string
e.name;       // 'Error'

// add a code for machine-readable handling
const err = new Error('file missing');
err.code = 'ENOENT';
err.errno = -2;

// Error.cause (Node 16.9+) — chain underlying errors
try {
  JSON.parse(bad);
} catch (original) {
  throw new Error('config parse failed', { cause: original });
}

// inspect the cause
console.log(err.cause);            // the original SyntaxError

Domains et nettoyage

Utilisez 'beforeExit' pour le nettoyage async (il peut reporter la sortie), et 'exit' seulement pour du travail synchrone. Gérez SIGTERM (arrêt de conteneur) et SIGINT (Ctrl-C) pour drainer les connexions avant de quitter — ajoutez un timeout de sortie forcée pour qu'une connexion bloquée ne suspende pas le processus. Domains est déprécié ; utilisez try/catch et la gestion d'erreurs async.

nodejs
// modern cleanup: 'beforeExit' for async, 'exit' for sync
process.on('beforeExit', async () => {
  await closeDbConnections();
});

process.on('exit', code => {
  // ONLY sync code allowed here — no async, no promises
  console.log('exiting with', code);
});

// graceful signal handling
const shutdown = sig => {
  console.log('got', sig);
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(1), 5000).unref(); // force exit
};
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
15

Débogage

Méthodes console

console offre plus que log : table rend des tableaux d'objets, time/timeEnd mesure des durées, dir déverse un objet avec profondeur configurable, trace imprime une pile, et count comptabilise les passages. Utilisez console.error (stderr) pour séparer logs et erreurs dans les pipelines de production.

nodejs
console.log('basic');              // stdout
console.error('oops');           // stderr
console.warn('careful');         // stderr

// formatted table
console.table([{ id: 1, n: 'A' }, { id: 2, n: 'B' }]);

// inspect an object in depth
console.dir(obj, { depth: null, colors: true });

// timing a block
console.time('loop');
for (let i = 0; i < 1e6; i++) {}
console.timeEnd('loop');         // loop: 3.2ms

// stack trace
console.trace('where am I');

// count calls
for (let i = 0; i < 3; i++) console.count('hit');

node inspect et DevTools

--inspect démarre l'inspecteur V8 pour que Chrome DevTools (chrome://inspect) ou VS Code s'attache. --inspect-brk suspend à la première ligne pour poser des breakpoints avant le code de démarrage. Le classique 'node inspect' est un débogueur terminal utile en SSH où un navigateur n'est pas disponible.

nodejs
# open Chrome DevTools debugger
node --inspect app.js
# visit chrome://inspect, click "inspect"

# pause on first line (break before anything runs)
node --inspect-brk app.js

# wait for a debugger client to attach
node --inspect-wait app.js

# the legacy CLI debugger (still works, no browser)
node inspect app.js
# > cont, step, next, breakpoints, repl

L'instruction debugger

L'instruction debugger suspend l'exécution SEULEMENT quand un débogueur (DevTools ou VS Code) est attaché — sinon c'est un no-op, sûr de laisser dans le code. Combinez avec --inspect-brk pour s'arrêter au démarrage. Pour une inspection ponctuelle, glissez debugger; dans des boucles ou conditions au lieu de poser des breakpoints dans l'UI.

nodejs
function findBug(arr) {
  let sum = 0;
  for (const n of arr) {
    debugger;        // pauses only when a debugger is attached
    sum += n;
  }
  return sum;
}

// run with --inspect-brk to hit the breakpoint
// node --inspect-brk app.js

// conditional breakpoints in DevTools/VSCode:
//   if (n > 100) { debugger; }

Débogage VS Code

Le débogueur Node de VS Code (F5) lit .vscode/launch.json. "request": "launch" lance le programme avec l'inspecteur intégré ; "attach" se connecte à un processus déjà démarré avec --inspect. skipFiles masque les internals de Node au pas-à-pas. Utilisez le flag "restart" ou nodemon pour relancer automatiquement aux changements de fichiers.

nodejs
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug App",
      "program": "${workspaceFolder}/app.js",
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach by PID",
      "processId": "${command:PickProcess}"
    }
  ]
}

// F5 to start; set breakpoints in the editor
// "restart": true, "nodemon" for auto-restart on change

Warnings et piles d'appels

--trace-warnings imprime les piles des warnings du processus (fuites mémoire, API dépréciées). --trace-deprecation révèle l'usage d'API legacy ; --throw-deprecation les transforme en erreurs dures pour une CI plus stricte. --cpu-prof écrit un profil ouvrable dans Chrome DevTools pour trouver les fonctions chaudes. Relevez Error.stackTraceLimit pour des traces async plus profondes.

nodejs
# show stack traces for process warnings
node --trace-warnings app.js

# deprecation warnings (use --throw-deprecation to make them errors)
node --trace-deprecation app.js

# capture a stack trace manually
const e = new Error('here');
console.log(e.stack);

# show async stack traces (Node 12+ enabled by default)
Error.stackTraceLimit = 50;   // deeper traces

# profile CPU usage
node --cpu-prof app.js        # writes CPU.*.cpuprofile
# then load the file in Chrome DevTools
16

Crypto

Hashing (createHash)

createHash produit un digest à sens unique. SHA-256 est le défaut moderne pour checksums et signatures ; évitez MD5/SHA-1 pour la sécurité (sujets aux collisions). On peut alimenter les données incrémentalement et streamer de gros fichiers sans bufferiser. digest('hex') retourne une chaîne hex ; 'base64' aussi courant. Le hashing N'EST PAS du stockage de mots de passe — utilisez pbkdf2/scrypt.

nodejs
const crypto = require('crypto');

// common hashes: sha256, sha512, md5 (insecure!), sha1
const hash = crypto.createHash('sha256');
hash.update('hello');
hash.update(' world');        // can chain updates
console.log(hash.digest('hex'));
// b94d...  (64 hex chars)

// one-shot hashing
const h = crypto.createHash('sha256').update('data').digest('hex');
console.log(h);

// file hash (streaming)
const fs = require('fs');
const fhash = crypto.createHash('sha256');
fs.createReadStream('big.iso').on('data', c => fhash.update(c))
  .on('end', () => console.log(fhash.digest('hex')));

HMAC (createHmac)

HMAC signe des données avec un secret partagé pour que le récepteur vérifie intégrité et authenticité. C'est le socle des signatures JWT et de la vérification des webhooks (GitHub, Stripe). Comparez toujours les signatures avec timingSafeEqual — un === normal fuite de l'information par les différences de timing que les attaquants exploitent.

nodejs
const crypto = require('crypto');

// HMAC = keyed hash (authenticity + integrity)
const secret = process.env.SECRET_KEY;
const hmac = crypto.createHmac('sha256', secret);
hmac.update('payload to sign');
const signature = hmac.digest('hex');

// verify a webhook signature (constant-time compare)
function verify(payload, receivedSig) {
  const expected = crypto.createHmac('sha256', secret)
    .update(payload).digest('hex');
  // timingSafeEqual prevents timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSig)
  );
}

Octets aléatoires

crypto.randomBytes produit des données aléatoires cryptographiquement sûres — pour les tokens, IDs et secrets. La forme async évite de bloquer la boucle d'événements en générant beaucoup d'octets. crypto.randomInt donne des entiers aléatoires non biaisés, et randomUUID() génère des UUID RFC-4122 v4. N'utilisez jamais Math.random() pour quoi que ce soit lié à la sécurité.

nodejs
const crypto = require('crypto');

// async (preferred — doesn't block the event loop)
crypto.randomBytes(16, (err, buf) => {
  const token = buf.toString('hex');   // 32-char hex
});

// sync (blocks; fine for small sizes)
const id = crypto.randomBytes(8).toString('hex');

// random integer in [min, max)
const n = crypto.randomInt(1, 101);     // 1..100

// random UUID (Node 14.17+)
const uuid = crypto.randomUUID();
// '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'

// use crypto, NEVER Math.random() for secrets!

Chiffrement (createCipheriv)

AES-256-GCM est le chiffre symétrique recommandé — authentifié, donc la falsification est détectée. L'IV (nonce) doit être unique par chiffrement avec une clé donnée (jamais réutiliser) ; stockez-le à côté du ciphertext. setAuthTag vérifie l'intégrité au déchiffrement. N'utilisez jamais le createCipher déprécié (il dérive les clés de façon non sûre) — toujours createCipheriv avec une clé appropriée.

nodejs
const crypto = require('crypto');
const algorithm = 'aes-256-gcm';

// AES-256-GCM (authenticated encryption) ----------------
const key = crypto.randomBytes(32);   // 256-bit key
const iv = crypto.randomBytes(12);    // 96-bit nonce

function encrypt(text) {
  const cipher = crypto.createCipheriv(algorithm, key, iv);
  const enc = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
  const tag = cipher.getAuthTag();    // GCM auth tag
  return { enc, tag };
}

function decrypt(enc, tag) {
  const decipher = crypto.createDecipheriv(algorithm, key, iv);
  decipher.setAuthTag(tag);           // verify integrity
  return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8');
}

Hash de mots de passe (pbkdf2, scrypt)

Hasher les mots de passe avec un KDF lent et salé — jamais avec un hash simple. pbkdf2 (montez les itérations à mesure que le matériel progresse) et scrypt (memory-hard, résistant aux GPU) sont intégrés à Node. Stockez itérations, sel et hash ensemble pour vérifier puis monter les paramètres plus tard. Utilisez timingSafeEqual pour comparer les hashs sans fuite de timing.

nodejs
const crypto = require('crypto');

// PBKDF2: tuned with iterations
function hashPbkdf2(password) {
  const salt = crypto.randomBytes(16);
  const iterations = 100000;
  const hash = crypto.pbkdf2Sync(password, salt, iterations, 64, 'sha256');
  return `${iterations}.${salt.toString('hex')}.${hash.toString('hex')}`;
}

// scrypt: memory-hard, resistant to GPU/ASIC attacks
function hashScrypt(password) {
  const salt = crypto.randomBytes(16);
  const hash = crypto.scryptSync(password, salt, 64, { N: 16384 });
  return salt.toString('hex') + '.' + hash.toString('hex');
}

// verify: re-hash with the same salt and compare
function verify(password, stored) {
  const [iter, salt, hash] = stored.split('.');
  const computed = crypto.pbkdf2Sync(password, Buffer.from(salt, 'hex'),
    +iter, 64, 'sha256');
  return crypto.timingSafeEqual(Buffer.from(hash, 'hex'), computed);
}

Comparaison timing-safe

timingSafeEqual compare deux buffers en temps constant, prévenant les attaques par timing où un attaquant déduit un secret octet par octet depuis les délais de réponse. Les deux buffers doivent être de même longueur (vérifiez d'abord, mais cette vérification de longueur peut elle-même fuiter la longueur — pour les secrets, hashz d'abord les deux côtés). Utilisez-le pour toute comparaison de tokens, signatures ou clés API.

nodejs
const crypto = require('crypto');

// NORMAL compare leaks via timing (returns early on first diff)
// 'secret' === userInput  // BAD for secrets

// timingSafeEqual takes equal-length Buffers
function safeEqual(a, b) {
  const bufA = Buffer.from(a);
  const bufB = Buffer.from(b);
  if (bufA.length !== bufB.length) return false;
  return crypto.timingSafeEqual(bufA, bufB);
}

// common use: API key check
function auth(req) {
  const provided = req.headers['x-api-key'] || '';
  return safeEqual(provided, process.env.API_KEY);
}
17

Module OS

Informations système

os expose l'environnement hôte. platform/arch/type identifient l'OS pour les vérifications de portabilité. os.EOL donne la séquence de fin de ligne de la plateforme — utilisez-la pour écrire des fichiers texte corrects par plateforme. hostname est le nom réseau de la machine, utile pour logger quelle instance a traité une requête.

nodejs
const os = require('os');

os.platform();    // 'linux', 'darwin', 'win32'
os.arch();        // 'x64', 'arm64'
os.type();        // 'Linux', 'Darwin', 'Windows_NT'
os.release();     // kernel version
os.hostname();    // machine hostname
os.uptime();      // seconds since boot
os.EOL;           // '\n' (POSIX) or '\r\n' (Windows)

// detect platform portably
const isWin = os.platform() === 'win32';
const isMac = os.platform() === 'darwin';

Infos CPU

os.cpus() retourne un tableau de cœurs logiques (hyperthreads inclus), donc sa longueur est le bon indice de concurrence pour cluster.fork. Chaque entrée a model, speed et times (user/sys/idle). loadavg rapporte la charge système (Linux/macOS seulement) — une valeur au-dessus de cpus().length suggère une saturation.

nodejs
const os = require('os');

// logical core count (threads, not physical)
os.cpus().length;        // 8

// detailed per-core info
os.cpus().forEach((cpu, i) => {
  console.log(`core ${i}: ${cpu.model} @ ${cpu.speed}MHz`);
});

// 1/5/15-minute load averages (NOT on Windows)
os.loadavg();            // [0.45, 0.32, 0.28]

// set process scheduling priority
os.setPriority(os.constants.priority.PRIORITY_BELOW_NORMAL);

Mémoire

os.totalmem/freemem rapportent la RAM système, tandis que process.memoryUsage rapporte l'empreinte de ce processus. rss est la mémoire au niveau OS ; heapUsed les objets JS vivants. Surveillez heapUsed pour les fuites. Pour convertir des octets en Mo, divisez par 1024*1024 (1048576). Réglez --max-old-space-size quand le heap approche la limite.

nodejs
const os = require('os');

// system memory (bytes)
os.totalmem();          // e.g. 17179869184
os.freemem();           // currently free bytes

// process memory usage (bytes)
const m = process.memoryUsage();
m.rss;          // resident set size (total RAM held)
m.heapTotal;    // V8 heap allocated
m.heapUsed;     // V8 heap actually used
m.external;     // C++ objects bound to JS
m.arrayBuffers; // memory in ArrayBuffers

// human-readable
console.log(`heap: ${(m.heapUsed / 1048576).toFixed(1)} MB`);

Interfaces réseau

os.networkInterfaces() liste chaque interface réseau avec ses adresses, MAC et famille (IPv4/IPv6). Le flag 'internal' marque le loopback. C'est la façon portable de découvrir l'IP LAN de la machine pour lier des serveurs ou logger. Chaque interface peut avoir plusieurs adresses (hôtes multi-adressés).

nodejs
const os = require('os');

const nets = os.networkInterfaces();
for (const name of Object.keys(nets)) {
  for (const net of nets[name]) {
    console.log(`${name} ${net.family}: ${net.address} (${net.mac})`);
  }
}
// en0 IPv4: 192.168.1.10 (aa:bb:cc:...)
// lo IPv4: 127.0.0.1 (:::...)

// find this machine's LAN IPv4
function getLanIp() {
  for (const nets of Object.values(os.networkInterfaces())) {
    for (const n of nets) {
      if (n.family === 'IPv4' && !n.internal) return n.address;
    }
  }
  return '127.0.0.1';
}

Utilisateur et chemins

os.homedir retourne le répertoire personnel de l'utilisateur et os.tmpdir le dossier temporaire système — tous deux conscients de la plateforme, préférez-les aux chemins codés en dur. os.userInfo donne l'identité de l'utilisateur courant. os.constants centralise les valeurs numériques de signal/errno/priorité pour ne pas coder en dur des nombres magiques comme 15 pour SIGTERM.

nodejs
const os = require('os');

os.homedir();      // /home/alice  or C:\Users\alice
os.tmpdir();       // /tmp         or C:\Users\...\Temp
os.userInfo();     // { username, uid, gid, homedir, shell }
os.constants;      // signal/errno/priority constants

// errno constants map
os.constants.errno.ENOENT;   // -2
// signal constants
os.constants.signals.SIGTERM; // 15

// priority constants
os.constants.priority.PRIORITY_HIGH;

// build a portable temp path
const path = require('path');
const tmpFile = path.join(os.tmpdir(), 'app-' + Date.now() + '.log');
18

Process

process.argv

process.argv contient les arguments de ligne de commande : argv[0] est le binaire node, argv[1] le script, et le reste les arguments utilisateur. Tranchez les deux premiers pour ne garder que les arguments utilisateur. Au-delà des scripts jouets, utilisez un parseur comme minimist, yargs ou commander — ils gèrent flags, types, défauts et texte d'aide.

nodejs
// argv[0] = node path, argv[1] = script path, argv[2+] = args
// node app.js --port 3000 users.csv
console.log(process.argv);
// ['/usr/bin/node', '/app/app.js', '--port', '3000', 'users.csv']

const args = process.argv.slice(2);
console.log(args);  // ['--port', '3000', 'users.csv']

// minimal flag parsing
function parseArgs(arr) {
  const out = { _: [] };
  for (let i = 0; i < arr.length; i++) {
    if (arr[i].startsWith('--')) out[arr[i].slice(2)] = arr[++i];
    else out._.push(arr[i]);
  }
  return out;
}
// for real CLI use commander, yargs, or minimist

process.env

process.env contient les variables d'environnement sous forme de chaînes. Par convention, PORT, NODE_ENV, DATABASE_URL et API_KEY viennent de l'env pour que le même code tourne partout. Utilisez le package dotenv pour charger un .env en développement. Ne commitez jamais de secrets — injectez-les via l'environnement hôte/CI.

nodejs
// read environment variables
const port = process.env.PORT || 3000;
const dbUrl = process.env.DATABASE_URL;
const nodeEnv = process.env.NODE_ENV || 'development';

const isProd = process.env.NODE_ENV === 'production';

// set an env var (affects child processes too)
process.env.MY_VAR = 'value';

// load .env files (install: npm i dotenv)
// require('dotenv').config();

// enumerate everything
for (const [k, v] of Object.entries(process.env)) {
  console.log(k, '=', v);
}

process.exit et codes de sortie

process.exit(n) termine immédiatement, possiblement avant le flush des buffers d'I/O — préférez régler process.exitCode et laisser la boucle d'événements se drainer naturellement. Sortie 0 = succès ; non zéro signale un échec aux shells et à la CI. La convention 128+N encode une terminaison par signal N (donc SIGTERM donne 143).

nodejs
// exit immediately with a status code
process.exit(0);    // success
process.exit(1);    // general failure

// exit code is also settable
process.exitCode = 2;   // used if the loop ends naturally

// prefer setting exitCode + returning over process.exit()
// so async work can finish

// common conventions:
// 0  success
// 1  general error
// 2  misuse (bad args)
// 124 timeout (from the 'timeout' command)
// 128+N  killed by signal N (e.g. 143 = SIGTERM)

stdin / stdout / stderr

process.stdout et process.stderr sont des streams inscriptibles — write() n'ajoute pas de retour à la ligne (contrairement à console.log). stdin est un stream lisible consommable via des événements 'data' ou une itération async (le motif moderne le plus propre). Utilisez stderr pour les diagnostics afin de le séparer de la vraie sortie dans les pipes.

nodejs
// stdout/stderr are writable streams
process.stdout.write('no newline');
process.stdout.write('line\n');
console.log === process.stdout.write.bind(...); // roughly

// stdin is a readable stream
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => console.log('got:', chunk));

// read all of stdin (async iteration)
async function readStdin() {
  let data = '';
  for await (const chunk of process.stdin) data += chunk;
  return data;
}

// ask a yes/no question
process.stdin.resume();
process.stdin.once('data', input => process.exit(input[0] === 'y'.charCodeAt(0) ? 0 : 1));

Événements du processus (signaux)

'exit' se déclenche après vidage de la boucle d'événements — seul du code synchrone y tourne. 'beforeExit' peut exécuter du travail async et reporter la sortie. Gérez SIGINT (Ctrl-C) et SIGTERM (docker stop, kill) pour fermer serveurs et connexions DB proprement. Réglez toujours un timeout de sortie forcée pour qu'une connexion suspendue ne piège pas le processus indéfiniment.

nodejs
// lifecycle events
process.on('exit', code => {
  // sync only here — no async, no event loop
  console.log('bye, code', code);
});
process.on('beforeExit', () => {
  // async OK; can postpone exit
});

// signal handlers (Unix + Windows for SIGINT/SIGTERM)
process.on('SIGINT', () => {       // Ctrl-C
  console.log('graceful shutdown...');
  server.close(() => process.exit(0));
});
process.on('SIGTERM', () => {      // kill / docker stop
  server.close(() => process.exit(0));
});
process.on('SIGHUP', () => reloadConfig());

memoryUsage et uptime

process expose l'identité (pid, ppid, platform, version) et les stats d'exécution (uptime, memoryUsage, cpuUsage). cwd() est le répertoire de travail — chdir le change, affectant la résolution des chemins relatifs. memoryUsage et cpuUsage fondent les endpoints de health-check et les métriques d'autoscaling.

nodejs
// process info
process.pid;             // OS process ID
process.ppid;            // parent PID
process.platform;        // 'linux', 'darwin', 'win32'
process.version;         // 'v20.11.0'
process.versions;        // { v8, openssl, modules, ... }
process.cwd();           // current working directory
process.uptime();        // seconds since process started

// change directory
process.chdir('/tmp');

// memory snapshot
const m = process.memoryUsage();
console.log(m.rss, m.heapUsed);

// CPU usage of this process
const cpu = process.cpuUsage();
console.log(cpu.user, cpu.system);  // microseconds
19

Réseau (net)

Serveur TCP

net.createServer fabrique un serveur TCP brut. Chaque connexion invoque le callback avec un Socket (un stream Duplex). Lisez avec des événements 'data', écrivez avec socket.write. Traitez toujours 'error' sur les sockets sinon le processus crash. TCP est le fondement sous HTTP — utile pour protocoles custom, jeux et proxys.

nodejs
const net = require('net');

const server = net.createServer(socket => {
  console.log('client connected', socket.remoteAddress);
  socket.write('welcome\n');

  socket.on('data', data => {
    socket.write('echo: ' + data);     // echo back
  });

  socket.on('end', () => console.log('client left'));
  socket.on('error', err => console.error('socket err', err));
});

server.listen(5000, () => {
  console.log('TCP server on port 5000');
});

// test with: nc localhost 5000  or  telnet localhost 5000

Client TCP

net.connect (alias createConnection) ouvre un socket client TCP. Le callback se déclenche à la connexion ; les événements 'data' livrent les octets entrants. Réglez un encodage pour recevoir des chaînes plutôt que des Buffers. Comme tout stream, traitez 'error' pour éviter les crashs. Les sockets se ferment seuls sur 'end' ; appelez client.end() pour demi-fermer votre côté.

nodejs
const net = require('net');

// connect to a TCP server
const client = net.connect(5000, 'localhost', () => {
  console.log('connected');
  client.write('hello server\n');
});

client.setEncoding('utf8');
client.on('data', data => console.log('server said:', data));
client.on('end', () => console.log('disconnected'));
client.on('error', err => console.error(err));

// or with an options object + timeout
const c = net.createConnection({
  port: 5000,
  host: 'localhost',
  timeout: 5000
});

Événements socket et données

TCP est un flux d'octets, pas un protocole de messages — un événement 'data' ne vaut pas un message ; les données peuvent être scindées ou fusionnées. Vous DEVEZ cadrer les messages vous-même (préfixes de longueur, délimiteurs, ou un parseur). setKeepAlive détecte les pairs morts, setTimeout tue les connexions inactives, et 'drain' signale que le buffer d'écriture s'est vidé.

nodejs
const net = require('net');

net.createServer(socket => {
  socket.setEncoding('utf8');
  socket.setKeepAlive(true, 30000);   // enable TCP keepalive
  socket.setTimeout(60000);           // idle timeout

  socket.on('data', chunk => {
    // TCP is a STREAM: chunks may split or merge messages.
    // Frame your protocol (length prefix, delimiter, etc.)
    console.log('received', chunk.length, 'bytes');
  });

  socket.on('timeout', () => socket.end());
  socket.on('close', hadError => console.log('closed', hadError));
  socket.on('drain', () => console.log('buffer drained'));
}).listen(5000);

Écriture et demi-fermeture

socket.write respecte la backpressure (retourne false quand plein — attendez 'drain'). end() demi-ferme : il flush les écritures en attente puis envoie FIN tout en continuant à lire le pair. destroy() tue le socket immédiatement. Utilisez remoteAddress/remotePort pour le logging et le contrôle d'accès. Pause/resume throttlent un émetteur trop rapide.

nodejs
const net = require('net');

net.createServer(socket => {
  // write() returns false when the buffer is full (backpressure)
  const ok = socket.write(bigPayload);
  if (!ok) socket.once('drain', writeMore);

  // half-close: send FIN, keep reading
  socket.end();   // writes any pending data, then closes our side
  // socket.end('final message\n'); // write + close

  // fully destroy the socket immediately
  socket.destroy();

  // pause/resume reading
  socket.pause();
  socket.resume();

  // address info
  socket.remoteAddress;  // '192.168.1.5'
  socket.remotePort;     // 54321
}).listen(5000);

Événements serveur et IPC

Un net.Server émet 'connection' (par client), 'listening', 'error' (gérez EADDRINUSE) et 'close'. listen peut prendre un chemin pour un socket Unix (ou named pipe sous Windows) — IPC local rapide et sûr entre processus du même hôte. server.close() cesse d'accepter de nouvelles connexions et attend que les existantes se finissent.

nodejs
const net = require('net');

const server = net.createServer();
server.on('connection', socket => {});   // same as createServer cb
server.on('listening', () => console.log('bound'));
server.on('error', err => {
  if (err.code === 'EADDRINUSE') console.error('port taken');
});
server.on('close', () => console.log('server closed'));

server.listen(5000);

// Unix domain socket / named pipe (fast local IPC)
server.listen('/tmp/app.sock');
// Windows: server.listen('\\\\.\\pipe\\app');

// stop accepting, close idle connections
server.close(() => console.log('all done'));

// get bound address
server.address();   // { port: 5000, family: 'IPv4', address: '::' }
20

Timers et utilitaires

Timers (setTimeout, setInterval)

setTimeout tourne une fois après un délai, setInterval répète. setImmediate tourne après les événements d'I/O du même tour de boucle. queueMicrotask encore plus tôt, juste après l'opération courante. L'ordre dans une boucle est : microtasks d'abord, puis timers, puis I/O, puis setImmediate — utile à savoir quand planifier du travail de suivi.

nodejs
// run once after a delay (ms)
const t = setTimeout(() => console.log('hi'), 1000);

// run repeatedly every interval
const i = setInterval(() => console.log('tick'), 2000);

// run right after the current event loop turn
setImmediate(() => console.log('immediate'));

// run before the next event loop turn (microtask)
queueMicrotask(() => console.log('microtask'));

// order inside one loop:
// microtasks -> timers -> I/O -> check (setImmediate)

Effacer les timers et ref

Chaque timer a une fonction clear correspondante. unref() marque un timer comme « ne garde pas le processus vivant » — s'il ne reste que des timers unref'd, Node quitte (pratique pour un nettoyage périodique qui ne doit pas piéger le processus). ref() inverse. Les arguments supplémentaires après le délai sont transmis au callback, évitant une fonction fléchée de plus.

nodejs
const t = setTimeout(() => {}, 1000);
clearTimeout(t);     // cancel

const i = setInterval(() => {}, 1000);
clearInterval(i);

const imm = setImmediate(() => {});
clearImmediate(imm);

// keep the event loop alive?
// timers do by default; unref() lets the process exit if
// only this timer is pending
const timer = setInterval(() => {}, 1000);
timer.unref();       // won't keep Node alive
timer.ref();         // keep alive again

// pass args to the callback
setTimeout((a, b) => console.log(a, b), 500, 'x', 'y');

util.inspect et format

util.format construit des chaînes avec placeholders printf (%s %d %j %o %O %%). util.inspect rend n'importe quel objet — passez { depth: null, colors: true } pour un déversement coloré complet, utile dans les logs. util.deprecate enveloppe une fonction pour émettre un DeprecationWarning (révélé avec --trace-deprecation) quand appelée.

nodejs
const util = require('util');

// format like printf
util.format('%s:%d', 'port', 3000);   // 'port:3000'
util.format('%j', { a: 1 });           // JSON

// deep inspect an object (what console.dir uses)
util.inspect(obj, { depth: null, colors: true, compact: false });

// pretty-print a function (its source)
util.inspect(function f() { return 1; });

// deprecate an API with a warning
const oldFn = util.deprecate(
  () => doThingOldWay(),
  'oldFn() is deprecated, use newFn() instead'
);

util.promisify

util.promisify enveloppe une fonction à callback error-first en une fonction retournant une Promise — le pont des API legacy à callbacks vers async/await. Beaucoup de modules cœur livrent maintenant des versions promise natives (fs/promises) préférables, mais promisify sauve toujours les API tierces à callbacks. Une fonction peut définir [util.promisify.custom] pour contrôler la conversion.

nodejs
const util = require('util');
const fs = require('fs');

// turn an error-first callback fn into a promise fn
const readFile = util.promisify(fs.readFile);
const text = await readFile('data.txt', 'utf8');

// works on custom functions too
function delay(ms, cb) { setTimeout(() => cb(null, ms), ms); }
const delayP = util.promisify(delay);
await delayP(100);

// custom promisify symbol (controls the promise behavior)
// const { promisify } = util;
// obj[util.promisify.custom] = () => Promise.resolve(42);

// many core modules ship promise versions directly:
// require('fs/promises'), require('dns/promises')

Types util et callbackify

util.types offre des vérifications de type fiables (isPromise, isAsyncFunction, isRegExp, isMap) qui survivent mieux aux cas limites cross-realm et de sous-classe que instanceof. util.callbackify inverse promisify — utile quand il faut exposer une fonction basée promise à une API à callbacks. util.MIMEType (Node 19+) parse et manipule les types MIME.

nodejs
const util = require('util');

// type checks
util.isPromise(Promise.resolve());    // true
util.isFunction(() => {});            // true
util.types.isMap(new Map());          // true
util.types.isAsyncFunction(async () => {}); // true
util.types.isRegExp(/x/);             // true

// reverse of promisify: promise -> error-first callback
const readFileCb = util.callbackify(require('fs/promises').readFile);
readFileCb('x.txt', 'utf8', (err, data) => {
  if (err) console.error(err);
  else console.log(data);
});

// MIME type utilities (Node 19+)
util.MIMEType.parse('text/html; charset=utf-8');

nextTick vs setImmediate

process.nextTick tourne juste après l'opération synchrone courante, AVANT l'I/O — donc appeler nextTick récursivement peut affamer l'I/O indéfiniment (la boucle n'avance jamais). setImmediate tourne après l'I/O, dans la phase 'check'. Pour céder la main à la boucle d'événements et laisser l'I/O en attente se stabiliser, préférez setImmediate ; réservez nextTick au nettoyage qui doit se produire avant tout callback d'I/O.

nodejs
// process.nextTick: runs BEFORE I/O, after the current op
process.nextTick(() => console.log('tick'));

// setImmediate: runs AFTER I/O events, in the 'check' phase
setImmediate(() => console.log('immediate'));

// setTimeout(0): runs in the timers phase, after nextTick
setTimeout(() => console.log('timeout'), 0);

// typical order in one loop turn:
// 1. current sync code
// 2. nextTick callbacks  (can starve I/O!)
// 3. timers
// 4. I/O callbacks
// 5. setImmediate

// prefer setImmediate to yield to I/O; use nextTick for
// immediate post-sync cleanup

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.