meocord 4.2.0 → 4.2.1

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

@@ -1,10 +1,11 @@
 'use strict';
 
 var discord_js = require('discord.js');
-var controller_decorator = require('./controller.decorator-CRn9kWob.cjs');
-var providers = require('./providers-ChvMqnLd.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-DhDVbT5M.cjs');
+var node_async_hooks = require('node:async_hooks');
+var translateError = require('./translate-error-BUAR1WYG.cjs');
 
 /**
  * How a pattern ranks, one character per segment twice over: `L` for literal text or `P` for a param, then how narrow
@@ -519,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
@@ -527,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
@@ -605,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) {
@@ -822,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,
@@ -833,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();
@@ -845,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();
@@ -863,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);
@@ -876,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);
@@ -889,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) {
@@ -902,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) {
@@ -972,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
@@ -996,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;
 }
@@ -1056,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,
@@ -1668,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([
@@ -1691,6 +1844,8 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
 
 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;
@@ -1713,6 +1868,7 @@ exports.runReadyHooks = runReadyHooks;
 exports.runShutdownSequence = runShutdownSequence;
 exports.shutdownTimeoutOf = shutdownTimeoutOf;
 exports.shutdownTimeoutProblem = shutdownTimeoutProblem;
+exports.stageDependencies = stageDependencies;
 exports.startupClasses = startupClasses;
 exports.warnHandlersOffControllers = warnHandlersOffControllers;
 exports.warnInheritedRoutes = warnInheritedRoutes;

package/dist/cjs/_shared/{translate-error-DhDVbT5M.cjs → translate-error-BUAR1WYG.cjs}

@@ -1,9 +1,9 @@
 'use strict';
 
-var controller_decorator = require('./controller.decorator-CRn9kWob.cjs');
+var controller_decorator = require('./controller.decorator-XKMlcUZz.cjs');
 var discord_js = require('discord.js');
 
-/** The longest customId Discord accepts. */ const MAX_CUSTOM_ID_LENGTH = 100;
+const logger = new controller_decorator.Logger('Route');
 const PLACEHOLDER = /\{(\w+)(?::([^}/]*))?}/g;
 /** Encodes the characters that would end a param's segment, or read as an encoding, in a customId. */ const encodeSegment = (value)=>value.replace(/%/g, '%25').replace(/\//g, '%2F');
 /**
@@ -32,7 +32,8 @@ const PLACEHOLDER = /\{(\w+)(?::([^}/]*))?}/g;
  * fails to compile, and a typed param takes a value of its type.
  *
  * @param pattern - The customId pattern, where `{name}` captures one `/`-separated segment and `{name:int}` a
- *   typed one.
+ *   typed one. A param's name is ASCII letters, digits and _: a brace pair such as `{café}` is literal text, and is
+ *   warned about.
  * @returns A route whose `build` takes a value for each param.
  * @throws Error when the pattern cannot be read, as `@Command` would throw for it.
  *
@@ -57,6 +58,9 @@ const PLACEHOLDER = /\{(\w+)(?::([^}/]*))?}/g;
  * @see {@link https://meocord.dev/docs/4.2/components | Buttons, selects and modals}
  */ function route(pattern) {
     const { params, types } = controller_decorator.createRegexFromPattern(pattern);
+    const braces = controller_decorator.literalBraces(pattern);
+    // Once per pattern, as a route made inside a handler is made on every call
+    if (braces) controller_decorator.warnOnce(logger, `Pattern "${pattern}": ${braces}`);
     const names = new Set(params);
     const build = (values = {})=>{
         const unknown = Object.keys(values).filter((name)=>!names.has(name));
@@ -80,8 +84,9 @@ const PLACEHOLDER = /\{(\w+)(?::([^}/]*))?}/g;
             }
             return encodeSegment(text);
         });
-        if (id.length > MAX_CUSTOM_ID_LENGTH) {
-            throw new RangeError(`route('${pattern}').build() made a customId of ${id.length} characters, over Discord's ${MAX_CUSTOM_ID_LENGTH}: "${id}".`);
+        if (id === '') throw new RangeError(`route('${pattern}').build() made an empty customId; Discord's customIds are 1 to ${controller_decorator.MAX_CUSTOM_ID_LENGTH} characters.`);
+        if (id.length > controller_decorator.MAX_CUSTOM_ID_LENGTH) {
+            throw new RangeError(`route('${pattern}').build() made a customId of ${id.length} characters, over Discord's ${controller_decorator.MAX_CUSTOM_ID_LENGTH}: "${id}".`);
         }
         return id;
     };

package/dist/cjs/common/index.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var controller_decorator = require('../_shared/controller.decorator-CRn9kWob.cjs');
+var controller_decorator = require('../_shared/controller.decorator-XKMlcUZz.cjs');
 require('reflect-metadata');
-var translateError = require('../_shared/translate-error-DhDVbT5M.cjs');
-var shardedCooldownStore = require('../_shared/sharded-cooldown-store-BdAUTdYs.cjs');
+var translateError = require('../_shared/translate-error-BUAR1WYG.cjs');
+var shardedCooldownStore = require('../_shared/sharded-cooldown-store-CsJJyCZd.cjs');
 require('../enum/index.cjs');
 require('discord.js');
 require('path');