@wolfstar/http-framework 3.2.1 → 3.3.0-next-20260901122142

package/dist/esm/index.js

@@ -5,12 +5,58 @@ import { AsyncEventEmitter } from "@vladfrangu/async_event_emitter";
 import { ApplicationCommandOptionType, ApplicationCommandType, ComponentType, InteractionResponseType, InteractionType, PermissionFlagsBits, Routes } from "discord-api-types/v10";
 import { createServer } from "node:http";
 import { Result, err, ok } from "@sapphire/result";
+import { relative } from "node:path";
 import { Collection } from "@discordjs/collection";
 import { ContextMenuCommandBuilder, SlashCommandBuilder, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder } from "@discordjs/builders";
 import { isJSONEncodable } from "@discordjs/util";
 import { webcrypto } from "node:crypto";
 import { TextDecoder } from "node:util";
 
+//#region src/lib/ClientEvents.ts
+/**
+* The name of every event emitted by the {@link Client}, mirroring the keys of {@link ClientEvents}.
+*
+* @remarks
+* Each member's value is the plain event name, so they are interchangeable with the string literals
+* accepted by `Client#on`, `Client#emit`, and {@link Listener.Options.event}.
+*
+* @example
+* ```typescript
+* client.on(Events.CommandError, (error, context) => console.error(context.command.name, error));
+* ```
+*
+* @since 3.4.0
+*/
+let Events = /* @__PURE__ */ function(Events) {
+	Events["Error"] = "error";
+	Events["PluginLoaded"] = "pluginLoaded";
+	Events["CommandNameMissing"] = "commandNameMissing";
+	Events["CommandNameUnknown"] = "commandNameUnknown";
+	Events["CommandMethodUnknown"] = "commandMethodUnknown";
+	Events["CommandRun"] = "commandRun";
+	Events["CommandSuccess"] = "commandSuccess";
+	Events["CommandError"] = "commandError";
+	Events["CommandFinish"] = "commandFinish";
+	Events["AutocompleteRun"] = "autocompleteRun";
+	Events["AutocompleteSuccess"] = "autocompleteSuccess";
+	Events["AutocompleteError"] = "autocompleteError";
+	Events["AutocompleteFinish"] = "autocompleteFinish";
+	Events["InteractionHandlerNameInvalid"] = "interactionHandlerNameInvalid";
+	Events["InteractionHandlerNameUnknown"] = "interactionHandlerNameUnknown";
+	Events["InteractionHandlerRun"] = "interactionHandlerRun";
+	Events["InteractionHandlerSuccess"] = "interactionHandlerSuccess";
+	Events["InteractionHandlerError"] = "interactionHandlerError";
+	Events["InteractionHandlerFinish"] = "interactionHandlerFinish";
+	Events["HmrStart"] = "hmrStart";
+	Events["HmrStop"] = "hmrStop";
+	Events["HmrPiecesLoaded"] = "hmrPiecesLoaded";
+	Events["HmrPieceReloaded"] = "hmrPieceReloaded";
+	Events["HmrPieceUnloaded"] = "hmrPieceUnloaded";
+	Events["HmrError"] = "hmrError";
+	return Events;
+}({});
+
+//#endregion
 //#region src/lib/api/HttpCodes.ts
 let HttpCodes = /* @__PURE__ */ function(HttpCodes) {
 	/**
@@ -391,42 +437,6 @@ let HttpCodes = /* @__PURE__ */ function(HttpCodes) {
 	return HttpCodes;
 }({});
 
-//#endregion
-//#region src/lib/components/StringIdParser.ts
-var StringIdParser = class {
-	run(customId) {
-		if (customId.length === 0) return null;
-		const index = customId.indexOf(".");
-		if (index === -1) return {
-			name: customId,
-			content: null
-		};
-		return {
-			name: customId.slice(0, index),
-			content: customId.slice(index + 1).split(".").map((contentEntry) => contentEntry || null)
-		};
-	}
-};
-
-//#endregion
-//#region src/lib/types/Enums.ts
-let PluginHook = /* @__PURE__ */ function(PluginHook) {
-	PluginHook["PreGenericsInitialization"] = "preGenericsInitialization";
-	PluginHook["PreInitialization"] = "preInitialization";
-	PluginHook["PostInitialization"] = "postInitialization";
-	PluginHook["PreLoad"] = "preLoad";
-	PluginHook["PostListen"] = "postListen";
-	return PluginHook;
-}({});
-
-//#endregion
-//#region src/lib/plugins/symbols.ts
-const preGenericsInitialization = Symbol("HttpFrameworkPluginsPreGenericsInitialization");
-const preInitialization = Symbol("HttpFrameworkPluginsPreInitialization");
-const postInitialization = Symbol("HttpFrameworkPluginsPostInitialization");
-const preLoad = Symbol("HttpFrameworkPluginsPreLoad");
-const postListen = Symbol("HttpFrameworkPluginsPostListen");
-
 //#endregion
 //#region \0@oxc-project+runtime@0.144.0/helpers/esm/typeof.js
 function _typeof(o) {
@@ -469,6 +479,218 @@ function _defineProperty(e, r, t) {
 	}) : e[r] = t, e;
 }
 
+//#endregion
+//#region \0@oxc-project+runtime@0.144.0/helpers/esm/checkPrivateRedeclaration.js
+function _checkPrivateRedeclaration(e, t) {
+	if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object");
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.144.0/helpers/esm/classPrivateFieldInitSpec.js
+function _classPrivateFieldInitSpec(e, t, a) {
+	_checkPrivateRedeclaration(e, t), t.set(e, a);
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.144.0/helpers/esm/assertClassBrand.js
+function _assertClassBrand(e, t, n) {
+	if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n;
+	throw new TypeError("Private element is not present on this object");
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.144.0/helpers/esm/classPrivateFieldGet2.js
+function _classPrivateFieldGet2(s, a) {
+	return s.get(_assertClassBrand(s, a));
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.144.0/helpers/esm/classPrivateFieldSet2.js
+function _classPrivateFieldSet2(s, a, r) {
+	return s.set(_assertClassBrand(s, a), r), r;
+}
+
+//#endregion
+//#region src/lib/hmr/HotModuleReloader.ts
+var _watchers = /* @__PURE__ */ new WeakMap();
+var _running = /* @__PURE__ */ new WeakMap();
+/**
+* Hot Module Reloading for every {@link Store} registered in {@link container.stores}.
+*
+* @remarks The reloader watches each store's registered paths and reacts to file system events by loading, reloading,
+* and unloading the affected pieces in place, without restarting the process. It is a development-only utility: watching
+* the file system in production adds overhead and reloads code that is not supposed to change, which is why it is
+* opt-in.
+* @since 3.3.0
+* @example
+* ```typescript
+* const client = new Client({ hmr: { enabled: process.env.NODE_ENV !== 'production' } });
+* await client.load();
+* ```
+*/
+var HotModuleReloader = class {
+	constructor(options = {}) {
+		_defineProperty(this, "options", void 0);
+		_classPrivateFieldInitSpec(this, _watchers, []);
+		_classPrivateFieldInitSpec(this, _running, false);
+		this.options = options;
+	}
+	/**
+	* Whether the reloader is currently watching for changes.
+	*
+	* @since 3.3.0
+	*/
+	get running() {
+		return _classPrivateFieldGet2(_running, this);
+	}
+	/**
+	* The paths currently being watched, one entry per store path.
+	*
+	* @since 3.3.0
+	*/
+	get paths() {
+		return _classPrivateFieldGet2(_watchers, this).flatMap((watcher) => Object.keys(watcher.getWatched()));
+	}
+	/**
+	* Starts watching every path registered in every store.
+	*
+	* @remarks This is a no-op when {@link HotModuleReloader.Options.enabled} is `false`, when the reloader is already
+	* running, or when no store has registered paths. `chokidar` is imported lazily, so applications that never enable
+	* HMR do not pay for loading it.
+	* @since 3.3.0
+	* @returns This instance, for chaining.
+	*/
+	async start() {
+		if (_classPrivateFieldGet2(_running, this)) return this;
+		const { enabled = true, silent = false, ...chokidarOptions } = this.options;
+		if (!enabled) return this;
+		const { watch } = await import("chokidar");
+		const watchedPaths = [];
+		for (const store of container$1.stores.values()) {
+			const paths = [...store.paths];
+			if (paths.length === 0) continue;
+			watchedPaths.push(...paths);
+			_classPrivateFieldGet2(_watchers, this).push(watch(paths, {
+				ignoreInitial: true,
+				...chokidarOptions
+			}).on("add", (path) => void this.handlePieceUpdate(store, path)).on("change", (path) => void this.handlePieceUpdate(store, path)).on("unlink", (path) => void this.handlePieceDelete(store, path)));
+		}
+		_classPrivateFieldSet2(_running, this, true);
+		if (!silent) console.info(`[HMR]: Enabled, watching ${watchedPaths.length} path(s) for piece changes.`);
+		container$1.client?.emit("hmrStart", watchedPaths);
+		return this;
+	}
+	/**
+	* Stops watching for changes and closes every watcher.
+	*
+	* @remarks Calling this on a reloader that is not running is a no-op. Already loaded pieces are left untouched.
+	* @since 3.3.0
+	*/
+	async stop() {
+		if (!_classPrivateFieldGet2(_running, this)) return;
+		const watchers = _classPrivateFieldGet2(_watchers, this);
+		_classPrivateFieldSet2(_watchers, this, []);
+		_classPrivateFieldSet2(_running, this, false);
+		await Promise.all(watchers.map((watcher) => watcher.close()));
+		if (!this.options.silent) console.info("[HMR]: Disabled, no longer watching for piece changes.");
+		container$1.client?.emit("hmrStop");
+	}
+	/**
+	* Handles a file being added to, or modified in, one of the store's paths, reloading the piece it defines when it is
+	* already loaded, and loading it otherwise.
+	*
+	* @since 3.3.0
+	* @param store - The store the path belongs to.
+	* @param path - The full path of the file that changed.
+	*/
+	async handlePieceUpdate(store, path) {
+		if (!store.strategy.filter(path)) return;
+		const piece = store.find((entry) => entry.location.full === path);
+		(await Result.fromAsync(async () => {
+			if (piece) {
+				await piece.reload();
+				if (!this.options.silent) console.info(`[HMR]: Reloaded '${piece.name}' from the '${store.name}' store.`);
+				container$1.client?.emit("hmrPieceReloaded", piece, path);
+				return;
+			}
+			const root = [...store.paths].find((storePath) => path.startsWith(storePath));
+			if (!root) throw new Error(`Could not find the root path for '${path}'.`);
+			const pieces = await store.load(root, relative(root, path));
+			if (!this.options.silent) {
+				const names = pieces.map((entry) => `'${entry.name}'`).join(", ");
+				console.info(`[HMR]: Loaded ${pieces.length} piece(s) into the '${store.name}' store: ${names}.`);
+			}
+			container$1.client?.emit("hmrPiecesLoaded", pieces, path);
+		})).inspectErr((error) => this.handleError(error, path));
+	}
+	/**
+	* Handles a file being removed from one of the store's paths, unloading the piece it defined.
+	*
+	* @since 3.3.0
+	* @param store - The store the path belongs to.
+	* @param path - The full path of the file that was deleted.
+	*/
+	async handlePieceDelete(store, path) {
+		if (!store.strategy.filter(path)) return;
+		const piece = store.find((entry) => entry.location.full === path);
+		if (!piece) return;
+		(await Result.fromAsync(async () => {
+			await piece.unload();
+			if (!this.options.silent) console.info(`[HMR]: Unloaded '${piece.name}' from the '${store.name}' store.`);
+			container$1.client?.emit("hmrPieceUnloaded", piece, path);
+		})).inspectErr((error) => this.handleError(error, path));
+	}
+	/**
+	* Handles an error thrown while (re)loading or unloading a piece.
+	*
+	* @remarks Errors are never rethrown: a broken file must not take the process down, the user is expected to fix it
+	* and save again, which triggers a new reload.
+	* @since 3.3.0
+	* @param error - The error that was thrown.
+	* @param path - The full path of the file that was being processed.
+	*/
+	handleError(error, path) {
+		if (!this.options.silent) console.error(`[HMR]: Failed to process '${path}'.`, error);
+		container$1.client?.emit("hmrError", error, path);
+	}
+};
+
+//#endregion
+//#region src/lib/components/StringIdParser.ts
+var StringIdParser = class {
+	run(customId) {
+		if (customId.length === 0) return null;
+		const index = customId.indexOf(".");
+		if (index === -1) return {
+			name: customId,
+			content: null
+		};
+		return {
+			name: customId.slice(0, index),
+			content: customId.slice(index + 1).split(".").map((contentEntry) => contentEntry || null)
+		};
+	}
+};
+
+//#endregion
+//#region src/lib/types/Enums.ts
+let PluginHook = /* @__PURE__ */ function(PluginHook) {
+	PluginHook["PreGenericsInitialization"] = "preGenericsInitialization";
+	PluginHook["PreInitialization"] = "preInitialization";
+	PluginHook["PostInitialization"] = "postInitialization";
+	PluginHook["PreLoad"] = "preLoad";
+	PluginHook["PostListen"] = "postListen";
+	return PluginHook;
+}({});
+
+//#endregion
+//#region src/lib/plugins/symbols.ts
+const preGenericsInitialization = Symbol("HttpFrameworkPluginsPreGenericsInitialization");
+const preInitialization = Symbol("HttpFrameworkPluginsPreInitialization");
+const postInitialization = Symbol("HttpFrameworkPluginsPostInitialization");
+const preLoad = Symbol("HttpFrameworkPluginsPreLoad");
+const postListen = Symbol("HttpFrameworkPluginsPostListen");
+
 //#endregion
 //#region src/lib/plugins/PluginManager.ts
 var PluginManager = class {
@@ -910,43 +1132,12 @@ function getLinkedMethod(object) {
 	return Reflect.get(object, linkSymbol) ?? null;
 }
 
-//#endregion
-//#region \0@oxc-project+runtime@0.144.0/helpers/esm/checkPrivateRedeclaration.js
-function _checkPrivateRedeclaration(e, t) {
-	if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object");
-}
-
 //#endregion
 //#region \0@oxc-project+runtime@0.144.0/helpers/esm/classPrivateMethodInitSpec.js
 function _classPrivateMethodInitSpec(e, a) {
 	_checkPrivateRedeclaration(e, a), a.add(e);
 }
 
-//#endregion
-//#region \0@oxc-project+runtime@0.144.0/helpers/esm/classPrivateFieldInitSpec.js
-function _classPrivateFieldInitSpec(e, t, a) {
-	_checkPrivateRedeclaration(e, t), t.set(e, a);
-}
-
-//#endregion
-//#region \0@oxc-project+runtime@0.144.0/helpers/esm/assertClassBrand.js
-function _assertClassBrand(e, t, n) {
-	if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n;
-	throw new TypeError("Private element is not present on this object");
-}
-
-//#endregion
-//#region \0@oxc-project+runtime@0.144.0/helpers/esm/classPrivateFieldSet2.js
-function _classPrivateFieldSet2(s, a, r) {
-	return s.set(_assertClassBrand(s, a), r), r;
-}
-
-//#endregion
-//#region \0@oxc-project+runtime@0.144.0/helpers/esm/classPrivateFieldGet2.js
-function _classPrivateFieldGet2(s, a) {
-	return s.get(_assertClassBrand(s, a));
-}
-
 //#endregion
 //#region src/lib/interactions/resolvers/ChatInputCommandResolver.ts
 var _data$1 = /* @__PURE__ */ new WeakMap();
@@ -3225,6 +3416,10 @@ var CommandLoaderStrategy = class extends LoaderStrategy {
 	/**
 	* Called when a command is unloaded.
 	*
+	* @remarks This also drops the command's {@link ApplicationCommandRegistryEntry} from the
+	* {@link ApplicationCommandRegistry}. The registry is keyed by command class, and reloading a command evaluates its
+	* module again, producing a brand new class: without this, the entry of the previous class would linger and the
+	* command would be pushed to Discord twice.
 	* @since 2.0.0
 	* @param store - The command store.
 	* @param piece - The command being unloaded.
@@ -3233,6 +3428,7 @@ var CommandLoaderStrategy = class extends LoaderStrategy {
 	onUnload(store, piece) {
 		if (piece.router.chatInputName) store.router.removeChatInputMapping(piece.router.chatInputName);
 		for (const name of piece.router.contextMenuNames) store.router.removeContextMenuMapping(name);
+		container$1.applicationCommandRegistry.delete(piece.constructor);
 		return piece;
 	}
 };
@@ -3611,6 +3807,7 @@ var Client = class Client extends AsyncEventEmitter {
 	constructor(options = {}) {
 		super();
 		_defineProperty(this, "server", void 0);
+		_defineProperty(this, "hmr", null);
 		_defineProperty(this, "id", void 0);
 		_defineProperty(this, "options", void 0);
 		_defineProperty(this, "bodySizeLimit", void 0);
@@ -3681,6 +3878,10 @@ var Client = class Client extends AsyncEventEmitter {
 		}
 		if (options.baseUserDirectory !== null) container$1.stores.registerPath(options.baseUserDirectory);
 		await container$1.stores.load();
+		if (this.options.hmr && (this.options.hmr.enabled ?? true)) {
+			this.hmr = new HotModuleReloader(this.options.hmr);
+			await this.hmr.start();
+		}
 	}
 	/**
 	* Starts the HTTP server, listening for HTTP interactions.
@@ -4140,5 +4341,5 @@ _defineProperty(Plugin, preLoad, void 0);
 _defineProperty(Plugin, postListen, void 0);
 
 //#endregion
-export { AliasPiece, AliasStore, ApplicationCommandRegistry, ApplicationCommandRegistryEntry, ApplyOptions, ArgumentError, AutocompleteInteraction, BaseInteraction, ChatInputCommandInteraction, ChatInputRouterError, ChatInputRouterErrors, Client, Command, CommandInteraction, CommandLoaderStrategy, CommandRegistry, CommandRouter, CommandStore, CommandStoreRouter, Enumerable, EnumerableMethod, HttpCodes, Identifiers, InteractionHandler, InteractionHandlerStore, Listener, ListenerLoaderStrategy, ListenerStore, LoaderError, Message, MessageComponentButtonInteraction, MessageComponentChannelSelectInteraction, MessageComponentInteraction, MessageComponentMentionableSelectInteraction, MessageComponentRoleSelectInteraction, MessageComponentStringSelectInteraction as MessageComponentSelectMenuInteraction, MessageComponentStringSelectInteraction, MessageComponentUserSelectInteraction, MessageContextMenuCommandInteraction, MissingExportsError, ModalSubmitInteraction, PartialMessage, Piece, Plugin, PluginHook, PluginManager, PreconditionError, RegisterCommand, RegisterMessageCommand, RegisterSubcommand, RegisterSubcommandGroup, RegisterUserCommand, RequiresClientPermissions, RequiresDMContext, RequiresGuildContext, RequiresUserPermissions, RestrictGuildIds, Store, StoreRegistry, StringIdParser, UserContextMenuCommandInteraction, UserError, applicationCommandRegistry, container, createClassDecorator, createFunctionPrecondition, createMethodDecorator, createProxy, extractTopLevelOptions, getMissingPermissions, makeInteraction, postInitialization, postListen, preGenericsInitialization, preInitialization, preLoad, resolvePermissions, restrictedGuildIdRegistry, toPermissionNames, transformAutocompleteInteraction, transformInteraction, transformMessageInteraction, transformUserInteraction };
+export { AliasPiece, AliasStore, ApplicationCommandRegistry, ApplicationCommandRegistryEntry, ApplyOptions, ArgumentError, AutocompleteInteraction, BaseInteraction, ChatInputCommandInteraction, ChatInputRouterError, ChatInputRouterErrors, Client, Command, CommandInteraction, CommandLoaderStrategy, CommandRegistry, CommandRouter, CommandStore, CommandStoreRouter, Enumerable, EnumerableMethod, Events, HotModuleReloader, HttpCodes, Identifiers, InteractionHandler, InteractionHandlerStore, Listener, ListenerLoaderStrategy, ListenerStore, LoaderError, Message, MessageComponentButtonInteraction, MessageComponentChannelSelectInteraction, MessageComponentInteraction, MessageComponentMentionableSelectInteraction, MessageComponentRoleSelectInteraction, MessageComponentStringSelectInteraction as MessageComponentSelectMenuInteraction, MessageComponentStringSelectInteraction, MessageComponentUserSelectInteraction, MessageContextMenuCommandInteraction, MissingExportsError, ModalSubmitInteraction, PartialMessage, Piece, Plugin, PluginHook, PluginManager, PreconditionError, RegisterCommand, RegisterMessageCommand, RegisterSubcommand, RegisterSubcommandGroup, RegisterUserCommand, RequiresClientPermissions, RequiresDMContext, RequiresGuildContext, RequiresUserPermissions, RestrictGuildIds, Store, StoreRegistry, StringIdParser, UserContextMenuCommandInteraction, UserError, applicationCommandRegistry, container, createClassDecorator, createFunctionPrecondition, createMethodDecorator, createProxy, extractTopLevelOptions, getMissingPermissions, makeInteraction, postInitialization, postListen, preGenericsInitialization, preInitialization, preLoad, resolvePermissions, restrictedGuildIdRegistry, toPermissionNames, transformAutocompleteInteraction, transformInteraction, transformMessageInteraction, transformUserInteraction };
 //# sourceMappingURL=index.js.map