A Javascript Wrapper for the League of Legends API. Originated from ClaudioWilson/LeagueJS but after a complete rework now published under leaguejs and using RIOT API V3
Note: Tournament API is not included at this time
- v4 endpoints now are mandatory
- removed deprecated methods
npm install leaguejs --save
// setting default platformId to be used if you don't specify it on the endpoint method
process.env.LEAGUE_API_PLATFORM_ID = 'euw1'
const LeagueJS = require('../lib/LeagueJS.js');
const leagueJs = new LeagueJS(process.env.LEAGUE_API_KEY);
leagueJs.Summoner
.gettingByName('EldoranDev')
.then(data => {
'use strict';
console.log(data);
})
.catch(err => {
'use strict';
console.log(err);
});
leagueJs.Summoner
.gettingByAccount(22177292, 'euw')
.then(data => {
'use strict';
console.log(data);
})
.catch(err => {
'use strict';
console.log(err);
});Endpoints and their methods are named in alignment to the API documentation.
Methods returning a promise are named in present progressive (gettingXY) while synchronous methods are called in present tense (getXY)
Each Endpoint is located in it's own class, accessible by its name on the leagueJs object.
leagueJs.Challenges
leagueJs.Champion
leagueJs.ChampionMastery
leagueJs.League
leagueJs.LolStatus
leagueJs.Masteries
leagueJs.Match
leagueJs.Runes
leagueJs.Spectator
leagueJs.StaticData
leagueJs.SummonerLeagueJS uses DataDragonHelper for StaticData handling.
NOTE: code using LeagueJS 1.9.x or earlier should check their usage of StaticData.gettingChampions, as the returned properties have changed. All other StaticData methods can be used as dropin-replacement without any code changes.
LeagueJS provides the DataDragonHelper class to handle DataDragon files. Please also refer to the module readme and the respective unit-tests for additional usage info.
By default, DataDragonHelper will store DDragonFiles within it's own module-directory. To prevent this you can either set the appropriate path during instantiation
const leagueJs = LeagueJS(process.env.LEAGUE_API_KEY, {STATIC_DATA_ROOT: ...});or use the setup method within StaticData
// DataDragonHelper will use the provided path to store the downloaded files
// you have multiple possibilities to set the path
leagueJs.StaticData.setup('absolute/path/for/files')
leagueJs.StaticData.setup('./relative/path/for/files')
leagueJs.StaticData.setup([__dirname, '../', 'pathSegments', 'to/be/resolved'])
// to enable logging to the console, pass `true` as second parameter
// (otherwise you'll need to add listeners to respective leagueJs.DataDragonHelper.events)
leagueJs.StaticData.setup('absolute/path/for/files', true)Utility methods are located within /lib/util separated into thematic groups. They can be accessed in 2 ways:
const LeagueJSUtil = api.util
const Util = require('leaguejs/lib/util')All Utility methods are implemented as static and pure functions
LEAGUE_API_PLATFORM_ID The value of this environmental variable will be used as default platformId. If not provided, 'na1' is used.
Alternatively they can be provided to the League constructor within the options parameter
const leagueJs = new League(<Your Api key>, {PLATFORM_ID: <default api region>})We recommend you read the API key from your environment variables too and pass that to the LeagueJS constructor
const leagueJs = new League(process.env.LEAGUE_API_KEY)
Rate limiting will be handled for you by default using RiotRateLimiter-node. Code created with LeagueJS < 1.5.0 should not be affected other then that the default limiting strategy now is SPREAD (see RiotRateLimiter-node docs for details.), which means your code might execute slower then before.
You can change the limiting strategy in two ways:
const leagueJs = require('../lib/LeagueJS.js');
// passing in allowBursts: true on instantiation
const api = new LeagueJS(process.env.LEAGUE_API_KEY, {
limits: {allowBurst: true}
});
// updating the limiter
api.updateRateLimiter({allowBursts: true})By default, we will retry requests to the API that respond with 500, 503 and 429 that are not caused by the API-edge servers (so missing additional information about retry and limits).
Up to 3 retries will be done by default, starting at a timeout of 1000 MS.
First retry will be done with the timeout given in config.limits.intervalRetryMS.
All subsequent retries will be done with a timeout of 2* the previous one (so with initial intervalRetryMS of 1000 it will be 1000, 2000, 4000 MS for the first 3 retries respectively.
You can configure this behaviour by passing the relevant options into the LeagueJS constructor on instantiation:
const LeagueJS = require('../lib/LeagueJS.js');
const api = new LeagueJS(process.env.LEAGUE_API_KEY, {
limits: {
'allowBursts': false,
// maximum amount of retries done when encountering 429 without retry-after header or 503 / 500
'numMaxRetries': 3,
// starting retry backoff time on RIOT service overload (not related to API key limits)
// will be increased exponentially with every retry
'intervalRetryMS': 1000,
// per default, retry is enabled on all endpoints
// pass in an Array with the Names of the Endpoints you want to ENABLE retries on
// if you see the need.
// See [Endpoints](#Endpoints) above
'retryEndpoints': LeagueJS.util.EndpointUtil.getEndpointNames()
}
});By default, caching is disabled.
If enabled, the default caching is using node-cache with the request-urls as caching-key The easiest way to setup caching is to pass a minimum set of caching options to LeagueJS on instantiation
const leagueJs = new LeagueJS({
...
caching: {
isEnabled: true, // enable basic caching
defaults: {stdTTL: 120} // add a TTL to all Endpoints you think is appropriate (you can tune it later per Endpoint)
}
...
})You can setup caching globally or on an Endpoint basis
// replacing Cache-options within Summoner endpoint (overwrites global options for that Endpoint)
leagueJs.Summoner.setCache({ stdTTL: 120})
leagueJs.Summoner.enableCaching();
leagueJs.Summoner.disableCaching();
// Set caching options for all endpoints (overwrites previously set options)
leagueJs.setCache({ stdTTL: 120}, MyCache)
leagueJs.setCache({ stdTTL: 120})
leagueJs.enableCaching();
leagueJs.disableCaching();Options not explicitly set use following defaults (found in /lib/Config.js)
{
/** the standard ttl as number in seconds for every generated cache element.
* (default: 0)
* */
stdTTL: 0,
/**
* The period in seconds, as a number, used for the automatic delete check interval.
* 0 = no periodic check.
* (default: 600)
*/
checkperiod: 600,
/**
* en/disable throwing or passing an error to the callback if attempting to .get a missing or expired value.
* (default: false)
*/
errorOnMissing: false,
/**
* en/disable cloning of variables. If true you'll get a copy of the cached variable.
* If false you'll save and get just the reference.
* Note: true is recommended, because it'll behave like a server-based caching.
* You should set false if you want to save mutable objects or other complex types
* with mutability involved and wanted.
*/
useClones: true
}You can set your own Caching implementation if you like NOTE: make sure the public interface of your caching implementation is the same as node-cache uses to prevent incompatibilities.
const MyCache = require('myCache')
// replacing Cache during instantiation (for all endpoints)
const leagueJs = new LeagueJS({
...
caching: {
isEnabled: true, // enable caching
constructor: MyCache, // set a custom Caching implementation
},
...
})
// replacing Cache globally (overwrites previously set options on endpoints)
leagueJs.setCache({ stdTTL: 120}, MyCache)
// replacing Cache within specific endpoint (overwrites global options for that Endpoint)
leagueJs.Summoner.setCache({ stdTTL: 120}, MyCache)// TODO: propably rework this doc-part
Gulp.js is a streaming build system. Thanks to it's simplicity and code-over-configuration we are able to create a simple, efficient and more intuitive build process.
npm install -g gulp
- [] TODO: check if all are working and update description if neccessary
Run JSLint on all js files:
gulp lint
Run BDD tests:
gulp test
Run istabul to generate a code coverage report:
gulp test-coverage
Run plato to generate a code analysis report:
gulp code-report
Runs both istanbul and plato in with one command:
gulp reports
Removes both coverage and report directories created by istanbul and plato
gulp clean-reports
Sets up a development environment that will watch for code changes then run JSLint and BDD tests upon saving:
gulp dev