meocord 4.1.2 → 4.2.1

package/dist/cjs/_shared/{startup-roots-lFc69AxC.cjs → startup-roots-CgfPQrNl.cjs}

@@ -1,13 +1,40 @@
 'use strict';
 
 var discord_js = require('discord.js');
-var controller_decorator = require('./controller.decorator-BywwkU9O.cjs');
-var providers = require('./providers-BMMLp2SN.cjs');
+var controller_decorator = require('./controller.decorator-XKMlcUZz.cjs');
+var providers = require('./providers-BZgJyfZS.cjs');
 var enum_index = require('../enum/index.cjs');
-var translateError = require('./translate-error-BnM8FbSH.cjs');
+var node_async_hooks = require('node:async_hooks');
+var translateError = require('./translate-error-BUAR1WYG.cjs');
 
 /**
- * Every customId-pattern route of the given controllers, most specific first, read from metadata alone.
+ * How a pattern ranks, one character per segment twice over: `L` for literal text or `P` for a param, then how narrow
+ * each param is, the narrowest as the lowest digit. Two keys of one length compare as text: literal before param at
+ * the first segment where they differ, then the narrower type.
+ */ function rankKey(pattern) {
+    const narrowness = pattern.split('/').map(controller_decorator.paramNarrowness);
+    const kinds = narrowness.map((rank)=>rank === undefined ? 'L' : 'P').join('');
+    return `${kinds}/${narrowness.map((rank)=>String(rank === undefined ? 0 : 9 - rank)).join('')}`;
+}
+/**
+ * Orders two routes as dispatch tries them. Left to right, the first segment one pattern spells out as literal text
+ * while the other leaves it to a param ranks the literal one first: `a/{x}` before `{x}/abcd`, `profile/me/{section}`
+ * before `profile/{userId}/edit`. Between patterns that leaves tied, the first param where one type is narrower ranks
+ * it first: words to choose from, then `bool`, `uuid`, `snowflake`, `int`, `number`, then text. Patterns of different
+ * segment counts, which no customId matches both of, are ordered by count only so the order is total; component
+ * patterns have no catch-all param. What remains tied keeps its listing order.
+ */ function rank(keys) {
+    return (a, b)=>{
+        const [left, right] = [
+            keys.get(a),
+            keys.get(b)
+        ];
+        if (left.length !== right.length) return left.length - right.length;
+        return left < right ? -1 : left > right ? 1 : 0;
+    };
+}
+/**
+ * Every customId-pattern route of the given controllers, in the order dispatch tries them, read from metadata alone.
  * Throws for two handlers whose patterns match the same customIds of one component type; one handler
  * declared under two spellings of a pattern keeps one route.
  */ function buildComponentRoutes(controllerClasses) {
@@ -40,22 +67,11 @@ var translateError = require('./translate-error-BnM8FbSH.cjs');
             }
         }
     }
-    // A stable sort, so equally specific patterns keep the order their controllers and handlers are listed in
-    return routes.sort((a, b)=>(b.meta.specificity ?? 0) - (a.meta.specificity ?? 0));
-}
-/**
- * Whether `a` spells out the first segment where it and `b` differ as literal text while `b` leaves it to a
- * parameter, the tie-break between equally specific patterns in the next major version (5.0).
- */ function literalFirst(a, b) {
-    const [left, right] = [
-        a.split('/'),
-        b.split('/')
-    ];
-    for(let i = 0; i < Math.min(left.length, right.length); i++){
-        const leftLiteral = !left[i].includes('{');
-        if (leftLiteral !== !right[i].includes('{')) return leftLiteral;
-    }
-    return false;
+    // A stable sort, so what the ranking leaves tied keeps the order controllers and handlers are listed in
+    return routes.sort(rank(new Map(routes.map((route)=>[
+            route,
+            rankKey(route.pattern)
+        ]))));
 }
 /** A component type as an error names it: `button`, `modal submit`, `select menu`. */ const typeLabel = (type)=>type.toLowerCase().replaceAll('_', ' ');
 /**
@@ -80,6 +96,12 @@ const typesByPattern = new Map();
     if (!types) typesByPattern.set(pattern, types = controller_decorator.createRegexFromPattern(pattern).types);
     return types;
 }
+/**
+ * The params `pattern`, compiled as `regex`, captures from a customId, each typed param as its value:
+ * `undefined` when the customId does not match, or a segment is not a value of its param's type.
+ */ function readCustomId(pattern, regex, customId) {
+    return readCustomIdSegments(pattern, regex, customId)?.values;
+}
 /** {@link readCustomId}'s values, with each param's text as the customId gave it. */ function readCustomIdSegments(pattern, regex, customId) {
     const match = regex.exec(customId);
     if (!match) return undefined;
@@ -97,18 +119,40 @@ const typesByPattern = new Map();
         text
     };
 }
-/** Pattern pairs that can match one customId, compared only within a component type, as dispatch does. */ function findComponentRouteConflicts(routes) {
-    const byType = new Map();
-    for (const { meta, pattern } of routes)byType.set(meta.type, [
-        ...byType.get(meta.type) ?? [],
-        pattern
-    ]);
-    return [
-        ...byType
-    ].flatMap(([type, patterns])=>controller_decorator.findAmbiguousRoutes(patterns).map((pair)=>({
-                type,
-                patterns: pair
-            })));
+/**
+ * Pattern pairs of one component type that the ranking leaves tied and that can match one customId, each with the
+ * pattern that runs, the one ranked first in `routes`, and an id both match. Only patterns of one rank key, read
+ * together, can tie, so each group is compared within itself.
+ */ function findComponentRouteConflicts(routes) {
+    const groups = new Map();
+    for (const route of routes){
+        // The literal text and each param's narrowness: patterns that differ in either rank apart or match no id in common
+        const key = `${route.meta.type}\0${route.pattern.split('/').map((segment)=>controller_decorator.paramNarrowness(segment) ?? `=${segment}`).join('\0')}`;
+        groups.set(key, [
+            ...groups.get(key) ?? [],
+            route
+        ]);
+    }
+    const conflicts = [];
+    for (const group of groups.values()){
+        for(let i = 0; i < group.length; i++){
+            for(let j = i + 1; j < group.length; j++){
+                const customId = controller_decorator.sharedCustomId(group[i].pattern, group[j].pattern);
+                if (customId === undefined) continue;
+                const patterns = [
+                    group[i].pattern,
+                    group[j].pattern
+                ];
+                conflicts.push({
+                    type: group[i].meta.type,
+                    patterns,
+                    runs: group[i].pattern,
+                    customId
+                });
+            }
+        }
+    }
+    return conflicts;
 }
 
 const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.methodName}`;
@@ -131,7 +175,7 @@ const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.metho
  * Refuses commands of which only one could run or be registered: two handlers of one slash command name or subcommand
  * path or of one context menu name and kind, or two builders of one command; a command's subcommands, and a user and a
  * message context menu of one name, are no clash. The app, `meocord register`, the shard manager and testing call it.
- * @throws Error naming both handlers, or both builders, with what to do instead.
+ * Each clash is a startup error, naming both handlers or both builders with what to do instead; see `startupError`.
  */ function assertDistinctCommands(controllerClasses) {
     const handlers = new Map();
     const builders = new Map();
@@ -149,7 +193,8 @@ const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.metho
                 const key = `${meta.type}\0${name}`;
                 const earlier = (handlers.get(key) ?? []).find((other)=>overlap(other.meta, meta));
                 if (earlier) {
-                    throw controller_decorator.refuse(new Error(`${where(earlier)}: it and ${where(here)} both handle the ${describe(meta.type, name, contextMenuKind(meta) ?? contextMenuKind(earlier.meta))}, ` + `so only ${where(earlier)} would ever run. Keep one handler for it, or give the other a name or ` + `subcommand path of its own.`));
+                    controller_decorator.startupError(new Error(`${where(earlier)}: it and ${where(here)} both handle the ${describe(meta.type, name, contextMenuKind(meta) ?? contextMenuKind(earlier.meta))}, ` + `so only ${where(earlier)} would ever run. Keep one handler for it, or give the other a name or ` + `subcommand path of its own.`));
+                    continue;
                 }
                 handlers.set(key, [
                     ...handlers.get(key) ?? [],
@@ -170,7 +215,7 @@ const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.metho
                         name: typeof body.name === 'string' ? body.name : name
                     });
                 } else if (built.meta.builderClass !== meta.builderClass) {
-                    throw controller_decorator.refuse(new Error(`${where(built)}: its builder ${built.meta.builderClass.name} and ${meta.builderClass.name} on ${where(here)} both ` + `build the ${describe(meta.type, built.name, contextMenuKind(meta))}, and Discord registers one command ` + `per name and type, so only the first would be. Keep one builder, on a single @Command, and declare ` + `the other handlers with CommandType.${meta.type}.`));
+                    controller_decorator.startupError(new Error(`${where(built)}: its builder ${built.meta.builderClass.name} and ${meta.builderClass.name} on ${where(here)} both ` + `build the ${describe(meta.type, built.name, contextMenuKind(meta))}, and Discord registers one command ` + `per name and type, so only the first would be. Keep one builder, on a single @Command, and declare ` + `the other handlers with CommandType.${meta.type}.`));
                 }
             }
         }
@@ -348,18 +393,21 @@ const quoted = (names)=>names.length < 2 ? names.map((name)=>`"${name}"`).join('
 /**
  * Warns about a handler a subclass re-declares on other routes while it still answers the ones it inherits, for
  * `@Command`, `@MessageHandler`, `@ReactionHandler` and `@Autocomplete` alike. The next major version (5.0) drops
- * the inherited routes. Every class a listed controller extends is checked once, a base that is not listed included.
+ * the inherited routes. Every class a listed controller extends is checked, a base that is not listed included, for
+ * the methods the controller still inherits through it.
  */ function warnInheritedRoutes(controllerClasses) {
-    const checked = new Set();
-    const problems = [];
+    // A set, so a class two listed controllers extend is named once, for the routes either of them still answers
+    const problems = new Set();
     for (const controllerClass of controllerClasses){
+        // Methods a class below re-declares with @Controller({ inheritedRoutes: 'replace' }): the listed controller inherits
+        // nothing of them from above it, so a class above is not named for them
+        const cut = new Set();
         for(let prototype = controllerClass.prototype; prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)){
-            if (checked.has(prototype)) break;
-            checked.add(prototype);
             const declared = controller_decorator.getDeclaredRoutes(prototype);
             const base = Object.getPrototypeOf(prototype);
             if (declared.length === 0 || !base) continue;
-            const inherited = controller_decorator.getHandlerRoutes(base);
+            if (Reflect.getOwnMetadata(controller_decorator.META.replacesInheritedRoutes, prototype)) for (const route of declared)cut.add(route.method);
+            const inherited = controller_decorator.getHandlerRoutes(base).filter((route)=>!cut.has(route.method));
             for (const method of new Set(declared.map((route)=>route.method))){
                 const own = [
                     ...new Set(declared.filter((route)=>route.method === method).map((route)=>route.label))
@@ -369,17 +417,19 @@ const quoted = (names)=>names.length < 2 ? names.map((name)=>`"${name}"`).join('
                 ].filter((label)=>!own.includes(label));
                 if (kept.length === 0) continue;
                 const name = prototype.constructor.name;
-                problems.push(`  ${name}.${method} answers ${controller_decorator.listed(kept)}, which it inherits, as well as its own ${controller_decorator.listed(own)}.`);
+                problems.add(`  ${name}.${method} answers ${controller_decorator.listed(kept)}, which it inherits, as well as its own ${controller_decorator.listed(own)}.`);
             }
         }
     }
-    if (problems.length === 0) return;
-    const one = problems.length === 1;
-    logger.warn(`${problems.length} re-declared ${one ? 'handler still answers routes it inherits' : 'handlers still answer routes they inherit'}:\n` + `${problems.join('\n')}\nIn the next major version (5.0), a handler's own routes replace the ones it inherits. ` + "To keep an inherited route, declare it on the subclass's method as well.");
+    if (problems.size === 0) return;
+    const one = problems.size === 1;
+    logger.warn(`${problems.size} re-declared ${one ? 'handler still answers routes it inherits' : 'handlers still answer routes they inherit'}:\n` + `${[
+        ...problems
+    ].join('\n')}\nIn the next major version (5.0), a handler's own routes replace the ones it inherits. ` + "To keep an inherited route, declare it on the subclass's method as well; to drop it now, give the subclass " + "@Controller({ inheritedRoutes: 'replace' }).");
 }
 /**
- * Warns of customId patterns of one component type that can match one customId, naming the handler that runs and why;
- * an app whose patterns overlap works, so refusing to start would turn a latent mis-route into an outage.
+ * Warns of customId patterns of one component type that rank equally and can match one customId, naming an id both
+ * match and the handler that runs. An app with such a pair works, so it starts; the next major version (5.0) refuses.
  * @throws Error for two handlers whose patterns match the same customIds, which the app refuses as well.
  */ function warnOverlappingPatterns(controllerClasses) {
     const routes = buildComponentRoutes(controllerClasses);
@@ -389,23 +439,16 @@ const quoted = (names)=>names.length < 2 ? names.map((name)=>`"${name}"`).join('
             `${route.meta.type}\0${route.pattern}`,
             route
         ]));
-    const lines = conflicts.map(({ type, patterns: [left, right] })=>{
-        const outcome = ambiguityOutcome(routeOf.get(`${type}\0${left}`), routeOf.get(`${type}\0${right}`));
-        return `  "${left}"  vs  "${right}": ${outcome}`;
-    });
-    logger.warn(`${conflicts.length} pattern pair(s) can match the same customId, so which one runs is decided by ranking rather ` + `than by the ids themselves:\n${lines.join('\n')}`);
-}
-/**
- * Which of two overlapping routes runs for the ids both match, and why: `runs` ranks first. Between equally
- * specific patterns, the order they are listed in decides until 5.0, which prefers the earlier literal segment.
- */ function ambiguityOutcome(runs, other) {
     const name = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.methodName}`;
-    if ((runs.meta.specificity ?? 0) !== (other.meta.specificity ?? 0)) return `${name(runs)} runs, as its pattern is more specific.`;
-    const together = runs.controllerClass === other.controllerClass;
-    const listed = together ? 'it is declared first' : 'its controller is listed first';
-    if (!literalFirst(other.pattern, runs.pattern)) return `${name(runs)} runs, as ${listed}.`;
-    const reorder = together ? `Declare ${name(other)} first` : `List ${other.controllerClass.name} first`;
-    return `${name(runs)} runs, as ${listed}. In the next major version (5.0), ${name(other)} runs instead, as ` + `"${other.pattern}" spells out the first segment where the two differ. ${reorder}, or make the patterns distinct.`;
+    const lines = conflicts.map(({ type, patterns: [left, right], customId })=>{
+        const [runs, other] = [
+            routeOf.get(`${type}\0${left}`),
+            routeOf.get(`${type}\0${right}`)
+        ];
+        const listed = runs.controllerClass === other.controllerClass ? 'it is declared first' : 'its controller is listed first';
+        return `  "${left}"  vs  "${right}", which both match "${customId}": ${name(runs)} runs, as ${listed}.`;
+    });
+    logger.warn(`${conflicts.length} pattern pair(s) rank equally and can match the same customId, so the order they are listed in ` + `decides which one runs:\n${lines.join('\n')}\nMake the patterns distinct: in the next major version (5.0), ` + 'MeoCord refuses to start with such a pair.');
 }
 
 const UNKNOWN_INTERACTION = 10062;
@@ -477,7 +520,10 @@ function errorCode(error) {
         return send(reply.withoutFiles);
     }
 }
-/** The text of a reply to a message, after the call's `emojis.warning` when `withEmoji`. */ const replyText = (text, withEmoji)=>withEmoji ? `${controller_decorator.useTheme().emojis.warning} ${text}` : text;
+/** The text of a reply to a message, after the call's `emojis.warning` when `withEmoji`, cut to fit a message's content. */ function replyText(text, withEmoji) {
+    const emoji = withEmoji ? `${controller_decorator.useTheme().emojis.warning} ` : '';
+    return emoji + controller_decorator.fitText(text, controller_decorator.TEXT_LIMITS.content - emoji.length);
+}
 /**
  * `text`, answering `error` for `message`: plain, after the call's `emojis.warning` when `withEmoji`, unless the
  * presenter's `messageError` draws it as an embed, coloured as an interaction's view is, with that emoji when it has
@@ -485,28 +531,33 @@ function errorCode(error) {
  * the failure comes back with it, for the caller to report once sent.
  */ async function presentedReply(message, error, text, withEmoji, logger) {
     const presenter = controller_decorator.presenterFor(message.client);
+    const translator = controller_decorator.translatorOfClient(message.client);
+    const locale = controller_decorator.messageLocale(message) ?? translator?.defaultLocale ?? 'en-US';
+    // An empty or whitespace-only message, which Discord refuses, reads as MeoCord's generic error text, so neither the plain reply nor a presenter is left without one
+    const shown = text.trim() === '' ? controller_decorator.renderText(translator, locale, {
+        key: 'meocord.fallback.error'
+    }) : text;
     const plain = {
         body: {
-            content: replyText(text, withEmoji)
+            content: replyText(shown, withEmoji)
         }
     };
     const { messageError } = presenter;
     if (!messageError) return plain;
     try {
         const theme = await controller_decorator.themeForInteraction(message);
-        const translator = controller_decorator.translatorOfClient(message.client);
-        const locale = controller_decorator.messageLocale(message) ?? translator?.defaultLocale ?? 'en-US';
         const tone = controller_decorator.isUserOutcome(error, message) ? 'warning' : 'danger';
+        const presented = {
+            message: controller_decorator.fitText(shown, controller_decorator.TEXT_LIMITS.embed),
+            error,
+            tone
+        };
         const drawn = await messageError.call(presenter, {
             message,
             locale,
             mode: 'embed',
             theme
-        }, {
-            message: text,
-            error,
-            tone
-        });
+        }, presented);
         let view = drawn.color === undefined ? {
             ...drawn,
             color: theme.colors.primary
@@ -563,7 +614,8 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
         await sendReply(reply, (body)=>message.reply({
                 ...body,
                 allowedMentions: {
-                    repliedUser: false
+                    repliedUser: false,
+                    parse: []
                 }
             }));
     } catch (replyError) {
@@ -780,6 +832,46 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
     }
 }
 
+/**
+ * The calls an app is running, which shutdown waits for before the `onShutdown` hooks. A call that asks the app to
+ * stop is excused, so a handler awaiting `app.stop()` never waits for itself.
+ */ class RunningCalls {
+    /** Runs `run` as a call named `label`, tracked until it settles. */ run(label, run) {
+        const token = {};
+        this.calls.set(token, label);
+        const done = this.current.run(token, run);
+        const settle = ()=>{
+            this.calls.delete(token);
+            this.notify();
+        };
+        done.then(settle, settle);
+        return done;
+    }
+    /** Excuses the call this runs in, and any it runs within, from the wait; outside a call, nothing. */ excuseCurrent() {
+        const token = this.current.getStore();
+        if (!token || !this.calls.has(token)) return;
+        this.excused.add(token);
+        this.notify();
+    }
+    /** The names of the calls a wait would still wait for. */ running() {
+        return [
+            ...this.calls
+        ].filter(([token])=>!this.excused.has(token)).map(([, label])=>label);
+    }
+    /** Settles once every call not excused has, those that start or are excused meanwhile included. */ async settled() {
+        while(this.running().length > 0)await (this.changed ?? (this.changed = Promise.withResolvers())).promise;
+    }
+    notify() {
+        this.changed?.resolve();
+        this.changed = undefined;
+    }
+    constructor(){
+        this.current = new node_async_hooks.AsyncLocalStorage();
+        /** Each call under way, by its token, with the name a log gives it. */ this.calls = new Map();
+        this.excused = new WeakSet();
+    }
+}
+
 /** The entry of a unit whose instance is `instance`. */ function lifecycleEntry(unit, instance) {
     return {
         name: unit.name,
@@ -791,11 +883,45 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
         }
     };
 }
+/**
+ * The ready hooks' pass, which shutdown waits for before it reads which units to shut down, so a unit whose `onReady`
+ * finishes meanwhile is shut down too. An `onReady` still running that asks the app to stop is not waited for; a timer
+ * or callback an `onReady` that has settled left behind excuses nothing.
+ */ class ReadyPass {
+    /** Runs `pass`, the ready hooks, as the pass shutdown waits for. */ run(pass) {
+        return this.passes.run('onReady', pass);
+    }
+    /** Excuses the pass when this runs within the `onReady` in progress, as one that stops the app does. */ excuseCurrent() {
+        if (this.current && this.hooks.getStore() === this.current) this.passes.excuseCurrent();
+    }
+    /** Settles once the pass has, unless excused. */ settled() {
+        return this.passes.settled();
+    }
+    /** The unit whose `onReady` a wait would still wait for, if any. */ running() {
+        return this.passes.running().length > 0 ? [
+            this.unit ?? 'a unit'
+        ] : [];
+    }
+    constructor(){
+        this.passes = new RunningCalls();
+        /** The `onReady` each async context belongs to. */ this.hooks = new node_async_hooks.AsyncLocalStorage();
+        /** Runs a unit's `onReady` as the one in progress. */ this.runOnReady = async (unit, run)=>{
+            const hook = {};
+            this.current = hook;
+            this.unit = unit.name;
+            try {
+                await this.hooks.run(hook, run);
+            } finally{
+                if (this.current === hook) this.current = undefined;
+            }
+        };
+    }
+}
 /**
  * Resolves each unit and runs its `onReady` one at a time, in the units' dependency order. A failure is
  * reported and the next unit still runs. Each unit whose `onReady` settled, or that has none, is pushed
  * to `entries` as it finishes, so a shutdown that starts meanwhile closes exactly those.
- */ async function runReadyHooks(container, units, client, info, entries, report, { stopped = ()=>false, slowAfterMs, settled } = {}) {
+ */ async function runReadyHooks(container, units, client, info, entries, report, { stopped = ()=>false, slowAfterMs, settled, runOnReady } = {}) {
     const failed = new Set();
     // For each unit, the failed units it depends on, directly or through another dependency
     const failedUpstream = new Map();
@@ -803,6 +929,9 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
             unit.token,
             unit
         ]));
+    // The token each instance was first reached by: one instance two tokens reach, an alias or one value provided twice,
+    // runs its hooks once
+    const firstToken = new Map();
     for (const unit of units){
         if (stopped()) break;
         const upstream = new Set();
@@ -821,9 +950,17 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
             settled?.(unit);
             continue;
         }
+        const first = firstToken.get(instance);
+        if (first !== undefined) {
+            // Failed or not as the token that ran its hooks did, for what depends on this one
+            if (failed.has(first)) failed.add(unit.token);
+            settled?.(unit);
+            continue;
+        }
+        firstToken.set(instance, unit.token);
         const entry = lifecycleEntry(unit, instance);
-        // Only a unit whose onReady has settled, or that has none, is shut down: a stop mid-ready skips
-        // the one still starting, and those not reached yet
+        // Only a unit whose onReady has settled, or that has none, is shut down: a stop mid-ready waits for the one still
+        // starting, within its time, and skips those not reached yet
         if (typeof instance.onReady !== 'function') {
             entries.push(entry);
             settled?.(unit);
@@ -834,7 +971,8 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
         ]);
         const slow = slowAfterMs !== undefined && report.slow ? setTimeout(()=>report.slow(unit), slowAfterMs) : undefined;
         try {
-            await instance.onReady(client, info);
+            const onReady = ()=>instance.onReady(client, info);
+            await (runOnReady ? runOnReady(unit, onReady) : onReady());
         } catch (error) {
             failed.add(unit.token);
             report.hookFailed(unit, error);
@@ -847,12 +985,14 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
 }
 /**
  * Runs the entries' `onShutdown` hooks one at a time, in reverse, so a unit stops before those it
- * depends on. A failure is reported and the next hook still runs.
- */ async function runShutdownHooks(entries, hookFailed) {
+ * depends on. A failure is reported and the next hook still runs. An instance already in `ran` is not shut down again,
+ * so one that two entries reach stops once.
+ */ async function runShutdownHooks(entries, hookFailed, ran = new Set()) {
     for (const { name, instance } of [
         ...entries
     ].reverse()){
-        if (typeof instance.onShutdown !== 'function') continue;
+        if (typeof instance.onShutdown !== 'function' || ran.has(instance)) continue;
+        ran.add(instance);
         try {
             await instance.onShutdown();
         } catch (error) {
@@ -860,54 +1000,91 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
         }
     }
 }
-/**
- * Shuts down the entries there are when it begins, as a bot and a testing module both do. When the cooldown store, or
- * anything it injects directly or through another, has an `onShutdown`, the calls under way finish first, then the
- * store operations they started, so the store's last writes and releases still reach it. The other hooks then run in
- * reverse dependency order, and the store and what it injects last. The whole sequence is waited for at most
- * `timeoutMs`.
- */ async function runShutdownSequence(container, entries, { drainCalls, timeoutMs, hookFailed, warn }) {
-    // A unit whose onReady settles while the calls drain was still starting when shutdown began, so it is not shut down
-    entries = [
-        ...entries
-    ];
-    const byToken = new Map(entries.map((entry)=>[
-            entry.token,
-            entry
-        ]));
-    // The store and everything it reaches through what it injects
-    const storeSide = new Set();
-    const reach = (entry)=>{
-        if (!entry || storeSide.has(entry)) return;
-        storeSide.add(entry);
-        for (const dependency of entry.dependencies)reach(byToken.get(dependency));
-    };
-    for (const entry of entries)if (entry.cooldownStore) reach(entry);
-    const needsStore = [
-        ...storeSide
-    ].some((entry)=>typeof entry.instance.onShutdown === 'function');
-    const sequence = (async ()=>{
-        if (needsStore) {
-            await drainCalls();
-            await providers.storeOperationsSettled(container);
-        }
-        // Nothing on the store's side injects anything outside it, so running it last keeps the reverse dependency order
-        await runShutdownHooks(entries.filter((entry)=>!storeSide.has(entry)), hookFailed);
-        await runShutdownHooks(entries.filter((entry)=>storeSide.has(entry)), hookFailed);
-    })();
+/** The part of `timeoutMs` the drain leaves for the hooks: a quarter, at least 1 s, and never more than half. */ function hooksReserveMs(timeoutMs) {
+    return Math.min(Math.max(timeoutMs / 4, 1000), timeoutMs / 2);
+}
+/** A timer whose promise resolves with `value` after `ms`, and `cancel` to clear it. */ function after(ms, value) {
     let timer;
-    const timedOut = new Promise((resolve)=>{
-        timer = setTimeout(()=>resolve('timeout'), timeoutMs);
+    const promise = new Promise((resolve)=>{
+        timer = setTimeout(()=>resolve(value), ms);
     });
+    return {
+        promise,
+        cancel: ()=>clearTimeout(timer)
+    };
+}
+/**
+ * Shuts down the entries there are once an `onReady` in progress has settled, as a bot and a testing module both do.
+ * The calls under way finish first, on every shutdown with `drainAlways`, and otherwise when the cooldown store, or
+ * anything it injects directly or through another, has an `onShutdown`; then the store operations they started, so the
+ * store's last writes and releases still reach it. The other hooks then run in reverse dependency order, and the store
+ * and what it injects last.
+ *
+ * The whole sequence is waited for at most `timeoutMs`. The wait for the `onReady` and the drain stop early enough to
+ * leave the hooks {@link hooksReserveMs}, with a warning naming what still runs, and the hooks run in the time left.
+ */ async function runShutdownSequence(container, readEntries, { drainCalls, drainAlways = false, runningCalls, readyPass, timeoutMs, hookFailed, warn }) {
+    const whole = after(timeoutMs, 'timeout');
+    const reserve = hooksReserveMs(timeoutMs);
+    const drainEnds = after(timeoutMs - reserve, false);
+    // At once on a shutdown that always drains, so no call starts while an onReady finishes
+    let draining = drainAlways ? drainCalls().then(()=>true) : undefined;
     try {
+        const readying = readyPass?.running() ?? [];
+        if (readying.length > 0 && !await Promise.race([
+            readyPass.settled().then(()=>true),
+            drainEnds.promise
+        ])) {
+            warn(`onReady in ${readying.join(', ')} is still running after ${timeoutMs - reserve} ms; shutting down without waiting for it.`);
+        }
+        // Read once the onReady in progress has settled, so its unit is among them
+        const entries = [
+            ...readEntries()
+        ];
+        const byToken = new Map(entries.map((entry)=>[
+                entry.token,
+                entry
+            ]));
+        // The store and everything it reaches through what it injects
+        const storeSide = new Set();
+        const reach = (entry)=>{
+            if (!entry || storeSide.has(entry)) return;
+            storeSide.add(entry);
+            for (const dependency of entry.dependencies)reach(byToken.get(dependency));
+        };
+        for (const entry of entries)if (entry.cooldownStore) reach(entry);
+        const needsStore = [
+            ...storeSide
+        ].some((entry)=>typeof entry.instance.onShutdown === 'function');
+        let drained = true;
+        if (needsStore) draining ?? (draining = drainCalls().then(()=>true));
+        if (draining) {
+            drained = await Promise.race([
+                draining,
+                drainEnds.promise
+            ]);
+            if (!drained) {
+                const running = runningCalls?.() ?? [];
+                warn(`Calls still running after ${timeoutMs - reserve} ms${running.length > 0 ? `: ${running.join(', ')}` : ''}; ` + `running the onShutdown hooks in the ${reserve} ms left.`);
+            }
+        }
+        drainEnds.cancel();
+        const sequence = (async ()=>{
+            // Only after the calls settled: a call still running may never let its store operations settle
+            if (needsStore && drained) await providers.storeOperationsSettled(container);
+            // Nothing on the store's side injects anything outside it, so running it last keeps the reverse dependency order
+            const ran = new Set();
+            await runShutdownHooks(entries.filter((entry)=>!storeSide.has(entry)), hookFailed, ran);
+            await runShutdownHooks(entries.filter((entry)=>storeSide.has(entry)), hookFailed, ran);
+        })();
         if (await Promise.race([
             sequence,
-            timedOut
+            whole.promise
         ]) === 'timeout') {
             warn(`onShutdown hooks did not finish within ${timeoutMs} ms; shutting down anyway.`);
         }
     } finally{
-        clearTimeout(timer);
+        drainEnds.cancel();
+        whole.cancel();
     }
 }
 /** Settles once every promise in `calls` has, those added while waiting included. */ async function callsSettled(calls) {
@@ -930,7 +1107,7 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
  */ function matchCommandRoute(controllers, interaction) {
     for (const key of commandRouteKeys(interaction)){
         for (const controllerClass of controllers){
-            const meta = controller_decorator.getCommandMap(controllerClass.prototype)?.[key]?.find((each)=>controller_decorator.matchesHandler(each, interaction));
+            const meta = controller_decorator.commandsNamed(controller_decorator.getCommandMap(controllerClass.prototype), key).find((each)=>controller_decorator.matchesHandler(each, interaction));
             if (meta) return {
                 controllerClass,
                 meta
@@ -954,8 +1131,8 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
     for (const [customId, field] of fields){
         const data = field;
         // An upload's `values` are the attachments' ids; discord.js resolves the attachments themselves alongside
-        if (data.type === discord_js.ComponentType.FileUpload) values[customId] = entriesOf(interaction.fields.getUploadedFiles(customId));
-        else values[customId] = 'value' in data ? data.value : data.values;
+        if (data.type === discord_js.ComponentType.FileUpload) controller_decorator.setOwn(values, customId, entriesOf(interaction.fields.getUploadedFiles(customId)));
+        else controller_decorator.setOwn(values, customId, 'value' in data ? data.value : data.values);
     }
     return values;
 }
@@ -1014,7 +1191,7 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
         collisions: []
     };
     const fields = interaction instanceof discord_js.ModalSubmitInteraction ? modalFields(interaction) : selectChoices(interaction);
-    const collisions = Object.keys(routeParams).filter((name)=>name in fields);
+    const collisions = Object.keys(routeParams).filter((name)=>Object.hasOwn(fields, name));
     return {
         params: {
             ...fields,
@@ -1100,6 +1277,7 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
     if (state && state !== 'unanswered') return true;
     return 'replied' in interaction && (interaction.replied || interaction.deferred);
 }
+/** How long a message's handler may take, with others waiting after it, before it is named as slow. */ const SLOW_HANDLER_MS = 5000;
 /**
  * Routes interactions, messages and reactions to the handlers that take them, as the bot does, and runs
  * each through its pipeline. The app and the testing module share it, so a test routes exactly as the bot.
@@ -1355,22 +1533,64 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
                 message
             ], error, this.runOptions(call));
         }
+        // The matched handler, then every listener, each resolved from the container only as it starts
+        const runs = [];
         if (target) {
             const { route, params, start, given } = target;
             noteInvocation(message, `${start}${providers.commandWordsOf(route.tokens).join(' ')}`);
             const hooks = providers.messageCommandHooks(route, params, message, start, given, this.messageOptions.types);
-            await this.invokeHandler(this.getInstance(route.controllerClass), route.method, [
-                message,
-                params
-            ], call, hooks);
+            runs.push({
+                name: `${route.controllerClass.name}.${route.method}`,
+                run: (at)=>this.invokeHandler(this.getInstance(route.controllerClass), route.method, [
+                        message,
+                        params
+                    ], at, hooks)
+            });
         }
         for (const { controllerClass, method } of this.messageListeners){
-            await this.invokeHandler(this.getInstance(controllerClass), method, [
-                message
-            ], call);
+            runs.push({
+                name: `${controllerClass.name}.${method}`,
+                run: (at)=>this.invokeHandler(this.getInstance(controllerClass), method, [
+                        message
+                    ], at)
+            });
+        }
+        if (this.messageOptions.handlers === 'concurrent') await this.runTogether(runs, call);
+        else await this.runInTurn(runs, call);
+    }
+    /** Runs a message's handlers one after another, warning once about one that held the rest back for long. */ async runInTurn(runs, call) {
+        const warn = this.messageOptions.slowHandlerWarning ?? this.options.warnSlowMessageHandlers ?? true;
+        for (const [index, { name, run }] of runs.entries()){
+            const started = performance.now();
+            await run(call);
+            const waiting = runs.length - 1 - index;
+            if (warn && waiting > 0) this.warnSlowOnce(name, performance.now() - started, waiting);
         }
     }
     /**
+   * Starts a message's handlers together and settles once all have. Each is reported as settled in the order the
+   * handlers are listed, whichever settles first, and a call that rejects, rejects this once every one has settled.
+   */ async runTogether(runs, call) {
+        const { record } = call;
+        const reports = runs.map(()=>[]);
+        const results = await Promise.allSettled(runs.map(({ run }, index)=>run(record ? {
+                ...call,
+                record: {
+                    settled: (...report)=>reports[index].push(report),
+                    unhandled: (error)=>record.unhandled(error)
+                }
+            } : call)));
+        for (const report of reports.flat())record?.settled(...report);
+        const failed = results.find((result)=>result.status === 'rejected');
+        if (failed) throw failed.reason;
+    }
+    /** Warns, once per handler, that it took `SLOW_HANDLER_MS` or longer with `waiting` handlers held back behind it. */ warnSlowOnce(name, took, waiting) {
+        if (took < SLOW_HANDLER_MS || this.warnedSlow.has(name)) return;
+        this.warnedSlow.add(name);
+        const held = waiting === 1 ? 'the listener after it' : `the ${waiting} listeners after it`;
+        this.logger.warn(`${name} took ${(took / 1000).toFixed(1)} s on a message, and held back ${held}. ` + "@MeoCord({ messages: { handlers: 'concurrent' } }) runs them side by side; messages: { slowHandlerWarning: false } turns this off.");
+    }
+    /**
    * Answers a message that asks the built-in help, when `messages.help` is on and no handler took the message:
    * through the presenter's `messageHelp` when it has one, else in plain text, once the app's guards allow it.
    * `known` is the message's starts when they hold the app's prefixes already. Whether it answered, or a
@@ -1491,6 +1711,7 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
         this.controllerInstancesCache = new Map();
         /** Handler and name pairs already warned about, so a collision warns once, not on every submit or selection. */ this.warnedCollisions = new Set();
         /** The handlers already warned about, so each is named once however often it runs. */ this.warnedUnanswered = new Set();
+        /** The message handlers already warned about as slow, so each is named once. */ this.warnedSlow = new Set();
         this.container = options.container;
         this.controllerClasses = options.controllerClasses;
         this.messageOptions = options.messageOptions ?? {};
@@ -1582,6 +1803,24 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
         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$1, seen = new Set()) {
+    seen.add(cls);
+    return providers.injectedTokens(cls).some((token)=>token === controller_decorator.ExecutionContext || providers.isAppClassToken(token) && !providers$1.has(token) && !seen.has(token) && reachesContext(token, providers$1, 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$1, presenter) {
+    const stages = [
+        ...decorators
+    ].filter(([, decorator])=>decorator !== '@Controller()').map(([stage])=>stage);
+    if (typeof presenter === 'function') stages.push(presenter);
+    return [
+        ...new Set(stages.flatMap((stage)=>providers.injectedTokens(stage)))
+    ].filter(providers.isAppClassToken).filter((cls)=>!reachesContext(cls, providers$1));
+}
 /** 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$1, translator) {
     return (guard)=>assertStartupClasses({
             classes: providers.reachableClasses([
@@ -1600,12 +1839,13 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
 /** 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 }) {
     providers.assertTypedParameters(classes, decorators);
     if (translator) return;
-    const needsOne = classes.find((cls)=>providers.injectedTokens(cls).includes(controller_decorator.Translator));
-    if (needsOne) throw controller_decorator.refuse(controller_decorator.missingTranslatorError(needsOne));
+    for (const needsOne of classes.filter((cls)=>providers.injectedTokens(cls).includes(controller_decorator.Translator)))controller_decorator.startupError(controller_decorator.missingTranslatorError(needsOne));
 }
 
 exports.DEFAULT_SHUTDOWN_TIMEOUT_MS = DEFAULT_SHUTDOWN_TIMEOUT_MS;
 exports.Dispatcher = Dispatcher;
+exports.ReadyPass = ReadyPass;
+exports.RunningCalls = RunningCalls;
 exports.SHUTDOWN_MARGIN_MS = SHUTDOWN_MARGIN_MS;
 exports.assertDistinctCommands = assertDistinctCommands;
 exports.assertStartupClasses = assertStartupClasses;
@@ -1622,11 +1862,13 @@ exports.matchComponentRoute = matchComponentRoute;
 exports.messageDecorator = messageDecorator;
 exports.ownInteractionListener = ownInteractionListener;
 exports.reactionDecorator = reactionDecorator;
+exports.readCustomId = readCustomId;
 exports.replyWithUserError = replyWithUserError;
 exports.runReadyHooks = runReadyHooks;
 exports.runShutdownSequence = runShutdownSequence;
 exports.shutdownTimeoutOf = shutdownTimeoutOf;
 exports.shutdownTimeoutProblem = shutdownTimeoutProblem;
+exports.stageDependencies = stageDependencies;
 exports.startupClasses = startupClasses;
 exports.warnHandlersOffControllers = warnHandlersOffControllers;
 exports.warnInheritedRoutes = warnInheritedRoutes;