meocord 4.0.0-beta.3 → 4.0.0-beta.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # meocord
 
+## 4.0.0-beta.4
+
+### Major Changes
+
+- [#44](https://github.com/l7aromeo/meocord/pull/44) [`e48472e`](https://github.com/l7aromeo/meocord/commit/e48472e9ffee2f0371a7a2a71a4063e99ce61674) Thanks [@l7aromeo](https://github.com/l7aromeo)! - **Breaking:** `meocord/decorator` exports only the decorators. The routing helpers it also exported
+  — `getCommandMap`, `getMessageHandlers`, `getReactionHandlers`, `getAutocompleteHandlers`,
+  `findAmbiguousRoutes` and `PARAM_SEPARATOR` — are internal to MeoCord now. See the
+  [migration guide](https://github.com/l7aromeo/meocord/blob/main/docs/MIGRATING.md#internal-helpers-are-no-longer-exported).
+
 ## 4.0.0-beta.3
 
 ### Patch Changes

package/README.md

@@ -273,7 +273,9 @@ See [Self-contained builds](#self-contained-builds) for when to turn on `bundleD
 
 ### ESLint
 
-MeoCord exports a base ESLint config from `meocord/eslint`. Extend it as needed:
+MeoCord exports a base ESLint config from `meocord/eslint`. It lints your TypeScript, `meocord.config.ts`
+included, with type information from `tsconfig.json`, `tsconfig.test.json` and `tsconfig.eslint.json`; a
+file ESLint reports as not included in any of them needs listing in one. Extend it as needed:
 
 ```javascript
 import meocordEslint, { typescriptConfig } from 'meocord/eslint'

package/dist/cjs/_shared/{controller.decorator-9nIxOp9y.cjs → controller.decorator-CqgGgjj3.cjs}

@@ -3,18 +3,12 @@
 require('reflect-metadata');
 var inversify = require('inversify');
 var enum_index = require('../enum/index.cjs');
-var metadataKey_enum = require('./metadata-key.enum-aABGdodb.cjs');
+var metadataKey_enum = require('./metadata-key.enum-DG7cVMc4.cjs');
 var discord_js = require('discord.js');
 
 /**
- * The discord.js class each command type is handled by.
- *
- * One table rather than a chain of `isButton() || isStringSelectMenu() || ...`: the
- * registration guard in `@Command`, the dispatcher, and the type-level
- * `CommandInteractionType` all have to agree on what a command type accepts, and a
- * chain repeated in three files drifts the moment a fifth select menu appears. Adding
- * a `CommandType` member without an entry here is a compile error, not a silent
- * fall-through to "Command not found!".
+ * The discord.js class check for each command type, shared by `@Command`, the dispatcher and
+ * `CommandInteractionType`. A `CommandType` without an entry here fails to compile.
  */ const INTERACTION_MATCHERS = {
     [enum_index.CommandType.SLASH]: (interaction)=>interaction instanceof discord_js.ChatInputCommandInteraction,
     [enum_index.CommandType.CONTEXT_MENU]: (interaction)=>interaction instanceof discord_js.ContextMenuCommandInteraction,
@@ -32,47 +26,24 @@ var discord_js = require('discord.js');
     enum_index.CommandType.CONTEXT_MENU,
     enum_index.CommandType.PRIMARY_ENTRY_POINT
 ]);
-/**
- * Whether an interaction is the kind the given command type handles.
- *
- * @param type - The command type declared on `@Command`.
- * @param interaction - The interaction being dispatched.
- */ function matchesCommandType(type, interaction) {
+/** Whether an interaction is the kind the given command type handles. */ function matchesCommandType(type, interaction) {
     const matches = INTERACTION_MATCHERS[type];
     return matches !== undefined && matches(interaction);
 }
 /**
- * Whether the command type is routed by matching a customId pattern.
- *
- * Components carry an application-defined customId and so are matched by pattern;
- * commands carry a name Discord itself registered and are matched exactly.
- *
- * @param type - The command type declared on `@Command`.
+ * Whether a command type is routed by customId pattern: components carry an application-defined
+ * customId, while commands are matched by the name Discord registered.
  */ function isCustomIdRouted(type) {
     return !NAME_ROUTED_TYPES.has(type);
 }
-/**
- * Whether an interaction carries a customId, and so can be routed by pattern.
- *
- * @param interaction - The interaction being dispatched.
- */ function hasCustomId(interaction) {
+/** Whether an interaction carries a customId, and so can be routed by pattern. */ function hasCustomId(interaction) {
     return interaction instanceof discord_js.MessageComponentInteraction || interaction instanceof discord_js.ModalSubmitInteraction;
 }
 /** Separates a command from its subcommand group and subcommand in a route key. */ const COMMAND_PATH_SEPARATOR = ' ';
 /**
- * The route keys a chat input interaction can be handled by, most specific first.
- *
- * Discord sends `/settings notify email` as one interaction named `settings`, so
- * routing on `commandName` alone gives every subcommand of a command the same handler
- * — and the framework would run whichever one was declared first. The full path is
- * tried before the bare name so a command can either split its subcommands across
- * methods or keep handling them in one, but never both by accident.
- *
- * A group is never dropped on the way down: `settings notify email` does not fall back
- * to `settings email`, because a second group could declare its own `email` and the
- * two would be indistinguishable.
- *
- * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * The route keys a chat input interaction can be handled by, most specific first:
+ * `settings notify email`, then `settings`. Discord names the whole interaction `settings`, so the
+ * full path comes first; a group is never skipped, since two groups may share a subcommand name.
  * @returns The keys to look up, most specific first.
  */ function resolveCommandPaths(interaction) {
     const { commandName } = interaction;
@@ -99,24 +70,14 @@ var discord_js = require('discord.js');
     discord_js.ApplicationCommandOptionType.SubcommandGroup
 ]);
 /**
- * The value a handler should receive for one option.
- *
- * Discord sends entity options as a snowflake plus a `resolved` payload, and discord.js
- * puts that payload on the option as `user`/`role`/`channel`/`attachment`. Passing
- * `value` alone would hand the handler a bare id string for `@user`, forcing every
- * handler to re-fetch what the gateway already delivered.
+ * The value a handler receives for one option: the resolved user, role, channel or attachment
+ * discord.js attaches, rather than a bare snowflake to re-fetch.
  */ function resolveOptionValue(option) {
     return option.attachment ?? option.channel ?? option.role ?? option.user ?? option.member ?? option.value;
 }
 /**
- * Flattens a chat input interaction's options into the params record handlers receive.
- *
- * Subcommand and subcommand-group options are containers, not values — for
- * `/settings notify email true` the top level holds only `notify`. Recursing past them
- * means a subcommand handler sees `{ email: true }`, the same shape a flat command's
- * handler sees.
- *
- * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * Flattens an interaction's options into the params record handlers receive, looking through
+ * subcommand and group containers, so `/settings notify email true` yields `{ email: true }`.
  * @returns Each supplied option keyed by name, with entity options resolved.
  */ function resolveOptionParams(interaction) {
     const data = interaction.options?.data;
@@ -135,14 +96,8 @@ var discord_js = require('discord.js');
     return params;
 }
 /**
- * The name of the option the user is currently typing, or `undefined`.
- *
- * `getFocused` throws when nothing is focused rather than returning null, and it is
- * absent altogether on a hand-built test double. Neither is worth failing a dispatch
- * over — an autocomplete with no focused option simply matches no option-specific
- * handler.
- *
- * @param interaction - The autocomplete interaction being dispatched.
+ * The name of the option the user is typing, or undefined when nothing is focused; `getFocused`
+ * throws then, and hand-built test doubles lack it entirely.
  */ function focusedOptionName(interaction) {
     if (typeof interaction.options?.getFocused !== 'function') return undefined;
     try {
@@ -254,21 +209,9 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
 /** The character a parameter will not cross, so one pattern segment maps to one value. */ const PARAM_SEPARATOR = '/';
 /** Escapes a literal stretch of a pattern so only placeholders stay meaningful. */ const escapeLiteral = (literal)=>literal.replace(/[/\\^$*+?.()|[\]{}]/g, '\\$&');
 /**
- * Helper function to create regex and parameter mappings from a pattern string.
- *
- * A `{name}` matches anything up to the next `/`, the same rule Express and Rails use
- * for a path segment. That is what lets a value the application does not control — a
- * uuid, an opaque vendor id, a slug — be captured whole without the author annotating
- * anything, since a hyphen inside it is data rather than structure.
- *
- * It also keeps neighbouring patterns apart: `profile/{uuid}` and `profile/{uuid}/{id}`
- * cannot both match one id, because a parameter cannot swallow the separator between
- * them. Patterns separated by `-` instead have no such boundary, so a pair like
- * `profile-{uuid}` and `profile-{uuid}-{id}` is ambiguous — {@link findAmbiguousRoutes}
- * reports those at registration.
- *
- * @param pattern - The pattern string to parse.
- * @returns The regex, the parameter names, and how specific the pattern is.
+ * Compiles a pattern into a regex, its parameter names and its specificity. A `{name}` matches up to
+ * the next `/`, so a uuid is captured whole and `profile/{uuid}` never overlaps `profile/{uuid}/{id}`;
+ * `-`-separated patterns can, which {@link findAmbiguousRoutes} reports at registration.
  */ function createRegexFromPattern(pattern) {
     const params = [];
     let regexPattern = '';
@@ -405,19 +348,13 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     return Reflect.getMetadata(COMMAND_METADATA_KEY, controller);
 }
 /**
- * Decorator to register an autocomplete handler for a chat input command's option.
+ * Registers an autocomplete handler for an option of a chat input command.
  *
- * Autocomplete is a separate interaction from the command it belongs to, and Discord
- * sends it while the user is still typing. It is not a `@Command`: nothing is
- * registered for it — the option's own `setAutocomplete(true)` is what turns it on —
- * and it is answered with `interaction.respond()` rather than a reply. Leaving it
- * unhandled is not silent to the user: the client shows a loading state until the
- * three-second window closes.
+ * Enable it on the option with `setAutocomplete(true)` and answer with `interaction.respond()`.
  *
- * @param commandPath - The command to complete, e.g. `settings` or `settings notify email`
- *   for a subcommand. Parts are separated by a single space, as Discord displays them.
- * @param optionName - The option to complete. Omit to handle every option of the command,
- *   branching on `interaction.options.getFocused(true)`.
+ * @param commandPath - The command, such as `search` or `settings notify email` for a subcommand.
+ * @param optionName - The option to complete. Omit to handle every option, branching on
+ *   `interaction.options.getFocused(true)`.
  *
  * @example
  * ```typescript
@@ -439,13 +376,8 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     };
 }
 /**
- * Retrieves autocomplete handler metadata from a given controller.
- *
- * Handlers naming an option come first, so a command-wide handler acts as the fallback
- * for options no specific handler claimed rather than shadowing them by declaration order.
- *
- * @param controller - The controller class instance.
- * @returns The registered autocomplete handlers, most specific first.
+ * Returns a controller's autocomplete handlers, option-specific ones first.
+ * @param controller - The controller instance.
  */ function getAutocompleteHandlers(controller) {
     const handlers = Reflect.getMetadata(AUTOCOMPLETE_METADATA_KEY, controller) || [];
     return [
@@ -453,7 +385,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     ].sort((a, b)=>Number(Boolean(b.optionName)) - Number(Boolean(a.optionName)));
 }
 /**
- * Decorator to mark a class as a controller that can later be registered to the App class `(app.ts)` using the `@MeoCord` decorator.
+ * Marks a class as a controller, to be listed in `@MeoCord({ controllers })`.
  *
  * @example
  * ```typescript
@@ -463,8 +395,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
  *
  *   @Command('ping', PingCommandBuilder)
  *   async ping(interaction: ChatInputCommandInteraction) {
- *     const response = await this.pingService.handlePing()
- *     await interaction.reply(response)
+ *     await interaction.reply(await this.pingService.handlePing())
  *   }
  * }
  * ```
@@ -476,15 +407,8 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     };
 }
 /**
- * Finds pattern pairs that can both match one customId.
- *
- * Patterns of different segment counts are disjoint, because a parameter cannot cross
- * `/`. Within the same count, two patterns overlap unless some position holds literals
- * that differ: `a/{x}/c` and `a/b/{y}` both take `a/b/c`, and neither is more literal
- * than the other, so ranking cannot settle it either.
- *
- * @param patterns - The registered patterns.
- * @returns Each ambiguous pair, once, in the order the patterns were given.
+ * Finds pairs of customId patterns that can both match one id, such as `a/{x}/c` and `a/b/{y}`.
+ * @returns Each ambiguous pair once, in the order the patterns were given.
  */ function findAmbiguousRoutes(patterns) {
     const isParam = (segment)=>PLACEHOLDER_PATTERN.test(segment);
     const segmentsOf = (pattern)=>pattern.split(PARAM_SEPARATOR);

package/dist/cjs/_shared/{metadata-key.enum-aABGdodb.cjs → metadata-key.enum-DG7cVMc4.cjs}

@@ -8,7 +8,6 @@
  */ var MetadataKey = /*#__PURE__*/ function(MetadataKey) {
     /**
    * Set by Inversify 8's `injectable()` decorator.
-   * Renamed from the legacy `'inversify:injectable'` string used in older versions.
    */ MetadataKey["Injectable"] = "@inversifyjs/core/classIsInjectableFlagReflectKey";
     /**
    * Stores the Inversify `Container` instance on a controller class.

package/dist/cjs/_shared/{theme-Dqwlnz0m.cjs → theme-C8w8ivsR.cjs}

@@ -13,17 +13,9 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 let cachedConfig;
 let configLoaded = false;
 /**
- * Loads the configuration a built application runs with: `dist/meocord.config.mjs`, which
- * `meocord build` compiles from `meocord.config.ts`.
- *
- * Reads only the compiled file, which is plain JavaScript and needs no transpiler, tsconfig or
- * source. Reading `meocord.config.ts` is {@link loadMeoCordSourceConfig}'s job, and it lives in its
- * own module because it needs jiti: this one is imported by the logger and the factory, so a
- * bot built with `bundleDependencies` bundles whatever it imports.
- *
- * The result is cached after the first load.
- *
- * @returns The configuration, or undefined when there is no compiled config or it fails to load.
+ * Loads the configuration a built application runs with, `dist/meocord.config.mjs`, and caches it.
+ * Imports no transpiler, since the logger and the factory import this module into every bot.
+ * @returns The configuration, or undefined when the compiled config is missing or fails to load.
  */ function loadMeoCordConfig() {
     if (configLoaded) return cachedConfig;
     configLoaded = true;
@@ -39,7 +31,7 @@ let configLoaded = false;
     try {
         // Called through a variable so a bundler does not try to resolve the path while building the
         // application; the file is only there once the build is done.
-        const load = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('_shared/theme-Dqwlnz0m.cjs', document.baseURI).href)));
+        const load = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('_shared/theme-C8w8ivsR.cjs', document.baseURI).href)));
         const loaded = load(compiledPath);
         return loaded.default ?? loaded;
     } catch (error) {

package/dist/cjs/common/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var theme = require('../_shared/theme-Dqwlnz0m.cjs');
+var theme = require('../_shared/theme-C8w8ivsR.cjs');
 require('node:util');
 require('dayjs');
 require('dayjs/plugin/utc.js');

package/dist/cjs/core/index.cjs

@@ -3,14 +3,14 @@
 require('reflect-metadata');
 var inversify = require('inversify');
 var discord_js = require('discord.js');
-var theme = require('../_shared/theme-Dqwlnz0m.cjs');
-var controller_decorator = require('../_shared/controller.decorator-9nIxOp9y.cjs');
+var theme = require('../_shared/theme-C8w8ivsR.cjs');
+var controller_decorator = require('../_shared/controller.decorator-CqgGgjj3.cjs');
 var lodashEs = require('lodash-es');
 var enum_index = require('../enum/index.cjs');
 var Table = require('cli-table3');
 var fs = require('fs');
 var path = require('path');
-var metadataKey_enum = require('../_shared/metadata-key.enum-aABGdodb.cjs');
+var metadataKey_enum = require('../_shared/metadata-key.enum-DG7cVMc4.cjs');
 require('node:util');
 require('dayjs');
 require('dayjs/plugin/utc.js');
@@ -66,20 +66,8 @@ const createErrorEmbed = (description)=>{
 }
 class MeoCordApp {
     /**
-   * Runs an event handler so a failure inside it cannot take the process down.
-   *
-   * discord.js calls listeners without awaiting them, so a rejection escaping one has
-   * nothing left to settle it: Node reports an unhandled rejection, which terminates
-   * the process by default. Losing the whole bot because one reaction landed on a
-   * deleted message, or one controller could not be resolved, is a worse failure than
-   * the one that caused it -- every other user is served by the same process.
-   *
-   * Nothing is silenced. The error is logged against the event that produced it, so a
-   * genuine misconfiguration -- an unbound controller, a missing dependency -- shows
-   * up on the very first interaction rather than staying hidden.
-   *
-   * @param event - The gateway event being handled, named in the log.
-   * @param run - The handler to run.
+   * Runs an event handler so its failure is logged against the event instead of surfacing as an
+   * unhandled rejection, which would terminate the whole bot.
    */ async runListener(event, run) {
         try {
             await run();
@@ -107,14 +95,20 @@ class MeoCordApp {
         return this.controllerInstancesCache.get(controllerClass);
     }
     /**
-   * Registers the Discord event handlers and logs in.
+   * Registers the Discord event handlers and logs the bot in.
+   *
+   * If the login fails, the process exit code is set to `1` before the promise rejects, so the
+   * process exits non-zero even when the caller catches the error to log it. A later `start()`
+   * that logs in clears that code again.
+   *
+   * @returns A promise that resolves once the bot is logged in.
+   * @throws The login error, such as an invalid token or Discord being unreachable.
    *
-   * Rejects when the login fails -- an invalid token, or Discord unreachable -- and sets the exit
-   * code to 1 first. A bot that never came online is a failed start, and a supervisor such as
-   * Docker's `restart: on-failure` or systemd can only tell if the process says so. The exit code is
-   * set here rather than left to the entry point because an entry point that catches the rejection
-   * to log it has handled it, and the process would otherwise end with 0. A later `start()` that
-   * logs in -- an entry point retrying -- clears the code again, if this is what set it.
+   * @example
+   * ```ts
+   * const app = MeoCordFactory.create(App)
+   * await app.start()
+   * ```
    */ async start() {
         this.logger.log('Starting bot...');
         this.bot.on('clientReady', ()=>this.runListener('clientReady', async ()=>{
@@ -147,12 +141,8 @@ class MeoCordApp {
         this.logger.log('Bot is online!');
     }
     async registerCommands() {
-        // Keyed by type and name together, because that pair is what Discord treats as one
-        // command: a user context menu and a message context menu are free to share a name,
-        // and keying on the name alone would drop one of them from the payload. Within a
-        // single type the name is unique, so a command whose subcommands live in separate
-        // methods still contributes its builder once — sending it twice makes Discord
-        // reject the whole payload.
+        // Keyed by type and name: Discord treats that pair as one command, so a user and a message context
+        // menu may share a name, and a command split across methods sends its builder once.
         const buildersByCommand = new Map();
         for (const controllerClass of this.controllerClasses){
             const instance = this.getInstance(controllerClass);
@@ -265,13 +255,8 @@ class MeoCordApp {
         return routes;
     }
     /**
-   * Dispatches an interaction, and makes sure a failure anywhere in that still reaches
-   * the person who triggered it.
-   *
-   * {@link executeCommand} already reports what a handler throws, but everything
-   * *before* the handler can fail too — resolving a controller through the container
-   * is the common case — and a component that fails there would otherwise look dead
-   * with nothing said to the user and nothing in the log.
+   * Dispatches an interaction, reporting a failure before the handler, such as resolving the
+   * controller, to the user and the log as well.
    */ async handleInteraction(interaction) {
         try {
             await this.dispatchInteraction(interaction);
@@ -344,12 +329,8 @@ class MeoCordApp {
         return [];
     }
     /**
-   * Answers an autocomplete interaction from the `@Autocomplete` handler that claims it.
-   *
-   * Discord closes the window after three seconds and shows a loading state until
-   * something arrives, so an unclaimed option is answered with an empty list rather
-   * than left to time out -- a visibly empty menu is a better failure than a stuck one,
-   * and the warning says which option is missing a handler.
+   * Answers an autocomplete interaction from the `@Autocomplete` handler that claims it. An unclaimed
+   * option gets an empty list and a warning, rather than a menu stuck loading until Discord times out.
    */ async handleAutocomplete(interaction) {
         const focusedName = controller_decorator.focusedOptionName(interaction);
         for (const path of controller_decorator.resolveCommandPaths(interaction)){
@@ -402,12 +383,8 @@ class MeoCordApp {
         }
     }
     /**
-   * Tells the user something went wrong, if the interaction can still hear it.
-   *
-   * A handler that replies and *then* throws is the common shape of a failure, and
-   * replying twice throws in turn -- out of the catch block, where nothing is left to
-   * handle it. Whatever the interaction's state, reporting an error must not be able
-   * to become a second, worse one.
+   * Tells the user something went wrong, if the interaction can still take a reply. Never throws, since
+   * a handler that already replied would otherwise turn one error into two.
    */ async replyWithError(interaction, message) {
         if (!interaction.isRepliable() || interaction.replied || interaction.deferred) return;
         try {
@@ -561,14 +538,9 @@ class MeoCordApp {
     return !built.libc || !running.libc || built.libc === running.libc;
 }
 /**
- * Stops a bundle from starting on a platform its native addons were not built for.
- *
- * A binary for the wrong platform does not fail at startup. It fails when something first loads
- * it -- for an image library, the first command that renders one -- with a dynamic linker error
- * that names a file rather than the cause. Checking the manifest up front turns that into one
- * clear message before the bot goes online.
- *
- * @param distDir - Directory holding the manifest. Defaults to the directory of the entry script.
+ * Stops a bundle from starting on a platform its native addons were not built for, with one clear
+ * message instead of a linker error on the first command that loads an addon.
+ * @param distDir - Directory holding the manifest. Defaults to the entry script's directory.
  */ function assertBuiltForThisPlatform(distDir = process.argv[1] ? path.dirname(process.argv[1]) : undefined) {
     if (!distDir) return;
     const manifest = path.join(distDir, PLATFORM_MANIFEST);