Skip to content
GitHub

API

Every public symbol of MeoCord 4.2, by kind. Each page names the entry point to import it from.

At a glance

  • Decorators

    Every 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 helpers

    Every helper meocord/testing exports, how it is called and what it does.

  • CLI

    Every command of the CLI, what it does, and an example to copy.

Controllers

Decorators

App

  • MeoCord

    Declares the application class: its controllers, services, client options and what applies to every handler.

  • Service

    Marks a class as a service, which controllers and other services inject by its type.

Controllers

  • Controller

    Marks a class as a controller, whose methods handle commands, components, messages, reactions or events.

  • UseTheme

    Sets part of the theme for a controller's handlers, or for one handler.

Handlers

  • Autocomplete

    Suggests values for an option of a chat input command as the user types.

  • Command

    Routes a command, a component or a modal submission to the method it decorates.

  • CommandBuilder

    Marks a class as a command's builder, which describes the command MeoCord registers with Discord.

  • MessageHandler

    Runs the method it decorates for every message a user sends, whatever it says.

  • On

    Handles a discord.js client event every time it is emitted, on a controller or a service.

  • Once

    Handles a discord.js client event the first time it is emitted only, on a controller or a service.

  • ReactionHandler

    Runs the method it decorates when a reaction with an emoji is added to or removed from a message.

Params

  • Inject

    Injects what a token provides into a constructor parameter.

Pipeline stages

  • Catch

    Marks a class as an exception filter for the given error types.

  • Cooldown

    Limits how often a handler runs, counted per user, server, channel or for everyone.

  • Defer

    Acknowledges an interaction for its handler, then locks a component's message while the handler runs.

  • Guard

    Marks a class as a guard, which decides whether a handler runs.

  • Interceptor

    Marks a class as an interceptor, which wraps a handler to act before and after it.

  • Observer

    Marks a class as a dispatch observer, told about every call once it has settled, for metrics and audit logs.

  • Pipe

    Marks a class as a pipe, which turns one input value into what the handler works with.

  • UseFilter

    Applies exception filters to a handler, or to every handler of a controller.

  • UseGuard

    Runs guards before a handler, or before every handler of a controller.

  • UseInterceptor

    Runs interceptors around a handler, or around every handler of a controller.

  • UsePipe

    Runs pipes on one value of a handler's input, to turn it into what the handler works with.

  • Validate

    Validates a handler's input with a Standard Schema before it runs.

Responses

  • bindTheme

    Makes a function run in the theme of the call that binds it, wherever it is called from later.

  • respond

    The response state of an interaction, through which its replies, edits, follow-ups and errors go.

  • ResponseCall

    One answer call an interaction got, as getResponse from meocord/testing reports it: made through respond(), or with discord.js directly on a mock interaction.

  • ResponseEditFlags

    The flags an edit through respond() can ask for.

  • ResponseEditPayload

    An edit made with edit(): text, or edit options with the flags an edit can take.

  • ResponseErrorOptions

    Options for ResponseState.error.

  • ResponseFlags

    The flags a message sent through respond() can ask for.

  • ResponseLockOptions

    Options for ResponseState.lock.

  • ResponsePayload

    A message sent with send() or followUp(): text, or reply options with the flags it can take.

  • ResponsePhase

    Where an interaction's answer stands.

  • ResponseSendOptions

    Options for one message sent with send(), edit() or followUp().

  • ResponseState

    How one interaction is answered: the single place its replies, edits and follow-ups go through.

  • Theme Deprecated

    Five of the theme's colours as static properties: primary, success, info, danger and warning.

  • useTheme

    The theme of the running call, with every role present.

Errors

  • CommandNotFoundError

    The error raised for an interaction no handler matches, such as a button whose customId fits no pattern.

  • CooldownError

    Thrown when a @Cooldown blocks a call, so the handler does not run.

  • CooldownStoreError

    Thrown when the cooldown store fails and @MeoCord({ cooldownStoreFailure }) is 'deny', its default.

  • GuardDeniedError

    Thrown by a guard to deny a call and tell the user why.

  • MessageUsageError

    The error raised when a message names a command but does not fit its pattern, which the user is told.

  • UserError

    A mistake the user can fix, such as too few coins, rather than a fault in the bot.

  • ValidationError

    Thrown when a handler's input fails its @Validate schema, so the handler does not run.

Presenters

  • MessageResponseContext

    What a presenter knows about the message command it renders an error reply for, in ResponsePresenter.messageError.

  • PresentedError

    An error a presenter styles: the words a filter chose, and the error itself.

  • ResponseContext

    What a presenter knows about the interaction it renders for.

  • ResponseFile

    A file a ResponseView carries: a discord.js AttachmentBuilder, or the file's name and its bytes.

  • ResponsePresenter

    Styles MeoCord's own answers: the loading view @Defer shows, the error view respond().error() shows, and, with messageError, the error replies and direct messages the built-in fallback sends a message command's author.

  • ResponseView

    What a presenter renders for a loading view or an error.

Utilities

  • applyDecorators

    Composes several class or method decorators into one.

  • cooldownMessage

    The 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.

  • cooldownStoreMessage

    The answer the built-in fallback gives a call CooldownStoreError refused, in English.

  • createMetadata

    Creates a typed decorator for facts about a handler that guards and other stages read.

  • createToken

    Creates a token to provide and inject a value by, typed with what it provides.

  • ExecutionContext

    Describes one handler call: which controller and method run, with which arguments, and the metadata on them.

  • factoryProvider

    Makes a factory provider whose function is typed from its inject list and its token.

  • getInstallContext

    Reports where an interaction happened and whether the bot is present there.

  • isExplainedError

    Whether MeoCord has already logged what went wrong and what to do about it.

  • Logger

    Prints timestamped lines to the console, each named with the app and a context, at a level the config can hide.

  • route

    Makes a typed route from a customId pattern, so one declaration serves the handler and the ids that reach it.

  • SetMetadata Deprecated

    Attaches a value to a controller or a handler under a string key of your choosing.

  • ThemeCache

    An app's cache of the themes @MeoCord({ themeFor }) looked up, by server and by user.

Cooldown stores

Localisation

  • createTranslator

    Creates the application's translator from one catalog per locale.

  • defineCatalog

    Declares a message catalog, keeping each message's text as its type so the params it takes can be checked.

  • translateError

    The text MeoCord's fallback answers an error with, in a user's or a server's language.

  • Translator

    Translates messages from one catalog per locale, typed by the default one.

Testing

Inspection

Mocks

  • ChatInputOptions

    The options of a mock slash command, as createChatInputOptions takes them: each value by its option's name.

  • clearAllMocks

    Clears the calls every mock from meocord/testing has recorded, keeping what each was told to do.

  • createChatInputOptions

    Builds a slash command's options from a plain record, found by name as the real options resolver finds them.

  • createDiscordError

    Creates the error discord.js throws for a failed Discord API call, for a mock to reject with.

  • createMock

    Creates a mock of any type, with no class needed, for service doubles and interfaces.

  • createMockChannel

    Creates a mock channel of the given class, such as TextChannel, ThreadChannel or DMChannel.

  • createMockClient

    Creates a mock Client, with users, channels, guilds and application.commands ready to stub.

  • createMockFn

    Creates a mock function that jest's and Vitest's expect both read.

  • createMockGuild

    Creates a mock Guild, with the members, channels, roles and bans managers ready to stub.

  • createMockInteraction

    Creates a mock instance of a discord.js class, such as an interaction, keeping its prototype so instanceof holds.

  • createMockMember

    Creates a mock GuildMember: a user in a server, with the roles given.

  • createMockMessage

    Creates a mock Message that tracks whether it has been deleted.

  • createMockRawMember

    Creates the member Discord sends with an interaction from a server the bot isn't in, as discord.js keeps it.

  • createMockTheme

    Makes a whole theme for a test: MeoCord's defaults with overrides merged over them, frozen.

  • createMockUser

    Creates a mock User: a person, not a bot, with an id of its own.

  • createModalFields

    Builds the fields of a submitted form, as discord.js does when a user submits one.

  • DeepMocked

    A 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's member, when it is present.

  • isMockFunction

    Tells whether a value is a mock function: one from meocord/testing, jest.fn() or vi.fn().

  • Mock

    A mock function, as jest's Mock and Vitest's Mock name it: the same type as MockedFunction.

  • MockedFunction

    A mock function with the signature of T, and the mock API of MockInstance.

  • MockFnFactory

    A test runner's mock function factory, such as vi.fn.

  • MockGuildOverrides

    What createMockGuild puts in the guild's caches, as the gateway would have filled them.

  • MockInstance

    The mock API of a mock function: what it has recorded, and the methods that change what it does.

  • MockMemberOverrides

    What createMockMember builds a member with.

  • MockMessageOverrides

    What createMockMessage builds a message with.

  • MockProps

    Property values a mock factory sets as it builds the mock.

  • MockRawMemberOverrides

    What createMockRawMember builds a member with: any field Discord sends, with permissions as a permission set and user as the fields of the user given.

  • MockResult

    One call's outcome, as a mock function records it: the value it returned, or the error it threw.

  • MockState

    What a mock function has recorded: each call's arguments, outcome and this, in order.

  • resetAllMocks

    Clears every mock from meocord/testing, and puts each back to the implementation it was created with.

  • RunnerMock

    A mock function a test runner makes, as useMockFn takes it.

  • useMockFn

    Makes every mock meocord/testing creates with the test runner's own mock function, such as Vitest's vi.fn.

  • useStrictMocks

    Has every mock from meocord/testing compute the values discord.js computes, where it reads a placeholder otherwise.

  • withTheme

    Runs fn with theme as the theme of the call, as a handler's call runs.

Module

Configuration

App options

  • ClassProvider

    A provider that binds a class's instance under a token, made once and shared, with its own dependencies injected.

  • CooldownStoreFailure

    What a call gets when the cooldown store throws, rejects or does not answer in time.

  • FactoryProvider

    A provider that binds what a function returns, called once with the values of inject, in order.

  • MeoCordOptions

    What @MeoCord takes: the app's controllers, services and client options, and what applies to every handler.

  • MessageCommandOptions

    How message commands start and match across the app, set in @MeoCord({ messages }).

  • MessageHandlerOptions

    What one message command sets for itself, over the app's messages options.

  • MessageHelpOptions

    The words the built-in help command answers to, as @MeoCord({ messages: { help } }) takes them.

  • MessageParamType

    A param type an app adds for its message patterns, such as {accent:color}: it reads a word as a value.

  • MessagePrefix

    One prefix or several that start a message command, such as '!' or ['!', '?']; '' stands for none.

  • Provider

    A value @MeoCord({ providers }) or a testing module binds under a token, for classes to @Inject.

  • RootTheme

    The app's theme, as @MeoCord({ theme }) takes it.

  • ThemeOverride

    Part of a theme, as a scope sets it: any role, of MeoCord's or the app's, and nothing unknown.

  • ThemeResolver

    A class, decorated with @Service(), that looks themes up with the app's services, as @MeoCord({ themeFor }) takes it in place of ThemeResolvers.

  • ThemeResolvers

    Themes that depend on where a call comes from, as @MeoCord({ themeFor }) takes them, or a class implementing ThemeResolver.

  • ValueProvider

    A provider that binds an existing value, such as a settings object or a configured client, as it is.

Config file

  • CommandRegistrationConfig

    Where and whether MeoCord registers the application's commands with Discord, set as meocord.config.ts's commands.

  • MeoCordConfig

    The configuration meocord.config.ts exports: the bot's token, how it is built, and how it registers and shards.

  • RsbuildConfig

    Rsbuild's configuration, as meocord.config.ts's rsbuild hook receives and returns it.

  • ShardingConfig

    How the bot splits its gateway connection into shards, set as meocord.config.ts's sharding.

ESLint

  • default

    The ESLint configuration a new MeoCord app's eslint.config.ts exports, extended by the app's own rules.

  • typescriptConfig

    Lints TypeScript as a new MeoCord app does: type-aware rules, Prettier, and import cycles that break injection.

CLI

  • show

    Display information

  • create

    Create a new MeoCord application

  • build

    Build the application

  • start

    Start the application

  • register

    Register the application commands with Discord, without starting the bot

  • generate

    Generate components

Types

  • BuildableCommandType

    The command types registered with Discord, which take a builder: slash, context menu and entry point commands.

  • CallHandler

    Runs the rest of a call from inside an interceptor: the next interceptor, then the handler.

  • CatalogDefinition

    What defineCatalog takes: a catalog, checked as it is written.

  • CatalogShape

    A message catalog: messages, plurals, and nested groups of them, keyed by name.

  • CheckedParams

    The params a message handler declares, Declared, as @MessageHandler checks them against its pattern P.

  • CommandBuilderBase

    What a command builder implements: build, which describes the command to register.

  • CommandBuilderConstructor

    A command builder class, as @Command takes it.

  • CommandBuilderOptions

    Where a command @CommandBuilder describes is registered, in place of the configured scope.

  • CommandBuildResult

    What a builder's build() returns for its command type.

  • CommandInteractionType

    The interaction a @Command handler receives, from its builder or its CommandType.

  • CommandType

    The kind of interaction a @Command handles, such as a slash command or a button.

  • ControllerOptions

    How @Controller treats a class: whether the handlers it declares take the stages of the classes it extends.

  • CooldownBatchVerdict

    Whether a call may run against every cooldown it counts against, and if not, which refused it.

  • CooldownEntry

    One cooldown a call counts against: the key it counts under, and its limit.

  • CooldownLimit

    How many calls a cooldown allows, and in how long a window.

  • CooldownOptions

    What @Cooldown takes: the limit, whose calls count together, and how to exempt or tell calls apart.

  • CooldownScope

    The scope a cooldown counts calls in.

  • CooldownVerdict

    Whether a call may run, and if not, how long until one may.

  • DeepPartial

    T with every property optional, at every depth; arrays and tuples stay whole.

  • DeepReadonly

    T with every property readonly, at every depth; an array becomes a readonly one of readonly elements.

  • DeferOptions

    How @Defer acknowledges an interaction and locks a component's message.

  • DispatchObserver

    Observes every call MeoCord dispatches, as it starts and once it has settled, for metrics and audit logs.

  • DispatchOutcome

    How a dispatched call ended, as a DispatchObserver is told.

  • DispatchResult

    What a DispatchObserver is told about a call once it has settled.

  • EntityRef

    A member, user, role or channel a message command names, as its guards see it: not fetched yet.

  • ExceptionFilter

    What an exception filter implements: catch, which answers an error its @Catch names.

  • ExecutionContextType

    What an ExecutionContext is running a handler for: an interaction, an autocomplete, a message, a reaction or a gateway event.

  • GuardInterface

    What a guard implements: canActivate, which decides whether the handler runs.

  • GuardOptions

    What @Guard takes: the context types the guard runs for.

  • GuildThemeTarget

    What a per-server theme resolver is given: the server a call came from.

  • InferSchemaOutput

    The value a schema produces when validation succeeds: what a handler with @Validate(schema) receives.

  • Injected

    The values a factory receives for its inject list, in order, each what its token provides.

  • InstallContext

    Where an interaction happened, as getInstallContext reports it.

  • InterceptorInterface

    What an interceptor implements: intercept, which runs around the handler.

  • InterceptorOptions

    What @Interceptor takes: the context types the interceptor runs for.

  • Jsonified

    A value as it arrives after a trip through JSON: what toJSON returns, so a Date as a string; a Map or a Set as an empty object; a function, a symbol or undefined left out of an object, null in a list, and undefined on its own.

  • LocaleCatalog

    What a locale other than the default provides: any part of the default catalog, in its own wording.

  • LocalizationKey

    The keys Translator.localizations takes: a single string with no {params}, since Discord shows a command's name or description as written, with no plural forms.

  • MeoCordMessages

    MeoCord'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.

  • MeoCordTheme

    A theme: design tokens by role, in three groups.

  • MessageHelp

    What the built-in help command found, for a presenter's messageHelp to write.

  • MessageHelpEntry

    One message command as the built-in help shows it: how to type it, what it does, and where it works.

  • MessageHelpParam

    One param or flag of a MessageHelpEntry, with what it takes in words.

  • MessageKey

    Every message key of a catalog: the dotted path to each message or plural.

  • MessageParams

    The params a catalog message takes: one per {name} placeholder, whose name is ASCII letters, digits or _, and count for a plural message.

  • MessageParamTypes

    What each param type in a message pattern gives the handler, by the name a pattern uses for it.

  • MessageScope

    Where a message command works: 'guild' in servers only, 'dm' in direct messages only, or 'any'.

  • MessageUsageIssue

    One thing wrong with a message command's input: a word that is not a value of its param's type, or a param missing.

  • MetadataDecorator

    A typed metadata decorator, made by createMetadata.

  • ObserverOptions

    What @Observer takes: the context types the observer is told about.

  • OnReady

    A controller, service or provided value that does work once the bot is online, such as starting timers.

  • OnShutdown

    A controller, service or provided value that cleans up before the bot stops, such as closing a connection.

  • ParamRefsOf

    The params of a message pattern as its guards see them: each member, user, role and channel as an EntityRef.

  • ParamsOf

    The params a message pattern gives its handler, read from the pattern itself.

  • Piped

    Marks a value of a handler's input that a separate @UsePipe produces, so the checks of what a call gives leave its type to that pipe.

  • PipeInterface

    What a pipe implements: transform, which turns one input value into what the handler receives.

  • PluralCategory

    The plural categories Intl.PluralRules selects between.

  • PluralMessage

    A message with a form per plural category, chosen by the count param through Intl.PluralRules.

  • PrimaryEntryPointCommandData

    The body an entry point command is registered with.

  • Provided

    What a token provides: a class's instance, or a createToken token's type; unknown for a string or a plain symbol.

  • ProviderToken

    What a provider is bound under and injected by: a class, a string, a symbol, or a typed Token.

  • ReactionEvent

    The second argument a @ReactionHandler method receives: who reacted, and whether they added or removed it.

  • ReactionHandlerAction

    Whether a @ReactionHandler call is for a reaction added to a message or removed from it.

  • ReactionHandlerOptions Deprecated

    The second argument a @ReactionHandler method receives: another name for ReactionEvent.

  • ReactionHandlerSettings

    The settings a @ReactionHandler takes for itself.

  • ReadyInfo

    What onReady learns about its process, beside the client: whether it should do one-off work.

  • RedisCooldownStoreOptions

    How a RedisCooldownStore names its keys and runs its script.

  • RedisEval

    Runs a Lua script on the server, as a client's EVAL does.

  • RedisEvalSha

    Runs a script the server already holds, by its SHA1, as a client's EVALSHA does.

  • ReservedThemeRole

    Names MeoCord keeps for roles it may add to any group.

  • Route

    A component's customId pattern with a typed build, as route makes it.

  • RouteParams

    The names of a customId pattern's params, as a union, such as 'id' | 'page' for 'list/{id}/{page:int}'.

  • RouteValue

    A value build takes for an untyped customId param: its text, or a number or snowflake written as its digits.

  • RouteValues

    The values a route's build takes, one for each of its params and no others.

  • ShardCallResult

    One process's answer to a ShardContext.call: the shards it runs, and the method's value or its error.

  • StageParams

    The params a guard, interceptor, filter or pipe declares, as { provide, params } must give them.

  • StandardSchemaV1

    The Standard Schema interface, version 1, which zod, valibot, arktype and other validation libraries implement.

  • StandardSchemaV1Issue

    One problem a schema found.

  • StandardSchemaV1Props

    What a Standard Schema exposes under ~standard.

  • StandardSchemaV1Result

    The outcome of validation: the output value, or the issues found.

  • StringMessageKey

    The keys whose message is a single string rather than plural forms, with or without {params}.

  • ThemeButtons

    The button style each role maps to, for the app's own buttons.

  • ThemeButtonStyle

    A button style a theme role maps to: one of Discord's four coloured styles.

  • ThemeColors

    The colours a theme names by role.

  • ThemeEmojis

    The emojis a theme names by role.

  • Token

    A symbol that names a value to provide and inject, typed with what it provides, as createToken makes it.

  • Translate

    Translates a key into one locale's message.

  • TranslatorOptions

    What createTranslator takes: the default locale, and a catalog per locale.

  • UserErrorOptions

    What a UserError carries besides its message.

  • UserThemeTarget

    What a per-user theme resolver is given: the user a call came from.

  • ValidateOptions

    What @Validate takes beside its schema: pipes for single values of the schema's output.

  • ValidatePipes

    The pipes @Validate takes for a schema: some of the schema's output keys, each with one pipe or several applied in order.

  • ValidationIssue

    One problem @Validate found in a handler's input.