meocord 4.2.0 → 4.2.2

package/dist/esm/core/meocord.app.js

@@ -5,18 +5,15 @@ import './theme-scope.js';
 import './theme-validation.js';
 import '../common/decorator.js';
 import 'reflect-metadata';
+import '../common/response/response-state.js';
 import { GuardDeniedError, UserError } from '../common/errors.js';
-import '../common/translator.js';
-import '../common/response/send-failure.js';
-import '../util/interaction.util.js';
-import '../common/response/flags.js';
-import 'path';
-import '../common/response/components.js';
 import 'node:crypto';
 import { getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
 import './scalar-types.js';
 import { isShardMessage } from './shard-messages.js';
 import { managerGone } from '../util/sharding-mode.util.js';
+import '../common/translator.js';
+import '../common/meocord-text.js';
 import { markExplained } from '../common/explained-error.js';
 import { messageDecorator, reactionDecorator } from './command-conflicts.js';
 import { ReactionHandlerAction } from '../enum/controller.enum.js';
@@ -27,7 +24,8 @@ import { stageTypes, stageClass } from './stage-scope.js';
 import { getEventHandlers } from '../decorator/event.decorator.js';
 import { eventRequirements, messageHandlerRequirements, REACTION_HANDLER_REQUIREMENTS, missingRequirementWarnings } from './event-requirements.js';
 import { classUnits } from './lifecycle-order.js';
-import { runReadyHooks, runShutdownSequence, callsSettled } from './lifecycle-hooks.js';
+import { runReadyHooks, runShutdownSequence, ReadyPass } from './lifecycle-hooks.js';
+import { RunningCalls } from './running-calls.js';
 import { stopRequests } from '../util/stop-request.util.js';
 import { tellDevRunner, onDevRunnerStop } from '../util/dev-runner.util.js';
 import { fatalLoginCode, explainLoginFailure, tokenMessage, isRefusedToken } from './login-failure.js';
@@ -41,7 +39,6 @@ import { loadMeoCordConfig } from '../util/meocord-config-loader.util.js';
 import { isRegisterOnly, FORCE_REGISTER_ENV, REGISTER_GUILD_ENV } from '../util/registration-mode.util.js';
 import { shutdownTimeoutOf } from '../util/shutdown-timeout.util.js';
 import { escapeForLog } from '../util/user-text.util.js';
-import { isShardProcess } from '../util/shard-process.util.js';
 
 /** How long an `onReady` hook runs before a warning says the hooks after it are waiting. */ const SLOW_READY_HOOK_MS = 10000;
 /** Closes each started app: runs its shutdown hooks and destroys its client, resolving `false` on failure. */ const runningApps = new Set();
@@ -52,11 +49,11 @@ let shuttingDown;
  * Shuts every started app down and exits, with a code already set or 0, and 1 if a client failed to close. Signals call
  * it, and in a shard its manager's request or its going. A call within `REPEAT_SIGNAL_WINDOW_MS` of the first is the
  * same request; one after it forces exit 1, except in a shard, whose manager forces it.
- */ async function shutdownAndExit() {
+ */ async function shutdownAndExit(shard) {
     const request = stopRequest();
     if (request !== 'first') {
         // A shard hears Ctrl+C both directly and from its manager, which owns forcing it; so it waits
-        if (request === 'duplicate' || isShardProcess()) return;
+        if (request === 'duplicate' || shard) return;
         process.exit(1);
         return;
     }
@@ -77,47 +74,48 @@ let shuttingDown;
     markExplained(error);
     return error;
 }
-/** One pair of signal listeners for the process, however many apps it starts. */ function installSignalHandlers() {
+/** One pair of signal listeners for the process, however many apps it starts, for the role the first decided. */ function installSignalHandlers(shard) {
     if (signalHandlersInstalled) return;
     signalHandlersInstalled = true;
-    process.on('SIGINT', ()=>void shutdownAndExit());
-    process.on('SIGTERM', ()=>void shutdownAndExit());
+    process.on('SIGINT', ()=>void shutdownAndExit(shard));
+    process.on('SIGTERM', ()=>void shutdownAndExit(shard));
     // How `meocord start --dev` stops the application to restart it, a signal being no graceful stop on Windows. It is
     // not the user's stop request: their first Ctrl+C during it joins this shutdown, and only a repeat forces exit 1.
-    onDevRunnerStop(()=>void shutDown());
+    onDevRunnerStop(()=>void shutDown(), shard);
     // A shard stops when its manager asks, or when the manager is gone and cannot ask
-    if (isShardProcess()) {
+    if (shard) {
         process.on('message', (message)=>{
-            if (isShardMessage(message) && message.meocord === 'shutdown') void shutdownAndExit();
+            if (isShardMessage(message) && message.meocord === 'shutdown') void shutdownAndExit(shard);
         });
-        process.on('disconnect', ()=>void shutdownAndExit());
+        process.on('disconnect', ()=>void shutdownAndExit(shard));
     }
 }
-/** Tells the manager a shard cannot log in, and why, and waits until the message is sent. */ async function reportFatalLogin(code, reason) {
-    if (isShardProcess()) await tellManager({
+/** Tells the manager a shard cannot log in, and why, and waits until the message is sent. */ async function reportFatalLogin(shard, code, reason) {
+    if (shard) await tellManager({
         meocord: 'fatal',
         code,
         message: reason
     });
 }
+/** How a shutdown warning names an interaction still being handled: by its command, or a component's customId. */ function interactionLabel(interaction) {
+    if ('commandName' in interaction) return `interaction "/${escapeForLog(interaction.commandName)}"`;
+    if ('customId' in interaction) return `interaction "${escapeForLog(interaction.customId)}"`;
+    return '"interactionCreate"';
+}
 class MeoCordApp {
     /**
    * Runs an event handler so its failure is logged against the event instead of surfacing as an
    * unhandled rejection, which would terminate the whole bot.
-   */ async runListener(event, run) {
-        const handled = (async ()=>{
+   */ async runListener(event, run, label = `"${event}"`) {
+        const handle = async ()=>{
             try {
                 await run();
             } catch (error) {
                 this.logger.error(`Unhandled error while handling "${event}":`, error);
             }
-        })();
-        // A call, which the cooldown store outlasts at shutdown; the ready listener's work is not one
-        if (event !== 'clientReady') {
-            this.calls.add(handled);
-            void handled.then(()=>this.calls.delete(handled));
-        }
-        await handled;
+        };
+        // A call, which shutdown waits for before the onShutdown hooks; the ready listener's work is not one
+        await (event === 'clientReady' ? handle() : this.calls.run(label, handle));
     }
     /**
    * Shows the next of the app's activities, in the order listed, starting again after the last. Guarded apart from
@@ -139,7 +137,7 @@ class MeoCordApp {
         if (this.online) return;
         this.starting ?? (this.starting = this.startOnce().catch((error)=>{
             // A shard ends, for its manager to restart, or to stop all if told it is fatal; a stopped start is the stop's
-            if (isShardProcess() && !this.closing) endFailedShard(error);
+            if (this.shard && !this.closing) endFailedShard(error);
             throw error;
         }).finally(()=>this.starting = undefined));
         return this.starting;
@@ -149,7 +147,10 @@ class MeoCordApp {
    * which then asks this one too, so the process ends. A client that fails to close sets `process.exitCode` to 1,
    * unless a code is already set.
    */ async stop() {
-        if (isShardProcess()) await tellManager({
+        // A handler or an onReady awaiting stop() would otherwise hold up the shutdown that waits for it
+        this.calls.excuseCurrent();
+        this.readyPass.excuseCurrent();
+        if (this.shard) await tellManager({
             meocord: 'stop'
         });
         // As a signal's shutdown exits 1 for a client that failed to close, a code another failure set aside
@@ -159,14 +160,20 @@ class MeoCordApp {
         this.logger.log('Starting bot...');
         // Before the providers are made, so a signal, or a shard's manager, can stop a start that is slow to come online
         runningApps.add(this.close);
-        installSignalHandlers();
+        installSignalHandlers(this.shard);
         // A shard whose manager is already gone has no one to answer to, and nothing would stop it later
-        if (isShardProcess() && managerGone()) void shutdownAndExit();
+        if (this.shard && managerGone()) void shutdownAndExit(this.shard);
         // A bot runs one app, whose theme code outside any call reads, its providers' factories included; claimed for
         // each start, as a failed one gives it up
         claimAmbientAppTheme(this.container);
         if (!this.prepared) {
-            await this.prepare();
+            // Kept while it runs, so a stop meanwhile waits for it
+            this.preparing = this.prepare();
+            try {
+                await this.preparing;
+            } finally{
+                this.preparing = undefined;
+            }
             this.prepared = true;
         }
         if (this.loginFailed) {
@@ -179,7 +186,10 @@ class MeoCordApp {
         // Every provided value is made before anything that injects it is resolved, and before login
         if (this.startup) {
             try {
-                await this.startup();
+                await this.startup({
+                    stopped: ()=>this.closing,
+                    pending: (name)=>this.pendingProvider = name
+                });
             } catch (error) {
                 releaseAmbientAppTheme(this.container);
                 if (process.exitCode === undefined || process.exitCode === 0) {
@@ -189,7 +199,8 @@ class MeoCordApp {
                 throw error;
             }
         }
-        // A stop that came while the providers were being made has nothing to close: nothing is attached or logged in
+        // A stop that came while the providers were being made has waited for them, and the startup made no more after it;
+        // nothing is attached or logged in
         if (this.closing) throw stoppedBeforeOnline();
         // Calls wait for the store's onReady, which may connect it, before asking it
         if (this.lifecycleUnits.some((unit)=>unit.cooldownStore)) {
@@ -205,10 +216,10 @@ class MeoCordApp {
                 // Started before registration and not waited on by it, so a slow or failed registration never holds them up
                 const readyHooks = this.runReadyHooks(readyClient ?? this.bot);
                 // With process sharding, the manager registers once for every shard
-                if (!isShardProcess()) await this.registerCommands();
+                if (!this.shard) await this.registerCommands();
                 await readyHooks;
             }));
-        this.bot.on('interactionCreate', ownInteractionListener((interaction)=>this.runListener('interactionCreate', ()=>this.dispatcher.interaction(interaction))));
+        this.bot.on('interactionCreate', ownInteractionListener((interaction)=>this.runListener('interactionCreate', ()=>this.dispatcher.interaction(interaction), interactionLabel(interaction))));
         this.bot.on('messageCreate', (message)=>this.runListener('messageCreate', ()=>this.dispatcher.message(message)));
         this.bot.on('messageReactionAdd', (reaction, user)=>this.runListener('messageReactionAdd', ()=>this.dispatcher.reaction(reaction, {
                     user,
@@ -251,18 +262,18 @@ class MeoCordApp {
             const explanation = fatal && explainLoginFailure(fatal, this.bot.options?.intents, this.discordToken);
             if (explanation) {
                 // The explanation is what to act on, and the stack only for debugging. A shard's manager logs it instead.
-                if (!isShardProcess()) this.logger.error(explanation);
+                if (!this.shard) this.logger.error(explanation);
                 this.logger.debug('Login failed:', error);
                 markExplained(error);
             }
-            if (fatal) await reportFatalLogin(fatal, explanation ?? (error instanceof Error ? error.message : String(error)));
+            if (fatal) await reportFatalLogin(this.shard, fatal, explanation ?? (error instanceof Error ? error.message : String(error)));
             if (process.exitCode === undefined || process.exitCode === 0) {
                 process.exitCode = 1;
                 MeoCordApp.failedLoginSetExitCode = true;
             }
             await tellDevRunner({
                 meocord: 'login-failed'
-            });
+            }, this.shard);
             MeoCordApp.toldDevRunnerLoginFailed = true;
             this.loginFailed = true;
             throw error;
@@ -280,7 +291,7 @@ class MeoCordApp {
             MeoCordApp.toldDevRunnerLoginFailed = false;
             await tellDevRunner({
                 meocord: 'online'
-            });
+            }, this.shard);
         }
         this.online = true;
         this.logger.log('Bot is online!');
@@ -363,18 +374,20 @@ class MeoCordApp {
                     } else logError(error);
                     return undefined;
                 };
-                const listener = async (...args)=>{
-                    try {
-                        const instance = this.container.get(lifecycleClass);
-                        await runHandler(this.container, instance, method, args, {
-                            fallback,
-                            type: 'event'
-                        });
-                    } catch (error) {
-                        // Only resolving the instance can fail here; the pipeline hands every other error to the fallback
-                        logError(error);
-                    }
-                };
+                const label = `@${once ? 'Once' : 'On'}('${event}') in ${lifecycleClass.name}.${method}`;
+                // A call, as a dispatched one is, which shutdown waits for
+                const listener = (...args)=>this.calls.run(label, async ()=>{
+                        try {
+                            const instance = this.container.get(lifecycleClass);
+                            await runHandler(this.container, instance, method, args, {
+                                fallback,
+                                type: 'event'
+                            });
+                        } catch (error) {
+                            // Only resolving the instance can fail here; the pipeline hands every other error to the fallback
+                            logError(error);
+                        }
+                    });
                 if (once) this.bot.once(event, listener);
                 else this.bot.on(event, listener);
             }
@@ -443,29 +456,35 @@ class MeoCordApp {
    */ async runReadyHooks(client) {
         const entries = [];
         this.lifecycleEntries = entries;
-        await runReadyHooks(this.container, this.lifecycleUnits, client, {
-            primary: client.shard ? client.shard.ids.includes(0) : true
-        }, entries, {
-            resolveFailed: (unit, error)=>this.logger.error(`Could not resolve ${unit.name} to run its lifecycle hooks:`, error),
-            hookFailed: (unit, error)=>this.logger.error(`onReady failed in ${unit.name}:`, error),
-            dependsOnFailed: (unit, failed)=>this.logger.warn(`Running onReady in ${unit.name} although it depends on ${failed.map(({ name })=>name).join(', ')}, which failed.`),
-            slow: (unit)=>this.logger.warn(`onReady in ${unit.name} has run for over ${SLOW_READY_HOOK_MS} ms; the hooks after it are waiting.`)
-        }, // Shutdown has begun: the client is going away, so no further hook starts
-        {
-            stopped: ()=>this.closing,
-            slowAfterMs: SLOW_READY_HOOK_MS,
-            settled: (unit)=>unit.cooldownStore && this.storeReady?.resolve()
-        });
+        await this.readyPass.run(()=>runReadyHooks(this.container, this.lifecycleUnits, client, {
+                primary: client.shard ? client.shard.ids.includes(0) : true
+            }, entries, {
+                resolveFailed: (unit, error)=>this.logger.error(`Could not resolve ${unit.name} to run its lifecycle hooks:`, error),
+                hookFailed: (unit, error)=>this.logger.error(`onReady failed in ${unit.name}:`, error),
+                dependsOnFailed: (unit, failed)=>this.logger.warn(`Running onReady in ${unit.name} although it depends on ${failed.map(({ name })=>name).join(', ')}, which failed.`),
+                slow: (unit)=>this.logger.warn(`onReady in ${unit.name} has run for over ${SLOW_READY_HOOK_MS} ms; the hooks after it are waiting.`)
+            }, // Shutdown has begun: the client is going away, so no further hook starts
+            {
+                stopped: ()=>this.closing,
+                slowAfterMs: SLOW_READY_HOOK_MS,
+                settled: (unit)=>unit.cooldownStore && this.storeReady?.resolve(),
+                runOnReady: this.readyPass.runOnReady
+            }));
         // Also when shutdown stopped the hooks before the store's, so no call waits on it
         this.storeReady?.resolve();
     }
-    /** Runs the `onShutdown` hooks through the shutdown sequence, within the configured `shutdownTimeout`. */ async runShutdownHooks(entries) {
-        await runShutdownSequence(this.container, entries, {
-            // No new call starts once the listeners are gone
+    /** Runs the `onShutdown` hooks through the shutdown sequence, within the configured `shutdownTimeout`. */ async runShutdownHooks() {
+        // Read once the onReady in progress settled; a login that failed never ran onReady, so there is no onShutdown to undo
+        await runShutdownSequence(this.container, ()=>this.lifecycleEntries ?? [], {
+            // No new call starts once the listeners are gone; an error the client emits meanwhile still has its listeners
             drainCalls: ()=>{
-                this.bot.removeAllListeners();
-                return callsSettled(this.calls);
+                const emitter = this.bot;
+                for (const event of emitter.eventNames())if (event !== 'error') emitter.removeAllListeners(event);
+                return this.calls.settled();
             },
+            drainAlways: true,
+            runningCalls: ()=>this.calls.running(),
+            readyPass: this.readyPass,
             timeoutMs: this.shutdownTimeout,
             hookFailed: (name, error)=>this.logger.error(`onShutdown failed in ${name}:`, error),
             warn: (message)=>this.logger.warn(message)
@@ -484,8 +503,28 @@ class MeoCordApp {
             releaseAmbientAppTheme(this.container);
         }
     }
+    /**
+   * Waits for the startup under way to stop making providers and services, at most `shutdownTimeout`; past it, warns
+   * with the factory it still awaits, which then makes nothing more.
+   */ async waitForStartup(preparing) {
+        let timer;
+        const outlasted = new Promise((resolve)=>{
+            timer = setTimeout(()=>resolve(true), this.shutdownTimeout);
+        });
+        const settled = preparing.then(()=>false, ()=>false);
+        if (await Promise.race([
+            settled,
+            outlasted
+        ])) {
+            const what = this.pendingProvider ? `the factory providing ${this.pendingProvider}` : 'its providers';
+            this.logger.warn(`The startup still waits for ${what} after ${this.shutdownTimeout} ms; shutting down without it.`);
+        }
+        clearTimeout(timer);
+    }
     async shutDownClient() {
         this.logger.log('Shutting down bot...');
+        // So nothing is made after the bot has shut down
+        if (this.preparing) await this.waitForStartup(this.preparing);
         // Nothing came online, so there are no hooks to undo; the listeners go first, so none of them runs
         if (this.abortLogin) {
             this.logger.log('The bot was still logging in, so it stops without coming online');
@@ -495,8 +534,8 @@ class MeoCordApp {
             return true;
         }
         if (this.activityInterval) clearInterval(this.activityInterval);
-        // A login that failed never ran onReady, so there is nothing for onShutdown to undo
-        if (this.lifecycleEntries) await this.runShutdownHooks(this.lifecycleEntries);
+        // The calls drain on every shutdown, and the onReady in progress settles first
+        await this.runShutdownHooks();
         try {
             this.bot.removeAllListeners();
             await this.bot.destroy();
@@ -507,7 +546,7 @@ class MeoCordApp {
             return false;
         }
     }
-    constructor(controllerClasses, container, discordClient, discordToken, activities, lifecycleClasses = [], shutdownTimeout, startup, lifecycleUnits, messageOptions = {}, warnUnanswered = false){
+    constructor(controllerClasses, container, discordClient, discordToken, activities, lifecycleClasses = [], shutdownTimeout, startup, lifecycleUnits, messageOptions = {}, warnUnanswered = false, /** Whether a manager spawned this process, as `MeoCordFactory.create` decided before anything could change it. */ shard = false){
         this.controllerClasses = controllerClasses;
         this.container = container;
         this.discordClient = discordClient;
@@ -516,6 +555,7 @@ class MeoCordApp {
         this.lifecycleClasses = lifecycleClasses;
         this.startup = startup;
         this.messageOptions = messageOptions;
+        this.shard = shard;
         this.logger = new Logger(MeoCordApp.name);
         this.fallback = createFallback(this.logger, ()=>this.messageOptions, {
             cooldownNotice: (refusal)=>claimCooldownNotice(this.container, refusal),
@@ -528,7 +568,8 @@ class MeoCordApp {
    * Closes the app once, however many stops and signals ask: whether the client was destroyed cleanly. The app stays
    * among the running ones until the close settles, so a signal or a manager's request meanwhile waits for it.
    */ this.close = ()=>this.stopped ?? (this.stopped = this.closeClient().finally(()=>runningApps.delete(this.close)));
-        /** The calls under way, each settling once its handling has. */ this.calls = new Set();
+        /** The calls under way, which shutdown waits for, less one that asked the app to stop. */ this.calls = new RunningCalls();
+        /** The ready hooks' pass, whose `onReady` in progress shutdown waits for, less one that asked the app to stop. */ this.readyPass = new ReadyPass();
         /** Whether the providers, services and event handlers are set up, which a retry after a failed login reuses. */ this.prepared = false;
         /** Whether the bot logged in, after which `start()` has nothing to do. */ this.online = false;
         /** Whether a login of this app failed, so a retry restores the client discord.js destroyed. */ this.loginFailed = false;

package/dist/esm/core/message-help.js

@@ -249,22 +249,48 @@ const sortedEntries = (entries)=>entries.sort((a, b)=>a.usage < b.usage ? -1 : a
         scope
     ].filter((line)=>line !== undefined).join('\n');
 }
-/** Splits a reply into Discord-sized messages at line breaks, a line longer than one message cut where it must be. */ function splitReply(text) {
+// Built on first use, for a line longer than a message
+let graphemes;
+/**
+ * Where a line longer than one message is cut: after the last character a reader sees as one, such as an emoji, a flag
+ * or a letter with its accent, that still fits. A single such character longer than a message is cut between code points.
+ */ function fittingCut(piece) {
+    let cut = 0;
+    graphemes ?? (graphemes = new Intl.Segmenter(undefined, {
+        granularity: 'grapheme'
+    }));
+    for (const { index, segment } of graphemes.segment(piece)){
+        if (index + segment.length > MAX_REPLY_LENGTH) break;
+        cut = index + segment.length;
+    }
+    if (cut > 0) return cut;
+    const high = piece.charCodeAt(MAX_REPLY_LENGTH - 1);
+    return high >= 0xd800 && high <= 0xdbff ? MAX_REPLY_LENGTH - 1 : MAX_REPLY_LENGTH;
+}
+/**
+ * Splits a reply into Discord-sized messages at line breaks, a line longer than one message cut where it must be. A
+ * message of only whitespace, which Discord refuses as empty, is left out.
+ */ function splitReply(text) {
     const chunks = [];
+    const push = (chunk)=>{
+        if (chunk.trim() !== '') chunks.push(chunk);
+    };
     let current = '';
     for (const line of text.split('\n')){
-        for(let piece = line;; piece = piece.slice(MAX_REPLY_LENGTH)){
-            const part = piece.slice(0, MAX_REPLY_LENGTH);
+        for(let piece = line;;){
+            const cut = piece.length <= MAX_REPLY_LENGTH ? piece.length : fittingCut(piece);
+            const part = piece.slice(0, cut);
             const joined = current ? `${current}\n${part}` : part;
             if (joined.length <= MAX_REPLY_LENGTH) current = joined;
             else {
-                chunks.push(current);
+                push(current);
                 current = part;
             }
-            if (piece.length <= MAX_REPLY_LENGTH) break;
+            if (cut === piece.length) break;
+            piece = piece.slice(cut);
         }
     }
-    if (current) chunks.push(current);
+    push(current);
     return chunks;
 }
 

package/dist/esm/core/observer-runner.js

@@ -5,6 +5,7 @@ import { bindShared } from './interceptor-runner.js';
 import { appliesTo } from './stage-scope.js';
 import { respond } from '../common/response/response-state.js';
 import { startupError } from '../util/refusal.util.js';
+import { isConstructor } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
 
 /** Where a container keeps the observers its calls are reported to, in order. */ const OBSERVERS = Symbol('observers');
@@ -12,7 +13,7 @@ const logger = new Logger('Observer');
 /** Reports each entry that is not an `@Observer` class, naming where it was listed. */ function assertObservers(where, observers) {
     for (const observer of observers){
         if (typeof observer !== 'function' || !Reflect.getMetadata(META.observerClass, observer)) {
-            const name = typeof observer === 'function' ? observer.name : String(observer);
+            const name = isConstructor(observer) ? observer.name || 'an anonymous class' : typeof observer === 'function' ? 'a function' : String(observer);
             startupError(new Error(`${where} takes classes decorated with @Observer(), not ${name}.`));
             continue;
         }

package/dist/esm/core/providers.js

@@ -4,6 +4,7 @@ import { meocordClasses, meocordClassAdvice } from './meocord-classes.js';
 import { isAppClassToken } from './lifecycle-order.js';
 import { makeInjectable } from '../util/injectable.util.js';
 import { startupError, refuse } from '../util/refusal.util.js';
+import { isConstructor } from '../util/value.util.js';
 
 const isValueProvider = (provider)=>'useValue' in provider;
 const isClassProvider = (provider)=>'useClass' in provider;
@@ -43,7 +44,7 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
             startupError(new Error(`${where}: the provider for ${name} needs exactly one of useValue, useClass and useFactory.`));
             continue;
         }
-        if ('useClass' in entry && typeof entry.useClass !== 'function') {
+        if ('useClass' in entry && !isConstructor(entry.useClass)) {
             startupError(new Error(`${where}: the provider for ${name} has a useClass that is not a class.`));
             continue;
         }
@@ -120,6 +121,15 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
     });
     for (const dependency of inject)if (isAppClassToken(dependency)) bindClass(dependency);
 }
+/**
+ * Reports each service listed by a string or symbol token that no provider provides, which would otherwise be bound
+ * as if it were a class.
+ */ function assertProvidedServices(appName, services, providers, where) {
+    for (const service of services){
+        if (typeof service === 'function' || providers.has(service)) continue;
+        startupError(new Error(`${appName}: @MeoCord({ services }) lists ${tokenName(service)}, which nothing provides: add a provider for it to ${where}.`));
+    }
+}
 /**
  * Reports a class or a factory that asks for a string or symbol token nothing binds, naming both, rather than failing
  * when the class is first resolved. A class token is bound on demand, so it is never missing.
@@ -253,17 +263,22 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
 }
 /**
  * Runs every factory in `order`, awaiting those that return a promise, so each value is made before
- * anything that injects it is resolved. Rejects with {@link providerFailure} for the first that fails.
- */ async function resolveProviders(container, providers, order) {
+ * anything that injects it is resolved. Rejects with {@link providerFailure} for the first that fails. With `control`,
+ * it makes no further value once the app is stopping.
+ */ async function resolveProviders(container, providers, order, control) {
     for (const token of order){
         const provider = providers.get(token);
         if (!provider || !isFactoryProvider(provider)) continue;
+        if (control?.stopped()) return;
+        control?.pending(tokenName(token));
         try {
             await container.getAsync(token);
         } catch (error) {
             throw providerFailure(token, error);
+        } finally{
+            control?.pending(undefined);
         }
     }
 }
 
-export { assertProvided, assertTypedParameters, bindProvider, bindsOwnToken, isClassProvider, isFactoryProvider, isValueProvider, providerFailure, providerMap, reachableClasses, resolutionOrder, resolveProviders, tokenDependencies, tokenName };
+export { assertProvided, assertProvidedServices, assertTypedParameters, bindProvider, bindsOwnToken, isClassProvider, isFactoryProvider, isValueProvider, providerFailure, providerMap, reachableClasses, resolutionOrder, resolveProviders, tokenDependencies, tokenName };

package/dist/esm/core/running-calls.js

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * 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 AsyncLocalStorage();
+        /** Each call under way, by its token, with the name a log gives it. */ this.calls = new Map();
+        this.excused = new WeakSet();
+    }
+}
+
+export { RunningCalls };

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

@@ -5,16 +5,15 @@ import './theme-validation.js';
 import '../common/decorator.js';
 import 'reflect-metadata';
 import 'discord.js';
-import '../common/translator.js';
-import '../common/response/send-failure.js';
-import '../util/interaction.util.js';
-import '../common/response/flags.js';
-import 'path';
-import '../common/response/components.js';
+import '../common/response/response-state.js';
+import '../common/errors.js';
 import '../decorator/controller.decorator.js';
 import './scalar-types.js';
+import 'path';
 import 'node:fs';
 import 'node:url';
+import '../common/translator.js';
+import '../common/meocord-text.js';
 
 /** Where each shard's client keeps the function that runs a `ShardContext.call` in that shard. */ const SHARD_CALL_KEY = Symbol.for('meocord.shardCall');
 const packArgs = (args)=>Object.assign({