Skip to content
GitHub

ShardContext

class in meocord/core Since 4.1.0

class ShardContext

Tells a service which shards its process runs, and calls a service method in every shard.

Inject it where the answer needs every shard, such as a total server count, or where one-off work must run in one process only. With process sharding each shard runs in its own process; otherwise one process runs every shard and call runs once, here.

Examples

TypeScript
@Service()
export class StatsService {
  constructor(private readonly shards: ShardContext, private readonly client: Client) {}

  guildCount() {
    return this.client.guilds.cache.size
  }

  async totalGuilds() {
    const results = await this.shards.call(StatsService, 'guildCount')
    return results.reduce((sum, result) => sum + (result.ok ? result.value : 0), 0)
  }
}

Members

constructor

new ShardContext(client: Client | undefined, runHere: ShardCallHandler)

Parameters

NameTypeDescription
clientClient | undefined

The bot's client, or undefined in a testing module, which runs as one process.

runHereShardCallHandler

Runs a service method in this process, given its class, or its name with process sharding.

count

get count(): number

How many shards the bot runs in all.

ids

get ids(): number[]

The ids of the shards this process runs. With process sharding, one id; otherwise every shard, once ready.

isPrimary

get isPrimary(): boolean

Whether this process should do one-off work: always with one process, and with process sharding only in the process running shard 0.

broadcastEval

broadcastEval<R, C = undefined>(
  fn: (client: Client, context: C) => R,
  context?: C,
): Promise<Awaited<R>[]>

Runs a function in every shard with discord.js's broadcastEval, or here with one process.

The function is converted to a string and evaluated in each shard, so it cannot use anything outside its parameters; a minified bundle can break it. Prefer call.

Parameters

NameTypeDescription
fn(client: Client, context: C) => R

The function, given each shard's client and context.

context?C

JSON passed to the function.

Returns

Promise<Awaited<R>[]>

Each process's result.

call

call<T, M extends MethodName<T>>(
  service: abstract new (...args: any[]) => T,
  method: M,
  ...args: JsonArgs<MethodArgs<T, M>>
): Promise<ShardCallResult<Jsonified<MethodResult<T, M>>>[]>

Calls a service method in every process, each resolving the service from its own container, and collects one result per process.

With process sharding that is one result per shard; with one process, a single result listing every shard. The arguments and the result pass as JSON in every mode, one process and tests included, so a Date arrives as a string and a Map as {} wherever it runs, and a value JSON cannot carry, such as a BigInt, fails the call. A method whose params JSON would change, such as one taking a Date, cannot be called: the argument is refused, naming what to declare instead. An undefined argument arrives as undefined. A process that throws, lacks the service, or does not answer within 10 seconds gives an error result instead of failing the others.

Parameters

NameTypeDescription
serviceabstract new (...args: any[]) => T

The controller, the service, or a class a provider stands in for; each process resolves its own instance.

methodM

The method to call.

...argsJsonArgs<MethodArgs<T, M>>

The method's arguments.

Returns

Promise<ShardCallResult<Jsonified<MethodResult<T, M>>>[]>

One result per process, each value as JSON gives it back: see Jsonified.

See also