meocord 4.2.2 → 4.2.3

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

@@ -10,6 +10,7 @@ import { GuardDeniedError } from '../common/errors.js';
 import { getCommandMap, getMessageHandlers, getReactionHandlers, getAutocompleteHandlers } from '../decorator/controller.decorator.js';
 import { getEventHandlers } from '../decorator/event.decorator.js';
 import { META } from '../util/metadata-keys.js';
+import { wrapsMethod } from '../util/method-wrapper.util.js';
 
 /** Whether a `@UseGuard` entry is a guard with params rather than a guard class. */ function isGuardWithParams(guard) {
     // Entries are checked when @UseGuard or @MeoCord applies, so an object here is always { provide, params? }
@@ -259,6 +260,28 @@ const warnedShared = new WeakMap();
     }
     return undefined;
 }
+/**
+ * The prototypes on the chain that declare `methodName` as written, base first: the handler and each override of it,
+ * looking through methods a class-level `@UseGuard` re-declared to wrap an inherited handler. A handler's method-level
+ * stages are read from each, so an override keeps its base method's, as it keeps its route.
+ */ function stageOwners(prototype, methodName) {
+    const owners = [];
+    for(let current = prototype; current && current !== Object.prototype; current = Object.getPrototypeOf(current)){
+        if (!Object.prototype.hasOwnProperty.call(current, methodName)) continue;
+        if (!Reflect.getOwnMetadata(META.inheritedFrom, current, methodName)) owners.push(current);
+    }
+    return owners.reverse();
+}
+/** The entries a method-level stage lists under `key` on each of a handler's {@link stageOwners}, base first. */ function methodStages(prototype, methodName, key) {
+    return stageOwners(prototype, methodName).flatMap((owner)=>Reflect.getOwnMetadata(key, owner, methodName) ?? []);
+}
+/** The value a method-level stage holds under `key` on the nearest of a handler's {@link stageOwners} that declares one. */ function nearestMethodStage(prototype, methodName, key) {
+    for (const owner of stageOwners(prototype, methodName).reverse()){
+        const value = Reflect.getOwnMetadata(key, owner, methodName);
+        if (value !== undefined) return value;
+    }
+    return undefined;
+}
 /**
  * Caches a function of a class's prototype and one of its handlers. Handler metadata is fixed once
  * the classes are decorated, so dispatch resolves each handler's stages once, not on every call.
@@ -310,50 +333,165 @@ const warnedShared = new WeakMap();
  * The guards dispatch runs before a handler: its classes' class-level guards, outermost first, then
  * the method's. A method that is no handler has only its own, since class guards apply to handlers.
  */ const handlerGuards = perHandler((prototype, methodName)=>{
-    const source = sourcePrototype(prototype, methodName);
-    if (!source) return [];
+    if (!sourcePrototype(prototype, methodName)) return [];
     return [
         ...handlerMethods(prototype).has(methodName) ? stageClasses(prototype, methodName).flatMap(classLevelGuards) : [],
-        ...Reflect.getOwnMetadata(META.methodGuards, source, methodName) ?? []
+        ...methodStages(prototype, methodName, META.methodGuards)
     ];
 });
-const wrapperCount = perHandler((prototype, methodName)=>{
-    const owner = declaringPrototype(prototype, methodName);
-    return owner ? Reflect.getOwnMetadata(META.guardWrappers, owner, methodName) ?? 0 : 0;
+/**
+ * The type a direct call to a handler runs as, which is the one dispatch gives it: `'event'` for an `@On` or `@Once`
+ * handler, as its first argument may be a message or an interaction; otherwise read from the first argument.
+ */ const directCallType = perHandler((prototype, methodName)=>{
+    if (!getEventHandlers(prototype).some((handler)=>handler.method === methodName)) return undefined;
+    const routed = [
+        ...Object.values(getCommandMap(prototype) ?? {}).flat().map((command)=>command.methodName),
+        ...getMessageHandlers(prototype).map((handler)=>handler.method),
+        ...getReactionHandlers(prototype).map((handler)=>handler.method),
+        ...getAutocompleteHandlers(prototype).map((handler)=>handler.methodName)
+    ];
+    // A method dispatch also routes as a command, message or reaction has no one type
+    return routed.includes(methodName) ? undefined : 'event';
+});
+/** Whether `@UseGuard` wraps the method anywhere on the chain, an override's base included. */ const isWrapped = perHandler((prototype, methodName)=>{
+    for(let current = prototype; current; current = Object.getPrototypeOf(current)){
+        if (Object.prototype.hasOwnProperty.call(current, methodName) && Reflect.getOwnMetadata(META.guardWrappers, current, methodName)) return true;
+    }
+    return false;
 });
 /**
- * Calls dispatch has already guarded, keyed by first argument and method, counting the wrappers still
- * to pass. A user decorator that awaits between two wrappers leaves a pass pending during that await,
- * which a concurrent direct call with the same object and method could take; other overlaps fail closed.
- * An event whose first argument is not an object, such as `debug`'s string, is keyed by the instance.
- */ const dispatched = new WeakMap();
-/** The object a call's dispatch mark is kept on: its first argument, or the instance when that is not an object. */ function markKey(first, instance) {
-    return typeof first === 'object' && first !== null ? first : instance;
-}
-/** Takes one pass for the wrapper being entered, if dispatch left one for this call. */ function consumeDispatchMark(first, instance, methodName) {
-    const marks = dispatched.get(markKey(first, instance));
-    const remaining = marks?.get(methodName);
-    if (!marks || !remaining) return false;
-    if (remaining > 1) marks.set(methodName, remaining - 1);
-    else marks.delete(methodName);
+ * The pass of the guarded call running. Kept per call, so a concurrent call with the same object and method runs its own
+ * guards, and closed when the call returns, so work it leaves running, such as a timer, does not carry it.
+ */ const guardedPasses = new AsyncLocalStorage();
+/** Takes the pass for `wrapper` when it belongs to a call whose guards have already run and has not let it through yet. */ function takeGuardedPass(wrapper, first, instance, methodName) {
+    const pass = guardedPasses.getStore();
+    if (!pass?.open || pass.instance !== instance || pass.methodName !== methodName || pass.first !== first) return false;
+    if (pass.entered.has(wrapper)) return false;
+    pass.entered.add(wrapper);
     return true;
 }
+/** Runs a call whose guards have run, with its pass; `wrapper` is the one that ran them, which it has entered. */ async function runWithPass(instance, methodName, args, call, wrapper) {
+    const pass = {
+        instance,
+        methodName,
+        first: args[0],
+        entered: new Set(wrapper ? [
+            wrapper
+        ] : []),
+        open: true
+    };
+    try {
+        return await guardedPasses.run(pass, call);
+    } finally{
+        pass.open = false;
+    }
+}
+/**
+ * Adds guards to a method's class or method list, then republishes the effective list under
+ * `META.guards`, in the order they run: the bases' before the class's own, and within one class or method the
+ * latest decorator first, since it wraps outermost.
+ */ function recordGuards(key, guards, prototype, methodName) {
+    const existing = Reflect.getOwnMetadata(key, prototype, methodName) ?? [];
+    const bases = key === META.classGuards ? Reflect.getOwnMetadata(META.baseClassGuards, prototype, methodName) ?? 0 : 0;
+    Reflect.defineMetadata(key, [
+        ...existing.slice(0, bases),
+        ...guards,
+        ...existing.slice(bases)
+    ], prototype, methodName);
+    const [classGuards, inheritedGuards] = [
+        META.classGuards,
+        META.inheritedGuards
+    ].map((list)=>Reflect.getOwnMetadata(list, prototype, methodName) ?? []);
+    // The method's guards and those of the methods it overrides, base first, as dispatch runs them
+    const methodGuards = methodStages(prototype, methodName, META.methodGuards);
+    Reflect.defineMetadata(META.guards, [
+        ...inheritedGuards,
+        ...classGuards,
+        ...methodGuards
+    ], prototype, methodName);
+}
+/** The classes {@link guardOwnHandlersWithBaseGuards} has handled, as `@Controller` and each app's startup both call it. */ const guardedWithBases = new WeakSet();
+/**
+ * Gives each handler a class declares itself the class-level guards of the classes it extends,
+ * as its inherited handlers have: recorded under `META.guards`, and wrapped so a direct call
+ * runs them when no other guard wraps the handler. `@Controller` calls this as it decorates, and
+ * {@link prepareDirectCalls} for every class an app runs, a service included. Once per class.
+ */ function guardOwnHandlersWithBaseGuards(target) {
+    if (guardedWithBases.has(target)) return;
+    guardedWithBases.add(target);
+    const prototype = target.prototype;
+    for (const methodName of handlerMethods(prototype)){
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, methodName);
+        // Inherited handlers have the chain of the class that declares them
+        if (typeof descriptor?.value !== 'function' || Reflect.getOwnMetadata(META.inheritedFrom, prototype, methodName)) continue;
+        // Base first, as dispatch runs them
+        const guards = classChain(prototype, prototype).slice(1).reverse().flatMap(classLevelGuards);
+        if (guards.length === 0) continue;
+        if (!Reflect.getOwnMetadata(META.guardWrappers, prototype, methodName)) {
+            applyGuards(descriptor, prototype, methodName);
+            Object.defineProperty(prototype, methodName, descriptor);
+        }
+        recordGuards(META.inheritedGuards, guards, prototype, methodName);
+    }
+}
 /** The container that made each instance, so a direct call runs in its own app or testing module. */ const instanceContainers = new WeakMap();
 /**
- * Records each instance `container` makes of `classes` as its own. Two testing modules made from one class each run a
- * direct call on their own instance in themselves, where the class's metadata names only the last.
- */ function recordInstanceContainers(container, classes) {
+ * Readies direct calls to the handlers of the classes an app or testing module runs, controllers and services alike:
+ * - stamps each class with the container, and records each instance the container makes as its own, so two testing
+ *   modules made from one class each run a direct call on their own instance in themselves;
+ * - gives each handler a class declares itself the class-level guards of the classes it extends, and wraps each
+ *   override of a guarded handler, so a direct call to it runs the guards it inherits before its body.
+ */ function prepareDirectCalls(container, classes) {
     for (const cls of classes){
+        Reflect.defineMetadata(META.container, container, cls);
+        // Each class on the chain, base first, so an override above the one the app runs is wrapped too
+        for (const owner of classesOf(cls).reverse())guardOwnHandlersWithBaseGuards(owner);
+        wrapGuardedOverrides(cls.prototype);
         container.onActivation(cls, (_context, instance)=>{
             if (typeof instance === 'object' && instance !== null) instanceContainers.set(instance, container);
             return instance;
         });
     }
 }
+/** `cls` and the classes it extends, innermost first. */ function classesOf(cls) {
+    const classes = [];
+    for(let current = cls.prototype; current && current !== Object.prototype; current = Object.getPrototypeOf(current)){
+        classes.push(current.constructor);
+    }
+    return classes;
+}
+/** Wraps each method on the chain that overrides a handler a base method guards and is not wrapped itself. */ function wrapGuardedOverrides(prototype) {
+    for (const methodName of handlerMethods(prototype)){
+        let guardedBelow = false;
+        for (const owner of stageOwners(prototype, methodName)){
+            const descriptor = Object.getOwnPropertyDescriptor(owner, methodName);
+            if (guardedBelow && typeof descriptor?.value === 'function' && !Reflect.getOwnMetadata(META.guardWrappers, owner, methodName)) {
+                applyGuards(descriptor, owner, methodName);
+                Object.defineProperty(owner, methodName, descriptor);
+            }
+            if ((Reflect.getOwnMetadata(META.methodGuards, owner, methodName) ?? []).length > 0) guardedBelow = true;
+        }
+    }
+}
+/**
+ * Wraps a method so a direct call runs its guards first: the wrapper entered first runs the whole
+ * chain dispatch resolves for the handler, and lets the ones inside it through. A call from dispatch,
+ * which has already run the guards, passes through every wrapper.
+ */ function applyGuards(descriptor, prototype, propertyKey) {
+    const originalMethod = descriptor.value;
+    // Which wrapper a call has passed, so it passes each once
+    const wrapper = {};
+    descriptor.value = wrapsMethod(async function(...args) {
+        if (takeGuardedPass(wrapper, args[0], this, propertyKey)) return originalMethod.apply(this, args);
+        return runDirectCall(this, propertyKey, args, ()=>originalMethod.apply(this, args), wrapper);
+    }, originalMethod);
+    const wrappers = Reflect.getOwnMetadata(META.guardWrappers, prototype, propertyKey) ?? 0;
+    Reflect.defineMetadata(META.guardWrappers, wrappers + 1, prototype, propertyKey);
+}
 /**
- * Runs a direct call to a guarded handler: the handler's guards, as dispatch resolves them, then the
- * call with a pass for each wrapper inside the one entered, so no guard runs twice.
- */ async function runDirectCall(instance, methodName, args, call) {
+ * Runs a direct call to a guarded handler: the handler's guards, as dispatch resolves and types them, then
+ * the call with a pass every wrapper inside the one entered takes, so no guard runs twice.
+ */ async function runDirectCall(instance, methodName, args, call, wrapper) {
     const prototype = Object.getPrototypeOf(instance);
     const controller = instance.constructor;
     // The container that made the instance, or else the app that made the class or a class it extends: a subclass the
@@ -362,39 +500,22 @@ const wrapperCount = perHandler((prototype, methodName)=>{
     if (!container) {
         throw new Error(`${controller.name}.${methodName}: @UseGuard runs its guards through the app that made ${controller.name}, and this ` + `instance was made outside one. Inject ${controller.name}, or call it on an instance the app made.`);
     }
+    const type = directCallType(prototype, methodName);
     if (!await runGuards(handlerGuards(prototype, methodName), {
         container,
         controller,
         methodName,
-        args
+        args,
+        type
     })) return undefined;
-    const inner = wrapperCount(prototype, methodName) - 1;
-    if (inner <= 0) return call();
-    const key = markKey(args[0], instance);
-    let marks = dispatched.get(key);
-    if (!marks) dispatched.set(key, marks = new Map());
-    marks.set(methodName, inner);
-    try {
-        return await call();
-    } finally{
-        marks.delete(methodName);
-    }
+    return runWithPass(instance, methodName, args, call, wrapper);
 }
 /**
- * Calls a handler dispatch has already guarded. Its wrappers let this one call through; the passes
- * are removed afterwards, so a later direct call with the same (cached) object runs its guards.
+ * Calls a handler dispatch has already guarded. Its wrappers let this one call through; the pass
+ * closes afterwards, so a later direct call with the same (cached) object runs its guards.
  */ async function callGuardedHandler(instance, methodName, args) {
-    const count = wrapperCount(Object.getPrototypeOf(instance), methodName);
-    if (count === 0) return instance[methodName](...args);
-    const key = markKey(args[0], instance);
-    let marks = dispatched.get(key);
-    if (!marks) dispatched.set(key, marks = new Map());
-    marks.set(methodName, count);
-    try {
-        return await instance[methodName](...args);
-    } finally{
-        marks.delete(methodName);
-    }
+    if (!isWrapped(Object.getPrototypeOf(instance), methodName)) return instance[methodName](...args);
+    return runWithPass(instance, methodName, args, ()=>instance[methodName](...args));
 }
 
-export { callGuardedHandler, classChain, classLevelGuards, consumeDispatchMark, declaringPrototype, handlerGuards, handlerMethods, injectedTokens, isGuardWithParams, perHandler, recordInstanceContainers, runDirectCall, runGuards, singletonContextError, sourcePrototype, stageClasses, undecoratedConstructor, untypedParameter };
+export { applyGuards, callGuardedHandler, classChain, classLevelGuards, declaringPrototype, guardOwnHandlersWithBaseGuards, handlerGuards, handlerMethods, injectedTokens, isGuardWithParams, methodStages, nearestMethodStage, perHandler, prepareDirectCalls, recordGuards, runDirectCall, runGuards, singletonContextError, sourcePrototype, stageClasses, stageOwners, takeGuardedPass, undecoratedConstructor, untypedParameter };

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

@@ -1,9 +1,10 @@
 import { ModalSubmitInteraction, ComponentType, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, ChannelSelectMenuInteraction, MentionableSelectMenuInteraction } from 'discord.js';
-import { getCommandMap } from '../decorator/controller.decorator.js';
 import { matchComponentRoute } from './component-routes.js';
-import { hasCustomId, isCustomIdRouted, matchesHandler, resolveOptionParams, matchesCommandType } from '../util/interaction.util.js';
+import { hasCustomId, isCustomIdRouted, matchesHandler, resolveOptionParams, describeInteraction, focusedOptionName, matchesCommandType } from '../util/interaction.util.js';
 import { setOwn } from '../util/value.util.js';
 import { commandRouteKeys, matchCommandRoute } from './command-routes.js';
+import { matchAutocompleteRoute, buildAutocompleteRoutes } from './autocomplete-routes.js';
+import { getCommandMap, getAutocompleteHandlers } from '../decorator/controller.decorator.js';
 
 /** The entries of a discord.js Collection, or none for anything else, such as a test double's stub. */ const entriesOf = (collection)=>collection instanceof Map ? [
         ...collection.values()
@@ -143,5 +144,25 @@ import { commandRouteKeys, matchCommandRoute } from './command-routes.js';
     if (winner) return `command '${keys[0]}' does not reach ${handler}: dispatch runs ${winner.controllerClass.name}.${winner.meta.methodName}.`;
     return `command '${keys[0]}' does not match ${handler}'s route ${named.map(({ route })=>`'${route}'`).join(' or ')}.`;
 }
+/**
+ * Why an autocomplete could not reach a handler, for a test calling the handler directly: the handler is checked
+ * against the one dispatch routes the autocomplete to among `controllers`, by its command path and focused option.
+ * `undefined` when it is that one, when the handler has no `@Autocomplete` route, or when the interaction is not an
+ * autocomplete or has no command name.
+ */ function autocompleteMismatch(controllers, controller, methodName, interaction) {
+    if (!interaction.isAutocomplete() || typeof interaction.commandName !== 'string') return undefined;
+    const own = getAutocompleteHandlers(controller.prototype).filter((meta)=>meta.methodName === methodName);
+    if (own.length === 0) return undefined;
+    const winner = matchAutocompleteRoute(buildAutocompleteRoutes(controllers), interaction);
+    if (winner?.controllerClass === controller && winner.meta.methodName === methodName) return undefined;
+    const handler = `${controller.name}.${methodName}`;
+    const received = describeInteraction(interaction);
+    // A mock without a focused option reaches no option's handler, the commonest way to miss one
+    const option = focusedOptionName(interaction) === undefined ? own.find((meta)=>meta.optionName !== undefined)?.optionName : undefined;
+    const fix = option === undefined ? '' : ` Give the mock the focused option: options: createChatInputOptions({ focused: '${option}' }).`;
+    if (winner) return `${received} does not reach ${handler}: dispatch runs ${winner.controllerClass.name}.${winner.meta.methodName}.${fix}`;
+    const routes = own.map((meta)=>meta.optionName === undefined ? `'${meta.commandPath}'` : `'${meta.commandPath}' option '${meta.optionName}'`);
+    return `${received} does not match ${handler}'s route ${routes.join(' or ')}.${fix}`;
+}
 
-export { commandMismatch, componentRouteFor, handlerInput };
+export { autocompleteMismatch, commandMismatch, componentRouteFor, handlerInput };

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

@@ -1,13 +1,13 @@
 import 'reflect-metadata';
-import { refuse, startupError } from '../util/refusal.util.js';
+import { refuse, startupError, collectStartupErrors, isRefusal, startupErrorsOf } 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, runGuards, callGuardedHandler, handlerGuards, isGuardWithParams } from './guard-runner.js';
-import { prepareInterceptor, handlerInterceptors, bindShared, runInterceptors, interceptorClass } from './interceptor-runner.js';
+import { handlerDefer, startDefer, nonInteractionHandler, deferMisuseError } from './defer.js';
+import { perHandler, handlerGuards, runGuards, callGuardedHandler, isGuardWithParams } from './guard-runner.js';
+import { prepareInterceptor, bindShared, interceptorClass, handlerInterceptors, runInterceptors } 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, prepareHandlerArgs, pipeClass } from './input-runner.js';
+import { prepareFilter, filterClass, handlerFilterLevels, matchFilter, callFilter } from './filter-runner.js';
+import { handlerInputStages, pipeClass, prepareHandlerArgs, preparePipe } from './input-runner.js';
 import { hasObservers, notifyStart, outcomeOf, responsePhaseOf, notifyObservers } from './observer-runner.js';
 import { handlerCooldowns, peekCooldowns, methodCooldowns } from './cooldown-runner.js';
 import { Logger } from '../common/logger.js';
@@ -165,19 +165,35 @@ const stagesByGlobals = new WeakMap();
     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) {
-                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);
-        }
+        for (const method of handlerMethods(prototype))prepareHandler(container, controller, method);
         assertInputStagesOnInteractions(controller, prototype);
     }
 }
+/**
+ * Prepares one `@On` or `@Once` handler of a class the app reaches only as something it makes, as
+ * {@link prepareHandlerStages} prepares a controller's.
+ *
+ * @returns The errors a controller's handler would be refused with; none when the handler is ready to run.
+ */ function prepareEventHandler(container, cls, method) {
+    try {
+        collectStartupErrors(()=>{
+            prepareHandler(container, cls, method);
+            assertInputStages(cls, cls.prototype, method, 'event');
+        });
+        return [];
+    } catch (error) {
+        if (!isRefusal(error)) throw error;
+        return startupErrorsOf(error);
+    }
+}
+/** Binds what one handler's interceptors, filters and pipes need, refusing `@Defer` where it cannot apply. */ function prepareHandler(container, controller, method) {
+    const prototype = controller.prototype;
+    const kind = handlerDefer(prototype, method) ? nonInteractionHandler(prototype, method) : undefined;
+    if (kind) return startupError(deferMisuseError(controller.name, method, kind));
+    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);
+}
 /** 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);
@@ -223,17 +239,17 @@ const stagesByGlobals = new WeakMap();
                 'event'
             ])
     ];
-    for (const [method, kind] of others){
-        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) {
-            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) {
-            startupError(new Error(`${controller.name}.${method}: @Cooldown is for interaction and message handlers, and this is ${handler}.`));
-        }
+    for (const [method, kind] of others)assertInputStages(controller, prototype, method, kind);
+}
+/** Refuses `@Validate` and `@UsePipe` on one handler of `kind` with no params to check, and `@Cooldown` where it never counts. */ function assertInputStages(controller, prototype, method, kind) {
+    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) {
+        return 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}.`));
+    }
+    // A controller's own @Cooldown skips these handlers; one on the method itself is a mistake.
+    if (kind !== 'message' && methodCooldowns(prototype, method).length > 0) {
+        startupError(new Error(`${controller.name}.${method}: @Cooldown is for interaction and message handlers, and this is ${handler}.`));
     }
 }
 /**
@@ -481,4 +497,4 @@ const logger = new Logger('ExceptionFilter');
     }, options);
 }
 
-export { appPresenterOf, appStages, bindAppPresenter, bindGlobalStages, classDecorators, globalStagesOf, handleUnroutedError, handlerStageClasses, handlerStages, observeUnclaimed, prepareAppPresenter, prepareHandlerStages, prepareThemes, runHandler, runInAppTheme };
+export { appPresenterOf, appStages, bindAppPresenter, bindGlobalStages, classDecorators, globalStagesOf, handleUnroutedError, handlerStageClasses, handlerStages, observeUnclaimed, prepareAppPresenter, prepareEventHandler, prepareHandlerStages, prepareThemes, runHandler, runInAppTheme };

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

@@ -4,10 +4,10 @@ import { getCommandMap, getAutocompleteHandlers, getMessageHandlers, getReaction
 import { getEventHandlers } from '../decorator/event.decorator.js';
 import { CommandType } from '../enum/controller.enum.js';
 import { buildMessageRoutes, messageStarts, afterStart, parseMessagePattern, commandWordsOf } from './message-routes.js';
-import { computeMessageHelp, helpInvocation, effectiveScope } from './message-help.js';
+import { computeMessageHelp, helpInvocation } from './message-help.js';
+import { usageOf, effectiveScope } from './message-params.js';
 import { registrationKey, SENT_AS, commandNameOf, serialise } from './command-registration.js';
 import { textRenderer, messageLocale } from '../common/meocord-text.js';
-import { usageOf } from './message-params.js';
 
 const COMMAND_TYPES = new Set([
     CommandType.SLASH,
@@ -65,6 +65,28 @@ const COMMAND_TYPES = new Set([
     };
 }
 /** The message routes the app's dispatcher reads, by the app's registry, so its help and dispatch read one table. */ const dispatchedRoutes = new WeakMap();
+/** What every entry has: its class and method, and the metadata on them. */ function entryBase(controller, method) {
+    const context = new HandlerExecutionContext({
+        controller,
+        methodName: method,
+        args: []
+    });
+    return {
+        controller,
+        method,
+        get: context.get.bind(context),
+        getAll: context.getAll.bind(context)
+    };
+}
+const lateEventSources = new WeakMap();
+// The late sources each registry's cached entries were read with, so a list made before they arrived is read again
+const collectedWith = new WeakMap();
+/**
+ * Has `registry` list the `@On` and `@Once` handlers that run on `sources`, the instances the app attaches them for,
+ * where they are on a class it does not list already.
+ */ function listEventSources(registry, sources) {
+    lateEventSources.set(registry, sources);
+}
 /** Has `registry` work out message help from `routes`, the table the app's dispatcher routes messages with. */ function shareMessageRoutes(registry, routes) {
     dispatchedRoutes.set(registry, routes);
 }
@@ -105,7 +127,11 @@ const COMMAND_TYPES = new Set([
    * @param filter - Narrows the list by kind, controller, or both.
    * @returns The handlers, class by class in the order the app makes its classes, each after what it injects.
    */ list(filter = {}) {
-        this.entries ?? (this.entries = this.collect());
+        const late = lateEventSources.get(this);
+        if (!this.entries || collectedWith.get(this) !== late) {
+            this.entries = this.collect();
+            collectedWith.set(this, late);
+        }
         return this.entries.filter((entry)=>(filter.kind === undefined || entry.kind === filter.kind) && (filter.controller === undefined || entry.controller === filter.controller));
     }
     /**
@@ -129,8 +155,9 @@ const COMMAND_TYPES = new Set([
    * }
    * ```
    */ async messageHelp(message, query) {
+        // Until a dispatcher shares its table, the same one built from the same controllers, so help lists what dispatch reaches
         const routes = dispatchedRoutes.get(this) ?? this.messageRoutes ?? (this.messageRoutes = buildMessageRoutes([
-            ...this.classes
+            ...this.controllers
         ], this.messages));
         const starts = await messageStarts(this.messages, message, message.client?.user?.id);
         const text = (message.content ?? '').trim();
@@ -160,19 +187,7 @@ const COMMAND_TYPES = new Set([
         const entries = [];
         for (const controller of this.classes){
             const prototype = controller.prototype;
-            const base = (method)=>{
-                const context = new HandlerExecutionContext({
-                    controller,
-                    methodName: method,
-                    args: []
-                });
-                return {
-                    controller,
-                    method,
-                    get: context.get.bind(context),
-                    getAll: context.getAll.bind(context)
-                };
-            };
+            const base = (method)=>entryBase(controller, method);
             for (const [name, metas] of Object.entries(getCommandMap(prototype) ?? {})){
                 for (const { methodName, type, builder } of metas){
                     if (COMMAND_TYPES.has(type)) {
@@ -235,18 +250,33 @@ const COMMAND_TYPES = new Set([
                 });
             }
         }
+        // The classes the app reaches only as something it makes, listed once each, with the handlers that run on them
+        const listed = new Set(this.classes);
+        for (const { cls, handlers } of lateEventSources.get(this) ?? []){
+            if (listed.has(cls)) continue;
+            listed.add(cls);
+            for (const { event, method, once } of handlers)entries.push({
+                ...entryBase(cls, method),
+                kind: 'event',
+                name: event,
+                once
+            });
+        }
         return entries;
     }
     /**
-   * @param classes - The app's classes to read handlers from. The factory fills the list
-   *   once the app is bound; entries are read on the first {@link list}.
+   * @param classes - The app's classes to read handlers from, controllers and services alike. The factory fills the
+   *   list once the app is bound; entries are read on the first {@link list}.
    * @param messages - The app's `messages` options, whose `caseSensitive` message entries' `matches` follows.
    * @param translator - The app's translator, read when {@link messageHelp} words its labels; none for English.
-   */ constructor(classes, messages = {}, translator = ()=>undefined){
+   * @param controllers - The app's controllers, the classes dispatch routes messages to, which {@link messageHelp}
+   *   lists; `classes` when not given.
+   */ constructor(classes, messages = {}, translator = ()=>undefined, controllers = classes){
         this.classes = classes;
         this.messages = messages;
         this.translator = translator;
+        this.controllers = controllers;
     }
 }
 
-export { HandlerRegistry, shareMessageRoutes };
+export { HandlerRegistry, listEventSources, shareMessageRoutes };

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

@@ -1,7 +1,7 @@
 import 'reflect-metadata';
 import { ValidationError } from '../common/errors.js';
 import { prepareInterceptor } from './interceptor-runner.js';
-import { perHandler, sourcePrototype } from './guard-runner.js';
+import { perHandler, nearestMethodStage, methodStages } from './guard-runner.js';
 import { handlerCooldowns, consumeCooldowns } from './cooldown-runner.js';
 import { META } from '../util/metadata-keys.js';
 
@@ -15,17 +15,16 @@ function isPipeWithParams(entry) {
 const asList = (entries)=>Array.isArray(entries) ? entries : [
         entries
     ];
-/** The validation and pipes that run on a handler's input: `@Validate`'s first, then `@UsePipe`'s. */ const handlerInputStages = perHandler((prototype, methodName)=>{
-    const source = sourcePrototype(prototype, methodName);
-    if (!source) return {
-        pipes: []
-    };
-    const validation = Reflect.getOwnMetadata(META.methodValidation, source, methodName);
+/**
+ * The validation and pipes that run on a handler's input: `@Validate`'s first, then `@UsePipe`'s. The `@Validate` is the
+ * handler's own, or else that of the nearest method it overrides that has one; `@UsePipe`'s are every one's, base first.
+ */ const handlerInputStages = perHandler((prototype, methodName)=>{
+    const validation = nearestMethodStage(prototype, methodName, META.methodValidation);
     const inline = Object.entries(validation?.pipes ?? {}).flatMap(([key, entries])=>asList(entries).map((entry)=>({
                 key,
                 entry
             })));
-    const used = Reflect.getOwnMetadata(META.methodPipes, source, methodName) ?? [];
+    const used = methodStages(prototype, methodName, META.methodPipes);
     return {
         schema: validation?.schema,
         pipes: [

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

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
 import { assertStartupChecked } from './startup-checked.js';
-import { perHandler, injectedTokens, singletonContextError, sourcePrototype, stageClasses } from './guard-runner.js';
+import { injectedTokens, singletonContextError, perHandler, sourcePrototype, stageClasses, methodStages } from './guard-runner.js';
 import { ExecutionContext } from '../common/execution-context.js';
 import { makeInjectable } from '../util/injectable.util.js';
 import { isAppClassToken } from './lifecycle-order.js';
@@ -24,13 +24,12 @@ function isInterceptorWithParams(entry) {
 }
 /**
  * The interceptors around a handler: each class's, base first, down to the controller it is dispatched on, then the
- * method's.
+ * method's and its overrides', base first.
  */ const handlerInterceptors = perHandler((prototype, methodName)=>{
-    const source = sourcePrototype(prototype, methodName);
-    if (!source) return [];
+    if (!sourcePrototype(prototype, methodName)) return [];
     return [
         ...stageClasses(prototype, methodName).flatMap((cls)=>Reflect.getOwnMetadata(META.classInterceptors, cls) ?? []),
-        ...Reflect.getOwnMetadata(META.methodInterceptors, source, methodName) ?? []
+        ...methodStages(prototype, methodName, META.methodInterceptors)
     ];
 });
 /** Binds `cls` and its unbound dependencies as singletons, refusing any that injects `ExecutionContext`. */ function bindShared(container, cls) {