osu-utils

A comprehensive Node.js library for osu! development, providing tools for API integration, PP calculation, beatmap parsing, and various osu!-related utilities.

Features

• Complete osu! API v1 Client - Full interface with automatic data formatting
• Advanced PP Calculation - High-performance PP and difficulty calculations using rosu-pp-js
• Multi-mode Support - Support for all osu! game modes (osu!, taiko, catch, mania)
• Beatmap Parsing - Extract metadata and information from beatmap files
• Utility Functions - Accuracy calculations, mod conversions, time formatting
• Error Handling - Robust error handling with automatic retry and caching
• Type Safety - Comprehensive parameter validation and type checking

Installation

npm install osu-utils

Quick Start

const { osuUtils, ApiV1 } = require('osu-utils');

// API Client
const api = new ApiV1('your-api-key');
const user = await api.getUser('Puparia');

// PP Calculation
const fs = require('fs');
const beatmapContent = fs.readFileSync('beatmap.osu', 'utf8');
const result = osuUtils.CalculatePP(beatmapContent, { combo: 200, misses: 0 });

console.log(`Star Rating: ${result.difficulty.stars}`);
console.log(`PP: ${result.performance.pp}`);

osu! API v1 Client

Complete interface for osu! API v1 with automatic data formatting and multi-mode support.

const { ApiV1 } = require('osu-utils');
const api = new ApiV1('your-api-key');

const user = await api.getUser('Puparia');
const bestScores = await api.getUserBest('Puparia', 0, 5);

Features: Auto-detection, structured responses, all game modes, error handling, retry logic, caching
Documentation: Data Formats • Examples • Error Handling

Performance Points (PP) Calculation

osu-utils includes advanced PP and difficulty calculation capabilities!

This integration uses rosu-pp-js by @MaxOhn - a high-performance JavaScript binding to the Rust library rosu-pp through WebAssembly. This provides:

• Ultra-fast calculations using WebAssembly
• Industry-standard accuracy with rosu-pp algorithm
• Full game mode support (osu!, taiko, catch, mania)
• Advanced features like strain data and gradual calculations

PP Calculation Methods:

• CalculatePP() - Complete difficulty + performance calculation
• CalculateDifficulty() - Difficulty calculation only
• GetStrains() - Strain data for difficulty visualization
• ConvertBeatmap() - Convert beatmaps between game modes
• GetBeatmapInfo() - Extract comprehensive beatmap metadata

Special thanks to @MaxOhn for creating the amazing rosu-pp-js library!

Usage Examples

API Client

const { ApiV1 } = require('osu-utils');
const api = new ApiV1('your-api-key');

// Get user information
const user = await api.getUser('Puparia');
console.log(`${user.username} is level ${user.stats.level}`);

// Get best scores with beatmap info
const bestScores = await api.getUserBest('Puparia', 0, 5, true);
bestScores.forEach(score => {
    console.log(`${score.beatmap.metadata.artist} - ${score.beatmap.metadata.title}`);
    console.log(`Score: ${score.score.toLocaleString()} - ${score.performance.accuracy}%`);
});

// Multi-mode support
const modes = [
    { name: 'osu!', id: 0 },
    { name: 'Taiko', id: 1 },
    { name: 'CTB', id: 2 },
    { name: 'Mania', id: 3 }
];

for (const mode of modes) {
    const user = await api.getUser('Puparia', mode.id);
    console.log(`${mode.name}: ${user.stats.pp} PP (#${user.stats.ppRank})`);
}

PP Calculation

const { osuUtils } = require('osu-utils');
const fs = require('fs');

// Read beatmap content
const beatmapContent = fs.readFileSync('beatmap.osu', 'utf8');

// Calculate PP for perfect score
const result = osuUtils.CalculatePP(beatmapContent, {
    combo: 200,
    misses: 0,
    mods: 0
});

console.log(`Star Rating: ${result.difficulty.stars}`);
console.log(`PP: ${result.performance.pp}`);

// Calculate PP with mods
const hrResult = osuUtils.CalculatePP(beatmapContent, {
    combo: 200,
    misses: 0,
    mods: 16 // Hard Rock
});

console.log(`PP with HR: ${hrResult.performance.pp}`);

// Calculate difficulty only (faster)
const difficulty = osuUtils.CalculateDifficulty(beatmapContent, {
    mods: 64 // Double Time
});

console.log(`Star Rating with DT: ${difficulty.stars}`);

Utility Functions

const { osuUtils } = require('osu-utils');

// Calculate accuracy
const accuracy = osuUtils.CalcAccuracy(0, 100, 50, 25, 5); // osu! mode
console.log(`Accuracy: ${accuracy}%`);

// Format time
const formatted = osuUtils.FormatMs(125000);
console.log(formatted); // "2:05.000"

// Convert mods
const bitmask = osuUtils.ModsStringToInt('HDHRDT');
console.log(bitmask); // 88

const modsString = osuUtils.ModsIntToString(88);
console.log(modsString); // "HDHRDT"

// Check mods
const hasHidden = osuUtils.HasMod(88, 'HD');
console.log(hasHidden); // true

Error Handling

try {
    const user = await api.getUser('Puparia');
    if (user === null) {
        console.log('User not found');
    } else {
        console.log('User found:', user.username);
    }
} catch (error) {
    console.error('API Error:', error.message);
}

Performance Features

• Automatic Caching - API responses are cached for 5 minutes
• Retry Logic - Automatic retry with exponential backoff for network errors
• WebAssembly - PP calculations use WebAssembly for high performance
• Memory Management - Beatmaps are automatically freed after calculations
• Parameter Validation - Comprehensive input validation and error messages

Documentation

• API Reference - Complete API documentation
• Data Formats - Detailed data structure documentation
• Examples - Practical usage examples
• Error Handling - Error handling patterns and best practices
• PP Calculation - Detailed PP calculation documentation

Testing

The library includes a comprehensive test suite covering all functionality:

# Run all tests
npm test

# Run API-specific tests
npm run test:api

Test Coverage:

• API Client (8 tests) - All endpoints and error handling
• PP Calculation (4 tests) - All game modes and mods
• Star Rating (3 tests) - Difficulty calculations
• Beatmap Parsing (3 tests) - Metadata extraction
• Utility Functions (4 tests) - Accuracy, time formatting, mods
• Error Handling (2 tests) - Invalid inputs and network errors

Requirements

• Node.js 12.0.0 or higher
• osu! API key (for API client functionality)

License

MIT License - see LICENSE file for details.

Contributing

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

Support

For questions, issues, or feature requests, please open an issue on GitHub.

---

Made with ❤️ for the osu! community