brickcharts
Advanced tools
A comprehensive library for managing Billboard and Last.FM charts with visualizations and data management
A comprehensive TypeScript library for managing Billboard and Last.FM charts with powerful data management, visualization support, and easy-to-use APIs.
@aribradshaw/billboard-top-100npm install brickcharts
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 configurationapiKeys?: { lastfm?: string } - API keys for external servicesChart Sources:
ChartSource.BILLBOARD - Billboard commercial chartsChartSource.LASTFM - Last.FM global and personal chartsgetChart(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}`);
});
interface ChartEntry {
rank: number;
title: string;
artist: string;
album?: string;
lastWeek?: number;
peakPosition?: number;
weeksOnChart?: number;
chartDate: Date;
source: ChartSource;
metadata?: Record<string, any>;
}
interface ChartData {
chartType: string;
date: Date;
entries: ChartEntry[];
source: ChartSource;
totalEntries: number;
metadata?: Record<string, any>;
}
hot-100 - Billboard Hot 100 Songsbillboard-200 - Billboard 200 Albumsartist-100 - Artist 100pop-songs - Pop Songscountry-songs - Country Songsrock-songs - Rock Songsr-b-songs - R&B Songsrap-songs - Rap Songsdance-songs - Dance/Electronic Songslatin-songs - Latin Songsstreaming-songs - Streaming Songsradio-songs - Radio Songsdigital-songs - Digital Songssocial-50 - Social 50top-tracks - Global top trackstop-albums - Global top albumstop-artists - Global top artiststop-tracks-weekly - Weekly top trackstop-tracks-monthly - Monthly top trackstop-tracks-yearly - Yearly top trackstop-albums-weekly - Weekly top albumstop-albums-monthly - Monthly top albumstop-albums-yearly - Yearly top albumstop-artists-weekly - Weekly top artiststop-artists-monthly - Monthly top artiststop-artists-yearly - Yearly top artistsconst 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 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
// 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);
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);
}
}
const health = await brickCharts.healthCheck();
console.log('Service Health:', Object.fromEntries(health));
# 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
npm run test:interactive
What it does:
Try these features:
npm run demo
What you'll see:
npm run demo:lastfm
What you'll see:
npm run demo:combined
What you'll see:
npm run demo:personal-lastfm
What you'll see:
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Watch mode for development
npm test --watch
npm run build
Validates:
// Should work immediately
const hot100 = await brickCharts.getChart('hot-100');
// Expected: ~100 entries, 1-3 second fetch time
Test scenarios:
// 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:
// Test all export formats
await exportManager.exportChartData(chart, { format: 'csv' });
await exportManager.exportChartData(chart, { format: 'json' });
await exportManager.exportChartData(chart, { format: 'svg' });
Expected outputs:
"Billboard service unavailable"
"Search returns no results"
searchEngine.indexChartData([chart])"Export fails"
ExportManager.validateOptions(options)"Build errors"
npm install to ensure dependencies# 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
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));
@aribradshaw/billboard-top-100To use Last.FM features, you'll need a free 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'
}
});
Contributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)This project is licensed under the MIT License - see the LICENSE file for details.
Copyright (c) 2025 Brickstone Studios LLC
Ari Daniel Bradshaw
Brickstone Studios LLC
If you have any questions or run into issues, please open an issue on GitHub.
FAQs
A comprehensive library for managing Billboard and Last.FM charts with visualizations and data management
The npm package brickcharts receives a total of 4 weekly downloads. As such, brickcharts popularity was classified as not popular.
We found that brickcharts demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.