meocord 4.1.2 → 4.2.1

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

@@ -2,12 +2,13 @@ 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';
-import { isSegmentType, choicesOf, lookupTable, parseSegment } from '../core/scalar-types.js';
-import { refuseOnClass, refuse } from '../util/refusal.util.js';
+import { lookupTable, isSegmentType, choicesOf, parseSegment } from '../core/scalar-types.js';
+import { declaring, refuse, refuseOnClass } from '../util/refusal.util.js';
 import { withArticle, describeValue } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
 
@@ -69,19 +70,60 @@ const autocompleteRoute = (method, commandPath, optionName)=>({
     else handlers[index] = entry;
     Reflect.defineMetadata(key, handlers, target);
 }
-/** The class's own command map, started from a copy of the inherited one, for the same reason. */ function ownCommandMap(target) {
+/**
+ * Leaves each method the class's own decorators declare only those routes, of every kind, dropping the ones it inherits
+ * for it: what `@Controller({ inheritedRoutes: 'replace' })` does once the class's method decorators have run.
+ */ function dropInheritedRoutes(prototype) {
+    const redeclared = new Set(getDeclaredRoutes(prototype).map((route)=>route.method));
+    if (redeclared.size === 0) return;
+    const base = Object.getPrototypeOf(prototype);
+    // 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) ?? Object.create(null);
+    for (const [name, metas] of Object.entries(commands)){
+        const kept = metas.filter((meta)=>!inheritedFor(commandsNamed(baseCommands, name), (entry)=>entry.methodName)(meta));
+        if (kept.length > 0) commands[name] = kept;
+        else delete commands[name];
+    }
+    Reflect.defineMetadata(META.commands, commands, prototype);
+    const lists = [
+        [
+            META.messageHandlers,
+            (entry)=>entry.method
+        ],
+        [
+            META.reactionHandlers,
+            (entry)=>entry.method
+        ],
+        [
+            META.autocompleteHandlers,
+            (entry)=>entry.methodName
+        ]
+    ];
+    for (const [key, method] of lists){
+        const inherited = Reflect.getMetadata(key, base) ?? [];
+        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. 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 function(target, propertyKey) {
+    return declaring(function(target, propertyKey) {
         refuseOnClass('@MessageHandler', target, propertyKey);
         // An empty pattern means every message, as no pattern does
         if (pattern === '') {
@@ -95,7 +137,7 @@ function MessageHandler(pattern, options = {}) {
         };
         addOwnHandler(META.messageHandlers, target, declared, (other)=>other.method === method && other.pattern === declared.pattern);
         declareRoute(target, messageRoute(method, declared.pattern));
-    };
+    });
 }
 function ReactionHandler(emojiOrSettings, settings = {}) {
     const [emoji, own] = typeof emojiOrSettings === 'object' ? [
@@ -105,7 +147,7 @@ function ReactionHandler(emojiOrSettings, settings = {}) {
         emojiOrSettings,
         settings
     ];
-    return function(target, propertyKey) {
+    return declaring(function(target, propertyKey) {
         refuseOnClass('@ReactionHandler', target, propertyKey);
         const method = propertyKey.toString();
         addOwnHandler(META.reactionHandlers, target, {
@@ -114,7 +156,7 @@ function ReactionHandler(emojiOrSettings, settings = {}) {
             settings: own
         }, (other)=>other.method === method && other.emoji === emoji);
         declareRoute(target, reactionRoute(method, emoji));
-    };
+    });
 }
 /** A custom emoji as Discord writes it in a message: `<:name:id>`, or `<a:name:id>` for an animated one. */ const CUSTOM_EMOJI = /^<a?:\w+:(\d+)>$/;
 /**
@@ -143,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 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
@@ -169,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('')) {
@@ -186,25 +247,23 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
     literalLength += trailing.length;
     regexPattern += escapeLiteral(trailing);
     const regex = new RegExp(`^${regexPattern}$`);
-    // Literal text is the signal: a pattern spelling out more of the id describes it
-    // more exactly than one leaving it to a parameter. Fewer parameters breaks a tie
-    // between equal-length patterns, then narrower typed params; the order the controllers
-    // and handlers are listed in settles what is left, and the startup warning names the pair.
+    // What 4.1 ranked by, kept for code that reads CommandMeta.specificity; routing ranks segment by segment
     const specificity = routeSpecificity({
         literals: literalLength,
         params: params.length,
-        typed: Object.values(types).reduce((sum, type)=>sum + narrowness(type), 0)
+        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
     };
 }
-/** How few values a segment type takes, so a narrower type ranks first: words to choose from, then bool, int, number. */ const narrowness = (type)=>choicesOf(type) ? 4 : type === 'bool' ? 3 : type === 'int' ? 2 : 1;
 /** Why a `{name:type}` cannot type a customId segment, which holds text the bot wrote, with no message to read. */ function segmentTypeProblem(param, type) {
-    const kinds = 'string, int, number, bool, or words to choose from such as {mode:on|off}';
+    const kinds = 'string, int, number, bool, snowflake, uuid, or words to choose from such as {mode:on|off}';
     if ([
         'member',
         'user',
@@ -228,10 +287,11 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
  * the keys the handler's params require are checked against the pattern or route, a typed segment's value against
  * its type, and a select menu's choices, such as `values: string[]`, against what discord.js gives; a key a pipe
  * produces is declared `Piped<T>`, and left to the pipe. Two component handlers of one type whose patterns match
- * exactly the same ids stop the bot at startup; patterns that only overlap are warned about, naming the one that
- * runs: the more specific, or between equally specific ones, the one listed first. In the next major version (5.0),
- * the one that spells out the first segment where two equally specific patterns differ runs instead, and the warning
- * names the pairs that changes. A context menu handler receives the kind its builder's `setType()` names, and one
+ * exactly the same ids stop the bot at startup. Patterns that both match an id rank segment by segment, left to
+ * right: at the first segment one spells out as literal text and the other leaves to a param, the literal one runs,
+ * so `profile/me/{section}` takes `profile/me/edit` from `profile/{userId}/edit`; between patterns that leaves tied,
+ * the narrower type at the first param where they differ. Two still tied are warned about as the bot starts, and the
+ * one listed first runs. A context menu handler receives the kind its builder's `setType()` names, and one
  * declaring the other kind fails to compile; when the compiler cannot tell the kind, `@Command` checks the parameter
  * type it emits as it applies. A subclass that re-declares an inherited handler on the same name or pattern takes its
  * own builder and options; on another it still answers the inherited one too, which the bot warns about as it
@@ -264,12 +324,11 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
  * @category Handlers
  * @see {@link CommandBuilder}
  * @see {@link route}
- * @see {@link https://meocord.dev/docs/4.1/slash-commands | Slash commands}
- * @see {@link https://meocord.dev/docs/4.1/components | Buttons, selects and modals}
+ * @see {@link https://meocord.dev/docs/4.2/slash-commands | Slash commands}
+ * @see {@link https://meocord.dev/docs/4.2/components | Buttons, selects and modals}
  */ function Command(name, builderOrType) {
     const commandName = typeof name === 'string' ? name : name.pattern;
-    return function(target, propertyKey, _descriptor) {
-        var _commands, _commandName;
+    return declaring(function(target, propertyKey, _descriptor) {
         refuseOnClass('@Command', target, propertyKey);
         const originalMethod = _descriptor.value;
         if (!originalMethod) {
@@ -277,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)}.`);
             }
@@ -286,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;
@@ -321,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
                 }));
             }
@@ -341,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);
@@ -349,10 +412,14 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
                     cause: error
                 }));
             }
-            const { regex: generatedRegex, params, specificity: patternSpecificity } = pattern;
-            regex = generatedRegex;
-            dynamicParams = params;
-            specificity = patternSpecificity;
+            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,
@@ -369,14 +436,15 @@ 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;
         Reflect.defineMetadata(META.commands, commands, target);
         declareRoute(target, commandRoute(propertyKey, commandType, commandName));
-    };
+    });
 }
 /** The interaction class Discord sends for each context menu kind. */ const CONTEXT_MENU_INTERACTIONS = new Map([
     [
@@ -448,9 +516,9 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
  * @group Decorators
  * @category Handlers
  * @see {@link Command}
- * @see {@link https://meocord.dev/docs/4.1/autocomplete | Autocomplete}
+ * @see {@link https://meocord.dev/docs/4.2/autocomplete | Autocomplete}
  */ function Autocomplete(commandPath, optionName) {
-    return function(target, propertyKey, _descriptor) {
+    return declaring(function(target, propertyKey, _descriptor) {
         refuseOnClass('@Autocomplete', target, propertyKey);
         const methodName = propertyKey.toString();
         addOwnHandler(META.autocompleteHandlers, target, {
@@ -459,7 +527,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
             methodName
         }, (other)=>other.methodName === methodName && other.commandPath === commandPath && other.optionName === optionName);
         declareRoute(target, autocompleteRoute(methodName, commandPath, optionName));
-    };
+    });
 }
 /**
  * Returns a controller's autocomplete handlers, option-specific ones first.
@@ -481,52 +549,63 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
     const match = new RegExp(`^${PLACEHOLDER_PATTERN.source}$`).exec(segment);
     return match ? typeKey(match[2]) : undefined;
 }
-/** Whether a segment's two readings can both take one value: a literal, text, or a typed param. */ function segmentsOverlap(left, right) {
+/**
+ * How few values a segment type takes, so a narrower type ranks first: words to choose from, then bool, uuid,
+ * snowflake, int, number, and text last. A snowflake is narrower than a number, which takes all its values.
+ */ const NARROWNESS = lookupTable({
+    bool: 5,
+    uuid: 4,
+    snowflake: 3,
+    int: 2,
+    number: 1,
+    '': 0
+});
+const narrowness = (type)=>choicesOf(type) ? 6 : NARROWNESS[type];
+/**
+ * How narrow a pattern segment that is a param, `{name}` or `{name:type}`, is: from `0` for text to `4` for words to
+ * choose from. `undefined` for a segment of literal text.
+ */ function paramNarrowness(segment) {
+    const type = segmentParamType(segment);
+    return type === undefined ? undefined : narrowness(type);
+}
+/** A value of each scalar segment type: an int, a bool, a snowflake and a uuid; text takes any. */ const SAMPLE_VALUES = [
+    '1',
+    'true',
+    '10000000000000000',
+    '00000000-0000-0000-0000-000000000000'
+];
+/** A value both readings of a segment take: a literal, text, or a typed param; `undefined` when they share none. */ function sharedValue(left, right) {
     const [a, b] = [
         segmentParamType(left),
         segmentParamType(right)
     ];
-    if (a === undefined && b === undefined) return left === right;
-    if (a === undefined || b === undefined) {
-        const [type, literal] = a === undefined ? [
-            b,
+    const takes = (type, segment, value)=>type === undefined ? segment === value : type === '' || parseSegment(type, value) !== undefined;
+    // Every type takes one of these when it takes anything another reading takes: a literal, a listed word, or a value
+    // of each scalar type
+    const candidates = [
+        ...a === undefined ? [
             left
-        ] : [
-            a,
+        ] : [],
+        ...b === undefined ? [
             right
-        ];
-        return type === '' || parseSegment(type, literal) !== undefined;
-    }
-    if (a === '' || b === '' || a === b) return true;
-    // Words to choose from overlap another type when one of them is a value of it
-    const [wordsA, wordsB] = [
-        choicesOf(a),
-        choicesOf(b)
+        ] : [],
+        ...choicesOf(a ?? '') ?? [],
+        ...choicesOf(b ?? '') ?? [],
+        ...SAMPLE_VALUES
     ];
-    if (wordsA) return wordsA.some((word)=>parseSegment(b, word) !== undefined);
-    if (wordsB) return wordsB.some((word)=>parseSegment(a, word) !== undefined);
-    // Of the scalar types, only a whole number and a number share values
-    return a === 'int' && b === 'number' || a === 'number' && b === 'int';
+    return candidates.find((value)=>takes(a, left, value) && takes(b, right, value));
 }
 /**
- * Finds pairs of customId patterns that can both match one id, such as `a/{x}/c` and `a/b/{y}`.
- * @returns Each ambiguous pair once, in the order the patterns were given.
- */ function findAmbiguousRoutes(patterns) {
-    const segmentsOf = (pattern)=>pattern.split(PARAM_SEPARATOR);
-    const collisions = [];
-    for(let i = 0; i < patterns.length; i++){
-        for(let j = i + 1; j < patterns.length; j++){
-            const left = segmentsOf(patterns[i]);
-            const right = segmentsOf(patterns[j]);
-            if (left.length !== right.length) continue;
-            const disjoint = left.some((segment, index)=>!segmentsOverlap(segment, right[index]));
-            if (!disjoint) collisions.push([
-                patterns[i],
-                patterns[j]
-            ]);
-        }
-    }
-    return collisions;
+ * A customId both patterns match, such as `ticket/1/close` for `ticket/{id}/close` and `ticket/{n:int}/close`;
+ * `undefined` when no id matches both.
+ */ function sharedCustomId(left, right) {
+    const [a, b] = [
+        left.split(PARAM_SEPARATOR),
+        right.split(PARAM_SEPARATOR)
+    ];
+    if (a.length !== b.length) return undefined;
+    const values = a.map((segment, index)=>sharedValue(segment, b[index]));
+    return values.every((value)=>value !== undefined) ? values.join(PARAM_SEPARATOR) : undefined;
 }
 
-export { Autocomplete, Command, MessageHandler, PARAM_SEPARATOR, ReactionHandler, createRegexFromPattern, findAmbiguousRoutes, getAutocompleteHandlers, getCommandMap, getDeclaredRoutes, getHandlerRoutes, getMessageHandlers, getReactionHandlers, matchesEmoji, ownHandlerList, patternShape };
+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 { refuse, decoratedName } from '../util/refusal.util.js';
+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) {
@@ -10,10 +12,11 @@ function Cooldown(options) {
         per,
         windowMs: Math.round(seconds * 1000)
     };
-    return function(target, propertyKey) {
+    return declaring(function(target, propertyKey) {
         // 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) ?? [];
@@ -28,12 +31,26 @@ function Cooldown(options) {
                 ...existing
             ], target, propertyKey);
         }
-    };
+    });
 }
 /**
  * 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/defer.decorator.js

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
 import { nonInteractionHandler, deferMisuseError } from '../core/defer.js';
-import { refuseOnClass, refuse } from '../util/refusal.util.js';
+import { declaring, refuseOnClass, refuse } from '../util/refusal.util.js';
 import { META } from '../util/metadata-keys.js';
 
 /**
@@ -37,9 +37,9 @@ import { META } from '../util/metadata-keys.js';
  * @category Pipeline stages
  * @see {@link DeferOptions}
  * @see {@link respond}
- * @see {@link https://meocord.dev/docs/4.1/defer | Deferring}
+ * @see {@link https://meocord.dev/docs/4.2/defer | Deferring}
  */ function Defer(options = {}) {
-    return (target, propertyKey)=>{
+    return declaring((target, propertyKey)=>{
         refuseOnClass('@Defer', target, propertyKey);
         const methodName = String(propertyKey);
         const kind = nonInteractionHandler(target, methodName);
@@ -47,7 +47,7 @@ import { META } from '../util/metadata-keys.js';
         Reflect.defineMetadata(META.deferOptions, {
             ...options
         }, target, methodName);
-    };
+    });
 }
 
 export { Defer };

package/dist/esm/decorator/event.decorator.js

@@ -1,11 +1,11 @@
 import 'reflect-metadata';
 import { ownHandlerList } from './controller.decorator.js';
 import { META } from '../util/metadata-keys.js';
-import { refuseOnClass } from '../util/refusal.util.js';
+import { declaring, refuseOnClass } from '../util/refusal.util.js';
 
 function eventDecorator(event, once) {
     // Generic over the method, so it is checked against the event's arguments rather than required to match exactly
-    return function(target, propertyKey, _descriptor) {
+    return declaring(function(target, propertyKey, _descriptor) {
         refuseOnClass(once ? '@Once' : '@On', target, propertyKey);
         const handlers = ownHandlerList(META.eventHandlers, target);
         handlers.push({
@@ -14,7 +14,7 @@ function eventDecorator(event, once) {
             once
         });
         Reflect.defineMetadata(META.eventHandlers, handlers, target);
-    };
+    });
 }
 /**
  * Handles a discord.js client event every time it is emitted, on a controller or a service.
@@ -42,7 +42,7 @@ function eventDecorator(event, once) {
  * @group Decorators
  * @category Handlers
  * @see {@link Once}
- * @see {@link https://meocord.dev/docs/4.1/gateway-events | Gateway events}
+ * @see {@link https://meocord.dev/docs/4.2/gateway-events | Gateway events}
  */ function On(event) {
     return eventDecorator(event, false);
 }
@@ -69,7 +69,7 @@ function eventDecorator(event, once) {
  * @group Decorators
  * @category Handlers
  * @see {@link On}
- * @see {@link https://meocord.dev/docs/4.1/gateway-events | Gateway events}
+ * @see {@link https://meocord.dev/docs/4.2/gateway-events | Gateway events}
  */ function Once(event) {
     return eventDecorator(event, true);
 }

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

@@ -5,7 +5,7 @@ import { Logger } from '../common/logger.js';
 import { warnDeprecatedBehaviour } from '../common/deprecation.js';
 import { isConstructor, describeValue } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
-import { refuseOnMethod } from '../util/refusal.util.js';
+import { declaring, refuseOnMethod } from '../util/refusal.util.js';
 
 /**
  * Marks a class as an exception filter for the given error types.
@@ -34,9 +34,9 @@ import { refuseOnMethod } from '../util/refusal.util.js';
  * @group Decorators
  * @category Pipeline stages
  * @see {@link UseFilter}
- * @see {@link https://meocord.dev/docs/4.1/exception-filters | Exception filters}
+ * @see {@link https://meocord.dev/docs/4.2/exception-filters | Exception filters}
  */ function Catch(...errorTypes) {
-    return function(target, propertyKey) {
+    return declaring(function(target, propertyKey) {
         refuseOnMethod('@Catch', target, propertyKey);
         makeInjectable(target);
         errorTypes.forEach((type, index)=>{
@@ -45,7 +45,7 @@ import { refuseOnMethod } from '../util/refusal.util.js';
             warnDeprecatedBehaviour(logger, `${target.name}: @Catch's ${entry}, ${describeValue(type)}, which matches no error,`, 'is refused', 'an error class, such as @Catch(CooldownError),');
         });
         Reflect.defineMetadata(META.catchTypes, errorTypes, target);
-    };
+    });
 }
 const logger = new Logger('Catch');
 const ORDINALS = [
@@ -85,9 +85,9 @@ const ORDINALS = [
  * @group Decorators
  * @category Pipeline stages
  * @see {@link Catch}
- * @see {@link https://meocord.dev/docs/4.1/exception-filters | Exception filters}
+ * @see {@link https://meocord.dev/docs/4.2/exception-filters | Exception filters}
  */ function UseFilter(...filters) {
-    return function(target, propertyKey) {
+    return declaring(function(target, propertyKey) {
         const where = propertyKey === undefined ? target.name : `${target.constructor.name}.${String(propertyKey)}`;
         assertStageEntries('@UseFilter', 'filter', where, filters);
         // Decorators apply bottom-up, so a higher decorator's filters are tried first.
@@ -104,7 +104,7 @@ const ORDINALS = [
                 ...existing
             ], target, propertyKey);
         }
-    };
+    });
 }
 
 export { Catch, UseFilter };