README
Pokewrap
A JavaScript wrapper for the Pokemon API
Because Snorlax ain't the only RESTful thing in the Pokemon Storage System!
Table of Contents
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 ownPromise
library if your target environment doesn't support them natively. Bothes6-promise
andbluebird
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' ]
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 } ]
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.
Support for callbacks
// Which pokemon loves asynchronous programming?
pokewrap.getOneById(483, (pokemon) => console.log(pokemon.name));
);
'dialga'
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
getOne(type, id, ?opts, ?callback) => Promise<Resource>
type: ResourceType
id: NameOrId
opts: ?Object
callback: ?Function
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)
);
getOneById()
Signature
getOneById(id, ?opts, ?callback) => Promise<Resource>
id: NameOrId
opts: ?Object
callback: ?Function
Note: You can also call this method using
getOneByID
orgetOneByName
.
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)
);
getOneByName()
This is an alias for getOneById()
, for when it seems strange to fetch a
pokemon by name
using a method called getOneById
.
getMany()
Signature
getMany(type, ?opts, ?callback) => Promise<Array<Resource>>
type: ResourceType
opts: ?Object
callback: ?Function
getMany(type, ids, ?opts, ?callback) => Promise<Array<Resource>>
type: ResourceType
ids: Array<NameOrId|ResourceObject>
opts: ?Object
callback: ?Function
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)
);
getByUrl()
Signature
getByUrl(url, ?opts, ?callback)
url: String,
?opts: Object,
?callback: Function
Note: You can also call this method using
getByURL
.
Examples
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
Other Great Wrappers
pokedex-promise
- A lightweight Pokemon API wrapper for node
License
Pokewrap is licensed under the ISC License.
For details, please see the LICENSE
file.