API
Every public symbol of MeoCord 4.2, by kind. Each page names the entry point to import it from.
At a glance
DecoratorsEvery decorator, how it is called and what it does, by what it applies to.
respond()What
respond(interaction)gives a handler: each method and property of the response state.Testing helpersEvery helper
meocord/testingexports, how it is called and what it does.CLIEvery command of the CLI, what it does, and an example to copy.
Controllers
AutocompleteHandlerEntryA registered
@Autocompletehandler, as the registry lists it.CommandHandlerEntryA registered slash command, subcommand, context menu command or entry point command, as the registry lists it.
ComponentHandlerEntryA registered button or select menu handler, as the registry lists it.
EventHandlerEntryA registered
@Onor@Oncehandler, as the registry lists it.HandlerEntryOne registered handler, as
HandlerRegistry.listgives it, narrowed by itskind.HandlerFilterWhat
HandlerRegistry.listlists: handlers of one kind, of one controller, or both.HandlerKindThe kind of handler a
HandlerEntrydescribes, such as'command'or'message'.HandlerRegistryLists every handler the app registered, with the metadata declared on it.
MeoCordApplicationThe application
MeoCordFactory.createreturns: a bot in one process, or the manager of a process per shard.MeoCordFactoryCreates the application from the class
@MeoCorddecorates, ready to start.MessageHandlerEntryA registered
@MessageHandler, a message command or a listener for every message, as the registry lists it.ModalHandlerEntryA registered modal submit handler, as the registry lists it.
ReactionHandlerEntryA registered
@ReactionHandler, as the registry lists it.ShardContextTells a service which shards its process runs, and calls a service method in every shard.
Decorators
App
MeoCordDeclares the application class: its controllers, services, client options and what applies to every handler.
ServiceMarks a class as a service, which controllers and other services inject by its type.
Controllers
ControllerMarks a class as a controller, whose methods handle commands, components, messages, reactions or events.
UseThemeSets part of the theme for a controller's handlers, or for one handler.
Handlers
AutocompleteSuggests values for an option of a chat input command as the user types.
CommandRoutes a command, a component or a modal submission to the method it decorates.
CommandBuilderMarks a class as a command's builder, which describes the command MeoCord registers with Discord.
MessageHandlerRuns the method it decorates for every message a user sends, whatever it says.
OnHandles a discord.js client event every time it is emitted, on a controller or a service.
OnceHandles a discord.js client event the first time it is emitted only, on a controller or a service.
ReactionHandlerRuns the method it decorates when a reaction with an emoji is added to or removed from a message.
Params
InjectInjects what a token provides into a constructor parameter.
Pipeline stages
CatchMarks a class as an exception filter for the given error types.
CooldownLimits how often a handler runs, counted per user, server, channel or for everyone.
DeferAcknowledges an interaction for its handler, then locks a component's message while the handler runs.
GuardMarks a class as a guard, which decides whether a handler runs.
InterceptorMarks a class as an interceptor, which wraps a handler to act before and after it.
ObserverMarks a class as a dispatch observer, told about every call once it has settled, for metrics and audit logs.
PipeMarks a class as a pipe, which turns one input value into what the handler works with.
UseFilterApplies exception filters to a handler, or to every handler of a controller.
UseGuardRuns guards before a handler, or before every handler of a controller.
UseInterceptorRuns interceptors around a handler, or around every handler of a controller.
UsePipeRuns pipes on one value of a handler's input, to turn it into what the handler works with.
ValidateValidates a handler's input with a Standard Schema before it runs.
Responses
bindThemeMakes a function run in the theme of the call that binds it, wherever it is called from later.
respondThe response state of an interaction, through which its replies, edits, follow-ups and errors go.
ResponseCallOne answer call an interaction got, as
getResponsefrommeocord/testingreports it: made throughrespond(), or with discord.js directly on a mock interaction.ResponseEditFlagsThe flags an edit through
respond()can ask for.ResponseEditPayloadAn edit made with
edit(): text, or edit options with the flags an edit can take.ResponseErrorOptionsOptions for
ResponseState.error.ResponseFlagsThe flags a message sent through
respond()can ask for.ResponseLockOptionsOptions for
ResponseState.lock.ResponsePayloadA message sent with
send()orfollowUp(): text, or reply options with the flags it can take.ResponsePhaseWhere an interaction's answer stands.
ResponseSendOptionsOptions for one message sent with
send(),edit()orfollowUp().ResponseStateHow one interaction is answered: the single place its replies, edits and follow-ups go through.
ThemeDeprecatedFive of the theme's colours as static properties: primary, success, info, danger and warning.
useThemeThe theme of the running call, with every role present.
Errors
CommandNotFoundErrorThe error raised for an interaction no handler matches, such as a button whose customId fits no pattern.
CooldownErrorThrown when a
@Cooldownblocks a call, so the handler does not run.CooldownStoreErrorThrown when the cooldown store fails and
@MeoCord({ cooldownStoreFailure })is'deny', its default.GuardDeniedErrorThrown by a guard to deny a call and tell the user why.
MessageUsageErrorThe error raised when a message names a command but does not fit its pattern, which the user is told.
UserErrorA mistake the user can fix, such as too few coins, rather than a fault in the bot.
ValidationErrorThrown when a handler's input fails its
@Validateschema, so the handler does not run.
Presenters
MessageResponseContextWhat a presenter knows about the message command it renders an error reply for, in
ResponsePresenter.messageError.PresentedErrorAn error a presenter styles: the words a filter chose, and the error itself.
ResponseContextWhat a presenter knows about the interaction it renders for.
ResponseFileA file a
ResponseViewcarries: a discord.jsAttachmentBuilder, or the file's name and its bytes.ResponsePresenterStyles MeoCord's own answers: the loading view
@Defershows, the error viewrespond().error()shows, and, withmessageError, the error replies and direct messages the built-in fallback sends a message command's author.ResponseViewWhat a presenter renders for a loading view or an error.
Utilities
applyDecoratorsComposes several class or method decorators into one.
cooldownMessageThe wait before a cooldown allows another call, in plain English, such as "Slow down: try again in 12s.": the message of a
CooldownError, for logs and tests.cooldownStoreMessageThe answer the built-in fallback gives a call
CooldownStoreErrorrefused, in English.createMetadataCreates a typed decorator for facts about a handler that guards and other stages read.
createTokenCreates a token to provide and inject a value by, typed with what it provides.
ExecutionContextDescribes one handler call: which controller and method run, with which arguments, and the metadata on them.
factoryProviderMakes a factory provider whose function is typed from its
injectlist and its token.getInstallContextReports where an interaction happened and whether the bot is present there.
isExplainedErrorWhether MeoCord has already logged what went wrong and what to do about it.
LoggerPrints timestamped lines to the console, each named with the app and a context, at a level the config can hide.
routeMakes a typed route from a customId pattern, so one declaration serves the handler and the ids that reach it.
SetMetadataDeprecatedAttaches a value to a controller or a handler under a string key of your choosing.
ThemeCacheAn app's cache of the themes
@MeoCord({ themeFor })looked up, by server and by user.
Cooldown stores
CooldownStoreWhere
@Cooldowncounts calls.MemoryCooldownStoreCounts cooldown calls in this process's memory: the store
@Cooldownuses unless another is bound.RedisCooldownStoreA
CooldownStoreon Redis, or on any server that speaks its protocol and runs its Lua scripts.ShardedCooldownStoreA
CooldownStorefor process sharding that needs no database.
Localisation
createTranslatorCreates the application's translator from one catalog per locale.
defineCatalogDeclares a message catalog, keeping each message's text as its type so the params it takes can be checked.
translateErrorThe text MeoCord's fallback answers an error with, in a user's or a server's language.
TranslatorTranslates messages from one catalog per locale, typed by the default one.
Testing
Inspection
ComponentCommandTypeThe command types routed by a
customIdpattern: buttons, select menus and modals.CooldownStoreSuiteFrameworkThe test framework
testCooldownStoreregisters its cases with: itsdescribe,itandexpect.createExecutionContextBuilds the
ExecutionContexta guard, interceptor or filter receives for one handler, to test it on its own.ExecutionContextOptionsWhat
createExecutionContextdescribes besides the handler.expectCompleteCatalogChecks that every locale translates every message, and throws listing each gap, locale by locale.
findRouteConflictsFinds component patterns that rank equally and can match the same
customId, which MeoCord otherwise only warns about at startup.getResponseReports how an interaction was answered: where its answer stands, and every answer call it got, in order.
HandlerInspectionWhat runs for one handler, and the metadata declared on it, as
inspectHandlerreports it.InspectedCooldownOne
@Cooldownon a handler, with its defaults filled in, asinspectHandlerreports it.InspectedFilterA filter as
@UseFilterdeclares it: the class, or the class with its params.InspectedGuardA guard as
@UseGuarddeclares it: the class, or the class with its params.InspectedInterceptorAn interceptor as
@UseInterceptordeclares it: the class, or the class with its params.inspectHandlerReports what runs when a handler is dispatched, and the metadata declared on it, without running anything.
InspectHandlerOptionsWhat
inspectHandlerincludes besides the handler's own stages.MessageToResolveA message, as
resolveRoutetakes it.ResolvedRouteThe handler a component interaction or a message reaches, as
resolveRoutereports it.resolveRouteResolves which handler a component's
customIdor a message's content reaches, as dispatch routes it.ResponseReportHow an interaction was answered, as
getResponsereports it.RouteConflictTwo patterns of one component type that rank equally and can both match a
customId, asfindRouteConflictsreports them.testCooldownStoreChecks that a
CooldownStorecounts calls asMemoryCooldownStoredoes, as a suite of test cases.
Mocks
ChatInputOptionsThe options of a mock slash command, as
createChatInputOptionstakes them: each value by its option's name.clearAllMocksClears the calls every mock from
meocord/testinghas recorded, keeping what each was told to do.createChatInputOptionsBuilds a slash command's options from a plain record, found by name as the real options resolver finds them.
createDiscordErrorCreates the error discord.js throws for a failed Discord API call, for a mock to reject with.
createMockCreates a mock of any type, with no class needed, for service doubles and interfaces.
createMockChannelCreates a mock channel of the given class, such as
TextChannel,ThreadChannelorDMChannel.createMockClientCreates a mock
Client, withusers,channels,guildsandapplication.commandsready to stub.createMockFnCreates a mock function that jest's and Vitest's
expectboth read.createMockGuildCreates a mock
Guild, with themembers,channels,rolesandbansmanagers ready to stub.createMockInteractionCreates a mock instance of a discord.js class, such as an interaction, keeping its prototype so
instanceofholds.createMockMemberCreates a mock
GuildMember: a user in a server, with the roles given.createMockMessageCreates a mock
Messagethat tracks whether it has been deleted.createMockRawMemberCreates the member Discord sends with an interaction from a server the bot isn't in, as discord.js keeps it.
createMockThemeMakes a whole theme for a test: MeoCord's defaults with
overridesmerged over them, frozen.createMockUserCreates a mock
User: a person, not a bot, with an id of its own.createModalFieldsBuilds the
fieldsof a submitted form, as discord.js does when a user submits one.DeepMockedA mock of
T: every method a mock function, and every nested object mocked in turn, five levels deep, including a discord.js structure that may be absent, such as a message'smember, when it is present.isMockFunctionTells whether a value is a mock function: one from
meocord/testing,jest.fn()orvi.fn().MockA mock function, as jest's
Mockand Vitest'sMockname it: the same type asMockedFunction.MockedFunctionA mock function with the signature of
T, and the mock API ofMockInstance.MockFnFactoryA test runner's mock function factory, such as
vi.fn.MockGuildOverridesWhat
createMockGuildputs in the guild's caches, as the gateway would have filled them.MockInstanceThe mock API of a mock function: what it has recorded, and the methods that change what it does.
MockMemberOverridesWhat
createMockMemberbuilds a member with.MockMessageOverridesWhat
createMockMessagebuilds a message with.MockPropsProperty values a mock factory sets as it builds the mock.
MockRawMemberOverridesWhat
createMockRawMemberbuilds a member with: any field Discord sends, withpermissionsas a permission set anduseras the fields of the user given.MockResultOne call's outcome, as a mock function records it: the value it returned, or the error it threw.
MockStateWhat a mock function has recorded: each call's arguments, outcome and
this, in order.resetAllMocksClears every mock from
meocord/testing, and puts each back to the implementation it was created with.RunnerMockA mock function a test runner makes, as
useMockFntakes it.useMockFnMakes every mock
meocord/testingcreates with the test runner's own mock function, such as Vitest'svi.fn.useStrictMocksHas every mock from
meocord/testingcompute the values discord.js computes, where it reads a placeholder otherwise.withThemeRuns
fnwiththemeas the theme of the call, as a handler's call runs.
Module
DispatchedCallWhat
TestingModule.dispatchdid with an interaction, a message or a reaction.DispatchedHandlerOne handler
TestingModule.dispatchran, and how its call ended.EmitResultHow an event sent with
TestingModule.emitwas handled.FromAppOptionsWhat a test changes of the app
MeoCordTestingModule.fromAppbuilds.HandlerNameThe names of a class's instance methods, as
TestingModule.invoketakes them.InvocationResultHow a call made with
TestingModule.invokeended.MeoCordTestingModuleBuilds testing modules: the classes a test needs, in a container of their own, with no Discord connection.
reportAllStartupErrorsHas decorators keep the startup errors they find, as a bot built with
startupErrors: 'all'does, so a testing module reports every one at once.TestingModuleA compiled testing module, which runs handlers as the bot does and resolves the classes it built.
TestingModuleBuilderBuilds a testing module, with stand-ins for the providers, stages and theme a test replaces.
TestingModuleInitOptionsHow
TestingModule.initprepares the module.TestingModuleOptionsWhat a testing module is built from: the classes a test needs, and the app whose global stages apply.
Configuration
App options
ClassProviderA provider that binds a class's instance under a token, made once and shared, with its own dependencies injected.
CooldownStoreFailureWhat a call gets when the cooldown store throws, rejects or does not answer in time.
FactoryProviderA provider that binds what a function returns, called once with the values of
inject, in order.MeoCordOptionsWhat
@MeoCordtakes: the app's controllers, services and client options, and what applies to every handler.MessageCommandOptionsHow message commands start and match across the app, set in
@MeoCord({ messages }).MessageHandlerOptionsWhat one message command sets for itself, over the app's
messagesoptions.MessageHelpOptionsThe words the built-in help command answers to, as
@MeoCord({ messages: { help } })takes them.MessageParamTypeA param type an app adds for its message patterns, such as
{accent:color}: it reads a word as a value.MessagePrefixOne prefix or several that start a message command, such as
'!'or['!', '?'];''stands for none.ProviderA value
@MeoCord({ providers })or a testing module binds under a token, for classes to@Inject.RootThemeThe app's theme, as
@MeoCord({ theme })takes it.ThemeOverridePart of a theme, as a scope sets it: any role, of MeoCord's or the app's, and nothing unknown.
ThemeResolverA class, decorated with
@Service(), that looks themes up with the app's services, as@MeoCord({ themeFor })takes it in place ofThemeResolvers.ThemeResolversThemes that depend on where a call comes from, as
@MeoCord({ themeFor })takes them, or a class implementingThemeResolver.ValueProviderA provider that binds an existing value, such as a settings object or a configured client, as it is.
Config file
CommandRegistrationConfigWhere and whether MeoCord registers the application's commands with Discord, set as
meocord.config.ts'scommands.MeoCordConfigThe configuration
meocord.config.tsexports: the bot's token, how it is built, and how it registers and shards.RsbuildConfigRsbuild's configuration, as
meocord.config.ts'srsbuildhook receives and returns it.ShardingConfigHow the bot splits its gateway connection into shards, set as
meocord.config.ts'ssharding.
ESLint
defaultThe ESLint configuration a new MeoCord app's
eslint.config.tsexports, extended by the app's own rules.typescriptConfigLints TypeScript as a new MeoCord app does: type-aware rules, Prettier, and import cycles that break injection.
CLI
showDisplay information
createCreate a new MeoCord application
buildBuild the application
startStart the application
registerRegister the application commands with Discord, without starting the bot
generateGenerate components
Types
BuildableCommandTypeThe command types registered with Discord, which take a builder: slash, context menu and entry point commands.
CallHandlerRuns the rest of a call from inside an interceptor: the next interceptor, then the handler.
CatalogDefinitionWhat
defineCatalogtakes: a catalog, checked as it is written.CatalogShapeA message catalog: messages, plurals, and nested groups of them, keyed by name.
CheckedParamsThe params a message handler declares,
Declared, as@MessageHandlerchecks them against its patternP.CommandBuilderBaseWhat a command builder implements:
build, which describes the command to register.CommandBuilderConstructorA command builder class, as
@Commandtakes it.CommandBuilderOptionsWhere a command
@CommandBuilderdescribes is registered, in place of the configured scope.CommandBuildResultWhat a builder's
build()returns for its command type.CommandInteractionTypeThe interaction a
@Commandhandler receives, from its builder or itsCommandType.CommandTypeThe kind of interaction a
@Commandhandles, such as a slash command or a button.ControllerOptionsHow
@Controllertreats a class: whether the handlers it declares take the stages of the classes it extends.CooldownBatchVerdictWhether a call may run against every cooldown it counts against, and if not, which refused it.
CooldownEntryOne cooldown a call counts against: the key it counts under, and its limit.
CooldownLimitHow many calls a cooldown allows, and in how long a window.
CooldownOptionsWhat
@Cooldowntakes: the limit, whose calls count together, and how to exempt or tell calls apart.CooldownScopeThe scope a cooldown counts calls in.
CooldownVerdictWhether a call may run, and if not, how long until one may.
DeepPartialTwith every property optional, at every depth; arrays and tuples stay whole.DeepReadonlyTwith every property readonly, at every depth; an array becomes a readonly one of readonly elements.DeferOptionsHow
@Deferacknowledges an interaction and locks a component's message.DispatchObserverObserves every call MeoCord dispatches, as it starts and once it has settled, for metrics and audit logs.
DispatchOutcomeHow a dispatched call ended, as a
DispatchObserveris told.DispatchResultWhat a
DispatchObserveris told about a call once it has settled.EntityRefA member, user, role or channel a message command names, as its guards see it: not fetched yet.
ExceptionFilterWhat an exception filter implements:
catch, which answers an error its@Catchnames.ExecutionContextTypeWhat an
ExecutionContextis running a handler for: an interaction, an autocomplete, a message, a reaction or a gateway event.GuardInterfaceWhat a guard implements:
canActivate, which decides whether the handler runs.GuardOptionsWhat
@Guardtakes: the context types the guard runs for.GuildThemeTargetWhat a per-server theme resolver is given: the server a call came from.
InferSchemaOutputThe value a schema produces when validation succeeds: what a handler with
@Validate(schema)receives.InjectedThe values a factory receives for its
injectlist, in order, each what its token provides.InstallContextWhere an interaction happened, as
getInstallContextreports it.InterceptorInterfaceWhat an interceptor implements:
intercept, which runs around the handler.InterceptorOptionsWhat
@Interceptortakes: the context types the interceptor runs for.JsonifiedA value as it arrives after a trip through JSON: what
toJSONreturns, so aDateas a string; aMapor aSetas an empty object; a function, a symbol orundefinedleft out of an object,nullin a list, andundefinedon its own.LocaleCatalogWhat a locale other than the default provides: any part of the default catalog, in its own wording.
LocalizationKeyThe keys
Translator.localizationstakes: a single string with no{params}, since Discord shows a command's name or description as written, with no plural forms.MeoCordMessagesMeoCord's own texts for users, in English, by key under
meocord: usage replies, the built-in help, cooldown refusals, the fallback's answers and the default presenter's views.MeoCordThemeA theme: design tokens by role, in three groups.
MessageHelpWhat the built-in help command found, for a presenter's
messageHelpto write.MessageHelpEntryOne message command as the built-in help shows it: how to type it, what it does, and where it works.
MessageHelpParamOne param or flag of a
MessageHelpEntry, with what it takes in words.MessageKeyEvery message key of a catalog: the dotted path to each message or plural.
MessageParamsThe params a catalog message takes: one per
{name}placeholder, whose name is ASCII letters, digits or_, andcountfor a plural message.MessageParamTypesWhat each param type in a message pattern gives the handler, by the name a pattern uses for it.
MessageScopeWhere a message command works:
'guild'in servers only,'dm'in direct messages only, or'any'.MessageUsageIssueOne thing wrong with a message command's input: a word that is not a value of its param's type, or a param missing.
MetadataDecoratorA typed metadata decorator, made by
createMetadata.ObserverOptionsWhat
@Observertakes: the context types the observer is told about.OnReadyA controller, service or provided value that does work once the bot is online, such as starting timers.
OnShutdownA controller, service or provided value that cleans up before the bot stops, such as closing a connection.
ParamRefsOfThe params of a message pattern as its guards see them: each member, user, role and channel as an
EntityRef.ParamsOfThe params a message pattern gives its handler, read from the pattern itself.
PipedMarks a value of a handler's input that a separate
@UsePipeproduces, so the checks of what a call gives leave its type to that pipe.PipeInterfaceWhat a pipe implements:
transform, which turns one input value into what the handler receives.PluralCategoryThe plural categories
Intl.PluralRulesselects between.PluralMessageA message with a form per plural category, chosen by the
countparam throughIntl.PluralRules.PrimaryEntryPointCommandDataThe body an entry point command is registered with.
ProvidedWhat a token provides: a class's instance, or a
createTokentoken's type;unknownfor a string or a plain symbol.ProviderTokenWhat a provider is bound under and injected by: a class, a string, a symbol, or a typed
Token.ReactionEventThe second argument a
@ReactionHandlermethod receives: who reacted, and whether they added or removed it.ReactionHandlerActionWhether a
@ReactionHandlercall is for a reaction added to a message or removed from it.ReactionHandlerOptionsDeprecatedThe second argument a
@ReactionHandlermethod receives: another name forReactionEvent.ReactionHandlerSettingsThe settings a
@ReactionHandlertakes for itself.ReadyInfoWhat
onReadylearns about its process, beside the client: whether it should do one-off work.RedisCooldownStoreOptionsHow a
RedisCooldownStorenames its keys and runs its script.RedisEvalRuns a Lua script on the server, as a client's
EVALdoes.RedisEvalShaRuns a script the server already holds, by its SHA1, as a client's
EVALSHAdoes.ReservedThemeRoleNames MeoCord keeps for roles it may add to any group.
RouteA component's customId pattern with a typed
build, asroutemakes it.RouteParamsThe names of a customId pattern's params, as a union, such as
'id' | 'page'for'list/{id}/{page:int}'.RouteValueA value
buildtakes for an untyped customId param: its text, or a number or snowflake written as its digits.RouteValuesThe values a route's
buildtakes, one for each of its params and no others.ShardCallResultOne process's answer to a
ShardContext.call: the shards it runs, and the method's value or its error.StageParamsThe params a guard, interceptor, filter or pipe declares, as
{ provide, params }must give them.StandardSchemaV1The Standard Schema interface, version 1, which zod, valibot, arktype and other validation libraries implement.
StandardSchemaV1IssueOne problem a schema found.
StandardSchemaV1PropsWhat a Standard Schema exposes under
~standard.StandardSchemaV1ResultThe outcome of validation: the output value, or the issues found.
StringMessageKeyThe keys whose message is a single string rather than plural forms, with or without
{params}.ThemeButtonsThe button style each role maps to, for the app's own buttons.
ThemeButtonStyleA button style a theme role maps to: one of Discord's four coloured styles.
ThemeColorsThe colours a theme names by role.
ThemeEmojisThe emojis a theme names by role.
TokenA symbol that names a value to provide and inject, typed with what it provides, as
createTokenmakes it.TranslateTranslates a key into one locale's message.
TranslatorOptionsWhat
createTranslatortakes: the default locale, and a catalog per locale.UserErrorOptionsWhat a
UserErrorcarries besides its message.UserThemeTargetWhat a per-user theme resolver is given: the user a call came from.
ValidateOptionsWhat
@Validatetakes beside its schema: pipes for single values of the schema's output.ValidatePipesThe pipes
@Validatetakes for a schema: some of the schema's output keys, each with one pipe or several applied in order.ValidationIssueOne problem
@Validatefound in a handler's input.