M

MLOG

Français

Maîtrisez les vérifications de propriétés en excès de TypeScript pour prévenir les erreurs d'exécution et renforcer la sécurité des types pour des applications robustes.

Vérifications des propriétés en excès de TypeScript : Renforcer la sécurité de vos types d'objets

Dans le domaine du développement logiciel moderne, en particulier avec JavaScript, garantir l'intégrité et la prévisibilité de votre code est primordial. Bien que JavaScript offre une immense flexibilité, il peut parfois entraîner des erreurs d'exécution dues à des structures de données inattendues ou à des inadéquations de propriétés. C'est là que TypeScript brille, en fournissant des capacités de typage statique qui interceptent de nombreuses erreurs courantes avant qu'elles ne se manifestent en production. L'une des fonctionnalités les plus puissantes mais parfois mal comprises de TypeScript est sa vérification des propriétés en excès.

Cet article explore en profondeur les vérifications des propriétés en excès de TypeScript, expliquant ce qu'elles sont, pourquoi elles sont cruciales pour la sécurité des types d'objets, et comment les utiliser efficacement pour construire des applications plus robustes et prévisibles. Nous examinerons divers scénarios, pièges courants et meilleures pratiques pour aider les développeurs du monde entier, quel que soit leur parcours, à exploiter ce mécanisme vital de TypeScript.

Comprendre le concept de base : Que sont les vérifications des propriétés en excès ?

Au cœur de son fonctionnement, la vérification des propriétés en excès de TypeScript est un mécanisme du compilateur qui vous empêche d'assigner un littéral d'objet à une variable dont le type n'autorise pas explicitement ces propriétés supplémentaires. En termes plus simples, si vous définissez un littéral d'objet et essayez de l'assigner à une variable avec une définition de type spécifique (comme une interface ou un alias de type), et que ce littéral contient des propriétés non déclarées dans le type défini, TypeScript le signalera comme une erreur lors de la compilation.

Illustrons cela avec un exemple simple :


interface User {
  name: string;
  age: number;
}

const newUser: User = {
  name: 'Alice',
  age: 30,
  email: 'alice@example.com' // Erreur : Le littéral d'objet ne peut spécifier que des propriétés connues, et 'email' n'existe pas dans le type 'User'.
};

Dans cet extrait, nous définissons une interface nommée User avec deux propriétés : name et age. Lorsque nous tentons de créer un littéral d'objet avec une propriété additionnelle, email, et de l'assigner à une variable typée comme User, TypeScript détecte immédiatement l'inadéquation. La propriété email est une propriété 'en excès' car elle n'est pas définie dans l'interface User. Cette vérification est effectuée spécifiquement lorsque vous utilisez un littéral d'objet pour une assignation.

Pourquoi les vérifications des propriétés en excès sont-elles importantes ?

L'importance des vérifications des propriétés en excès réside dans leur capacité à faire respecter un contrat entre vos données et leur structure attendue. Elles contribuent à la sécurité des types d'objets de plusieurs manières critiques :

Quand les vérifications des propriétés en excès s'appliquent-elles ?

Il est crucial de comprendre les conditions spécifiques dans lesquelles TypeScript effectue ces vérifications. Elles sont principalement appliquées aux littéraux d'objet lorsqu'ils sont assignés à une variable ou passés comme argument à une fonction.

Scénario 1 : Assignation de littéraux d'objet à des variables

Comme vu dans l'exemple User ci-dessus, l'assignation directe d'un littéral d'objet avec des propriétés supplémentaires à une variable typée déclenche la vérification.

Scénario 2 : Passage de littéraux d'objet à des fonctions

Lorsqu'une fonction attend un argument d'un type spécifique, et que vous passez un littéral d'objet qui contient des propriétés en excès, TypeScript le signalera.


interface Product {
  id: number;
  name: string;
}

function displayProduct(product: Product): void {
  console.log(`Product ID: ${product.id}, Name: ${product.name}`);
}

displayProduct({
  id: 101,
  name: 'Laptop',
  price: 1200 // Erreur : L'argument de type '{ id: number; name: string; price: number; }' n'est pas assignable au paramètre de type 'Product'.
             // Le littéral d'objet ne peut spécifier que des propriétés connues, et 'price' n'existe pas dans le type 'Product'.
});

Ici, la propriété price dans le littéral d'objet passé à displayProduct est une propriété en excès, car l'interface Product ne la définit pas.

Quand les vérifications des propriétés en excès ne s'appliquent-elles *pas* ?

Comprendre quand ces vérifications sont contournées est tout aussi important pour éviter la confusion et savoir quand vous pourriez avoir besoin de stratégies alternatives.

1. Lorsqu'on n'utilise pas de littéraux d'objet pour l'assignation

Si vous assignez un objet qui n'est pas un littéral d'objet (par exemple, une variable qui contient déjà un objet), la vérification des propriétés en excès est généralement contournée.


interface Config {
  timeout: number;
}

function setupConfig(config: Config) {
  console.log(`Timeout set to: ${config.timeout}`);
}

const userProvidedConfig = {
  timeout: 5000,
  retries: 3 // Cette propriété 'retries' est une propriété en excès selon 'Config'
};

setupConfig(userProvidedConfig); // Pas d'erreur !

// Même si userProvidedConfig a une propriété supplémentaire, la vérification est ignorée
// car ce n'est pas un littéral d'objet qui est directement passé.
// TypeScript vérifie le type de userProvidedConfig lui-même.
// Si userProvidedConfig était déclaré avec le type Config, une erreur se produirait plus tôt.
// Cependant, s'il est déclaré comme 'any' ou un type plus large, l'erreur est différée.

// Une manière plus précise de montrer le contournement :
let anotherConfig;

if (Math.random() > 0.5) {
  anotherConfig = {
    timeout: 1000,
    host: 'localhost' // Propriété en excès
  };
} else {
  anotherConfig = {
    timeout: 2000,
    port: 8080 // Propriété en excès
  };
}

setupConfig(anotherConfig as Config); // Pas d'erreur en raison de l'assertion de type et du contournement

// La clé est que 'anotherConfig' n'est pas un littéral d'objet au moment de l'assignation à setupConfig.
// Si nous avions une variable intermédiaire typée comme 'Config', l'assignation initiale échouerait.

// Exemple de variable intermédiaire :
let intermediateConfig: Config;

intermediateConfig = {
  timeout: 3000,
  logging: true // Erreur : Le littéral d'objet ne peut spécifier que des propriétés connues, et 'logging' n'existe pas dans le type 'Config'.
};

Dans le premier exemple setupConfig(userProvidedConfig), userProvidedConfig est une variable contenant un objet. TypeScript vérifie si userProvidedConfig dans son ensemble est conforme au type Config. Il n'applique pas la vérification stricte du littéral d'objet à userProvidedConfig lui-même. Si userProvidedConfig avait été déclaré avec un type qui ne correspondait pas à Config, une erreur se serait produite lors de sa déclaration ou de son assignation. Le contournement se produit parce que l'objet est déjà créé et assigné à une variable avant d'être passé à la fonction.

2. Assertions de type

Vous pouvez contourner les vérifications des propriétés en excès en utilisant des assertions de type, bien que cela doive être fait avec prudence car cela supplante les garanties de sécurité de TypeScript.


interface Settings {
  theme: 'dark' | 'light';
}

const mySettings = {
  theme: 'dark',
  fontSize: 14 // Propriété en excès
} as Settings;

// Pas d'erreur ici à cause de l'assertion de type.
// Nous disons à TypeScript : "Fais-moi confiance, cet objet est conforme à Settings."
console.log(mySettings.theme);
// console.log(mySettings.fontSize); // Cela provoquerait une erreur d'exécution si fontSize n'était pas réellement là.

3. Utilisation de signatures d'index ou de la syntaxe de décomposition dans les définitions de type

Si votre interface ou votre alias de type autorise explicitement des propriétés arbitraires, les vérifications des propriétés en excès ne s'appliqueront pas.

Utilisation de signatures d'index :


interface FlexibleObject {
  id: number;
  [key: string]: any; // Autorise toute clé de type chaîne avec n'importe quelle valeur
}

const flexibleItem: FlexibleObject = {
  id: 1,
  name: 'Widget',
  version: '1.0.0'
};

// Pas d'erreur car 'name' et 'version' sont autorisés par la signature d'index.
console.log(flexibleItem.name);

Utilisation de la syntaxe de décomposition dans les définitions de type (moins courant pour contourner directement les vérifications, plus pour définir des types compatibles) :

Bien que ce ne soit pas un contournement direct, la décomposition (spread) permet de créer de nouveaux objets qui incorporent des propriétés existantes, et la vérification s'applique au nouveau littéral formé.

4. Utilisation de Object.assign() ou de la syntaxe de décomposition pour la fusion

Lorsque vous utilisez Object.assign() ou la syntaxe de décomposition (...) pour fusionner des objets, la vérification des propriétés en excès se comporte différemment. Elle s'applique au littéral d'objet résultant qui est formé.


interface BaseConfig {
  host: string;
}

interface ExtendedConfig extends BaseConfig {
  port: number;
}

const defaultConfig: BaseConfig = {
  host: 'localhost'
};

const userConfig = {
  port: 8080,
  timeout: 5000 // Propriété en excès par rapport à BaseConfig, mais attendue par le type fusionné
};

// Décomposition dans un nouveau littéral d'objet conforme à ExtendedConfig
const finalConfig: ExtendedConfig = {
  ...defaultConfig,
  ...userConfig
};

// C'est généralement acceptable car 'finalConfig' est déclaré comme 'ExtendedConfig'
// et les propriétés correspondent. La vérification porte sur le type de 'finalConfig'.

// Considérons un scénario où cela échouerait :

interface SmallConfig {
  key: string;
}

const data1 = { key: 'abc', value: 123 }; // 'value' est en trop ici
const data2 = { key: 'xyz', status: 'active' }; // 'status' est en trop ici

// Tentative d'assignation à un type qui n'accepte pas les extras

// const combined: SmallConfig = {
//   ...data1, // Erreur : Le littéral d'objet ne peut spécifier que des propriétés connues, et 'value' n'existe pas dans le type 'SmallConfig'.
//   ...data2  // Erreur : Le littéral d'objet ne peut spécifier que des propriétés connues, et 'status' n'existe pas dans le type 'SmallConfig'.
// };

// L'erreur se produit parce que le littéral d'objet formé par la syntaxe de décomposition
// contient des propriétés ('value', 'status') non présentes dans 'SmallConfig'.

// Si nous créons une variable intermédiaire avec un type plus large :

const temp: any = {
  ...data1,
  ...data2
};

// Ensuite, en assignant à SmallConfig, la vérification des propriétés en excès est contournée lors de la création du littéral initial,
// mais la vérification de type lors de l'assignation pourrait toujours se produire si le type de temp est inféré plus strictement.
// Cependant, si temp est 'any', aucune vérification ne se produit jusqu'à l'assignation à 'combined'.

// Affinons la compréhension de la décomposition avec les vérifications de propriétés en excès :
// La vérification a lieu lorsque le littéral d'objet créé par la syntaxe de décomposition est assigné
// à une variable ou passé à une fonction qui attend un type plus spécifique.

interface SpecificShape { 
  id: number;
}

const objA = { id: 1, extra1: 'hello' };
const objB = { id: 2, extra2: 'world' };

// Cela échouera si SpecificShape n'autorise pas 'extra1' ou 'extra2' :
// const merged: SpecificShape = {
//   ...objA,
//   ...objB
// };

// La raison de l'échec est que la syntaxe de décomposition crée effectivement un nouveau littéral d'objet.
// Si objA et objB avaient des clés qui se chevauchaient, la dernière l'emporterait. Le compilateur
// voit ce littéral résultant et le vérifie par rapport à 'SpecificShape'.

// Pour que cela fonctionne, vous pourriez avoir besoin d'une étape intermédiaire ou d'un type plus permissif :

const tempObj = {
  ...objA,
  ...objB
};

// Maintenant, si tempObj a des propriétés qui ne sont pas dans SpecificShape, l'assignation échouera :
// const mergedCorrected: SpecificShape = tempObj; // Erreur : Le littéral d'objet ne peut spécifier que des propriétés connues...

// La clé est que le compilateur analyse la forme du littéral d'objet en cours de formation.
// Si ce littéral contient des propriétés non définies dans le type cible, c'est une erreur.

// Le cas d'utilisation typique de la syntaxe de décomposition avec les vérifications de propriétés en excès :

interface UserProfile {
  userId: string;
  username: string;
}

interface AdminProfile extends UserProfile {
  adminLevel: number;
}

const baseUserData: UserProfile = {
  userId: 'user-123',
  username: 'coder'
};

const adminData = {
  adminLevel: 5,
  lastLogin: '2023-10-27'
};

// C'est ici que la vérification des propriétés en excès est pertinente :
// const adminProfile: AdminProfile = {
//   ...baseUserData,
//   ...adminData // Erreur : Le littéral d'objet ne peut spécifier que des propriétés connues, et 'lastLogin' n'existe pas dans le type 'AdminProfile'.
// };

// Le littéral d'objet créé par la décomposition a 'lastLogin', qui n'est pas dans 'AdminProfile'.
// Pour corriger cela, 'adminData' devrait idéalement être conforme à AdminProfile ou la propriété en excès devrait être gérée.

// Approche corrigée :
const validAdminData = {
  adminLevel: 5
};

const adminProfileCorrect: AdminProfile = {
  ...baseUserData,
  ...validAdminData
};

console.log(adminProfileCorrect.userId);
console.log(adminProfileCorrect.adminLevel);

La vérification des propriétés en excès s'applique au littéral d'objet résultant créé par la syntaxe de décomposition. Si ce littéral résultant contient des propriétés non déclarées dans le type cible, TypeScript signalera une erreur.

Stratégies pour gérer les propriétés en excès

Bien que les vérifications des propriétés en excès soient bénéfiques, il existe des scénarios légitimes où vous pourriez avoir des propriétés supplémentaires que vous souhaitez inclure ou traiter différemment. Voici des stratégies courantes :

1. Propriétés "rest" avec des alias de type ou des interfaces

Vous pouvez utiliser la syntaxe des paramètres "rest" (...rest) dans les alias de type ou les interfaces pour capturer toutes les propriétés restantes qui ne sont pas explicitement définies. C'est une manière propre de reconnaître et de collecter ces propriétés en excès.


interface UserProfile {
  id: number;
  name: string;
}

interface UserWithMetadata extends UserProfile {
  metadata: {
    [key: string]: any;
  };
}

// Ou plus couramment avec un alias de type et la syntaxe rest :
type UserProfileWithMetadata = UserProfile & {
  [key: string]: any;
};

const user1: UserProfileWithMetadata = {
  id: 1,
  name: 'Bob',
  email: 'bob@example.com',
  isAdmin: true
};

// Pas d'erreur, car 'email' et 'isAdmin' sont capturés par la signature d'index dans UserProfileWithMetadata.
console.log(user1.email);
console.log(user1.isAdmin);

// Une autre manière en utilisant les paramètres rest dans une définition de type :
interface ConfigWithRest {
  apiUrl: string;
  timeout?: number;
  // Capture toutes les autres propriétés dans 'extraConfig'
  [key: string]: any;
}

const appConfig: ConfigWithRest = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
  featureFlags: {
    newUI: true,
    betaFeatures: false
  }
};

console.log(appConfig.featureFlags);

Utiliser [key: string]: any; ou des signatures d'index similaires est la manière idiomatique de gérer des propriétés supplémentaires arbitraires.

2. Déstructuration avec la syntaxe "rest"

Lorsque vous recevez un objet et que vous devez en extraire des propriétés spécifiques tout en gardant le reste, la déstructuration avec la syntaxe "rest" est inestimable.


interface Employee {
  employeeId: string;
  department: string;
}

function processEmployeeData(data: Employee & { [key: string]: any }) {
  const { employeeId, department, ...otherDetails } = data;

  console.log(`Employee ID: ${employeeId}`);
  console.log(`Department: ${department}`);
  console.log('Other details:', otherDetails);
  // otherDetails contiendra toutes les propriétés non explicitement déstructurées,
  // comme 'salary', 'startDate', etc.
}

const employeeInfo = {
  employeeId: 'emp-789',
  department: 'Engineering',
  salary: 90000,
  startDate: '2022-01-15'
};

processEmployeeData(employeeInfo);

// Même si employeeInfo avait une propriété supplémentaire au départ, la vérification des propriétés en excès
// est contournée si la signature de la fonction l'accepte (par exemple, en utilisant une signature d'index).
// Si processEmployeeData était typé strictement comme 'Employee', et que employeeInfo avait 'salary',
// une erreur se produirait SI employeeInfo était un littéral d'objet passé directement.
// Mais ici, employeeInfo est une variable, et le type de la fonction gère les extras.

3. Définir explicitement toutes les propriétés (si elles sont connues)

Si vous connaissez les propriétés supplémentaires potentielles, la meilleure approche est de les ajouter à votre interface ou alias de type. Cela offre la plus grande sécurité de type.


interface UserProfile {
  id: number;
  name: string;
  email?: string; // email optionnel
}

const userWithEmail: UserProfile = {
  id: 2,
  name: 'Charlie',
  email: 'charlie@example.com'
};

const userWithoutEmail: UserProfile = {
  id: 3,
  name: 'David'
};

// Si nous essayons d'ajouter une propriété non présente dans UserProfile :
// const userWithExtra: UserProfile = {
//   id: 4,
//   name: 'Eve',
//   phoneNumber: '555-1234'
// }; // Erreur : Le littéral d'objet ne peut spécifier que des propriétés connues, et 'phoneNumber' n'existe pas dans le type 'UserProfile'.

4. Utiliser as pour les assertions de type (avec prudence)

Comme montré précédemment, les assertions de type peuvent supprimer les vérifications des propriétés en excès. Utilisez-les avec parcimonie et uniquement lorsque vous êtes absolument certain de la forme de l'objet.


interface ProductConfig {
  id: string;
  version: string;
}

// Imaginez que cela vienne d'une source externe ou d'un module moins strict
const externalConfig = {
  id: 'prod-abc',
  version: '1.2',
  debugMode: true // Propriété en excès
};

// Si vous savez que 'externalConfig' aura toujours 'id' et 'version' et que vous voulez le traiter comme ProductConfig :
const productConfig = externalConfig as ProductConfig;

// Cette assertion contourne la vérification des propriétés en excès sur `externalConfig` lui-même.
// Cependant, si vous passiez un littéral d'objet directement :

// const productConfigLiteral: ProductConfig = {
//   id: 'prod-xyz',
//   version: '2.0',
//   debugMode: false
// }; // Erreur : Le littéral d'objet ne peut spécifier que des propriétés connues, et 'debugMode' n'existe pas dans le type 'ProductConfig'.

5. Gardes de type

Pour des scénarios plus complexes, les gardes de type (type guards) peuvent aider à affiner les types et à gérer les propriétés de manière conditionnelle.


interface Shape {
  kind: 'circle' | 'square';
}

interface Circle extends Shape {
  kind: 'circle';
  radius: number;
}

interface Square extends Shape {
  kind: 'square';
  sideLength: number;
}

function calculateArea(shape: Shape) {
  if (shape.kind === 'circle') {
    // TypeScript sait que 'shape' est un Circle ici
    console.log(Math.PI * shape.radius ** 2);
  } else if (shape.kind === 'square') {
    // TypeScript sait que 'shape' est un Square ici
    console.log(shape.sideLength ** 2);
  }
}

const circleData = {
  kind: 'circle' as const, // Utilisation de 'as const' pour l'inférence de type littéral
  radius: 10,
  color: 'red' // Propriété en excès
};

// Lorsqu'il est passé à calculateArea, la signature de la fonction attend 'Shape'.
// La fonction elle-même accédera correctement à 'kind'.
// Si calculateArea attendait 'Circle' directement et recevait circleData
// en tant que littéral d'objet, 'color' serait un problème.

// Illustrons la vérification des propriétés en excès avec une fonction attendant un sous-type spécifique :

function processCircle(circle: Circle) {
  console.log(`Processing circle with radius: ${circle.radius}`);
}

// processCircle(circleData); // Erreur : L'argument de type '{ kind: "circle"; radius: number; color: string; }' n'est pas assignable au paramètre de type 'Circle'.
                         // Le littéral d'objet ne peut spécifier que des propriétés connues, et 'color' n'existe pas dans le type 'Circle'.

// Pour corriger cela, vous pouvez déstructurer ou utiliser un type plus permissif pour circleData :

const { color, ...circleDataWithoutColor } = circleData;
processCircle(circleDataWithoutColor);

// Ou définir circleData pour inclure un type plus large :

const circleDataWithExtras: Circle & { [key: string]: any } = {
  kind: 'circle',
  radius: 15,
  color: 'blue'
};
processCircle(circleDataWithExtras); // Maintenant, ça fonctionne.

Pièges courants et comment les éviter

Même les développeurs expérimentés peuvent parfois être surpris par les vérifications des propriétés en excès. Voici les pièges courants :

Considérations globales et meilleures pratiques

Lorsque l'on travaille dans un environnement de développement mondial et diversifié, il est crucial de respecter des pratiques cohérentes en matière de sécurité des types :

Conclusion

Les vérifications des propriétés en excès de TypeScript sont une pierre angulaire de sa capacité à fournir une sécurité robuste des types d'objets. En comprenant quand et pourquoi ces vérifications se produisent, les développeurs peuvent écrire un code plus prévisible et moins sujet aux erreurs.

Pour les développeurs du monde entier, adopter cette fonctionnalité signifie moins de surprises à l'exécution, une collaboration plus facile et des bases de code plus maintenables. Que vous construisiez un petit utilitaire ou une application d'entreprise à grande échelle, la maîtrise des vérifications des propriétés en excès élèvera sans aucun doute la qualité et la fiabilité de vos projets JavaScript.

Points clés à retenir :

En appliquant consciemment ces principes, vous pouvez améliorer de manière significative la sécurité et la maintenabilité de votre code TypeScript, menant à des résultats plus réussis dans le développement de logiciels.