@callback all() :: Enumerable.t(Nostrum.Struct.Guild.t())

Return an enumerable for all guilds in the cache.

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

@callback channel_delete(Nostrum.Struct.Guild.id(), Nostrum.Struct.Channel.id()) ::
  Nostrum.Struct.Channel.t() | :noop

Delete the given channel from the guild.

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

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

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

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

@callback child_spec(term()) :: Supervisor.child_spec()

Retrieve the child specification for starting this mapping under a supervisor.

@callback create(map()) :: Nostrum.Struct.Guild.t()

Create a guild in the cache.

@callback delete(Nostrum.Struct.Guild.id()) :: Nostrum.Struct.Guild.t() | nil

Delete a guild from the cache.

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

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

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

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

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

@callback member_count_down(Nostrum.Struct.Guild.id()) :: true

Decrement the member count for this guild by one.

@callback member_count_up(Nostrum.Struct.Guild.id()) :: true

Increment the member count for this guild by one.

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

@callback role_delete(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id()) ::
  {Nostrum.Struct.Guild.id(), old_role :: Nostrum.Struct.Guild.Role.t()} | :noop

Delete the given role on the given guild.

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

@callback role_update(Nostrum.Struct.Guild.id(), role :: map()) ::
  {Nostrum.Struct.Guild.id(), old_role :: Nostrum.Struct.Guild.Role.t() | nil,
   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.

@callback stickers_update(Nostrum.Struct.Guild.id(), stickers :: [map()]) ::
  {old_stickers :: [Nostrum.Struct.Sticker.t()],
   new_stickers :: [Nostrum.Struct.Sticker.t()]}

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

Discord sends us a complete list of stickers on an update, which is passed here.

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

@callback update(map()) ::
  {old_guild :: Nostrum.Struct.Guild.t() | nil,
   updated_guild :: Nostrum.Struct.Guild.t()}

Update a guild from upstream data.

Return the original guild before the update (if it was cached) and the updated guild.

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

@callback wrap_query((-> result)) :: result when result: term()

A function that should wrap any queries.

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.