@wolfstar/plugin-cache 0.0.0

package/dist/esm/index.js

@@ -0,0 +1,1436 @@
+import { GatewayDispatchEvents } from "discord-api-types/v10";
+import { promisify } from "node:util";
+import { brotliCompress, brotliDecompress, gunzip, gzip } from "node:zlib";
+
+//#region src/lib/keys.ts
+/**
+* Creates a stable key for a guild-scoped entity.
+*/
+function guildScopedKey(guildId, id) {
+	return `${guildId}:${id}`;
+}
+/**
+* Creates a stable key for a channel message.
+*/
+function messageKey(channelId, messageId) {
+	return `${channelId}:${messageId}`;
+}
+/**
+* Creates a stable key for a guild member.
+*/
+function memberKey(guildId, userId) {
+	return guildScopedKey(guildId, userId);
+}
+/**
+* Creates a stable key for a guild presence.
+*/
+function presenceKey(guildId, userId) {
+	return guildScopedKey(guildId, userId);
+}
+/**
+* Creates a stable key for a guild voice state.
+*/
+function voiceStateKey(guildId, userId) {
+	return guildScopedKey(guildId, userId);
+}
+/**
+* Creates a stable key for a guild role.
+*/
+function roleKey(guildId, roleId) {
+	return guildScopedKey(guildId, roleId);
+}
+/**
+* Creates a stable key for a guild emoji.
+*/
+function emojiKey(guildId, emojiId) {
+	return guildScopedKey(guildId, emojiId);
+}
+/**
+* Creates a stable key for a guild sticker.
+*/
+function stickerKey(guildId, stickerId) {
+	return guildScopedKey(guildId, stickerId);
+}
+/**
+* Creates a stable key for a guild scheduled event.
+*/
+function scheduledEventKey(guildId, scheduledEventId) {
+	return guildScopedKey(guildId, scheduledEventId);
+}
+/**
+* Creates a stable key for a stage instance.
+*/
+function stageInstanceKey(guildId, channelId) {
+	return guildScopedKey(guildId, channelId);
+}
+/**
+* Creates a stable key for a guild soundboard sound.
+*/
+function soundboardSoundKey(guildId, soundId) {
+	return guildScopedKey(guildId, soundId);
+}
+/**
+* Creates a stable key for a guild auto moderation rule.
+*/
+function autoModerationRuleKey(guildId, ruleId) {
+	return guildScopedKey(guildId, ruleId);
+}
+/**
+* Creates a stable key for a guild ban.
+*/
+function banKey(guildId, userId) {
+	return guildScopedKey(guildId, userId);
+}
+/**
+* Creates a stable key for a guild integration.
+*/
+function integrationKey(guildId, integrationId) {
+	return guildScopedKey(guildId, integrationId);
+}
+/**
+* Creates a stable key for an invite, using `@global` for invites that do not belong to a guild.
+*/
+function inviteKey(guildId, code) {
+	return `${guildId ?? "@global"}:${code}`;
+}
+/**
+* Creates a stable key for a thread member.
+*/
+function threadMemberKey(threadId, userId) {
+	return `${threadId}:${userId}`;
+}
+/**
+* Creates a stable key for application command permissions.
+*/
+function applicationCommandPermissionsKey(applicationId, guildId, commandId) {
+	return `${applicationId}:${guildId}:${commandId}`;
+}
+
+//#endregion
+//#region src/lib/reactions.ts
+/**
+* Whether two reaction emojis are the same: custom emojis match by ID, Unicode emojis by name.
+*/
+function isSameEmoji(a, b) {
+	return a.id ? a.id === b.id : !b.id && a.name === b.name;
+}
+/**
+* Adds a `MESSAGE_REACTION_ADD` to a cached message's reactions.
+*
+* @param message The cached message.
+* @param data The dispatch data.
+* @param clientUserId The bot's user ID, to set `me` when the bot reacted.
+*/
+function addReaction(message, data, clientUserId) {
+	const me = data.user_id === clientUserId;
+	const kind = data.burst ? "burst" : "normal";
+	const reactions = message.reactions ?? [];
+	const existing = reactions.find((reaction) => isSameEmoji(reaction.emoji, data.emoji));
+	if (!existing) {
+		const reaction = {
+			emoji: data.emoji,
+			count: 1,
+			count_details: {
+				normal: data.burst ? 0 : 1,
+				burst: data.burst ? 1 : 0
+			},
+			me: me && !data.burst,
+			me_burst: me && data.burst,
+			burst_colors: data.burst_colors ?? []
+		};
+		return {
+			...message,
+			reactions: [...reactions, reaction]
+		};
+	}
+	return {
+		...message,
+		reactions: reactions.map((reaction) => reaction === existing ? {
+			...reaction,
+			count: reaction.count + 1,
+			count_details: {
+				...reaction.count_details,
+				[kind]: reaction.count_details[kind] + 1
+			},
+			me: reaction.me || me && !data.burst,
+			me_burst: reaction.me_burst || me && data.burst,
+			burst_colors: data.burst ? data.burst_colors ?? reaction.burst_colors : reaction.burst_colors
+		} : reaction)
+	};
+}
+/**
+* Removes a `MESSAGE_REACTION_REMOVE` from a cached message's reactions, dropping the reaction when its count reaches
+* zero.
+*
+* @param message The cached message.
+* @param data The dispatch data.
+* @param clientUserId The bot's user ID, to clear `me` when the bot's reaction was removed.
+*/
+function removeReaction(message, data, clientUserId) {
+	const me = data.user_id === clientUserId;
+	const kind = data.burst ? "burst" : "normal";
+	const reactions = (message.reactions ?? []).flatMap((reaction) => {
+		if (!isSameEmoji(reaction.emoji, data.emoji)) return [reaction];
+		if (reaction.count <= 1) return [];
+		return [{
+			...reaction,
+			count: reaction.count - 1,
+			count_details: {
+				...reaction.count_details,
+				[kind]: Math.max(0, reaction.count_details[kind] - 1)
+			},
+			me: reaction.me && !(me && !data.burst),
+			me_burst: reaction.me_burst && !(me && data.burst)
+		}];
+	});
+	return {
+		...message,
+		reactions
+	};
+}
+/**
+* Removes every reaction with one emoji from a cached message.
+*
+* @param message The cached message.
+* @param emoji The emoji.
+*/
+function removeReactionEmoji(message, emoji) {
+	return {
+		...message,
+		reactions: (message.reactions ?? []).filter((reaction) => !isSameEmoji(reaction.emoji, emoji))
+	};
+}
+/**
+* Counts a `MESSAGE_POLL_VOTE_ADD` or `MESSAGE_POLL_VOTE_REMOVE` in a cached message's poll results.
+*
+* @param message The cached message.
+* @param data The dispatch data.
+* @param delta `1` for a vote, `-1` for a removed vote.
+* @param clientUserId The bot's user ID, to set `me_voted` when the bot voted.
+*/
+function countPollVote(message, data, delta, clientUserId) {
+	const { poll } = message;
+	if (!poll) return message;
+	const me = data.user_id === clientUserId;
+	const results = poll.results ?? {
+		is_finalized: false,
+		answer_counts: []
+	};
+	const counts = results.answer_counts.some((count) => count.id === data.answer_id) ? results.answer_counts : [...results.answer_counts, {
+		id: data.answer_id,
+		count: 0,
+		me_voted: false
+	}];
+	return {
+		...message,
+		poll: {
+			...poll,
+			results: {
+				...results,
+				answer_counts: counts.map((count) => count.id === data.answer_id ? {
+					...count,
+					count: Math.max(0, count.count + delta),
+					me_voted: me ? delta === 1 : count.me_voted
+				} : count)
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/lib/operations.ts
+const cacheEntityNameRecord = {
+	applicationCommandPermissions: true,
+	auditLogEntries: true,
+	autoModerationRules: true,
+	bans: true,
+	channels: true,
+	emojis: true,
+	entitlements: true,
+	guilds: true,
+	integrations: true,
+	invites: true,
+	members: true,
+	messages: true,
+	presences: true,
+	roles: true,
+	scheduledEvents: true,
+	soundboardSounds: true,
+	stageInstances: true,
+	stickers: true,
+	subscriptions: true,
+	threadMembers: true,
+	threads: true,
+	users: true,
+	voiceStates: true
+};
+/**
+* The name of every entity cache held by a {@link Cache}.
+*/
+const CacheEntityNames = Object.keys(cacheEntityNameRecord);
+/**
+* Translates a gateway dispatch into the list of {@link CacheOperation}s it implies, including the cascades (e.g.
+* `CHANNEL_DELETE` also drops that channel's messages).
+*
+* @remarks
+* This is a pure function, it does not touch any cache. Use {@link applyGatewayDispatch} to apply them.
+* `INTERACTION_CREATE` is intentionally ignored: interactions are short-lived and never cached.
+*
+* @param payload The gateway dispatch payload.
+* @param context The bot's user ID, for the `me` flags of reactions and poll votes.
+*/
+function createCacheOperations(payload, context = {}) {
+	const { clientUserId } = context;
+	const operations = [];
+	switch (payload.t) {
+		case GatewayDispatchEvents.ApplicationCommandPermissionsUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "applicationCommandPermissions",
+				key: applicationCommandPermissionsKey(data.application_id, data.guild_id, data.id),
+				raw: data
+			});
+			break;
+		}
+		case GatewayDispatchEvents.AutoModerationRuleCreate:
+		case GatewayDispatchEvents.AutoModerationRuleUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "autoModerationRules",
+				key: autoModerationRuleKey(data.guild_id, data.id),
+				raw: data
+			});
+			break;
+		}
+		case GatewayDispatchEvents.AutoModerationRuleDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "autoModerationRules",
+				key: autoModerationRuleKey(data.guild_id, data.id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.ChannelCreate:
+		case GatewayDispatchEvents.ChannelUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "channels",
+				key: data.id,
+				raw: data,
+				merge: payload.t === GatewayDispatchEvents.ChannelUpdate
+			});
+			break;
+		}
+		case GatewayDispatchEvents.ChannelDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "channels",
+				key: data.id
+			});
+			operations.push({
+				type: "deletePrefix",
+				store: "messages",
+				prefix: `${data.id}:`
+			});
+			break;
+		}
+		case GatewayDispatchEvents.EntitlementCreate:
+		case GatewayDispatchEvents.EntitlementUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "entitlements",
+				key: data.id,
+				raw: data
+			});
+			break;
+		}
+		case GatewayDispatchEvents.EntitlementDelete:
+			operations.push({
+				type: "delete",
+				store: "entitlements",
+				key: payload.d.id
+			});
+			break;
+		case GatewayDispatchEvents.GuildAuditLogEntryCreate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "auditLogEntries",
+				key: guildScopedKey(data.guild_id, data.id),
+				raw: data
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildBanAdd: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "bans",
+				key: banKey(data.guild_id, data.user.id),
+				raw: data
+			});
+			operations.push({
+				type: "upsert",
+				store: "users",
+				key: data.user.id,
+				raw: data.user
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildBanRemove: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "bans",
+				key: banKey(data.guild_id, data.user.id)
+			});
+			operations.push({
+				type: "upsert",
+				store: "users",
+				key: data.user.id,
+				raw: data.user
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildCreate:
+			hydrateGuildCreate(operations, payload.d);
+			break;
+		case GatewayDispatchEvents.GuildUpdate: {
+			const { roles, emojis, stickers, ...data } = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "guilds",
+				key: data.id,
+				raw: data,
+				merge: true
+			});
+			for (const role of roles ?? []) hydrateRole(operations, data.id, role);
+			for (const emoji of emojis ?? []) hydrateEmoji(operations, data.id, emoji);
+			for (const sticker of stickers ?? []) hydrateSticker(operations, data.id, sticker);
+			break;
+		}
+		case GatewayDispatchEvents.GuildDelete: {
+			const data = payload.d;
+			if (data.unavailable) {
+				operations.push({
+					type: "upsert",
+					store: "guilds",
+					key: data.id,
+					raw: data,
+					merge: true
+				});
+				break;
+			}
+			operations.push({
+				type: "delete",
+				store: "guilds",
+				key: data.id
+			});
+			deleteGuildScopedResources(operations, data.id);
+			break;
+		}
+		case GatewayDispatchEvents.GuildEmojisUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "deletePrefix",
+				store: "emojis",
+				prefix: `${data.guild_id}:`
+			});
+			for (const emoji of data.emojis) {
+				if (!emoji.id) continue;
+				operations.push({
+					type: "upsert",
+					store: "emojis",
+					key: emojiKey(data.guild_id, emoji.id),
+					raw: withGuildId(emoji, data.guild_id)
+				});
+			}
+			break;
+		}
+		case GatewayDispatchEvents.GuildStickersUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "deletePrefix",
+				store: "stickers",
+				prefix: `${data.guild_id}:`
+			});
+			for (const sticker of data.stickers) operations.push({
+				type: "upsert",
+				store: "stickers",
+				key: stickerKey(data.guild_id, sticker.id),
+				raw: withGuildId(sticker, data.guild_id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildMemberAdd:
+		case GatewayDispatchEvents.GuildMemberUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "members",
+				key: memberKey(data.guild_id, data.user.id),
+				raw: data,
+				merge: true
+			});
+			operations.push({
+				type: "upsert",
+				store: "users",
+				key: data.user.id,
+				raw: data.user
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildMemberRemove: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "members",
+				key: memberKey(data.guild_id, data.user.id)
+			});
+			operations.push({
+				type: "upsert",
+				store: "users",
+				key: data.user.id,
+				raw: data.user
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildMembersChunk:
+			hydrateGuildMembersChunk(operations, payload.d);
+			break;
+		case GatewayDispatchEvents.GuildRoleCreate:
+		case GatewayDispatchEvents.GuildRoleUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "roles",
+				key: roleKey(data.guild_id, data.role.id),
+				raw: withGuildId(data.role, data.guild_id),
+				merge: payload.t === GatewayDispatchEvents.GuildRoleUpdate
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildRoleDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "roles",
+				key: roleKey(data.guild_id, data.role_id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildScheduledEventCreate:
+		case GatewayDispatchEvents.GuildScheduledEventUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "scheduledEvents",
+				key: scheduledEventKey(data.guild_id, data.id),
+				raw: data,
+				merge: true
+			});
+			if (data.creator) operations.push({
+				type: "upsert",
+				store: "users",
+				key: data.creator.id,
+				raw: data.creator
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildScheduledEventDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "scheduledEvents",
+				key: scheduledEventKey(data.guild_id, data.id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildSoundboardSoundCreate:
+		case GatewayDispatchEvents.GuildSoundboardSoundUpdate: {
+			const data = payload.d;
+			if (!data.guild_id) break;
+			operations.push({
+				type: "upsert",
+				store: "soundboardSounds",
+				key: soundboardSoundKey(data.guild_id, data.sound_id),
+				raw: data,
+				merge: payload.t === GatewayDispatchEvents.GuildSoundboardSoundUpdate
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildSoundboardSoundDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "soundboardSounds",
+				key: soundboardSoundKey(data.guild_id, data.sound_id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.GuildSoundboardSoundsUpdate:
+			hydrateGuildSoundboardSoundsUpdate(operations, payload.d);
+			break;
+		case GatewayDispatchEvents.SoundboardSounds:
+			hydrateSoundboardSounds(operations, payload.d);
+			break;
+		case GatewayDispatchEvents.IntegrationCreate:
+		case GatewayDispatchEvents.IntegrationUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "integrations",
+				key: integrationKey(data.guild_id, data.id),
+				raw: data,
+				merge: true
+			});
+			break;
+		}
+		case GatewayDispatchEvents.IntegrationDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "integrations",
+				key: integrationKey(data.guild_id, data.id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.InviteCreate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "invites",
+				key: inviteKey(data.guild_id, data.code),
+				raw: data
+			});
+			break;
+		}
+		case GatewayDispatchEvents.InviteDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "invites",
+				key: inviteKey(data.guild_id, data.code)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.MessageCreate:
+		case GatewayDispatchEvents.MessageUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "messages",
+				key: messageKey(data.channel_id, data.id),
+				raw: data,
+				merge: payload.t === GatewayDispatchEvents.MessageUpdate
+			});
+			const author = "author" in data ? data.author : void 0;
+			if (author) {
+				operations.push({
+					type: "upsert",
+					store: "users",
+					key: author.id,
+					raw: author
+				});
+				if (data.member && data.guild_id) operations.push({
+					type: "upsert",
+					store: "members",
+					key: memberKey(data.guild_id, author.id),
+					raw: withGuildId(data.member, data.guild_id),
+					merge: true
+				});
+			}
+			break;
+		}
+		case GatewayDispatchEvents.MessageDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "messages",
+				key: messageKey(data.channel_id, data.id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.MessageDeleteBulk: {
+			const data = payload.d;
+			for (const id of data.ids) operations.push({
+				type: "delete",
+				store: "messages",
+				key: messageKey(data.channel_id, id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.MessageReactionAdd: {
+			const data = payload.d;
+			operations.push(updateMessage(data.channel_id, data.message_id, (message) => addReaction(message, data, clientUserId)));
+			const user = data.member?.user;
+			if (user && data.guild_id) {
+				operations.push({
+					type: "upsert",
+					store: "users",
+					key: user.id,
+					raw: user
+				});
+				operations.push({
+					type: "upsert",
+					store: "members",
+					key: memberKey(data.guild_id, user.id),
+					raw: withGuildId(data.member, data.guild_id),
+					merge: true
+				});
+			}
+			break;
+		}
+		case GatewayDispatchEvents.MessageReactionRemove: {
+			const data = payload.d;
+			operations.push(updateMessage(data.channel_id, data.message_id, (message) => removeReaction(message, data, clientUserId)));
+			break;
+		}
+		case GatewayDispatchEvents.MessageReactionRemoveAll: {
+			const data = payload.d;
+			operations.push(updateMessage(data.channel_id, data.message_id, (message) => ({
+				...message,
+				reactions: []
+			})));
+			break;
+		}
+		case GatewayDispatchEvents.MessageReactionRemoveEmoji: {
+			const data = payload.d;
+			operations.push(updateMessage(data.channel_id, data.message_id, (message) => removeReactionEmoji(message, data.emoji)));
+			break;
+		}
+		case GatewayDispatchEvents.MessagePollVoteAdd:
+		case GatewayDispatchEvents.MessagePollVoteRemove: {
+			const data = payload.d;
+			const delta = payload.t === GatewayDispatchEvents.MessagePollVoteAdd ? 1 : -1;
+			operations.push(updateMessage(data.channel_id, data.message_id, (message) => countPollVote(message, data, delta, clientUserId)));
+			break;
+		}
+		case GatewayDispatchEvents.PresenceUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "presences",
+				key: presenceKey(data.guild_id, data.user.id),
+				raw: data,
+				merge: true
+			});
+			operations.push({
+				type: "upsert",
+				store: "users",
+				key: data.user.id,
+				raw: data.user,
+				merge: true
+			});
+			break;
+		}
+		case GatewayDispatchEvents.Ready: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "users",
+				key: data.user.id,
+				raw: data.user
+			});
+			for (const guild of data.guilds) operations.push({
+				type: "upsert",
+				store: "guilds",
+				key: guild.id,
+				raw: guild,
+				merge: true
+			});
+			break;
+		}
+		case GatewayDispatchEvents.StageInstanceCreate:
+		case GatewayDispatchEvents.StageInstanceUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "stageInstances",
+				key: stageInstanceKey(data.guild_id, data.channel_id),
+				raw: data,
+				merge: true
+			});
+			break;
+		}
+		case GatewayDispatchEvents.StageInstanceDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "stageInstances",
+				key: stageInstanceKey(data.guild_id, data.channel_id)
+			});
+			break;
+		}
+		case GatewayDispatchEvents.SubscriptionCreate:
+		case GatewayDispatchEvents.SubscriptionUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "subscriptions",
+				key: data.id,
+				raw: data
+			});
+			break;
+		}
+		case GatewayDispatchEvents.SubscriptionDelete:
+			operations.push({
+				type: "delete",
+				store: "subscriptions",
+				key: payload.d.id
+			});
+			break;
+		case GatewayDispatchEvents.ThreadCreate:
+		case GatewayDispatchEvents.ThreadUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "threads",
+				key: data.id,
+				raw: data,
+				merge: payload.t === GatewayDispatchEvents.ThreadUpdate
+			});
+			const member = "member" in data ? data.member : void 0;
+			if (member?.user_id) operations.push({
+				type: "upsert",
+				store: "threadMembers",
+				key: threadMemberKey(data.id, member.user_id),
+				raw: data.guild_id ? withGuildId(member, data.guild_id) : member,
+				merge: true
+			});
+			break;
+		}
+		case GatewayDispatchEvents.ThreadDelete: {
+			const data = payload.d;
+			operations.push({
+				type: "delete",
+				store: "threads",
+				key: data.id
+			});
+			operations.push({
+				type: "deletePrefix",
+				store: "threadMembers",
+				prefix: `${data.id}:`
+			});
+			operations.push({
+				type: "deletePrefix",
+				store: "messages",
+				prefix: `${data.id}:`
+			});
+			break;
+		}
+		case GatewayDispatchEvents.ThreadListSync:
+			hydrateThreadListSync(operations, payload.d);
+			break;
+		case GatewayDispatchEvents.ThreadMemberUpdate: {
+			const data = payload.d;
+			if (!data.id || !data.user_id) break;
+			operations.push({
+				type: "upsert",
+				store: "threadMembers",
+				key: threadMemberKey(data.id, data.user_id),
+				raw: data,
+				merge: true
+			});
+			break;
+		}
+		case GatewayDispatchEvents.ThreadMembersUpdate:
+			hydrateThreadMembersUpdate(operations, payload.d);
+			break;
+		case GatewayDispatchEvents.UserUpdate: {
+			const data = payload.d;
+			operations.push({
+				type: "upsert",
+				store: "users",
+				key: data.id,
+				raw: data,
+				merge: true
+			});
+			break;
+		}
+		case GatewayDispatchEvents.VoiceStateUpdate: {
+			const data = payload.d;
+			if (!data.guild_id) break;
+			const key = voiceStateKey(data.guild_id, data.user_id);
+			if (data.channel_id) operations.push({
+				type: "upsert",
+				store: "voiceStates",
+				key,
+				raw: data,
+				merge: true
+			});
+			else operations.push({
+				type: "delete",
+				store: "voiceStates",
+				key
+			});
+			const user = data.member?.user;
+			if (data.member && user) {
+				operations.push({
+					type: "upsert",
+					store: "users",
+					key: user.id,
+					raw: user
+				});
+				operations.push({
+					type: "upsert",
+					store: "members",
+					key: memberKey(data.guild_id, user.id),
+					raw: withGuildId(data.member, data.guild_id),
+					merge: true
+				});
+			}
+			break;
+		}
+	}
+	return operations;
+}
+/**
+* Applies a list of {@link CacheOperation}s to a {@link Cache}, sequentially and in order.
+*
+* @param cache The cache to mutate.
+* @param operations The operations to apply, usually created by {@link createCacheOperations}.
+*/
+async function applyCacheOperations(cache, operations) {
+	for (const operation of operations) {
+		const store = cache[operation.store];
+		switch (operation.type) {
+			case "upsert": {
+				const value = operation.merge ? mergeValues(await store.get(operation.key), operation.raw) : operation.raw;
+				await store.set(operation.key, value);
+				break;
+			}
+			case "update": {
+				const existing = await store.get(operation.key);
+				if (existing !== void 0) await store.set(operation.key, operation.update(existing));
+				break;
+			}
+			case "delete":
+				await store.delete(operation.key);
+				break;
+			case "deletePrefix":
+				for (const key of await store.keys()) if (key.startsWith(operation.prefix)) await store.delete(key);
+				break;
+			case "deleteWhere": for (const [key, value] of await store.entries()) if (operation.predicate(value)) await store.delete(key);
+		}
+	}
+}
+/**
+* Writes a gateway dispatch into every relevant entity cache of a {@link Cache}.
+*
+* @param cache The cache to mutate.
+* @param payload The gateway dispatch payload.
+* @param context The bot's user ID, for the `me` flags of reactions and poll votes.
+*/
+function applyGatewayDispatch(cache, payload, context) {
+	return applyCacheOperations(cache, createCacheOperations(payload, context));
+}
+/**
+* Shallow-merges `value` onto `existing` when both are plain objects, returning `value` otherwise.
+*/
+function mergeValues(existing, value) {
+	if (isObject(existing) && isObject(value)) return {
+		...existing,
+		...value
+	};
+	return value;
+}
+function hydrateGuildCreate(operations, guild) {
+	if ("unavailable" in guild && guild.unavailable) {
+		operations.push({
+			type: "upsert",
+			store: "guilds",
+			key: guild.id,
+			raw: guild,
+			merge: true
+		});
+		return;
+	}
+	const { channels, threads, members, presences, voice_states: voiceStates, stage_instances: stageInstances, guild_scheduled_events: scheduledEvents, soundboard_sounds: soundboardSounds, roles, emojis, stickers, ...rest } = guild;
+	operations.push({
+		type: "upsert",
+		store: "guilds",
+		key: guild.id,
+		raw: rest
+	});
+	for (const channel of channels ?? []) operations.push({
+		type: "upsert",
+		store: "channels",
+		key: channel.id,
+		raw: withGuildId(channel, guild.id)
+	});
+	for (const thread of threads ?? []) {
+		operations.push({
+			type: "upsert",
+			store: "threads",
+			key: thread.id,
+			raw: withGuildId(thread, guild.id)
+		});
+		if (thread.member?.user_id) operations.push({
+			type: "upsert",
+			store: "threadMembers",
+			key: threadMemberKey(thread.id, thread.member.user_id),
+			raw: withGuildId(thread.member, guild.id)
+		});
+	}
+	for (const member of members ?? []) hydrateMember(operations, guild.id, member);
+	for (const presence of presences ?? []) operations.push({
+		type: "upsert",
+		store: "presences",
+		key: presenceKey(guild.id, presence.user.id),
+		raw: withGuildId(presence, guild.id)
+	});
+	for (const role of roles ?? []) hydrateRole(operations, guild.id, role);
+	for (const emoji of emojis ?? []) hydrateEmoji(operations, guild.id, emoji);
+	for (const sticker of stickers ?? []) hydrateSticker(operations, guild.id, sticker);
+	for (const voiceState of voiceStates ?? []) {
+		if (!voiceState.channel_id) continue;
+		operations.push({
+			type: "upsert",
+			store: "voiceStates",
+			key: voiceStateKey(guild.id, voiceState.user_id),
+			raw: withGuildId(voiceState, guild.id)
+		});
+	}
+	for (const stageInstance of stageInstances ?? []) operations.push({
+		type: "upsert",
+		store: "stageInstances",
+		key: stageInstanceKey(guild.id, stageInstance.channel_id),
+		raw: stageInstance
+	});
+	for (const scheduledEvent of scheduledEvents ?? []) operations.push({
+		type: "upsert",
+		store: "scheduledEvents",
+		key: scheduledEventKey(guild.id, scheduledEvent.id),
+		raw: scheduledEvent
+	});
+	for (const sound of soundboardSounds ?? []) hydrateSoundboardSound(operations, guild.id, sound);
+}
+function hydrateGuildMembersChunk(operations, data) {
+	for (const member of data.members) hydrateMember(operations, data.guild_id, member);
+	for (const presence of data.presences ?? []) operations.push({
+		type: "upsert",
+		store: "presences",
+		key: presenceKey(data.guild_id, presence.user.id),
+		raw: withGuildId(presence, data.guild_id)
+	});
+}
+function hydrateGuildSoundboardSoundsUpdate(operations, data) {
+	operations.push({
+		type: "deletePrefix",
+		store: "soundboardSounds",
+		prefix: `${data.guild_id}:`
+	});
+	for (const sound of data.soundboard_sounds) hydrateSoundboardSound(operations, data.guild_id, sound);
+}
+function hydrateSoundboardSounds(operations, data) {
+	for (const sound of data.soundboard_sounds) hydrateSoundboardSound(operations, data.guild_id, sound);
+}
+function hydrateThreadListSync(operations, data) {
+	for (const thread of data.threads) operations.push({
+		type: "upsert",
+		store: "threads",
+		key: thread.id,
+		raw: withGuildId(thread, data.guild_id),
+		merge: true
+	});
+	for (const member of data.members) {
+		if (!member.id || !member.user_id) continue;
+		operations.push({
+			type: "upsert",
+			store: "threadMembers",
+			key: threadMemberKey(member.id, member.user_id),
+			raw: withGuildId(member, data.guild_id),
+			merge: true
+		});
+	}
+}
+function hydrateThreadMembersUpdate(operations, data) {
+	for (const member of data.added_members ?? []) {
+		if (!member.user_id) continue;
+		operations.push({
+			type: "upsert",
+			store: "threadMembers",
+			key: threadMemberKey(data.id, member.user_id),
+			raw: withGuildId(member, data.guild_id),
+			merge: true
+		});
+	}
+	for (const userId of data.removed_member_ids ?? []) operations.push({
+		type: "delete",
+		store: "threadMembers",
+		key: threadMemberKey(data.id, userId)
+	});
+}
+function hydrateMember(operations, guildId, member) {
+	if (!member.user) return;
+	operations.push({
+		type: "upsert",
+		store: "members",
+		key: memberKey(guildId, member.user.id),
+		raw: withGuildId(member, guildId),
+		merge: true
+	});
+	operations.push({
+		type: "upsert",
+		store: "users",
+		key: member.user.id,
+		raw: member.user
+	});
+}
+function hydrateRole(operations, guildId, role) {
+	operations.push({
+		type: "upsert",
+		store: "roles",
+		key: roleKey(guildId, role.id),
+		raw: withGuildId(role, guildId)
+	});
+}
+function hydrateEmoji(operations, guildId, emoji) {
+	if (!emoji.id) return;
+	operations.push({
+		type: "upsert",
+		store: "emojis",
+		key: emojiKey(guildId, emoji.id),
+		raw: withGuildId(emoji, guildId)
+	});
+}
+function hydrateSticker(operations, guildId, sticker) {
+	operations.push({
+		type: "upsert",
+		store: "stickers",
+		key: stickerKey(guildId, sticker.id),
+		raw: withGuildId(sticker, guildId)
+	});
+}
+function hydrateSoundboardSound(operations, guildId, sound) {
+	operations.push({
+		type: "upsert",
+		store: "soundboardSounds",
+		key: soundboardSoundKey(guildId, sound.sound_id),
+		raw: withGuildId(sound, guildId)
+	});
+}
+function deleteGuildScopedResources(operations, guildId) {
+	for (const store of [
+		"auditLogEntries",
+		"autoModerationRules",
+		"bans",
+		"emojis",
+		"integrations",
+		"members",
+		"presences",
+		"roles",
+		"scheduledEvents",
+		"soundboardSounds",
+		"stageInstances",
+		"stickers",
+		"voiceStates"
+	]) operations.push({
+		type: "deletePrefix",
+		store,
+		prefix: `${guildId}:`
+	});
+	for (const store of [
+		"applicationCommandPermissions",
+		"channels",
+		"threads",
+		"threadMembers",
+		"messages",
+		"invites"
+	]) operations.push({
+		type: "deleteWhere",
+		store,
+		predicate: (value) => isObject(value) && value.guild_id === guildId
+	});
+}
+function updateMessage(channelId, messageId, update) {
+	return {
+		type: "update",
+		store: "messages",
+		key: messageKey(channelId, messageId),
+		update: (value) => update(value)
+	};
+}
+function withGuildId(value, guildId) {
+	return {
+		...value,
+		guild_id: guildId
+	};
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+//#endregion
+//#region src/lib/gateway.ts
+/**
+* Writes gateway dispatches into a cache. Call the returned function to stop listening.
+* Use this when a gateway has no GatewayClient managing its dispatch queue.
+*/
+function attachCacheToGateway(gateway, cache, options = {}) {
+	const listener = (payload, shardId) => {
+		applyGatewayDispatch(cache, payload, { clientUserId: options.clientUserId }).catch((error) => {
+			if (options.onError) options.onError(error, payload, shardId);
+			else console.error("Failed to cache gateway dispatch", error);
+		});
+	};
+	gateway.on("dispatch", listener);
+	return () => gateway.off?.("dispatch", listener);
+}
+
+//#endregion
+//#region src/lib/memory.ts
+/**
+* An {@link EntityCache} backed by a `Map`, optionally bounded as a least-recently-used cache.
+*/
+var MemoryEntityCache = class {
+	/**
+	* The maximum amount of entries, `Infinity` for an unbounded cache.
+	*/
+	maxSize;
+	#items = /* @__PURE__ */ new Map();
+	constructor(maxSize = Infinity) {
+		if (maxSize !== Infinity && (!Number.isInteger(maxSize) || maxSize < 0)) throw new RangeError(`maxSize must be a non-negative integer or Infinity, received ${maxSize}`);
+		this.maxSize = maxSize;
+	}
+	get(key) {
+		const value = this.#items.get(key);
+		if (value !== void 0 && this.maxSize !== Infinity) {
+			this.#items.delete(key);
+			this.#items.set(key, value);
+		}
+		return value;
+	}
+	set(key, value) {
+		if (this.maxSize === 0) return;
+		this.#items.delete(key);
+		this.#items.set(key, value);
+		if (this.#items.size > this.maxSize) this.#items.delete(this.#items.keys().next().value);
+	}
+	has(key) {
+		return this.#items.has(key);
+	}
+	delete(key) {
+		return this.#items.delete(key);
+	}
+	clear() {
+		this.#items.clear();
+	}
+	getSize() {
+		return this.#items.size;
+	}
+	keys() {
+		return [...this.#items.keys()];
+	}
+	values() {
+		return [...this.#items.values()];
+	}
+	entries() {
+		return [...this.#items.entries()];
+	}
+};
+/**
+* Creates a {@link Cache} that keeps everything in the process' memory.
+*
+* @example
+* ```typescript
+* import { createInMemoryCache } from '@wolfstar/plugin-cache';
+*
+* // Keep at most 1000 messages around, everything else is unbounded.
+* const cache = createInMemoryCache({ maxSize: { messages: 1_000 } });
+* ```
+*
+* @param options The options for the cache.
+*/
+function createInMemoryCache(options = {}) {
+	const { maxSize } = options;
+	const resolve = (name) => typeof maxSize === "number" ? maxSize : maxSize?.[name] ?? Infinity;
+	return Object.freeze(Object.fromEntries(CacheEntityNames.map((name) => [name, new MemoryEntityCache(resolve(name))])));
+}
+
+//#endregion
+//#region src/lib/redis.ts
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+const brotliCompressAsync = promisify(brotliCompress);
+const brotliDecompressAsync = promisify(brotliDecompress);
+/**
+* Thrown when a value stored in Redis cannot be read back: invalid JSON, or compressed bytes that fail to decompress.
+*
+* @remarks
+* A missing value is not an error, `get` resolves to `undefined` for it. Redis connection errors are not wrapped
+* either, they propagate as the client throws them.
+*/
+var CacheValueError = class extends Error {
+	/**
+	* The Redis key holding the unreadable value.
+	*/
+	key;
+	constructor(key, cause) {
+		super(`Cannot read the cached value at "${key}"`, { cause });
+		this.name = "CacheValueError";
+		this.key = key;
+	}
+};
+const CompressionMarkers = {
+	gzip: "gz:",
+	brotli: "br:"
+};
+/**
+* An {@link EntityCache} backed by Redis.
+*
+* @remarks
+* Every entry is stored as its own string key (`<prefix>:<key>`), and a sorted set (`<prefix>:@index`) tracks the
+* stored keys with their expiration time as score, which is what `keys`, `entries`, `getSize`, and `clear` read from.
+*/
+var RedisEntityCache = class {
+	prefix;
+	ttl;
+	compression;
+	compressionThreshold;
+	#redis;
+	constructor(redis, options) {
+		if (options.ttl !== void 0 && !(options.ttl > 0)) throw new RangeError(`ttl must be a positive amount of seconds, received ${options.ttl}`);
+		this.#redis = redis;
+		this.prefix = options.prefix;
+		this.ttl = options.ttl;
+		this.compression = options.compression ?? "none";
+		this.compressionThreshold = options.compressionThreshold ?? 1024;
+	}
+	async get(key) {
+		const valueKey = this.valueKey(key);
+		const value = await this.#redis.get(valueKey);
+		return value === null ? void 0 : this.deserialize(valueKey, value);
+	}
+	async set(key, value) {
+		const serialized = await this.serialize(value);
+		const transaction = this.#redis.multi();
+		if (this.ttl === void 0) transaction.set(this.valueKey(key), serialized).zadd(this.indexKey, "+inf", key);
+		else {
+			const now = Date.now();
+			const milliseconds = Math.round(this.ttl * 1e3);
+			transaction.set(this.valueKey(key), serialized, "PX", milliseconds).zadd(this.indexKey, now + milliseconds, key).zremrangebyscore(this.indexKey, "-inf", now);
+		}
+		await execute(transaction);
+	}
+	async has(key) {
+		return await this.#redis.exists(this.valueKey(key)) > 0;
+	}
+	async delete(key) {
+		const [deleted] = await execute(this.#redis.multi().del(this.valueKey(key)).zrem(this.indexKey, key));
+		return deleted > 0;
+	}
+	async clear() {
+		const keys = await this.#redis.zrange(this.indexKey, "0", "-1");
+		if (keys.length > 0) await this.#redis.del(...keys.map((key) => this.valueKey(key)));
+		await this.#redis.del(this.indexKey);
+	}
+	async getSize() {
+		await this.prune();
+		return this.#redis.zcard(this.indexKey);
+	}
+	async keys() {
+		await this.prune();
+		return this.#redis.zrange(this.indexKey, "0", "-1");
+	}
+	async values() {
+		return (await this.entries()).map(([, value]) => value);
+	}
+	async entries() {
+		const keys = await this.keys();
+		if (keys.length === 0) return [];
+		const values = await this.#redis.mget(...keys.map((key) => this.valueKey(key)));
+		const entries = [];
+		for (const [index, value] of values.entries()) if (value !== null) {
+			const key = keys[index];
+			entries.push([key, await this.deserialize(this.valueKey(key), value)]);
+		}
+		return entries;
+	}
+	/**
+	* Gets the Redis key a value is stored at.
+	* @param key The entity cache key.
+	*/
+	valueKey(key) {
+		return `${this.prefix}:${key}`;
+	}
+	/**
+	* The Redis key of the sorted set indexing the stored keys.
+	*/
+	get indexKey() {
+		return `${this.prefix}:@index`;
+	}
+	async prune() {
+		if (this.ttl !== void 0) await this.#redis.zremrangebyscore(this.indexKey, "-inf", Date.now());
+	}
+	async serialize(value) {
+		const json = JSON.stringify(value);
+		if (this.compression === "none" || Buffer.byteLength(json) < this.compressionThreshold) return json;
+		const compressed = this.compression === "gzip" ? await gzipAsync(json) : await brotliCompressAsync(json);
+		return `${CompressionMarkers[this.compression]}${compressed.toString("base64")}`;
+	}
+	async deserialize(valueKey, value) {
+		try {
+			if (value.startsWith(CompressionMarkers.gzip)) return JSON.parse((await gunzipAsync(decode(value))).toString("utf8"));
+			if (value.startsWith(CompressionMarkers.brotli)) return JSON.parse((await brotliDecompressAsync(decode(value))).toString("utf8"));
+			return JSON.parse(value);
+		} catch (error) {
+			throw new CacheValueError(valueKey, error);
+		}
+	}
+};
+/**
+* Runs a transaction, throwing the first command error, and resolves to the command results.
+*/
+async function execute(transaction) {
+	const results = await transaction.exec();
+	if (results === null) throw new Error("The Redis transaction was aborted");
+	return results.map(([error, result]) => {
+		if (error) throw error;
+		return result;
+	});
+}
+function decode(value) {
+	return Buffer.from(value.slice(3), "base64");
+}
+/**
+* The default prefix of every Redis key owned by a cache created with {@link createRedisCache}.
+*/
+const DefaultRedisCachePrefix = "wolfstar:cache";
+/**
+* Creates a {@link Cache} stored in Redis, optionally compressing its values.
+*
+* @example
+* ```typescript
+* import { createRedisCache } from '@wolfstar/plugin-cache';
+* import { Redis } from 'ioredis';
+*
+* const cache = createRedisCache({
+*   redis: new Redis(process.env.REDIS_URL!),
+*   compression: 'gzip',
+*   ttl: { guilds: 60 * 60, users: 30 * 60 },
+* });
+* ```
+*
+* @param options The options for the cache.
+*/
+function createRedisCache(options) {
+	const { redis, prefix = DefaultRedisCachePrefix, compression, compressionThreshold, ttl } = options;
+	return Object.freeze(Object.fromEntries(CacheEntityNames.map((name) => [name, new RedisEntityCache(redis, {
+		prefix: `${prefix}:${name}`,
+		ttl: ttl?.[name],
+		compression,
+		compressionThreshold
+	})])));
+}
+
+//#endregion
+export { CacheEntityNames, CacheValueError, DefaultRedisCachePrefix, MemoryEntityCache, RedisEntityCache, applicationCommandPermissionsKey, applyCacheOperations, applyGatewayDispatch, attachCacheToGateway, autoModerationRuleKey, banKey, createCacheOperations, createInMemoryCache, createRedisCache, emojiKey, guildScopedKey, integrationKey, inviteKey, memberKey, mergeValues, messageKey, presenceKey, roleKey, scheduledEventKey, soundboardSoundKey, stageInstanceKey, stickerKey, threadMemberKey, voiceStateKey };
+//# sourceMappingURL=index.js.map