Builders and Formatting

assets#

const assets: AssetHelpers

import { assets, AssetFormats, type Guild, type GuildEmoji, type GuildMember, type User, type UserProfile } from "@neontechspace/fluxerly/effect"

export const assetsEffectExample = (user: Pick<User, "id" | "avatar">, member: Pick<GuildMember, "guildId" | "userId" | "avatar" | "profileFlags">, guild: Pick<Guild, "id" | "icon">, emoji: Pick<GuildEmoji, "id" | "animated">, profile: UserProfile) => ({
    avatar: assets.displayAvatar(user, { size: 256, format: AssetFormats.Webp }),
    memberAvatar: assets.displayMemberAvatar(user, member, { size: 256 }),
    icon: assets.guildIcon(guild, { format: AssetFormats.Png }),
    emojiUrl: assets.emoji(emoji, { animated: emoji.animated }),
    banner: assets.userBanner(profile),
})

colors#

const colors: ColorHelpers

display#

const display: DisplayHelpers

format#

const format: FormatHelpers

import { Effect } from "effect"
import { format, links, type GuildChannel } from "@neontechspace/fluxerly/effect"

export const helpersEffectExample = (userId: string, messageId: string, channel: GuildChannel, userText: string) =>
    Effect.gen(function* () {
        const mentioned = yield* format.tryParseMention(userText)
        return {
            escaped: format.escapeMarkdown("@everyone: **literal**"),
            mention: format.userMention(userId),
            message: links.message({ id: messageId, channelId: channel.id }, channel),
            mentionedId: mentioned.id,
        }
    })

links#

const links: LinkHelpers

snowflakes#

const snowflakes: SnowflakeHelpers

text#

const text: TextHelpers

import { Effect } from "effect"
import { permissionBits, colors, text } from "@neontechspace/fluxerly/effect"

export function pureHelpersExample(bits: bigint, content: string, colorText: string) {
    return Effect.gen(function* () {
        const color = yield* colors.tryParse(colorText)
        return {
            required: permissionBits.from(["ManageRoles", "ManageMessages"]),
            missing: permissionBits.missing(bits, ["ManageRoles", "ManageMessages"]),
            inspection: permissionBits.inspect(bits),
            color,
            chunks: text.split(content, { maxLength: 2_000 }),
            title: text.truncate(content, { maxLength: 100 }),
        }
    })
}

ColorHelpers#

type ColorHelpers = Readonly<{ … }>

parse#

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

(value: ColorInput) => number

toHex#

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

(value: number) => string

toRgb#

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

(value: number) => RgbColor

tryParse#

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

(value: ColorInput) => Effect.Effect<number, HelperError, never>(value: ColorInput)
  => Effect.Effect<
    number, HelperError, never
  >

FormatHelpers#

type FormatHelpers = Readonly<{ … }>type FormatHelpers =
    Readonly<{ … }>

channelMention#

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

(id: string) => string

customEmoji#

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

(input: CustomEmojiMarkup) => string

escapeMarkdown#

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

(value: string) => string

parseCustomEmoji#

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

(value: string) => CustomEmojiMarkup

parseMention#

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

(value: string) => Mention

parseTimestamp#

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

(value: string) => TimestampMarkup

roleMention#

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

(id: string) => string

timestamp#

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

(value: Date, style?: TimestampStyle) => string(value: Date, style?: TimestampStyle)
  => string

tryParseCustomEmoji#

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

(value: string)
    => Effect.Effect<CustomEmojiMarkup, HelperError, never>(value: string)
  => Effect.Effect<
    CustomEmojiMarkup, HelperError,
    never
  >

tryParseMention#

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

(value: string) => Effect.Effect<Mention, HelperError, never>(value: string)
  => Effect.Effect<
    Mention, HelperError, never
  >

tryParseTimestamp#

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

(value: string)
    => Effect.Effect<TimestampMarkup, HelperError, never>(value: string)
  => Effect.Effect<
    TimestampMarkup, HelperError,
    never
  >

userMention#

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

(id: string) => string

SnowflakeHelpers#

type SnowflakeHelpers = Readonly<{ … }>type SnowflakeHelpers =
    Readonly<{ … }>

boundary#

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

(value: Date) => string

createdAt#

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

(value: string) => Date

isValid#

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

(value: unknown) => value is string

parse#

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

(value: string) => bigint

shardFor#

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

(guildId: string, totalShards: number) => number(guildId: string, totalShards: number)
  => number

tryParse#

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

(value: string) => Effect.Effect<bigint, HelperError, never>(value: string)
  => Effect.Effect<
    bigint, HelperError, never
  >