meocord 4.2.2 → 4.2.3

package/dist/esm/core/lifecycle-hooks.js

@@ -49,9 +49,9 @@ import { RunningCalls } from './running-calls.js';
 }
 /**
  * Resolves each unit and runs its `onReady` one at a time, in the units' dependency order. A failure is
- * reported and the next unit still runs. Each unit whose `onReady` settled, or that has none, is pushed
- * to `entries` as it finishes, so a shutdown that starts meanwhile closes exactly those.
- */ async function runReadyHooks(container, units, client, info, entries, report, { stopped = ()=>false, slowAfterMs, settled, runOnReady } = {}) {
+ * reported and the next unit still runs. `settled` hears of each unit as its `onReady` settles, or once it is found
+ * to have none, which is what a shutdown that starts meanwhile reads.
+ */ async function runReadyHooks(container, units, client, info, report, { stopped = ()=>false, slowAfterMs, settled, runOnReady } = {}) {
     const failed = new Set();
     // For each unit, the failed units it depends on, directly or through another dependency
     const failedUpstream = new Map();
@@ -88,11 +88,7 @@ import { RunningCalls } from './running-calls.js';
             continue;
         }
         firstToken.set(instance, unit.token);
-        const entry = lifecycleEntry(unit, instance);
-        // Only a unit whose onReady has settled, or that has none, is shut down: a stop mid-ready waits for the one still
-        // starting, within its time, and skips those not reached yet
         if (typeof instance.onReady !== 'function') {
-            entries.push(entry);
             settled?.(unit);
             continue;
         }
@@ -109,7 +105,6 @@ import { RunningCalls } from './running-calls.js';
         } finally{
             clearTimeout(slow);
         }
-        entries.push(entry);
         settled?.(unit);
     }
 }

package/dist/esm/core/lifecycle-order.js

@@ -1,5 +1,4 @@
 import { Client } from 'discord.js';
-import { injectedTokens } from './guard-runner.js';
 
 /**
  * The whole source the runtime gives a native function, such as `function NumberFormat() { [native code] }`. A class's
@@ -11,18 +10,5 @@ import { injectedTokens } from './guard-runner.js';
  */ function isAppClassToken(token) {
     return typeof token === 'function' && token !== Client && !NATIVE_SOURCE.test(Function.prototype.toString.call(token));
 }
-/**
- * The bound classes `cls` injects, by constructor type or `@inject` token: the classes whose hooks
- * run before its own.
- */ function lifecycleDependencies(container, cls) {
-    return injectedTokens(cls).filter((token)=>isAppClassToken(token) && container.isBound(token));
-}
-/** 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)
-        }));
-}
 
-export { classUnits, isAppClassToken, lifecycleDependencies };
+export { isAppClassToken };

package/dist/esm/core/meocord-classes.js

@@ -1,3 +1,4 @@
+import { Client } from 'discord.js';
 import { CooldownStore } from '../common/cooldown-store.js';
 import { CooldownError, CooldownStoreError, GuardDeniedError, MessageUsageError, UserError, ValidationError } from '../common/errors.js';
 import { ExecutionContext } from '../common/execution-context.js';
@@ -16,6 +17,18 @@ import { ThemeCache } from './theme-resolvers.js';
         ThemeCache,
         Translator
     ];
+/**
+ * The tokens the bot binds before an app's providers, which `@MeoCord({ providers })` cannot provide: `Translator` too
+ * when the app gives `i18n`.
+ */ const boundBeforeProviders = (i18n)=>[
+        Client,
+        HandlerRegistry,
+        ShardContext,
+        CooldownStore,
+        ...i18n ? [
+            Translator
+        ] : []
+    ];
 const created = (cls)=>`create it with \`new ${cls.name}(…)\``;
 /** What to do in place of injecting each of MeoCord's classes an app makes itself; the testing module adds its own. */ const advice = new Map([
     [
@@ -45,4 +58,4 @@ const created = (cls)=>`create it with \`new ${cls.name}(…)\``;
     advice.set(cls, instead);
 }
 
-export { adviseInPlaceOfInjecting, meocordClassAdvice, meocordClasses };
+export { adviseInPlaceOfInjecting, boundBeforeProviders, meocordClassAdvice, meocordClasses };

package/dist/esm/core/meocord-factory.js

@@ -3,9 +3,7 @@ import { COOLDOWN_POLICY, cooldownPolicyFrom, handlerCooldowns } from './cooldow
 import { Container } from 'inversify';
 import { Client } from 'discord.js';
 import { Logger } from '../common/logger.js';
-import { warnOnce } from '../common/deprecation.js';
-import './theme-scope.js';
-import './theme-validation.js';
+import '../common/theme.js';
 import '../common/decorator.js';
 import { ExecutionContext } from '../common/execution-context.js';
 import '../common/errors.js';
@@ -13,31 +11,34 @@ import { CooldownStore, MemoryCooldownStore } from '../common/cooldown-store.js'
 import 'node:crypto';
 import { getCommandMap, getMessageHandlers } from '../decorator/controller.decorator.js';
 import './scalar-types.js';
+import '../common/deprecation.js';
 import { processShardingEnabled, shardingRole, clientOptionsWithSharding } from '../util/sharding-mode.util.js';
-import { Translator, missingTranslatorError } from '../common/translator.js';
+import { Translator } from '../common/translator.js';
 import { registerClientTranslator } from '../common/meocord-text.js';
 import '../common/response/response-state.js';
 import { isExplainedError, markExplained } from '../common/explained-error.js';
-import { themeResolverClass, ThemeCache } from './theme-resolvers.js';
+import './theme-scope.js';
+import { themeResolverClass } from './theme-resolvers.js';
 import { MeoCordApp } from './meocord.app.js';
 import { loadMeoCordConfig, compiledConfigMessage } from '../util/meocord-config-loader.util.js';
 import { bunDevelopmentValues, bunDevelopmentWarning } from '../util/inherited-env.util.js';
 import { isRegisterOnly } from '../util/registration-mode.util.js';
-import { recordInstanceContainers, injectedTokens, singletonContextError } from './guard-runner.js';
+import { prepareDirectCalls, injectedTokens, singletonContextError } from './guard-runner.js';
 import { appStages, bindGlobalStages, prepareHandlerStages, prepareThemes, bindAppPresenter } from './handler-pipeline.js';
-import { startupClasses, assertStartupClasses, lateGuardCheck, stageDependencies } from './startup-roots.js';
+import { startupClasses, assertStartupClasses, lateGuardCheck, stageDependencies, perCallEventWarnings } from './startup-roots.js';
+import { eventSources } from './event-sources.js';
 import { markStartupChecked, assertStartupChecked } from './startup-checked.js';
 import { makeInjectable } from '../util/injectable.util.js';
 import { meocordClasses } from './meocord-classes.js';
 import { buildMessageRoutes } from './message-routes.js';
 import { appObservers, bindObservers } from './observer-runner.js';
 import { isAppClassToken } from './lifecycle-order.js';
-import { reachableClasses, providerMap, assertProvidedServices, bindsOwnToken, tokenName, bindProvider, resolutionOrder, isClassProvider, assertProvided, tokenDependencies, resolveProviders } from './providers.js';
-import { HandlerRegistry } from './handler-registry.js';
+import { providerMap, assertProvidedServices, bindsOwnToken, appProviderRefusal, bindProvider, resolutionOrder, isClassProvider, assertProvided, tokenDependencies, tokenName, resolveProviders, isValueProvider, forgetFactoryValues } from './providers.js';
+import { HandlerRegistry, listEventSources } from './handler-registry.js';
 import { ShardManager } from './shard-manager.js';
 import { warnUnregisteredCommands, warnInheritedRoutes, warnOverlappingPatterns, warnHandlersOffControllers, assertDistinctCommands } from './command-conflicts.js';
 import { ShardContext, SHARD_CALL_KEY, shardCallHandler } from './shard-context.js';
-import { registerClientTheme } from './theme-runtime.js';
+import { prepareLateThemes, registerClientTheme } from './theme-runtime.js';
 import { isRefusal, logStartupErrors, describeRefusal, allDeclaredErrors, declaredErrorsOf, collectStartupErrors, refuse, startupError, stopOnStartupErrors } from '../util/refusal.util.js';
 import { endFailedShard } from './shard-exit.js';
 import { isBuiltApplication } from '../util/bundle-entry.util.js';
@@ -55,8 +56,7 @@ import { isShardProcess } from '../util/shard-process.util.js';
     container.bind(cls).toSelf().inSingletonScope();
     // By constructor type or @inject token; an interface-typed parameter records Object, which is skipped
     for (const dep of injectedTokens(cls)){
-        if (dep === Translator && !container.isBound(Translator)) startupError(missingTranslatorError(cls));
-        else if (isAppClassToken(dep)) bindDependencies(container, dep, providers);
+        if (isAppClassToken(dep)) bindDependencies(container, dep, providers);
     }
 }
 /**
@@ -145,6 +145,10 @@ import { isShardProcess } from '../util/shard-process.util.js';
                     markExplained(error);
                 }
             }
+            // A built bot that refuses its app exits 1, as one whose start fails does, whatever main.ts does with the error
+            if (!shard && isBuiltApplication() && isRefusal(error) && (process.exitCode === undefined || process.exitCode === 0)) {
+                process.exitCode = 1;
+            }
             throw error;
         }
     }
@@ -182,24 +186,24 @@ import { isShardProcess } from '../util/shard-process.util.js';
         });
         // A themeFor class is bound on its own, as the cooldown store is, and resolved like a service
         const themeResolver = themeResolverClass(options.themeFor);
-        // The app's classes and every class they inject, which the container binds
-        const roots = [
-            ...options.controllers,
-            ...options.services ?? [],
-            ...themeResolver ? [
-                themeResolver
-            ] : [],
-            ...options.cooldownStore ? [
-                options.cooldownStore
-            ] : [],
-            ...appObservers(target)
-        ];
+        // Every class the app runs, its stages and presenter and what they inject included
+        const stages = appStages(target);
+        const runs = startupClasses({
+            controllers: options.controllers,
+            services: options.services ?? [],
+            providers,
+            stages,
+            presenter: options.presenter,
+            cooldownStore: options.cooldownStore,
+            themeFor: options.themeFor,
+            observers: appObservers(target)
+        });
         // A shard's manager runs the same checks, so a sharded bot warns once
         if (!shard) {
             warnUnregisteredCommands(options.controllers);
             warnInheritedRoutes(options.controllers);
             warnOverlappingPatterns(options.controllers);
-            warnHandlersOffControllers(options.controllers, reachableClasses(roots, providers));
+            warnHandlersOffControllers(options.controllers, runs.classes);
             const developmentEnv = bunDevelopmentValues();
             if (developmentEnv.keys.length > 0) {
                 this.logger.warn(bunDevelopmentWarning(developmentEnv));
@@ -220,19 +224,8 @@ import { isShardProcess } from '../util/shard-process.util.js';
         }
         // The checks of what the app binds and runs report every error each finds, and the first is thrown
         return collectStartupErrors(()=>{
-            // Every class the app runs, its stages and presenter included, checked before binding, where inversify would
-            // otherwise fail first with an error about compiler options, or a guard only at its first call
-            const stages = appStages(target);
-            const runs = startupClasses({
-                controllers: options.controllers,
-                services: options.services ?? [],
-                providers,
-                stages,
-                presenter: options.presenter,
-                cooldownStore: options.cooldownStore,
-                themeFor: options.themeFor,
-                observers: appObservers(target)
-            });
+            // Every class the app runs checked before binding, where inversify would otherwise fail first with an error about
+            // compiler options, or a guard only at its first call
             assertStartupClasses(runs, {
                 translator: options.i18n !== undefined || providers.has(Translator)
             });
@@ -257,7 +250,8 @@ import { isShardProcess } from '../util/shard-process.util.js';
             }
             // Bound before the app's classes, so a class that injects it gets this instance; filled once they are bound
             const appClasses = [];
-            container.bind(HandlerRegistry).toConstantValue(new HandlerRegistry(appClasses, options.messages, ()=>options.i18n));
+            const registry = new HandlerRegistry(appClasses, options.messages, ()=>options.i18n, options.controllers);
+            container.bind(HandlerRegistry).toConstantValue(registry);
             container.bind(ShardContext).toDynamicValue(()=>{
                 const client = container.get(Client);
                 return new ShardContext(client, (service, method, args)=>Reflect.get(client, SHARD_CALL_KEY)(service, method, args));
@@ -277,12 +271,9 @@ import { isShardProcess } from '../util/shard-process.util.js';
             // After MeoCord's own tokens, which a provider may not replace, and before the app's classes, so
             // a class token that is provided is not also bound as itself
             for (const [token, provider] of providers){
-                // Bound later, or for each call, so not caught below; supported until 5.0 refuses it
-                if (token === ThemeCache || token === ExecutionContext) {
-                    warnOnce(this.logger, `${target.name}: @MeoCord({ providers }) provides ${tokenName(token)}, which MeoCord binds itself; ` + 'the next major version (5.0) refuses it. Remove the provider.');
-                }
-                if (container.isBound(token)) {
-                    startupError(new Error(`${target.name}: @MeoCord({ providers }) cannot provide ${tokenName(token)}, which MeoCord binds itself.`));
+                const refusal = appProviderRefusal(`${target.name}`, token, (own)=>container.isBound(own), this.logger);
+                if (refusal) {
+                    startupError(refusal);
                     continue;
                 }
                 bindProvider(container, provider, (cls)=>bindDependencies(container, cls, providers));
@@ -367,26 +358,35 @@ import { isShardProcess } from '../util/shard-process.util.js';
             buildMessageRoutes(options.controllers, options.messages);
             // Every check has run, and touched only the container: from here the app is made, once none found an error
             stopOnStartupErrors();
+            for (const warning of perCallEventWarnings(runs, providers, options.presenter))this.logger.warn(warning);
             const discordClient = container.get(Client);
             Reflect.set(discordClient, SHARD_CALL_KEY, shardCallHandler(container, ()=>callable, 'this app'));
-            // Stamp every class the app runs with the container, so @UseGuard resolves guards on a direct call to any of them
-            for (const cls of runs.classes){
-                Reflect.defineMetadata(META.container, container, cls);
-            }
-            recordInstanceContainers(container, runs.classes);
+            // Every class the app runs, so @UseGuard resolves guards on a direct call to any of them
+            prepareDirectCalls(container, runs.classes);
             prepareThemes(container, appClasses);
             // Run by start() before it logs in: what may inject a provided value is resolved once every factory
             // has made its value, including those that return a promise
             const logger = this.logger;
+            let sources;
             const startup = async (control)=>{
+                let made;
                 try {
-                    await resolveProviders(container, providers, order, control);
+                    made = await resolveProviders(container, providers, order, control);
                 } catch (error) {
                     logger.error(`${error.message}. The bot cannot start without it.`);
                     logger.debug('Provider failure:', error.cause);
                     markExplained(error);
                     throw error;
                 }
+                // A stop came while the providers were being made: what follows resolves provided values, which would make the
+                // factories it left unmade
+                if (!made) return;
+                // Read once every provided value is made, and before anything the app makes could list its handlers
+                if (!sources) {
+                    sources = eventSources(container, providers, lifecycle, appClasses, (text)=>logger.warn(text));
+                    listEventSources(registry, sources);
+                    prepareLateThemes(container, sources.map(({ cls })=>cls));
+                }
                 // The listed services are made now, so constructors that attach listeners or connect run before login; a stop
                 // meanwhile makes no more of them
                 for (const svc of options.services ?? []){
@@ -401,11 +401,38 @@ import { isShardProcess } from '../util/shard-process.util.js';
                 registerClientTheme(discordClient, container);
                 registerClientTranslator(discordClient, options.i18n);
             };
-            return new MeoCordApp(options.controllers, container, discordClient, meocordConfig.discordToken, options.activities, appClasses, meocordConfig.shutdownTimeout, startup, lifecycle, options.messages, // In development only, unless the app says otherwise
-            options.warnUnanswered ?? process.env.NODE_ENV === 'development', shard);
+            return new MeoCordApp(options.controllers, container, discordClient, meocordConfig.discordToken, options.activities, ()=>sources ?? [], meocordConfig.shutdownTimeout, startup, lifecycle, options.messages, // In development only, unless the app says otherwise
+            options.warnUnanswered ?? process.env.NODE_ENV === 'development', shard, startAttempt(container, lifecycle, providers));
         });
     }
 }
 MeoCordFactory.logger = new Logger();
+/**
+ * What the app's starts make: each lifecycle unit is recorded as the container constructs it, as the testing module
+ * records them, and a container snapshot marks where a start begins, so a failed start drops every singleton it made,
+ * the values factory providers keep included.
+ */ function startAttempt(container, lifecycle, providers) {
+    const constructed = new Set();
+    for (const { token } of lifecycle){
+        container.onActivation(token, (_context, instance)=>{
+            constructed.add(token);
+            return instance;
+        });
+    }
+    const drop = ()=>{
+        container.restore();
+        forgetFactoryValues(container);
+    };
+    const given = new Set(lifecycle.map(({ token })=>token).filter((token)=>{
+        const provider = providers.get(token);
+        return provider !== undefined && isValueProvider(provider);
+    }));
+    return {
+        constructed,
+        given,
+        begin: ()=>container.snapshot(),
+        drop
+    };
+}
 
 export { MeoCordFactory };