meocord 4.1.2 → 4.2.0

package/dist/esm/core/scalar-types.js

@@ -34,18 +34,30 @@ const UNIT_MS = lookupTable({
         return total + Number(amount) * UNIT_MS[unit];
     }, 0);
 }
+/** The largest snowflake: Discord's IDs are unsigned 64-bit integers. */ const MAX_SNOWFLAKE = 2n ** 64n - 1n;
+/**
+ * A Discord ID, kept as its text: 17 to 20 digits, no leading zero, up to the largest 64-bit value. An ID's top 42 bits
+ * are milliseconds since 2015-01-01, so every ID made from 2015-01-28 on has 17 digits or more, and none is a safe
+ * integer.
+ */ const snowflake = (word)=>/^[1-9]\d{16,19}$/.test(word) && BigInt(word) <= MAX_SNOWFLAKE ? word : undefined;
+/** A UUID in its canonical 8-4-4-4-12 form, in either case, kept as written. */ const uuid = (word)=>/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(word) ? word : undefined;
 /** The words a type such as `on|off` chooses from, or `undefined` for any other type. */ const choicesOf = (type)=>type.includes('|') ? type.split('|') : undefined;
 /** The types a component's customId segment can take: each parsed from the segment alone, with no request. */ const SEGMENT_TYPES = lookupTable({
     string: (segment)=>segment,
     int: (segment)=>number(segment, true),
     number: (segment)=>number(segment, false),
-    bool
+    bool,
+    snowflake,
+    uuid
 });
-/** Whether `type` can type a customId segment: `string`, `int`, `number`, `bool`, or words to choose from. */ const isSegmentType = (type)=>type in SEGMENT_TYPES || choicesOf(type) !== undefined;
+/**
+ * Whether `type` can type a customId segment: `string`, `int`, `number`, `bool`, `snowflake`, `uuid`, or words to
+ * choose from.
+ */ const isSegmentType = (type)=>type in SEGMENT_TYPES || choicesOf(type) !== undefined;
 /** A customId segment as its type's value, words to choose from compared as written: `undefined` when it is not one. */ function parseSegment(type, segment) {
     const choices = choicesOf(type);
     if (choices) return choices.includes(segment) ? segment : undefined;
     return SEGMENT_TYPES[type](segment);
 }
 
-export { bool, choicesOf, duration, isSegmentType, lookupTable, number, parseSegment };
+export { bool, choicesOf, duration, isSegmentType, lookupTable, number, parseSegment, snowflake, uuid };

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

@@ -95,7 +95,7 @@ async function withTimeout(promise, ms, what) {
  *
  * @group Controllers
  * @see {@link ShardCallResult}
- * @see {@link https://meocord.dev/docs/4.1/sharding | Sharding}
+ * @see {@link https://meocord.dev/docs/4.2/sharding | Sharding}
  */ class ShardContext {
     /** The ids of the shards this process runs. With process sharding, one id; otherwise every shard, once ready. */ get ids() {
         if (this.client?.shard) return [

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

@@ -4,7 +4,7 @@ import { classDecorators, handlerStageClasses } from './handler-pipeline.js';
 import { reachableClasses, assertTypedParameters } from './providers.js';
 import { themeResolverClass } from './theme-resolvers.js';
 import { META } from '../util/metadata-keys.js';
-import { refuse } from '../util/refusal.util.js';
+import { startupError } from '../util/refusal.util.js';
 
 /** The guards `@UseGuard` puts on a class's methods, handlers or not, which a direct call runs too. */ function methodGuards(cls) {
     const guards = [];
@@ -75,8 +75,7 @@ import { refuse } from '../util/refusal.util.js';
 /** Runs the startup checks over every class an app runs, so a class that cannot be made is refused by name now. */ function assertStartupClasses({ classes, decorators }, { translator }) {
     assertTypedParameters(classes, decorators);
     if (translator) return;
-    const needsOne = classes.find((cls)=>injectedTokens(cls).includes(Translator));
-    if (needsOne) throw refuse(missingTranslatorError(needsOne));
+    for (const needsOne of classes.filter((cls)=>injectedTokens(cls).includes(Translator)))startupError(missingTranslatorError(needsOne));
 }
 
 export { assertStartupClasses, lateGuardCheck, startupClasses };

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

@@ -1,8 +1,8 @@
 import 'reflect-metadata';
 import { stageClasses, sourcePrototype } from './guard-runner.js';
 import { makeInjectable } from '../util/injectable.util.js';
-import { resolverCaches, ThemeCache, attachThemeCache, lookupLayers } from './theme-resolvers.js';
-import { releaseAmbientTheme, claimAmbientTheme, defaultTheme, mergeTheme, themeLayersVersion, ambientThemeVersion, ownsAmbientTheme, hasAmbientTheme, setThemeOutsideCalls, useTheme } from './theme-scope.js';
+import { lookupLayers, resolverCaches, ThemeCache, attachThemeCache } from './theme-resolvers.js';
+import { releaseAmbientTheme, claimAmbientTheme, mergeTheme, defaultTheme, themeLayersVersion, ambientThemeVersion, ownsAmbientTheme, hasAmbientTheme, setThemeOutsideCalls, useTheme } from './theme-scope.js';
 import { META } from '../util/metadata-keys.js';
 
 /** Classes with a `@UseTheme`, on the class or one of its methods. */ const THEMED_CLASSES = new WeakSet();

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

@@ -7,7 +7,7 @@ import { BUILT_IN_TYPES } from '../core/message-params.js';
 import { assertObservers } from '../core/observer-runner.js';
 import { assertValidTheme, themeForProblem } from '../core/theme-validation.js';
 import { copyLayer } from '../core/theme-scope.js';
-import { deprecatedOnMethod, refuse } from '../util/refusal.util.js';
+import { declaring, deprecatedOnMethod, refuse } from '../util/refusal.util.js';
 import { timeoutProblem } from '../util/timer-limit.util.js';
 import { META } from '../util/metadata-keys.js';
 
@@ -18,14 +18,19 @@ import { META } from '../util/metadata-keys.js';
     if (prefix !== undefined && !isText(prefix) && typeof prefix !== 'function' && !(Array.isArray(prefix) && prefix.every(isText))) {
         throw refuse(new TypeError(`${appName}: @MeoCord({ messages: { prefix } }) takes a string, a list of strings, or a function of the message returning them.`));
     }
-    for (const [name, value] of Object.entries({
+    const flags = {
         caseSensitive,
         replyEmoji: messages.replyEmoji,
         dmOnError: messages.dmOnError,
-        dmOnCooldown: messages.dmOnCooldown
-    })){
+        dmOnCooldown: messages.dmOnCooldown,
+        slowHandlerWarning: messages.slowHandlerWarning
+    };
+    for (const [name, value] of Object.entries(flags)){
         if (value !== undefined && typeof value !== 'boolean') throw refuse(new TypeError(`${appName}: @MeoCord({ messages: { ${name} } }) takes true or false.`));
     }
+    if (messages.handlers !== undefined && messages.handlers !== 'sequential' && messages.handlers !== 'concurrent') {
+        throw refuse(new TypeError(`${appName}: @MeoCord({ messages: { handlers } }) takes 'sequential' or 'concurrent'.`));
+    }
     if (mention !== undefined && typeof mention !== 'boolean' && mention !== 'only') {
         throw refuse(new TypeError(`${appName}: @MeoCord({ messages: { mention } }) takes true, false or 'only'.`));
     }
@@ -87,9 +92,9 @@ import { META } from '../util/metadata-keys.js';
  * @see {@link MeoCordOptions}
  * @see {@link MeoCordFactory}
  * @see {@link MeoCordConfig}
- * @see {@link https://meocord.dev/docs/4.1/configuration | Configuration}
+ * @see {@link https://meocord.dev/docs/4.2/configuration | Configuration}
  */ function MeoCord(options) {
-    return (target, propertyKey)=>{
+    return declaring((target, propertyKey)=>{
         if (deprecatedOnMethod('@MeoCord', target, propertyKey)) return;
         assertStageEntries('@MeoCord({ guards })', 'guard', target.name, options.guards ?? []);
         assertStageEntries('@MeoCord({ interceptors })', 'interceptor', target.name, options.interceptors ?? []);
@@ -111,7 +116,7 @@ import { META } from '../util/metadata-keys.js';
             ...options,
             theme
         }, target);
-    };
+    });
 }
 /** Refuses theme resolvers and cache options the runtime cannot follow, where the app is declared. */ function assertThemeFor(appName, { themeFor, themeCache, themeForTimeoutMs }) {
     const problem = themeFor === undefined ? undefined : themeForProblem(themeFor, `${appName}: @MeoCord({ themeFor })`, 'or a class implementing ThemeResolver.');

package/dist/esm/decorator/command-builder.decorator.js

@@ -1,7 +1,7 @@
 import 'reflect-metadata';
 import { makeInjectable } from '../util/injectable.util.js';
 import { META } from '../util/metadata-keys.js';
-import { deprecatedOnMethod } from '../util/refusal.util.js';
+import { declaring, deprecatedOnMethod } from '../util/refusal.util.js';
 
 /**
  * Marks a class as a command's builder, which describes the command MeoCord registers with Discord.
@@ -30,9 +30,9 @@ import { deprecatedOnMethod } from '../util/refusal.util.js';
  * @group Decorators
  * @category Handlers
  * @see {@link Command}
- * @see {@link https://meocord.dev/docs/4.1/slash-commands | Slash commands}
+ * @see {@link https://meocord.dev/docs/4.2/slash-commands | Slash commands}
  */ function CommandBuilder(commandType, options = {}) {
-    return function(target, propertyKey) {
+    return declaring(function(target, propertyKey) {
         if (deprecatedOnMethod('@CommandBuilder', target, propertyKey)) return;
         makeInjectable(target);
         // Define the command type metadata for the target class
@@ -40,7 +40,7 @@ import { deprecatedOnMethod } from '../util/refusal.util.js';
         if (options.guilds) Reflect.defineMetadata(META.builderGuilds, [
             ...options.guilds
         ], target);
-    };
+    });
 }
 
 export { CommandBuilder };

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

@@ -1,7 +1,8 @@
+import { dropInheritedRoutes } from './controller.decorator.js';
 import { guardOwnHandlersWithBaseGuards } from './guard.decorator.js';
 import { makeInjectable } from '../util/injectable.util.js';
 import { META } from '../util/metadata-keys.js';
-import { deprecatedOnMethod } from '../util/refusal.util.js';
+import { declaring, deprecatedOnMethod } from '../util/refusal.util.js';
 
 /**
  * Marks a class as a controller, whose methods handle commands, components, messages, reactions or events.
@@ -35,14 +36,18 @@ import { deprecatedOnMethod } from '../util/refusal.util.js';
  * @category Controllers
  * @see {@link Command}
  * @see {@link ControllerOptions}
- * @see {@link https://meocord.dev/docs/4.1/how-a-call-runs | How a call runs}
+ * @see {@link https://meocord.dev/docs/4.2/how-a-call-runs | How a call runs}
  */ function Controller(options = {}) {
-    return function(target, propertyKey) {
+    return declaring(function(target, propertyKey) {
         if (deprecatedOnMethod('@Controller', target, propertyKey)) return;
         makeInjectable(target);
         if (options.inheritStages === false) Reflect.defineMetadata(META.inheritStages, false, target);
+        if (options.inheritedRoutes === 'replace') {
+            dropInheritedRoutes(target.prototype);
+            Reflect.defineMetadata(META.replacesInheritedRoutes, true, target.prototype);
+        }
         guardOwnHandlersWithBaseGuards(target);
-    };
+    });
 }
 
 export { Controller };

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

@@ -6,8 +6,8 @@ import { matchesCommandType, interactionClassName, isCustomIdRouted } from '../u
 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,6 +69,42 @@ const autocompleteRoute = (method, commandPath, optionName)=>({
     else handlers[index] = entry;
     Reflect.defineMetadata(key, handlers, 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) ?? {};
+    for (const [name, metas] of Object.entries(commands)){
+        const kept = metas.filter((meta)=>!inheritedFor(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. */ function ownCommandMap(target) {
     const own = Reflect.getOwnMetadata(META.commands, target);
     if (own) return own;
@@ -81,7 +117,7 @@ const autocompleteRoute = (method, commandPath, optionName)=>({
         ]));
 }
 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 +131,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 +141,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 +150,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+)>$/;
 /**
@@ -146,7 +182,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
 /** The character a parameter will not cross, so one pattern segment maps to one value. */ const PARAM_SEPARATOR = '/';
 /** 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
+ * 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.
  */ function createRegexFromPattern(pattern) {
@@ -186,14 +222,11 @@ 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)
     });
     return {
         regex,
@@ -202,9 +235,8 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
         specificity
     };
 }
-/** 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 +260,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,11 +297,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) {
+    return declaring(function(target, propertyKey, _descriptor) {
         var _commands, _commandName;
         refuseOnClass('@Command', target, propertyKey);
         const originalMethod = _descriptor.value;
@@ -349,10 +382,9 @@ 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;
         }
         const declared = {
             methodName: propertyKey,
@@ -376,7 +408,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)(?::([^}/]*))?}/g;
         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 +480,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 +491,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 +513,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, MessageHandler, PARAM_SEPARATOR, ReactionHandler, createRegexFromPattern, dropInheritedRoutes, getAutocompleteHandlers, getCommandMap, getDeclaredRoutes, getHandlerRoutes, getMessageHandlers, getReactionHandlers, matchesEmoji, ownHandlerList, paramNarrowness, patternShape, sharedCustomId };

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

@@ -1,5 +1,5 @@
 import 'reflect-metadata';
-import { refuse, decoratedName } from '../util/refusal.util.js';
+import { declaring, refuse, decoratedName } from '../util/refusal.util.js';
 import { META } from '../util/metadata-keys.js';
 
 function Cooldown(options) {
@@ -10,7 +10,7 @@ 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}`));
@@ -28,7 +28,7 @@ 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

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 };