chapterjs 0.2.3 → 0.4.0

package/dist/structures/invite.js

@@ -27,6 +27,17 @@ export class Invite extends Structure {
     get channelId() {
         return dataOf(this).channel?.id ?? null;
     }
+    /**
+     * The channel the invite leads to, when the bot knows it. It never sends
+     * a request.
+     */
+    get channel() {
+        const id = this.channelId;
+        const found = id ? ctxOf(this).cache.channels.get(id) : undefined;
+        return found && found.guildId !== null && !found.isThread()
+            ? found
+            : null;
+    }
     /** When the invite stops working; `null` when it never does. */
     get expiresAt() {
         return toDate(dataOf(this).expires_at);

package/dist/tasks/scheduler.d.ts

@@ -25,6 +25,12 @@ export interface SchedulerOptions {
     /** Something the developer should know, that is not an error of theirs. */
     onWarning: (file: string, message: string) => void;
 }
+/**
+ * Runs a task once, as the scheduler does when its time comes: for no
+ * server (what a store per server reads), with the error of a `run` that
+ * throws given to `onError`. Resolves once the run is done.
+ */
+export declare function runTask(entry: TaskEntry, context: Omit<TaskContext, 'now'>, now: Date, onError: (file: string, error: unknown) => void): Promise<void>;
 /** Tasks run by the timers of this process. */
 export declare class TimerScheduler implements Scheduler {
     #private;

package/dist/tasks/scheduler.js

@@ -5,6 +5,14 @@ import { withGuild } from '../store/scope.js';
 import { describeSchedule, nextRun, scheduleKey } from './schedule.js';
 /** The longest a timer of Node can wait. */
 const MAX_DELAY = 2 ** 31 - 1;
+/**
+ * Runs a task once, as the scheduler does when its time comes: for no
+ * server (what a store per server reads), with the error of a `run` that
+ * throws given to `onError`. Resolves once the run is done.
+ */
+export function runTask(entry, context, now, onError) {
+    return new Promise(resolve => resolve(withGuild(null, () => entry.task.run(Object.freeze({ ...context, now }))))).then(() => { }, (error) => onError(entry.file, error));
+}
 /** Tasks run by the timers of this process. */
 export class TimerScheduler {
     #options;
@@ -99,9 +107,7 @@ export class TimerScheduler {
             return;
         }
         scheduled.running = true;
-        new Promise(resolve => resolve(withGuild(null, () => scheduled.entry.task.run(Object.freeze({ ...context, now })))))
-            .catch((error) => this.#options.onError(file, error))
-            .finally(() => {
+        runTask(scheduled.entry, context, now, this.#options.onError).finally(() => {
             scheduled.running = false;
         });
     }

package/dist/testing/failure.d.ts

@@ -0,0 +1,9 @@
+/** An expectation of a test that the bot did not meet. */
+export declare class TestFailure extends Error {
+    readonly name = "TestFailure";
+    constructor(message: string);
+}
+/** Throws a `TestFailure` unless `condition` holds. */
+export declare function expectThat(condition: boolean, message: string): void;
+/** A value as a failure shows it: quoted, cut when very long. */
+export declare function shown(value: unknown): string;

package/dist/testing/failure.js

@@ -0,0 +1,20 @@
+// What a check of `chapterjs test` throws when the bot did not do what the
+// test expected: a plain sentence, shown with the file and the line of the
+// scenario that asked.
+/** An expectation of a test that the bot did not meet. */
+export class TestFailure extends Error {
+    name = 'TestFailure';
+    constructor(message) {
+        super(message);
+    }
+}
+/** Throws a `TestFailure` unless `condition` holds. */
+export function expectThat(condition, message) {
+    if (!condition)
+        throw new TestFailure(message);
+}
+/** A value as a failure shows it: quoted, cut when very long. */
+export function shown(value) {
+    const text = typeof value === 'string' ? JSON.stringify(value) : String(value);
+    return text.length > 200 ? `${text.slice(0, 197)}..."` : text;
+}

package/dist/testing/fake-discord.d.ts

@@ -0,0 +1,59 @@
+import { type IncomingHttpHeaders } from 'node:http';
+/** A request the code under test sent to the fake Discord. */
+export interface FakeDiscordRequest {
+    method: string;
+    /** The path without the API version: `/guilds/1/members`. */
+    path: string;
+    /** The query string parameters; repeated ones keep every value. */
+    query: Record<string, string[]>;
+    headers: IncomingHttpHeaders;
+    /**
+     * The JSON body. For a multipart request: the content of its
+     * `payload_json` part.
+     */
+    body: unknown;
+    /** The files of a multipart request, by form field name. */
+    files: Record<string, {
+        name: string;
+        type: string;
+        text: string;
+    }>;
+}
+/** What the fake Discord answers. */
+export interface FakeDiscordResponse {
+    /** Default: 200, or 204 when there is no body. */
+    status?: number;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Milliseconds to wait before answering. */
+    delay?: number;
+}
+export type FakeDiscordResponder = FakeDiscordResponse | ((request: FakeDiscordRequest) => FakeDiscordResponse | Promise<FakeDiscordResponse>);
+export interface FakeDiscord {
+    /** The base URL to give to the code under test, without the version. */
+    url: string;
+    /** Every request received, in order. */
+    requests: FakeDiscordRequest[];
+    /**
+     * Sets the answer to a route. A list of answers is consumed one request
+     * at a time; the last one stays. The path has no version and no query.
+     */
+    on(method: string, path: string, ...responses: FakeDiscordResponder[]): void;
+    /** The requests received for one route. */
+    requestsTo(method: string, path: string): FakeDiscordRequest[];
+    /** Stops the server. */
+    close(): Promise<void>;
+}
+export interface FakeDiscordOptions {
+    /**
+     * Answers the routes that were not set with `on()`. Without it, they
+     * answer 404 with Discord's "Unknown" error shape.
+     */
+    fallback?: FakeDiscordResponder;
+}
+/** What Discord answers for a route that does not exist. */
+export declare const NOT_FOUND: FakeDiscordResponse;
+/**
+ * Starts the fake Discord. The caller closes it.
+ */
+export declare function fakeDiscord(options?: FakeDiscordOptions): Promise<FakeDiscord>;

package/dist/testing/fake-discord.js

@@ -0,0 +1,120 @@
+// A local HTTP server that plays the REST API of Discord: the real client
+// of the framework runs against it. Answers are programmed per route, or
+// given by a fallback for everything else; every request is recorded.
+import { createServer } from 'node:http';
+/** What Discord answers for a route that does not exist. */
+export const NOT_FOUND = {
+    status: 404,
+    body: { message: '404: Not Found', code: 0 },
+};
+/**
+ * Starts the fake Discord. The caller closes it.
+ */
+export async function fakeDiscord(options = {}) {
+    const routes = new Map();
+    const requests = [];
+    const server = createServer(async (req, res) => {
+        const chunks = [];
+        for await (const chunk of req)
+            chunks.push(chunk);
+        const raw = Buffer.concat(chunks);
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const path = url.pathname.replace(/^\/v\d+/, '');
+        const query = {};
+        for (const [key, value] of url.searchParams)
+            (query[key] ??= []).push(value);
+        let body;
+        const files = {};
+        const type = req.headers['content-type'] ?? '';
+        if (type.startsWith('multipart/form-data')) {
+            const form = await new Request('http://localhost', {
+                method: 'POST',
+                headers: { 'content-type': type },
+                body: raw,
+            }).formData();
+            for (const [field, value] of form) {
+                if (typeof value === 'string') {
+                    if (field === 'payload_json')
+                        body = JSON.parse(value);
+                }
+                else {
+                    files[field] = {
+                        name: value.name,
+                        type: value.type,
+                        text: await value.text(),
+                    };
+                }
+            }
+        }
+        else if (raw.length > 0) {
+            const text = raw.toString('utf8');
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+        }
+        const request = {
+            method: req.method ?? 'GET',
+            path,
+            query,
+            headers: req.headers,
+            body,
+            files,
+        };
+        requests.push(request);
+        const queue = routes.get(`${request.method} ${path}`);
+        let responder = options.fallback ?? NOT_FOUND;
+        if (queue && queue.length > 0) {
+            responder = queue.length > 1 ? queue.shift() : queue[0];
+        }
+        let response;
+        try {
+            response =
+                typeof responder === 'function' ? await responder(request) : responder;
+        }
+        catch (error) {
+            // A fallback that throws is a bug of the fake, not of the bot: say so.
+            response = {
+                status: 500,
+                body: {
+                    message: `The fake Discord failed: ${error instanceof Error ? error.message : String(error)}`,
+                    code: 0,
+                },
+            };
+        }
+        if (response.delay) {
+            await new Promise(resolve => setTimeout(resolve, response.delay));
+        }
+        const hasBody = response.body !== undefined;
+        const payload = !hasBody
+            ? ''
+            : typeof response.body === 'string'
+                ? response.body
+                : JSON.stringify(response.body);
+        res.writeHead(response.status ?? (hasBody ? 200 : 204), {
+            ...(hasBody && typeof response.body !== 'string'
+                ? { 'content-type': 'application/json' }
+                : {}),
+            ...response.headers,
+        });
+        res.end(payload);
+    });
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address();
+    return {
+        url: `http://127.0.0.1:${port}`,
+        requests,
+        on(method, path, ...responses) {
+            routes.set(`${method} ${path}`, responses);
+        },
+        requestsTo(method, path) {
+            return requests.filter(request => request.method === method && request.path === path);
+        },
+        close: () => new Promise(resolve => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}

package/dist/testing/fake-gateway.d.ts

@@ -0,0 +1,59 @@
+/** A payload exchanged with the gateway: `{ op, d, s, t }`. */
+export interface FakeGatewayPayload {
+    op: number;
+    d?: unknown;
+    s?: number | null;
+    t?: string | null;
+}
+/** One WebSocket connection the code under test opened. */
+export interface FakeGatewayConnection {
+    /** The query string of the URL it connected to (`v`, `encoding`...). */
+    query: Record<string, string>;
+    /** Every payload received from the code under test, in order. */
+    received: FakeGatewayPayload[];
+    /** Set once the connection is closed, with the code the client gave. */
+    closed: {
+        code: number | null;
+    } | null;
+    /** Sends any payload. */
+    send(payload: FakeGatewayPayload): void;
+    /** Sends a Dispatch (opcode 0) with the next sequence number. */
+    dispatch(type: string, data: unknown): void;
+    /** Closes the connection with a close code, as Discord does. */
+    close(code: number): void;
+    /** Drops the connection without a close frame (a network failure). */
+    drop(): void;
+    /** Resolves with the next (or an already received) payload that matches. */
+    waitFor(match: number | ((payload: FakeGatewayPayload) => boolean), timeout?: number): Promise<FakeGatewayPayload>;
+    /** Resolves when the connection is closed, with the client's close code. */
+    waitForClose(timeout?: number): Promise<number | null>;
+}
+/** How the fake gateway reacts; change it at any time. */
+export interface FakeGatewayBehavior {
+    /** The `heartbeat_interval` of Hello, in ms; `null` sends no Hello. */
+    heartbeatInterval: number | null;
+    /** Whether heartbeats are acknowledged. */
+    ackHeartbeats: boolean;
+    /**
+     * Called for each Identify (opcode 2). By default answers with a Ready
+     * built from `ready`.
+     */
+    onIdentify: (connection: FakeGatewayConnection, data: unknown) => void;
+    /** Called for each Resume (opcode 6). By default answers Resumed. */
+    onResume: (connection: FakeGatewayConnection, data: unknown) => void;
+    /** Fields of the Ready event sent by the default `onIdentify`. */
+    ready: Record<string, unknown>;
+}
+export interface FakeGateway {
+    /** The URL to connect to: `ws://127.0.0.1:port`. */
+    url: string;
+    behavior: FakeGatewayBehavior;
+    /** Every connection received, in order. */
+    connections: FakeGatewayConnection[];
+    /** Resolves with the connection number `index` (0 is the first one). */
+    connection(index: number, timeout?: number): Promise<FakeGatewayConnection>;
+    /** Drops every connection and stops the server. */
+    close(): Promise<void>;
+}
+/** Starts the fake gateway. The caller closes it. */
+export declare function fakeGateway(options?: Partial<FakeGatewayBehavior>): Promise<FakeGateway>;

package/dist/testing/fake-gateway.js

@@ -0,0 +1,123 @@
+// A local WebSocket server that plays the gateway of Discord: the real
+// shard code of the framework connects to it. By default it says Hello,
+// acknowledges heartbeats, answers Identify with Ready and Resume with
+// Resumed; every part of that can be changed, and each connection driven
+// by hand (dispatch an event, close with a code, drop the socket).
+// https://docs.discord.com/developers/events/gateway
+import { webSocketServer } from './websocket.js';
+/** Starts the fake gateway. The caller closes it. */
+export async function fakeGateway(options = {}) {
+    const connections = [];
+    const connectionWaiters = [];
+    let sessions = 0;
+    const behavior = {
+        heartbeatInterval: 45_000,
+        ackHeartbeats: true,
+        ready: {},
+        onIdentify(connection) {
+            connection.dispatch('READY', {
+                v: 10,
+                user: { id: '100000000000000002', username: 'bot', discriminator: '0' },
+                guilds: [],
+                session_id: `session-${++sessions}`,
+                resume_gateway_url: server.url,
+                application: { id: '100000000000000002', flags: 0 },
+                ...behavior.ready,
+            });
+        },
+        onResume(connection) {
+            connection.dispatch('RESUMED', {});
+        },
+        ...options,
+    };
+    const server = await webSocketServer((peer, _request, on) => {
+        let sequence = 0;
+        const waiters = [];
+        const connection = {
+            query: peer.query,
+            received: [],
+            get closed() {
+                return peer.closed;
+            },
+            send(payload) {
+                peer.sendText(JSON.stringify(payload));
+            },
+            dispatch(type, data) {
+                connection.send({ op: 0, t: type, s: ++sequence, d: data });
+            },
+            close: code => peer.close(code),
+            drop: () => peer.drop(),
+            waitFor(match, timeout = 2000) {
+                const test = typeof match === 'number'
+                    ? (payload) => payload.op === match
+                    : match;
+                const found = connection.received.find(test);
+                if (found)
+                    return Promise.resolve(found);
+                return new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error(`The fake gateway waited ${timeout}ms for a payload that never came. Received: ${JSON.stringify(connection.received)}`)), timeout);
+                    waiters.push({
+                        match: test,
+                        resolve: payload => {
+                            clearTimeout(timer);
+                            resolve(payload);
+                        },
+                    });
+                });
+            },
+            waitForClose: timeout => peer.waitForClose(timeout),
+        };
+        on.message(data => {
+            if (typeof data !== 'string')
+                return;
+            const payload = JSON.parse(data);
+            connection.received.push(payload);
+            for (let index = waiters.length - 1; index >= 0; index--) {
+                if (waiters[index].match(payload)) {
+                    waiters.splice(index, 1)[0].resolve(payload);
+                }
+            }
+            if (payload.op === 1 && behavior.ackHeartbeats) {
+                connection.send({ op: 11 });
+            }
+            else if (payload.op === 2) {
+                behavior.onIdentify(connection, payload.d);
+            }
+            else if (payload.op === 6) {
+                behavior.onResume(connection, payload.d);
+            }
+        });
+        connections.push(connection);
+        for (const resolve of connectionWaiters.splice(0))
+            resolve();
+        if (behavior.heartbeatInterval !== null) {
+            connection.send({
+                op: 10,
+                d: { heartbeat_interval: behavior.heartbeatInterval },
+            });
+        }
+    });
+    return {
+        url: server.url,
+        behavior,
+        connections,
+        async connection(index, timeout = 2000) {
+            const deadline = Date.now() + timeout;
+            while (connections.length <= index) {
+                const left = deadline - Date.now();
+                if (left <= 0) {
+                    throw new Error(`The fake gateway waited ${timeout}ms for connection ${index}: only ${connections.length} were opened.`);
+                }
+                await new Promise(resolve => {
+                    const timer = setTimeout(resolve, left);
+                    connectionWaiters.push(() => {
+                        clearTimeout(timer);
+                        resolve();
+                    });
+                });
+            }
+            return connections[index];
+        },
+        close: () => server.close(),
+    };
+}