meocord 4.2.1 → 4.2.3

package/dist/cjs/decorator/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
 require('reflect-metadata');
-var providers = require('../_shared/providers-BZgJyfZS.cjs');
-var controller_decorator = require('../_shared/controller.decorator-XKMlcUZz.cjs');
+var providers = require('../_shared/providers-BBvbnmLP.cjs');
+var controller_decorator = require('../_shared/controller.decorator-hp5xdJU4.cjs');
 var inversify = require('inversify');
 require('node:async_hooks');
 require('../enum/index.cjs');
@@ -12,14 +12,14 @@ require('fs');
 require('path');
 require('cli-table3');
 require('node:crypto');
-require('node:fs');
-require('node:url');
 require('node:util');
 require('dayjs');
 require('dayjs/plugin/utc.js');
 require('dayjs/plugin/timezone.js');
 require('module');
+require('node:fs');
 require('chalk');
+require('node:url');
 
 /**
  * Marks a class as a service, which controllers and other services inject by its type.
@@ -54,6 +54,13 @@ require('chalk');
     });
 }
 
+const logger$3 = new controller_decorator.Logger('CommandBuilder');
+/** The nearest base class of `target` that gives `guilds`, which `target` inherits when it gives none. */ function guildsBase(target) {
+    for(let base = Object.getPrototypeOf(target); base && base !== Function.prototype; base = Object.getPrototypeOf(base)){
+        if (Reflect.hasOwnMetadata(controller_decorator.META.builderGuilds, base)) return base;
+    }
+    return undefined;
+}
 /**
  * Marks a class as a command's builder, which describes the command MeoCord registers with Discord.
  *
@@ -91,45 +98,61 @@ require('chalk');
         if (options.guilds) Reflect.defineMetadata(controller_decorator.META.builderGuilds, [
             ...options.guilds
         ], target);
+        else {
+            const base = guildsBase(target);
+            if (base) {
+                logger$3.warn(`${target.name} gives no guilds and inherits ${base.name}'s; declare guilds on ${target.name} to keep them. ` + 'The next major version (5.0) registers it in the configured scope.');
+            }
+        }
     });
 }
 
 /**
- * Adds guards to a method's class or method list, then republishes the effective list under
- * `META.guards`, in the order they run: the bases' before the class's own, and within one class or method the
- * latest decorator first, since it wraps outermost.
- */ function recordGuards(key, guards, prototype, methodName) {
-    const existing = Reflect.getOwnMetadata(key, prototype, methodName) ?? [];
-    const bases = key === controller_decorator.META.classGuards ? Reflect.getOwnMetadata(controller_decorator.META.baseClassGuards, prototype, methodName) ?? 0 : 0;
-    Reflect.defineMetadata(key, [
-        ...existing.slice(0, bases),
-        ...guards,
-        ...existing.slice(bases)
-    ], prototype, methodName);
-    const [classGuards, inheritedGuards, methodGuards] = [
-        controller_decorator.META.classGuards,
-        controller_decorator.META.inheritedGuards,
-        controller_decorator.META.methodGuards
-    ].map((list)=>Reflect.getOwnMetadata(list, prototype, methodName) ?? []);
-    Reflect.defineMetadata(controller_decorator.META.guards, [
-        ...inheritedGuards,
-        ...classGuards,
-        ...methodGuards
-    ], prototype, methodName);
-}
-/**
- * Wraps a method so a direct call runs its guards first: the wrapper entered first runs the whole
- * chain dispatch resolves for the handler, and lets the ones inside it through. A call from dispatch,
- * which has already run the guards, passes through every wrapper.
- */ function applyGuards(descriptor, prototype, propertyKey) {
-    const originalMethod = descriptor.value;
-    descriptor.value = controller_decorator.wrapsMethod(async function(...args) {
-        if (providers.consumeDispatchMark(args[0], this, propertyKey)) return originalMethod.apply(this, args);
-        return providers.runDirectCall(this, propertyKey, args, ()=>originalMethod.apply(this, args));
-    }, originalMethod);
-    const wrappers = Reflect.getOwnMetadata(controller_decorator.META.guardWrappers, prototype, propertyKey) ?? 0;
-    Reflect.defineMetadata(controller_decorator.META.guardWrappers, wrappers + 1, prototype, propertyKey);
+ * Marks a class as a controller, whose methods handle commands, components, messages, reactions or events.
+ *
+ * Use it on every class of handlers, and list the class in `@MeoCord({ controllers })`. Logic the handlers
+ * share, such as database access, belongs in a service it injects.
+ *
+ * @remarks
+ * A controller's class-level guards and filters apply to every handler it declares or inherits, its interceptors to
+ * all but autocomplete, and its cooldowns to its command, component and message handlers; each also applies to the
+ * handlers of a class that extends it. A base wraps what extends it: guards and interceptors
+ * run the top base's first, then each subclass's, then the method's, and filters are tried the other way, the
+ * method's first. `inheritStages: false` keeps the handlers a subclass declares to its own stages.
+ *
+ * @param options - Whether the handlers it declares take the stages of the classes it extends.
+ *
+ * @example
+ * ```ts
+ * @Controller()
+ * export class ProfileSlashController {
+ *   constructor(private readonly profiles: ProfileService) {}
+ *
+ *   @Command('profile', CommandType.SLASH)
+ *   async profile(interaction: ChatInputCommandInteraction) {
+ *     await respond(interaction).send({ embeds: [await this.profiles.render(interaction.user.id)] })
+ *   }
+ * }
+ * ```
+ *
+ * @group Decorators
+ * @category Controllers
+ * @see {@link Command}
+ * @see {@link ControllerOptions}
+ * @see {@link https://meocord.dev/docs/4.2/how-a-call-runs | How a call runs}
+ */ function Controller(options = {}) {
+    return controller_decorator.declaring(function(target, propertyKey) {
+        if (controller_decorator.deprecatedOnMethod('@Controller', target, propertyKey)) return;
+        providers.makeInjectable(target);
+        if (options.inheritStages === false) Reflect.defineMetadata(controller_decorator.META.inheritStages, false, target);
+        if (options.inheritedRoutes === 'replace') {
+            controller_decorator.dropInheritedRoutes(target.prototype);
+            Reflect.defineMetadata(controller_decorator.META.replacesInheritedRoutes, true, target.prototype);
+        }
+        providers.guardOwnHandlersWithBaseGuards(target);
+    });
 }
+
 /**
  * The class's own descriptor for a handler. An inherited handler gets one that calls the inherited
  * method, starting from its guard lists and wrapper count, so class guards wrap it like an own method.
@@ -157,26 +180,6 @@ require('chalk');
         ...inherited
     };
 }
-/**
- * Gives each handler a controller declares itself the class-level guards of the classes it extends,
- * as its inherited handlers have: recorded under `META.guards`, and wrapped so a direct call
- * runs them when no other guard wraps the handler. `@Controller` calls this.
- */ function guardOwnHandlersWithBaseGuards(target) {
-    const prototype = target.prototype;
-    for (const methodName of providers.handlerMethods(prototype)){
-        const descriptor = Object.getOwnPropertyDescriptor(prototype, methodName);
-        // Inherited handlers have the chain of the class that declares them
-        if (typeof descriptor?.value !== 'function' || Reflect.getOwnMetadata(controller_decorator.META.inheritedFrom, prototype, methodName)) continue;
-        // Base first, as dispatch runs them
-        const guards = providers.classChain(prototype, prototype).slice(1).reverse().flatMap(providers.classLevelGuards);
-        if (guards.length === 0) continue;
-        if (!Reflect.getOwnMetadata(controller_decorator.META.guardWrappers, prototype, methodName)) {
-            applyGuards(descriptor, prototype, methodName);
-            Object.defineProperty(prototype, methodName, descriptor);
-        }
-        recordGuards(controller_decorator.META.inheritedGuards, guards, prototype, methodName);
-    }
-}
 /**
  * Marks a class as a guard, which decides whether a handler runs.
  *
@@ -250,12 +253,12 @@ require('chalk');
  */ function UseGuard(...entries) {
     const guards = entries;
     return controller_decorator.declaring(function(target, propertyKey, descriptor) {
-        const where = propertyKey === undefined ? String(target?.name) : `${target.constructor.name}.${String(propertyKey)}`;
+        const where = controller_decorator.decoratedName(target, propertyKey);
         providers.assertStageEntries('@UseGuard', 'guard', where, guards);
         if (descriptor && propertyKey) {
             // Method Decorator
-            applyGuards(descriptor, target, String(propertyKey));
-            recordGuards(controller_decorator.META.methodGuards, guards, target, String(propertyKey));
+            providers.applyGuards(descriptor, target, String(propertyKey));
+            providers.recordGuards(controller_decorator.META.methodGuards, guards, target, String(propertyKey));
         } else if (typeof target === 'function' && !propertyKey && !descriptor) {
             // Class Decorator
             const prototype = target.prototype;
@@ -268,61 +271,15 @@ require('chalk');
             for (const methodName of methods){
                 const methodDescriptor = ownHandlerDescriptor(prototype, methodName);
                 if (methodDescriptor) {
-                    applyGuards(methodDescriptor, prototype, methodName);
+                    providers.applyGuards(methodDescriptor, prototype, methodName);
                     Object.defineProperty(prototype, methodName, methodDescriptor);
-                    recordGuards(controller_decorator.META.classGuards, guards, prototype, methodName);
+                    providers.recordGuards(controller_decorator.META.classGuards, guards, prototype, methodName);
                 }
             }
         }
     });
 }
 
-/**
- * Marks a class as a controller, whose methods handle commands, components, messages, reactions or events.
- *
- * Use it on every class of handlers, and list the class in `@MeoCord({ controllers })`. Logic the handlers
- * share, such as database access, belongs in a service it injects.
- *
- * @remarks
- * A controller's class-level guards and filters apply to every handler it declares or inherits, its interceptors to
- * all but autocomplete, and its cooldowns to its command, component and message handlers; each also applies to the
- * handlers of a class that extends it. A base wraps what extends it: guards and interceptors
- * run the top base's first, then each subclass's, then the method's, and filters are tried the other way, the
- * method's first. `inheritStages: false` keeps the handlers a subclass declares to its own stages.
- *
- * @param options - Whether the handlers it declares take the stages of the classes it extends.
- *
- * @example
- * ```ts
- * @Controller()
- * export class ProfileSlashController {
- *   constructor(private readonly profiles: ProfileService) {}
- *
- *   @Command('profile', CommandType.SLASH)
- *   async profile(interaction: ChatInputCommandInteraction) {
- *     await respond(interaction).send({ embeds: [await this.profiles.render(interaction.user.id)] })
- *   }
- * }
- * ```
- *
- * @group Decorators
- * @category Controllers
- * @see {@link Command}
- * @see {@link ControllerOptions}
- * @see {@link https://meocord.dev/docs/4.2/how-a-call-runs | How a call runs}
- */ function Controller(options = {}) {
-    return controller_decorator.declaring(function(target, propertyKey) {
-        if (controller_decorator.deprecatedOnMethod('@Controller', target, propertyKey)) return;
-        providers.makeInjectable(target);
-        if (options.inheritStages === false) Reflect.defineMetadata(controller_decorator.META.inheritStages, false, target);
-        if (options.inheritedRoutes === 'replace') {
-            controller_decorator.dropInheritedRoutes(target.prototype);
-            Reflect.defineMetadata(controller_decorator.META.replacesInheritedRoutes, true, target.prototype);
-        }
-        guardOwnHandlersWithBaseGuards(target);
-    });
-}
-
 /**
  * Marks a class as an interceptor, which wraps a handler to act before and after it.
  *
@@ -395,7 +352,7 @@ require('chalk');
  * @see {@link https://meocord.dev/docs/4.2/interceptors | Interceptors}
  */ function UseInterceptor(...interceptors) {
     return controller_decorator.declaring(function(target, propertyKey) {
-        const where = propertyKey === undefined ? target.name : `${target.constructor.name}.${String(propertyKey)}`;
+        const where = controller_decorator.decoratedName(target, propertyKey);
         providers.assertStageEntries('@UseInterceptor', 'interceptor', where, interceptors);
         // Decorators apply bottom-up, so a higher decorator's interceptors go first, as with @UseGuard.
         if (propertyKey === undefined) {
@@ -447,14 +404,14 @@ require('chalk');
         controller_decorator.refuseOnMethod('@Catch', target, propertyKey);
         providers.makeInjectable(target);
         errorTypes.forEach((type, index)=>{
-            if (controller_decorator.isConstructor(type)) return;
+            if (controller_decorator.isConstructible(type)) return;
             const entry = ORDINALS[index] ? `${ORDINALS[index]} entry` : `entry ${index + 1}`;
-            controller_decorator.warnDeprecatedBehaviour(logger$1, `${target.name}: @Catch's ${entry}, ${controller_decorator.describeValue(type)}, which matches no error,`, 'is refused', 'an error class, such as @Catch(CooldownError),');
+            controller_decorator.warnDeprecatedBehaviour(logger$2, `${target.name}: @Catch's ${entry}, ${controller_decorator.describeValue(type)}, which matches no error,`, 'is refused', 'an error class, such as @Catch(CooldownError),');
         });
         Reflect.defineMetadata(controller_decorator.META.catchTypes, errorTypes, target);
     });
 }
-const logger$1 = new controller_decorator.Logger('Catch');
+const logger$2 = new controller_decorator.Logger('Catch');
 const ORDINALS = [
     'first',
     'second',
@@ -495,7 +452,7 @@ const ORDINALS = [
  * @see {@link https://meocord.dev/docs/4.2/exception-filters | Exception filters}
  */ function UseFilter(...filters) {
     return controller_decorator.declaring(function(target, propertyKey) {
-        const where = propertyKey === undefined ? target.name : `${target.constructor.name}.${String(propertyKey)}`;
+        const where = controller_decorator.decoratedName(target, propertyKey);
         providers.assertStageEntries('@UseFilter', 'filter', where, filters);
         // Decorators apply bottom-up, so a higher decorator's filters are tried first.
         if (propertyKey === undefined) {
@@ -514,6 +471,7 @@ const ORDINALS = [
     });
 }
 
+const logger$1 = new controller_decorator.Logger('MeoCord');
 /** Refuses a `messages` option of the wrong type where the app is declared, rather than at the first message. */ function assertMessageOptions(appName, messages, i18n) {
     if (!messages) return;
     const { prefix, mention, caseSensitive } = messages;
@@ -541,6 +499,9 @@ const ORDINALS = [
     if (deleteUsageRepliesAfter !== undefined && !(typeof deleteUsageRepliesAfter === 'number' && deleteUsageRepliesAfter >= 0 && Number.isFinite(deleteUsageRepliesAfter))) {
         throw controller_decorator.refuse(new TypeError(`${appName}: @MeoCord({ messages: { deleteUsageRepliesAfter } }) takes a number of seconds, or 0 to keep usage replies.`));
     }
+    if (deleteUsageRepliesAfter !== undefined && !providers.timerKeepsSeconds(deleteUsageRepliesAfter)) {
+        logger$1.warn(`${appName}: @MeoCord({ messages: { deleteUsageRepliesAfter } }) is ${deleteUsageRepliesAfter} seconds, longer than a timer ` + `can wait (${providers.MAX_TIMER_SECONDS}), so usage replies are kept. The next major version (5.0) refuses it.`);
+    }
     const { help } = messages;
     // One word each, since help is asked for by its first word
     const isWord = (value)=>typeof value === 'string' && /^\S+$/.test(value);
@@ -555,6 +516,35 @@ const ORDINALS = [
         if (type.labelKey !== undefined) assertLabelKey(appName, name, type.labelKey, i18n);
     }
 }
+/**
+ * Refuses an option that takes a class given anything else, such as an object or an arrow function, where the app is
+ * declared: the startup checks read each class's prototype, and would otherwise fail on it without naming the option.
+ */ function assertClassOptions(appName, { presenter, cooldownStore, controllers, services }) {
+    for (const [name, value, implementing] of [
+        [
+            'presenter',
+            presenter,
+            'ResponsePresenter'
+        ],
+        [
+            'cooldownStore',
+            cooldownStore,
+            'CooldownStore'
+        ]
+    ]){
+        if (value !== undefined && !controller_decorator.isConstructor(value)) {
+            throw controller_decorator.refuse(new TypeError(`${appName}: @MeoCord({ ${name} }) takes a class implementing ${implementing}, not ${controller_decorator.describeValue(value)}.`));
+        }
+    }
+    for (const controller of controllers ?? []){
+        if (!controller_decorator.isConstructor(controller)) throw controller_decorator.refuse(new TypeError(`${appName}: @MeoCord({ controllers }) takes classes, not ${controller_decorator.describeValue(controller)}.`));
+    }
+    // A string or symbol is a token, which a provider has to provide; that is checked as the app is created
+    for (const service of services ?? []){
+        if (controller_decorator.isConstructor(service) || typeof service === 'string' || typeof service === 'symbol') continue;
+        throw controller_decorator.refuse(new TypeError(`${appName}: @MeoCord({ services }) takes classes, or tokens that providers provide, not ${controller_decorator.describeValue(service)}.`));
+    }
+}
 /** Refuses a type's `labelKey` that no message of the app's default catalog has, as it would be shown as the key. */ function assertLabelKey(appName, name, labelKey, i18n) {
     const where = `${appName}: @MeoCord({ messages: { types } }): "${name}" has labelKey`;
     if (typeof labelKey !== 'string') throw controller_decorator.refuse(new TypeError(`${where} ${String(labelKey)}; it takes a message key, such as 'types.${name}'.`));
@@ -599,6 +589,7 @@ const ORDINALS = [
  */ function MeoCord(options) {
     return controller_decorator.declaring((target, propertyKey)=>{
         if (controller_decorator.deprecatedOnMethod('@MeoCord', target, propertyKey)) return;
+        assertClassOptions(target.name, options);
         providers.assertStageEntries('@MeoCord({ guards })', 'guard', target.name, options.guards ?? []);
         providers.assertStageEntries('@MeoCord({ interceptors })', 'interceptor', target.name, options.interceptors ?? []);
         providers.assertStageEntries('@MeoCord({ filters })', 'filter', target.name, options.filters ?? []);
@@ -693,15 +684,15 @@ const ORDINALS = [
         controller_decorator.refuseOnClass('@Validate', target, propertyKey);
         // Checked where it applies, so the refusal names the handler
         if (typeof schema?.['~standard']?.validate !== 'function') {
-            throw controller_decorator.refuse(new Error(`${target.constructor.name}.${propertyKey}: @Validate takes a Standard Schema, such as a zod, valibot or arktype schema.`));
+            throw controller_decorator.refuse(new Error(`${controller_decorator.decoratedName(target, propertyKey)}: @Validate takes a Standard Schema, such as a zod, valibot or arktype schema.`));
         }
         if (Reflect.hasOwnMetadata(controller_decorator.META.methodValidation, target, propertyKey)) {
-            throw controller_decorator.refuse(new Error(`${target.constructor.name}.${propertyKey}: more than one @Validate; one @Validate per handler: combine the schemas into one.`));
+            throw controller_decorator.refuse(new Error(`${controller_decorator.decoratedName(target, propertyKey)}: more than one @Validate; one @Validate per handler: combine the schemas into one.`));
         }
         const inlinePipes = Object.values(options.pipes ?? {}).flatMap((entries)=>Array.isArray(entries) ? entries : [
                 entries
             ]);
-        providers.assertStageEntries('@Validate', 'pipe', `${target.constructor.name}.${propertyKey}`, inlinePipes);
+        providers.assertStageEntries('@Validate', 'pipe', controller_decorator.decoratedName(target, propertyKey), inlinePipes);
         const metadata = {
             schema,
             pipes: options.pipes ?? {}
@@ -743,7 +734,7 @@ const ORDINALS = [
  */ function UsePipe(key, ...pipes) {
     return controller_decorator.declaring(function(target, propertyKey, _descriptor) {
         controller_decorator.refuseOnClass('@UsePipe', target, propertyKey);
-        providers.assertStageEntries('@UsePipe', 'pipe', `${target.constructor.name}.${propertyKey}`, pipes);
+        providers.assertStageEntries('@UsePipe', 'pipe', controller_decorator.decoratedName(target, propertyKey), pipes);
         // Decorators apply bottom-up, so a higher @UsePipe's pipes go first, in the order they read.
         const existing = Reflect.getOwnMetadata(controller_decorator.META.methodPipes, target, propertyKey) ?? [];
         Reflect.defineMetadata(controller_decorator.META.methodPipes, [
@@ -891,7 +882,7 @@ const logger = new controller_decorator.Logger('Cooldown');
         controller_decorator.refuseOnClass('@Defer', target, propertyKey);
         const methodName = String(propertyKey);
         const kind = providers.nonInteractionHandler(target, methodName);
-        if (kind) throw controller_decorator.refuse(providers.deferMisuseError(target.constructor.name, methodName, kind));
+        if (kind) throw controller_decorator.refuse(providers.deferMisuseError(controller_decorator.ownerName(target), methodName, kind));
         Reflect.defineMetadata(controller_decorator.META.deferOptions, {
             ...options
         }, target, methodName);
@@ -927,6 +918,9 @@ const logger = new controller_decorator.Logger('Cooldown');
     return controller_decorator.declaring((target, propertyKey, parameterIndex)=>{
         // A constructor parameter has no property key either, but has an index
         if (typeof parameterIndex !== 'number') controller_decorator.refuseOnClass('@Inject', target, propertyKey, 'a constructor parameter or a property');
+        else if (propertyKey !== undefined) {
+            throw controller_decorator.refuse(new Error(`${controller_decorator.decoratedName(target, propertyKey)}: @Inject goes on a constructor parameter or a property, not a method parameter.`));
+        }
         decorate(target, propertyKey, parameterIndex);
     });
 }
@@ -1007,8 +1001,9 @@ const logger = new controller_decorator.Logger('Cooldown');
  */ function UseTheme(theme) {
     return controller_decorator.declaring(function(target, propertyKey) {
         const onClass = propertyKey === undefined;
-        const owner = onClass ? target : target.constructor;
-        const where = `${owner.name}${onClass ? '' : `.${String(propertyKey)}`}: @UseTheme`;
+        // The class it themes: the target itself on a class or a static member, else the target's constructor
+        const owner = onClass || typeof target === 'function' ? target : target.constructor;
+        const where = `${controller_decorator.decoratedName(target, propertyKey)}: @UseTheme`;
         controller_decorator.assertValidTheme(theme, where);
         const key = onClass ? controller_decorator.META.classTheme : controller_decorator.META.methodTheme;
         const existing = onClass ? Reflect.getOwnMetadata(key, target) : Reflect.getOwnMetadata(key, target, propertyKey);