PokemonAppEngine

A lightweight, type-safe TypeScript engine for fetching Pokémon data from the PokéAPI.

Features

• 🎯 Fully Typed - TypeScript interfaces for all Pokémon data
• 🚀 Simple API - Clean, intuitive methods for fetching Pokémon data
• 📦 Lightweight - No dependencies, just native fetch
• 🔄 Pagination Support - Built-in pagination for list endpoints
• ⚡ Modern - Uses async/await and ES modules

Installation

npm install pokemon-app-engine
# or
yarn add pokemon-app-engine
# or
pnpm add pokemon-app-engine

Usage

Basic Setup

import { PokemonAppEngine } from 'pokemon-app-engine';

const engine = new PokemonAppEngine();

Fetch a Pokémon

Get detailed information about a specific Pokémon by ID or name:

// By ID
const pikachu = await engine.getBy(25);

// By name
const charizard = await engine.getBy('charizard');

console.log(pikachu.name); // "pikachu"
console.log(pikachu.types); // [{ slot: 1, type: { name: "electric", url: "..." } }]
console.log(pikachu.stats); // [{ base_stat: 35, effort: 0, stat: {...} }, ...]

Fetch Pokémon Species

Get species-specific information including evolution chain, habitat, and flavor text:

const species = await engine.getSpeciesBy('pikachu');

console.log(species.is_legendary); // false
console.log(species.habitat.name); // "forest"
console.log(species.evolution_chain.url); // "https://pokeapi.co/api/v2/evolution-chain/10/"

Fetch Pokémon Types

Get type information including damage relations and Pokémon of that type:

const electricType = await engine.getTypeBy('electric');

console.log(electricType.damage_relations.double_damage_to);
// [{ name: "water", url: "..." }, { name: "flying", url: "..." }]

console.log(electricType.pokemon);
// [{ slot: 1, pokemon: { name: "pikachu", url: "..." } }, ...]

List Pokémon (Paginated)

Fetch a paginated list of Pokémon:

// Get first 20 Pokémon
const pokemonList = await engine.getPokemons();

// Get next 20 Pokémon
const nextPage = await engine.getPokemons({ offset: 20, limit: 20 });

// Get 50 Pokémon starting from position 100
const customPage = await engine.getPokemons({ offset: 100, limit: 50 });

console.log(pokemonList.count); // Total count (e.g., 1302)
console.log(pokemonList.results); // Array of { name, url }
console.log(pokemonList.next); // URL to next page
console.log(pokemonList.previous); // URL to previous page

List All Types

Get all available Pokémon types:

const types = await engine.getTypes();

console.log(types.results);
// [
//   { name: "normal", url: "..." },
//   { name: "fighting", url: "..." },
//   { name: "flying", url: "..." },
//   ...
// ]

List All Generations

Get all Pokémon generations:

const generations = await engine.getGenerations();

console.log(generations.results);
// [
//   { name: "generation-i", url: "..." },
//   { name: "generation-ii", url: "..." },
//   ...
// ]

List All Species (Paginated)

Fetch a paginated list of Pokémon species:

const speciesList = await engine.getSpecies({ offset: 0, limit: 50 });

console.log(speciesList.results);
// [{ name: "bulbasaur", url: "..." }, ...]

List All Abilities (Paginated)

Fetch a paginated list of abilities:

const abilities = await engine.getAbilities({ offset: 0, limit: 50 });

console.log(abilities.results);
// [{ name: "stench", url: "..." }, { name: "drizzle", url: "..." }, ...]

Generic GET Request

For any custom endpoint not covered by the methods above:

import { Ability } from 'pokemon-app-engine';

// Fetch a specific ability
const overgrow = await engine.get<Ability>('https://pokeapi.co/api/v2/ability/65');

console.log(overgrow.name); // "overgrow"
console.log(overgrow.effect_entries[0].short_effect);

API Reference

Methods

| Method | Parameters | Returns | Description | |--------|-----------|---------|-------------| | getBy(id) | number \| string | Promise<Pokemon> | Fetch Pokémon by ID or name | | getSpeciesBy(id) | number \| string | Promise<Species> | Fetch species by ID or name | | getTypeBy(id) | number \| string | Promise<PokemonType> | Fetch type by ID or name | | getPokemons(options?) | GetPaginatedOptions? | Promise<PaginatedResponse<Raw>> | Fetch paginated Pokémon list | | getSpecies(options?) | GetPaginatedOptions? | Promise<PaginatedResponse<Raw>> | Fetch paginated species list | | getAbilities(options?) | GetPaginatedOptions? | Promise<PaginatedResponse<Raw>> | Fetch paginated abilities list | | getTypes() | - | Promise<PaginatedResponse<Raw>> | Fetch all types | | getGenerations() | - | Promise<PaginatedResponse<Raw>> | Fetch all generations | | get<T>(url) | string | Promise<T> | Generic GET request |

Examples

Build a Pokédex

const engine = new PokemonAppEngine();

// Fetch first 151 Pokémon (Gen 1)
const gen1 = await engine.getPokemons({ offset: 0, limit: 151 });

// Fetch detailed data for each
const pokemonDetails = await Promise.all(
  gen1.results.map(p => engine.getBy(p.name))
);

console.log(pokemonDetails.map(p => ({
  name: p.name,
  types: p.types.map(t => t.type.name),
  stats: p.stats.find(s => s.stat.name === 'hp')?.base_stat
})));

Find All Fire-type Pokémon

const fireType = await engine.getTypeBy('fire');

console.log(`There are ${fireType.pokemon.length} Fire-type Pokémon`);
console.log(fireType.pokemon.map(p => p.pokemon.name));

Check Legendary Status

const mew = await engine.getSpeciesBy('mew');
const pikachu = await engine.getSpeciesBy('pikachu');

console.log(`Mew is legendary: ${mew.is_legendary}`); // true
console.log(`Pikachu is legendary: ${pikachu.is_legendary}`); // false

For Developers

Running Tests

Run the unit tests:

npm run test

Development Setup

1. Clone the repository
2. Install dependencies:

   npm install

3. Make your changes
4. Run tests to ensure everything works:

   npm run test

Credits

Powered by PokéAPI - The RESTful Pokémon API.

License

MIT