howlongtobeat-core

A TypeScript/Deno library to retrieve game completion times from HowLongToBeat.com.

Features

• Search games by name or HLTB ID
• Get completion times (Main Story, Main + Extra, Completionist)
• Get game statistics (releases, ratings, popular games by year/platform)
• Dual similarity algorithms (Gestalt & Levenshtein)
• Filter by DLC, mods, or hacks
• Works with Deno, Node.js, and browsers
• TypeScript-first with full type definitions

Installation

Deno

import { HowLongToBeat } from "jsr:howlongtobeat-core";

Node.js / npm

npm install howlongtobeat-core

import { HowLongToBeat } from "howlongtobeat-core";

Usage

Search by Name

import { HowLongToBeat } from "howlongtobeat-core";

const hltb = new HowLongToBeat();
const results = await hltb.search("Elden Ring");

if (results && results.length > 0) {
  const game = results[0];
  console.log(`${game.gameName}`);
  console.log(`  Main Story: ${game.mainStory} hours`);
  console.log(`  Main + Extra: ${game.mainExtra} hours`);
  console.log(`  Completionist: ${game.completionist} hours`);
}

Search by ID

const game = await hltb.searchById(68151); // Elden Ring
console.log(game?.gameName); // "Elden Ring"

Get Game Statistics

// Get stats for a specific year (returns monthly breakdown)
const stats2026 = await hltb.getGameStats({ year: "2026" });
if (stats2026) {
  console.log(`Total releases: ${stats2026.breakdown.totalReleases}`);
  console.log(`Average time: ${stats2026.breakdown.avgTime}`);
  console.log(`Average rating: ${stats2026.breakdown.avgRating}`);
  console.log(`Monthly breakdown:`, stats2026.months);
}

// Get all-time stats (returns yearly breakdown)
const allTimeStats = await hltb.getGameStats();
console.log(`Yearly breakdown:`, allTimeStats?.years);

// Filter by platform, genre, perspective, etc.
const pcStats = await hltb.getGameStats({
  platform: "PC",
  year: "2026",
  genre: "RPG",
});

With Options

const hltb = new HowLongToBeat({
  minimumSimilarity: 0.5, // Filter results below 50% similarity
  autoFilterTimes: true, // Nullify irrelevant times (e.g., SP times for MP-only games)
  similarityAlgorithm: "gestalt", // or "levenshtein"
});

Filter DLC/Mods

import { HowLongToBeat, SearchModifiers } from "howlongtobeat-core";

const hltb = new HowLongToBeat();
const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);

API Reference

HowLongToBeat

Constructor Options

| Option | Type | Default | Description | | --------------------- | ---------------------------- | ----------- | ------------------------------------------------------ | | minimumSimilarity | number | 0.4 | Filter results below this similarity threshold (0-1) | | autoFilterTimes | boolean | false | Auto-nullify irrelevant time fields based on game type | | similarityAlgorithm | "gestalt" \| "levenshtein" | "gestalt" | Algorithm for string similarity matching |

Methods

| Method | Returns | Description | | ------------------------- | --------------------------------------- | -------------------- | | search(name, modifier?) | Promise<HowLongToBeatEntry[] \| null> | Search games by name | | searchById(id) | Promise<HowLongToBeatEntry \| null> | Get game by HLTB ID | | getGameStats(options?) | Promise<GameStatsResponse \| null> | Get game statistics |

HowLongToBeatEntry

| Property | Type | Description | | ------------------ | ------------------ | ---------------------------- | | gameId | number | HLTB game ID | | gameName | string \| null | Game title | | gameImageUrl | string \| null | Cover image URL | | gameWebLink | string | Link to HLTB page | | mainStory | number \| null | Main story time (hours) | | mainExtra | number \| null | Main + extras time (hours) | | completionist | number \| null | 100% completion time (hours) | | allStyles | number \| null | Average of all playstyles | | similarity | number | Match similarity (0-1) | | reviewScore | number \| null | User review score | | profilePlatforms | string[] \| null | Available platforms | | releaseWorld | number \| null | Release year |

SearchModifiers

| Value | Description | | --------------- | --------------------- | | NONE | No filter (default) | | ISOLATE_DLC | Only show DLC | | ISOLATE_MODS | Only show mods | | ISOLATE_HACKS | Only show hacks | | HIDE_DLC | Hide DLC from results |

GameStatsOptions

| Option | Type | Description | | ------------- | -------- | ------------------------------------------------ | | platform | string | Filter by platform (e.g., "PC", "PlayStation 5") | | year | string | Filter by year (e.g., "2026") | | perspective | string | Filter by perspective (e.g., "First-Person") | | flow | string | Filter by pacing/flow | | genre | string | Filter by genre (e.g., "RPG", "Action") |

GameStatsResponse

| Property | Type | Description | | ------------------------ | ------------------------ | --------------------------------------- | | tags | StatsTags | Applied filter tags | | breakdown | StatsBreakdown | Summary stats (releases, avgTime, etc.) | | months | Record<string, number> | Monthly distribution (when year set) | | years | Record<string, number> | Yearly distribution (when year not set) | | platformList | PlatformCount[] | Games per platform | | categoryMostBacklogged | CategoryEntry[] | Most backlogged games | | categoryMostCompleted | CategoryEntry[] | Most completed games | | categoryBestRated | CategoryEntry[] | Highest rated games | | categoryTopPlaying | CategoryEntry[] | Currently most played games | | popularGames | PopularGameEntry[] | Popular games list |

Development

# Run tests
deno task test

# Run unit tests only
deno task test:unit

# Run integration tests (requires network)
deno task test:integration

# Type check
deno task check

# Format code
deno task fmt

# Lint
deno task lint

License

MIT © 2026