Skip to content

Wrapping handlers

Without any extra code, Shardlens measures how long each interaction took to get its first response (reply, defer, update, modal or autocomplete result), and whether Discord’s 3-second deadline was missed. That covers what users feel.

Wrapping your handler adds two things:

  • Handler duration: how long your code ran, including work after the first response.
  • Failures: when the handler throws, the error class and Discord error code are recorded against the command. The error message is never sent, because it can contain user input or tokens.
bot.ts
import type { Shardlens } from '@shardlens/discordjs';
import { type Client, Events, MessageFlags } from 'discord.js';
declare const client: Client;
declare const lens: Shardlens;
client.on(
Events.InteractionCreate,
lens.wrap(async (interaction) => {
if (!interaction.isChatInputCommand()) return;
if (interaction.commandName === 'ping') {
await interaction.reply({ content: 'Pong!', flags: MessageFlags.Ephemeral });
}
// An error thrown here is recorded (class and Discord code, never the message) and then re-thrown unchanged.
}),
);
// Errors caught inside the SDK itself are counted, never thrown. Listen if you want to log them.
lens.on('error', (name) => console.warn(`[shardlens] internal error: ${name}`));
  • Errors are re-thrown unchanged after they are recorded, so your own error handling and logging still run.
  • The wrapper is async: it returns a promise that settles when your handler does.
  • If the SDK itself fails while recording, the failure is counted in SDK health and your handler is unaffected.

wrap only sees an error that leaves the function it wraps. Many bots catch command errors themselves, to reply “something went wrong”:

client.on(Events.InteractionCreate, async (interaction) => {
try {
await runCommand(interaction);
} catch (error) {
await replyWithError(interaction, error);
}
});

Wrapping that whole listener would record every command as successful, because nothing is thrown out of it. Wrap the function inside the try instead, and leave your catch as it is:

const runCommand = lens.wrap(async (interaction: ChatInputCommandInteraction) => {
await commands.get(interaction.commandName)?.execute(interaction);
});

The error passes through wrap, which records it and throws it on to your catch.

Call the wrapped function exactly as the original was called. If a listener calls your handler without await (client.on('interactionCreate', (i) => { handle(i); })), keep it that way and wrap handle, not the listener: turning a listener async changes where a failure goes, because discord.js passes a rejected listener’s error to the client’s error event.

Wrap the function that receives the interaction, wherever your framework calls it:

client.on(Events.InteractionCreate, lens.wrap((interaction) => router.handle(interaction)));

wrap records interactions only. If a wrapped function also receives prefix commands, it runs them untouched and records nothing for them. Record those with wrapMessageCommand or trackMessageCommand.