@fluxerjs/util 1.0.2

package/dist/index.d.mts

@@ -0,0 +1,263 @@
+/**
+ * Data structure that allows efficient storage of multiple flags (bits) in a single number.
+ */
+type BitFieldResolvable<S extends string> = S | number | BitField<S> | (S | number | BitField<S>)[];
+declare class BitField<S extends string> {
+    static Flags: Record<string, number>;
+    defaultBit: number;
+    bitfield: number;
+    constructor(bits?: BitFieldResolvable<S>);
+    get [Symbol.toStringTag](): string;
+    static resolve<S extends string>(bit: BitFieldResolvable<S>): number;
+    has(bit: BitFieldResolvable<S>): boolean;
+    add(...bits: BitFieldResolvable<S>[]): this;
+    remove(...bits: BitFieldResolvable<S>[]): this;
+    serialize(): Record<S, boolean>;
+    toArray(): S[];
+    toJSON(): number;
+    valueOf(): number;
+    equals(bitfield: BitField<S>): boolean;
+    freeze(): Readonly<BitField<S>>;
+}
+
+/** Fluxer epoch (2015-01-01 00:00:00 UTC) in milliseconds */
+declare const FLUXER_EPOCH = 1420070400000n;
+/**
+ * Utilities for Fluxer snowflake IDs.
+ * Fluxer uses Twitter Snowflakes with a custom epoch.
+ */
+declare class SnowflakeUtil {
+    static readonly EPOCH = 1420070400000n;
+    /**
+     * Converts a snowflake to a Unix timestamp in milliseconds.
+     */
+    static timestampFromSnowflake(snowflake: string): number;
+    /**
+     * Converts a snowflake to a Date.
+     */
+    static dateFromSnowflake(snowflake: string): Date;
+    /**
+     * Converts a Unix timestamp (ms) to a snowflake string.
+     * Useful for pagination (before/after).
+     */
+    static snowflakeFromTimestamp(timestamp: number): string;
+    /**
+     * Deconstructs a snowflake into its components.
+     */
+    static deconstruct(snowflake: string): {
+        timestamp: number;
+        date: Date;
+        workerId: number;
+        processId: number;
+        increment: number;
+    };
+    /**
+     * Checks if a string is a valid snowflake format (numeric string, 0 or positive).
+     */
+    static isValid(snowflake: string): boolean;
+}
+
+/**
+ * Permission flags (Discord-compatible subset used by Fluxer).
+ * Values are bit positions; actual permission value is 1 << n.
+ */
+declare const PermissionFlags: {
+    readonly CreateInstantInvite: number;
+    readonly KickMembers: number;
+    readonly BanMembers: number;
+    readonly Administrator: number;
+    readonly ManageChannels: number;
+    readonly ManageGuild: number;
+    readonly AddReactions: number;
+    readonly ViewAuditLog: number;
+    readonly PrioritySpeaker: number;
+    readonly Stream: number;
+    readonly ViewChannel: number;
+    readonly SendMessages: number;
+    readonly SendTtsMessages: number;
+    readonly ManageMessages: number;
+    readonly EmbedLinks: number;
+    readonly AttachFiles: number;
+    readonly ReadMessageHistory: number;
+    readonly MentionEveryone: number;
+    readonly UseExternalEmojis: number;
+    readonly ViewGuildInsights: number;
+    readonly Connect: number;
+    readonly Speak: number;
+    readonly MuteMembers: number;
+    readonly DeafenMembers: number;
+    readonly MoveMembers: number;
+    readonly UseVad: number;
+    readonly ChangeNickname: number;
+    readonly ManageNicknames: number;
+    readonly ManageRoles: number;
+    readonly ManageWebhooks: number;
+    readonly ManageEmojisAndStickers: number;
+    readonly UseApplicationCommands: number;
+    readonly RequestToSpeak: number;
+    readonly ManageEvents: number;
+    readonly ManageThreads: number;
+    readonly CreatePublicThreads: number;
+    readonly CreatePrivateThreads: number;
+    readonly UseExternalStickers: number;
+    readonly SendMessagesInThreads: number;
+};
+type PermissionString = keyof typeof PermissionFlags;
+declare class PermissionsBitField extends BitField<PermissionString> {
+    static Flags: {
+        readonly CreateInstantInvite: number;
+        readonly KickMembers: number;
+        readonly BanMembers: number;
+        readonly Administrator: number;
+        readonly ManageChannels: number;
+        readonly ManageGuild: number;
+        readonly AddReactions: number;
+        readonly ViewAuditLog: number;
+        readonly PrioritySpeaker: number;
+        readonly Stream: number;
+        readonly ViewChannel: number;
+        readonly SendMessages: number;
+        readonly SendTtsMessages: number;
+        readonly ManageMessages: number;
+        readonly EmbedLinks: number;
+        readonly AttachFiles: number;
+        readonly ReadMessageHistory: number;
+        readonly MentionEveryone: number;
+        readonly UseExternalEmojis: number;
+        readonly ViewGuildInsights: number;
+        readonly Connect: number;
+        readonly Speak: number;
+        readonly MuteMembers: number;
+        readonly DeafenMembers: number;
+        readonly MoveMembers: number;
+        readonly UseVad: number;
+        readonly ChangeNickname: number;
+        readonly ManageNicknames: number;
+        readonly ManageRoles: number;
+        readonly ManageWebhooks: number;
+        readonly ManageEmojisAndStickers: number;
+        readonly UseApplicationCommands: number;
+        readonly RequestToSpeak: number;
+        readonly ManageEvents: number;
+        readonly ManageThreads: number;
+        readonly CreatePublicThreads: number;
+        readonly CreatePrivateThreads: number;
+        readonly UseExternalStickers: number;
+        readonly SendMessagesInThreads: number;
+    };
+}
+type PermissionResolvable = BitFieldResolvable<PermissionString>;
+
+declare const MessageFlagsBits: {
+    readonly Crossposted: number;
+    readonly IsCrosspost: number;
+    readonly SuppressEmbeds: number;
+    readonly SourceMessageDeleted: number;
+    readonly Urgent: number;
+    readonly HasThread: number;
+    readonly Ephemeral: number;
+    readonly Loading: number;
+    readonly FailToLinkToRole: number;
+    readonly SuppressNotifications: number;
+    readonly IsVoiceMessage: number;
+    readonly CompactAttachments: number;
+};
+type MessageFlagsString = keyof typeof MessageFlagsBits;
+declare class MessageFlagsBitField extends BitField<MessageFlagsString> {
+    static Flags: {
+        readonly Crossposted: number;
+        readonly IsCrosspost: number;
+        readonly SuppressEmbeds: number;
+        readonly SourceMessageDeleted: number;
+        readonly Urgent: number;
+        readonly HasThread: number;
+        readonly Ephemeral: number;
+        readonly Loading: number;
+        readonly FailToLinkToRole: number;
+        readonly SuppressNotifications: number;
+        readonly IsVoiceMessage: number;
+        readonly CompactAttachments: number;
+    };
+}
+type MessageFlagsResolvable = BitFieldResolvable<MessageFlagsString>;
+
+declare const UserFlagsBits: {
+    readonly Staff: number;
+    readonly Partner: number;
+    readonly Hypesquad: number;
+    readonly BugHunterLevel1: number;
+    readonly HypeSquadOnlineHouse1: number;
+    readonly HypeSquadOnlineHouse2: number;
+    readonly HypeSquadOnlineHouse3: number;
+    readonly PremiumEarlySupporter: number;
+    readonly BugHunterLevel2: number;
+    readonly VerifiedBot: number;
+    readonly VerifiedDeveloper: number;
+    readonly CertifiedModerator: number;
+    readonly BotHttpInteractions: number;
+    readonly FriendlyBot: number;
+    readonly FriendlyBotManualApproval: number;
+};
+type UserFlagsString = keyof typeof UserFlagsBits;
+declare class UserFlagsBitField extends BitField<UserFlagsString> {
+    static Flags: {
+        readonly Staff: number;
+        readonly Partner: number;
+        readonly Hypesquad: number;
+        readonly BugHunterLevel1: number;
+        readonly HypeSquadOnlineHouse1: number;
+        readonly HypeSquadOnlineHouse2: number;
+        readonly HypeSquadOnlineHouse3: number;
+        readonly PremiumEarlySupporter: number;
+        readonly BugHunterLevel2: number;
+        readonly VerifiedBot: number;
+        readonly VerifiedDeveloper: number;
+        readonly CertifiedModerator: number;
+        readonly BotHttpInteractions: number;
+        readonly FriendlyBot: number;
+        readonly FriendlyBotManualApproval: number;
+    };
+}
+type UserFlagsResolvable = BitFieldResolvable<UserFlagsString>;
+
+/**
+ * Format a number as a hex color string.
+ */
+declare function formatColor(color: number): string;
+/**
+ * Escape markdown formatting characters in a string.
+ */
+declare function escapeMarkdown(text: string): string;
+/**
+ * Format a Unix timestamp for Fluxer/Discord style timestamps.
+ * @param timestamp - Unix timestamp in seconds
+ * @param style - t, T, d, D, f, F, R, etc.
+ */
+declare function formatTimestamp(timestamp: number, style?: 't' | 'T' | 'd' | 'D' | 'f' | 'F' | 'R'): string;
+/**
+ * Truncate a string to a maximum length with an optional suffix.
+ */
+declare function truncate(str: string, maxLength: number, suffix?: string): string;
+
+/**
+ * Resolve a color from various input types to a number (0-16777215).
+ */
+declare function resolveColor(color: number | string | [number, number, number]): number;
+/**
+ * Parse an emoji string (e.g. :name:123 or unicode) into id and name.
+ */
+declare function parseEmoji(emoji: string): {
+    id: string | null;
+    name: string;
+} | null;
+/**
+ * Convert emoji to the format used in API (for reactions etc).
+ * Custom: "name:id", Unicode: "unicode"
+ */
+declare function formatEmoji(emoji: {
+    id: string | null;
+    name: string;
+    animated?: boolean;
+}): string;
+
+export { BitField, type BitFieldResolvable, FLUXER_EPOCH, MessageFlagsBitField, MessageFlagsBits, type MessageFlagsResolvable, type MessageFlagsString, PermissionFlags, type PermissionResolvable, type PermissionString, PermissionsBitField, SnowflakeUtil, UserFlagsBitField, UserFlagsBits, type UserFlagsResolvable, type UserFlagsString, escapeMarkdown, formatColor, formatEmoji, formatTimestamp, parseEmoji, resolveColor, truncate };

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Data structure that allows efficient storage of multiple flags (bits) in a single number.
+ */
+type BitFieldResolvable<S extends string> = S | number | BitField<S> | (S | number | BitField<S>)[];
+declare class BitField<S extends string> {
+    static Flags: Record<string, number>;
+    defaultBit: number;
+    bitfield: number;
+    constructor(bits?: BitFieldResolvable<S>);
+    get [Symbol.toStringTag](): string;
+    static resolve<S extends string>(bit: BitFieldResolvable<S>): number;
+    has(bit: BitFieldResolvable<S>): boolean;
+    add(...bits: BitFieldResolvable<S>[]): this;
+    remove(...bits: BitFieldResolvable<S>[]): this;
+    serialize(): Record<S, boolean>;
+    toArray(): S[];
+    toJSON(): number;
+    valueOf(): number;
+    equals(bitfield: BitField<S>): boolean;
+    freeze(): Readonly<BitField<S>>;
+}
+
+/** Fluxer epoch (2015-01-01 00:00:00 UTC) in milliseconds */
+declare const FLUXER_EPOCH = 1420070400000n;
+/**
+ * Utilities for Fluxer snowflake IDs.
+ * Fluxer uses Twitter Snowflakes with a custom epoch.
+ */
+declare class SnowflakeUtil {
+    static readonly EPOCH = 1420070400000n;
+    /**
+     * Converts a snowflake to a Unix timestamp in milliseconds.
+     */
+    static timestampFromSnowflake(snowflake: string): number;
+    /**
+     * Converts a snowflake to a Date.
+     */
+    static dateFromSnowflake(snowflake: string): Date;
+    /**
+     * Converts a Unix timestamp (ms) to a snowflake string.
+     * Useful for pagination (before/after).
+     */
+    static snowflakeFromTimestamp(timestamp: number): string;
+    /**
+     * Deconstructs a snowflake into its components.
+     */
+    static deconstruct(snowflake: string): {
+        timestamp: number;
+        date: Date;
+        workerId: number;
+        processId: number;
+        increment: number;
+    };
+    /**
+     * Checks if a string is a valid snowflake format (numeric string, 0 or positive).
+     */
+    static isValid(snowflake: string): boolean;
+}
+
+/**
+ * Permission flags (Discord-compatible subset used by Fluxer).
+ * Values are bit positions; actual permission value is 1 << n.
+ */
+declare const PermissionFlags: {
+    readonly CreateInstantInvite: number;
+    readonly KickMembers: number;
+    readonly BanMembers: number;
+    readonly Administrator: number;
+    readonly ManageChannels: number;
+    readonly ManageGuild: number;
+    readonly AddReactions: number;
+    readonly ViewAuditLog: number;
+    readonly PrioritySpeaker: number;
+    readonly Stream: number;
+    readonly ViewChannel: number;
+    readonly SendMessages: number;
+    readonly SendTtsMessages: number;
+    readonly ManageMessages: number;
+    readonly EmbedLinks: number;
+    readonly AttachFiles: number;
+    readonly ReadMessageHistory: number;
+    readonly MentionEveryone: number;
+    readonly UseExternalEmojis: number;
+    readonly ViewGuildInsights: number;
+    readonly Connect: number;
+    readonly Speak: number;
+    readonly MuteMembers: number;
+    readonly DeafenMembers: number;
+    readonly MoveMembers: number;
+    readonly UseVad: number;
+    readonly ChangeNickname: number;
+    readonly ManageNicknames: number;
+    readonly ManageRoles: number;
+    readonly ManageWebhooks: number;
+    readonly ManageEmojisAndStickers: number;
+    readonly UseApplicationCommands: number;
+    readonly RequestToSpeak: number;
+    readonly ManageEvents: number;
+    readonly ManageThreads: number;
+    readonly CreatePublicThreads: number;
+    readonly CreatePrivateThreads: number;
+    readonly UseExternalStickers: number;
+    readonly SendMessagesInThreads: number;
+};
+type PermissionString = keyof typeof PermissionFlags;
+declare class PermissionsBitField extends BitField<PermissionString> {
+    static Flags: {
+        readonly CreateInstantInvite: number;
+        readonly KickMembers: number;
+        readonly BanMembers: number;
+        readonly Administrator: number;
+        readonly ManageChannels: number;
+        readonly ManageGuild: number;
+        readonly AddReactions: number;
+        readonly ViewAuditLog: number;
+        readonly PrioritySpeaker: number;
+        readonly Stream: number;
+        readonly ViewChannel: number;
+        readonly SendMessages: number;
+        readonly SendTtsMessages: number;
+        readonly ManageMessages: number;
+        readonly EmbedLinks: number;
+        readonly AttachFiles: number;
+        readonly ReadMessageHistory: number;
+        readonly MentionEveryone: number;
+        readonly UseExternalEmojis: number;
+        readonly ViewGuildInsights: number;
+        readonly Connect: number;
+        readonly Speak: number;
+        readonly MuteMembers: number;
+        readonly DeafenMembers: number;
+        readonly MoveMembers: number;
+        readonly UseVad: number;
+        readonly ChangeNickname: number;
+        readonly ManageNicknames: number;
+        readonly ManageRoles: number;
+        readonly ManageWebhooks: number;
+        readonly ManageEmojisAndStickers: number;
+        readonly UseApplicationCommands: number;
+        readonly RequestToSpeak: number;
+        readonly ManageEvents: number;
+        readonly ManageThreads: number;
+        readonly CreatePublicThreads: number;
+        readonly CreatePrivateThreads: number;
+        readonly UseExternalStickers: number;
+        readonly SendMessagesInThreads: number;
+    };
+}
+type PermissionResolvable = BitFieldResolvable<PermissionString>;
+
+declare const MessageFlagsBits: {
+    readonly Crossposted: number;
+    readonly IsCrosspost: number;
+    readonly SuppressEmbeds: number;
+    readonly SourceMessageDeleted: number;
+    readonly Urgent: number;
+    readonly HasThread: number;
+    readonly Ephemeral: number;
+    readonly Loading: number;
+    readonly FailToLinkToRole: number;
+    readonly SuppressNotifications: number;
+    readonly IsVoiceMessage: number;
+    readonly CompactAttachments: number;
+};
+type MessageFlagsString = keyof typeof MessageFlagsBits;
+declare class MessageFlagsBitField extends BitField<MessageFlagsString> {
+    static Flags: {
+        readonly Crossposted: number;
+        readonly IsCrosspost: number;
+        readonly SuppressEmbeds: number;
+        readonly SourceMessageDeleted: number;
+        readonly Urgent: number;
+        readonly HasThread: number;
+        readonly Ephemeral: number;
+        readonly Loading: number;
+        readonly FailToLinkToRole: number;
+        readonly SuppressNotifications: number;
+        readonly IsVoiceMessage: number;
+        readonly CompactAttachments: number;
+    };
+}
+type MessageFlagsResolvable = BitFieldResolvable<MessageFlagsString>;
+
+declare const UserFlagsBits: {
+    readonly Staff: number;
+    readonly Partner: number;
+    readonly Hypesquad: number;
+    readonly BugHunterLevel1: number;
+    readonly HypeSquadOnlineHouse1: number;
+    readonly HypeSquadOnlineHouse2: number;
+    readonly HypeSquadOnlineHouse3: number;
+    readonly PremiumEarlySupporter: number;
+    readonly BugHunterLevel2: number;
+    readonly VerifiedBot: number;
+    readonly VerifiedDeveloper: number;
+    readonly CertifiedModerator: number;
+    readonly BotHttpInteractions: number;
+    readonly FriendlyBot: number;
+    readonly FriendlyBotManualApproval: number;
+};
+type UserFlagsString = keyof typeof UserFlagsBits;
+declare class UserFlagsBitField extends BitField<UserFlagsString> {
+    static Flags: {
+        readonly Staff: number;
+        readonly Partner: number;
+        readonly Hypesquad: number;
+        readonly BugHunterLevel1: number;
+        readonly HypeSquadOnlineHouse1: number;
+        readonly HypeSquadOnlineHouse2: number;
+        readonly HypeSquadOnlineHouse3: number;
+        readonly PremiumEarlySupporter: number;
+        readonly BugHunterLevel2: number;
+        readonly VerifiedBot: number;
+        readonly VerifiedDeveloper: number;
+        readonly CertifiedModerator: number;
+        readonly BotHttpInteractions: number;
+        readonly FriendlyBot: number;
+        readonly FriendlyBotManualApproval: number;
+    };
+}
+type UserFlagsResolvable = BitFieldResolvable<UserFlagsString>;
+
+/**
+ * Format a number as a hex color string.
+ */
+declare function formatColor(color: number): string;
+/**
+ * Escape markdown formatting characters in a string.
+ */
+declare function escapeMarkdown(text: string): string;
+/**
+ * Format a Unix timestamp for Fluxer/Discord style timestamps.
+ * @param timestamp - Unix timestamp in seconds
+ * @param style - t, T, d, D, f, F, R, etc.
+ */
+declare function formatTimestamp(timestamp: number, style?: 't' | 'T' | 'd' | 'D' | 'f' | 'F' | 'R'): string;
+/**
+ * Truncate a string to a maximum length with an optional suffix.
+ */
+declare function truncate(str: string, maxLength: number, suffix?: string): string;
+
+/**
+ * Resolve a color from various input types to a number (0-16777215).
+ */
+declare function resolveColor(color: number | string | [number, number, number]): number;
+/**
+ * Parse an emoji string (e.g. :name:123 or unicode) into id and name.
+ */
+declare function parseEmoji(emoji: string): {
+    id: string | null;
+    name: string;
+} | null;
+/**
+ * Convert emoji to the format used in API (for reactions etc).
+ * Custom: "name:id", Unicode: "unicode"
+ */
+declare function formatEmoji(emoji: {
+    id: string | null;
+    name: string;
+    animated?: boolean;
+}): string;
+
+export { BitField, type BitFieldResolvable, FLUXER_EPOCH, MessageFlagsBitField, MessageFlagsBits, type MessageFlagsResolvable, type MessageFlagsString, PermissionFlags, type PermissionResolvable, type PermissionString, PermissionsBitField, SnowflakeUtil, UserFlagsBitField, UserFlagsBits, type UserFlagsResolvable, type UserFlagsString, escapeMarkdown, formatColor, formatEmoji, formatTimestamp, parseEmoji, resolveColor, truncate };

package/dist/index.js

@@ -0,0 +1,308 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BitField: () => BitField,
+  FLUXER_EPOCH: () => FLUXER_EPOCH,
+  MessageFlagsBitField: () => MessageFlagsBitField,
+  MessageFlagsBits: () => MessageFlagsBits,
+  PermissionFlags: () => PermissionFlags,
+  PermissionsBitField: () => PermissionsBitField,
+  SnowflakeUtil: () => SnowflakeUtil,
+  UserFlagsBitField: () => UserFlagsBitField,
+  UserFlagsBits: () => UserFlagsBits,
+  escapeMarkdown: () => escapeMarkdown,
+  formatColor: () => formatColor,
+  formatEmoji: () => formatEmoji,
+  formatTimestamp: () => formatTimestamp,
+  parseEmoji: () => parseEmoji,
+  resolveColor: () => resolveColor,
+  truncate: () => truncate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/BitField.ts
+var BitField = class _BitField {
+  static Flags = {};
+  defaultBit = 0;
+  bitfield;
+  constructor(bits = 0) {
+    const Ctor = this.constructor;
+    this.bitfield = Ctor.resolve(bits);
+  }
+  get [Symbol.toStringTag]() {
+    return `BitField${this.bitfield}`;
+  }
+  static resolve(bit) {
+    const Flags = this.Flags;
+    if (typeof bit === "number" && bit >= 0) return bit;
+    if (bit instanceof _BitField) return bit.bitfield;
+    if (Array.isArray(bit)) return bit.map((b) => this.resolve(b)).reduce((a, b) => a | b, 0);
+    if (typeof bit === "string" && typeof Flags[bit] !== "undefined") return Flags[bit];
+    throw new RangeError(`Invalid bitfield flag or number: ${bit}`);
+  }
+  has(bit) {
+    bit = this.constructor.resolve(bit);
+    return (this.bitfield & bit) === bit;
+  }
+  add(...bits) {
+    let total = 0;
+    for (const bit of bits) {
+      total |= this.constructor.resolve(bit);
+    }
+    this.bitfield |= total;
+    return this;
+  }
+  remove(...bits) {
+    let total = 0;
+    for (const bit of bits) {
+      total |= this.constructor.resolve(bit);
+    }
+    this.bitfield &= ~total;
+    return this;
+  }
+  serialize() {
+    const Flags = this.constructor.Flags;
+    const serialized = {};
+    for (const [key, value] of Object.entries(Flags)) {
+      serialized[key] = (this.bitfield & value) === value;
+    }
+    return serialized;
+  }
+  toArray() {
+    const Flags = this.constructor.Flags;
+    return Object.entries(Flags).filter(([, value]) => (this.bitfield & value) === value).map(([key]) => key);
+  }
+  toJSON() {
+    return this.bitfield;
+  }
+  valueOf() {
+    return this.bitfield;
+  }
+  equals(bitfield) {
+    return this.bitfield === bitfield.bitfield;
+  }
+  freeze() {
+    return Object.freeze(this);
+  }
+};
+
+// src/SnowflakeUtil.ts
+var FLUXER_EPOCH = 1420070400000n;
+var SnowflakeUtil = class {
+  static EPOCH = FLUXER_EPOCH;
+  /**
+   * Converts a snowflake to a Unix timestamp in milliseconds.
+   */
+  static timestampFromSnowflake(snowflake) {
+    return Number((BigInt(snowflake) >> 22n) + FLUXER_EPOCH);
+  }
+  /**
+   * Converts a snowflake to a Date.
+   */
+  static dateFromSnowflake(snowflake) {
+    return new Date(this.timestampFromSnowflake(snowflake));
+  }
+  /**
+   * Converts a Unix timestamp (ms) to a snowflake string.
+   * Useful for pagination (before/after).
+   */
+  static snowflakeFromTimestamp(timestamp) {
+    return (BigInt(timestamp) - FLUXER_EPOCH << 22n).toString();
+  }
+  /**
+   * Deconstructs a snowflake into its components.
+   */
+  static deconstruct(snowflake) {
+    const big = BigInt(snowflake);
+    return {
+      timestamp: Number((big >> 22n) + FLUXER_EPOCH),
+      date: new Date(Number((big >> 22n) + FLUXER_EPOCH)),
+      workerId: Number(big >> 17n & 0x1fn),
+      processId: Number(big >> 12n & 0x1fn),
+      increment: Number(big & 0xfffn)
+    };
+  }
+  /**
+   * Checks if a string is a valid snowflake format (numeric string, 0 or positive).
+   */
+  static isValid(snowflake) {
+    return /^(0|[1-9]\d*)$/.test(snowflake) && snowflake.length <= 20;
+  }
+};
+
+// src/PermissionsBitField.ts
+var PermissionFlags = {
+  CreateInstantInvite: 1 << 0,
+  KickMembers: 1 << 1,
+  BanMembers: 1 << 2,
+  Administrator: 1 << 3,
+  ManageChannels: 1 << 4,
+  ManageGuild: 1 << 5,
+  AddReactions: 1 << 6,
+  ViewAuditLog: 1 << 7,
+  PrioritySpeaker: 1 << 8,
+  Stream: 1 << 9,
+  ViewChannel: 1 << 10,
+  SendMessages: 1 << 11,
+  SendTtsMessages: 1 << 12,
+  ManageMessages: 1 << 13,
+  EmbedLinks: 1 << 14,
+  AttachFiles: 1 << 15,
+  ReadMessageHistory: 1 << 16,
+  MentionEveryone: 1 << 17,
+  UseExternalEmojis: 1 << 18,
+  ViewGuildInsights: 1 << 19,
+  Connect: 1 << 20,
+  Speak: 1 << 21,
+  MuteMembers: 1 << 22,
+  DeafenMembers: 1 << 23,
+  MoveMembers: 1 << 24,
+  UseVad: 1 << 25,
+  ChangeNickname: 1 << 26,
+  ManageNicknames: 1 << 27,
+  ManageRoles: 1 << 28,
+  ManageWebhooks: 1 << 29,
+  ManageEmojisAndStickers: 1 << 30,
+  UseApplicationCommands: 1 << 31,
+  RequestToSpeak: 1 << 32,
+  ManageEvents: 1 << 33,
+  ManageThreads: 1 << 34,
+  CreatePublicThreads: 1 << 35,
+  CreatePrivateThreads: 1 << 36,
+  UseExternalStickers: 1 << 37,
+  SendMessagesInThreads: 1 << 38
+};
+var PermissionsBitField = class extends BitField {
+  static Flags = PermissionFlags;
+};
+
+// src/MessageFlagsBitField.ts
+var MessageFlagsBits = {
+  Crossposted: 1 << 0,
+  IsCrosspost: 1 << 1,
+  SuppressEmbeds: 1 << 2,
+  SourceMessageDeleted: 1 << 3,
+  Urgent: 1 << 4,
+  HasThread: 1 << 5,
+  Ephemeral: 1 << 6,
+  Loading: 1 << 7,
+  FailToLinkToRole: 1 << 8,
+  SuppressNotifications: 1 << 12,
+  IsVoiceMessage: 1 << 13,
+  CompactAttachments: 1 << 17
+};
+var MessageFlagsBitField = class extends BitField {
+  static Flags = MessageFlagsBits;
+};
+
+// src/UserFlagsBitField.ts
+var UserFlagsBits = {
+  Staff: 1 << 0,
+  Partner: 1 << 1,
+  Hypesquad: 1 << 2,
+  BugHunterLevel1: 1 << 3,
+  HypeSquadOnlineHouse1: 1 << 6,
+  HypeSquadOnlineHouse2: 1 << 7,
+  HypeSquadOnlineHouse3: 1 << 8,
+  PremiumEarlySupporter: 1 << 9,
+  BugHunterLevel2: 1 << 14,
+  VerifiedBot: 1 << 16,
+  VerifiedDeveloper: 1 << 17,
+  CertifiedModerator: 1 << 18,
+  BotHttpInteractions: 1 << 19,
+  FriendlyBot: 1 << 20,
+  FriendlyBotManualApproval: 1 << 21
+};
+var UserFlagsBitField = class extends BitField {
+  static Flags = UserFlagsBits;
+};
+
+// src/formatters.ts
+function formatColor(color) {
+  const hex = color.toString(16).padStart(6, "0");
+  return `#${hex}`;
+}
+function escapeMarkdown(text) {
+  return text.replace(/([\\*_`~|])/g, "\\$1");
+}
+function formatTimestamp(timestamp, style) {
+  const suffix = style ? `:${style}` : "";
+  return `<t:${Math.floor(timestamp / 1e3)}${suffix}>`;
+}
+function truncate(str, maxLength, suffix = "...") {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - suffix.length) + suffix;
+}
+
+// src/resolvers.ts
+function resolveColor(color) {
+  if (typeof color === "number") {
+    if (color < 0 || color > 16777215) throw new RangeError("Color must be between 0 and 16777215");
+    return color;
+  }
+  if (Array.isArray(color)) {
+    const [r, g, b] = color;
+    return r << 16 | g << 8 | b;
+  }
+  if (typeof color === "string") {
+    const hex = color.replace(/^#/, "");
+    if (!/^[0-9a-fA-F]{6}$/.test(hex)) throw new RangeError("Invalid hex color");
+    return parseInt(hex, 16);
+  }
+  throw new TypeError("Color must be a number, hex string, or RGB array");
+}
+function parseEmoji(emoji) {
+  const custom = /^<a?:\w+:(\d+)>$/;
+  const match = emoji.match(custom);
+  if (match) {
+    const name = emoji.slice(emoji.indexOf(":") + 1, emoji.lastIndexOf(":"));
+    return { id: match[1], name };
+  }
+  if (emoji.length > 0) return { id: null, name: emoji };
+  return null;
+}
+function formatEmoji(emoji) {
+  if (emoji.id) {
+    const prefix = emoji.animated ? "a" : "";
+    return `${prefix}:${emoji.name}:${emoji.id}`;
+  }
+  return encodeURIComponent(emoji.name);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BitField,
+  FLUXER_EPOCH,
+  MessageFlagsBitField,
+  MessageFlagsBits,
+  PermissionFlags,
+  PermissionsBitField,
+  SnowflakeUtil,
+  UserFlagsBitField,
+  UserFlagsBits,
+  escapeMarkdown,
+  formatColor,
+  formatEmoji,
+  formatTimestamp,
+  parseEmoji,
+  resolveColor,
+  truncate
+});

package/dist/index.mjs

@@ -0,0 +1,266 @@
+// src/BitField.ts
+var BitField = class _BitField {
+  static Flags = {};
+  defaultBit = 0;
+  bitfield;
+  constructor(bits = 0) {
+    const Ctor = this.constructor;
+    this.bitfield = Ctor.resolve(bits);
+  }
+  get [Symbol.toStringTag]() {
+    return `BitField${this.bitfield}`;
+  }
+  static resolve(bit) {
+    const Flags = this.Flags;
+    if (typeof bit === "number" && bit >= 0) return bit;
+    if (bit instanceof _BitField) return bit.bitfield;
+    if (Array.isArray(bit)) return bit.map((b) => this.resolve(b)).reduce((a, b) => a | b, 0);
+    if (typeof bit === "string" && typeof Flags[bit] !== "undefined") return Flags[bit];
+    throw new RangeError(`Invalid bitfield flag or number: ${bit}`);
+  }
+  has(bit) {
+    bit = this.constructor.resolve(bit);
+    return (this.bitfield & bit) === bit;
+  }
+  add(...bits) {
+    let total = 0;
+    for (const bit of bits) {
+      total |= this.constructor.resolve(bit);
+    }
+    this.bitfield |= total;
+    return this;
+  }
+  remove(...bits) {
+    let total = 0;
+    for (const bit of bits) {
+      total |= this.constructor.resolve(bit);
+    }
+    this.bitfield &= ~total;
+    return this;
+  }
+  serialize() {
+    const Flags = this.constructor.Flags;
+    const serialized = {};
+    for (const [key, value] of Object.entries(Flags)) {
+      serialized[key] = (this.bitfield & value) === value;
+    }
+    return serialized;
+  }
+  toArray() {
+    const Flags = this.constructor.Flags;
+    return Object.entries(Flags).filter(([, value]) => (this.bitfield & value) === value).map(([key]) => key);
+  }
+  toJSON() {
+    return this.bitfield;
+  }
+  valueOf() {
+    return this.bitfield;
+  }
+  equals(bitfield) {
+    return this.bitfield === bitfield.bitfield;
+  }
+  freeze() {
+    return Object.freeze(this);
+  }
+};
+
+// src/SnowflakeUtil.ts
+var FLUXER_EPOCH = 1420070400000n;
+var SnowflakeUtil = class {
+  static EPOCH = FLUXER_EPOCH;
+  /**
+   * Converts a snowflake to a Unix timestamp in milliseconds.
+   */
+  static timestampFromSnowflake(snowflake) {
+    return Number((BigInt(snowflake) >> 22n) + FLUXER_EPOCH);
+  }
+  /**
+   * Converts a snowflake to a Date.
+   */
+  static dateFromSnowflake(snowflake) {
+    return new Date(this.timestampFromSnowflake(snowflake));
+  }
+  /**
+   * Converts a Unix timestamp (ms) to a snowflake string.
+   * Useful for pagination (before/after).
+   */
+  static snowflakeFromTimestamp(timestamp) {
+    return (BigInt(timestamp) - FLUXER_EPOCH << 22n).toString();
+  }
+  /**
+   * Deconstructs a snowflake into its components.
+   */
+  static deconstruct(snowflake) {
+    const big = BigInt(snowflake);
+    return {
+      timestamp: Number((big >> 22n) + FLUXER_EPOCH),
+      date: new Date(Number((big >> 22n) + FLUXER_EPOCH)),
+      workerId: Number(big >> 17n & 0x1fn),
+      processId: Number(big >> 12n & 0x1fn),
+      increment: Number(big & 0xfffn)
+    };
+  }
+  /**
+   * Checks if a string is a valid snowflake format (numeric string, 0 or positive).
+   */
+  static isValid(snowflake) {
+    return /^(0|[1-9]\d*)$/.test(snowflake) && snowflake.length <= 20;
+  }
+};
+
+// src/PermissionsBitField.ts
+var PermissionFlags = {
+  CreateInstantInvite: 1 << 0,
+  KickMembers: 1 << 1,
+  BanMembers: 1 << 2,
+  Administrator: 1 << 3,
+  ManageChannels: 1 << 4,
+  ManageGuild: 1 << 5,
+  AddReactions: 1 << 6,
+  ViewAuditLog: 1 << 7,
+  PrioritySpeaker: 1 << 8,
+  Stream: 1 << 9,
+  ViewChannel: 1 << 10,
+  SendMessages: 1 << 11,
+  SendTtsMessages: 1 << 12,
+  ManageMessages: 1 << 13,
+  EmbedLinks: 1 << 14,
+  AttachFiles: 1 << 15,
+  ReadMessageHistory: 1 << 16,
+  MentionEveryone: 1 << 17,
+  UseExternalEmojis: 1 << 18,
+  ViewGuildInsights: 1 << 19,
+  Connect: 1 << 20,
+  Speak: 1 << 21,
+  MuteMembers: 1 << 22,
+  DeafenMembers: 1 << 23,
+  MoveMembers: 1 << 24,
+  UseVad: 1 << 25,
+  ChangeNickname: 1 << 26,
+  ManageNicknames: 1 << 27,
+  ManageRoles: 1 << 28,
+  ManageWebhooks: 1 << 29,
+  ManageEmojisAndStickers: 1 << 30,
+  UseApplicationCommands: 1 << 31,
+  RequestToSpeak: 1 << 32,
+  ManageEvents: 1 << 33,
+  ManageThreads: 1 << 34,
+  CreatePublicThreads: 1 << 35,
+  CreatePrivateThreads: 1 << 36,
+  UseExternalStickers: 1 << 37,
+  SendMessagesInThreads: 1 << 38
+};
+var PermissionsBitField = class extends BitField {
+  static Flags = PermissionFlags;
+};
+
+// src/MessageFlagsBitField.ts
+var MessageFlagsBits = {
+  Crossposted: 1 << 0,
+  IsCrosspost: 1 << 1,
+  SuppressEmbeds: 1 << 2,
+  SourceMessageDeleted: 1 << 3,
+  Urgent: 1 << 4,
+  HasThread: 1 << 5,
+  Ephemeral: 1 << 6,
+  Loading: 1 << 7,
+  FailToLinkToRole: 1 << 8,
+  SuppressNotifications: 1 << 12,
+  IsVoiceMessage: 1 << 13,
+  CompactAttachments: 1 << 17
+};
+var MessageFlagsBitField = class extends BitField {
+  static Flags = MessageFlagsBits;
+};
+
+// src/UserFlagsBitField.ts
+var UserFlagsBits = {
+  Staff: 1 << 0,
+  Partner: 1 << 1,
+  Hypesquad: 1 << 2,
+  BugHunterLevel1: 1 << 3,
+  HypeSquadOnlineHouse1: 1 << 6,
+  HypeSquadOnlineHouse2: 1 << 7,
+  HypeSquadOnlineHouse3: 1 << 8,
+  PremiumEarlySupporter: 1 << 9,
+  BugHunterLevel2: 1 << 14,
+  VerifiedBot: 1 << 16,
+  VerifiedDeveloper: 1 << 17,
+  CertifiedModerator: 1 << 18,
+  BotHttpInteractions: 1 << 19,
+  FriendlyBot: 1 << 20,
+  FriendlyBotManualApproval: 1 << 21
+};
+var UserFlagsBitField = class extends BitField {
+  static Flags = UserFlagsBits;
+};
+
+// src/formatters.ts
+function formatColor(color) {
+  const hex = color.toString(16).padStart(6, "0");
+  return `#${hex}`;
+}
+function escapeMarkdown(text) {
+  return text.replace(/([\\*_`~|])/g, "\\$1");
+}
+function formatTimestamp(timestamp, style) {
+  const suffix = style ? `:${style}` : "";
+  return `<t:${Math.floor(timestamp / 1e3)}${suffix}>`;
+}
+function truncate(str, maxLength, suffix = "...") {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - suffix.length) + suffix;
+}
+
+// src/resolvers.ts
+function resolveColor(color) {
+  if (typeof color === "number") {
+    if (color < 0 || color > 16777215) throw new RangeError("Color must be between 0 and 16777215");
+    return color;
+  }
+  if (Array.isArray(color)) {
+    const [r, g, b] = color;
+    return r << 16 | g << 8 | b;
+  }
+  if (typeof color === "string") {
+    const hex = color.replace(/^#/, "");
+    if (!/^[0-9a-fA-F]{6}$/.test(hex)) throw new RangeError("Invalid hex color");
+    return parseInt(hex, 16);
+  }
+  throw new TypeError("Color must be a number, hex string, or RGB array");
+}
+function parseEmoji(emoji) {
+  const custom = /^<a?:\w+:(\d+)>$/;
+  const match = emoji.match(custom);
+  if (match) {
+    const name = emoji.slice(emoji.indexOf(":") + 1, emoji.lastIndexOf(":"));
+    return { id: match[1], name };
+  }
+  if (emoji.length > 0) return { id: null, name: emoji };
+  return null;
+}
+function formatEmoji(emoji) {
+  if (emoji.id) {
+    const prefix = emoji.animated ? "a" : "";
+    return `${prefix}:${emoji.name}:${emoji.id}`;
+  }
+  return encodeURIComponent(emoji.name);
+}
+export {
+  BitField,
+  FLUXER_EPOCH,
+  MessageFlagsBitField,
+  MessageFlagsBits,
+  PermissionFlags,
+  PermissionsBitField,
+  SnowflakeUtil,
+  UserFlagsBitField,
+  UserFlagsBits,
+  escapeMarkdown,
+  formatColor,
+  formatEmoji,
+  formatTimestamp,
+  parseEmoji,
+  resolveColor,
+  truncate
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@fluxerjs/util",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.2",
+  "description": "Shared utilities for @fluxerjs/core",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "clean": "rm -rf dist"
+  }
+}