@wolfstar/plugin-sharder 0.0.0

package/dist/esm/index.d.ts

@@ -0,0 +1,2052 @@
+import { Err, Ok, Result, Result as Result$1 } from "@sapphire/result";
+import { EventEmitter } from "node:events";
+import { WorkerOptions } from "node:worker_threads";
+import { ZlibOptions } from "node:zlib";
+import { Worker as Worker$1 } from "node:cluster";
+import { ChildProcess } from "node:child_process";
+import { ConnectionOptions, TlsOptions } from "node:tls";
+//#region src/ShardPing.d.ts
+/**
+ * The options of the manager's pings.
+ */
+export interface ShardPingOptions {
+  /**
+   * How often the manager pings each ready shard, in milliseconds; `-1` or `Infinity` disables the pings.
+   *
+   * @default 45_000
+   */
+  interval?: number;
+  /**
+   * How long a ready shard may go without answering a ping, in milliseconds, before it is deemed unresponsive:
+   * emitted as `shardUnresponsive`, or restarted when nothing listens to it.
+   *
+   * @default 60_000
+   */
+  timeout?: number;
+  /**
+   * Whether the next ping is sent `interval` after the last answer, rather than after the last ping.
+   *
+   * @default false
+   */
+  delaySinceReceived?: boolean;
+}
+/**
+ * Pings a shard, measures its latency, and notices when it stops answering.
+ */
+export declare class ShardPing {
+  #private;
+  /**
+   * When the last ping was sent, `-1` before the first one.
+   */
+  lastSentTimestamp: number;
+  /**
+   * When the last answer came, `-1` before the first one.
+   */
+  lastReceivedTimestamp: number;
+  /**
+   * The round trip of the last ping, in milliseconds; `-1` before the first answer.
+   */
+  latency: number;
+  readonly interval: number;
+  readonly timeout: number;
+  readonly delaySinceReceived: boolean;
+  /**
+   * @internal
+   */
+  constructor(options: ShardPingOptions, send: (sentAt: number) => Promise<void>, onTimeout: () => void);
+  /**
+   * Whether the pings are running.
+   */
+  get running(): boolean;
+  /**
+   * Whether the last ping was answered.
+   */
+  get hasReceivedResponse(): boolean;
+  get lastSentAt(): Date | null;
+  get lastReceivedAt(): Date | null;
+  /**
+   * When the next ping is due, or `null` when the pings are not running.
+   */
+  get nextPingTimestamp(): number | null;
+  /**
+   * @internal
+   */
+  start(): void;
+  /**
+   * @internal
+   */
+  stop(): void;
+  /**
+   * @internal
+   */
+  receive(sentAt: number): void;
+  /**
+   * Whether the manager pings at all.
+   */
+  get enabled(): boolean;
+}
+//#endregion
+//#region src/messages/MessageHandler.d.ts
+/**
+ * The data a channel carries between the manager and a shard, once serialized and transformed.
+ */
+export type ChannelData = string | Uint8Array;
+/**
+ * Turns the packets exchanged by the manager and its shards into data a channel carries, and back.
+ *
+ * @remarks
+ * The manager tells its shards the name of its handler, and {@link ShardClient} builds the same one from the registry
+ * (see {@link registerMessageHandler}): a custom handler must be registered in the shards too.
+ */
+export interface MessageHandler {
+  /**
+   * The name of the handler in the registry.
+   */
+  readonly name: string;
+  serialize(packet: unknown): unknown;
+  deserialize(data: unknown): unknown;
+}
+/**
+ * Serializes packets as JSON: every body must be JSON-serializable. The default.
+ */
+export declare class JsonMessageHandler implements MessageHandler {
+  readonly name = "json";
+  serialize(packet: unknown): string;
+  deserialize(data: unknown): unknown;
+}
+/**
+ * Serializes packets with `node:v8`, which keeps `Map`s, `Set`s, `Date`s, `BigInt`s, typed arrays, and circular
+ * references.
+ */
+export declare class V8MessageHandler implements MessageHandler {
+  readonly name = "v8";
+  serialize(packet: unknown): Uint8Array;
+  deserialize(data: unknown): unknown;
+}
+/**
+ * Passes packets as they are, for channels that clone values themselves: worker threads, and processes with the
+ * `advanced` IPC serialization. It cannot be combined with transformers, nor cross the network.
+ */
+export declare class RawMessageHandler implements MessageHandler {
+  readonly name = "raw";
+  serialize(packet: unknown): unknown;
+  deserialize(data: unknown): unknown;
+}
+/**
+ * Registers a message handler under its name, so managers and shards can refer to it by name.
+ *
+ * @param name The name of the handler, the same as its `name`.
+ * @param factory Builds the handler.
+ */
+export declare function registerMessageHandler(name: string, factory: () => MessageHandler): void;
+/**
+ * Resolves a message handler, or the name of a registered one.
+ *
+ * @param handler The handler, or its name.
+ */
+export declare function resolveMessageHandler(handler: MessageHandler | string): MessageHandler;
+//#endregion
+//#region src/messages/MessageTransformer.d.ts
+/**
+ * The channel a transformer reads or writes on.
+ */
+export interface TransformerContext {
+  /**
+   * The ID of the channel: the shard the data comes from or goes to.
+   */
+  channelId: number;
+}
+/**
+ * Transforms serialized data on its way to the channel, and back: compression, encryption, signing, ...
+ *
+ * @remarks
+ * Transformers compose: they write in the order they are given, and read in the reverse order. `[gzip, aes]` gzips
+ * then encrypts when writing, and decrypts then gunzips when reading. A transformer throwing while reading rejects the
+ * data, which is reported as an invalid message.
+ *
+ * Like {@link MessageHandler}s, the manager tells its shards the names of its transformers: custom ones must be
+ * registered in the shards too, see {@link registerMessageTransformer}.
+ */
+export interface MessageTransformer {
+  /**
+   * The name of the transformer in the registry.
+   */
+  readonly name: string;
+  write(data: ChannelData, context: TransformerContext): ChannelData | Promise<ChannelData>;
+  read(data: ChannelData, context: TransformerContext): ChannelData | Promise<ChannelData>;
+}
+/**
+ * Compresses messages with gzip.
+ */
+export declare class GzipTransformer implements MessageTransformer {
+  readonly name = "gzip";
+  private readonly options;
+  /**
+   * @param options The compression options, e.g. its `level`.
+   */
+  constructor(options?: ZlibOptions);
+  write(data: ChannelData): Promise<Uint8Array>;
+  read(data: ChannelData): Promise<Uint8Array>;
+}
+/**
+ * Compresses messages with Brotli, smaller than gzip at a higher CPU cost.
+ */
+export declare class BrotliTransformer implements MessageTransformer {
+  readonly name = "brotli";
+  write(data: ChannelData): Promise<Uint8Array>;
+  read(data: ChannelData): Promise<Uint8Array>;
+}
+/**
+ * Registers a message transformer under its name, so managers and shards can refer to it by name.
+ *
+ * @param name The name of the transformer, the same as its `name`.
+ * @param factory Builds the transformer, e.g. with a key read from the environment.
+ */
+export declare function registerMessageTransformer(name: string, factory: () => MessageTransformer): void;
+/**
+ * Resolves a message transformer, or the name of a registered one.
+ *
+ * @param transformer The transformer, or its name.
+ */
+export declare function resolveMessageTransformer(transformer: MessageTransformer | string): MessageTransformer;
+//#endregion
+//#region src/messages/protocol.d.ts
+/**
+ * The lifecycle status of a shard, as it signals it to its manager.
+ */
+export declare const ShardStatus: {
+  /**
+   * Not spawned yet, or stopped.
+   */
+  readonly Idle: "Idle";
+  /**
+   * Spawned, and not ready to answer yet.
+   */
+  readonly Starting: "Starting";
+  /**
+   * Fully operative.
+   */
+  readonly Ready: "Ready";
+  /**
+   * Running, but disconnected from what it serves, e.g. the gateway.
+   */
+  readonly Disconnected: "Disconnected";
+  /**
+   * Running, and reconnecting to what it serves.
+   */
+  readonly Reconnecting: "Reconnecting";
+  /**
+   * Shutting down, not to be restarted.
+   */
+  readonly Exiting: "Exiting";
+  /**
+   * Shutting down, to be restarted.
+   */
+  readonly Restarting: "Restarting";
+};
+export type ShardStatus = (typeof ShardStatus)[keyof typeof ShardStatus];
+/**
+ * Where a message or a request goes: a shard's ID, or `"all"` for every shard. Left out, it goes to the manager.
+ */
+type ShardTarget = number | "all";
+/**
+ * The operation of a packet.
+ *
+ * @internal
+ */
+declare const Op: {
+  readonly Signal: 0;
+  readonly Ping: 1;
+  readonly Pong: 2;
+  readonly Message: 3;
+  readonly Request: 4;
+  readonly Reply: 5;
+  readonly Abort: 6;
+  readonly Close: 7;
+};
+/**
+ * @internal
+ */
+type Op = (typeof Op)[keyof typeof Op];
+/**
+ * The requests the sharder itself sends, rather than the application.
+ *
+ * - `identify` (shard → manager): waits for the turn of a gateway shard to identify. Body: the gateway shard ID.
+ * - `gatewayInformation` (shard → manager): the manager's cached `GET /gateway/bot`.
+ * - `control` (shard → manager): starts, closes, or restarts shards or gateway shards. Body: {@link ControlRequest}.
+ * - `startShard` / `closeShard` (manager → shard): starts or closes a gateway shard. Body: the gateway shard ID.
+ *
+ * @internal
+ */
+type SystemCall = "identify" | "gatewayInformation" | "control" | "startShard" | "closeShard";
+/**
+ * What a shard asks its manager to start, close, or restart.
+ */
+interface ControlRequest {
+  action: "start" | "close" | "restart";
+  /**
+   * A shard (`{ channel }`, or `"all"`), or a gateway shard (`{ shard }`).
+   */
+  target: {
+    channel: ShardTarget;
+  } | {
+    shard: number;
+  };
+}
+/**
+ * The error of a failed request, as sent over the channel.
+ *
+ * @internal
+ */
+interface SerializedError {
+  name: string;
+  message: string;
+}
+/**
+ * The packets exchanged between the manager and its shards, before serialization.
+ *
+ * @internal
+ */
+type Packet = {
+  op: typeof Op.Signal;
+  status: ShardStatus;
+} | {
+  op: typeof Op.Ping;
+  sentAt: number;
+} | {
+  op: typeof Op.Pong;
+  sentAt: number;
+} | {
+  op: typeof Op.Message;
+  body: unknown;
+  to?: ShardTarget;
+  from?: number | null;
+} | {
+  op: typeof Op.Request;
+  nonce: number;
+  body: unknown;
+  to?: ShardTarget;
+  from?: number | null;
+  timeout?: number;
+  /**
+   * For broadcasts: reply with every outcome rather than rejecting on the first failure.
+   */
+  partial?: boolean;
+  system?: SystemCall;
+} | {
+  op: typeof Op.Reply;
+  nonce: number;
+  body?: unknown;
+  error?: SerializedError;
+} | {
+  op: typeof Op.Abort;
+  nonce: number;
+} | {
+  op: typeof Op.Close;
+};
+/**
+ * Serializes packets with a {@link MessageHandler}, then runs them through the {@link MessageTransformer}s, and the
+ * other way around.
+ *
+ * @internal
+ */
+declare class PacketCodec {
+  readonly handler: MessageHandler;
+  readonly transformers: readonly MessageTransformer[];
+  constructor(handler: MessageHandler, transformers: readonly MessageTransformer[]);
+  encode(packet: Packet, context: TransformerContext): Promise<unknown>;
+  decode(data: unknown, context: TransformerContext): Promise<Packet>;
+}
+//#endregion
+//#region src/strategies/ChannelStrategy.d.ts
+/**
+ * What a shard is told about itself when spawned, read back by {@link ShardClient}.
+ */
+export interface ShardContext {
+  /**
+   * The ID of the shard: the index of its channel in the manager.
+   */
+  id: number;
+  /**
+   * The IDs of the gateway shards the shard connects.
+   */
+  shards: readonly number[];
+  /**
+   * The total number of gateway shards, across every shard (and every manager).
+   */
+  shardCount: number;
+  /**
+   * How long the ready shard may go without a ping from its manager, in milliseconds, before
+   * `managerUnresponsive`; `null` when the manager does not ping.
+   */
+  pingTimeout: number | null;
+  /**
+   * How long the shard waits for the replies of its requests by default, in milliseconds.
+   */
+  requestTimeout: number;
+  /**
+   * The name of the manager's message handler.
+   */
+  messageHandler: string;
+  /**
+   * The names of the manager's message transformers, in order.
+   */
+  transformers: readonly string[];
+  /**
+   * How the shard talks to its parent: the process IPC channel, or its worker thread port. Set by the strategy.
+   */
+  transport?: "process" | "worker";
+}
+/**
+ * The callbacks a {@link ChannelStrategy} reports a spawned shard's activity through.
+ */
+export interface ShardTransportEvents {
+  message(data: unknown): void;
+  /**
+   * The shard stopped. Called once per spawn.
+   */
+  exit(code: number | null): void;
+  /**
+   * The shard failed, e.g. a worker that could not start.
+   */
+  error(error: unknown): void;
+}
+/**
+ * What a strategy spawns a shard with, on top of its context.
+ */
+export interface SpawnOptions {
+  /**
+   * Environment variables for the shard, e.g. `DISCORD_TOKEN`.
+   */
+  env: Record<string, string>;
+}
+/**
+ * The manager's end of the channel to one spawned shard.
+ */
+export interface ShardTransport {
+  send(data: unknown): Promise<void>;
+  /**
+   * Stops the shard, resolving once it stopped.
+   */
+  kill(): Promise<void>;
+  /**
+   * The ID of the shard's process, for observability.
+   */
+  readonly pid?: number | null;
+  /**
+   * The ID of the shard's worker thread.
+   */
+  readonly threadId?: number | null;
+  /**
+   * The host running the shard, for strategies spawning shards elsewhere.
+   */
+  readonly host?: string | null;
+}
+/**
+ * Spawns shards: as child processes, cluster workers, worker threads, on other machines, or anything else. The
+ * sharder RFC's channel strategy.
+ */
+export interface ChannelStrategy {
+  /**
+   * The name of the strategy in the registry, see {@link registerStrategy}.
+   */
+  readonly name: string;
+  /**
+   * Prepares the strategy before the first spawn, e.g. starts listening for proxies.
+   */
+  init?(): Promise<void>;
+  /**
+   * Releases what the strategy holds, once every shard is closed.
+   */
+  destroy?(): Promise<void>;
+  spawn(context: ShardContext, events: ShardTransportEvents, options: SpawnOptions): ShardTransport;
+}
+/**
+ * The environment variable carrying the {@link ShardContext} of a shard.
+ */
+export declare const ShardContextVariable = "WOLFSTAR_SHARDER";
+/**
+ * Serializes a shard's context for its environment or worker data.
+ *
+ * @internal
+ */
+export declare function encodeContext(context: ShardContext): string;
+//#endregion
+//#region src/util/errors.d.ts
+/**
+ * What a sharder operation fails with: the `E` of the `try*` methods' `Result<T, E>`.
+ */
+export type ShardError = ShardRequestError | ShardRequestTimeoutError | ShardUnavailableError | ShardSpawnError | Error;
+/**
+ * The handler of a request threw, or there was none: the error is the remote one, rebuilt.
+ */
+export declare class ShardRequestError extends Error {
+  /**
+   * The name of the remote error, e.g. `TypeError`.
+   */
+  readonly remoteName: string;
+  constructor(remoteName: string, message: string);
+}
+/**
+ * A request got no reply in time. The other side was told to abort it.
+ */
+export declare class ShardRequestTimeoutError extends Error {
+  readonly timeout: number;
+  constructor(timeout: number);
+}
+/**
+ * A shard stopped, is not ready in time, or does not exist.
+ */
+export declare class ShardUnavailableError extends Error {
+  readonly channelId: number;
+  constructor(channelId: number, reason: string);
+}
+/**
+ * A shard failed before it was ready: its process exited, or its worker could not start. The sharder RFC's `error`
+ * signal.
+ */
+export declare class ShardSpawnError extends Error {
+  readonly channelId: number;
+  /**
+   * The exit code, when the shard exited.
+   */
+  readonly code: number | null;
+  constructor(channelId: number, code: number | null, cause?: unknown);
+}
+//#endregion
+//#region src/util/gateway.d.ts
+/**
+ * The `GET /gateway/bot` payload, the same shape as discord-api-types' `APIGatewayBotInfo`, which `@discordjs/ws`'s
+ * `WebSocketManager#fetchGatewayInformation` returns.
+ */
+interface GatewayInformation {
+  url: string;
+  shards: number;
+  session_start_limit: {
+    total: number;
+    remaining: number;
+    /**
+     * In milliseconds.
+     */
+    reset_after: number;
+    max_concurrency: number;
+  };
+}
+/**
+ * The options of {@link fetchRecommendedShardCount}.
+ */
+interface RecommendedShardCountOptions {
+  /**
+   * How many guilds a gateway shard should hold. Discord's recommendation is based on 1000.
+   *
+   * @default 1000
+   */
+  guildsPerShard?: number;
+  /**
+   * Rounds the count up to a multiple of it, e.g. 16 for large bot sharding.
+   *
+   * @default 1
+   */
+  multipleOf?: number;
+}
+/**
+ * Fetches `GET /gateway/bot`.
+ *
+ * @param token The bot token.
+ */
+export declare function fetchGatewayInformation(token: string): Promise<GatewayInformation>;
+/**
+ * Turns Discord's recommended shard count into the one to spawn.
+ *
+ * @param recommended The `shards` of `GET /gateway/bot`.
+ * @param options How many guilds per gateway shard, and what to round the count up to.
+ */
+export declare function resolveRecommendedShardCount(recommended: number, options?: RecommendedShardCountOptions): number;
+/**
+ * Fetches how many gateway shards Discord recommends for the bot, like discord.js's `fetchRecommendedShardCount`.
+ *
+ * @param token The bot token.
+ * @param options How many guilds per gateway shard, and what to round the count up to.
+ */
+export declare function fetchRecommendedShardCount(token: string, options?: RecommendedShardCountOptions): Promise<number>;
+/**
+ * Gets the gateway shard receiving the events of a guild.
+ *
+ * @param guildId The ID of the guild.
+ * @param shardCount The total number of gateway shards.
+ */
+export declare function shardIdForGuild(guildId: string, shardCount: number): number;
+//#endregion
+//#region src/util/requests.d.ts
+/**
+ * The options of a request.
+ */
+interface RequestOptions {
+  /**
+   * How long to wait for the reply, in milliseconds. Defaults to the manager's `requestTimeout`.
+   */
+  timeout?: number;
+  /**
+   * Aborts the request: dropped from the queue if it waits for a shard to be ready, and aborted on the other side
+   * otherwise, whose handler gets an aborted `signal`.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * The options of a broadcast request.
+ */
+interface BroadcastRequestOptions extends RequestOptions {
+  /**
+   * Whether to resolve with the outcome of every shard, like `Promise.allSettled`, rather than rejecting on the first
+   * failure: the replies that came before a timeout or an abort are kept.
+   */
+  partial?: boolean;
+}
+/**
+ * Answers the requests of the other side. Its return value (or the value it resolves to) is the reply, and a throw is
+ * rejected on the other side as a {@link ShardRequestError}. It may also return a `Result`: `Ok` is the reply, `Err`
+ * the error.
+ */
+type RequestHandler<Context> = (body: any, context: Context & {
+  signal: AbortSignal;
+}) => unknown;
+//#endregion
+//#region src/util/Supervisor.d.ts
+/**
+ * What else restarts when a shard crashes, after Erlang/OTP's supervisor strategies.
+ *
+ * - `one-for-one`: only the crashed shard.
+ * - `one-for-all`: every shard.
+ * - `rest-for-one`: the crashed shard, and every shard after it.
+ */
+type SupervisorStrategy = "one-for-one" | "one-for-all" | "rest-for-one";
+/**
+ * How a manager restarts crashing shards, after Erlang/OTP's supervisors: a shard crashing more than `intensity`
+ * times within `period` is given up on.
+ */
+interface SupervisorOptions {
+  /**
+   * How many crashes are tolerated, `-1` or `Infinity` for no limit.
+   *
+   * @default -1
+   */
+  intensity?: number;
+  /**
+   * The window the crashes are counted in, in milliseconds. `0` counts the crashes in a row instead, until the shard
+   * is ready again.
+   *
+   * @default 0
+   */
+  period?: number;
+  /**
+   * @default "one-for-one"
+   */
+  strategy?: SupervisorStrategy;
+}
+/**
+ * Counts the crashes of each shard against the supervisor's intensity.
+ *
+ * @internal
+ */
+declare class Supervisor {
+  #private;
+  readonly intensity: number;
+  readonly period: number;
+  readonly strategy: SupervisorStrategy;
+  constructor(options?: SupervisorOptions);
+  /**
+   * Counts a crash. Returns how many crashes count, and whether the shard may be restarted.
+   *
+   * @param channelId The ID of the crashed shard.
+   */
+  crash(channelId: number): {
+    crashes: number;
+    restart: boolean;
+  };
+  /**
+   * Forgets the crashes of a shard that is ready again, when they are counted in a row.
+   *
+   * @param channelId The ID of the shard.
+   */
+  ready(channelId: number): void;
+}
+//#endregion
+//#region src/ShardManager.d.ts
+/**
+ * How the gateway shards are laid out across shards.
+ */
+export interface ShardLayoutOptions {
+  /**
+   * The layout: a number spawns one shard per gateway shard, an array spawns one shard per entry connecting that
+   * many gateway shards, and `"auto"` splits the gateway shards across `clusters` shards.
+   *
+   * @default "auto"
+   * @example
+   * ```ts
+   * // 9 shards, connecting one gateway shard each.
+   * new ShardManager({ shards: 9 });
+   * // 3 shards, connecting 3 gateway shards each: 0-2, 3-5 and 6-8.
+   * new ShardManager({ shards: [3, 3, 3] });
+   * // Discord's recommended count, split across 4 shards.
+   * new ShardManager({ shards: "auto", clusters: 4 });
+   * ```
+   */
+  shards?: number | readonly number[] | "auto";
+  /**
+   * The total number of gateway shards, across every manager: `"auto"` is Discord's recommendation. Defaults to the
+   * number of gateway shards of this manager.
+   */
+  totalShards?: number | "auto";
+  /**
+   * The gateway shards this manager spawns, when several managers split them. Defaults to all of them.
+   */
+  shardList?: readonly number[];
+  /**
+   * How many shards to split the gateway shards across, with `shards: "auto"`.
+   *
+   * @default os.availableParallelism()
+   */
+  clusters?: number;
+  /**
+   * How Discord's recommended count is turned into the total, with `"auto"`.
+   */
+  recommended?: RecommendedShardCountOptions;
+}
+/**
+ * The options of a {@link ShardManager}.
+ */
+export interface ShardManagerOptions extends ShardLayoutOptions {
+  /**
+   * How to spawn the shards: a {@link ChannelStrategy}, or the name of a registered one (`"fork"`, `"cluster"`,
+   * `"worker"`, `"network"`), built with `strategyOptions`.
+   *
+   * @default "fork"
+   */
+  strategy?: ChannelStrategy | string;
+  /**
+   * The options of a strategy given by name.
+   */
+  strategyOptions?: unknown;
+  /**
+   * The bot token: used for `"auto"` layouts and `GET /gateway/bot`, and passed to the shards as `DISCORD_TOKEN`.
+   *
+   * @default process.env.DISCORD_TOKEN
+   */
+  token?: string;
+  /**
+   * How `GET /gateway/bot` is fetched and cached. The shards get it from the manager, so it is fetched once for all.
+   */
+  gatewayInformation?: {
+    /**
+     * Fetches it, instead of requesting Discord with the token.
+     */
+    fetch?: () => Promise<GatewayInformation>;
+    /**
+     * How long to reuse it, in milliseconds; the session start limit is kept up to date meanwhile.
+     *
+     * @default 86_400_000
+     */
+    ttl?: number;
+  };
+  /**
+   * How the identifies of the gateway shards are paced, across every shard. See {@link ShardClient.identifyThrottler}.
+   */
+  identify?: {
+    /**
+     * How many gateway shards may identify at once: `"auto"` is the `max_concurrency` of `GET /gateway/bot`, or `1`
+     * without a token.
+     *
+     * @default "auto"
+     */
+    concurrency?: number | "auto";
+    /**
+     * How long a concurrency bucket waits between identifies, in milliseconds.
+     *
+     * @default 5_000
+     */
+    delay?: number;
+  };
+  /**
+   * How crashing shards are restarted.
+   */
+  supervisor?: SupervisorOptions;
+  spawn?: {
+    /**
+     * How long to wait after a shard is ready before spawning the next one, in milliseconds. With
+     * {@link ShardClient.identifyThrottler} pacing the identifies, it can be `0`.
+     *
+     * @default 5_000
+     */
+    delay?: number;
+    /**
+     * How long a shard has to signal that it is ready, in milliseconds. Past it, it is killed and spawned again at
+     * the end of the queue.
+     *
+     * @default 30_000
+     */
+    timeout?: number;
+    /**
+     * How long a shard is expected to take to be ready, in milliseconds. Defaults to the average of the shards
+     * spawned so far. A shard slower than the estimate (plus the margin) is emitted as `shardSlowStart`, and a request
+     * for a starting shard that is not expected to be ready before its timeout is rejected right away.
+     */
+    readyHint?: number;
+    /**
+     * The margin of error of the estimate, as a fraction of it.
+     *
+     * @default 0.1
+     */
+    readyHintMargin?: number;
+  };
+  ping?: ShardPingOptions;
+  /**
+   * How long requests wait for their reply by default, in milliseconds.
+   *
+   * @default ping.timeout
+   */
+  requestTimeout?: number;
+  /**
+   * How messages are serialized: a handler, or the name of a registered one. The shards build the same one.
+   *
+   * @default "json"
+   */
+  messageHandler?: MessageHandler | string;
+  /**
+   * How serialized messages are transformed (compressed, encrypted, ...), in order: transformers, or names of
+   * registered ones. The shards build the same ones.
+   *
+   * @default []
+   */
+  transformers?: readonly (MessageTransformer | string)[];
+}
+/**
+ * The events of a {@link ShardManager}.
+ */
+export interface ShardManagerEvents {
+  /**
+   * A shard was spawned.
+   */
+  shardCreate: [channel: ShardChannel];
+  /**
+   * A shard signalled a new status, or stopped (`Idle`).
+   */
+  shardStatus: [channel: ShardChannel, status: ShardStatus];
+  shardReady: [channel: ShardChannel];
+  shardDisconnect: [channel: ShardChannel];
+  shardReconnecting: [channel: ShardChannel];
+  /**
+   * A shard answered a ping; `latency` is the round trip, in milliseconds.
+   */
+  shardPing: [channel: ShardChannel, latency: number];
+  /**
+   * A ready shard did not answer the pings in time. Without listeners, it is restarted.
+   */
+  shardUnresponsive: [channel: ShardChannel];
+  /**
+   * A shard takes longer than the estimate (plus its margin) to be ready.
+   */
+  shardSlowStart: [channel: ShardChannel, elapsed: number, estimate: number];
+  /**
+   * A shard is about to be spawned again: it asked for it, crashed, or was restarted.
+   */
+  shardRestart: [channel: ShardChannel];
+  /**
+   * A shard's process or thread stopped.
+   */
+  shardExit: [channel: ShardChannel, code: number | null];
+  /**
+   * A shard was closed by its manager.
+   */
+  shardDestroy: [channel: ShardChannel];
+  /**
+   * A shard failed: it exited before it was ready (a {@link ShardSpawnError}), or its strategy reported an error.
+   * Without listeners, it goes to `error`.
+   */
+  shardError: [channel: ShardChannel, error: unknown];
+  /**
+   * A shard crashed more often than the supervisor tolerates, and is not restarted anymore. Without listeners, it
+   * goes to `error`.
+   */
+  shardGiveUp: [channel: ShardChannel, crashes: number];
+  /**
+   * A shard sent data that could not be read. Without listeners, it is logged with `console.error`.
+   */
+  shardInvalidMessage: [channel: ShardChannel, error: unknown];
+  /**
+   * A shard sent a message to the manager.
+   */
+  message: [body: any, channel: ShardChannel];
+  /**
+   * Without listeners, errors are logged with `console.error`.
+   */
+  error: [error: unknown];
+}
+/**
+ * Spawns shards, keeps them alive, and carries messages between them.
+ *
+ * @remarks
+ * Follows discord.js's sharder RFC (discordjs/discord.js#8084): a "shard" is a process, cluster worker, worker
+ * thread, or remote process, which may connect several gateway shards, and the manager talks to each through a
+ * {@link ShardChannel}. The manager is agnostic of the bot: a shard runs any script using {@link ShardClient}.
+ *
+ * @example
+ * ```ts
+ * const manager = new ShardManager({ strategy: new ForkStrategy({ path: "./bot.js" }), clusters: 4 });
+ * manager.setRequestHandler((body, { channel }) => ...);
+ * await manager.spawn();
+ * const guilds = await manager.broadcastRequest({ type: "guildCount" });
+ * ```
+ */
+export declare class ShardManager extends EventEmitter<ShardManagerEvents> {
+  #private;
+  readonly strategy: ChannelStrategy;
+  /**
+   * The channels to the shards, by ID. Empty until {@link ShardManager.spawn} for `"auto"` layouts.
+   */
+  channels: readonly ShardChannel[];
+  /**
+   * The total number of gateway shards, `0` until resolved for `"auto"` layouts.
+   */
+  shardCount: number;
+  readonly spawnDelay: number;
+  readonly spawnTimeout: number;
+  readonly readyHint: number | null;
+  readonly readyHintMargin: number;
+  readonly requestTimeout: number;
+  readonly pingOptions: Required<ShardPingOptions>;
+  /**
+   * @internal
+   */
+  readonly codec: PacketCodec;
+  /**
+   * @internal
+   */
+  readonly supervisor: Supervisor;
+  /**
+   * @internal
+   */
+  readonly spawnEnv: Record<string, string>;
+  /**
+   * @internal
+   */
+  requestHandler: RequestHandler<{
+    channel: ShardChannel;
+  }> | null;
+  constructor(options?: ShardManagerOptions);
+  /**
+   * How long a shard is expected to take to be ready: `spawn.readyHint`, or the average of the shards so far.
+   */
+  get readyEstimate(): number | null;
+  /**
+   * Spawns every shard, one after the other, each waiting for the previous one to be ready plus the spawn delay. A
+   * shard not ready in time is killed and tried again at the end of the queue, as long as the supervisor allows.
+   */
+  spawn(): Promise<void>;
+  /**
+   * Fetches `GET /gateway/bot`, cached for every shard, with its session start limit kept up to date.
+   *
+   * @param force Whether to skip the cache.
+   */
+  fetchGatewayInformation(force?: boolean): Promise<GatewayInformation>;
+  /**
+   * Gets the channel to the shard connecting a gateway shard.
+   *
+   * @param shardId The ID of the gateway shard.
+   */
+  channelFor(shardId: number): ShardChannel | undefined;
+  /**
+   * Gets the channel to the shard receiving the events of a guild.
+   *
+   * @param guildId The ID of the guild.
+   */
+  channelForGuild(guildId: string): ShardChannel | undefined;
+  /**
+   * Sets the handler answering the requests the shards send to the manager.
+   *
+   * @param handler The handler; its return value is the reply.
+   */
+  setRequestHandler(handler: RequestHandler<{
+    channel: ShardChannel;
+  }> | null): this;
+  /**
+   * Sends a message to a shard, emitted as `message` by its {@link ShardClient}.
+   *
+   * @param channelId The ID of the shard.
+   * @param body The message.
+   * @param options How long to wait for the shard to be ready, and an abort signal.
+   */
+  send(channelId: number, body: unknown, options?: RequestOptions): Promise<void>;
+  /**
+   * Sends a request to a shard, answered by its {@link ShardClient}'s request handler.
+   *
+   * @param channelId The ID of the shard.
+   * @param body The request.
+   * @param options The timeout and abort signal of the request.
+   */
+  request<Reply = unknown>(channelId: number, body: unknown, options?: RequestOptions): Promise<Reply>;
+  /**
+   * Sends a message to every shard.
+   *
+   * @param body The message.
+   * @param options How long to wait for the shards to be ready, and an abort signal.
+   */
+  broadcast(body: unknown, options?: RequestOptions): Promise<void>;
+  /**
+   * Sends a request to every shard, like discord.js's `broadcastEval` without the `eval`.
+   *
+   * @param body The request.
+   * @param options The timeout and abort signal of every request, and whether to keep partial results.
+   * @returns The replies by shard ID, or with `partial`, the outcome of every request.
+   */
+  broadcastRequest<Reply = unknown>(body: unknown, options: BroadcastRequestOptions & {
+    partial: true;
+  }): Promise<PromiseSettledResult<Reply>[]>;
+  broadcastRequest<Reply = unknown>(body: unknown, options?: BroadcastRequestOptions): Promise<Reply[]>;
+  /**
+   * {@link ShardManager.send}, resolving with a `Result` rather than rejecting.
+   */
+  trySend(channelId: number, body: unknown, options?: RequestOptions): Promise<Result$1<void, ShardError>>;
+  /**
+   * {@link ShardManager.request}, resolving with a `Result` rather than rejecting.
+   */
+  tryRequest<Reply = unknown>(channelId: number, body: unknown, options?: RequestOptions): Promise<Result$1<Reply, ShardError>>;
+  /**
+   * {@link ShardManager.broadcastRequest}, resolving with one `Result` per shard, by shard ID.
+   */
+  tryBroadcastRequest<Reply = unknown>(body: unknown, options?: RequestOptions): Promise<Result$1<Reply, ShardError>[]>;
+  /**
+   * Restarts a shard: closes it then spawns it again, or with `rolling`, spawns the new one first and closes the old
+   * one once the new one is ready.
+   *
+   * @param channelId The ID of the shard.
+   * @param options Whether to restart it rolling, and the timeout.
+   */
+  restart(channelId: number, options?: ShardRestartOptions): Promise<void>;
+  /**
+   * Restarts every shard, one after the other, with the spawn delay between them.
+   *
+   * @param options Whether to restart them rolling, and the timeout.
+   */
+  restartAll(options?: ShardRestartOptions): Promise<void>;
+  /**
+   * Reshards with close to no downtime: spawns the shards of a new layout while the current ones keep running, then
+   * closes the current ones once every new one is ready.
+   *
+   * @param layout The new layout. Left out, Discord's recommendation split across `clusters`.
+   */
+  reshard(layout?: ShardLayoutOptions): Promise<void>;
+  /**
+   * Asks the shard connecting a gateway shard to start it, through its {@link ShardClient.setShardHandler}.
+   *
+   * @param shardId The ID of the gateway shard.
+   * @param options The timeout and abort signal of the request.
+   */
+  startShard(shardId: number, options?: RequestOptions): Promise<void>;
+  /**
+   * Asks the shard connecting a gateway shard to close it, through its {@link ShardClient.setShardHandler}.
+   *
+   * @param shardId The ID of the gateway shard.
+   * @param options The timeout and abort signal of the request.
+   */
+  closeShard(shardId: number, options?: RequestOptions): Promise<void>;
+  /**
+   * Closes then starts a gateway shard, see {@link ShardManager.startShard}.
+   *
+   * @param shardId The ID of the gateway shard.
+   * @param options The timeout and abort signal of each request.
+   */
+  restartShard(shardId: number, options?: RequestOptions): Promise<void>;
+  /**
+   * Waits for a gateway shard's turn to identify, like {@link ShardClient.identifyThrottler} does from a shard.
+   *
+   * @param shardId The ID of the gateway shard.
+   * @param signal Aborts the wait.
+   */
+  waitForIdentify(shardId: number, signal?: AbortSignal): Promise<void>;
+  /**
+   * Closes every shard for good, and releases the strategy.
+   */
+  destroy(): Promise<void>;
+  /**
+   * Carries a message a shard sends to another shard, or to every shard.
+   *
+   * @internal
+   */
+  route(body: unknown, to: ShardTarget, from: number): Promise<void>;
+  /**
+   * Carries a request a shard sends to another shard, or to every shard.
+   *
+   * @internal
+   */
+  forward(body: unknown, to: ShardTarget, from: number, options: BroadcastRequestOptions): Promise<unknown>;
+  /**
+   * Answers the requests the sharder itself sends.
+   *
+   * @internal
+   */
+  handleSystem(call: SystemCall, body: unknown, channel: ShardChannel, signal: AbortSignal): Promise<unknown>;
+  /**
+   * Decides what happens to a shard that stopped on its own.
+   *
+   * @internal
+   */
+  supervise(channel: ShardChannel, previous: ShardStatus): void;
+  /**
+   * @internal
+   */
+  recordReadyTime(time: number): void;
+  /**
+   * @internal
+   */
+  reportError(error: unknown): void;
+  /**
+   * @internal
+   */
+  reportShardError(channel: ShardChannel, error: unknown): void;
+  /**
+   * @internal
+   */
+  reportInvalidMessage(channel: ShardChannel, error: unknown): void;
+}
+//#endregion
+//#region src/ShardChannel.d.ts
+/**
+ * The events of a {@link ShardChannel}. The manager emits them too, prefixed with `shard` and with the channel first.
+ */
+export interface ShardChannelEvents {
+  /**
+   * The shard was spawned (`shardCreate` on the manager).
+   */
+  spawn: [];
+  status: [status: ShardStatus];
+  ready: [];
+  disconnect: [];
+  reconnecting: [];
+  /**
+   * The shard answered a ping; `latency` is the round trip, in milliseconds.
+   */
+  ping: [latency: number];
+  unresponsive: [];
+  /**
+   * The shard takes longer than expected to be ready, see `spawn.readyHint`.
+   */
+  slowStart: [elapsed: number, estimate: number];
+  exit: [code: number | null];
+  destroy: [];
+  error: [error: unknown];
+  message: [body: any];
+}
+/**
+ * The options of a restart.
+ */
+export interface ShardRestartOptions {
+  /**
+   * Whether to spawn the new shard before closing the old one, which only closes once the new one is ready: close to
+   * no downtime, at the cost of both running for a moment.
+   *
+   * @default false
+   */
+  rolling?: boolean;
+  /**
+   * How long to wait for the old shard to exit, and for the new one to be ready, in milliseconds.
+   */
+  timeout?: number;
+}
+/**
+ * The manager's channel to one shard: a process, cluster worker, worker thread, or remote process, connecting some
+ * gateway shards.
+ *
+ * @remarks
+ * Named after discord.js's sharder: a "shard" is the client a manager spawns, and the channel is how the manager
+ * talks to it, whatever the channel strategy.
+ */
+export declare class ShardChannel extends EventEmitter<ShardChannelEvents> {
+  #private;
+  /**
+   * The ID of the channel, its index in {@link ShardManager.channels}.
+   */
+  readonly id: number;
+  /**
+   * The IDs of the gateway shards the shard connects.
+   */
+  readonly shards: readonly number[];
+  /**
+   * The total number of gateway shards the shard is told about.
+   */
+  readonly shardCount: number;
+  readonly manager: ShardManager;
+  /**
+   * The pings of the shard.
+   */
+  readonly ping: ShardPing;
+  /**
+   * The status of the running shard, `Idle` when none runs.
+   */
+  status: ShardStatus;
+  /**
+   * @internal
+   */
+  constructor(manager: ShardManager, id: number, shards: readonly number[], shardCount: number);
+  /**
+   * Whether the shard is running and signalled that it is ready.
+   */
+  get ready(): boolean;
+  /**
+   * Whether a shard is running: spawned, and not stopped yet.
+   */
+  get running(): boolean;
+  /**
+   * Whether the channel was stopped for good: closed, exited, or given up on.
+   */
+  get stopped(): boolean;
+  /**
+   * The ID of the shard's process.
+   */
+  get pid(): number | null;
+  /**
+   * The ID of the shard's worker thread, for {@link WorkerStrategy}.
+   */
+  get threadId(): number | null;
+  /**
+   * The host running the shard, for strategies spawning shards elsewhere.
+   */
+  get host(): string | null;
+  /**
+   * When the running shard was spawned.
+   */
+  get startedTimestamp(): number | null;
+  /**
+   * Spawns the shard, and waits for it to signal that it is ready.
+   *
+   * @param timeout How long to wait for it, in milliseconds. Past it, the shard is killed and the promise rejects.
+   */
+  start(timeout?: number): Promise<void>;
+  /**
+   * Stops the shard for good. It is first asked to close, which runs its close handler, and is killed if it did not
+   * exit within the timeout.
+   *
+   * @param timeout How long to wait for the shard to exit by itself, in milliseconds.
+   */
+  close(timeout?: number): Promise<void>;
+  /**
+   * Restarts the shard through its manager, see {@link ShardManager.restart}.
+   *
+   * @param options Whether to restart it rolling, and the timeout.
+   */
+  restart(options?: ShardRestartOptions): Promise<void>;
+  /**
+   * Waits for the shard to be ready.
+   *
+   * @param timeout How long to wait, in milliseconds.
+   * @param signal Aborts the wait.
+   * @throws A {@link ShardUnavailableError} when the shard is stopped for good, not ready in time, or expected to be
+   * ready past the timeout (see `spawn.readyHint`).
+   */
+  waitForReady(timeout?: number, signal?: AbortSignal): Promise<void>;
+  /**
+   * Sends a message to the shard, emitted as `message` by its {@link ShardClient}. Waits for the shard to be ready.
+   *
+   * @param body The message.
+   * @param options How long to wait for the shard to be ready, and an abort signal.
+   * @param from The shard the message comes from, `null` for the manager.
+   */
+  send(body: unknown, options?: RequestOptions, from?: number | null): Promise<void>;
+  /**
+   * Sends a request to the shard, answered by its {@link ShardClient}'s request handler. Waits for the shard to be
+   * ready.
+   *
+   * @param body The request.
+   * @param options The timeout and abort signal of the request.
+   * @param from The shard the request comes from, `null` for the manager.
+   */
+  request<Reply = unknown>(body: unknown, options?: RequestOptions, from?: number | null): Promise<Reply>;
+  /**
+   * {@link ShardChannel.send}, resolving with a `Result` rather than rejecting.
+   */
+  trySend(body: unknown, options?: RequestOptions): Promise<Result$1<void, ShardError>>;
+  /**
+   * {@link ShardChannel.request}, resolving with a `Result` rather than rejecting.
+   */
+  tryRequest<Reply = unknown>(body: unknown, options?: RequestOptions): Promise<Result$1<Reply, ShardError>>;
+  /**
+   * Asks the shard to start one of its gateway shards, through its shard handler.
+   *
+   * @param shardId The ID of the gateway shard.
+   * @param options The timeout and abort signal of the request.
+   */
+  startShard(shardId: number, options?: RequestOptions): Promise<void>;
+  /**
+   * Asks the shard to close one of its gateway shards, through its shard handler.
+   *
+   * @param shardId The ID of the gateway shard.
+   * @param options The timeout and abort signal of the request.
+   */
+  closeShard(shardId: number, options?: RequestOptions): Promise<void>;
+  /**
+   * Restarts the shard, keeping the old one until the new one is ready.
+   *
+   * @internal
+   */
+  rollingRestart(timeout?: number): Promise<void>;
+  /**
+   * Stops the channel for good without closing anything, when its shard exited or was given up on.
+   *
+   * @internal
+   */
+  markStopped(reason: string): void;
+}
+//#endregion
+//#region src/ShardClient.d.ts
+/**
+ * The shard's end of the channel to its manager (or proxy).
+ */
+export interface ClientTransport {
+  send(data: unknown): Promise<void>;
+  onMessage(listener: (data: unknown) => void): void;
+  /**
+   * Registers what to do when the channel to the manager closes, i.e. when the manager died.
+   */
+  onDisconnect(listener: () => void): void;
+  /**
+   * Stops the shard.
+   */
+  exit(code: number): void;
+}
+/**
+ * The options of a {@link ShardClient}.
+ */
+export interface ShardClientOptions {
+  /**
+   * How messages are serialized. Defaults to the manager's, built from the registry.
+   */
+  messageHandler?: MessageHandler | string;
+  /**
+   * How serialized messages are transformed. Defaults to the manager's, built from the registry.
+   */
+  transformers?: readonly (MessageTransformer | string)[];
+  /**
+   * The shard's context. Defaults to the one its manager passed when spawning it.
+   */
+  context?: ShardContext;
+  /**
+   * The channel to the manager. Defaults to the one of {@link ShardContext.transport}.
+   */
+  transport?: ClientTransport;
+}
+/**
+ * Starts and closes the gateway shards of this shard, when the manager asks.
+ */
+export interface ShardHandler {
+  start?(shardId: number, context: {
+    signal: AbortSignal;
+  }): unknown;
+  close?(shardId: number, context: {
+    signal: AbortSignal;
+  }): unknown;
+}
+/**
+ * Paces identifies across every shard, the shape of `@discordjs/ws`'s `IIdentifyThrottler`.
+ */
+export interface IdentifyThrottler {
+  waitForIdentify(shardId: number, signal: AbortSignal): Promise<void>;
+}
+/**
+ * The events of a {@link ShardClient}.
+ */
+export interface ShardClientEvents {
+  /**
+   * A message from the manager (`from` is `null`) or from another shard.
+   */
+  message: [body: any, from: number | null];
+  /**
+   * The channel to the manager closed. Without listeners, the shard exits.
+   */
+  disconnect: [];
+  /**
+   * The manager stopped pinging, e.g. a proxy lost it. The shard keeps running.
+   */
+  managerUnresponsive: [];
+  /**
+   * The manager sent data that could not be read. Without listeners, it is logged with `console.error`.
+   */
+  invalidMessage: [error: unknown];
+  /**
+   * Without listeners, errors are logged with `console.error`.
+   */
+  error: [error: unknown];
+}
+/**
+ * The shard's side of the sharder: it tells the manager its status, and messages the manager and the other shards.
+ *
+ * @example
+ * ```ts
+ * const shard = new ShardClient();
+ * const client = new GatewayClient({
+ *   ...options,
+ *   ...shard.gatewayOptions,
+ *   gateway: { buildIdentifyThrottler: () => shard.identifyThrottler },
+ * });
+ * // Reuse the manager's `GET /gateway/bot` rather than requesting it again.
+ * client.gateway.fetchGatewayInformation = () => shard.fetchGatewayInformation();
+ * shard.setRequestHandler((body) => ...);
+ * ```
+ */
+export declare class ShardClient extends EventEmitter<ShardClientEvents> {
+  #private;
+  /**
+   * The context of this process or thread, when a {@link ShardManager} spawned it; `null` otherwise.
+   */
+  static get context(): ShardContext | null;
+  /**
+   * Registers a message handler the manager can refer to by name. The sharder RFC's API.
+   *
+   * @param name The name of the handler.
+   * @param factory Builds the handler.
+   */
+  static registerMessageHandler(name: string, factory: () => MessageHandler): typeof ShardClient;
+  /**
+   * Registers a message transformer the manager can refer to by name. The sharder RFC's API.
+   *
+   * @param name The name of the transformer.
+   * @param factory Builds the transformer.
+   */
+  static registerMessageTransformer(name: string, factory: () => MessageTransformer): typeof ShardClient;
+  /**
+   * The ID of the shard, its channel's in the manager.
+   */
+  readonly id: number;
+  /**
+   * The IDs of the gateway shards the shard connects.
+   */
+  readonly shards: readonly number[];
+  /**
+   * The total number of gateway shards, across every shard.
+   */
+  readonly shardCount: number;
+  readonly requestTimeout: number;
+  /**
+   * The last status signalled to the manager.
+   */
+  status: ShardStatus;
+  /**
+   * When the manager last pinged the shard, `null` before its first ping.
+   */
+  lastPingTimestamp: number | null;
+  constructor(options?: ShardClientOptions);
+  /**
+   * The ID of the shard's process.
+   */
+  get pid(): number;
+  /**
+   * The ID of the shard's thread, `0` for a process's main thread.
+   */
+  get threadId(): number;
+  /**
+   * The gateway shards to connect, to spread into `GatewayClient`'s (or `@discordjs/ws`'s) options.
+   */
+  get gatewayOptions(): {
+    shardIds: number[];
+    shardCount: number;
+  };
+  /**
+   * Paces the identifies of the gateway shards across every shard, through the manager: pass it as `@discordjs/ws`'s
+   * `buildIdentifyThrottler`. The manager then needs no spawn delay.
+   */
+  get identifyThrottler(): IdentifyThrottler;
+  /**
+   * Gets `GET /gateway/bot` from the manager, fetched once for every shard, e.g. to replace `@discordjs/ws`'s
+   * `WebSocketManager#fetchGatewayInformation`.
+   */
+  fetchGatewayInformation(): Promise<GatewayInformation>;
+  /**
+   * Tells the manager that the shard is ready, e.g. once its gateway shards are. The manager spawns the next shard
+   * only then.
+   */
+  ready(): Promise<void>;
+  /**
+   * Tells the manager that the shard lost what it serves, e.g. the gateway. Messages for it wait until it is ready
+   * again.
+   */
+  disconnected(): Promise<void>;
+  /**
+   * Tells the manager that the shard is reconnecting to what it serves.
+   */
+  reconnecting(): Promise<void>;
+  /**
+   * Stops the shard for good: the manager does not respawn it.
+   *
+   * @param code The exit code.
+   */
+  exit(code?: number): Promise<void>;
+  /**
+   * Stops the shard, for the manager to spawn it again.
+   */
+  restart(): Promise<void>;
+  /**
+   * Sends a message to the manager, emitted as its `message` event, or to other shards.
+   *
+   * @param body The message.
+   * @param to The ID of the shard to send it to, or `"all"`. Left out, it goes to the manager.
+   */
+  send(body: unknown, to?: ShardTarget): Promise<void>;
+  /**
+   * Sends a request to the manager or to another shard.
+   *
+   * @param body The request.
+   * @param options Where it goes (the manager by default), its timeout, and its abort signal.
+   */
+  request<Reply = unknown>(body: unknown, options?: RequestOptions & {
+    to?: number;
+  }): Promise<Reply>;
+  /**
+   * Sends a request to every shard, this one included, like discord.js's `broadcastEval` without the `eval`.
+   *
+   * @param body The request.
+   * @param options The timeout and abort signal of the request, and whether to keep partial results.
+   * @returns The replies by shard ID, or with `partial`, the outcome of every request.
+   */
+  broadcastRequest<Reply = unknown>(body: unknown, options: BroadcastRequestOptions & {
+    partial: true;
+  }): Promise<PromiseSettledResult<Reply>[]>;
+  broadcastRequest<Reply = unknown>(body: unknown, options?: BroadcastRequestOptions): Promise<Reply[]>;
+  /**
+   * {@link ShardClient.send}, resolving with a `Result` rather than rejecting.
+   */
+  trySend(body: unknown, to?: ShardTarget): Promise<Result$1<void, ShardError>>;
+  /**
+   * {@link ShardClient.request}, resolving with a `Result` rather than rejecting.
+   */
+  tryRequest<Reply = unknown>(body: unknown, options?: RequestOptions & {
+    to?: number;
+  }): Promise<Result$1<Reply, ShardError>>;
+  /**
+   * {@link ShardClient.broadcastRequest}, with one `Result` per shard, by shard ID. The broadcast itself failing
+   * (e.g. the manager not answering) is the outer `Err`.
+   */
+  tryBroadcastRequest<Reply = unknown>(body: unknown, options?: RequestOptions): Promise<Result$1<Result$1<Reply, ShardError>[], ShardError>>;
+  /**
+   * {@link ShardClient.control}, resolving with a `Result` rather than rejecting.
+   */
+  tryControl(request: ControlRequest, options?: RequestOptions): Promise<Result$1<void, ShardError>>;
+  /**
+   * Asks the manager to start, close, or restart shards or gateway shards.
+   *
+   * @param request What to do, and to what.
+   * @param options The timeout and abort signal of the request.
+   * @example
+   * ```ts
+   * await shard.control({ action: "restart", target: { channel: "all" } });
+   * await shard.control({ action: "restart", target: { shard: 12 } });
+   * ```
+   */
+  control(request: ControlRequest, options?: RequestOptions): Promise<void>;
+  /**
+   * Sets the handler answering the requests of the manager and of the other shards.
+   *
+   * @param handler The handler; its return value is the reply. `from` is the shard asking, `null` for the manager.
+   */
+  setRequestHandler(handler: RequestHandler<{
+    from: number | null;
+  }> | null): this;
+  /**
+   * Sets what to do when the manager closes the shard, e.g. disconnect from the gateway. The shard exits once it
+   * resolves; without a handler, it exits right away.
+   *
+   * @param handler The handler.
+   */
+  setCloseHandler(handler: (() => unknown) | null): this;
+  /**
+   * Sets how the manager starts and closes the gateway shards of this shard, for `manager.startShard` & co.
+   *
+   * @param handler Starts or closes a gateway shard, resolving once done.
+   */
+  setShardHandler(handler: ShardHandler | null): this;
+}
+//#endregion
+//#region src/network/Connection.d.ts
+/**
+ * Where a proxy accepts peer connections.
+ */
+interface PeerAddress {
+  host: string;
+  port: number;
+}
+//#endregion
+//#region src/ShardManagerProxy.d.ts
+/**
+ * A manager a proxy connects to.
+ */
+export interface ProxyManagerAddress {
+  host: string;
+  port: number;
+  /**
+   * The manager's token, when it differs from the proxy's `token`.
+   */
+  token?: string;
+  /**
+   * The TLS options of this manager, when they differ from the proxy's `tls`.
+   */
+  tls?: boolean | ConnectionOptions;
+}
+/**
+ * How a proxy accepts connections from other proxies, to carry the messages between their shards directly.
+ */
+export interface ProxyPeerOptions {
+  /**
+   * The port to listen on, `0` for any.
+   */
+  port: number;
+  host?: string;
+  /**
+   * The host other proxies reach this one at.
+   *
+   * @default host ?? os.hostname()
+   */
+  advertise?: string;
+  /**
+   * The shared secret of the peers.
+   *
+   * @default the proxy's token
+   */
+  token?: string;
+  /**
+   * The TLS options of the peer server (`key`, `cert`, ...). Left out, peers talk plain TCP.
+   */
+  tls?: TlsOptions;
+  /**
+   * The TLS options to connect to other peers with, `true` for the defaults.
+   */
+  connectTls?: boolean | ConnectionOptions;
+}
+/**
+ * The options of a {@link ShardManagerProxy}.
+ */
+export interface ShardManagerProxyOptions {
+  /**
+   * The managers to connect to, as `{ host, port }` or `"host:port"`.
+   */
+  managers: readonly (ProxyManagerAddress | string)[];
+  /**
+   * How the proxy serves its managers:
+   *
+   * - `"failover"`: one at a time, the first reachable, failing over to the next ones when it loses it.
+   * - `"all"`: all of them at once, sharing its capacity, e.g. managers each running part of the gateway shards.
+   *
+   * @default "failover"
+   */
+  mode?: "failover" | "all";
+  /**
+   * The shared secret of the managers' {@link NetworkStrategy}.
+   */
+  token: string;
+  /**
+   * The name of the proxy, unique across the proxies of a manager. It finds its shards back under it after a
+   * reconnection.
+   *
+   * @default `${os.hostname()}:${process.pid}`
+   */
+  name?: string;
+  /**
+   * How many shards the proxy runs at most, across all its managers.
+   *
+   * @default os.availableParallelism()
+   */
+  capacity?: number;
+  /**
+   * How the proxy spawns its shards locally: a strategy, or the name of a registered one.
+   *
+   * @default "fork"
+   */
+  strategy?: ChannelStrategy | string;
+  strategyOptions?: unknown;
+  /**
+   * Connects to the managers with TLS: `true` with the default options, or the options (`ca`, `servername`, ...).
+   *
+   * @default false
+   */
+  tls?: boolean | ConnectionOptions;
+  /**
+   * What the proxy does with the shards of a manager it loses: keep them running and reconnect (the manager takes
+   * them back within its `reconnectGrace`), or stop them.
+   *
+   * @default "keep"
+   */
+  managerLoss?: "keep" | "exit";
+  /**
+   * How long to wait between connection attempts, in milliseconds.
+   *
+   * @default 5_000
+   */
+  reconnectDelay?: number;
+  /**
+   * Whether to carry the messages and requests between shards of this proxy (and, with `peer`, of other proxies)
+   * without going through the manager. It decodes their packets with the manager's message handler and
+   * transformers, built from the registry: custom ones must be registered in the proxy too.
+   *
+   * @default true
+   */
+  localRouting?: boolean;
+  /**
+   * Accepts connections from other proxies, and connects to them, to carry the messages between shards of different
+   * proxies directly. Needs `localRouting`.
+   */
+  peer?: ProxyPeerOptions;
+  heartbeat?: {
+    interval?: number;
+    timeout?: number;
+  };
+}
+/**
+ * The events of a {@link ShardManagerProxy}.
+ */
+export interface ShardManagerProxyEvents {
+  /**
+   * The proxy connected to a manager.
+   */
+  connect: [manager: ProxyManagerAddress];
+  /**
+   * The proxy lost a manager.
+   */
+  disconnect: [manager: ProxyManagerAddress, error: Error | undefined];
+  /**
+   * A manager rejected the proxy, e.g. for a wrong token.
+   */
+  reject: [manager: ProxyManagerAddress, reason: string];
+  spawn: [context: ShardContext];
+  exit: [context: ShardContext, code: number | null];
+  /**
+   * A peer connection to another proxy opened.
+   */
+  peerConnect: [name: string];
+  peerDisconnect: [name: string];
+  error: [error: unknown];
+}
+/**
+ * Runs shards for remote {@link ShardManager}s using a {@link NetworkStrategy}: the sharder RFC's
+ * `ShardManagerProxy`. It spawns them locally with its own strategy, carries their messages to their manager, and
+ * carries the messages between shards of the same manager directly, locally or through peer proxies.
+ *
+ * @example
+ * ```ts
+ * const proxy = new ShardManagerProxy({
+ *   managers: ["manager.internal:7000", "manager-backup.internal:7000"],
+ *   token: process.env.SHARDER_TOKEN!,
+ *   tls: { ca: readFileSync("ca.pem") },
+ *   strategy: new ForkStrategy({ path: "./bot.js" }),
+ *   capacity: 8,
+ *   peer: { port: 7001 },
+ * });
+ * await proxy.connect();
+ * ```
+ */
+export declare class ShardManagerProxy extends EventEmitter<ShardManagerProxyEvents> {
+  #private;
+  readonly name: string;
+  readonly capacity: number;
+  readonly strategy: ChannelStrategy;
+  readonly managers: readonly ProxyManagerAddress[];
+  readonly mode: "failover" | "all";
+  constructor(options: ShardManagerProxyOptions);
+  /**
+   * The managers the proxy is connected to.
+   */
+  get connectedManagers(): ProxyManagerAddress[];
+  /**
+   * The manager the proxy is connected to in `"failover"` mode, `null` while it is not.
+   */
+  get manager(): ProxyManagerAddress | null;
+  /**
+   * The contexts of the shards the proxy runs.
+   */
+  get shards(): ShardContext[];
+  /**
+   * Where other proxies reach this one, once connected with `peer`.
+   */
+  get peerAddress(): PeerAddress | null;
+  /**
+   * The names of the proxies this one has a peer connection with.
+   */
+  get peers(): string[];
+  /**
+   * Connects to the managers, and keeps reconnecting whenever a connection is lost, until
+   * {@link ShardManagerProxy.destroy}. Resolves once connected to a first manager.
+   */
+  connect(): Promise<void>;
+  /**
+   * Stops every shard, and disconnects for good.
+   */
+  destroy(): Promise<void>;
+}
+//#endregion
+//#region src/strategies/ProcessStrategy.d.ts
+/**
+ * The options shared by the strategies spawning processes.
+ */
+export interface ProcessStrategyOptions {
+  /**
+   * The arguments passed to the shard's script.
+   */
+  args?: readonly string[];
+  /**
+   * The arguments passed to Node.js, e.g. `["--enable-source-maps"]`.
+   */
+  execArgv?: readonly string[];
+  /**
+   * Extra environment variables, on top of the manager's own.
+   */
+  env?: NodeJS.ProcessEnv;
+}
+/**
+ * The base of {@link ForkStrategy} and {@link ClusterStrategy}: a shard is a process with an IPC channel, using the
+ * `advanced` serialization so binary data (and {@link RawMessageHandler}'s values) survive it.
+ */
+export declare abstract class ProcessStrategy implements ChannelStrategy {
+  abstract readonly name: string;
+  spawn(context: ShardContext, events: ShardTransportEvents, options: SpawnOptions): ShardTransport;
+  protected abstract createProcess(context: ShardContext, options: SpawnOptions): ChildProcess | Worker$1;
+}
+//#endregion
+//#region src/strategies/ClusterStrategy.d.ts
+/**
+ * The options of {@link ClusterStrategy}.
+ */
+export interface ClusterStrategyOptions extends ProcessStrategyOptions {
+  /**
+   * The script every shard runs. Defaults to the manager's own script, so one file handles both sides: check
+   * `cluster.isPrimary` to tell them apart.
+   */
+  path?: string | URL;
+}
+/**
+ * Spawns every shard as a `node:cluster` worker. Unlike {@link ForkStrategy}, the shards share the ports they listen
+ * on, and the primary balances the connections between them.
+ */
+export declare class ClusterStrategy extends ProcessStrategy {
+  readonly name = "cluster";
+  readonly options: ClusterStrategyOptions;
+  constructor(options?: ClusterStrategyOptions);
+  protected createProcess(context: ShardContext, options: SpawnOptions): Worker$1;
+}
+//#endregion
+//#region src/strategies/ForkStrategy.d.ts
+/**
+ * The options of {@link ForkStrategy}.
+ */
+export interface ForkStrategyOptions extends ProcessStrategyOptions {
+  /**
+   * The script every shard runs. Defaults to the manager's own script: check {@link ShardClient.context} to tell the
+   * manager and the shards apart.
+   */
+  path?: string | URL;
+}
+/**
+ * Spawns every shard as a child process with `child_process.fork`. The default strategy.
+ *
+ * @remarks
+ * Every shard is its own process: ports opened by the shards (e.g. an HTTP interactions server) must differ.
+ */
+export declare class ForkStrategy extends ProcessStrategy {
+  readonly name = "fork";
+  readonly options: ForkStrategyOptions;
+  constructor(options?: ForkStrategyOptions);
+  protected createProcess(context: ShardContext, options: SpawnOptions): ChildProcess;
+}
+//#endregion
+//#region src/strategies/NetworkStrategy.d.ts
+/**
+ * The options of {@link NetworkStrategy}.
+ */
+export interface NetworkStrategyOptions {
+  /**
+   * The port to listen on for proxies.
+   */
+  port: number;
+  host?: string;
+  /**
+   * The shared secret proxies authenticate with.
+   */
+  token: string;
+  /**
+   * The ID of the manager, which proxies serving several managers tell them apart by. Defaults to a random UUID.
+   */
+  id?: string;
+  /**
+   * The TLS options (`key`, `cert`, ...) to encrypt the connections, recommended. Left out, the connections are plain
+   * TCP: only for trusted networks.
+   */
+  tls?: TlsOptions;
+  /**
+   * How long a proxy that lost its connection has to come back before its shards are deemed dead and spawned
+   * elsewhere, in milliseconds.
+   *
+   * @default 30_000
+   */
+  reconnectGrace?: number;
+  heartbeat?: {
+    /**
+     * @default 15_000
+     */
+    interval?: number;
+    /**
+     * @default 45_000
+     */
+    timeout?: number;
+  };
+}
+/**
+ * A proxy connected to a {@link NetworkStrategy}.
+ */
+export interface ProxyInfo {
+  name: string;
+  /**
+   * The address the proxy connected from.
+   */
+  host: string | null;
+  /**
+   * How many shards it runs at most, across all its managers.
+   */
+  capacity: number;
+  /**
+   * How many more shards it takes, across all its managers.
+   */
+  available: number;
+  /**
+   * How many shards it runs for this manager.
+   */
+  load: number;
+  /**
+   * Where other proxies reach it, when it accepts peers.
+   */
+  peer: PeerAddress | null;
+}
+/**
+ * Spawns shards on other machines, through {@link ShardManagerProxy}s connecting to the manager: the sharder RFC's
+ * network strategy.
+ *
+ * @remarks
+ * Each spawn goes to the connected proxy with the most room, as the proxies report it across all the managers they
+ * serve; without room, it waits for a proxy, or for the spawn timeout. A proxy losing its connection has
+ * `reconnectGrace` to come back with its shards, after which they are spawned elsewhere; its stale shards are killed
+ * when it comes back later. Proxies coming back are not rebalanced: they take the next spawns.
+ *
+ * The strategy keeps the proxies accepting peers informed of which proxy runs which ready shard, so they carry the
+ * messages between their shards directly.
+ */
+export declare class NetworkStrategy implements ChannelStrategy {
+  #private;
+  readonly name = "network";
+  readonly options: NetworkStrategyOptions;
+  /**
+   * The ID of the manager, see {@link NetworkStrategyOptions.id}.
+   */
+  readonly id: string;
+  constructor(options: NetworkStrategyOptions);
+  /**
+   * The proxies, connected or within their reconnect grace.
+   */
+  get proxies(): ProxyInfo[];
+  /**
+   * The port the strategy listens on, once initialized.
+   */
+  get port(): number | null;
+  /**
+   * Drops the connection of a proxy, which reconnects: its shards are kept if it comes back within the grace.
+   *
+   * @param name The name of the proxy.
+   * @returns Whether a proxy of that name was connected.
+   */
+  disconnectProxy(name: string): boolean;
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  spawn(context: ShardContext, events: ShardTransportEvents, options: SpawnOptions): ShardTransport;
+}
+//#endregion
+//#region src/strategies/WorkerStrategy.d.ts
+/**
+ * The options of {@link WorkerStrategy}.
+ */
+export interface WorkerStrategyOptions {
+  /**
+   * The script every shard runs.
+   */
+  path: string | URL;
+  /**
+   * Extra options of the `Worker`, e.g. its `resourceLimits`. `workerData` is reserved for the shard's context.
+   */
+  worker?: Omit<WorkerOptions, "workerData">;
+}
+/**
+ * Spawns every shard as a worker thread of the manager's process. Messages are the fastest, but the shards share the
+ * process: a crash of the process stops them all.
+ */
+export declare class WorkerStrategy implements ChannelStrategy {
+  readonly name = "worker";
+  readonly options: WorkerStrategyOptions;
+  constructor(options: WorkerStrategyOptions);
+  spawn(context: ShardContext, events: ShardTransportEvents, options: SpawnOptions): ShardTransport;
+}
+//#endregion
+//#region src/strategies/registry.d.ts
+/**
+ * Registers a strategy under a name, so managers and proxies can be given its name, like the built-in `"fork"`,
+ * `"cluster"`, `"worker"`, and `"network"`.
+ *
+ * @param name The name of the strategy.
+ * @param factory Builds the strategy from the `strategyOptions`.
+ */
+export declare function registerStrategy<Options>(name: string, factory: (options: Options) => ChannelStrategy): void;
+/**
+ * Resolves a strategy, or the name of a registered one.
+ *
+ * @param strategy The strategy, or its name.
+ * @param options The options of a named strategy.
+ */
+export declare function resolveStrategy(strategy: ChannelStrategy | string, options?: unknown): ChannelStrategy;
+//#endregion
+//#region src/util/commands.d.ts
+/**
+ * A request naming a command, the optional command layer on top of raw requests.
+ */
+export interface CommandRequest<Name extends string = string, Data = unknown> {
+  command: Name;
+  data: Data;
+}
+/**
+ * The commands a handler answers, by name.
+ */
+export type Commands<Context = unknown> = Record<string, (data: any, context: Context & {
+  signal: AbortSignal;
+}) => unknown>;
+/**
+ * The reply of a command.
+ */
+export type CommandReply<C extends Commands<any>, Name extends keyof C> = Awaited<ReturnType<C[Name]>>;
+/**
+ * Builds a request handler answering {@link CommandRequest}s: the sharder stays raw data (as the RFC settled), and
+ * this is the optional, typed layer on top.
+ *
+ * @param commands The commands, by name.
+ * @example
+ * ```ts
+ * const commands = {
+ *   guildCount: () => guilds.size,
+ *   guild: (id: string) => guilds.get(id) ?? null,
+ * } satisfies Commands;
+ *
+ * shard.setRequestHandler(createCommandHandler(commands));
+ * const counts = await manager.broadcastRequest<CommandReply<typeof commands, "guildCount">>(
+ *   command<typeof commands>("guildCount"),
+ * );
+ * ```
+ */
+export declare function createCommandHandler<Context>(commands: Commands<Context>): RequestHandler<Context>;
+/**
+ * Builds a {@link CommandRequest}.
+ *
+ * @param name The name of the command.
+ * @param data Its argument.
+ */
+export declare function command<C extends Commands<any>, Name extends keyof C & string = keyof C & string>(name: Name, ...data: Parameters<C[Name]>[0] extends undefined ? [] : [data: Parameters<C[Name]>[0]]): CommandRequest<Name, Parameters<C[Name]>[0]>;
+//#endregion
+export { type BroadcastRequestOptions, type ControlRequest, type Err, type GatewayInformation, type Ok, type RecommendedShardCountOptions, type RequestHandler, type RequestOptions, Result, type ShardTarget, type SupervisorOptions, type SupervisorStrategy };
+//# sourceMappingURL=index.d.ts.map