PokeApi class

The PokeApi class is the main feature of this package. It allows easy and customizable ways for fetching data from PokéApi database. As stated here, you can also use the same interface in a procedural approach if you like.

Since the procedural approach uses the same core from object-oriented approach, this page focus on the class API: parameters, properties, methods, and how to extend and customize it.

Parameters

Property	Type	Required	Description
endpoint	PokeApiEndpoint	Yes	The endpoint from PokéAPI resource.
configuration	PokeApiConfig	Yes	An object to customize the class behaviour.

Logging

Logging is an excelent tool for debugging applications. In PokeApi class, is very simple to display both request and response logs. To allow logging, just set debug: true.

The following code:

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

const api = new PokeApi('pokemon', { 
  debug: true,  // Will output logs
});

await api.get('pikachu');

Outputs:

/*
  [GET] https://pokeapi.co/api/v2/pokemon/pikachu
  [STATUS] 200
*/

info

The logging format follows the template:

Request

'[${httpMethod}] ${pokeApiResourceURL}'

Response

'[STATUS] ${statusCode}'

Interceptors

Interceptors are middleware that allows common patterns around retrying, caching, logging, and authentication to be abstracted away from individual requests. They are functions which you can run for each request, and have broad capabilities to affect the contents and overall flow of requests and responses. TS-PokéAPI provides an interceptor property that allows customization for both request and response callbacks.

• The interceptor.request callback receives an URL string and HTTP method as parameters, which can be used to access the proper methods of libraries instances.
• The interceptor.response callback receives the returning data from request and must adapt the library instance data to match at least the returning value from property .data of Fetch API Response object.
• The interceptor.statusKey is an optional parameter to help PokeApi class map the status code key utilized by library instance. Default value is status (same as Fetch API), but in some libraries the values diff, so further configuration is needed.

The following code shows the PokeApiConfig.interceptor property:

export interface PokeApiConfig {
  // ...
  interceptor?: {
    request: (url: string, method: string) => unknown,
    response: (response: unknown) => Response,
    statusKey: 'a-status-key', 
  }
},

The nex subsections show how easily you can extend PokeApi class interceptors with the library of your choice. This is helpful if you wish to add more complex patterns such as cache and retry.

axios-cache-interceptor

npm

npm install axios axios-cache-interceptor

Yarn

yarn add axios axios-cache-interceptor

pnpm

pnpm add axios axios-cache-interceptor

import Axios from 'axios';
import { CacheAxiosResponse, setupCache } from 'axios-cache-interceptor';

const instance = Axios.create();
const axios = setupCache(instance);

new PokeApi(endpoint, {
  interceptor: {
    request: url => axios.get(url),
    response: (resp: CacheAxiosResponse) => resp.data,
  },
});

got

Human-friendly and powerful HTTP request library for Node.js

npm

npm install got

Yarn

yarn add got

pnpm

pnpm add got

warning

This package is native ESM and no longer provides a CommonJS export. If your project uses CommonJS, you'll have to convert to ESM or use the dynamic import() function. You can also use Got v11 instead which is pretty stable, or also switch to package got-cjs.

npm

npm install got-cjs

Yarn

yarn add got-cjs

pnpm

pnpm add got-cjs

import got, {Response} from 'got';

new PokeApi(endpoint, {
  interceptor: {
  request: url => got.get(url),
  response: (resp: Response<string>) => JSON.parse(resp.body),
  statusKey: 'statusCode',
});

superagent

Small progressive client-side HTTP request library, and Node.js module with the same API, supporting many high-level HTTP client features.

npm

npm install superagent @types/superagent

Yarn

yarn add superagent @types/superagent

pnpm

pnpm add superagent @types/superagent

import { Response } from 'superagent';
const superagent = require('superagent');

new PokeApi(endpoint, {
  interceptor: {
    request: url => superagent.get(url),
    response: (resp: Response) => JSON.parse(resp.text),
  },
});

Creating your own interceptor

If none of above solutions works for you and/or you need more control over your implementation, just choose your desired approach and extend it with your logic:

Class-based approach

import { PokeApi, PokeApiProps, TypeMapKeys } from "@jaflesch/ts-pokeapi";

export class MyCustomClass<T extends TypeMapKeys> extends PokeApi<T> implements PokeApiProps<T> {
  constructor(endpoint: T) {
    super(endpoint);
    return new PokeApi(endpoint, {
      interceptor: {
        request: (url, method) => {
          // Your interceptor request logic here
        },
        response: resp => {
          // Your interceptor responde logic here
        },
        statusKey: 'a-custom-status-property', 
      },
    });
  }
}

Procedural approach

import { pokeApi, TypeMapKeys } from "@jaflesch/ts-pokeapi";

export const myPokeapi = <T extends TypeMapKeys>(endpoint: T) => {
  return pokeapi(endpoint, {
    interceptor: {
      interceptor: {
        request: (url, method) => {
          // Your interceptor request logic here
        },
        response: resp => {
          // Your interceptor responde logic here
        },
        statusKey: 'a-custom-status-property', 
      },
  }});
}

Type Definitions

PokeApiEndpoint

Type

enum('berry', 'berry-firmness', 'berry-flavor', 'contest-type', 'contest-effect', 'super-contest-effect', 'encounter-method', 'encounter-condition', 'encounter-condition-value', 'evolution-chain', 'evolution-trigger', 'generation', 'pokedex', 'version', 'version-group', 'item', 'item-attribute', 'item-category', 'item-fling-effect', 'item-pocket', 'location', 'location-area', 'pal-park-area', 'region', 'machine', 'move', 'move-ailment', 'move-battle-style', 'move-category', 'move-damage-class', 'move-learn-method', 'move-target', 'ability', 'characteristic', 'egg-group', 'gender', 'growth-rate', 'nature', 'pokeathlon-stat', 'pokemon', 'pokemon-location-area', 'pokemon-color', 'pokemon-form', 'pokemon-habitat', 'pokemon-shape', 'pokemon-species', 'stat', 'type', 'language')

PokeApiConfig

Type
Interface

Parameter	Type	Required	Description
debug	boolean	No	Wheter enable request and response loggings.
interceptor	object	No	An object to customize interceptor request and response callbacks.
interceptor.request	(url: string, method?: string) => unknown	Yes	The request interceptor callback.
interceptor.response	(response: unknown) => Response	Yes	The response interceptor callback.
interceptor.statusKey	string	No	The key to access the value of status property.