meocord 4.1.2 → 4.2.0

package/dist/esm/core/dispatcher.js

@@ -38,6 +38,7 @@ import { existingResponse } from '../common/response/response-state.js';
     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.
@@ -293,22 +294,64 @@ import { existingResponse } from '../common/response/response-state.js';
                 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}${commandWordsOf(route.tokens).join(' ')}`);
             const hooks = 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
@@ -429,6 +472,7 @@ import { existingResponse } from '../common/response/response-state.js';
         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 ?? {};

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

@@ -1,7 +1,7 @@
 import 'reflect-metadata';
 import { perHandler, sourcePrototype, stageClasses } from './guard-runner.js';
 import { bindShared } from './interceptor-runner.js';
-import { refuse } from '../util/refusal.util.js';
+import { startupError } from '../util/refusal.util.js';
 import { isConstructor } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
 
@@ -41,7 +41,7 @@ import { META } from '../util/metadata-keys.js';
 /** Binds a filter as a singleton, after checking it is one. */ function prepareFilter(container, entry) {
     const cls = filterClass(entry);
     if (!Reflect.hasOwnMetadata(META.catchTypes, cls)) {
-        throw refuse(new Error(`${cls.name || 'A filter'}: used as an exception filter, but not decorated with @Catch().`));
+        return startupError(new Error(`${cls.name || 'A filter'}: used as an exception filter, but not decorated with @Catch().`));
     }
     bindShared(container, cls);
 }

package/dist/esm/core/handler-pipeline.js

@@ -1,17 +1,17 @@
 import 'reflect-metadata';
-import { refuse } from '../util/refusal.util.js';
+import { refuse, startupError } from '../util/refusal.util.js';
 import { setPresenter } from '../common/response/presenter.js';
 import { responseOf } from '../common/response/response-state.js';
 import { handlerDefer, nonInteractionHandler, deferMisuseError, startDefer } from './defer.js';
-import { perHandler, handlerGuards, runGuards, callGuardedHandler, isGuardWithParams } from './guard-runner.js';
-import { prepareInterceptor, handlerInterceptors, bindShared, interceptorClass, runInterceptors } from './interceptor-runner.js';
+import { perHandler, runGuards, callGuardedHandler, handlerGuards, isGuardWithParams } from './guard-runner.js';
+import { prepareInterceptor, handlerInterceptors, bindShared, runInterceptors, interceptorClass } from './interceptor-runner.js';
 import { inferContextType, HandlerExecutionContext, UnroutedExecutionContext } from '../common/execution-context.js';
 import { prepareFilter, handlerFilterLevels, filterClass, matchFilter, callFilter } from './filter-runner.js';
-import { handlerInputStages, preparePipe, pipeClass, prepareHandlerArgs } from './input-runner.js';
+import { handlerInputStages, preparePipe, prepareHandlerArgs, pipeClass } from './input-runner.js';
 import { hasObservers, notifyStart, outcomeOf, responsePhaseOf, notifyObservers } from './observer-runner.js';
-import { methodCooldowns, handlerCooldowns, peekCooldowns } from './cooldown-runner.js';
+import { handlerCooldowns, peekCooldowns, methodCooldowns } from './cooldown-runner.js';
 import { Logger } from '../common/logger.js';
-import { configureThemes, beginCallTheme } from './theme-runtime.js';
+import { beginCallTheme, configureThemes } from './theme-runtime.js';
 import { runInThemeScope } from './theme-scope.js';
 import { getEventHandlers } from '../decorator/event.decorator.js';
 import { getCommandMap, getMessageHandlers, getReactionHandlers, getAutocompleteHandlers } from '../decorator/controller.decorator.js';
@@ -57,12 +57,16 @@ const NO_GLOBAL_STAGES = {
  */ function bindAppPresenter(container, app, client) {
     const options = Reflect.getMetadata(META.appOptions, app);
     if (!options?.presenter) return undefined;
-    bindShared(container, options.presenter);
+    prepareAppPresenter(container, app);
     const presenter = container.get(options.presenter);
     container.bind(APP_PRESENTER).toConstantValue(presenter);
     if (client) setPresenter(client, presenter);
     return presenter;
 }
+/** Binds the app's presenter class as a shared stage, checking it as one, without making it. */ function prepareAppPresenter(container, app) {
+    const options = Reflect.getMetadata(META.appOptions, app);
+    if (options?.presenter) bindShared(container, options.presenter);
+}
 /** Where a container keeps the application's presenter. */ const APP_PRESENTER = Symbol('app_presenter');
 /** The presenter `bindAppPresenter` resolved into `container`, if any. */ function appPresenterOf(container) {
     return container.isBound(APP_PRESENTER) ? container.get(APP_PRESENTER) : undefined;
@@ -152,18 +156,21 @@ const stagesByGlobals = new WeakMap();
 /**
  * Binds the interceptors, filters and pipes every handler of `controllers` uses, and the global ones, as singletons, so
  * one that cannot be shared, or a filter without `@Catch`, fails at startup; refuses there `@Defer`, `@Validate`,
- * `@UsePipe` and `@Cooldown` where they cannot apply, and two classes that keep state under one name.
+ * `@UsePipe` and `@Cooldown` where they cannot apply, and two classes that keep state under one name. Binds only; it
+ * makes nothing, so it runs with the other startup checks.
  */ function prepareHandlerStages(container, controllers) {
     assertDistinctNamesWhereKeyed(controllers);
     const globals = globalStagesOf(container);
-    configureThemes(container, globals.theme, controllers, globals.themeFor);
     for (const entry of globals.interceptors)prepareInterceptor(container, entry);
     for (const entry of globals.filters)prepareFilter(container, entry);
     for (const controller of controllers){
         const prototype = controller.prototype;
         for (const method of handlerMethods(prototype)){
             const kind = handlerDefer(prototype, method) ? nonInteractionHandler(prototype, method) : undefined;
-            if (kind) throw refuse(deferMisuseError(controller.name, method, kind));
+            if (kind) {
+                startupError(deferMisuseError(controller.name, method, kind));
+                continue;
+            }
             for (const entry of handlerInterceptors(prototype, method))prepareInterceptor(container, entry);
             for (const entry of handlerFilterLevels(prototype, method, []).flat())prepareFilter(container, entry);
             for (const { entry } of handlerInputStages(prototype, method).pipes)preparePipe(container, entry);
@@ -171,6 +178,10 @@ const stagesByGlobals = new WeakMap();
         assertInputStagesOnInteractions(controller, prototype);
     }
 }
+/** Records the app's theme for the handlers of `controllers`, once the startup checks have passed: it makes the theme cache. */ function prepareThemes(container, controllers) {
+    const globals = globalStagesOf(container);
+    configureThemes(container, globals.theme, controllers, globals.themeFor);
+}
 /** Whether a class has state keyed by its name: a cooldown on a handler, or a `@Once` handler. */ function keyedByName(cls) {
     const prototype = cls.prototype;
     const handlers = [
@@ -187,7 +198,8 @@ const stagesByGlobals = new WeakMap();
     for (const cls of classes){
         const other = byName.get(cls.name);
         if (other && other !== cls && (keyedByName(cls) || keyedByName(other))) {
-            throw refuse(new Error(`${cls.name}: two classes have this name; @Cooldown and @Once tell classes apart by name, so they would share ` + `their counts. Rename one of them.`));
+            startupError(new Error(`${cls.name}: two classes have this name; @Cooldown and @Once tell classes apart by name, so they would share ` + `their counts. Rename one of them.`));
+            continue;
         }
         byName.set(cls.name, cls);
     }
@@ -215,11 +227,12 @@ const stagesByGlobals = new WeakMap();
         const { schema, pipes } = handlerInputStages(prototype, method);
         const handler = kind === 'message' ? 'a message handler without a pattern' : `${kind === 'autocomplete' || kind === 'event' ? 'an' : 'a'} ${kind} handler`;
         if (schema || pipes.length > 0) {
-            throw refuse(new Error(`${controller.name}.${method}: @Validate and @UsePipe are for interaction and patterned message handlers, ` + `whose options, customId params, modal fields and pattern params they check, and this is ${handler}.`));
+            startupError(new Error(`${controller.name}.${method}: @Validate and @UsePipe are for interaction and patterned message handlers, ` + `whose options, customId params, modal fields and pattern params they check, and this is ${handler}.`));
+            continue;
         }
         // A controller's own @Cooldown skips these handlers; one on the method itself is a mistake.
         if (kind !== 'message' && methodCooldowns(prototype, method).length > 0) {
-            throw refuse(new Error(`${controller.name}.${method}: @Cooldown is for interaction and message handlers, and this is ${handler}.`));
+            startupError(new Error(`${controller.name}.${method}: @Cooldown is for interaction and message handlers, and this is ${handler}.`));
         }
     }
 }
@@ -462,4 +475,4 @@ const logger = new Logger('ExceptionFilter');
     }, options);
 }
 
-export { appPresenterOf, appStages, bindAppPresenter, bindGlobalStages, classDecorators, globalStagesOf, handleUnroutedError, handlerStageClasses, handlerStages, observeUnclaimed, prepareHandlerStages, runHandler, runInAppTheme };
+export { appPresenterOf, appStages, bindAppPresenter, bindGlobalStages, classDecorators, globalStagesOf, handleUnroutedError, handlerStageClasses, handlerStages, observeUnclaimed, prepareAppPresenter, prepareHandlerStages, prepareThemes, runHandler, runInAppTheme };

package/dist/esm/core/handler-registry.js

@@ -97,7 +97,7 @@ const COMMAND_TYPES = new Set([
  *
  * @group Controllers
  * @see {@link HandlerEntry}
- * @see {@link https://meocord.dev/docs/4.1/handler-discovery | Handler discovery}
+ * @see {@link https://meocord.dev/docs/4.2/handler-discovery | Handler discovery}
  */ class HandlerRegistry {
     /**
    * Lists the registered handlers.

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

@@ -4,7 +4,7 @@ import { perHandler, injectedTokens, singletonContextError, sourcePrototype, sta
 import { ExecutionContext } from '../common/execution-context.js';
 import { makeInjectable } from '../util/injectable.util.js';
 import { isAppClassToken } from './lifecycle-order.js';
-import { refuse } from '../util/refusal.util.js';
+import { startupError } from '../util/refusal.util.js';
 import { Logger } from '../common/logger.js';
 import { META } from '../util/metadata-keys.js';
 
@@ -35,7 +35,7 @@ function isInterceptorWithParams(entry) {
 });
 /** Binds `cls` and its unbound dependencies as singletons, refusing any that injects `ExecutionContext`. */ function bindShared(container, cls) {
     if (container.isBound(cls)) return;
-    if (injectedTokens(cls).includes(ExecutionContext)) throw refuse(singletonContextError(cls));
+    if (injectedTokens(cls).includes(ExecutionContext)) return startupError(singletonContextError(cls));
     assertStartupChecked(container, cls);
     makeInjectable(cls);
     container.bind(cls).toSelf().inSingletonScope();