Aller au contenu principal

Sphalma

σφάλμα - « erreur »

Fabriques d'erreurs typées avec codes hexadécimaux. Créez des erreurs structurées et identifiables pour le debugging et le logging.

Sphalma fournit un moyen systématique de créer et gérer les erreurs applicatives. Au lieu de disperser des new Error() dans votre codebase, vous définissez les codes d'erreur en amont et créez des fabriques typées qui produisent des erreurs cohérentes et identifiables. Chaque erreur porte un code numérique, un label de type et des détails optionnels, facilitant le traçage dans les logs et la correspondance avec des messages utilisateur. La classe CodedError étend Error avec des métadonnées structurées.

Quelques exemples​

Définissez vos codes d'erreur comme des constantes hexadécimales pour la lisibilité, puis créez une fabrique typée. Chaque erreur produite par la fabrique inclut une clé structurée comme [Api:0x1001] instantanément recherchable dans les logs :

import { createErrorFactory, CodedError } from "pithos/sphalma/error-factory";

// Définir les codes d'erreur (hex pour la lisibilité)
const ErrorCodes = {
  NOT_FOUND: 0x1001,
  INVALID_INPUT: 0x1002,
} as const;

// Créer une fabrique typée
const createApiError = createErrorFactory<0x1001 | 0x1002>("Api");

// Lancer des erreurs structurées
throw createApiError(ErrorCodes.NOT_FOUND, { id: "user-123" });
// Error: [Api:0x1001] avec details.id = "user-123"
i18n

Les codes structurés comme [Api:0x1001] simplifient l'internationalisation : associez chaque code à un message traduit, et votre gestion d'erreurs reste indépendante de la langue.

CodedError​

CodedError est la classe d'erreur structurée au cœur de Sphalma. Elle étend le Error natif avec un code numérique, un label de type et un objet de détails optionnel. La propriété key combine type et code en un identifiant unique pour le filtrage et la recherche :

import { CodedError } from "pithos/sphalma/error-factory";

const error = new CodedError(0x2000, "Semaphore", { count: -1 });

error.code;    // 0x2000 (8192)
error.type;    // "Semaphore"
error.key;     // "Semaphore:0x2000"
error.details; // { count: -1 }
error.message; // "[Semaphore:0x2000]"

Convention de codes d'erreur​

Pithos utilise un format hexadécimal à 4 chiffres : 0xMFEE

0x M F EE
   │  │  └── Erreur (00-FF) → 256 erreurs par fonctionnalité
   │  └── Fonctionnalité (0-F) → 16 fonctionnalités par module
   └── Module (1-F) → 15 modules

Les plages de codes sont documentées dans chaque module utilisant Sphalma.

Intégration avec Zygos​

Sphalma se combine naturellement avec les types Result de Zygos pour la gestion fonctionnelle des erreurs. Au lieu de lancer des erreurs, retournez-les comme des valeurs Err typées. Cela rend chaque chemin d'échec visible dans la signature de la fonction :

import { createErrorFactory } from "pithos/sphalma/error-factory";
import { ok, err, Result } from "pithos/zygos/result/result";

const createUserError = createErrorFactory<0x3001 | 0x3002>("User");

function getUser(id: string): Result<User, CodedError> {
  if (!id) return err(createUserError(0x3001, { reason: "ID vide" }));
  // ...
  return ok(user);
}

Quand l'utiliser​

Sphalma est le plus utile dans les projets où les erreurs doivent être catégorisées, suivies et communiquées à travers les frontières du système :

  • Erreurs de module → Codes d'erreur cohérents à travers un module
  • Erreurs API → Le frontend peut mapper les codes vers des messages UI
  • Debugging → [Animation:0x1001] est instantanément identifiable dans les logs

Quand NE PAS l'utiliser​

Pour les cas d'erreur simples ou les patterns de gestion d'erreurs spécialisés, considérez ces alternatives :

BesoinUtilisez plutôt
Throw simpleError, TypeError, RangeError natifs
Erreurs de validationKanon
Flux de gestion d'erreursZygos

Fonctionne bien avec​

Voir Alchimie des modules pour découvrir comment Sphalma se combine avec Zygos et Kanon dans des pipelines typés.

Ressources associées