meocord 4.2.2 → 4.2.3

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

@@ -1,12 +1,68 @@
 import { CooldownStore } from '../common/index.js';
 import { BuildableCommandType, CommandBuilderOptions, CommandBuilderBase, PIPED_BRAND, CommandBuilderConstructor, CommandInteractionType, MessageHandlerOptions, CheckedParams, ReactionHandlerSettings, ReactionEvent, ControllerOptions, StageParams, GuardOptions, GuardInterface, InterceptorOptions, InterceptorInterface, ExceptionFilter, Provider, CooldownStoreFailure, ResponsePresenter, MessageCommandOptions, DispatchObserver, RootTheme, ThemeResolvers, ThemeResolver, PipeInterface, StandardSchemaV1, ValidatePipes, ValidateOptions, InferSchemaOutput, CooldownOptions, ProviderToken, ObserverOptions, ThemeOverride } from '../interface/index.js';
-import { AutocompleteInteraction, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, ChannelSelectMenuInteraction, MentionableSelectMenuInteraction, OmitPartialGroupDMChannel, Message, MessageReaction, PartialMessageReaction, ClientEvents, ClientOptions, ActivityOptions } from 'discord.js';
+import { ClientEvents, AutocompleteInteraction, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, ChannelSelectMenuInteraction, MentionableSelectMenuInteraction, OmitPartialGroupDMChannel, Message, MessageReaction, PartialMessageReaction, ClientOptions, ActivityOptions } from 'discord.js';
 import { CommandType } from '../enum/index.js';
 import { Route, RouteParams, RouteValues, RouteValue } from '../common/index.js';
 import { ServiceIdentifier } from 'inversify';
 import { Translator } from '../common/index.js';
 import '@rsbuild/core';
 
+/**
+ * Handles a discord.js client event every time it is emitted, on a controller or a service.
+ *
+ * Use it for gateway events MeoCord has no handler type for, such as a member joining or a channel being
+ * created. For commands, components, messages and reactions, use {@link Command}, `@MessageHandler` or
+ * `@ReactionHandler`, which route them.
+ *
+ * @remarks
+ * The handler's parameters are typed from discord.js's `ClientEvents`. It runs through the pipeline, so the app's
+ * global guards apply to it, and its class's and its own, and an error it throws is logged without stopping the bot. Handling `interactionCreate`
+ * or `messageCreate` here runs alongside MeoCord's own dispatch of them.
+ *
+ * @param event - The client event to handle, such as `'guildMemberAdd'`.
+ *
+ * @example
+ * ```ts
+ * @On('guildMemberAdd')
+ * async greet(member: GuildMember) {
+ *   await member.send(`Welcome to ${member.guild.name}!`)
+ * }
+ * ```
+ *
+ * @pipeline handler with the guards, interceptors and filters that apply to events: the app's global ones, its class's and its own
+ * @group Decorators
+ * @category Handlers
+ * @see {@link Once}
+ * @see {@link https://meocord.dev/docs/4.2/gateway-events | Gateway events}
+ */
+declare function On<E extends keyof ClientEvents>(event: E): <F extends (...args: ClientEvents[E]) => unknown>(target: object, propertyKey: string, _descriptor: TypedPropertyDescriptor<F>) => void;
+/**
+ * Handles a discord.js client event the first time it is emitted only, on a controller or a service.
+ *
+ * Use it for one-off work on an event, such as warming a cache once the client is ready. For every emission,
+ * use {@link On}; for work at startup and shutdown, a service's `onReady` and `onShutdown` hooks.
+ *
+ * @param event - The client event to handle, such as `'clientReady'`.
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * export class CacheWarmer {
+ *   @Once('clientReady')
+ *   async warm(client: Client<true>) {
+ *     await client.guilds.fetch()
+ *   }
+ * }
+ * ```
+ *
+ * @pipeline handler with the guards, interceptors and filters that apply to events: the app's global ones, its class's and its own
+ * @group Decorators
+ * @category Handlers
+ * @see {@link On}
+ * @see {@link https://meocord.dev/docs/4.2/gateway-events | Gateway events}
+ */
+declare function Once<E extends keyof ClientEvents>(event: E): <F extends (...args: ClientEvents[E]) => unknown>(target: object, propertyKey: string, _descriptor: TypedPropertyDescriptor<F>) => void;
+
 /**
  * Marks a class as a service, which controllers and other services inject by its type.
  *
@@ -424,62 +480,6 @@ declare function Autocomplete<_R = unknown>(commandPath: string, optionName?: st
  */
 declare function Controller(options?: ControllerOptions): (target: abstract new (...args: any[]) => unknown, propertyKey?: string | symbol) => void;
 
-/**
- * Handles a discord.js client event every time it is emitted, on a controller or a service.
- *
- * Use it for gateway events MeoCord has no handler type for, such as a member joining or a channel being
- * created. For commands, components, messages and reactions, use {@link Command}, `@MessageHandler` or
- * `@ReactionHandler`, which route them.
- *
- * @remarks
- * The handler's parameters are typed from discord.js's `ClientEvents`. It runs through the pipeline, so the app's
- * global guards apply to it, and its class's and its own, and an error it throws is logged without stopping the bot. Handling `interactionCreate`
- * or `messageCreate` here runs alongside MeoCord's own dispatch of them.
- *
- * @param event - The client event to handle, such as `'guildMemberAdd'`.
- *
- * @example
- * ```ts
- * @On('guildMemberAdd')
- * async greet(member: GuildMember) {
- *   await member.send(`Welcome to ${member.guild.name}!`)
- * }
- * ```
- *
- * @pipeline handler with the guards, interceptors and filters that apply to events: the app's global ones, its class's and its own
- * @group Decorators
- * @category Handlers
- * @see {@link Once}
- * @see {@link https://meocord.dev/docs/4.2/gateway-events | Gateway events}
- */
-declare function On<E extends keyof ClientEvents>(event: E): <F extends (...args: ClientEvents[E]) => unknown>(target: object, propertyKey: string, _descriptor: TypedPropertyDescriptor<F>) => void;
-/**
- * Handles a discord.js client event the first time it is emitted only, on a controller or a service.
- *
- * Use it for one-off work on an event, such as warming a cache once the client is ready. For every emission,
- * use {@link On}; for work at startup and shutdown, a service's `onReady` and `onShutdown` hooks.
- *
- * @param event - The client event to handle, such as `'clientReady'`.
- *
- * @example
- * ```ts
- * @Service()
- * export class CacheWarmer {
- *   @Once('clientReady')
- *   async warm(client: Client<true>) {
- *     await client.guilds.fetch()
- *   }
- * }
- * ```
- *
- * @pipeline handler with the guards, interceptors and filters that apply to events: the app's global ones, its class's and its own
- * @group Decorators
- * @category Handlers
- * @see {@link On}
- * @see {@link https://meocord.dev/docs/4.2/gateway-events | Gateway events}
- */
-declare function Once<E extends keyof ClientEvents>(event: E): <F extends (...args: ClientEvents[E]) => unknown>(target: object, propertyKey: string, _descriptor: TypedPropertyDescriptor<F>) => void;
-
 /**
  * One entry of `@UseGuard`, `@UseInterceptor`, `@UseFilter`, `@UsePipe` or `@MeoCord`'s lists, checked
  * against the class it provides: `params` against the params the class declares. An entry typed only as
@@ -735,8 +735,8 @@ declare function UseFilter<const T extends readonly unknown[]>(...filters: {
  * @see {@link MeoCordConfig}
  */
 interface MeoCordOptions<G extends readonly unknown[] = readonly unknown[], I extends readonly unknown[] = readonly unknown[], F extends readonly unknown[] = readonly unknown[]> {
-    /** Controllers to register. */
-    controllers: ServiceIdentifier[];
+    /** Controllers to register: their classes. */
+    controllers: (abstract new (...args: any[]) => any)[];
     /**
      * Options for the discord.js `Client`, such as its intents and partials. The shards it runs as are set in
      * `meocord.config.ts`, under `sharding`.
@@ -835,10 +835,10 @@ interface MeoCordOptions<G extends readonly unknown[] = readonly unknown[], I ex
     /**
      * Themes by where a call comes from: `guild` for a server's, over the handler's, and `user` for a user's, over the
      * server's, in a server or a DM. Each returns part of a theme or `undefined`, at once or as a promise, and is looked
-     * up while `@Defer` acknowledges, before the guards. A result that is not a valid theme is left out, with a warning
-     * once per server or user; a resolver that fails or passes its timeout leaves its theme out of the call, logged once
-     * until it answers again. A class implementing {@link ThemeResolver} does the same with the app's services, resolved
-     * from its container.
+     * up while `@Defer` acknowledges, before the guards. A result that is not a valid theme, as is one that cannot be
+     * read, such as an object with a cycle or a getter that throws, is left out, with a warning once per server or user;
+     * a resolver that fails or passes its timeout leaves its theme out of the call, logged once until it answers again.
+     * A class implementing {@link ThemeResolver} does the same with the app's services, resolved from its container.
      */
     themeFor?: ThemeResolvers | (new (...args: any[]) => ThemeResolver);
     /**

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

@@ -307,9 +307,10 @@ interface ResponseSendOptions {
  */
 interface ResponseCall {
     /**
-     * The Discord method it used; `message.edit` edits the message itself, once the interaction's token has expired.
+     * The Discord method it used; `respond` answers an autocomplete with its choices, and `message.edit` edits the message
+     * itself, once the interaction's token has expired.
      */
-    method: 'deferReply' | 'deferUpdate' | 'reply' | 'update' | 'editReply' | 'followUp' | 'deleteReply' | 'showModal' | 'message.edit';
+    method: 'deferReply' | 'deferUpdate' | 'reply' | 'update' | 'editReply' | 'followUp' | 'deleteReply' | 'showModal' | 'launchActivity' | 'sendPremiumRequired' | 'respond' | 'message.edit';
     /** What was sent, as that method received it; none for a deferral or a deletion. */
     payload?: unknown;
     /** What the call rejected with, such as the `DiscordAPIError` for a refused call; absent when it succeeded. */
@@ -794,7 +795,8 @@ declare abstract class ExecutionContext {
     /**
      * The response state of the interaction being handled, the same one `respond(interaction)` returns,
      * or `undefined` for anything that cannot be answered: a message, a reaction, an event or
-     * autocomplete.
+     * autocomplete. An `@On('interactionCreate')` handler's call has none either, as MeoCord answers that interaction
+     * through the handler it dispatches it to.
      */
     get response(): ResponseState | undefined;
     /**
@@ -834,11 +836,19 @@ declare abstract class ExecutionContext {
      * {@link ExecutionContext.getHandlerParams} returns.
      */
     abstract getArgs(): readonly unknown[];
-    /** The interaction being handled, or `undefined` for a message, reaction or event. */
+    /**
+     * The interaction being handled, or `undefined` for a message or a reaction. For an event, the interaction it
+     * carries, as `@On('interactionCreate')` does; `undefined` for any other event.
+     */
     abstract getInteraction(): Interaction | undefined;
-    /** The message being handled, or `undefined` for anything else. */
+    /**
+     * The message being handled, or an event's first argument when it is a message, as in `@On('messageCreate')`;
+     * `undefined` for anything else, a reaction's message included. For `@On('messageUpdate')`, that is the message as it
+     * was before the edit, which may be partial; the edited one is the event's second argument, from
+     * {@link ExecutionContext.getArgs}.
+     */
     abstract getMessage(): Message | undefined;
-    /** The reaction being handled, or `undefined` for anything else. */
+    /** The reaction being handled, or the one an event carries; `undefined` for anything else. */
     abstract getReaction(): MessageReaction | PartialMessageReaction | undefined;
     /** What is being handled: an interaction, an autocomplete request, a message, a reaction or an event. */
     abstract getType(): ExecutionContextType;
@@ -1099,7 +1109,8 @@ interface CooldownVerdict {
      * With a refusal, when the next call is allowed, as a Unix timestamp in milliseconds on the store's own clock. Every
      * refusal in one wait gives the same one, so `messages.dmOnCooldown` tells one wait from the next by it, across
      * processes and however late the answer arrives. The built-in stores give it; a store without it is told apart by
-     * `retryAfterMs` and the bot's clock instead.
+     * `retryAfterMs` and the bot's clock instead. Their `consume`, and the default `consumeMany` of a store that asks it,
+     * give it as a non-enumerable property, so their verdicts compare and serialise without it.
      */
     retryTimestamp?: number;
 }
@@ -1684,8 +1695,9 @@ interface DispatchResult {
      */
     durationMs: number;
     /**
-     * The guard class that denied the call, whether it returned `false` or threw `GuardDeniedError`.
-     * Only with the outcome `'denied'`, and not for a `GuardDeniedError` the handler threw itself.
+     * The guard class that denied the call, whether it returned `false` or threw `GuardDeniedError`. With the outcome
+     * `'denied'`, or `'error'` when the answer to a guard's `GuardDeniedError` failed to build; not for a
+     * `GuardDeniedError` the handler threw itself.
      */
     deniedBy?: abstract new (...args: any[]) => unknown;
     /**
@@ -1781,8 +1793,11 @@ type StageParams<C extends abstract new (...args: any[]) => unknown> = 'params'
 interface GuardOptions {
     /**
      * The context types the guard runs for, as `ExecutionContext.getType()` reports them; it is skipped for
-     * any other call. A subclass inherits them unless it declares its own. A global guard also runs before
-     * `@On` handlers, so one that reads an interaction declares `['interaction']`.
+     * any other call. An autocomplete is its own type, `'autocomplete'`, so a guard limited to `'interaction'`
+     * doesn't run before `@Autocomplete` handlers. A subclass inherits them unless it declares its own. A global
+     * guard also runs before `@On` handlers, so one that reads an interaction declares `['interaction']`, or
+     * `['interaction', 'autocomplete']` to run before autocomplete handlers too. A guard that runs before an
+     * autocomplete answers nothing there: return `false` to show no choices.
      *
      * @defaultValue every type
      */
@@ -2108,10 +2123,11 @@ interface MeoCordApplication {
      * every shard would meet, MeoCord refusing the app or Discord refusing the login for good (an invalid token, or
      * intents it disallows or does not know), the manager logs why, stops every shard and exits 1 instead.
      *
-     * @returns A promise that resolves once the bot is logged in, or every shard has been spawned.
-     * @throws For a bot in one process, the error of a provider's factory that failed, or the login
-     *   error, such as an invalid token. A start that `stop()` ends rejects, and so does a start of an app already
-     *   stopped.
+     * @returns A promise that resolves once the bot is logged in, or every shard has been spawned. With process
+     *   sharding, it also resolves when `stop()` ends the start, which then spawns no more shards.
+     * @throws For a bot in one process, the error of a provider's factory that failed, or the login error, such as an
+     *   invalid token; it also rejects when `stop()` ends the start. In either mode, a start of an app already stopped
+     *   rejects.
      */
     start(): Promise<void>;
     /**
@@ -2122,7 +2138,8 @@ interface MeoCordApplication {
      * 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.
+     * nothing more is made after it. What the start made is shut down by the rule {@link OnShutdown} gives. 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.
@@ -2131,6 +2148,10 @@ interface MeoCordApplication {
     /**
      * Registers the application's commands with Discord, where `meocord.config.ts`'s `commands` says.
      * A failure is logged rather than thrown.
+     *
+     * For a bot in one process, it needs the bot online, as the application comes from the login; called earlier, it
+     * logs a warning and registers nothing. With process sharding, the manager registers over REST, before or after
+     * `start()`.
      */
     registerCommands(): Promise<void>;
 }
@@ -2197,17 +2218,25 @@ interface OnReady {
  * Implement it to stop what {@link OnReady} started: timers, open connections, writes still buffered.
  *
  * @remarks
- * Called when the bot stops, on SIGINT or SIGTERM or through `app.stop()`, before the client is destroyed, and only
- * if `onReady` hooks ran. Hooks run one at a time in reverse dependency order, so a service stops before the services
- * 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 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
+ * Called when the bot stops, on SIGINT or SIGTERM or through `app.stop()`, before the client is destroyed, and when
+ * its start fails. Hooks run one at a time in reverse dependency order, so a service stops before the services 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 for each class and provided value the bot has made whose `onReady`, and that of everything it depends on,
+ * has finished or doesn't exist. So a provided value with no `onReady`, such as a connection pool, is closed on any
+ * stop once it is made, one during startup included, while a class whose `onReady` never ran is not shut down, nor is
+ * anything that depends on it. A stop while the ready hooks are running waits for the `onReady` in progress, within
+ * `shutdownTimeout`, then shuts that class down too, 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.
  *
+ * A start that fails, because a provider's factory or the login failed, shuts down what it made by the same rule, so
+ * the process can end with its exit code. A value the app gave with `useValue` is left open: a retry of `start()` makes
+ * the rest again, and once the bot stops, by `app.stop()`, a Ctrl+C or a SIGTERM, the value is shut down by the same
+ * rule, which leaves out one with an `onReady` a failed start never ran. A stop while a failed start shuts down waits
+ * for that shutdown, all within one `shutdownTimeout`.
+ *
  * @example
  * ```ts
  * import { appendFile } from 'node:fs/promises'
@@ -2646,7 +2675,8 @@ interface MessageCommandOptions {
     types?: Record<string, MessageParamType>;
     /**
      * How long a reply showing a command's usage, or a guard's or validation's reason, stays before it is deleted, in
-     * seconds. `0` keeps it.
+     * seconds. `0` keeps it, and so does a time longer than a timer can wait, 2147483 seconds (about 24.8 days), which
+     * startup warns about.
      * @defaultValue `10`
      */
     deleteUsageRepliesAfter?: number;
@@ -2787,7 +2817,7 @@ interface MessageHelpEntry {
     description?: string;
     /** Its aliases and other spellings, as the caller types them, such as `!m`. */
     aliases: string[];
-    /** Where it works; a command with a `member`, `role` or `channel` param works in servers only. */
+    /** Where it works; a command with a `member`, `role` or `channel` param, or required flag, works in servers only. */
     scope: MessageScope;
     /** Each param and flag, with what it takes. */
     params: MessageHelpParam[];
@@ -2902,7 +2932,10 @@ interface MessageParamTypes {
     member: GuildMember;
     /** A user, by mention or ID. */
     user: User;
-    /** A role of the message's server, by mention, ID or name. */
+    /**
+     * A role of the message's server, by mention, ID or name; an optional one that another optional param follows
+     * takes a mention or an ID only.
+     */
     role: Role;
     /** A channel of the message's server, by mention or ID. */
     channel: GuildBasedChannel;
@@ -2940,8 +2973,11 @@ interface EntityRef<T> {
     /** Fetches the entity, once however many callers ask at the same time; `undefined` when there is none. */
     resolve(): Promise<T | undefined>;
 }
-/** Splits a pattern into its words, at most 16 of them, so the checker's work stays small. */
-type PatternWords<S extends string, Acc extends string[] = []> = Acc['length'] extends 16 ? Acc : S extends `${infer Word} ${infer Rest}` ? PatternWords<Rest, Word extends '' ? Acc : [...Acc, Word]> : S extends '' ? Acc : [...Acc, S];
+/**
+ * Splits a pattern into its words. Each word is one step of tail recursion, with the words found so far in `Acc`, so a
+ * pattern may hold about 1,000 of them.
+ */
+type PatternWords<S extends string, Acc extends string[] = []> = S extends `${infer Word} ${infer Rest}` ? PatternWords<Rest, Word extends '' ? Acc : [...Acc, Word]> : S extends '' ? Acc : [...Acc, S];
 /**
  * The value a param's type gives: a named type, or one of the words `a|b` lists. An app's type not declared
  * in {@link MessageParamTypes} is not checked.
@@ -3099,8 +3135,9 @@ interface MessageHandlerOptions {
     description?: string;
     /**
      * Where the command works; `'any'` by default. A message sent elsewhere gets a usage reply saying
-     * where it works, and the handler does not run. A command with a `member`, `role` or `channel` param
-     * works in servers only; `'dm'` with one is refused as the bot starts.
+     * where it works, and the handler does not run. A command with a `member`, `role` or `channel` param, or a required
+     * flag of one of those types, works in servers only; `'dm'` with one, or with an optional such flag, is refused as the
+     * bot starts. An optional flag of those types refuses a DM only when the message gives it.
      */
     scope?: MessageScope;
     /**
@@ -3182,8 +3219,13 @@ interface MeoCordConfig {
     rsbuild?: (config: RsbuildConfig) => RsbuildConfig | undefined;
     /**
      * Makes stack traces name your source files, lines and columns, from the source map the build writes
-     * beside `dist/main.js`. Under Node, `meocord start` passes `--enable-source-maps`; under Bun, or Node
-     * started without the flag, the bundle maps each stack through `Error.prepareStackTrace` itself.
+     * beside `dist/main.js`. Under Node, `meocord start` passes `--enable-source-maps`; started without the
+     * flag, the bundle maps each stack through `Error.prepareStackTrace` itself. Either way every trace Node
+     * prints is mapped.
+     *
+     * Under Bun, the bundle maps `error.stack`, and so each trace MeoCord's `Logger` prints. What Bun prints
+     * itself, for an uncaught error, an unhandled rejection or `console.error(error)` before `error.stack` is
+     * read, keeps the bundle's positions.
      *
      * Set `false` for an error tracker that applies uploaded source maps to the bundle's positions, or a
      * source mapper of your own.
@@ -3355,7 +3397,11 @@ interface CommandBuilderOptions {
      * empty after dropping blank ids is not registered at all, rather than falling back to global. Under a
      * development server, it goes there with every other command.
      *
-     * @defaultValue the configured scope
+     * A builder that extends another and gives no `guilds` inherits its base's, with a warning when it is decorated: declare
+     * `guilds` on the subclass to keep them. The next major version (5.0) registers such a builder's command in the
+     * configured scope.
+     *
+     * @defaultValue the configured scope, or the guilds of the builder it extends
      */
     guilds?: (string | undefined)[];
 }