# CustomId

`class` in `seedcord` · v0.12.0

<https://docs.seedcord.org/packages/seedcord/0.12.0/classes/custom-id>

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 rather than plain stringified tokens, so the 100-char Discord limit goes further. More string per string, basically.

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

## Examples

```ts
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);
```

## Constructors

### constructor

```ts
CustomId(prefix: Prefix, shape?: Shape)
```

Constructs a new instance of the `CustomId` class

## Properties

### prefix

```ts
public readonly prefix: Prefix
```

### routeKey

```ts
public readonly routeKey: string
```

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

### shape

```ts
public readonly shape: Shape
```

## Methods

### bool

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

Add a boolean flag.

### decode

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

Read a wire string back into values. Throws StaleCustomId when the shape changed since the wire was minted, or InvalidCustomId on a corrupt wire.

### encode

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

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

### int

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

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

Add an integer field. Pass min and max to pack it tightly, or omit both for an unbounded value up to 2^53.

### oneOf

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

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

### owns

```ts
public owns(wire: string): boolean
```

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

### snowflake

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

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

### str

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

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

### uuid

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

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