Classcorev0.1.4

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 field in components. Values are packed into a compact wire string, which fits more of them inside Discord's 100-char limit.

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' }));

// 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 CustomId class

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

Shape

The accumulated fields, filled in by the chain.

Shape extends CustomIdShape = {}

prefix

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

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

shape

The field definitions accumulated by the chain, keyed by name.

public readonly shape: Shape

bool()

Add a boolean flag.

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>

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

Parameter: values

One value per field, typed by the chain.

int()

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>>
>

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>>
>

oneOf()

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

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

snowflake()

Add a Discord ID field, decoded as a string (the Snowflake type from discord-api-types).

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, which makes it the most expensive field on the wire.

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>>
>

Classcorev0.1.4

CustomId

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' }));

// 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 CustomId class

CustomId(prefix: Prefix, shape?: Shape)

Showing members with Protected visibility and higher.

Properties

prefix
routeKey
shape

Methods

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

Prefix

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

Prefix extends string

Shape

The accumulated fields, filled in by the chain.

Shape extends CustomIdShape = {}

prefix

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

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

shape

The field definitions accumulated by the chain, keyed by name.

public readonly shape: Shape

bool()

Add a boolean flag.

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>

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

Parameter: values

One value per field, typed by the chain.

int()

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>>
>

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>>
>

oneOf()

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

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

snowflake()

Add a Discord ID field, decoded as a string (the Snowflake type from discord-api-types).

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, which makes it the most expensive field on the wire.

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>>
>