lunibee 0.3.0 → 0.3.1

package/dist/sharding/index.d.ts

@@ -1,12 +1,23 @@
 import { type GatewayBotInfo } from "./gateway-bot.js";
 import { Gateway } from "@lunibee/ws";
-export { fetchGatewayBot, type GatewayBotInfo } from "./gateway-bot.js";
+import { type ClusterContext } from "./context.js";
+import type { ShardHealth, WorkerReport } from "./health.js";
+import { ClusterWorker, type IdentifyGate } from "./worker.js";
+export { MAX_GUILDS_PER_SHARD, fetchGatewayBot, fetchGuildCount, shardsForGuilds, type GatewayBotInfo, } from "./gateway-bot.js";
 export { ShardBus } from "./bus.js";
 export { BroadcastChannelTransport, IpcTransport, type IpcEndpoint, type ShardBusTransport, } from "./transport.js";
 export { ShardSupervisor, type SupervisorOptions } from "./supervisor.js";
 export type { ShardBusErrorHandler, ShardBusOptions, ShardMessage, ShardMessageHandler, ShardReply, } from "./bus.js";
 export { ClusterManager } from "./cluster.js";
-export type { ClusterManagerOptions, ClusterInfo } from "./cluster.js";
+export type { ClusterManagerOptions, ClusterManagerEvents, ClusterInfo, BroadcastResult, RequestOptions, } from "./cluster.js";
+export { allocateShards, assertCompleteAllocation, isClusterWorker, readClusterContext, validateShardIds, type ClusterContext, } from "./context.js";
+export { ClusterWorker, type IdentifyGate } from "./worker.js";
+export { ClusterHost, type ClusterHostEvents, type ClusterHostOptions, } from "./host.js";
+export type { HostStatus, RemoteOptions } from "./remote.js";
+export { RemoteClose, REMOTE_PROTOCOL_VERSION } from "./remote-protocol.js";
+export { IdentifyCoordinator, IDENTIFY_INTERVAL, type IdentifyBudget, type IdentifyCoordinatorOptions, } from "./identify.js";
+export { RequestTracker } from "./requests.js";
+export type { ClusterHealth, ClusterManagerHealth, ClusterState, ShardHealth, ShardStatus, WorkerMetrics, WorkerReport, } from "./health.js";
 /** Configuration for a sharded Gateway client. */
 export interface ShardManagerOptions {
     /** Bot token. */
@@ -15,6 +26,16 @@ export interface ShardManagerOptions {
     intents: ConstructorParameters<typeof Gateway>[0]["intents"];
     /** Number of shards. Use `"auto"` to request Discord's recommended count. */
     shardCount?: number | "auto";
+    /**
+     * With `shardCount: "auto"`, size the deployment by guilds instead of
+     * Discord's recommendation: `ceil(guilds / guildsPerShard)` shards, at
+     * least one. 1 to 2500 (Discord's limit); Discord recommends about 1000.
+     * Guilds are assigned to shards by their ID, so this sets the average,
+     * not an exact split.
+     */
+    guildsPerShard?: number;
+    /** The bot's guild count for `guildsPerShard`, instead of asking Discord for it. */
+    guildCount?: number;
     /** Gateway reconnect behavior. */
     reconnect?: boolean;
     /**
@@ -35,14 +56,25 @@ export interface ShardManagerOptions {
     autoScaleInterval?: number;
     /** Optional handler invoked when a background auto-scale check fails. Receives the thrown error. */
     onAutoScaleError?: (error: unknown) => void;
-}
-/** Health snapshot for one shard. */
-export interface ShardHealth {
-    id: number;
-    /** Gateway connection state. */
-    state: Gateway["state"];
-    /** Last heartbeat round-trip in ms, or -1 before the first ACK. */
-    ping: number;
+    /**
+     * The shards this manager runs, out of `shardCount`. Defaults to all of
+     * them, or to the cluster's own list inside a worker forked by
+     * `ClusterManager`. Must be unique integers in `[0, shardCount)`.
+     */
+    shardIds?: number[];
+    /**
+     * The worker contract. Read from the environment inside a worker forked by
+     * `ClusterManager`; pass `false` to ignore it, or a context to override it.
+     */
+    cluster?: ClusterContext | false;
+    /**
+     * Where to get IDENTIFY slots. Inside a coordinated cluster this is the
+     * parent, so the limit holds across all clusters. Pass `false` to pace
+     * locally with `spawnDelay` instead.
+     */
+    identify?: IdentifyGate | false;
+    /** The worker to report to. Defaults to this process's `ClusterWorker` inside a cluster. */
+    worker?: ClusterWorker | false;
 }
 /** What `ShardManager` emits about its shards. */
 export interface ShardManagerEvents {
@@ -57,6 +89,8 @@ export interface ShardManagerEvents {
     shardResume: [shardId: number];
     /** A shard reported an error. */
     shardError: [shardId: number, error: Error];
+    /** Every shard this manager owns is ready. Emitted again after a shard drops and recovers. */
+    ready: [];
     /** A shard reconnected too often too fast and is backing off (see `Gateway` `unstable`). */
     shardUnstable: [
         shardId: number,
@@ -80,8 +114,10 @@ export declare class ShardManager {
     static readonly IDENTIFY_INTERVAL = 5000;
     /** Active Gateway shards indexed by shard identifier. */
     readonly shards: Map<number, Gateway>;
-    /** Number of shards managed by this instance after initialization. */
+    /** Total shards in the deployment once initialized, 0 before and after `destroy()`. */
     get shardCount(): number;
+    /** IDs of the shards this manager owns. */
+    get shardIds(): number[];
     /** Creates a shard manager. @param options Sharding configuration. @throws {TypeError} If token or intents are invalid. @throws {RangeError} If shard count is invalid. */
     constructor(options: ShardManagerOptions);
     /** Retrieves Discord's recommended shard count. @returns Recommended shard count. @throws {Error} If discovery fails or returns invalid data. */
@@ -90,6 +126,12 @@ export declare class ShardManager {
     fetchGatewayInfo(): Promise<GatewayBotInfo>;
     /** Connects all shards sequentially. A destroyed manager is reinitialized before connecting. @returns A promise fulfilled after all shards connect. @throws {Error} If a shard fails to connect. */
     connect(): Promise<void>;
+    /**
+     * Takes over more shards of the same deployment (recovery after another
+     * cluster gave up) and connects them through the same IDENTIFY path.
+     * @throws {RangeError} If an ID is invalid, already owned, or the manager is not initialized.
+     */
+    addShards(shardIds: readonly number[]): Promise<void>;
     /** Checks if the recommended shard count has changed and reconnects if so. */
     checkAutoScale(): Promise<void>;
     /** Forces a reshard to a new shard count, replacing all active shards. @param count New shard count. */
@@ -109,8 +151,10 @@ export declare class ShardManager {
     }): boolean;
     /** Gets a shard by ID. @param id Shard identifier. @returns Gateway instance or undefined. */
     get(id: number): Gateway | undefined;
-    /** Returns each shard's connection state and heartbeat latency. */
+    /** Returns each shard's connection state, lifecycle status and heartbeat latency. */
     health(): ShardHealth[];
+    /** A health report for the parent: shard health and, on request, process metrics. */
+    report(metrics?: boolean): WorkerReport;
     /** Returns information for all managed shards. @returns Shard information snapshots. */
     values(): ShardInfo[];
 }