Add toJSON methods (#1859)

* tojson things

* fix client

* ignore private properties

* remove extra property descriptors

* handle primitive flattening

* remove unused import

* add toJSON to collections

* reduce stateful props

* state

* allow custom prop names when flattening

* fix client

* fix build

* fix flatten docs

* remove guild.available, cleanup permissions, remove arbitrary id reduction

* fix util import

* add valueOf as needed, update member props

* fix incorrect merge

* update permissionoverwrites and permissions

remove serialization of permissions in PermissionOverwrites#toJSON.
change Permissions#toJSON to serialize permissions, by default excluding
admin checks.

* change Permissions#toJSON to return the primitive

* Permissions#toJSON explicitly return bitfield

src/client/BaseClient.js

@@ -105,6 +105,10 @@ class BaseClient extends EventEmitter {
     clearInterval(interval);
     this._intervals.delete(interval);
   }
+
+  toJSON(...props) {
+    return Util.flatten(this, { domain: false }, ...props);
+  }
 }
 
 module.exports = BaseClient;

src/client/Client.js

@@ -411,6 +411,15 @@ class Client extends BaseClient {
     );
   }
 
+  toJSON() {
+    return super.toJSON({
+      readyAt: false,
+      broadcasts: false,
+      pings: false,
+      presences: false,
+    });
+  }
+
   /**
    * Adds a ping to {@link Client#pings}.
    * @param {number} startTime Starting time of the ping

src/structures/Base.js

@@ -1,3 +1,5 @@
+const Util = require('../util/Util');
+
 /**
  * Represents a data model that is identifiable by a Snowflake (i.e. Discord API data models).
  */
@@ -23,6 +25,14 @@ class Base {
     this._patch(data);
     return clone;
   }
+
+  toJSON(...props) {
+    return Util.flatten(this, ...props);
+  }
+
+  valueOf() {
+    return this.id;
+  }
 }
 
 module.exports = Base;

src/structures/Channel.js

@@ -114,6 +114,10 @@ class Channel extends Base {
     }
     return channel;
   }
+
+  toJSON(...props) {
+    return super.toJSON({ createdTimestamp: true }, ...props);
+  }
 }
 
 module.exports = Channel;

src/structures/ClientApplication.js

@@ -205,6 +205,10 @@ class ClientApplication extends Base {
   toString() {
     return this.name;
   }
+
+  toJSON() {
+    return super.toJSON({ createdTimestamp: true });
+  }
 }
 
 module.exports = ClientApplication;

src/structures/ClientUser.js

@@ -327,6 +327,16 @@ class ClientUser extends Structures.get('User') {
     return this.client.api.users('@me').channels.post({ data })
       .then(res => this.client.channels.add(res));
   }
+
+  toJSON() {
+    return super.toJSON({
+      friends: false,
+      blocked: false,
+      notes: false,
+      settings: false,
+      guildSettings: false,
+    });
+  }
 }
 
 module.exports = ClientUser;

src/structures/Emoji.js

@@ -61,6 +61,15 @@ class Emoji extends Base {
   toString() {
     return this.id ? `<${this.animated ? 'a' : ''}:${this.name}:${this.id}>` : this.name;
   }
+
+  toJSON() {
+    return super.toJSON({
+      guild: 'guildID',
+      createdTimestamp: true,
+      url: true,
+      identifier: true,
+    });
+  }
 }
 
 module.exports = Emoji;

src/structures/Guild.js

@@ -951,6 +951,19 @@ class Guild extends Base {
     return this.name;
   }
 
+  toJSON() {
+    const json = super.toJSON({
+      available: false,
+      createdTimestamp: true,
+      nameAcronym: true,
+      presences: false,
+      voiceStates: false,
+    });
+    json.iconURL = this.iconURL();
+    json.splashURL = this.splashURL();
+    return json;
+  }
+
   /**
    * Creates a collection of this guild's roles, sorted by their position and IDs.
    * @returns {Collection<Role>}

src/structures/GuildAuditLogs.js

@@ -1,6 +1,7 @@
 const Collection = require('../util/Collection');
 const Snowflake = require('../util/Snowflake');
 const Webhook = require('./Webhook');
+const Util = require('../util/Util');
 
 /**
  * The target type of an entry, e.g. `GUILD`. Here are the available types:
@@ -220,6 +221,10 @@ class GuildAuditLogs {
 
     return 'ALL';
   }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
 }
 
 /**
@@ -371,6 +376,10 @@ class GuildAuditLogsEntry {
   get createdAt() {
     return new Date(this.createdTimestamp);
   }
+
+  toJSON() {
+    return Util.flatten(this, { createdTimestamp: true });
+  }
 }
 
 GuildAuditLogs.Actions = Actions;

src/structures/GuildMember.js

@@ -419,6 +419,17 @@ class GuildMember extends Base {
     return `<@${this.nickname ? '!' : ''}${this.user.id}>`;
   }
 
+  toJSON() {
+    return super.toJSON({
+      guild: 'guildID',
+      user: 'userID',
+      displayName: true,
+      speaking: false,
+      lastMessage: false,
+      lastMessageID: false,
+    });
+  }
+
   // These are here only for documentation purposes - they are implemented by TextBasedChannel
   /* eslint-disable no-empty-function */
   send() {}

src/structures/Invite.js

@@ -149,6 +149,21 @@ class Invite extends Base {
   toString() {
     return this.url;
   }
+
+  toJSON() {
+    return super.toJSON({
+      url: true,
+      expiresTimestamp: true,
+      presenceCount: false,
+      memberCount: false,
+      textChannelCount: false,
+      voiceChannelCount: false,
+      uses: false,
+      channel: 'channelID',
+      inviter: 'inviterID',
+      guild: 'guildID',
+    });
+  }
 }
 
 module.exports = Invite;

src/structures/Message.js

@@ -556,6 +556,18 @@ class Message extends Base {
   toString() {
     return this.content;
   }
+
+  toJSON() {
+    return super.toJSON({
+      channel: 'channelID',
+      author: 'authorID',
+      application: 'applicationID',
+      guild: 'guildID',
+      cleanContent: true,
+      member: false,
+      reactions: false,
+    });
+  }
 }
 
 module.exports = Message;

src/structures/MessageAttachment.js

@@ -1,3 +1,5 @@
+const Util = require('../util/Util');
+
 /**
  * Represents an attachment in a message.
  * @param {BufferResolvable|Stream} file The file
@@ -108,6 +110,10 @@ class MessageAttachment {
      */
     this.width = data.width;
   }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
 }
 
 module.exports = MessageAttachment;

src/structures/MessageEmbed.js

@@ -302,6 +302,10 @@ class MessageEmbed {
     return this;
   }
 
+  toJSON() {
+    return Util.flatten(this, { hexColor: true });
+  }
+
   /**
    * Transforms the embed object to be processed.
    * @returns {Object} The raw data of this embed

src/structures/MessageMentions.js

@@ -1,4 +1,5 @@
 const Collection = require('../util/Collection');
+const Util = require('../util/Util');
 const GuildMember = require('./GuildMember');
 
 /**
@@ -139,6 +140,13 @@ class MessageMentions {
 
     return false;
   }
+
+  toJSON() {
+    return Util.flatten(this, {
+      members: true,
+      channels: true,
+    });
+  }
 }
 
 /**

src/structures/MessageReaction.js

@@ -1,4 +1,5 @@
 const GuildEmoji = require('./GuildEmoji');
+const Util = require('../util/Util');
 const ReactionEmoji = require('./ReactionEmoji');
 const ReactionUserStore = require('../stores/ReactionUserStore');
 
@@ -55,6 +56,11 @@ class MessageReaction {
     return this._emoji;
   }
 
+
+  toJSON() {
+    return Util.flatten(this, { emoji: 'emojiID', message: 'messageID' });
+  }
+
   _add(user) {
     if (!this.users.has(user.id)) {
       this.users.set(user.id, user);

src/structures/PermissionOverwrites.js

@@ -1,4 +1,5 @@
 const Permissions = require('../util/Permissions');
+const Util = require('../util/Util');
 
 /**
  * Represents a permission overwrite for a role or member in a guild channel.
@@ -59,6 +60,10 @@ class PermissionOverwrites {
       .delete({ reason })
       .then(() => this);
   }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
 }
 
 module.exports = PermissionOverwrites;

src/structures/Presence.js

@@ -1,3 +1,4 @@
+const Util = require('../util/Util');
 const { ActivityTypes, ActivityFlags } = require('../util/Constants');
 
 /**
@@ -56,6 +57,10 @@ class Presence {
       this.activity ? this.activity.equals(presence.activity) : !presence.activity
     );
   }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
 }
 
 /**

src/structures/ReactionEmoji.js

@@ -1,3 +1,4 @@
+const Util = require('../util/Util');
 const Emoji = require('./Emoji');
 
 /**
@@ -15,6 +16,14 @@ class ReactionEmoji extends Emoji {
      */
     this.reaction = reaction;
   }
+
+  toJSON() {
+    return Util.flatten(this, { identifier: true });
+  }
+
+  valueOf() {
+    return this.id;
+  }
 }
 
 module.exports = ReactionEmoji;

src/structures/Role.js

@@ -353,6 +353,10 @@ class Role extends Base {
     return `<@&${this.id}>`;
   }
 
+  toJSON() {
+    return super.toJSON({ createdTimestamp: true });
+  }
+
   /**
    * Compares the positions of two roles.
    * @param {Role} role1 First role to compare

src/structures/User.js

@@ -258,6 +258,19 @@ class User extends Base {
     return `<@${this.id}>`;
   }
 
+  toJSON(...props) {
+    const json = super.toJSON({
+      createdTimestamp: true,
+      defaultAvatarURL: true,
+      tag: true,
+      lastMessage: false,
+      lastMessageID: false,
+    }, ...props);
+    json.avatarURL = this.avatarURL();
+    json.displayAvatarURL = this.displayAvatarURL();
+    return json;
+  }
+
   // These are here only for documentation purposes - they are implemented by TextBasedChannel
   /* eslint-disable no-empty-function */
   send() {}

src/structures/UserConnection.js

@@ -1,3 +1,5 @@
+const Util = require('../util/Util');
+
 /**
  * Represents a user connection (or "platform identity").
  */
@@ -43,6 +45,10 @@ class UserConnection {
      */
     this.integrations = data.integrations;
   }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
 }
 
 module.exports = UserConnection;

src/structures/UserProfile.js

@@ -74,6 +74,10 @@ class UserProfile extends Base {
     }
     return flags;
   }
+
+  toJSON() {
+    return super.toJSON({ flags: true });
+  }
 }
 
 module.exports = UserProfile;

src/structures/VoiceRegion.js

@@ -1,3 +1,5 @@
+const Util = require('../util/Util');
+
 /**
  * Represents a Discord voice region for guilds.
  */
@@ -45,6 +47,10 @@ class VoiceRegion {
      */
     this.sampleHostname = data.sample_hostname;
   }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
 }
 
 module.exports = VoiceRegion;

src/structures/interfaces/Collector.js

@@ -1,4 +1,5 @@
 const Collection = require('../../util/Collection');
+const Util = require('../../util/Util');
 const EventEmitter = require('events');
 
 /**
@@ -172,6 +173,10 @@ class Collector extends EventEmitter {
     if (reason) this.stop(reason);
   }
 
+  toJSON() {
+    return Util.flatten(this);
+  }
+
   /* eslint-disable no-empty-function, valid-jsdoc */
   /**
    * Handles incoming events from the `handleCollect` function. Returns null if the event should not

src/util/Collection.js

@@ -1,3 +1,5 @@
+const Util = require('./Util');
+
 /**
  * A Map with additional utility methods. This is used throughout discord.js rather than Arrays for anything that has
  * an ID, for significantly improved performance and ease-of-use.
@@ -425,6 +427,10 @@ class Collection extends Map {
   sort(compareFunction = (x, y) => +(x > y) || +(x === y) - 1) {
     return new Collection([...this.entries()].sort((a, b) => compareFunction(a[1], b[1], a[0], b[0])));
   }
+
+  toJSON() {
+    return this.map(e => typeof e.toJSON === 'function' ? e.toJSON() : Util.flatten(e));
+  }
 }
 
 module.exports = Collection;

src/util/Permissions.js

@@ -102,6 +102,10 @@ class Permissions {
     return Object.keys(this.constructor.FLAGS).filter(perm => this.has(perm, checkAdmin));
   }
 
+  toJSON() {
+    return this.bitfield;
+  }
+
   valueOf() {
     return this.bitfield;
   }

src/util/Util.js

@@ -12,6 +12,41 @@ class Util {
     throw new Error(`The ${this.constructor.name} class may not be instantiated.`);
   }
 
+  /**
+   * Flatten an object. Any properties that are collections will get converted to an array of keys.
+   * @param {Object} obj The object to flatten.
+   * @param {...Object<string, boolean|string>} [props] Specific properties to include/exclude.
+   * @returns {Object}
+   */
+  static flatten(obj, ...props) {
+    const isObject = d => typeof d === 'object' && d !== null;
+    if (!isObject(obj)) return obj;
+
+    props = Object.assign(...Object.keys(obj).filter(k => !k.startsWith('_')).map(k => ({ [k]: true })), ...props);
+
+    const out = {};
+
+    for (let [prop, newProp] of Object.entries(props)) {
+      if (!newProp) continue;
+      newProp = newProp === true ? prop : newProp;
+
+      const element = obj[prop];
+      const elemIsObj = isObject(element);
+      const valueOf = elemIsObj && typeof element.valueOf === 'function' ? element.valueOf() : null;
+
+      // If it's a collection, make the array of keys
+      if (element instanceof require('./Collection')) out[newProp] = Array.from(element.keys());
+      // If it's an array, flatten each element
+      else if (Array.isArray(element)) out[newProp] = element.map(e => Util.flatten(e));
+      // If it's an object with a primitive `valueOf`, use that value
+      else if (valueOf && !isObject(valueOf)) out[newProp] = valueOf;
+      // If it's a primitive
+      else if (!elemIsObj) out[newProp] = element;
+    }
+
+    return out;
+  }
+
   /**
    * Splits a string into multiple chunks at a designated character that do not exceed a specific length.
    * @param {string} text Content to split