OSRS Wiki Bucket Builder

npm install @dava96/osrs-wiki-bucket-builder

Quick Start

import { bucket, BucketResponse } from '@dava96/osrs-wiki-bucket-builder';
import type { InferBucketResult } from '@dava96/osrs-wiki-bucket-builder';

const query = bucket('exchange')
    .select('id', 'name', 'value')
    .where('name', 'Abyssal whip');

// .toUrl() generates the full API URL, ready to fetch
const raw = await fetch(query.toUrl()).then(r => r.json());

// BucketResponse.from() infers the result type from the query
const response = BucketResponse.from(query, raw);
const whip = response.first();
console.log(whip?.name);  // ✅ typed as string
console.log(whip?.value); // ✅ typed as number

Core Concepts

Guide

Selecting Fields

Use .select() to pick which fields to retrieve. Supports wildcards (*, alias.*) which are expanded client-side into explicit field lists.

const query = bucket('exchange')
    .select('name', 'value', 'limit')
    .limit(5)
    .run();

Filtering with Where

The .where() method supports equality, comparison operators, and chaining for implicit AND.

Equality (implicit =)

bucket('exchange')
    .select('name', 'value')
    .where('name', 'Dragon scimitar')
    .run();

Comparison Operators

Supported: =, !=, >, <, >=, <=

bucket('exchange')
    .select('name', 'value')
    .where('value', '>', 1000000)
    .limit(10)
    .run();

Convenience Filters

.whereNot(field, value) — exclude matches

bucket('exchange')
    .select('name', 'value')
    .whereNot('name', 'Coins')
    .where('value', '>', 0)
    .limit(10)
    .run();

.whereNull() / .whereNotNull() — null checks

bucket('infobox_item')
    .select('item_name', 'weight')
    .whereNotNull('weight')
    .limit(10)
    .run();

.whereBetween(field, [min, max]) — inclusive range

bucket('exchange')
    .select('name', 'value')
    .whereBetween('value', [10000, 100000])
    .limit(10)
    .run();

.whereIn(field, values) — match any value

bucket('exchange')
    .select('name', 'value')
    .whereIn('name', ['Bronze axe', 'Iron axe', 'Steel axe'])
    .run();

Combining Conditions

For complex logic, use the Bucket helper object:

import { bucket, Bucket } from '@dava96/osrs-wiki-bucket-builder';

Bucket.Or(...) — match any condition

bucket('exchange')
    .select('name', 'value')
    .where(Bucket.Or(
        ['name', 'Bronze axe'],
        ['name', 'Iron axe'],
        ['name', 'Steel axe']
    ))
    .run();

Bucket.And(...) — all conditions must match

bucket('exchange')
    .select('name', 'value')
    .where(Bucket.And(
        ['value', '>', 1000],
        ['value', '<', 50000]
    ))
    .run();

Bucket.Not(...) — negate a condition

bucket('exchange')
    .select('name', 'value')
    .where(Bucket.Not(['name', 'Coins']))
    .run();

Bucket.Null() — represents a null value

bucket('infobox_item')
    .select('item_name', 'weight')
    .where('weight', '!=', Bucket.Null())
    .run();

Joining Buckets

Join two or more buckets to combine data from different sources, similar to a SQL JOIN.

Basic join

bucket('infobox_item')
    .join('exchange', 'item_name', 'name')
    .select('item_name', 'weight', 'exchange.value')
    .limit(5)
    .run();

Join with alias

Aliases are resolved to real bucket names in the generated Lua:

bucket('infobox_item')
    .join('exchange', 'ex', 'item_name', 'name')
    .select('item_name', 'ex.value', 'ex.limit')
    .where('ex.value', '>', 100000)
    .limit(10)
    .run();

Multiple joins

Join three buckets to combine item info, GE prices, and shop data:

bucket('infobox_item')
    .join('exchange', 'item_name', 'name')
    .join('storeline', 'item_name', 'sold_item')
    .select(
        'item_name', 'weight',
        'exchange.value',
        'storeline.sold_by', 'storeline.store_sell_price'
    )
    .limit(5)
    .run();

Ordering & Pagination

.orderBy(field, direction)

Sort by a selected field. The field must appear in a prior .select() call.

.paginate(page, perPage)

A helper that computes .limit() and .offset() from a 1-based page number:

const page2 = bucket('exchange')
    .select('name', 'value')
    .where('value', '>', 0)
    .orderBy('value', 'desc')
    .paginate(2, 25)
    .run();

.first()

Shorthand for .limit(1) — grab just the top result:

const top = bucket('exchange')
    .select('name', 'value')
    .orderBy('value', 'desc')
    .first()
    .run();

Conditional Logic — .when()

Conditionally apply query modifications based on runtime values:

const isMembers = true;
const query = bucket('infobox_item')
    .select('item_name', 'value', 'members')
    .when(isMembers, (q) => q.where('members', true))
    .limit(10)
    .run();

Reusing Queries — .clone()

Creates an independent deep copy. Changes to the clone don't affect the original:

const base = bucket('exchange')
    .select('name', 'value')
    .where('value', '>', 0);

const topExpensive = base.clone().orderBy('value', 'desc').limit(5);
const topCheap = base.clone().orderBy('value', 'asc').limit(5);

Executing Queries

.run() — URL-encoded output (default)

const query = bucket('exchange').select('name', 'value').run();
const url = `https://oldschool.runescape.wiki/api.php?action=bucket&format=json&query=${query}`;

.run({ encodeURI: false }) — raw Lua output

const lua = bucket('exchange').select('name', 'value').run({ encodeURI: false });
// bucket('exchange').select('name', 'value').run()

.printSQL() — raw Lua string

Equivalent to .run({ encodeURI: false }):

const lua = bucket('exchange').select('name', 'value').printSQL();

BucketResponse — response wrapper

Wraps the raw API response with convenient accessors:

import { bucket, BucketResponse } from '@dava96/osrs-wiki-bucket-builder';

const query = bucket('exchange').select('name', 'value').first();
const raw = await fetch(query.toUrl()).then(r => r.json());
const response = new BucketResponse(raw);

response.results  // Array of matching rows
response.first()  // First result or undefined
response.query    // The Lua query echoed by the API
response.error    // Error message if the query failed

BucketResponse.from() — typed responses from queries

Automatically infers the result type from the query builder — no manual type parameter needed:

const query = bucket('exchange').select('name', 'value');
const raw = await fetch(query.toUrl()).then(r => r.json());
const response = BucketResponse.from(query, raw);

response.first()?.name;  // ✅ typed as string
response.first()?.value; // ✅ typed as number

InferBucketResult — extract the result type

Use InferBucketResult<typeof query> to extract the inferred row type without executing the query:

import type { InferBucketResult } from '@dava96/osrs-wiki-bucket-builder';

const query = bucket('exchange').select('id', 'name', 'value');
type ExchangeRow = InferBucketResult<typeof query>;
// { id: number; name: string; value: number; page_name: string; page_name_sub: string }

.toUrl() — generate the full API URL

Generates the complete Wiki API URL, ready to pass to fetch():

const url = bucket('exchange')
    .select('name', 'value')
    .where('value', '>', 100000)
    .limit(10)
    .toUrl();

const data = await fetch(url).then(r => r.json());

Full Example

Multi-join with aliases, mixed conditions, ordering, and pagination — all in one query:

import { bucket, Bucket } from '@dava96/osrs-wiki-bucket-builder';

const query = bucket('infobox_item')
    .join('exchange', 'ex', 'item_name', 'name')
    .join('storeline', 'shop', 'item_name', 'sold_item')
    .select(
        'item_name', 'weight',
        'ex.value', 'ex.limit',
        'shop.sold_by', 'shop.store_sell_price'
    )
    .where('ex.value', '>', 1000)
    .whereNotNull('shop.sold_by')
    .orderBy('ex.value', 'desc')
    .limit(10)
    .run();

API Reference

Bucket Helpers

Resources

Bucket Usage Guide · Bucket API · Browse All Buckets · GitHub · Icons Provided by osrs-icons