meocord 4.1.2 → 4.2.1

package/dist/types/{index-D7n0FBMm.d.ts → index-DKJclIi-.d.ts}

@@ -1,4 +1,4 @@
-import { BaseInteraction, Message, APIEmbed, InteractionReplyOptions, BitFieldResolvable, MessageFlags, InteractionEditReplyOptions, JSONEncodable, APIModalInteractionResponseCallbackData, ModalComponentData, Interaction, ColorResolvable, ButtonStyle, MessageReaction, PartialMessageReaction, ContextMenuCommandType, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, ApplicationCommandType, SlashCommandBuilder, SlashCommandOptionsOnlyBuilder, SlashCommandSubcommandsOnlyBuilder, ContextMenuCommandBuilder, RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody, ChatInputCommandInteraction, PrimaryEntryPointCommandInteraction, ButtonInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, ChannelSelectMenuInteraction, ModalSubmitInteraction, APIComponentInContainer, AttachmentBuilder, MessageReplyOptions, GuildMember, User, Role, GuildBasedChannel, PartialUser, Client } from 'discord.js';
+import { BaseInteraction, Message, APIMessageTopLevelComponent, APIEmbed, InteractionReplyOptions, BitFieldResolvable, MessageFlags, InteractionEditReplyOptions, JSONEncodable, APIModalInteractionResponseCallbackData, ModalComponentData, Interaction, ColorResolvable, ButtonStyle, MessageReaction, PartialMessageReaction, ContextMenuCommandType, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, ApplicationCommandType, SlashCommandBuilder, SlashCommandOptionsOnlyBuilder, SlashCommandSubcommandsOnlyBuilder, ContextMenuCommandBuilder, RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody, ChatInputCommandInteraction, PrimaryEntryPointCommandInteraction, ButtonInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, ChannelSelectMenuInteraction, ModalSubmitInteraction, APIComponentInContainer, AttachmentBuilder, MessageReplyOptions, GuildMember, User, Role, GuildBasedChannel, PartialUser, Client } from 'discord.js';
 import { RsbuildConfig as RsbuildConfig$1 } from '@rsbuild/core';
 import { C as CommandType, R as ReactionHandlerAction } from './controller.enum-DTDn69N9.js';
 
@@ -48,7 +48,7 @@ interface MetadataDecorator<T> {
  *
  * @group Utilities
  * @see {@link ExecutionContext}
- * @see {@link https://meocord.dev/docs/4.1/guards | Guards}
+ * @see {@link https://meocord.dev/docs/4.2/guards | Guards}
  */
 declare function createMetadata<T>(description?: string): MetadataDecorator<T>;
 
@@ -329,13 +329,14 @@ interface ResponseState {
     /** Where the answer stands, re-read from the interaction so answers made around this state count. */
     readonly state: ResponsePhase;
     /**
-     * The message this state last replied with, updated or edited, never a follow-up, or the message a component is on.
-     * Read-only: edit through the state.
+     * The answer's message: the one this state last replied with, updated or edited, or the message a component is on. A
+     * follow-up is it only once it is the answer, after replacing a public deferral or after `delete()`; after `delete()`
+     * it is `undefined` until something is sent. Read-only: edit through the state.
      */
     readonly message: Message | undefined;
     /** The components and embeds of the message before `@Defer` locked it; `undefined` until then. */
     readonly original: {
-        readonly components: readonly unknown[];
+        readonly components: readonly APIMessageTopLevelComponent[];
         readonly embeds: readonly APIEmbed[];
     } | undefined;
     /**
@@ -366,6 +367,9 @@ interface ResponseState {
      * A reply Discord refuses as already acknowledged elsewhere still throws, and the next `send()` edits.
      * After `modal()` it throws: a modal has no message, and the modal's submit is answered instead.
      *
+     * After a private `followUp()` replaced a public deferral, it edits that follow-up. After `delete()` it sends a
+     * follow-up, private when the deleted answer was unless `flags` say otherwise, and that follow-up is the answer.
+     *
      * After `@Defer` locked a message, omitting `components` puts back its components as they were
      * before the lock, and omitting `embeds` drops the loading view; `components: []` clears them.
      *
@@ -375,7 +379,8 @@ interface ResponseState {
      */
     send(payload: ResponsePayload, options?: ResponseSendOptions): Promise<Message | undefined>;
     /**
-     * Edits the answer, routed as `send()` is: an edit once the interaction is answered.
+     * Edits the answer, routed as `send()` is: an edit once the interaction is answered, of the follow-up that replaced
+     * a public deferral, or, after `delete()`, a follow-up that becomes the answer.
      *
      * @param payload - Text, or edit options.
      * @param options - `fill: false` leaves this edit's embeds and containers uncoloured.
@@ -386,8 +391,9 @@ interface ResponseState {
      * Sends another message after the answer. Before any answer it is the first reply. While a command's
      * reply is deferred and nothing is sent yet, Discord turns a follow-up into the deferred reply and
      * ignores its flags, so it is sent as that edit; a private follow-up on a public deferral deletes the
-     * deferral first and is sent privately. After `modal()` it is sent as made, and Discord decides whether it
-     * accepts a follow-up there; the modal's submit is the interaction to answer.
+     * deferral first, is sent privately, and is the answer `send()`, `edit()` and `delete()` act on. After `delete()`,
+     * it is the answer too. After `modal()` it is sent as made, and Discord decides whether it accepts a follow-up
+     * there; the modal's submit is the interaction to answer.
      *
      * @param payload - Text, or reply options; `Ephemeral` makes the follow-up private.
      * @param options - `fill: false` leaves this follow-up's embeds and containers uncoloured.
@@ -395,8 +401,9 @@ interface ResponseState {
      */
     followUp(payload: ResponsePayload, options?: ResponseSendOptions): Promise<Message | undefined>;
     /**
-     * Deletes the answer: the reply, or for a component deferred without a reply of its own, its message.
-     * Throws before any answer, and after `modal()`, which leaves no message.
+     * Deletes the answer: the reply, the follow-up that replaced a public deferral, or for a component deferred
+     * without a reply of its own, its message. `message` is then `undefined` until something is sent. Throws before any
+     * answer, after `modal()`, which leaves no message, and again with nothing sent since the last `delete()`.
      */
     delete(): Promise<void>;
     /**
@@ -781,7 +788,7 @@ type ExecutionContextType = 'interaction' | 'autocomplete' | 'message' | 'reacti
  * @group Utilities
  * @see {@link createMetadata}
  * @see {@link StageParams}
- * @see {@link https://meocord.dev/docs/4.1/guards | Guards}
+ * @see {@link https://meocord.dev/docs/4.2/guards | Guards}
  */
 declare abstract class ExecutionContext {
     /**
@@ -1243,7 +1250,10 @@ declare class MemoryCooldownStore extends CooldownStore {
     peekMany(entries: readonly CooldownEntry[]): Promise<CooldownBatchVerdict>;
     /** Each entry's call times, trimmed to its window, and whether it allows one more call now. */
     private check;
-    /** Drops the keys whose calls have all left their window, once a minute from the store's first call. */
+    /**
+     * Drops the keys whose calls have all left their window, once a minute from a call, until a sweep leaves none: an
+     * idle store then holds no timer, so one nothing references is collected, and its next call starts the sweep again.
+     */
     private startSweeping;
 }
 
@@ -1348,7 +1358,7 @@ declare class UserError extends Error {
  * @group Responses
  * @category Errors
  * @see {@link Catch}
- * @see {@link https://meocord.dev/docs/4.1/exception-filters | Exception filters}
+ * @see {@link https://meocord.dev/docs/4.2/exception-filters | Exception filters}
  */
 declare class CommandNotFoundError extends Error {
     /** @param message - What the error says, `No handler matched the interaction.` unless given. */
@@ -1439,7 +1449,7 @@ interface MessageUsageIssue {
  * @category Errors
  * @see {@link MessageHandler}
  * @see {@link translateError}
- * @see {@link https://meocord.dev/docs/4.1/message-commands | Message commands}
+ * @see {@link https://meocord.dev/docs/4.2/message-commands | Message commands}
  */
 declare class MessageUsageError extends Error {
     readonly usage: string;
@@ -1956,8 +1966,10 @@ interface CommandMeta<T extends string = string> {
     /** The params a component's customId pattern captures, in the order they appear. */
     dynamicParams?: T[];
     /**
-     * How specific this pattern is; the highest wins when several routes match one customId, so
-     * `gi-profile/summary/{ownerId}/{uid}` beats `gi-profile/{uuid}/{uid}` whatever the declaration order.
+     * How specific this pattern is, as 4.1 ranked patterns: more literal text first.
+     *
+     * @deprecated Since 4.2, and removed in the next major version (5.0). Internal: nothing replaces it. Component routing
+     * ranks patterns segment by segment and doesn't read it.
      */
     specificity?: number;
     /** The builder's own `guilds` option, when it has one. */
@@ -2103,10 +2115,14 @@ interface MeoCordApplication {
      */
     start(): Promise<void>;
     /**
-     * Stops the bot: runs the `onShutdown` hooks under the configured `shutdownTimeout` and closes the client, or with
-     * process sharding, asks every shard to shut down and waits for it. It ends no process of its own accord, except that
-     * called in a shard, it asks the manager to stop every shard, which then shuts that shard's process down too. A stop
-     * while the bot starts ends that start, a call after the first waits for it, and a stopped app does not start again.
+     * Stops the bot: stops taking events, waits for the calls under way, runs the `onShutdown` hooks under the configured
+     * `shutdownTimeout` and closes the client, or with process sharding, asks every shard to shut down and waits for it.
+     * It ends no process of its own accord, except that called in a shard, it asks the manager to stop every shard, which
+     * then shuts that shard's process down too. A call that awaits `stop()`, as an owner-only shutdown command does, is
+     * not waited for.
+     *
+     * A stop while the bot starts ends that start: it waits for the providers being made, at most `shutdownTimeout`, and
+     * nothing more is made after it. A call after the first waits for it, and a stopped app does not start again.
      *
      * @returns A promise that resolves once the bot is stopped. It never rejects: a failure to close is logged, and sets
      *   `process.exitCode` to 1 unless another code is already set.
@@ -2164,7 +2180,7 @@ interface ReadyInfo {
  *
  * @group Types
  * @see {@link OnShutdown}
- * @see {@link https://meocord.dev/docs/4.1/lifecycle-hooks | Lifecycle hooks}
+ * @see {@link https://meocord.dev/docs/4.2/lifecycle-hooks | Lifecycle hooks}
  */
 interface OnReady {
     /**
@@ -2186,9 +2202,11 @@ interface OnReady {
  * it injects. The whole sequence is limited by `shutdownTimeout` in `meocord.config.ts`; shutdown then goes on
  * whether or not it finished. A hook that throws is logged and the next one still runs.
  *
- * It runs only for a class whose `onReady` has finished, or that has none: a signal that arrives
- * while the ready hooks are running skips the class still starting and those not reached yet, and no
- * further `onReady` starts. An `onReady` that threw counts as finished, so its partial setup is cleaned up.
+ * It runs only for a class whose `onReady` has finished, or that has none. A stop while the ready hooks
+ * are running waits for the `onReady` in progress, within `shutdownTimeout`, then shuts that class down too;
+ * those not reached yet are skipped, and no further `onReady` starts. An `onReady` still running once only the
+ * hooks' share of the timeout is left is named in a warning and skipped. An `onReady` that threw counts as
+ * finished, so its partial setup is cleaned up.
  *
  * @example
  * ```ts
@@ -2211,7 +2229,7 @@ interface OnReady {
  *
  * @group Types
  * @see {@link OnReady}
- * @see {@link https://meocord.dev/docs/4.1/lifecycle-hooks | Lifecycle hooks}
+ * @see {@link https://meocord.dev/docs/4.2/lifecycle-hooks | Lifecycle hooks}
  */
 interface OnShutdown {
     /** Runs before the client is destroyed. */
@@ -2353,7 +2371,11 @@ interface MessageResponseContext {
  * @category Presenters
  */
 interface PresentedError {
-    /** What the user is told. */
+    /**
+     * What the user is told, fitted to Discord's limit for the answer's `mode`: at most 4096 characters for an embed and
+     * 4000 for a Components V2 Text Display, cut to end in `…`. An empty or whitespace-only message comes as MeoCord's generic error text.
+     * So a presenter that writes it as its view's text renders, whatever the error's message.
+     */
     message: string;
     /** The error being answered, so a presenter can style it by kind. */
     error: unknown;
@@ -2546,6 +2568,15 @@ interface ControllerOptions {
      * @defaultValue `true`
      */
     inheritStages?: boolean;
+    /**
+     * What a handler this class re-decorates answers of the routes its base classes declare for it. `'keep'` answers
+     * them as well as its own; `'replace'` answers only the routes this class declares for it, of every kind: commands,
+     * component patterns, message patterns, reactions and autocompletes. A command no handler answers any more is not
+     * registered. A method overridden without decorators keeps every route it inherits either way.
+     *
+     * @defaultValue `'keep'`; the next major version (5.0) replaces them by default
+     */
+    inheritedRoutes?: 'keep' | 'replace';
 }
 /**
  * One prefix or several that start a message command, such as `'!'` or `['!', '?']`; `''` stands for none.
@@ -2583,7 +2614,7 @@ type MessagePrefix = string | readonly string[];
  * @group Configuration
  * @category App options
  * @see {@link MessageHandler}
- * @see {@link https://meocord.dev/docs/4.1/message-commands | Message commands}
+ * @see {@link https://meocord.dev/docs/4.2/message-commands | Message commands}
  */
 interface MessageCommandOptions {
     /**
@@ -2656,6 +2687,28 @@ interface MessageCommandOptions {
      * @defaultValue `false`
      */
     help?: boolean | MessageHelpOptions;
+    /**
+     * How a message's handlers run: the patterned handler it matched, then every `@MessageHandler()` listener.
+     * `'sequential'` runs each once the one before it has settled, so a slow command delays the listeners after it.
+     * `'concurrent'` starts them together and settles once all have: each keeps its own guards, interceptors, filters
+     * and observers, and no order holds between them, so a listener can run before the command has written what it
+     * reads. The built-in help and a command's usage are answered first either way.
+     * @defaultValue `'sequential'`; the next major version (5.0) may run them concurrently by default
+     *
+     * @example
+     * ```ts
+     * @MeoCord({ controllers: [Commands, Moderation], messages: { prefix: '!', handlers: 'concurrent' } })
+     * class App {}
+     * ```
+     */
+    handlers?: 'sequential' | 'concurrent';
+    /**
+     * Warns, once per handler, when a message's handler takes 5 seconds or more with listeners waiting after it, under
+     * `handlers: 'sequential'`, naming the handler and how many it held back. A testing module warns only when this is
+     * `true`, since a test's fake clock can pass 5 seconds inside a handler.
+     * @defaultValue `true` in a running bot, `false` in a `MeoCordTestingModule`
+     */
+    slowHandlerWarning?: boolean;
 }
 /**
  * The words the built-in help command answers to, as `@MeoCord({ messages: { help } })` takes them.
@@ -2775,7 +2828,7 @@ interface MessageHelpParam {
  * ```
  *
  * @group Types
- * @see {@link https://meocord.dev/docs/4.1/localisation | Localisation}
+ * @see {@link https://meocord.dev/docs/4.2/localisation | Localisation}
  */
 type MeoCordMessages = (typeof MEOCORD_MESSAGES)['meocord'];
 /**
@@ -2806,7 +2859,7 @@ type MeoCordMessages = (typeof MEOCORD_MESSAGES)['meocord'];
  *
  * @group Configuration
  * @category App options
- * @see {@link https://meocord.dev/docs/4.1/message-params | Message params}
+ * @see {@link https://meocord.dev/docs/4.2/message-params | Message params}
  */
 interface MessageParamType<T = unknown> {
     /** A noun such as `hex colour`, read in "is not a valid hex colour". Defaults to the type's key. */
@@ -3019,7 +3072,7 @@ type MessageScope = 'guild' | 'dm' | 'any';
  * @group Configuration
  * @category App options
  * @see {@link MessageHandler}
- * @see {@link https://meocord.dev/docs/4.1/message-commands | Message commands}
+ * @see {@link https://meocord.dev/docs/4.2/message-commands | Message commands}
  */
 interface MessageHandlerOptions {
     /**
@@ -3077,7 +3130,7 @@ interface MessageHandlerOptions {
  * @group Configuration
  * @category Config file
  * @see {@link MeoCord}
- * @see {@link https://meocord.dev/docs/4.1/configuration | Configuration}
+ * @see {@link https://meocord.dev/docs/4.2/configuration | Configuration}
  */
 interface MeoCordConfig {
     /** Shown as a prefix on every log line. Omitted when unset. */
@@ -3139,9 +3192,27 @@ interface MeoCordConfig {
      */
     sourceMappedStacks?: boolean;
     /**
-     * How long, in milliseconds, shutdown waits for the `onShutdown` hooks before destroying the client
-     * anyway: from 0 to 2147478647, the longest a timer keeps less the margin the shard manager waits on top. The limit covers the whole sequence, not each hook,
-     * including the calls under way that the cooldown store's shutdown waits for.
+     * How a startup error a decorator finds, such as an invalid customId pattern, is reported.
+     *
+     * With `'first'`, a decorator throws its error as its class is defined, when its file is imported, so a bot with
+     * three mistakes shows one per run. With `'all'`, decorators keep their errors, and `MeoCordFactory.create()` logs
+     * every one, each with its handler and file, alongside the errors its own checks find, then throws the first. The
+     * built bot reads it before your modules load. In a test, call `reportAllStartupErrors()` from `meocord/testing` in
+     * the setup file instead.
+     *
+     * Whichever you choose, `create()` reports every error its own checks find, such as two handlers of one command.
+     *
+     * @defaultValue `'first'`; `'all'` in the next major version (5.0)
+     */
+    startupErrors?: 'first' | 'all';
+    /**
+     * How long, in milliseconds, shutdown waits for the calls under way and the `onShutdown` hooks before destroying the
+     * client anyway: from 0 to 2147478647, the longest a timer keeps less the margin the shard manager waits on top. The
+     * limit covers the whole sequence, not each hook.
+     *
+     * The calls are waited for first, but no longer than the timeout less a reserve kept for the hooks: a quarter of it,
+     * at least 1 second and never more than half. A call still running then is named in a warning, and the hooks run in
+     * the time left.
      *
      * @defaultValue `10_000`
      */
@@ -3196,7 +3267,7 @@ interface MeoCordConfig {
  * @group Configuration
  * @category Config file
  * @see {@link ShardContext}
- * @see {@link https://meocord.dev/docs/4.1/sharding | Sharding}
+ * @see {@link https://meocord.dev/docs/4.2/sharding | Sharding}
  */
 interface ShardingConfig {
     /**
@@ -3239,7 +3310,7 @@ interface ShardingConfig {
  *
  * @group Configuration
  * @category Config file
- * @see {@link https://meocord.dev/docs/4.1/slash-commands | Slash commands}
+ * @see {@link https://meocord.dev/docs/4.2/slash-commands | Slash commands}
  */
 interface CommandRegistrationConfig {
     /**