feat(interaction-handlers): add events for parse return states (#641)

* feat(interaction-handlers): add events for parse return states

* Update src/lib/types/Events.ts

Co-authored-by: Aura Román <kyradiscord@gmail.com>

---------

Co-authored-by: Aura Román <kyradiscord@gmail.com>

Author: favna

src/lib/structures/InteractionHandlerStore.ts

@@ -1,5 +1,5 @@
 import { Store } from '@sapphire/pieces';
-import { Result } from '@sapphire/result';
+import { Result, type Option } from '@sapphire/result';
 import type { Interaction } from 'discord.js';
 import { Events } from '../types/Events';
 import { InteractionHandler, InteractionHandlerTypes, type InteractionHandlerOptions } from './InteractionHandler';
@@ -27,13 +27,27 @@ export class InteractionHandlerStore extends Store<InteractionHandler> {
 			const result = await Result.fromAsync(() => handler.parse(interaction));
 			result.match({
 				ok: (option) => {
-					// If the `parse` method returned a `Some` (whatever that `Some`'s value is, it should be handled)
-					option.inspect((value) => {
-						// Schedule the run of the handler method
-						const promise = Result.fromAsync(() => handler.run(interaction, value)) //
-							.then((res) => res.mapErr((error) => ({ handler, error })));
+					// Emit an event to the user to let them know `parse` was successful
+					this.container.client.emit(Events.InteractionHandlerParseSuccess, option, { interaction, handler });
 
-						promises.push(promise);
+					option.match({
+						// If the `parse` method returned a `Some` (whatever that `Some`'s value is, it should be handled)
+						some: (value) => {
+							// Emit an event to the user to let them know parse was successful and `some` was returned.
+							this.container.client.emit(Events.InteractionHandlerParseSome, option as Option.Some<typeof value>, {
+								interaction,
+								handler,
+								value
+							});
+
+							// Schedule the run of the handler method
+							const promise = Result.fromAsync(() => handler.run(interaction, value)) //
+								.then((res) => res.mapErr((error) => ({ handler, error })));
+
+							promises.push(promise);
+						},
+						// Emit an event to the user to let them know parse was successful and `none` was returned.
+						none: () => this.container.client.emit(Events.InteractionHandlerParseNone, option as Option.None, { interaction, handler })
 					});
 				},
 				err: (error) => {

src/lib/types/Events.ts

@@ -1,4 +1,5 @@
 import type { Piece, Store } from '@sapphire/pieces';
+import type { Option } from '@sapphire/result';
 import {
 	Events as DJSEvents,
 	type AutocompleteInteraction,
@@ -246,6 +247,25 @@ export const Events = {
 	PluginLoaded: 'pluginLoaded' as const,
 
 	// Interaction handlers
+	/**
+	 * Emitted when the `parse` method of an interaction handler passes successfully (no errors are encountered)
+	 * Use the {@link option} parameter to determine if `some` or `none` was passed.
+	 * @param {Option.None | Option.Some<unknown>} option The {@link Option} from the `parse` method.
+	 * @param {InteractionHandlerParseSuccess} payload The contextual payload
+	 */
+	InteractionHandlerParseSuccess: 'interactionHandlerParseSuccess' as const,
+	/**
+	 * Emitted when the `parse` method of an interaction handler passes successfully (no errors are encountered) and `some` is returned.
+	 * @param {Option.Some<unknown>} option The {@link Option.Some} from the `parse` method.
+	 * @param {InteractionHandlerParseSome} payload The contextual payload
+	 */
+	InteractionHandlerParseSome: 'interactionHandlerParseSome' as const,
+	/**
+	 * Emitted when the `parse` method of an interaction handler passes successfully (no errors are encountered) and `none` is returned.
+	 * @param {Option.None} option The {@link Option.None} from the `parse` method.
+	 * @param {InteractionHandlerParseNone} payload The contextual payload
+	 */
+	InteractionHandlerParseNone: 'interactionHandlerParseNone' as const,
 	/**
 	 * Emitted when the `parse` method of an interaction handler encounters an error.
 	 * @param {*} error The error that was encountered
@@ -551,6 +571,17 @@ export interface IInteractionHandlerPayload {
 	handler: InteractionHandler;
 }
 
+export interface InteractionHandlerParseSuccess extends IInteractionHandlerPayload {}
+
+export interface InteractionHandlerParseSome<T = unknown> extends IInteractionHandlerPayload {
+	/**
+	 * The value that was passed to the `some` function.
+	 */
+	value: T;
+}
+
+export interface InteractionHandlerParseNone extends IInteractionHandlerPayload {}
+
 export interface InteractionHandlerParseError extends IInteractionHandlerPayload {}
 
 export interface InteractionHandlerError extends IInteractionHandlerPayload {}
@@ -597,6 +628,9 @@ declare module 'discord.js' {
 
 		[SapphireEvents.PluginLoaded]: [hook: PluginHook, name: string | undefined];
 
+		[SapphireEvents.InteractionHandlerParseSuccess]: [option: Option<unknown>, payload: InteractionHandlerParseSuccess];
+		[SapphireEvents.InteractionHandlerParseSome]: [option: Option.Some<unknown>, payload: InteractionHandlerParseSome];
+		[SapphireEvents.InteractionHandlerParseNone]: [option: Option.None, payload: InteractionHandlerParseNone];
 		[SapphireEvents.InteractionHandlerParseError]: [error: unknown, payload: InteractionHandlerParseError];
 		[SapphireEvents.InteractionHandlerError]: [error: unknown, payload: InteractionHandlerError];