View Source Nostrum.Cache.MemberCache behaviour (Nostrum v0.7.0)

Cache behaviour & dispatcher for guild members.

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.MemberCache.ETS will be used for caching members. You can override this in the :caches option of the :nostrum application by setting the :members field to a different module implementing the behaviour defined by this module.

See the documentation for the Nostrum.Cache.GuildCache module for more details on how to implement your own.

Link to this section Summary

Callbacks

Bulk create multiple members in the cache from upstream data.

Get all members cached for the given user ID.

Add the member for the given guild from upstream data.

Remove the given user for the given guild.

Get members for a given guild ID.

Get a single member on the given guild ID.

Return a query handle for usage with :qlc.

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

Link to this section Callbacks

Link to this callback

bulk_create(id, members)

View Source (since 0.7.0)
@callback bulk_create(Nostrum.Struct.Guild.id(), members :: [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

by_user(user_id)

View Source (since 0.7.0)

Get all members cached for the given user ID.

The members will be returned alongside their guild ID as a pair in the format {guild_id, member}.

The result is returned as a stream.

Link to this callback

create(id, member)

View Source (since 0.7.0)
@callback create(Nostrum.Struct.Guild.id(), member :: map()) ::
  Nostrum.Struct.Guild.Member.t()

Add the member for the given guild from upstream data.

Return the casted member structure.

Link to this callback

delete(id, user)

View Source (since 0.7.0)
@callback delete(Nostrum.Struct.Guild.id(), user :: map()) ::
  {Nostrum.Struct.Guild.id(), old_member :: Nostrum.Struct.Guild.Member.t()}
  | :noop

Remove the given user for the given guild.

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

Get members for a given guild ID.

The result is returned as a stream to accomodate for large guilds.

Link to this callback

get(id, user_id)

View Source (since 0.7.0)

Get a single member on the given guild ID.

The result should be returned as a stream to accomodate for large guilds.

Link to this callback

qlc_handle()

View Source (since 0.7.0)
@callback qlc_handle() :: :qlc.query_handle()

Return a query handle for usage with :qlc.

This is used by nostrum to provide automatic joins between the member and the user cache, and may be used for other functions in the future.

The Erlang manual on Implementing a QLC Table contains examples for implementation.

The query handle must return items in the form {guild_id, user_id, member}, where:

Link to this callback

update(id, member)

View Source (since 0.7.0)
@callback 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

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 issue predates the modern nostrum caching infrastructure.

Link to this section Functions

Link to this function

by_user(member_id)

View Source (since 0.7.0)

See Nostrum.Cache.MemberCache.ETS.by_user/1.

Link to this function

get(guild_id)

View Source (since 0.7.0)

See Nostrum.Cache.MemberCache.ETS.get/1.

Link to this function

get(guild_id, member_id)

View Source (since 0.7.0)

See Nostrum.Cache.MemberCache.ETS.get/2.

Link to this function

get_with_user(guild_id, member_id)

View Source (since 0.7.0)

Return a member together with its user via the user cache.

Link to this function

get_with_users(guild_id)

View Source (since 0.7.0)

Return an enumerable of members with their users.

parameters

Parameters

return-value

Return value

Returns an enumerable that can be consumed with any function in the Stream or Enumerable module.

If the user for a guild member is not found, the member and user won't be present in the result. Barring a bug in nostrum's caching, this should never happen in practice.