@lilsnibbi/discord 1.0.1

package/src/DiscordCommand.ts

@@ -0,0 +1,93 @@
+import type {
+	AutocompleteInteraction,
+	ChatInputCommandInteraction,
+	Client,
+	ContextMenuCommandBuilder,
+	ContextMenuCommandInteraction,
+	SlashCommandBuilder,
+	SlashCommandOptionsOnlyBuilder,
+	SlashCommandSubcommandsOnlyBuilder,
+} from "discord.js";
+
+/** Any builder discord.js accepts as an application command definition. */
+export type CommandData =
+	| SlashCommandBuilder
+	| SlashCommandOptionsOnlyBuilder
+	| SlashCommandSubcommandsOnlyBuilder
+	| ContextMenuCommandBuilder;
+
+/** Interactions a command's `execute` handler can receive. */
+export type CommandInteraction =
+	| ChatInputCommandInteraction
+	| ContextMenuCommandInteraction;
+
+/**
+ * Arbitrary per-command data, empty by default.
+ *
+ * Augment it via module declaration to give your own fields types across every
+ * command in the project.
+ *
+ * @example
+ * ```ts
+ * declare module "@lilsnibbi/discord" {
+ *   interface DiscordCommandMetadata {
+ *     cooldown?: number;
+ *     category?: string;
+ *   }
+ * }
+ * ```
+ */
+export interface DiscordCommandMetadata extends Record<string, unknown> {}
+
+/** Constructor options for {@link DiscordCommand}. */
+export interface DiscordCommandOptions<C extends Client = Client> {
+	/** The slash or context menu command definition. */
+	data: CommandData;
+	/** Consumer-defined data — see {@link DiscordCommandMetadata}. */
+	metadata: DiscordCommandMetadata;
+	/** Runs when the command is invoked. */
+	execute: (client: C, interaction: CommandInteraction) => void | Promise<void>;
+	/** Runs when an option with autocomplete enabled is focused. */
+	autocomplete?: (
+		client: C,
+		interaction: AutocompleteInteraction,
+	) => void | Promise<void>;
+}
+
+/**
+ * A discord.js slash or context menu command bundled with its handlers.
+ *
+ * Holding the definition and its handlers together lets a command loader read
+ * `data` for registration and call `execute` for dispatch without a separate
+ * lookup table.
+ *
+ * @typeParam C - The bot's `Client` type, forwarded to every handler.
+ *
+ * @example
+ * ```ts
+ * export default new DiscordCommand({
+ *   data: new SlashCommandBuilder().setName("ping").setDescription("Pong."),
+ *   metadata: {},
+ *   execute: async (_client, interaction) => {
+ *     await interaction.reply("Pong!");
+ *   },
+ * });
+ * ```
+ */
+export class DiscordCommand<C extends Client = Client> {
+	/** The slash or context menu command definition. */
+	public readonly data: CommandData;
+	/** Runs when the command is invoked. */
+	public readonly execute: DiscordCommandOptions<C>["execute"];
+	/** Runs when an option with autocomplete enabled is focused. */
+	public readonly autocomplete?: DiscordCommandOptions<C>["autocomplete"];
+	/** Consumer-defined data — see {@link DiscordCommandMetadata}. */
+	public metadata: DiscordCommandMetadata;
+
+	constructor(options: DiscordCommandOptions<C>) {
+		this.data = options.data;
+		this.metadata = options.metadata;
+		this.execute = options.execute;
+		this.autocomplete = options.autocomplete;
+	}
+}

package/src/DiscordEvent.ts

@@ -0,0 +1,126 @@
+import type { Client, ClientEvents, RestEvents } from "discord.js";
+
+/**
+ * Custom events, empty by default.
+ *
+ * Augment it via module declaration to make your own events available to
+ * {@link DiscordEvent} under `type: "custom"`.
+ *
+ * @example
+ * ```ts
+ * declare module "@lilsnibbi/discord" {
+ *   interface DiscordEventCustomType {
+ *     myEvent: [data: string];
+ *   }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: the empty shape is the extension point
+export interface DiscordEventCustomType {}
+
+/** Which discord.js emitter an event belongs to. */
+export type DiscordEventSource = "client" | "rest" | "custom";
+
+/**
+ * Shown instead of `never` when `type: "custom"` is used before any custom
+ * event has been declared, so autocomplete explains the missing augmentation
+ * rather than offering nothing.
+ */
+interface NoCustomEventsDeclared {
+	"augment DiscordEventCustomType to declare custom events": [];
+}
+
+/** Resolves an event source to the event map it emits. */
+export type EventMap<T extends DiscordEventSource> = T extends "client"
+	? ClientEvents
+	: T extends "rest"
+		? RestEvents
+		: keyof DiscordEventCustomType extends never
+			? NoCustomEventsDeclared
+			: DiscordEventCustomType;
+
+/** Resolves the listener argument tuple for a source and event name. */
+export type EventArgs<
+	T extends DiscordEventSource,
+	K extends keyof EventMap<T>,
+> = Extract<EventMap<T>[K], unknown[]>;
+
+/** Constructor options for {@link DiscordEvent}. */
+export interface DiscordEventOptions<
+	T extends DiscordEventSource,
+	K extends keyof EventMap<T>,
+	C extends Client = Client,
+> {
+	/** Which emitter the event comes from. */
+	type: T;
+	/** The event name, checked against the map `type` selects. */
+	name: K;
+	/** Detach the listener after its first call. Defaults to `false`. */
+	once?: boolean;
+	/** Runs when the event fires. */
+	method: (client: C, ...args: EventArgs<T, K>) => void | Promise<void>;
+}
+
+/**
+ * A discord.js event listener bundled with the metadata needed to register it.
+ *
+ * The `type` discriminant selects the event map `name` and the handler
+ * arguments are checked against, covering the gateway client, the REST manager,
+ * and any events declared through {@link DiscordEventCustomType}.
+ *
+ * @typeParam T - The event source.
+ * @typeParam K - The event name within that source's map.
+ * @typeParam C - The bot's `Client` type, forwarded to the handler.
+ *
+ * @example
+ * ```ts
+ * export default new DiscordEvent({
+ *   type: "client",
+ *   name: "messageCreate",
+ *   method: async (_client, message) => {
+ *     if (!message.author.bot) await message.react("👋");
+ *   },
+ * });
+ * ```
+ */
+export class DiscordEvent<
+	T extends DiscordEventSource,
+	K extends keyof EventMap<T> = keyof EventMap<T>,
+	C extends Client = Client,
+> {
+	/** Which emitter the event comes from. */
+	public readonly type: T;
+	/** The event name. */
+	public readonly name: K;
+	/** Whether the listener detaches after its first call. */
+	public readonly once: boolean;
+	/** Runs when the event fires. */
+	public readonly method: DiscordEventOptions<T, K, C>["method"];
+
+	constructor(options: DiscordEventOptions<T, K, C>) {
+		this.type = options.type;
+		this.name = options.name;
+		this.once = options.once ?? false;
+		this.method = options.method;
+	}
+}
+
+/**
+ * Any event, whatever its source — the shape a registry stores.
+ *
+ * {@link DiscordEvent} cannot be widened by passing the union to `T`:
+ * `keyof EventMap<DiscordEventSource>` is the *intersection* of the three
+ * maps' keys, which is `never`, so nothing would be assignable. Naming each
+ * source separately keeps `type` narrowable, and `any` for `K` collapses the
+ * per-event argument tuple that would otherwise make a concrete event
+ * incompatible under `strictFunctionTypes`.
+ *
+ * @typeParam C - The bot's `Client` type, forwarded to every handler.
+ */
+export type AnyDiscordEvent<C extends Client = Client> =
+	// biome-ignore lint/suspicious/noExplicitAny: widening K is the point
+	| DiscordEvent<"client", any, C>
+	// biome-ignore lint/suspicious/noExplicitAny: widening K is the point
+	| DiscordEvent<"rest", any, C>
+	// biome-ignore lint/suspicious/noExplicitAny: widening K is the point
+	| DiscordEvent<"custom", any, C>;

package/src/DiscordModuleLoader.ts

@@ -0,0 +1,49 @@
+import { resolve } from "node:path";
+import { stat } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+/** Discovery options, resolved relative to `custom.root`. */
+export interface DiscordModuleOptions {
+	/** Directory containing feature folders. Defaults to `custom.root`. */
+	directory?: string;
+	/** Explicit entrypoints only; no discovery happens when patterns are omitted. */
+	patterns?: readonly string[];
+}
+
+/**
+ * Discovers sorted, unique module entrypoints. Tests, declarations and
+ * node_modules are excluded even when a broad pattern is supplied.
+ */
+export async function discoverDiscordModules(
+	root: string,
+	options: DiscordModuleOptions,
+): Promise<string[]> {
+	const paths = new Set<string>();
+	const directory = resolve(root, options.directory ?? ".");
+	if (options.patterns?.length && !(await stat(directory)).isDirectory()) {
+		throw new Error(
+			`Discord module directory is not a directory: ${directory}`,
+		);
+	}
+	for (const pattern of options.patterns ?? []) {
+		for await (const path of new Bun.Glob(pattern).scan({
+			cwd: directory,
+			absolute: true,
+			onlyFiles: true,
+		})) {
+			const normalized = path.replaceAll("\\", "/");
+			if (
+				/\.(?:test|spec|d)\.[cm]?[jt]sx?$/.test(normalized) ||
+				/(?:^|\/)(?:node_modules|__tests__|__mocks__)(?:\/|$)/.test(normalized)
+			)
+				continue;
+			paths.add(resolve(path));
+		}
+	}
+	return [...paths].sort();
+}
+
+/** Imports via file URLs so Windows paths and reserved URL characters work. */
+export async function importDiscordModule(path: string): Promise<unknown> {
+	return (await import(pathToFileURL(path).href)).default;
+}