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 defined error 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-fetch instead of deprecated request package
• ✅ 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-100

Usage

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 above

API 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 chart
• callback (function): Callback function with signature (error, chart)

Returns:

• chart object 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:

• charts array with objects containing:

  [
    {
      name: 'Hot 100',
      url: 'http://www.billboard.com/charts/hot-100'
    }
    // ... more charts
  ]

Available Charts

• hot-100 - Billboard Hot 100
• latin-songs - Hot Latin Songs
• artist-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 install

Running Tests

npm test

Linting

npm run lint

Changes from Original

This fork includes the following improvements over the original library:

1. Modern Dependencies:

   • Replaced deprecated request package with node-fetch
   • Updated all dependencies to latest versions
   • Removed security vulnerabilities

2. ES Module Support:

   • Full ES module support with import/export
   • Compatible with modern Node.js applications
   • TypeScript-friendly

3. Better Error Handling:

   • Improved error messages
   • More robust HTTP request handling

4. 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.