@wolfstar/plugin-gateway 0.14.0 → 0.15.0-next-20261017094524

package/dist/esm/index.js

@@ -16189,6 +16189,19 @@ var Typing = class extends Structure {
 //#endregion
 //#region src/util/events.ts
 /**
+* The {@link GatewayOnlyEventName} events, for telling them from {@link DispatchEventName} ones at runtime.
+*/
+const gatewayOnlyEvents = /* @__PURE__ */ new Set([
+	"dispatch",
+	"shardReady",
+	"clientReady",
+	"shardResume",
+	"shardClose",
+	"shardError",
+	"cacheError",
+	"cacheSweep"
+]);
+/**
 * The name of every event a {@link GatewayClient} emits, mirroring the keys of {@link GatewayEventMap}, like
 * `@wolfstar/http-framework`'s own `Events`.
 *
@@ -17975,6 +17988,7 @@ var GatewayClient = class extends Client {
 	*/
 	clientReadyTimestamp = null;
 	#queue = new DispatchQueue();
+	#dispatchForwarders = 0;
 	#caches = /* @__PURE__ */ new Map();
 	#cacheConstructor;
 	#cacheOptions;
@@ -17984,7 +17998,7 @@ var GatewayClient = class extends Client {
 	#shardCount;
 	#intents;
 	#token;
-	#expectedGuilds = /* @__PURE__ */ new Set();
+	#expectedGuilds = /* @__PURE__ */ new Map();
 	#clientReadyTimer = null;
 	#userRestore = null;
 	#sessions = null;
@@ -18351,6 +18365,29 @@ var GatewayClient = class extends Client {
 		return emitAndWait(this, event, args);
 	}
 	/**
+	* Whether the dispatches of this client are forwarded to workers, which replay them on their own listeners, see
+	* `forwardGatewayDispatches` from `@wolfstar/plugin-broker`. Listeners registered with
+	* {@link RegisterAsDispatchListener} stay idle on a client that does.
+	*/
+	get forwardsDispatches() {
+		return this.#dispatchForwarders > 0;
+	}
+	/**
+	* Marks this client as forwarding its dispatches, until the returned function is called. Called by
+	* `forwardGatewayDispatches`, it counts, so the client keeps forwarding while any forwarder is left.
+	*
+	* @returns A function to undo the mark, which does nothing when called again.
+	*/
+	markDispatchesForwarded() {
+		this.#dispatchForwarders++;
+		let marked = true;
+		return () => {
+			if (!marked) return;
+			marked = false;
+			this.#dispatchForwarders--;
+		};
+	}
+	/**
 	* The dispatch types {@link GatewayClient.replayDispatch} turns into events.
 	*/
 	get replayDispatchTypes() {
@@ -18407,7 +18444,11 @@ var GatewayClient = class extends Client {
 		const isReady = payload.t === GatewayDispatchEvents.Ready;
 		if (isReady) {
 			await this.reconcileGuilds(payload.d, shardId);
-			for (const guild of payload.d.guilds) this.#expectedGuilds.add(guild.id);
+			if (this.clientReadyTimestamp === null) {
+				const expected = new Set(payload.d.guilds.map((guild) => guild.id));
+				if (expected.size > 0) this.#expectedGuilds.set(shardId, expected);
+				else this.#expectedGuilds.delete(shardId);
+			}
 		}
 		let state;
 		try {
@@ -18422,9 +18463,15 @@ var GatewayClient = class extends Client {
 		await action?.handle(payload.d, state, shardId);
 		if (this.clientReadyTimestamp === null) {
 			if (isReady) await this.#checkClientReady();
-			else if ((payload.t === GatewayDispatchEvents.GuildCreate || payload.t === GatewayDispatchEvents.GuildDelete) && this.#expectedGuilds.delete(payload.d.id)) await this.#checkClientReady();
+			else if ((payload.t === GatewayDispatchEvents.GuildCreate || payload.t === GatewayDispatchEvents.GuildDelete) && this.#forgetExpectedGuild(shardId, payload.d.id)) await this.#checkClientReady();
 		}
 	}
+	#forgetExpectedGuild(shardId, guildId) {
+		const expected = this.#expectedGuilds.get(shardId);
+		if (!expected?.delete(guildId)) return false;
+		if (expected.size === 0) this.#expectedGuilds.delete(shardId);
+		return true;
+	}
 	async #readyAfterResume(shardId) {
 		await this.#restoreUser().catch((error) => this.reportError(error, "RESUMED", shardId));
 		await this.#checkClientReady().catch((error) => this.reportError(error, "RESUMED", shardId));
@@ -18485,12 +18532,17 @@ var GatewayClient = class extends Client {
 		this.emit("clientReady", this);
 	}
 	/**
-	* Drops the cached guilds of a shard its `READY` no longer lists, and emits `guildDelete` for each of them.
+	* Drops the cached guilds of a shard its `READY` no longer lists, and emits `dispatch` and `guildDelete` for each of
+	* them.
 	*
 	* @remarks
 	* They are the guilds the bot left while it was disconnected, or while the process was down with a persistent
 	* cache. Discord does not replay those removals on a new session, so the cache would otherwise keep them forever.
 	*
+	* Each drop is handled as a `GUILD_DELETE` (with `s: 0`) Discord would have sent, `raw` aside: `dispatch` fires once
+	* the guild is gone from the cache, with the cached guild as its state, so forwarding `dispatch` to other processes
+	* (`@wolfstar/plugin-broker`'s `forwardGatewayDispatches`) carries these deletions too.
+	*
 	* It needs a guilds cache able to enumerate its entries, and is skipped without one.
 	*
 	* It is best effort: any failure (cache unreachable, unknown shard count) is reported through `error` and stops the
@@ -18515,16 +18567,19 @@ var GatewayClient = class extends Client {
 		const count = data.shard?.[1] ?? this.#shardCount ?? await this.gateway.getShardCount();
 		const listed = new Set(data.guilds.map((guild) => guild.id));
 		const shardCount = BigInt(count);
+		const action = this.actions.get(GatewayDispatchEvents.GuildDelete);
 		for (const id of cached) {
 			if (listed.has(id) || Number((BigInt(id) >> 22n) % shardCount) !== shardId) continue;
-			const guild = await this.guilds.cache.get(id) ?? null;
-			await applyGatewayDispatch(cache, {
+			const payload = {
 				op: GatewayOpcodes.Dispatch,
 				s: 0,
 				t: GatewayDispatchEvents.GuildDelete,
 				d: { id }
-			});
-			this.emit("guildDelete", guild, { id });
+			};
+			const state = await action?.before(payload.d);
+			await applyGatewayDispatch(cache, payload);
+			this.emit("dispatch", payload, shardId, state);
+			await action?.handle(payload.d, state, shardId);
 		}
 	}
 	async runDispatch(payload, shardId, partition) {
@@ -18790,6 +18845,55 @@ function RegisterAsGatewayListener(event, options = {}) {
 		};
 	};
 }
+/**
+* Like {@link RegisterAsGatewayListener}, for an event that comes from a dispatch, but the listener only runs on one
+* process: the workers replaying the dispatches while the gateway client forwards them (see `forwardGatewayDispatches`
+* from `@wolfstar/plugin-broker`), the gateway client itself otherwise. A bot loading the same pieces on both
+* processes therefore handles each dispatch once, without reading its environment to tell which process it is on.
+*
+* @remarks
+* The decision is made on every emit, so it does not matter whether the forwarding starts before or after the
+* listener is loaded, and stopping it brings the listener back. A `once` listener is not spent while it idles.
+*
+* The events only the gateway client emits (`clientReady`, `shardReady`, `shardResume`, `shardClose`, `shardError`,
+* `dispatch`, `cacheError`, `cacheSweep`) are never replayed on a worker: they are rejected by the types, and the
+* decorator throws for them. Use {@link RegisterAsGatewayListener} for those.
+*
+* Only the dispatches that are forwarded reach the workers: with `forwardGatewayDispatches`'s `events` set, a listener
+* of an event built from another dispatch runs nowhere. A `guildDelete` that `READY` emits for the guilds it no longer
+* lists is not forwarded either (wolfstar-project/plugins#243), so a listener on the workers misses it. Delivery to the
+* workers is at-least-once, so the listener should be idempotent.
+*
+* @example
+* ```typescript
+* import { EventGatewayListener, RegisterAsDispatchListener, type Message } from '@wolfstar/plugin-gateway';
+*
+* @RegisterAsDispatchListener('messageCreate')
+* export class LogMessagesListener extends EventGatewayListener<'messageCreate'> {
+*   public override run(message: Message) {
+*     console.log(`${message.author.username}: ${message.content}`);
+*   }
+* }
+* ```
+*
+* @param event The dispatch event to listen to.
+* @param options The additional listener options.
+* @throws {TypeError} When the event is one only the gateway client emits.
+*/
+function RegisterAsDispatchListener(event, options = {}) {
+	if (gatewayOnlyEvents.has(event)) throw new TypeError(`The "${event}" event is only emitted by the gateway client, and never reaches a worker: use RegisterAsGatewayListener.`);
+	const register = RegisterAsGatewayListener(event, options);
+	return function decorate(target) {
+		const base = register(target);
+		return class extends base {
+			constructor(...args) {
+				super(...args);
+				const listener = this._listener;
+				this._listener = (...listenerArgs) => this.emitter.forwardsDispatches ? void 0 : listener(...listenerArgs);
+			}
+		};
+	};
+}
 
 //#endregion
 //#region src/util/limits.ts
@@ -18835,5 +18939,5 @@ const DefaultSweeperSettings = Object.freeze({
 });
 
 //#endregion
-export { Action, ActionRow, ActionsManager, Activity, ActivityFlagsBitField, AnnouncementChannel, AnnouncementThreadChannel, AnonymousGuild, Application, ApplicationFlagsBitField, AppliedTagsMixin, Attachment, AttachmentBuilder, AttachmentFlagsBitField, AutoModerationActionExecution, AutoModerationRule, AutoModerationRuleManager, BaseChannel, BaseChannelMixin, BaseInvite, BaseManager, BitField, CachedManager, CategoryChannel, CategoryChannelChildManager, Channel, ChannelFlagsBitField, ChannelManager, ChannelMessageManager, ChannelOwnerMixin, ChannelParentMixin, ChannelPermissionMixin, ChannelSelectMenuComponent, ChannelSlowmodeMixin, ChannelThreadManager, ChannelThreadsMixin, ChannelTopicMixin, ChannelWebhooksMixin, CheckboxComponent, CheckboxGroupComponent, ClientApplication, ClientUser, CollectionCache, Colors, Component, ComponentMixin, ContainerComponent, DMChannel, DMChannelMixin, DataManager, DefaultSweeperSettings, DispatchAction, DispatchHandlers, DispatchQueue, DispatchStateCodecs, DispatchTimeoutError, Embed, Emoji, EntityStoreCache, EventGatewayListener, FileComponent, FileUploadComponent, ForumChannel, GatewayClient, GatewayError, GatewayErrorCodes, GatewayErrorMessages, GatewayEvents, GatewayRangeError, GatewaySessionStoreError, GatewayTypeError, GroupDMChannel, GroupDMInvite, GroupDMMixin, Guild, GuildAuditLogsEntry, GuildBan, GuildBanManager, GuildChannelFields, GuildChannelInfoTimeoutError, GuildChannelManager, GuildChannelMixin, GuildEmoji, GuildEmojiManager, GuildEmojiRoleManager, GuildIntegrationManager, GuildInvite, GuildInviteManager, GuildManager, GuildMember, GuildMemberFlagsBitField, GuildMemberManager, GuildMemberRoleManager, GuildMembersRateLimitError, GuildMembersTimeoutError, GuildOnboarding, GuildOnboardingPrompt, GuildOnboardingPromptOption, GuildPreview, GuildScheduledEvent, GuildScheduledEventManager, GuildSoundboardSoundManager, GuildSoundboardSoundsTimeoutError, GuildStickerManager, GuildTemplate, GuildTemplateManager, GuildTemplatesPattern, Integration, IntentsBitField, InteractiveButtonComponent, InviteGuild, InvitesPattern, LabelComponent, LinkButtonComponent, MediaChannel, MediaGalleryComponent, MediaGalleryItem, MentionableSelectMenuComponent, Message, MessageFlagsBitField, MessageManager, MessageMentions, MessagePayload, MessageReaction, Mixin, MultiDispatchAction, MultiDispatchHandlers, NullCache, NumberFlagsBitField, Partials, PermissionOverwriteManager, PermissionOverwrites, PermissionsBitField, Poll, PollAnswer, PollAnswerVoterManager, PremiumButtonComponent, Presence, PresenceManager, PrivateThreadChannel, PublicThreadChannel, RadioGroupComponent, ReactionEmoji, ReactionManager, ReactionUserManager, RegisterAsGatewayListener, RichPresenceAssets, Role, RoleFlagsBitField, RoleManager, RoleSelectMenuComponent, SectionComponent, SeparatorComponent, SoundboardSound, StageChannel, StageInstance, StageInstanceManager, Sticker, StickerPack, StringSelectMenuComponent, Structure, StructureMixin, SweepableEntityNames, Sweepers, SystemChannelFlagsBitField, Team, TeamMember, TextChannel, TextChannelMixin, TextDisplayComponent, TextGuildChannelMixin, TextInputComponent, ThreadChannelMemberManager, ThreadChannelMixin, ThreadManager, ThreadMember, ThreadMemberManager, ThreadOnlyChannelMixin, ThumbnailComponent, Typing, UnfurledMediaItem, User, UserFlagsBitField, UserManager, UserSelectMenuComponent, VoiceChannel, VoiceChannelMixin, VoiceState, VoiceStateManager, Webhook, WebhookManager, WebhookMixin, WelcomeScreen, Widget, WidgetMember, basename, bindClient, cacheWithLimits, cleanCodeBlockContent, cleanContent, compareRolePositions, computeCachedPermissionsIn, computeCachedTargetPermissions, computeChannelPermissions, computeGuildPermissions, computePermissionsIn, computePositions, computeTargetPermissions, createChannel, createComponent, createInvite, discordSort, dispatchPartition, fillGuildId, findComponentByCustomId, findName, flatten, getGatewayClient, getSortableGroupTypes, initStructure, isDeepEqual, isThreadChannelType, kClient, kClone, kData, kPatch, kPatchRelations, kRelations, lazyRelation, makeError, makePlainError, moveElementInArray, parseEmoji, parseWebhookURL, requireGuild, requireMe, resolveBase64, resolveCode, resolveColor, resolveFile, resolveGuildEmoji, resolveGuildTemplateCode, resolveId, resolveImage, resolveImageOption, resolveInviteCode, resolveOverwriteOptions, resolvePartialEmoji, resolveSKUId, sameOverwrites, snakeCase, snowflakeTimestamp, toAPIOverwrite, toChannelBody, toSnakeCase, transformAPIAuditLogChange, transformAPIAutoModerationAction, transformAPIAutoModerationRuleTriggerMetadata, transformAPIAvatarDecorationData, transformAPIChannelMention, transformAPIEmbedAsset, transformAPIEmbedAuthor, transformAPIEmbedFooter, transformAPIGuildDefaultReaction, transformAPIGuildForumTag, transformAPIGuildScheduledEventEntityMetadata, transformAPIGuildScheduledEventRecurrenceRule, transformAPIIncidentsData, transformAPIMessageActivity, transformAPIMessageCall, transformAPIMessageInteractionMetadata, transformAPIMessageReference, transformAPIMessageSharedClientTheme, transformAPIRoleSubscriptionData, transformAPIRoleTags, transformAPIUserPrimaryGuild, transformAutoModerationAction, transformAutoModerationRuleTriggerMetadata, transformCollectibles, transformGuildDefaultReaction, transformGuildForumTag, transformGuildScheduledEventRecurrenceRule, transformResolved, verifyString, withGuildId };
+export { Action, ActionRow, ActionsManager, Activity, ActivityFlagsBitField, AnnouncementChannel, AnnouncementThreadChannel, AnonymousGuild, Application, ApplicationFlagsBitField, AppliedTagsMixin, Attachment, AttachmentBuilder, AttachmentFlagsBitField, AutoModerationActionExecution, AutoModerationRule, AutoModerationRuleManager, BaseChannel, BaseChannelMixin, BaseInvite, BaseManager, BitField, CachedManager, CategoryChannel, CategoryChannelChildManager, Channel, ChannelFlagsBitField, ChannelManager, ChannelMessageManager, ChannelOwnerMixin, ChannelParentMixin, ChannelPermissionMixin, ChannelSelectMenuComponent, ChannelSlowmodeMixin, ChannelThreadManager, ChannelThreadsMixin, ChannelTopicMixin, ChannelWebhooksMixin, CheckboxComponent, CheckboxGroupComponent, ClientApplication, ClientUser, CollectionCache, Colors, Component, ComponentMixin, ContainerComponent, DMChannel, DMChannelMixin, DataManager, DefaultSweeperSettings, DispatchAction, DispatchHandlers, DispatchQueue, DispatchStateCodecs, DispatchTimeoutError, Embed, Emoji, EntityStoreCache, EventGatewayListener, FileComponent, FileUploadComponent, ForumChannel, GatewayClient, GatewayError, GatewayErrorCodes, GatewayErrorMessages, GatewayEvents, GatewayRangeError, GatewaySessionStoreError, GatewayTypeError, GroupDMChannel, GroupDMInvite, GroupDMMixin, Guild, GuildAuditLogsEntry, GuildBan, GuildBanManager, GuildChannelFields, GuildChannelInfoTimeoutError, GuildChannelManager, GuildChannelMixin, GuildEmoji, GuildEmojiManager, GuildEmojiRoleManager, GuildIntegrationManager, GuildInvite, GuildInviteManager, GuildManager, GuildMember, GuildMemberFlagsBitField, GuildMemberManager, GuildMemberRoleManager, GuildMembersRateLimitError, GuildMembersTimeoutError, GuildOnboarding, GuildOnboardingPrompt, GuildOnboardingPromptOption, GuildPreview, GuildScheduledEvent, GuildScheduledEventManager, GuildSoundboardSoundManager, GuildSoundboardSoundsTimeoutError, GuildStickerManager, GuildTemplate, GuildTemplateManager, GuildTemplatesPattern, Integration, IntentsBitField, InteractiveButtonComponent, InviteGuild, InvitesPattern, LabelComponent, LinkButtonComponent, MediaChannel, MediaGalleryComponent, MediaGalleryItem, MentionableSelectMenuComponent, Message, MessageFlagsBitField, MessageManager, MessageMentions, MessagePayload, MessageReaction, Mixin, MultiDispatchAction, MultiDispatchHandlers, NullCache, NumberFlagsBitField, Partials, PermissionOverwriteManager, PermissionOverwrites, PermissionsBitField, Poll, PollAnswer, PollAnswerVoterManager, PremiumButtonComponent, Presence, PresenceManager, PrivateThreadChannel, PublicThreadChannel, RadioGroupComponent, ReactionEmoji, ReactionManager, ReactionUserManager, RegisterAsDispatchListener, RegisterAsGatewayListener, RichPresenceAssets, Role, RoleFlagsBitField, RoleManager, RoleSelectMenuComponent, SectionComponent, SeparatorComponent, SoundboardSound, StageChannel, StageInstance, StageInstanceManager, Sticker, StickerPack, StringSelectMenuComponent, Structure, StructureMixin, SweepableEntityNames, Sweepers, SystemChannelFlagsBitField, Team, TeamMember, TextChannel, TextChannelMixin, TextDisplayComponent, TextGuildChannelMixin, TextInputComponent, ThreadChannelMemberManager, ThreadChannelMixin, ThreadManager, ThreadMember, ThreadMemberManager, ThreadOnlyChannelMixin, ThumbnailComponent, Typing, UnfurledMediaItem, User, UserFlagsBitField, UserManager, UserSelectMenuComponent, VoiceChannel, VoiceChannelMixin, VoiceState, VoiceStateManager, Webhook, WebhookManager, WebhookMixin, WelcomeScreen, Widget, WidgetMember, basename, bindClient, cacheWithLimits, cleanCodeBlockContent, cleanContent, compareRolePositions, computeCachedPermissionsIn, computeCachedTargetPermissions, computeChannelPermissions, computeGuildPermissions, computePermissionsIn, computePositions, computeTargetPermissions, createChannel, createComponent, createInvite, discordSort, dispatchPartition, fillGuildId, findComponentByCustomId, findName, flatten, gatewayOnlyEvents, getGatewayClient, getSortableGroupTypes, initStructure, isDeepEqual, isThreadChannelType, kClient, kClone, kData, kPatch, kPatchRelations, kRelations, lazyRelation, makeError, makePlainError, moveElementInArray, parseEmoji, parseWebhookURL, requireGuild, requireMe, resolveBase64, resolveCode, resolveColor, resolveFile, resolveGuildEmoji, resolveGuildTemplateCode, resolveId, resolveImage, resolveImageOption, resolveInviteCode, resolveOverwriteOptions, resolvePartialEmoji, resolveSKUId, sameOverwrites, snakeCase, snowflakeTimestamp, toAPIOverwrite, toChannelBody, toSnakeCase, transformAPIAuditLogChange, transformAPIAutoModerationAction, transformAPIAutoModerationRuleTriggerMetadata, transformAPIAvatarDecorationData, transformAPIChannelMention, transformAPIEmbedAsset, transformAPIEmbedAuthor, transformAPIEmbedFooter, transformAPIGuildDefaultReaction, transformAPIGuildForumTag, transformAPIGuildScheduledEventEntityMetadata, transformAPIGuildScheduledEventRecurrenceRule, transformAPIIncidentsData, transformAPIMessageActivity, transformAPIMessageCall, transformAPIMessageInteractionMetadata, transformAPIMessageReference, transformAPIMessageSharedClientTheme, transformAPIRoleSubscriptionData, transformAPIRoleTags, transformAPIUserPrimaryGuild, transformAutoModerationAction, transformAutoModerationRuleTriggerMetadata, transformCollectibles, transformGuildDefaultReaction, transformGuildForumTag, transformGuildScheduledEventRecurrenceRule, transformResolved, verifyString, withGuildId };
 //# sourceMappingURL=index.js.map