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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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