Cache

Caching system for Discord entities with configurable policies and flags

The cache package provides a flexible, thread-safe caching system for Discord entities. It supports granular control over what gets cached using flags and policies.

Core interfaces

Cache

Thread-safe key-value store for Discord entities.

type Cache[T any] interface {
    Get(id snowflake.ID) (T, bool)
    Put(id snowflake.ID, entity T)
    Remove(id snowflake.ID) (T, bool)
    RemoveIf(filterFunc FilterFunc[T])
    Len() int
    All() iter.Seq[T]
}

T · any

The entity type to cache (e.g., discord.Guild, discord.Message)

Methods

Get(id) · (T, bool)

Returns a copy of the entity with the given ID and whether it was found

Put(id, entity) · void

Stores the entity with the given ID. Overwrites if already present

Remove(id) · (T, bool)

Removes and returns the entity with the given ID

RemoveIf(filterFunc) · void

Removes all entities that pass the filter function

Len() · int

Returns the number of entities in the cache

All() · iter.Seq[T]

Returns an iterator over all entities in the cache

GroupedCache

Cache for entities grouped by a parent ID (e.g., roles grouped by guild).

type GroupedCache[T any] interface {
    Get(groupID snowflake.ID, id snowflake.ID) (T, bool)
    Put(groupID snowflake.ID, id snowflake.ID, entity T)
    Remove(groupID snowflake.ID, id snowflake.ID) (T, bool)
    GroupRemove(groupID snowflake.ID)
    RemoveIf(filterFunc GroupedFilterFunc[T])
    GroupRemoveIf(groupID snowflake.ID, filterFunc GroupedFilterFunc[T])
    Len() int
    GroupLen(groupID snowflake.ID) int
    All() iter.Seq2[snowflake.ID, T]
    GroupAll(groupID snowflake.ID) iter.Seq[T]
}

groupID · snowflake.ID

The parent entity ID (e.g., guild ID for roles)

Methods

Get(groupID, id) · (T, bool)

Returns the entity within the specified group

GroupRemove(groupID) · void

Removes all entities in the specified group

GroupLen(groupID) · int

Returns the number of entities in the specified group

GroupAll(groupID) · iter.Seq[T]

Returns an iterator over all entities in the specified group

Caches

Combines all entity-specific caches into a unified interface.

type Caches interface {
    SelfUserCache
    GuildCache
    ChannelCache
    RoleCache
    MemberCache
    MessageCache
    // ... and more
    
    CacheFlags() Flags
    MemberPermissions(member discord.Member) discord.Permissions
    MemberPermissionsInChannel(channel discord.GuildChannel, member discord.Member) discord.Permissions
}

Utility methods

MemberPermissions(member) · discord.Permissions

Calculates the permissions of the member in their guild. Requires FlagRoles to be set

MemberPermissionsInChannel(channel, member) · discord.Permissions

Calculates the permissions of the member in a specific channel. Requires FlagRoles and FlagChannels

MemberRoles(member) · []discord.Role

Returns all roles of the member. Requires FlagRoles

AudioChannelMembers(channel) · []discord.Member

Returns all members in the audio channel. Requires FlagVoiceStates

SelfMember(guildID) · (discord.Member, bool)

Returns the bot’s member object in the specified guild

Cache flags

Control which entities are cached using bitwise flags.

type Flags int

const (
    FlagGuilds                Flags = 1 << iota
    FlagGuildScheduledEvents
    FlagMembers
    FlagThreadMembers
    FlagMessages
    FlagPresences
    FlagChannels
    FlagRoles
    FlagEmojis
    FlagStickers
    FlagVoiceStates
    FlagStageInstances
    FlagGuildSoundboardSounds
    
    FlagsNone Flags = 0
    FlagsAll        = FlagGuilds | FlagGuildScheduledEvents | ...
)

Flag operations

Add(bits...) · Flags

Adds the specified flags

Remove(bits...) · Flags

Removes the specified flags

Has(bits...) · bool

Checks if all specified flags are present

Missing(bits...) · bool

Checks if any specified flags are missing

Usage example

// Enable only guilds, channels, and roles
flags := cache.FlagGuilds.Add(cache.FlagChannels, cache.FlagRoles)

// Check if messages are cached
if flags.Has(cache.FlagMessages) {
    // Handle messages
}

Cache policies

Define custom rules for which entities to cache using policy functions.

type Policy[T any] func(entity T) bool

Built-in policies

PolicyAll[T] · Policy[T]

Caches all entities (default)

PolicyNone[T] · Policy[T]

Caches no entities

PolicyMembersInclude(guildIDs) · Policy[discord.Member]

Caches members only from the specified guilds

PolicyMembersPending · Policy[discord.Member]

Caches only members that are pending (haven’t completed membership screening)

PolicyMembersInVoice(caches) · Policy[discord.Member]

Caches only members that are connected to a voice channel

PolicyChannelInclude(types) · Policy[discord.Channel]

Caches only channels of the specified types

PolicyChannelExclude(types) · Policy[discord.Channel]

Caches all channels except the specified types

Combining policies

Policies can be combined using logical operations:

// Cache members that are pending OR in voice
policy := cache.PolicyMembersPending.Or(
    cache.PolicyMembersInVoice(caches),
)

// Cache only text channels in specific guilds
policy := cache.PolicyChannelInclude(discord.ChannelTypeGuildText).And(
    func(ch discord.Channel) bool {
        return ch.GuildID() == myGuildID
    },
)

Or(policy) · Policy[T]

Returns a policy that passes if either policy passes

And(policy) · Policy[T]

Returns a policy that passes only if both policies pass

AnyPolicy(policies...) · Policy[T]

Returns a policy that passes if any of the policies pass

AllPolicies(policies...) · Policy[T]

Returns a policy that passes only if all policies pass

Configuration

Configure caches using the New function and config options.

func New(opts ...ConfigOpt) Caches

Config options

WithCaches(flags) · ConfigOpt

Sets which entity types to cache

WithGuildCachePolicy(policy) · ConfigOpt

Sets the policy for caching guilds

WithMemberCachePolicy(policy) · ConfigOpt

Sets the policy for caching members

WithMessageCachePolicy(policy) · ConfigOpt

Sets the policy for caching messages

WithChannelCachePolicy(policy) · ConfigOpt

Sets the policy for caching channels

WithRoleCachePolicy(policy) · ConfigOpt

Sets the policy for caching roles

WithPresenceCachePolicy(policy) · ConfigOpt

Sets the policy for caching user presences

WithVoiceStateCachePolicy(policy) · ConfigOpt

Sets the policy for caching voice states

Additional config options available for: emojis, stickers, stage instances, scheduled events, thread members, and soundboard sounds.

Entity-specific caches

Each entity type has a dedicated cache interface:

GuildCache

type GuildCache interface {
    Guild(guildID snowflake.ID) (discord.Guild, bool)
    Guilds() iter.Seq[discord.Guild]
    GuildsLen() int
    AddGuild(guild discord.Guild)
    RemoveGuild(guildID snowflake.ID) (discord.Guild, bool)
    
    IsGuildUnready(guildID snowflake.ID) bool
    IsGuildUnavailable(guildID snowflake.ID) bool
}

ChannelCache

type ChannelCache interface {
    Channel(channelID snowflake.ID) (discord.GuildChannel, bool)
    Channels() iter.Seq[discord.GuildChannel]
    ChannelsForGuild(guildID snowflake.ID) iter.Seq[discord.GuildChannel]
    ChannelsLen() int
    AddChannel(channel discord.GuildChannel)
    RemoveChannel(channelID snowflake.ID) (discord.GuildChannel, bool)
    RemoveChannelsByGuildID(guildID snowflake.ID)
}

MemberCache

type MemberCache interface {
    Member(guildID snowflake.ID, userID snowflake.ID) (discord.Member, bool)
    Members(guildID snowflake.ID) iter.Seq[discord.Member]
    MembersLen(guildID snowflake.ID) int
    AddMember(member discord.Member)
    RemoveMember(guildID snowflake.ID, userID snowflake.ID) (discord.Member, bool)
    RemoveMembersByGuildID(guildID snowflake.ID)
}

MessageCache

type MessageCache interface {
    Message(channelID snowflake.ID, messageID snowflake.ID) (discord.Message, bool)
    Messages(channelID snowflake.ID) iter.Seq[discord.Message]
    MessagesLen(channelID snowflake.ID) int
    AddMessage(message discord.Message)
    RemoveMessage(channelID snowflake.ID, messageID snowflake.ID) (discord.Message, bool)
    RemoveMessagesByChannelID(channelID snowflake.ID)
}

Similar interfaces exist for: roles, emojis, stickers, voice states, presences, scheduled events, stage instances, thread members, and soundboard sounds.

Usage example

package main

import (
    "github.com/disgoorg/disgo/cache"
    "github.com/disgoorg/disgo/discord"
)

func main() {
    // Create caches with specific flags and policies
    caches := cache.New(
        // Only cache guilds, channels, roles, and members
        cache.WithCaches(
            cache.FlagGuilds,
            cache.FlagChannels,
            cache.FlagRoles,
            cache.FlagMembers,
        ),
        // Only cache members from specific guilds
        cache.WithMemberCachePolicy(
            cache.PolicyMembersInclude(guildID1, guildID2),
        ),
        // Don't cache DM channels
        cache.WithChannelCachePolicy(
            cache.PolicyChannelExclude(discord.ChannelTypeDM),
        ),
    )
    
    // Use with bot client
    client, _ := disgo.New(token,
        bot.WithCaches(caches),
    )
    
    // Access cached data
    if guild, ok := caches.Guild(guildID); ok {
        fmt.Printf("Guild: %s\n", guild.Name)
    }
    
    // Calculate permissions
    if member, ok := caches.Member(guildID, userID); ok {
        perms := caches.MemberPermissions(member)
        if perms.Has(discord.PermissionAdministrator) {
            fmt.Println("User is an administrator")
        }
    }
}