Helpers

Small functions and types exported by chapterjs to write messages and work with ids and images.

How to send what they produce is in the Messages guide; everything a message can contain is in Message options.

import { timestamp, TimestampStyle, type GuildMember } from 'chapterjs';

function welcome(member: GuildMember) {
  return `Welcome ${member}! You joined ${timestamp(member.joinedAt ?? new Date(), TimestampStyle.Relative)}.`;
}

Mentions

A structure put in a text becomes its mention: ${user} is <@id>, ${channel} is <#id>, ${role} is <@&id>. When you only have an id, use these functions. They build text; Discord turns it into a mention when the message is shown.

userMention()

userMention(userId: Snowflake): `<@${string}>`

<@USER_ID>: mentions a user.

channelMention()

channelMention(channelId: Snowflake): `<#${string}>`

<#CHANNEL_ID>: links a channel.

roleMention()

roleMention(roleId: Snowflake): `<@&${string}>`

<@&ROLE_ID>: mentions a role.

commandMention()

commandMention(name: string, commandId: Snowflake): `</${string}:${string}>`

</NAME:COMMAND_ID>: a clickable slash command. The name includes the subcommand group and subcommand when there are some ("foo group bar").

emojiMention()

emojiMention(name: string, emojiId: Snowflake, animated?: boolean): string

<:NAME:ID> or <a:NAME:ID>: a custom emoji.

GuildNavigation

Guild Navigation Types: links to a tab of the current server. Put the value in a message as it is.

Name	Value	Opens
`GuildNavigation.Customize`	`'<id:customize>'`	The Channels & Roles tab, with the onboarding prompts
`GuildNavigation.Browse`	`'<id:browse>'`	The Browse Channels tab
`GuildNavigation.Guide`	`'<id:guide>'`	The Server Guide tab
`GuildNavigation.LinkedRoles`	`'<id:linked-roles>'`	The Linked Roles tab

Discord documentation

Dates

timestamp()

timestamp(date: Date | number, style?: TimestampStyle): string

<t:TIMESTAMP> or <t:TIMESTAMP:STYLE>: a date shown to each reader in their own timezone and language. Timestamps are expressed in seconds. A number is milliseconds since the Unix epoch, like Date.now(). Something that is not a date throws a TypeError:

timestamp() needs a valid date.

TimestampStyle

How timestamp() is shown. Without a style, Discord uses LongDateShortTime.

Name	Value	Shown as
`TimestampStyle.ShortTime`	`'t'`	16:20
`TimestampStyle.MediumTime`	`'T'`	16:20:30
`TimestampStyle.ShortDate`	`'d'`	20/04/2021
`TimestampStyle.LongDate`	`'D'`	April 20, 2021
`TimestampStyle.LongDateShortTime`	`'f'`	April 20, 2021 at 16:20 (default)
`TimestampStyle.FullDateShortTime`	`'F'`	Tuesday, April 20, 2021 at 16:20
`TimestampStyle.ShortDateShortTime`	`'s'`	20/04/2021, 16:20
`TimestampStyle.ShortDateMediumTime`	`'S'`	20/04/2021, 16:20:30
`TimestampStyle.Relative`	`'R'`	4 years ago

Discord documentation

Ids

Snowflake

A Discord id: a 64-bit number serialized as a string.

type Snowflake = string

Every id is one, and every option that takes an id takes a Snowflake. It is text because the number is too big for a JavaScript number: never turn it into one.

isSnowflake()

isSnowflake(value: unknown): value is Snowflake

Whether a value looks like a Discord id: used to reject a wrong value (a name, a mention, a number) before it is sent to Discord.

snowflakeTimestamp()

snowflakeTimestamp(id: Snowflake): number

When the thing a snowflake identifies was created, in milliseconds since the Unix epoch: (snowflake >> 22) + 1420070400000. Structures already have createdAt; this is for an id alone.

snowflakeFromTimestamp()

snowflakeFromTimestamp(timestamp: number | Date): Snowflake

The smallest snowflake created at a given time: lets before / after pagination start from a date.

import { snowflakeFromTimestamp, type TextChannel } from 'chapterjs';

async function sinceYesterday(channel: TextChannel) {
  const yesterday = Date.now() - 24 * 3600 * 1000;
  return channel.fetchMessages({ after: snowflakeFromTimestamp(yesterday), limit: 100 });
}

A date before Discord existed throws a RangeError:

Discord ids start in 2015: the date is too early.

Discord documentation

Images

ImageOptions

What every method that ends with URL takes: user.avatarURL(), member.avatarURL(), guild.iconURL(), guild.bannerURL(), guild.splashURL(), role.iconURL(), emoji.url()…

ImageFormat

The file format. By default: WebP, which Discord recommends since it works for still and animated images, whatever was uploaded.

ImageSize

The size in pixels: a power of two between 16 and 4096.

boolean

false to get the first frame of an animated image. By default an animated image stays animated.

import type { User } from 'chapterjs';

function bigAvatar(user: User) {
  return user.avatarURL({ format: 'png', size: 1024 });
}

What you get follows a few rules:

Asking for 'gif' on an image that is not animated gives a PNG instead.
An animated image stays animated only in WebP (the default) or GIF; animated: false gives its first frame.
A wrong value throws a RangeError before any URL is built:

"bmp" is not an image format. Use png, jpg, webp or gif.

100 is not an image size. Use a power of two between 16 and 4096 (64, 128, 256...).

ImageFormat

type ImageFormat = 'png' | 'jpg' | 'jpeg' | 'webp' | 'gif'

ImageSize

Image size can be any power of two between 16 and 4096.

type ImageSize = 16 | 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096

Discord documentation

Reference

Your files

Structures

Types

CLI

Mentions

userMention()

channelMention()

roleMention()

commandMention()

emojiMention()

GuildNavigation

Dates

timestamp()

TimestampStyle

Ids

Snowflake

isSnowflake()

snowflakeTimestamp()

snowflakeFromTimestamp()

Images

ImageOptions

ImageFormat

ImageSize