chapterjs 0.1.2 → 0.2.0

package/dist/rest/rate-limiter.js

@@ -0,0 +1,153 @@
+// Waits before each request so Discord's rate limits are never exceeded.
+// Limits are never hard coded: they are read from the headers of each
+// response, as the documentation asks.
+// https://docs.discord.com/developers/topics/rate-limits
+import { setTimeout as sleep } from 'node:timers/promises';
+import { GLOBAL_REQUESTS_PER_SECOND } from '../discord/api.js';
+export function readRateLimitHeaders(headers) {
+    const number = (name) => {
+        const value = headers.get(name);
+        if (value === null || value === '')
+            return null;
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    };
+    return {
+        bucket: headers.get('x-ratelimit-bucket'),
+        remaining: number('x-ratelimit-remaining'),
+        resetAfter: number('x-ratelimit-reset-after'),
+    };
+}
+/** The state of one bucket for one top-level resource. */
+class Bucket {
+    remaining = 1;
+    /** When `remaining` goes back to its maximum (ms since epoch). */
+    resetAt = 0;
+    /** Requests of this bucket run one at a time, in order. */
+    tail = Promise.resolve();
+    pending = 0;
+}
+export class RateLimiter {
+    /** `METHOD /path/template` → the bucket Discord said it belongs to. */
+    #bucketOfRoute = new Map();
+    /** `bucket:majorParameter` → its state. */
+    #buckets = new Map();
+    #globalLimit;
+    #onWait;
+    /** Start of the current one-second window of the global limit. */
+    #windowStart = 0;
+    #windowCount = 0;
+    /** Until when every request is paused after a global 429. */
+    #globalBlockedUntil = 0;
+    constructor(options = {}) {
+        this.#globalLimit = options.globalLimit ?? GLOBAL_REQUESTS_PER_SECOND;
+        this.#onWait = options.onWait;
+    }
+    #bucket(route, major) {
+        // Until Discord names the bucket of a route, the route is its own bucket.
+        const key = `${this.#bucketOfRoute.get(route) ?? route}:${major}`;
+        let bucket = this.#buckets.get(key);
+        if (!bucket) {
+            bucket = new Bucket();
+            this.#buckets.set(key, bucket);
+        }
+        return bucket;
+    }
+    async #wait(route, ms, global) {
+        if (ms <= 0)
+            return;
+        this.#onWait?.({ route, ms, global });
+        await sleep(ms);
+    }
+    /** Waits for a slot in the global limit, then takes it. */
+    async #takeGlobalSlot(route) {
+        for (;;) {
+            const now = Date.now();
+            if (now < this.#globalBlockedUntil) {
+                await this.#wait(route, this.#globalBlockedUntil - now, true);
+                continue;
+            }
+            if (now - this.#windowStart >= 1000) {
+                this.#windowStart = now;
+                this.#windowCount = 0;
+            }
+            if (this.#windowCount < this.#globalLimit) {
+                this.#windowCount++;
+                return;
+            }
+            await this.#wait(route, this.#windowStart + 1000 - now, true);
+        }
+    }
+    /**
+     * Runs `send` when the limits allow it. Requests of the same bucket run
+     * one after the other; different buckets run in parallel. `send` reports
+     * what the response said through `update` and returns its result, or a
+     * `RateLimitHit` to be run again after the delay Discord asked for.
+     */
+    async run(input, send) {
+        const { route, major } = input;
+        const bucket = this.#bucket(route, major);
+        const previous = bucket.tail;
+        let release;
+        bucket.tail = new Promise(resolve => (release = resolve));
+        bucket.pending++;
+        await previous;
+        try {
+            for (;;) {
+                // The bucket may have been renamed by an earlier response.
+                const current = this.#bucket(route, major);
+                const now = Date.now();
+                if (current.remaining <= 0 && now < current.resetAt) {
+                    await this.#wait(route, current.resetAt - now, false);
+                }
+                if (input.countsForGlobal)
+                    await this.#takeGlobalSlot(route);
+                const result = await send(headers => {
+                    if (headers.bucket !== null) {
+                        this.#bucketOfRoute.set(route, headers.bucket);
+                    }
+                    const target = this.#bucket(route, major);
+                    if (headers.remaining !== null)
+                        target.remaining = headers.remaining;
+                    if (headers.resetAfter !== null) {
+                        target.resetAt = Date.now() + headers.resetAfter * 1000;
+                    }
+                });
+                if (!isRateLimitHit(result))
+                    return result;
+                const ms = Math.ceil(result.retryAfter * 1000);
+                if (result.global || result.scope === 'global') {
+                    this.#globalBlockedUntil = Date.now() + ms;
+                }
+                else {
+                    const target = this.#bucket(route, major);
+                    target.remaining = 0;
+                    target.resetAt = Date.now() + ms;
+                }
+            }
+        }
+        finally {
+            bucket.pending--;
+            release();
+            this.#sweep();
+        }
+    }
+    /** Forgets buckets that are idle and reset, so memory doesn't grow. */
+    #sweep() {
+        if (this.#buckets.size < 1000)
+            return;
+        const now = Date.now();
+        for (const [key, bucket] of this.#buckets) {
+            if (bucket.pending === 0 && bucket.resetAt <= now) {
+                this.#buckets.delete(key);
+            }
+        }
+    }
+}
+const HIT = Symbol('rate limit hit');
+export function rateLimitHit(hit) {
+    return Object.assign(hit, { [HIT]: true });
+}
+function isRateLimitHit(value) {
+    return typeof value === 'object' && value !== null && HIT in value;
+}

package/dist/rest/rest.d.ts

@@ -0,0 +1,63 @@
+import { type Endpoint, type EndpointBody, type EndpointQuery, type EndpointResult, type PathParams } from '../discord/endpoint.js';
+/** A file to upload with a request. */
+/** The content of a file, or how to read it when it is sent. */
+export type RestFileData = Blob | Uint8Array | ArrayBuffer | string;
+export interface RestFile {
+    /** The name of the file, with its extension: `chart.png`. */
+    name: string;
+    /** The content, or a function that reads it when the request is sent. */
+    data: RestFileData | (() => Promise<RestFileData>);
+    /** The media type; guessed by Discord from the name when missing. */
+    contentType?: string;
+    /**
+     * The name of the form field. By default `files[n]`, which is what
+     * message attachments use.
+     * @see https://docs.discord.com/developers/reference#uploading-files
+     */
+    field?: string;
+}
+export interface RequestOptions<E extends Endpoint = Endpoint> {
+    body?: EndpointBody<E>;
+    query?: EndpointQuery<E>;
+    /**
+     * Why the action is taken, shown in the audit log of the server.
+     * @see https://docs.discord.com/developers/resources/audit-log#audit-log-entry-object
+     */
+    reason?: string;
+    files?: readonly RestFile[];
+    /**
+     * `false` for endpoints authenticated by a token in their path (webhooks,
+     * interactions): the bot token is not sent and the global limit is not
+     * counted.
+     */
+    auth?: boolean;
+    signal?: AbortSignal;
+}
+export interface RestOptions {
+    token: string;
+    /** The version of the framework, sent in the User-Agent header. */
+    version: string;
+    /** Where Discord is. Only tests change it. */
+    baseUrl?: string;
+    /** How many times a request is tried again after a 5xx or a network error. Default: 3. */
+    retries?: number;
+    /** How long to wait for a response, in milliseconds. Default: 15000. */
+    timeout?: number;
+    /** Requests per second for the whole bot. Default: 50. */
+    globalLimit?: number;
+    /** Called every time a request has to wait for a rate limit. */
+    onRateLimit?: (info: {
+        route: string;
+        ms: number;
+        global: boolean;
+    }) => void;
+}
+/** The interface features use to talk to Discord over HTTP. */
+export interface Rest {
+    request<E extends Endpoint>(endpoint: E, params: PathParams<E['path']>, options?: RequestOptions<E>): Promise<EndpointResult<E>>;
+}
+export declare class RestClient implements Rest {
+    #private;
+    constructor(options: RestOptions);
+    request<E extends Endpoint>(endpoint: E, params: PathParams<E['path']>, options?: RequestOptions<E>): Promise<EndpointResult<E>>;
+}

package/dist/rest/rest.js

@@ -0,0 +1,194 @@
+// The only place that sends HTTP requests to Discord.
+// https://docs.discord.com/developers/reference#http-api
+import { setTimeout as sleep } from 'node:timers/promises';
+import { API_BASE_URL, API_VERSION, AUDIT_LOG_REASON_MAX_LENGTH, userAgent, } from '../discord/api.js';
+import { HttpStatus } from '../discord/codes.js';
+import { fillPath, majorParameter, } from '../discord/endpoint.js';
+import { DiscordApiError, DiscordUnavailableError, InvalidTokenError, } from './errors.js';
+import { RateLimiter, rateLimitHit, readRateLimitHeaders, } from './rate-limiter.js';
+/** A 429 that is still there after this many tries is reported as an error. */
+const MAX_RATE_LIMIT_RETRIES = 5;
+function toQueryString(query) {
+    if (typeof query !== 'object' || query === null)
+        return '';
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        // Arrays are sent as several instances of the same parameter.
+        // https://docs.discord.com/developers/reference#array-query-strings
+        for (const item of Array.isArray(value) ? value : [value]) {
+            search.append(key, String(item));
+        }
+    }
+    const text = search.toString();
+    return text === '' ? '' : `?${text}`;
+}
+function toBlob(file, data) {
+    if (data instanceof Blob) {
+        return file.contentType
+            ? new Blob([data], { type: file.contentType })
+            : data;
+    }
+    const part = typeof data === 'string' || data instanceof ArrayBuffer
+        ? data
+        : new Uint8Array(data);
+    return new Blob([part], file.contentType ? { type: file.contentType } : {});
+}
+function encodeReason(reason) {
+    const trimmed = reason.trim();
+    if (trimmed === '') {
+        throw new TypeError('The reason is empty: leave it out or write one.');
+    }
+    if (trimmed.length > AUDIT_LOG_REASON_MAX_LENGTH) {
+        throw new RangeError(`The reason is ${trimmed.length} characters long: Discord accepts ${AUDIT_LOG_REASON_MAX_LENGTH} at most.`);
+    }
+    return encodeURIComponent(trimmed);
+}
+export class RestClient {
+    #token;
+    #baseUrl;
+    #userAgent;
+    #retries;
+    #timeout;
+    #limiter;
+    /** Set after a 401: no further request is sent with a refused token. */
+    #tokenRefused = false;
+    constructor(options) {
+        if (typeof options.token !== 'string' || options.token.trim() === '') {
+            throw new InvalidTokenError();
+        }
+        this.#token = options.token.trim().replace(/^Bot\s+/i, '');
+        this.#baseUrl = `${(options.baseUrl ?? API_BASE_URL).replace(/\/+$/, '')}/v${API_VERSION}`;
+        this.#userAgent = userAgent(options.version);
+        this.#retries = options.retries ?? 3;
+        this.#timeout = options.timeout ?? 15_000;
+        this.#limiter = new RateLimiter({
+            globalLimit: options.globalLimit,
+            onWait: options.onRateLimit,
+        });
+    }
+    async request(endpoint, params, options = {}) {
+        const auth = options.auth ?? true;
+        if (auth && this.#tokenRefused)
+            throw new InvalidTokenError();
+        const { method, path } = endpoint;
+        const url = this.#baseUrl + fillPath(path, params) + toQueryString(options.query);
+        const headers = { 'User-Agent': this.#userAgent };
+        if (auth)
+            headers.Authorization = `Bot ${this.#token}`;
+        if (options.reason !== undefined) {
+            headers['X-Audit-Log-Reason'] = encodeReason(options.reason);
+        }
+        // Built once: a retry sends the same thing.
+        let body;
+        if (options.files && options.files.length > 0) {
+            // A file read on demand is read once, now: a retry sends the same.
+            const blobs = await Promise.all(options.files.map(async (file) => toBlob(file, typeof file.data === 'function' ? await file.data() : file.data)));
+            const files = options.files;
+            const json = options.body === undefined ? undefined : JSON.stringify(options.body);
+            body = () => {
+                const form = new FormData();
+                if (json !== undefined)
+                    form.set('payload_json', json);
+                files.forEach((file, index) => {
+                    form.set(file.field ?? `files[${index}]`, blobs[index], file.name);
+                });
+                return form;
+            };
+        }
+        else if (options.body !== undefined) {
+            body = JSON.stringify(options.body);
+            headers['Content-Type'] = 'application/json';
+        }
+        const route = `${method} ${path}`;
+        let failures = 0;
+        let rateLimits = 0;
+        return this.#limiter.run({ route, major: majorParameter(path, params), countsForGlobal: auth }, async (update) => {
+            for (;;) {
+                let response;
+                try {
+                    response = await fetch(url, {
+                        method,
+                        headers,
+                        body: typeof body === 'function' ? body() : body,
+                        signal: options.signal
+                            ? AbortSignal.any([
+                                options.signal,
+                                AbortSignal.timeout(this.#timeout),
+                            ])
+                            : AbortSignal.timeout(this.#timeout),
+                    });
+                }
+                catch (error) {
+                    if (options.signal?.aborted)
+                        throw options.signal.reason;
+                    if (failures++ >= this.#retries) {
+                        throw new DiscordUnavailableError(method, path, error);
+                    }
+                    await sleep(250 * 2 ** (failures - 1));
+                    continue;
+                }
+                update(readRateLimitHeaders(response.headers));
+                if (response.status === HttpStatus.TooManyRequests) {
+                    const data = await readBody(response);
+                    const retryAfter = typeof data?.retry_after ===
+                        'number'
+                        ? data.retry_after
+                        : Number(response.headers.get('retry-after') ?? 1);
+                    if (rateLimits++ >= MAX_RATE_LIMIT_RETRIES) {
+                        throw new DiscordApiError({
+                            status: response.status,
+                            method,
+                            route: path,
+                            body: data,
+                        });
+                    }
+                    return rateLimitHit({
+                        retryAfter: Number.isFinite(retryAfter) ? retryAfter : 1,
+                        scope: response.headers.get('x-ratelimit-scope'),
+                        global: response.headers.get('x-ratelimit-global') === 'true' ||
+                            data?.global === true,
+                    });
+                }
+                if (response.status >= 500) {
+                    if (failures++ >= this.#retries) {
+                        throw new DiscordUnavailableError(method, path, new Error(`HTTP ${response.status}`));
+                    }
+                    await response.body?.cancel();
+                    await sleep(250 * 2 ** (failures - 1));
+                    continue;
+                }
+                const data = await readBody(response);
+                if (response.ok)
+                    return data;
+                if (response.status === HttpStatus.Unauthorized && auth) {
+                    this.#tokenRefused = true;
+                    throw new InvalidTokenError();
+                }
+                throw new DiscordApiError({
+                    status: response.status,
+                    method,
+                    route: path,
+                    body: data,
+                });
+            }
+        });
+    }
+}
+async function readBody(response) {
+    if (response.status === HttpStatus.NoContent)
+        return undefined;
+    const text = await response.text();
+    if (text === '')
+        return undefined;
+    if (response.headers.get('content-type')?.includes('application/json')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}

package/dist/structures/base.d.ts

@@ -0,0 +1,48 @@
+import { inspect } from 'node:util';
+import type { Snowflake } from '../discord/types/common.js';
+import { type Camelize } from '../util/case.js';
+import type { Context } from './context.js';
+/** Only the framework reads the context and the data of a structure. */
+export declare let ctxOf: (structure: Structure<object>) => Context;
+export declare let dataOf: <Raw extends object>(structure: Structure<Raw>) => Raw;
+/** What a structure was created with: see `known.ts`, which owns it. */
+export declare let originOf: (structure: Structure<object>) => object | undefined;
+export declare let setOrigin: (structure: Structure<object>, origin: object | undefined) => void;
+/**
+ * Something of Discord (a server, a member, a message...) as user code sees
+ * it: the data Discord sent, read through camelCase properties, and the
+ * actions that can be done on it. Structures are only created by the
+ * framework.
+ */
+export declare abstract class Structure<Raw extends object> {
+    #private;
+    constructor(ctx: Context, data: Raw);
+    /** The data of Discord as a plain object, with camelCase names. */
+    toJSON(): Camelize<Raw>;
+    /** What `console.log` shows: the name of the class, then `toJSON()`. */
+    [inspect.custom](_depth: number, options: Parameters<typeof inspect>[1]): string;
+}
+/** A structure Discord identifies with an id. */
+export declare abstract class IdStructure<Raw extends {
+    id: Snowflake;
+}> extends Structure<Raw> {
+    /** The unique id Discord gave it. */
+    get id(): Snowflake;
+    /** When it was created: a Discord id contains its creation date. */
+    get createdAt(): Date;
+}
+/**
+ * Updates the data of a structure with what Discord just sent. Fields
+ * Discord left out keep their value.
+ */
+export declare function patch<Raw extends object>(structure: Structure<Raw>, data: Partial<Raw>): void;
+/** Copies shared methods onto a class (see `TextBasedChannel`). */
+export declare function mixin(target: {
+    prototype: object;
+}, methods: object): void;
+/** Parses a date of Discord, which may be missing. */
+export declare function toDate(value: string | null | undefined): Date | null;
+/** The id of something given as an id or as a structure. */
+export declare function idOf(value: Snowflake | {
+    id: Snowflake;
+}): Snowflake;

package/dist/structures/base.js

@@ -0,0 +1,84 @@
+import { inspect } from 'node:util';
+import { snowflakeTimestamp } from '../discord/snowflake.js';
+import { toCamelCase } from '../util/case.js';
+/** Only the framework reads the context and the data of a structure. */
+export let ctxOf;
+export let dataOf;
+/** What a structure was created with: see `known.ts`, which owns it. */
+export let originOf;
+export let setOrigin;
+/**
+ * Something of Discord (a server, a member, a message...) as user code sees
+ * it: the data Discord sent, read through camelCase properties, and the
+ * actions that can be done on it. Structures are only created by the
+ * framework.
+ */
+export class Structure {
+    #ctx;
+    #data;
+    // One reference, in the structure itself: nothing is allocated to keep it.
+    #origin = undefined;
+    static {
+        originOf = structure => structure.#origin;
+        setOrigin = (structure, origin) => {
+            structure.#origin = origin;
+        };
+        ctxOf = structure => structure.#ctx;
+        dataOf = (structure) => structure.#data;
+    }
+    constructor(ctx, data) {
+        this.#ctx = ctx;
+        this.#data = data;
+    }
+    /** The data of Discord as a plain object, with camelCase names. */
+    toJSON() {
+        return toCamelCase(this.#data);
+    }
+    /** What `console.log` shows: the name of the class, then `toJSON()`. */
+    [inspect.custom](_depth, options) {
+        return `${this.constructor.name} ${inspect(this.toJSON(), options)}`;
+    }
+}
+/** A structure Discord identifies with an id. */
+export class IdStructure extends Structure {
+    /** The unique id Discord gave it. */
+    get id() {
+        return dataOf(this).id;
+    }
+    /** When it was created: a Discord id contains its creation date. */
+    get createdAt() {
+        return new Date(snowflakeTimestamp(this.id));
+    }
+}
+/**
+ * Updates the data of a structure with what Discord just sent. Fields
+ * Discord left out keep their value.
+ */
+export function patch(structure, data) {
+    const target = dataOf(structure);
+    for (const [key, value] of Object.entries(data)) {
+        if (value !== undefined)
+            target[key] = value;
+    }
+}
+/** Copies shared methods onto a class (see `TextBasedChannel`). */
+export function mixin(target, methods) {
+    for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(methods))) {
+        Object.defineProperty(target.prototype, name, {
+            ...descriptor,
+            enumerable: false,
+        });
+    }
+}
+/** Parses a date of Discord, which may be missing. */
+export function toDate(value) {
+    return value ? new Date(value) : null;
+}
+/** The id of something given as an id or as a structure. */
+export function idOf(value) {
+    const id = typeof value === 'string' ? value : value?.id;
+    if (typeof id !== 'string' || id === '') {
+        throw new TypeError(`Expected an id or something with an id, got ${value === null ? 'null' : typeof value}.`);
+    }
+    return id;
+}