chapterjs 0.1.2 → 0.2.0

package/dist/events/router.d.ts

@@ -0,0 +1,46 @@
+import { type CacheLimits } from '../cache/cache.js';
+import type { GatewayDispatchEventName, GatewayDispatchEvents } from '../discord/types/gateway-events.js';
+import type { Context } from '../structures/context.js';
+import type { EventHandler } from './declaration.js';
+import { type EventContexts, type EventName } from './registry.js';
+/** A handler, with the file and the export it comes from (to report its errors). */
+export interface LoadedEvent {
+    file: string;
+    export: string;
+    event: EventHandler;
+}
+/**
+ * The intents the bot needs: Guilds, which keeps the cache of servers,
+ * roles and channels up to date, plus the ones of the events listened to
+ * and of the options their files turned on.
+ */
+export declare function intentsFor(events: Iterable<LoadedEvent>): number;
+/**
+ * How much the bot remembers for a set of files: the default, raised by
+ * the events that need more to give all they can.
+ */
+export declare function limitsFor(events: Iterable<LoadedEvent>): CacheLimits;
+/** The intents one file needs, given the options it passed. */
+export declare function intentsOf(event: EventHandler): number;
+export declare class EventRouter {
+    #private;
+    /**
+     * `onError`: a handler threw. `onSkipped`: an event could not be given
+     * to its handlers, because Discord refused what they are promised.
+     */
+    constructor(onError: (file: string, error: unknown) => void, onSkipped?: (event: EventName, error: unknown) => void);
+    /** Replaces every handler (after a load or a reload). */
+    set(events: Iterable<LoadedEvent>): void;
+    /**
+     * Reads what the event is about to remove from the cache. Returns what
+     * `dispatch` needs back; nothing is read for events nobody listens to.
+     */
+    before<E extends GatewayDispatchEventName>(ctx: Context, event: E, data: GatewayDispatchEvents[E]): unknown[] | undefined;
+    /** Runs the handlers of a gateway event, once the cache reflects it. */
+    dispatch<E extends GatewayDispatchEventName>(ctx: Context, event: E, data: GatewayDispatchEvents[E], extra: {
+        joined: boolean;
+        before: unknown[] | undefined;
+    }): void;
+    /** Runs the handlers of an event with what they receive. */
+    emit<Name extends EventName>(name: Name, context: EventContexts[Name]): void;
+}

package/dist/events/router.js

@@ -0,0 +1,133 @@
+// Delivers gateway events to the handlers of the project.
+import { DEFAULT_CACHE_LIMITS } from '../cache/cache.js';
+import { GatewayIntent } from '../discord/intents.js';
+import { audienceLocale, translation } from '../messages/translate.js';
+import { EVENTS } from './registry.js';
+/**
+ * The intents the bot needs: Guilds, which keeps the cache of servers,
+ * roles and channels up to date, plus the ones of the events listened to
+ * and of the options their files turned on.
+ */
+export function intentsFor(events) {
+    let intents = GatewayIntent.Guilds;
+    for (const { event } of events)
+        intents |= intentsOf(event);
+    return intents;
+}
+/**
+ * How much the bot remembers for a set of files: the default, raised by
+ * the events that need more to give all they can.
+ */
+export function limitsFor(events) {
+    const limits = { ...DEFAULT_CACHE_LIMITS };
+    for (const { event } of events) {
+        const needed = EVENTS[event.name].remembers ?? {};
+        for (const kind of Object.keys(needed)) {
+            limits[kind] = Math.max(limits[kind], needed[kind]);
+        }
+    }
+    return limits;
+}
+/** The intents one file needs, given the options it passed. */
+export function intentsOf(event) {
+    const { intents } = EVENTS[event.name];
+    return typeof intents === 'function'
+        ? intents(event.options)
+        : intents;
+}
+/** For each gateway event, the events it may turn into. */
+const BY_GATEWAY_EVENT = new Map();
+for (const [name, definition] of Object.entries(EVENTS)) {
+    for (const source of definition.sources) {
+        const list = BY_GATEWAY_EVENT.get(source.on) ?? [];
+        list.push({ name: name, ...source });
+        BY_GATEWAY_EVENT.set(source.on, list);
+    }
+}
+export class EventRouter {
+    #handlers = new Map();
+    #onError;
+    #onSkipped;
+    /**
+     * `onError`: a handler threw. `onSkipped`: an event could not be given
+     * to its handlers, because Discord refused what they are promised.
+     */
+    constructor(onError, onSkipped = () => { }) {
+        this.#onError = onError;
+        this.#onSkipped = onSkipped;
+    }
+    /** Replaces every handler (after a load or a reload). */
+    set(events) {
+        const handlers = new Map();
+        for (const loaded of events) {
+            const list = handlers.get(loaded.event.name) ?? [];
+            list.push(loaded);
+            handlers.set(loaded.event.name, list);
+        }
+        this.#handlers = handlers;
+    }
+    /**
+     * Reads what the event is about to remove from the cache. Returns what
+     * `dispatch` needs back; nothing is read for events nobody listens to.
+     */
+    before(ctx, event, data) {
+        const sources = BY_GATEWAY_EVENT.get(event);
+        if (!sources)
+            return undefined;
+        return sources.map(source => source.before && this.#handlers.has(source.name)
+            ? source.before(ctx, data)
+            : undefined);
+    }
+    /** Runs the handlers of a gateway event, once the cache reflects it. */
+    dispatch(ctx, event, data, extra) {
+        const sources = BY_GATEWAY_EVENT.get(event);
+        if (!sources)
+            return;
+        sources.forEach((source, index) => {
+            if (!this.#handlers.has(source.name))
+                return;
+            const deliver = (prepared) => {
+                const built = source.build(ctx, data, {
+                    joined: extra.joined,
+                    before: extra.before?.[index],
+                    prepared,
+                });
+                if (!built)
+                    return;
+                // One gateway event can be several occurrences (messages deleted
+                // together, emojis changed at once): each is delivered.
+                const occurrences = Array.isArray(built)
+                    ? built
+                    : [built];
+                const guildOf = EVENTS[source.name].guildOf;
+                for (const context of occurrences) {
+                    // `t` speaks the language of the server the event happened in.
+                    const guild = guildOf?.(context);
+                    this.emit(source.name, {
+                        ...context,
+                        ...translation(ctx, audienceLocale({ guild })),
+                    });
+                }
+            };
+            const preparing = source.prepare?.(ctx, data);
+            if (!preparing)
+                return deliver();
+            preparing.then(deliver, (error) => this.#onSkipped(source.name, error));
+        });
+    }
+    /** Runs the handlers of an event with what they receive. */
+    emit(name, context) {
+        const handlers = this.#handlers.get(name);
+        if (!handlers)
+            return;
+        // Handlers can't change what the others receive.
+        const frozen = Object.freeze({ ...context });
+        const accepts = EVENTS[name].accepts;
+        for (const { file, event } of handlers) {
+            if (accepts && !accepts(frozen, event.options))
+                continue;
+            // One handler failing never stops the others, nor the bot.
+            new Promise(resolve => resolve(event.handler(frozen))).catch((error) => this.#onError(file, error));
+        }
+    }
+}

package/dist/gateway/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Discord closed the connection for a reason that reconnecting can't fix:
+ * something has to change before the bot can connect.
+ * @see https://docs.discord.com/developers/topics/opcodes-and-status-codes#gateway-gateway-close-event-codes
+ */
+export declare class GatewayFatalError extends Error {
+    readonly name = "GatewayFatalError";
+    /** The close code Discord gave. */
+    readonly code: number;
+    constructor(code: number, intents: number);
+}
+/** The bot started too many sessions today: Discord would reset its token. */
+export declare class SessionLimitError extends Error {
+    readonly name = "SessionLimitError";
+    /** When the bot can connect again. */
+    readonly resetAt: Date;
+    constructor(needed: number, remaining: number, resetAfter: number);
+}

package/dist/gateway/errors.js

@@ -0,0 +1,47 @@
+import { GatewayCloseCode } from '../discord/codes.js';
+import { intentNames, PRIVILEGED_INTENTS } from '../discord/intents.js';
+/**
+ * Discord closed the connection for a reason that reconnecting can't fix:
+ * something has to change before the bot can connect.
+ * @see https://docs.discord.com/developers/topics/opcodes-and-status-codes#gateway-gateway-close-event-codes
+ */
+export class GatewayFatalError extends Error {
+    name = 'GatewayFatalError';
+    /** The close code Discord gave. */
+    code;
+    constructor(code, intents) {
+        super(explain(code, intents));
+        this.code = code;
+    }
+}
+function explain(code, intents) {
+    switch (code) {
+        case GatewayCloseCode.AuthenticationFailed:
+            return 'Discord refused the bot token. Copy it again from the Developer Portal (your application → Bot → Reset Token) into BOT_TOKEN in your .env file.';
+        case GatewayCloseCode.DisallowedIntents: {
+            const privileged = intentNames(intents).filter(name => PRIVILEGED_INTENTS.includes(name));
+            return `Discord refused the connection: the bot uses privileged intents (${privileged.join(', ') || 'none found'}) that are not enabled. Enable them in the Developer Portal: your application → Bot → Privileged Gateway Intents.`;
+        }
+        case GatewayCloseCode.InvalidIntents:
+            return 'Discord refused the intents sent by the framework. This is a bug in ChapterJS: please report it.';
+        case GatewayCloseCode.ShardingRequired:
+            return 'The bot is in too many servers for a single connection: it must use more shards.';
+        case GatewayCloseCode.InvalidShard:
+            return 'Discord refused the shard of this connection: the number of shards is not the one Discord expects for this bot.';
+        case GatewayCloseCode.InvalidApiVersion:
+            return 'Discord no longer accepts the gateway version this version of ChapterJS speaks: update ChapterJS.';
+        default:
+            return `Discord closed the connection for good (close code ${code}).`;
+    }
+}
+/** The bot started too many sessions today: Discord would reset its token. */
+export class SessionLimitError extends Error {
+    name = 'SessionLimitError';
+    /** When the bot can connect again. */
+    resetAt;
+    constructor(needed, remaining, resetAfter) {
+        const resetAt = new Date(Date.now() + resetAfter);
+        super(`The bot needs to start ${needed} session(s) but Discord only allows ${remaining} more until ${resetAt.toLocaleString()}. Going over that limit makes Discord reset the bot token, so the bot is not started. This usually means it was restarted too many times: wait, then start it again.`);
+        this.resetAt = resetAt;
+    }
+}

package/dist/gateway/gateway.d.ts

@@ -0,0 +1,64 @@
+import type { GatewayOpcode } from '../discord/codes.js';
+import type { Snowflake } from '../discord/types/common.js';
+import type { RawGatewayPresenceUpdate } from '../discord/types/gateway-events.js';
+import type { Rest } from '../rest/rest.js';
+import { type IdentifyGate } from './identify-queue.js';
+import { Shard, type ShardEvent, type ShardOptions } from './shard.js';
+export interface GatewayOptions {
+    rest: Rest;
+    token: string;
+    intents: number;
+    presence?: RawGatewayPresenceUpdate | undefined;
+    /**
+     * Which shards this process runs, out of how many. By default: all of
+     * them, as many as Discord recommends. A layer that spreads shards over
+     * several processes gives each process its share.
+     */
+    shards?: {
+        ids: readonly number[];
+        count: number;
+    };
+    /**
+     * Decides when a shard may identify. By default: a queue for the shards
+     * of this process. Processes sharing a bot must share one gate.
+     */
+    identifyGate?: IdentifyGate;
+    onDispatch: ShardOptions['onDispatch'];
+    onEvent?: (event: ShardEvent) => void;
+    /** Only tests change these. */
+    backoff?: ShardOptions['backoff'];
+    identifyInterval?: number;
+}
+/**
+ * The shard that receives the events of a server:
+ * `(guild_id >> 22) % num_shards`.
+ * @see https://docs.discord.com/developers/events/gateway#sharding-sharding-formula
+ */
+export declare function shardIdFor(guildId: Snowflake, shardCount: number): number;
+export declare class Gateway {
+    #private;
+    constructor(options: GatewayOptions);
+    /** How many shards the bot is split into, across every process. */
+    get shardCount(): number;
+    /** The shards this process runs. */
+    get shards(): ReadonlyMap<number, Shard>;
+    /** The average heartbeat latency of the shards, in ms; `null` at first. */
+    get ping(): number | null;
+    /**
+     * Connects every shard of this process, and resolves once they are all
+     * ready. Rejects (and closes them all) if Discord refuses the connection.
+     */
+    connect(): Promise<void>;
+    /**
+     * Changes the presence of the bot on every shard of this process: sent
+     * now when Discord's limit allows it, and carried by every session
+     * started later.
+     */
+    setPresence(presence: RawGatewayPresenceUpdate): void;
+    /** The shard of this process that handles a server, if it runs here. */
+    shardFor(guildId: Snowflake): Shard | undefined;
+    /** Sends an event to Discord through one shard. */
+    send(shardId: number, op: GatewayOpcode, data: unknown): Promise<void>;
+    /** Closes every connection: the bot goes offline right away. */
+    close(): Promise<void>;
+}

package/dist/gateway/gateway.js

@@ -0,0 +1,117 @@
+// Every connection of the bot to the Discord gateway: how many shards,
+// when each one may identify, and one place to listen to them all.
+// https://docs.discord.com/developers/events/gateway#sharding
+import { GetGatewayBot } from '../discord/endpoints.js';
+import { SessionLimitError } from './errors.js';
+import { IdentifyQueue } from './identify-queue.js';
+import { Shard } from './shard.js';
+/**
+ * The shard that receives the events of a server:
+ * `(guild_id >> 22) % num_shards`.
+ * @see https://docs.discord.com/developers/events/gateway#sharding-sharding-formula
+ */
+export function shardIdFor(guildId, shardCount) {
+    return Number((BigInt(guildId) >> 22n) % BigInt(shardCount));
+}
+export class Gateway {
+    #options;
+    #shards = new Map();
+    #shardCount = 0;
+    #started = false;
+    /** The presence every session starts with. */
+    #presence;
+    constructor(options) {
+        this.#options = options;
+        this.#presence = options.presence;
+    }
+    /** How many shards the bot is split into, across every process. */
+    get shardCount() {
+        return this.#shardCount;
+    }
+    /** The shards this process runs. */
+    get shards() {
+        return this.#shards;
+    }
+    /** The average heartbeat latency of the shards, in ms; `null` at first. */
+    get ping() {
+        const pings = [...this.#shards.values()]
+            .map(shard => shard.ping)
+            .filter(ping => ping !== null);
+        if (pings.length === 0)
+            return null;
+        return Math.round(pings.reduce((sum, ping) => sum + ping, 0) / pings.length);
+    }
+    /**
+     * Connects every shard of this process, and resolves once they are all
+     * ready. Rejects (and closes them all) if Discord refuses the connection.
+     */
+    async connect() {
+        if (this.#started)
+            throw new Error('The gateway was already started.');
+        this.#started = true;
+        const options = this.#options;
+        // Not cached: the recommended number of shards changes as the bot grows.
+        const info = await options.rest.request(GetGatewayBot, []);
+        const count = options.shards?.count ?? info.shards;
+        const ids = options.shards?.ids ?? Array.from({ length: count }, (_, id) => id);
+        for (const id of ids) {
+            if (!Number.isInteger(id) || id < 0 || id >= count) {
+                throw new RangeError(`Shard ${id} does not exist: with ${count} shard(s), ids go from 0 to ${count - 1}.`);
+            }
+        }
+        const limit = info.session_start_limit;
+        if (limit.remaining < ids.length) {
+            throw new SessionLimitError(ids.length, limit.remaining, limit.reset_after);
+        }
+        this.#shardCount = count;
+        const identifyGate = options.identifyGate ??
+            new IdentifyQueue(limit.max_concurrency, options.identifyInterval);
+        for (const id of ids) {
+            this.#shards.set(id, new Shard({
+                id,
+                count,
+                token: options.token,
+                intents: options.intents,
+                url: info.url,
+                presence: this.#presence,
+                identifyGate,
+                onDispatch: options.onDispatch,
+                onEvent: options.onEvent,
+                backoff: options.backoff,
+            }));
+        }
+        try {
+            await Promise.all([...this.#shards.values()].map(shard => shard.connect()));
+        }
+        catch (error) {
+            await this.close();
+            throw error;
+        }
+    }
+    /**
+     * Changes the presence of the bot on every shard of this process: sent
+     * now when Discord's limit allows it, and carried by every session
+     * started later.
+     */
+    setPresence(presence) {
+        this.#presence = presence;
+        for (const shard of this.#shards.values())
+            shard.setPresence(presence);
+    }
+    /** The shard of this process that handles a server, if it runs here. */
+    shardFor(guildId) {
+        return this.#shards.get(shardIdFor(guildId, this.#shardCount));
+    }
+    /** Sends an event to Discord through one shard. */
+    async send(shardId, op, data) {
+        const shard = this.#shards.get(shardId);
+        if (!shard) {
+            throw new RangeError(`Shard ${shardId} does not run in this process.`);
+        }
+        await shard.send(op, data);
+    }
+    /** Closes every connection: the bot goes offline right away. */
+    async close() {
+        await Promise.all([...this.#shards.values()].map(shard => shard.close()));
+    }
+}

package/dist/gateway/identify-queue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decides when a shard may identify. Behind an interface because shards of
+ * the same bot may run in several processes, which then have to share one
+ * gate.
+ */
+export interface IdentifyGate {
+    /** Resolves when the shard may send its Identify. */
+    wait(shardId: number): Promise<void>;
+}
+/**
+ * How long Discord counts concurrent identifies for, in milliseconds.
+ * @see https://docs.discord.com/developers/events/gateway#rate-limiting
+ */
+export declare const IDENTIFY_INTERVAL = 5000;
+/**
+ * The default gate, for shards of one process. Shards are put in buckets by
+ * `shard_id % max_concurrency`; a bucket lets one shard identify every 5
+ * seconds, and different buckets don't wait for each other.
+ * @see https://docs.discord.com/developers/events/gateway#sharding-max-concurrency
+ */
+export declare class IdentifyQueue implements IdentifyGate {
+    #private;
+    constructor(maxConcurrency: number, interval?: number);
+    wait(shardId: number): Promise<void>;
+}

package/dist/gateway/identify-queue.js

@@ -0,0 +1,29 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+/**
+ * How long Discord counts concurrent identifies for, in milliseconds.
+ * @see https://docs.discord.com/developers/events/gateway#rate-limiting
+ */
+export const IDENTIFY_INTERVAL = 5000;
+/**
+ * The default gate, for shards of one process. Shards are put in buckets by
+ * `shard_id % max_concurrency`; a bucket lets one shard identify every 5
+ * seconds, and different buckets don't wait for each other.
+ * @see https://docs.discord.com/developers/events/gateway#sharding-max-concurrency
+ */
+export class IdentifyQueue {
+    #maxConcurrency;
+    #interval;
+    /** For each bucket: when its last waiting shard will have identified. */
+    #tails = new Map();
+    constructor(maxConcurrency, interval = IDENTIFY_INTERVAL) {
+        this.#maxConcurrency = Math.max(1, Math.floor(maxConcurrency));
+        this.#interval = interval;
+    }
+    wait(shardId) {
+        const key = shardId % this.#maxConcurrency;
+        const turn = this.#tails.get(key) ?? Promise.resolve();
+        // The next shard of the bucket goes one interval after this one.
+        this.#tails.set(key, turn.then(() => sleep(this.#interval)).then(() => undefined));
+        return turn;
+    }
+}

package/dist/gateway/shard.d.ts

@@ -0,0 +1,94 @@
+import { GatewayOpcode } from '../discord/codes.js';
+import type { GatewayDispatchEventName, GatewayDispatchEvents, RawGatewayPresenceUpdate } from '../discord/types/gateway-events.js';
+import type { IdentifyGate } from './identify-queue.js';
+export type ShardStatus = 
+/** Not started yet. */
+'idle'
+/** Opening the WebSocket, or waiting for Hello. */
+ | 'connecting'
+/** Waiting for its turn to identify, or for Ready. */
+ | 'identifying'
+/** Waiting for Discord to replay the events missed while disconnected. */
+ | 'resuming'
+/** Connected: events are flowing. */
+ | 'ready'
+/** Disconnected, about to try again. */
+ | 'reconnecting'
+/** Closed for good: by the bot, or by a fatal error. */
+ | 'closed';
+/** What happens to a shard, for whoever shows it to the developer. */
+export type ShardEvent = {
+    type: 'ready';
+    shardId: number;
+    resumed: boolean;
+} | {
+    type: 'disconnected';
+    shardId: number;
+    /** The close code, when the connection was closed with one. */
+    code: number | null;
+    /** Whether the session can be resumed without losing events. */
+    resumable: boolean;
+    /** In how many milliseconds the shard tries again. */
+    retryIn: number;
+} | {
+    type: 'fatal';
+    shardId: number;
+    error: Error;
+};
+export interface ShardOptions {
+    /** `[shard_id, num_shards]` of the Identify payload. */
+    id: number;
+    count: number;
+    token: string;
+    intents: number;
+    /** The WSS URL given by Get Gateway Bot. */
+    url: string;
+    /** The presence the bot has as soon as it is connected. */
+    presence?: RawGatewayPresenceUpdate | undefined;
+    /** Decides when this shard may identify. */
+    identifyGate: IdentifyGate;
+    /** Called for every event Discord dispatches, in order. */
+    onDispatch: <E extends GatewayDispatchEventName>(event: E, data: GatewayDispatchEvents[E], shardId: number) => void;
+    onEvent?: (event: ShardEvent) => void;
+    /** Milliseconds to wait before the nth try in a row. Only tests change it. */
+    backoff?: (attempt: number) => number;
+    /** The window of the presence update limit, in ms. Only tests change it. */
+    presenceWindow?: number | undefined;
+}
+export declare class Shard {
+    #private;
+    readonly id: number;
+    constructor(options: ShardOptions);
+    get status(): ShardStatus;
+    /**
+     * How long Discord took to acknowledge the last heartbeat, in
+     * milliseconds; `null` before the first one.
+     */
+    get ping(): number | null;
+    /**
+     * Connects, and resolves once Discord said the shard is ready. Rejects if
+     * Discord refuses the connection for good. After that the shard stays
+     * connected by itself.
+     */
+    connect(): Promise<void>;
+    /**
+     * Sends an event to Discord, once the shard is ready and the send limit
+     * allows it.
+     * @see https://docs.discord.com/developers/events/gateway-events#send-events
+     */
+    send(op: GatewayOpcode, data: unknown): Promise<void>;
+    /**
+     * Changes the presence of the bot on this shard. It is sent right away
+     * when the shard is ready and Discord's limit allows it, otherwise as
+     * soon as one of them does (only the latest presence is sent then); a
+     * session started later identifies with it.
+     * @see https://docs.discord.com/developers/events/gateway-events#update-presence
+     */
+    setPresence(presence: RawGatewayPresenceUpdate): void;
+    /**
+     * Closes the connection for good. The session is ended, so the bot
+     * appears offline right away instead of staying online as a ghost.
+     * @see https://docs.discord.com/developers/events/gateway#initiating-a-disconnect
+     */
+    close(): Promise<void>;
+}