Skip to content

Commit 4708b5f

Browse files
leeyehleeyeh
committed
docs(leaderboard): document AV.Leaderboard
1 parent 429b8ee commit 4708b5f

File tree

4 files changed

+264
-88
lines changed

4 files changed

+264
-88
lines changed

‎src/av.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,7 @@ AV._decode = function(value, key) {
256256
/**
257257
* The inverse function of {@link AV.Object#toFullJSON}.
258258
* @since 2.0.0
259+
* @method
259260
* @param {Object}
260261
* return {AV.Object|AV.File|any}
261262
*/

‎src/index.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ require('./search')(AV);
3737
require('./insight')(AV);
3838

3939
AV.Conversation = require('./conversation');
40-
_.extend(AV, require('./leaderboard'));
40+
require('./leaderboard');
4141
module.exports = AV;
4242

4343
/**

‎src/leaderboard.js‎

Lines changed: 195 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -4,36 +4,94 @@ const { request } = require('./request');
44
const { ensureArray, parseDate } = require('./utils');
55
const AV = require('./av');
66

7-
const LeaderboardVersionChangeInterval = {
7+
/**
8+
* The version change interval for Leaderboard
9+
* @enum
10+
*/
11+
AV.LeaderboardVersionChangeInterval = {
812
NEVER: 'never',
913
HOUR: 'hour',
1014
DAY: 'day',
1115
WEEK: 'week',
1216
MONTH: 'month',
1317
};
1418

15-
const LeaderboardOrder = {
19+
/**
20+
* The order of the leaderboard results
21+
* @enum
22+
*/
23+
AV.LeaderboardOrder = {
1624
ASCENDING: 'ascending',
1725
DESCENDING: 'descending',
1826
};
1927

28+
/**
29+
* @class
30+
*/
2031
function Statistic({ user, name, value, position, version }) {
32+
/**
33+
* @type {string}
34+
*/
2135
this.name = name;
36+
/**
37+
* @type {number}
38+
*/
2239
this.value = value;
40+
/**
41+
* @type {AV.User}
42+
*/
2343
this.user = user;
44+
/**
45+
* The position of the leandboard. Only occurs in leaderboard results.
46+
* @type {number?}
47+
*/
2448
this.position = position;
49+
/**
50+
* @type {number?}
51+
*/
2552
this.version = version;
2653
}
2754

28-
function Leaderboard(statisticName) {
55+
/**
56+
* @class
57+
*/
58+
AV.Leaderboard = function(statisticName) {
59+
/**
60+
* @type {string}
61+
*/
2962
this.statisticName = statisticName;
63+
/**
64+
* @type {AV.LeaderboardVersionChangeInterval}
65+
*/
3066
this.versionChangeInterval = undefined;
67+
/**
68+
* @type {number}
69+
*/
3170
this.version = undefined;
71+
/**
72+
* @type {Date?}
73+
*/
3274
this.nextResetAt = undefined;
33-
}
75+
};
76+
const Leaderboard = AV.Leaderboard;
3477

35-
Leaderboard.createWithoutData = statisticName => new Leaderboard(statisticName);
36-
Leaderboard.createLeaderboard = (
78+
/**
79+
* Create an instance of Leaderboard for the give statistic name.
80+
* @param {string} statisticName
81+
* @return {AV.Leaderboard}
82+
*/
83+
AV.Leaderboard.createWithoutData = statisticName =>
84+
new Leaderboard(statisticName);
85+
/**
86+
* (masterKey required) Create a new Leaderboard.
87+
* @param {Object} options
88+
* @param {string} options.statisticName
89+
* @param {AV.LeaderboardOrder} options.order
90+
* @param {AV.LeaderboardVersionChangeInterval} options.versionChangeInterval
91+
* @param {AuthOptions} [authOptions]
92+
* @return {Promise<AV.Leaderboard>}
93+
*/
94+
AV.Leaderboard.createLeaderboard = (
3795
{ statisticName, order, versionChangeInterval },
3896
authOptions
3997
) =>
@@ -50,9 +108,23 @@ Leaderboard.createLeaderboard = (
50108
const leaderboard = new Leaderboard(statisticName);
51109
return leaderboard._finishFetch(data);
52110
});
53-
Leaderboard.getLeaderboard = (statisticName, authOptions) =>
111+
/**
112+
* Get the Leaderboard with the specified statistic name.
113+
* @param {string} statisticName
114+
* @param {AuthOptions} [authOptions]
115+
* @return {Promise<AV.Leaderboard>}
116+
*/
117+
AV.Leaderboard.getLeaderboard = (statisticName, authOptions) =>
54118
Leaderboard.createWithoutData(statisticName).fetch(authOptions);
55-
Leaderboard.getStatistics = (user, { statisticNames } = {}, authOptions) =>
119+
/**
120+
* Get Statistics for the specified user.
121+
* @param {AV.User} user The specified AV.User pointer.
122+
* @param {Object} [options]
123+
* @param {string[]} [options.statisticNames] Specify the statisticNames. If not set, all statistics of the user will be fetched.
124+
* @param {AuthOptions} [authOptions]
125+
* @return {Promise<Statistic[]>}
126+
*/
127+
AV.Leaderboard.getStatistics = (user, { statisticNames } = {}, authOptions) =>
56128
Promise.resolve().then(() => {
57129
if (!(user && user.id)) throw new Error('user must be an AV.User');
58130
return request({
@@ -73,7 +145,14 @@ Leaderboard.getStatistics = (user, { statisticNames } = {}, authOptions) =>
73145
})
74146
);
75147
});
76-
Leaderboard.updateStatistics = (user, statistics, authOptions) =>
148+
/**
149+
* Update Statistics for the specified user.
150+
* @param {AV.User} user The specified AV.User pointer.
151+
* @param {Object} statistics A name-value pair representing the statistics to update.
152+
* @param {AuthOptions} [authOptions]
153+
* @return {Promise<Statistic[]>}
154+
*/
155+
AV.Leaderboard.updateStatistics = (user, statistics, authOptions) =>
77156
Promise.resolve().then(() => {
78157
if (!(user && user.id)) throw new Error('user must be an AV.User');
79158
const data = _.map(statistics, (value, key) => ({
@@ -97,80 +176,110 @@ Leaderboard.updateStatistics = (user, statistics, authOptions) =>
97176
);
98177
});
99178

100-
_.extend(Leaderboard.prototype, {
101-
_finishFetch(data) {
102-
_.forEach(data, (value, key) => {
103-
if (key === 'updatedAt' || key === 'objectId') return;
104-
if (key === 'expiredAt') {
105-
key = 'nextResetAt';
106-
}
107-
if (value.__type === 'Date') {
108-
value = parseDate(value.iso);
109-
}
110-
this[key] = value;
111-
});
112-
return this;
113-
},
114-
fetch(authOptions) {
115-
return request({
116-
method: 'GET',
117-
path: `/play/leaderboards/${this.statisticName}`,
118-
authOptions,
119-
}).then(data => this._finishFetch(data));
120-
},
121-
_getResults({ skip, limit, includeUserKeys }, authOptions, self) {
122-
return request({
123-
method: 'GET',
124-
path: `/play/leaderboards/${this.statisticName}/positions${
125-
self ? '/self' : ''
126-
}`,
127-
query: {
128-
skip,
129-
limit,
130-
includeUser: includeUserKeys
131-
? ensureArray(includeUserKeys).join(',')
132-
: undefined,
133-
},
134-
authOptions,
135-
}).then(({ results }) =>
136-
results.map(statisticData => {
137-
const {
138-
user,
139-
statisticName: name,
140-
statisticValue: value,
141-
position,
142-
} = AV._decode(statisticData);
143-
return new Statistic({ user, name, value, position });
144-
})
145-
);
146-
},
147-
getResults({ skip, limit, includeUserKeys } = {}, authOptions) {
148-
return this._getResults({ skip, limit, includeUserKeys }, authOptions);
149-
},
150-
getResultsAroundUser({ limit, includeUserKeys } = {}, authOptions) {
151-
return this._getResults({ limit, includeUserKeys }, authOptions, true);
152-
},
153-
updateVersionChangeInterval(versionChangeInterval, authOptions) {
154-
return request({
155-
method: 'PUT',
156-
path: `/play/leaderboards/${this.statisticName}`,
157-
data: {
158-
versionChangeInterval,
159-
},
160-
authOptions,
161-
}).then(data => this._finishFetch(data));
162-
},
163-
reset(authOptions) {
164-
return request({
165-
method: 'PUT',
166-
path: `/play/leaderboards/${this.statisticName}/incrementVersion`,
167-
authOptions,
168-
}).then(data => this._finishFetch(data));
169-
},
170-
});
171-
172-
module.exports = {
173-
Leaderboard,
174-
LeaderboardOrder,
175-
LeaderboardVersionChangeInterval,
176-
};
179+
_.extend(
180+
Leaderboard.prototype,
181+
/** @lends AV.Leaderboard.prototype */ {
182+
_finishFetch(data) {
183+
_.forEach(data, (value, key) => {
184+
if (key === 'updatedAt' || key === 'objectId') return;
185+
if (key === 'expiredAt') {
186+
key = 'nextResetAt';
187+
}
188+
if (value.__type === 'Date') {
189+
value = parseDate(value.iso);
190+
}
191+
this[key] = value;
192+
});
193+
return this;
194+
},
195+
/**
196+
* Fetch data from the srever.
197+
* @param {AuthOptions} [authOptions]
198+
* @return {Promise<AV.Leaderboard>}
199+
*/
200+
fetch(authOptions) {
201+
return request({
202+
method: 'GET',
203+
path: `/play/leaderboards/${this.statisticName}`,
204+
authOptions,
205+
}).then(data => this._finishFetch(data));
206+
},
207+
_getResults({ skip, limit, includeUserKeys }, authOptions, self) {
208+
return request({
209+
method: 'GET',
210+
path: `/play/leaderboards/${this.statisticName}/positions${
211+
self ? '/self' : ''
212+
}`,
213+
query: {
214+
skip,
215+
limit,
216+
includeUser: includeUserKeys
217+
? ensureArray(includeUserKeys).join(',')
218+
: undefined,
219+
},
220+
authOptions,
221+
}).then(({ results }) =>
222+
results.map(statisticData => {
223+
const {
224+
user,
225+
statisticName: name,
226+
statisticValue: value,
227+
position,
228+
} = AV._decode(statisticData);
229+
return new Statistic({ user, name, value, position });
230+
})
231+
);
232+
},
233+
/**
234+
* Retrieve a list of ranked users for this Leaderboard.
235+
* @param {Object} [options]
236+
* @param {number} [options.skip] The number of results to skip. This is useful for pagination.
237+
* @param {number} [options.limit] The limit of the number of results.
238+
* @param {string[]} [options.includeUserKeys] Specify keys of the users to include
239+
* @param {AuthOptions} [authOptions]
240+
* @return {Promise<Statistic[]>}
241+
*/
242+
getResults({ skip, limit, includeUserKeys } = {}, authOptions) {
243+
return this._getResults({ skip, limit, includeUserKeys }, authOptions);
244+
},
245+
/**
246+
* Retrieve a list of ranked users for this Leaderboard, centered on the specified user.
247+
* @param {Object} [options]
248+
* @param {number} [options.limit] The limit of the number of results.
249+
* @param {string[]} [options.includeUserKeys] Specify keys of the users to include
250+
* @param {AuthOptions} [authOptions]
251+
* @return {Promise<Statistic[]>}
252+
*/
253+
getResultsAroundUser({ limit, includeUserKeys } = {}, authOptions) {
254+
return this._getResults({ limit, includeUserKeys }, authOptions, true);
255+
},
256+
/**
257+
* (masterKey required) Update the version change interval of the Leaderboard.
258+
* @param {AV.LeaderboardVersionChangeInterval} versionChangeInterval
259+
* @param {AuthOptions} [authOptions]
260+
* @return {Promise<AV.Leaderboard>}
261+
*/
262+
updateVersionChangeInterval(versionChangeInterval, authOptions) {
263+
return request({
264+
method: 'PUT',
265+
path: `/play/leaderboards/${this.statisticName}`,
266+
data: {
267+
versionChangeInterval,
268+
},
269+
authOptions,
270+
}).then(data => this._finishFetch(data));
271+
},
272+
/**
273+
* (masterKey required) Reset the Leaderboard. The version of the Leaderboard will be incremented by 1.
274+
* @param {AuthOptions} [authOptions]
275+
* @return {Promise<AV.Leaderboard>}
276+
*/
277+
reset(authOptions) {
278+
return request({
279+
method: 'PUT',
280+
path: `/play/leaderboards/${this.statisticName}/incrementVersion`,
281+
authOptions,
282+
}).then(data => this._finishFetch(data));
283+
},
284+
}
285+
);

0 commit comments

Comments
 (0)