Nostrum.Cache.MemberCache behaviour (nostrum v0.11.0-dev)
View SourceCache 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.
The user-facing functions of this module can be called with a custom cache as the final argument. This is mainly useful if you want to test the cache: by default, nostrum will use Elixir.Nostrum.Cache.MemberCache.ETS.
In order to use this cache, you must enable the :guild_members intent, and you must also enable the request_guild_members: true configuration option.
Summary
Callbacks
Bulk create multiple members in the cache from upstream data.
Yield an enumerable of members associated with the given guild ID.
Yield an enumerable of {guild_id, member} pairs associated with the given user ID.
Retrieve the child specification for starting this mapping under a supervisor.
Add the member for the given guild from upstream data.
Remove the given user for the given guild.
Retrieve a member from the cache by guild and user ID.
Update the given member for the given guild from upstream data.
A function that should wrap any long-running query operations.
Functions
Fold (reduce) over members for the given guild ID.
Reduce over all members cached for the given user ID.
Calls fun on each member and its user on the given guild ID, with the given
accumulator.
Get a single member on the given guild ID.
Return a member together with its user via the user cache.
Call wrap_query/1 on the given cache, if implemented.
Callbacks
@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.
@callback by_guild(Nostrum.Struct.Guild.id()) :: Enumerable.t(Nostrum.Struct.Guild.Member.t())
Yield an enumerable of members associated with the given guild ID.
@callback by_user(Nostrum.Struct.User.id()) :: Enumerable.t({Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.t()})
Yield an enumerable of {guild_id, member} pairs associated with the given user ID.
Since nostrum does not know when it can stop streaming you results, you have
to wrap calls to this function in wrap_query/1.
@callback child_spec(term()) :: Supervisor.child_spec()
Retrieve the child specification for starting this mapping under a supervisor.
@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.
@callback delete(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.user_id()) :: {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.
@callback get(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.user_id()) :: {:ok, Nostrum.Struct.Guild.Member.t()} | {:error, atom()}
Retrieve a member from the cache by guild and user ID.
@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
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.
@callback wrap_query((-> result)) :: result when result: term()
A function that should wrap any long-running query operations.
If you implement a cache that is backed by a database and want to perform
cleanup and teardown actions such as opening and closing connections,
managing transactions and so on, you want to implement this function. nostrum
will then effectively call wrap_query(fn -> ... end).
If your cache does not need any wrapping, you can omit this.
Functions
@spec fold( acc, Nostrum.Struct.Guild.id(), (Nostrum.Struct.Guild.Member.t(), acc -> acc), module() ) :: acc when acc: term()
Fold (reduce) over members for the given guild ID.
Parameters
acc: The initial accumulator. Also returned if no guild members were found.guild_id: The guild for which to reduce members.member_reducer: Called for every element in the result. Takes a pair in the form(member, acc), and must return the updated accumulator.
Return value
Returns the resulting accumulator via fun. Returns acc unchanged if no
results were found.
Raises
Fails when by_guild/1 of the selected cache returns an error.
@spec fold_by_user( acc, Nostrum.Struct.Guild.Member.user_id(), ({Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.t()}, acc -> acc), module() ) :: acc when acc: term()
Reduce over 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}.
Raises
Fails when by_user/1 of the selected cache returns an error.
@spec fold_with_users( acc, Nostrum.Struct.Guild.id(), ({Nostrum.Struct.Guild.Member.t(), Nostrum.Struct.User.t()}, acc -> acc), module() ) :: acc when acc: term()
Calls fun on each member and its user on the given guild ID, with the given
accumulator.
Parameters
acc(term()): The initial accumulator. Also returned if no guild members were found.guild_id(Nostrum.Struct.Guild.id/0): The guild for which to reduce members.fun(function()): Called for every element in the result. Takes a pair in the form({member, user}, acc), and must return the updated accumulator.
Return value
Returns the resulting accumulator via fun. Returns acc unchanged if no
results were found.
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.
Raises
Fails when by_guild/1 of the selected cache returns an error.
@spec get(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.user_id()) :: {:ok, Nostrum.Struct.Guild.Member.t()} | {:error, atom()}
Get a single member on the given guild ID.
@spec get_with_user( Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.user_id(), module() ) :: {Nostrum.Struct.Guild.Member.t(), Nostrum.Struct.User.t() | nil} | nil
Return a member together with its user via the user cache.
Call wrap_query/1 on the given cache, if implemented.
If no cache is given, calls out to the default cache.