@gymfinity/errors

Un sistema di gestione errori standardizzato per l'ecosistema Gymfinity, con supporto per internazionalizzazione, categorizzazione e documentazione automatica.

Caratteristiche

• 🌍 Supporto multi-lingua per i messaggi di errore
• 🎯 Categorizzazione degli errori per tipo e severità
• 📝 Documentazione automatica degli errori
• 🔍 Metadati estensibili per ogni errore
• 📊 Integrazione con il sistema di logging
• 🛡️ Errori HTTP standardizzati
• 🔄 Serializzazione JSON automatica

Installazione

npm install @gymfinity/errors

Prerequisiti

{
  "peerDependencies": {
    "@gymfinity/logger": "^1.0.0"
  }
}

Casi d'Uso

Caso d'Uso Completo: Gestione Errori in un Microservizio

// src/errors/serviceErrors.ts
import { AppError, ErrorCategory, ErrorCode } from '@gymfinity/errors';

// 1. Definisci errori specifici del servizio
const ServiceErrors = {
  USER_NOT_FOUND: {
    message: 'User not found',
    statusCode: 404,
    category: ErrorCategory.BUSINESS,
    severity: 'LOW',
    metadata: { errorType: 'USER_MANAGEMENT' },
    documentation: 'https://docs.example.com/errors/user-not-found'
  },
  INVALID_PASSWORD: {
    message: 'Invalid password format',
    statusCode: 400,
    category: ErrorCategory.VALIDATION,
    severity: 'LOW',
    metadata: { errorType: 'VALIDATION' },
    documentation: 'https://docs.example.com/errors/invalid-password'
  }
} as const;

// 2. Crea helper per lanciare errori localizzati
export const createServiceError = (
  code: keyof typeof ServiceErrors,
  language: string = 'en',
  additionalMetadata?: Record<string, any>
) => {
  const errorCode = {
    ...ServiceErrors[code],
    message: translateError(code, language)
  };
  return new AppError(errorCode, additionalMetadata);
};

// 3. Usa gli errori nel codice
try {
  const user = await findUser(userId);
  if (!user) {
    throw createServiceError('USER_NOT_FOUND', req.language, {
      userId,
      attemptedAt: new Date()
    });
  }
  
  if (!validatePassword(password)) {
    throw createServiceError('INVALID_PASSWORD', req.language, {
      validationErrors: getPasswordErrors(password)
    });
  }
} catch (error) {
  next(error);
}

Varianti di Implementazione

1. Errori Base con CommonErrorCodes

import { AppError, CommonErrorCodes } from '@gymfinity/errors';

// Usa errori predefiniti
throw new AppError(
  CommonErrorCodes('it').not_found, 
  { resourceId: '123', resourceType: 'user' }
);

2. Errori di Validazione con Dettagli

import { AppError, ErrorCategory } from '@gymfinity/errors';

function validateUserInput(data: unknown) {
  const errors = [];
  // ... logica di validazione
  
  if (errors.length > 0) {
    throw new AppError({
      message: 'Validation failed',
      statusCode: 400,
      category: ErrorCategory.VALIDATION,
      severity: 'LOW',
      metadata: { 
        validationErrors: errors,
        receivedData: data
      }
    });
  }
}

3. Errori di Business Logic

import { AppError, ErrorCategory } from '@gymfinity/errors';

class InsufficientFundsError extends AppError {
  constructor(accountId: string, required: number, available: number) {
    super({
      message: 'Insufficient funds',
      statusCode: 400,
      category: ErrorCategory.BUSINESS,
      severity: 'MEDIUM',
      metadata: {
        accountId,
        required,
        available,
        deficit: required - available
      },
      documentation: 'https://docs.example.com/errors/insufficient-funds'
    });
  }
}

4. Errori di Integrazione

import { AppError, ErrorCategory } from '@gymfinity/errors';

async function externalServiceCall() {
  try {
    // ... chiamata API esterna
  } catch (error) {
    throw new AppError({
      message: 'External service error',
      statusCode: 502,
      category: ErrorCategory.INTEGRATION,
      severity: 'HIGH',
      metadata: {
        service: 'payment-gateway',
        originalError: error.message,
        requestId: error.requestId
      }
    });
  }
}

Configurazione

Categorie di Errore

enum ErrorCategory {
  VALIDATION = 'VALIDATION',
  AUTHENTICATION = 'AUTHENTICATION',
  AUTHORIZATION = 'AUTHORIZATION',
  BUSINESS = 'BUSINESS',
  INFRASTRUCTURE = 'INFRASTRUCTURE',
  INTEGRATION = 'INTEGRATION',
  SYSTEM = 'SYSTEM'
}

Livelli di Severità

type ErrorSeverity = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';

Struttura ErrorCode

interface ErrorCode {
  message: string;
  statusCode: number;
  metadata?: Record<string, any>;
  category: ErrorCategory;
  severity: ErrorSeverity;
  documentation?: string;
}

Best Practices

1. Organizzazione degli Errori

/errors
  /business
    user.errors.ts
    order.errors.ts
  /validation
    input.errors.ts
  /integration
    external.errors.ts
  index.ts

2. Metadati Consistenti

const errorMetadata = {
  requestId: req.id,
  userId: req.user?.id,
  timestamp: new Date().toISOString(),
  environment: process.env.NODE_ENV,
  // Metadati specifici dell'errore
  ...specificMetadata
};

3. Documentazione degli Errori

const errorCode: ErrorCode = {
  // ... altri campi
  documentation: `https://docs.example.com/errors/${category}/${code}`,
  metadata: {
    errorCode: 'USER_001',
    troubleshooting: 'Check user permissions and authentication status'
  }
};

Debug e Troubleshooting

Output JSON Standard

{
  "message": "User not found",
  "statusCode": 404,
  "category": "BUSINESS",
  "severity": "LOW",
  "metadata": {
    "errorType": "USER_MANAGEMENT",
    "userId": "123",
    "attemptedAt": "2024-11-13T21:47:13.262Z"
  },
  "documentation": "https://docs.example.com/errors/user-not-found"
}

Integrazione con Logger

Ogni errore viene automaticamente loggato con:

• Messaggio e stack trace
• Categoria e severità
• Metadati estesi
• Timestamp e contesto
• Link alla documentazione

Licenza

Questo progetto è di proprietà di Gymfinity. Tutti i diritti riservati.