Pokewrap

A JavaScript wrapper for the Pokemon API

Because Snorlax ain't the only RESTful thing in the Pokemon Storage System!

Table of Contents

• Installation & Setup
• Examples
• API
  • Pokewrap()
    • getOne()
    • getOneById()
    • getOneByName()
    • getMany()
    • getByUrl()
• Contributing
  • Building
  • Testing
• Other great wrappers
• License

Features

• Clean, flexible interface to the RESTful Pokemon API
• Supports promises and callbacks
• Works in both node and the browser

Installation & Setup

Download the files:

$ npm install --save pokewrap

Then include it in your source:

// ES6+
import Pokewrap from 'pokewrap';
const pokewrap = new Pokewrap();

// CommonJS
const Pokewrap = require('pokewrap').default;
const pokewrap = new Pokewrap();

// Browser
var pokewrap = new Pokewrap.default();

Notes:

• If you use the global variable or CommonJS to work with Pokewrap, you need to explicitly reference the Pokewrap.default object.

• Although Pokewrap supports callbacks, it is built using the isomorphic-fetch, which requires you to bring your own Promise library if your target environment doesn't support them natively. Both es6-promise and bluebird are great options.

Examples

Basic Usage

// What can Magikarp do, anyway?
pokewrap.getOneByName('magikarp')
  .then((pokemon) => pokemon.moves.map(({ move }) => move.name))
  .then((moves) => console.log(moves));

[ 'bounce', 'splash', 'tackle', 'flail' ]

Back to Top ↑

Fetch multiple resources in a single call

// Uno, dos, tres!
pokewrap
  .getMany(['articuno', 'zapdos', 'moltres'])
  .then((pokemon) => console.log(getVitals(pokemon)))
  .catch((err) => console.error(err));

function getVitals(pokemon) {
  return pokemon.map(
    ({ name, height, weight }) => ({name, height, weight})
  );
}

[ { name: 'articuno', height: 17, weight: 554 },
  { name: 'zapdos', height: 16, weight: 526 },
  { name: 'moltres', height: 20, weight: 600 } ]

Back to Top ↑

Fetch any type of resource from the Pokemon API

// How big is a pinap berry?
pokewrap.getOne('berry', 'pinap')
  .then((berry) => {
    console.log(`A pinap berry is ${berry.size}mm in size.`);
  });

A pinap berry is 80mm in size.

Back to Top ↑

Support for callbacks

// Which pokemon loves asynchronous programming?
pokewrap.getOneById(483, (pokemon) => console.log(pokemon.name));
);

'dialga'

Back to Top ↑

API

Pokewrap()

Signature

new Pokewrap(?config) => Pokewrap

config: ?Object

The configuration options and their default values are as follows:

Option | Default | Comments --------------|------------------------------|---------- baseUrl | 'http://pokeapi.co/api/v2' | The base URL to send requests to. Changing this value can be useful for testing your own local copy of the Pokemon API defaultType | 'pokemon' | The default endpoint to fetch resources from. If no type is provided to a call, then Pokewrap will fallback to using this type. requests | { redirect: 'follow' } | Options that are passed to each Request object. See the Request documentation at MDN for the full list of options.

getOne()

Signature

1. getOne(type, id, ?opts, ?callback) => Promise<Resource>

type:     ResourceType
id:       NameOrId
opts:     ?Object
callback: ?Function

2. getOne(opts, ?callback) => Promise<Resource>

opts:     Object
callback: ?Function

Examples

// These calls are identical
pokewrap.getOne('berry', 'pinap');
pokewrap.getOne({ type: 'berry', id: 'pinap' });
pokewrap.getOne({ type: 'berry', name: 'pinap' });

// Pass options to the Request object
pokewrap.getOne('pokemon', 'magikarp', { cache: 'no-cache' });

// With a callback
pokewrap.getOne('pokemon', 'magikarp', (pokemon) => console.log(pokemon));

// With callback and options
pokewrap.getOne(
  'pokemon', 'magikarp',
  { cache: 'no-cache' },
  (pokemon) => console.log(pokemon)
);

Back to Top ↑

getOneById()

Signature

getOneById(id, ?opts, ?callback) => Promise<Resource>

id:       NameOrId
opts:     ?Object
callback: ?Function

Note: You can also call this method using getOneByID or getOneByName.

Examples

pokewrap.getOneById(1);
pokewrap.getOneById('bulbasaur');
pokewrap.getOneByName('bulbasaur');

// Using a different default type
const pokewrap = new Pokewrap({ defaultType: 'berry' });

// Fetches a cheri berry, not bulbasaur
pokewrap.getOneById(1);

// Pass options to the Request object
pokewrap.getOneById('pikachu', { cache: 'no-cache' });

// With a callback
pokewrap.getOneById(1, (pokemon) => console.log(pokemon));

// With callback and options
pokewrap.getOneById(
  'magikarp',
  { cache: 'no-cache' },
  (pokemon) => console.log(pokemon)
);

Back to Top ↑

getOneByName()

This is an alias for getOneById(), for when it seems strange to fetch a pokemon by name using a method called getOneById.

Back to Top ↑

getMany()

Signature

1. getMany(type, ?opts, ?callback) => Promise<Array<Resource>>

type:     ResourceType
opts:     ?Object
callback: ?Function

2. getMany(type, ids, ?opts, ?callback) => Promise<Array<Resource>>

type:     ResourceType
ids:      Array<NameOrId|ResourceObject>
opts:     ?Object
callback: ?Function

2. getMany(ids, ?opts, ?callback) => Promise<Array<Resource>>

ids:       Array<NameOrId|ResourceObject>
opts:      ?Object
callback:  ?Function

Examples

// Fetch a paginated list of resources in the given type
pokewrap.getMany('pokemon');
pokewrap.getMany('berry');

// Fetch an array of cherri, sitrus, and pinap berries
pokewrap.getMany('berry', [1, 10, 20]);

// Fetch multiple individual resources using the default type
pokewrap.getMany(['bulbasaur', 'ivysaur', 'venusaur']);

// Using a different default type
const pokewrap = new Pokewrap({ defaultType: 'berry' });

// Fetches a cheri berry, not bulbasaur
pokewrap.getMany(['bulbasaur', 'charmander', 'squirtle']);

// Mix & Match IDs, names, and objects in the request
const bulbasaur  = 1;
const ivysaur   = 'ivysaur'
const venusaur  = { name: 'venusaur' };
const solarBeam  = { type: 'move', name: 'solar-beam' };

pokewrap.getMany([bulbasaur, ivysaur, venusaur, solarBeam]);

// Pass options to the Request object
pokewrap.getMany(
  'item',
  [1, 2, 3],
  { cache: 'no-cache' }
);

pokewrap.getMany(
  ['bulbasaur', 'charmander', 'squirtle'],
  { cache: 'no-cache' }
);

// With a callback
pokewrap.getMany(
  'item',
  [1, 2, 3],
  (items) => items.forEach((item) => console.log(item));
);

pokewrap.getMany(
  ['bulbasaur', 'charmander', 'squirtle'],
  (pokemonList) => {
    pokemonList.forEach((pokemon) => console.log(pokemon));
  }
);

// With callback and options
pokewrap.getMany(
  'berry', ['cherri', 'sitrus', 'pinap'],
  { cache: 'no-cache' },
  (berry) => console.log(berry)
);

Back to Top ↑

getByUrl()

Signature

getByUrl(url, ?opts, ?callback)

url:       String,
?opts:     Object,
?callback: Function

Note: You can also call this method using getByURL.

Examples

Back to Top ↑

Contributing

Building

The following npm scripts are available for use during development:

Command | Use to... ---------------------------|----------- npm run build | Transpile & bundle (no minification) npm run build:production | Transpile & bundle (w/ minification) npm run clean | Remove the dist/ files npm run compile | Transpile src/ to dist/ npm run lint | Lint the files in src/

Testing

For tests with pretty output via faucet, run:

$ npm test

For raw TAP-formatted output, run:

$ npm run test:tap

Back to Top ↑

Other Great Wrappers

• pokedex-promise - A lightweight Pokemon API wrapper for node

Back to Top ↑

License

Pokewrap is licensed under the ISC License.

For details, please see the LICENSE file.

Back to Top ↑