Librería Utilities (Core)

Prioridad: Muy Alta

Propósito: Proveer utilidades transversales reutilizables en todo el monorepo GoGrab, siendo la base fundamental para operaciones comunes en fechas, strings, validaciones, archivos y formato de datos.

Especificación funcional

Esta librería debe proporcionar utilidades organizadas por dominio:

DateUtils:

• Parsing y formateo de fechas
• Cálculos de diferencias temporales
• Validaciones de rangos de fechas
• Conversiones de zona horaria
• Utilities para fechas relativas

StringUtils:

• Formateo y normalización de texto
• Validaciones de formato (email, teléfono, etc.)
• Manipulación de casos (camelCase, kebab-case, etc.)
• Sanitización y escape de caracteres
• Generación de slugs y URLs amigables

Array/ObjectUtils:

• Operaciones funcionales avanzadas
• Transformaciones y mapeos complejos
• Comparaciones profundas
• Clonado y merge de objetos
• Utilities para agrupación y filtrado

ValidationUtils:

• Validadores comunes reutilizables
• Schemas de validación
• Validaciones de negocio específicas
• Utilities para formularios reactivos
• Validaciones asíncronas

FileUtils:

• Upload y download de archivos
• Validación de tipos MIME
• Compresión y redimensionado de imágenes
• Conversiones de formato
• Utilities para drag & drop

CurrencyUtils/NumberUtils:

• Formateo de monedas
• Cálculos financieros precisos
• Conversiones entre divisas
• Formateo de números grandes
• Validaciones numéricas

Estado actual

• Tipo: librería Nx de Angular.
• Ruta de importación: @gograb-space/utilities (configurada en tsconfig.base.json).
• API pública actual: solo barrel src/index.ts.

API pública actual

• Re-export desde: libs/core/utilities/src/index.ts.
• Utilities existe como componente interno placeholder y no constituye una API estable.

Estructura del paquete

• src/lib/utilities/utilities.ts: componente placeholder interno.
• src/index.ts: barrel para futuros exports públicos.

Comandos de mantenimiento

• Ejecutar pruebas: nx test utilities
• Linting: nx lint utilities

Importancia en el ecosistema GoGrab

Esta librería es foundational para toda la plataforma, siendo la primera dependencia que debe implementarse:

• Base para todos los módulos: Prácticamente todos los módulos del sistema requerirán utilidades básicas
• Consistencia: Garantiza comportamientos uniformes para operaciones comunes en todo el monorepo
• Reutilización: Evita duplicación de código y bugs por implementaciones inconsistentes
• Calidad: Centraliza funciones críticas con testing exhaustivo
• Performance: Implementaciones optimizadas de operaciones comunes

Sin estas utilidades, el desarrollo de otros módulos será significativamente más lento y propenso a errores.

Dependencias identificadas

Esta librería será requerida por virtualmente todos los módulos del sistema:

• LogSystem - Para formateo de fechas, validaciones y utilities de string
• EventSystem - Para validaciones y transformaciones de datos
• Autenticación y autorización - Para validaciones, crypto utilities y formateo
• DataAccess - Para transformaciones de datos y validaciones
• UI Framework - Para validators, formatters y utilities de archivos
• I18n - Para formateo de fechas, números y validaciones localizadas
• Module Integrator - Para validaciones de configuración y utilities generales
• Media Asset Management - Para FileUtils y validaciones
• Core App - Para todas las utilities transversales

Dependencias propias: Ninguna - debe ser completamente independiente.

Convenciones para nuevas utilidades (cuando se incorporen)

• Funciones puras y determinísticas; evitar efectos secundarios.
• Tipado explícito y sin any no tipado.
• Cobertura de tests por caso de borde y entradas inválidas.
• Exportación a través del barrel src/index.ts.
• Nombres claros: DateUtils, StringUtils, ArrayUtils, ObjectUtils, ValidationUtils, FileUtils, CurrencyUtils, etc.
• Organización sugerida dentro de src/lib/ (por dominio), por ejemplo:
  • src/lib/date/...
  • src/lib/string/...
  • src/lib/number/...
  • src/lib/validation/...

Roadmap de implementación

Fase 1 - Utilities críticas (Prioridad: Muy Alta)

Objetivo: Funcionalidad básica requerida inmediatamente por otros módulos

• ✅ DateUtils básicos - Formateo, parsing, validaciones
• ✅ StringUtils básicos - Normalización, validaciones, case manipulation
• ✅ ValidationUtils core - Validadores comunes (email, teléfono, etc.)
• ✅ ObjectUtils básicos - Clone, merge, comparaciones
• ✅ ArrayUtils básicos - Operaciones funcionales comunes

Fase 2 - Utilities avanzadas

Objetivo: Funcionalidad completa para desarrollo robusto

• FileUtils completos - Upload, download, validaciones MIME
• CurrencyUtils completos - Formateo, conversiones, cálculos
• DateUtils avanzados - Zonas horarias, rangos complejos
• ValidationUtils avanzados - Schemas, validaciones asíncronas
• StringUtils avanzados - Sanitización, slugs, URLs

Fase 3 - Optimizaciones y herramientas

Objetivo: Performance y herramientas de desarrollo

• Performance optimizations para operaciones pesadas
• Tree-shaking optimizations
• Bundle size analysis
• Documentación interactiva

Estructura propuesta

libs/core/utilities/src/
  index.ts
  lib/
    date/
      date-utils.ts
      date-validators.ts
      timezone-utils.ts
    string/
      string-utils.ts
      string-validators.ts
      slug-utils.ts
    array/
      array-utils.ts
      collection-utils.ts
    object/
      object-utils.ts
      deep-merge.ts
    validation/
      validators.ts
      schemas.ts
      async-validators.ts
    file/
      file-utils.ts
      upload-utils.ts
      mime-utils.ts
    number/
      number-utils.ts
      currency-utils.ts
      format-utils.ts

Próximos pasos críticos

Implementación inmediata requerida

1. Completar Fase 1 - Es bloqueante para todos los demás módulos
2. Testing exhaustivo - Al ser dependencia universal, debe ser extremadamente estable
3. Documentación completa - Para facilitar adopción en todo el equipo

Estado actual crítico

BLOQUEANTE: Esta librería debe implementarse PRIMERO antes que cualquier otro módulo, ya que prácticamente todos dependen de ella.

Orden de implementación recomendado

1. DateUtils y StringUtils - Requeridos por LogSystem
2. ValidationUtils - Requerido por múltiples módulos
3. ObjectUtils y ArrayUtils - Para transformaciones de datos
4. FileUtils - Para Media Asset Management
5. CurrencyUtils - Para módulos de negocio

Estado recomendado: Implementar inmediatamente como primera prioridad del proyecto.

Nota: Al agregar nuevas utilidades, seguir las convenciones anteriores para mantener coherencia y auditabilidad.