Guards and middleware

A guard decides whether a handler runs. Middleware runs around it. Both can be set on the whole bot, on a folder, and on a single command, component, modal or menu.

Built-in guards

import { command, cooldown, guildOnly, hasPermission } from "nubis";
import { PermissionFlagsBits } from "discord-api-types/v10";

export default command({
	description: "Post an announcement",
	guards: [
		guildOnly,
		hasPermission(PermissionFlagsBits.ManageMessages),
		cooldown({ seconds: 60 }),
	],
	run: ({ reply }) => reply("Posted."),
});

Put cooldown last: a check that fails earlier shouldn't use up the user's turn. Cooldowns are kept in memory, per process.

Writing a guard

A guard gets the user, member, server and channel, and api. It returns nothing to pass, or deny(message) to stop; the user sees the message, privately.

import { guard } from "nubis";

export const betaTesters = guard(async ({ user, deny }) => {
	if (!(await db.isBetaTester(user.id))) {
		return deny("This is only open to beta testers for now.");
	}
});

Middleware

Middleware wraps a handler. Code before await next() runs first; code after runs once the handler has finished, and a handler's error comes out of next().

import { middleware } from "nubis";

export const timing = middleware(async ({ kind, name }, next) => {
	const started = performance.now();
	try {
		await next();
	} finally {
		console.log(`${kind} ${name}: ${Math.round(performance.now() - started)}ms`);
	}
});

The context has kind (command, component or modal), name (/config set, or the component's id), and the user, member, server, channel and api.

Order

From the outside in:

1. The bot's, from nubis.config.ts
2. Each folder's, outermost folder first
3. The command's, component's or menu's own

Guards run in that order and stop at the first denial. Middleware nests in that order, so the bot's middleware is outermost.