feat(User): add User#associateWithAuthData & #disassociateAuthData (#519)

Author: leeyeh

package.json

@@ -48,7 +48,7 @@
     "gulp-babel": "^6.1.1",
     "gulp-clean": "^0.3.1",
     "gulp-shell": "^0.5.2",
-    "jsdoc": "~3.4.0",
+    "jsdoc": "^3.5.5",
     "mocha": "^3.0.0",
     "nyc": "^8.1.0",
     "qiniu": "^6.1.11",

src/user.js

@@ -108,7 +108,7 @@ module.exports = function(AV) {
       }
       var success = provider.restoreAuthentication(authData[authType]);
       if (!success) {
-        this._unlinkFrom(provider);
+        this.dissociateAuthData(provider);
       }
     },
 
@@ -160,21 +160,43 @@ module.exports = function(AV) {
       }
     },
 
+    /**
+     * Associate the user with a third party authData.
+     * @since 3.3.0
+     * @param {Object} authData The response json data returned from third party token, maybe like { openid: 'abc123', access_token: '123abc', expires_in: 1382686496 }
+     * @param {string} platform Available platform for sign up.
+     * @return {Promise<AV.User>} A promise that is fulfilled with the user when completed.
+     * @example user.associateWithAuthData({
+     *   openid: 'abc123',
+     *   access_token: '123abc',
+     *   expires_in: 1382686496
+     * }, 'weixin').then(function(user) {
+     *   //Access user here
+     * }).catch(function(error) {
+     *   //console.error("error: ", error);
+     * });
+     */
+    associateWithAuthData(authData, platform) {
+      return this._linkWith(platform, authData);
+    },
+
     /**
      * 将用户与小程序用户进行关联。适用于为已经在用户系统中存在的用户关联当前使用小程序的微信帐号。
      * 仅在小程序中可用。
      *
-     * @return {AV.User}
+     * @return {Promise<AV.User>}
      */
     linkWithWeapp() {
       return getWeappLoginCode().then(code => this._linkWith('lc_weapp', { code }));
     },
 
     /**
      * Unlinks a user from a service.
-     * @private
+     * @param {string} platform
+     * @return {Promise<AV.User>}
+     * @since 3.3.0
      */
-    _unlinkFrom: function(provider) {
+    dissociateAuthData(provider) {
       if (_.isString(provider)) {
         provider = AV.User._authProviders[provider];
       }
@@ -184,6 +206,15 @@ module.exports = function(AV) {
       });
     },
 
+    /**
+     * @private
+     * @deprecated
+     */
+    _unlinkFrom(provider) {
+      console.warn('DEPRECATED: User#_unlinkFrom 已废弃，请使用 User#dissociateAuthData 代替');
+      return this.dissociateAuthData(provider);
+    },
+
     /**
      * Checks whether a user is linked to a service.
      * @private
@@ -800,24 +831,8 @@ module.exports = function(AV) {
       return getWeappLoginCode().then(code => this.signUpOrlogInWithAuthData({ code }, 'lc_weapp'));
     },
 
-    /**
-     * Associate a user with a third party auth data(AccessToken).
-     *
-     * @param {AV.User} userObj A user which you want to associate.
-     * @param {string} platform Available platform for sign up.
-     * @param {Object} authData The response json data returned from third party token, maybe like { openid: 'abc123', access_token: '123abc', expires_in: 1382686496 }
-     * @return {Promise} A promise that is fulfilled with the user when completed.
-     * @example AV.User.associateWithAuthData(loginUser, 'weixin', {
-     *   openid: 'abc123',
-     *   access_token: '123abc',
-     *   expires_in: 1382686496
-     * }).then(function(user) {
-     *   //Access user here
-     * }).catch(function(error) {
-     *   //console.error("error: ", error);
-     * });
-     */
     associateWithAuthData(userObj, platform, authData) {
+      console.warn('DEPRECATED: User.associateWithAuthData 已废弃，请使用 User#dissociateAuthData 代替');
       return userObj._linkWith(platform, authData);
     },
     /**

storage.d.ts

@@ -576,6 +576,8 @@ declare namespace AV {
         isAuthenticated(): Promise<boolean>;
         isCurrent(): boolean;
 
+        associateWithAuthData(authData: Object, platform?: string): Promise<User>;
+        dissociateAuthData(platform?: string): Promise<User>;
 
         getEmail(): string;
         setEmail(email: string, options?: AuthOptions): boolean;