seedcord 0.5.1 → 0.6.2

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { Logger, CoordinatedShutdown, CoordinatedStartup, StartupPhase } from '@seedcord/services';
+import { CoordinatedShutdown, CoordinatedStartup, Logger, StartupPhase } from '@seedcord/services';
 export * from '@seedcord/services';
 import { ClientOptions, Guild, User, SlashCommandBuilder, ContextMenuCommandBuilder, Collection, Client, ChatInputCommandInteraction, ButtonInteraction, ModalSubmitInteraction, AutocompleteInteraction, AnySelectMenuInteraction, ContextMenuCommandInteraction, ClientEvents, Events, AutocompleteFocusedOption, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder, EmbedBuilder, ModalBuilder, LabelBuilder, TextInputBuilder, FileUploadBuilder, ButtonBuilder, StringSelectMenuBuilder, StringSelectMenuOptionBuilder, UserSelectMenuBuilder, ChannelSelectMenuBuilder, MentionableSelectMenuBuilder, RoleSelectMenuBuilder, ContainerBuilder, TextDisplayBuilder, FileBuilder, MediaGalleryBuilder, SectionBuilder, SeparatorBuilder, ActionRowBuilder, ColorResolvable, Interaction, Role, TextChannel, TextChannelResolvable, MessageActionRowComponentBuilder, Message, GuildMember, Snowflake, WebhookClient } from 'discord.js';
-import { Nullable, Tail, TypedConstructor, TypedExclude } from '@seedcord/types';
+import { Tail, Nullable, TypedConstructor, TypedExclude } from '@seedcord/types';
 export * from '@seedcord/types';
 import { UUID } from 'crypto';
 import { Constructor, RequireAtLeastOne } from 'type-fest';
@@ -108,6 +108,74 @@ interface Config {
     effects: EffectsConfig;
 }
 
+/** Interface for objects that can be initialized asynchronously */
+interface Initializeable {
+    init(): Promise<void>;
+}
+/**
+ * Base class for Seedcord plugins
+ *
+ * Extend this class to create plugins that integrate with the Seedcord lifecycle.
+ * Plugins have access to the core instance and must implement initialization logic.
+ */
+declare abstract class Plugin implements Initializeable {
+    protected pluggable: Core;
+    /** Logger instance for this plugin - must be implemented by subclasses */
+    abstract logger: Logger;
+    constructor(pluggable: Core);
+    /**
+     * Initialize the plugin - implement setup logic here
+     * @virtual Override this method in your plugin classes
+     */
+    abstract init(): Promise<void>;
+}
+/**
+ * Constructor type for plugins that can accept additional arguments after Core
+ * @typeParam TPlugin - The plugin type being constructed
+ */
+type PluginCtor<TPlugin extends Plugin = Plugin> = new (core: Core, ...args: any[]) => TPlugin;
+/**
+ * Extracts the argument types for a plugin constructor (excluding the Core parameter)
+ * @typeParam Ctor - The plugin constructor to extract arguments from
+ */
+type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;
+/**
+ * Base class for objects that can have plugins attached
+ *
+ * Provides plugin attachment capabilities and lifecycle management.
+ * Plugins are attached during configuration and initialized during startup.
+ */
+declare class Pluggable {
+    protected isInitialized: boolean;
+    protected readonly shutdown: CoordinatedShutdown;
+    protected readonly startup: CoordinatedStartup;
+    private static readonly PLUGIN_INIT_TIMEOUT_MS;
+    constructor(shutdown: CoordinatedShutdown, startup: CoordinatedStartup);
+    protected init(): Promise<this>;
+    /**
+     * Attaches a plugin to this instance
+     *
+     * Plugins provide external functionality and are initialized during the specified startup phase.
+     * The plugin instance becomes available as a property in `core` wherever it's available.
+     *
+     * Make sure to augment the {@link Core} interface with the plugin type to ensure TypeScript recognizes it and provides intellisense.
+     *
+     * @typeParam Key - The property name for accessing the plugin
+     * @typeParam Ctor - The plugin constructor type
+     * @param key - Property name to access the plugin instance
+     * @param Plugin - Plugin constructor class
+     * @param startupPhase - When during startup to initialize this plugin ({@link StartupPhase})
+     * @param args - Additional arguments to pass to the plugin constructor
+     * @returns This instance with the plugin attached as a typed property
+     * @throws An {@link Error} When called after initialization or if key already exists
+     * @example
+     * ```typescript
+     * seedcord.attach('db', Mongo, StartupPhase.Configuration, { uri: 'mongodb://...', name: 'seedcord', dir: ... })
+     * ```
+     */
+    attach<Key extends string, Ctor extends PluginCtor>(this: this, key: Key, Plugin: Ctor, startupPhase: StartupPhase, ...args: PluginArgs<Ctor>): this & Record<Key, InstanceType<Ctor>>;
+}
+
 /**
  * Default side effects that are always available in the framework.
  */
@@ -211,74 +279,6 @@ interface BaseCore {
 interface Core extends BaseCore {
 }
 
-/** Interface for objects that can be initialized asynchronously */
-interface Initializeable {
-    init(): Promise<void>;
-}
-/**
- * Base class for Seedcord plugins
- *
- * Extend this class to create plugins that integrate with the Seedcord lifecycle.
- * Plugins have access to the core instance and must implement initialization logic.
- */
-declare abstract class Plugin implements Initializeable {
-    protected pluggable: Core;
-    /** Logger instance for this plugin - must be implemented by subclasses */
-    abstract logger: Logger;
-    constructor(pluggable: Core);
-    /**
-     * Initialize the plugin - implement setup logic here
-     * @virtual Override this method in your plugin classes
-     */
-    abstract init(): Promise<void>;
-}
-/**
- * Constructor type for plugins that can accept additional arguments after Core
- * @typeParam TPlugin - The plugin type being constructed
- */
-type PluginCtor<TPlugin extends Plugin = Plugin> = new (core: Core, ...args: any[]) => TPlugin;
-/**
- * Extracts the argument types for a plugin constructor (excluding the Core parameter)
- * @typeParam Ctor - The plugin constructor to extract arguments from
- */
-type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;
-/**
- * Base class for objects that can have plugins attached
- *
- * Provides plugin attachment capabilities and lifecycle management.
- * Plugins are attached during configuration and initialized during startup.
- */
-declare class Pluggable {
-    protected isInitialized: boolean;
-    protected readonly shutdown: CoordinatedShutdown;
-    protected readonly startup: CoordinatedStartup;
-    private static readonly PLUGIN_INIT_TIMEOUT_MS;
-    constructor(shutdown: CoordinatedShutdown, startup: CoordinatedStartup);
-    protected init(): Promise<this>;
-    /**
-     * Attaches a plugin to this instance
-     *
-     * Plugins provide external functionality and are initialized during the specified startup phase.
-     * The plugin instance becomes available as a property in `core` wherever it's available.
-     *
-     * Make sure to augment the {@link Core} interface with the plugin type to ensure TypeScript recognizes it and provides intellisense.
-     *
-     * @typeParam Key - The property name for accessing the plugin
-     * @typeParam Ctor - The plugin constructor type
-     * @param key - Property name to access the plugin instance
-     * @param Plugin - Plugin constructor class
-     * @param startupPhase - When during startup to initialize this plugin ({@link StartupPhase})
-     * @param args - Additional arguments to pass to the plugin constructor
-     * @returns This instance with the plugin attached as a typed property
-     * @throws An {@link Error} When called after initialization or if key already exists
-     * @example
-     * ```typescript
-     * seedcord.attach('db', Mongo, StartupPhase.Configuration, { uri: 'mongodb://...', name: 'seedcord', dir: ... })
-     * ```
-     */
-    attach<Key extends string, Ctor extends PluginCtor>(this: this, key: Key, Plugin: Ctor, startupPhase: StartupPhase, ...args: PluginArgs<Ctor>): this & Record<Key, InstanceType<Ctor>>;
-}
-
 /**
  * Manages Discord application command registration and deployment.
  *
@@ -832,15 +832,41 @@ declare function RegisterCommand(scope: 'guild', guilds: string[]): (ctor: Comma
  */
 declare function EventCatchable(log?: boolean): (_target: EventHandler<keyof ClientEvents>, _prop: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise<void>>) => void;
 
+/**
+ * The frequency at which the event handler should be executed.
+ */
+type EventFrequency = 'once' | 'on';
+
+/**
+ * Metadata key used to store event handler information
+ *
+ * @internal
+ */
 declare const EventMetadataKey: unique symbol;
+/** Options accepted by the `@RegisterEvent` decorator. */
+interface RegisterEventOptions {
+    /** Frequency: `'once'` or `'on'`. Defaults to `'on'`. */
+    readonly frequency?: EventFrequency | undefined;
+}
+/**
+ * Metadata entry representing a registered event handler.
+ *
+ * @internal
+ */
+interface RegisterEventMetadataEntry<KeyofEvents extends keyof ClientEvents> {
+    readonly event: KeyofEvents;
+    readonly frequency: EventFrequency;
+}
 /**
  * Registers an event handler class with a one or multiple Discord.js event(s).
  *
- * Associates the decorated class with the mentioned Discord client event(s) for automatic
- * registration and execution when the event is emitted.
+ * Associates the decorated class with the mentioned Discord client event(s) for automatic registration and execution when the event is emitted.
+ *
+ * You can use this decorator multiple times on the same class to register for different events with varying option settings.
  *
  * @typeParam KeyofEvents - The key of the Discord.js ClientEvents to register for
  * @param events - The Discord.js event name(s) to listen for
+ * @param options - Options to configure the event handler registration.
  * @decorator
  * @example
  * ```typescript
@@ -861,8 +887,18 @@ declare const EventMetadataKey: unique symbol;
  *   }
  * }
  * ```
+ *
+ * @example
+ * ```ts
+ * \@RegisterEvent(Events.MessageCreate, { frequency: 'once' })
+ * class OneTimeMessageHandler extends EventHandler<Events.MessageCreate> {
+ *   async execute() {
+ *     // Handle only the first message creation
+ *   }
+ * }
+ * ```
  */
-declare function RegisterEvent<KeyofEvents extends keyof ClientEvents>(events: KeyofEvents | KeyofEvents[]): (constructor: Constructor<unknown>) => void;
+declare function RegisterEvent<KeyofEvents extends keyof ClientEvents>(events: KeyofEvents | KeyofEvents[], options?: RegisterEventOptions): (constructor: Constructor<unknown>) => void;
 
 /**
  * Enum defining interaction route types for decorators
@@ -1079,6 +1115,7 @@ declare class EventController implements Initializeable {
     private registerHandler;
     private attachToClient;
     private processEvent;
+    private processHandler;
 }
 
 /**
@@ -1596,12 +1633,55 @@ declare class EffectsEmitter {
     emit<KeyOfEffects extends EffectKeys>(event: KeyOfEffects, data: AllEffects[KeyOfEffects]): boolean;
 }
 
+/**
+ * Abstract base class for handling application side effects.
+ *
+ * Provides type-safe access to effects data and the core framework instance.
+ * Extend this class to create custom side effect handlers.
+ *
+ * @typeParam KeyOfEffects - The specific side effect type this handler processes
+ */
+declare abstract class EffectsHandler<KeyOfEffects extends EffectKeys> {
+    protected readonly data: AllEffects[KeyOfEffects];
+    protected readonly core: Core;
+    /**
+     * Creates a new effects handler instance.
+     *
+     * @param data - The effect event data
+     * @param core - The core framework instance
+     */
+    constructor(data: AllEffects[KeyOfEffects], core: Core);
+    /**
+     * Executes the effect handler logic.
+     * @virtual Override this method in your handler classes
+     */
+    abstract execute(): Promise<void>;
+}
+
 /**
  * Metadata key used to store effect handler information
  *
  * @internal
  */
 declare const EffectMetadataKey: unique symbol;
+/**
+ * Options accepted by the `@RegisterEffect` decorator.
+ */
+interface RegisterEffectOptions {
+    /** Frequency: `'once'` or `'on'`. Defaults to `'on'`. */
+    readonly frequency?: EventFrequency | undefined;
+}
+/**
+ * Metadata entry representing a registered effect handler.
+ *
+ * @internal
+ */
+interface RegisterEffectMetadataEntry {
+    /** The effect event name to register for. */
+    readonly effect: EffectKeys;
+    /** Frequency: `'once'` or `'on'`. Defaults to `'on'`. */
+    readonly frequency?: EventFrequency | undefined;
+}
 /**
  * Registers a side effect handler class with a specific side effect event.
  *
@@ -1610,6 +1690,7 @@ declare const EffectMetadataKey: unique symbol;
  *
  * @typeParam TEffect - The side effect event name to register for
  * @param effect - The side effect event name to register for
+ * @param options - Options to configure the effect handler registration.
  * @decorator
  * @example
  * ```typescript
@@ -1620,39 +1701,20 @@ declare const EffectMetadataKey: unique symbol;
  *   }
  * }
  * ```
+ * @example
+ * ```ts
+ * \@RegisterEffect('userJoin', { frequency: 'once' })
+ * // or
+ * \@RegisterEffect('userJoin')
+ * ```
  */
-declare function RegisterEffect<TEffect extends EffectKeys>(effect: TEffect): (constructor: Constructor<unknown>) => void;
-
-/**
- * Abstract base class for handling application side effects.
- *
- * Provides type-safe access to effects data and the core framework instance.
- * Extend this class to create custom side effect handlers.
- *
- * @typeParam KeyOfEffects - The specific side effect type this handler processes
- */
-declare abstract class EffectsHandler<KeyOfEffects extends EffectKeys> {
-    protected readonly data: AllEffects[KeyOfEffects];
-    protected readonly core: Core;
-    /**
-     * Creates a new effects handler instance.
-     *
-     * @param data - The effect event data
-     * @param core - The core framework instance
-     */
-    constructor(data: AllEffects[KeyOfEffects], core: Core);
-    /**
-     * Executes the effect handler logic.
-     * @virtual Override this method in your handler classes
-     */
-    abstract execute(): Promise<void>;
-}
+declare function RegisterEffect<TEffect extends EffectKeys>(effect: TEffect, options?: RegisterEffectOptions): (constructor: Constructor<unknown>) => void;
 
 /**
  * Abstract webhook logging handler for side effect events.
  *
  * Extends EffectsHandler to provide webhook-based logging capabilities.
- * Implementations must define the webhook client to send messages to.
+ * Implementations must define the `webhook client` to send messages to by implementing the webhook property.
  *
  * @typeParam KeyOfEffects - The specific side effect type this handler processes
  */
@@ -1683,4 +1745,4 @@ declare class UnknownException extends WebhookLog<'unknownException'> {
     private prepareMetadataFile;
 }
 
-export { type ActionRowComponentType, type AllEffects, type AtleastOneMessageComponent, AutocompleteHandler, type AutocompleteHandlerConstructor, AutocompleteRoute, BaseComponent, type BaseCore, BaseErrorEmbed, BaseHandler, Bot, type BotConfig, type BotPermissionScope, type BotPermissionScopeGroups, BuilderComponent, type BuilderType, BuilderTypes, ButtonRoute, CannotAssignBotRole, CannotSendEmbedsError, Catchable, type CatchableOptions, ChannelNotFoundError, ChannelNotTextChannel, Checkable, type CommandCtor, type CommandMeta, CommandMetadataKey, CommandRegistry, type CommandRouteString, type CommandScope, type CommandsConfig, type Config, ContextMenuRoute, type Core, CouldNotFindChannel, CustomError, type CustomErrorConstructor, DatabaseError, type DefaultEffects, type EffectKeys, EffectMetadataKey, type EffectParams, type Effects, type EffectsConfig, EffectsEmitter, EffectsHandler, EffectsRegistry, EmojiInjector, EventCatchable, EventController, EventHandler, type EventHandlerConstructor, EventMetadataKey, EventMiddleware, type EventMiddlewareConstructor, type EventsConfig, type ExtractedErrorResponse, GenericError, type GlobalMeta, type GuildMeta, type Handler, type HandlerConstructor, type HandlerCtor, type HandlerWithChecks, HasDangerousPermissions, type Initializeable, type InstantiatedActionRow, type InstantiatedBuilder, InteractionController, InteractionHandler, InteractionMetadataKey, InteractionMiddleware, type InteractionMiddlewareConstructor, InteractionRoutes, type InteractionsConfig, type MessageContent, Middleware, type MiddlewareConstructor, type MiddlewareMetadata, MiddlewareMetadataKey, type MiddlewareOptions, MiddlewareType, MissingPermissions, ModalRoute, PERM_GROUPS, PermissionNames, Pluggable, Plugin, type PluginArgs, type PluginCtor, RegisterCommand, RegisterEffect, RegisterEvent, type RepliableInteractionHandler, type Repliables, RoleDoesNotExist, RoleHigherThanMe, RowComponent, RowTypes, Seedcord, SelectMenuRoute, SelectMenuType, SlashRoute, UnhandledEvent, UnknownException, UserNotFound, UserNotInGuild, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionTypes, WebhookLog, type WithChecks, attemptSendDM, buildSlashRoute, checkBotPermissions, checkPermissions, extractErrorResponse, fetchGuildMember, fetchManyGuildMembers, fetchManyUsers, fetchRole, fetchText, fetchUser, getBotRole, hasPermsToAssign, sendInText, throwCustomError, updateMemberRoles };
+export { type ActionRowComponentType, type AllEffects, type AtleastOneMessageComponent, AutocompleteHandler, type AutocompleteHandlerConstructor, AutocompleteRoute, BaseComponent, type BaseCore, BaseErrorEmbed, BaseHandler, Bot, type BotConfig, type BotPermissionScope, type BotPermissionScopeGroups, BuilderComponent, type BuilderType, BuilderTypes, ButtonRoute, CannotAssignBotRole, CannotSendEmbedsError, Catchable, type CatchableOptions, ChannelNotFoundError, ChannelNotTextChannel, Checkable, type CommandCtor, type CommandMeta, CommandMetadataKey, CommandRegistry, type CommandRouteString, type CommandScope, type CommandsConfig, type Config, ContextMenuRoute, type Core, CouldNotFindChannel, CustomError, type CustomErrorConstructor, DatabaseError, type DefaultEffects, type EffectKeys, EffectMetadataKey, type EffectParams, type Effects, type EffectsConfig, EffectsEmitter, EffectsHandler, EffectsRegistry, EmojiInjector, EventCatchable, EventController, EventHandler, type EventHandlerConstructor, EventMetadataKey, EventMiddleware, type EventMiddlewareConstructor, type EventsConfig, type ExtractedErrorResponse, GenericError, type GlobalMeta, type GuildMeta, type Handler, type HandlerConstructor, type HandlerCtor, type HandlerWithChecks, HasDangerousPermissions, type Initializeable, type InstantiatedActionRow, type InstantiatedBuilder, InteractionController, InteractionHandler, InteractionMetadataKey, InteractionMiddleware, type InteractionMiddlewareConstructor, InteractionRoutes, type InteractionsConfig, type MessageContent, Middleware, type MiddlewareConstructor, type MiddlewareMetadata, MiddlewareMetadataKey, type MiddlewareOptions, MiddlewareType, MissingPermissions, ModalRoute, PERM_GROUPS, PermissionNames, Pluggable, Plugin, type PluginArgs, type PluginCtor, RegisterCommand, RegisterEffect, type RegisterEffectMetadataEntry, type RegisterEffectOptions, RegisterEvent, type RegisterEventMetadataEntry, type RegisterEventOptions, type RepliableInteractionHandler, type Repliables, RoleDoesNotExist, RoleHigherThanMe, RowComponent, RowTypes, Seedcord, SelectMenuRoute, SelectMenuType, SlashRoute, UnhandledEvent, UnknownException, UserNotFound, UserNotInGuild, type ValidEventTypes, type ValidInteractionTypes, type ValidNonInteractionTypes, WebhookLog, type WithChecks, attemptSendDM, buildSlashRoute, checkBotPermissions, checkPermissions, extractErrorResponse, fetchGuildMember, fetchManyGuildMembers, fetchManyUsers, fetchRole, fetchText, fetchUser, getBotRole, hasPermsToAssign, sendInText, throwCustomError, updateMemberRoles };