@ezzi/base 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# Ezzi Base
+
+Library with structures and functions for creating modern Discord applications.
+
+It all starts with the bootstrap function.
+
+```ts
+import { bootstrap } from "@ezzi/base";
+
+await bootstrap({ meta: import.meta });
+```
+
+> Migrating from Constatic to Ezzi is very simple! Just replace `@constatic/base` with `@ezzi/base`.
+
+---
+
+## 🍴 About this project (Fork)
+
+**Ezzi** is a fork of the original project [Constatic](https://github.com/rinckodev/constatic) developed by [@rinckodev](https://github.com/rinckodev).
+
+While keeping the excellent core ideas and structure of the original project, Ezzi was created to introduce customized modifications, adjustments, and improvements tailored specifically for our ecosystem's needs. All credits for the brilliant base architecture go to the original author.
+
+---
+
+## Constatic
+
+⚠️ It is recommended to use the [Constant CLI](https://constatic-docs.vercel.app/pt/docs/discord/start) to generate a project instead of doing it manually.
+
+[📚 Read the full documentation here](https://constatic-docs.vercel.app/pt/docs)

package/dist/app.d.ts

@@ -0,0 +1,47 @@
+import { type Client, type CommandInteraction, type Message, type PermissionResolvable } from "discord.js";
+import { type OptionNeed } from "./creators/commands/command.js";
+import { type CommandContext } from "./creators/commands/context.js";
+import { CommandManager } from "./creators/commands/manager.js";
+import type { EventPropData } from "./creators/events/event.js";
+import { EventManager } from "./creators/events/manager.js";
+import { ResponderManager, type GenericResponderInteraction } from "./creators/responders/manager.js";
+export interface BaseCommandsConfig {
+    guilds?: string[];
+    verbose?: boolean;
+    prefix?(message: Message): string[] | Promise<string[]>;
+    middleware?(ctx: CommandContext, block: () => void): Promise<void>;
+    onNotFound?(interaction: CommandInteraction): void;
+    onError?(ctx: CommandContext, error: unknown): void;
+    onOptionsError?(message: Message, options: OptionNeed[]): void;
+    onMemberPermissionsFailed?(ctx: CommandContext, missing: PermissionResolvable[]): void;
+    onBotPermissionsFailed?(ctx: CommandContext, missing: PermissionResolvable[]): void;
+}
+export interface BaseRespondersConfig {
+    middleware?(interaction: GenericResponderInteraction, block: () => void, params: object): Promise<void>;
+    onNotFound?(interaction: GenericResponderInteraction): void;
+    onError?(error: unknown, interaction: GenericResponderInteraction, params: object): void;
+}
+export interface BaseEventsConfig {
+    middleware?(event: EventPropData, block: (...tags: string[]) => void): Promise<void>;
+    onError?(error: unknown, event: EventPropData): void;
+}
+export type BaseErrorHandler = (error: Error | unknown, client: Client) => void;
+export interface BaseConfig {
+    commands: BaseCommandsConfig;
+    events: BaseEventsConfig;
+    responders: BaseRespondersConfig;
+    errorHandler: BaseErrorHandler;
+}
+export declare class EzziApp {
+    readonly commands: CommandManager;
+    readonly responders: ResponderManager;
+    readonly events: EventManager;
+    readonly config: BaseConfig;
+    private static "~instance";
+    private constructor();
+    static getInstance(): EzziApp;
+    static destroy(): void;
+    setErrorHandler(handler: BaseErrorHandler): void;
+    intro(): void;
+    printLogs(): void;
+}

package/dist/app.js

@@ -0,0 +1,54 @@
+// src/app.ts
+import { brBuilder } from "@magicyan/discord";
+import {
+  version as djsVersion
+} from "discord.js";
+import { styleText } from "node:util";
+import { CommandManager } from "./creators/commands/manager.js";
+import { EventManager } from "./creators/events/manager.js";
+import {
+  ResponderManager
+} from "./creators/responders/manager.js";
+import { baseErrorHandler } from "./error.js";
+import { version } from "./version.js";
+var isBun = typeof Bun !== "undefined";
+
+class EzziApp {
+  commands;
+  responders;
+  events;
+  config;
+  static "~instance" = null;
+  constructor() {
+    this.events = new EventManager(this);
+    this.commands = new CommandManager(this);
+    this.responders = new ResponderManager(this);
+    this.config = {
+      commands: {},
+      responders: {},
+      events: {},
+      errorHandler: baseErrorHandler
+    };
+  }
+  static getInstance() {
+    return this["~instance"] ??= new EzziApp;
+  }
+  static destroy() {
+    this["~instance"] = null;
+  }
+  setErrorHandler(handler) {
+    this.config.errorHandler = handler;
+  }
+  intro() {
+    console.log();
+    console.log("%s %s", styleText("blue", "★ Ezzi Base"), styleText("dim", version));
+    console.log("%s %s | %s %s", styleText("blueBright", "◌ discord.js"), styleText("dim", djsVersion), isBun ? "◌ Bun" : styleText("green", "⬢ Node.js"), styleText("dim", isBun ? Bun.version : process.versions.node));
+    console.log();
+  }
+  printLogs() {
+    console.log(brBuilder(...this.commands.logs, ...this.responders.logs, ...this.events.logs));
+  }
+}
+export {
+  EzziApp
+};

package/dist/bootstrap.d.ts

@@ -0,0 +1,68 @@
+import { type Client } from "discord.js";
+import { type BaseErrorHandler } from "./app.js";
+import { type CustomClientOptions } from "./client.js";
+export interface BootstrapOptions extends CustomClientOptions {
+    /**
+     * The caller module's `import.meta`.
+     * Internally used for resolving file paths when dynamically loading modules.
+     */
+    meta: ImportMeta;
+    /**
+     * The Discord bot token.
+     * If omitted, bootstrap will attempt to use:
+     * - `env.BOT_TOKEN`
+     * - `process.env.BOT_TOKEN`
+     */
+    token?: string;
+    /**
+     * A custom error handler that overrides the default one
+     * configured by `EzziApp`.
+     *
+     * If provided, all global errors such as:
+     * - `uncaughtException`
+     * - `unhandledRejection`
+     *
+     * will be handled by this function.
+     */
+    errorHandler?: BaseErrorHandler;
+    /**
+     * A hook executed before loading the modules.
+     * Can be used to register services, prepare caches,
+     * validate dependencies, or modify the client before initialization.
+     */
+    beforeLoad?(client: Client<boolean>): Promise<void>;
+    /**
+     * Additional glob patterns used to load application modules.
+     */
+    modules?: string[];
+    /**
+     * Whether initialization logs should be displayed.
+     * Defaults to `true`.
+     */
+    loadLogs?: boolean;
+    /**
+     * Custom environment variables that may complement or override
+     * values from `process.env`.
+     */
+    env?: Record<string, any>;
+}
+/**
+ *
+ * Bootstraps and initializes a Ezzi application, creating the Discord client,
+ * loading modules, registering events, and applying global error handlers.
+ *
+ * @example
+ * import { bootstrap } from "@ezzi/base";
+ *
+ * await bootstrap({ meta: import.meta });
+ *
+ * @example
+ * import { env } from "#env";
+ * import { bootstrap } from "@ezzi/base";
+ *
+ * await bootstrap({ meta: import.meta, env });
+ */
+export declare function bootstrap(options: BootstrapOptions): Promise<{
+    client: Client<boolean>;
+    imports: import("./modules.js").ModuleImported[];
+}>;

package/dist/bootstrap.js

@@ -0,0 +1,35 @@
+// src/bootstrap.ts
+import { EzziApp } from "./app.js";
+import { createClient } from "./client.js";
+import { EzziError } from "./error.js";
+import { loadModules } from "./modules.js";
+async function bootstrap(options) {
+  const token = options.token ?? options.env?.BOT_TOKEN ?? process.env?.BOT_TOKEN;
+  if (!token)
+    throw new EzziError("The application token was not provided!");
+  const app = EzziApp.getInstance();
+  if (options.errorHandler) {
+    app.setErrorHandler(options.errorHandler);
+  }
+  const client = createClient(token, options);
+  process.on("uncaughtException", (error) => app.config.errorHandler(error, client));
+  process.on("unhandledRejection", (error) => app.config.errorHandler(error, client));
+  if (options.beforeLoad) {
+    await options.beforeLoad(client);
+  }
+  const imports = await loadModules(options.meta, [
+    "./discord/**/*.{js,ts,jsx,tsx}",
+    "!./discord/index.{js,ts,jsx,tsx}",
+    ...options.modules ?? []
+  ]);
+  if (options.loadLogs ?? true) {
+    app.printLogs();
+  }
+  app.intro();
+  app.events.register(client);
+  client.login();
+  return { client, imports };
+}
+export {
+  bootstrap
+};

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+import { Client, type ClientOptions } from "discord.js";
+export type CustomClientOptions = Partial<ClientOptions>;
+/**
+ * Creates and configures a Discord.js client instance integrated with EzziApp.
+ *
+ * This function initializes a `Client`, assigns the provided bot token, binds
+ * lifecycle events, and automatically wires command handlers, autocomplete
+ * handlers, prefix messages, and general interaction responders from the Ezzi framework.
+ *
+ * The client will log a formatted startup message once it becomes ready.
+ */
+export declare function createClient(token: string, options: CustomClientOptions): Client<boolean>;

package/dist/client.js

@@ -0,0 +1,42 @@
+// src/client.ts
+import { CustomItents, CustomPartials } from "@magicyan/discord";
+import { Client } from "discord.js";
+import { styleText } from "node:util";
+import { EzziApp } from "./app.js";
+function createClient(token, options) {
+  const app = EzziApp.getInstance();
+  const client = new Client({
+    ...options,
+    intents: options.intents ?? CustomItents.All,
+    partials: options.partials ?? CustomPartials.All,
+    failIfNotExists: options.failIfNotExists ?? false
+  });
+  client.token = token;
+  client.once("clientReady", async (readyClient) => {
+    console.log("%s %s %s", styleText("green", "●"), styleText(["greenBright", "underline"], readyClient.user.username), styleText("green", "application is ready!"));
+    await app.commands.register(readyClient);
+    if (typeof app.events.runReady === "function") {
+      await app.events.runReady(readyClient);
+    }
+  });
+  client.on("messageCreate", async (message) => {
+    if (message.author.bot)
+      return;
+    await app.commands.onPrefixCommand(message);
+  });
+  client.on("interactionCreate", async (interaction) => {
+    if (interaction.isAutocomplete()) {
+      await app.commands.onAutocomplete(interaction);
+      return;
+    }
+    if (interaction.isCommand()) {
+      await app.commands.onCommand(interaction);
+      return;
+    }
+    await app.responders.onResponder(interaction);
+  });
+  return client;
+}
+export {
+  createClient
+};

package/dist/creators/commands/command.d.ts

@@ -0,0 +1,140 @@
+import { type APIInteractionDataResolvedGuildMember, type APIRole, type ApplicationCommandOptionAllowedChannelTypes, type ApplicationCommandOptionChoiceData, ApplicationCommandOptionType, ApplicationCommandType, Attachment, AutocompleteInteraction, type BaseApplicationCommandData, type CacheType, type Channel, ChatInputCommandInteraction, GuildMember, InteractionContextType, type LocalizationMap, MessageContextMenuCommandInteraction, type PermissionResolvable, Role, User, UserContextMenuCommandInteraction } from "discord.js";
+import type { NotEmptyArray, UniqueArray } from "../../utils/types.js";
+import { CommandContext } from "./context.js";
+export declare const IgnoreCommand: {
+    readonly Slash: "slash";
+    readonly Message: "message";
+};
+export type IgnoreCommandType = (typeof IgnoreCommand)[keyof typeof IgnoreCommand];
+export type CommandType = Exclude<ApplicationCommandType, ApplicationCommandType.PrimaryEntryPoint>;
+export type CommandContextOptions = {
+    getString(name: string, required?: boolean): string | null;
+    getNumber(name: string, required?: boolean): number | null;
+    getInteger(name: string, required?: boolean): number | null;
+    getBoolean(name: string, required?: boolean): boolean | null;
+    getUser(name: string, required?: boolean): User | null;
+    getMember(name: string): GuildMember | APIInteractionDataResolvedGuildMember | null;
+    getRole(name: string, required?: boolean): Role | APIRole | null;
+    getChannel(name: string, required?: boolean): ReturnType<ChatInputCommandInteraction["options"]["getChannel"]> | Channel | null;
+    getMentionable(name: string, required?: boolean): User | GuildMember | Role | APIInteractionDataResolvedGuildMember | APIRole | null;
+    getAttachment(name: string, required?: boolean): Attachment | null;
+    getSubcommand(required?: true): string | null;
+    getSubcommandGroup(required?: true): string | null;
+};
+export type CommandCategoryType = string;
+export type OptionValueType = "text" | "number" | "integer" | "user" | "role" | "mentionable" | "channel" | "attachment" | "boolean";
+export interface OptionNeed {
+    name: string;
+    description: string;
+    value: OptionValueType;
+}
+type AutocompleteData<T> = Promise<readonly ApplicationCommandOptionChoiceData<T extends number | string ? T : number | string>[] | undefined | void>;
+export type CacheMode<Contexts> = Contexts extends readonly InteractionContextType[] ? {
+    [InteractionContextType.Guild]: "cached";
+    [InteractionContextType.BotDM]: CacheType;
+    [InteractionContextType.PrivateChannel]: CacheType;
+}[Contexts[number]] : CacheType;
+export type AutocompleteRun<T, Contexts> = (this: void, interaction: AutocompleteInteraction<CacheMode<Contexts>>) => AutocompleteData<T>;
+interface AutocompleteOptionData<T, Contexts> {
+    autocomplete?: true | AutocompleteRun<T, Contexts>;
+}
+interface BaseOptionData {
+    name: string;
+    nameLocalizations?: LocalizationMap;
+    description?: string;
+    descriptionLocalizations?: LocalizationMap;
+    required?: boolean;
+}
+interface StringOptionData<Contexts> extends BaseOptionData, AutocompleteOptionData<string, Contexts> {
+    type: ApplicationCommandOptionType.String;
+    choices?: readonly ApplicationCommandOptionChoiceData<string>[];
+    minLength?: number;
+    maxLength?: number;
+}
+interface NumberOptionData<Contexts> extends BaseOptionData, AutocompleteOptionData<number, Contexts> {
+    type: ApplicationCommandOptionType.Number | ApplicationCommandOptionType.Integer;
+    choices?: readonly ApplicationCommandOptionChoiceData<number>[];
+    minValue?: number;
+    maxValue?: number;
+}
+interface ChannelOptionData extends BaseOptionData {
+    type: ApplicationCommandOptionType.Channel;
+    channelTypes?: readonly ApplicationCommandOptionAllowedChannelTypes[];
+}
+interface CommonOptionData extends BaseOptionData {
+    type: ApplicationCommandOptionType.Attachment | ApplicationCommandOptionType.Boolean | ApplicationCommandOptionType.Mentionable | ApplicationCommandOptionType.Role | ApplicationCommandOptionType.User;
+}
+export type SlashCommandPrimitiveOptionData<Contexts> = StringOptionData<Contexts> | NumberOptionData<Contexts> | CommonOptionData | ChannelOptionData;
+export interface SubCommandOptionData<Contexts> extends Omit<BaseOptionData, "required"> {
+    type: ApplicationCommandOptionType.Subcommand;
+    defaultMemberPermissions?: PermissionResolvable;
+    botPermissions?: PermissionResolvable[];
+    options?: SlashCommandPrimitiveOptionData<Contexts>[];
+}
+export interface GroupOptionData<Contexts> extends Omit<BaseOptionData, "required"> {
+    type: ApplicationCommandOptionType.SubcommandGroup;
+    defaultMemberPermissions?: PermissionResolvable;
+    botPermissions?: PermissionResolvable[];
+    options: SubCommandOptionData<Contexts>[];
+}
+export type SlashCommandOptionData<Contexts> = SlashCommandPrimitiveOptionData<Contexts> | GroupOptionData<Contexts> | SubCommandOptionData<Contexts>;
+export type RunInteraction<T, Contexts> = T extends ApplicationCommandType.Message ? MessageContextMenuCommandInteraction<CacheMode<Contexts>> : T extends ApplicationCommandType.User ? UserContextMenuCommandInteraction<CacheMode<Contexts>> : ChatInputCommandInteraction<CacheMode<Contexts>>;
+interface CommandRunThis {
+    /** Blocks the flow of executions */
+    block(): never;
+}
+type BaseAppCommandData = Omit<BaseApplicationCommandData, "contexts" | "dmPermission"> & Pick<BaseOptionData, "descriptionLocalizations">;
+type ResolveCommandModuleData<R> = R extends void ? undefined : R;
+export type SubCommandModuleData<Contexts, R> = Omit<BaseOptionData, "required"> & {
+    group?: string;
+    shortcut?: boolean;
+    aliases?: string[];
+    ignore?: IgnoreCommandType;
+    defaultMemberPermissions?: PermissionResolvable;
+    botPermissions?: PermissionResolvable[];
+    run(this: CommandRunThis, ctx: CommandContext, data: ResolveCommandModuleData<R>): Promise<void>;
+    options?: SlashCommandPrimitiveOptionData<Contexts>[];
+};
+export type SubCommandGroupModuleData<Contexts, R, T> = Omit<BaseOptionData, "required"> & {
+    aliases?: string[];
+    defaultMemberPermissions?: PermissionResolvable;
+    botPermissions?: PermissionResolvable[];
+    options?: Omit<SubCommandOptionData<Contexts>, "type">[];
+    run?(this: CommandRunThis, ctx: CommandContext, data: ResolveCommandModuleData<R>): Promise<T>;
+};
+export type CommandModule = (SubCommandGroupModuleData<any, any, any> & {
+    type: ApplicationCommandOptionType.SubcommandGroup;
+}) | (SubCommandModuleData<any, any> & {
+    type: ApplicationCommandOptionType.Subcommand;
+    group?: string;
+});
+export interface AppCommandData<T, Contexts, R> extends BaseAppCommandData {
+    name: string;
+    aliases?: string[];
+    category?: CommandCategoryType;
+    description?: string;
+    contexts?: NotEmptyArray<UniqueArray<Contexts>>;
+    dmPermission?: boolean;
+    type?: T;
+    global?: boolean;
+    ignore?: IgnoreCommandType;
+    botPermissions?: PermissionResolvable[];
+    run?(this: CommandRunThis, ctx: CommandContext): Promise<R>;
+    autocomplete?: AutocompleteRun<string | number, Contexts>;
+    options?: SlashCommandPrimitiveOptionData<Contexts>[] | (GroupOptionData<Contexts> | SubCommandOptionData<Contexts>)[];
+}
+export type GenericAppCommandData = AppCommandData<CommandType, readonly InteractionContextType[], unknown>;
+declare class GroupCommandModule<Type, Contexts extends readonly InteractionContextType[], Return, ModuleReturn> {
+    readonly command: Command<Type, Contexts, Return>;
+    readonly data: SubCommandGroupModuleData<Contexts, Return, ModuleReturn>;
+    constructor(command: Command<Type, Contexts, Return>, data: SubCommandGroupModuleData<Contexts, Return, ModuleReturn>);
+    subcommand(data: SubCommandModuleData<Contexts, ModuleReturn>): this;
+}
+export declare class Command<Type, Contexts extends readonly InteractionContextType[] = readonly [typeof InteractionContextType.Guild], Return = unknown> {
+    readonly modules: CommandModule[];
+    readonly data: AppCommandData<Type, Contexts, Return>;
+    constructor(data: AppCommandData<Type, Contexts, Return>);
+    group<ModuleReturn = Return>(data: SubCommandGroupModuleData<Contexts, Return, ModuleReturn>): GroupCommandModule<Type, Contexts, Return, ModuleReturn>;
+    subcommand<R = Return>(data: SubCommandModuleData<Contexts, R>): this;
+}
+export {};

package/dist/creators/commands/command.js

@@ -0,0 +1,63 @@
+// src/creators/commands/command.ts
+import {
+  ApplicationCommandOptionType,
+  ApplicationCommandType,
+  InteractionContextType
+} from "discord.js";
+var IgnoreCommand = {
+  Slash: "slash",
+  Message: "message"
+};
+
+class GroupCommandModule {
+  command;
+  data;
+  constructor(command, data) {
+    this.command = command;
+    this.data = data;
+  }
+  subcommand(data) {
+    data.group ??= this.data.name;
+    this.command.subcommand(data);
+    return this;
+  }
+}
+
+class Command {
+  modules = [];
+  data;
+  constructor(data) {
+    this.data = data;
+    this.data.type ??= ApplicationCommandType.ChatInput;
+    if (this.data.type === ApplicationCommandType.ChatInput) {
+      this.data.description ??= this.data.name;
+      this.data.name = this.data.name.toLowerCase().replaceAll(" ", "");
+    }
+    if (this.data.name.length > 32) {
+      this.data.name = this.data.name.slice(0, 32);
+    }
+    if (!this.data.contexts) {
+      Object.assign(this.data, {
+        contexts: [InteractionContextType.Guild]
+      });
+    }
+  }
+  group(data) {
+    this.modules.push({
+      ...data,
+      type: ApplicationCommandOptionType.SubcommandGroup
+    });
+    return new GroupCommandModule(this, data);
+  }
+  subcommand(data) {
+    this.modules.push({
+      ...data,
+      type: ApplicationCommandOptionType.Subcommand
+    });
+    return this;
+  }
+}
+export {
+  IgnoreCommand,
+  Command
+};

package/dist/creators/commands/context.d.ts

@@ -0,0 +1,33 @@
+import { Client, CommandInteraction, GuildMember, type InteractionEditReplyOptions, type InteractionReplyOptions, Message, type MessageEditOptions, type MessageReplyOptions, User } from "discord.js";
+import type { CommandContextOptions, SlashCommandPrimitiveOptionData } from "./command.js";
+type Source = Message | CommandInteraction;
+type ReplyOptions = string | InteractionReplyOptions | MessageReplyOptions;
+type EditOptions = string | InteractionEditReplyOptions | MessageEditOptions;
+export declare class CommandContext {
+    readonly client: Client;
+    readonly source: Source;
+    private _botReply;
+    readonly args: string[];
+    private _parsedOptions;
+    constructor(client: Client, source: Source, args?: string[], optionDefs?: SlashCommandPrimitiveOptionData<boolean>[]);
+    private _parsePrefixOptions;
+    get user(): User;
+    get member(): GuildMember | null;
+    get message(): Message<boolean> | null;
+    get guild(): import("discord.js").Guild | null;
+    get guildId(): string | null;
+    get channel(): import("discord.js").TextBasedChannel | null;
+    isInteraction(): this is CommandContext & {
+        source: CommandInteraction;
+    };
+    isMessage(): this is CommandContext & {
+        source: Message;
+    };
+    get options(): CommandContextOptions;
+    getRaw(name: string): string | null;
+    deferReply(ephemeral?: boolean): Promise<void>;
+    reply(options: ReplyOptions): Promise<Message | undefined>;
+    editReply(options: EditOptions): Promise<Message | undefined>;
+    delete(): Promise<void>;
+}
+export {};