Utils

BdApi.Utils - Utility functions for common operations

BdApi.Utils provides commonly reused utility functions for working with objects, trees, debouncing, HTML escaping, and more.

Methods

findInTree

Finds a value, subobject, or array from a tree that matches a specific filter using depth-first search.

BdApi.Utils.findInTree(
  tree: object,
  searchFilter: (value: any) => boolean,
  options?: {
    walkable?: string[] | null,
    ignore?: string[]
  }
): any

tree · object · required

Tree that should be walked

searchFilter · function · required

Filter to check against each object and subobject. Should return true when the desired value is found.

options.walkable · string[] | null · default: "null"

Array of strings to use as keys that are allowed to be walked on. null indicates all keys are walkable.

options.ignore · string[] · default: "[]"

Array of strings to use as keys to exclude from the search. Most helpful when walkable is null.

const user = {
  profile: {
    settings: {
      theme: "dark"
    }
  }
};

const theme = BdApi.Utils.findInTree(
  user,
  (value) => value === "dark"
);
// Returns: "dark"

forceLoad

Loads the module ids within a webpack chunk.

BdApi.Utils.forceLoad(id: number | string): Promise<object>

id · number | string · required

Module with the chunk id

Returns a Promise that resolves to the loaded chunk module.

const module = await BdApi.Utils.forceLoad(12345);

extend

Deep extends an object with a set of other objects. Objects later in the list have priority.

BdApi.Utils.extend(
  extendee: object,
  ...extenders: object[]
): object

extendee · object · required

Object to be extended

extenders · object[] · required

Objects to extend with. Later objects have priority.

Returns a reference to the modified extendee.

const base = {a: 1, b: {c: 2}};
const extended = BdApi.Utils.extend(
  base,
  {b: {d: 3}},
  {e: 4}
);
// base is now: {a: 1, b: {c: 2, d: 3}, e: 4}

debounce

Returns a debounced function that delays invoking the provided function until after delay milliseconds have elapsed since the last invocation.

BdApi.Utils.debounce(
  executor: (...args: any[]) => any,
  delay: number
): (...args: any[]) => any

executor · function · required

The function to be debounced

delay · number · required

Number of milliseconds to delay calls

const saveSettings = BdApi.Utils.debounce((settings) => {
  console.log("Saving:", settings);
}, 500);

// Only the last call will execute after 500ms
saveSettings({theme: "dark"});
saveSettings({theme: "light"});

escapeHTML

Takes a string of HTML and escapes it using the browser’s own escaping mechanism.

BdApi.Utils.escapeHTML(html: string): string

html · string · required

HTML to be escaped

const escaped = BdApi.Utils.escapeHTML('<script>alert("XSS")</script>');
// Returns: "&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;"

className

Builds a classname string from any number of arguments. Supports arrays and objects.

BdApi.Utils.className(
  ...arguments: any[]
): string

arguments · any[] · required

Anything that should be used to add classnames. Arrays add all values, objects add keys where values are truthy.

// Strings
BdApi.Utils.className('foo', 'bar');
// Returns: "foo bar"

// Objects
BdApi.Utils.className({foo: true, bar: false, baz: true});
// Returns: "foo baz"

// Arrays
BdApi.Utils.className(['foo', 'bar']);
// Returns: "foo bar"

// Mixed
BdApi.Utils.className('foo', {bar: true, baz: false}, ['qux']);
// Returns: "foo bar qux"

getNestedValue

Gets a nested value (if it exists) of an object safely using a key path string.

BdApi.Utils.getNestedValue<T, R>(
  object: T,
  path: string
): R

object · object · required

Object to get nested value from

path · string · required

Key path to the desired value (e.g., "key.key2.key3"). Numbers can be used for arrays like "key.array.0.id".

const data = {
  user: {
    profile: {
      name: "Alice"
    },
    posts: [{id: 1, title: "Hello"}]
  }
};

BdApi.Utils.getNestedValue(data, "user.profile.name");
// Returns: "Alice"

BdApi.Utils.getNestedValue(data, "user.posts.0.title");
// Returns: "Hello"

semverCompare

Compares two semantic version strings (e.g., “1.0.0”).

BdApi.Utils.semverCompare(
  currentVersion: string,
  newVersion: string
): number

currentVersion · string · required

First version to compare

newVersion · string · required

Second version to compare

Returns:

• 0 if versions are equal
• -1 if currentVersion is greater
• 1 if newVersion is greater

BdApi.Utils.semverCompare("1.0.0", "1.0.0");
// Returns: 0

BdApi.Utils.semverCompare("2.0.0", "1.0.0");
// Returns: -1

BdApi.Utils.semverCompare("1.0.0", "2.0.0");
// Returns: 1

Store

Base store class for creating custom stores with subscription support.

const myStore = new BdApi.Utils.Store();