Classkitv0.1.1

CustomId

A typed customId. The single source of truth shared by the component that mints it and the handler that reads it. This gives you typed reads on the .customId.customId field in components. Values are packed into a compact wire string rather than plain stringified tokens, so the 100-char Discord limit goes further. More string per string, basically.

class CustomId<
    Prefix extends string,
    Shape extends CustomIdShape = {}
>

class CustomId<
    Prefix extends string,
    Shape extends CustomIdShape = {}
>

const ApproveId = new CustomId('approve')
    .snowflake('userId')
    .oneOf('action', ['approve', 'deny']);

// Set the custom id on a button when creating it.
new ButtonBuilder().setCustomId(ApproveId.encode({ userId: '123', action: 'approve' }));

// reading in the handler: userId comes back a string
const { userId, action } = this.params; // userId: string, action: 'approve' | 'deny'
await this.event.guild?.members.fetch(userId);

const ApproveId = new CustomId('approve')
    .snowflake('userId')
    .oneOf('action', ['approve', 'deny']);

// Set the custom id on a button when creating it.
new ButtonBuilder().setCustomId(ApproveId.encode({ userId: '123', action: 'approve' }));

// reading in the handler: userId comes back a string
const { userId, action } = this.params; // userId: string, action: 'approve' | 'deny'
await this.event.guild?.members.fetch(userId);

Member visibility

Filter class members by access level.

constructor

Constructs a new instance of the CustomIdCustomId class

CustomId(prefix: Prefix, shape?: Shape)

CustomId(prefix: Prefix, shape?: Shape)

Showing members with Protected visibility and higher.

Methods

bool()
decode()
encode()
int()
oneOf()
owns()
snowflake()
str()
uuid()

Prefix

The stable route prefix, e.g. 'approve'.

Prefix extends string

Prefix extends string

Shape

The accumulated fields, filled in by the chain.

Shape extends CustomIdShape = {}

Shape extends CustomIdShape = {}

prefix

public readonly prefix: Prefix

public readonly prefix: Prefix

routeKey

The prefix plus a short hash of the shape, the part of the wire before the colon.

public readonly routeKey: string

public readonly routeKey: string

shape

public readonly shape: Shape

public readonly shape: Shape

bool()

Add a boolean flag.

public bool<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<boolean>>
>

public bool<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<boolean>>
>

decode()

Read a wire string back into values.

This will refuse with a default Notice when the shape changed since the wire was minted. - Or refuse with a different default Notice on a corrupt or foreign wire.

public decode(wire: string): DecodedParams<Shape>

public decode(wire: string): DecodedParams<Shape>

Parameter: wire

The customId string from the interaction.

encode()

Mint a wire string from values. Throws if a value is out of its field's range or the wire is over 100 chars.

public encode(values: DecodedParams<Shape>): string

public encode(values: DecodedParams<Shape>): string

Parameter: values

One value per field, typed by the chain.

int()

Overloads

Overload 1Overload 2

Add an integer field with no bounds, for a value up to 2^53.

public int<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<number>>
>

public int<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<number>>
>

Add an integer field bounded by min and max, so it packs into fewer characters on the wire.

public int<Name>(
    name: Name,
    min: number,
    max: number
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<number>>
>

public int<Name>(
    name: Name,
    min: number,
    max: number
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<number>>
>

oneOf()

Add a field that is one value from a fixed list, decoded as the literal union. No as constas const needed.

public oneOf<Name, Choices>(
    name: Name,
    choices: Choices
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<Choices[number]>>
>

public oneOf<Name, Choices>(
    name: Name,
    choices: Choices
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<Choices[number]>>
>

owns()

True if this wire was minted from this customId's prefix, ignoring the shape hash.

public owns(wire: string): boolean

public owns(wire: string): boolean

snowflake()

Add a Discord ID field, decoded as a string (the discord.js SnowflakeSnowflake type).

public snowflake<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<Snowflake>>
>

public snowflake<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<Snowflake>>
>

str()

Add a free short text field. Avoid it where possible, it cannot be packed so it costs the most wire space.

public str<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<string>>
>

public str<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<string>>
>

uuid()

Add a UUID field, decoded as a lowercase uuid string.

public uuid<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<string>>
>

public uuid<Name>(
    name: Name
): CustomId<
    Prefix,
    Shape & Record<Name, CustomIdField<string>>
>