better-wiki

A typed, cache-aware client for MediaWiki / Fandom wikis. Wraps the api.php endpoint with typed responses, in-memory caching, and resilient HTTP.

Features

• Typed responses — every method returns a typed result.
• Built-in caching — identical requests are served from an in-memory cache (TTL configurable).
• Resilient HTTP — sends a User-Agent, aborts slow requests, and retries with backoff.
• ESM, tree-shakeable — ships ES modules with declaration maps.

Installation

npm install better-wiki

Requires Node.js 18+ (for the global fetch/AbortController), or any modern browser.

Quick start

import { wiki } from 'better-wiki';

const client = wiki('https://dc.fandom.com');

// Search pages
const pages = await client.getPage('Absolute Superman');
const page = pages[0];

// Infobox and images
const infobox = await page.getInfobox();
const images = await page.getImages(300); // optional width to scale URLs

// Lookup by title or ID
const exact = await client.getPageByTitle('Absolute Superman Vol 1 1');
const byId = await client.getPageById(123456);

// Categories
const members = await client.getPagesByCategory('Category:DC Comics characters');

// Raw wikitext or structured infobox key/value map
const wikitext = await client.getPageContent(page.id);
const structured = await client.getPageContent(page.id, { structured: true });

Configuration

wiki(url, options) accepts an options object (all fields optional):

| Option | Type | Default | Description | | ----------- | -------- | ------------------- | --------------------------------------------------------------- | | CACHE_TTL | number | 300000 (5 min) | How long, in ms, an API response stays cached. | | userAgent | string | better-wiki (...) | User-Agent header sent with every request. | | timeout | number | 15000 | Abort a request after this many ms. | | retries | number | 2 | Number of retries (with backoff) on a failed/timed-out request. | | publisher | string | '' | Publisher name included in series-related data. |

const client = wiki('https://dc.fandom.com', {
  CACHE_TTL: 60_000,
  userAgent: 'my-app/1.0 ([email protected])',
});

API

wiki(url, options?) → Wiki

Factory function — returns a Wiki client for the given wiki URL.

Client methods

| Method | Returns | | ---------------------------------------------- | --------------------------------------------------------- | | getPage(query, flags?) | WikiPage[] — full-text search results | | getPageById(pageId, flags?) | WikiPage \| null | | getPageById(pageIds[], flags?) | WikiPage[] — batch lookup by IDs | | getPageByTitle(title, flags?) | WikiPage \| null | | getPagesByCategory(category, flags?) | WikiPage[] | | getPageContent(pageId) | string \| undefined — raw wikitext | | getPageContent(pageId, { structured: true }) | Record<string, string> — parsed infobox | | getCategoryMembers(categoryTitle, flags?) | WikiCategoryMemberItem[] | | getCategoryMembers(titles[], flags?) | WikiCategoryMemberItem[] — intersection across titles | | searchCategories(query) | string[] | | getCategoriesFromPage(pageId) | Array<{ ns, title }> | | getThumbnailById(pageId, width?) | string — thumbnail URL, optionally scaled to width px | | clearCache() | void |

Pass flags to any page-fetching method to filter or augment results:

| Flag | Type | Description | | --------------- | ---------- | ------------------------------------------------------------------------- | | category | string[] | Filter results to pages belonging to all listed categories (AND). | | categoriesOr | string[] | Filter results to pages belonging to any listed category (OR). | | thumbnailSize | number | Scale thumbnail URLs to this width (px) when building WikiPage results. | | limit | number | Cap the number of results returned (default: 20 for getPage). |

WikiPage properties

| Property | Type | Description | | -------------- | ---------- | ------------------------------------------------------ | | id | number | MediaWiki page ID. | | title | string | Page title. | | thumbnail | string | Thumbnail URL (empty string if the page has no image). | | categories | string[] | Category titles the page belongs to. | | canonicalUrl | string | Canonical URL of the page. |

WikiSearchGeneratorPageItem properties

Raw page shape returned by the search generator (before WikiPage is constructed).

| Property | Type | Description | | -------------- | -------------------------------------- | ----------------------------------------------------------- | | pageid | number | MediaWiki page ID. | | ns | number | MediaWiki namespace ID. | | title | string | Page title. | | index | number | Position in the search result set. | | thumbnail | string | Thumbnail URL (optional — absent if the page has no image). | | categories | Array<{ ns: number; title: string }> | Categories the page belongs to. | | canonicalUrl | string | Canonical URL of the page. |

WikiPage instance methods

| Method | Returns | | ------------------------ | --------------------------------------------------------- | | getInfobox() | Record<string, string> — infobox key/value pairs | | getImages(width?) | string[] — image URLs, optionally scaled | | getGallery(width?) | string[] — gallery image URLs | | getPageContent() | string \| undefined — raw wikitext | | getStructuredContent() | Record<string, string> — first infobox template, parsed |

Plugins

Plugins extend the base Wiki client with domain-specific methods. Pass { plugin } instead of a URL — the plugin supplies the target wiki URL automatically.

import { wiki } from 'better-wiki';

const dc = wiki({ plugin: 'dc-fandom' });

// Fetch a comic by search query (picks the best match)
const comic = await dc.getComic('Batman #700 (2010)');
console.log(comic.credits.writers, comic.appearing.featuredCharacters);

// Fetch by page ID
const comicById = await dc.getComicById(123456);

// Fetch a volume
const volume = await dc.getVolume('Batman Vol 1');
const volumeById = await dc.getVolumeById(789);

// Multiple results
const allMatches = await dc.getComic('Batman', { multiple: true });

All base Wiki methods (getPage, clearCache, etc.) remain available on the returned client.

dc-fandom plugin

Targets https://dc.fandom.com. Adds:

| Method | Returns | Description | | -------------------------------------------- | ----------------------- | -------------------------------------------- | | getComic(query, flags?) | WikiComic \| null | Best-match comic by search query | | getComic(query, { multiple: true }) | WikiComic[] | All matching comics | | getComicById(pageId, flags?) | WikiComic \| null | Comic by MediaWiki page ID | | getComicById(pageIds[], flags?) | WikiComic[] | Batch comic lookup by IDs | | getVolume(query, flags?) | WikiVolume \| null | Best-match volume by search query | | getVolume(query, { multiple: true }) | WikiVolume[] | All matching volumes | | getVolumeById(pageId, thumbnailSize?) | WikiVolume \| null | Volume by MediaWiki page ID | | getVolumeById(pageIds[], thumbnailSize?) | WikiVolume[] | Batch volume lookup by IDs | | getCharacter(query, flags?) | WikiCharacter \| null | Best-match character by search query | | getCharacter(query, { multiple: true }) | WikiCharacter[] | All matching characters | | getCharacterById(pageId, flags?) | WikiCharacter \| null | Character by MediaWiki page ID | | getCharacterAppearances(title, { sorted }) | WikiComic[] | All comics in Category:<title>/Appearances |

A WikiCharacter carries bio fields (realName, aliases, alignment, …), parsed history sections, list fields (powers, abilities, equipment, …), an optional quotation, and a getAppearances({ sorted? }) method returning its Appearances comics.

getComic accepts additional flags:

| Flag | Type | Description | | -------------------- | ---------- | -------------------------------------------------------------------------------------- | | thumbnailSize | number | Scale cover thumbnail URLs to this width (px). | | includeCollections | boolean | Also match pages in Category:Collected Editions (default: comics only). | | categoriesIn | string[] | AND-filter: result must belong to all listed categories in addition to the OR set. | | sorted | boolean | With multiple: true, return comics ordered by release date (oldest first). |

Pass flags.thumbnailSize (number, px) to scale cover thumbnail URLs.

All returned types (WikiComic, WikiVolume, WikiCredits, WikiAppearingSection, etc.) are exported from the package root for use in your own type annotations.

Development

pnpm install
pnpm test         # run the unit tests (mocking fetch)
pnpm run lint     # eslint + prettier
pnpm run build    # emit dist/

License

MIT