speedruncom.js 1.1.0 → 1.2.1

package/dist/build-client.js

@@ -2,6 +2,26 @@ import { Project } from 'ts-morph';
 const project = new Project({
     tsConfigFilePath: "tsconfig.json",
 });
+const isInterfaceEmpty = (interfaceName, sourceFile) => {
+    const declarations = sourceFile.getExportedDeclarations().get(interfaceName);
+    if (!declarations || declarations.length === 0)
+        return false;
+    const decl = declarations[0];
+    if (!decl || !decl.getKindName || decl.getKindName() !== "InterfaceDeclaration")
+        return false;
+    const props = decl.getProperties();
+    return props.length === 0;
+};
+const isInterfaceAllOptional = (name, sourceFile) => {
+    const iface = sourceFile.getInterface(name);
+    if (iface) {
+        return iface.getProperties().some(p => !p.hasQuestionToken());
+    }
+    const typeNode = sourceFile.getTypeAliasOrThrow(name).getType();
+    return typeNode
+        .getProperties()
+        .some(p => !p.isOptional());
+};
 const baseClient = project.getSourceFileOrThrow('src/BaseClient.ts');
 const clientFile = project.createSourceFile('src/Client.ts', baseClient.getFullText(), { overwrite: true });
 const clientClass = clientFile.getClasses()[1];
@@ -11,32 +31,33 @@ const responsesFile = project.getSourceFileOrThrow('src/responses.ts');
 const getEndpointNames = Array.from(getEndpointsFile.getExportedDeclarations().keys());
 const postEndpointNames = Array.from(postEndpointsFile.getExportedDeclarations().keys());
 const responseNames = new Set(Array.from(responsesFile.getExportedDeclarations().keys()));
-for (const endpointName of getEndpointNames) {
-    const returnType = responseNames.has(endpointName) ? `Promise<Responses.${endpointName}>` : 'Promise<void>';
-    clientClass.addMethod({
-        name: endpointName,
-        isAsync: true,
-        parameters: [{ name: 'params', type: `GetEndpoints.${endpointName}` }],
-        returnType,
-        statements: [`return await this.request('${endpointName}', params, 'post');`]
-    });
-    clientClass.addMethod({
-        name: endpointName,
-        isStatic: true,
+const makeMethod = (name, isStatic, returnType, isEmpty, interfaces, isOptional) => {
+    const method = {
+        name,
+        isStatic,
         isAsync: true,
-        parameters: [{ name: 'params', type: `GetEndpoints.${endpointName}` }],
         returnType,
-        statements: [`return await this.request('${endpointName}', params, 'get');`]
-    });
+        statements: [`return await this.request('${name}'${!isEmpty ? ', params' : ''});`]
+    };
+    if (!isEmpty)
+        method.parameters = [{
+                name: 'params',
+                type: `${interfaces}.${name}`,
+                hasQuestionToken: isOptional
+            }];
+    clientClass.addMethod(method);
+};
+for (const endpointName of getEndpointNames) {
+    const returnType = responseNames.has(endpointName) ? `Promise<Readonly<Responses.${endpointName}>>` : 'Promise<void>';
+    const isEmpty = isInterfaceEmpty(endpointName, getEndpointsFile);
+    const isAllOptional = isInterfaceAllOptional(endpointName, getEndpointsFile);
+    makeMethod(endpointName, false, returnType, isEmpty, 'GetEndpoints', isAllOptional);
+    makeMethod(endpointName, true, returnType, isEmpty, 'GetEndpoints', isAllOptional);
 }
 for (const endpointName of postEndpointNames) {
-    const returnType = responseNames.has(endpointName) ? `Promise<Responses.${endpointName}>` : 'Promise<void>';
-    clientClass.addMethod({
-        name: endpointName,
-        isAsync: true,
-        parameters: [{ name: 'params', type: `PostEndpoints.${endpointName}` }],
-        returnType,
-        statements: [`return await this.request('${endpointName}', params, 'post');`]
-    });
+    const returnType = responseNames.has(endpointName) ? `Promise<Readonly<Responses.${endpointName}>>` : 'Promise<void>';
+    const isEmpty = isInterfaceEmpty(endpointName, postEndpointsFile);
+    const isAllOptional = isInterfaceAllOptional(endpointName, postEndpointsFile);
+    makeMethod(endpointName, false, returnType, isEmpty, 'PostEndpoints', isAllOptional);
 }
 clientFile.saveSync();

package/dist/endpoints/endpoints.get.d.ts

@@ -3,46 +3,51 @@ import * as Interfaces from '../interfaces.js';
 import { AtLeastOne } from '../types.js';
 /**
  * Gets a leaderboard, with Players included.
+ *
  * `GetGameLeaderboard` can fetch twice as many runs, and also fetches Games, Platforms, Regions, Values, and Variables.
  */
 export interface GetGameLeaderboard2 {
     /**
-     * Filtering parameters.
+     * The leaderboard to fetch.
      */
     params: Interfaces.LeaderboardParams;
     /**
-     * The leaderboard page, in relation to `limit`.
-     */
-    page?: number;
-    /**
-     * The limit of Runs per page.
-     * Max: 100
+     * The maximum amount of `Run`s per page.
+     *
+     * @max 100
      * @default 100
      */
     limit?: number;
+    /**
+     * The leaderboard page, in relation to `limit`.
+     */
+    page?: number;
 }
 /**
  * Gets a leaderboard, with all relevant items included.
+ *
  * `GetGameLeaderboard2` only includes Runs and Players, and has half the maximum `limit`.
  */
 export interface GetGameLeaderboard {
     /**
-     * Filtering parameters.
+     * The leaderboard to fetch.
      */
     params: Interfaces.LeaderboardParams;
-    /**
-     * The leaderboard page, in relation to `limit`.
-     */
-    page?: number;
     /**
      * The limit of Runs per page.
-     * Max: 200
+     *
+     * @max 200
      * @default 100
      */
     limit?: number;
+    /**
+     * The leaderboard page, in relation to `limit`.
+     */
+    page?: number;
 }
 /**
  * Gets mostly leaderboard-related data of a game.
+ *
  * Both parameters function the same. If both are included, `gameId` will override.
  */
 interface GetGameData_Base {
@@ -57,7 +62,8 @@ interface GetGameData_Base {
 }
 export type GetGameData = AtLeastOne<GetGameData_Base, 'gameId' | 'gameUrl'>;
 /**
- * Gets miscellaneous data of a game.
+ * Gets mostly miscellaneous data of a game.
+ *
  * Both parameters function the same. If both are included, `gameId` will override.
  */
 interface GetGameSummary_Base {
@@ -66,7 +72,7 @@ interface GetGameSummary_Base {
      */
     gameId?: string;
     /**
-     * Game page URL.
+     * Subpath URL of the game.
      */
     gameUrl?: string;
 }
@@ -75,14 +81,63 @@ export type GetGameSummary = AtLeastOne<GetGameSummary_Base, 'gameId' | 'gameUrl
  * Gets the world record history of a game leaderboard.
  */
 export interface GetGameRecordHistory {
+    params?: {
+        /**
+         * ID of the leaderboard's category.
+         */
+        categoryId?: string;
+        /**
+         * `EmulatorFilter` to filter the leaderboard by.
+         */
+        emulator?: Enums.EmulatorFilter;
+        /**
+         * ID of the game. When exempted, the lists will be empty arrays.
+         */
+        gameId?: string;
+        /**
+         * `ObsoleteFilter` to filter the leaderboard by.
+         */
+        obsolete?: Enums.ObsoleteFilter;
+        /**
+         * IDs of platforms to filter the leaderboard by.
+         *
+         * All Platforms can be fetched with `GetPlatformList`.
+         */
+        platformIds?: string[];
+        /**
+         * IDs of regions to filter the leaderboard by.
+         *
+         * All Regions can be fetched with `GetStaticData.regionList`.
+         */
+        regionIds?: string[];
+        /**
+         * `TimingMethod` to filter the leaderboard by.
+         */
+        timer?: Enums.TimingMethod;
+        /**
+         * `RunStatus` to filter the leaderboard by.
+         */
+        verified?: Enums.RunStatus;
+        /**
+         * `VariableValues` to filter the leaderboard by.
+         */
+        values?: Interfaces.VariableValues[];
+        /**
+         * `VideoState` of runs to filter the leaderboard by.
+         */
+        video?: Enums.VideoState;
+    };
+    /**
+     * The limit of Runs per page.
+     *
+     * @max 200
+     * @default 100
+     */
+    limit?: number;
     /**
-     * ID of the game. When exempted, both properties will be empty arrays.
+     * The leaderboard page, in relation to `limit`.
      */
-    gameId?: string;
-    categoryId?: string;
-    values?: Interfaces.VariableValues[];
-    emulator?: Enums.EmulatorFilter;
-    obsolete?: Enums.ObsoleteFilter;
+    page?: number;
 }
 /**
  * Searches for site items with a query.
@@ -93,7 +148,7 @@ export interface GetSearch {
      */
     query?: string;
     /**
-     * todo
+     * Useless parameter, there is no affect on what is fetched based on the value.
      */
     favorExactMatches?: boolean;
     /**
@@ -121,32 +176,47 @@ export interface GetSearch {
      */
     includeChallenges?: boolean;
     /**
-     * The maximum amount of elements in each array.
+     * The maximum amount of items to fetch in each `[item]List` array.
+     *
+     * @max 100
      * @default 100
-     * Max: 100
      */
     limit?: number;
+    /**
+     * The leaderboard page, in relation to `limit`.
+     */
+    page?: number;
 }
 /**
- * Gets non-obsolete latest runs.
+ * Gets non-obsolete latest runs of a game.
+ *
+ * When `seriesId` and `gameId` are exempted,
  */
 export interface GetLatestLeaderboard {
+    /**
+     * ID of the game.
+     *
+     * When exempted, lists in the responses will be empty.
+     */
     gameId?: string;
+    /**
+     * ID of a series
+     */
     seriesId?: string;
     /**
-     * The maximum amount of `runs` there will be in the response.
+     * The maximum amount of Runs to fetch.
      *
      * Warning: Obsolete runs are not included, but still count to the limit.
      *
      * If this is `20` and 5 out of the 20 latest runs are obsolete, it will only return the 15 non-obsolete runs.
      *
+     * @max Around 99999, however it varies with caching-related factors.
      * @default 25
-     * Max: 99999
      */
     limit?: number;
 }
 /**
- * Gets a run.
+ * Gets a single run.
  */
 export interface GetRun {
     /**
@@ -159,7 +229,7 @@ export interface GetRun {
  */
 export interface GetUserSummary {
     /**
-     * Page URL of the user.
+     * Subpath URL of the user.
      */
     url: string;
 }
@@ -172,7 +242,13 @@ export interface GetUserComments {
      */
     userId: string;
 }
+/**
+ * Gets threads created by a specific user.
+ */
 export interface GetUserThreads {
+    /**
+     * ID of the user.
+     */
     userId: string;
 }
 /**
@@ -190,7 +266,7 @@ export interface GetUserPopoverData {
 export interface GetTitleList {
 }
 /**
- * Gets a Title.
+ * Gets a specific Title.
  */
 export interface GetTitle {
     /**
@@ -199,7 +275,7 @@ export interface GetTitle {
     titleId: string;
 }
 /**
- * Gets articles on the site.
+ * Gets site articles.
  */
 export interface GetArticleList {
     /**
@@ -219,36 +295,63 @@ export interface GetArticleList {
      */
     tags?: string[];
     /**
-     * The target of an article, either being `news` or a page URL for site information articles.
+     * The target of an article, either being `news` or a path URL for site information articles.
      */
     target?: string;
     /**
-     * The maximum amount of articles included in the response.
+     * The maximum amount of Articles to fetch.
      *
+     * @max 500
      * @default 500
-     * Max: 500
      */
     limit?: number;
+    /**
+     * The article list page, in relation to `limit`.
+     */
+    page?: number;
 }
 /**
- * Gets a specific article from the site.
+ * Gets a specific site article.
  */
 export interface GetArticle {
     id?: string;
     slug?: string;
 }
 /**
- * Gets a list of all games on the site.
+ * Gets a list of games.
  */
 export interface GetGameList {
+    /**
+     * ID of a series to filter by.
+     */
     seriesId?: string;
+    /**
+     * ID of a platform to filter by.
+     */
     platformId?: string;
+    /**
+     * Search query for game names or game subpath URLs.
+     */
     search?: string;
-    orderType?: 1;
+    /**
+     * `GameOrderType` to filter games by.
+     */
+    orderType?: Enums.GameOrderType;
+    /**
+     * The maximum amount of Games to fetch.
+     *
+     * @max 500
+     * @default 500
+     */
     limit?: number;
 }
 /**
- * Gets information for the home page. Often empty.
+ * Gets a list of Platforms in the site.
+ */
+export interface GetPlatformList {
+}
+/**
+ * Gets information for the home page.
  */
 export interface GetHomeSummary {
 }
@@ -256,40 +359,48 @@ export interface GetHomeSummary {
  * Gets a list of series on the site.
  */
 export interface GetSeriesList {
+    /**
+     * A query to search for, of series names or subpath URLs.
+     */
     search?: string;
-    orderType?: 1;
+    orderType?: Enums.GameOrderType;
+    /**
+     * The maximum amount of Series to fetch.
+     *
+     * @max 500
+     * @default 500
+     */
     limit?: number;
 }
 /**
  * Gets most information pertinent to a series.
  */
 export interface GetSeriesSummary {
-    seriesUrl?: string;
+    /**
+     * Subpath URL of the series.
+     */
+    seriesUrl: string;
 }
 /**
  * Gets the top 3 runs from all levels under a level category.
  */
 export interface GetGameLevelSummary {
-    gameId: string;
-    categoryId: string;
-    dateFrom?: string;
-    dateTo?: string;
-    emulator?: Enums.EmulatorFilter;
     /**
-     * If `categoryId: string` refers to a level category.
+     * The game leaderboard to fetch level summaries from.
+     *
+     * When not included, `runList[]` will be empty.
      */
-    levelId?: string;
-    obsolete?: Enums.ObsoleteFilter;
-    platformId?: string;
-    regionId?: string;
-    timer?: Enums.TimingMethod;
+    params?: Interfaces.LeaderboardParams;
     /**
-     * If runs other than verified should be included.
+     * The leaderboard page, in relation to `limit`.
      */
-    verified?: Enums.RunStatus;
-    values?: Interfaces.VariableValues[];
-    video?: Enums.VideoFilter;
     page?: number;
+    /**
+     * The limit of Runs per page.
+     *
+     * @max Unknown - likely around 99999.
+     * @default Unknown - likely around 99999.
+     */
     limit?: number;
 }
 /**
@@ -301,24 +412,36 @@ export interface GetGameRandom {
  * Gets all guides on a game.
  */
 export interface GetGuideList {
+    /**
+     * ID of the game.
+     */
     gameId: string;
 }
 /**
- * Get a specific guide by id.
+ * Get a specific guide.
  */
 export interface GetGuide {
+    /**
+     * ID of the guide.
+     */
     id: string;
 }
 /**
- * Get a list of game news articles.
+ * Gets news posts in a game.
  */
 export interface GetNewsList {
+    /**
+     * ID of the game.
+     */
     gameId: string;
 }
 /**
- * Get a game news article.
+ * Gets a specific game news post.
  */
 export interface GetNews {
+    /**
+     * ID of the news post.
+     */
     id: string;
 }
 /**
@@ -328,22 +451,36 @@ export interface GetResourceList {
     gameId: string;
 }
 /**
- * Gets a list of live runners.
+ * Gets a list of live streams on twitch that have the `Speedrun` tag.
+ *
+ * A stream is assigned to a game when the Twitch game is the Game's `GameSettings.twitchName`.
  */
 export interface GetStreamList {
+    /**
+     * ID of a series.
+     */
     seriesId?: string;
+    /**
+     * ID of a game.
+     */
     gameId?: string;
 }
 /**
  * Get threads on a forum.
  */
 export interface GetThreadList {
+    /**
+     * ID of the forum.
+     */
     forumId: string;
 }
 /**
- * Gets a comment post's Thread and Forum.
+ * Gets a comment post's Thread and Forum by `commentId`.
  */
 export interface GetThreadStateByCommentId {
+    /**
+     * ID of the comment.
+     */
     commentId: string;
 }
 /**
@@ -356,6 +493,9 @@ export interface GetChallenge {
  * Get runs from a Challenge board.
  */
 export interface GetChallengeLeaderboard {
+    /**
+     * ID of the challenge you are getting the leaderboard from.
+     */
     challengeId: string;
 }
 /**
@@ -367,18 +507,27 @@ export interface GetChallengeGlobalRankingList {
  * Get a specific Challenge run (not the same as a normal run!)
  */
 export interface GetChallengeRun {
+    /**
+     * ID of the challenge.
+     */
     id: string;
 }
 /**
  * Get a user's runs for display on their profile.
  */
 export interface GetUserLeaderboard {
+    /**
+     * ID of the user.
+     */
     userId: string;
 }
 /**
  * Gets game and series moderation stats for any user.
  */
 export interface GetUserModeration {
+    /**
+     * ID of the user.
+     */
     userId: string;
 }
 /**
@@ -387,7 +536,7 @@ export interface GetUserModeration {
 export interface GetCommentList {
     itemId: string;
     /**
-     * ItemType of the above `itemId: string;`
+     * `ItemType` of the item referenced in `itemId`.
      */
     itemType: Enums.ItemType;
 }
@@ -395,10 +544,13 @@ export interface GetCommentList {
  * Get a specific thread.
  */
 export interface GetThread {
+    /**
+     * ID of the thread.
+     */
     id: string;
 }
 /**
- * Get static data for the site. Including all areas, colors, gameTypes, platforms, etc.
+ * Get static data for the site.
  */
 export interface GetStaticData {
 }