fix(leaderboard): revise #getResults

- returns Ranking[] instead of Statistic[]
- add includeStatistics option

Author: leeyeh

demo/leaderboard/index.html

@@ -31,14 +31,14 @@
         </transition>
       </div>
     </div>
-    <transition-group name="statistic-list" class="statistic-list" tag="ul">
-      <li v-for="statistic in statistics" class="statistic" :key="statistic.user.username" :class="{ completed: statistic.done }">
-        <span>{{statistic.position + 1}}.&nbsp;</span>
-        <span class="username">{{statistic.user.username}}
-          <span v-if="statistic.user.username == user.username">（你）</span>
+    <transition-group name="ranking-list" class="ranking-list" tag="ul">
+      <li v-for="ranking in rankings" class="ranking" :key="ranking.user.username" :class="{ completed: ranking.done }">
+        <span>{{ranking.rank + 1}}.&nbsp;</span>
+        <span class="username">{{ranking.user.username}}
+          <span v-if="ranking.user.username == user.username">（你）</span>
         </span>
         <span class="score">
-          <animated-integer :value="statistic.value"></animated-integer>
+          <animated-integer :value="ranking.value"></animated-integer>
         </span>
       </li>
     </transition-group>

demo/leaderboard/leaderboard.css

@@ -62,7 +62,7 @@ a:visited {
   left: 0;
 }
 
-.statistic-list {
+.ranking-list {
   height: 100%;
   flex: 1;
   margin: 0;
@@ -74,7 +74,7 @@ a:visited {
   overflow: auto;
 }
 
-.statistic {
+.ranking {
   background: linear-gradient(320deg, #581b98, #9c1de7);
   height: 100%;
   max-height: 8.333%;
@@ -87,34 +87,34 @@ a:visited {
   position: relative;
 }
 
-.statistic-list-move {
+.ranking-list-move {
   transition: transform 1s;
 }
 
-.statistic-list-enter,
-.statistic-list-leave-to {
+.ranking-list-enter,
+.ranking-list-leave-to {
   opacity: 0;
   transform: translateY(-30px);
 }
-.statistic-list-leave-active {
+.ranking-list-leave-active {
   position: absolute;
 }
 
-.statistic:nth-child(1) {
+.ranking:nth-child(1) {
   color: gold;
 }
-.statistic:nth-child(2) {
+.ranking:nth-child(2) {
   color: lightgray;
 }
-.statistic:nth-child(3) {
+.ranking:nth-child(3) {
   color: sandybrown;
 }
 
 .username {
   width: 100%;
   flex: 1;
 }
-.statistic .score {
+.ranking .score {
   max-width: 44px;
   overflow: hidden;
 }

demo/leaderboard/leaderboard.js

@@ -48,7 +48,7 @@ Vue.component('animated-integer', {
 
 var app = new Vue({
   data: {
-    statistics: [],
+    rankings: [],
     score: null,
     highScore: 0,
     newHighScore: false,
@@ -115,32 +115,32 @@ var app = new Vue({
       Promise.all([
         leaderboard.getResults({
           limit: MAX_RESULTS_COUNT,
-          includeUserKeys: ['username'],
+          selectUserKeys: ['username'],
         }),
         Promise.resolve(
           AV.User.current()
             ? leaderboard.getResultsAroundUser({
                 limit: 3,
-                includeUserKeys: ['username'],
+                selectUserKeys: ['username'],
               })
             : []
         ),
       ])
-        .then(([topStatistics, [beforeUserStatistic, userStatistic]]) => {
-          console.log(topStatistics, [beforeUserStatistic, userStatistic]);
-          let statistics;
-          if (userStatistic && userStatistic.position >= MAX_RESULTS_COUNT) {
-            statistics = [
-              ...topStatistics.slice(0, -2),
-              beforeUserStatistic,
-              userStatistic,
+        .then(([topRankings, [beforeUserRankings, userRanking]]) => {
+          console.log(topRankings, [beforeUserRankings, userRanking]);
+          let rankings;
+          if (userRanking && userRanking.rank >= MAX_RESULTS_COUNT) {
+            rankings = [
+              ...topRankings.slice(0, -2),
+              beforeUserRankings,
+              userRanking,
             ];
           } else {
-            statistics = topStatistics;
+            rankings = topRankings;
           }
-          this.statistics = JSON.parse(JSON.stringify(statistics));
-          if (userStatistic) {
-            this.highScore = userStatistic.value;
+          this.rankings = JSON.parse(JSON.stringify(rankings));
+          if (userRanking) {
+            this.highScore = userRanking.value;
           }
         })
         .catch(console.error);

src/leaderboard.js

@@ -36,10 +36,18 @@ AV.LeaderboardUpdateStrategy = {
   LAST: 'last',
 };
 
+/**
+ * @typedef {Object} Ranking
+ * @property {number} rank Starts at 0
+ * @property {number} value the statistic value of this ranking
+ * @property {AV.User} user The user of this ranking
+ * @property {Statistic[]} [includedStatistics] Other statistics of the user, specified by the `includeStatistic` option of `AV.Leaderboard.getResults()`
+ */
+
 /**
  * @class
  */
-function Statistic({ user, name, value, position, version }) {
+function Statistic({ name, value, version }) {
   /**
    * @type {string}
    */
@@ -48,21 +56,19 @@ function Statistic({ user, name, value, position, version }) {
    * @type {number}
    */
   this.value = value;
-  /**
-   * @type {AV.User}
-   */
-  this.user = user;
-  /**
-   * The position of the leandboard. Only occurs in leaderboard results.
-   * @type {number?}
-   */
-  this.position = position;
   /**
    * @type {number?}
    */
   this.version = version;
 }
 
+const parseStatisticData = statisticData => {
+  const { statisticName: name, statisticValue: value, version } = AV._decode(
+    statisticData
+  );
+  return new Statistic({ name, value, version });
+};
+
 /**
  * @class
  */
@@ -156,19 +162,12 @@ AV.Leaderboard.getStatistics = (user, { statisticNames } = {}, authOptions) =>
       method: 'GET',
       path: `/leaderboard/users/${user.id}/statistics`,
       query: {
-        statistics: statisticNames ? ensureArray(statisticNames) : undefined,
+        statistics: statisticNames
+          ? ensureArray(statisticNames).join(',')
+          : undefined,
       },
       authOptions,
-    }).then(({ results }) =>
-      results.map(statisticData => {
-        const {
-          statisticName: name,
-          statisticValue: value,
-          version,
-        } = AV._decode(statisticData);
-        return new Statistic({ user, name, value, version });
-      })
-    );
+    }).then(({ results }) => results.map(parseStatisticData));
   });
 /**
  * Update Statistics for the specified user.
@@ -189,16 +188,7 @@ AV.Leaderboard.updateStatistics = (user, statistics, authOptions) =>
       path: `/leaderboard/users/${user.id}/statistics`,
       data,
       authOptions,
-    }).then(({ results }) =>
-      results.map(statisticData => {
-        const {
-          statisticName: name,
-          statisticValue: value,
-          version,
-        } = AV._decode(statisticData);
-        return new Statistic({ user, name, value, version });
-      })
-    );
+    }).then(({ results }) => results.map(parseStatisticData));
   });
 
 _.extend(
@@ -213,7 +203,7 @@ _.extend(
         if (key === 'createdAt') {
           value = parseDate(value);
         }
-        if (value.__type === 'Date') {
+        if (value && value.__type === 'Date') {
           value = parseDate(value.iso);
         }
         this[key] = value;
@@ -232,29 +222,41 @@ _.extend(
         authOptions,
       }).then(data => this._finishFetch(data));
     },
-    _getResults({ skip, limit, includeUserKeys }, authOptions, self) {
+    _getResults(
+      { skip, limit, selectUserKeys, includeStatistics },
+      authOptions,
+      self
+    ) {
       return request({
         method: 'GET',
-        path: `/leaderboard/leaderboards/${this.statisticName}/positions${
+        path: `/leaderboard/leaderboards/${this.statisticName}/ranks${
           self ? '/self' : ''
         }`,
         query: {
           skip,
           limit,
-          includeUser: includeUserKeys
-            ? ensureArray(includeUserKeys).join(',')
+          includeUser: selectUserKeys
+            ? ensureArray(selectUserKeys).join(',')
+            : undefined,
+          includeStatistics: includeStatistics
+            ? ensureArray(includeStatistics).join(',')
             : undefined,
         },
         authOptions,
-      }).then(({ results }) =>
-        results.map(statisticData => {
+      }).then(({ results: rankings }) =>
+        rankings.map(rankingData => {
           const {
             user,
-            statisticName: name,
             statisticValue: value,
-            position,
-          } = AV._decode(statisticData);
-          return new Statistic({ user, name, value, position });
+            rank,
+            statistics = [],
+          } = AV._decode(rankingData);
+          return {
+            user,
+            value,
+            rank,
+            includedStatistics: statistics.map(parseStatisticData),
+          };
         })
       );
     },
@@ -263,23 +265,38 @@ _.extend(
      * @param {Object} [options]
      * @param {number} [options.skip] The number of results to skip. This is useful for pagination.
      * @param {number} [options.limit] The limit of the number of results.
-     * @param {string[]} [options.includeUserKeys] Specify keys of the users to include
+     * @param {string[]} [options.selectUserKeys] Specify keys of the users to include
+     * @param {string[]} [options.includeStatistics] Specify other statistics to include in the Rankings
      * @param {AuthOptions} [authOptions]
-     * @return {Promise<Statistic[]>}
+     * @return {Promise<Ranking[]>}
      */
-    getResults({ skip, limit, includeUserKeys } = {}, authOptions) {
-      return this._getResults({ skip, limit, includeUserKeys }, authOptions);
+    getResults(
+      { skip, limit, selectUserKeys, includeStatistics } = {},
+      authOptions
+    ) {
+      return this._getResults(
+        { skip, limit, selectUserKeys, includeStatistics },
+        authOptions
+      );
     },
     /**
      * Retrieve a list of ranked users for this Leaderboard, centered on the specified user.
      * @param {Object} [options]
      * @param {number} [options.limit] The limit of the number of results.
-     * @param {string[]} [options.includeUserKeys] Specify keys of the users to include
+     * @param {string[]} [options.selectUserKeys] Specify keys of the users to include
+     * @param {string[]} [options.includeStatistics] Specify other statistics to include in the Rankings
      * @param {AuthOptions} [authOptions]
-     * @return {Promise<Statistic[]>}
+     * @return {Promise<Ranking[]>}
      */
-    getResultsAroundUser({ limit, includeUserKeys } = {}, authOptions) {
-      return this._getResults({ limit, includeUserKeys }, authOptions, true);
+    getResultsAroundUser(
+      { limit, selectUserKeys, includeStatistics } = {},
+      authOptions
+    ) {
+      return this._getResults(
+        { limit, selectUserKeys, includeStatistics },
+        authOptions,
+        true
+      );
     },
     _update(data, authOptions) {
       return request({

storage.d.ts

@@ -791,11 +791,16 @@ export class Conversation extends Object {
 declare class Statistic {
   name: string;
   value: number;
-  user: AV.User;
-  position?: number;
   version?: number;
 }
 
+declare interface Ranking {
+  value: number;
+  user: AV.User;
+  rank: number;
+  includedStatistics?: Statistic[];
+}
+
 export class Leaderboard {
   statisticName: string;
   order?: LeaderboardOrder;
@@ -831,13 +836,22 @@ export class Leaderboard {
 
   fetch(authOptions?: AuthOptions): Promise<Leaderboard>;
   getResults(
-    options?: { skip?: number; limit?: number; includeUserKeys?: string[] },
+    options?: {
+      skip?: number;
+      limit?: number;
+      selectUserKeys?: string | string[];
+      includeStatistics?: string | string[];
+    },
     authOptions?: AuthOptions
-  ): Promise<Statistic[]>;
+  ): Promise<Ranking[]>;
   getResultsAroundUser(
-    options?: { limit?: number; includeUserKeys?: string[] },
+    options?: {
+      limit?: number;
+      selectUserKeys?: string | string[];
+      includeStatistics?: string | string[];
+    },
     authOptions?: AuthOptions
-  ): Promise<Statistic[]>;
+  ): Promise<Ranking[]>;
   updateVersionChangeInterval(
     versionChangeInterval: LeaderboardVersionChangeInterval,
     authOptions?: AuthOptions