@lilsnibbi/discord 1.0.1

package/src/DiscordShutdown.ts

@@ -0,0 +1,110 @@
+/** A named shutdown phase. Tasks within a phase run concurrently. */
+export interface DiscordShutdownPhase {
+	label: string;
+	tasks: readonly ((signal: AbortSignal) => unknown | Promise<unknown>)[];
+	/** Per-phase deadline; defaults to 1,500ms. */
+	timeoutMs?: number;
+}
+
+/** Options for bounded, best-effort shutdown. */
+export interface DiscordShutdownOptions {
+	/** Total deadline shared by all phases; defaults to 7,000ms. */
+	budgetMs?: number;
+	/** Receives task failures, phase timeouts, and skipped phases. */
+	onError?: (label: string, error: unknown) => void | Promise<void>;
+}
+
+/** Reject invalid timer values rather than allowing immediate/overflow timers. */
+export function validateShutdownTimeout(value: number): void {
+	if (!Number.isFinite(value) || value <= 0 || value > 2_147_483_647) {
+		throw new RangeError(
+			"Shutdown timeouts must be between 0 and 2147483647ms",
+		);
+	}
+}
+
+/**
+ * Runs phases in order, continuing after failures. A timed-out phase receives
+ * an aborted signal; tasks must cooperate with cancellation. No process exit
+ * or signal handlers are installed. Returns every failure, including timeouts.
+ */
+export async function runDiscordShutdown(
+	phases: readonly DiscordShutdownPhase[],
+	options: DiscordShutdownOptions = {},
+): Promise<{ label: string; error: unknown }[]> {
+	const budget = options.budgetMs ?? 7_000;
+	validateShutdownTimeout(budget);
+	for (const phase of phases) validateShutdownTimeout(phase.timeoutMs ?? 1_500);
+	const deadline = performance.now() + budget;
+	const failures: { label: string; error: unknown }[] = [];
+	const report = async (label: string, error: unknown) => {
+		failures.push({ label, error });
+		try {
+			const reporter = Promise.resolve(options.onError?.(label, error)).then(
+				() => ({ status: "fulfilled" }) as const,
+				(reportError: unknown) =>
+					({ status: "rejected", error: reportError }) as const,
+			);
+			const remaining = deadline - performance.now();
+			if (remaining <= 0) {
+				void reporter;
+				return;
+			}
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const result = await Promise.race([
+				reporter,
+				new Promise<{ status: "timed-out" }>((resolve) => {
+					timer = setTimeout(() => resolve({ status: "timed-out" }), remaining);
+				}),
+			]);
+			clearTimeout(timer);
+			if (result.status === "rejected") {
+				failures.push({ label: `${label}:reporter`, error: result.error });
+			} else if (result.status === "timed-out") {
+				failures.push({
+					label: `${label}:reporter`,
+					error: new Error(
+						"Shutdown error reporter exceeded the remaining budget",
+					),
+				});
+			}
+		} catch (reportError) {
+			failures.push({ label: `${label}:reporter`, error: reportError });
+		}
+	};
+	for (const phase of phases) {
+		const remaining = deadline - performance.now();
+		if (remaining <= 0) {
+			await report(
+				phase.label,
+				new Error("Shutdown budget exhausted; phase skipped"),
+			);
+			continue;
+		}
+		const controller = new AbortController();
+		const timeoutMs = Math.min(phase.timeoutMs ?? 1_500, remaining);
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const results = await Promise.race([
+			Promise.allSettled(
+				phase.tasks.map((task) =>
+					Promise.resolve().then(() => task(controller.signal)),
+				),
+			),
+			new Promise<null>((resolve) => {
+				timer = setTimeout(() => resolve(null), timeoutMs);
+			}),
+		]);
+		clearTimeout(timer);
+		if (results === null) {
+			const error = new Error(`Shutdown phase timed out after ${timeoutMs}ms`);
+			controller.abort(error);
+			await report(phase.label, error);
+		} else {
+			for (const result of results) {
+				if (result.status === "rejected")
+					await report(phase.label, result.reason);
+			}
+		}
+	}
+	return failures;
+}

package/src/container.ts

@@ -0,0 +1,65 @@
+import type { DiscordClient } from "./DiscordClient";
+
+/**
+ * The shared dependency bag, reachable from any module without threading the
+ * client through every constructor.
+ *
+ * Augment it via module declaration to register your own singletons alongside
+ * the client.
+ *
+ * @example
+ * ```ts
+ * declare module "@lilsnibbi/discord" {
+ *   interface Container {
+ *     db: Database;
+ *   }
+ * }
+ * ```
+ */
+export interface Container {
+	/** The live client, assigned by the `DiscordClient` constructor. */
+	client: DiscordClient;
+}
+
+/**
+ * The process-wide {@link Container}.
+ *
+ * It is a mutable object rather than a re-exported binding so importers always
+ * read the current value, and it is empty until a `DiscordClient` is
+ * constructed — reach for {@link getClient} if you need that guarded.
+ *
+ * @example
+ * ```ts
+ * import { container } from "@lilsnibbi/discord";
+ *
+ * container.client.log.notif("ready");
+ * ```
+ */
+export const container = {} as Container;
+
+/**
+ * Returns the active client, throwing before construction or after destruction.
+ *
+ * Pass a client class to also check its runtime type and retrieve subclass members.
+ * @throws {Error} If no active client exists or its class does not match.
+ */
+export function getClient(): DiscordClient;
+export function getClient<C extends DiscordClient>(
+	clientType: abstract new (...args: never[]) => C,
+): C;
+export function getClient(
+	clientType?: abstract new (...args: never[]) => DiscordClient,
+): DiscordClient {
+	if (!container.client) {
+		throw new Error(
+			"No DiscordClient has been constructed yet — the container is empty.",
+		);
+	}
+	if (clientType && !(container.client instanceof clientType)) {
+		throw new Error(
+			`The active DiscordClient is not an instance of ${clientType.name}`,
+		);
+	}
+
+	return container.client;
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Entry point for `@lilsnibbi/discord`.
+ *
+ * Requires the `discord.js` peer dependency. The client publishes itself to
+ * `container`, and the command, event and pagination structures are the pieces
+ * a bot registers against it.
+ */
+export * from "./container";
+export * from "./DiscordClient";
+export * from "./DiscordCommand";
+export * from "./DiscordEvent";
+export * from "./DiscordPagination";
+export type { DiscordModuleOptions } from "./DiscordModuleLoader";
+export { runDiscordShutdown } from "./DiscordShutdown";
+export type {
+	DiscordShutdownPhase,
+	DiscordShutdownOptions,
+} from "./DiscordShutdown";