@kyvrixon/utils 1.0.10 → 1.0.12

package/README.md

@@ -4,6 +4,4 @@ General utility files I use for alot of projects! Designed for use with the [bun
 
 ```bash
 bun install @kyvrixon/utils
-# or
-bun install github:kyvrixon/utils#1.0.10
-```
+```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kyvrixon/utils",
 	"main": "./src/index.ts",
-	"version": "1.0.10",
+	"version": "1.0.12",
 	"type": "module",
 	"private": false,
 	"license": "MIT",
@@ -9,21 +9,20 @@
 		"src"
 	],
 	"engines": {
-		"bun": "1.3.10"
+		"bun": "1.3.11"
 	},
 	"repository": {
 		"url": "https://github.com/kyvrixon/utils"
 	},
 	"scripts": {
-		"pub": "bun prebuild.ts && bun publish --access public",
+		"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",
-		"@types/bun": "1.3.10",
-		"typescript": "5.9.3"
+		"@biomejs/biome": "2.4.9",
+		"@types/bun": "1.3.11",
+		"typescript": "6.0.2"
 	},
 	"dependencies": {
 		"chalk": "5.6.2",

package/src/index.ts

@@ -3,4 +3,4 @@ export * from "./lib/toOrdinal";
 export * from "./lib/discord-utils/Command";
 export * from "./lib/discord-utils/createPagination";
 export * from "./lib/discord-utils/Event";
-export * from "./lib/modules/LoggerModule";
+export * from "./lib/modules/LoggerModule";

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

@@ -7,6 +7,10 @@ import type {
 	SlashCommandSubcommandsOnlyBuilder,
 } from "discord.js";
 
+/**
+ * Wraps a discord.js slash command with typed `execute` and optional `autocomplete` handlers.
+ * @typeParam C - The bot's `Client` type.
+ */
 export class DiscordCommand<C extends Client<boolean>> {
 	public readonly data:
 		| SlashCommandBuilder

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

@@ -1,61 +1,61 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: Its fine */
 import type { Client, ClientEvents, RestEvents } from "discord.js";
 
-// biome-ignore lint/suspicious/noEmptyInterface: Its fine
-export interface DiscordEventCustomType {}
 /**
- * To define custom types:
+ * Augment this interface via module declaration to register custom event types.
  * @example
  * declare module "@kyvrixon/utils" {
- * 	interface DiscordEventCustomType {
- *			myEventName: [data: string];
- *		}
- * }
- * // You can also add these to `ClientEvents` if you wish for better typing like so:
- * declare module "discord.js" {
- * 	interface ClientEvents extends DiscordEventCustomType {}
+ *   interface DiscordEventCustomType {
+ *     myEvent: [data: string];
+ *   }
  * }
  */
+// biome-ignore lint/suspicious/noEmptyInterface: Its fine
+export interface DiscordEventCustomType {}
+
+/** Maps an event type discriminant to its corresponding event map. */
+type EventMap<T extends "client" | "rest" | "custom"> = T extends "client"
+	? ClientEvents
+	: T extends "rest"
+		? RestEvents
+		: keyof DiscordEventCustomType extends never
+			? { "sooo.. there's no custom events..": [] }
+			: DiscordEventCustomType;
+
+/** Resolves the argument tuple for a given event type + key pair. */
+type EventArgs<
+	T extends "client" | "rest" | "custom",
+	K extends keyof EventMap<T>,
+> = Extract<EventMap<T>[K], any[]>;
+
+/**
+ * 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,
-	T extends "client" | "custom" | "rest" = "client",
-	K extends T extends "custom"
-		? keyof DiscordEventCustomType
-		: T extends "client"
-			? keyof ClientEvents
-			: keyof RestEvents = T extends "custom"
-		? keyof DiscordEventCustomType
-		: T extends "client"
-			? keyof ClientEvents
-			: keyof RestEvents,
+	T extends "client" | "rest" | "custom",
+	K extends keyof EventMap<T> = keyof EventMap<T>,
 > {
 	public readonly type: T;
 	public readonly name: K;
 	public readonly once: boolean;
 	public readonly method: (
 		client: V,
-		...args: T extends "client"
-			? K extends keyof ClientEvents
-				? ClientEvents[K]
-				: any[]
-			: T extends "rest"
-				? K extends keyof RestEvents
-					? RestEvents[K]
-					: any[]
-				: K extends keyof DiscordEventCustomType
-					? DiscordEventCustomType[K]
-					: any[]
-	) => Promise<void>;
+		...args: EventArgs<T, K>
+	) => void | Promise<void>;
 
 	constructor(opts: {
 		type: T;
 		name: K;
-		once?: boolean;
+		once: boolean;
 		method: DiscordEvent<V, T, K>["method"];
 	}) {
 		this.type = opts.type;
 		this.name = opts.name;
-		this.once = opts.once ?? false;
+		this.once = opts.once;
 		this.method = opts.method;
 	}
 }

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

@@ -8,14 +8,14 @@ import {
 	type ChatInputCommandInteraction,
 	ComponentType,
 	ContainerBuilder,
-	type FileBuilder,
+	FileBuilder,
 	LabelBuilder,
-	type MediaGalleryBuilder,
+	MediaGalleryBuilder,
 	type MentionableSelectMenuBuilder,
 	ModalBuilder,
 	type RoleSelectMenuBuilder,
-	type SectionBuilder,
-	type SeparatorBuilder,
+	SectionBuilder,
+	SeparatorBuilder,
 	type StringSelectMenuBuilder,
 	TextDisplayBuilder,
 	TextInputBuilder,
@@ -23,6 +23,7 @@ import {
 	type UserSelectMenuBuilder,
 } from "discord.js";
 
+/** An action row containing any interactive message component. */
 export type MessageActionRow = ActionRowBuilder<
 	| ButtonBuilder
 	| StringSelectMenuBuilder
@@ -32,8 +33,24 @@ export type MessageActionRow = ActionRowBuilder<
 	| MentionableSelectMenuBuilder
 >;
 
-export type LeaderboardComponentType =
+const BUTTONS_SYMBOL: unique symbol = Symbol("pagination-buttons");
+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 +58,356 @@ export type LeaderboardComponentType =
 	| { type: "gallery"; component: MediaGalleryBuilder }
 	| { type: "actionrow"; component: MessageActionRow };
 
-export interface LeaderboardOptions {
-	contentMarker?: string;
+export interface PaginationOptions {
+	/** Number of list entries shown per page (default: 5). */
 	entriesPerPage?: number;
+	/** Key-value pairs replaced in rendered content. */
 	replacements?: Record<string, string>;
+	/** Per-page container styling overrides. */
 	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,
-	);
-}
+/**
+ * Discord Components V2 paginator. Renders a `ContainerBuilder`-based layout
+ * with Prev/Next/page-jump buttons. Collector expires after 60 seconds.
+ *
+ * Use `DiscordPagination.BUTTONS` and `DiscordPagination.DATA` as sentinel
+ * values in the structure array to position the navigation row and list data.
+ *
+ * @example
+ * const pagination = new DiscordPagination(
+ *    entries,
+ *    [
+ *        [
+ *            "# Leaderboard",
+ *            new SeparatorBuilder(),
+ *            DiscordPagination.DATA,
+ *            new SeparatorBuilder(),
+ *            DiscordPagination.BUTTONS,
+ *        ],
+ *    ],
+ *    {
+ *        entriesPerPage: 5,
+ *        ephemeral: false,
+ *        styling: [{ accent_color: 0x5865f2 }],
+ *    },
+ * );
+ */
+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 structure: Array<Array<InternalComponent>>;
+	private readonly entriesPerPage: number;
+	private readonly replacements?: Record<string, string>;
+	private readonly styling?: PaginationOptions["styling"];
+	private readonly ephemeral: boolean;
+	private readonly prefix: string;
+	private readonly totalPages: number;
+
+	private currentIndex = 0;
+	private ended = false;
+	private interaction!: ButtonInteraction | ChatInputCommandInteraction;
+
+	constructor(
+		list: string[],
+		structure: Array<Array<PaginationInput>>,
+		options: PaginationOptions = {},
+	) {
+		const {
+			entriesPerPage = 5,
+			replacements,
+			styling,
+			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.styling = styling;
+		this.ephemeral = ephemeral;
+		this.prefix = `~PAGINATION_${randomUUIDv7()}_`;
+		this.totalPages = Math.ceil(list.length / entriesPerPage);
+		this.structure = this.expandStructure(
+			structure.map((page) => page.map((input) => this.normalize(input))),
+		);
+	}
 
-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),
-	);
-}
+	/**
+	 * Sends the paginated message and starts the button collector.
+	 * @param interaction - The interaction to reply to.
+	 */
+	public async send(
+		interaction: ButtonInteraction | ChatInputCommandInteraction,
+	): Promise<void> {
+		this.interaction = interaction;
+
+		if (!this.list.length) {
+			await interaction
+				.reply({
+					allowedMentions: { parse: [], repliedUser: false },
+					components: [
+						new ContainerBuilder().addTextDisplayComponents(
+							new TextDisplayBuilder().setContent("No data to show"),
+						),
+					],
+					flags: this.ephemeral
+						? ["Ephemeral", "IsComponentsV2"]
+						: ["IsComponentsV2"],
+				})
+				.catch(() => {});
+			return;
+		}
 
-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"),
+		if (!interaction.replied && !interaction.deferred) {
+			await interaction
+				.deferReply({
+					withResponse: true,
+					flags: this.ephemeral ? ["Ephemeral"] : [],
+				})
+				.catch(() => null);
+		}
+
+		const channel = interaction.channel;
+		if (!channel || !("createMessageComponentCollector" in channel)) {
+			throw new Error("Invalid channel type");
+		}
+
+		await this.render();
+
+		const collector = channel.createMessageComponentCollector({
+			componentType: ComponentType.Button,
+			time: 60000,
+		});
+
+		collector.on("collect", async (btn) => {
+			if (btn.user.id !== interaction.user.id) {
+				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 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 };
+	}
 
-	if (!lastPage) throw new Error("createLeaderboard is in a corrupted state");
+	private expandStructure(
+		structure: Array<Array<InternalComponent>>,
+	): Array<Array<InternalComponent>> {
+		const lastPage = structure[structure.length - 1];
+		if (!lastPage) throw new Error("Structure must have at least one page");
+
+		while (structure.length < this.totalPages) {
+			structure.push(this.clonePage(lastPage));
+		}
+
+		return structure;
+	}
 
-	while (structure.length < totalPages) {
-		structure.push(
-			lastPage.map((comp) => {
-				if (comp.type === "display") {
-					return {
-						type: "display",
+	private clonePage(page: Array<InternalComponent>): Array<InternalComponent> {
+		return page.map((comp) =>
+			comp.type === "display"
+				? {
+						type: "display" as const,
 						component: new TextDisplayBuilder(comp.component.toJSON()),
-					};
-				}
-				return comp;
-			}),
+					}
+				: comp,
+		);
+	}
+
+	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),
+					),
+			);
+
+		await btn.showModal(modal).catch((e) => console.error(e));
+		const modalSubmit = await btn
+			.awaitModalSubmit({ time: 60_000 })
+			.catch(() => null);
+
+		if (!modalSubmit) {
+			await btn
+				.followUp({
+					content: "Modal timed out.",
+					flags: ["Ephemeral"],
+				})
+				.catch(() => null);
+			return;
+		}
+
+		const pageNumber = Number(
+			modalSubmit.fields.getTextInputValue(`${this.prefix}number`),
 		);
+
+		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;
+		}
+
+		await modalSubmit.deferUpdate().catch(() => null);
+		this.currentIndex = (pageNumber - 1) * this.entriesPerPage;
 	}
 
-	function generateContainer(page: number): ContainerBuilder {
-		const pageStructure = structure[page];
+	private generateContainer(page: number): ContainerBuilder {
+		const pageStructure = this.structure[page];
 		if (!pageStructure) throw new Error(`Page ${page} structure not found`);
 
 		return new ContainerBuilder({
 			components: pageStructure.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();
-						}
-
-						const content = list
+						return this.getPaginationRow().toJSON();
+
+					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 clause applies to the below as well
+					// case "display":
+					// 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.styling?.[page]?.accent_color,
+			spoiler: this.styling?.[page]?.spoiler,
 		});
 	}
 
-	if (!interaction.replied && !interaction.deferred) {
-		await interaction
-			.deferReply({
-				withResponse: true,
-				flags: ephemeral ? ["Ephemeral"] : [],
-			})
-			.catch(() => null);
+	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),
+			new ButtonBuilder()
+				.setCustomId(`${this.prefix}forward`)
+				.setLabel("Next")
+				.setStyle(ButtonStyle.Secondary)
+				.setDisabled(
+					this.ended ||
+						this.currentIndex + this.entriesPerPage >= this.list.length,
+				),
+		);
 	}
 
-	const channel = interaction.channel;
-	if (!channel || !("createMessageComponentCollector" in channel)) {
-		throw new Error("Invalid channel type");
+	private applyReplacements(content: string): string {
+		if (!this.replacements) return content;
+		return Object.entries(this.replacements).reduce(
+			(acc, [key, value]) => acc.replaceAll(key, value),
+			content,
+		);
 	}
 
-	async function render(): Promise<void> {
+	private async render(): Promise<void> {
 		try {
-			await interaction.editReply({
+			await this.interaction.editReply({
 				components: [
-					generateContainer(Math.floor(currentIndex / entriesPerPage)),
+					this.generateContainer(
+						Math.floor(this.currentIndex / this.entriesPerPage),
+					),
 				],
 				flags: ["IsComponentsV2"],
-				allowedMentions: {
-					parse: [],
-					repliedUser: false,
-				},
+				allowedMentions: { parse: [], repliedUser: false },
 			});
 		} catch (error) {
 			const e = error as Error;
 			if (!e.message.includes("Unknown Message")) {
-				console.error("Failed to render leaderboard:", error);
+				console.error("Failed to render pagination:", error);
 			}
 		}
 	}
-
-	await render();
-
-	const collector = channel.createMessageComponentCollector({
-		componentType: ComponentType.Button,
-		time: 60000,
-	});
-
-	collector.on("collect", async (btn) => {
-		if (btn.user.id !== interaction.user.id) {
-			return void btn.deferUpdate();
-		}
-
-		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),
-						),
-				);
-
-			await btn.showModal(modal).catch((e) => console.error(e));
-			const modalSubmit = await btn
-				.awaitModalSubmit({ time: 60_000 })
-				.catch((e) => console.error(e));
-
-			if (!modalSubmit) {
-				await btn
-					.followUp({
-						content: "Modal timed out.",
-						flags: ["Ephemeral"],
-					})
-					.catch(() => null);
-				return;
-			}
-
-			await modalSubmit.deferUpdate().catch(() => null);
-			const pageNumber = Number(
-				modalSubmit.fields.getTextInputValue(`${prefix}number`),
-			);
-
-			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;
-			}
-
-			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(() => {});
-		}
-
-		await render();
-	});
-
-	collector.on("end", async () => {
-		ended = true;
-		await render();
-	});
-}
+}

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/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)]}`;
 }