docs: LiveQuery

Author: leeyeh

src/live-query.js

@@ -4,7 +4,12 @@ const { inherits } = require('./utils');
 const { request } = require('./request');
 
 module.exports = (AV) => {
-  const LiveQuery = AV.LiveQuery = inherits(EventEmitter, {
+  /**
+   * @class
+   * A LiveQuery, created by {@link AV.Query#subscribe} is an EventEmitter notifies changes of the Query.
+   * @since 3.0.0
+   */
+  AV.LiveQuery = inherits(EventEmitter, /** @lends AV.LiveQuery.prototype */ {
     constructor(id, client) {
       EventEmitter.apply(this);
       this.id = id;
@@ -24,12 +29,43 @@ module.exports = (AV) => {
           __type: object.className === '_File' ? 'File' : 'Object',
         }, object));
         if (updatedKeys) {
+          /**
+           * An existing AV.Object which fulfills the Query you subscribe is updated.
+           * @event AV.LiveQuery#update
+           * @param {AV.Object|AV.File} target updated object
+           * @param {String[]} updatedKeys updated keys
+           */
           this.emit(op, target, updatedKeys);
         } else {
+          /**
+           * A new AV.Object which fulfills the Query you subscribe is created.
+           * @event AV.LiveQuery#create
+           * @param {AV.Object|AV.File} target updated object
+           */
+          /**
+           * An existing AV.Object which fulfills the Query you subscribe is deleted.
+           * @event AV.LiveQuery#delete
+           * @param {AV.Object|AV.File} target updated object
+           */
+          /**
+           * An existing AV.Object which doesn't fulfill the Query is updated and now it fulfills the Query.
+           * @event AV.LiveQuery#enter
+           * @param {AV.Object|AV.File} target updated object
+           */
+          /**
+           * An existing AV.Object which fulfills the Query is updated and now it doesn't fulfill the Query.
+           * @event AV.LiveQuery#leave
+           * @param {AV.Object|AV.File} target updated object
+           */
           this.emit(op, target);
         }
       });
     },
+    /**
+     * unsubscribe the query
+     *
+     * @return {Promise}
+     */
     unsubscribe() {
       this._client.deregister(this);
       return request({
@@ -64,7 +100,7 @@ module.exports = (AV) => {
           }).then(({
             query_id: queryId,
           }) => AV._config.realtime.createLiveQueryClient(subscriptionId)
-            .then(liveQueryClient => new LiveQuery(queryId, liveQueryClient))
+            .then(liveQueryClient => new AV.LiveQuery(queryId, liveQueryClient))
           )
         );
     },

src/query.js

@@ -1014,6 +1014,14 @@ module.exports = function(AV) {
       });
     },
 
+    /**
+     * Subscribe the changes of this query.
+     * 
+     * LiveQuery is not included in the default bundle: {@link https://url.leanapp.cn/enable-live-query}.
+     * 
+     * @since 3.0.0
+     * @return {AV.LiveQuery} An eventemitter which can be used to get LiveQuery updates;
+     */
     subscribe(options) {
       return AV.LiveQuery.init(this, options);
     },

storage.d.ts

@@ -2,6 +2,13 @@ interface AsyncIterator<T> {
   next(): Promise<IteratorResult<T>>
 }
 
+declare class EventEmitter {
+  on(evt: string, listener: Function): EventEmitter;
+  once(evt: string, listener: Function): EventEmitter;
+  off(evt: string, listener: Function): EventEmitter;
+  emit(evt: string, ...args: any[]): Boolean;
+}
+
 declare namespace AV {
 
     export var applicationId: string;
@@ -469,7 +476,12 @@ declare namespace AV {
         withinKilometers(key: string, point: GeoPoint, maxDistance: number): Query;
         withinMiles(key: string, point: GeoPoint, maxDistance: number): Query;
         withinRadians(key: string, point: GeoPoint, maxDistance: number): Query;
-        scan<T>(options?:{ orderedBy?: string, batchSize?: number }, authOptions?: AuthOptions): AsyncIterator<T>
+        scan<T>(options?:{ orderedBy?: string, batchSize?: number }, authOptions?: AuthOptions): AsyncIterator<T>;
+        subscribe(options?:{ subscriptionId?: string }): Promise<LiveQuery>;
+    }
+
+    class LiveQuery extends EventEmitter {
+      unsubscribe(): Promise<void>;
     }
 
     export namespace Query {