Cooldowns

A command that calls a paid API or posts in a channel needs a limit, or one person can run it dozens of times a minute. By hand, that's a map of last-use times in every handler that needs one, plus a reply telling the caller when to try again.

Cooldown is that limit as a gate. It allows a set number of uses per window and refuses once they're used up, with a card that shows when the caller can try again.

import {
    Cooldown,
    Gated,
    SlashHandler,
    SlashRoute
} from '@seedcord/gateway';

@Gated(Cooldown('30m'))
@SlashRoute('feed')
export class Feed extends SlashHandler<'feed'> {
    public async execute(): Promise<void> {
        await this.reply('Fed.');
    }
}

Start with a duration alone, then add options as the command needs them. Each line below adds one option to the line above it.

// one use per caller every 30 seconds
Cooldown(30);

// three uses per caller every ten minutes
Cooldown('10m', { limit: 3 });

// three uses per server every ten minutes
Cooldown('10m', { limit: 3, per: 'guild' });

The sections below cover each option in detail.

You pass a duration literal as a string, or a number of seconds.

Cooldown('30m'); // thirty minutes
Cooldown(30); // thirty seconds

A duration literal is digits followed by one lowercase unit.

Cooldown('1.5h');

Everything else the parser rejects throws the same way.

• an uppercase unit, as in 30M
• a bare number in a string, as in '30'
• a zero duration, as in 0s

You set how many uses fit in one window with limit. It defaults to 1.

Cooldown('10m', { limit: 3 });

The window is a sliding window, so each use counts for ten minutes after it happens. If someone runs the command at 12:00, 12:02, and 12:05, all three pass. A fourth run at 12:06 is refused. At 12:10 the 12:00 use expires, so the next run after that passes.

If you leave per out, every caller gets their own window. Pass 'guild' or 'channel' to widen it.

Cooldown('10m', { per: '
user
guild
channel

Cooldown('1h', { per: 'guild' });

With per: 'guild', every caller outside a server shares one global window. If one person uses the command in a DM, they can use up the window for every other DM caller. Pair it with GuildOnly when your command should only run in a server anyway.

If two handlers use the same settings, they still get separate windows, since the key includes the route. If one handler has two Cooldown calls with different settings, their windows stay separate too.

message rewords the refusal. notice replaces it with a Notice you write. If you set both, seedcord uses notice. Both take a function, and seedcord calls it with resetAt. That's the time the caller can use the command again, as an EpochMs number of milliseconds since 1970.

import { Cooldown, toEpochSeconds } from '@seedcord/gateway';

Cooldown('10s', {
    per: 'channel',
    message: (resetAt) =>
        `Slow down. Try again <t:${toEpochSeconds(resetAt)}:R>.`
});

Discord's <t:...:R> markup takes seconds, and toEpochSeconds converts it. The default card already prints a relative time.

Cooldown('1m', { notice: (resetAt) => new SlowDown(resetAt) });

This handler sets every option that works together. Each server gets three feeds every ten minutes. When a server has used all three, the refusal says when the caller can try again.

import {
    Cooldown,
    Gated,
    SlashHandler,
    SlashRoute,
    toEpochSeconds
} from '@seedcord/gateway';

@Gated(
    Cooldown('10m', {
        limit: 3,
        per: 'guild',
        message: (resetAt) =>
            `Out of feeds. Try again <t:${toEpochSeconds(resetAt)}:R>.`
    })
)
@SlashRoute('feed')
export class Feed extends SlashHandler<'feed'> {
    public async execute(): Promise<void> {
        await this.reply('Fed.');
    }
}

It sets message and leaves notice out, since notice would replace the reworded refusal.

Cooldown is an effect gate. It reads the window during the check and records the use only after every gate on the handler has passed. If a later gate refuses, the commit never runs, so the caller keeps their use.

core.rateLimiter holds the cooldown windows and counts them in memory by default. A restart clears every cooldown, and on a serverless deploy each running copy keeps its own counts. A durable store keeps the windows through both.