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

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;
@@ -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() {
@@ -18790,6 +18827,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 +18921,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