View Source Nostrum.Cache.MessageCache behaviour (Nostrum v0.10.0)

Cache 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/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.
the child_spec/1 callback for starting the cache under a supervisor.

You need to implement both of them for nostrum to work with your custom cache.

Summary

Types

timestamp_like()

Used to constrain the return values of functions that can return a list of messages from the cache.

Callbacks

bulk_delete(id, list)

Deletes multiple messages from the cache, any message IDs given will always be for the same channel.

channel_delete(id)

Called when a channel is deleted.

child_spec(term)

Retrieve the child spec for starting the cache under a supervisor.

create(map)

Creates a message in the cache.

delete(id, id)

Deletes a message from the cache.

get(id)

Retrieve a single Nostrum.Struct.Message from the cache by its ID.

get_by_author(id, after_timestamp, before_timestamp)

Retrieve a list of messages from the cache with a given author ID, optionally after a given date, and before a given date.

get_by_channel(id, after_timestamp, before_timestamp)

Retrieves a list of messages from the cache with a given channel ID, after a given date, and before a given date.

get_by_channel_and_author(id, id, after_timestamp, before_timestamp)

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.

update(map)

Updates a message in the cache.

Functions

get(message_id)

Retrieve a message from the cache by channel and message id.

get_by_author(user_id, after_timestamp \\ 0, before_timestamp \\ :infinity)

Retrieve a list of messages from the cache with a given author ID, optionally after a given date, and before a given date.

get_by_channel_and_author(channel_id, author_id, after_timestamp \\ 0, before_timestamp \\ :infinity)

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

timestamp_like()

(since 0.10.0)

@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

bulk_delete(id, list)

(since 0.10.0)

@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.

channel_delete(id)

(since 0.10.0)

@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.

child_spec(term)

(since 0.10.0)

@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.

create(map)

(since 0.10.0)

@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.

delete(id, id)

(since 0.10.0)

@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.

get(id)

(since 0.10.0)

@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.

get_by_author(id, after_timestamp, before_timestamp)

(since 0.10.0)

@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.

get_by_channel(id, after_timestamp, before_timestamp)

(since 0.10.0)

@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.

get_by_channel_and_author(id, id, after_timestamp, before_timestamp)

(since 0.10.0)

@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.

update(map)

(since 0.10.0)

@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

get(message_id)

(since 0.10.0)

Retrieve a message from the cache by channel and message id.

get_by_author(user_id, after_timestamp \\ 0, before_timestamp \\ :infinity)

(since 0.10.0)

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.

get_by_channel_and_author(channel_id, author_id, after_timestamp \\ 0, before_timestamp \\ :infinity)

(since 0.10.0)

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.