Pokédex CLI

A command-line interface application built with TypeScript that allows users to explore the Pokémon world, catch Pokémon, and build their own Pokédex using the PokéAPI.

Features

• Interactive REPL: Command-line interface with readline for seamless user interaction
• Location Navigation: Browse through Pokémon locations with pagination support
• Exploration: Discover wild Pokémon in different areas
• Catch Mechanics: Attempt to catch Pokémon with probability-based success rates
• Pokédex Management: Store and inspect caught Pokémon with detailed stats
• Smart Caching: Built-in cache system with automatic cleanup to optimize API calls
• Type Safety: Fully typed with TypeScript for robust code quality

Tech Stack

• Runtime: Node.js
• Language: TypeScript (ESNext)
• API: PokéAPI v2
• Testing: Vitest
• Build Tool: TypeScript Compiler (tsc)

Project Structure

src/
├── main.ts              # Application entry point
├── repl.ts              # REPL implementation and input handling
├── state.ts             # Application state management
├── commands.ts          # Command registry
├── pokeapi.ts           # PokéAPI client with type definitions
├── pokecache.ts         # Caching layer with TTL support
├── command_*.ts         # Individual command implementations
├── *.test.ts            # Unit tests

Installation

1. Clone the repository:

git clone https://github.com/farulivan/pokedex-cli-ts.git
cd pokedex-cli-ts

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Start the application:

npm start

Or run in development mode (build + start):

npm run dev

Available Commands

Command	Usage	Description
help	help	Display all available commands
map	map	Show the next page of location areas
mapb	mapb	Show the previous page of location areas
explore	explore <location-name>	List all Pokémon in a specific location
catch	catch <pokemon-name>	Attempt to catch a Pokémon
inspect	inspect <pokemon-name>	View details of a caught Pokémon
pokedex	pokedex	List all caught Pokémon
exit	exit	Exit the application

Example Session

Pokedex > help
Available commands:
  exit: Exits the pokedex
  help: Displays a help message
  map: Displays next locations
  mapb: Displays previous locations
  explore: Displays list of pokemon in the location
  catch: Try to catch a pokemon
  inspect: Inspect a pokemon in our pokedex
  pokedex: Displays list of pokemon in the pokedex

Pokedex > map
canalave-city-area
eterna-city-area
pastoria-city-area
...

Pokedex > explore canalave-city-area
Exploring canalave-city-area...
Found Pokemon:
 - tentacool
 - tentacruel
 - staryu
 - magikarp
 - gyarados
 - wingull
 - pelipper

Pokedex > catch tentacool
Throwing a Pokeball at tentacool...
tentacool was caught!
You may now inspect it with the inspect command.

Pokedex > inspect tentacool
Name: tentacool
Height: 9
Weight: 455
Stats:
  -hp: 40
  -attack: 40
  -defense: 35
  -special-attack: 50
  -special-defense: 100
  -speed: 70
Types:
  - water
  - poison

Pokedex > pokedex
Your Pokedex:
 - tentacool

Architecture Highlights

State Management

The application uses a centralized state object that includes:

• Readline interface for user input
• Command registry
• PokéAPI client instance
• Location pagination URLs
• Pokédex storage (in-memory)

Caching System

The Cache class implements:

• Time-based expiration (60-second TTL)
• Automatic cleanup with reap loop
• Generic type support for different data structures

Catch Mechanics

Pokémon catch probability is calculated based on base_experience:

catchThreshold = max(0.1, 1 - (base_experience / 300))

Higher experience Pokémon are harder to catch, with a minimum 10% catch rate.

Testing

Run the test suite:

npm test

The project includes unit tests for:

• Cache functionality (pokecache.test.ts)
• REPL input cleaning (repl.test.ts)

Future Enhancements

This project can be extended with the following features:

• REPL Module Integration: Implement the official Node.js REPL module for enhanced command-line experience
• Battle System: Simulate turn-based battles between Pokémon with type advantages and move sets
• Expanded Test Coverage: Add comprehensive unit tests for all commands and edge cases
• Code Refactoring: Improve modularity and testability through better separation of concerns
• Pokémon Party System: Maintain a party of up to 6 Pokémon with level-up mechanics
• Evolution System: Allow caught Pokémon to evolve after meeting time or level requirements
• Persistent Storage: Save Pokédex progress to disk (JSON/SQLite) for session continuity
• Enhanced Navigation: Replace manual location names with directional choices (left/right/forward)
• Random Encounters: Implement probability-based wild Pokémon encounters during exploration
• Poké Ball Variety: Add different ball types (Great Ball, Ultra Ball, Master Ball) with varying catch rates
• Pokémon Stats Display: Show IV/EV stats and nature for competitive gameplay
• Move Learning: Allow Pokémon to learn and use moves in battles
• Trainer Profile: Track player statistics, badges, and achievements

Development

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm start - Run the compiled application
• npm run dev - Build and run in one command
• npm test - Run test suite with Vitest

TypeScript Configuration

The project uses strict TypeScript settings:

• Target: ESNext
• Module: ESNext
• Strict mode enabled
• ES Module interop enabled

License

ISC

Repository

https://github.com/farulivan/pokedex-cli-ts

---

Built with ❤️ using TypeScript and PokéAPI