Containers and iterables

Discordia relies on custom classes to store, retrieve, update, and delete Discord data in situations where simple Lua tables may not be sufficient.

When certain payloads are received from the Discord gateway via WebSocket, data is passed to an event handler where it is encapsulated in containers, stored in caches, and sometimes made accessible via other iterables.

Containers

Discordia uses special Container classes to store raw Discord data as objects with useful properties and methods.

Every container has a client and parent property. The client property is a handle for the main client instance that is manages the container while the parent property is a handle for the object where the container is directly cached. Sometimes, these are the same. For example, guild.parent and guild.client are equivalent. Otherwise, the parent will be defined differently. For example, role.parent and role.guild are equivalent. Additionally, role.guild.client and role.client are equivalent, since both the guild and its roles are necessarily managed by the same client.

Every container has a __hash method that returns a certain property that can be used to uniquely identify the container. For example, message:__hash() is equivalent to message.id and is guaranteed to be unique for all messages.

Every container has a __tostring method that returns a string of the container name and the container hash. This string has the general format Name: hash.

Every container has an __eq method that allowed containers to be compared with the == operator. For two containers to be equivalent, they must be of the same type and their hashes must be identical.

The following is a list of Discord containers, their parents, and their hash properties:

Container	Parent	Hash
Ban	Guild	user.id
Emoji	Guild	id
GroupChannel	Client	id
Guild	Client	id
GuildCategoryChannel	Guild	id
GuildTextChannel	Guild	id
GuildVoiceChannel	Guild	id
Invite	Client	code
Member	Guild	user.id
Message	TextChannel	id
PermissionOverwrite	GuildChannel	id
PrivateChannel	Client	id
Reaction	Message	emojiId or emojiName
Relationship	Client	user.id
Role	Guild	id
User	Client	id
Webhook	Client	id

Iterables

Discordia uses special Iterable classes to cache and access containers. They function similarly to tables, with __len and __pairs methods, plus a variety of methods that help to find the object that you want, such as get, find, and iter.

Primary Iterables - Caches

For a variety of containers and the main client instance, there are properties that are some sort of iterable class. Caches are a special type of iterable that are used as the main storage for Discordia containers. Cache properties and the objects that they contain are updated via various gateway events.

Parent	Property	Iterable Type	Container Type
Client	guilds	Cache	Guild
Client	groupChannels	Cache	GroupChannel
Client	privateChannels	Cache	PrivateChannel
Client	users	Cache	User
Guild	categories	Cache	GuildCategoryChannel
Guild	emojis	Cache	Emoji
Guild	members	Cache	Member
Guild	roles	Cache	Role
Guild	textChannels	Cache	GuildTextChannel
Guild	voiceChannels	Cache	GuildVoiceChannel
Message	reactions	Cache	Reaction
TextChannel	permissionOverwrites	Cache	PermissionOverwrite
TextChannel	messages	WeakCache	Message

Secondary Iterables

Some other containers have properties for secondary iterables. These iterables do not store original objects; they store references to cached objects listed above. Conveniently, all iterable classes, including caches, have the same methods (and no properties), so Discordia users do not necessarily have to remember which iterable is used; remembering one set of iterable methods is sufficient. Secondary iterable properties and the objects that they reference are updated via various gateway events.

Parent	Property	Iterable Type	Container Type
GroupChannel	recipients	SecondaryCache	User
GuildTextChannel	members	FilteredIterable	Member
Message	mentionedUsers	ArrayIterable	User
Message	mentionedRoles	ArrayIterable	Role
Message	mentionedChannels	ArrayIterable	Channel
Role	members	FilteredIterable	Member
User	mutualGuilds	FilteredIterable	Guild

Static Iterables

Some objects cannot be reliably updated by gateway events alone. These objects are instead accessed by HTTP requests via class methods. Every time the methods listed below are called, they will make an HTTP request and return a new copy of an iterable and containers (if successful). Containers stored in static caches (bans, invites, webhooks) are not updated via gateway events. Containers stored in static secondary caches (messages, users) are updated via gateway events, but objects are never added to or removed from the cache via gateway events.

Parent	Method	Iterable Type	Container Type
Guild	getBans	Cache	Ban
Guild	getInvites	Cache	Invite
Guild	getWebhooks	Cache	Webhook
GuildChannel	getInvites	Cache	Invite
GuildTextChannel	getWebhooks	Cache	Webhook
Reaction	getUsers	SecondaryCache	User
TextChannel	getMessages	SecondaryCache	Message
TextChannel	getPinnedMessages	SecondaryCache	Message

Examples

Below are some examples of accessing role objects. In some cases, the following predicate is used to filter by color:

local function fn(r) return r.color > 0 end

Counting Objects

local n = #guild.roles -- count all roles
local n = guild.roles:count(fn) -- count some roles

Accessing One Object

local role = guild.roles:get('1234567890') -- get by Snowflake ID
local role = guild.roles:find(fn) -- get by predicate

Accessing Many Objects

for id, role in pairs(guild.roles) do
	print(id, role.name) -- iterate all roles
end

for role in guild.roles:iter() do
	print(role.name) -- iterate all roles
end

for role in guild.roles:findAll(fn) do
	print(role.name, role.color) -- iterate through some roles
end

local roles = roles:toArray() -- get an array of roles
local roles = roles:toArray('position') -- get a sorted array of roles
local roles = roles:toArray('position', fn) -- get a sorted, filtered array of roles

Accessing Properties in Bulk

local rows = guild.roles:select('position', 'id', 'name') -- get a sorted array of properties
local row = rows[1]
print(row[1]) -- position
print(row[2]) -- id
print(row[3]) -- name

Special Cases

There are some special cases or exceptions to the rules outlined above.

Guild Unavailability

When there is a Discord server outage, some guilds (and their child objects) may become unavailable. When this happens, Discordia guild objects may not be cached at all, may be mostly empty, or may be an old copy. In the latter two cases, guild.unavailible would be true.

Offline Members

By default, offline guild members may not be cached in Discordia. To compensate for missing members, Guild:getMember will make an HTTP request to fetch a member if it is not cached. If you do need to have all members cached, then the cacheAllMembers option must be enabled on client initialization. You can check the ratio of cached to total members by comparing the #guild.members and guild.totalMemberCount values.

Private Channels

Private channels may not be cached if they were previously closed. If you are unable to access the channel object via either Client:getChannel or other methods, use User:getPrivateMessage or the User:send shortcut.

Messages

Discordia has no cached messages on startup and will only weakly cache the most recent messages as they are received. If you want to access messages that are not cached, either use TextChannel:getMessages (and related methods) or TextChannel:getMessage, which will make an HTTP request to fetch the message if it is not cached.

Permission Overwrites

Permission overwrites are only cached if they were edited. If you want to get an overwrite for a specific role or member, use GuildChannel:getPermissionOverwriteFor. This will create a new object if one does not already exist.