Builders and Formatting

Build the user's custom-avatar URL, or null when the avatar field is null

Uses only the supplied id and avatar fields, and no profile is fetched. An omitted avatar is invalid and throws AssetUrlError

avatar(
    user: Pick<User, "id" | "avatar">,
    options?: AssetUrlOptions
): string | nullavatar(
  user:
    Pick<User, "id" | "avatar">,
  options?: AssetUrlOptions
): string | null

Build Fluxer's static default-avatar URL from a canonical user ID

Static defaults have no media transform query and do not depend on user-profile availability

defaultAvatar(userId: string): string

Build a URL suitable for displaying a user avatar, using the custom avatar or a static default when avatar is null

Requires known user id and avatar fields. It never produces null, and invalid targets or options throw AssetUrlError

displayAvatar(
    user: Pick<User, "id" | "avatar">,
    options?: AssetUrlOptions
): stringdisplayAvatar(
  user:
    Pick<User, "id" | "avatar">,
  options?: AssetUrlOptions
): string

Choose an avatar to display for a user in a community

The user ID must match member.userId. Normally chooses the member avatar, then the account avatar, then a static default, while AvatarUnset selects the static default directly. Produces undefined if profileFlags is omitted or avatar is omitted without AvatarUnset. Reads guildId, userId, avatar and profileFlags from the member, not banner. Invalid targets or options throw AssetUrlError

displayMemberAvatar(
    user: Pick<User, "id" | "avatar">,
    member: Pick<
        GuildMember,
        "guildId" | "userId" | "avatar" | "profileFlags"
    >,
    options?: AssetUrlOptions
): string | undefineddisplayMemberAvatar(
  user:
    Pick<User, "id" | "avatar">,
  member: Pick<
    GuildMember,
    | "guildId" | "userId"
    | "avatar" | "profileFlags"
  >,
  options?: AssetUrlOptions
): string | undefined

Build a custom-emoji image URL from only its ID and animated metadata, without looking up the emoji

Animated emoji request animation by default. Choose Webp, Gif or Apng to preserve it, or animated false for a still image

emoji(
    emoji: Pick<GuildEmoji, "id" | "animated">,
    options?: AssetUrlOptions
): stringemoji(
  emoji: Pick<
    GuildEmoji, "id" | "animated"
  >,
  options?: AssetUrlOptions
): string

Build a community banner URL from the community's id and banner

An omitted banner hash produces undefined, and an explicitly absent banner produces null

guildBanner(
    guild: Pick<Guild, "id" | "banner">,
    options?: AssetUrlOptions
): string | null | undefinedguildBanner(
  guild:
    Pick<Guild, "id" | "banner">,
  options?: AssetUrlOptions
): string | null | undefined

Build the background image URL for an embedded community invite, using id and embedSplash

An omitted embedSplash hash produces undefined, and an explicitly absent one produces null

guildEmbedSplash(
    guild: Pick<Guild, "id" | "embedSplash">,
    options?: AssetUrlOptions
): string | null | undefinedguildEmbedSplash(
  guild: Pick<
    Guild, "id" | "embedSplash"
  >,
  options?: AssetUrlOptions
): string | null | undefined

Build a community icon URL from the community's id and icon

An omitted icon hash produces undefined, and an explicitly absent icon produces null

guildIcon(
    guild: Pick<Guild, "id" | "icon">,
    options?: AssetUrlOptions
): string | null | undefinedguildIcon(
  guild:
    Pick<Guild, "id" | "icon">,
  options?: AssetUrlOptions
): string | null | undefined

Build the community's invite-background image URL from id and splash

An omitted splash hash produces undefined, and an explicitly absent splash produces null

guildSplash(
    guild: Pick<Guild, "id" | "splash">,
    options?: AssetUrlOptions
): string | null | undefinedguildSplash(
  guild:
    Pick<Guild, "id" | "splash">,
  options?: AssetUrlOptions
): string | null | undefined

Build the member's community avatar URL using only guildId, userId and avatar

Produces undefined for an omitted avatar hash, or null for an explicitly absent avatar. It does not choose a fallback, which displayMemberAvatar provides

memberAvatar(
    member: Pick<GuildMember, "guildId" | "userId" | "avatar">,
    options?: AssetUrlOptions
): string | null | undefinedmemberAvatar(
  member: Pick<
    GuildMember,
    "guildId" | "userId" | "avatar"
  >,
  options?: AssetUrlOptions
): string | null | undefined

Build the member's community banner URL using only guildId, userId and banner

Produces undefined for an omitted banner hash, or null for an explicitly absent banner. It does not substitute the account banner

memberBanner(
    member: Pick<GuildMember, "guildId" | "userId" | "banner">,
    options?: AssetUrlOptions
): string | null | undefinedmemberBanner(
  member: Pick<
    GuildMember,
    "guildId" | "userId" | "banner"
  >,
  options?: AssetUrlOptions
): string | null | undefined

Build a role icon URL from the role's id and icon

Role icons are never animated. An omitted icon hash produces undefined, and an explicitly absent icon produces null. A role that shows an emoji has no image icon, so read its unicodeEmoji

roleIcon(
    role: Pick<GuildRole, "id" | "icon">,
    options?: AssetUrlOptions
): string | null | undefinedroleIcon(
  role:
    Pick<GuildRole, "id" | "icon">,
  options?: AssetUrlOptions
): string | null | undefined

Build a custom-sticker URL from only its ID and animated metadata

Sticker format is intentionally absent, because Fluxer returns WebP except an animated sticker's GIF source

sticker(
    sticker: Pick<GuildSticker, "id" | "animated">,
    options?: StickerAssetUrlOptions
): stringsticker(
  sticker: Pick<
    GuildSticker, "id" | "animated"
  >,
  options?: StickerAssetUrlOptions
): string

Build an account-banner URL from a users.fetchProfile result, using only user.id and profile.banner

A null banner stays null, even when a limited profile withheld the banner, so null does not prove that the account has no banner. Uses AssetUrlOptions' WebP default and transform validation, without fetching, selecting a community banner or verifying existence or access

userBanner(
    profile: Readonly<
        {
            profile: Pick<UserProfileFields, "banner">
            user: Pick<User, "id">
        }
    >,
    options?: AssetUrlOptions
): string | nulluserBanner(
  profile: Readonly<
    {
      profile: Pick<
        UserProfileFields, "banner"
      >
      user: Pick<User, "id">
    }
  >,
  options?: AssetUrlOptions
): string | null

Convert a six-digit hexadecimal string, an RGB array of three integer channels from 0 through 255, or a color number to the integer used by embeds and roles

The leading # is optional. CSS names, three-digit shorthand, alpha channels and surrounding whitespace are rejected. Values are never rounded or clamped, and invalid input throws HelperError. For colors received from users, use tryParse, which reports the same HelperError without throwing

parse(value: ColorInput): number

Turn a color integer into a lowercase six-digit string such as "#000001", including leading zeroes

Accepts only integers from 0 through 0xffffff, not the strings or arrays accepted by parse. Throws HelperError for invalid numbers

toHex(value: number): string

Split a color integer into a new frozen [red, green, blue] array, each from 0 through 255

Accepts only integers from 0 through 0xffffff. Throws HelperError for invalid numbers

toRgb(value: number): RgbColor

Convert a color with the same rules as parse, but report invalid input without throwing

The default API returns a Result holding the color integer or HelperError. The native API returns an Effect that reads the input when run and fails with HelperError. Use it for colors received from users or other untrusted sources

tryParse(value: ColorInput): Result<number, HelperError>tryParse(
  value: ColorInput
): Result<number, HelperError>

Return the member's nickname, otherwise the user's displayName, otherwise username

Only null or undefined trigger a fallback. Supply a member for the same user, this helper does not check identity or fetch data

name(
    user:
        & Pick<User, "username">
        & { readonly displayName?: string | null },
    member?: Pick<GuildMember, "nickname">
): stringname(
  user:
    & Pick<User, "username">
    & {
        readonly displayName?:
          | string | null
      },
  member?:
    Pick<GuildMember, "nickname">
): string

Create <#id> text linking to a channel, such as <#123>, and return it directly

Throws HelperError for an invalid decimal-string ID, and no channel lookup occurs

channelMention(id: string): string

Create <:name:id> text, or <a:name:id> when animated is true

A GuildEmoji can be passed directly. Throws HelperError for invalid names, IDs or animation values. This does not upload or look up an emoji

customEmoji(input: CustomEmojiMarkup): stringcustomEmoji(
  input: CustomEmojiMarkup
): string

Add backslashes so text is treated literally by Fluxer's markup parser, for example escaping **bold**

Returns the escaped string immediately and never throws for string input. It does not change a message's allowedMentions or enable notifications

escapeMarkdown(value: string): string

Read exactly one <:name:id> or <a:name:id> string into frozen name, ID and animated fields

Throws HelperError for malformed markup. This does not resolve shortcodes such as :smile: or parse Unicode emoji. For text received from users, use tryParseCustomEmoji, which reports the same HelperError without throwing

parseCustomEmoji(value: string): CustomEmojiMarkupparseCustomEmoji(
  value: string
): CustomEmojiMarkup

Read a string containing exactly one user, role or channel mention into a frozen { kind, id } object

Both <@id> and <@!id> produce kind "user". Throws HelperError for surrounding text, malformed markup or an invalid decimal ID. For text received from users, use tryParseMention, which reports the same HelperError without throwing

parseMention(value: string): Mention

Read exactly one <t:seconds:style> or <t:seconds> string into a frozen object with a new Date and style

A missing style becomes ShortDateTime. The Date has whole-second precision. Throws HelperError for malformed markup, nonpositive seconds or dates outside JavaScript's range. For text received from users, use tryParseTimestamp, which reports the same HelperError without throwing

parseTimestamp(value: string): TimestampMarkupparseTimestamp(
  value: string
): TimestampMarkup

Create <@&id> text for a decimal role ID, such as <@&123>, and return it directly

Throws HelperError for an invalid ID. Role members are not notified merely because this text appears in a message, and allowedMentions must be set separately

roleMention(id: string): string

Create <t:seconds:style> message text from a Date, which Fluxer displays in the reader's local time

The style defaults to ShortDateTime, and milliseconds are dropped. The whole Unix second must be from 1 through 8_640_000_000_000. Throws HelperError for an invalid Date, a time outside that range or an unsupported style. The input Date is not changed

timestamp(value: Date, style?: TimestampStyle): stringtimestamp(
  value: Date,
  style?: TimestampStyle
): string

Read custom-emoji markup with the same rules as parseCustomEmoji, but report invalid text without throwing

The default API returns a Result holding the frozen name, ID and animated fields or HelperError. The native API returns an Effect that reads the text when run and fails with HelperError. Use it for text received from users or other untrusted sources

tryParseCustomEmoji(value: string): Result<
    CustomEmojiMarkup, HelperError
>tryParseCustomEmoji(
  value: string
): Result<
  CustomEmojiMarkup, HelperError
>

Read a mention with the same rules as parseMention, but report invalid text without throwing

The default API returns a Result holding the frozen { kind, id } object or HelperError. The native API returns an Effect that reads the text when run and fails with HelperError. Use it for text received from users or other untrusted sources

tryParseMention(value: string): Result<Mention, HelperError>tryParseMention(value: string): Result<
  Mention, HelperError
>

Read timestamp markup with the same rules as parseTimestamp, but report invalid text without throwing

The default API returns a Result holding the frozen date and style or HelperError. The native API returns an Effect that reads the text when run and fails with HelperError. Use it for text received from users or other untrusted sources

tryParseTimestamp(value: string): Result<
    TimestampMarkup, HelperError
>tryParseTimestamp(
  value: string
): Result<
  TimestampMarkup, HelperError
>

Create <@id> text for a decimal user ID, such as <@123>, and return it directly

Throws HelperError when the ID is not a valid decimal-string snowflake. This does not look up the user, and allowedMentions must be set separately to request a notification

userMention(id: string): string

Build a hosted community-channel or direct-message URL from { id, guildId } for a community channel or { id } for a private conversation

DirectMessageChannel inputs use Fluxer's /channels/@me/:channelId route. Throws HelperError for invalid decimal IDs. A URL does not prove the channel exists or the reader can open it

channel(target: ChannelLinkTarget): stringchannel(
  target: ChannelLinkTarget
): string

Build a URL for Fluxer's bot-installation flow from an application ID, with the fixed bot scope and optional unsigned 64-bit permissions

For the hosted links export, the URL starts at Fluxer's API authorization route, which redirects to the web app's installation page wherever Fluxer currently serves it. Instance links open the instance web app's installation page directly. Throws HelperError for invalid IDs or options, and an alternate origin or scope is not accepted. This does not open the page, install the bot, authorize permissions or check whether the application exists

installation(
    applicationId: string,
    options?: InstallationLinkOptions
): stringinstallation(
  applicationId: string,
  options?: InstallationLinkOptions
): string

Build a hosted message URL in the supplied actual community-channel or direct-message context

Message and channel IDs must match, otherwise the call throws HelperError. Private versus community context is not inferred from the message alone, and access is not checked

message(
    message: MessageReference,
    channel: ChannelLinkTarget
): stringmessage(
  message: MessageReference,
  channel: ChannelLinkTarget
): string

Make the smallest ID for a Date's exact UTC millisecond, useful as a time-based pagination boundary

Throws HelperError for an invalid Date, a date before 2015-01-01 UTC or a result outside the ID range. This does not create a resource. Whether the boundary is included depends on the endpoint using it

boundary(value: Date): string

Return a new UTC Date for the creation time encoded in an ID

Throws HelperError for an invalid ID. This decodes the ID's high 41 timestamp bits relative to 2015-01-01 UTC, and does not fetch the resource or prove it is visible

createdAt(value: string): Date

Return true for a decimal string from "0" through "9223372036854775807", with no extra leading zeroes

Returns false immediately for numbers, whitespace and invalid strings, without converting through Number or failing

isValid(value: unknown): value is stringisValid(
  value: unknown
): value is string

Convert a valid decimal-string ID to bigint without losing precision

Throws HelperError for an invalid ID. For IDs received from users, use tryParse, which reports the same HelperError without throwing

parse(value: string): bigint

Return the shard that receives a community's gateway events when the bot runs totalShards shards

Fluxer calls a community a guild, so the first argument is a guild ID. Fluxer routes each community with (guildId >> 22) % totalShards, and this helper applies the same formula. Use it to find which process owns a community when shards run in several processes. Throws HelperError for an invalid ID or a totalShards outside 1 through 16,384. It does not check whether the bot belongs to that community

shardFor(guildId: string, totalShards: number): numbershardFor(
  guildId: string,
  totalShards: number
): number

Convert a decimal-string ID with the same rules as parse, but report an invalid ID without throwing

The default API returns a Result holding the bigint or HelperError. The native API returns an Effect that reads the ID when run and fails with HelperError. Use it for IDs received from users or other untrusted sources

tryParse(value: string): Result<bigint, HelperError>tryParse(value: string): Result<
  bigint, HelperError
>

Split text into a frozen array of pieces, each with string.length at most options.maxLength UTF-16 units

Prefer the last newline within a full piece, then the last whitespace, otherwise split a long word. Whitespace stays in the preceding piece, so joining with an empty separator reconstructs the input. Each lone surrogate, such as half of an emoji left by slice, first becomes U+FFFD (�) of the same length, because Fluxer refuses a lone surrogate. The pieces then join to content.toWellFormed(). To reject such text instead, check content.isWellFormed() first. Empty text gives []

split(content: string, options: TextSplitOptions): readonly string[]split(
  content: string,
  options: TextSplitOptions
): readonly string[]

Shorten text to at most options.maxLength UTF-16 units, ending in options.suffix when anything was cut

Each lone surrogate, such as half of an emoji left by slice, first becomes U+FFFD (�) of the same length, because Fluxer refuses a lone surrogate. To reject such text instead, check content.isWellFormed() first. Text that then fits is returned as it is

Otherwise the text is cut so that the kept text and the suffix together fit, at a grapheme boundary of Intl.Segmenter, so only whole visible characters are kept: The two UTF-16 units of a single Unicode code point, a base character with its combining marks, a flag, a skin-tone emoji and a joined emoji are never separated, which can leave the result shorter than maxLength

When the first character does not fit in the room before the suffix, or no room is left, the suffix alone is returned. The suffix defaults to "…" (U+2026), and a suffix of "" cuts without marking it

truncate(content: string, options: TextTruncateOptions): stringtruncate(
  content: string,
  options: TextTruncateOptions
): string