Nostrum.Cache.MessageCache behaviour (nostrum v0.11.0-dev)
View SourceCache behaviour & dispatcher for Discord messages.
By default, Elixir.Nostrum.Cache.MessageCache.Noop will be used for caching
messages. You can override this in the :caches option of the nostrum
application by setting the :messages field to a different module, or
to the tuple {module, config} where module is the module to use and
config is any compile-time configuration to pass to the module.
Unlike the other caches, the default is a no-op cache, as messages take
up a lot of memory and most bots do not need messages to be cached.
If you would like to cache messages, you can change the cache implementation
to one of the provided modules under Nostrum.Cache.MessageCache
or write your own.
Writing your own message cache
As with the other caches, the message cache API consists of two parts:
The functions that nostrum calls, such as
create/1orupdate/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 byNostrum.Apiinstead.the
child_spec/1callback for starting the cache under a supervisor.
You need to implement both of them for nostrum to work with your custom cache.
Summary
Types
Used to constrain the return values of functions that can return a list of messages from the cache.
Callbacks
Deletes multiple messages from the cache, any message IDs given will always be for the same channel.
Called when a channel is deleted.
Retrieve the child spec for starting the cache under a supervisor.
Creates a message in the cache.
Deletes a message from the cache.
Retrieve a single Nostrum.Struct.Message from the cache by its ID.
Retrieve a list of messages from the cache with a given author ID, optionally after a given date, and before a given date.
Retrieves a list of messages from the cache with a given channel ID, after a given date, and before a given date.
Retrieve a list of messages from the cache with a given channel ID and author ID, optionally after a given date, and before a given date.
Updates a message in the cache.
Functions
Retrieve a message from the cache by channel and message id.
Retrieve a list of messages from the cache with a given author ID, optionally after a given date, and before a given date.
Retrieve a list of messages from the cache with a given channel ID and author ID, optionally after a given date, and before a given date.
Types
@type timestamp_like() :: Nostrum.Snowflake.t() | DateTime.t()
Used to constrain the return values of functions that can return a list of messages from the cache.
Callbacks
@callback bulk_delete(Nostrum.Struct.Channel.id(), [Nostrum.Struct.Message.id()]) :: [ Nostrum.Struct.Message.t() ]
Deletes multiple messages from the cache, any message IDs given will always be for the same channel.
Returns a list of the deleted messages. Note that if a message was not found in the cache, it will not be included in the returned list.
@callback channel_delete(Nostrum.Struct.Channel.id()) :: :ok
Called when a channel is deleted.
Any messages in the cache for the channel should be removed.
@callback child_spec(term()) :: Supervisor.child_spec()
Retrieve the child spec for starting the cache under a supervisor.
This callback is optional, and if not implemented, the cache will not be started under a supervisor.
@callback create(map()) :: Nostrum.Struct.Message.t()
Creates a message in the cache.
The argument given is the raw message payload from Discord's gateway.
@callback delete(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) :: Nostrum.Struct.Message.t() | nil
Deletes a message from the cache.
Expects the deleted message to be returned if it was found.
@callback get(Nostrum.Struct.Message.id()) :: {:ok, Nostrum.Struct.Message.t()} | {:error, :not_found}
Retrieve a single Nostrum.Struct.Message from the cache by its ID.
@callback get_by_author( Nostrum.Struct.User.id(), after_timestamp :: timestamp_like(), before_timestamp :: timestamp_like() | :infinity ) :: [Nostrum.Struct.Message.t()]
Retrieve a list of messages from the cache with a given author ID, optionally after a given date, and before a given date.
Integers are treated as snowflakes, and the atom :infinity when given
as a before date will be treated as the maximum possible date.
@callback get_by_channel( Nostrum.Struct.Channel.id(), after_timestamp :: timestamp_like(), before_timestamp :: timestamp_like() | :infinity ) :: [Nostrum.Struct.Message.t()]
Retrieves a list of messages from the cache with a given channel ID, after a given date, and before a given date.
Integers should be treated as snowflakes, and the atom :infinity when given
as a before date should be treated as the maximum possible date.
@callback get_by_channel_and_author( Nostrum.Struct.Channel.id(), Nostrum.Struct.User.id(), after_timestamp :: timestamp_like(), before_timestamp :: timestamp_like() | :infinity ) :: [Nostrum.Struct.Message.t()]
Retrieve a list of messages from the cache with a given channel ID and author ID, optionally after a given date, and before a given date.
@callback update(map()) :: {old_message :: Nostrum.Struct.Message.t() | nil, updated_message :: Nostrum.Struct.Message.t()}
Updates a message in the cache.
The argument given is the raw message payload from Discord's gateway,
and the return value is a tuple of the updated message and the old message if
it was found in the cache, otherwise nil.
Functions
Retrieve a message from the cache by channel and message id.
Retrieve a list of messages from the cache with a given author ID, optionally after a given date, and before a given date.
Integers are treated as snowflakes, and the atom :infinity when given
as a before date will be treated as the maximum possible date.
Retrieve a list of messages from the cache with a given channel ID and author ID, optionally after a given date, and before a given date.