API Reference

Complete API reference for DBI (Discord Bot Infrastructure).

createDBI
DBI Class
Register API
Interaction Classes
Event Classes
Locale Classes
Utility Functions
Types

createDBI

Creates a new DBI instance.

function createDBI<TNamespace, TOtherType>(
  namespace: TNamespace,
  config: DBIConfigConstructor<TNamespace, TOtherType>
): DBI<TNamespace, TOtherType>

Parameters

Parameter	Type	Description
`namespace`	`string`	Unique identifier for this bot instance
`config`	`DBIConfigConstructor`	Configuration object

Config Options

interface DBIConfigConstructor {
  // Discord client configuration
  discord: {
    token: string;
    options: Discord.ClientOptions;
  } | Array<{
    namespace: string;
    token: string;
    options: Discord.ClientOptions;
  }>;
  
  // Default settings
  defaults?: {
    locale?: {
      name?: string;
      invalidPath?: string | ((ctx: { path: string; locale: DBILocale }) => string);
    };
    directMessages?: boolean;
    defaultMemberPermissions?: Discord.PermissionsString[];
    messageCommands?: {
      deferReplyContent?: string | ((ctx) => string | Promise<string>);
    };
  };
  
  // Sharding mode
  sharding?: "hybrid" | "default" | "off";
  
  // Persistent store
  store?: DBIStore;
  
  // Reference auto-cleanup
  references?: {
    autoClear?: {
      check: number;  // Check interval in ms
      ttl: number;    // Time-to-live in ms
    };
  };
  
  // Inline listener auto-cleanup
  inlineListeners?: {
    autoClear?: {
      check: number;
      ttl: number;
    };
  };
  
  // Initial data
  data?: {
    other?: Record<string, any>;
    refs?: Map<string, { at: number; value: any; ttl?: number }>;
  };
  
  // Strict mode (throws on duplicates)
  strict?: boolean;
  
  // Message command configuration
  messageCommands?: {
    prefixes: string[] | ((ctx: { message: Discord.Message }) => string[] | Promise<string[]>);
    typeAliases?: {
      booleans?: Record<string, boolean>;
    };
  };
}

Example

const dbi = createDBI("my-bot", {
  strict: true,
  discord: {
    token: process.env.DISCORD_TOKEN,
    options: { intents: ["Guilds"] }
  },
  defaults: {
    locale: { name: "en" },
    directMessages: false
  }
});

DBI Class

Main DBI instance class.

Properties

Property	Type	Description
`namespace`	`string`	Bot namespace
`config`	`DBIConfig`	Configuration object
`data`	`DBIData`	Data storage
`events`	`Events`	Event system
`cluster`	`ClusterClient \| undefined`	Hybrid sharding cluster
`loaded`	`boolean`	Whether DBI is loaded

data Object

interface DBIData {
  interactions: Discord.Collection<string, TDBIInteractions>;
  events: Discord.Collection<string, DBIEvent>;
  locales: Discord.Collection<string, DBILocale>;
  interactionLocales: Discord.Collection<string, DBIInteractionLocale>;
  other: Record<string, any>;
  eventMap: Record<string, string[]>;
  customEventNames: Set<string>;
  unloaders: Set<() => void>;
  registers: Set<Function>;
  registerUnloaders: Set<Function>;
  refs: Map<string, { at: number; value: any; ttl?: number }>;
  clients: ClientsArray;
}

Methods

register(callback)

async register(
  callback: (api: DBIRegisterAPI) => void | Promise<void>
): Promise<void>

load(...flags)

Load all registered features.

async load(...flags: string[]): Promise<boolean>

unload()

Unload all features and cleanup.

async unload(): Promise<boolean>

login()

Connect to Discord.

async login(): Promise<void>

publish(type, guildId?, clear?)

Publish commands to Discord.

async publish(type: "Global", clear?: boolean): Promise<void>
async publish(type: "Guild", guildId: string, clear?: boolean): Promise<void>

interaction(name)

Get a registered interaction.

interaction<T>(name: T): TDBIInteractions

event(name)

Get a registered event.

event(name: string): DBIEvent

locale(name)

Get a registered locale.

locale(name: string): DBILocale

client(namespace?)

Get a client.

client(namespace?: string): TDBIClientData

emit(name, args)

Emit a custom event.

emit(name: string, args: object): void

get(key, defaultValue?)

Get from data.other.

get<K>(key: K, defaultValue?: any): any

set(key, value)

Set in data.other.

set<K>(key: K, value: any): void

has(key)

Check if key exists in data.other.

has(key: string): boolean

delete(key)

Delete from data.other.

delete(key: string): boolean

Register API

Functions available in the register callback.

ChatInput

Create a slash command.

ChatInput(config: {
  name: string;
  description: string;
  options?: any[];
  directMessages?: boolean;
  defaultMemberPermissions?: Discord.PermissionsString[];
  rateLimits?: DBIRateLimit[];
  flag?: string;
  publish?: string;
  other?: {
    messageCommand?: {
      aliases?: string[];
      ignore?: boolean;
    };
  };
  onExecute: (ctx: IDBIChatInputExecuteCtx) => void | Promise<void>;
}): DBIChatInput

ChatInputOptions

Option builders for ChatInput.

class ChatInputOptions {
  string(config): ApplicationCommandOption
  stringChoices(config): ApplicationCommandOption
  stringAutocomplete(config): ApplicationCommandOption
  integer(config): ApplicationCommandOption
  integerChoices(config): ApplicationCommandOption
  integerAutocomplete(config): ApplicationCommandOption
  number(config): ApplicationCommandOption
  numberChoices(config): ApplicationCommandOption
  numberAutocomplete(config): ApplicationCommandOption
  boolean(config): ApplicationCommandOption
  user(config): ApplicationCommandOption
  channel(config): ApplicationCommandOption
  role(config): ApplicationCommandOption
  mentionable(config): ApplicationCommandOption
  attachment(config): ApplicationCommandOption
}

Button

Create a button component.

Button(config: {
  name: string;
  options?: {
    style: Discord.ButtonStyle;
    label?: string;
    emoji?: string;
    disabled?: boolean;
    url?: string;
  };
  rateLimits?: DBIRateLimit[];
  flag?: string;
  ttl?: number;
  onExecute: (ctx: IDBIButtonExecuteCtx) => void | Promise<void>;
}): DBIButton

StringSelectMenu

Create a string select menu.

StringSelectMenu(config: {
  name: string;
  options?: {
    placeholder?: string;
    minValues?: number;
    maxValues?: number;
    disabled?: boolean;
    options: Array<{
      label: string;
      value: string;
      description?: string;
      emoji?: string;
      default?: boolean;
    }>;
  };
  rateLimits?: DBIRateLimit[];
  flag?: string;
  ttl?: number;
  onExecute: (ctx: IDBISelectMenuExecuteCtx) => void | Promise<void>;
}): DBIStringSelectMenu

UserSelectMenu, RoleSelectMenu, ChannelSelectMenu, MentionableSelectMenu

Similar to StringSelectMenu but for user/role/channel/mentionable selection.

Modal

Create a modal dialog.

Modal(config: {
  name: string;
  options?: {
    title: string;
    components: Discord.ActionRowData<Discord.ModalActionRowComponentData>[];
  };
  rateLimits?: DBIRateLimit[];
  flag?: string;
  ttl?: number;
  onExecute: (ctx: IDBIModalExecuteCtx) => void | Promise<void>;
}): DBIModal

MessageContextMenu

Create a message context menu command.

MessageContextMenu(config: {
  name: string;
  directMessages?: boolean;
  defaultMemberPermissions?: Discord.PermissionsString[];
  rateLimits?: DBIRateLimit[];
  flag?: string;
  publish?: string;
  onExecute: (ctx: IDBIMessageContextMenuExecuteCtx) => void | Promise<void>;
}): DBIMessageContextMenu

UserContextMenu

Create a user context menu command.

UserContextMenu(config: {
  name: string;
  directMessages?: boolean;
  defaultMemberPermissions?: Discord.PermissionsString[];
  rateLimits?: DBIRateLimit[];
  flag?: string;
  publish?: string;
  onExecute: (ctx: IDBIUserContextMenuExecuteCtx) => void | Promise<void>;
}): DBIUserContextMenu

Event

Create an event handler.

Event(config: {
  name: keyof ClientEvents;
  id?: string;
  disabled?: boolean;
  triggerType?: "OneByOne" | "OneByOneGlobal" | "Random" | "First";
  ordered?: {
    await?: boolean;
    delayBefore?: number;
    delayAfter?: number;
  };
  flag?: string;
  ttl?: number;
  onExecute: (ctx) => void | Promise<void>;
}): DBIEvent

Locale

Create a content locale.

Locale(config: {
  name: TDBILocaleString;
  data: Record<string, any>;
  flag?: string;
}): DBILocale

InteractionLocale

Create an interaction locale (command translation).

InteractionLocale(config: {
  name: string;  // Name of the interaction to translate
  data: Record<string, {
    name: string;
    description: string;
    options?: Record<string, {
      name: string;
      description: string;
      choices?: Record<string, string>;
    }>;
  }>;
  flag?: string;
}): DBIInteractionLocale

CustomEvent

Define a custom event.

CustomEvent(config: {
  name: string;
  map: Record<string, string>;
}): DBICustomEvent

HTMLComponentsV2

Create a Svelte/Eta template component.

HTMLComponentsV2(config: {
  name: string;
  mode?: "svelte" | "eta";
  template?: string;
  file?: string;
  handlers?: any[];
  rateLimits?: DBIRateLimit[];
  flag?: string;
  onExecute?: (ctx) => void;
}): DBIHTMLComponentsV2

Inline Creators

Create one-time use components.

createInlineButton(config): DBIButton
createInlineStringSelectMenu(config): DBIStringSelectMenu
createInlineUserSelectMenu(config): DBIUserSelectMenu
createInlineRoleSelectMenu(config): DBIRoleSelectMenu
createInlineChannelSelectMenu(config): DBIChannelSelectMenu
createInlineMentionableSelectMenu(config): DBIMentionableSelectMenu
createInlineModal(config): DBIModal
createInlineEvent(config): DBIEvent

onUnload

onUnload(callback: () => void | Promise<void>): void

Interaction Classes

DBIBaseInteraction

Base class for all interactions.

class DBIBaseInteraction {
  dbi: DBI;
  name: string;
  description: string;
  type: TDBIInteractionTypes;
  options?: any;
  other?: Record<string, any>;
  rateLimits?: DBIRateLimit[];
  flag?: string;
  publish?: string;
  ttl?: number;
  at?: number;
  
  toJSON(args?: IDBIToJSONArgs): any;
  onExecute(ctx: IDBIBaseExecuteCtx): void | Promise<void>;
}

toJSON Options

interface IDBIToJSONArgs {
  overrides?: Record<string, any>;
  reference?: {
    data?: any[];
    ttl?: number;
  };
}

Execution Context

interface IDBIBaseExecuteCtx {
  interaction: Discord.Interaction;
  locale: {
    user: DBILocale;
    guild?: DBILocale;
  };
  dbi: DBI;
  dbiInteraction: TDBIInteractions;
  setRateLimit: (type: TDBIRateLimitTypes, duration: number) => Promise<void>;
  other: Record<string, any>;
  clientNamespace: string;
  v2: boolean;
}

Builder Methods

Each component class has a createBuilder() method:

// Button
const builder = dbi.interaction("my-btn").createBuilder();
builder.setLabel("Label")
       .setEmoji("🎉")
       .setStyle(Discord.ButtonStyle.Primary)
       .setReference(["data"])
       .setTTL(60000)
       .toJSON();

// Select Menu
const builder = dbi.interaction("my-select").createBuilder();
builder.setPlaceholder("Select...")
       .setMinValues(1)
       .setMaxValues(3)
       .setOptions([...])
       .toJSON();

Event Classes

DBIEvent

Event handler class.

class DBIEvent {
  type: "Event";
  id?: string;
  name: string;
  other?: Record<string, any>;
  triggerType?: "OneByOne" | "OneByOneGlobal" | "Random" | "First";
  ordered?: TDBIEventOrder;
  dbi: DBI;
  disabled: boolean;
  flag?: string;
  ttl?: number;
  at?: number;
  
  toggle(disabled?: boolean): this;
  onExecute(ctx): void | Promise<void>;
}

Events Class

DBI event system.

class Events {
  on(
    eventName: TDBIEventNames,
    handler: (data: any) => boolean | Promise<boolean>,
    options?: { once: boolean }
  ): () => void;  // Returns unsubscribe function
  
  trigger(
    name: TDBIEventNames,
    data?: any,
    ignoreResponse?: boolean
  ): Promise<boolean>;
}

DBI Event Names

type TDBIEventNames =
  | "beforeInteraction"
  | "afterInteraction"
  | "interactionRateLimit"
  | "beforeEvent"
  | "afterEvent"
  | "interactionError"
  | "eventError"
  | "messageCommandArgumentError"
  | "messageCommandDirectMessageUsageError"
  | "messageCommandDefaultMemberPermissionsError"
  | "clientsReady";

Locale Classes

DBILocale

Content locale class.

class DBILocale {
  name: TDBILocaleString;
  data: InfinitePathProxy;  // Auto-callable nested object
  _data: Record<string, any>;  // Raw data
  dbi: DBI;
  flag?: string;
  
  mergeLocale(locale: DBILocale): DBILocale;
  get(path: string): string | null;
  format(path: string, ...args: any[]): string;
}

Usage

// Function-style access with variables
locale.data.greeting();           // "Hello!"
locale.data.welcome("John");      // "Welcome, John!"
locale.data.nested.path("a", "b"); // "a and b"

// Direct access
locale.get("greeting");           // "Hello!"
locale.format("welcome", "John"); // "Welcome, John!"

Utility Functions

Utils

const { Utils } = require("@mostfeatured/dbi");

// Recursively import all files
await Utils.recursiveImport(path: string): Promise<void>

// Parse a custom ID
Utils.parseCustomId(dbi, customId: string): {
  name: string;
  data: any[];
  v2: boolean;
}

// Build a custom ID
Utils.buildCustomId(
  dbi,
  name: string,
  data: any[],
  ttl?: number,
  v2?: boolean
): string

// Unload a module from require cache
Utils.unloadModule(path: string): void

// Recursively unload modules
Utils.recursiveUnload(path: string): void

MemoryStore

class MemoryStore {
  async get(key: string, defaultValue?: any): Promise<any>
  async set(key: string, value: any): Promise<void>
  async delete(key: string): Promise<void>
  async has(key: string): Promise<boolean>
}

Types

Rate Limit Types

type TDBIRateLimitTypes =
  | "User"
  | "Channel"
  | "Guild"
  | "Member"
  | "Message";

interface DBIRateLimit {
  type: TDBIRateLimitTypes;
  duration: number;  // milliseconds
}

Interaction Types

type TDBIInteractionTypes =
  | "ChatInput"
  | "UserContextMenu"
  | "MessageContextMenu"
  | "Modal"
  | "Autocomplete"
  | "StringSelectMenu"
  | "UserSelectMenu"
  | "ChannelSelectMenu"
  | "MentionableSelectMenu"
  | "RoleSelectMenu"
  | "Button"
  | "HTMLComponentsV2";

Locale Strings

type TDBILocaleString =
  | "en" | "bg" | "zh" | "hr" | "cs" | "da" | "nl"
  | "fi" | "fr" | "de" | "el" | "hi" | "hu" | "it"
  | "ja" | "ko" | "no" | "pl" | "pt" | "ro" | "ru"
  | "es" | "sv" | "th" | "tr" | "uk" | "vi";

Store Interface

interface DBIStore {
  get(key: string, defaultValue?: any): Promise<any>;
  set(key: string, value: any): Promise<void>;
  delete(key: string): Promise<void>;
  has(key: string): Promise<boolean>;
}

Client Data

interface TDBIClientData {
  namespace: string;
  token: string;
  options: Discord.ClientOptions;
  client: Discord.Client<true>;
}

interface ClientsArray extends Array<TDBIClientData> {
  next(key?: string): TDBIClientData;
  random(): TDBIClientData;
  random(size: number): TDBIClientData[];
  first(): TDBIClientData;
  get(namespace: string): TDBIClientData;
  indexes: Record<string, number>;
}

Referenced Data

type TDBIReferencedData = 
  | string 
  | number 
  | {
      [key: string]: any;
      $ref: string;
      $unRef(): boolean;
    };

HTMLComponentsV2 (Svelte)

Component Methods

class DBIHTMLComponentsV2 {
  // Send component to interaction or channel
  async send(
    target: Discord.Interaction | Discord.TextChannel,
    options?: {
      data?: Record<string, any>;
      flags?: string[];
      content?: string;
      ephemeral?: boolean;
      reply?: boolean;
      followUp?: boolean;
    }
  ): Promise<void>
  
  // Destroy a specific instance
  destroy(refId: string): void
  
  // Destroy all active instances
  destroyAll(): void
  
  // Get JSON representation
  toJSON(args?: { data?: Record<string, any> }): object
}

Svelte Globals

Available in Svelte component scripts:

// Props (Svelte 5 rune)
let { prop1, prop2 } = $props();

// Reactive data proxy
const data: Record<string, any>;

// Render control
function render(): void;
function update(): Promise<void>;
function rerender(): Promise<void>;
function noRender(): void;
function setThrottle(ms: number): void;

// Lifecycle
function onMount(callback: () => void | (() => void)): void;
function onDestroy(callback: () => void): void;
function destroy(): void;

// Handler context
interface HandlerContext {
  interaction: Discord.ButtonInteraction | Discord.SelectMenuInteraction;
  dbi: DBI;
  locale: { user: DBILocale; guild?: DBILocale };
}

FilesExpand file tree

API_REFERENCE.md

Latest commit

History