npm i @spectacles/gateway


The gateway to Discord.

by spec-tacles

0.12.1 (see all)License:MITTypeScript:Built-In
npm i @spectacles/gateway

Spectacles Gateway

Spawns shards and manages a bot's lifetime on the Discord WebSocket gateway.

Getting started

const { Cluster } = require('@spectacles/gateway');
const cluster = new Cluster('a token');

You've just spawned the recommended number of shards. If you want to use a custom or fixed shard count:

const { Cluster, Gateway } = require('@spectacles/gateway');
const gateway = Gateway.from('token', 30);

const cluster = new Cluster(gateway);

This will spawn 30 shards for the given token. Providing shard count isn't necessary after the first call.


The shard emits events in the form [event name], [data]. The cluster emits events in the form [event name], [data], [shard]. When using a cluster, events will only be emitted on shards that have event listeners. Available events:

  • open - WebSocket opened
  • close - WebSocket closures (follows the CloseEvent API)
  • error - proxied from the underlying WebSocket connection
  • send - before data is sent over the connection (emitted as unencoded packet, or buffer)
  • receive - data that is received from the connection (decoded prior to emission)
  • connect - explicit connections to the WebSocket (fired initially and upon any reconnections)
  • disconnect - explicit disconnections from the WebSocket (i.e. when the client requests a connection closure)
  • [Discord gateway event] - OP 0 data, keyed by t (only d is emitted)

For details about Discord Gateway events, check out their documentation.

shard.on('MESSAGE_CREATE', message => {
  // message = https://discordapp.com/developers/docs/resources/channel#message-object-message-structure



  • gateway: Gateway - the gateway session to use with the cluster
  • token: string - your token
  • shards: Map<number, Shard> - a map of your shard connections, keyed by shard id
  • constructor(token: string | Gateway)
  • spawn(shards: number | number[]) - spawn shards number of shards (if number), or spawn the specified shard IDs (if array)


  • static readonly ZLIB_SUFFIX: UInt8Array - the zlib suffix
  • gateway: Gateway - the gateway session to use with this shard
  • client: Client - the client of this shard
  • shard: number - this shard id
  • version: 6 - the gateway version to use (locked at 6)
  • constructor(token: string | Gateway, shard: number)
  • readonly seq: number - the current sequence
  • readonly session?: string - the current session identifier
  • readonly ws: WebSocket - the raw websocket
  • connect(): Promise<void> - connect to the gateway
  • disconnect(code?: number): Promise<void> - disconnect
  • reconnect(code?: number): Promise<void> - reconnect
  • identify(pk?: Partial<Identify>): Promise<void> - identify
  • resume(): void - resume the session
  • heartbeat(): void - send a heartbeat
  • receive(data: WebSocket.Data): void - handle packets received
  • send(opOrPK: number | buffer | Payload | string, d?: any): void - send data to the gateway
    • send(pk: Buffer) - just send a buffer
    • send(pk: Payload) - send a pre-formatted payload object
    • send(op: number | string, d: any) - send d to the gateway: if op is a number, send as that op; if op is a string, send as op 0 with op as t


Represents connection information for a token.

  • static tokens: Map<string, Gateway> - map of tokens to instantiated gateway instances; used to ensure singletons per token
  • static fetch(tokenOrGateway: string | Gateway): Gateway - fetches the gateway for a given token
  • constructor(token: string, shardCount?: number)
  • token: string - the token of this gateway
  • shards: number - total shard count of this token; recommended count is set if no value is provided
  • readonly url: string - the gateway URL to connect to
  • readonly sessionStartLimit: null | { total: number, remaining: number, resetAfter: Date } - information about the session start ratelimits
  • identify(shard: Shard, packet: Partial<Identify>): Promise<void> - identify with the given shard; attempts to resume if a session is available on the shard
  • fetch(force = false): Promise<this> - fetch gateway information; automatically called when connecting



GitHub Stars



3yrs ago








3yrs ago
No alternatives found
No tutorials found
Add a tutorial