String DAC 📚

String Detect And Clean Una librería TypeScript completa para detectar, limpiar y filtrar strings con soporte especial para TTS (Text-to-Speech) y detección de spam.

📋 Índice

• 🚀 Características
• 📦 Instalación
• 📚 Documentación por Módulos
• 💡 Ejemplos Rápidos
• 🔧 Configuración
• 🧪 Testing
• 📝 Licencia

🚀 Características

| Categoría | Características | |-----------|----------------| | Detección | Emojis (incluyendo 🌐🌍🌎🌏), símbolos (★♦♥), caracteres especiales, patrones de spam | | Limpieza | TTS optimizado, eliminación/reemplazo de emojis y símbolos decorativos | | Multiidioma | Inglés (por defecto), español, francés, alemán + personalizable | | Spam Detection | Análisis de patrones, generación de variaciones, filtrado personalizado | | Estadísticas | Análisis detallado de caracteres y porcentajes |

📦 Instalación

npm install string-dac

📚 Documentación por Módulos

🔍 StringDetector - Detección y Limpieza

El módulo principal para detectar y limpiar texto.

Métodos Principales

| Método | Descripción | Parámetros | Retorno | |--------|-------------|------------|---------| | detect(input, options?) | Detecta emojis, símbolos y caracteres especiales | input: string, options?: DetectionOptions | DetectionResult | | clean(input, options?) | Limpia el texto según opciones | input: string, options?: CleaningOptions | string | | hasEmojis(input) | Verifica si hay emojis | input: string | boolean | | hasSymbols(input) | Verifica si hay símbolos | input: string | boolean | | hasSpecialChars(input) | Verifica caracteres especiales | input: string | boolean | | extractEmojis(input) | Extrae todos los emojis | input: string | string[] | | extractSymbols(input) | Extrae todos los símbolos | input: string | string[] | | getCharacterStats(input) | Estadísticas detalladas | input: string | CharacterStats |

DetectionResult

{
  hasEmojis: boolean;
  hasSymbols: boolean;
  hasSpecialChars: boolean;
  emojiCount: number;
  symbolCount: number;
  specialCharCount: number;
  emojiPercentage: number;
  symbolPercentage: number;
  specialCharPercentage: number;
  cleanedString: string;
  totalCharacters: number;
}

🛡️ SpamDetector - Detección de Spam

Detección de spam basada en patrones y análisis estadístico.

Métodos Principales

| Método | Descripción | Parámetros | Retorno | |--------|-------------|------------|---------| | detectSpam(input, options?) | Detecta spam con análisis completo | input: string, options?: SpamDetectionOptions | SpamDetectionResult | | isSpam(input, threshold?, iterations?) | Verificación rápida de spam | input: string, threshold?: number, iterations?: number | boolean | | getSpamScore(input, iterations?) | Obtiene puntuación de spam | input: string, iterations?: number | number |

SpamDetectionResult

{
  isSpam: boolean;
  spamScore: number;
  confidence: number;
  patterns: PatternMatch[];
  variations: SpamVariation[];
  analysis: PatternAnalysisResult;
}

🎯 PatternAnalyzer - Análisis de Patrones

Análisis detallado de patrones en el texto.

Métodos Principales

| Método | Descripción | Parámetros | Retorno | |--------|-------------|------------|---------| | analyze(input, options?) | Analiza patrones en el texto | input: string, options?: PatternAnalysisOptions | PatternAnalysisResult | | getPatternScore(input) | Calcula puntuación de patrones | input: string | number | | findRepetitions(input) | Encuentra repeticiones | input: string | RepetitionResult[] |

🔗 HybridSpamDetector - Detección Híbrida

Combina múltiples métodos de detección para mayor precisión.

Métodos Principales

| Método | Descripción | Parámetros | Retorno | |--------|-------------|------------|---------| | detect(input, options?) | Detección híbrida completa | input: string, options?: HybridSpamOptions | HybridSpamResult | | analyzeWithAllMethods(input) | Análisis con todos los métodos | input: string | CombinedAnalysis |

🎨 SentenceVariationGenerator - Generador de Variaciones

Genera variaciones de texto para pruebas de spam.

Métodos Principales

| Método | Descripción | Parámetros | Retorno | |--------|-------------|------------|---------| | generateVariation(input, options?) | Genera una variación | input: string, options?: VariationOptions | SentenceVariation | | generateVariations(input, count, options?) | Genera múltiples variaciones | input: string, count: number, options?: VariationOptions | SentenceVariation[] |

🔤 WordFilter - Filtro de Palabras

Filtra palabras específicas con detección de duplicados.

Métodos Principales

| Método | Descripción | Parámetros | Retorno | |--------|-------------|------------|---------| | processSentence(sentence) | Procesa una oración y filtra palabras | sentence: string | WordFilterEvent[] | | setWordsToFilter(words) | Establece palabras a filtrar | words: string[] | void | | getStats() | Obtiene estadísticas del filtro | - | FilterStats | | clear() | Limpia el historial | - | void |

🎯 EmojiMapper - Mapeo Inteligente de Emojis

Optimiza el mapeo de emojis seleccionando automáticamente los nombres más cortos y descriptivos.

Características de Optimización

• Selección inteligente: Elige automáticamente la keyword más corta y descriptiva
• Filtrado de keywords no descriptivas: Excluye palabras genéricas como "face", "emoji", "symbol"
• Límite de longitud: Filtra keywords excesivamente largas (>20 caracteres)
• Fallback inteligente: Usa shortName de node-emoji cuando es más corto
• Mapeo hardcodeado optimizado: Incluye mapeos específicos para emojis comunes

Ejemplo de Optimización

// Antes: "smiling_face_with_smiling_eyes" (30 caracteres)
// Después: "happy" (5 caracteres) - más corto y descriptivo

const detector = new StringDetector();
const result = detector.clean('😊 Hello World!', {
  clean: true,
  replaceEmojis: true
});
// Resultado: "[happy] Hello World!"

WordFilterEvent

{
  word: string;
  index: number;
  totalWords: number;
  isDuplicate: boolean;
  isNew: boolean;
  timestamp: number;
}

🎭 LanguagePackManager - Gestión de Idiomas

Gestiona language packs para diferentes idiomas.

Métodos Principales

| Método | Descripción | Parámetros | Retorno | |--------|-------------|------------|---------| | getLanguagePack(language) | Obtiene pack de idioma | language: string | LanguagePack | | getEmotionMapping(language) | Obtiene mapeo de emociones | language: string | EmotionMapping | | createCustomPack(name, emotions) | Crea pack personalizado | name: string, emotions: EmotionMapping | LanguagePack |

💡 Ejemplos Rápidos

Ejemplo 1: Detección Básica

import { StringDetector } from 'string-dac';

const detector = new StringDetector();
const result = detector.detect('Hola 😊 ¿Cómo estás? 👋');

console.log(`Emojis encontrados: ${result.emojiCount}`);
console.log(`Porcentaje de emojis: ${result.emojiPercentage}%`);
console.log(`Limpio: ${result.cleanedString}`); // "Hola [happy] ¿Cómo estás? [wave]"

Ejemplo 2: Limpieza para TTS

const ttsText = detector.clean('¡Hola! 😊 ¿Cómo estás? 🤔', {
  clean: true,
  language: 'es'
});
// Resultado: "¡Hola! [happy] ¿Cómo estás? [thinking]"

Ejemplo 3: Eliminación de caracteres especiales

// Eliminar caracteres especiales incluyendo español e internacionales
const cleaned = detector.clean('¡Hola! ¿Cómo estás? «Bonjour» €100', {
  removeSpecialChars: true
});
// Resultado: "Hola Cómo estás Bonjour 100"

Ejemplo 3: Detección de Spam

import { SpamDetector } from 'string-dac';

const spamDetector = new SpamDetector();
const result = spamDetector.detectSpam('compra ahora gratis limitada', {
  iterations: 100,
  similarityThreshold: 0.8
});

console.log(`¿Es spam? ${result.isSpam}`);
console.log(`Score: ${result.spamScore}`);

Ejemplo 4: Sistema de Filtrado

import { SpamFilterSystem } from 'string-dac';

const filter = new SpamFilterSystem({
  iterations: 10,
  targetWords: ['spam', 'scam', 'fake'],
  wordFilterOptions: {
    caseSensitive: false,
    ignoreDuplicates: true
  }
});

const result = await filter.runFilterSystem('este mensaje contiene spam');
console.log(`Palabras filtradas: ${result.totalFilteredWords}`);

🔧 Configuración

Opciones de Detección

interface DetectionOptions {
  includeEmojis?: boolean;        // default: true
  includeSymbols?: boolean;       // default: true
  includeSpecialChars?: boolean;  // default: true
  threshold?: number;             // default: 0.1
}

Opciones de Limpieza

interface CleaningOptions {
  removeEmojis?: boolean;        // default: false - reemplaza emojis con etiquetas
  replaceEmojis?: boolean;       // default: true - convierte emojis a texto
  removeSymbols?: boolean;       // default: false
  removeSpecialChars?: boolean;  // default: false
  preserveWhitespace?: boolean;  // default: true
  language?: 'en' | 'es' | 'fr' | 'de' | 'custom'; // default: 'en'
  emotionMapping?: { [emoji: string]: string };     // mapeo personalizado de emojis
}

🌍 Comportamiento por Idioma

Por defecto (Inglés):

const detector = new StringDetector();
const text = detector.clean('¡Hola! 😊 ¿Cómo estás? 🤔', { clean: true });
// Resultado: "¡Hola! [happy] ¿Cómo estás? [thinking]"

Español:

const text = detector.clean('¡Hola! 😊 ¿Cómo estás? 🤔', {
  clean: true,
  language: 'es'
});
// NOTA: Actualmente también devuelve: "¡Hola! [happy] ¿Cómo estás? [thinking]"
// Las traducciones de emociones deben implementarse externamente

Eliminar emojis completamente:

const text = detector.clean('¡Hola! 😊 ¿Cómo estás? 🤔', {
  clean: true,
  removeEmojis: true
});
// Resultado: "¡Hola! ¿Cómo estás?"

Opciones de Spam

interface SpamDetectionOptions {
  iterations?: number;           // default: 1000
  similarityThreshold?: number;  // default: 0.8
  randomCharCount?: number;      // default: 1-3
  randomCharTypes?: ('letters' | 'numbers' | 'symbols')[];
  insertionPoints?: ('start' | 'end' | 'random')[];
}

📁 Estructura de Archivos

string-dac/
├── src/
│   ├── core/                    # Módulos principales
│   │   ├── string-detector.ts   # Detector principal
│   │   ├── spam-detector.ts     # Detector de spam
│   │   ├── pattern-analyzer.ts  # Analizador de patrones
│   │   ├── hybrid-spam-detector.ts # Detector híbrido
│   │   ├── sentence-variation-generator.ts # Generador de variaciones
│   │   └── word-filter.ts       # Filtro de palabras
│   ├── language-packs/          # Packs de idiomas
│   ├── types/                   # Definiciones de tipos
│   └── utils/                   # Utilidades
├── examples/                    # Ejemplos y configuraciones
│   ├── default-config.ts        # Configuraciones por defecto
│   ├── spam-filter-system.ts    # Sistema de filtrado completo
│   └── logger.ts               # Sistema de logging
├── test/                       # Tests
└── docs/                       # Documentación adicional

🧪 Testing

# Ejecutar todos los tests
npm test

# Ejecutar tests específicos
npm test StringDetector
npm test SpamDetector
npm test SpamFilterSystem

# Ver cobertura
npm test -- --coverage

📝 Licencia

MIT License - puedes usar esta librería en proyectos comerciales y personales.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature
3. Commit tus cambios
4. Push a la rama
5. Abre un Pull Request

📚 Notas:

1. Mapeo de Emojis Optimizado: La librería utiliza un algoritmo inteligente para seleccionar los nombres de emojis más cortos y descriptivos, mejorando la legibilidad en aplicaciones TTS. Por ejemplo, 😊 se mapea como "happy" en lugar de "smiling_face_with_smiling_eyes".

2. Configuración de Spam: Esta librería no incluye configuraciones predefinidas de spam. El usuario debe proporcionar sus propias palabras y reglas de filtrado.

3. Multiidioma: El soporte para francés y alemán requiere implementación adicional mediante el sistema de LanguagePackManager.