Add a .URL() method to all actions and restructure .exec()

Author: b-cho

CHANGELOG.md

@@ -35,6 +35,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
   > const summonerData: dto.SummonerDTO = ...
   > // get summoner data
   > ```
+- Direct access to action URLs using the **`.URL()`** method
+  >
+  > ```typescript
+  > const summonerURL = galeforce.lol.summoner().region(galeforce.regions.lol.NORTH_AMERICA).name('name').URL();
+  > // https://na1.api.riotgames.com/lol/summoner/v4/summoners/by-name/name
+  > ```
 
 #### Changed
 

README.md

@@ -24,7 +24,7 @@ A customizable, promise-based, and command-oriented TypeScript library and fluen
 - **Fluent interface** for seamless method chaining
 - **Built-in, customizable debugging** using `debug`
 
-**Documentation** available [here](https://bcho04.github.io/galeforce/) and in the section [below](#guide).
+Automatically-generated **documentation** is available [here](https://bcho04.github.io/galeforce/), and code **examples** can be found the section [below](#guide).
 
 ## Table of Contents
 
@@ -140,6 +140,26 @@ Each endpoint in the Galeforce library is an instance of an `Action` containing
 > ```
 >
 </details>
+
+<details>
+<summary><code>.URL()</code></summary>
+
+> Returns the endpoint URL associated with the `Action` and its previously-set parameters.
+>
+> **Example**
+>
+> ```javascript
+> /* Gets the Data Dragon URL associated with the Galeforce icon. */
+> const galeforceURL = galeforce.ddragon.item.art() // Fetch item icon art from Data Dragon
+>   .version('11.9.1') // See the .<property>() section for documentation. Sets the version to retrieve data from.
+>   .assetId('6671') // See below for documentation. Get the icon for the Galeforce item.
+>   .URL(); // Get the encoded URL corresponding with the selected endpoint as a string.
+> 
+> console.log(galeforceURL); // 'https://ddragon.leagueoflegends.com/cdn/11.9.1/img/item/6671.png'
+> ```
+>
+</details>
+
 <details>
 <summary><code>.<em>&lt;property&gt;</em>()</code></summary>
 
@@ -152,13 +172,11 @@ Each endpoint in the Galeforce library is an instance of an `Action` containing
 > const currentGameInfo = await galeforce.lol.spectator.active() // Target the /lol/spectator/v4/active-games/by-summoner/{summonerId} endpoint
 >   .region(galeforce.regions.lol.NORTH_AMERICA) // Sets the request region to 'na1' (i.e., target the NA server)
 >   .summonerId('summonerId') // Sets the request summonerId to 'summonerId'
->   .exec() // See .exec() above.
+>   .exec(); // See .exec() above.
 > ```
 >
 > `.<property>()` methods may only be called once and are removed from the Action after being used.
 >
-> **Example**
->
 > ```javascript
 > /* Gets current game info for a specific summonerId. */
 > const currentGameInfo = await galeforce.lol.spectator.active() // Target the /lol/spectator/v4/active-games/by-summoner/{summonerId} endpoint
@@ -188,26 +206,28 @@ Galeforce includes DTOs for all Riot API responses as TypeScript interfaces. Alt
 
 ### Config structure
 
-When initializing Galeforce, a config object (JSON) or a path to a YAML file must be passed to the `GaleforceModule()` constructor as an argument:
+When initializing Galeforce, a config object (JSON) or a path to a YAML file may *optionally* be passed to the `GaleforceModule()` constructor as an argument:
 
 ```javascript
 const galeforce = new GaleforceModule(/* config file path or object */);
 ```
 
-Template string-like values (such as `${RIOT_KEY}`) will be evaluated using environment variables in `process.env`. The configuration file must have the following structure:
+Omitting the config will prevent Galeforce from being able to interface with the [Riot Games API](https://developer.riotgames.com/) (as no API key will be specified), although Data Dragon and the Live Client Data API will still be available.
+
+Template string-like values (such as `${RIOT_KEY}`) will be evaluated using environment variables in `process.env`. The configuration file must have the following structure (all top-level fields are optional):
 
 ```yaml
-riot-api: # REQUIRED
+riot-api:
   key: ${RIOT_KEY} # (string) Your Riot API key from https://developer.riotgames.com
-cache: # OPTIONAL
+cache:
   type: ${CACHE_TYPE} # (string) What kind of cache to use ('redis', 'javascript', 'null')
   uri: ${CACHE_URI} # (string) The cache URI to connect to (required for 'redis' cache)
-rate-limit: # OPTIONAL, Requires a cache to be configured.
+rate-limit: # Requires a cache to be configured.
   prefix: riotapi-ratelimit- # The prefix for the Riot API rate limit keys in the cache.
   intervals: # key <secs>: value <number of requests>. 
     120: 100
     1: 20
-debug: [] # OPTIONAL, A list containing any of 'action', 'payload', 'rate-limit', 'riot-api', '*' (all).
+debug: [] # A list containing any of 'action', 'payload', 'rate-limit', 'riot-api', '*' (all).
 ```
 
 ### Documentation

src/galeforce/actions/action.ts

@@ -49,6 +49,8 @@ export default class Action<TResult> {
      * fails with an error.
      */
     public async exec(): Promise<TResult> {
+        this.inferEndpoint();
+
         actionDebug(`${chalk.bold.magenta(this.payload._id)} | ${chalk.bold.yellow('execute')} \u00AB %O`, this.payload);
         try {
             if (typeof this.payload.endpoint === 'undefined') {
@@ -135,6 +137,32 @@ export default class Action<TResult> {
         }
     }
 
+    protected inferEndpoint(): void { /* Empty because this may be implemented by classes that inherit from Action */ }
+
+    /**
+     * Returns the **encoded** target URL for the action without executing an HTTP request.
+     * Useful if the URL string is needed for custom actions outside the scope of the library.
+     * @throws Will throw an error if a required payload value (*region*,
+     * *body* on POST or PUT requests, etc.) is missing or the HTTP request
+     * fails with an error.
+     */
+    public URL(): string {
+        this.inferEndpoint();
+
+        if (typeof this.payload.endpoint === 'undefined') {
+            throw new Error('[galeforce]: Action endpoint is required but undefined.');
+        }
+
+        const request = this.submodules.RiotAPI.request(
+            this.payload.endpoint,
+            this.payload,
+            this.payload.query,
+            this.payload.body,
+        );
+
+        return request.targetURL;
+    }
+
     private async getQueries(key: string, region: Region): Promise<number> {
         const { prefix } = this.submodules.cache.RLConfig;
         const value: string | null = await this.submodules.cache.get(prefix + key + region);

src/galeforce/actions/data-dragon/dragon-tail.ts

@@ -12,12 +12,11 @@ export default class GetDataDragonTail extends BaseAction<Buffer> {
         this.payload.method = 'GET';
     }
 
-    public async exec(): Promise<Buffer> {
+    protected inferEndpoint(): void {
         if (this.payload.version === '10.10.5') {
             this.payload.endpoint = ENDPOINTS.DATA_DRAGON.DRAGON_TAIL_ZIP;
         } else {
             this.payload.endpoint = ENDPOINTS.DATA_DRAGON.DRAGON_TAIL;
         }
-        return super.exec();
     }
 }

src/galeforce/actions/lol/clash/tournaments.ts

@@ -18,14 +18,13 @@ export default class GetClashTournament extends BaseAction<TournamentDTO> {
         this.payload.method = 'GET';
     }
 
-    public async exec(): Promise<TournamentDTO> {
+    protected inferEndpoint(): void {
         if (this.payload.tournamentId) {
             this.payload.endpoint = ENDPOINTS.CLASH.GET_TOURNAMENT;
         } else if (this.payload.teamId) {
             this.payload.endpoint = ENDPOINTS.CLASH.GET_TEAM_TOURNAMENT;
         } else {
             throw new Error('[galeforce]: Not enough parameters provided to select API endpoint.');
         }
-        return super.exec();
     }
 }

src/galeforce/actions/lol/league/entries.ts

@@ -30,7 +30,7 @@ export default class GetLeagueEntries extends BaseAction<LeagueEntryDTO[]> {
         this.payload.method = 'GET';
     }
 
-    public async exec(): Promise<LeagueEntryDTO[]> {
+    protected inferEndpoint(): void {
         if (this.payload.summonerId) {
             this.payload.endpoint = ENDPOINTS.LEAGUE.SUMMONER_ID;
         } else if (this.payload.queue || this.payload.tier || this.payload.division) {
@@ -43,7 +43,5 @@ export default class GetLeagueEntries extends BaseAction<LeagueEntryDTO[]> {
         } else {
             throw new Error('[galeforce]: Not enough parameters provided to select API endpoint.');
         }
-
-        return super.exec();
     }
 }

src/galeforce/actions/lol/league/leagues.ts

@@ -23,7 +23,7 @@ export default class GetLeagueList extends BaseAction<LeagueListDTO> {
         this.payload.method = 'GET';
     }
 
-    public async exec(): Promise<LeagueListDTO> {
+    protected inferEndpoint(): void {
         if (this.payload.leagueId) {
             this.payload.endpoint = ENDPOINTS.LEAGUE.LEAGUE_ID;
         } else if (this.payload.tier) {
@@ -43,7 +43,5 @@ export default class GetLeagueList extends BaseAction<LeagueListDTO> {
         } else {
             throw new Error('[galeforce]: Not enough parameters provided to select API endpoint.');
         }
-
-        return super.exec();
     }
 }

src/galeforce/actions/lol/match/match.ts

@@ -18,13 +18,11 @@ export default class GetMatch extends BaseAction<MatchDTO> {
         this.payload.method = 'GET';
     }
 
-    public async exec(): Promise<MatchDTO> {
+    protected inferEndpoint(): void {
         if (this.payload.tournamentCode) {
             this.payload.endpoint = ENDPOINTS.MATCH.MATCH_ID_TOURNAMENT;
         } else {
             this.payload.endpoint = ENDPOINTS.MATCH.MATCH_ID;
         }
-
-        return super.exec();
     }
 }

src/galeforce/actions/lol/summoner/index.ts

@@ -24,7 +24,7 @@ export default class GetSummoner extends BaseAction<SummonerDTO> {
         this.payload.method = 'GET';
     }
 
-    public async exec(): Promise<SummonerDTO> {
+    protected inferEndpoint(): void {
         if (this.payload.summonerName) {
             this.payload.endpoint = ENDPOINTS.SUMMONER.SUMMONER_NAME;
         } else if (this.payload.summonerId) {
@@ -36,7 +36,5 @@ export default class GetSummoner extends BaseAction<SummonerDTO> {
         } else {
             throw new Error('[galeforce]: Not enough parameters provided to select API endpoint.');
         }
-
-        return super.exec();
     }
-}
+}

src/galeforce/actions/riot/account/account.ts

@@ -19,15 +19,13 @@ export default class GetAccount extends BaseAction<AccountDTO> {
         this.payload.method = 'GET';
     }
 
-    public async exec(): Promise<AccountDTO> {
+    protected inferEndpoint(): void {
         if (this.payload.puuid) {
             this.payload.endpoint = ENDPOINTS.ACCOUNT.PUUID;
         } else if (this.payload.gameName || this.payload.tagLine) {
             this.payload.endpoint = ENDPOINTS.ACCOUNT.RIOT_ID;
         } else {
             throw new Error('[galeforce]: Not enough parameters provided to select API endpoint.');
         }
-
-        return super.exec();
     }
 }