🎵 BrickCharts

A comprehensive TypeScript library for managing Billboard and Last.FM charts with powerful data management, visualization support, and easy-to-use APIs.

✨ Features

• 🎯 Billboard Integration: Complete access to 255+ Billboard charts via @aribradshaw/billboard-top-100
• 🌐 Last.FM Integration: Global music charts and personal listening data
• 📈 Trend Analysis: Compare charts across time periods and track movement
• 💾 Smart Caching: Built-in caching with localStorage persistence
• 🔍 Search & Filter: Find tracks and artists across multiple charts
• 📊 Data Normalization: Unified data format across different sources
• 🚀 TypeScript Support: Full type safety and IntelliSense
• ⚡ Performance Optimized: Efficient data fetching and caching strategies
• 👤 Personal Charts: Access your own Last.FM listening history
• 🧪 Comprehensive Testing: 10+ test suites covering all functionality

🚀 Quick Start

Installation

npm install brickcharts

Basic Usage

import { BrickCharts, ChartSource } from 'brickcharts';

// Initialize the library
const brickCharts = new BrickCharts({
  enableCache: true,
  defaultSource: ChartSource.BILLBOARD,
  cacheOptions: {
    ttl: 1000 * 60 * 30, // 30 minutes
    maxSize: 50,
    persistent: true
  }
});

// Get current Billboard Hot 100
const hot100 = await brickCharts.getChart('hot-100');
console.log('Current #1 song:', hot100.entries[0]);

// Get Billboard 200 Albums
const albums = await brickCharts.getChart('billboard-200');
console.log('Top album:', albums.entries[0]);

// Get trends analysis
const trends = await brickCharts.getTrends('hot-100');
console.log('Biggest climbers:', trends.topMovers.climbers.slice(0, 5));

// Get Last.FM global charts
const lastfmTracks = await brickCharts.getChart('top-tracks', ChartSource.LASTFM);
console.log('Last.FM #1 track:', lastfmTracks.entries[0]);

## 📖 API Reference

### Core Class: BrickCharts

#### Constructor

```typescript
const brickCharts = new BrickCharts(config?: BrickChartsConfig);

Config Options:

• enableCache?: boolean - Enable caching (default: true)
• defaultSource?: ChartSource - Default chart source (default: BILLBOARD)
• cacheOptions?: CacheOptions - Cache configuration
• apiKeys?: { lastfm?: string } - API keys for external services

Chart Sources:

• ChartSource.BILLBOARD - Billboard commercial charts
• ChartSource.LASTFM - Last.FM global and personal charts

Methods

getChart(chartType, source?, options?)

Get a specific chart for the current week or a specific date.

// Current Hot 100
const chart = await brickCharts.getChart('hot-100');

// Hot 100 for specific date
const historicalChart = await brickCharts.getChart('hot-100', ChartSource.BILLBOARD, {
  date: new Date('2023-01-01')
});

getAvailableCharts(source?)

Get list of all available charts from a source.

const charts = await brickCharts.getAvailableCharts();
console.log('Available charts:', charts);

getTrends(chartType, source?, weeksBack?)

Analyze trends by comparing current chart with previous weeks.

const trends = await brickCharts.getTrends('hot-100', ChartSource.BILLBOARD, 2);
console.log('New entries:', trends.newEntries);
console.log('Biggest climbers:', trends.topMovers.climbers);

compareCharts(chartType, date1, date2, source?)

Compare two charts from different dates.

const comparison = await brickCharts.compareCharts(
  'hot-100',
  new Date('2023-01-01'),
  new Date('2023-01-08')
);

searchTrack(title, artist, chartType?, source?)

Search for tracks across charts.

const results = await brickCharts.searchTrack('', 'Taylor Swift');
results.forEach(chart => {
  console.log(`Found in ${chart.chartType}`);
});

Data Types

ChartEntry

interface ChartEntry {
  rank: number;
  title: string;
  artist: string;
  album?: string;
  lastWeek?: number;
  peakPosition?: number;
  weeksOnChart?: number;
  chartDate: Date;
  source: ChartSource;
  metadata?: Record<string, any>;
}

ChartData

interface ChartData {
  chartType: string;
  date: Date;
  entries: ChartEntry[];
  source: ChartSource;
  totalEntries: number;
  metadata?: Record<string, any>;
}

📊 Available Chart Types

Billboard Charts

• hot-100 - Billboard Hot 100 Songs
• billboard-200 - Billboard 200 Albums
• artist-100 - Artist 100
• pop-songs - Pop Songs
• country-songs - Country Songs
• rock-songs - Rock Songs
• r-b-songs - R&B Songs
• rap-songs - Rap Songs
• dance-songs - Dance/Electronic Songs
• latin-songs - Latin Songs
• streaming-songs - Streaming Songs
• radio-songs - Radio Songs
• digital-songs - Digital Songs
• social-50 - Social 50
• And 240+ more charts...

Last.FM Charts

• top-tracks - Global top tracks
• top-albums - Global top albums
• top-artists - Global top artists
• top-tracks-weekly - Weekly top tracks
• top-tracks-monthly - Monthly top tracks
• top-tracks-yearly - Yearly top tracks
• top-albums-weekly - Weekly top albums
• top-albums-monthly - Monthly top albums
• top-albums-yearly - Yearly top albums
• top-artists-weekly - Weekly top artists
• top-artists-monthly - Monthly top artists
• top-artists-yearly - Yearly top artists

🛠️ Advanced Usage

Caching Configuration

const brickCharts = new BrickCharts({
  cacheOptions: {
    ttl: 1000 * 60 * 60, // 1 hour
    maxSize: 100,
    persistent: true // Save to localStorage
  }
});

// Clear cache
await brickCharts.clearCache();

// Get cache stats
const stats = await brickCharts.getCacheStats();

Billboard Integration

// Billboard integration is included by default
const brickCharts = new BrickCharts();

// Get current Hot 100
const hot100 = await brickCharts.getChart('hot-100');

// Get Billboard 200 albums
const albums = await brickCharts.getChart('billboard-200');

// Get historical data
const historicalChart = await brickCharts.getChart('hot-100', ChartSource.BILLBOARD, {
  date: new Date('2023-01-01')
});

// Get available charts
const availableCharts = await brickCharts.getAvailableCharts(ChartSource.BILLBOARD);
console.log('Available charts:', availableCharts.length); // 255+ charts

Last.FM Integration

// Initialize with Last.FM API key
const brickCharts = new BrickCharts({
  apiKeys: {
    lastfm: 'your-lastfm-api-key'
  }
});

// Get global Last.FM charts
const globalTracks = await brickCharts.getChart('top-tracks', ChartSource.LASTFM);

// Get personal charts (requires username)
const personalTracks = await getPersonalTopTracks(apiKey, 'username', 10);

Error Handling

try {
  const chart = await brickCharts.getChart('hot-100');
} catch (error) {
  if (error instanceof APIError) {
    console.log('API Error:', error.message);
    console.log('Status Code:', error.statusCode);
    console.log('Source:', error.source);
  }
}

Health Monitoring

const health = await brickCharts.healthCheck();
console.log('Service Health:', Object.fromEntries(health));

🔧 Development & Testing

🚀 Quick Start for New Users

# 1. Clone the repository
git clone https://github.com/aribradshaw/brickcharts.git
cd brickcharts

# 2. Install dependencies
npm install

# 3. Start with interactive testing (RECOMMENDED)
npm run test:interactive

# 4. Run the comprehensive demo
npm run demo

# 5. Test Last.FM integration (requires API key)
export LASTFM_API_KEY="your-api-key"
npm run demo:lastfm

# 6. Test combined Billboard + Last.FM
npm run demo:combined

# 7. Test personal Last.FM charts
export LASTFM_USERNAME="your-username"
npm run demo:personal-lastfm

# 8. Build the library
npm run build

📋 Testing Guide

Interactive Testing Suite (Best First Experience)

npm run test:interactive

What it does:

• Menu-driven CLI interface
• Test all features: fetching, search, export, caching
• Real-time performance metrics
• Perfect for exploring capabilities

Try these features:

1. Chart Fetching - Get Hot 100, Billboard 200, historical data
2. Search Engine - Artist search, fuzzy matching, autocomplete
3. Export Functions - CSV, JSON, SVG generation
4. Performance Testing - Cache behavior, response times
5. Health Monitoring - Service availability

Core Demo (Production Examples)

npm run demo

What you'll see:

• ✅ Health check of Billboard services
• 📊 255+ available charts listed
• 🔥 Current Hot 100 with trend analysis
• 📈 Week-over-week comparisons
• 💾 Cache performance metrics
• 🔍 Search functionality demo

Last.FM Demo (Global Charts)

npm run demo:lastfm

What you'll see:

• ✅ Last.FM global top tracks, albums, artists
• 📊 Time-period specific charts (weekly, monthly, yearly)
• 🎧 Play count and listener statistics
• 💾 Unified caching with Billboard

Combined Demo (Cross-Platform Analysis)

npm run demo:combined

What you'll see:

• ✅ Billboard vs Last.FM chart comparisons
• 🎯 Tracks popular on both platforms
• 📊 Genre-specific analysis
• 📈 Time-based trend analysis

Personal Last.FM Demo (Individual Data)

npm run demo:personal-lastfm

What you'll see:

• ✅ Personal top tracks, artists, albums
• 📅 Recent listening activity
• 📊 Time-period analysis (weekly, monthly, yearly)
• ❤️ Loved tracks collection

Unit Tests (Developer Validation)

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode for development
npm test --watch

Build Testing (Production Ready)

npm run build

Validates:

• TypeScript compilation
• Bundle generation (ES + UMD)
• Type declaration files
• Tree-shaking optimization

🎯 What to Test & Expect

Chart Data Fetching

// Should work immediately
const hot100 = await brickCharts.getChart('hot-100');
// Expected: ~100 entries, 1-3 second fetch time

Test scenarios:

• ✅ Current charts load in 1-3 seconds
• ✅ 255+ charts available
• ✅ Historical data from past weeks
• ✅ Proper error handling for invalid dates

Advanced Search

// Try these searches
searchEngine.search({ artist: 'Taylor Swift' });        // Exact match
searchEngine.search({ artist: 'Tayler Swift', fuzzy: true }); // Fuzzy match
searchEngine.quickSearch('tay', 'artist');              // Autocomplete

Expected results:

• ✅ Fast search results (<50ms after indexing)
• ✅ Fuzzy matching handles typos
• ✅ Rank filtering works correctly
• ✅ Autocomplete provides relevant suggestions

Export Functionality

// Test all export formats
await exportManager.exportChartData(chart, { format: 'csv' });
await exportManager.exportChartData(chart, { format: 'json' });
await exportManager.exportChartData(chart, { format: 'svg' });

Expected outputs:

• ✅ CSV with proper escaping and metadata
• ✅ JSON with complete data structure
• ✅ SVG charts with proper dimensions
• ✅ Validation prevents invalid options

Performance Benchmarks

• First fetch: 1-3 seconds (network dependent)
• Cached fetch: <50ms
• Search: <50ms after indexing
• Export: <500ms for typical chart sizes

🐛 Common Issues & Solutions

"Billboard service unavailable"

• Wait 5-10 minutes (temporary service issues)
• Check internet connection
• Try different chart types

"Search returns no results"

• Ensure chart data is indexed first: searchEngine.indexChartData([chart])
• Try fuzzy search for partial matches
• Check spelling and try broader terms

"Export fails"

• Validate options first: ExportManager.validateOptions(options)
• Ensure browser supports Blob downloads
• Check file permissions for Node.js environments

"Build errors"

• Run npm install to ensure dependencies
• Check TypeScript version compatibility
• Clear node_modules and reinstall if needed

🔄 Development Workflow

# 1. Make changes to source code
# 2. Test changes
npm test

# 3. Try interactive testing
npm run test:interactive

# 4. Verify demo still works
npm run demo

# 5. Build for production
npm run build

# 6. Commit and push
git add .
git commit -m "Your changes"
git push

📊 Performance Monitoring

The library includes built-in performance monitoring:

// Check cache performance
const stats = await brickCharts.getCacheStats();
console.log(`Cache hit rate: ${stats.hitRate}%`);

// Monitor service health
const health = await brickCharts.healthCheck();
console.log('Services:', Object.fromEntries(health));

🗺️ Roadmap

✅ Completed Features

• [x] Billboard Integration - Full access to 255+ Billboard charts via @aribradshaw/billboard-top-100
• [x] Last.FM Integration - Global charts and personal listening data
• [x] Advanced Search Engine - Fuzzy matching, filtering, autocomplete
• [x] Export Functions - CSV, JSON, SVG exports with validation
• [x] React Components - TypeScript chart visualization components
• [x] Performance Optimization - Smart caching with localStorage
• [x] Comprehensive Testing - 10+ test suites covering all functionality
• [x] Type Safety - Full TypeScript support with strict typing
• [x] Cross-Platform Analysis - Billboard vs Last.FM comparisons
• [x] Stress Testing - Robust error handling and performance validation

🚧 In Progress

• [ ] Additional React Components - Bar, Bubble, Heatmap, Timeline charts
• [ ] Component Library - Dashboard, TrendAnalyzer, ChartComparison
• [ ] Image Export - PNG rendering with html2canvas
• [ ] PDF Export - Complete report generation
• [ ] Enhanced Billboard Features - Historical data improvements and custom chart types

🔮 Future Enhancements

• [ ] Spotify Integration - Connect with Spotify API for streaming data
• [ ] Real-time Updates - WebSocket support for live chart updates
• [ ] Genre Analysis - Advanced genre and mood analysis
• [ ] Playlist Generation - Auto-generate playlists from chart data
• [ ] Apple Music Charts - Additional chart source integration
• [ ] Chart Predictions - ML-based trend forecasting
• [ ] Advanced Personal Analytics - Deep listening pattern analysis

💡 Community Requested

• [ ] Mobile Optimization - React Native compatible components
• [ ] Chart Animations - Smooth transitions and loading states

🔑 API Keys

Last.FM API Key

To use Last.FM features, you'll need a free API key:

1. Visit Last.FM API Registration
2. Create a free account or log in
3. Create a new application
4. Copy your API key

# Set environment variable
export LASTFM_API_KEY="your-api-key-here"

# Or use in code
const brickCharts = new BrickCharts({
  apiKeys: {
    lastfm: 'your-api-key-here'
  }
});

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Brickstone Studios LLC

👨‍💻 Author

Ari Daniel Bradshaw
Brickstone Studios LLC

🙏 Acknowledgments

• @aribradshaw/billboard-top-100 for Billboard API access
• Billboard.com for providing music chart data
• The Billboard Top 100 community for maintaining the original package

📞 Support

If you have any questions or run into issues, please open an issue on GitHub.