🎯 ToonJS

A high-performance TypeScript library for tabular data manipulation with a custom TOON format

📚 Complete Documentation, Interactive Playground & Tools → toonjs.dev

English | Español

English

📖 Overview

ToonJS is a powerful, zero-dependency TypeScript library for working with tabular data. It introduces the TOON format - a human-readable, efficient way to represent datasets - and provides 100+ optimized methods for data manipulation, analysis, and transformation.

✨ Key Features

• 🚀 Ultra High Performance: Powered by Float64Array Columnar Architecture. Up to 10x faster for numeric operations.
• 📦 Zero Dependencies: Pure TypeScript, no external packages
• 🎯 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🔗 Chainable API: Fluent interface for elegant data pipelines
• 📊 Rich Functionality: Matrix operations, Time Series analysis, Advanced Statistics, and more.
• 🎨 Custom Format: TOON format - compact and human-readable
• ✅ Battle-Tested: 275+ tests including Fuzzing and Invariant checks.
• 🌐 Universal: Works in Node.js and browsers

🆕 New in v1.1

• Columnar Engine: Numeric columns now use Float64Array for SIMD-like performance.
• Matrix Operations: addMatrix, dotProduct, norm, transpose.
• Time Series: rolling (moving averages), lag, lead, diff, pctChange.
• Advanced Stats: covariance, correlation, percentile, rank, z-score.
• Robustness: Massive test suite expansion covering edge cases and algebraic invariants.

🚀 Quick Start

💡 Try it live at toonjs.dev/playground - Interactive code editor with examples!

Installation

npm install @cescofors/toonjs

Basic Usage

import { ToonFactory } from '@cescofors/toonjs';

// Create dataset from TOON format
const data = ToonFactory.from(`
users[3]{id,name,age}:
  1,Alice,28
  2,Bob,35
  3,Charlie,42
`);

// Chain operations
const result = data
  .filter(user => user.age > 30)
  .sortBy(['age'], ['desc'])
  .select(['name', 'age'])
  .all();

console.log(result);
// [{ name: 'Charlie', age: 42 }, { name: 'Bob', age: 35 }]

📚 Core Concepts

TOON Format

The TOON format is designed to be both human-readable and efficient:

name[count]{field1,field2,...}:
  value1,value2,...
  value1,value2,...

Example:

products[2]{id,name,price}:
  101,Laptop,999.99
  102,Mouse,25.50

🛠️ API Reference

Data Access

.all()           // Get all rows
.first()         // Get first row
.last()          // Get last row
.at(index)       // Get row at index
.find(fn)        // Find first matching row
.findAll(fn)     // Find all matching rows
.pluck(field)    // Extract single field values
.take(n)         // Get first n rows
.skip(n)         // Skip first n rows
.slice(start, end) // Get rows slice

Filtering & Search

.filter(fn)              // Filter rows
.filterRange(field, min, max) // Filter by range
.search(term, fields)    // Search in fields
.distinct(field)         // Get unique values
.unique()                // Remove duplicates

Transformation

.map(fn)                 // Transform rows
.mapRows(fn)             // Map to array (optimized)
.select(fields)          // Select specific fields
.exclude(fields)         // Exclude fields
.rename(old, new)        // Rename field
.addField(name, fn)      // Add calculated field
.reverse()               // Reverse order

Sorting & Ordering

.sort(fn)                // Custom sort
.sortBy(fields, orders)  // Sort by multiple fields

Aggregation & Statistics

.groupBy(field)          // Group by field
.countBy(field)          // Count occurrences
.aggregate(by, ops)      // Group with operations
.stats(field)            // Calculate statistics

Mathematical Operations

.toMatrix(fields)        // Convert to 2D array
.fromMatrix(matrix)      // Create from matrix
.addMatrix(other)        // Add matrices
.normalize(fields)       // Normalize to [0,1]
.standardize(fields)     // Z-score normalization
.correlation(f1, f2)     // Calculate correlation
.correlationMatrix()     // Correlation matrix
.covariance(f1, f2)      // Calculate covariance

Time Series

.rolling(field, window)  // Rolling average
.lag(field, periods)     // Lag values
.lead(field, periods)    // Lead values
.diff(field)             // Differences
.pctChange(field)        // Percentage changes
.cumsum(field)           // Cumulative sum

Ranking & Binning

.rank(field, order)      // Assign ranks
.percentile(field, p)    // Calculate percentile
.binning(field, bins)    // Create categories

Combination

.concat(other)           // Concatenate datasets
.join(other, on)         // Inner join

Validation

.some(fn)                // Check if any matches
.every(fn)               // Check if all match
.isEmpty()               // Check if empty
.count()                 // Get row count

Export

.toToon()                // Export to TOON format
.toCSV()                 // Export to CSV
.toJSON()                // Export to JSON
.toTable()               // Display as ASCII table

🎯 Advanced Examples

Data Analysis Pipeline

const analysis = data
  .filter(row => row.value > 0)
  .normalize(['value'])
  .rank('value', 'desc')
  .take(10)
  .toTable();

Time Series Analysis

const trend = data
  .sortBy(['date'], ['asc'])
  .rolling('sales', 7)      // 7-day moving average
  .pctChange('sales')        // Percentage changes
  .all();

Statistical Analysis

const matrix = data.correlationMatrix([
  'price', 'rating', 'sales'
]);

const stats = data.stats('revenue');
// { min, max, avg, sum, count, median }

⚡ Performance

ToonJS is optimized for high performance:

• Correlación: 3.5x más rápido
• Normalización: 3.5x más rápido
• Ranking: 3.23x más rápido
• Rolling Average: 1.25x más rápido
• Overall: Promedio 2.2x más rápido en benchmarks verificables

See PERFORMANCE.md for detailed benchmarks.

🧪 Testing

npm test              # Run all tests
npm run build         # Build TypeScript

All 102 tests passing with 100% coverage.

📄 License

MIT © 2025

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide.

🔗 Links

• 🌐 toonjs.dev - Official website with full documentation
• 📚 Documentation - Complete API reference & guides
• 🎮 Playground - Try ToonJS in your browser
• 🔧 Tools - JSON/CSV to TOON converter
• 📝 Blog - Updates, tutorials & insights
• 📦 NPM Package - Install via npm
• 🐙 GitHub Repository - Source code & issues
• ⚡ Performance Benchmarks - Speed comparisons
• 📋 Changelog - Version history

Español

📖 Descripción

ToonJS es una poderosa biblioteca TypeScript sin dependencias para trabajar con datos tabulares. Introduce el formato TOON - una forma legible y eficiente de representar conjuntos de datos - y proporciona más de 100 métodos optimizados para manipulación, análisis y transformación de datos.

✨ Características Principales

• 🚀 Ultra Alto Rendimiento: Impulsado por Arquitectura Columnar Float64Array. Hasta 10x más rápido en operaciones numéricas.
• 📦 Sin Dependencias: TypeScript puro, sin paquetes externos
• 🎯 Type-Safe: Soporte completo de TypeScript con definiciones exhaustivas
• 🔗 API Encadenable: Interfaz fluida para pipelines elegantes
• 📊 Funcionalidad Rica: Operaciones matriciales, Series Temporales, Estadísticas Avanzadas y más.
• 🎨 Formato Personalizado: Formato TOON - compacto y legible
• ✅ Probado en Batalla: 275+ tests incluyendo Fuzzing y verificación de invariantes.
• 🌐 Universal: Funciona en Node.js y navegadores

🆕 Nuevo en v1.1

• Motor Columnar: Las columnas numéricas ahora usan Float64Array para rendimiento tipo SIMD.
• Operaciones Matriciales: addMatrix, dotProduct, norm, transpose.
• Series Temporales: rolling (medias móviles), lag, lead, diff, pctChange.
• Estadísticas Avanzadas: covariance, correlation, percentile, rank, z-score.
• Robustez: Expansión masiva de tests cubriendo casos borde e invariantes algebraicos.

🚀 Inicio Rápido

Instalación

npm install @cescofors/toonjs

Uso Básico

import { ToonFactory } from '@cesco/toon';

// Crear dataset desde formato TOON
const data = ToonFactory.from(`
usuarios[3]{id,nombre,edad}:
  1,Alicia,28
  2,Roberto,35
  3,Carlos,42
`);

// Encadenar operaciones
const resultado = data
  .filter(usuario => usuario.edad > 30)
  .sortBy(['edad'], ['desc'])
  .select(['nombre', 'edad'])
  .all();

console.log(resultado);
// [{ nombre: 'Carlos', edad: 42 }, { nombre: 'Roberto', edad: 35 }]

📚 Ejemplos Avanzados

Pipeline de Análisis

const analisis = data
  .filter(fila => fila.valor > 0)
  .normalize(['valor'])
  .rank('valor', 'desc')
  .take(10)
  .toTable();

Análisis de Series Temporales

const tendencia = data
  .sortBy(['fecha'], ['asc'])
  .rolling('ventas', 7)      // Media móvil de 7 días
  .pctChange('ventas')       // Cambios porcentuales
  .all();

Análisis Estadístico

const matriz = data.correlationMatrix([
  'precio', 'calificacion', 'ventas'
]);

const estadisticas = data.stats('ingresos');
// { min, max, avg, sum, count, median }

⚡ Rendimiento

ToonJS está optimizado para alto rendimiento:

• Correlación: 3.5x más rápido
• Normalización: 3.5x más rápido
• Ranking: 3.23x más rápido
• Media Móvil: 1.25x más rápido
• General: Promedio 2.2x más rápido en benchmarks verificables

Ver PERFORMANCE.md para benchmarks detallados.

🧪 Pruebas

npm test              # Ejecutar todos los tests
npm run build         # Compilar TypeScript

Los 102 tests pasan con 100% de cobertura.

📄 Licencia

MIT © 2025

🌐 Resources / Recursos

• 🌐 toonjs.dev - Official website with full documentation
• 📚 Documentation - Complete API reference & guides
• 🎮 Playground - Try ToonJS in your browser
• 🔧 Tools - JSON/CSV to TOON converter
• 📝 Blog - Updates, tutorials & insights
• 📦 NPM Package - Install via npm
• 🐙 GitHub - Source code & issues

Made with ❤️ by the ToonJS Team