pokedex-ts

A fast, simple, and fully-typed TypeScript wrapper for the PokeAPI. Built-in LRU caching, zero runtime dependencies, and a clean API that abstracts away all the complexity.

✨ Features

• ⚡ Fast — In-memory LRU cache so repeated lookups are instant
• 🎯 Simple — One class, intuitive method names, clean return types
• 🔒 Fully Typed — Written in TypeScript with complete type definitions
• 📦 Zero Dependencies — Uses native fetch (Node 18+)
• 🔍 Search — Fuzzy search Pokémon by partial name

📦 Installation

npm install pokedex-ts

yarn add pokedex-ts

🚀 Quick Start

import { Pokedex } from "pokedex-ts";

const dex = new Pokedex();

// Get a Pokémon by name or ID
const pikachu = await dex.getPokemon("pikachu");
console.log(pikachu.name);       // "pikachu"
console.log(pikachu.types);      // [{ slot: 1, name: "electric" }]
console.log(pikachu.stats);      // [{ baseStat: 35, effort: 0, name: "hp" }, ...]

// Get all fire-type Pokémon
const fireTypes = await dex.getPokemonByType("fire");
console.log(fireTypes.length);   // 90+

// Search by partial name
const results = await dex.searchPokemon("char");
// → [{ name: "charmander" }, { name: "charmeleon" }, { name: "charizard" }, ...]

📖 API Reference

new Pokedex(options?)

| Option | Type | Default | Description | |---|---|---|---| | cacheMaxSize | number | 500 | Max entries in the LRU cache | | cacheTTL | number | 300000 | Cache entry lifetime in ms (5 min) |

Methods

| Method | Returns | Description | |---|---|---| | getPokemon(nameOrId) | Promise<Pokemon> | Get a single Pokémon by name or Dex number | | getPokemonSpecies(nameOrId) | Promise<PokemonSpecies> | Get species info (flavor text, generation, legendary status) | | getAllPokemon(limit?, offset?) | Promise<PaginatedResult<NamedResource>> | Paginated list of all Pokémon | | getPokemonByType(type) | Promise<NamedResource[]> | All Pokémon of a given type | | getGeneration(nameOrId) | Promise<Generation> | Get a generation and its Pokémon list | | getAllGenerations() | Promise<NamedResource[]> | List every generation | | getType(nameOrId) | Promise<TypeDetail> | Get type details and damage relations | | getAllTypes() | Promise<NamedResource[]> | List every type | | searchPokemon(query) | Promise<NamedResource[]> | Fuzzy search Pokémon by partial name | | clearCache() | void | Flush the in-memory cache |

Key Types

interface Pokemon {
  id: number;
  name: string;
  height: number;
  weight: number;
  baseExperience: number;
  types: PokemonType[];
  stats: PokemonStat[];
  abilities: PokemonAbility[];
  sprites: PokemonSprites;
  moves: PokemonMove[];
}

interface PokemonSpecies {
  id: number;
  name: string;
  generation: string;
  flavorTextEntries: FlavorTextEntry[];
  evolutionChainUrl: string | null;
  isLegendary: boolean;
  isMythical: boolean;
  habitat: string | null;
  color: string;
}

interface Generation {
  id: number;
  name: string;
  region: string;
  pokemonSpecies: NamedResource[];
  types: NamedResource[];
  moves: NamedResource[];
}

interface TypeDetail {
  id: number;
  name: string;
  damageRelations: DamageRelations;
  pokemon: NamedResource[];
}

🧪 Examples

Get Generation I Pokémon

const gen1 = await dex.getGeneration(1);
console.log(`${gen1.name} (${gen1.region}): ${gen1.pokemonSpecies.length} Pokémon`);
// → "generation-i (kanto): 151 Pokémon"

Type Matchups

const fire = await dex.getType("fire");
console.log("Fire is weak to:", fire.damageRelations.doubleDamageFrom.map(t => t.name));
// → ["ground", "rock", "water"]

Species Info

const species = await dex.getPokemonSpecies("mewtwo");
console.log(species.isLegendary);  // true
console.log(species.generation);   // "generation-i"

Custom Cache Settings

const dex = new Pokedex({
  cacheMaxSize: 1000,     // Store up to 1000 entries
  cacheTTL: 600_000,      // 10-minute TTL
});

📋 Requirements

• Node.js ≥ 18 (uses native fetch)

📄 License

MIT