meocord 4.2.0 → 4.2.2

package/dist/types/testing/index.d.ts

@@ -1,10 +1,10 @@
 import { ServiceIdentifier, Container } from 'inversify';
 import { Client, Interaction, Message, MessageReaction, PartialMessageReaction, User, PartialUser, ClientEvents, Base, Locale, GuildMember, Role, GuildBasedChannel, Guild, APIMessageTopLevelComponent, JSONEncodable, APIEmbed, MessageFlagsResolvable, TextBasedChannel, BaseChannel, APIAuthorizingIntegrationOwnersMap, APIInteractionGuildMember, PermissionResolvable, APIUser, CacheType, CommandInteractionOptionResolver, ThreadChannel, AnyThreadChannel, ChatInputCommandInteraction, AutocompleteInteraction, MessageContextMenuCommandInteraction, UserContextMenuCommandInteraction, PrimaryEntryPointCommandInteraction, ContextMenuCommandInteraction, CommandInteraction, ButtonInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, ChannelSelectMenuInteraction, MessageComponentInteraction, ModalSubmitInteraction, BaseInteraction, DMChannel, PartialGroupDMChannel, OmitPartialGroupDMChannel, Attachment, ModalSubmitFields, MessagePayload, InteractionReplyOptions, InteractionUpdateOptions, InteractionEditReplyOptions, MessageEditOptions, APIModalInteractionResponseCallbackData, ModalComponentData, InteractionDeferReplyOptions, InteractionDeferUpdateOptions, MessageResolvable, DiscordAPIError } from 'discord.js';
 import { ReactionHandlerAction, CommandType } from '../enum/index.js';
-import { a8 as Provider, P as ProviderToken } from '../index-CdXsFgjE.js';
+import { a8 as Provider, P as ProviderToken } from '../index-DKJclIi-.js';
 import { CooldownStore, ExecutionContextType, ExecutionContext, CooldownScope, MetadataDecorator, ResponsePhase, ResponseCall } from '../common/index.js';
 import { DispatchObserver, GuardInterface, InterceptorInterface, ExceptionFilter, ThemeOverride, ThemeResolvers, ThemeResolver, MessageCommandOptions, MessagePrefix, RootTheme, DeepReadonly, MeoCordTheme } from '../interface/index.js';
-export { ao as ClassProvider, F as FactoryProvider, ap as ValueProvider } from '../index-CdXsFgjE.js';
+export { ao as ClassProvider, F as FactoryProvider, ap as ValueProvider } from '../index-DKJclIi-.js';
 import { ThemeCache } from '../common/index.js';
 import { Translator } from '../common/index.js';
 import '@rsbuild/core';
@@ -161,7 +161,11 @@ interface DispatchedCall extends InvocationResult {
  * @category Module
  */
 interface EmitResult {
-    /** How many `@On` and `@Once` handlers ran; a handler a guard denied is not counted. */
+    /**
+     * How many `@On` and `@Once` handlers ran; a handler a guard denied by returning `false` is not counted. A guard
+     * that throws `GuardDeniedError` rejects `emit` instead, as the bot's event fallback, which skips the event, doesn't
+     * run in a testing module.
+     */
     ran: number;
 }
 /**
@@ -224,6 +228,8 @@ declare class TestingModule {
     private resolving?;
     private readying?;
     private closing?;
+    /** The `onReady` hooks' pass, which `close()` waits for, less one whose `onReady` called `close()`. */
+    private readonly readyPass;
     /**
      * Resolves the module's `useFactory` providers, awaiting those that return a promise, in dependency
      * order. `invoke`, `dispatch` and `emit` call it first; call it yourself before `get` resolves anything that
@@ -266,12 +272,21 @@ declare class TestingModule {
      * It first gives up the theme read outside calls, if `init({ ready: true })` made it this module's;
      * reads outside calls then return MeoCord's defaults until another module or app is ready.
      *
+     * A stopped bot runs nothing more. Once `close()` is called, a module still runs what `dispatch`, `invoke` and `emit`
+     * are given, against services shut down, or shutting down, and warns once that it is closed, so a `close()` in the
+     * wrong place shows.
+     *
      * The cooldown store and what it injects shut down last, in the same sequence as the bot's. When any of them has an
      * `onShutdown`, the calls `invoke`, `dispatch` and `emit` have under way finish first, then the store operations
      * they started, so the store's last writes still reach it. The module stops waiting for the whole sequence after
      * its `shutdownTimeout`, 10 seconds unless set, and logs that it did. Give a test whose fake store never answers, or
      * whose `onShutdown` never settles, a short `shutdownTimeout`.
      *
+     * A `close()` while `init({ ready: true })` runs the `onReady` hooks waits for them first, within the same
+     * `shutdownTimeout`. An `onReady` still running once only the hooks' share of it is left is named in a warning, and
+     * its class is shut down all the same, as everything the module constructed is. One that calls `close()` itself isn't
+     * waited for.
+     *
      * @returns Once every hook has run. Rejects with the error of a hook that failed, or an
      *   `AggregateError` naming each when several did.
      *
@@ -287,6 +302,9 @@ declare class TestingModule {
      * ```
      */
     close(): Promise<void>;
+    private warnedClosed;
+    /** Warns once, after `close()`, that a call runs against services already shut down. */
+    private warnIfClosed;
     private runReady;
     /**
      * The module's {@link ThemeCache}: the instance its classes inject, holding what `themeFor`, or
@@ -349,7 +367,9 @@ declare class TestingModule {
      * @returns Whether the handler ran, and the error a filter handled, if any. Rejects with an error no
      *   filter handles, or with the error a filter throws: the built-in fallback, which answers such
      *   errors in the bot, does not run here. Rejects before running anything with an interaction or a
-     *   message the handler's route does not match, naming both.
+     *   message the handler's route does not match, naming both. Given fewer arguments than the handler
+     *   declares, with a first that is neither an interaction nor a message, such as a reaction without its
+     *   `ReactionEvent`, it rejects under `useStrictMocks()`, and otherwise warns once and runs the handler.
      *
      * @example
      * ```ts
@@ -372,6 +392,13 @@ declare class TestingModule {
      * ```
      */
     invoke<C extends new (...args: any[]) => unknown, M extends HandlerName<C>>(controller: C, methodName: M, ...args: HandlerArgs<C, M>): Promise<InvocationResult>;
+    /** The handlers already warned about for being given fewer arguments than they take, so each is named once. */
+    private readonly warnedArgumentCounts;
+    /**
+     * Refuses under `useStrictMocks()`, or warns once otherwise, a call that gives a handler fewer arguments than it
+     * declares when `invoke` builds none for it, as for a reaction given without its `ReactionEvent`.
+     */
+    private checkArgumentCount;
     /** The calls under way, each removed once it settles: what `close()` lets finish before the cooldown store stops. */
     private readonly calls;
     /** Counts `call` as under way until it settles. */
@@ -422,15 +449,20 @@ declare class TestingModule {
         action?: ReactionHandlerAction;
     }): Promise<DispatchedCall>;
     /**
-     * Emits a client event to the module's `@On` and `@Once` handlers, through the same pipeline the app
-     * runs them in: the global guards of the module's `app`, then each handler's own. Handlers on the
-     * module's controllers, class providers and their dependencies all receive it. A `@Once` handler
-     * handles only the first event, as it would on a client.
+     * Emits a client event to the module's `@On` and `@Once` handlers, through the pipeline the app runs
+     * them in up to its event fallback: the global guards of the module's `app`, then each handler's own.
+     * Handlers on the module's controllers, class providers and their dependencies all receive it. A
+     * `@Once` handler handles only the first event, as it would on a client.
+     *
+     * The bot's event fallback doesn't run here. On a bot, a guard's `GuardDeniedError` is logged and the
+     * event skipped, and a handler's `UserError` is logged and, when the event carries a message, answered
+     * as a reply to it; here both reject `emit` as any error does, so a test checks them with `rejects`.
      *
      * @param event - The client event, such as `'guildMemberAdd'`.
      * @param args - The event's arguments, typed from discord.js's `ClientEvents`.
-     * @returns How many handlers ran. Rejects once every handler has settled if any threw: with that
-     *   error when one handler failed, or an `AggregateError` of them when several did.
+     * @returns How many handlers ran. Rejects once every handler has settled if any threw, a guard's
+     *   `GuardDeniedError` and a handler's `UserError` included: with that error when one handler failed,
+     *   or an `AggregateError` of them when several did.
      *
      * @example
      * ```ts
@@ -501,6 +533,10 @@ declare class TestingModuleBuilder {
     /**
      * Replaces a guard with a stub wherever it applies, globally or on a controller or handler.
      *
+     * It stands in for the guard wherever the guard is bound, a provider of the same token included, and wins over an
+     * `overrideProvider` of it. The stub needs a `canActivate`, its own or its prototype's: `compile()` refuses one without
+     * it under `useStrictMocks()`, and otherwise warns.
+     *
      * @param guard - The guard class to replace.
      * @example
      * ```ts
@@ -514,6 +550,10 @@ declare class TestingModuleBuilder {
      * Replaces an interceptor with a stub wherever it applies, globally or on a controller or handler.
      * The stub's `intercept` receives the context and `next`; call `next.handle()` to run the handler.
      *
+     * It stands in for the interceptor wherever it is bound, a provider of the same token included, and wins over an
+     * `overrideProvider` of it. A stub without `intercept` is refused by `compile()` under `useStrictMocks()`, and
+     * otherwise warned about.
+     *
      * @param interceptor - The interceptor class to replace.
      * @example
      * ```ts
@@ -527,6 +567,10 @@ declare class TestingModuleBuilder {
      * Replaces an exception filter with a stub wherever it applies. The filter's `@Catch` still decides
      * which errors reach the stub.
      *
+     * It stands in for the filter wherever it is bound, a provider of the same token included, and wins over an
+     * `overrideProvider` of it. A stub without `catch` is refused by `compile()` under `useStrictMocks()`, and otherwise
+     * warned about.
+     *
      * @param filter - The filter class to replace.
      * @example
      * ```ts
@@ -640,7 +684,8 @@ declare class MeoCordTestingModule {
      * @param app - The class `@MeoCord` decorates.
      * @param options - Providers that replace the app's by token, extra controllers, and observers.
      * @returns The builder, whose `override*` methods still apply, for `compile()`.
-     * @throws TypeError when `app` is not a `@MeoCord` class.
+     * @throws TypeError when `app` is not a `@MeoCord` class. After {@link reportAllStartupErrors}, an app whose
+     *   `@MeoCord` was refused throws the error it was refused for instead.
      *
      * @example
      * ```ts
@@ -707,6 +752,22 @@ interface MockResult<T = unknown> {
     /** What the call returned, or the error it threw. */
     value: T;
 }
+/**
+ * One call's outcome once it has settled, as a mock function records it.
+ *
+ * It holds what a returned promise resolved or rejected with, or what the call returned or threw. Vitest's
+ * `toHaveResolved` and the rest read it.
+ *
+ * @group Testing
+ * @category Mocks
+ * @see {@link MockState}
+ */
+interface MockSettledResult<T = unknown> {
+    /** `'fulfilled'` once the call resolved or returned, `'rejected'` once it rejected or threw, `'incomplete'` before. */
+    type: 'fulfilled' | 'rejected' | 'incomplete';
+    /** What the call resolved, returned, rejected or threw with; `undefined` while it is incomplete. */
+    value: T | undefined;
+}
 /**
  * What a mock function has recorded: each call's arguments, outcome and `this`, in order.
  *
@@ -725,12 +786,19 @@ interface MockState<T extends (...args: any[]) => any = (...args: any[]) => any>
     readonly instances: any[];
     /** Arguments from the most recent call, or undefined if never called. */
     readonly lastCall?: CallArgs<T>;
+    /** Each call's outcome once it has settled, in order. */
+    readonly settledResults: MockSettledResult<Awaited<CallResult<T>>>[];
+    /** When each call came, as a number that grows across meocord's own mocks. */
+    readonly invocationCallOrder: number[];
+    /** The `this` each call had, in order. */
+    readonly contexts: unknown[];
 }
 /**
  * The mock API of a mock function: what it has recorded, and the methods that change what it does.
  *
  * Every mock from `meocord/testing` has it, with the names jest and Vitest use, so a test written for either runner
- * reads the same.
+ * reads the same. The values it takes and records aren't checked against the function it mocks; see
+ * {@link MockedFunction}.
  *
  * @group Testing
  * @category Mocks
@@ -772,9 +840,12 @@ interface MockInstance<T extends (...args: any[]) => any = (...args: any[]) => a
 /**
  * A mock function with the signature of `T`, and the mock API of {@link MockInstance}.
  *
- * It takes the place of jest's `MockedFunction<T>` and Vitest's `MockedFunction<T>`. The mock factories type each
- * method of a mock with it, so `interaction.reply.mockResolvedValue(...)` type-checks. For an overloaded method, such as
- * a manager's `fetch`, the mock API takes what any of its overloads takes or returns.
+ * It takes the place of jest's `MockedFunction<T>` and Vitest's `MockedFunction<T>`, and the mock factories type each
+ * method of a mock with it. Calling the mock is checked against `T`. The values its mock API takes and records are
+ * not, for a plain function as for an overloaded one: `mockReturnValue` and `mockResolvedValue` take any value,
+ * `mockImplementation` takes any function, and each of `mock.calls`' arguments and each of `mock.results`' values reads
+ * as `any`. So a partial fake, such as `guild.members.fetch.mockResolvedValue({ id })`, type-checks, and so does a
+ * value of the wrong type.
  *
  * @group Testing
  * @category Mocks
@@ -926,6 +997,14 @@ declare function resetAllMocks(): void;
  * `mockReturnValue`, `mockResolvedValue`, `mockRejectedValue` and `mockImplementation` share one implementation, so
  * the last one set wins. The `*Once` variants queue, and run first, in the order they were set.
  *
+ * It records what Vitest's `toHaveResolved` and `toHaveBeenCalledBefore` read as well. Its call order is counted
+ * across meocord's own mocks, apart from the runner's, so compare the order of two of meocord's mocks, or of two of the
+ * runner's, not one of each.
+ *
+ * A promise the implementation returns is handed back as one that settles the same way, not as the same object: test
+ * it with `toEqual`, `toHaveReturnedWith` or by awaiting it, not with `toBe`. A property set on the given promise, such
+ * as a `cancel` method, isn't carried over.
+ *
  * @param impl - The implementation to run until another is set.
  *
  * @example
@@ -997,6 +1076,11 @@ type OutsideServer = {
 } | {
     channel: DMChannel | PartialGroupDMChannel;
 };
+type NotRaw<T> = T extends {
+    member: unknown;
+} ? {
+    member?: Exclude<MockProps<T>['member'], APIInteractionGuildMember>;
+} : unknown;
 /**
  * Creates a mock instance of a discord.js class, such as an interaction, keeping its prototype so `instanceof` holds.
  *
@@ -1008,19 +1092,34 @@ type OutsideServer = {
  * `user` of its own unless given, and its `locale` is `'en-US'`; without a `guildId` it is a DM, and with one its
  * `member` is its user: for a `user` given, when the test gives the `guild`, the guild's cached member for that user,
  * so a message and an interaction from one user in that server share it, and `memberPermissions` are that member's
- * permissions (`null` in a DM). A user is a person, `bot: false`, and a member has the server's @everyone role and the
- * roles {@link createMockMember} gave it; with a `guildId` but no `guild`, a server the bot isn't in, that @everyone role
- * has the `guildId`. A DM sent to a member goes through its user's `send()` and the user's one DM channel. Its
- * `channel` is a text channel of its server, the one its guild caches under `channelId`, or the user's DM channel. A
- * `channel` given sets what the test leaves out of `channelId`, `guildId` and `guild`, as discord.js reads them from
- * it: a DM channel is no server, and a server's channel its server; one in another server than the `guildId` given is
- * refused, naming both. A select menu has picked nothing unless given: its
- * `values` are the ids of the `users` and `members`, `roles` or `channels` given, the collections of what it picks,
- * each empty unless given. Other data Discord always sends reads as
- * Discord sends it, such as `false` for a flag and `null` for what may be absent; what picks the handler, `commandName`
- * or `customId`, is the test's to give. Replies follow Discord's order, so a second `reply()` rejects, and
- * {@link getResponse} reports every answer the interaction got. Every method is a mock function, and one that returns a
- * promise in discord.js resolves.
+ * permissions, with its channel's overwrites applied under `useStrictMocks()` (`null` in a DM). A user is a person,
+ * `bot: false`, and a member has the server's @everyone role and the roles {@link createMockMember} gave it; with a
+ * `guildId` but no `guild`, a server the bot isn't in, that @everyone role has the `guildId`. A DM sent to a member
+ * goes through its user's `send()` and the user's one DM channel. Its `channel` is a text channel of its server, the
+ * one its guild caches under `channelId` when it is read, or the user's DM channel. A `channel` given sets what the test leaves out of
+ * `channelId`, `guildId` and `guild`, as discord.js reads them from it: a DM channel is no server, and a server's
+ * channel its server; one in another server than the `guildId` given is refused, naming both. Under `useStrictMocks()`
+ * a `message` given places it in the message's channel and server, a `guild` or a member's guild in that server, and a
+ * `guildId` alone in a server the bot isn't in, with no `guild` or `channel` and a raw member for its user; a
+ * `channel`, `guild` or `guildId` other than the place a test gave the message is refused, and a message whose place
+ * `createMockMessage()` made moves to the one given. In default mode it stays where its own channel and guild fields
+ * place it, and reading where it is warns once where strict mocks would place it otherwise. A select menu has picked
+ * nothing unless given: its `values` are the ids of the `users` and `members`, `roles` or `channels` given, the
+ * collections of what it picks, each empty unless given. Other data Discord always sends reads as Discord sends it,
+ * such as `false` for a flag and `null` for what may be absent; what picks the handler, `commandName` or `customId`, is
+ * the test's to give. Replies follow Discord's order, so a second `reply()` rejects, and {@link getResponse} reports
+ * every answer the interaction got. Under `useStrictMocks()` an answer marks the interaction `replied` or `deferred`
+ * once it resolves, as discord.js does after Discord takes it: an edit or follow-up made before then rejects with
+ * `InteractionNotReplied`, and a second answer sent while the first is in flight is refused with Discord's 40060. In
+ * default mode the mark is made at the call, with a warning where a bot would fail. Every method is a mock function, and one that returns a promise in discord.js
+ * resolves. What the mock computes for itself, such as `memberPermissions` and `appPermissions`, calls none of them and
+ * caches nothing, so a stub a test sets stays for its own code.
+ *
+ * An answer keeps that order whatever it is set to do: one a test gives a value with `mockResolvedValue` replies or
+ * defers as a real one would, and one that rejects changes nothing. `fetchReply()` reads back what `reply()` or
+ * `update()` sent; after `deleteReply()`, or before any answer, fetching, editing or deleting the original response
+ * rejects with 10008 (Unknown Message), while follow-ups stay reachable by their id. Flags are read as discord.js
+ * reads them, and its errors carry its codes, such as `InteractionAlreadyReplied`.
  *
  * Given `guild: null`, `member: null` or a DM channel, it is typed as an interaction that may come from anywhere, so
  * its `guild` and `member` read as possibly `null`; otherwise as one from a server the bot is in.
@@ -1045,10 +1144,11 @@ type OutsideServer = {
  * @see {@link createChatInputOptions}
  * @see {@link https://meocord.dev/docs/4.2/mocks | Mocks}
  */
-declare function createMockInteraction<T extends object>(Class: InteractionClass<T>, props?: MockProps<T>): DeepMocked<T>;
+declare function createMockInteraction<T extends object>(Class: InteractionClass<T>, props?: MockProps<T> & NotRaw<T>): DeepMocked<T>;
 /**
  * Creates a mock interaction from a server the bot isn't in: one given a {@link createMockRawMember | raw member} and
- * that server's `guildId`, as a user-installed command run there arrives.
+ * that server's `guildId`, with no `channel`, as discord.js caches none there, as a user-installed command run there
+ * arrives.
  *
  * It is typed as discord.js types an interaction from such a server, `'raw'`: its `guild` is `null` and its `member`
  * the raw member. Everything else is as {@link createMockInteraction} builds it.
@@ -1067,10 +1167,11 @@ declare function createMockInteraction<T extends object>(Class: InteractionClass
  * @group Testing
  * @category Mocks
  */
-declare function createMockInteraction<T extends object>(Class: InteractionClass<T>, props: Omit<MockProps<WithCache<T, 'raw'>>, 'options'> & {
+declare function createMockInteraction<T extends object>(Class: InteractionClass<T>, props: Omit<MockProps<WithCache<T, 'raw'>>, 'options' | 'channel'> & {
     options?: object;
     guildId: string;
     member: APIInteractionGuildMember;
+    channel?: never;
 }): DeepMocked<WithCache<T, 'raw'>>;
 /**
  * Creates a mock interaction from outside a server: one given `guild: null`, `member: null` or a DM channel, as from a
@@ -1093,7 +1194,7 @@ declare function createMockInteraction<T extends object>(Class: InteractionClass
  * @group Testing
  * @category Mocks
  */
-declare function createMockInteraction<T extends object>(Class: InteractionClass<T>, props: MockProps<WithCache<T, CacheType>> & OutsideServer): DeepMocked<WithCache<T, CacheType>>;
+declare function createMockInteraction<T extends object>(Class: InteractionClass<T>, props: MockProps<WithCache<T, CacheType>> & OutsideServer & NotRaw<WithCache<T, CacheType>>): DeepMocked<WithCache<T, CacheType>>;
 /**
  * Creates a mock of any type, with no class needed, for service doubles and interfaces.
  *
@@ -1152,7 +1253,7 @@ declare function createMock<T extends object>(props?: MockProps<T>): DeepMocked<
  * @category Mocks
  * @see {@link createMockInteraction}
  */
-declare const createMockUser: (props?: MockProps<User>) => DeepMocked<User>;
+declare function createMockUser(props?: MockProps<User>): DeepMocked<User>;
 /**
  * Creates a mock {@link Client}, with `users`, `channels`, `guilds` and `application.commands` ready to stub.
  *
@@ -1202,7 +1303,8 @@ interface MockGuildOverrides {
     channels?: readonly GuildBasedChannel[];
 }
 /**
- * Creates a mock {@link Guild}, with the `members`, `channels`, `roles` and `bans` managers ready to stub.
+ * Creates a mock {@link Guild}, with its `members`, `channels`, `roles`, `bans`, `emojis`, `stickers`, `scheduledEvents`,
+ * `autoModerationRules` and `invites` managers ready to stub.
  *
  * Use it for the server a message or an interaction came from, with the members, roles and channels a handler looks
  * up in it.
@@ -1212,9 +1314,11 @@ interface MockGuildOverrides {
  *
  * @remarks
  * A manager's `fetch(id)` resolves to its cached item with that id, as discord.js looks there first, or to a new one it
- * caches under that id: a member or channel in this guild, a role with that id, or a ban. `members.fetch({ user: ids })`
- * resolves to a collection of each of those members, found or made the same way; `create()` and `edit()` resolve to a
- * mock of its item, and a list fetch to an empty collection. Members, roles and channels given are put in
+ * caches under that id: a member, channel, emoji, sticker, scheduled event or AutoMod rule in this guild, a role with
+ * that id, a ban, or an invite with that code. `members.fetch({ user: ids })` resolves to a collection of each of those
+ * members, found or made the same way; `create()` and `edit()` resolve to a mock of its item, which `create()` caches
+ * as discord.js does, but for an invite, made for the channel given and cached nowhere; a list fetch resolves to an
+ * empty collection. Members, roles and channels given are put in
  * their managers' caches, where dispatch looks first when it resolves a message's typed params; a member
  * {@link createMockMember} made without a server is in this one. Its `roles.everyone` is the role given with the
  * guild's id, or else an @everyone role of its own at position 0 with no permissions, in `roles.cache` as Discord has
@@ -1339,8 +1443,9 @@ interface MockMemberOverrides {
  * highest, by position, then the lower id. `permissions` are computed as discord.js computes them: every permission for
  * the server's owner, and otherwise its roles' permissions combined, @everyone's included, so a member with no roles has
  * @everyone's alone. The member is put in its guild's member cache, so an interaction or a message from its user in that
- * server has it as its `member`, and `memberPermissions` are its permissions. A DM sent to the member goes through its
- * user's `send()` and the user's one DM channel.
+ * server has it as its `member`, and `memberPermissions` are its permissions, with the interaction's channel's
+ * overwrites applied under `useStrictMocks()`. A DM sent to the member goes through its user's `send()` and the user's
+ * one DM channel.
  *
  * @param overrides - The member's user, server, roles and nickname; see {@link MockMemberOverrides}.
  * @returns The mock member.
@@ -1382,9 +1487,12 @@ interface MockMessageOverrides {
      * on the message's client, and in a server its `member` is the guild's cached member for that user, or a new one.
      */
     author?: User;
-    /** Its top-level components: action rows, or Components V2 such as a container. */
+    /**
+     * Its top-level components: action rows, or Components V2 such as a container. Builders or API JSON, held as
+     * discord.js's classes, such as `ActionRow` and `ButtonComponent`, built from their JSON at the time of the call.
+     */
     components?: readonly (APIMessageTopLevelComponent | JSONEncodable<APIMessageTopLevelComponent>)[];
-    /** Its embeds. */
+    /** Its embeds, builders or API JSON, held as discord.js's `Embed` built from their JSON at the time of the call. */
     embeds?: readonly (APIEmbed | JSONEncodable<APIEmbed>)[];
     /** Its flags: a number, flag names or a `MessageFlagsBitField`. */
     flags?: MessageFlagsResolvable;
@@ -1412,12 +1520,14 @@ interface MockMessageOverrides {
  * `@MessageHandler` does not skip it.
  *
  * @remarks
- * `delete()`, `edit()`, `reply()`, `react()`, `pin()` and `unpin()` throw once the message is deleted, and `edit()`
- * and `reply()` resolve to a new mock message. Without overrides the message is empty, in a server, from a new
- * person who is its `member`; with `guild: null` it is a direct message. Give `author` to send several messages as
- * one user, such as to reach a per-user cooldown. An author given, and the users, roles and channels the content
- * mentions, are cached as the gateway delivers them. It is typed as discord.js emits a message, never in a group DM,
- * so it fits `messageCreate` and the other message events.
+ * `delete()`, `edit()`, `reply()`, `react()`, `pin()` and `unpin()` throw once the message is deleted. `edit()` changes
+ * this message and resolves to it, and `reply()` resolves to the reply, sent in this message's channel and holding what
+ * was sent, as a channel's `send()` does. Under `useStrictMocks()` a message the bot sends is its `client.user`'s, and
+ * one sent in a DM is in that DM. Without overrides the message is empty, in a server, from a new person who is its
+ * `member`; with `guild: null` it is a direct message. Give `author` to send several messages as one user, such as to
+ * reach a per-user cooldown. An author given, and the users, roles and channels the content mentions, are cached as the
+ * gateway delivers them. It is typed as discord.js emits a message, never in a group DM, so it fits `messageCreate` and
+ * the other message events.
  *
  * @param overrides - The message's content, components and the rest; see {@link MockMessageOverrides}.
  *
@@ -1482,6 +1592,10 @@ interface ChatInputOptions {
  * A whole number is an Integer option and a fraction a Number one, so
  * `getInteger()` reads only a whole number, and `getNumber()` reads either.
  *
+ * The `focused` option reads as Discord sends it, through `getFocused()`, `getFocused(true)` and `data` alike: a
+ * string, `''` when no value is given, and marked `focused` in `data`. A number given for it is its digits under
+ * `useStrictMocks()`; otherwise it stays the number, with a warning when read.
+ *
  * @typeParam Cached - `any` by default, to match `createMockInteraction(ChatInputCommandInteraction)`; pass it when the
  *   interaction under test is cache-pinned.
  *
@@ -1508,17 +1622,36 @@ declare function createChatInputOptions<Cached extends CacheType = any>(opts?: C
  *
  * Call it once in the test runner's setup file. A message's `editable`, `deletable`, `pinnable`, `crosspostable`,
  * `bulkDeletable`, `hasThread` and `partial`, a member's `manageable`, `kickable`, `bannable` and `moderatable`, a
- * role's `editable`, a channel's and a thread's `viewable`, `manageable`, `deletable`, `joinable` and the rest, and
- * `partial` on users, channels and reactions then run discord.js's own getters against the mock, and `message.thread`
- * is `null` when the channel caches no thread under the message's id. No placeholder warning is logged.
+ * role's `editable`, a channel's and a thread's `viewable`, `manageable`, `deletable`, `joinable` and the rest, a voice
+ * channel's `full`, and `partial` on users, channels and reactions then run discord.js's own getters against the mock,
+ * and `message.thread` is `null` when the channel caches no thread under the message's id. So do a message's
+ * `editedAt`, a member's `presence`, a server's `verified` and `systemChannel` and a channel's `parent`, each `null` or
+ * `false` until the test gives what it is computed from. A reaction's `me` is `false`, a message's
+ * `mentions.repliedUser` and a modal's `message` are `null`, an interaction's `ephemeral` is `null` until `reply()` or
+ * `deferReply()` decides it, and a reaction has a whole message of its own, so MeoCord's dispatcher fetches neither. No
+ * placeholder warning is logged.
  *
  * @remarks
- * Those getters read what a server holds, so strict mocks also have it as Discord sends it: the bot's member is in
- * the server's member cache from the start, @everyone has the permissions Discord gives it in a new server, and a
- * channel or thread made without a server has one of its own, a thread with a text channel as its parent. A message
- * has empty `content`, a thread is neither archived nor locked, and a reaction's `count` is 1. Give the bot's member
- * a role to let it do more, such as kick a member its role ranks above. A value the test sets on a mock wins over the
- * computed one. The next major version (5.0) computes these values without the call.
+ * Those getters read what a server holds, so strict mocks also have it as Discord sends it: the bot's member is in the
+ * server's member cache from the start, @everyone has the permissions Discord gives it in a new server, and a channel
+ * or thread made without a server has one of its own, a thread with a text channel as its parent. A message has empty
+ * `content`, a thread is neither archived nor locked, and a reaction's `count` is 1. A user, server or channel made
+ * with a generated id was created when the mock was made, as a message is. An interaction's `memberPermissions` apply
+ * its channel's overwrites, a thread's parent's for a thread, to its member's permissions. An interaction is in its
+ * message's channel and server, a guild's or a member's server, or, given a `guildId` alone, a server the bot isn't in.
+ * A message the bot sends is its `client.user`'s, and one it sends in a DM is in that DM. Give the bot's member a role
+ * to let it do more, such as kick a member its role ranks above. A value the test sets on a mock wins over the computed
+ * one. An interaction's answer that discord.js would refuse, such as a second `reply()` after one a test set with
+ * `mockResolvedValue`, is refused too, where without it the mock runs it and warns. An answer marks the interaction
+ * `replied`, `deferred` or `responded` once it resolves, as discord.js does, so code that doesn't await one fails as it
+ * would on a bot, within one run of the test's code. The next major version (5.0) computes these values, and refuses
+ * those answers, without the call.
+ *
+ * `invoke` also refuses a call that gives a handler fewer arguments than it declares where it builds none, such as a
+ * reaction handler given its reaction without its `ReactionEvent`; without strict mocks, it warns once and calls it.
+ *
+ * `compile()` also refuses an `overrideGuard`, `overrideInterceptor` or `overrideFilter` stub without the stage's
+ * method, `canActivate`, `intercept` or `catch`; without strict mocks, it warns and builds the module.
  *
  * @throws Error when a mock already exists, which was made without it.
  *
@@ -1756,9 +1889,11 @@ declare function createModalFields(values: Record<string, string | string[] | At
  *
  * Use it in a test for a team that wants no fallback in production. It reports the messages a locale lacks, the
  * messages the default catalog doesn't have, the plural forms a language needs but a plural lacks, such as `few` for
- * Russian, and each `{param}` a translation uses that the message it translates doesn't take. It reads the catalogs'
- * own strings, so it checks the params of a catalog from a plain variable or a JSON file too, which the compiler
- * can't.
+ * Russian, a translation of another shape than the default's, a text for a plural or a plural for a text, and each
+ * `{param}` a translation uses that the message it translates doesn't take. An empty translation, `''`, counts as
+ * lacking, as the translator reads it as missing. It reads the catalogs' own strings, so it checks the params of a
+ * catalog from a plain variable or a JSON file too, which the compiler can't. An object counts as a plural only when
+ * its every key is a plural category, so a group with an `other` key is a group.
  *
  * @remarks
  * MeoCord's own texts, a catalog's `meocord` group, fall back to English by design, so only a key MeoCord lacks, and
@@ -1827,8 +1962,9 @@ interface CooldownStoreSuiteFramework {
  *
  * @remarks
  * The cases cover what a shared store most often gets wrong: a sliding window rather than fixed buckets,
- * `retryAfterMs` from the oldest call still in the window, calls in the same millisecond kept apart, and concurrent
- * calls at the limit where exactly one may pass. They use real time, with windows short enough that the suite takes
+ * `retryAfterMs` until a use frees up, from the oldest of the newest `uses` calls in the window, calls in the same
+ * millisecond kept apart, concurrent calls at the limit where exactly one may pass, a batch refusal that names the
+ * longest wait, and a release that frees only the call it gave back. They use real time, with windows short enough that the suite takes
  * a few seconds and margins wide enough that a correct store passes when timers fire late, as on a busy CI runner,
  * and each case counts under keys of its own. Each window is a whole number of milliseconds, as
  * `@Cooldown` gives a store: it rounds its `seconds` to the millisecond.
@@ -2226,4 +2362,4 @@ declare function createMockTheme(...[overrides]: MockThemeArgs): DeepReadonly<Me
 declare function withTheme<T>(theme: DeepReadonly<MeoCordTheme> | RootTheme, fn: () => T): T;
 
 export { MeoCordTestingModule, Provider, ProviderToken, TestingModule, TestingModuleBuilder, clearAllMocks, createChatInputOptions, createDiscordError, createExecutionContext, createMock, createMockChannel, createMockClient, createMockFn, createMockGuild, createMockInteraction, createMockMember, createMockMessage, createMockRawMember, createMockTheme, createMockUser, createModalFields, expectCompleteCatalog, findRouteConflicts, getResponse, inspectHandler, isMockFunction, reportAllStartupErrors, resetAllMocks, resolveRoute, testCooldownStore, useMockFn, useStrictMocks, withTheme };
-export type { ChatInputOptions, ComponentCommandType, CooldownStoreSuiteFramework, DeepMocked, DispatchedCall, DispatchedHandler, EmitResult, ExecutionContextOptions, FromAppOptions, HandlerInspection, HandlerName, InspectHandlerOptions, InspectedCooldown, InspectedFilter, InspectedGuard, InspectedInterceptor, InvocationResult, MessageToResolve, Mock, MockFnFactory, MockGuildOverrides, MockInstance, MockMemberOverrides, MockMessageOverrides, MockProps, MockRawMemberOverrides, MockResult, MockState, MockedFunction, ResolvedRoute, ResponseReport, RouteConflict, RunnerMock, TestingModuleInitOptions, TestingModuleOptions };
+export type { ChatInputOptions, ComponentCommandType, CooldownStoreSuiteFramework, DeepMocked, DispatchedCall, DispatchedHandler, EmitResult, ExecutionContextOptions, FromAppOptions, HandlerInspection, HandlerName, InspectHandlerOptions, InspectedCooldown, InspectedFilter, InspectedGuard, InspectedInterceptor, InvocationResult, MessageToResolve, Mock, MockFnFactory, MockGuildOverrides, MockInstance, MockMemberOverrides, MockMessageOverrides, MockProps, MockRawMemberOverrides, MockResult, MockSettledResult, MockState, MockedFunction, ResolvedRoute, ResponseReport, RouteConflict, RunnerMock, TestingModuleInitOptions, TestingModuleOptions };

package/dist/types/{theme-resolvers-UKr3-6Ys.d.cts → theme-resolvers-CyEz9pnv.d.cts}

@@ -1,4 +1,4 @@
-import './index-nn5p7OoX.cjs';
+import './index-Dlf0ZZtS.cjs';
 
 /**
  * An app's cache of the themes `@MeoCord({ themeFor })` looked up, by server and by user.

package/dist/types/{theme-resolvers-BcOJVzR9.d.ts → theme-resolvers-DA204O-q.d.ts}

@@ -1,4 +1,4 @@
-import './index-CdXsFgjE.js';
+import './index-DKJclIi-.js';
 
 /**
  * An app's cache of the themes `@MeoCord({ themeFor })` looked up, by server and by user.

package/dist/types/{translator-DHMkkCpg.d.cts → translator-Bg7hwxDF.d.cts}

@@ -1,5 +1,5 @@
 import { Locale, Interaction, Guild } from 'discord.js';
-import { aq as MeoCordMessages } from './index-nn5p7OoX.cjs';
+import { aq as MeoCordMessages } from './index-Dlf0ZZtS.cjs';
 
 /**
  * The plural categories `Intl.PluralRules` selects between.
@@ -33,10 +33,13 @@ type IsPlural<T> = T extends object ? [Exclude<keyof T, PluralCategory>] extends
 /**
  * Every message key of a catalog: the dotted path to each message or plural.
  *
+ * A key with a `.` in its own name is left out, as a lookup reads it as a path and never finds it; `createTranslator`
+ * warns about one. Nest it as a group.
+ *
  * @group Types
  */
 type MessageKey<C> = {
-    [K in keyof C & string]: C[K] extends string ? K : IsPlural<C[K]> extends true ? K : `${K}.${MessageKey<C[K]>}`;
+    [K in keyof C & string]: K extends `${string}.${string}` ? never : C[K] extends string ? K : IsPlural<C[K]> extends true ? K : `${K}.${MessageKey<C[K]>}`;
 }[keyof C & string];
 /**
  * The keys whose message is a single string rather than plural forms, with or without `{params}`.
@@ -45,7 +48,7 @@ type MessageKey<C> = {
  * @see {@link LocalizationKey}
  */
 type StringMessageKey<C> = {
-    [K in keyof C & string]: C[K] extends string ? K : IsPlural<C[K]> extends true ? never : `${K}.${StringMessageKey<C[K]>}`;
+    [K in keyof C & string]: K extends `${string}.${string}` ? never : C[K] extends string ? K : IsPlural<C[K]> extends true ? never : `${K}.${StringMessageKey<C[K]>}`;
 }[keyof C & string];
 /**
  * The keys {@link Translator.localizations} takes: a single string with no `{params}`, since Discord shows a command's
@@ -105,12 +108,17 @@ type Translate<C> = <K extends MessageKey<C>>(key: K, ...params: ParamsArgs<Mess
  * Its messages may use only the `{params}` the default's take: `createTranslator` checks that for a catalog that keeps
  * its text, and `expectCompleteCatalog` for any.
  *
- * A message it leaves out falls back to a related locale, then to the default.
+ * A message it leaves out falls back to a related locale, then to the default. Its `meocord` group translates MeoCord's
+ * own texts.
  *
  * @group Types
  */
-type LocaleCatalog<C> = {
-    readonly [K in keyof C]?: C[K] extends string ? string : IsPlural<C[K]> extends true ? PluralMessage : LocaleCatalog<C[K]>;
+type LocaleCatalog<C> = LocaleMessages<C> & {
+    readonly meocord?: LocaleMessages<MeoCordMessages>;
+};
+/** Any part of a catalog, in a locale's own wording. */
+type LocaleMessages<C> = {
+    readonly [K in keyof C]?: C[K] extends string ? string : IsPlural<C[K]> extends true ? PluralMessage : LocaleMessages<C[K]>;
 };
 /**
  * What is wrong with a catalog's `meocord` group, one message per mistake: a key MeoCord has no text for, a group where
@@ -266,8 +274,13 @@ declare abstract class Translator<C = CatalogShape> {
     /**
      * A message in every locale other than the default whose own catalog has it, for a builder's
      * `setNameLocalizations` or `setDescriptionLocalizations`. Locales without it are left out, so
-     * Discord falls back to the default name for them, and so is a translation with a `{param}`, which
-     * `expectCompleteCatalog` reports.
+     * Discord falls back to the default name for them, and so are an empty translation and a translation
+     * with a `{param}`, which `expectCompleteCatalog` reports.
+     *
+     * Discord shows en-US users the en-GB value, en-GB users the en-US one, and es-419 users the es-ES one,
+     * when their own locale has none. So when the default is en-US, en-GB or es-419 and its partner is in
+     * the result, the default's own message is added under the default's key, and its users keep the default
+     * wording.
      *
      * @param key - A plain message key without `{params}`: Discord shows a name or description as written, and has no
      *   plural forms for it.