buncord-hybrid-sharding 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,28 @@
+------------------------------------------------------------------------------------------
+| This following License accounts to the changes in Changes.md,                         | 
+| the unchanged code is the intellectual property of discord.js and their Contributors.  |
+| Check the attached License of Discord.js in the Repo                                  |
+------------------------------------------------------------------------------------------
+
+MIT License
+
+Copyright (c) 2026 Luigi Colantuono
+
+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,91 @@
+# ⚡ Buncord-Hybrid-Sharding
+
+The ultimate **Enterprise Bun-native** sharding manager for Discord bots. Built for performance, reliability, and scale.
+
+`buncord-hybrid-sharding` is a ground-up refactor of the hybrid sharding concept, optimized specifically for the Bun runtime. It eliminates all Node.js dependencies, leveraging `Bun.spawn` and native Bun IPC for ultra-fast, low-overhead clustering.
+
+## 🚀 Key Features
+
+- **🔋 Bun-Native Core**: Zero Node.js dependencies. Uses `Bun.spawn` and native IPC for maximum performance.
+- **🔄 Zero-Downtime Rolling Restarts**: Built-in `ReClusterManager` for updating your bot with zero service interruption.
+- **💓 Redis-Backed Heartbeats**: Distributed health monitoring using Redis. If a cluster hangs, it's detected and restarted automatically via TTL.
+- **📊 Integrated Dashboard API**: Built-in monitoring server (port 3001) using `Bun.serve` to track cluster health and trigger administrative actions.
+- **🚦 QueueManager Plugin**: Advanced control over cluster spawning to respect Discord's rate limits precisely.
+- **📉 Resource Efficiency**: Hybrid sharding (multiple shards per process) reduces memory overhead by 40-60%.
+
+---
+
+## 📦 Installation
+
+```bash
+bun add buncord-hybrid-sharding
+```
+
+## 🛠️ Quick Start
+
+### 1. The Manager (`cluster.js`)
+
+```js
+import { ClusterManager, ReClusterManager, HeartbeatManager, DashboardServer } from 'buncord-hybrid-sharding';
+
+const manager = new ClusterManager(`./bot.js`, {
+    totalShards: 'auto',
+    shardsPerClusters: 2,
+    mode: 'process', // Native Bun processes
+    token: 'YOUR_BOT_TOKEN',
+});
+
+// Extend with Enterprise features
+manager.extend(
+    new ReClusterManager(),
+    new HeartbeatManager({
+        redis: { host: 'localhost', port: 6379 },
+        interval: 10000,
+    }),
+    new DashboardServer({ port: 3001 })
+);
+
+manager.on('clusterCreate', (cluster) => console.log(`🚀 Launched Cluster ${cluster.id}`));
+manager.spawn();
+```
+
+### 2. The Client (`bot.js`)
+
+```js
+import { ClusterClient, getInfo } from 'buncord-hybrid-sharding';
+import { Client, GatewayIntentBits } from 'discord.js';
+
+const client = new Client({
+    shards: getInfo().SHARD_LIST,
+    shardCount: getInfo().TOTAL_SHARDS,
+    intents: [GatewayIntentBits.Guilds],
+});
+
+client.cluster = new ClusterClient(client);
+
+client.on('ready', () => {
+    client.cluster.triggerReady();
+    console.log(`✅ Cluster ${client.cluster.id} is ready!`);
+});
+
+client.login('YOUR_BOT_TOKEN');
+```
+
+---
+
+## 📈 Monitoring API
+
+The built-in `DashboardServer` provides a JSON API for monitoring and management:
+
+- `GET /stats`: Unified metrics across all clusters.
+- `POST /restart`: Trigger a rolling restart.
+- `POST /maintenance`: Toggle maintenance mode.
+
+---
+
+## 📝 License
+
+This project is licensed under the MIT License. See the [LICENSE](file:///LICENSE) file for details.
+Portions of this code are based on `discord.js` and `discord-hybrid-sharding`, copyright of their respective authors.
+
+Developed with ❤️ by [Luigi Colantuono](https://github.com/LuigiColantuono).

package/bun.lock

@@ -0,0 +1,88 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "buncord-hybrid-sharding",
+      "dependencies": {
+        "discord.js": "^14.25.1",
+        "redis": "^5.1.0",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@discordjs/builders": ["@discordjs/builders@1.13.1", "", { "dependencies": { "@discordjs/formatters": "^0.6.2", "@discordjs/util": "^1.2.0", "@sapphire/shapeshift": "^4.0.0", "discord-api-types": "^0.38.33", "fast-deep-equal": "^3.1.3", "ts-mixer": "^6.0.4", "tslib": "^2.6.3" } }, "sha512-cOU0UDHc3lp/5nKByDxkmRiNZBpdp0kx55aarbiAfakfKJHlxv/yFW1zmIqCAmwH5CRlrH9iMFKJMpvW4DPB+w=="],
+
+    "@discordjs/collection": ["@discordjs/collection@1.5.3", "", {}, "sha512-SVb428OMd3WO1paV3rm6tSjM4wC+Kecaa1EUGX7vc6/fddvw/6lg90z4QtCqm21zvVe92vMMDt9+DkIvjXImQQ=="],
+
+    "@discordjs/formatters": ["@discordjs/formatters@0.6.2", "", { "dependencies": { "discord-api-types": "^0.38.33" } }, "sha512-y4UPwWhH6vChKRkGdMB4odasUbHOUwy7KL+OVwF86PvT6QVOwElx+TiI1/6kcmcEe+g5YRXJFiXSXUdabqZOvQ=="],
+
+    "@discordjs/rest": ["@discordjs/rest@2.6.0", "", { "dependencies": { "@discordjs/collection": "^2.1.1", "@discordjs/util": "^1.1.1", "@sapphire/async-queue": "^1.5.3", "@sapphire/snowflake": "^3.5.3", "@vladfrangu/async_event_emitter": "^2.4.6", "discord-api-types": "^0.38.16", "magic-bytes.js": "^1.10.0", "tslib": "^2.6.3", "undici": "6.21.3" } }, "sha512-RDYrhmpB7mTvmCKcpj+pc5k7POKszS4E2O9TYc+U+Y4iaCP+r910QdO43qmpOja8LRr1RJ0b3U+CqVsnPqzf4w=="],
+
+    "@discordjs/util": ["@discordjs/util@1.2.0", "", { "dependencies": { "discord-api-types": "^0.38.33" } }, "sha512-3LKP7F2+atl9vJFhaBjn4nOaSWahZ/yWjOvA4e5pnXkt2qyXRCHLxoBQy81GFtLGCq7K9lPm9R517M1U+/90Qg=="],
+
+    "@discordjs/ws": ["@discordjs/ws@1.2.3", "", { "dependencies": { "@discordjs/collection": "^2.1.0", "@discordjs/rest": "^2.5.1", "@discordjs/util": "^1.1.0", "@sapphire/async-queue": "^1.5.2", "@types/ws": "^8.5.10", "@vladfrangu/async_event_emitter": "^2.2.4", "discord-api-types": "^0.38.1", "tslib": "^2.6.2", "ws": "^8.17.0" } }, "sha512-wPlQDxEmlDg5IxhJPuxXr3Vy9AjYq5xCvFWGJyD7w7Np8ZGu+Mc+97LCoEc/+AYCo2IDpKioiH0/c/mj5ZR9Uw=="],
+
+    "@redis/bloom": ["@redis/bloom@5.10.0", "", { "peerDependencies": { "@redis/client": "^5.10.0" } }, "sha512-doIF37ob+l47n0rkpRNgU8n4iacBlKM9xLiP1LtTZTvz8TloJB8qx/MgvhMhKdYG+CvCY2aPBnN2706izFn/4A=="],
+
+    "@redis/client": ["@redis/client@5.10.0", "", { "dependencies": { "cluster-key-slot": "1.1.2" } }, "sha512-JXmM4XCoso6C75Mr3lhKA3eNxSzkYi3nCzxDIKY+YOszYsJjuKbFgVtguVPbLMOttN4iu2fXoc2BGhdnYhIOxA=="],
+
+    "@redis/json": ["@redis/json@5.10.0", "", { "peerDependencies": { "@redis/client": "^5.10.0" } }, "sha512-B2G8XlOmTPUuZtD44EMGbtoepQG34RCDXLZbjrtON1Djet0t5Ri7/YPXvL9aomXqP8lLTreaprtyLKF4tmXEEA=="],
+
+    "@redis/search": ["@redis/search@5.10.0", "", { "peerDependencies": { "@redis/client": "^5.10.0" } }, "sha512-3SVcPswoSfp2HnmWbAGUzlbUPn7fOohVu2weUQ0S+EMiQi8jwjL+aN2p6V3TI65eNfVsJ8vyPvqWklm6H6esmg=="],
+
+    "@redis/time-series": ["@redis/time-series@5.10.0", "", { "peerDependencies": { "@redis/client": "^5.10.0" } }, "sha512-cPkpddXH5kc/SdRhF0YG0qtjL+noqFT0AcHbQ6axhsPsO7iqPi1cjxgdkE9TNeKiBUUdCaU1DbqkR/LzbzPBhg=="],
+
+    "@sapphire/async-queue": ["@sapphire/async-queue@1.5.5", "", {}, "sha512-cvGzxbba6sav2zZkH8GPf2oGk9yYoD5qrNWdu9fRehifgnFZJMV+nuy2nON2roRO4yQQ+v7MK/Pktl/HgfsUXg=="],
+
+    "@sapphire/shapeshift": ["@sapphire/shapeshift@4.0.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "lodash": "^4.17.21" } }, "sha512-d9dUmWVA7MMiKobL3VpLF8P2aeanRTu6ypG2OIaEv/ZHH/SUQ2iHOVyi5wAPjQ+HmnMuL0whK9ez8I/raWbtIg=="],
+
+    "@sapphire/snowflake": ["@sapphire/snowflake@3.5.3", "", {}, "sha512-jjmJywLAFoWeBi1W7994zZyiNWPIiqRRNAmSERxyg93xRGzNYvGjlZ0gR6x0F4gPRi2+0O6S71kOZYyr3cxaIQ=="],
+
+    "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
+
+    "@types/node": ["@types/node@25.0.10", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-zWW5KPngR/yvakJgGOmZ5vTBemDoSqF3AcV/LrO5u5wTWyEAVVh+IT39G4gtyAkh3CtTZs8aX/yRM82OfzHJRg=="],
+
+    "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
+
+    "@vladfrangu/async_event_emitter": ["@vladfrangu/async_event_emitter@2.4.7", "", {}, "sha512-Xfe6rpCTxSxfbswi/W/Pz7zp1WWSNn4A0eW4mLkQUewCrXXtMj31lCg+iQyTkh/CkusZSq9eDflu7tjEDXUY6g=="],
+
+    "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
+
+    "cluster-key-slot": ["cluster-key-slot@1.1.2", "", {}, "sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA=="],
+
+    "discord-api-types": ["discord-api-types@0.38.37", "", {}, "sha512-Cv47jzY1jkGkh5sv0bfHYqGgKOWO1peOrGMkDFM4UmaGMOTgOW8QSexhvixa9sVOiz8MnVOBryWYyw/CEVhj7w=="],
+
+    "discord.js": ["discord.js@14.25.1", "", { "dependencies": { "@discordjs/builders": "^1.13.0", "@discordjs/collection": "1.5.3", "@discordjs/formatters": "^0.6.2", "@discordjs/rest": "^2.6.0", "@discordjs/util": "^1.2.0", "@discordjs/ws": "^1.2.3", "@sapphire/snowflake": "3.5.3", "discord-api-types": "^0.38.33", "fast-deep-equal": "3.1.3", "lodash.snakecase": "4.1.1", "magic-bytes.js": "^1.10.0", "tslib": "^2.6.3", "undici": "6.21.3" } }, "sha512-2l0gsPOLPs5t6GFZfQZKnL1OJNYFcuC/ETWsW4VtKVD/tg4ICa9x+jb9bkPffkMdRpRpuUaO/fKkHCBeiCKh8g=="],
+
+    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
+
+    "lodash": ["lodash@4.17.23", "", {}, "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w=="],
+
+    "lodash.snakecase": ["lodash.snakecase@4.1.1", "", {}, "sha512-QZ1d4xoBHYUeuouhEq3lk3Uq7ldgyFXGBhg04+oRLnIz8o9T65Eh+8YdroUwn846zchkA9yDsDl5CVVaV2nqYw=="],
+
+    "magic-bytes.js": ["magic-bytes.js@1.13.0", "", {}, "sha512-afO2mnxW7GDTXMm5/AoN1WuOcdoKhtgXjIvHmobqTD1grNplhGdv3PFOyjCVmrnOZBIT/gD/koDKpYG+0mvHcg=="],
+
+    "redis": ["redis@5.10.0", "", { "dependencies": { "@redis/bloom": "5.10.0", "@redis/client": "5.10.0", "@redis/json": "5.10.0", "@redis/search": "5.10.0", "@redis/time-series": "5.10.0" } }, "sha512-0/Y+7IEiTgVGPrLFKy8oAEArSyEJkU0zvgV5xyi9NzNQ+SLZmyFbUsWIbgPcd4UdUh00opXGKlXJwMmsis5Byw=="],
+
+    "ts-mixer": ["ts-mixer@6.0.4", "", {}, "sha512-ufKpbmrugz5Aou4wcr5Wc1UUFWOLhq+Fm6qa6P0w0K5Qw2yhaUoiWszhCVuNQyNwrlGiscHOmqYoAox1PtvgjA=="],
+
+    "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici": ["undici@6.21.3", "", {}, "sha512-gBLkYIlEnSp8pFbT64yFgGE6UIB9tAkhukC23PmMDCe5Nd+cRqKxSjw5y54MK2AZMgZfJWMaNE4nYUHgi1XEOw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
+    "ws": ["ws@8.19.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg=="],
+
+    "@discordjs/rest/@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
+
+    "@discordjs/ws/@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "buncord-hybrid-sharding",
+    "version": "1.0.0",
+    "description": "Enterprise Bun-native sharding manager for Discord bots, featuring Redis heartbeats, rolling restarts, and integrated monitoring.",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "type": "module",
+    "scripts": {
+        "test": "bun test",
+        "format": "bun format"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/LuigiColantuono/buncord-hybrid-sharding.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "discord",
+        "bun",
+        "sharding",
+        "clustering",
+        "hybrid-sharding",
+        "zero-downtime",
+        "redis"
+    ],
+    "author": "Luigi Colantuono",
+    "license": "MIT",
+    "dependencies": {
+        "discord.js": "^14.25.1",
+        "redis": "^5.1.0"
+    },
+    "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.9.3"
+    }
+}
+

package/src/Core/Cluster.ts

@@ -0,0 +1,414 @@
+import EventEmitter from "node:events";
+import path from "node:path";
+
+import { Child } from "../Structures/Child.js";
+import { ClusterHandler } from "../Structures/IPCHandler.js";
+import { BaseMessage, IPCMessage, RawMessage } from "../Structures/IPCMessage.js";
+import { ClusterEvents, ClusterKillOptions, DjsDiscordClient, messageType } from "../types/shared.js"; // eslint-disable-line @typescript-eslint/no-unused-vars
+import { delayFor, generateNonce } from "../Util/Util.js";
+import { ClusterManager } from "./ClusterManager.js";
+
+/**
+ * A self-contained cluster created by the {@link ClusterManager}. Each one has a {@link DjsDiscordClient} that contains
+ * an instance of the bot and its {@link DjsDiscordClient}. When its child process exits for any reason, the cluster will
+ * spawn a new one to replace it as necessary.
+ * @augments EventEmitter
+ */
+export class Cluster extends EventEmitter {
+    /**
+     * Manager that created the cluster
+     */
+    manager: ClusterManager;
+
+    /**
+     * ID of the cluster in the manager
+     */
+    id: number;
+
+    /**
+     * Arguments for the shard's process
+     */
+    args: string[];
+
+    /**
+     * Arguments for the shard's process executable
+     */
+    execArgv: string[];
+
+    /**
+     * Internal Shards which will get spawned in the cluster
+     */
+    shardList: number[];
+
+    /**
+     * the amount of real shards
+     */
+    totalShards: number;
+
+    /**
+     * Environment variables for the cluster's process
+     */
+    env: Record<string, any> & {
+        SHARD_LIST: number[];
+        TOTAL_SHARDS: number;
+        CLUSTER_MANAGER: boolean;
+        CLUSTER: number;
+        CLUSTER_COUNT: number;
+        DISCORD_TOKEN: string;
+    };
+
+    /**
+     * Process of the cluster
+     */
+    thread: null | Child;
+
+    restarts: {
+        current: number;
+        max: number;
+        interval: number;
+        reset?: any;
+        resetRestarts: () => void;
+        cleanup: () => void;
+        append: () => void;
+    };
+
+    messageHandler: any;
+
+    /**
+     * Whether the cluster's {@link DjsDiscordClient} is ready
+     */
+    ready: boolean;
+
+    /**
+     * @param manager Manager that is creating this cluster
+     * @param id ID of this cluster
+     * @param shardList
+     * @param totalShards
+     */
+    constructor(manager: ClusterManager, id: number, shardList: number[], totalShards: number) {
+        super();
+
+        this.manager = manager;
+
+        this.id = id;
+
+        this.args = manager.shardArgs || [];
+
+        this.execArgv = manager.execArgv;
+
+        this.shardList = shardList;
+
+        this.totalShards = totalShards;
+
+        this.env = Object.assign({}, process.env, {
+            SHARD_LIST: this.shardList,
+            TOTAL_SHARDS: this.totalShards,
+            CLUSTER_MANAGER: true,
+            CLUSTER: this.id,
+            CLUSTER_COUNT: this.manager.totalClusters,
+            DISCORD_TOKEN: this.manager.token as string,
+        });
+
+        this.ready = false;
+
+        this.thread = null;
+
+        this.restarts = {
+            current: this.manager.restarts.current ?? 0,
+            max: this.manager.restarts.max,
+            interval: this.manager.restarts.interval,
+            reset: undefined,
+            resetRestarts: () => {
+                this.restarts.reset = setInterval(() => {
+                    this.restarts.current = 0;
+                }, this.manager.restarts.interval);
+            },
+            cleanup: () => {
+                if (this.restarts.reset) clearInterval(this.restarts.reset);
+            },
+            append: () => {
+                this.restarts.current++;
+            },
+        };
+    }
+    /**
+     * Spawns a child process for the cluster.
+     * <warn>You should not need to call this manually.</warn>
+     * @param spawnTimeout The amount in milliseconds to wait until the {@link DjsDiscordClient} has become ready
+     * before resolving. (-1 or Infinity for no wait)
+     */
+    public async spawn(spawnTimeout = -1) {
+        if (this.thread) throw new Error('CLUSTER ALREADY SPAWNED | ClusterId: ' + this.id);
+        this.thread = new Child(path.resolve(this.manager.file), {
+            ...this.manager.clusterOptions,
+            env: this.env as any,
+            /** Construct args with hooks, to provide parameters with in the context of a cluster */
+            args: this.manager.hooks.constructClusterArgs(this, this.args),
+            clusterData: { ...this.env, ...this.manager.clusterData },
+        });
+        this.messageHandler = new ClusterHandler(this.manager, this, this.thread);
+
+        this.thread
+            .spawn()
+            .on('message', this._handleMessage.bind(this))
+            .on('exit', this._handleExit.bind(this))
+            .on('error', this._handleError.bind(this));
+
+        /**
+         * Emitted upon the creation of the cluster's child process.
+         * @event Cluster#spawn
+         * @param {Child} process Child process that was created
+         */
+        this.emit('spawn', this.thread.process);
+
+        await new Promise((resolve, reject) => {
+            let spawnTimeoutTimer: any | undefined = undefined;
+
+            const cleanup = (death = false) => {
+                clearTimeout(spawnTimeoutTimer);
+
+                // Remove listeners if cluster died to prevent event emitter leaks
+                if (death) {
+                    this.off('ready', onReady);
+                    this.off('death', onDeath);
+                }
+            };
+
+            const onReady = () => {
+                this.manager.emit('clusterReady', this);
+                this.restarts.cleanup();
+                this.restarts.resetRestarts();
+                cleanup();
+                resolve('Cluster is ready');
+            };
+
+            const onDeath = () => {
+                cleanup(true);
+                reject(new Error('CLUSTERING_READY_DIED | ClusterId: ' + this.id));
+            };
+
+            const onTimeout = () => {
+                cleanup();
+                reject(new Error('CLUSTERING_READY_TIMEOUT | ClusterId: ' + this.id));
+            };
+
+            // If there is a spawn timeout wait and error if cluster does not get ready
+            if (spawnTimeout !== -1 && spawnTimeout !== Infinity) {
+                spawnTimeoutTimer = setTimeout(onTimeout, spawnTimeout);
+            } else {
+                // No timeout, next cluster will be spawned, without waiting for ready
+                resolve('Skipping ready check');
+            }
+
+            this.once('ready', onReady);
+            this.once('death', onDeath);
+        });
+        return this.thread.process;
+    }
+    /**
+     * Immediately kills the clusters process and does not restart it.
+     * @param options Some Options for managing the Kill
+     * @param options.force Whether the Cluster should be force kill and be ever respawned...
+     */
+    public kill(options: ClusterKillOptions) {
+        this.thread?.kill();
+        if (this.thread) {
+            this.thread = null;
+        }
+        // Heartbeat will automatically detect death via Redis TTL Key expiration
+        this.restarts.cleanup();
+        this.manager._debug('[KILL] Cluster killed with reason: ' + (options?.reason || 'not given'), this.id);
+    }
+    /**
+     * Kills and restarts the cluster's process.
+     * @param options Options for respawning the cluster
+     */
+    public async respawn({ delay = 5500, timeout = -1 } = this.manager.spawnOptions) {
+        if (this.thread) this.kill({ force: true });
+        if (delay > 0) await delayFor(delay);
+        // Heartbeat will automatically detect death via Redis TTL Key expiration
+        return this.spawn(timeout);
+    }
+    /**
+     * Sends a message to the cluster's process.
+     * @param  message Message to send to the cluster
+     */
+    public send(message: RawMessage) {
+        if (typeof message === 'object') this.thread?.send(new BaseMessage(message).toJSON());
+        else return this.thread?.send(message);
+    }
+
+    /**
+     * Sends a Request to the ClusterClient and returns the reply
+     * @param message Message, which should be sent as request
+     * @returns Reply of the Message
+     * @example
+     * client.cluster.request({content: 'hello'})
+     *   .then(result => console.log(result)) //hi
+     *   .catch(console.error);
+     * @see {@link IPCMessage#reply}
+     */
+    public request(message: RawMessage) {
+        message._type = messageType.CUSTOM_REQUEST;
+        this.send(message);
+        return this.manager.promise.create(message, message.options);
+    }
+    /**
+     * Evaluates a script or function on the cluster, in the context of the {@link DjsDiscordClient}.
+     * @param script JavaScript to run on the cluster
+     * @param context
+     * @param timeout
+     * @returns Result of the script execution
+     */
+    public async eval(script: string, context: any, timeout: number) {
+        // Stringify the script if it's a Function
+        const _eval = typeof script === 'function' ? `(${script})(this, ${JSON.stringify(context)})` : script;
+
+        // cluster is dead (maybe respawning), don't cache anything and error immediately
+        if (!this.thread) return Promise.reject(new Error('CLUSTERING_NO_CHILD_EXISTS | ClusterId: ' + this.id));
+        const nonce = generateNonce();
+        const message = { nonce, _eval, options: { timeout }, _type: messageType.CLIENT_EVAL_REQUEST };
+        await this.send(message);
+        return await this.manager.promise.create(message, message.options);
+    }
+
+    /**
+     * @param reason If maintenance should be enabled with a given reason or disabled when nonce provided
+     */
+    public triggerMaintenance(reason?: string) {
+        const _type = reason ? messageType.CLIENT_MAINTENANCE_ENABLE : messageType.CLIENT_MAINTENANCE_DISABLE;
+        return this.send({ _type, maintenance: reason });
+    }
+
+    /**
+     * Handles a message received from the child process.
+     * @param message Message received
+     * @private
+     */
+    private _handleMessage(message: any) {
+        if (!message) return;
+        const emit = this.messageHandler.handleMessage(message);
+        if (!emit) return;
+
+        let emitMessage;
+        if (typeof message === 'object') {
+            emitMessage = new IPCMessage(this, message);
+            if (emitMessage._type === messageType.CUSTOM_REQUEST) this.manager.emit('clientRequest', emitMessage);
+        } else emitMessage = message;
+        /**
+         * Emitted upon receiving a message from the child process.
+         * @event Shard#message
+         * @param {*|IPCMessage} message Message that was received
+         */
+        this.emit('message', emitMessage);
+    }
+
+    /**
+     * Handles the cluster's process exiting.
+     * @private
+     * @param {Number} exitCode
+     */
+    private _handleExit(exitCode: number) { // eslint-disable-line @typescript-eslint/no-unused-vars
+        /**
+         * Emitted upon the cluster's child process exiting.
+         * @event Cluster#death
+         * @param {Child} process Child process that exited
+         */
+
+        const respawn = this.manager.respawn;
+
+        // Cleanup functions
+        this.manager.heartbeat?.stop(); // This is just a placeholder if needed, but actually the manager-side heartbeat stops automatically or doesn't need per-cluster stop anymore.
+        this.restarts.cleanup();
+
+        this.emit('death', this, this.thread?.process);
+
+        this.manager._debug(
+            '[DEATH] Cluster died, attempting respawn | Restarts Left: ' + (this.restarts.max - this.restarts.current),
+            this.id,
+        );
+
+        this.ready = false;
+
+        this.thread = null;
+
+        if (!respawn) return;
+
+        if (this.restarts.current >= this.restarts.max)
+            this.manager._debug(
+                '[ATTEMPTED_RESPAWN] Attempted Respawn Declined | Max Restarts have been exceeded',
+                this.id,
+            );
+        if (respawn && this.restarts.current < this.restarts.max) this.spawn().catch(err => this.emit('error', err));
+
+        this.restarts.append();
+    }
+
+    /**
+     * Handles the cluster's process error.
+     * @param  error the error, which occurred on the child process
+     * @private
+     */
+    private _handleError(error: Error) {
+        /**
+         * Emitted upon the cluster's child process error.
+         * @event Cluster#error
+         * @param {Child} process Child process, where error occurred
+         */
+        this.manager.emit('error', error);
+    }
+}
+
+// Credits for EventEmitter typings: https://github.com/discordjs/discord.js/blob/main/packages/rest/src/lib/RequestManager.ts#L159 | See attached license
+export interface Cluster {
+    emit: (<K extends keyof ClusterEvents>(event: K, ...args: ClusterEvents[K]) => boolean) &
+        (<S extends string | symbol>(event: Exclude<S, keyof ClusterEvents>, ...args: any[]) => boolean);
+
+    off: (<K extends keyof ClusterEvents>(event: K, listener: (...args: ClusterEvents[K]) => void) => this) &
+        (<S extends string | symbol>(
+            event: Exclude<S, keyof ClusterEvents>,
+            listener: (...args: any[]) => void,
+        ) => this);
+
+    on: (<K extends keyof ClusterEvents>(event: K, listener: (...args: ClusterEvents[K]) => void) => this) &
+        (<S extends string | symbol>(
+            event: Exclude<S, keyof ClusterEvents>,
+            listener: (...args: any[]) => void,
+        ) => this);
+
+    once: (<K extends keyof ClusterEvents>(event: K, listener: (...args: ClusterEvents[K]) => void) => this) &
+        (<S extends string | symbol>(
+            event: Exclude<S, keyof ClusterEvents>,
+            listener: (...args: any[]) => void,
+        ) => this);
+
+    removeAllListeners: (<K extends keyof ClusterEvents>(event?: K) => this) &
+        (<S extends string | symbol>(event?: Exclude<S, keyof ClusterEvents>) => this);
+}
+
+// Credits for EventEmitter typings: https://github.com/discordjs/discord.js/blob/main/packages/rest/src/lib/RequestManager.ts#L159 | See attached license
+export interface Cluster {
+    emit: (<K extends keyof ClusterEvents>(event: K, ...args: ClusterEvents[K]) => boolean) &
+        (<S extends string | symbol>(event: Exclude<S, keyof ClusterEvents>, ...args: any[]) => boolean);
+
+    off: (<K extends keyof ClusterEvents>(event: K, listener: (...args: ClusterEvents[K]) => void) => this) &
+        (<S extends string | symbol>(
+            event: Exclude<S, keyof ClusterEvents>,
+            listener: (...args: any[]) => void,
+        ) => this);
+
+    on: (<K extends keyof ClusterEvents>(event: K, listener: (...args: ClusterEvents[K]) => void) => this) &
+        (<S extends string | symbol>(
+            event: Exclude<S, keyof ClusterEvents>,
+            listener: (...args: any[]) => void,
+        ) => this);
+
+    once: (<K extends keyof ClusterEvents>(event: K, listener: (...args: ClusterEvents[K]) => void) => this) &
+        (<S extends string | symbol>(
+            event: Exclude<S, keyof ClusterEvents>,
+            listener: (...args: any[]) => void,
+        ) => this);
+
+    removeAllListeners: (<K extends keyof ClusterEvents>(event?: K) => this) &
+        (<S extends string | symbol>(event?: Exclude<S, keyof ClusterEvents>) => this);
+}