chapterjs 0.2.2 → 0.3.0

package/dist/store/store.js

@@ -0,0 +1,203 @@
+// What a file declares with `store()`: a place to keep data from one
+// restart to the next, per server by default, typed by what it holds,
+// with an expiration if wanted. Named by its export, like a button:
+// `export const warnings = store<Warning[]>()` is the store `warnings`.
+// What `store()` returns works once the loader bound it to that name and
+// the bot runs; the data itself lives in a backend (`backend.ts`).
+import { parseDuration } from '../util/duration.js';
+import { storeBackend, } from './backend.js';
+import { currentGuildId } from './scope.js';
+const STATE = Symbol.for('chapterjs.store');
+/** The state of a declared store, if the value is one. */
+export function storeStateOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    return value[STATE];
+}
+export const isStoreDeclaration = (value) => storeStateOf(value) !== undefined;
+/** Binds a declared store to the name of its export. */
+export function bindStore(declared, bound) {
+    const state = storeStateOf(declared);
+    if (!state)
+        throw new TypeError('Not a store.');
+    state.name = bound.name;
+    state.scope = bound.scope;
+    state.expires = bound.expires;
+}
+const parts = (key) => {
+    const list = typeof key === 'string' ? [key] : [...key];
+    if (list.length === 0) {
+        throw new TypeError('A key of a store is a text that is not empty, or a list of such texts with at least one.');
+    }
+    for (const part of list) {
+        if (typeof part !== 'string') {
+            throw new TypeError(`A key of a store is made of texts, got ${JSON.stringify(part) ?? typeof part}. Write an id as a text: member.id, not a number.`);
+        }
+        if (part === '') {
+            throw new TypeError('A key of a store is a text that is not empty, or a list of such texts with at least one.');
+        }
+    }
+    return list;
+};
+/**
+ * Refuses what would not survive a trip through JSON: a `Date` would come
+ * back as a text, a `Map` as `{}`, a class instance as a plain object.
+ */
+export function checkJson(value, path = 'the value') {
+    if (value === undefined) {
+        throw new TypeError(`${path} is undefined: a store keeps JSON. To forget a value, use delete().`);
+    }
+    if (value === null)
+        return;
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return;
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new TypeError(`${path} is ${value}, which JSON can't hold: a store keeps JSON.`);
+            }
+            return;
+        case 'bigint':
+        case 'function':
+        case 'symbol':
+            throw new TypeError(`${path} is a ${typeof value}, which JSON can't hold: a store keeps JSON (texts, numbers, booleans, lists and plain objects).`);
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => checkJson(item, `${path}[${index}]`));
+        return;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype) {
+        const name = value.constructor?.name ??
+            'an object of a class';
+        throw new TypeError(`${path} is a ${name}, which JSON can't hold: a store keeps JSON (texts, numbers, booleans, lists and plain objects). Keep what you need of it: an id, a text, a number.`);
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined)
+            checkJson(item, `${path}.${key}`);
+    }
+}
+/** When a value set now expires, from what was asked. */
+function expiresAt(options, fallback, now) {
+    if (!options || options.expires === undefined) {
+        return fallback === null ? null : now + fallback;
+    }
+    const { expires } = options;
+    if (expires === null)
+        return null;
+    if (expires instanceof Date) {
+        const ms = expires.getTime();
+        if (!Number.isFinite(ms)) {
+            throw new TypeError('"expires" is a Date that is not a valid date.');
+        }
+        return ms;
+    }
+    const ms = typeof expires === 'string' ? parseDuration(expires) : null;
+    if (ms === null || ms < 1000) {
+        throw new TypeError(`"expires" is a duration (a number and a unit: s, m, h or d, like '10m' or '1d', 1 s at least), a Date, or null to keep the value forever. Got ${JSON.stringify(expires)}.`);
+    }
+    return now + ms;
+}
+/** The store as its functions see it: the backend, the name, the scope prefix. */
+function scoped(state, guildOf) {
+    const ready = () => {
+        if (!state.name) {
+            throw new Error('This store was not loaded by ChapterJS: a store is exported from a file of src/ (export const name = store()), and used once the bot started.');
+        }
+        const backend = storeBackend();
+        if (state.scope === 'global') {
+            return { backend, name: state.name, prefix: [] };
+        }
+        const guildId = guildOf();
+        if (!guildId) {
+            throw new Error(`${state.name} is a store per server, and this code does not run in one: use ${state.name}.in(guild) to say which server, or declare the store with scope: 'global'.`);
+        }
+        return { backend, name: state.name, prefix: [guildId] };
+    };
+    const full = (prefix, key) => [
+        ...prefix,
+        ...parts(key),
+    ];
+    const set = async (key, value, options, keep) => {
+        const { backend, name, prefix } = ready();
+        checkJson(value);
+        const now = Date.now();
+        const at = keep !== undefined && (!options || options.expires === undefined)
+            ? keep
+            : expiresAt(options, state.expires, now);
+        await backend.set(name, full(prefix, key), { value, expiresAt: at });
+    };
+    return {
+        async get(key) {
+            const { backend, name, prefix } = ready();
+            const entry = await backend.get(name, full(prefix, key));
+            return entry?.value;
+        },
+        set: (key, value, options) => set(key, value, options, undefined),
+        async update(key, change, options) {
+            const { backend, name, prefix } = ready();
+            const entry = await backend.get(name, full(prefix, key));
+            const next = change(entry?.value);
+            await set(key, next, options, entry ? entry.expiresAt : undefined);
+            return next;
+        },
+        async delete(key) {
+            const { backend, name, prefix } = ready();
+            return backend.delete(name, full(prefix, key));
+        },
+        async entries(prefixKey) {
+            const { backend, name, prefix } = ready();
+            const listed = await backend.entries(name, prefixKey === undefined ? prefix : full(prefix, prefixKey));
+            return listed.map(entry => ({
+                key: entry.key.slice(prefix.length),
+                value: entry.value,
+                expires: entry.expiresAt === null ? null : new Date(entry.expiresAt),
+            }));
+        },
+        async ttl(key) {
+            const { backend, name, prefix } = ready();
+            const entry = await backend.get(name, full(prefix, key));
+            if (!entry)
+                return undefined;
+            return entry.expiresAt === null
+                ? null
+                : Math.max(0, entry.expiresAt - Date.now());
+        },
+    };
+}
+/**
+ * Declares a store: data the bot keeps from one restart to the next,
+ * typed by what it holds. Export the result from any file of `src/`: the
+ * name of the export is the name of the store, and its file in `data/`.
+ * Per server unless `scope: 'global'` is given, with an expiration if
+ * `expires` is.
+ *
+ * ```ts
+ * import { store } from 'chapterjs';
+ *
+ * export const warnings = store<Warning[]>({ expires: '30d' });
+ *
+ * // In a command, in a server:
+ * await warnings.update(member.id, (list = []) => [...list, warning]);
+ * ```
+ */
+export function store(config = {}) {
+    const state = { config, scope: 'guild', expires: null };
+    const guildIdOf = (guild) => {
+        const id = typeof guild === 'string' ? guild : guild?.id;
+        if (typeof id !== 'string' || id === '') {
+            throw new TypeError('in() takes a server (a Guild) or its id, like warnings.in(guild) or warnings.in(guild.id).');
+        }
+        return id;
+    };
+    const declared = {
+        ...scoped(state, () => currentGuildId() ?? null),
+        in: guild => {
+            const id = guildIdOf(guild);
+            return scoped(state, () => id);
+        },
+    };
+    Object.defineProperty(declared, STATE, { value: state });
+    return declared;
+}

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

@@ -1,9 +1,18 @@
 // Runs the tasks of the project when they are due. Behind an interface:
 // this one keeps timers in the process; a bot on several machines would
 // share one through another implementation, with no change to the files.
+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;
@@ -98,9 +107,7 @@ export class TimerScheduler {
             return;
         }
         scheduled.running = true;
-        new Promise(resolve => resolve(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(),
+    };
+}