@worldsdev/tools
v1.0.0
Published
Utility tools for arrays, text formatting and download files and others...
Maintainers
Readme
📦 @worldsdev/Tools
TypeScript utility library for arrays, text formatting, HTML transformation, and file downloads.
English
📋 Project Summary
@worldsdev/Tools is a production-ready TypeScript utility library that provides robust, reusable utilities for common programming tasks. The library is designed for developers who need reliable, well-tested utilities for array manipulation, string operations, HTML formatting, and browser-based file downloads. This package can be built and published to npm for seamless integration into any TypeScript/JavaScript project (Angular, React, Vue or plain).
🎯 Project Overview
The Tools library encapsulates five core utility classes, each solving specific programming challenges:
- Array Operations: Move, remove, combine, and shuffle array elements with a fluent API
- String Manipulation: Insert, replace, extract, and remove text segments with precision
- Rule-Based Transformations: Apply bulk replacements and removals using declarative rule objects
- HTML Formatting: Transform user input into safe, displayable HTML with support for custom tags, code blocks, images, and embedded media
- File Downloads: Export JavaScript objects directly to JSON files in the browser
✨ Key Features
- ✅ ArraysTool: Move elements left/right, remove items, combine arrays, shuffle with Fisher-Yates algorithm
- ✅ TextTool: Replace, insert, and extract text with selection-aware positioning
- ✅ RemoveReplaceOption: Bulk text operations using declarative rule-based configuration
- ✅ HtmlTextTool: Safe HTML display with custom tag conversion, code formatting, image/video embedding
- ✅ DownloadTool: Browser-based JSON export functionality
- ✅ Inheritance-based Architecture: Clean separation of concerns with extensible class hierarchy
- ✅ TypeScript: Full type safety with strict null checking
- ✅ Framework-Agnostic Core: Utilities can be used independently
📂 Project Structure
src/
├── lib/
│ ├── arrays-tool/ # Array manipulation utilities
│ ├── text-tool/ # Base text manipulation
│ ├── remove-replace-option/ # Rule-based transformation
│ ├── html-tool/ # HTML-specific formatting
│ ├── download-tool/ # Browser download utilities
│ └── element-like.ts
├── public-api.ts # Public barrel export
package.json # Package metadata
tsconfig.json / vitest.config.ts🏗️ Architecture Highlights
The library uses an inheritance-based hierarchy for code reuse:
TextTool (base string operations)
↓
RemoveReplaceOption (rule-based bulk operations)
↓
HtmlTextTool (HTML-safe transformations)Patterns Used:
- Inheritance: Reusable base functionality in parent classes
- Composition: Rule objects (
RemoveReplaceOptions,ReplaceStrings) for flexible configuration - Strategy Pattern: Different formatting rules for code, images, and videos
- Immutable Operations: Methods return new strings without mutating originals (where applicable)
🛠️ Technology Stack
- TypeScript — Type-safe implementation, compiled with
tsc - Vitest + jsdom — Unit testing
- Zero runtime dependencies
💻 Code Quality & Engineering Practices
This library demonstrates professional software engineering:
- Type Safety: Full TypeScript strict mode with explicit types
- Separation of Concerns: Single Responsibility Principle with focused utility classes
- Extensibility: Base classes designed for inheritance and composition
- Testability: Isolated, pure functions with clear contracts
- Documentation: Self-documenting method names and clear parameter intent
- Maintainability: Clean code structure with logical grouping in separate files
🚀 How to Build & Run Locally
Prerequisites: Node.js >= 18
npm install # install dev dependencies
npm test # run tests (vitest + jsdom)
npm run build # compile to dist/ with tsc
npm publish # builds automatically (prepublishOnly) and publishes dist/📖 Usage Examples
After publishing to npm or importing from source:
import { ArraysTool, DownloadTool, HtmlTextTool, TextTool } from '@worldsdev/tools';
// Array utilities
const arrayTool = new ArraysTool();
const shuffled = arrayTool.shuffle([1, 2, 3, 4, 5]);
const moved = [...shuffled];
arrayTool.moveElementRight(moved, 3); // Move element 3 to the right
// Text utilities
const textTool = new TextTool();
const inserted = textTool.insertAfter('Hello World', 'Hello', '✨ ');
// Result: "Hello✨ World"
// HTML formatting
const htmlTool = new HtmlTextTool();
const safe = htmlTool.formatAllText('<app-root>My Component</app-root>');
// Converts tags to safe HTML entities: <app-root>My Component</app-root>
// File downloads
const downloadTool = new DownloadTool();
downloadTool.DownloadTextToFileAsJson({ name: 'John', age: 30 }, 'user-data');
// Downloads: user-data.json📚 Class Reference
| Class | Purpose | Key Methods |
|-------|---------|-------------|
| ArraysTool | Array manipulation | shuffle, moveElementInArray, removeFromArray, combine |
| TextTool | String operations | replaceText, insertText, getTextBetween, removeAllTextFromTo |
| RemoveReplaceOption | Bulk transformations | removeAllOptions, replaceTextOptions |
| HtmlTextTool | HTML formatting | formatAllText, formatTextToCode, setToTag, removeAllTags |
| DownloadTool | Browser downloads | DownloadTextToFileAsJson |
💡 Development Insights
- Modular Design: Each utility can be used independently without dependencies on others
- Performance: Efficient string algorithms with configurable limits on replacement iterations
- Browser Compatibility: Works with modern browsers supporting Blob API and DOM selections
- Framework-agnostic: Plain TypeScript with no runtime dependencies; element-based methods accept anything shaped like
{ nativeElement }(e.g. Angular'sElementRef)
🎓 Learning Outcomes
This project demonstrates:
- Building production-grade npm packages in plain TypeScript
- TypeScript strict mode and type system best practices
- Library architecture with inheritance and composition
- Unit testing with Vitest
- String manipulation algorithms and edge case handling
- HTML sanitization and safe text formatting
👨💼 Author
Abraham Sanchez — Full-stack developer focused on reusable utilities and reusable components.
Español
📋 Resumen del Proyecto
@worldsdev/Tools es una librería de utilidades TypeScript lista para producción que proporciona herramientas robustas y reutilizables para tareas comunes. La librería está diseñada para desarrolladores que necesitan utilidades confiables y bien probadas para manipulación de arrays, operaciones con cadenas, formateo HTML y descargas de archivos en el navegador. Este paquete puede compilarse y publicarse en npm para integrarse sin problemas en otros proyectos TypeScript/JavaScript (Angular, React, Vue o simples).
🎯 Descripción General del Proyecto
La librería Tools encapsula cinco clases de utilidades principales, cada una resolviendo desafíos de programación específicos:
- Operaciones con Arrays: Mover, eliminar, combinar y barajar elementos de un array con una API fluida
- Manipulación de Cadenas: Insertar, reemplazar, extraer y eliminar segmentos de texto con precisión
- Transformaciones Basadas en Reglas: Aplicar reemplazos y eliminaciones masivas usando objetos de reglas declarativos
- Formateo HTML: Transformar entrada de usuario en HTML seguro y mostrable con soporte para etiquetas personalizadas, bloques de código, imágenes y medios integrados
- Descargas de Archivos: Exportar objetos JavaScript directamente a archivos JSON en el navegador
✨ Características Principales
- ✅ ArraysTool: Mover elementos izquierda/derecha, eliminar elementos, combinar arrays, barajar con algoritmo Fisher-Yates
- ✅ TextTool: Reemplazar, insertar y extraer texto con posicionamiento consciente de la selección
- ✅ RemoveReplaceOption: Operaciones de texto masivas usando configuración declarativa basada en reglas
- ✅ HtmlTextTool: Visualización segura de HTML con conversión de etiquetas personalizadas, formateo de código, incrustación de imágenes/vídeo
- ✅ DownloadTool: Funcionalidad de exportación JSON basada en navegador
- ✅ Arquitectura Basada en Herencia: Separación clara de responsabilidades con jerarquía de clases extensible
- ✅ TypeScript: Seguridad de tipos completa con verificación de nulidad estricta
- ✅ Núcleo Agnóstico de Framework: Las utilidades pueden usarse independientemente
📂 Estructura del Proyecto
src/
├── lib/
│ ├── arrays-tool/ # Utilidades de manipulación de arrays
│ ├── text-tool/ # Manipulación base de texto
│ ├── remove-replace-option/ # Transformación basada en reglas
│ ├── html-tool/ # Formateo específico de HTML
│ ├── download-tool/ # Utilidades de descarga en navegador
│ └── element-like.ts
├── public-api.ts # Exportación barrel pública
package.json # Metadatos del paquete
tsconfig.json / vitest.config.ts🏗️ Aspectos Destacados de la Arquitectura
La librería usa una jerarquía basada en herencia para reutilización de código:
TextTool (operaciones base de cadenas)
↓
RemoveReplaceOption (operaciones masivas basadas en reglas)
↓
HtmlTextTool (transformaciones seguras para HTML)Patrones Utilizados:
- Herencia: Funcionalidad base reutilizable en clases padre
- Composición: Objetos de reglas (
RemoveReplaceOptions,ReplaceStrings) para configuración flexible - Patrón Strategy: Diferentes reglas de formateo para código, imágenes y vídeos
- Operaciones Inmutables: Los métodos devuelven nuevas cadenas sin mutar originales (donde aplica)
🛠️ Stack Tecnológico
- TypeScript — Type-safe implementation, compiled with
tsc - Vitest + jsdom — Unit testing
- Zero runtime dependencies
💻 Calidad de Código y Prácticas de Ingeniería
Esta librería demuestra ingeniería de software profesional:
- Seguridad de Tipos: TypeScript en modo estricto completo con tipos explícitos
- Separación de Responsabilidades: Principio de Responsabilidad Única con clases de utilidades enfocadas
- Extensibilidad: Clases base diseñadas para herencia y composición
- Testabilidad: Funciones aisladas y puras con contratos claros
- Documentación: Nombres de métodos auto-documentados e intención clara de parámetros
- Mantenibilidad: Estructura de código limpia con agrupación lógica en archivos separados
🚀 Cómo Compilar y Ejecutar Localmente
Requisitos Previos: Node.js >= 18
npm install # instala dependencias de desarrollo
npm test # ejecuta tests (vitest + jsdom)
npm run build # compila a dist/ con tsc
npm publish # compila automáticamente (prepublishOnly) y publica dist/📖 Ejemplos de Uso
Después de publicar en npm o importar desde la fuente:
import { ArraysTool, DownloadTool, HtmlTextTool, TextTool } from '@worldsdev/tools';
// Utilidades de array
const arrayTool = new ArraysTool();
const barajado = arrayTool.shuffle([1, 2, 3, 4, 5]);
const movido = [...barajado];
arrayTool.moveElementRight(movido, 3); // Mover elemento 3 a la derecha
// Utilidades de texto
const textTool = new TextTool();
const insertado = textTool.insertAfter('Hola Mundo', 'Hola', '✨ ');
// Resultado: "Hola✨ Mundo"
// Formateo HTML
const htmlTool = new HtmlTextTool();
const seguro = htmlTool.formatAllText('<app-root>Mi Componente</app-root>');
// Convierte etiquetas a entidades HTML seguras: <app-root>Mi Componente</app-root>
// Descargas de archivos
const downloadTool = new DownloadTool();
downloadTool.DownloadTextToFileAsJson({ nombre: 'Juan', edad: 30 }, 'datos-usuario');
// Descarga: datos-usuario.json📚 Referencia de Clases
| Clase | Propósito | Métodos Principales |
|-------|-----------|-------------------|
| ArraysTool | Manipulación de arrays | shuffle, moveElementInArray, removeFromArray, combine |
| TextTool | Operaciones de cadenas | replaceText, insertText, getTextBetween, removeAllTextFromTo |
| RemoveReplaceOption | Transformaciones masivas | removeAllOptions, replaceTextOptions |
| HtmlTextTool | Formateo de HTML | formatAllText, formatTextToCode, setToTag, removeAllTags |
| DownloadTool | Descargas en navegador | DownloadTextToFileAsJson |
💡 Insights de Desarrollo
- Diseño Modular: Cada utilidad puede usarse independientemente sin dependencias en otras
- Rendimiento: Algoritmos eficientes de cadenas con límites configurables en iteraciones de reemplazo
- Compatibilidad del Navegador: Funciona con navegadores modernos que soportan Blob API y selecciones de DOM
- Agnóstico de framework: TypeScript puro sin dependencias en runtime; los métodos con elementos aceptan cualquier objeto
{ nativeElement }(p. ej.ElementRefde Angular)
🎓 Resultados de Aprendizaje
Este proyecto demuestra:
- Construcción de paquetes npm listos para producción en TypeScript puro
- Mejores prácticas de TypeScript en modo estricto y sistema de tipos
- Arquitectura de librerías con herencia y composición
- Testing unitario con Vitest
- Algoritmos de manipulación de cadenas y manejo de casos límite
- Sanitización de HTML y formateo seguro de texto
👨💼 Autor
Abraham Sanchez — Desarrollador full-stack enfocado en utilidades reutilizables y componentes reutilizables.
