@wolfstar/http-framework 6.0.1 → 6.1.0

package/dist/esm/index.js

@@ -685,6 +685,28 @@ let PluginHook = /* @__PURE__ */ function(PluginHook) {
 	return PluginHook;
 }({});
 
+//#endregion
+//#region src/lib/plugins/definePlugin.ts
+function definePlugin(plugin) {
+	return plugin;
+}
+/**
+* The error a {@link StarsPlugin} hook is wrapped in, so a failure points at the plugin that threw. The original
+* error is available as `cause`.
+*
+* @since 6.1.0
+*/
+var PluginHookError = class extends Error {
+	constructor(pluginName, hook, cause) {
+		super(`The "${hook}" hook of the plugin "${pluginName}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		_defineProperty(this, "pluginName", void 0);
+		_defineProperty(this, "hook", void 0);
+		this.name = "PluginHookError";
+		this.pluginName = pluginName;
+		this.hook = hook;
+	}
+};
+
 //#endregion
 //#region src/lib/plugins/symbols.ts
 const preGenericsInitialization = Symbol("HttpFrameworkPluginsPreGenericsInitialization");
@@ -693,16 +715,118 @@ const postInitialization = Symbol("HttpFrameworkPluginsPostInitialization");
 const preLoad = Symbol("HttpFrameworkPluginsPreLoad");
 const postListen = Symbol("HttpFrameworkPluginsPostListen");
 
+//#endregion
+//#region \0@oxc-project+runtime@0.151.0/helpers/esm/classPrivateMethodInitSpec.js
+function _classPrivateMethodInitSpec(e, a) {
+	_checkPrivateRedeclaration(e, a), a.add(e);
+}
+
 //#endregion
 //#region src/lib/plugins/PluginManager.ts
+const HOOK_NAMES = [
+	"preGenericsInitialization",
+	"preInitialization",
+	"postInitialization",
+	"preLoad",
+	"postListen"
+];
+const LEGACY_SYMBOLS = [
+	[preGenericsInitialization, "preGenericsInitialization"],
+	[preInitialization, "preInitialization"],
+	[postInitialization, "postInitialization"],
+	[preLoad, "preLoad"],
+	[postListen, "postListen"]
+];
+const warnedLegacyNames = /* @__PURE__ */ new Set();
+function warnLegacy(name) {
+	const label = name ?? "anonymous";
+	if (warnedLegacyNames.has(label)) return;
+	warnedLegacyNames.add(label);
+	process.emitWarning(`The plugin "${label}" uses the legacy class/symbol plugin API (Plugin, Client.use(Class), registerXHook), which is deprecated. Port it to definePlugin.`, {
+		type: "DeprecationWarning",
+		code: "HTTP_FRAMEWORK_LEGACY_PLUGIN"
+	});
+}
+function isThenable(value) {
+	return typeof value?.then === "function";
+}
+function flatten(option, into) {
+	if (!option) return into;
+	if (Array.isArray(option)) for (const entry of option) flatten(entry, into);
+	else into.push(option);
+	return into;
+}
+/**
+* Converts plugin options into hook entries, one per defined hook.
+*
+* @param option The plugin(s) to convert.
+* @returns The entries, in the plugin order and in {@link PluginHook} order inside each plugin.
+*/
+function toPluginEntries(option) {
+	const entries = [];
+	for (const plugin of flatten(option, [])) {
+		if (typeof plugin?.name !== "string" || plugin.name === "") throw new TypeError("A plugin must have a non-empty name");
+		for (const type of HOOK_NAMES) {
+			const hook = plugin[type];
+			if (hook === void 0) continue;
+			if (typeof hook !== "function") throw new TypeError(`The "${type}" hook of the plugin "${plugin.name}" is not a function`);
+			const name = plugin.name;
+			const invoker = (client, options) => {
+				try {
+					const result = hook.call(plugin, client, options);
+					return isThenable(result) ? Promise.resolve(result).then(void 0, (error) => {
+						throw new PluginHookError(name, type, error);
+					}) : result;
+				} catch (error) {
+					throw new PluginHookError(name, type, error);
+				}
+			};
+			entries.push({
+				hook: function(options) {
+					return invoker(this, options);
+				},
+				run: invoker,
+				type,
+				name,
+				enforce: plugin.enforce,
+				apply: plugin.apply,
+				plugin
+			});
+		}
+	}
+	return entries;
+}
+/**
+* Decides whether an entry applies. A function is called once per plugin per `decisions` map (one per client) and its
+* answer kept, so every hook of a plugin sees the same decision: a predicate that is not stable cannot leave a plugin
+* half-applied, with its early hooks run and its later ones skipped. The decision is the plugin's own, never shared
+* with another plugin that happens to use the same function, because each is asked with the options it will receive.
+*/
+function isApplicable(entry, options, decisions) {
+	const { apply } = entry;
+	if (apply === void 0) return true;
+	if (apply === "development") return process.env.NODE_ENV === "development";
+	if (apply === "production") return process.env.NODE_ENV === "production";
+	const owner = entry.plugin ?? entry;
+	let decision = decisions.get(owner);
+	if (decision === void 0) {
+		decision = apply(options);
+		decisions.set(owner, decision);
+	}
+	return decision;
+}
+var _PluginManager_brand = /* @__PURE__ */ new WeakSet();
 var PluginManager = class {
 	constructor() {
+		_classPrivateMethodInitSpec(this, _PluginManager_brand);
 		_defineProperty(this, "registry", /* @__PURE__ */ new Set());
 	}
 	registerHook(hook, type, name) {
 		if (typeof hook !== "function") throw new TypeError(`The provided hook ${name ? `(${name}) ` : ""}is not a function`);
+		warnLegacy(name);
 		this.registry.add({
 			hook,
+			run: (client, options) => hook.call(client, options),
 			type,
 			name
 		});
@@ -723,28 +847,42 @@ var PluginManager = class {
 	registerPostListenHook(hook, name) {
 		return this.registerHook(hook, "postListen", name);
 	}
-	use(plugin) {
-		const possibleSymbolHooks = [
-			[preGenericsInitialization, "preGenericsInitialization"],
-			[preInitialization, "preInitialization"],
-			[postInitialization, "postInitialization"],
-			[preLoad, "preLoad"],
-			[postListen, "postListen"]
-		];
-		for (const [hookSymbol, hookType] of possibleSymbolHooks) {
-			const hook = Reflect.get(plugin, hookSymbol);
-			if (typeof hook !== "function") continue;
-			this.registerHook(hook, hookType, plugin.name);
-		}
+	/**
+	* Registers plugins: {@link StarsPlugin} objects (possibly nested in arrays, with falsy entries dropped) or, for
+	* backwards compatibility, legacy {@link Plugin} classes.
+	*
+	* @param plugins The plugins to register.
+	*/
+	use(...plugins) {
+		for (const plugin of plugins) if (typeof plugin === "function") _assertClassBrand(_PluginManager_brand, this, _useLegacy).call(this, plugin);
+		else for (const entry of toPluginEntries(plugin)) this.registry.add(entry);
 		return this;
 	}
-	*values(hook) {
-		for (const plugin of this.registry) {
-			if (hook && plugin.type !== hook) continue;
-			yield plugin;
-		}
+	*values(hook, extra = []) {
+		const entries = [...this.registry, ...extra].filter((entry) => !hook || entry.type === hook);
+		for (const enforce of [
+			"pre",
+			void 0,
+			"post"
+		]) for (const entry of entries) if (entry.enforce === enforce) yield entry;
+	}
+	/**
+	* Like {@link PluginManager.values}, but only the entries whose `apply` accepts the client's options.
+	*
+	* @param decisions The answers of `apply` functions already given for this client, by plugin. Pass the same map for
+	* every phase of one client so a plugin is accepted or rejected as a whole.
+	*/
+	*applicable(hook, options, extra = [], decisions = /* @__PURE__ */ new Map()) {
+		for (const entry of this.values(hook, extra)) if (isApplicable(entry, options, decisions)) yield entry;
 	}
 };
+function _useLegacy(plugin) {
+	for (const [hookSymbol, hookType] of LEGACY_SYMBOLS) {
+		const hook = Reflect.get(plugin, hookSymbol);
+		if (typeof hook !== "function") continue;
+		this.registerHook(hook, hookType, plugin.name);
+	}
+}
 
 //#endregion
 //#region src/lib/utils/decorators.ts
@@ -1083,12 +1221,6 @@ function getLinkedMethod(object) {
 	return Reflect.get(object, linkSymbol) ?? null;
 }
 
-//#endregion
-//#region \0@oxc-project+runtime@0.151.0/helpers/esm/classPrivateMethodInitSpec.js
-function _classPrivateMethodInitSpec(e, a) {
-	_checkPrivateRedeclaration(e, a), a.add(e);
-}
-
 //#endregion
 //#region src/lib/interactions/resolvers/ChatInputCommandResolver.ts
 var _data$1 = /* @__PURE__ */ new WeakMap();
@@ -3900,6 +4032,8 @@ container$1.stores.register(new ListenerStore());
 container$1.logger ??= new Logger();
 var _discordPublicKey = /* @__PURE__ */ new WeakMap();
 var _fetchKey = /* @__PURE__ */ new WeakMap();
+var _pluginEntries = /* @__PURE__ */ new WeakMap();
+var _applyDecisions = /* @__PURE__ */ new WeakMap();
 var Client = class Client extends AsyncEventEmitter {
 	constructor(options = {}) {
 		super();
@@ -3912,19 +4046,22 @@ var Client = class Client extends AsyncEventEmitter {
 		_defineProperty(this, "httpReplyOnError", void 0);
 		_classPrivateFieldInitSpec(this, _discordPublicKey, void 0);
 		_classPrivateFieldInitSpec(this, _fetchKey, null);
+		_classPrivateFieldInitSpec(this, _pluginEntries, void 0);
+		_classPrivateFieldInitSpec(this, _applyDecisions, /* @__PURE__ */ new Map());
 		this.options = {
 			...options,
 			discordToken: void 0,
 			discordPublicKey: void 0
 		};
-		for (const plugin of Client.plugins.values("preGenericsInitialization")) {
-			plugin.hook.call(this, this.options);
+		_classPrivateFieldSet2(_pluginEntries, this, toPluginEntries(options.plugins));
+		for (const plugin of Client.plugins.applicable("preGenericsInitialization", this.options, _classPrivateFieldGet2(_pluginEntries, this), _classPrivateFieldGet2(_applyDecisions, this))) {
+			plugin.run(this, this.options);
 			this.emit("pluginLoaded", plugin.type, plugin.name);
 		}
 		this.logger = this.options.logger?.instance ?? new Logger(this.options.logger?.level ?? 30);
 		container$1.logger = this.logger;
-		for (const plugin of Client.plugins.values("preInitialization")) {
-			plugin.hook.call(this, this.options);
+		for (const plugin of Client.plugins.applicable("preInitialization", this.options, _classPrivateFieldGet2(_pluginEntries, this), _classPrivateFieldGet2(_applyDecisions, this))) {
+			plugin.run(this, this.options);
 			this.emit("pluginLoaded", plugin.type, plugin.name);
 		}
 		this.bodySizeLimit = options.bodySizeLimit ?? 1048576;
@@ -3944,19 +4081,20 @@ var Client = class Client extends AsyncEventEmitter {
 			rest: container$1.rest,
 			authPrefix: options.authPrefix
 		});
-		for (const plugin of Client.plugins.values("postInitialization")) {
-			plugin.hook.call(this, this.options);
+		for (const plugin of Client.plugins.applicable("postInitialization", this.options, _classPrivateFieldGet2(_pluginEntries, this), _classPrivateFieldGet2(_applyDecisions, this))) {
+			plugin.run(this, this.options);
 			this.emit("pluginLoaded", plugin.type, plugin.name);
 		}
 	}
 	/**
-	* Registers a plugin onto the {@link Client}, applying all of its hooks.
+	* Registers plugins onto the {@link Client}, applying all of their hooks. Accepts {@link StarsPlugin} objects
+	* (see {@link definePlugin}) and, deprecated, legacy {@link Plugin} classes.
 	*
 	* @since 2.4.0
-	* @param plugin The plugin to register.
+	* @param plugins The plugins to register.
 	*/
-	static use(plugin) {
-		this.plugins.use(plugin);
+	static use(...plugins) {
+		this.plugins.use(...plugins);
 		return this;
 	}
 	/**
@@ -3973,8 +4111,8 @@ var Client = class Client extends AsyncEventEmitter {
 	* @param options The load options.
 	*/
 	async load(options = {}) {
-		for (const plugin of Client.plugins.values("preLoad")) {
-			await plugin.hook.call(this, this.options);
+		for (const plugin of Client.plugins.applicable("preLoad", this.options, _classPrivateFieldGet2(_pluginEntries, this), _classPrivateFieldGet2(_applyDecisions, this))) {
+			await plugin.run(this, this.options);
 			this.emit("pluginLoaded", plugin.type, plugin.name);
 		}
 		if (options.baseUserDirectory !== null) container$1.stores.registerPath(options.baseUserDirectory);
@@ -3999,8 +4137,8 @@ var Client = class Client extends AsyncEventEmitter {
 			host: address
 		}, resolve));
 		try {
-			for (const plugin of Client.plugins.values("postListen")) {
-				await plugin.hook.call(this, this.options);
+			for (const plugin of Client.plugins.applicable("postListen", this.options, _classPrivateFieldGet2(_pluginEntries, this), _classPrivateFieldGet2(_applyDecisions, this))) {
+				await plugin.run(this, this.options);
 				this.emit("pluginLoaded", plugin.type, plugin.name);
 			}
 		} catch (error) {
@@ -4210,5 +4348,5 @@ function toPermissionNames(bits) {
 }
 
 //#endregion
-export { AliasPiece, AliasStore, ApplicationCommandRegistry, ApplicationCommandRegistryEntry, ArgumentError, AutocompleteInteraction, BaseInteraction, ChatInputCommandInteraction, ChatInputRouterError, ChatInputRouterErrors, Client, Command, CommandInteraction, CommandLoaderStrategy, CommandRegistry, CommandRouter, CommandStore, CommandStoreRouter, Events, HotModuleReloader, HttpCodes, Identifiers, InteractionHandler, InteractionHandlerStore, Listener, ListenerLoaderStrategy, ListenerStore, LoaderError, LogLevel, Logger, 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, RestrictGuildIds, Store, StoreRegistry, StringIdParser, UserContextMenuCommandInteraction, UserError, applicationCommandRegistry, container, extractTopLevelOptions, getMissingPermissions, makeInteraction, postInitialization, postListen, preGenericsInitialization, preInitialization, preLoad, resolvePermissions, restrictedGuildIdRegistry, toPermissionNames, transformAutocompleteInteraction, transformInteraction, transformMessageInteraction, transformUserInteraction };
+export { AliasPiece, AliasStore, ApplicationCommandRegistry, ApplicationCommandRegistryEntry, ArgumentError, AutocompleteInteraction, BaseInteraction, ChatInputCommandInteraction, ChatInputRouterError, ChatInputRouterErrors, Client, Command, CommandInteraction, CommandLoaderStrategy, CommandRegistry, CommandRouter, CommandStore, CommandStoreRouter, Events, HotModuleReloader, HttpCodes, Identifiers, InteractionHandler, InteractionHandlerStore, Listener, ListenerLoaderStrategy, ListenerStore, LoaderError, LogLevel, Logger, Message, MessageComponentButtonInteraction, MessageComponentChannelSelectInteraction, MessageComponentInteraction, MessageComponentMentionableSelectInteraction, MessageComponentRoleSelectInteraction, MessageComponentStringSelectInteraction as MessageComponentSelectMenuInteraction, MessageComponentStringSelectInteraction, MessageComponentUserSelectInteraction, MessageContextMenuCommandInteraction, MissingExportsError, ModalSubmitInteraction, PartialMessage, Piece, Plugin, PluginHook, PluginHookError, PluginManager, PreconditionError, RegisterCommand, RegisterMessageCommand, RegisterSubcommand, RegisterSubcommandGroup, RegisterUserCommand, RestrictGuildIds, Store, StoreRegistry, StringIdParser, UserContextMenuCommandInteraction, UserError, applicationCommandRegistry, container, definePlugin, extractTopLevelOptions, getMissingPermissions, makeInteraction, postInitialization, postListen, preGenericsInitialization, preInitialization, preLoad, resolvePermissions, restrictedGuildIdRegistry, toPermissionNames, toPluginEntries, transformAutocompleteInteraction, transformInteraction, transformMessageInteraction, transformUserInteraction };
 //# sourceMappingURL=index.js.map