commandkit 0.1.11-dev.20250308073818 → 0.1.11-dev.20250308122630

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as discord_js from 'discord.js';
-import { RESTPostAPIApplicationCommandsJSONBody, Client, Interaction, CacheType, PermissionsString, ChatInputCommandInteraction, ContextMenuCommandInteraction, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, AutocompleteInteraction, ClientEvents, Awaitable, ButtonBuilder, ButtonInteraction, Events, ModalBuilder, ModalSubmitInteraction, ActionRowBuilder, TextInputBuilder, ButtonStyle, ComponentEmojiResolvable, TextInputStyle, Locale, Message as Message$1, ApplicationCommandOptionType, GuildMember, Attachment, User, Role, CommandInteractionOption, Collection, SlashCommandBuilder, ContextMenuCommandBuilder, PartialMessage } from 'discord.js';
+import { RESTPostAPIApplicationCommandsJSONBody, Client, Interaction, CacheType, PermissionsString, ChatInputCommandInteraction, ContextMenuCommandInteraction, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, AutocompleteInteraction, ClientEvents, Awaitable, ButtonBuilder, ButtonInteraction, Events, ModalBuilder, ModalSubmitInteraction, ActionRowBuilder, TextInputBuilder, ButtonStyle, ComponentEmojiResolvable, TextInputStyle, LocalizationMap, Locale, Message as Message$1, ApplicationCommandOptionType, GuildMember, Attachment, User, Role, CommandInteractionOption, Collection, SlashCommandBuilder, ContextMenuCommandBuilder, PartialMessage } from 'discord.js';
 import EventEmitter from 'node:events';
 import { Channel } from 'diagnostics_channel';
 import * as commander from 'commander';
@@ -576,6 +576,11 @@ interface TranslatableCommandOptions {
     ref: string;
     name?: string;
     description?: string;
+    options?: TranslatableCommandOptions[];
+}
+interface ApiTranslatableCommandOptions extends TranslatableCommandOptions {
+    name_localizations?: LocalizationMap;
+    description_localizations?: LocalizationMap;
 }
 interface Translation {
     command: TranslatableCommand;
@@ -842,7 +847,7 @@ declare const CommandExecutionMode: {
     readonly Message: "message";
 };
 type CommandExecutionMode = (typeof CommandExecutionMode)[keyof typeof CommandExecutionMode];
-interface ContextParameters<T extends CommandExecutionMode> {
+interface ContextParameters<T extends CommandExecutionMode, Args = Record<string, any>> {
     environment?: CommandKitEnvironment;
     executionMode: T;
     interaction: T extends 'chatInput' ? ChatInputCommandInteraction : T extends 'messageContextMenu' ? MessageContextMenuCommandInteraction : T extends 'userContextMenu' ? UserContextMenuCommandInteraction : T extends 'autocomplete' ? AutocompleteInteraction : never;
@@ -850,6 +855,7 @@ interface ContextParameters<T extends CommandExecutionMode> {
     forwarded?: boolean;
     messageCommandParser?: T extends 'message' ? MessageCommandParser : never;
     store?: Map<string, any>;
+    customArgs?: Args;
 }
 type MessageCommandContext = Context<'message'>;
 type InteractionCommandContext = Context<'autocomplete' | 'chatInput' | 'messageContextMenu' | 'userContextMenu'>;
@@ -870,10 +876,13 @@ type AutocompleteCommand = AnyCommandExecute<AutocompleteCommandContext>;
 type MessageContextMenuCommand = AnyCommandExecute<MessageContextMenuCommandContext>;
 type UserContextMenuCommand = AnyCommandExecute<UserContextMenuCommandContext>;
 type MessageCommand = AnyCommandExecute<MessageCommandContext>;
-declare class Context<ExecutionMode extends CommandExecutionMode = CommandExecutionMode> {
+interface MiddlewareContextArgs {
+    setCommandRunner?: GenericFunction<[RunCommand]>;
+}
+declare class Context<ExecutionMode extends CommandExecutionMode = CommandExecutionMode, Args extends Record<string, any> = Record<string, any>> {
     #private;
     readonly commandkit: CommandKit;
-    private readonly config;
+    protected readonly config: ContextParameters<ExecutionMode, Args>;
     /**
      * The interaction that triggered the command.
      */
@@ -892,7 +901,7 @@ declare class Context<ExecutionMode extends CommandExecutionMode = CommandExecut
      * @param commandkit The command kit instance.
      * @param config The context parameters.
      */
-    constructor(commandkit: CommandKit, config: ContextParameters<ExecutionMode>);
+    constructor(commandkit: CommandKit, config: ContextParameters<ExecutionMode, Args>);
     /**
      * The shared key-value store for this context. This can be used to store data that needs to be shared between middlewares or commands.
      * This store is shared across all contexts in the same command execution, including the cloned contexts and middleware contexts.
@@ -995,7 +1004,7 @@ declare class Context<ExecutionMode extends CommandExecutionMode = CommandExecut
      */
     isCached(fn: GenericFunction): boolean;
 }
-declare class MiddlewareContext<T extends CommandExecutionMode = CommandExecutionMode> extends Context<T> {
+declare class MiddlewareContext<T extends CommandExecutionMode = CommandExecutionMode> extends Context<T, MiddlewareContextArgs> {
     #private;
     /**
      * Whether the command execution was cancelled.
@@ -1005,167 +1014,69 @@ declare class MiddlewareContext<T extends CommandExecutionMode = CommandExecutio
      * Cancels the command execution.
      */
     cancel(): void;
+    /**
+     * Sets command runner function to wrap the command execution.
+     * @param fn The function to set.
+     * @example ctx.setCommandRunner(async (execute) => {
+     *  // do something before command execution
+     *  await execute();
+     *  // do something after command execution
+     * })
+     */
+    setCommandRunner(fn: RunCommand): void;
 }
 
-/**
- * Represents a command file info parsed from the file system.
- * It does not contain any command specific data, as that's loaded later by the command handler.
- */
 interface ParsedCommand {
-    /**
-     * The unique identifier of the command. This is used to distinguish between commands that may have the same name.
-     */
     id: string;
-    /**
-     * The file name of the command.
-     */
     name: string;
-    /**
-     * The absolute path to the command file.
-     */
     path: string;
-    /**
-     * The relative path from the cwd to the command file.
-     */
     relativePath: string;
-    /**
-     * The category of this command. This will be the parent directory segment that matches /(category)/ in the path.
-     * When there are multiple segments, they are combined with a colon.
-     * Example: `/commands/(games)/tictactoe.js` -> category is `games`
-     * Example: `/commands/(games)/(fun)/tictactoe.js` -> category is `games:fun`
-     * Category is `null` if the parent directory segment does not match `/(\w+)/`.
-     */
     category: string | null;
-    /**
-     * Array of ids referencing the associated middleware for this command.
-     */
-    middlewares: string[];
-    /**
-     * Array of ids referencing the associated subcommands for this command.
-     */
-    subcommands: string[];
+    subcommands: ParsedSubCommand[];
+    middlewareIds: string[];
 }
-/**
- * Represents a middleware file info parsed from the file system.
- */
 interface ParsedMiddleware {
-    /**
-     * The unique identifier of the middleware. This is used to distinguish between middlewares that may have the same name.
-     */
     id: string;
-    /**
-     * The file name of the middleware.
-     */
-    name: string;
-    /**
-     * The absolute path to the middleware file.
-     */
     path: string;
-    /**
-     * The relative path from the cwd to the middleware file.
-     */
     relativePath: string;
-    /**
-     * The category of this middleware. This will be the parent directory segment that matches /(category)/ in the path.
-     */
-    category: string | null;
 }
-/**
- * Represents a subcommand file info parsed from the file system.
- */
 interface ParsedSubCommand {
-    /**
-     * The unique identifier of the subcommand. This is used to distinguish between subcommands that may have the same name.
-     */
-    id: string;
-    /**
-     * The name of the subcommand.
-     */
     name: string;
-    /**
-     * The group name of the subcommand. This is used to group subcommands together in the Discord UI.
-     */
     group: string | null;
-    /**
-     * The category of this subcommand. This will be the parent directory segment that matches /(category)/ in the path.
-     */
-    category: string | null;
-    /**
-     * The absolute path to the subcommand file.
-     */
     path: string;
-    /**
-     * The relative path from the cwd to the subcommand file.
-     */
     relativePath: string;
-    /**
-     * Array of ids referencing the associated middleware for this subcommand.
-     */
-    middlewares: string[];
+    command: string;
 }
-/**
- * Represents a JSON compatible object that contains all the parsed commands, middlewares, and subcommands.
- */
-interface CommandTree {
-    commands: Record<string, ParsedCommand>;
-    middlewares: Record<string, ParsedMiddleware>;
-    subcommands: Record<string, ParsedSubCommand>;
+interface CommandsRouterOptions {
+    entrypoint: string;
 }
-/**
- * Represents the scanned and parsed command files.
- */
-interface ParsedCommandData {
+interface CommandsRouterData {
     commands: Collection<string, ParsedCommand>;
     middlewares: Collection<string, ParsedMiddleware>;
-    subcommands: Collection<string, ParsedSubCommand>;
 }
-interface CommandsRouterOptions {
-    /**
-     * The path to the directory containing the command files.
-     */
-    entrypoint: string;
+interface CommandsRouterRawData {
+    commands: Record<string, ParsedCommand>;
+    middlewares: Record<string, ParsedMiddleware>;
 }
 declare class CommandsRouter {
-    private options;
+    private readonly options;
     private commands;
     private middlewares;
-    private subcommands;
     constructor(options: CommandsRouterOptions);
+    fromData(data: CommandsRouterRawData): void;
     isValidPath(): boolean;
-    get entrypoint(): string;
+    getData(): CommandsRouterData;
+    toJSON(): CommandsRouterRawData;
     clear(): void;
-    reload(): Promise<CommandTree>;
-    visualize(): string;
-    getData(): ParsedCommandData;
-    toJSON(): CommandTree;
-    scan(): Promise<CommandTree>;
-    private scanDeep;
-    /**
-     * Gets path segments between two paths, excluding the start and end paths
-     * Used to check if all directories between a path and the entrypoint are category directories
-     */
-    private getPathSegmentsBetween;
-    private processMiddleware;
-    private processSubcommand;
-    private processCommand;
-    private extractDirOmitCategory;
-    /**
-     * Gets the appropriate file name, handling index files specially
-     * For index files, it returns the parent directory name (excluding category markers)
-     */
-    private getAppropriateFileName;
-    /**
-     * Extract the clean directory name, removing any category markers
-     */
-    private getDirectoryName;
-    private isCategoryDirectory;
-    private applyMiddlewareToCommands;
-    private applySubcommandToCommands;
-    private extractCategory;
-    private getRelativePath;
-    private isMiddleware;
-    private shouldIgnore;
-    private extractName;
+    reload(): Promise<CommandsRouterRawData>;
+    scan(): Promise<CommandsRouterRawData>;
+    private traverse;
+    private applyBindings;
+    private distanceFromRoot;
+    private parseGroup;
+    private parseCategory;
+    private parseFileName;
+    private toRelativePath;
 }
 
 /**
@@ -1280,68 +1191,6 @@ declare class CommandRegistrar {
     updateGuildCommands(commands: CommandData[]): Promise<void>;
 }
 
-interface AppCommand {
-    command: SlashCommandBuilder | Record<string, any>;
-    chatInput?: (ctx: Context) => Awaitable<unknown>;
-    autocomplete?: (ctx: Context) => Awaitable<unknown>;
-    message?: (ctx: Context) => Awaitable<unknown>;
-    messageContextMenu?: (ctx: Context) => Awaitable<unknown>;
-    userContextMenu?: (ctx: Context) => Awaitable<unknown>;
-}
-interface AppCommandMiddleware {
-    beforeExecute: (ctx: Context) => Awaitable<unknown>;
-    afterExecute: (ctx: Context) => Awaitable<unknown>;
-}
-interface LoadedCommand {
-    command: ParsedCommand;
-    data: AppCommand;
-    subcommands?: ParsedSubCommand[];
-    guilds?: string[];
-}
-interface LoadedMiddleware {
-    middleware: ParsedMiddleware;
-    data: AppCommandMiddleware;
-}
-interface PreparedAppCommandExecution {
-    command: LoadedCommand;
-    subcommand?: LoadedSubCommand | null;
-    middlewares: LoadedMiddleware[];
-    messageCommandParser?: MessageCommandParser;
-}
-interface LoadedSubCommand {
-    subcommand: ParsedSubCommand;
-    data: AppCommand;
-}
-type CommandBuilderLike = SlashCommandBuilder | ContextMenuCommandBuilder | Record<string, any>;
-declare class AppCommandHandler {
-    readonly commandkit: CommandKit;
-    private loadedCommands;
-    private loadedSubCommands;
-    private loadedMiddlewares;
-    private commandNameToId;
-    private subcommandPathToId;
-    readonly registrar: CommandRegistrar;
-    private onInteraction;
-    private onMessageCreate;
-    private onMessageUpdate;
-    constructor(commandkit: CommandKit);
-    getCommandsArray(): LoadedCommand[];
-    /**
-     * Get subcommand data by ID for the command registrar
-     */
-    getSubcommandData(id: string): any;
-    registerCommandHandler(): void;
-    getExecutionMode(source: Interaction | Message$1): CommandExecutionMode;
-    runCommand(prepared: PreparedAppCommandExecution, source: Interaction | Message$1): Promise<void>;
-    prepareCommandRun(source: Interaction | Message$1): Promise<PreparedAppCommandExecution | null>;
-    reloadCommands(): Promise<void>;
-    loadCommands(): Promise<void>;
-    private loadMiddleware;
-    private loadCommand;
-    private loadSubcommand;
-    applyLocalizations(command: CommandBuilderLike): Promise<discord_js.RESTPostAPIContextMenuApplicationCommandsJSONBody | CommandBuilderLike>;
-}
-
 declare class MemoryCache extends CacheProvider {
     #private;
     get<T>(key: string): Promise<CacheEntry<T> | undefined>;
@@ -1470,6 +1319,69 @@ declare function revalidate<T = unknown>(tag: string, ...args: any[]): Promise<T
  */
 declare function isCachedFunction(fn: GenericFunction): boolean;
 
+type RunCommand = <T extends AsyncFunction>(fn: T) => T;
+interface AppCommand {
+    command: SlashCommandBuilder | Record<string, any>;
+    chatInput?: (ctx: Context) => Awaitable<unknown>;
+    autocomplete?: (ctx: Context) => Awaitable<unknown>;
+    message?: (ctx: Context) => Awaitable<unknown>;
+    messageContextMenu?: (ctx: Context) => Awaitable<unknown>;
+    userContextMenu?: (ctx: Context) => Awaitable<unknown>;
+}
+interface AppCommandMiddleware {
+    beforeExecute: (ctx: Context) => Awaitable<unknown>;
+    afterExecute: (ctx: Context) => Awaitable<unknown>;
+}
+interface LoadedCommand {
+    command: ParsedCommand;
+    data: AppCommand;
+    subcommands?: ParsedSubCommand[];
+    guilds?: string[];
+}
+interface LoadedMiddleware {
+    middleware: ParsedMiddleware;
+    data: AppCommandMiddleware;
+}
+interface PreparedAppCommandExecution {
+    command: LoadedCommand;
+    subcommand?: LoadedSubCommand | null;
+    middlewares: LoadedMiddleware[];
+    messageCommandParser?: MessageCommandParser;
+}
+interface LoadedSubCommand {
+    subcommand: ParsedSubCommand;
+    data: AppCommand;
+}
+type CommandBuilderLike = SlashCommandBuilder | ContextMenuCommandBuilder | Record<string, any>;
+declare class AppCommandHandler {
+    readonly commandkit: CommandKit;
+    private loadedCommands;
+    private loadedSubCommands;
+    private loadedMiddlewares;
+    private commandNameToId;
+    private subcommandPathToId;
+    readonly registrar: CommandRegistrar;
+    private onInteraction;
+    private onMessageCreate;
+    private onMessageUpdate;
+    constructor(commandkit: CommandKit);
+    getCommandsArray(): LoadedCommand[];
+    /**
+     * Get subcommand data by command ID and subcommand name
+     */
+    getSubcommandData(commandId: string, subcommandName: string): any;
+    registerCommandHandler(): void;
+    getExecutionMode(source: Interaction | Message$1): CommandExecutionMode;
+    runCommand(prepared: PreparedAppCommandExecution, source: Interaction | Message$1): Promise<void>;
+    prepareCommandRun(source: Interaction | Message$1): Promise<PreparedAppCommandExecution | null>;
+    reloadCommands(): Promise<void>;
+    loadCommands(): Promise<void>;
+    private loadMiddleware;
+    private loadCommand;
+    private loadSubcommand;
+    applyLocalizations(command: CommandBuilderLike, subcommand?: ParsedSubCommand): Promise<CommandBuilderLike>;
+}
+
 type ListenerFunction = GenericFunction | AsyncFunction;
 declare class CommandKitEventsChannel {
     readonly commandkit: CommandKit;
@@ -2013,4 +1925,4 @@ declare const version: string;
  */
 declare function bootstrapCommandkitCLI(argv: string[], options?: commander.ParseOptions | undefined): Promise<void>;
 
-export { ActionRow, type ActionRowProps, type AnyCommandExecute, type AnyCommandKitElement, AppCommandHandler, type AsyncFunction, type AutocompleteCommand, type AutocompleteCommandContext, type AutocompleteCommandMiddlewareContext, type AutocompleteProps, Button, type ButtonChildrenLike, ButtonKit, type ButtonKitPredicate, type ButtonProps, type CacheContext, type CacheEntry, type CacheMetadata, CacheProvider, type CommandContext, type CommandContextOptions, type CommandData, CommandExecutionMode, type CommandFileObject, CommandKit, type CommandKitButtonBuilderInteractionCollectorDispatch, type CommandKitButtonBuilderInteractionCollectorDispatchContextData, type CommandKitButtonBuilderOnEnd, type CommandKitConfiguration, type CommandKitElement, type CommandKitElementData, CommandKitEnvironment, type CommandKitEnvironmentInternalData, CommandKitEnvironmentType, type CommandKitLoggerOptions, type CommandKitModalBuilderInteractionCollectorDispatch, type CommandKitModalBuilderInteractionCollectorDispatchContextData, type CommandKitModalBuilderOnEnd, type CommandKitOptions, type CommandObject, type CommandOptions, type CommandProps, type CommandTree, CommandsRouter, type CommandsRouterOptions, Context, type ContextMenuCommandProps, type ContextParameters, DefaultLocalizationStrategy, DefaultLogger, ElementType, EventInterceptor, type EventInterceptorContextData, type EventInterceptorErrorHandler, EventsRouter, type EventsRouterOptions, type EventsTree, Fragment, type FragmentElementProps, type GenericFunction, type ILogger, type InteractionCommandContext, type InteractionCommandMiddlewareContext, type LoadedCommand, Localization, type LocalizationConfig, type LocalizationStrategy, type LocalizationTranslationRequest, Logger, type LoggerImpl, type MaybeArray, MemoryCache, type MessageCommand, type MessageCommandContext, type MessageCommandMiddlewareContext, MessageCommandOptions, type MessageCommandOptionsSchema, MessageCommandParser, type MessageContextMenuCommand, type MessageContextMenuCommandContext, type MessageContextMenuCommandMiddlewareContext, type MessageContextMenuCommandProps, MiddlewareContext, Modal, ModalKit, type ModalKitPredicate, type ModalProps, type OnButtonKitClick, type OnButtonKitEnd, type OnModalKitEnd, type OnModalKitSubmit, ParagraphInput, type ParsedCommand, type ParsedCommandData, type ParsedEvent, type ParsedMessageCommand, type ParsedMiddleware, type ParsedSubCommand, type PreparedAppCommandExecution, type ReloadOptions, ReloadType, ShortInput, type SlashCommand, type SlashCommandContext, type SlashCommandMiddlewareContext, type SlashCommandProps, TextInput, type TextInputProps, type TranslatableArguments, type TranslatableCommand, type TranslatableCommandOptions, type Translation, type TranslationResult, type Translator, type UserContextMenuCommand, type UserContextMenuCommandContext, type UserContextMenuCommandMiddlewareContext, type UserContextMenuCommandProps, type ValidationProps, afterCommand, bootstrapCommandkitCLI, cache, cacheLife, cacheTag, cancelAfterCommand, createElement, createLogger, CommandKit as default, defineConfig, dmOnly, exitContext, exitMiddleware, getCommandKit, getConfig, getContext, getElement, guildOnly, invalidate, isCachedFunction, isCommandKitElement, makeContextAwareFunction, redirect, rethrow, revalidate, useCache as super_duper_secret_internal_for_use_cache_directive_of_commandkit_cli_do_not_use_it_directly_or_you_will_be_fired_from_your_job_kthxbai, useEnvironment, version };
+export { ActionRow, type ActionRowProps, type AnyCommandExecute, type AnyCommandKitElement, type ApiTranslatableCommandOptions, AppCommandHandler, type AsyncFunction, type AutocompleteCommand, type AutocompleteCommandContext, type AutocompleteCommandMiddlewareContext, type AutocompleteProps, Button, type ButtonChildrenLike, ButtonKit, type ButtonKitPredicate, type ButtonProps, type CacheContext, type CacheEntry, type CacheMetadata, CacheProvider, type CommandContext, type CommandContextOptions, type CommandData, CommandExecutionMode, type CommandFileObject, CommandKit, type CommandKitButtonBuilderInteractionCollectorDispatch, type CommandKitButtonBuilderInteractionCollectorDispatchContextData, type CommandKitButtonBuilderOnEnd, type CommandKitConfiguration, type CommandKitElement, type CommandKitElementData, CommandKitEnvironment, type CommandKitEnvironmentInternalData, CommandKitEnvironmentType, type CommandKitLoggerOptions, type CommandKitModalBuilderInteractionCollectorDispatch, type CommandKitModalBuilderInteractionCollectorDispatchContextData, type CommandKitModalBuilderOnEnd, type CommandKitOptions, type CommandObject, type CommandOptions, type CommandProps, CommandsRouter, type CommandsRouterData, type CommandsRouterOptions, type CommandsRouterRawData, Context, type ContextMenuCommandProps, type ContextParameters, DefaultLocalizationStrategy, DefaultLogger, ElementType, EventInterceptor, type EventInterceptorContextData, type EventInterceptorErrorHandler, EventsRouter, type EventsRouterOptions, type EventsTree, Fragment, type FragmentElementProps, type GenericFunction, type ILogger, type InteractionCommandContext, type InteractionCommandMiddlewareContext, type LoadedCommand, Localization, type LocalizationConfig, type LocalizationStrategy, type LocalizationTranslationRequest, Logger, type LoggerImpl, type MaybeArray, MemoryCache, type MessageCommand, type MessageCommandContext, type MessageCommandMiddlewareContext, MessageCommandOptions, type MessageCommandOptionsSchema, MessageCommandParser, type MessageContextMenuCommand, type MessageContextMenuCommandContext, type MessageContextMenuCommandMiddlewareContext, type MessageContextMenuCommandProps, MiddlewareContext, type MiddlewareContextArgs, Modal, ModalKit, type ModalKitPredicate, type ModalProps, type OnButtonKitClick, type OnButtonKitEnd, type OnModalKitEnd, type OnModalKitSubmit, ParagraphInput, type ParsedCommand, type ParsedEvent, type ParsedMessageCommand, type ParsedMiddleware, type ParsedSubCommand, type PreparedAppCommandExecution, type ReloadOptions, ReloadType, type RunCommand, ShortInput, type SlashCommand, type SlashCommandContext, type SlashCommandMiddlewareContext, type SlashCommandProps, TextInput, type TextInputProps, type TranslatableArguments, type TranslatableCommand, type TranslatableCommandOptions, type Translation, type TranslationResult, type Translator, type UserContextMenuCommand, type UserContextMenuCommandContext, type UserContextMenuCommandMiddlewareContext, type UserContextMenuCommandProps, type ValidationProps, afterCommand, bootstrapCommandkitCLI, cache, cacheLife, cacheTag, cancelAfterCommand, createElement, createLogger, CommandKit as default, defineConfig, dmOnly, exitContext, exitMiddleware, getCommandKit, getConfig, getContext, getElement, guildOnly, invalidate, isCachedFunction, isCommandKitElement, makeContextAwareFunction, redirect, rethrow, revalidate, useCache as super_duper_secret_internal_for_use_cache_directive_of_commandkit_cli_do_not_use_it_directly_or_you_will_be_fired_from_your_job_kthxbai, useEnvironment, version };