Configuration et écosystème

// Les trois fichiers de web/, sans leurs commentaires d'en-tete, les tableaux
// remis sur une ligne.

// web/tsconfig.json : les options communes, et aucun fichier.
{
  "compileOnSave": false,
  "compilerOptions": {
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "experimentalDecorators": true,
    "importHelpers": true,
    "target": "ES2022",
    "module": "preserve"
  },
  "angularCompilerOptions": {
    "enableI18nLegacyMessageIdFormat": false,
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
  },
  "files": [],
  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.spec.json" }]
}

// web/tsconfig.app.json : le programme que compile ng build (angular.json, "tsConfig").
{
  "extends": "./tsconfig.json",
  "compilerOptions": { "types": [] },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.spec.ts"]
}

// web/tsconfig.spec.json : les tests, avec les globales describe, it, expect.
{
  "extends": "./tsconfig.json",
  "compilerOptions": { "types": ["vitest/globals"] },
  "include": ["src/**/*.d.ts", "src/**/*.spec.ts"]
}

// Chaque erreur ci-dessous vient d'un drapeau de la famille strict ; avec
// "strict": false, le fichier compile sans un mot, lignes fautives comprises.

// strictPropertyInitialization : un champ est affecte par le constructeur ou
// porte un initialiseur.
class Panier {
  lignes: string[];
  // total: number;
  // error TS2564: Property 'total' has no initializer and is not definitely assigned in the constructor.
  total = 0;

  constructor() {
    this.lignes = [];
  }
}

// noImplicitThis : dans une fonction libre, this n'a pas de type.
// function compter() { return this.lignes.length; }
// error TS2683: 'this' implicitly has type 'any' because it does not have a type annotation.
function compter(this: Panier): number {
  return this.lignes.length;
}

// strictBindCallApply : call, apply et bind verifient leurs arguments.
function ajouter(reference: string, quantite: number): void {
  console.log(`${quantite} x ${reference}`);
}
// ajouter.call(undefined, 'USB-64', '2');
// error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
ajouter.call(undefined, 'USB-64', 2); // 2 x USB-64

// strictBuiltinIteratorReturn (TypeScript 5.6) : ce que rend un iterateur de la
// bibliotheque une fois epuise est undefined, et non plus any.
const iterateur = ['USB-64', 'SSD-1T'][Symbol.iterator]();
const valeur = iterateur.next().value; // string | undefined
// const reference: string = valeur;
// error TS2322: Type 'string | undefined' is not assignable to type 'string'.
//   Type 'undefined' is not assignable to type 'string'.

console.log(compter.call(new Panier()), valeur ?? 'aucune'); // 0 USB-64

// "strict": true, sans noUncheckedIndexedAccess.
const stock: Record<string, number> = { 'USB-64': 12, 'SSD-1T': 3 };
const references = ['USB-64', 'SSD-1T'];

// Un acces par index rend le type de l'element, comme si la cle ou l'indice
// existait toujours.
function disponible(reference: string): number {
  return stock[reference] - 1; // number, pour le compilateur
}

const troisieme: string = references[2]; // string, pour le compilateur

console.log(disponible('HDMI-2M')); // NaN
console.log(troisieme.toUpperCase());
// A l'execution (Node) : TypeError: Cannot read properties of undefined (reading 'toUpperCase')

// "strict": true et "noUncheckedIndexedAccess": true.
const stock: Record<string, number> = { 'USB-64': 12, 'SSD-1T': 3 };
const references = ['USB-64', 'SSD-1T'];

// Chaque acces par index rend desormais T | undefined.
// function disponible(reference: string): number { return stock[reference] - 1; }
// error TS2532: Object is possibly 'undefined'.
function disponible(reference: string): number {
  const quantite = stock[reference]; // number | undefined
  return quantite === undefined ? 0 : quantite - 1;
}

// const troisieme: string = references[2];
// error TS2322: Type 'string | undefined' is not assignable to type 'string'.
//   Type 'undefined' is not assignable to type 'string'.
const troisieme = references[2] ?? 'aucune';

// Ce qui ne peut pas manquer n'est pas touche : l'element d'un for...of, et
// l'indice d'un tuple, dont la longueur est connue.
for (const reference of references) {
  console.log(reference.toLowerCase()); // usb-64, puis ssd-1t
}
const paire: [string, number] = ['USB-64', 12];
const prix: number = paire[1];

console.log(disponible('HDMI-2M'), troisieme, prix); // 0 aucune 12

// Les quatre options que web/tsconfig.json ajoute a strict, puis
// exactOptionalPropertyTypes, qu'il n'active pas.

// noImplicitOverride : redefinir une methode heritee exige override. Que la
// methode de base soit renommee, et la redefinition devient une erreur au lieu
// d'une methode orpheline que plus personne n'appelle.
class Composant {
  initialiser(): void {}
}

class Panier extends Composant {
  // initialiser(): void {}
  // error TS4114: This member must have an 'override' modifier because it overrides a member in the base class 'Composant'.
  override initialiser(): void {}
}

// noPropertyAccessFromIndexSignature : une cle venue d'une signature d'index se
// lit entre crochets, ce qui la distingue d'une propriete declaree.
const entetes: { [nom: string]: string } = { accept: 'application/json' };
// console.log(entetes.accept);
// error TS4111: Property 'accept' comes from an index signature, so it must be accessed with ['accept'].
console.log(entetes['accept']); // application/json

// noImplicitReturns : toutes les branches rendent une valeur, ou aucune.
// function libelle(code: number) { if (code === 200) { return 'OK'; } }
// error TS7030: Not all code paths return a value.
function libelle(code: number): string {
  return code === 200 ? 'OK' : 'Erreur';
}

// noFallthroughCasesInSwitch : un case non vide finit par break ou return.
// function niveau(code: number) { switch (code) { case 404: console.log('404'); case 500: return 'erreur'; } return 'info'; }
// error TS7029: Fallthrough case in switch.
function niveau(code: number): string {
  switch (code) {
    case 404:
      return 'avertissement';
    case 500:
      return 'erreur';
    default:
      return 'info';
  }
}

// exactOptionalPropertyTypes : ? veut dire « peut manquer », pas « peut valoir
// undefined ». Sans l'option, { delaiMs: undefined } est admis, et ecrase le
// defaut dans une decomposition : { ...defauts, ...options } rend alors
// { delaiMs: undefined }.
interface Options {
  delaiMs?: number;
}

const defauts = { delaiMs: 500 };
// const options: Options = { delaiMs: undefined };
// error TS2375: Type '{ delaiMs: undefined; }' is not assignable to type 'Options' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
//   Types of property 'delaiMs' are incompatible.
//     Type 'undefined' is not assignable to type 'number'.
const options: Options = {};

console.log(libelle(200), niveau(404), { ...defauts, ...options });
// OK avertissement { delaiMs: 500 }
new Panier().initialiser();

// tsconfig.json : "target": "es2022", sans "lib" : lib vaut alors es2022 et dom.
interface Ligne {
  reference: string;
  prix?: number;
}

const lignes: Ligne[] = [{ reference: 'USB-64', prix: 12 }, { reference: 'CABLE-2M' }];

// lib decrit les API qui existent a l'execution. findLast date d'ES2023.
// const derniere = lignes.findLast((l) => l.prix !== undefined);
// error TS2550: Property 'findLast' does not exist on type 'Ligne[]'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2023' or later.
// error TS7006: Parameter 'l' implicitly has an 'any' type.

// "lib": ["es2023", "dom"] fait taire l'erreur, mais n'ajoute rien au
// navigateur : s'il ne connait pas findLast, l'appel leve a l'execution.
// lib promet ; un polyfill fournit.
const derniere = lignes.at(-1); // at date d'ES2022 : admis

// target decrit la syntaxe emise. Avec "target": "es2019" et une lib qui declare
// at ("lib": ["es2022", "dom"] ; seule, la cible es2019 amene sa propre lib, et
// at y devient l'erreur TS2550), tsc reecrit ?. et ??, qui datent d'ES2020 :
//   const prix = (_b = (_a = lignes[0]) === null || _a === void 0 ? void 0 : _a.prix) !== null && _b !== void 0 ? _b : 0;
// mais il laisse lignes.at(-1) tel quel : il ne reecrit jamais une API.
const prix = lignes[0]?.prix ?? 0;

console.log(derniere?.reference, prix); // CABLE-2M 12
export {};

// tsconfig.json : "module": "esnext", donc "moduleResolution": "bundler", pour
// un programme que Node execute sans bundler. package.json : "type": "module".
// src/panier.ts : export const lignes = [{ reference: 'USB-64', prix: 12 }];
import { lignes } from './panier';
import { arrondir } from 'prix-utils';

console.log(arrondir(lignes[0].prix * 1.2));

// tsc ne signale rien et emet l'import tel qu'il est ecrit : './panier'.
// A l'execution (Node 24), dist/panier n'existe pas, seul dist/panier.js existe
// (chemins abreges) :
// Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../dist/panier' imported from .../dist/main.js

// tsconfig.json : "module": "nodenext" ; moduleResolution suit, nodenext.
// TypeScript applique la regle de Node : un import relatif porte son extension,
// celle du fichier emis.
// import { lignes } from './panier';
// error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './panier.js'?
import { lignes } from './panier.js';
import { arrondir } from 'prix-utils';

// Le champ exports de prix-utils ne publie que "." : le reste du paquet
// n'existe pas, pour Node comme pour TypeScript (bundler le respecte aussi).
// import { TVA } from 'prix-utils/interne/taux.js';
// error TS2307: Cannot find module 'prix-utils/interne/taux.js' or its corresponding type declarations.

console.log(arrondir(lignes[0].prix * 1.2)); // 14.4

// tsconfig.json : "module": "nodenext" ; package.json sans champ "type" :
// pour Node, un .js y est CommonJS.
// src/panier.ts : export const lignes = [{ reference: 'USB-64', prix: 12 }];

// src/main.ts est donc CommonJS : l'import s'emet en require("./panier"), et
// require trouve panier.js sans extension. Le fichier compile et s'execute.
import { lignes } from './panier';

console.log(lignes.length); // 1

// src/outil.mts : l'extension .mts rend le fichier ESM (emis en outil.mjs), quel
// que soit package.json ; .cts rend un fichier CommonJS de la meme facon.
// import { lignes } from './panier';
// error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './panier.js'?

# Meme projet CommonJS ; prix-esm est un paquet ESM ("type": "module").
# src/main.ts : import { TVA } from 'prix-esm';
# src/json.mts : import config from './config.json' with { type: 'json' };
# (chemins abreges)

# "module": "node16"
src/json.mts(1,36): error TS2823: Import attributes are only supported when the '--module' option is set to 'esnext', 'node18', 'node20', 'nodenext', or 'preserve'.
src/main.ts(1,21): error TS1479: The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("prix-esm")' call instead.
  To convert this file to an ECMAScript module, change its file extension to '.mts', or add the field `"type": "module"` to '.../package.json'.

# "module": "node18" : TS2823 disparait, TS1479 reste.
# "module": "node20" ou "nodenext" : tout compile, et Node 24 execute le
# require("prix-esm") emis :
node dist/main.js
0.2

// src/panier.ts : export const lignes = [{ reference: 'USB-64', prix: 12 }];

// "module": "esnext" n'admet que la syntaxe ESM :
// import panier = require('./panier');
// error TS1202: Import assignment cannot be used when targeting ECMAScript modules. Consider using 'import * as ns from "mod"', 'import {a} from "mod"', 'import d from "mod"', or another module format instead.

// "module": "preserve" admet les deux syntaxes dans un meme fichier et les
// emet telles quelles ; c'est au bundler de les meler.
import panier = require('./panier');
import { lignes } from './panier';

console.log(panier.lignes === lignes);

// JavaScript emis :
//   const panier = require("./panier");
//   import { lignes } from './panier';
//   console.log(panier.lignes === lignes);

// node_modules/prix-utils/package.json : exports est une liste blanche.
{
  "name": "prix-utils",
  "type": "module",
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "default": "./index.js"
    }
  }
}

// package.json de l'application : imports declare des alias internes, qui
// commencent toujours par #. Depuis TypeScript 6.0 (nodenext et bundler), un
// alias peut commencer par #/ tout court, comme dans les versions recentes de
// Node : import { TVA } from '#/domaine/prix.js';
{
  "name": "boutique",
  "type": "module",
  "imports": {
    "#/*": "./dist/*"
  }
}

// node_modules/double/package.json : un point d'entree par format d'importeur.
{
  "name": "double",
  "exports": {
    ".": {
      "import": { "types": "./esm.d.mts", "default": "./esm.mjs" },
      "require": { "types": "./cjs.d.cts", "default": "./cjs.cjs" }
    }
  }
}

// esm.d.mts : export declare const format: 'esm';  (cjs.d.cts : 'cjs')
// src/a.mts :
//   import { format } from 'double';
//   const f: 'esm' = format;
// src/b.cts : les memes lignes, avec 'cjs'.

// Sous nodenext, a.mts recoit esm, b.cts recoit cjs : Node 24 affiche esm,
// puis cjs. Sous bundler, un .ts recoit esm : la condition import s'applique.

// La premiere condition qui s'applique gagne, dans l'ordre du fichier. Placee
// en tete, "default" s'applique a tous et masque import :
//   ".": { "default": { ... cjs ... }, "import": { ... esm ... } }
// src/a.mts(2,7): error TS2322: Type '"cjs"' is not assignable to type '"esm"'.

// panier.ts : export interface Ligne { ... } et export function total(...) { ... }
// Sans isolatedModules, tsc accepte ce fichier : il lit panier.ts, sait que
// Ligne est un type, et efface ce qui le concerne.
import { Ligne, total } from './panier';

// Un outil qui transpile fichier par fichier ne lit pas panier.ts : il ne sait
// pas s'il doit garder Ligne dans le JavaScript emis.
export { Ligne, total } from './panier';
// "isolatedModules": true
// error TS1205: Re-exporting a type when 'isolatedModules' is enabled requires using 'export type'.

// "verbatimModuleSyntax": true signale en plus l'import :
// error TS1484: 'Ligne' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.
// error TS1205: Re-exporting a type when 'verbatimModuleSyntax' is enabled requires using 'export type'.

export function resume(lignes: Ligne[]): string {
  return `${lignes.length} ligne(s), ${total(lignes)} EUR`;
}

// "verbatimModuleSyntax": true. Ce qui porte type disparait, le reste est emis
// tel qu'il est ecrit.
import { total } from './panier';
import type { Ligne } from './panier';

export { total } from './panier';
export type { Ligne } from './panier';

export function resume(lignes: Ligne[]): string {
  return `${lignes.length} ligne(s), ${total(lignes)} EUR`;
}

// JavaScript emis :
//   import { total } from './panier';
//   export { total } from './panier';
//   export function resume(lignes) { ... }

// Le modificateur en ligne, import { type Ligne }, efface le nom mais garde la
// declaration : seul, il laisse import {} from './panier', qui charge encore le
// module. import type efface la ligne entiere.

// Un depot npm a deux espaces de travail : package.json racine,
// "workspaces": ["domaine", "app"], et "type": "module" partout.

// domaine/package.json : le paquet publie ce que tsc emet dans dist.
{
  "name": "@boutique/domaine",
  "type": "module",
  "exports": {
    ".": { "types": "./dist/prix.d.ts", "default": "./dist/prix.js" }
  }
}

// domaine/tsconfig.json : un projet reference doit etre composite.
{
  "compilerOptions": {
    "module": "nodenext",
    "composite": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

// app/tsconfig.json : app depend de domaine, pas l'inverse.
{
  "compilerOptions": {
    "module": "nodenext",
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"],
  "references": [{ "path": "../domaine" }]
}

// app/src/main.ts :
//   import { total, type Ligne } from '@boutique/domaine';
//   const lignes: Ligne[] = [{ reference: 'USB-64', prix: 12, quantite: 2 }];
//   console.log(total(lignes));

# tsc -p app, domaine n'ayant jamais ete construit : app lit les .d.ts de
# domaine, qui n'existent pas encore (chemins abreges ici et plus bas).
app/src/main.ts(1,35): error TS2307: Cannot find module '@boutique/domaine' or its corresponding type declarations.

# tsc -b app construit domaine, puis app, dans l'ordre du graphe.
tsc -b app
node app/dist/main.js
24

# Au second appel, rien n'a change ; tsc -b app --verbose dit pourquoi chaque
# projet est saute (horodatage omis) :
Project 'domaine/tsconfig.json' is up to date because newest input 'domaine/src/prix.ts' is older than output 'domaine/tsconfig.tsbuildinfo'

# domaine/src/remise.ts importe '../../app/src/panier.js' : le sens interdit.
domaine/src/remise.ts(1,24): error TS6059: File '.../app/src/panier.ts' is not under 'rootDir' '.../domaine/src'. 'rootDir' is expected to contain all source files.
  File is ECMAScript module because '.../app/package.json' has field "type" with value "module"
domaine/src/remise.ts(1,24): error TS6307: File '.../app/src/panier.ts' is not listed within the file list of project '.../domaine/tsconfig.json'. Projects must list all files or use an 'include' pattern.
  File is ECMAScript module because '.../app/package.json' has field "type" with value "module"

# Et une reference de domaine vers app forme un cycle :
error TS6202: Project references may not form a circular graph. Cycle detected: .../app/tsconfig.json
.../domaine/tsconfig.json

# tsc 6.0. rootDir vaut desormais le dossier du tsconfig.json : avec les sources
# dans src/ et "outDir": "dist", la sortie irait dans dist/src/.
tsconfig.json(1,24): error TS5011: The common source directory of 'tsconfig.json' is './src'. The 'rootDir' setting must be explicitly set to this or another path to adjust your output's file layout.
  Visit https://aka.ms/ts6 for migration information.

# types vaut [] : les paquets @types ne sont plus charges d'office.
src/spec.ts(1,1): error TS2593: Cannot find name 'describe'. Do you need to install type definitions for a test runner? Try `npm i --save-dev @types/jest` or `npm i --save-dev @types/mocha` and then add 'jest' or 'mocha' to the types field in your tsconfig.

# noUncheckedSideEffectImports vaut true : import './polyfils' (faute de frappe).
src/effet.ts(1,8): error TS2882: Cannot find module or type declarations for side-effect import of './polyfils'.

# tsc fichier.ts, dans un dossier qui contient un tsconfig.json :
error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error.

// Un tsconfig.json courant il y a quelques annees, compile par tsc 6.0.
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node",
    "baseUrl": "./src",
    "esModuleInterop": false,
    "downlevelIteration": true,
    "alwaysStrict": false,
    "outDir": "dist"
  }
}

// tsconfig.json(3,15): error TS5107: Option 'target=ES5' is deprecated and will stop functioning in TypeScript 7.0. Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.
// tsconfig.json(5,25): error TS5107: Option 'moduleResolution=node10' is deprecated and will stop functioning in TypeScript 7.0. Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.
//   Visit https://aka.ms/ts6 for migration information.
// tsconfig.json(6,5): error TS5101: Option 'baseUrl' is deprecated and will stop functioning in TypeScript 7.0. Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.
//   Visit https://aka.ms/ts6 for migration information.
// tsconfig.json(7,24): error TS5107: Option 'esModuleInterop=false' is deprecated and will stop functioning in TypeScript 7.0. Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.
// tsconfig.json(8,5): error TS5101: Option 'downlevelIteration' is deprecated and will stop functioning in TypeScript 7.0. Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.
// tsconfig.json(9,21): error TS5107: Option 'alwaysStrict=false' is deprecated and will stop functioning in TypeScript 7.0. Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.

// Meme message pour outFile (TS5101), module amd, umd, system et none, et
// moduleResolution classic (TS5107).