meocord 4.2.1 → 4.2.2

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

@@ -684,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
@@ -796,7 +797,8 @@ interface MockState<T extends (...args: any[]) => any = (...args: any[]) => any>
  * 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
@@ -838,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
@@ -1103,7 +1108,10 @@ type NotRaw<T> = T extends {
  * 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
+ * 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.
  *
@@ -1295,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.
@@ -1305,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
@@ -1616,8 +1627,9 @@ declare function createChatInputOptions<Cached extends CacheType = any>(opts?: C
  * 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`, and a reaction has a whole message of its own, so
- * MeoCord's dispatcher fetches neither. No placeholder warning is logged.
+ * `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
@@ -1630,8 +1642,10 @@ declare function createChatInputOptions<Cached extends CacheType = any>(opts?: C
  * 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. The next major version (5.0)
- * computes these values, and refuses those answers, without the call.
+ * `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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "meocord",
   "description": "Decorator-based framework for Discord bots on discord.js, with dependency injection, guards, a CLI and a testing toolkit.",
-  "version": "4.2.1",
+  "version": "4.2.2",
   "type": "module",
   "engines": {
     "node": ">=22.13"