osu-utils/README.md

Basics Utils for osu projects

# osu-utils
[![npm version](https://img.shields.io/npm/v/osu-utils)](https://www.npmjs.com/package/osu-utils)
[![Downloads](https://img.shields.io/npm/dt/osu-utils)](https://www.npmjs.com/package/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

```bash
npm install osu-utils
```

## Quick Start

```javascript
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.**

```javascript
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](api/v1/DATA_FORMATS.md) • [Examples](api/v1/EXAMPLES.md) • [Error Handling](api/v1/ERROR_HANDLING.md)

### Testing

Run the comprehensive test suite:
```bash
npm test
```

Run API-specific tests:
```bash
npm run test:api
```

## Performance Points (PP) Calculation

**osu-utils includes advanced PP and difficulty calculation capabilities!** 

This integration uses [rosu-pp-js](https://github.com/MaxOhn/rosu-pp-js) by [@MaxOhn](https://github.com/MaxOhn) - a high-performance JavaScript binding to the Rust library [rosu-pp](https://github.com/MaxOhn/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](https://github.com/MaxOhn) for creating the amazing [rosu-pp-js](https://github.com/MaxOhn/rosu-pp-js) library!** 

## Usage Examples

### API Client

```javascript
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

```javascript
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

```javascript
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

```javascript
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

## Testing

The library includes a comprehensive test suite covering all functionality:

```bash
# 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

## Documentation

- **[API Reference](API_REFERENCE.md)** - Complete API documentation
- **[Data Formats](api/v1/DATA_FORMATS.md)** - Detailed data structure documentation
- **[Examples](api/v1/EXAMPLES.md)** - Practical usage examples
- **[Error Handling](api/v1/ERROR_HANDLING.md)** - Error handling patterns and best practices
- **[PP Calculation](PP_CALCULATION.md)** - Detailed PP calculation documentation

## Requirements

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

## License

MIT License - see [LICENSE](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