sparkline-fast

Fast WASM-based sparkline chart generator that converts arrays of numbers to PNG images. Built with Rust and WebAssembly for maximum performance.

Features

• ⚡ Blazing fast - Generates charts in less than a millisecond (thousands of images per second)
• 🎨 Simple API: pass an array, get a PNG
• 📏 Customizable dimensions, colors, and line width
• 🌈 Gradient fills with transparency support
• 🎯 Smart color system - gradients override fills automatically
• 🌐 Zero runtime dependencies in the browser
• 🔧 Works in Node.js, browsers, and bundlers

Installation

npm install sparkline-fast

Quick Start

import { generateSparklineSimple, generateSparkline, SparklineConfig } from 'sparkline-fast';

// Simple usage
const data = new Float32Array([3, 12, 5, 4, 6, 11, 9, 10]);
const pngBytes = generateSparklineSimple(data);

// Advanced usage
const config = new SparklineConfig();
config.width = 400;
config.height = 100;
config.setLineColorHex('FF0000');  // Red line
config.setBackgroundColorHex('FFFFFF');  // White background
config.setFillColorHex('FF000080');  // Semi-transparent red fill

const pngBytes = generateSparkline(data, config);

API Reference

Functions

generateSparklineSimple(data: Float32Array): Uint8Array

Generates a sparkline with default configuration (200x50px, red line, white background).

generateSparkline(data: Float32Array, config?: Object): Uint8Array

Generates a sparkline with optional plain object configuration. If no config is provided, uses defaults.

Configuration Object

Optional plain object with the following properties:

const config = {
  // Dimensions
  width: 400,           // Image width in pixels
  height: 100,          // Image height in pixels
  lineWidth: 2.5,       // Line width in pixels
  
  // Colors (using hex strings - supports RGB, RRGGBB, RRGGBBAA)
  lineColor: 'FF0000',           // Red line
  backgroundColor: 'FFFFFF',     // White background
  fillColor: 'FF000080',         // Semi-transparent red fill
  
  // Gradient colors (gradients automatically override fills)
  gradientFromColor: '3B82F6',   // Blue at top
  gradientToColor: '8B5CF6'      // Purple at bottom
};

Color System

The library uses a smart color system:

• Line & Background: Always required
• Fill: Optional - only applied if setFillColorHex() is called
• Gradient: Optional - automatically overrides fill if either gradient color is set
• Missing gradient color: Automatically becomes transparent version of the other color

Hex Color Format

Supports multiple hex formats:

• 'F00' → 'FF0000FF' (RGB shorthand)
• 'FF0000' → 'FF0000FF' (RGB)
• 'FF000080' → 'FF000080' (RGBA)

Usage Examples

Basic Sparkline

import { generateSparklineSimple } from 'sparkline-fast';

const data = new Float32Array([3, 12, 5, 4, 6, 11, 9, 10]);
const pngBytes = generateSparklineSimple(data);

// In Node.js
import fs from 'fs';
fs.writeFileSync('sparkline.png', Buffer.from(pngBytes));

// In browser
const blob = new Blob([pngBytes], { type: 'image/png' });
const url = URL.createObjectURL(blob);
document.getElementById('chart').src = url;

Custom Styling

import { generateSparkline } from 'sparkline-fast';

const data = new Float32Array([1, 4, 2, 8, 5, 7, 3, 9, 6, 10]);
const pngBytes = generateSparkline(data, {
  width: 400,
  height: 100,
  lineWidth: 3.0,
  lineColor: '00FF00',        // Green line
  backgroundColor: 'FFFFFF'   // White background
});

Dark Theme

const data = new Float32Array([15, 8, 12, 20, 18, 22, 19, 25, 21, 28]);
const pngBytes = generateSparkline(data, {
  width: 300,
  height: 80,
  lineWidth: 2.5,
  lineColor: '00D4FF',        // Cyan line
  backgroundColor: '1A1A1A'   // Dark background
});

Stock Price Visualization

const stockPrices = new Float32Array([
  100, 102, 98, 105, 108, 107, 110, 115, 112, 118,
  120, 117, 122, 119, 125, 128, 130, 127, 132, 135
]);
const pngBytes = generateSparkline(stockPrices, {
  width: 500,
  height: 120,
  lineWidth: 2.0,
  lineColor: 'FF4444',        // Red line
  backgroundColor: 'F5F5F5'   // Light gray background
});

Area Chart with Fill

const data = new Float32Array([5, 10, 8, 15, 12, 18, 16, 20, 17, 22]);
const pngBytes = generateSparkline(data, {
  width: 400,
  height: 100,
  lineWidth: 2.5,
  lineColor: '3B82F6',        // Blue line
  backgroundColor: 'FFFFFF',  // White background
  fillColor: '3B82F655'       // Blue fill with 33% opacity
});

Bold Fill Area Chart

const data = new Float32Array([10, 25, 15, 30, 20, 35, 28, 40, 32, 45]);
const pngBytes = generateSparkline(data, {
  width: 500,
  height: 120,
  lineWidth: 3.0,
  lineColor: 'F59E0B',        // Amber line
  backgroundColor: 'FFFBEB',  // Light amber background
  fillColor: 'F59E0B66'       // Amber with 40% opacity
});

Gradient Fills

Blue to Purple Gradient

const data = new Float32Array([5, 12, 8, 18, 14, 22, 19, 26, 23, 30]);
const pngBytes = generateSparkline(data, {
  width: 400,
  height: 100,
  lineWidth: 2.5,
  lineColor: '8B5CF6',          // Purple line
  backgroundColor: 'FFFFFF',    // White background
  gradientFromColor: '3B82F6',  // Blue at top
  gradientToColor: '8B5CF6'     // Purple at bottom
});

Orange to Red Gradient

const data = new Float32Array([8, 15, 12, 20, 16, 25, 19, 28, 22, 32]);
const pngBytes = generateSparkline(data, {
  width: 450,
  height: 110,
  lineWidth: 3.0,
  lineColor: 'EF4444',          // Red line
  backgroundColor: 'FFF7ED',    // Light orange background
  gradientFromColor: 'F59E0B',  // Orange at top
  gradientToColor: 'EF4444'     // Red at bottom
});

White to Blue Gradient (Subtle Effect)

const data = new Float32Array([12, 18, 15, 22, 19, 26, 23, 28, 25, 32]);
const pngBytes = generateSparkline(data, {
  width: 400,
  height: 100,
  lineWidth: 2.0,
  lineColor: '1E40AF',          // Dark blue line
  backgroundColor: 'F8FAFC',    // Light blue-gray background
  gradientFromColor: 'FFFFFF',  // White at top
  gradientToColor: '3B82F6'     // Blue at bottom
});

Blue to Green Gradient

const data = new Float32Array([4, 11, 7, 16, 12, 19, 15, 23, 18, 26]);
const pngBytes = generateSparkline(data, {
  width: 500,
  height: 120,
  lineWidth: 3.0,
  lineColor: '059669',          // Green line
  backgroundColor: 'FFFFFF',    // White background
  gradientFromColor: '3B82F6',  // Blue at top
  gradientToColor: '10B981'     // Green at bottom
});

Transparent Backgrounds

Transparent Background with Fill

const data = new Float32Array([3, 8, 6, 12, 9, 15, 11, 18, 14, 20]);
const pngBytes = generateSparkline(data, {
  width: 350,
  height: 90,
  lineWidth: 2.0,
  lineColor: '10B981',        // Emerald green line
  backgroundColor: '00000000', // Fully transparent
  fillColor: '10B98180'        // Semi-transparent green fill
});

Green to Transparent Gradient

const data = new Float32Array([6, 14, 10, 20, 16, 24, 19, 27, 22, 30]);
const pngBytes = generateSparkline(data, {
  width: 400,
  height: 100,
  lineWidth: 2.5,
  lineColor: '10B981',          // Green line
  backgroundColor: '00000000',  // Transparent background
  gradientFromColor: '10B981',  // Solid green at top
  gradientToColor: '10B98100'   // Transparent green at bottom
});

Express.js API

import express from 'express';
import { generateSparklineSimple, generateSparkline } from 'sparkline-fast';

const app = express();

app.get('/sparkline', (req, res) => {
  const data = new Float32Array(
    req.query.data.split(',').map(Number)
  );
  
  const pngBytes = generateSparklineSimple(data);
  
  res.setHeader('Content-Type', 'image/png');
  res.send(Buffer.from(pngBytes));
});

app.listen(3000);

Development

Prerequisites

• Rust (latest stable)
• wasm-pack

Build Commands

# Build for bundlers (webpack, rollup, etc.)
npm run build

# Build for Node.js
npm run build:nodejs

# Build for web (ES modules)
npm run build:web

# Build and copy to docs directory
npm run build:docs

# Run examples
npm run example

# Run benchmarks
npm run benchmark

# Start dev server (builds docs + serves)
npm run server

# Run tests
npm test

Scripts

• scripts/example.js - Generates various example sparklines
• scripts/benchmark.js - Performance benchmarks
• scripts/test-server.js - Development server for docs

Performance

Benchmarked on MacBook Air M2 (Node.js v20.17.0):

Overall Performance

| Chart Type | Avg Time | Images/sec | |------------|----------|------------| | Simple sparkline | 0.374 ms | 2,671/sec | | With fill area | 1.496 ms | 668/sec | | Gradient fill | 1.743 ms | 574/sec | | Gradient + transparency | 1.712 ms | 584/sec |

Performance by Image Size

| Dimensions | Avg Time | Images/sec | |------------|----------|------------| | 100×25 px | 0.146 ms | 6,852/sec | | 200×50 px (default) | 0.395 ms | 2,531/sec | | 400×100 px | 1.197 ms | 835/sec | | 800×200 px | 3.995 ms | 250/sec | | 1600×400 px | 14.492 ms | 69/sec |

Performance by Data Points

| Data Points | Avg Time | Images/sec | |-------------|----------|------------| | 10 points | 0.301 ms | 3,322/sec | | 20 points | 0.342 ms | 2,926/sec | | 50 points | 0.558 ms | 1,791/sec | | 100 points | 0.751 ms | 1,331/sec | | 200 points | 0.959 ms | 1,042/sec |

Additional Metrics

• Bundle size: ~50KB gzipped WASM
• Memory: Minimal allocation, zero-copy operations
• Browser support: All modern browsers with WASM support

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Roadmap

• [x] Gradient fills with transparency
• [x] Smart color system (gradients override fills)
• [x] Hex color string API
• [x] Comprehensive examples and benchmarks
• [ ] Additional chart styles (bar charts, candlesticks)
• [ ] SVG output option
• [ ] Multiple data series support
• [ ] Custom axis/grid options