Shared Domain Library

Una librería de dominio compartido para el ecosistema de microservicios financieros, implementada con Clean Architecture y principios de Domain-Driven Design (DDD).

🚀 Características

• Clean Architecture: Separación clara entre dominio, infraestructura y utilidades
• Domain-Driven Design: Value Objects, servicios de dominio y errores especializados
• TypeScript: Completamente tipado con soporte para IntelliSense
• Validación: Utilidades y DTOs con validación integrada usando class-validator
• Testing: Configuración completa con Jest para pruebas unitarias
• Linting: ESLint y Prettier configurados para mantener calidad de código

📦 Instalación

npm install @financial-ecosystem/shared-domain

🏗️ Estructura del Proyecto

src/
├── domain/                     # Capa de dominio
│   ├── errors/                # Errores de dominio especializados
│   ├── services/              # Servicios de dominio
│   └── value-objects/         # Value Objects organizados por categoría
│       ├── primitives/        # Primitivos básicos (ID, Email, etc.)
│       ├── common/            # Comunes (Address, ContactInfo, etc.)
│       └── financial/         # Financieros (Money, Currency, etc.)
├── infrastructure/            # Capa de infraestructura
│   ├── mappers/              # Mapeadores de datos
│   └── services/             # Servicios de infraestructura
├── utils/                    # Utilidades generales
│   ├── date.utils.ts         # Utilidades de fechas
│   ├── string.utils.ts       # Utilidades de strings
│   └── validation.utils.ts   # Utilidades de validación
└── dto/                      # Data Transfer Objects
    ├── base.dto.ts           # DTOs base y de respuesta
    └── validation.dto.ts     # Validadores personalizados

🎯 Uso

Value Objects

import { Money, Currency, Email, PersonName } from '@financial-ecosystem/shared-domain';

// Crear objetos de valor
const currency = new Currency('USD');
const amount = new Money(100.5, currency);
const email = new Email('[email protected]');
const name = new PersonName('John', 'Doe');

// Operaciones con Money
const otherAmount = new Money(50.25, currency);
const total = amount.add(otherAmount); // $150.75 USD

Utilidades

import { StringUtils, DateUtils, ValidationUtils } from '@financial-ecosystem/shared-domain';

// Utilidades de strings
const slug = StringUtils.slugify('Hello World!'); // "hello-world"
const masked = StringUtils.maskEmail('[email protected]'); // "*[email protected]"

// Utilidades de fechas
const nextWorkingDay = DateUtils.getNextWorkingDay(new Date());
const age = DateUtils.getAge(new Date('1990-01-01'));

// Validaciones
const isValid = ValidationUtils.isEmail('[email protected]'); // true
const isStrong = ValidationUtils.isPasswordStrong('P@ssw0rd123'); // true

DTOs y Validaciones

import {
  BaseDto,
  PaginationDto,
  ResponseDto,
  ValidationUtils,
} from '@financial-ecosystem/shared-domain';

// DTO de respuesta
const response = ResponseDto.success(data, 'Operation completed');

// DTO de paginación
const pagination = new PaginationDto();
pagination.page = 1;
pagination.limit = 10;

Servicios

import { ValidationService, CacheService } from '@financial-ecosystem/shared-domain';

// Servicio de validación
const validationService = new ValidationService();
const isValidEmail = validationService.validateEmail('[email protected]');

// Servicio de cache
const cacheService = new CacheService();
cacheService.set('key', 'value', 3600); // Cache por 1 hora
const value = cacheService.get('key');

Errores de Dominio

import {
  ValidationError,
  BusinessRuleError,
  NotFoundError,
} from '@financial-ecosystem/shared-domain';

// Lanzar errores específicos
throw new ValidationError('Invalid email format', 'INVALID_EMAIL');
throw new BusinessRuleError('Insufficient funds');
throw new NotFoundError('User not found');

🧪 Testing

La librería incluye pruebas unitarias completas:

# Ejecutar pruebas
npm test

# Ejecutar pruebas con coverage
npm run test:coverage

# Ejecutar pruebas en modo watch
npm run test:watch

🔧 Desarrollo

Scripts Disponibles

# Compilar la librería
npm run build

# Ejecutar linting
npm run lint

# Ejecutar formatting
npm run format

# Limpiar archivos generados
npm run clean

Configuración TypeScript

El proyecto está configurado con:

• Strict mode habilitado
• Decorators experimentales
• Resolución de módulos Node
• Target ES2020

📋 Convenciones

Naming

• Classes: PascalCase (PersonName, ValidationService)
• Interfaces: PascalCase con prefijo I (IRepository, IValidator)
• Methods: camelCase (validateEmail, formatCurrency)
• Constants: SCREAMING_SNAKE_CASE (MAX_RETRY_ATTEMPTS)

Value Objects

• Inmutables por diseño
• Incluyen validación en el constructor
• Implementan método equals() para comparación
• Proporcionan métodos de acceso tipo getter

Errores

• Heredan de clases base específicas
• Incluyen código de error único
• Proporcionan contexto adicional cuando es relevante

🔄 Versionado

Este proyecto sigue Semantic Versioning:

• MAJOR: Cambios incompatibles en la API
• MINOR: Nueva funcionalidad compatible hacia atrás
• PATCH: Correcciones de bugs compatibles

🤝 Contribución

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -m 'Add: nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abre un Pull Request

Commits Convencionales

Seguimos la convención de Conventional Commits:

feat: añadir nuevo value object Money
fix: corregir validación de email
docs: actualizar README
test: añadir pruebas para StringUtils
refactor: mejorar estructura de errores

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

🔗 Links Relacionados

• Documentación de Arquitectura
• Guía de Utilidades Compartidas
• Proceso de Versionado

📞 Soporte

Para preguntas y soporte:

• Crear un Issue
• Contactar al equipo de arquitectura

Nota: Esta librería está diseñada específicamente para el ecosistema de microservicios financieros y sigue los patrones establecidos en la documentación de arquitectura del proyecto.