index.js

// @ts-check
"use strict"

const assert = require("node:assert")

/**
 * @template {Array<unknown>} Params
 * @typedef {{
 * 	name: string
 * 	type?: 1 | 2 | 3
 * 	integration_types?: Array<number>
 *	contexts?: Array<number>
 *	options?: Array<import("discord-api-types/v10").APIApplicationCommandOption>
 *	description: string
 *	category: string
 *	guild_ids?: Array<string>
 *	examples?: Array<string>
 *	order?: number
 *	default_member_permissions?: string | null
 *	process(...args: Params): unknown
 * }} Command
 */

/**
 * A wrapper around the Discord Chat Input Interaction
 */
class ChatInputCommand {
	/**
	 * The user who initiated this command
	 * @type {import("discord-api-types/v10").APIUser}
	 * @readonly
	 */
	author
	/**
	 * The member object of the user if this command was initiated in a guild
	 * @type {import("discord-api-types/v10").APIInteractionGuildMember | null}
	 * @readonly
	 */
	member
	/**
	 * The id of the guild this command was initiated in if any
	 * @type {string | null}
	 * @readonly
	 */
	guild_id
	/**
	 * The channel this command was initiated in
	 * @type {import("discord-api-types/v10").APIChatInputApplicationCommandInteraction["channel"]}
	 * @readonly
	 */
	channel
	/**
	 * The language the user initiating this command has set on their Discord client
	 * @type {import("discord-api-types/v10").Locale}
	 * @readonly
	 */
	locale
	/**
	 * The preferred language of the guild this command was initiated in if any
	 * @type {import("discord-api-types/v10").Locale | null}
	 * @readonly
	 */
	guild_locale

	/**
	 * The data inputted to the command if any such as options and their resolutions
	 * @type {ChatInputCommandData}
	 * @readonly
	 */
	data

	/**
	 * The Discord auto generated id of the command/webhook
	 * @type {string}
	 * @readonly
	 */
	id
	/**
	 * The id of the app this command is for
	 * @type {string}
	 * @readonly
	 */
	application_id
	/**
	 * The token for this command/webhook to respond/update responses
	 * @type {string}
	 * @readonly
	 */
	token
	/**
	 * The permissions the app or bot has within the channel the command was initiated in
	 * @type {string}
	 * @readonly
	 */
	app_permissions

	/**
	 * @param {import("discord-api-types/v10").APIChatInputApplicationCommandInteraction} interaction The Chat Input Interaction received from Discord
	 */
	constructor(interaction) {
		// @ts-expect-error
		this.author = interaction.member?.user ?? interaction.user
		this.member = interaction.member ?? null
		this.guild_id = interaction.guild_id ?? null
		this.channel = interaction.channel
		this.locale = interaction.locale
		this.guild_locale = interaction.guild_locale ?? null
		this.data = new ChatInputCommandData(interaction.data)

		this.id = interaction.id
		this.application_id = interaction.application_id
		this.token = interaction.token
		this.app_permissions = interaction.app_permissions
	}
}

/**
 * A wrapper around the Chat Input Interaction's options and their resolutions
 * using Maps for fast K, V fetching instead of iterating over the raw Object from the
 * API to find options and their resolutions
 */
class ChatInputCommandData {
	/**
	 * Resolved users from the supplied options
	 * @type {Map<string, import("discord-api-types/v10").APIUser>}
	 * @readonly
	 */
	users
	/**
	 * Resolved members from the supplied options
	 * @type {Map<string, import("discord-api-types/v10").APIInteractionDataResolvedGuildMember>}
	 * @readonly
	 */
	members
	/**
	 * Resolved roles from the supllied options
	 * @type {Map<string, import("discord-api-types/v10").APIRole>}
	 * @readonly
	 */
	roles
	/**
	 * Resolved channels from the supplied options
	 * @type {Map<string, import("discord-api-types/v10").APIInteractionDataResolvedChannel>}
	 * @readonly
	 */
	channels
	/**
	 * Resolved attachments from the supplied options
	 * @type {Map<string, import("discord-api-types/v10").APIAttachment>}
	 * @readonly
	 */
	attachments

	/**
	 * The options the user sent. For options that needed resolutions, the command options wrap id strings
	 * @type {Map<string, CommandOption>}
	 * @readonly
	 */
	options

	/**
	 * @param {import("discord-api-types/v10").APIChatInputApplicationCommandInteractionData} data The data for the Chat Input Interaction received from Discord
	 */
	constructor(data) {
		this.users = new Map(Object.entries(data.resolved?.users ?? {}))
		this.members = new Map(Object.entries(data.resolved?.members ?? {}))
		this.roles = new Map(Object.entries(data.resolved?.roles ?? {}))
		this.channels = new Map(Object.entries(data.resolved?.channels ?? {}))
		this.attachments = new Map(Object.entries(data.resolved?.attachments ?? {}))

		this.options = new Map(data.options?.map(c => [c.name, new CommandOption(c)]) ?? [])
	}
}

/**
 * A wrapper around any of the option types Discord could send from a user
 * Supports sub commands and their subsequent options
 */
class CommandOption {
	/**
	 * If a sub command, the options for said sub command. Empty Map otherwise
	 * @type {Map<string, CommandOption>}
	 * @readonly
	 */
	options
	/**
	 * The backing value this CommandOption represents or null if a sub command or was optional and not supplied. Use the as* methods to assert types
	 * @type {unknown}
	 * @readonly
	 */
	value

	/**
	 * @param {import("discord-api-types/v10").APIApplicationCommandInteractionDataOption | import("discord-api-types/v10").APIApplicationCommandInteractionDataBasicOption} data The data for this option received from Discord
	 */
	constructor(data) {
		if ("options" in data && data.options) this.options = new Map(data.options.map(c => [c.name, new CommandOption(c)]))
		else this.options = new Map()

		if ("value" in data) this.value = data.value ?? null
		else this.value = null
	}

	/**
	 * Assert this command option to be a string or null if the option was optional and not supplied
	 * @returns {string | null}
	 */
	asString() {
		// @ts-expect-error
		return this.value
	}

	/**
	 * Assert this command option to be a number or null if the option was optional and not supplied
	 * @returns {number | null}
	 */
	asNumber() {
		// @ts-expect-error
		return this.value
	}

	/**
	 * Assert this command option to be a boolean or null if the option was optional and not supplied
	 * @returns {boolean | null}
	 */
	asBoolean() {
		// @ts-expect-error
		return this.value
	}
}

/**
 * A wrapper around commands issued from the Discord context menu
 */
class ContextMenuCommand {
	/**
	 * The user who initiated this command
	 * @type {import("discord-api-types/v10").APIUser}
	 * @readonly
	 */
	author
	/**
	 * The member object of the user if this command was initiated in a guild
	 * @type {import("discord-api-types/v10").APIInteractionGuildMember | null}
	 * @readonly
	 */
	member
	/**
	 * The id of the guild this command was initiated in if any
	 * @type {string | null}
	 * @readonly
	 */
	guild_id
	/**
	 * The channel this command was initiated in
	 * @type {import("discord-api-types/v10").APIContextMenuInteraction["channel"]}
	 * @readonly
	 */
	channel
	/**
	 * The language the user initiating this command has set on their Discord client
	 * @type {import("discord-api-types/v10").Locale}
	 * @readonly
	 */
	locale
	/**
	 * The preferred language of the guild this command was initiated in if any
	 * @type {import("discord-api-types/v10").Locale | null}
	 * @readonly
	 */
	guild_locale
	/**
	 * The id of the target this command was issued for
	 * @type {string}
	 * @readonly
	 */
	target

	/**
	 * The resolved data for the target of this command
	 * @type {ContextMenuCommandData}
	 * @readonly
	 */
	data

	/**
	 * The Discord auto generated id of the command/webhook
	 * @type {string}
	 * @readonly
	 */
	id
	/**
	 * The id of the app this command is for
	 * @type {string}
	 * @readonly
	 */
	application_id
	/**
	 * The token for this command/webhook to respond/update responses
	 * @type {string}
	 * @readonly
	 */
	token
	/**
	 * The permissions the app or bot has within the channel the command was initiated in
	 * @type {string}
	 * @readonly
	 */
	app_permissions

	/**
	 * @param {import("discord-api-types/v10").APIContextMenuInteraction} interaction The Context Menu Interaction from Discord
	 */
	constructor(interaction) {
		// @ts-expect-error
		this.author = interaction.member?.user ?? interaction.user
		this.member = interaction.member ?? null
		this.guild_id = interaction.guild_id ?? null
		this.channel = interaction.channel
		this.locale = interaction.locale
		this.guild_locale = interaction.guild_locale ?? null
		this.data = new ContextMenuCommandData(interaction.data)
		this.target = interaction.data.target_id

		this.id = interaction.id
		this.application_id = interaction.application_id
		this.token = interaction.token
		this.app_permissions = interaction.app_permissions
	}
}

/**
 * A wrapper around the Context Menu command and its resolutions
 * using Maps for fast K, V fetching instead of iterating over the raw Object from the
 * API to find options and their resolutions
 */
class ContextMenuCommandData {
	/**
	 * The id of the target this command was issued for
	 * @type {string}
	 * @readonly
	 */
	target_id

	/**
	 * Resolved users from the context menu interaction
	 * @type {Map<string, import("discord-api-types/v10").APIUser>}
	 * @readonly
	 */
	users
	/**
	 * Resolved members from the context menu interaction
	 * @type {Map<string, import("discord-api-types/v10").APIInteractionDataResolvedGuildMember>}
	 * @readonly
	 */
	members
	/**
	 * Resolved messages from the context menu interaction
	 * @type {Map<string, import("discord-api-types/v10").APIMessage>}
	 * @readonly
	 */
	messages

	/**
	 * @param {import("discord-api-types/v10").APIContextMenuInteractionData} data The data for the Context Menu Interaction from Discord
	 */
	constructor(data) {
		this.target_id = data.target_id

		if (data.type === 2) {
			this.users = new Map(Object.entries(data.resolved.users))
			this.members = new Map(Object.entries(data.resolved.members ?? {}))
			this.messages = new Map()
		} else {
			this.messages = new Map(Object.entries(data.resolved.messages))
			this.users = new Map()
			this.members = new Map()
		}
	}
}

/**
 * A manager to store command info and their callback along with a centralized
 * way to handle incoming commands and handle the errors that might arise from
 * their execution
 *
 * @template {Array<unknown>} Params
 */
class CommandManager {
	/**
	 * Commands assigned to this manager
	 * @type {Map<string, Command<Params>>}
	 * @readonly
	 */
	commands = new Map()
	/**
	 * Categories from assigned commands. Managed automatically
	 * @type {Map<string, Array<string>>}
	 * @readonly
	 */
	categories = new Map()

	/**
	 * Function to get the types and values for every or specific commands. Typically for all
	 * @type {(command: import("discord-api-types/v10").APIChatInputApplicationCommandInteraction) => Params}
	 */
	paramGetter
	/**
	 * Function to handle errors from command execution or from the reply function
	 * @type {((command: import("discord-api-types/v10").APIChatInputApplicationCommandInteraction, error: unknown) => unknown) | undefined}
	 */
	errorHandler

	/**
	 * @param {(command: import("discord-api-types/v10").APIChatInputApplicationCommandInteraction) => Params} paramGetter Function to get the types and values for every or specific commands. Typically for all
	 * @param {(command: import("discord-api-types/v10").APIChatInputApplicationCommandInteraction, error: unknown) => unknown} [errorHandler] Function to handle errors from command execution or from the reply function
	 */
	constructor(paramGetter, errorHandler) {
		this.paramGetter = paramGetter
		this.errorHandler = errorHandler
	}

	/**
	 * Assign commands to this manager
	 * @param {Array<Command<Params>>} properties An Array of commands
	 * @returns {void}
	 */
	assign(properties) {
		for (const cmd of properties) {
			if (this.commands.get(cmd.name)) this.commands.delete(cmd.name)
			this.commands.set(cmd.name, cmd)
			for (const inCategory of this.categories.values()) {
				if (inCategory.includes(cmd.name)) inCategory.splice(inCategory.indexOf(cmd.name), 1)
			}
			const cat = this.categories.get(cmd.category)
			if (!cat) this.categories.set(cmd.category, [cmd.name])
			else if (!cat.includes(cmd.name)) cat.push(cmd.name)
		}
	}

	/**
	 * Remove commands from this manager
	 * @param {Array<string>} commands An array of command names
	 * @returns {void}
	 */
	remove(commands) {
		for (const cmd of commands) {
			if (this.commands.get(cmd)) {
				this.commands.delete(cmd)
				for (const [category, inCategory] of this.categories.entries()) {
					if (inCategory.includes(cmd)) inCategory.splice(inCategory.indexOf(cmd), 1)
					if (inCategory.length === 0) this.categories.delete(category)
				}
			}
		}
	}

	/**
	 * Returns JSON representations of the commands this manager contains that can be sent to Discord directly.
	 * If you have localizations, you will need to add them yourself.
	 * @returns {import("discord-api-types/v10").RESTPutAPIApplicationCommandsJSONBody}
	 */
	toJSON() {
		return [...this.commands.values()].map(cmd => {
			return {
				name: cmd.name,
				type: cmd.type ?? 1,
				description: cmd.description,
				guild_ids: cmd.guild_ids,
				integration_types: cmd.integration_types,
				contexts: cmd.contexts,
				options: cmd.options,
				default_member_permissions: cmd.default_member_permissions ?? null
			}
		})
	}

	/**
	 * Handler for incoming chat input command interactions
	 * @param {import("discord-api-types/v10").APIChatInputApplicationCommandInteraction} cmd The interaction from Discord
	 * @param {() => Promise<unknown> | unknown} [replyFn] An optional function to reply to Discord
	 * @returns {boolean} A boolean of if the command was handled or not
	 */
	handle(cmd, replyFn) {
		if (!this.commands.has(cmd.data?.name)) return false

		this._handle(cmd, replyFn)

		return true
	}

	/**
	 * Actual handler for the async part of the handler. `handle` isn't async because Discord wants a reply ASAP.
	 * @param {import("discord-api-types/v10").APIChatInputApplicationCommandInteraction} cmd The interaction from Discord
	 * @param {() => Promise<unknown> | unknown} [replyFn] An optional function to reply to Discord
	 * @returns {Promise<void>}
	 * @private
	 */
	async _handle(cmd, replyFn) {
		const params = this.paramGetter(cmd)
		let returnValue
		try {
			await replyFn?.()
			const local = this.commands.get(cmd.data.name)
			assert(local)
			returnValue = local.process(...params)
		} catch (e) {
			this.errorHandler?.(cmd, e)
		}
		if (returnValue instanceof Promise) returnValue.catch(reason => this.errorHandler?.(cmd, reason))
	}
}

module.exports = {
	ChatInputCommand,
	ChatInputCommandData,
	CommandOption,
	ContextMenuCommand,
	ContextMenuCommandData,
	CommandManager
}