OSRS Item Data

A TypeScript package for parsing Old School RuneScape item IDs, names, and icon images from the OSRS Wiki.

Features

- 16,000+ OSRS Items: Pre-scraped data from the OSRS Wiki
- Image URL Generation: Automatically construct image URLs for any item
- TypeScript Support: Full type definitions included
- Flexible API: Search by ID, name, or filter items
- Variant Handling: Properly handles item variants (e.g., charged, broken, poisoned)
- Zero Dependencies: No runtime dependencies (scraper uses cheerio for build-time only)

Installation

``bash
npm install osrs-item-data
`

Quick Start

`typescript
import { getItemById, searchItemsByName, getItemImageUrl } from 'osrs-item-data';

// Get item by ID
const item = getItemById(13263);
console.log(item);
// {
// id: 13263,
// name: 'Abyssal bludgeon',
// baseName: 'Abyssal bludgeon',
// imageUrl: 'https://oldschool.runescape.wiki/images/thumb/Abyssal_bludgeon_detail.png/120px-Abyssal_bludgeon_detail.png'
// }

// Search items by name
const items = searchItemsByName('dragon');
console.log(items.length); // All items with "dragon" in the name

// Get image URL for any item
const imageUrl = getItemImageUrl('Abyssal whip');
console.log(imageUrl);
// 'https://oldschool.runescape.wiki/images/thumb/Abyssal_whip_detail.png/120px-Abyssal_whip_detail.png'
`

API Reference

$3

#### getItemById(id: number): OsrsItem | undefined

Retrieve an item by its numeric ID.

`typescript
const item = getItemById(4151); // Dragon warhammer
`

#### getItemsById(id: number): OsrsItem[]

Get all items matching a specific ID (handles cases where multiple variants share IDs).

`typescript
const items = getItemsById(1704); // All items with ID 1704
`

#### getItemByName(name: string): OsrsItem | undefined

Get an item by its exact name (case-sensitive).

`typescript
const item = getItemByName('Twisted bow');
`

#### searchItemsByName(query: string, limit?: number): OsrsItem[]

Search for items by name (case-insensitive, partial match).

`typescript
const items = searchItemsByName('godsword', 5); // First 5 items matching "godsword"
`

#### getAllItems(filter?: ItemFilter): OsrsItem[]

Get all items, optionally filtered.

`typescript
// Get all items
const allItems = getAllItems();

// Get items with variants only
const variantItems = getAllItems({ hasVariant: true });

// Get first 100 items containing "rune"
const runeItems = getAllItems({
nameContains: 'rune',
limit: 100
});
`

$3

#### getItemImageUrl(itemName: string, options?: ImageUrlOptions): string

Construct an image URL for any item name.

`typescript
// Default: 120px thumbnail with variant
const url = getItemImageUrl('Amulet of glory#4');

// Custom width
const url = getItemImageUrl('Dragon scimitar', { width: 96 });

// Full-size image
const url = getItemImageUrl('Dragon scimitar', { useThumb: false });

// Exclude variant from URL
const url = getItemImageUrl('Amulet of glory#4', { includeVariant: false });
`

#### getItemImageUrls(itemName: string, options?: ImageUrlOptions)

Get both variant and base image URLs (useful for fallback).

`typescript
const { variantUrl, baseUrl } = getItemImageUrls('Amulet of glory#4');
// variantUrl: URL with (4) in filename
// baseUrl: URL without variant
`

#### parseItemName(itemName: string)

Parse an item name into base name and variant.

`typescript
const { baseName, variant } = parseItemName('Corrupted scythe of vitur#Charged');
// baseName: 'Corrupted scythe of vitur'
// variant: 'Charged'
`

$3

#### getItemCount(): number

Get the total number of items in the dataset.

#### getUniqueBaseNames(): string[]

Get all unique base item names (without variants).

#### getItemVariants(baseName: string): OsrsItem[]

Get all variants for a specific base item name.

`typescript
const variants = getItemVariants('Amulet of glory');
// Returns all glory variants: base, #1, #2, #3, #4, #5, #6
`

TypeScript Types

`typescript
interface OsrsItem {
id: number | number[]; // Single ID or array for items with ID ranges
name: string; // Full name including variant (e.g., "Amulet of glory#4")
baseName: string; // Name without variant (e.g., "Amulet of glory")
variant?: string; // Variant identifier (e.g., "4", "Charged", "(p)")
imageUrl: string; // Pre-constructed image URL
}

interface ImageUrlOptions {
width?: number; // Thumbnail width in pixels (default: 120)
useThumb?: boolean; // Use thumbnail vs full-size (default: true)
includeVariant?: boolean; // Include variant in filename (default: true)
}

interface ItemFilter {
nameContains?: string; // Filter by name substring (case-insensitive)
hasVariant?: boolean; // Filter items with/without variants
limit?: number; // Limit number of results
}
`

Understanding Item Variants

OSRS items often have variants denoted by a # symbol:

- Charge levels: Amulet of glory#1 through #6
- Damage states: Ahrim's hood#100, #75, #50, #25, #broken
- Status effects: Abyssal dagger#(p), Adamant arrow#(p++)
- Item states: Corrupted scythe of vitur#Charged

The package handles these automatically:
- The # postfix is removed when constructing image URLs
- Variants are converted to parentheses format: item#variant → item(variant)_detail.png
- You can choose to include or exclude variants in image URLs

Updating Item Data

The package includes a scraper script to update item data:

`bash
npm run scrape
`

This fetches the latest data from the OSRS Wiki and updates src/data/items.json.

Note: You only need to run this if you're contributing to the package or want to update to the latest wiki data.

Publishing to NPM

This package is configured to publish automatically via GitHub Actions:

1. Create a release on GitHub
2. The workflow will automatically:
- Run tests
- Build the package
- Publish to NPM

Setup required:
- Add NPM_TOKEN to your repository secrets
- Get your NPM token from https://www.npmjs.com/settings/[username]/tokens

Development

`bash


Install dependencies

npm install

Run tests

npm test

Build package

npm run build

Scrape latest data

npm run scrape
`

How It Works

1. Scraping: The scraper fetches the Item_IDs wiki page and parses the item table
2. Image URLs: Image URLs are constructed using the wiki's image naming convention
3. Special Characters: Apostrophes, parentheses, and other special characters are properly URL-encoded
4. Variants: Item variants (denoted by #) are handled by converting them to parentheses format

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run npm test` to ensure all tests pass
5. Submit a pull request

License

MIT

Data Source

All item data is sourced from the Old School RuneScape Wiki, which is licensed under CC BY-NC-SA 3.0.

Disclaimer

This package is not affiliated with or endorsed by Jagex Ltd. Old School RuneScape is a registered trademark of Jagex Ltd.