Cache

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

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]
}

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")
        }
    }
}

Core Packages

Features

Extensions

Cache

Core interfaces

Cache

Methods

GroupedCache

Methods

Caches

Utility methods

Cache flags

Flag operations

Usage example

Cache policies

Built-in policies

Combining policies

Configuration

Config options

Entity-specific caches

GuildCache

ChannelCache

MemberCache

MessageCache

Usage example

Build docs developers (and LLMs) love

Core Packages

Features

Extensions

Documentation Index

​Core interfaces

​Cache

​Methods

​GroupedCache

​Methods

​Caches

​Utility methods

​Cache flags

​Flag operations

​Usage example

​Cache policies

​Built-in policies

​Combining policies

​Configuration

​Config options

​Entity-specific caches

​GuildCache

​ChannelCache

​MemberCache

​MessageCache

​Usage example

Build docs developers (and LLMs) love

Core interfaces

Cache

Methods

GroupedCache

Methods

Caches

Utility methods

Cache flags

Flag operations

Usage example

Cache policies

Built-in policies

Combining policies

Configuration

Config options

Entity-specific caches

GuildCache

ChannelCache

MemberCache

MessageCache

Usage example