aribradshaw# Billboard Top 100
A modern Node.js library for fetching Billboard chart data. This is a fork of the original billboard-top-100 library, updated to use modern dependencies and ES modules.
Version 3.0.4 - Latest Release
This version includes significant improvements:
- ✅ Node.js 18+ Support: Updated to require Node.js 18+ for better performance and modern features
- ✅ Fixed ReadableStream Issue: Resolved the
ReadableStream is not definederror that was breaking CI/CD - ✅ Updated Dependencies: All dependencies updated to latest stable versions
- ✅ Improved Test Reliability: Fixed timeout issues and improved test stability
- ✅ Better CI/CD: Updated GitHub Actions to test against Node.js 18 and 20
- ✅ Stable CI/CD Pipeline: All workflows now properly configured for Node.js 18+
- ✅ npm Token Configured: Repository secrets updated for automatic publishing
- ✅ No Deprecated Dependencies: Removed all deprecated packages (node-fetch, har-validator, etc.)
- ✅ Native Fetch: Uses Node.js 18+ native fetch for better performance
Features
- ✅ Modern Dependencies: Uses
node-fetchinstead of deprecatedrequestpackage - ✅ ES Modules: Full ES module support with
import/export - ✅ Security Updates: Updated all dependencies to latest secure versions
- ✅ No Deprecation Warnings: All deprecated packages have been replaced
- ✅ TypeScript Ready: Can be easily used in TypeScript projects
Installation
npm install @aribradshaw/billboard-top-100Usage
ES Modules (Recommended)
import { getChart, listCharts } from '@aribradshaw/billboard-top-100';
// Get current Hot 100 chart
getChart('hot-100', (err, chart) => {
if (err) {
console.error('Error:', err);
return;
}
console.log('Week of:', chart.week);
console.log('Number 1 song:', chart.songs[0]);
});
// Get a specific week's chart
getChart('hot-100', '2023-12-30', (err, chart) => {
if (err) {
console.error('Error:', err);
return;
}
console.log('Chart for week of:', chart.week);
console.log('Previous week:', chart.previousWeek);
console.log('Next week:', chart.nextWeek);
});
// List all available charts
listCharts((err, charts) => {
if (err) {
console.error('Error:', err);
return;
}
console.log('Available charts:', charts);
});CommonJS (Legacy)
const { getChart, listCharts } = require('@aribradshaw/billboard-top-100');
// Same usage as aboveAPI Reference
getChart(chartName, date, callback)
Fetches a specific Billboard chart.
Parameters:
chartName(string): The name of the chart (e.g., 'hot-100', 'latin-songs', 'artist-100')date(string, optional): The date in YYYY-MM-DD format. If omitted, gets the current week's chartcallback(function): Callback function with signature(error, chart)
Returns:
chartobject with the following structure:{ week: '2023-12-30', previousWeek: { date: '2023-12-23', url: 'http://www.billboard.com/charts/hot-100/2023-12-23' }, nextWeek: { date: '2024-01-06', url: 'http://www.billboard.com/charts/hot-100/2024-01-06' }, songs: [ { rank: 1, title: 'Song Title', artist: 'Artist Name', cover: 'https://charts-static.billboard.com/img/...', position: { positionLastWeek: 1, peakPosition: 1, weeksOnChart: 14 } } // ... more songs ] }
listCharts(callback)
Lists all available Billboard charts.
Parameters:
callback(function): Callback function with signature(error, charts)
Returns:
chartsarray with objects containing:[ { name: 'Hot 100', url: 'http://www.billboard.com/charts/hot-100' } // ... more charts ]
Available Charts
hot-100- Billboard Hot 100latin-songs- Hot Latin Songsartist-100- Artist 100- And many more! Use
listCharts()to see all available charts.
Error Handling
The library uses callback-style error handling:
getChart('hot-100', (err, chart) => {
if (err) {
console.error('Error fetching chart:', err);
return;
}
// Use chart data
console.log(chart);
});Development
Prerequisites
- Node.js 18.0.0 or higher
- npm
Setup
git clone https://github.com/aribradshaw/billboard-top-100.git
cd billboard-top-100
npm installRunning Tests
npm testLinting
npm run lintChanges from Original
This fork includes the following improvements over the original library:
Modern Dependencies:
- Replaced deprecated
requestpackage withnode-fetch - Updated all dependencies to latest versions
- Removed security vulnerabilities
- Replaced deprecated
ES Module Support:
- Full ES module support with
import/export - Compatible with modern Node.js applications
- TypeScript-friendly
- Full ES module support with
Better Error Handling:
- Improved error messages
- More robust HTTP request handling
Code Quality:
- Updated ESLint configuration
- Better code formatting
- Removed deprecated code patterns
License
MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Disclaimer
This library scrapes Billboard's website. Please be respectful of their servers and use this library responsibly. Billboard's terms of service should be reviewed before using this library in production applications.