meocord 4.1.0-beta.0 → 4.1.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # meocord
 
+## 4.1.0-beta.3
+
+### Patch Changes
+
+- [#133](https://github.com/meocord/meocord/pull/133) [`9153786`](https://github.com/meocord/meocord/commit/9153786e695a7d98c5d6b777e77cc07381e2c22e) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Ships every change listed under 4.1.0-beta.2, which was not published on its own. Providers in `@MeoCord({ providers })` and in the testing module's `providers` can be listed in any order: a class listed there is bound once, even when a provider earlier in the list injects it.
+
+## 4.1.0-beta.2
+
+Not published to npm: these changes first ship in 4.1.0-beta.3.
+
+### Minor Changes
+
+- [#123](https://github.com/meocord/meocord/pull/123) [`3924763`](https://github.com/meocord/meocord/commit/3924763805de2c1b6c44ca2d94e72e823956b67d) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `@MeoCord({ providers })` provides values, classes and sync or async factories under a class, string, symbol or `createToken` token, injected with the new `@Inject(token)`, with their `onReady` and `onShutdown` hooks run in dependency order; `MeoCordTestingModule` takes the same providers.
+
+- [#132](https://github.com/meocord/meocord/pull/132) [`9dcfec5`](https://github.com/meocord/meocord/commit/9dcfec5d37b7a2f0e13a8fdf9193be80f39e994f) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `meocord/testing` exports `clearAllMocks()` and `resetAllMocks()`, which reach every mock it made: `createMockFn`, and the mocks inside `createMockInteraction`, `createMockClient` and the rest. Vitest's `clearMocks` and jest's `clearAllMocks()` only reach their own `vi.fn()` and `jest.fn()`. New projects call `resetAllMocks()` after every test from `vitest.setup.ts`. To do the same in an existing project, add `afterEach(() => resetAllMocks())` to a Vitest setup file, and set what a mock returns in the test, or in `beforeEach`, that relies on it.
+
+### Patch Changes
+
+- [#125](https://github.com/meocord/meocord/pull/125) [`c8584a6`](https://github.com/meocord/meocord/commit/c8584a63e9b9d0a4db629338c137bf26a96fa765) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `createMockChannel` takes `ThreadChannel`, stubs `threads.create` on text, announcement, forum and media channels, and gives a subclass the managers of the channel class it extends.
+
+- [#130](https://github.com/meocord/meocord/pull/130) [`1b81e6d`](https://github.com/meocord/meocord/commit/1b81e6d4035e41a02d5b2cabaed503927c8e09af) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Mocks from `meocord/testing` behave more like discord.js. An interaction mock has a `locale` of `'en-US'`, and a `guildLocale` of `'en-US'` with a `guildId` and `null` without, so `t.for(interaction, { public: true })` works on a default mock. A method that returns a promise in discord.js now resolves instead of returning `undefined`, so `await` and `.catch()` work without setup. `send()` and `reply()` resolve to a mock message. A manager's `fetch(id)`, `create()` and `edit()` resolve to a mock of its item, and a list fetch to an empty `Collection`. `createDM()` resolves to a DM channel, and a structure's own `edit()`, `fetch()` and setters to the structure itself. `mockResolvedValue` and `mockRejectedValue` still override them.
+
+- [#126](https://github.com/meocord/meocord/pull/126) [`8cee75d`](https://github.com/meocord/meocord/commit/8cee75d56a250cc86ced77325cdffa20557431eb) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `respond()` reads discord.js's deprecated `ephemeral: true` as `flags: MessageFlags.Ephemeral`, so a private follow-up on a public deferred reply is no longer shown to everyone as an edit of that reply, and tests see the privacy the bot sends; `flags: MessageFlags.Ephemeral` is the supported form.
+
+- [#131](https://github.com/meocord/meocord/pull/131) [`b5e7e63`](https://github.com/meocord/meocord/commit/b5e7e6358bdb325fac4a21b0415922a50ec1727a) Thanks [@l7aromeo](https://github.com/l7aromeo)! - A controller or service whose constructor parameter has no runtime type now stops `MeoCordFactory.create`, and the testing module, before anything is bound. The error names the class, the parameter and the classes that inject it, and says how to fix it. This happens when two services import each other, or a parameter is typed with an interface or an `import type`; the error inversify raised before pointed at the compiler options instead. `meocord/eslint` now warns on import cycles (`import-x/no-cycle`, type-only imports ignored) in projects that have `eslint-import-resolver-typescript`, which it needs to follow imports through `@src`. New projects include it; in a project without it the check stays off and lint is unchanged. Add it with `npm i -D eslint-import-resolver-typescript` to get the warning.
+
+## 4.1.0-beta.1
+
+### Minor Changes
+
+- [#120](https://github.com/meocord/meocord/pull/120) [`9d435d9`](https://github.com/meocord/meocord/commit/9d435d9da2bc62eab012ea2b80df2c1e001a926e) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `createMockMessage()` takes an `id`, `content`, `components`, `embeds` and `flags`, so a test can put controls on the message a button sits on, such as to check what `@Defer` locks; components and embeds may be API JSON, builders or discord.js instances.
+
+### Patch Changes
+
+- [#118](https://github.com/meocord/meocord/pull/118) [`5c636aa`](https://github.com/meocord/meocord/commit/5c636aa930224aef9b4670a5e16b234a3f57397d) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Tools that read the installed version with `require('meocord/package.json')` no longer fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+- [#121](https://github.com/meocord/meocord/pull/121) [`c6990c2`](https://github.com/meocord/meocord/commit/c6990c250f7694ca5adb9963e89f151b7ed5dc4b) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `inGuild()`, `inCachedGuild()` and `inRawGuild()` on a mock answer from its `guildId` and `guild`, so a mock created without a `guildId` is a DM and a guard that requires a guild returns `false`, not `undefined`.
+
 ## 4.1.0-beta.0
 
 ### Minor Changes

package/README.md

@@ -1,5 +1,11 @@
 # MeoCord Framework
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/meocord/meocord/main/docs/assets/brand/banner-dark.webp">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/meocord/meocord/main/docs/assets/brand/banner-light.webp">
+  <img alt="MeoCord: a controller method with @Command, @UseGuard and @Cooldown, answering with respond()" src="https://raw.githubusercontent.com/meocord/meocord/main/docs/assets/brand/banner.webp" width="1280">
+</picture>
+
 [![npm version](https://img.shields.io/npm/v/meocord.svg)](https://www.npmjs.com/package/meocord)
 [![CI](https://github.com/meocord/meocord/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/meocord/meocord/actions/workflows/release.yml)
 [![node](https://img.shields.io/node/v/meocord)](https://www.npmjs.com/package/meocord)
@@ -45,6 +51,7 @@
 - [Custom Decorators](#custom-decorators)
 - [Gateway Events](#gateway-events)
 - [Handler Discovery](#handler-discovery)
+- [Providers](#providers)
 - [Lifecycle Hooks](#lifecycle-hooks)
 - [Localisation](#localisation)
 - [Testing](#testing)
@@ -64,7 +71,7 @@
 ## Features
 
 - **Decorator-based controllers** — Handle every Discord interaction type — slash commands and their subcommands, autocomplete, buttons, modals, all five select menus, context menus, activity entry points, messages, and reactions — with `@Command`, `@Autocomplete`, `@MessageHandler` and `@ReactionHandler`. No routing boilerplate.
-- **Dependency injection** — Built on Inversify. Services are wired into controllers automatically; no manual instantiation or service locators.
+- **Dependency injection** — Built on Inversify. Services are wired into controllers automatically; no manual instantiation or service locators. Providers add values, classes and async factories under any token, injected with `@Inject`.
 - **A request pipeline** — [Guards](#guards) decide whether a handler runs, [interceptors](#interceptors) wrap it, [validation and pipes](#validation-and-pipes) check and transform its input, [cooldowns](#cooldowns) limit how often it runs, and [exception filters](#exception-filters) decide what the user is told when something throws. Each applies to a method, a controller, or the whole bot.
 - **Interaction responses** — `respond(interaction)` answers every interaction type correctly from any state, deferred or replied, wherever a user-installed app is used; a presenter styles MeoCord's own answers.
 - **Cooldowns** — `@Cooldown` limits how often a handler runs, per user, server, channel or for everyone, with a pluggable store to share the count across shards.
@@ -755,7 +762,7 @@ async profile(interaction: ChatInputCommandInteraction) {
 
 `state` tells where the answer stands (`'unanswered'`, `'deferred'` or `'replied'`), re-read from the interaction on every call, so answers made directly with discord.js or by a collector still count. `message` is the message last sent or edited, `location` is what [`getInstallContext`](#where-the-interaction-happened) reports, and `original` holds the message's components and embeds from before `@Defer` locked it. `lock()` is `@Defer`'s second step, for a handler that acknowledges on its own. Interceptors and filters reach the same state as `context.response`.
 
-Each call takes only the flags Discord accepts for it, computed afresh: an ephemeral follow-up never makes later messages ephemeral. `send()` and `followUp()` payloads are typed so an impossible flag does not compile. Once a message uses Components V2 its edits keep the flag, and content and embeds are dropped from them. When an edit re-sends an embed or Components V2 media whose image is one of the message's own Discord attachments, the URL is pointed at `attachment://` so the image survives the edit.
+Each call takes only the flags Discord accepts for it, computed afresh: an ephemeral follow-up never makes later messages ephemeral. `send()` and `followUp()` payloads are typed so an impossible flag does not compile. Make a message private with `flags: MessageFlags.Ephemeral`; discord.js's deprecated `ephemeral: true` is read as that flag, under the same rules. Once a message uses Components V2 its edits keep the flag, and content and embeds are dropped from them. When an edit re-sends an embed or Components V2 media whose image is one of the message's own Discord attachments, the URL is pointed at `attachment://` so the image survives the edit.
 
 ### `@Defer`
 
@@ -1323,6 +1330,62 @@ export class HelpService {
 
 ---
 
+## Providers
+
+A class that a controller or service injects by its type is bound for you. For anything else — a database pool, a configured client, settings, or the implementation behind an abstract class — list a provider in `@MeoCord({ providers })`, and inject it with `@Inject(token)`:
+
+```typescript
+import { createToken } from 'meocord/common'
+import { Inject, MeoCord, Service } from 'meocord/decorator'
+import { GatewayIntentBits } from 'discord.js'
+import pg from 'pg'
+
+export const DATABASE = createToken<pg.Pool>('Database')
+
+@Service()
+export class NotesStore {
+  constructor(@Inject(DATABASE) private readonly db: pg.Pool) {}
+
+  async list(userId: string) {
+    const { rows } = await this.db.query('SELECT text FROM notes WHERE user_id = $1', [userId])
+    return rows
+  }
+}
+
+@MeoCord({
+  controllers: [NotesController],
+  providers: [
+    { provide: 'databaseUrl', useValue: process.env.DATABASE_URL },
+    {
+      provide: DATABASE,
+      useFactory: async (url: string) => {
+        const pool = new pg.Pool({ connectionString: url })
+        await pool.query('SELECT 1') // fail at startup, not at the first command
+        return pool
+      },
+      inject: ['databaseUrl'],
+    },
+  ],
+  clientOptions: { intents: [GatewayIntentBits.Guilds] },
+})
+export default class App {}
+```
+
+| Provider                           | Provides                                                                               |
+| ---------------------------------- | -------------------------------------------------------------------------------------- |
+| `{ provide, useValue }`            | The value, as it is.                                                                   |
+| `{ provide, useClass }`            | One instance of the class, with its own constructor dependencies injected.             |
+| `{ provide, useFactory, inject? }` | What the function returns, called once with the values of `inject`. It may be `async`. |
+
+- **Tokens** are a class, a string, a symbol, or a token from `createToken<T>(description)`: a symbol whose description names it in errors, and whose type `TestingModule.get` returns. A parameter typed as a class needs no `@Inject`; `{ provide: Storage, useClass: RedisStorage }` makes every `Storage` parameter a `RedisStorage`.
+- **When**: every factory runs once, in dependency order, when `app.start()` begins, before the listed services are made and before login, awaiting those that return a promise. Anything that injects the value gets the resolved one.
+- **Lifecycle**: a provided value that implements `onReady` or `onShutdown` gets them called like a service's, in dependency order, so it closes after the services that use it. `pg.Pool` has no such hook; end it from the `onShutdown` of the service that owns it, or provide a class that wraps it.
+- **Failures**: a factory that throws or rejects stops the bot before it logs in. The log names the token and the cause, `app.start()` rejects with an error `isExplainedError` recognises, and the exit code is 1. A class or factory that injects a token nothing provides stops `MeoCordFactory.create()`, naming both. A token may be provided once, and the tokens MeoCord binds itself, such as `Client`, cannot be provided.
+
+In a test, `MeoCordTestingModule` takes the same providers, and `overrideProvider(token)` replaces one under any token. `invoke` and `emit` resolve asynchronous factories first; before calling `get` on something that depends on one, `await module.init()`.
+
+---
+
 ## Lifecycle Hooks
 
 A controller or service can do work once the bot is online, and clean up before it stops, by implementing `OnReady` and `OnShutdown` from `meocord/interface`:
@@ -1354,7 +1417,7 @@ export class ReminderScheduler implements OnReady, OnShutdown {
 }
 ```
 
-- **Which classes**: every controller and every service the app binds — the ones listed in `@MeoCord({ controllers, services })` and everything they depend on — including a service no handler has used yet. Guards are created per call and get no hooks.
+- **Which classes**: every controller and every service the app binds — the ones listed in `@MeoCord({ controllers, services })` and everything they depend on — including a service no handler has used yet, and every [provided](#providers) value that implements a hook. Guards are created per call and get no hooks.
 - **`onReady`** runs once the client is ready. It receives the client and `{ primary }`, which says whether this process should do one-off work: `true` for a bot running in one process, and with [process sharding](#sharding) only in the process running shard 0.
 - **Dependency order.** `onReady` hooks run one at a time, each class after the classes it injects: a `DatabaseService` is ready before the `ReminderScheduler` that injects it. Classes with no dependency between them run in declaration order, the `services` first, then the `controllers`. Command registration runs alongside and never delays the hooks. A hook still running after 10 seconds is named in a warning, and the hooks after it wait for it.
 - **`onShutdown`** runs on SIGINT or SIGTERM, before the client is destroyed, in reverse order, so a class stops before the classes it uses. The bot waits for the whole sequence up to `shutdownTimeout` from `meocord.config.ts` (10 seconds by default), then shuts down whether or not it finished. A second signal more than a second after the first exits at once; one sooner is taken as the same request, since a terminal's Ctrl+C can arrive twice. If the bot never became ready, for example because the login failed, no `onShutdown` hook runs. A signal that arrives while the `onReady` hooks are still running shuts down only the classes whose `onReady` finished, and those without one; the class still starting, and those after it, are skipped, and no further `onReady` starts.
@@ -1470,6 +1533,8 @@ const module = MeoCordTestingModule.create({
 const controller = module.get(GreetingSlashController)
 ```
 
+`providers` takes the same shapes as `@MeoCord({ providers })`: `useValue`, `useClass` and `useFactory`, under a class, string, symbol or `createToken` token. A factory that returns a promise is resolved by `await module.init()`, which `invoke` and `emit` call for you.
+
 ### Running a handler with `invoke`
 
 `module.invoke(Controller, 'method', ...args)` runs a handler through the [pipeline](#how-a-handler-runs) dispatch runs: `@Defer`, its guards, class guards first and each once, then its interceptors around validation, pipes, cooldowns and the handler, all inside its exception filters. Guards resolve from the module, so `overrideGuard` stubs and injected `ExecutionContext` work as they do in the bot. Pass the arguments dispatch would: the interaction, message or reaction, then the handler's params. An interaction must be one dispatch could route to the handler: a customId its pattern matches, or the command or subcommand path it handles. One that could not, such as `'something/else'` for `'profile/{id}'`, rejects with a message naming both, so a typo in a test does not pass silently. A mock built without a customId or command name is not checked.
@@ -1524,6 +1589,8 @@ Creates a smart mock instance of any discord.js class. The full prototype chain
 
 **Type guards run real logic** — `isButton()`, `isRepliable()`, `isChatInputCommand()`, etc. are backed by the actual discord.js prototype methods. The right fields (`type`, `componentType`, `commandType`) are set based on the class you pass in, so no manual `.mockReturnValue(true)` setup is needed. All type guard methods are still mock functions and can be overridden per test.
 
+**Guild checks read the mock's data** — `inGuild()`, `inCachedGuild()` and `inRawGuild()` answer from the `guildId` and `guild` the mock is given, as discord.js does: a `guildId` means a guild, a `guildId` with a `guild` (such as `createMockGuild()`) a cached one, and a mock created without a `guildId` is a DM, where all three return `false`. A `member` set to `null` or `undefined` makes all three `false` too. Its `locale` is `'en-US'`, and its `guildLocale` is `'en-US'` with a `guildId` and `null` without, as Discord sends them; pass either to change it.
+
 **Reply state machine** — for repliable interactions, `replied` and `deferred` start as `false`. Calling `reply()` or `deferReply()` twice throws, just like a real interaction. `followUp()`, `editReply()`, and `deleteReply()` throw if called before any reply. The ephemeral flag is tracked on `interaction.ephemeral`, read from `flags` only — the deprecated `ephemeral: true` reply option is not honoured. All reply methods are still mock functions so call assertions work normally.
 
 Autocomplete interactions are not repliable but get the equivalent for their own single-shot response: `responded` starts as `false`, `respond()` sets it, and a second call throws.
@@ -1531,6 +1598,8 @@ Autocomplete interactions are not repliable but get the equivalent for their own
 Guards discord.js has deprecated are deliberately left unwired — `isSelectMenu()` returns `undefined` rather than reproducing behaviour the library is removing. Use `isStringSelectMenu()`.
 
 > **Framework-agnostic** — the mocks returned here are plain mock functions that stamp `_isMockFunction` and expose `.mock.calls`, the exact contract both `jest` and `vitest` check. Use them with either framework's `expect(...).toHaveBeenCalledWith(...)` / `toHaveBeenCalledTimes(...)` — no jest or vitest import is required to produce them. For typed stubs in your own code, import `MockedFunction`, `createMockFn`, and `DeepMocked` from `meocord/testing`.
+>
+> **Resetting between tests** — Vitest's `clearMocks` and jest's `clearAllMocks()` reach only their own `vi.fn()` and `jest.fn()`. `clearAllMocks()` from `meocord/testing` clears the calls of every mock it made, and `resetAllMocks()` also undoes what a test set with `mockReturnValue`, `mockResolvedValue` and the rest, back to how each mock was created. Generated projects call `resetAllMocks()` after every test from `vitest.setup.ts`, so set a mock's behaviour in the test, or in `beforeEach`, that relies on it.
 
 ```typescript
 import { createMockInteraction } from 'meocord/testing'
@@ -1547,6 +1616,10 @@ interaction.isChatInputCommand() // → true
 interaction.isRepliable() // → true
 interaction.isButton() // → false
 
+// created without a guildId, the mock is a DM
+interaction.inGuild() // → false
+interaction.inCachedGuild() // → false
+
 // reply state machine
 interaction.replied // → false
 await interaction.reply({ content: 'hi' })
@@ -1650,6 +1723,8 @@ All methods are mock functions — override any per test with `.mockReturnValue(
 
 Convenience wrappers for common discord.js classes. All methods are auto-stubbed as mock functions. Nested managers (`client.users`, `guild.members`, etc.) are independent nested stubs.
 
+A method that returns a promise in discord.js resolves, so `await` and `.catch()` work without setup: `send()` and `reply()` to a mock `Message`, a manager's `fetch(id)`, `create()` and `edit()` to a mock of its item (`users.fetch(id)` to a `User`, `guild.members.fetch(id)` to a `GuildMember`), a list fetch such as `members.fetch()` to an empty `Collection`, `createDM()` to a `DMChannel`, and a structure's own `edit()`, `fetch()` and setters to the structure itself. Any other such method resolves to `undefined`. `mockResolvedValue` and `mockRejectedValue` still decide per test.
+
 ```typescript
 import { createMockFn, createMockUser, createMockClient, createMockGuild, createMockChannel } from 'meocord/testing'
 import { TextChannel } from 'discord.js'
@@ -1665,6 +1740,17 @@ await (client.users as any).fetch('user-123')
 expect((client.users as any).fetch).toHaveBeenCalledWith('user-123')
 ```
 
+`createMockChannel` sets up the managers each channel class has: `messages`; `threads` on text, announcement, forum and media channels; and `members` on a `ThreadChannel`. A subclass gets those of the class it extends.
+
+```typescript
+import { TextChannel, ThreadChannel } from 'discord.js'
+
+const text = createMockChannel(TextChannel)
+const thread = createMockChannel(ThreadChannel)
+// discord.js types a created thread as public or private, not as the ThreadChannel class
+text.threads.create.mockResolvedValue(thread as never)
+```
+
 </details>
 
 <details>
@@ -1691,6 +1777,23 @@ edited.delete // → a mock fn
 expect(msg.delete).toHaveBeenCalledTimes(1)
 ```
 
+Without arguments the message is empty. Give it an `id`, `content`, `components`, `embeds` and `flags` to test code that reads them, such as a button on a message whose controls `@Defer` locks. Components and embeds may be API JSON, builders or discord.js instances, and `flags` a number, flag names or a `MessageFlagsBitField`:
+
+```typescript
+const message = createMockMessage({
+  components: [
+    new ActionRowBuilder<ButtonBuilder>().addComponents(
+      new ButtonBuilder().setCustomId('card/refresh').setLabel('Refresh').setStyle(ButtonStyle.Primary),
+    ),
+  ],
+  embeds: [{ title: 'Card' }],
+  flags: MessageFlags.Ephemeral,
+})
+const interaction = createMockInteraction(ButtonInteraction, { customId: 'card/refresh', message })
+```
+
+API JSON and builders are kept as their JSON behind `toJSON()`, which is what `respond()` and `@Defer` read; discord.js instances are kept as they are.
+
 </details>
 
 <details>

package/dist/cjs/_shared/{cooldown-store-DTqJP31S.cjs → cooldown-store-DJ7s2HYv.cjs}

@@ -33,7 +33,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/cooldown-store-DTqJP31S.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/cooldown-store-DJ7s2HYv.cjs', document.baseURI).href)));
         const loaded = load(compiledPath);
         return loaded.default ?? loaded;
     } catch (error) {
@@ -485,11 +485,14 @@ function errorCode(error) {
     return interaction.isCommand() || interaction.isModalSubmit() && !interaction.isFromMessage();
 }
 function toBody(payload) {
-    return typeof payload === 'string' ? {
+    if (typeof payload === 'string') return {
         content: payload
-    } : {
-        ...payload
     };
+    // discord.js's deprecated option, read as the flag it stands for before anything decides on flags, and
+    // kept out of the call, where discord.js would add Ephemeral back to an edit or an update
+    const { ephemeral, ...body } = payload;
+    if (ephemeral) body.flags = Number(discord_js.MessageFlagsBitField.resolve(body.flags ?? 0)) | discord_js.MessageFlags.Ephemeral;
+    return body;
 }
 /** Drops what a Components V2 message cannot carry. */ function forMode(body, v2) {
     if (!v2) return body;

package/dist/cjs/_shared/{input-runner-CucAPIqF.cjs → providers-CHJHjNb9.cjs}

@@ -4,7 +4,7 @@ require('reflect-metadata');
 var enum_index = require('../enum/index.cjs');
 var metadataKey_enum = require('./metadata-key.enum-CXFdtEX9.cjs');
 var discord_js = require('discord.js');
-var cooldownStore = require('./cooldown-store-DTqJP31S.cjs');
+var cooldownStore = require('./cooldown-store-DJ7s2HYv.cjs');
 var inversify = require('inversify');
 
 /**
@@ -588,6 +588,18 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     }
     return tokens;
 }
+/**
+ * The position of the first constructor parameter with no runtime type and no `@Inject` token, or -1.
+ * Such a parameter reads as `Object` when it is typed with an interface or an `import type`, and as
+ * `Object` or `undefined` when its class's module had not finished loading, as when two classes
+ * import each other.
+ */ function untypedParameter(cls) {
+    const types = Reflect.getMetadata(metadataKey_enum.MetadataKey.ParamTypes, cls) ?? [];
+    const metadata = Reflect.getMetadata(INVERSIFY_CLASS_METADATA, cls);
+    // Once bound, inversify records each parameter here too: an @Inject token, or the parameter's type
+    const tokens = types.map((type, index)=>metadata?.constructorArguments?.[index]?.value ?? type);
+    return tokens.findIndex((token)=>token === undefined || token === Object);
+}
 /**
  * The error for a class resolved once and shared that asks for the per-call `ExecutionContext`,
  * which would keep the first call's context for every later one.
@@ -834,21 +846,12 @@ function eventDecorator(event, once) {
  */ function lifecycleDependencies(container, cls) {
     return injectedTokens(cls).filter((token)=>isAppClassToken(token) && container.isBound(token));
 }
-/**
- * The bound classes reachable from `roots`, each after everything it injects: the order lifecycle
- * hooks run in. Roots are the listed services, then the controllers, so classes with no dependency
- * between them keep that declaration order.
- */ function dependencyOrder(container, roots) {
-    const ordered = [];
-    const seen = new Set();
-    const visit = (cls)=>{
-        if (seen.has(cls)) return;
-        seen.add(cls);
-        lifecycleDependencies(container, cls).forEach(visit);
-        ordered.push(cls);
-    };
-    roots.forEach(visit);
-    return ordered;
+/** The units for a list of classes already in dependency order, as the app runs them without providers. */ function classUnits(container, classes) {
+    return classes.map((cls)=>({
+            token: cls,
+            name: cls.name,
+            dependencies: lifecycleDependencies(container, cls)
+        }));
 }
 
 function isInterceptorWithParams(entry) {
@@ -1124,6 +1127,170 @@ const asList = (entries)=>Array.isArray(entries) ? entries : [
     ];
 }
 
+const isValueProvider = (provider)=>'useValue' in provider;
+const isClassProvider = (provider)=>'useClass' in provider;
+const isFactoryProvider = (provider)=>'useFactory' in provider;
+/** A token as logs and errors name it: a class by its name, a symbol by its description, a string quoted. */ function tokenName(token) {
+    if (typeof token === 'function') return token.name || 'an anonymous class';
+    if (typeof token === 'symbol') return token.description ? `Symbol(${token.description})` : 'a symbol';
+    return `'${String(token)}'`;
+}
+const isToken = (value)=>typeof value === 'function' || typeof value === 'string' || typeof value === 'symbol';
+/**
+ * Checks each provider's shape and indexes them by token, throwing on the first that cannot be bound:
+ * no token, not exactly one of `useValue`, `useClass` and `useFactory`, or a token provided twice.
+ */ function providerMap(providers, where) {
+    const map = new Map();
+    for (const provider of providers){
+        const entry = provider;
+        if (!entry || typeof entry !== 'object' || !isToken(entry.provide)) {
+            throw new Error(`${where} has a provider without a token: set provide to a class, a string or a symbol.`);
+        }
+        const name = tokenName(entry.provide);
+        const kinds = [
+            'useValue',
+            'useClass',
+            'useFactory'
+        ].filter((kind)=>kind in entry);
+        if (kinds.length !== 1) {
+            throw new Error(`The provider for ${name} in ${where} needs exactly one of useValue, useClass and useFactory.`);
+        }
+        if ('useClass' in entry && typeof entry.useClass !== 'function') {
+            throw new Error(`The provider for ${name} in ${where} has a useClass that is not a class.`);
+        }
+        if ('useFactory' in entry) {
+            if (typeof entry.useFactory !== 'function') {
+                throw new Error(`The provider for ${name} in ${where} has a useFactory that is not a function.`);
+            }
+            if (entry.inject !== undefined && !(Array.isArray(entry.inject) && entry.inject.every(isToken))) {
+                throw new Error(`The provider for ${name} in ${where} has an inject that is not a list of tokens.`);
+            }
+        }
+        if (map.has(entry.provide)) throw new Error(`${name} is provided twice in ${where}.`);
+        map.set(entry.provide, provider);
+    }
+    return map;
+}
+/**
+ * Binds one provider into `container` as a singleton. `bindClass` binds a class a provider depends
+ * on, as the app binds its own, so a provided class or a factory's `inject` can name any class.
+ */ function bindProvider(container, provider, bindClass) {
+    const token = provider.provide;
+    if (isValueProvider(provider)) {
+        container.bind(token).toConstantValue(provider.useValue);
+        return;
+    }
+    if (isClassProvider(provider)) {
+        const cls = provider.useClass;
+        if (injectedTokens(cls).includes(cooldownStore.ExecutionContext)) throw singletonContextError(cls);
+        makeInjectable(cls);
+        container.bind(token).to(cls).inSingletonScope();
+        for (const dependency of injectedTokens(cls))if (isAppClassToken(dependency)) bindClass(dependency);
+        return;
+    }
+    const { useFactory, inject = [] } = provider;
+    // Resolved in dependency order before anything needs it, so each injected value is already made
+    container.bind(token).toDynamicValue((context)=>useFactory(...inject.map((dependency)=>context.get(dependency)))).inSingletonScope();
+    for (const dependency of inject)if (isAppClassToken(dependency)) bindClass(dependency);
+}
+/**
+ * Throws when a class or a factory asks for a string or symbol token that nothing binds, naming both,
+ * rather than failing when the class is first resolved. A class token is bound on demand, so it is
+ * never missing.
+ */ function assertProvided(container, providers, classes, where) {
+    const missing = (token)=>(typeof token === 'string' || typeof token === 'symbol') && !container.isBound(token);
+    for (const cls of classes){
+        const token = injectedTokens(cls).find(missing);
+        if (token !== undefined) {
+            throw new Error(`${cls.name} injects ${tokenName(token)}, which nothing provides: add a provider for it to ${where}.`);
+        }
+    }
+    for (const [provided, provider] of providers){
+        const dependencies = isFactoryProvider(provider) ? provider.inject ?? [] : isClassProvider(provider) ? injectedTokens(provider.useClass) : [];
+        const token = dependencies.find(missing);
+        if (token !== undefined) {
+            throw new Error(`The provider for ${tokenName(provided)} injects ${tokenName(token)}, which nothing provides: add a provider for it to ${where}.`);
+        }
+    }
+}
+/**
+ * The classes the app constructs, found from `roots` through what each injects, before anything is
+ * bound: a token a provider stands in for is not constructed as itself, so it is only followed when
+ * it is its own `useClass`. Providers' classes and factory dependencies are roots too.
+ */ function reachableClasses(roots, providers) {
+    const found = [];
+    const visit = (token)=>{
+        if (!isAppClassToken(token) || found.includes(token)) return;
+        const provider = providers.get(token);
+        if (provider && !(isClassProvider(provider) && provider.useClass === token)) return;
+        found.push(token);
+        injectedTokens(token).forEach(visit);
+    };
+    for (const provider of providers.values()){
+        if (isClassProvider(provider)) visit(provider.useClass);
+        if (isFactoryProvider(provider)) (provider.inject ?? []).forEach(visit);
+    }
+    roots.forEach(visit);
+    return found;
+}
+/**
+ * Throws for the first of `classes` with a constructor parameter nothing can inject: one with no
+ * runtime type and no `@Inject` token. It names the classes among `classes` that inject it, the likely
+ * other half when two classes import each other, rather than leaving inversify's error to point at
+ * the compiler options.
+ */ function assertTypedParameters(classes) {
+    for (const cls of classes){
+        const index = untypedParameter(cls);
+        if (index === -1) continue;
+        const injectors = classes.filter((other)=>other !== cls && injectedTokens(other).includes(cls)).map((other)=>other.name);
+        const injectedBy = injectors.length === 0 ? '' : ` (${injectors.length === 1 ? injectors[0] : `${injectors.slice(0, -1).join(', ')} and ${injectors.at(-1)}`} ` + `inject${injectors.length === 1 ? 's' : ''} ${cls.name})`;
+        throw new Error(`${cls.name} cannot be created: parameter ${index + 1} of its constructor has no runtime type. Usually ` + `${cls.name} and a class it injects import each other${injectedBy}, or the parameter is typed with an ` + 'interface or an `import type`. Move what they both need into a third service, or inject the parameter ' + 'with @Inject(token).');
+    }
+}
+/**
+ * What must exist before `token`: a factory's `inject`, a provided or bound class's constructor
+ * dependencies, nothing for a value. Only the app's classes and provided tokens count.
+ */ function tokenDependencies(container, providers, token) {
+    const provider = providers.get(token);
+    const dependencies = provider ? isFactoryProvider(provider) ? provider.inject ?? [] : isClassProvider(provider) ? injectedTokens(provider.useClass) : [] : isAppClassToken(token) ? injectedTokens(token) : [];
+    return dependencies.filter((dependency)=>(providers.has(dependency) || isAppClassToken(dependency)) && container.isBound(dependency));
+}
+/**
+ * The bound tokens reachable from `roots`, each after everything it depends on: the order factories
+ * are resolved and lifecycle hooks run in. Tokens with no dependency between them keep the roots' order.
+ */ function resolutionOrder(container, providers, roots) {
+    const ordered = [];
+    const seen = new Set();
+    const visit = (token)=>{
+        if (seen.has(token)) return;
+        seen.add(token);
+        tokenDependencies(container, providers, token).forEach(visit);
+        ordered.push(token);
+    };
+    roots.forEach(visit);
+    return ordered;
+}
+/** The error for a factory that threw or rejected, naming its token and carrying the original as `cause`. */ function providerFailure(token, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return new Error(`The factory providing ${tokenName(token)} failed: ${reason}`, {
+        cause: error
+    });
+}
+/**
+ * Runs every factory in `order`, awaiting those that return a promise, so each value is made before
+ * anything that injects it is resolved. Rejects with {@link providerFailure} for the first that fails.
+ */ async function resolveProviders(container, providers, order) {
+    for (const token of order){
+        const provider = providers.get(token);
+        if (!provider || !isFactoryProvider(provider)) continue;
+        try {
+            await container.getAsync(token);
+        } catch (error) {
+            throw providerFailure(token, error);
+        }
+    }
+}
+
 exports.Autocomplete = Autocomplete;
 exports.CATCH_TYPES = CATCH_TYPES;
 exports.CLASS_COOLDOWNS = CLASS_COOLDOWNS;
@@ -1147,15 +1314,18 @@ exports.Once = Once;
 exports.PARAM_SEPARATOR = PARAM_SEPARATOR;
 exports.ReactionHandler = ReactionHandler;
 exports.appliesTo = appliesTo;
+exports.assertProvided = assertProvided;
 exports.assertStageEntries = assertStageEntries;
+exports.assertTypedParameters = assertTypedParameters;
+exports.bindProvider = bindProvider;
 exports.bindShared = bindShared;
 exports.callFilter = callFilter;
 exports.callGuardedHandler = callGuardedHandler;
+exports.classUnits = classUnits;
 exports.consumeDispatchMark = consumeDispatchMark;
 exports.declaringPrototype = declaringPrototype;
 exports.deferMisuseError = deferMisuseError;
 exports.defineStageTypes = defineStageTypes;
-exports.dependencyOrder = dependencyOrder;
 exports.describeInteraction = describeInteraction;
 exports.findAmbiguousRoutes = findAmbiguousRoutes;
 exports.focusedOptionName = focusedOptionName;
@@ -1173,8 +1343,8 @@ exports.handlerInterceptors = handlerInterceptors;
 exports.hasCustomId = hasCustomId;
 exports.injectedTokens = injectedTokens;
 exports.isAppClassToken = isAppClassToken;
+exports.isClassProvider = isClassProvider;
 exports.isCustomIdRouted = isCustomIdRouted;
-exports.lifecycleDependencies = lifecycleDependencies;
 exports.makeInjectable = makeInjectable;
 exports.matchFilter = matchFilter;
 exports.matchesCommandType = matchesCommandType;
@@ -1184,11 +1354,17 @@ exports.prepareFilter = prepareFilter;
 exports.prepareHandlerArgs = prepareHandlerArgs;
 exports.prepareInterceptor = prepareInterceptor;
 exports.preparePipe = preparePipe;
+exports.providerMap = providerMap;
+exports.reachableClasses = reachableClasses;
+exports.resolutionOrder = resolutionOrder;
 exports.resolveCommandPaths = resolveCommandPaths;
 exports.resolveOptionParams = resolveOptionParams;
+exports.resolveProviders = resolveProviders;
 exports.runGuards = runGuards;
 exports.runInterceptors = runInterceptors;
 exports.singletonContextError = singletonContextError;
 exports.stageClass = stageClass;
 exports.stageTypes = stageTypes;
 exports.startDefer = startDefer;
+exports.tokenDependencies = tokenDependencies;
+exports.tokenName = tokenName;