View Source Nostrum.Cache.GuildCache behaviour (Nostrum v0.6.1)

Cache behaviour & dispatcher for guilds.

You can call the functions provided by this module independent of which cache is configured, and it will dispatch to the configured cache implementation.

By default, Elixir.Nostrum.Cache.GuildCache.ETS will be used for caching guilds. You can override this in the :caches option of the :nostrum application by setting the :guilds field to a different module implementing the Nostrum.Cache.GuildCache behaviour. Any module below Nostrum.Cache.GuildCache can be used as a cache.

Writing your own guild cache

As with the other caches, the guild cache API consists of two parts:

  • The functions that the user calls, such as all/0 or select_by/2.

  • The functions that nostrum calls, such as create/1 or update/1. These do not create any objects in the Discord API, they are purely created to update the cached data from data that Discord sends us. If you want to create objects on Discord, use the functions exposed by Nostrum.Api instead.

You need to implement both of them for nostrum to work with your custom cache. You also need to implement Supervisor callbacks, which will start your cache as a child under Nostrum.Cache.CacheSupervisor: As an example, the Nostrum.Cache.GuildCache.ETS implementation uses this to to set up its ETS table it uses for caching. See the callbacks section for every nostrum-related callback you need to implement.

Note that this module also defines a few helper functions, such as get!/1 or select_by!/2, which call the backing cache's regular functions and perform the result unwrapping by themselves.

The "upstream data" wording in this module references the fact that the data that the guild cache (and other caches) retrieves represents the raw data we receive from the upstream connection, no attempt is made by nostrum to sanitize the data before it enters the cache. Caching implementations need to cast the data to the resulting type themselves. A possible future improvement would be moving the data casting into this module before the backing cache implementation is called.

Link to this section Summary

Types

A clause for filtering guilds.

A collection of clause/0s for filtering guilds.

Specifies the reason for why a lookup operation has failed.

A selector for looking up entries in the cache.

Callbacks

Retrieves all Nostrum.Struct.Guild from the cache.

Create a channel for the guild from upstream data.

Delete the given channel from the guild.

Update the given channel on the given guild from upstream data.

Create a guild in the cache.

Delete a guild from the cache.

Update the emoji list of the given guild from upstream data.

Retrieves a single Nostrum.Struct.Guild from the cache via its id.

Retrieves a single Nostrum.Struct.Guild where it matches the clauses.

Add the member for the given guild from upstream data.

Bulk create multiple members in the cache from upstream data.

Remove the given member for the given guild from upstream data.

Update the given member for the given guild from upstream data.

Create a role on the given guild from upstream data.

Delete the given role on the given guild.

Update a role on the given guild from upstream data.

Selects values using a selector from a Nostrum.Struct.Guild.

Selects guilds matching selector from all Nostrum.Struct.Guild in the cache.

Selects values using a selector from a Nostrum.Struct.Guild that matches the clauses.

Update a guild from upstream data.

Update the voice state of the given guild from upstream data.

Link to this section Types

Specs

clause() ::
  {:id, Nostrum.Struct.Guild.id()}
  | {:channel_id, Nostrum.Struct.Channel.id()}
  | {:message, Nostrum.Struct.Message.t()}

A clause for filtering guilds.

Specs

clauses() :: [clause()] | map()

A collection of clause/0s for filtering guilds.

Specs

reason() :: :id_not_found | :id_not_found_on_guild_lookup

Specifies the reason for why a lookup operation has failed.

Specs

selector() :: (Nostrum.Struct.Guild.t() -> any())

A selector for looking up entries in the cache.

Link to this section Callbacks

Specs

all() :: Enum.t()

Retrieves all Nostrum.Struct.Guild from the cache.

Link to this callback

channel_create(id, channel)

View Source

Specs

channel_create(Nostrum.Struct.Guild.id(), channel :: map()) ::
  Nostrum.Struct.Channel.t()

Create a channel for the guild from upstream data.

Return the adapted Nostrum.Struct.Channel.t/0 structure.

Specs

Delete the given channel from the guild.

If the channel was cached, return the original channel. Return :noop otherwise.

Link to this callback

channel_update(id, channel)

View Source

Specs

channel_update(Nostrum.Struct.Guild.id(), channel :: map()) ::
  {old_channel :: Nostrum.Struct.Channel.t(),
   new_channel :: Nostrum.Struct.Channel.t()}

Update the given channel on the given guild from upstream data.

Return the original channel before the update, and the updated channel.

Specs

create(Nostrum.Struct.Guild.t()) :: true

Create a guild in the cache.

Specs

Delete a guild from the cache.

Return the old guild if it was cached, or nil otherwise.

Link to this callback

emoji_update(id, emojis)

View Source

Specs

emoji_update(Nostrum.Struct.Guild.id(), emojis :: [map()]) ::
  {old_emojis :: [Nostrum.Struct.Emoji.t()],
   new_emojis :: [Nostrum.Struct.Emoji.t()]}

Update the emoji list of the given guild from upstream data.

Discord sends us the complete emoji list on an update, which is passed here.

Return the old list of emojis before the update, and the updated list of emojis.

Specs

get(Nostrum.Struct.Guild.id()) ::
  {:ok, Nostrum.Struct.Guild.t()} | {:error, reason()}

Retrieves a single Nostrum.Struct.Guild from the cache via its id.

Returns {:error, reason} if no result was found.

Examples

iex> Nostrum.Cache.GuildCache.get(0)
{:ok, %Nostrum.Struct.Guild{id: 0}}

iex> Nostrum.Cache.GuildCache.get(10)
{:error, :id_not_found_on_guild_lookup}

Specs

get_by(clauses()) :: {:ok, Nostrum.Struct.Guild.t()} | {:error, reason()}

Retrieves a single Nostrum.Struct.Guild where it matches the clauses.

Returns {:error, reason} if no result was found.

iex> Nostrum.Cache.GuildCache.get_by(id: 0)
{:ok, %Nostrum.Struct.Guild{id: 0}}

iex> Nostrum.Cache.GuildCache.get_by(%{id: 0})
{:ok, %Nostrum.Struct.Guild{id: 0}}

iex> Nostrum.Cache.GuildCache.get_by(id: 10)
{:error, :id_not_found_on_guild_lookup}

Specs

Add the member for the given guild from upstream data.

Return the casted member structure.

Specs

member_chunk(Nostrum.Struct.Guild.id(), chunk :: [member :: map()]) :: true

Bulk create multiple members in the cache from upstream data.

Return value is unused, as we currently do not dispatch a gateway for this.

Link to this callback

member_remove(id, member)

View Source

Specs

member_remove(Nostrum.Struct.Guild.id(), member :: map()) ::
  {Nostrum.Struct.Guild.id(), old_member :: Nostrum.Struct.Guild.Member.t()}
  | :noop

Remove the given member for the given guild from upstream data.

Return the guild ID and old member if the member was cached. Otherwise, return :noop.

Link to this callback

member_update(id, member)

View Source

Specs

member_update(Nostrum.Struct.Guild.id(), member :: map()) ::
  {Nostrum.Struct.Guild.id(),
   old_member :: Nostrum.Struct.Guild.Member.t() | nil,
   updated_member :: Nostrum.Struct.Guild.Member.t()}

Update the given member for the given guild from upstream data.

Return the guild ID that was updated, the old cached member (if the member was known to the cache), and the updated member.

Note regarding intents

Even if the required intents to receive GUILD_MEMBER_UPDATE events are disabled to a point where we do not receive guild creation events, it is still possible to receive the event for our own user. An example of this can be found in issue #293. Note that the linked issue refers to the old contents of this module before the ETS-based guild cache was moved into Elixir.Nostrum.Cache.GuildCache.ETS.

Specs

role_create(Nostrum.Struct.Guild.id(), role :: map()) ::
  {Nostrum.Struct.Guild.id(), new_role :: Nostrum.Struct.Guild.Role.t()}

Create a role on the given guild from upstream data.

Return the casted role.

Specs

Delete the given role on the given guild.

Return the guild and the old role if it was cached, or :noop otherwise.

Specs

role_update(Nostrum.Struct.Guild.id(), role :: map()) ::
  {Nostrum.Struct.Guild.id(), old_role :: Nostrum.Struct.Guild.Role.t(),
   new_role :: Nostrum.Struct.Guild.Role.t()}

Update a role on the given guild from upstream data.

Return the old role before the update and the updated role.

Specs

select(Nostrum.Struct.Guild.id(), selector()) ::
  {:ok, any()} | {:error, reason()}

Selects values using a selector from a Nostrum.Struct.Guild.

Returns {:error, reason} if no result was found.

Examples

iex> Nostrum.Cache.GuildCache.select(0, fn guild -> guild.id end)
{:ok, 0}

iex> Nostrum.Cache.GuildCache.select(10, fn guild -> guild.id end)
{:error, :id_not_found_on_guild_lookup}

Specs

select_all(selector :: (Nostrum.Struct.Guild.t() -> any())) :: Enum.t()

Selects guilds matching selector from all Nostrum.Struct.Guild in the cache.

Link to this callback

select_by(clauses, selector)

View Source

Specs

select_by(clauses(), selector()) :: {:ok, any()} | {:error, reason()}

Selects values using a selector from a Nostrum.Struct.Guild that matches the clauses.

Returns {:error, reason} if no result was found.

iex> Nostrum.Cache.GuildCache.select_by([id: 0], fn guild -> guild.id end)
{:ok, 0}

iex> Nostrum.Cache.GuildCache.select_by(%{id: 0}, fn guild -> guild.id end)
{:ok, 0}

iex> Nostrum.Cache.GuildCache.select_by([id: 10], fn guild -> guild.id end)
{:error, :id_not_found_on_guild_lookup}

Specs

update(map()) ::
  {old_guild :: Nostrum.Struct.Guild.t(),
   updated_guild :: Nostrum.Struct.Guild.t()}

Update a guild from upstream data.

Return the original guild before the update, and the updated guild.

Link to this callback

voice_state_update(id, state)

View Source

Specs

voice_state_update(Nostrum.Struct.Guild.id(), state :: map()) ::
  {Nostrum.Struct.Guild.id(), new_state :: [map()]}

Update the voice state of the given guild from upstream data.

Note that it is recommended to drop the :member / "member" keys of the supplied upstream data, as these would otherwise duplicate the data that is being kept in the guild cache already.

Return the guild ID and the updated voice states of the guild.

Link to this section Functions