@jaflesch/ts-pokeapi

TS-PokéAPI

Summary

TS-PokeApi is a zero dependency Typescript package with type annotations and fetching methods for PokéAPI v2 endpoints. This package also provides useful Pokémon's games calculations in general, e.g.: damage, stats, catch rate etc.

For more detailed examples of endpoints, parameters, server responses and payloads of PokéApi, please check the documentation on their website.

Installation

To install run the following command with NPM

npm install @jaflesch/ts-pokeapi

or Yarn

yarn add @jaflesch/ts-pokeapi

Usage

Basic usage with Object Oriented approach

import { PokeApi } from '@jaflesch/ts-pokeapi';

const api = new PokeApi('pokemon');
const pokemon = await api.get(25);
console.log(pokemon.name); // Outputs "pikachu"

Or with with procedural approach

import { pokeapi } from '@jaflesch/ts-pokeapi';

const pokemon = await pokeapi('pokemon').get(906);
console.log(pokemon.name); // Outputs "sprigatito"

API

• Methods:
  • get()
  • getById()
  • getByName()
  • getAll()
  • count()
  • paginate()

Method

Get Resource

Fetches a single record of given PokéApi resource endpoint.

Signature

async get<T>(idOrName: number | string) => Promise<PokeApiResource<T>>

Parameter	Type	Required	Description
idOrName	number or string	Yes	The desired id or name for given PokéApi resource. If PokéApi resource is in type UnnamedPaginationResource, fetching data is only available via its id.

Returns

Promise with given single PokéApi resource.

Example

import { pokeapi } from '@jaflesch/ts-pokeapi';

const abilityById = await pokeapi('ability').get(1);
const abilityByName = await pokeapi('ability').get('sturdy');
const contestEffectOnlyById = await pokeapi('contest-effect').get(1);

// TS Error: Argument of type 'string' is not assignable to parameter of type 'number'.
const contestEffectByName = await pokeapi('contest-effect').get('foo'); 

Get Resource by Id

Fetches a single record of given PokéApi resource endpoint by its id.

Signature

async getById<T>(id: number) => Promise<PokeApiResource<T>>

Parameter	Type	Required	Description
id	number	Yes	The desired resource id for given PokéApi resource

Returns

Promise with given single PokéApi resource.

Example

import { pokeapi } from '@jaflesch/ts-pokeapi';

const item = await pokeapi('item').getById(1);

Get Resource by Name

Fetches a single record of given PokéApi resource endpoint by its name (if possible).

Signature

async getByName<T>(name: string) => Promise<PokeApiResource<T> | never>

Parameter	Type	Required	Description
name	string	Yes	The desired resource name for given PokéApi resource

Returns

Promise with given single PokéApi resource or never (if resource is in UnnamedPaginationResource).

Example

import { pokeapi } from '@jaflesch/ts-pokeapi';

const pokemon = await pokeapi('pokemon').getByName('charizard');

// contestEffect will be of type `never`, since ContestEffect resources don't have names.
const contestEffect = await pokeapi('contest-effect').getByName('foo');

Get all Resources

Fetches a list of records of given PokéApi resource endpoint.

Signature

async getAll<T>(
  params?: Partial<QueryParams> | void | string | number
) => Promise<NamedAPIResource | PokeApiResource<T>>

Parameter	Type	Required	Description
params	Partial<QueryParams>, void, string, or number	Yes / No	If resource is in type SubCollectionResource, a number or string must be provided. Otherwise, the parameter is optinal, and can be partially completed with QueryParams or void.

Returns

Promise with NamedAPIResource or, if given PokéApi resource endpoint is a sub-collection, a single PokéApi resource.

Example

import { pokeapi } from '@jaflesch/ts-pokeapi';

// optional param
const pokemon = await pokeapi('pokemon').getAll();

// query params
const pokemonWithQueryParams = await pokeapi('pokemon').getAll({ offset: 10, limit: 5 });

// required since PokemonLocationArea resource is a sub-collection
const pokemonLocationArea = await pokemon('pokemon-location-area').getAll(1);

Count Resource

Fetches the total number of records for given PokéApi resource (if possible)

Signature

async count<T>() => Promise<number | never>

Returns

Promise with total number of records for given PokéApi resource, if resource is not in SubCollectionResource, otherwise never.

Example

import { pokeapi } from '@jaflesch/ts-pokeapi';

const pokemon = await pokeapi('pokemon').count();

// returns never since PokemonLocationArea resource is a sub-collection
const pokemonLocationArea = await pokemon('pokemon-location-area').count();

Paginate Resources

Fetches a paginated result for given PokéApi resource (if possible).

Signature

async paginate<T>(params?: Partial<QueryParams>) => Promise<PaginatedResult | never>

Parameter	Type	Required	Description
params	Partial<QueryParams>	No	Optional parameter for setting resouce list limit and offset values

Returns

Promise with paginated result number of records for given PokéApi resource, if resource is not in SubCollectionResource, otherwise never.

Example

import { pokeapi } from '@jaflesch/ts-pokeapi';

const pokemon = await pokeapi('pokemon').paginate();
const pokemonWithParams = await pokeapi('pokemon').paginate({ limit: 10, offset: 100 });

// returns never since PokemonLocationArea resource is a sub-collection
const pokemonLocationArea = await pokemon('pokemon-location-area').paginate();

Full documentation @ Docusaurus coming soon. Thank you for understanding and support!

Credits

• Jean Flesch