meocord 4.1.2 → 4.2.1

package/dist/cjs/decorator/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
 require('reflect-metadata');
-var providers = require('../_shared/providers-BMMLp2SN.cjs');
-var controller_decorator = require('../_shared/controller.decorator-BywwkU9O.cjs');
+var providers = require('../_shared/providers-BZgJyfZS.cjs');
+var controller_decorator = require('../_shared/controller.decorator-XKMlcUZz.cjs');
 var inversify = require('inversify');
 require('node:async_hooks');
 require('../enum/index.cjs');
@@ -46,12 +46,12 @@ require('chalk');
  * @group Decorators
  * @category App
  * @see {@link Inject}
- * @see {@link https://meocord.dev/docs/4.1/services | Services}
+ * @see {@link https://meocord.dev/docs/4.2/services | Services}
  */ function Service() {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         if (controller_decorator.deprecatedOnMethod('@Service', target, propertyKey)) return;
         providers.makeInjectable(target);
-    };
+    });
 }
 
 /**
@@ -81,9 +81,9 @@ require('chalk');
  * @group Decorators
  * @category Handlers
  * @see {@link Command}
- * @see {@link https://meocord.dev/docs/4.1/slash-commands | Slash commands}
+ * @see {@link https://meocord.dev/docs/4.2/slash-commands | Slash commands}
  */ function CommandBuilder(commandType, options = {}) {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         if (controller_decorator.deprecatedOnMethod('@CommandBuilder', target, propertyKey)) return;
         providers.makeInjectable(target);
         // Define the command type metadata for the target class
@@ -91,7 +91,7 @@ require('chalk');
         if (options.guilds) Reflect.defineMetadata(controller_decorator.META.builderGuilds, [
             ...options.guilds
         ], target);
-    };
+    });
 }
 
 /**
@@ -123,10 +123,10 @@ require('chalk');
  * which has already run the guards, passes through every wrapper.
  */ function applyGuards(descriptor, prototype, propertyKey) {
     const originalMethod = descriptor.value;
-    descriptor.value = async function(...args) {
+    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);
 }
@@ -208,14 +208,14 @@ require('chalk');
  * @see {@link UseGuard}
  * @see {@link GuardDeniedError}
  * @see {@link ExecutionContext}
- * @see {@link https://meocord.dev/docs/4.1/guards | Guards}
+ * @see {@link https://meocord.dev/docs/4.2/guards | Guards}
  */ function Guard(options = {}) {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         if (controller_decorator.deprecatedOnMethod('@Guard', target, propertyKey)) return;
         providers.makeInjectable(target);
         providers.defineStageTypes(target, options.types, 'Guard');
         Reflect.defineMetadata(controller_decorator.META.guardClass, true, target);
-    };
+    });
 }
 /**
  * Runs guards before a handler, or before every handler of a controller.
@@ -246,10 +246,10 @@ require('chalk');
  * @see {@link Guard}
  * @see {@link GuardDeniedError}
  * @see {@link ExecutionContext}
- * @see {@link https://meocord.dev/docs/4.1/guards | Guards}
+ * @see {@link https://meocord.dev/docs/4.2/guards | Guards}
  */ function UseGuard(...entries) {
     const guards = entries;
-    return function(target, propertyKey, descriptor) {
+    return controller_decorator.declaring(function(target, propertyKey, descriptor) {
         const where = propertyKey === undefined ? String(target?.name) : `${target.constructor.name}.${String(propertyKey)}`;
         providers.assertStageEntries('@UseGuard', 'guard', where, guards);
         if (descriptor && propertyKey) {
@@ -274,7 +274,7 @@ require('chalk');
                 }
             }
         }
-    };
+    });
 }
 
 /**
@@ -309,14 +309,18 @@ require('chalk');
  * @category Controllers
  * @see {@link Command}
  * @see {@link ControllerOptions}
- * @see {@link https://meocord.dev/docs/4.1/how-a-call-runs | How a call runs}
+ * @see {@link https://meocord.dev/docs/4.2/how-a-call-runs | How a call runs}
  */ function Controller(options = {}) {
-    return function(target, propertyKey) {
+    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);
-    };
+    });
 }
 
 /**
@@ -351,13 +355,13 @@ require('chalk');
  * @group Decorators
  * @category Pipeline stages
  * @see {@link UseInterceptor}
- * @see {@link https://meocord.dev/docs/4.1/interceptors | Interceptors}
+ * @see {@link https://meocord.dev/docs/4.2/interceptors | Interceptors}
  */ function Interceptor(options = {}) {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         controller_decorator.refuseOnMethod('@Interceptor', target, propertyKey);
         providers.makeInjectable(target);
         providers.defineStageTypes(target, options.types, 'Interceptor');
-    };
+    });
 }
 /**
  * Runs interceptors around a handler, or around every handler of a controller.
@@ -388,9 +392,9 @@ require('chalk');
  * @group Decorators
  * @category Pipeline stages
  * @see {@link Interceptor}
- * @see {@link https://meocord.dev/docs/4.1/interceptors | Interceptors}
+ * @see {@link https://meocord.dev/docs/4.2/interceptors | Interceptors}
  */ function UseInterceptor(...interceptors) {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         const where = propertyKey === undefined ? target.name : `${target.constructor.name}.${String(propertyKey)}`;
         providers.assertStageEntries('@UseInterceptor', 'interceptor', where, interceptors);
         // Decorators apply bottom-up, so a higher decorator's interceptors go first, as with @UseGuard.
@@ -407,7 +411,7 @@ require('chalk');
                 ...existing
             ], target, propertyKey);
         }
-    };
+    });
 }
 
 /**
@@ -437,20 +441,20 @@ require('chalk');
  * @group Decorators
  * @category Pipeline stages
  * @see {@link UseFilter}
- * @see {@link https://meocord.dev/docs/4.1/exception-filters | Exception filters}
+ * @see {@link https://meocord.dev/docs/4.2/exception-filters | Exception filters}
  */ function Catch(...errorTypes) {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         controller_decorator.refuseOnMethod('@Catch', target, propertyKey);
         providers.makeInjectable(target);
         errorTypes.forEach((type, index)=>{
             if (controller_decorator.isConstructor(type)) return;
             const entry = ORDINALS[index] ? `${ORDINALS[index]} entry` : `entry ${index + 1}`;
-            controller_decorator.warnDeprecatedBehaviour(logger, `${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$1, `${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 = new controller_decorator.Logger('Catch');
+const logger$1 = new controller_decorator.Logger('Catch');
 const ORDINALS = [
     'first',
     'second',
@@ -488,9 +492,9 @@ const ORDINALS = [
  * @group Decorators
  * @category Pipeline stages
  * @see {@link Catch}
- * @see {@link https://meocord.dev/docs/4.1/exception-filters | Exception filters}
+ * @see {@link https://meocord.dev/docs/4.2/exception-filters | Exception filters}
  */ function UseFilter(...filters) {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         const where = propertyKey === undefined ? target.name : `${target.constructor.name}.${String(propertyKey)}`;
         providers.assertStageEntries('@UseFilter', 'filter', where, filters);
         // Decorators apply bottom-up, so a higher decorator's filters are tried first.
@@ -507,7 +511,7 @@ const ORDINALS = [
                 ...existing
             ], target, propertyKey);
         }
-    };
+    });
 }
 
 /** Refuses a `messages` option of the wrong type where the app is declared, rather than at the first message. */ function assertMessageOptions(appName, messages, i18n) {
@@ -517,14 +521,19 @@ const ORDINALS = [
     if (prefix !== undefined && !isText(prefix) && typeof prefix !== 'function' && !(Array.isArray(prefix) && prefix.every(isText))) {
         throw controller_decorator.refuse(new TypeError(`${appName}: @MeoCord({ messages: { prefix } }) takes a string, a list of strings, or a function of the message returning them.`));
     }
-    for (const [name, value] of Object.entries({
+    const flags = {
         caseSensitive,
         replyEmoji: messages.replyEmoji,
         dmOnError: messages.dmOnError,
-        dmOnCooldown: messages.dmOnCooldown
-    })){
+        dmOnCooldown: messages.dmOnCooldown,
+        slowHandlerWarning: messages.slowHandlerWarning
+    };
+    for (const [name, value] of Object.entries(flags)){
         if (value !== undefined && typeof value !== 'boolean') throw controller_decorator.refuse(new TypeError(`${appName}: @MeoCord({ messages: { ${name} } }) takes true or false.`));
     }
+    if (messages.handlers !== undefined && messages.handlers !== 'sequential' && messages.handlers !== 'concurrent') {
+        throw controller_decorator.refuse(new TypeError(`${appName}: @MeoCord({ messages: { handlers } }) takes 'sequential' or 'concurrent'.`));
+    }
     if (mention !== undefined && typeof mention !== 'boolean' && mention !== 'only') {
         throw controller_decorator.refuse(new TypeError(`${appName}: @MeoCord({ messages: { mention } }) takes true, false or 'only'.`));
     }
@@ -586,9 +595,9 @@ const ORDINALS = [
  * @see {@link MeoCordOptions}
  * @see {@link MeoCordFactory}
  * @see {@link MeoCordConfig}
- * @see {@link https://meocord.dev/docs/4.1/configuration | Configuration}
+ * @see {@link https://meocord.dev/docs/4.2/configuration | Configuration}
  */ function MeoCord(options) {
-    return (target, propertyKey)=>{
+    return controller_decorator.declaring((target, propertyKey)=>{
         if (controller_decorator.deprecatedOnMethod('@MeoCord', target, propertyKey)) return;
         providers.assertStageEntries('@MeoCord({ guards })', 'guard', target.name, options.guards ?? []);
         providers.assertStageEntries('@MeoCord({ interceptors })', 'interceptor', target.name, options.interceptors ?? []);
@@ -610,7 +619,7 @@ const ORDINALS = [
             ...options,
             theme
         }, target);
-    };
+    });
 }
 /** Refuses theme resolvers and cache options the runtime cannot follow, where the app is declared. */ function assertThemeFor(appName, { themeFor, themeCache, themeForTimeoutMs }) {
     const problem = themeFor === undefined ? undefined : controller_decorator.themeForProblem(themeFor, `${appName}: @MeoCord({ themeFor })`, 'or a class implementing ThemeResolver.');
@@ -678,9 +687,9 @@ const ORDINALS = [
  * @category Pipeline stages
  * @see {@link UsePipe}
  * @see {@link ValidationError}
- * @see {@link https://meocord.dev/docs/4.1/validation | Validation and pipes}
+ * @see {@link https://meocord.dev/docs/4.2/validation | Validation and pipes}
  */ function Validate(schema, options = {}) {
-    return function(target, propertyKey, _descriptor) {
+    return controller_decorator.declaring(function(target, propertyKey, _descriptor) {
         controller_decorator.refuseOnClass('@Validate', target, propertyKey);
         // Checked where it applies, so the refusal names the handler
         if (typeof schema?.['~standard']?.validate !== 'function') {
@@ -698,7 +707,7 @@ const ORDINALS = [
             pipes: options.pipes ?? {}
         };
         Reflect.defineMetadata(controller_decorator.META.methodValidation, metadata, target, propertyKey);
-    };
+    });
 }
 /**
  * Runs pipes on one value of a handler's input, to turn it into what the handler works with.
@@ -730,9 +739,9 @@ const ORDINALS = [
  * @category Pipeline stages
  * @see {@link Pipe}
  * @see {@link Validate}
- * @see {@link https://meocord.dev/docs/4.1/validation | Validation and pipes}
+ * @see {@link https://meocord.dev/docs/4.2/validation | Validation and pipes}
  */ function UsePipe(key, ...pipes) {
-    return function(target, propertyKey, _descriptor) {
+    return controller_decorator.declaring(function(target, propertyKey, _descriptor) {
         controller_decorator.refuseOnClass('@UsePipe', target, propertyKey);
         providers.assertStageEntries('@UsePipe', 'pipe', `${target.constructor.name}.${propertyKey}`, pipes);
         // Decorators apply bottom-up, so a higher @UsePipe's pipes go first, in the order they read.
@@ -744,7 +753,7 @@ const ORDINALS = [
                 })),
             ...existing
         ], target, propertyKey);
-    };
+    });
 }
 /**
  * Marks a class as a pipe, which turns one input value into what the handler works with.
@@ -770,12 +779,12 @@ const ORDINALS = [
  * @group Decorators
  * @category Pipeline stages
  * @see {@link UsePipe}
- * @see {@link https://meocord.dev/docs/4.1/validation | Validation and pipes}
+ * @see {@link https://meocord.dev/docs/4.2/validation | Validation and pipes}
  */ function Pipe() {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         controller_decorator.refuseOnMethod('@Pipe', target, propertyKey);
         providers.makeInjectable(target);
-    };
+    });
 }
 
 function Cooldown(options) {
@@ -786,10 +795,11 @@ function Cooldown(options) {
         per,
         windowMs: Math.round(seconds * 1000)
     };
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         // Checked where it applies, so the refusal names the handler or controller
         const problem = cooldownProblem(seconds, uses, per, by);
         if (problem) throw controller_decorator.refuse(new Error(`${controller_decorator.decoratedName(target, propertyKey)}: ${problem}`));
+        for (const warning of cooldownWarnings(options))logger.warn(`${controller_decorator.decoratedName(target, propertyKey)}: ${warning}`);
         // Decorators apply bottom-up; prepending keeps them in the order they read.
         if (propertyKey === undefined) {
             const existing = Reflect.getOwnMetadata(controller_decorator.META.classCooldowns, target) ?? [];
@@ -804,12 +814,26 @@ function Cooldown(options) {
                 ...existing
             ], target, propertyKey);
         }
-    };
+    });
 }
 /**
  * The longest window, in seconds: half the furthest time a `Date` holds, 8.64e15 ms, so the moment a wait ends, now
  * plus the window, is a real date for a refusal's `retryAt` and the time it shows.
  */ const MAX_SECONDS = 4320000000000;
+const logger = new controller_decorator.Logger('Cooldown');
+/**
+ * What a cooldown's options get wrong that the types refuse, yet still counts: a `bypass` that is not a function, which
+ * fails every call, and a `seconds` that is not a number, read as one. A falsy `bypass` means none.
+ */ function cooldownWarnings({ seconds, bypass }) {
+    const warnings = [];
+    if (bypass && typeof bypass !== 'function') {
+        warnings.push(`@Cooldown takes bypass as a function of the call, returning whether the call skips the cooldown, not ${controller_decorator.describeValue(bypass)}; ` + 'every call it counts fails with it. In the next major version (5.0) it is refused.');
+    }
+    if (typeof seconds !== 'number') {
+        warnings.push(`@Cooldown takes seconds as a number, not ${controller_decorator.describeValue(seconds)}, which it counts as a window of ` + `${Math.round(seconds * 1000)} ms. In the next major version (5.0) it is refused.`);
+    }
+    return warnings;
+}
 /** Why a cooldown's options cannot be counted, or undefined when they can. */ function cooldownProblem(seconds, uses, per, by) {
     if (!(seconds >= 0.001 && seconds <= MAX_SECONDS)) return `@Cooldown needs a number of seconds from 0.001 to ${MAX_SECONDS}, not ${seconds}.`;
     if (!Number.isInteger(uses) || uses < 1) return `@Cooldown needs a whole number of uses of at least 1, not ${uses}.`;
@@ -861,9 +885,9 @@ function Cooldown(options) {
  * @category Pipeline stages
  * @see {@link DeferOptions}
  * @see {@link respond}
- * @see {@link https://meocord.dev/docs/4.1/defer | Deferring}
+ * @see {@link https://meocord.dev/docs/4.2/defer | Deferring}
  */ function Defer(options = {}) {
-    return (target, propertyKey)=>{
+    return controller_decorator.declaring((target, propertyKey)=>{
         controller_decorator.refuseOnClass('@Defer', target, propertyKey);
         const methodName = String(propertyKey);
         const kind = providers.nonInteractionHandler(target, methodName);
@@ -871,7 +895,7 @@ function Cooldown(options) {
         Reflect.defineMetadata(controller_decorator.META.deferOptions, {
             ...options
         }, target, methodName);
-    };
+    });
 }
 
 /**
@@ -897,14 +921,14 @@ function Cooldown(options) {
  * @category Params
  * @see {@link Service}
  * @see {@link createToken}
- * @see {@link https://meocord.dev/docs/4.1/services | Services}
+ * @see {@link https://meocord.dev/docs/4.2/services | Services}
  */ function Inject(token) {
     const decorate = inversify.inject(token);
-    return (target, propertyKey, parameterIndex)=>{
+    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');
         decorate(target, propertyKey, parameterIndex);
-    };
+    });
 }
 
 /**
@@ -938,9 +962,9 @@ function Cooldown(options) {
  * @pipeline observers-settled once the call has settled and been answered, however it ended
  * @group Decorators
  * @category Pipeline stages
- * @see {@link https://meocord.dev/docs/4.1/observers | Observers}
+ * @see {@link https://meocord.dev/docs/4.2/observers | Observers}
  */ function Observer(options = {}) {
-    return function(target, propertyKey) {
+    return controller_decorator.declaring(function(target, propertyKey) {
         controller_decorator.refuseOnMethod('@Observer', target, propertyKey);
         if (typeof target.prototype.onSettled !== 'function') {
             throw controller_decorator.refuse(new Error(`${target.name}: an @Observer needs an onSettled method, and it has none.`));
@@ -948,7 +972,7 @@ function Cooldown(options) {
         providers.makeInjectable(target);
         providers.defineStageTypes(target, options.types, 'Observer');
         Reflect.defineMetadata(controller_decorator.META.observerClass, true, target);
-    };
+    });
 }
 
 /**
@@ -981,7 +1005,7 @@ function Cooldown(options) {
  * @group Decorators
  * @category Controllers
  */ function UseTheme(theme) {
-    return function(target, propertyKey) {
+    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`;
@@ -993,7 +1017,7 @@ function Cooldown(options) {
         if (onClass) Reflect.defineMetadata(key, layer, target);
         else Reflect.defineMetadata(key, layer, target, propertyKey);
         providers.THEMED_CLASSES.add(owner);
-    };
+    });
 }
 
 exports.On = providers.On;