meocord 4.2.0 → 4.2.2

package/dist/esm/core/shard-manager.js

@@ -4,24 +4,22 @@ import './theme-scope.js';
 import './theme-validation.js';
 import '../common/decorator.js';
 import 'reflect-metadata';
-import '../common/translator.js';
-import '../common/response/send-failure.js';
-import '../util/interaction.util.js';
-import '../common/response/flags.js';
-import 'path';
-import '../common/response/components.js';
+import '../common/response/response-state.js';
+import '../common/errors.js';
 import { MemoryCooldownStore } from '../common/cooldown-store.js';
 import 'node:crypto';
 import '../decorator/controller.decorator.js';
 import './scalar-types.js';
 import { answerCooldown } from '../common/sharded-cooldown-store.js';
+import '../common/translator.js';
+import '../common/meocord-text.js';
 import { registerCommands } from './command-registration.js';
 import { SHUTDOWN_MARGIN_MS, shutdownTimeoutOf } from '../util/shutdown-timeout.util.js';
 import { bundleEntry } from '../util/bundle-entry.util.js';
 import { FORCE_REGISTER_ENV } from '../util/registration-mode.util.js';
 import { isShardMessage, REFUSED_CODE } from './shard-messages.js';
 import { tokenMessage, isRefusedToken } from './login-failure.js';
-import { onDevRunnerStop, underDevRunner, tellDevRunner } from '../util/dev-runner.util.js';
+import { onDevRunnerStop, tellDevRunner, underDevRunner } from '../util/dev-runner.util.js';
 import { stopRequests } from '../util/stop-request.util.js';
 
 /** How long the manager waits for a shard to become ready before spawning the next. */ const SHARD_READY_TIMEOUT_MS = 30000;
@@ -60,7 +58,7 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
         process.on('SIGINT', ()=>void this.stopAndExit());
         process.on('SIGTERM', ()=>void this.stopAndExit());
         // How `meocord start --dev` stops the bot to restart it; no stop request of the user's, whose first Ctrl+C joins it
-        onDevRunnerStop(()=>void this.exitAfterShutdown());
+        onDevRunnerStop(()=>void this.exitAfterShutdown(), false);
         let total;
         try {
             const shards = config.sharding?.shards ?? 'auto';
@@ -77,6 +75,10 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
         const manager = (this.options.createManager ?? ((path, opts)=>new ShardingManager(path, opts)))(file, {
             token,
             totalShards: total,
+            // discord.js refuses a call to every shard unless shardList counts the shards; createShard leaves it 'auto'
+            shardList: [
+                ...Array(total).keys()
+            ],
             mode: 'process',
             execArgv: process.execArgv,
             respawn: false
@@ -173,12 +175,12 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
         void this.exitForLogin();
     }
     /** Exits 1 for a bot that could not log in, telling `meocord start --dev` first, which then waits for a change. */ exitForLogin() {
-        if (!underDevRunner()) return this.exit(1);
+        if (!this.devRunner) return this.exit(1);
         // Set first, so the process exits 1 even if it ends while the message is still on its way
         process.exitCode = 1;
         return tellDevRunner({
             meocord: 'login-failed'
-        }).then(()=>this.exit(1));
+        }, false).then(()=>this.exit(1));
     }
     /**
    * Asks every shard to shut down through its own hooks, waits for them up to the shutdown timeout plus a margin, and
@@ -255,6 +257,10 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
         /** Every shard's cooldown calls, for an app whose store is ShardedCooldownStore. */ this.cooldowns = new MemoryCooldownStore();
         this.stopping = false;
         this.fatal = false;
+        /**
+   * Whether `meocord start --dev` runs the manager, decided before discord.js's ShardingManager, which writes the
+   * variable that marks a shard into this process too.
+   */ this.devRunner = underDevRunner(false);
         // The manager holds the credential for its shards and logs their failures, without an app of its own to register it
         hideInLogs(options.token);
         this.exit = options.exit ?? ((code)=>process.exit(code));

package/dist/esm/core/stage-scope.js

@@ -46,7 +46,8 @@ import { META } from '../util/metadata-keys.js';
     }
 }
 /** The class of a stage entry. */ function stageClass(entry) {
-    return isConstructor(entry) ? entry : entry.provide;
+    // Entries were checked as they were declared, so a function is the class itself
+    return typeof entry === 'function' ? entry : entry.provide;
 }
 /** The context types a stage declared, or `undefined` when it runs for every type. */ function stageTypes(entry) {
     return Reflect.getMetadata(META.stageTypes, stageClass(entry));

package/dist/esm/core/startup-roots.js

@@ -3,6 +3,8 @@ import { injectedTokens, isGuardWithParams } from './guard-runner.js';
 import { classDecorators, handlerStageClasses } from './handler-pipeline.js';
 import { reachableClasses, assertTypedParameters } from './providers.js';
 import { themeResolverClass } from './theme-resolvers.js';
+import { isAppClassToken } from './lifecycle-order.js';
+import { ExecutionContext } from '../common/execution-context.js';
 import { META } from '../util/metadata-keys.js';
 import { startupError } from '../util/refusal.util.js';
 
@@ -57,6 +59,24 @@ import { startupError } from '../util/refusal.util.js';
         for (const [stage, decorator] of found)decorators.set(stage, decorator);
     }
 }
+/** Whether making `cls` reaches the per-call `ExecutionContext` through the classes it injects, which each call makes. */ function reachesContext(cls, providers, seen = new Set()) {
+    seen.add(cls);
+    return injectedTokens(cls).some((token)=>token === ExecutionContext || isAppClassToken(token) && !providers.has(token) && !seen.has(token) && reachesContext(token, providers, seen));
+}
+/**
+ * The classes the app's stages and presenter inject, which they would make only at their first call. Made with the
+ * app's own classes, a service among them gets its lifecycle hooks. One that reaches the call's `ExecutionContext` is
+ * made for each call, so it is left out, and a stage a test replaces is not among the stages, so what it would inject
+ * is not made.
+ */ function stageDependencies({ decorators }, providers, presenter) {
+    const stages = [
+        ...decorators
+    ].filter(([, decorator])=>decorator !== '@Controller()').map(([stage])=>stage);
+    if (typeof presenter === 'function') stages.push(presenter);
+    return [
+        ...new Set(stages.flatMap((stage)=>injectedTokens(stage)))
+    ].filter(isAppClassToken).filter((cls)=>!reachesContext(cls, providers));
+}
 /** How a container checks a guard first met at a call: the guard and what it injects, as the startup checks would. */ function lateGuardCheck(providers, translator) {
     return (guard)=>assertStartupClasses({
             classes: reachableClasses([
@@ -78,4 +98,4 @@ import { startupError } from '../util/refusal.util.js';
     for (const needsOne of classes.filter((cls)=>injectedTokens(cls).includes(Translator)))startupError(missingTranslatorError(needsOne));
 }
 
-export { assertStartupClasses, lateGuardCheck, startupClasses };
+export { assertStartupClasses, lateGuardCheck, stageDependencies, startupClasses };

package/dist/esm/core/theme-resolvers.js

@@ -118,7 +118,10 @@ const logger = new Logger('Theme');
    */ accept(id, result, report) {
         if (result === undefined || result === null) return undefined;
         const layer = copyLayer(result);
-        const problems = themeProblems(layer, `themeFor.${this.kind} for ${this.kind} ${id}`);
+        // A value from the app's data, such as a user's saved choice, shown as a log line shows outside text
+        const problems = themeProblems(layer, `themeFor.${this.kind} for ${this.kind} ${id}`, {
+            forLog: true
+        });
         if (problems.length === 0) {
             if (report) this.warned.delete(id);
             return layer;

package/dist/esm/core/theme-scope.js

@@ -1,7 +1,9 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { DEFAULT_THEME } from './theme-defaults.js';
+import { shared } from '../util/shared-state.util.js';
 
-const scope = new AsyncLocalStorage();
+// One per process for this meocord version, so a call's theme reads the same from its ES module and CommonJS builds
+const scope = shared('themeScope', ()=>new AsyncLocalStorage());
 const isPlainObject = (value)=>{
     if (value === null || typeof value !== 'object') return false;
     const prototype = Object.getPrototypeOf(value);
@@ -170,6 +172,9 @@ let themeOutsideCalls;
  * Such a listener runs in its emitter's context, so without it a `useTheme()` inside reads the theme outside any call.
  * Timers and promises the handler starts keep its theme without it.
  *
+ * The theme is the binding call's whole theme, its server's and user's themes included, so every later call, whoever
+ * it is for, is answered in the starting member's theme.
+ *
  * @param fn - The function to run in the call's theme; `this` and its arguments are passed through.
  * @returns A function that runs `fn` in the theme `useTheme()` returns where `bindTheme` is called.
  *
@@ -179,7 +184,7 @@ let themeOutsideCalls;
  * async poll(message: Message) {
  *   const collector = message.createMessageComponentCollector({ componentType: ComponentType.Button, time: 60_000 })
  *   collector.on('collect', bindTheme(async (click: ButtonInteraction) => {
- *     const { emojis } = useTheme() // the handler's theme, @UseTheme included
+ *     const { emojis } = useTheme() // the starting member's theme, @UseTheme included
  *     await click.reply(`${emojis.success} Picked`)
  *   }))
  * }

package/dist/esm/core/theme-validation.js

@@ -1,5 +1,6 @@
 import { ButtonStyle, Colors } from 'discord.js';
 import { refuse } from '../util/refusal.util.js';
+import { escapeForLog, quoteForLog } from '../util/user-text.util.js';
 
 /**
  * The role names MeoCord keeps for roles it may add to `colors`, `emojis` and `buttons`: the runtime copy of
@@ -25,9 +26,10 @@ const EMOJI = 'a unicode emoji, or a custom one written <:name:id> or <a:name:id
 const BUTTON = 'ButtonStyle.Primary, Secondary, Success or Danger';
 /** A custom emoji as Discord writes one in text: its name, 2 to 32 word characters, and its id. */ const CUSTOM_EMOJI = /^<a?:\w{2,32}:\d{17,20}>$/;
 /**
- * One unicode emoji: a flag of two regional indicators, a keycap, or a pictograph with an optional presentation
- * selector or skin tone, joined to others by zero-width joiners into one sequence.
- */ const UNICODE_EMOJI = /^(?:\p{Regional_Indicator}{2}|[#*0-9]️?⃣|\p{Extended_Pictographic}(?:️|\p{Emoji_Modifier})?(?:‍\p{Extended_Pictographic}(?:️|\p{Emoji_Modifier})?)*)$/u;
+ * One unicode emoji: a flag of two regional indicators, a subdivision flag (a black flag, tag characters and a cancel
+ * tag, as England's), a keycap, or a pictograph with an optional presentation selector or skin tone, joined to others by
+ * zero-width joiners into one sequence.
+ */ const UNICODE_EMOJI = /^(?:\p{Regional_Indicator}{2}|\u{1F3F4}[\u{E0020}-\u{E007E}]+\u{E007F}|[#*0-9]️?⃣|\p{Extended_Pictographic}(?:️|\p{Emoji_Modifier})?(?:‍\p{Extended_Pictographic}(?:️|\p{Emoji_Modifier})?)*)$/u;
 const byte = (value)=>Number.isInteger(value) && value >= 0 && value <= 255;
 /** Whether discord.js resolves the value to a colour Discord takes. Stricter on tuples, whose channels it only sums. */ function isColour(value) {
     if (typeof value === 'string') return /^#?[\da-f]{6}$/i.test(value) || value === 'Random' || value === 'Default' || Object.hasOwn(Colors, value);
@@ -42,8 +44,9 @@ const THEMED_BUTTON_STYLES = [
     ButtonStyle.Danger
 ];
 const isButtonStyle = (value)=>THEMED_BUTTON_STYLES.includes(value);
-const describe = (value)=>typeof value === 'string' ? `'${value}'` : Array.isArray(value) ? `[${value.map((item)=>typeof item === 'string' ? `'${item}'` : String(item)).join(', ')}]` : value === null ? 'null' : typeof value === 'object' ? 'an object' : String(value);
-const describeGroup = (value)=>Array.isArray(value) ? 'an array' : describe(value);
+const asWritten = (text)=>`'${text}'`;
+const describe = (value, quote = asWritten)=>typeof value === 'string' ? quote(value) : Array.isArray(value) ? `[${value.map((item)=>typeof item === 'string' ? quote(item) : String(item)).join(', ')}]` : value === null ? 'null' : typeof value === 'object' ? 'an object' : String(value);
+const describeGroup = (value, quote = asWritten)=>Array.isArray(value) ? 'an array' : describe(value, quote);
 /** Whether a value is a plain object, as an object literal or `JSON.parse` makes: one a theme merges key by key. */ const isPlainObject = (value)=>{
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
@@ -75,11 +78,15 @@ const PLAIN = "give a plain object, such as { ...value }, or a row's toObject(),
  * roles an app added, a colour discord.js cannot resolve, an emoji Discord would refuse, a button style other than
  * Discord's four coloured ones, or a reserved role name. A group of the app's own is its to check.
  * @param where - Where it was set, such as `themeFor.guild for guild 123`, to begin each line with.
- */ function themeProblems(theme, where) {
+ * @param options.forLog - Shows values and role names as a log line shows text from outside the code, for a theme a
+ *   `themeFor` resolver returned: escaped, and a value quoted and cut short.
+ */ function themeProblems(theme, where, { forLog = false } = {}) {
     const at = where ? `${where}: ` : '';
+    const quote = forLog ? quoteForLog : asWritten;
+    const name = forLog ? escapeForLog : (role)=>role;
     if (typeof theme !== 'object' || theme === null || Array.isArray(theme)) {
         return [
-            `${at}theme must be an object of groups (got ${describeGroup(theme)})`
+            `${at}theme must be an object of groups (got ${describeGroup(theme, quote)})`
         ];
     }
     if (!isPlainObject(theme)) return [
@@ -91,7 +98,7 @@ const PLAIN = "give a plain object, such as { ...value }, or a row's toObject(),
         const roles = theme[group];
         if (roles === undefined) continue;
         if (typeof roles !== 'object' || roles === null || Array.isArray(roles)) {
-            problems.push(`${at}theme.${group} must be an object of roles (got ${describeGroup(roles)})`);
+            problems.push(`${at}theme.${group} must be an object of roles (got ${describeGroup(roles, quote)})`);
             continue;
         }
         if (!isPlainObject(roles)) {
@@ -99,8 +106,8 @@ const PLAIN = "give a plain object, such as { ...value }, or a row's toObject(),
             continue;
         }
         for (const [role, value] of Object.entries(roles)){
-            if (reserved.has(role)) problems.push(`${at}theme.${group}.${role}: MeoCord reserves the role name ${role} for a role it may add; rename yours`);
-            else if (value !== undefined && !check(value)) problems.push(`${at}theme.${group}.${role}: ${describe(value)} is not ${what}: give ${instead}`);
+            if (reserved.has(role)) problems.push(`${at}theme.${group}.${name(role)}: MeoCord reserves the role name ${name(role)} for a role it may add; rename yours`);
+            else if (value !== undefined && !check(value)) problems.push(`${at}theme.${group}.${name(role)}: ${describe(value, quote)} is not ${what}: give ${instead}`);
         }
     }
     return problems;

package/dist/esm/decorator/app.decorator.js

@@ -9,6 +9,7 @@ import { assertValidTheme, themeForProblem } from '../core/theme-validation.js';
 import { copyLayer } from '../core/theme-scope.js';
 import { declaring, deprecatedOnMethod, refuse } from '../util/refusal.util.js';
 import { timeoutProblem } from '../util/timer-limit.util.js';
+import { isConstructor, describeValue } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
 
 /** Refuses a `messages` option of the wrong type where the app is declared, rather than at the first message. */ function assertMessageOptions(appName, messages, i18n) {
@@ -52,6 +53,35 @@ import { META } from '../util/metadata-keys.js';
         if (type.labelKey !== undefined) assertLabelKey(appName, name, type.labelKey, i18n);
     }
 }
+/**
+ * Refuses an option that takes a class given anything else, such as an object or an arrow function, where the app is
+ * declared: the startup checks read each class's prototype, and would otherwise fail on it without naming the option.
+ */ function assertClassOptions(appName, { presenter, cooldownStore, controllers, services }) {
+    for (const [name, value, implementing] of [
+        [
+            'presenter',
+            presenter,
+            'ResponsePresenter'
+        ],
+        [
+            'cooldownStore',
+            cooldownStore,
+            'CooldownStore'
+        ]
+    ]){
+        if (value !== undefined && !isConstructor(value)) {
+            throw refuse(new TypeError(`${appName}: @MeoCord({ ${name} }) takes a class implementing ${implementing}, not ${describeValue(value)}.`));
+        }
+    }
+    for (const controller of controllers ?? []){
+        if (!isConstructor(controller)) throw refuse(new TypeError(`${appName}: @MeoCord({ controllers }) takes classes, not ${describeValue(controller)}.`));
+    }
+    // A string or symbol is a token, which a provider has to provide; that is checked as the app is created
+    for (const service of services ?? []){
+        if (isConstructor(service) || typeof service === 'string' || typeof service === 'symbol') continue;
+        throw refuse(new TypeError(`${appName}: @MeoCord({ services }) takes classes, or tokens that providers provide, not ${describeValue(service)}.`));
+    }
+}
 /** Refuses a type's `labelKey` that no message of the app's default catalog has, as it would be shown as the key. */ function assertLabelKey(appName, name, labelKey, i18n) {
     const where = `${appName}: @MeoCord({ messages: { types } }): "${name}" has labelKey`;
     if (typeof labelKey !== 'string') throw refuse(new TypeError(`${where} ${String(labelKey)}; it takes a message key, such as 'types.${name}'.`));
@@ -96,6 +126,7 @@ import { META } from '../util/metadata-keys.js';
  */ function MeoCord(options) {
     return declaring((target, propertyKey)=>{
         if (deprecatedOnMethod('@MeoCord', target, propertyKey)) return;
+        assertClassOptions(target.name, options);
         assertStageEntries('@MeoCord({ guards })', 'guard', target.name, options.guards ?? []);
         assertStageEntries('@MeoCord({ interceptors })', 'interceptor', target.name, options.interceptors ?? []);
         assertStageEntries('@MeoCord({ filters })', 'filter', target.name, options.filters ?? []);

package/dist/esm/decorator/controller.decorator.js

@@ -2,7 +2,8 @@ import 'reflect-metadata';
 import { UserContextMenuCommandInteraction, ApplicationCommandType, MessageContextMenuCommandInteraction } from 'discord.js';
 import { CommandType } from '../enum/controller.enum.js';
 import { MetadataKey } from '../enum/metadata-key.enum.js';
-import { matchesCommandType, interactionClassName, isCustomIdRouted } from '../util/interaction.util.js';
+import { isCustomIdRouted, matchesCommandType, interactionClassName } from '../util/interaction.util.js';
+import { wrapsMethod } from '../util/method-wrapper.util.js';
 import { warnDeprecatedBehaviour } from '../common/deprecation.js';
 import { Logger } from '../common/logger.js';
 import { routeSpecificity } from '../core/route-specificity.js';
@@ -79,9 +80,9 @@ const autocompleteRoute = (method, commandPath, optionName)=>({
     // An entry the class takes from its base, for a method it re-declares
     const inheritedFor = (inherited, method)=>(entry)=>inherited.includes(entry) && redeclared.has(method(entry));
     const commands = ownCommandMap(prototype);
-    const baseCommands = Reflect.getMetadata(META.commands, base) ?? {};
+    const baseCommands = Reflect.getMetadata(META.commands, base) ?? Object.create(null);
     for (const [name, metas] of Object.entries(commands)){
-        const kept = metas.filter((meta)=>!inheritedFor(baseCommands[name] ?? [], (entry)=>entry.methodName)(meta));
+        const kept = metas.filter((meta)=>!inheritedFor(commandsNamed(baseCommands, name), (entry)=>entry.methodName)(meta));
         if (kept.length > 0) commands[name] = kept;
         else delete commands[name];
     }
@@ -105,16 +106,21 @@ const autocompleteRoute = (method, commandPath, optionName)=>({
         Reflect.defineMetadata(key, ownHandlerList(key, prototype).filter((entry)=>!inheritedFor(inherited, method)(entry)), prototype);
     }
 }
-/** The class's own command map, started from a copy of the inherited one, for the same reason. */ function ownCommandMap(target) {
+/**
+ * The class's own command map, started from a copy of the inherited one, for the same reason. Keyed by command name
+ * without a prototype, so a command named like an inherited key, such as `constructor`, is a key like any other.
+ */ function ownCommandMap(target) {
     const own = Reflect.getOwnMetadata(META.commands, target);
     if (own) return own;
     const inherited = Reflect.getMetadata(META.commands, target) ?? {};
-    return Object.fromEntries(Object.entries(inherited).map(([name, metas])=>[
-            name,
-            [
-                ...metas
-            ]
-        ]));
+    const copy = Object.create(null);
+    for (const [name, metas] of Object.entries(inherited))copy[name] = [
+        ...metas
+    ];
+    return copy;
+}
+/** The handlers a command map holds for `name`: its own entry only, never one `Object.prototype` holds. */ function commandsNamed(map, name) {
+    return map && Object.hasOwn(map, name) ? map[name] : [];
 }
 function MessageHandler(pattern, options = {}) {
     return declaring(function(target, propertyKey) {
@@ -179,12 +185,24 @@ function ReactionHandler(emojiOrSettings, settings = {}) {
 }
 // `{name}`, or `{name:type}` with the type read as far as the brace, so a type no segment can hold is named
 const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
+// The whole of a brace pair that is a param, as PLACEHOLDER_PATTERN reads one
+const WHOLE_PLACEHOLDER = new RegExp(`^${PLACEHOLDER_PATTERN.source}$`);
+/**
+ * Why a pattern's brace pairs that aren't params are matched as literal text, or undefined when it has none: a
+ * param's name is ASCII letters, digits and _, so `{café}` is text.
+ */ function literalBraces(pattern) {
+    const braces = (pattern.match(/\{[^{}]*}/g) ?? []).filter((brace)=>!WHOLE_PLACEHOLDER.test(brace));
+    if (braces.length === 0) return undefined;
+    const one = braces.length === 1;
+    return `${braces.join(', ')} ${one ? "isn't a param" : "aren't params"}, since a param's name is ASCII letters, digits and _; ` + `${one ? 'it is' : 'they are'} matched as literal text.`;
+}
 /** The character a parameter will not cross, so one pattern segment maps to one value. */ const PARAM_SEPARATOR = '/';
+/** The longest customId Discord accepts; the shortest is one character. */ const MAX_CUSTOM_ID_LENGTH = 100;
 /** Escapes a literal stretch of a pattern so only placeholders stay meaningful. */ const escapeLiteral = (literal)=>literal.replace(/[/\\^$*+?.()|[\]{}]/g, '\\$&');
 /**
- * Compiles a pattern into a regex, its parameter names, their types and its 4.1 specificity. A `{name}` takes a
- * whole `/`-separated segment, so a uuid is captured whole and `profile/{uuid}` never overlaps
- * `profile/{uuid}/{id}`; a param that shares a segment with literal text is refused.
+ * Compiles a pattern into a regex, its parameter names, their types, its 4.1 specificity and the length of the
+ * shortest customId it matches. A `{name}` takes a whole `/`-separated segment, so a uuid is captured whole and
+ * `profile/{uuid}` never overlaps `profile/{uuid}/{id}`; a param that shares a segment with literal text is refused.
  */ function createRegexFromPattern(pattern) {
     const params = [];
     // By the param's own name, so one named like an inherited key, such as `__proto__`, keeps its type
@@ -205,6 +223,13 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
         if (literal !== '' && !literal.endsWith(PARAM_SEPARATOR) || after !== undefined && after !== PARAM_SEPARATOR) {
             throw refuse(new Error(`Invalid pattern "${pattern}": {${param}} must occupy a whole segment, so it has to be ` + `preceded and followed by "${PARAM_SEPARATOR}" or by the ends of the pattern. ` + `Write "a${PARAM_SEPARATOR}{${param}}" rather than "a-{${param}}".`));
         }
+        // A regex group's name, which the engine would refuse with the compiled regex in place of the pattern
+        if (params.includes(param)) {
+            throw refuse(new Error(`Invalid pattern "${pattern}": {${param}} appears twice; give each param its own name.`));
+        }
+        if (/^\d/.test(param)) {
+            throw refuse(new Error(`Invalid pattern "${pattern}": {${param}} starts with a digit; start a param's name with a letter or _.`));
+        }
         if (type !== undefined) {
             if (!isSegmentType(type)) throw refuse(new Error(`Invalid pattern "${pattern}": ${segmentTypeProblem(param, type)}`));
             if (choicesOf(type)?.includes('')) {
@@ -228,11 +253,13 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
         params: params.length,
         typed: Object.values(types).reduce((sum, type)=>sum + (choicesOf(type) ? 4 : type === 'bool' ? 3 : type === 'int' ? 2 : 1), 0)
     });
+    // Each param takes at least one character
     return {
         regex,
         params,
         types: lookupTable(types),
-        specificity
+        specificity,
+        shortest: literalLength + params.length
     };
 }
 /** Why a `{name:type}` cannot type a customId segment, which holds text the bot wrote, with no message to read. */ function segmentTypeProblem(param, type) {
@@ -302,7 +329,6 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
  */ function Command(name, builderOrType) {
     const commandName = typeof name === 'string' ? name : name.pattern;
     return declaring(function(target, propertyKey, _descriptor) {
-        var _commands, _commandName;
         refuseOnClass('@Command', target, propertyKey);
         const originalMethod = _descriptor.value;
         if (!originalMethod) {
@@ -310,7 +336,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
         }
         // Wrap original method for interaction type validation
         const declaredAs = typeof builderOrType === 'function' ? builderOrType.name : `CommandType.${builderOrType}`;
-        _descriptor.value = function(interaction, params) {
+        const checked = function(interaction, params) {
             if (!matchesCommandType(commandType, interaction)) {
                 throw new Error(`${target.constructor.name}.${propertyKey}: @Command('${commandName}', ${declaredAs}) takes ` + `${interactionClassName(commandType)}${givenInstead(interaction)}.`);
             }
@@ -319,6 +345,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
                 params
             ]);
         };
+        _descriptor.value = wrapsMethod(checked, originalMethod);
         // This class's own map, inherited routes included
         const commands = ownCommandMap(target);
         let builderInstance;
@@ -354,7 +381,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
                     }));
                 }
                 // discord.js builders validate as they are set, and their errors name neither the command nor the field.
-                throw refuse(new Error(`${where}: ${builderOrType.name} could not build "${commandName}": ${detail}. Check its names, descriptions and ` + `localizations, which Discord limits to 32 and 100 characters.`, {
+                throw refuse(new Error(`${where}: ${builderOrType.name} could not build "${commandName}": ${detail}. Check its names, descriptions and ` + 'localizations, which Discord limits to 32 characters for a name and 100 for a description. A name is letters, ' + 'numbers, `-` and `_`, lowercase where the script has case, and without spaces, in every locale.', {
                     cause: error
                 }));
             }
@@ -374,6 +401,9 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
             commandType = builderOrType;
         }
         if (isCustomIdRouted(commandType)) {
+            // A route warned as it was made
+            const braces = typeof name === 'string' ? literalBraces(commandName) : undefined;
+            if (braces) logger.warn(`${target.constructor.name}.${propertyKey}: in the pattern "${commandName}", ${braces}`);
             let pattern;
             try {
                 pattern = createRegexFromPattern(commandName);
@@ -385,6 +415,11 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
             regex = pattern.regex;
             dynamicParams = pattern.params;
             specificity = pattern.specificity;
+            // Warned rather than refused, so a bot that carries such a handler still starts
+            if (pattern.shortest === 0 || pattern.shortest > MAX_CUSTOM_ID_LENGTH) {
+                const length = pattern.shortest === 0 ? 'the pattern is empty' : `its shortest is ${pattern.shortest} characters`;
+                logger.warn(`${target.constructor.name}.${propertyKey}: the pattern "${commandName}" matches no customId: Discord's customIds ` + `are 1 to ${MAX_CUSTOM_ID_LENGTH} characters, and ${length}, so the handler never runs.`);
+            }
         }
         const declared = {
             methodName: propertyKey,
@@ -401,8 +436,9 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
             }
         };
         // One the class inherits for this method and route is replaced where it stands, so this one's options apply
-        const metas = (_commands = commands)[_commandName = commandName] ?? (_commands[_commandName] = []);
-        const inherited = getCommandMap(Object.getPrototypeOf(target))?.[commandName] ?? [];
+        if (!Object.hasOwn(commands, commandName)) commands[commandName] = [];
+        const metas = commands[commandName];
+        const inherited = commandsNamed(getCommandMap(Object.getPrototypeOf(target)), commandName);
         const replaced = metas.findIndex((meta)=>inherited.includes(meta) && meta.methodName === propertyKey && meta.type === commandType);
         if (replaced === -1) metas.push(declared);
         else metas[replaced] = declared;
@@ -572,4 +608,4 @@ const narrowness = (type)=>choicesOf(type) ? 6 : NARROWNESS[type];
     return values.every((value)=>value !== undefined) ? values.join(PARAM_SEPARATOR) : undefined;
 }
 
-export { Autocomplete, Command, MessageHandler, PARAM_SEPARATOR, ReactionHandler, createRegexFromPattern, dropInheritedRoutes, getAutocompleteHandlers, getCommandMap, getDeclaredRoutes, getHandlerRoutes, getMessageHandlers, getReactionHandlers, matchesEmoji, ownHandlerList, paramNarrowness, patternShape, sharedCustomId };
+export { Autocomplete, Command, MAX_CUSTOM_ID_LENGTH, MessageHandler, PARAM_SEPARATOR, ReactionHandler, commandsNamed, createRegexFromPattern, dropInheritedRoutes, getAutocompleteHandlers, getCommandMap, getDeclaredRoutes, getHandlerRoutes, getMessageHandlers, getReactionHandlers, literalBraces, matchesEmoji, ownHandlerList, paramNarrowness, patternShape, sharedCustomId };

package/dist/esm/decorator/cooldown.decorator.js

@@ -1,5 +1,7 @@
 import 'reflect-metadata';
+import { Logger } from '../common/logger.js';
 import { declaring, refuse, decoratedName } from '../util/refusal.util.js';
+import { describeValue } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
 
 function Cooldown(options) {
@@ -14,6 +16,7 @@ function Cooldown(options) {
         // Checked where it applies, so the refusal names the handler or controller
         const problem = cooldownProblem(seconds, uses, per, by);
         if (problem) throw refuse(new Error(`${decoratedName(target, propertyKey)}: ${problem}`));
+        for (const warning of cooldownWarnings(options))logger.warn(`${decoratedName(target, propertyKey)}: ${warning}`);
         // Decorators apply bottom-up; prepending keeps them in the order they read.
         if (propertyKey === undefined) {
             const existing = Reflect.getOwnMetadata(META.classCooldowns, target) ?? [];
@@ -34,6 +37,20 @@ function Cooldown(options) {
  * The longest window, in seconds: half the furthest time a `Date` holds, 8.64e15 ms, so the moment a wait ends, now
  * plus the window, is a real date for a refusal's `retryAt` and the time it shows.
  */ const MAX_SECONDS = 4320000000000;
+const logger = new Logger('Cooldown');
+/**
+ * What a cooldown's options get wrong that the types refuse, yet still counts: a `bypass` that is not a function, which
+ * fails every call, and a `seconds` that is not a number, read as one. A falsy `bypass` means none.
+ */ function cooldownWarnings({ seconds, bypass }) {
+    const warnings = [];
+    if (bypass && typeof bypass !== 'function') {
+        warnings.push(`@Cooldown takes bypass as a function of the call, returning whether the call skips the cooldown, not ${describeValue(bypass)}; ` + 'every call it counts fails with it. In the next major version (5.0) it is refused.');
+    }
+    if (typeof seconds !== 'number') {
+        warnings.push(`@Cooldown takes seconds as a number, not ${describeValue(seconds)}, which it counts as a window of ` + `${Math.round(seconds * 1000)} ms. In the next major version (5.0) it is refused.`);
+    }
+    return warnings;
+}
 /** Why a cooldown's options cannot be counted, or undefined when they can. */ function cooldownProblem(seconds, uses, per, by) {
     if (!(seconds >= 0.001 && seconds <= MAX_SECONDS)) return `@Cooldown needs a number of seconds from 0.001 to ${MAX_SECONDS}, not ${seconds}.`;
     if (!Number.isInteger(uses) || uses < 1) return `@Cooldown needs a whole number of uses of at least 1, not ${uses}.`;

package/dist/esm/decorator/filter.decorator.js

@@ -3,7 +3,7 @@ import { makeInjectable } from '../util/injectable.util.js';
 import { assertStageEntries } from '../core/stage-scope.js';
 import { Logger } from '../common/logger.js';
 import { warnDeprecatedBehaviour } from '../common/deprecation.js';
-import { isConstructor, describeValue } from '../util/value.util.js';
+import { isConstructible, describeValue } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
 import { declaring, refuseOnMethod } from '../util/refusal.util.js';
 
@@ -40,7 +40,7 @@ import { declaring, refuseOnMethod } from '../util/refusal.util.js';
         refuseOnMethod('@Catch', target, propertyKey);
         makeInjectable(target);
         errorTypes.forEach((type, index)=>{
-            if (isConstructor(type)) return;
+            if (isConstructible(type)) return;
             const entry = ORDINALS[index] ? `${ORDINALS[index]} entry` : `entry ${index + 1}`;
             warnDeprecatedBehaviour(logger, `${target.name}: @Catch's ${entry}, ${describeValue(type)}, which matches no error,`, 'is refused', 'an error class, such as @Catch(CooldownError),');
         });

package/dist/esm/decorator/guard.decorator.js

@@ -1,6 +1,7 @@
 import 'reflect-metadata';
 import { handlerMethods, classLevelGuards, consumeDispatchMark, runDirectCall, declaringPrototype, classChain } from '../core/guard-runner.js';
 import { makeInjectable } from '../util/injectable.util.js';
+import { wrapsMethod } from '../util/method-wrapper.util.js';
 import { defineStageTypes, assertStageEntries } from '../core/stage-scope.js';
 import { META } from '../util/metadata-keys.js';
 import { declaring, deprecatedOnMethod } from '../util/refusal.util.js';
@@ -34,10 +35,10 @@ import { declaring, deprecatedOnMethod } from '../util/refusal.util.js';
  * which has already run the guards, passes through every wrapper.
  */ function applyGuards(descriptor, prototype, propertyKey) {
     const originalMethod = descriptor.value;
-    descriptor.value = async function(...args) {
+    descriptor.value = wrapsMethod(async function(...args) {
         if (consumeDispatchMark(args[0], this, propertyKey)) return originalMethod.apply(this, args);
         return runDirectCall(this, propertyKey, args, ()=>originalMethod.apply(this, args));
-    };
+    }, originalMethod);
     const wrappers = Reflect.getOwnMetadata(META.guardWrappers, prototype, propertyKey) ?? 0;
     Reflect.defineMetadata(META.guardWrappers, wrappers + 1, prototype, propertyKey);
 }

package/dist/esm/package.json.js

@@ -1,4 +1,4 @@
-var version = "4.2.0";
+var version = "4.2.2";
 var engines = {
 	node: ">=22.13"
 };