commandkit 1.0.0-dev.20250611020404 → 1.0.0-dev.20250611155146

package/dist/{CommandKit-CnLBu_7m.js → CommandKit-BqZBlSaB.js}

@@ -1,23 +1,23 @@
 const require_chunk = require('./chunk-nOFOJqeH.js');
 const require_colors = require('./colors-Cd4Oz-r-.js');
-const require_error_codes = require('./error-codes-C_UO39jz.js');
-const require_warn_unstable = require('./warn-unstable-DHLaxPC8.js');
-const require_element = require('./element-DcqNz1dV.js');
-const require_EventInterceptor = require('./EventInterceptor-Bvh05z7n.js');
-const require_constants = require('./constants-CCqS_v55.js');
-const require_CompilerPlugin = require('./CompilerPlugin-DrnhOC1c.js');
-const require_RuntimePlugin = require('./RuntimePlugin-BJoDa8ZR.js');
-const require_EventWorkerContext = require('./EventWorkerContext-BAKiTqJz.js');
+const require_error_codes = require('./error-codes-CxlUBdF6.js');
+const require_warn_unstable = require('./warn-unstable-CttBdmlS.js');
+const require_element = require('./element-Cq-LoDjk.js');
+const require_EventInterceptor = require('./EventInterceptor-DWCHCGRh.js');
+const require_constants = require('./constants-DDRctWlU.js');
+const require_CompilerPlugin = require('./CompilerPlugin-Bmy4izKz.js');
+const require_RuntimePlugin = require('./RuntimePlugin-CehKbceZ.js');
+const require_EventWorkerContext = require('./EventWorkerContext-DxfS_0fJ.js');
 const require_resolve_file_url = require('./resolve-file-url-ifwdwqmq.js');
-const require_MessageCommandParser = require('./MessageCommandParser-D02-wpZN.js');
-const require_signals = require('./signals-scJdEbly.js');
-const require_constants$1 = require('./constants-DWe181uQ.js');
-const require_types_package = require('./types-package-CTSNSM93.js');
-const require_CommandsRouter = require('./CommandsRouter-BHaPno8o.js');
+const require_MessageCommandParser = require('./MessageCommandParser-Cz-3I-wL.js');
+const require_signals = require('./signals-CSSSZAZ6.js');
+const require_constants$1 = require('./constants-CXwjhIYH.js');
+const require_types_package = require('./types-package-BpY3acyl.js');
+const require_CommandsRouter = require('./CommandsRouter-DFRh47qD.js');
 const require_EventsRouter = require('./EventsRouter-CqnrlbjN.js');
-const require_common = require('./common-CW8v7gAn.js');
-const require_CommandKitEventsChannel = require('./CommandKitEventsChannel-B6LKgxmv.js');
-const require_store = require('./store-Ci6ib2C9.js');
+const require_common = require('./common-Dasi9oKU.js');
+const require_CommandKitEventsChannel = require('./CommandKitEventsChannel-BL_YN3Rm.js');
+const require_store = require('./store-x93NXUy_.js');
 const node_events = require_chunk.__toESM(require("node:events"));
 const discord_js = require_chunk.__toESM(require("discord.js"));
 const node_async_hooks = require_chunk.__toESM(require("node:async_hooks"));
@@ -29,12 +29,23 @@ const __rollup_plugin_json = require_chunk.__toESM(require("@rollup/plugin-json"
 //#region src/context/async-context.ts
 const kCommandWorker = Symbol("commandkitCommandWorker");
 const context = new node_async_hooks.AsyncLocalStorage();
+/**
+* Checks if the given worker is a CommandKit worker context.
+* @param worker The worker to check.
+* @returns True if the worker is a CommandKit worker context, false otherwise.
+*/
 function isCommandWorkerContext(worker) {
 	return worker && Reflect.get(worker, kCommandWorker) === true;
 }
 function exitContext(fn) {
 	return context.exit(fn);
 }
+/**
+* Executes the provided function within a CommandKit context.
+* @param value The CommandKit environment to use for the context.
+* @param receiver The function to execute within the context.
+* @returns The result of the receiver function.
+*/
 function provideContext(value, receiver) {
 	Reflect.set(value, kCommandWorker, true);
 	return context.run(value, receiver);
@@ -90,6 +101,9 @@ function useEnvironment() {
 
 //#endregion
 //#region src/components/v1/button/ButtonKit.ts
+/**
+* A builder for creating buttons with additional features like interaction collectors and event handling.
+*/
 var ButtonKit = class extends discord_js.ButtonBuilder {
 	#onClickHandler = null;
 	#contextData = {
@@ -196,6 +210,9 @@ var ButtonKit = class extends discord_js.ButtonBuilder {
 			return handler(interaction, this);
 		}, this.#contextData);
 	}
+	/**
+	* Disposes of the button collector and cleans up resources.
+	*/
 	dispose() {
 		this.#destroyCollector();
 		return this;
@@ -237,6 +254,11 @@ function Button(props) {
 
 //#endregion
 //#region src/components/v1/modal/ModalKit.ts
+/**
+* A builder for creating modals with additional features like interaction collectors and event handling.
+* This class extends the ModalBuilder from discord.js and adds methods for handling interactions.
+* It allows you to set a handler for when the modal is submitted, filter interactions, and handle the end of the interaction collector.
+*/
 var ModalKit = class extends discord_js.ModalBuilder {
 	#onSubmitHandler = null;
 	#contextData = {
@@ -339,6 +361,9 @@ var ModalKit = class extends discord_js.ModalBuilder {
 			return handler(interaction, this);
 		}, this.#contextData);
 	}
+	/**
+	* Disposes of the modal collector and cleans up resources.
+	*/
 	dispose() {
 		this.#destroyCollector();
 		return this;
@@ -421,6 +446,11 @@ function ParagraphInput(props) {
 
 //#endregion
 //#region src/components/v1/select-menu/StringSelectMenuKit.ts
+/**
+* A builder for creating string select menus with additional features like interaction collectors and event handling.
+* This class extends the StringSelectMenuBuilder from discord.js and adds methods for handling interactions.
+* It allows you to set a handler for when the string select menu is submitted, filter interactions, and handle the end of the interaction collector.
+*/
 var StringSelectMenuKit = class extends discord_js.StringSelectMenuBuilder {
 	#onSelectHandler = null;
 	#contextData = {
@@ -523,6 +553,9 @@ var StringSelectMenuKit = class extends discord_js.StringSelectMenuBuilder {
 			return handler(interaction, this);
 		}, this.#contextData);
 	}
+	/**
+	* Disposes of the interaction collector and cleans up resources.
+	*/
 	dispose() {
 		this.#destroyCollector();
 		return this;
@@ -538,6 +571,11 @@ var StringSelectMenuKit = class extends discord_js.StringSelectMenuBuilder {
 
 //#endregion
 //#region src/components/v1/select-menu/ChannelSelectMenuKit.ts
+/**
+* A builder for creating channel select menus with additional features like interaction collectors and event handling.
+* This class extends the ChannelSelectMenuBuilder from discord.js and adds methods for handling interactions.
+* It allows you to set a handler for when the channel select menu is submitted, filter interactions, and handle the end of the interaction collector.
+*/
 var ChannelSelectMenuKit = class extends discord_js.ChannelSelectMenuBuilder {
 	#onSelectHandler = null;
 	#contextData = {
@@ -640,6 +678,9 @@ var ChannelSelectMenuKit = class extends discord_js.ChannelSelectMenuBuilder {
 			return handler(interaction, this);
 		}, this.#contextData);
 	}
+	/**
+	* Cleans up the interaction collector and removes the handler.
+	*/
 	dispose() {
 		this.#destroyCollector();
 		return this;
@@ -757,6 +798,9 @@ var MentionableSelectMenuKit = class extends discord_js.MentionableSelectMenuBui
 			return handler(interaction, this);
 		}, this.#contextData);
 	}
+	/**
+	* Disposes of the mentionable select menu kit, cleaning up any resources used by the interaction collector.
+	*/
 	dispose() {
 		this.#destroyCollector();
 		return this;
@@ -772,6 +816,11 @@ var MentionableSelectMenuKit = class extends discord_js.MentionableSelectMenuBui
 
 //#endregion
 //#region src/components/v1/select-menu/UserSelectMenuKit.ts
+/**
+* A builder for creating user select menus with additional features like interaction collectors and event handling.
+* This class extends the UserSelectMenuBuilder from discord.js and adds methods for handling interactions.
+* It allows you to set a handler for when the user select menu is submitted, filter interactions, and handle the end of the interaction collector.
+*/
 var UserSelectMenuKit = class extends discord_js.UserSelectMenuBuilder {
 	#onSelectHandler = null;
 	#contextData = {
@@ -874,6 +923,9 @@ var UserSelectMenuKit = class extends discord_js.UserSelectMenuBuilder {
 			return handler(interaction, this);
 		}, this.#contextData);
 	}
+	/**
+	* Disposes of the user select menu kit, cleaning up any collectors and handlers.
+	*/
 	dispose() {
 		this.#destroyCollector();
 		return this;
@@ -889,6 +941,11 @@ var UserSelectMenuKit = class extends discord_js.UserSelectMenuBuilder {
 
 //#endregion
 //#region src/components/v1/select-menu/RoleSelectMenuKit.ts
+/**
+* A builder for creating role select menus with additional features like interaction collectors and event handling.
+* This class extends the RoleSelectMenuBuilder from discord.js and adds methods for handling interactions.
+* It allows you to set a handler for when the role select menu is submitted, filter interactions, and handle the end of the interaction collector.
+*/
 var RoleSelectMenuKit = class extends discord_js.RoleSelectMenuBuilder {
 	#onSelectHandler = null;
 	#contextData = {
@@ -991,6 +1048,9 @@ var RoleSelectMenuKit = class extends discord_js.RoleSelectMenuBuilder {
 			return handler(interaction, this);
 		}, this.#contextData);
 	}
+	/**
+	* Disposes of the role select menu kit, cleaning up any resources and event listeners.
+	*/
 	dispose() {
 		this.#destroyCollector();
 		return this;
@@ -1006,6 +1066,9 @@ var RoleSelectMenuKit = class extends discord_js.RoleSelectMenuBuilder {
 
 //#endregion
 //#region src/components/v1/select-menu/SelectMenu.ts
+/**
+* @private
+*/
 function applyPropsToBuilder(builder, props) {
 	builder.setCustomId(props.customId ?? `select-menu::${crypto.randomUUID()}`);
 	if (props.maxValues != null) builder.setMaxValues(props.maxValues);
@@ -1016,6 +1079,24 @@ function applyPropsToBuilder(builder, props) {
 	if (props.onError) builder.onError(props.onError);
 	if (props.onSelect) builder.onSelect(props.onSelect, props.options);
 }
+/**
+* The StringSelectMenu component.
+* @param props The properties for the string select menu component.
+* @returns The string select menu builder instance.
+* @example ```tsx
+* import { StringSelectMenu } from 'commandkit';
+*
+* const stringSelectMenu = <StringSelectMenu
+*   customId="my-select-menu"
+*   placeholder="Select an option"
+*   maxValues={1}
+*   minValues={1}
+* >
+*   <StringSelectMenuOption label="Option 1" value="option1" />
+*   <StringSelectMenuOption label="Option 2" value="option2" />
+* </StringSelectMenu>
+* ```
+*/
 function StringSelectMenu(props) {
 	const builder = new StringSelectMenuKit();
 	applyPropsToBuilder(builder, props);
@@ -1023,27 +1104,75 @@ function StringSelectMenu(props) {
 	if (props.children) builder.setOptions(Array.isArray(props.children) ? props.children : [props.children]);
 	return builder;
 }
+/**
+* A select menu option for the string select menu.
+* @param props The properties for the string select menu option.
+* @returns The string select menu option builder instance.
+* @example ```tsx
+* import { StringSelectMenuOption } from 'commandkit';
+*
+* const option = <StringSelectMenuOption label="Option 1" value="option1" />;
+* ```
+*/
 function StringSelectMenuOption(props) {
 	return new discord_js.StringSelectMenuOptionBuilder(props);
 }
+/**
+* The UserSelectMenu component.
+* @param props The properties for the user select menu component.
+* @returns The user select menu builder instance.
+* @example ```tsx
+* import { UserSelectMenu } from 'commandkit';
+*
+* const userSelectMenu = <UserSelectMenu />
+* ```
+*/
 function UserSelectMenu(props) {
 	const builder = new UserSelectMenuKit();
 	applyPropsToBuilder(builder, props);
 	if (props.defaultValues) builder.setDefaultUsers(Array.isArray(props.defaultValues) ? props.defaultValues : [props.defaultValues]);
 	return builder;
 }
+/**
+* The RoleSelectMenu component.
+* @param props The properties for the role select menu component.
+* @returns The role select menu builder instance.
+* @example ```tsx
+* import { RoleSelectMenu } from 'commandkit';
+*
+* const roleSelectMenu = <RoleSelectMenu />
+* ```
+*/
 function RoleSelectMenu(props) {
 	const builder = new RoleSelectMenuKit();
 	applyPropsToBuilder(builder, props);
 	if (props.defaultValues) builder.setDefaultRoles(Array.isArray(props.defaultValues) ? props.defaultValues : [props.defaultValues]);
 	return builder;
 }
+/**
+* The MentionableSelectMenu component.
+* @param props The properties for the mentionable select menu component.
+* @returns The mentionable select menu builder instance.
+* @example ```tsx
+* import { MentionableSelectMenu } from 'commandkit';
+* const mentionableSelectMenu = <MentionableSelectMenu />
+* ```
+*/
 function MentionableSelectMenu(props) {
 	const builder = new MentionableSelectMenuKit();
 	applyPropsToBuilder(builder, props);
 	if (props.defaultValues) builder.setDefaultValues(Array.isArray(props.defaultValues) ? props.defaultValues : [props.defaultValues]);
 	return builder;
 }
+/**
+* The ChannelSelectMenu component.
+* @param props The properties for the channel select menu component.
+* @returns The channel select menu builder instance.
+* @example ```tsx
+* import { ChannelSelectMenu } from 'commandkit';
+* const channelSelectMenu = <ChannelSelectMenu />
+* ```
+*/
 function ChannelSelectMenu(props) {
 	const builder = new ChannelSelectMenuKit();
 	applyPropsToBuilder(builder, props);
@@ -1054,6 +1183,9 @@ function ChannelSelectMenu(props) {
 
 //#endregion
 //#region src/logger/DefaultLogger.ts
+/**
+* Log levels for the logger.
+*/
 var LogLevel = /* @__PURE__ */ function(LogLevel$1) {
 	LogLevel$1[LogLevel$1["DEBUG"] = 0] = "DEBUG";
 	LogLevel$1[LogLevel$1["INFO"] = 1] = "INFO";
@@ -1090,8 +1222,17 @@ const BoxChars = {
 	verticalRight: "├",
 	corner: "└"
 };
+/**
+* Default logger implementation that logs messages to the console.
+* It formats the log messages with timestamps, log levels, and context information.
+*/
 var DefaultLogger = class {
 	logger;
+	/**
+	* Creates a new instance of DefaultLogger.
+	* @param stdout The output stream for standard messages (default: process.stdout).
+	* @param stderr The output stream for error messages (default: process.stderr).
+	*/
 	constructor(stdout = process.stdout, stderr = process.stderr) {
 		this.stdout = stdout;
 		this.stderr = stderr;
@@ -1151,18 +1292,38 @@ var DefaultLogger = class {
 		if (context$1) this.logger.log(`${prefix}\n${context$1} ${require_colors.colors_default.dim(BoxChars.corner)}`, ...args.map((arg) => colorFn(arg)));
 		else this.logger.log(`${prefix} ${require_colors.colors_default.dim(BoxChars.corner)}`, ...args.map((arg) => colorFn(arg)));
 	}
+	/**
+	* Logs a debug message.
+	* @param args The message arguments to log.
+	*/
 	debug(...args) {
 		this._log(LogLevel.DEBUG, ...args);
 	}
+	/**
+	* Logs an error message.
+	* @param args The message arguments to log.
+	*/
 	error(...args) {
 		this._log(LogLevel.ERROR, ...args);
 	}
+	/**
+	* Logs a default message.
+	* @param args The message arguments to log.
+	*/
 	log(...args) {
 		this._log(LogLevel.DEFAULT, ...args);
 	}
+	/**
+	* Logs an info message.
+	* @param args The message arguments to log.
+	*/
 	info(...args) {
 		this._log(LogLevel.INFO, ...args);
 	}
+	/**
+	* Logs a warning message.
+	* @param args The message arguments to log.
+	*/
 	warn(...args) {
 		this._log(LogLevel.WARN, ...args);
 	}
@@ -1170,6 +1331,11 @@ var DefaultLogger = class {
 
 //#endregion
 //#region src/logger/Logger.ts
+/**
+* Creates a new logger instance with the specified options.
+* @param options The options for configuring the logger.
+* @returns A new logger instance.
+*/
 function createLogger(options) {
 	let opt = options;
 	if (!(opt === null || opt === void 0 ? void 0 : opt.provider)) throw new Error("A logger provider must be provided.");
@@ -1188,21 +1354,53 @@ function createLogger(options) {
 	};
 	return impl;
 }
+/**
+* Default logger instance for CommandKit. This logger uses the DefaultLogger as its provider.
+* The provider can be replaced with a custom logger implementation using the `configure` method.
+*/
 const Logger = createLogger({ provider: new DefaultLogger() });
 
 //#endregion
 //#region src/plugins/plugin-runtime/CommandKitPluginRuntime.ts
+/**
+* Represents the runtime environment for CommandKit plugins.
+*/
 var CommandKitPluginRuntime = class {
 	plugins = new discord_js.Collection();
+	/**
+	* Creates a new instance of CommandKitPluginRuntime.
+	* @param commandkit The CommandKit instance associated with this runtime.
+	*/
 	constructor(commandkit$1) {
 		this.commandkit = commandkit$1;
 	}
+	/**
+	* Returns the plugins registered in this runtime.
+	* @returns A collection of plugins.
+	*/
 	getPlugins() {
 		return this.plugins;
 	}
+	/**
+	* Checks if there are no plugins registered in this runtime.
+	* @param pluginName The name of the plugin to check.
+	* @returns Boolean indicating whether the runtime is empty.
+	*/
 	getPlugin(pluginName) {
 		return this.plugins.get(pluginName) ?? null;
 	}
+	/**
+	* Fetches the given plugin
+	* @param plugin The plugin to be fetched.
+	*/
+	get(plugin) {
+		const p = this.plugins.find((p$1) => p$1 instanceof plugin) ?? null;
+		return p;
+	}
+	/**
+	* Soft registers a plugin in the runtime.
+	* @param plugin The plugin to be registered.
+	*/
 	async softRegisterPlugin(plugin) {
 		const pluginName = plugin.name;
 		if (this.plugins.has(pluginName)) return;
@@ -1213,6 +1411,11 @@ var CommandKitPluginRuntime = class {
 			throw new Error(`Failed to activate plugin "${pluginName}": ${(e === null || e === void 0 ? void 0 : e.stack) || e}`);
 		}
 	}
+	/**
+	* Registers a plugin in the runtime.
+	* @param plugin The plugin to be registered.
+	* @throws If a plugin with the same name already exists.
+	*/
 	async registerPlugin(plugin) {
 		const pluginName = plugin.name;
 		if (this.plugins.has(pluginName)) throw new Error(`Plugin with name "${pluginName}" already exists.`);
@@ -1223,6 +1426,11 @@ var CommandKitPluginRuntime = class {
 			throw new Error(`Failed to activate plugin "${pluginName}": ${(e === null || e === void 0 ? void 0 : e.stack) || e}`);
 		}
 	}
+	/**
+	* Unregisters a plugin from the runtime.
+	* @param plugin The plugin to be unregistered.
+	* @throws If the plugin does not exist.
+	*/
 	async unregisterPlugin(plugin) {
 		const pluginName = plugin.name;
 		if (!this.plugins.has(pluginName)) throw new Error(`Plugin with name "${pluginName}" does not exist.`);
@@ -1233,12 +1441,23 @@ var CommandKitPluginRuntime = class {
 			throw new Error(`Failed to deactivate plugin "${pluginName}": ${(e === null || e === void 0 ? void 0 : e.stack) || e}`);
 		}
 	}
+	/**
+	* Unregisters all plugins from the runtime.
+	*/
 	async unregisterAllPlugins() {
 		for (const plugin of this.plugins.values()) await this.unregisterPlugin(plugin);
 	}
+	/**
+	* Signals the runtime to allow the current plugin take ownership of the execution context.
+	*/
 	capture() {
 		throw require_error_codes.createCommandKitError(require_error_codes.CommandKitErrorCodes.PluginCaptureHandle);
 	}
+	/**
+	* Executes a function for each plugin in the runtime.
+	* @param f The function to execute for each plugin.
+	* @returns The result of the last executed function, or undefined if no plugins were executed.
+	*/
 	async execute(f) {
 		let result;
 		for (const plugin of this.plugins.values()) try {
@@ -1253,6 +1472,9 @@ var CommandKitPluginRuntime = class {
 
 //#endregion
 //#region src/plugins/plugin-runtime/builtin/CommonDirectiveTransformer.ts
+/**
+* Common directive transformer plugin is a compiler plugin that transforms directives to higher-order functions.
+*/
 var CommonDirectiveTransformer = class extends require_CompilerPlugin.CompilerPlugin {
 	transformer = null;
 	async activate(ctx) {
@@ -1276,6 +1498,18 @@ var CommonDirectiveTransformer = class extends require_CompilerPlugin.CompilerPl
 
 //#endregion
 //#region src/plugins/plugin-runtime/builtin/MacroPlugin.ts
+/**
+* Macro plugin enables the use of `"use macro"` directive in the code.
+* Functions with this directive will be transformed at compile time
+* and only the result will be included in the final bundle.
+* @example function myMacro() {
+*   "use macro";
+*   return Math.random();
+* }
+*
+* // This will be transformed to a constant value at compile time.
+* const result = myMacro();
+*/
 var MacroPlugin = class extends require_CompilerPlugin.CompilerPlugin {
 	name = "MacroPlugin";
 	macroTransformer;
@@ -1299,6 +1533,9 @@ var MacroPlugin = class extends require_CompilerPlugin.CompilerPlugin {
 
 //#endregion
 //#region src/config/default.ts
+/**
+* Default configuration for CommandKit.
+*/
 const defaultConfig = {
 	plugins: [new MacroPlugin({ enabled: true })],
 	rolldownPlugins: [(0, __rollup_plugin_json.default)()],
@@ -1364,6 +1601,10 @@ function getSrcDir() {
 	if (require_constants.COMMANDKIT_IS_DEV) return ".commandkit";
 	return getConfig().distDir;
 }
+/**
+* Returns the current working directory of the CommandKit application.
+* This is typically the directory where the source code is located.
+*/
 function getCurrentDirectory() {
 	if (currentDir) return currentDir;
 	const src = getSrcDir();
@@ -1372,6 +1613,11 @@ function getCurrentDirectory() {
 	currentDir = root;
 	return root;
 }
+/**
+* Returns the possible source directories for the CommandKit application.
+* This includes the `src`, `.commandkit`, and the distribution directory.
+* @returns An array of possible source directories.
+*/
 function getSourceDirectories() {
 	const dist = getConfig().distDir;
 	const locations = [
@@ -1401,6 +1647,14 @@ function findAppDirectory() {
 * @param fn The function to debounce.
 * @param ms The debounce time in milliseconds.
 * @returns The debounced function.
+* @example
+* const debouncedFn = debounce(() => {
+*   console.log('Debounced function called');
+* }, 300);
+*
+* debouncedFn(); // Will only execute after 300ms of inactivity
+* debouncedFn(); // Will reset the timer
+* debouncedFn(); // Will reset the timer again
 */
 function debounce(fn, ms) {
 	let timer = null;
@@ -1424,6 +1678,13 @@ function debounce(fn, ms) {
 /**
 * Defers the execution of a function.
 * @param fn The function to defer.
+* @param timeout The time in milliseconds to wait before executing the function. Defaults to 0.
+* @example
+* defer(() => {
+*   console.log('This will run after a delay');
+* });
+*
+* console.log('This will run immediately');
 */
 function defer(fn, timeout = 0) {
 	setTimeout(() => {
@@ -1471,8 +1732,17 @@ var StopEventPropagationError = class extends Error {
 	}
 };
 /**
-* Stops event propagation.
+* Stops event propagation. This function should be called inside an event handler
+* to prevent further event handling.
 * @throws {StopEventPropagationError}
+* @example // src/app/events/messageCreate/handler.ts
+* import { stopEvents } from 'commandkit';
+*
+* export default async function messageCreateHandler() {
+*   console.log('Message created');
+*   // Stop further event propagation
+*   stopEvents();
+* }
 */
 function stopEvents() {
 	if (!require_EventWorkerContext.eventWorkerContext.getStore()) throw new Error("stopEvents() may only be called inside an event handler");
@@ -1536,7 +1806,14 @@ function createProxy(target) {
 
 //#endregion
 //#region src/app/register/CommandRegistrar.ts
+/**
+* Handles registration of Discord application commands (slash commands, context menus).
+*/
 var CommandRegistrar = class {
+	/**
+	* @private
+	* @internal
+	*/
 	api = new discord_js.REST();
 	/**
 	* Creates an instance of CommandRegistrar.
@@ -1690,6 +1967,9 @@ var CommandRegistrar = class {
 
 //#endregion
 //#region src/context/environment.ts
+/**
+* Represents the execution environment for CommandKit commands.
+*/
 var CommandKitEnvironment = class {
 	#data = {
 		executionError: null,
@@ -1835,9 +2115,19 @@ let CommandKitEnvironmentType = /* @__PURE__ */ function(CommandKitEnvironmentTy
 	return CommandKitEnvironmentType$1;
 }({});
 /**
-* Runs the given function after the current command has finished executing.
+* Schedules the given function to run after the current command has finished executing.
 * @param fn The function to run after the current command.
 * @returns The deferred function id. This can be used to cancel the deferred function.
+* @example import { after } from 'commandkit';
+*
+* // inside a command
+* export const chatInput: ChatInputCommand = async (ctx) => {
+*   after(() => {
+*     console.log('This will run after the command has finished executing.');
+*   });
+*
+*   // ... command logic
+* }
 */
 function after(fn) {
 	const env = getContext();
@@ -1847,6 +2137,16 @@ function after(fn) {
 /**
 * Cancels a deferred function registered with `after`.
 * @param id The deferred function id to cancel.
+* @example import { cancelAfter } from 'commandkit';
+* // inside a command
+* export const chatInput: ChatInputCommand = async (ctx) => {
+*   const id = after(() => {
+*     console.log('This will run after the command has finished executing.');
+*   });
+*
+*  // cancel the deferred function if needed
+*  if (something) cancelAfter(id);
+* }
 */
 function cancelAfter(id) {
 	const env = getContext();
@@ -1856,6 +2156,9 @@ function cancelAfter(id) {
 
 //#endregion
 //#region src/app/commands/Context.ts
+/**
+* Enumeration of different command execution modes supported by CommandKit.
+*/
 const CommandExecutionMode = {
 	ChatInputCommand: "chatInput",
 	MessageContextMenu: "messageContextMenu",
@@ -1863,6 +2166,10 @@ const CommandExecutionMode = {
 	Autocomplete: "autocomplete",
 	Message: "message"
 };
+/**
+* Represents the execution context for a command, providing access to Discord.js objects,
+* command metadata, and various utility methods for command execution.
+*/
 var Context = class Context {
 	/**
 	* The interaction that triggered the command.
@@ -1896,7 +2203,15 @@ var Context = class Context {
 	* The command that this context belongs to.
 	*/
 	command;
+	/**
+	* @private
+	* @internal
+	*/
 	#store;
+	/**
+	* @private
+	* @internal
+	*/
 	_locale = null;
 	/**
 	* Creates a new command context.
@@ -1932,10 +2247,16 @@ var Context = class Context {
 	get store() {
 		return this.#store;
 	}
+	/**
+	* Gets the name of the current command.
+	*/
 	get commandName() {
 		if (this.isInteraction()) return this.interaction.commandName;
 		else return this.config.messageCommandParser.getCommand();
 	}
+	/**
+	* Gets the command options based on the execution mode.
+	*/
 	get options() {
 		if (this.isMessage()) {
 			const parser = this.config.messageCommandParser;
@@ -2062,6 +2383,7 @@ var Context = class Context {
 	}
 	/**
 	* Creates a clone of this context
+	* @param config - Optional partial config to override in the clone
 	*/
 	clone(config) {
 		if (!config) return new Context(this.commandkit, this.config);
@@ -2072,9 +2394,16 @@ var Context = class Context {
 		});
 		return ctx;
 	}
+	/**
+	* Checks if this context is a middleware context.
+	*/
 	isMiddleware() {
 		return this instanceof MiddlewareContext;
 	}
+	/**
+	* Gets the command arguments (only available for message commands).
+	* @returns Array of command arguments
+	*/
 	args() {
 		if (this.isMessage()) return this.config.messageCommandParser.getArgs();
 		return [];
@@ -2089,7 +2418,14 @@ var Context = class Context {
 		require_signals.exitMiddleware();
 	}
 };
+/**
+* Extended context class for middleware execution with additional control methods.
+*/
 var MiddlewareContext = class extends Context {
+	/**
+	* @private
+	* @internal
+	*/
 	#cancel = false;
 	/**
 	* Whether the command execution was cancelled.
@@ -2120,11 +2456,25 @@ var MiddlewareContext = class extends Context {
 
 //#endregion
 //#region src/app/commands/AppCommandRunner.ts
+/**
+* Handles the execution of application commands for CommandKit.
+* Manages middleware execution, environment setup, and command invocation.
+*/
 var AppCommandRunner = class {
+	/**
+	* Creates a new AppCommandRunner instance.
+	* @param handler - The app command handler instance to use for command execution
+	*/
 	constructor(handler) {
 		this.handler = handler;
 	}
-	async runCommand(prepared, source) {
+	/**
+	* Executes a prepared command with middleware support and environment setup.
+	* Handles the complete command lifecycle including before/after middleware execution.
+	* @param prepared - The prepared command execution data
+	* @param source - The source interaction or message that triggered the command
+	*/
+	async runCommand(prepared, source, options) {
 		const { commandkit: commandkit$1 } = this.handler;
 		const executionMode = this.getExecutionMode(source);
 		let runCommand = null;
@@ -2133,6 +2483,7 @@ var AppCommandRunner = class {
 		env.variables.set("commandHandlerType", "app");
 		env.variables.set("currentCommandName", prepared.command.command.name);
 		env.variables.set("execHandlerKind", executionMode);
+		env.variables.set("customHandler", (options === null || options === void 0 ? void 0 : options.handler) ?? null);
 		const ctx = new MiddlewareContext(commandkit$1, {
 			command: prepared.command,
 			environment: env,
@@ -2161,9 +2512,10 @@ var AppCommandRunner = class {
 				}
 			}
 		});
+		let result;
 		if (!ctx.cancelled) {
 			const targetData = prepared.command.data;
-			const fn = targetData[executionMode];
+			const fn = targetData[(options === null || options === void 0 ? void 0 : options.handler) || executionMode];
 			if (!fn) Logger.warn(`Command ${prepared.command.command.name} has no handler for ${executionMode}`);
 			const analytics = commandkit$1.analytics;
 			if (fn) try {
@@ -2210,7 +2562,7 @@ var AppCommandRunner = class {
 				const res = await commandkit$1.plugins.execute(async (ctx$1, plugin) => {
 					return plugin.executeCommand(ctx$1, env, source, prepared, executeCommand);
 				});
-				if (!res) await executeCommand();
+				if (!res) result = await executeCommand();
 			} catch (e) {
 				if (require_error_codes.isErrorType(e, require_error_codes.CommandKitErrorCodes.ExitMiddleware)) middlewaresCanceled = true;
 				if (!require_error_codes.isErrorType(e, [require_error_codes.CommandKitErrorCodes.ForwardedCommand, require_error_codes.CommandKitErrorCodes.ExitMiddleware])) Logger.error(e);
@@ -2227,7 +2579,13 @@ var AppCommandRunner = class {
 				}
 			}
 		});
+		return result;
 	}
+	/**
+	* @private
+	* @internal
+	* Finalizes command execution by running deferred functions and plugin cleanup.
+	*/
 	async #finalizer() {
 		const env = useEnvironment();
 		await env.runDeferredFunctions();
@@ -2236,6 +2594,11 @@ var AppCommandRunner = class {
 			await plugin.onAfterCommand(ctx, env);
 		});
 	}
+	/**
+	* Determines the execution mode based on the source of the command.
+	* @param source - The interaction or message that triggered the command
+	* @returns The appropriate command execution mode
+	*/
 	getExecutionMode(source) {
 		if (source instanceof discord_js.Message) return CommandExecutionMode.Message;
 		if (source.isChatInputCommand()) return CommandExecutionMode.ChatInputCommand;
@@ -2248,6 +2611,10 @@ var AppCommandRunner = class {
 
 //#endregion
 //#region src/app/handlers/AppCommandHandler.ts
+/**
+* @private
+* @internal
+*/
 const commandDataSchema = {
 	command: (c) => c instanceof discord_js.SlashCommandBuilder || c instanceof discord_js.ContextMenuCommandBuilder || c && typeof c === "object",
 	chatInput: (c) => typeof c === "function",
@@ -2256,25 +2623,76 @@ const commandDataSchema = {
 	messageContextMenu: (c) => typeof c === "function",
 	userContextMenu: (c) => typeof c === "function"
 };
+/**
+* @private
+* @internal
+*/
 const middlewareDataSchema = {
 	beforeExecute: (c) => typeof c === "function",
 	afterExecute: (c) => typeof c === "function"
 };
+/**
+* Handles application commands for CommandKit, including loading, registration, and execution.
+* Manages both slash commands and message commands with middleware support.
+*/
 var AppCommandHandler = class {
+	/**
+	* @private
+	* @internal
+	*/
 	loadedCommands = new discord_js.Collection();
+	/**
+	* @private
+	* @internal
+	*/
 	loadedMiddlewares = new discord_js.Collection();
+	/**
+	* @private
+	* @internal
+	*/
 	commandNameToId = /* @__PURE__ */ new Map();
+	/**
+	* @private
+	* @internal
+	*/
 	subcommandPathToId = /* @__PURE__ */ new Map();
+	/**
+	* Command registrar for handling Discord API registration.
+	*/
 	registrar;
+	/**
+	* @private
+	* @internal
+	*/
 	onInteraction = null;
+	/**
+	* @private
+	* @internal
+	*/
 	onMessageCreate = null;
+	/**
+	* Command runner instance for executing commands.
+	*/
 	commandRunner = new AppCommandRunner(this);
+	/**
+	* External command data storage.
+	*/
 	externalCommandData = new discord_js.Collection();
+	/**
+	* External middleware data storage.
+	*/
 	externalMiddlewareData = new discord_js.Collection();
+	/**
+	* Creates a new AppCommandHandler instance.
+	* @param commandkit - The CommandKit instance
+	*/
 	constructor(commandkit$1) {
 		this.commandkit = commandkit$1;
 		this.registrar = new CommandRegistrar(this.commandkit);
 	}
+	/**
+	* Prints a formatted banner showing all loaded commands organized by category.
+	*/
 	printBanner() {
 		const uncategorized = crypto.randomUUID();
 		const categorizedCommands = this.getCommandsArray().reduce((acc, cmd) => {
@@ -2350,9 +2768,16 @@ var AppCommandHandler = class {
 			printCategory(category, "", isLast);
 		});
 	}
+	/**
+	* Gets an array of all loaded commands.
+	* @returns Array of loaded commands
+	*/
 	getCommandsArray() {
 		return Array.from(this.loadedCommands.values());
 	}
+	/**
+	* Registers event handlers for Discord interactions and messages.
+	*/
 	registerCommandHandler() {
 		this.onInteraction ??= async (interaction) => {
 			const success = await this.commandkit.plugins.execute(async (ctx, plugin) => {
@@ -2378,6 +2803,12 @@ var AppCommandHandler = class {
 		this.commandkit.client.on(discord_js.Events.InteractionCreate, this.onInteraction);
 		this.commandkit.client.on(discord_js.Events.MessageCreate, this.onMessageCreate);
 	}
+	/**
+	* Prepares a command for execution by resolving the command and its middleware.
+	* @param source - The interaction or message that triggered the command
+	* @param cmdName - Optional command name override
+	* @returns Prepared command execution data or null if command not found
+	*/
 	async prepareCommandRun(source, cmdName) {
 		var _loadedCommand$guilds2;
 		let parser;
@@ -2427,6 +2858,9 @@ var AppCommandHandler = class {
 			messageCommandParser: parser
 		};
 	}
+	/**
+	* Reloads all commands and middleware from scratch.
+	*/
 	async reloadCommands() {
 		this.loadedCommands.clear();
 		this.loadedMiddlewares.clear();
@@ -2436,27 +2870,46 @@ var AppCommandHandler = class {
 		this.externalMiddlewareData.clear();
 		await this.loadCommands();
 	}
+	/**
+	* Adds external middleware data to be loaded.
+	* @param data - Array of middleware data to add
+	*/
 	async addExternalMiddleware(data) {
 		for (const middleware of data) {
 			if (!middleware.id) continue;
 			this.externalMiddlewareData.set(middleware.id, middleware);
 		}
 	}
+	/**
+	* Adds external command data to be loaded.
+	* @param data - Array of command data to add
+	*/
 	async addExternalCommands(data) {
 		for (const command of data) {
 			if (!command.id) continue;
 			this.externalCommandData.set(command.id, command);
 		}
 	}
+	/**
+	* Registers externally loaded middleware.
+	* @param data - Array of loaded middleware to register
+	*/
 	async registerExternalLoadedMiddleware(data) {
 		for (const middleware of data) this.loadedMiddlewares.set(middleware.middleware.id, middleware);
 	}
+	/**
+	* Registers externally loaded commands.
+	* @param data - Array of loaded commands to register
+	*/
 	async registerExternalLoadedCommands(data) {
 		for (const command of data) {
 			this.loadedCommands.set(command.command.id, command);
 			this.commandNameToId.set(command.command.name, command.command.id);
 		}
 	}
+	/**
+	* Loads all commands and middleware from the router.
+	*/
 	async loadCommands() {
 		await this.commandkit.plugins.execute((ctx, plugin) => {
 			return plugin.onBeforeCommandsLoad(ctx);
@@ -2473,6 +2926,10 @@ var AppCommandHandler = class {
 			return plugin.onAfterCommandsLoad(ctx);
 		});
 	}
+	/**
+	* @private
+	* @internal
+	*/
 	async loadMiddleware(id, middleware) {
 		try {
 			const data = await import(`${require_resolve_file_url.toFileURL(middleware.path)}?t=${Date.now()}`);
@@ -2490,6 +2947,10 @@ var AppCommandHandler = class {
 			Logger.error(`Failed to load middleware ${id}`, error);
 		}
 	}
+	/**
+	* @private
+	* @internal
+	*/
 	async loadCommand(id, command) {
 		try {
 			if (command.path === null) {
@@ -2533,11 +2994,26 @@ var AppCommandHandler = class {
 
 //#endregion
 //#region src/app/handlers/AppEventsHandler.ts
+/**
+* Handles Discord.js events and CommandKit custom events with support for namespacing and middleware.
+*/
 var AppEventsHandler = class {
+	/**
+	* @private
+	* @internal
+	*/
 	loadedEvents = new discord_js.Collection();
+	/**
+	* Creates a new AppEventsHandler instance.
+	* @param commandkit - The CommandKit instance
+	*/
 	constructor(commandkit$1) {
 		this.commandkit = commandkit$1;
 	}
+	/**
+	* Gets information about all loaded events.
+	* @returns Array of loaded event data
+	*/
 	getEvents() {
 		if (this.loadedEvents.size === 0) return [];
 		const events = this.loadedEvents.toJSON();
@@ -2549,10 +3025,16 @@ var AppEventsHandler = class {
 			metadata: event.event
 		}));
 	}
+	/**
+	* Reloads all events by unregistering existing ones and loading them again.
+	*/
 	async reloadEvents() {
 		this.unregisterAll();
 		await this.loadEvents();
 	}
+	/**
+	* Loads all events from the events router and registers them with Discord.js client.
+	*/
 	async loadEvents() {
 		await this.commandkit.plugins.execute((ctx, plugin) => {
 			return plugin.onBeforeEventsLoad(ctx);
@@ -2585,10 +3067,16 @@ var AppEventsHandler = class {
 			return plugin.onAfterEventsLoad(ctx);
 		});
 	}
+	/**
+	* Unregisters all event listeners and clears loaded events.
+	*/
 	unregisterAll() {
 		this.unregisterAllClientListeners();
 		this.loadedEvents.clear();
 	}
+	/**
+	* Registers all loaded events with the Discord.js client and CommandKit event system.
+	*/
 	registerAllClientEvents() {
 		const client = this.commandkit.client;
 		for (const [key, data] of this.loadedEvents.entries()) {
@@ -2698,6 +3186,9 @@ var AppEventsHandler = class {
 			Logger.info(`🔌 Registered event ${name}${namespace ? ` of namespace ${namespace}` : ""} (${onListeners.length} regular, ${onceListeners.length} once-only)`);
 		}
 	}
+	/**
+	* Unregisters all client event listeners and cleans up loaded events.
+	*/
 	unregisterAllClientListeners() {
 		const client = this.commandkit.client;
 		for (const [key, { name, mainListener, namespace }] of this.loadedEvents.entries()) {
@@ -2719,6 +3210,12 @@ const CONFIG_FILE_NAMES = [
 	"commandkit.config.cjs",
 	"commandkit.config.ts"
 ];
+/**
+* Returns an array of possible configuration file paths based on the provided root directory.
+* @param root The root directory to search for configuration files.
+* @returns The array of possible configuration file paths.
+* @private
+*/
 function getPossibleConfigPaths(root) {
 	return CONFIG_FILE_NAMES.map((name) => (0, node_path.join)(root, name));
 }
@@ -2746,6 +3243,10 @@ async function loadConfigFile(entrypoint = process.cwd()) {
 
 //#endregion
 //#region src/utils/dev-hooks.ts
+/**
+* Registers development hooks for CommandKit to handle HMR (Hot Module Replacement) events.
+* @param commandkit - The CommandKit instance to register hooks for.
+*/
 function registerDevHooks(commandkit$1) {
 	if (!require_constants.COMMANDKIT_IS_DEV) return;
 	process.on("message", async (message) => {
@@ -2797,6 +3298,10 @@ function registerDevHooks(commandkit$1) {
 
 //#endregion
 //#region src/analytics/utils.ts
+/**
+* @private
+* @internal
+*/
 function getVariableStore() {
 	const ctx = getContext();
 	if (!ctx) try {
@@ -2807,10 +3312,23 @@ function getVariableStore() {
 	}
 	return ctx.variables;
 }
+/**
+* @private
+* @internal
+*/
 function getDoNotTrack() {
 	const variables = getVariableStore();
 	return (variables === null || variables === void 0 ? void 0 : variables.get(require_constants$1.DO_NOT_TRACK_KEY)) === true;
 }
+/**
+* Signals commandkit to not track further analytics events within current context.
+* This is useful for scenarios where you want to disable analytics tracking
+* for a specific command or operation, such as during testing or when the user opts out.
+* @example import { noAnalytics } from 'commandkit/analytics';
+*
+* // inside commandkit context
+* noAnalytics();
+*/
 function noAnalytics() {
 	const variables = getVariableStore();
 	if (!variables) throw new Error("noAnalytics may only be used inside commandkit context");
@@ -2819,25 +3337,59 @@ function noAnalytics() {
 
 //#endregion
 //#region src/analytics/analytics-engine.ts
+/**
+* AnalyticsEngine class for managing analytics providers and tracking events.
+* This class allows you to register a provider, set a filter for events, and track or identify events.
+*/
 var AnalyticsEngine = class {
 	#provider = null;
 	#filter = null;
+	/**
+	* Creates an instance of the AnalyticsEngine.
+	* @param commandkit The CommandKit instance.
+	*/
 	constructor(commandkit$1) {
 		this.commandkit = commandkit$1;
 	}
+	/**
+	* Sets a filter function for analytics events.
+	* This function will be called before tracking an event to determine if it should be tracked.
+	* If the filter returns `false`, the event will not be tracked.
+	* If the filter is set to `null`, all events will be tracked unless `doNotTrack` is enabled.
+	* @param filter The filter function to set, or `null` to remove the filter.
+	*/
 	setFilter(filter) {
 		this.#filter = filter;
 	}
+	/**
+	* Registers an analytics provider.
+	* This provider will be used to track and identify events.
+	* If a provider is already registered, it will be replaced with the new one.
+	* @param provider The analytics provider to register.
+	*/
 	registerProvider(provider) {
 		require_warn_unstable.warnUnstable("analytics");
 		this.#provider = provider;
 	}
+	/**
+	* Removes the currently registered analytics provider.
+	* @param provider The analytics provider to remove.
+	*/
 	removeProvider(provider) {
 		if (this.#provider === provider) this.#provider = null;
 	}
+	/**
+	* Retrieves the currently registered analytics provider.
+	* @returns The currently registered analytics provider, or `null` if no provider is registered.
+	*/
 	getProvider() {
 		return this.#provider;
 	}
+	/**
+	* Identifies a user with the analytics provider.
+	* This method sends an identify event to the provider, which can be used to associate user data with events.
+	* @param event The identify event containing user data to send to the provider.
+	*/
 	async identify(event) {
 		if (!this.#provider) return;
 		try {
@@ -2847,6 +3399,12 @@ var AnalyticsEngine = class {
 			Logger.error(`Error identifying with provider ${this.#provider.name}`, error);
 		}
 	}
+	/**
+	* Tracks an analytics event with the registered provider.
+	* This method sends the event to the provider, which can then process it as needed.
+	* If the `doNotTrack` setting is enabled or if the filter function returns `false`, the event will not be tracked.
+	* @param event The analytics event to track.
+	*/
 	async track(event) {
 		if (!this.#provider) return;
 		try {
@@ -2900,30 +3458,77 @@ function onBootstrap(fn) {
 function onApplicationBootstrap(fn) {
 	onApplicationBootstrapHooks.add(fn);
 }
+/**
+* The commandkit class that serves as the main entry point for the CommandKit framework.
+*/
 var CommandKit = class CommandKit extends node_events.default {
 	#started = false;
 	#clientProxy = createProxy({});
 	#client;
+	/**
+	* The event interceptor to quickly register temporary event listeners
+	*/
 	eventInterceptor;
+	/**
+	* The static createElement function to create jsx elements
+	*/
 	static createElement = require_element.createElement;
+	/**
+	* The static Fragment component to create jsx fragments
+	*/
 	static Fragment = require_element.Fragment;
+	/**
+	* The configuration for the CommandKit instance.
+	*/
 	config = {
 		defaultLocale: discord_js.Locale.EnglishUS,
 		getMessageCommandPrefix: () => "!"
 	};
+	/**
+	* A key-value store for storing arbitrary data.
+	*/
 	store = /* @__PURE__ */ new Map();
+	/**
+	* A flag store for storing flags that can be used to enable or disable features.
+	*/
 	flags = new require_store.FlagStore();
+	/**
+	* The command router for the CommandKit instance.
+	*/
 	commandsRouter;
+	/**
+	* The events router for the CommandKit instance.
+	*/
 	eventsRouter;
+	/**
+	* The command handler for the CommandKit instance.
+	* This is responsible for handling commands and their execution.
+	*/
 	commandHandler;
+	/**
+	* The event handler for the CommandKit instance.
+	* This is responsible for handling events and their execution.
+	*/
 	eventHandler;
+	/**
+	* The plugins runtime for the CommandKit instance.
+	*/
 	plugins;
+	/**
+	* The events channel for the CommandKit instance. This can be used to emit custom events.
+	*/
 	events;
+	/**
+	* The analytics engine for the CommandKit instance.
+	* This is responsible for tracking events and user interactions.
+	*/
 	analytics;
+	/**
+	* The static instance of CommandKit.
+	*/
 	static instance = void 0;
 	/**
 	* Create a new command and event handler with CommandKit.
-	*
 	* @param options - The default CommandKit configuration.
 	* @see {@link https://commandkit.js.org/docs/guide/commandkit-setup}
 	*/
@@ -3108,6 +3713,11 @@ var CommandKit = class CommandKit extends node_events.default {
 	getAppDirectory() {
 		return findAppDirectory();
 	}
+	/**
+	* Get the path to the commands or events directory.
+	* @param to The type of path to get, either 'commands' or 'events'.
+	* @returns The path to the commands or events directory
+	*/
 	getPath(to) {
 		const appDir$1 = this.getAppDirectory();
 		if (!appDir$1) return null;
@@ -3118,6 +3728,9 @@ var CommandKit = class CommandKit extends node_events.default {
 		}
 	}
 };
+/**
+* The singleton instance of CommandKit.
+*/
 const commandkit = CommandKit.instance || new CommandKit();
 
 //#endregion
@@ -3511,4 +4124,4 @@ Object.defineProperty(exports, 'useEnvironment', {
     return useEnvironment;
   }
 });
-//# sourceMappingURL=CommandKit-CnLBu_7m.js.map
+//# sourceMappingURL=CommandKit-BqZBlSaB.js.map