@kyvrixon/utils 1.0.11 → 1.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kyvrixon/utils",
 	"main": "./src/index.ts",
-	"version": "1.0.11",
+	"version": "1.4.0",
 	"type": "module",
 	"private": false,
 	"license": "MIT",
@@ -11,6 +11,7 @@
 	"engines": {
 		"bun": "1.3.11"
 	},
+	"engineStrict": true,
 	"repository": {
 		"url": "https://github.com/kyvrixon/utils"
 	},
@@ -18,12 +19,11 @@
 		"pub": "bun publish --access public",
 		"pretty": "bun biome format --write ."
 	},
-	"packageManager": "bun@1.3.10",
 	"types": "./src/index.ts",
 	"devDependencies": {
-		"@biomejs/biome": "2.4.6",
+		"@biomejs/biome": "2.4.9",
 		"@types/bun": "1.3.11",
-		"typescript": "5.9.3"
+		"typescript": "6.0.2"
 	},
 	"dependencies": {
 		"chalk": "5.6.2",
@@ -33,6 +33,10 @@
 		".": {
 			"types": "./src/index.ts",
 			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./src/lib/*/index.ts",
+			"import": "./src/lib/*/index.ts"
 		}
 	}
 }

package/src/lib/discord-utils/Command.ts

@@ -7,7 +7,21 @@ import type {
 	SlashCommandSubcommandsOnlyBuilder,
 } from "discord.js";
 
-export class DiscordCommand<C extends Client<boolean>> {
+export interface DiscordCommandMetadata extends Record<string, unknown> {}
+
+/**
+ * Wraps a discord.js slash command with typed `execute` and optional `autocomplete` handlers.
+ * @typeParam C - The bot's `Client` type. Inferred from args[0] in `method`.
+ *
+ * @example To extend the `metadata` types
+ * declare module "@kyvrixon/utils" {
+ *     interface DiscordCommandMetadata {
+ *         cooldown?: number;
+ *         category?: string;
+ *     }
+ * }
+ */
+export class DiscordCommand<C extends Client> {
 	public readonly data:
 		| SlashCommandBuilder
 		| SlashCommandOptionsOnlyBuilder
@@ -20,13 +34,16 @@ export class DiscordCommand<C extends Client<boolean>> {
 		client: C,
 		interaction: AutocompleteInteraction,
 	) => Promise<void>;
+	public metadata: DiscordCommandMetadata;
 
 	constructor(ops: {
 		data: DiscordCommand<C>["data"];
+		metadata: DiscordCommand<C>["metadata"];
 		execute: DiscordCommand<C>["execute"];
 		autocomplete?: DiscordCommand<C>["autocomplete"];
 	}) {
 		this.data = ops.data;
+		this.metadata = ops.metadata;
 		this.execute = ops.execute;
 		this.autocomplete = ops.autocomplete;
 	}

package/src/lib/discord-utils/Event.ts

@@ -1,6 +1,15 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: Its fine */
 import type { Client, ClientEvents, RestEvents } from "discord.js";
 
+/**
+ * Augment this interface via module declaration to register custom event types.
+ * @example
+ * declare module "@kyvrixon/utils" {
+ *   interface DiscordEventCustomType {
+ *     myEvent: [data: string];
+ *   }
+ * }
+ */
 // biome-ignore lint/suspicious/noEmptyInterface: Its fine
 export interface DiscordEventCustomType {}
 
@@ -20,13 +29,10 @@ type EventArgs<
 > = Extract<EventMap<T>[K], any[]>;
 
 /**
- * To define custom types:
- * @example
- * declare module "@kyvrixon/utils" {
- *   interface DiscordEventCustomType {
- *     myEventName: [data: string];
- *   }
- * }
+ * Wraps a discord.js event handler. Supports `"client"`, `"rest"`, and `"custom"` event types.
+ * @typeParam V - The bot's `Client` type.
+ * @typeParam T - The event source discriminant.
+ * @typeParam K - The event name within the chosen source.
  */
 export class DiscordEvent<
 	V extends Client,

package/src/lib/discord-utils/createPagination.ts

@@ -8,14 +8,16 @@ import {
 	type ChatInputCommandInteraction,
 	ComponentType,
 	ContainerBuilder,
-	type FileBuilder,
+	EmbedBuilder,
+	FileBuilder,
 	LabelBuilder,
-	type MediaGalleryBuilder,
+	MediaGalleryBuilder,
 	type MentionableSelectMenuBuilder,
+	type Message,
 	ModalBuilder,
 	type RoleSelectMenuBuilder,
-	type SectionBuilder,
-	type SeparatorBuilder,
+	SectionBuilder,
+	SeparatorBuilder,
 	type StringSelectMenuBuilder,
 	TextDisplayBuilder,
 	TextInputBuilder,
@@ -23,6 +25,7 @@ import {
 	type UserSelectMenuBuilder,
 } from "discord.js";
 
+/** An action row containing any interactive message component. */
 export type MessageActionRow = ActionRowBuilder<
 	| ButtonBuilder
 	| StringSelectMenuBuilder
@@ -32,8 +35,24 @@ export type MessageActionRow = ActionRowBuilder<
 	| MentionableSelectMenuBuilder
 >;
 
-export type LeaderboardComponentType =
+export const BUTTONS_SYMBOL: unique symbol = Symbol("pagination-buttons");
+export const DATA_SYMBOL: unique symbol = Symbol("pagination-data");
+
+/** Valid component types that can appear in a pagination page layout. */
+export type PaginationInput =
+	| string
+	| TextDisplayBuilder
+	| SectionBuilder
+	| SeparatorBuilder
+	| FileBuilder
+	| MediaGalleryBuilder
+	| MessageActionRow
+	| typeof BUTTONS_SYMBOL
+	| typeof DATA_SYMBOL;
+
+type InternalComponent =
 	| { type: "buttons" }
+	| { type: "data" }
 	| { type: "display"; component: TextDisplayBuilder }
 	| { type: "section"; component: SectionBuilder }
 	| { type: "separator"; component: SeparatorBuilder }
@@ -41,287 +60,464 @@ export type LeaderboardComponentType =
 	| { type: "gallery"; component: MediaGalleryBuilder }
 	| { type: "actionrow"; component: MessageActionRow };
 
-export interface LeaderboardOptions {
-	contentMarker?: string;
+/** Shared options for all pagination modes. */
+export interface PaginationBaseOptions {
+	/** Number of list entries shown per page (default: 5). */
 	entriesPerPage?: number;
+	/** Key-value pairs replaced in rendered content. */
 	replacements?: Record<string, string>;
-	styling?: Array<{ accent_color?: number; spoiler?: boolean }>;
+	/** Whether the pagination message is ephemeral. */
 	ephemeral?: boolean;
 }
 
-function applyReplacements(
-	content: string,
-	replacements?: Record<string, string>,
-): string {
-	if (!replacements) return content;
-	return Object.entries(replacements).reduce(
-		(acc, [key, value]) => acc.replaceAll(key, value),
-		content,
-	);
+/**
+ * Options for **container** mode (Components V2).
+ * Uses a `ContainerBuilder`-based layout with the `IsComponentsV2` message flag.
+ */
+export interface PaginationContainerOptions extends PaginationBaseOptions {
+	/** Selects container mode. */
+	type: "container";
+	/** Single layout template using sentinels `DiscordPagination.DATA` and `DiscordPagination.BUTTONS`. */
+	layout: PaginationInput[];
+	/** Container accent color. */
+	accentColor?: number;
+	/** Whether the container is a spoiler. */
+	spoiler?: boolean;
 }
 
-function getPaginationRow(
-	prefix: string,
-	currentIndex: number,
-	entriesPerPage: number,
-	totalPages: number,
-	listLength: number,
-	ended: boolean,
-): ActionRowBuilder<ButtonBuilder> {
-	return new ActionRowBuilder<ButtonBuilder>().addComponents(
-		new ButtonBuilder()
-			.setCustomId(`${prefix}back`)
-			.setLabel("Prev")
-			.setStyle(ButtonStyle.Secondary)
-			.setDisabled(ended || currentIndex === 0),
-		new ButtonBuilder()
-			.setCustomId(`${prefix}info`)
-			.setLabel(
-				`${Math.floor(currentIndex / entriesPerPage) + 1}/${totalPages}`,
-			)
-			.setStyle(ButtonStyle.Secondary)
-			.setDisabled(ended || totalPages === 1),
-		new ButtonBuilder()
-			.setCustomId(`${prefix}forward`)
-			.setLabel("Next")
-			.setStyle(ButtonStyle.Secondary)
-			.setDisabled(ended || currentIndex + entriesPerPage >= listLength),
-	);
+/**
+ * Options for **embed** mode.
+ * Uses a standard `EmbedBuilder` with an `ActionRow` for navigation buttons.
+ * The embed's `description` and `footer` are reserved for page data and the page counter.
+ */
+export interface PaginationEmbedOptions extends PaginationBaseOptions {
+	/** Selects embed mode. */
+	type: "embed";
+	/** EmbedBuilder template. Description and footer are overwritten per page. */
+	embed: EmbedBuilder;
 }
 
-export async function createPagination(
-	list: Array<string>,
-	structure: Array<Array<LeaderboardComponentType>>,
-	interaction: ButtonInteraction | ChatInputCommandInteraction,
-	options: LeaderboardOptions = {},
-) {
-	const {
-		entriesPerPage = 5,
-		replacements,
-		styling,
-		ephemeral = false,
-		contentMarker = "--DATA_INPUT--",
-	} = options;
-
-	if (entriesPerPage <= 0)
-		throw new Error("entriesPerPage must be greater than 0");
-
-	const uID = randomUUIDv7();
-	const prefix = `~PAGINATION_${uID}_`;
-	let currentIndex = 0;
-	let ended = false;
-
-	if (!list.length) {
-		await interaction
-			.reply({
-				allowedMentions: {
-					parse: [],
-					repliedUser: false,
-				},
-				components: [
-					new ContainerBuilder().addTextDisplayComponents(
-						new TextDisplayBuilder().setContent("No data to show"),
+/** Discriminated union of all pagination option types. Use the `type` field to select a mode. */
+export type PaginationOptions =
+	| PaginationContainerOptions
+	| PaginationEmbedOptions;
+
+/**
+ * Discord paginator supporting both **Components V2** (`ContainerBuilder`) and
+ * **Embed** (`EmbedBuilder`) modes.
+ *
+ * @example Container mode
+ * ```ts
+ * const pagination = new DiscordPagination(entries, {
+ *     type: "container",
+ *     layout: [
+ *         "# Leaderboard",
+ *         new SeparatorBuilder(),
+ *         DiscordPagination.DATA,
+ *         new SeparatorBuilder(),
+ *         DiscordPagination.BUTTONS,
+ *     ],
+ *     entriesPerPage: 5,
+ *     accentColor: 0x5865f2,
+ * });
+ * ```
+ *
+ * @example Embed mode
+ * ```ts
+ * const pagination = new DiscordPagination(entries, {
+ *     type: "embed",
+ *     embed: new EmbedBuilder().setTitle("Leaderboard").setColor(0x5865f2),
+ *     entriesPerPage: 5,
+ * });
+ * ```
+ */
+export class DiscordPagination {
+	/** Sentinel — marks where the pagination buttons should render. */
+	static readonly BUTTONS: typeof BUTTONS_SYMBOL = BUTTONS_SYMBOL;
+	/** Sentinel — marks where the paginated list entries should render. */
+	static readonly DATA: typeof DATA_SYMBOL = DATA_SYMBOL;
+
+	private readonly list: string[];
+	private readonly entriesPerPage: number;
+	private readonly replacements?: Record<string, string>;
+	private readonly ephemeral: boolean;
+	private readonly prefix: string;
+	private readonly totalPages: number;
+	private readonly mode: "container" | "embed";
+
+	// Container mode
+	private readonly layout?: InternalComponent[];
+	private readonly accentColor?: number;
+	private readonly spoiler?: boolean;
+
+	// Embed mode
+	private readonly embedTemplate?: EmbedBuilder;
+
+	// Runtime state
+	private currentIndex = 0;
+	private ended = false;
+	private isMessage = false;
+	private interaction?: ButtonInteraction | ChatInputCommandInteraction;
+	private replyMessage?: Message;
+
+	constructor(list: string[], options: PaginationOptions) {
+		const { entriesPerPage = 5, replacements, ephemeral = false } = options;
+
+		if (entriesPerPage <= 0)
+			throw new Error("entriesPerPage must be greater than 0");
+
+		this.list = list;
+		this.entriesPerPage = entriesPerPage;
+		this.replacements = replacements;
+		this.ephemeral = ephemeral;
+		this.prefix = `~PAGINATION_${randomUUIDv7()}_`;
+		this.totalPages = Math.ceil(list.length / entriesPerPage);
+
+		this.mode = options.type;
+
+		if (options.type === "container") {
+			this.layout = options.layout.map((input) => this.normalize(input));
+			this.accentColor = options.accentColor;
+			this.spoiler = options.spoiler;
+		} else {
+			this.embedTemplate = options.embed;
+		}
+	}
+
+	/**
+	 * Sends the paginated message and starts the button collector.
+	 * @param target - The interaction or message to reply to.
+	 */
+	public async send(
+		target: ButtonInteraction | ChatInputCommandInteraction | Message,
+	): Promise<void> {
+		this.isMessage = !("deferReply" in target);
+		const userId = this.isMessage
+			? (target as Message).author.id
+			: (target as ButtonInteraction | ChatInputCommandInteraction).user.id;
+
+		if (!this.list.length) {
+			await this.sendEmpty(target);
+			return;
+		}
+
+		if (this.isMessage) {
+			this.replyMessage = await (target as Message).reply(this.buildPayload());
+		} else {
+			const interaction = target as
+				| ButtonInteraction
+				| ChatInputCommandInteraction;
+			this.interaction = interaction;
+
+			if (!interaction.replied && !interaction.deferred) {
+				const response = await interaction
+					.deferReply({
+						withResponse: true,
+						flags: this.ephemeral ? ["Ephemeral"] : [],
+					})
+					.catch(() => null);
+				this.replyMessage =
+					response?.resource?.message ??
+					(await interaction.fetchReply().catch(() => undefined));
+			} else {
+				this.replyMessage = await interaction
+					.fetchReply()
+					.catch(() => undefined);
+			}
+
+			await this.render();
+		}
+
+		if (!this.replyMessage) return;
+
+		const collector = this.replyMessage.createMessageComponentCollector({
+			componentType: ComponentType.Button,
+			time: 60_000,
+		});
+
+		collector.on("collect", async (btn) => {
+			if (btn.user.id !== userId) {
+				return void btn.deferUpdate();
+			}
+			if (!btn.customId.startsWith(this.prefix)) return;
+
+			this.ended = false;
+			collector.resetTimer();
+
+			if (btn.customId === `${this.prefix}info`) {
+				await this.handlePageJump(btn);
+			} else {
+				this.currentIndex +=
+					btn.customId === `${this.prefix}back`
+						? -this.entriesPerPage
+						: this.entriesPerPage;
+				this.currentIndex = Math.max(
+					0,
+					Math.min(
+						this.currentIndex,
+						(this.totalPages - 1) * this.entriesPerPage,
 					),
-				],
-				flags: ephemeral ? ["Ephemeral", "IsComponentsV2"] : ["IsComponentsV2"],
-			})
-			.catch(() => {});
-		return;
+				);
+				await btn.deferUpdate().catch(() => {});
+			}
+
+			await this.render();
+		});
+
+		collector.on("end", async () => {
+			this.ended = true;
+			await this.render();
+		});
 	}
 
-	const totalPages = Math.ceil(list.length / entriesPerPage);
-	const lastPage = structure[structure.length - 1];
+	private async sendEmpty(
+		target: ButtonInteraction | ChatInputCommandInteraction | Message,
+	): Promise<void> {
+		if (this.mode === "embed" && !this.embedTemplate)
+			throw new Error(
+				"[@kyvrixon/utils]: Pagination: embedTemplate is in a corrupted state",
+			);
 
-	if (!lastPage) throw new Error("createLeaderboard is in a corrupted state");
+		const allowedMentions = { parse: [] as const, repliedUser: false };
+
+		if (this.isMessage) {
+			const payload =
+				this.mode === "container"
+					? {
+							components: [
+								new ContainerBuilder().addTextDisplayComponents(
+									new TextDisplayBuilder().setContent("No data to show"),
+								),
+							],
+							flags: ["IsComponentsV2"] as const,
+							allowedMentions,
+						}
+					: {
+							embeds: [
+								new EmbedBuilder(this.embedTemplate?.toJSON()).setDescription(
+									"No data to show",
+								),
+							],
+							allowedMentions,
+						};
+			await (target as Message).reply(payload).catch(() => {});
+		} else {
+			const payload =
+				this.mode === "container"
+					? {
+							components: [
+								new ContainerBuilder().addTextDisplayComponents(
+									new TextDisplayBuilder().setContent("No data to show"),
+								),
+							],
+							flags: this.ephemeral
+								? (["Ephemeral", "IsComponentsV2"] as const)
+								: (["IsComponentsV2"] as const),
+							allowedMentions,
+						}
+					: {
+							embeds: [
+								new EmbedBuilder(this.embedTemplate?.toJSON()).setDescription(
+									"No data to show",
+								),
+							],
+							flags: this.ephemeral ? (["Ephemeral"] as const) : ([] as const),
+							allowedMentions,
+						};
+			await (target as ButtonInteraction | ChatInputCommandInteraction)
+				.reply(payload)
+				.catch(() => {});
+		}
+	}
 
-	while (structure.length < totalPages) {
-		structure.push(
-			lastPage.map((comp) => {
-				if (comp.type === "display") {
-					return {
-						type: "display",
-						component: new TextDisplayBuilder(comp.component.toJSON()),
-					};
-				}
-				return comp;
-			}),
-		);
+	private normalize(input: PaginationInput): InternalComponent {
+		if (input === BUTTONS_SYMBOL) return { type: "buttons" };
+		if (input === DATA_SYMBOL) return { type: "data" };
+		if (typeof input === "string")
+			return {
+				type: "display",
+				component: new TextDisplayBuilder().setContent(input),
+			};
+		if (input instanceof TextDisplayBuilder)
+			return { type: "display", component: input };
+		if (input instanceof SeparatorBuilder)
+			return { type: "separator", component: input };
+		if (input instanceof SectionBuilder)
+			return { type: "section", component: input };
+		if (input instanceof FileBuilder) return { type: "file", component: input };
+		if (input instanceof MediaGalleryBuilder)
+			return { type: "gallery", component: input };
+		return { type: "actionrow", component: input };
+	}
+
+	private buildPayload() {
+		if (this.mode === "embed") {
+			return {
+				embeds: [this.generateEmbed()],
+				components: [this.getPaginationRow()],
+				allowedMentions: { parse: [] as const, repliedUser: false },
+			};
+		}
+
+		return {
+			components: [this.generateContainer()],
+			flags: ["IsComponentsV2"] as const,
+			allowedMentions: { parse: [] as const, repliedUser: false },
+		};
 	}
 
-	function generateContainer(page: number): ContainerBuilder {
-		const pageStructure = structure[page];
-		if (!pageStructure) throw new Error(`Page ${page} structure not found`);
+	private generateContainer(): ContainerBuilder {
+		if (!this.layout)
+			throw new Error(
+				"[@kyvrixon/utils]: Pagination: layout is in a corrupted state",
+			);
+
+		const page = Math.floor(this.currentIndex / this.entriesPerPage);
 
 		return new ContainerBuilder({
-			components: pageStructure.map((comp) => {
+			components: this.layout.map((comp) => {
 				switch (comp.type) {
 					case "buttons":
-						return getPaginationRow(
-							prefix,
-							currentIndex,
-							entriesPerPage,
-							totalPages,
-							list.length,
-							ended,
-						).toJSON();
-
-					case "display": {
-						if (comp.component.data.content !== contentMarker) {
-							return comp.component.toJSON();
-						}
+						return this.getPaginationRow().toJSON();
 
-						const content = list
+					case "data": {
+						const content = this.list
 							.slice(
-								page * entriesPerPage,
-								page * entriesPerPage + entriesPerPage,
+								page * this.entriesPerPage,
+								(page + 1) * this.entriesPerPage,
 							)
 							.join("\n");
-						comp.component.data.content = applyReplacements(
-							content,
-							replacements,
-						);
-						return comp.component.toJSON();
+						return new TextDisplayBuilder()
+							.setContent(this.applyReplacements(content))
+							.toJSON();
 					}
 
-					case "section":
-					case "separator":
-					case "file":
-					case "gallery":
-					case "actionrow":
+					default:
 						return comp.component.toJSON();
-
-					default: {
-						return comp;
-					}
 				}
 			}),
-			accent_color: styling?.[page]?.accent_color,
-			spoiler: styling?.[page]?.spoiler,
+			accent_color: this.accentColor,
+			spoiler: this.spoiler,
 		});
 	}
 
-	if (!interaction.replied && !interaction.deferred) {
-		await interaction
-			.deferReply({
-				withResponse: true,
-				flags: ephemeral ? ["Ephemeral"] : [],
-			})
-			.catch(() => null);
-	}
+	private generateEmbed(): EmbedBuilder {
+		if (!this.embedTemplate)
+			throw new Error(
+				"[@kyvrixon/utils]: Pagination: embedTemplate is in a corrupted state",
+			);
 
-	const channel = interaction.channel;
-	if (!channel || !("createMessageComponentCollector" in channel)) {
-		throw new Error("Invalid channel type");
+		const page = Math.floor(this.currentIndex / this.entriesPerPage);
+		const content = this.list
+			.slice(page * this.entriesPerPage, (page + 1) * this.entriesPerPage)
+			.join("\n");
+
+		return new EmbedBuilder(this.embedTemplate.toJSON())
+			.setDescription(this.applyReplacements(content))
+			.setFooter({ text: `Page ${page + 1}/${this.totalPages}` });
 	}
 
-	async function render(): Promise<void> {
-		try {
-			await interaction.editReply({
-				components: [
-					generateContainer(Math.floor(currentIndex / entriesPerPage)),
-				],
-				flags: ["IsComponentsV2"],
-				allowedMentions: {
-					parse: [],
-					repliedUser: false,
-				},
-			});
-		} catch (error) {
-			const e = error as Error;
-			if (!e.message.includes("Unknown Message")) {
-				console.error("Failed to render leaderboard:", error);
-			}
-		}
+	private getPaginationRow(): ActionRowBuilder<ButtonBuilder> {
+		return new ActionRowBuilder<ButtonBuilder>().addComponents(
+			new ButtonBuilder()
+				.setCustomId(`${this.prefix}back`)
+				.setLabel("Prev")
+				.setStyle(ButtonStyle.Secondary)
+				.setDisabled(this.ended || this.currentIndex === 0),
+			new ButtonBuilder()
+				.setCustomId(`${this.prefix}info`)
+				.setLabel(
+					`${Math.floor(this.currentIndex / this.entriesPerPage) + 1}/${this.totalPages}`,
+				)
+				.setStyle(ButtonStyle.Secondary)
+				.setDisabled(this.ended || this.totalPages === 1 || this.isMessage),
+			new ButtonBuilder()
+				.setCustomId(`${this.prefix}forward`)
+				.setLabel("Next")
+				.setStyle(ButtonStyle.Secondary)
+				.setDisabled(
+					this.ended ||
+						this.currentIndex + this.entriesPerPage >= this.list.length,
+				),
+		);
 	}
 
-	await render();
+	private async handlePageJump(btn: ButtonInteraction): Promise<void> {
+		const modal = new ModalBuilder()
+			.setCustomId(`${this.prefix}modal`)
+			.setTitle("Page Indexer")
+			.addLabelComponents(
+				new LabelBuilder()
+					.setLabel("Input a page number")
+					.setTextInputComponent(
+						new TextInputBuilder()
+							.setCustomId(`${this.prefix}number`)
+							.setRequired(true)
+							.setMinLength(1)
+							.setStyle(TextInputStyle.Short),
+					),
+			);
 
-	const collector = channel.createMessageComponentCollector({
-		componentType: ComponentType.Button,
-		time: 60000,
-	});
+		await btn.showModal(modal).catch((e) => console.error(e));
+		const modalSubmit = await btn
+			.awaitModalSubmit({ time: 60_000 })
+			.catch(() => null);
 
-	collector.on("collect", async (btn) => {
-		if (btn.user.id !== interaction.user.id) {
-			return void btn.deferUpdate();
+		if (!modalSubmit) {
+			await btn
+				.followUp({
+					content: "Modal timed out.",
+					flags: ["Ephemeral"],
+				})
+				.catch(() => null);
+			return;
 		}
 
-		if (!btn.customId.startsWith(prefix)) return;
-
-		ended = false;
-		collector.resetTimer();
-
-		if (btn.customId === `${prefix}info`) {
-			const modal = new ModalBuilder()
-				.setCustomId(`${prefix}modal`)
-				.setTitle("Page Indexer")
-				.addLabelComponents(
-					new LabelBuilder()
-						// .setDescription("Input a page number")
-						.setLabel("Input a page number")
-						.setTextInputComponent(
-							new TextInputBuilder()
-								.setCustomId(`${prefix}number`)
-								.setRequired(true)
-								.setMinLength(1)
-								.setStyle(TextInputStyle.Short),
-						),
-				);
+		const pageNumber = Number(
+			modalSubmit.fields.getTextInputValue(`${this.prefix}number`),
+		);
 
-			await btn.showModal(modal).catch((e) => console.error(e));
-			const modalSubmit = await btn
-				.awaitModalSubmit({ time: 60_000 })
-				.catch((e) => console.error(e));
+		if (
+			!Number.isInteger(pageNumber) ||
+			pageNumber < 1 ||
+			pageNumber > this.totalPages
+		) {
+			await modalSubmit
+				.reply({
+					content: `Invalid page! Choose a number between **1** and **${this.totalPages}**.`,
+					flags: ["Ephemeral"],
+					allowedMentions: { parse: [], repliedUser: false },
+				})
+				.catch(() => null);
+			return;
+		}
 
-			if (!modalSubmit) {
-				await btn
-					.followUp({
-						content: "Modal timed out.",
-						flags: ["Ephemeral"],
-					})
-					.catch(() => null);
-				return;
-			}
+		await modalSubmit.deferUpdate().catch(() => null);
+		this.currentIndex = (pageNumber - 1) * this.entriesPerPage;
+	}
 
-			await modalSubmit.deferUpdate().catch(() => null);
-			const pageNumber = Number(
-				modalSubmit.fields.getTextInputValue(`${prefix}number`),
-			);
+	private applyReplacements(content: string): string {
+		if (!this.replacements) return content;
+		return Object.entries(this.replacements).reduce(
+			(acc, [key, value]) => acc.replaceAll(key, value),
+			content,
+		);
+	}
 
-			if (
-				Number.isNaN(pageNumber) ||
-				pageNumber < 1 ||
-				pageNumber > totalPages
-			) {
-				await modalSubmit
-					.reply({
-						content: `Invalid page! Choose a number between **1** and **${totalPages}**.`,
-						flags: ["Ephemeral"],
-						allowedMentions: {
-							parse: [],
-							repliedUser: false,
-						},
-					})
-					.catch(() => null);
-				return;
-			}
+	private async render(): Promise<void> {
+		try {
+			const payload = this.buildPayload();
 
-			currentIndex = (pageNumber - 1) * entriesPerPage;
-		} else {
-			currentIndex +=
-				btn.customId === `${prefix}back` ? -entriesPerPage : entriesPerPage;
-			currentIndex = Math.max(
-				0,
-				Math.min(currentIndex, (totalPages - 1) * entriesPerPage),
-			);
-			await btn.deferUpdate().catch(() => {});
+			if (this.isMessage && this.replyMessage) {
+				await this.replyMessage.edit(payload);
+			} else if (this.interaction) {
+				await this.interaction.editReply(payload);
+			}
+		} catch (error) {
+			const e = error as Error;
+			if (!e.message.includes("Unknown Message")) {
+				console.error("Failed to render pagination:", error);
+			}
 		}
-
-		await render();
-	});
-
-	collector.on("end", async () => {
-		ended = true;
-		await render();
-	});
+	}
 }

package/src/lib/discord-utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./Command";
+export * from "./createPagination";
+export * from "./Event";

package/src/lib/formatSeconds.ts

@@ -25,6 +25,16 @@ const ALL_UNITS_ORDER: Array<TimeUnitTypes> = [
 	"ms",
 ];
 
+/**
+ * Calendar-aware duration formatter. Converts raw seconds into a human-readable string.
+ * @param seconds - The duration in seconds to format.
+ * @param options - Formatting options.
+ * @param options.format - `"long"` (default) for full words, `"short"` for abbreviated units.
+ * @param options.onlyUnits - Restrict output to specific time units.
+ * @param options.includeZeroUnits - Include units with a value of zero.
+ * @param options.customFormatter - Override per-unit rendering.
+ * @returns A formatted duration string (e.g. `"2 hours and 30 minutes"` or `"2h 30m"`).
+ */
 export function formatSeconds(
 	seconds: number,
 	options: {
@@ -44,10 +54,13 @@ export function formatSeconds(
 		format = "long",
 		customFormatter,
 	} = options;
+
+	if (!Number.isFinite(seconds)) return format === "short" ? "0s" : "0 seconds";
+
 	let totalMs = Math.max(0, Math.round(seconds * 1000));
-	const unitsToDisplay = ALL_UNITS_ORDER.filter((u) =>
-		onlyUnits.length ? onlyUnits.includes(u) : true,
-	);
+	const unitsToDisplay = onlyUnits.length
+		? ALL_UNITS_ORDER.filter((u) => onlyUnits.includes(u))
+		: ALL_UNITS_ORDER;
 
 	const diff: Partial<Record<TimeUnitTypes, number>> = {};
 	const now = new Date();
@@ -55,28 +68,29 @@ export function formatSeconds(
 
 	if (unitsToDisplay.includes("y")) {
 		let y = end.getFullYear() - now.getFullYear();
-		const tempDate = new Date(now);
-		tempDate.setFullYear(now.getFullYear() + y);
-		if (tempDate > end) y--;
-		diff.y = y;
-		totalMs -= new Date(now).setFullYear(now.getFullYear() + y) - now.getTime();
+		const afterYears = new Date(now);
+		afterYears.setFullYear(now.getFullYear() + y);
+		if (afterYears > end) y--;
+		diff.y = Math.max(0, y);
+		totalMs -=
+			new Date(now).setFullYear(now.getFullYear() + diff.y) - now.getTime();
 	}
 
 	if (unitsToDisplay.includes("mo")) {
 		const startTotalMonths = now.getFullYear() * 12 + now.getMonth();
 		const endTotalMonths = end.getFullYear() * 12 + end.getMonth();
 		let mo = endTotalMonths - startTotalMonths;
-		if (diff.y) mo -= diff.y * 12;
+		if (diff.y !== undefined) mo -= diff.y * 12;
 
-		const tempDate = new Date(now);
-		tempDate.setFullYear(now.getFullYear() + (diff.y || 0));
-		tempDate.setMonth(now.getMonth() + mo);
-		if (tempDate > end) mo--;
+		const afterYearsAndMonths = new Date(now);
+		afterYearsAndMonths.setFullYear(now.getFullYear() + (diff.y ?? 0));
+		afterYearsAndMonths.setMonth(now.getMonth() + mo);
+		if (afterYearsAndMonths > end) mo--;
 
 		diff.mo = Math.max(0, mo);
 		const jumpDate = new Date(now);
-		jumpDate.setFullYear(now.getFullYear() + (diff.y || 0));
-		jumpDate.setMonth(now.getMonth() + (diff.mo || 0));
+		jumpDate.setFullYear(now.getFullYear() + (diff.y ?? 0));
+		jumpDate.setMonth(now.getMonth() + diff.mo);
 		totalMs = end.getTime() - jumpDate.getTime();
 	}
 

package/src/lib/modules/LoggerModule.ts

@@ -10,6 +10,10 @@ const formatter = new Intl.DateTimeFormat("en-AU", {
 	hour12: false,
 });
 
+/**
+ * Chalk-based structured logger with timestamped, color-coded output.
+ * Supports levels: `notif`, `alert`, `error`, `debug`.
+ */
 export class LoggerModule {
 	private readonly colors: Record<LogLevel, typeof chalk> = {
 		notif: cyan,
@@ -37,10 +41,15 @@ export class LoggerModule {
 		const timestamp = gray(`[${this.getTimestamp()}]`);
 		const levelLabel = bold(this.colors[level](level.toUpperCase().padEnd(5)));
 
-		const content =
-			message instanceof Error
-				? `${red(message.message)}\n${this.sanitizeStack(message.stack || "")}`
-				: String(message);
+		let content: string;
+		if (message instanceof Error) {
+			const stack = this.sanitizeStack(message.stack || "");
+			content = stack
+				? `${red(message.message)}\n${stack}`
+				: red(message.message);
+		} else {
+			content = String(message);
+		}
 
 		return `${timestamp} ${levelLabel} ${dim("»")} ${content}`;
 	}
@@ -76,21 +85,32 @@ export class LoggerModule {
 		console[this.logMethods[level]](msg);
 	}
 
+	/** Logs at the `notif` (info) level. If `raw` is true, returns the string instead of printing. */
 	public notif(m: unknown, raw = false) {
 		return this.log("notif", m, raw);
 	}
+	/** Logs at the `alert` (warn) level. If `raw` is true, returns the string instead of printing. */
 	public alert(m: unknown, raw = false) {
 		return this.log("alert", m, raw);
 	}
+	/**
+	 * Logs at the `error` level. Pass an optional `Error` to include its sanitized stack trace.
+	 * If `raw` is true, returns the string instead of printing.
+	 */
 	public error(m: unknown, e?: Error, raw = false) {
 		return this.log("error", e ?? m, raw);
 	}
+	/** Logs at the `debug` level. If `raw` is true, returns the string instead of printing. */
 	public debug(m: unknown, raw = false) {
 		return this.log("debug", m, raw);
 	}
 
+	/** Prints a centered `─` divider line with the given text. */
 	public divider(text: string): void {
-		const line = dim("─".repeat(Math.max(0, (50 - text.length - 2) / 2)));
-		console.log(`\n${line} ${bold(text.trim())} ${line}`);
+		const trimmed = text.trim();
+		const remaining = Math.max(0, 50 - trimmed.length - 2);
+		const left = dim("─".repeat(Math.ceil(remaining / 2)));
+		const right = dim("─".repeat(Math.floor(remaining / 2)));
+		console.log(`\n${left} ${bold(trimmed)} ${right}`);
 	}
 }

package/src/lib/modules/index.ts

@@ -0,0 +1 @@
+export * from "./LoggerModule";

package/src/lib/toOrdinal.ts

@@ -9,6 +9,12 @@ const suffixes: Record<Intl.LDMLPluralRule, string> = {
 	many: "th",
 };
 
+/**
+ * Converts a number to its English ordinal string (e.g. 1 → "1st", 12 → "12th").
+ * Handles teens, zero, negatives, and infinities.
+ * @param n - The number to convert.
+ * @returns The number with its ordinal suffix appended.
+ */
 export function toOrdinal(n: number): string {
 	return `${n}${suffixes[pr.select(n)]}`;
 }