Limits
Session limits cap how many concurrent sessions a user, guild, or channel can have for a given session type.
They are enforced before a session starts, and they are registered externally via plugin.getSessionLimits().register(...).
Limits must be registered and removed before starting. Calling register() or remove() after starting the bot throws an IllegalStateError.
Registration
Register limits through plugin.getSessionLimits().register() before starting the plugin. You can use either a plain object or a builder.
const : = {
: ,
: [
{
: 1,
: .,
: .,
},
],
};
.().();You can pass multiple limits to a single register() call and register as many limits as needed before the plugin starts.
Scopes
A scope determines which sessions count toward the limit. Each scope computes a string key from the session's starting interaction.
User
One session per user. Multiple users can each have their own session.
.().({
: ,
: [{
: 1,
: .,
: .()
}],
});Example: An interactive /counter command. A user opens a session with increment/decrement buttons.
Limit of 1 per user prevents duplicate counter sessions, and opening a second counter silently displaces the first.
Guild
One session per guild. DMs are grouped under the key 'dm'.
.().({
: ,
: [{
: 3,
: .,
: .
}],
});Example: A ticket wizard. The wizard walks the user through category, priority, and description steps. Limit of 3 per guild prevents a noisy server from spawning dozens of incomplete wizards.
Channel
One session per channel. Sessions without a channelId get the key 'unknown' (at the time of writing, never the case,
but it's still covered for future-proofing).
.().({
: ,
: [{
: 1,
: .,
: .
}],
});Example: A live poll session with reaction buttons. Limit of 1 per channel ensures only one active poll runs in a channel at a time.
Composite
Combine multiple scopes. For example, one session per user per guild:
.().({
: ,
: [
{
: 1,
: .(., .),
: .(),
},
],
});Example: An embedded game like tic-tac-toe. Limit of 1 per user per guild. A user can play one game in each server they're in, but not two games in the same server.
Custom
Provide an arbitrary function that returns a string key:
.().({
: ,
: [
{
: 1,
: .((: <unknown, DjsInteractionTypes>) => .().),
: .,
},
],
});Example: A translation-review session. Users with the same Discord locale share one review session across the bot, and only one reviewer per language at a time.
Actions
An action defines what happens when the limit is exceeded.
Error
Throws SessionLimitExceededError, which you can catch and reply to the user:
.().({
: ,
: [{
: 1,
: .,
: .
}],
});
// In your command handler:
try {
await .();
} catch () {
if ( instanceof ) {
await .({ : 'You already have an active session.', : true });
}
}Example: A profile setup wizard with max 1 per user. The second attempt throws, and the handler catches to reply with a friendly ephemeral message.
Displace
Evicts an existing session to make room. The displaced session receives SessionEndCodes.Displaced.
The existing session is only ended after the new one has started. If the new session doesn't start (its start filter
rejects it, a middleware stops it, or its onStart() throws), the existing session keeps running. Only running sessions
are displaced: if every session in the scope is still starting, the new one is rejected with SessionLimitExceededError.
// Default: replaces the first existing session
.().({
: ,
: [{
: 1,
: .,
: .()
}],
});
// With a custom pick function, e.g. oldest first:
.().({
: ,
: [
{
: 1,
: .,
: .((: <unknown, DjsInteractionTypes>[]) =>
.((, ) => (
.(). < .(). ? :
)),
),
},
],
});Example: An interactive counter. The user runs /counter, and if one already exists, it's silently replaced.
The old session's onEnd() fires, its buttons are disabled, and the promise resolves with SessionEndCodes.Displaced.
Custom
Full control via ExceedDecision:
const : = {
: ,
: [
{
: 3,
: .,
: .(async (: <DjsInteractionTypes>) => {
await ..().({
: `Queue full (${..} dashboards active). Try later.`,
: true,
});
return { : false };
}),
},
],
};
.().();{ proceed: false }: throwsSessionLimitExceededError{ proceed: true, displace: null }: allows the session without eviction (bypassing the limit){ proceed: true, displace: session }: evicts that specific session and starts
Example: An admin dashboard with max 3 per guild. On exceed, the custom handler replies with a queue status message and blocks the new session.
Predicates
When you need different limits for the same session type (e.g. premium vs free users), use predicates.
.().(
{
: ,
: (: <unknown, DjsInteractionTypes>, ) => .() === 'premium',
: [{ : 5, : ., : . }],
},
{
: ,
: (: <unknown, DjsInteractionTypes>, ) => .() !== 'premium',
: [{ : 1, : ., : . }],
},
);If two or more policies for the same constructor match (or all lack a predicate), an AmbiguousSessionLimitError is thrown. Make sure predicates are mutually exclusive.
Inheritance
Limits are inherited through the prototype chain. When you start a child session, both the parent's and the child's policies are checked (AND semantics).
.().({
: ,
: [{ : 2, : ., : . }],
});
.().({
: ,
: [{ : 1, : ., : . }],
});
// Starting a ChildSession checks both policies:
// 1. At most 2 sessions in the guild (from ParentSession)
// 2. At most 1 session per user (from ChildSession)Multiple Rules
A single policy can define multiple rules. All rules must pass for the session to start.
.().({
: ,
: [
{ : 3, : ., : . },
{ : 10, : ., : .() },
],
});
// Both rules are checked:
// - At most 3 per user => Error
// - At most 10 per guild => Displace