horizon.js 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Andrew (e60m5ss / wlix)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+<h1 align="center">horizon.js</h1>
+
+> Discord.js v14 command and event handler
+
+## Installation
+
+```bash
+npm install horizon.js
+# or
+yarn add horizon.js
+# or
+pnpm add horizon.js
+# or
+bun add horizon.js
+```
+
+## Example
+
+`src/index.js`
+
+```js
+import { Client, GatewayIntentBits } from "discord.js";
+import { CommandHandler, EventHandler } from "horizon.js";
+import url from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const client = new Client({
+    intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.MessageContent,
+    ],
+});
+
+new CommandHandler({
+    client,
+    commandsPath: path.join(__dirname, "commands"),
+});
+
+new EventHandler({
+    client,
+    eventsPath: path.join(__dirname, "events"),
+});
+
+client.login(TOKEN);
+```
+
+`src/commands/General/ping.js`
+
+```js
+import { SlashCommandBuilder } from "discord.js";
+
+export const data = new SlashCommandBuilder()
+    .setName("ping")
+    .setDescription("Replies with Pong");
+
+/**
+ * @param {import("horizon.js").SlashCommandProps} param0
+ */
+export async function run({ client, interaction, handler }) {
+    await interaction.reply(`Pong! Latency is ${client.ws.ping} ms.`);
+}
+```
+
+`src/events/messageCreate/hello.js`
+
+```js
+/**
+ * @param {import("discord.js").Message} message
+ */
+export default async function (message) {
+    if (message.author.bot) {
+        return;
+    }
+
+    if (message.content === "hello") {
+        await message.reply("Howdy! 👋");
+    }
+}
+```
+
+## Contributing
+
+Pull requests are always welcomed. For more major changes, please open an issue to discuss what you wish to change.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,64 @@
+import { Client, ChatInputCommandInteraction, AutocompleteInteraction, MessageContextMenuCommandInteraction, UserContextMenuCommandInteraction } from 'discord.js';
+
+type AnyCommandProps = SlashCommandProps | AnyContextMenuCommandProps;
+type AnyContextMenuCommandProps = MessageContextMenuCommandProps | UserContextMenuCommandProps;
+interface ApplicationCommand {
+    filePath: string;
+    name: string;
+    data: any;
+    run: (props: AnyCommandProps) => any;
+    autocomplete?: (props: AutocompleteProps) => any;
+    category: string;
+}
+interface AutocompleteProps {
+    client: Client;
+    interaction: AutocompleteInteraction;
+    handler: CommandHandler;
+}
+interface ClientEvent {
+    event: string;
+    filePath: string;
+    run: (...args: any[]) => any;
+    once: boolean;
+}
+interface CommandHandlerProps {
+    client: Client;
+    commandsPath: string;
+}
+interface EventHandlerProps {
+    client: Client;
+    eventsPath: string;
+}
+interface MessageContextMenuCommandProps {
+    client: Client;
+    interaction: MessageContextMenuCommandInteraction;
+    handler: CommandHandler;
+}
+interface SlashCommandProps {
+    client: Client<true>;
+    interaction: ChatInputCommandInteraction;
+    handler: CommandHandler;
+}
+interface UserContextMenuCommandProps {
+    client: Client;
+    interaction: UserContextMenuCommandInteraction;
+    handler: CommandHandler;
+}
+
+declare class CommandHandler {
+    #private;
+    client: Client;
+    commandsPath: string;
+    commands: ApplicationCommand[];
+    constructor(options: CommandHandlerProps);
+}
+
+declare class EventHandler {
+    #private;
+    client: Client;
+    eventsPath: string;
+    events: ClientEvent[];
+    constructor({ client, eventsPath }: EventHandlerProps);
+}
+
+export { type AnyCommandProps, type AnyContextMenuCommandProps, type ApplicationCommand, type AutocompleteProps, type ClientEvent, CommandHandler, type CommandHandlerProps, EventHandler, type EventHandlerProps, type MessageContextMenuCommandProps, type SlashCommandProps, type UserContextMenuCommandProps };

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { Client, ChatInputCommandInteraction, AutocompleteInteraction, MessageContextMenuCommandInteraction, UserContextMenuCommandInteraction } from 'discord.js';
+
+type AnyCommandProps = SlashCommandProps | AnyContextMenuCommandProps;
+type AnyContextMenuCommandProps = MessageContextMenuCommandProps | UserContextMenuCommandProps;
+interface ApplicationCommand {
+    filePath: string;
+    name: string;
+    data: any;
+    run: (props: AnyCommandProps) => any;
+    autocomplete?: (props: AutocompleteProps) => any;
+    category: string;
+}
+interface AutocompleteProps {
+    client: Client;
+    interaction: AutocompleteInteraction;
+    handler: CommandHandler;
+}
+interface ClientEvent {
+    event: string;
+    filePath: string;
+    run: (...args: any[]) => any;
+    once: boolean;
+}
+interface CommandHandlerProps {
+    client: Client;
+    commandsPath: string;
+}
+interface EventHandlerProps {
+    client: Client;
+    eventsPath: string;
+}
+interface MessageContextMenuCommandProps {
+    client: Client;
+    interaction: MessageContextMenuCommandInteraction;
+    handler: CommandHandler;
+}
+interface SlashCommandProps {
+    client: Client<true>;
+    interaction: ChatInputCommandInteraction;
+    handler: CommandHandler;
+}
+interface UserContextMenuCommandProps {
+    client: Client;
+    interaction: UserContextMenuCommandInteraction;
+    handler: CommandHandler;
+}
+
+declare class CommandHandler {
+    #private;
+    client: Client;
+    commandsPath: string;
+    commands: ApplicationCommand[];
+    constructor(options: CommandHandlerProps);
+}
+
+declare class EventHandler {
+    #private;
+    client: Client;
+    eventsPath: string;
+    events: ClientEvent[];
+    constructor({ client, eventsPath }: EventHandlerProps);
+}
+
+export { type AnyCommandProps, type AnyContextMenuCommandProps, type ApplicationCommand, type AutocompleteProps, type ClientEvent, CommandHandler, type CommandHandlerProps, EventHandler, type EventHandlerProps, type MessageContextMenuCommandProps, type SlashCommandProps, type UserContextMenuCommandProps };

package/dist/index.js

@@ -0,0 +1,248 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CommandHandler: () => CommandHandler,
+  EventHandler: () => EventHandler
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/structures/CommandHandler.ts
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_url = __toESM(require("node:url"));
+var validExtensions = [".js", ".cjs", ".mjs", ".ts", ".cts", ".mts"];
+var CommandHandler = class {
+  static {
+    __name(this, "CommandHandler");
+  }
+  client;
+  commandsPath;
+  commands = [];
+  /**
+   * Instantiate a new CommandHandler
+   * @param options Handler options
+   */
+  constructor(options) {
+    this.client = options.client;
+    this.commandsPath = options.commandsPath;
+    this.client.once("clientReady", async () => {
+      await this.#loadCommands(this.commandsPath);
+      await this.#registerCommands();
+    });
+  }
+  /**
+   * Loads commands from the provided directory and parent directories
+   * Only selects commands ending in validExtensions
+   * Ignores files with names that start with "."
+   */
+  async #loadCommands(directory) {
+    const entries = import_node_fs.default.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const fullPath = import_node_path.default.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await this.#loadCommands(fullPath);
+        continue;
+      }
+      if (!validExtensions.includes(import_node_path.default.extname(entry.name))) {
+        continue;
+      }
+      const module2 = await import(import_node_url.default.pathToFileURL(fullPath).href);
+      if (!module2?.data || !module2?.run) {
+        continue;
+      }
+      const name = module2.data?.name ?? (typeof module2.data?.toJSON === "function" ? module2.data.toJSON().name : null);
+      if (!name) {
+        continue;
+      }
+      this.commands.push({
+        name,
+        filePath: fullPath,
+        data: module2.data,
+        run: module2.run,
+        autocomplete: module2.autocomplete,
+        category: import_node_path.default.dirname(import_node_path.default.relative(this.commandsPath, fullPath)).split(import_node_path.default.sep)[0] || "None"
+      });
+    }
+  }
+  /**
+   * Registers the loaded commands against Discord's API
+   * Then, listens to them via interactionCreate
+   */
+  async #registerCommands() {
+    if (!this.client.application) {
+      return;
+    }
+    const commandData = this.commands.map(
+      ({ data }) => typeof data.toJSON === "function" ? data.toJSON() : data
+    );
+    const { size } = await this.client.application.commands.set(commandData);
+    this.client.on("interactionCreate", async (interaction) => {
+      if (interaction.isChatInputCommand()) {
+        const command = this.commands.find(
+          ({ name }) => name === interaction.commandName
+        );
+        if (command?.run) {
+          try {
+            await command.run({
+              client: this.client,
+              interaction,
+              handler: this
+            });
+          } catch (error) {
+            const reply = {
+              flags: "Ephemeral",
+              content: "An unexpected error occurred, please try again later."
+            };
+            try {
+              if (interaction.replied || interaction.deferred) {
+                await interaction.followUp(reply);
+              } else {
+                await interaction.reply(reply);
+              }
+            } catch {
+            }
+          }
+        }
+      }
+      if (interaction.isAutocomplete()) {
+        const command = this.commands.find(
+          ({ name }) => name === interaction.commandName
+        );
+        if (command?.autocomplete) {
+          try {
+            await command.autocomplete({
+              client: this.client,
+              interaction,
+              handler: this
+            });
+          } catch {
+          }
+        }
+      }
+      if (interaction.isContextMenuCommand()) {
+        const command = this.commands.find(
+          ({ name }) => name === interaction.commandName
+        );
+        if (command?.run) {
+          try {
+            await command.run({
+              client: this.client,
+              interaction,
+              handler: this
+            });
+          } catch {
+            const reply = {
+              flags: "Ephemeral",
+              content: "An unexpected error occurred, please try again later."
+            };
+            try {
+              if (interaction.replied || interaction.deferred) {
+                await interaction.followUp(reply);
+              } else {
+                await interaction.reply(reply);
+              }
+            } catch {
+            }
+          }
+        }
+      }
+    });
+  }
+};
+
+// src/structures/EventHandler.ts
+var import_node_path2 = __toESM(require("node:path"));
+var import_node_url2 = __toESM(require("node:url"));
+var import_node_fs2 = __toESM(require("node:fs"));
+var validExtensions2 = [".js", ".cjs", ".mjs", ".ts", ".cts", ".mts"];
+var EventHandler = class {
+  static {
+    __name(this, "EventHandler");
+  }
+  client;
+  eventsPath;
+  events = [];
+  constructor({ client, eventsPath }) {
+    this.client = client;
+    this.eventsPath = eventsPath;
+    this.#loadEvents(eventsPath).then(() => {
+      this.#registerEvents();
+    });
+  }
+  async #loadEvents(directory, topLevelFolder) {
+    const entries = import_node_fs2.default.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const fullPath = import_node_path2.default.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await this.#loadEvents(fullPath, topLevelFolder ?? entry.name);
+        continue;
+      }
+      if (!validExtensions2.includes(import_node_path2.default.extname(entry.name))) {
+        continue;
+      }
+      const module2 = await import(import_node_url2.default.pathToFileURL(fullPath).href);
+      if (!module2?.default) {
+        continue;
+      }
+      this.events.push({
+        event: topLevelFolder,
+        filePath: fullPath,
+        run: module2.default,
+        once: Boolean(module2.once)
+      });
+    }
+  }
+  #registerEvents() {
+    for (const event of this.events) {
+      try {
+        if (event.once) {
+          this.client.once(event.event, (...args) => event.run(...args));
+        } else {
+          this.client.on(event.event, (...args) => event.run(...args));
+        }
+      } catch (error) {
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CommandHandler,
+  EventHandler
+});

package/dist/index.mjs

@@ -0,0 +1,212 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/structures/CommandHandler.ts
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+var validExtensions = [".js", ".cjs", ".mjs", ".ts", ".cts", ".mts"];
+var CommandHandler = class {
+  static {
+    __name(this, "CommandHandler");
+  }
+  client;
+  commandsPath;
+  commands = [];
+  /**
+   * Instantiate a new CommandHandler
+   * @param options Handler options
+   */
+  constructor(options) {
+    this.client = options.client;
+    this.commandsPath = options.commandsPath;
+    this.client.once("clientReady", async () => {
+      await this.#loadCommands(this.commandsPath);
+      await this.#registerCommands();
+    });
+  }
+  /**
+   * Loads commands from the provided directory and parent directories
+   * Only selects commands ending in validExtensions
+   * Ignores files with names that start with "."
+   */
+  async #loadCommands(directory) {
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const fullPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await this.#loadCommands(fullPath);
+        continue;
+      }
+      if (!validExtensions.includes(path.extname(entry.name))) {
+        continue;
+      }
+      const module = await import(url.pathToFileURL(fullPath).href);
+      if (!module?.data || !module?.run) {
+        continue;
+      }
+      const name = module.data?.name ?? (typeof module.data?.toJSON === "function" ? module.data.toJSON().name : null);
+      if (!name) {
+        continue;
+      }
+      this.commands.push({
+        name,
+        filePath: fullPath,
+        data: module.data,
+        run: module.run,
+        autocomplete: module.autocomplete,
+        category: path.dirname(path.relative(this.commandsPath, fullPath)).split(path.sep)[0] || "None"
+      });
+    }
+  }
+  /**
+   * Registers the loaded commands against Discord's API
+   * Then, listens to them via interactionCreate
+   */
+  async #registerCommands() {
+    if (!this.client.application) {
+      return;
+    }
+    const commandData = this.commands.map(
+      ({ data }) => typeof data.toJSON === "function" ? data.toJSON() : data
+    );
+    const { size } = await this.client.application.commands.set(commandData);
+    this.client.on("interactionCreate", async (interaction) => {
+      if (interaction.isChatInputCommand()) {
+        const command = this.commands.find(
+          ({ name }) => name === interaction.commandName
+        );
+        if (command?.run) {
+          try {
+            await command.run({
+              client: this.client,
+              interaction,
+              handler: this
+            });
+          } catch (error) {
+            const reply = {
+              flags: "Ephemeral",
+              content: "An unexpected error occurred, please try again later."
+            };
+            try {
+              if (interaction.replied || interaction.deferred) {
+                await interaction.followUp(reply);
+              } else {
+                await interaction.reply(reply);
+              }
+            } catch {
+            }
+          }
+        }
+      }
+      if (interaction.isAutocomplete()) {
+        const command = this.commands.find(
+          ({ name }) => name === interaction.commandName
+        );
+        if (command?.autocomplete) {
+          try {
+            await command.autocomplete({
+              client: this.client,
+              interaction,
+              handler: this
+            });
+          } catch {
+          }
+        }
+      }
+      if (interaction.isContextMenuCommand()) {
+        const command = this.commands.find(
+          ({ name }) => name === interaction.commandName
+        );
+        if (command?.run) {
+          try {
+            await command.run({
+              client: this.client,
+              interaction,
+              handler: this
+            });
+          } catch {
+            const reply = {
+              flags: "Ephemeral",
+              content: "An unexpected error occurred, please try again later."
+            };
+            try {
+              if (interaction.replied || interaction.deferred) {
+                await interaction.followUp(reply);
+              } else {
+                await interaction.reply(reply);
+              }
+            } catch {
+            }
+          }
+        }
+      }
+    });
+  }
+};
+
+// src/structures/EventHandler.ts
+import path2 from "node:path";
+import url2 from "node:url";
+import fs2 from "node:fs";
+var validExtensions2 = [".js", ".cjs", ".mjs", ".ts", ".cts", ".mts"];
+var EventHandler = class {
+  static {
+    __name(this, "EventHandler");
+  }
+  client;
+  eventsPath;
+  events = [];
+  constructor({ client, eventsPath }) {
+    this.client = client;
+    this.eventsPath = eventsPath;
+    this.#loadEvents(eventsPath).then(() => {
+      this.#registerEvents();
+    });
+  }
+  async #loadEvents(directory, topLevelFolder) {
+    const entries = fs2.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const fullPath = path2.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await this.#loadEvents(fullPath, topLevelFolder ?? entry.name);
+        continue;
+      }
+      if (!validExtensions2.includes(path2.extname(entry.name))) {
+        continue;
+      }
+      const module = await import(url2.pathToFileURL(fullPath).href);
+      if (!module?.default) {
+        continue;
+      }
+      this.events.push({
+        event: topLevelFolder,
+        filePath: fullPath,
+        run: module.default,
+        once: Boolean(module.once)
+      });
+    }
+  }
+  #registerEvents() {
+    for (const event of this.events) {
+      try {
+        if (event.once) {
+          this.client.once(event.event, (...args) => event.run(...args));
+        } else {
+          this.client.on(event.event, (...args) => event.run(...args));
+        }
+      } catch (error) {
+      }
+    }
+  }
+};
+export {
+  CommandHandler,
+  EventHandler
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "horizon.js",
+  "description": "Discord.js v14 command and event handler",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/e60m5ss/horizon.js"
+  },
+  "author": {
+    "name": "e60m5ss",
+    "url": "https://github.com/e60m5ss"
+  },
+  "keywords": [
+    "command-handler",
+    "commands",
+    "discord",
+    "discord-bot",
+    "discord.js",
+    "event-handler",
+    "events"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "prettier": {
+    "jsxSingleQuote": false,
+    "printWidth": 85,
+    "semi": true,
+    "singleQuote": false,
+    "tabWidth": 4,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "discord.js": "^14.25.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "format": "prettier ./src --write --ignore-path=.prettierignore",
+    "lint": "tsc --noEmit; prettier ./src --check --ignore-path=.prettierignore",
+    "prepublish": "tsup"
+  }
+}