chapterjs 0.2.3 → 0.3.0

package/dist/components/router.d.ts

@@ -14,6 +14,11 @@ export declare class ComponentRouter {
     constructor(options: ComponentRouterOptions);
     /** Replaces every component (after a load or a reload). */
     set(entries: Iterable<ComponentEntry>): void;
-    /** Handles an Interaction Create event, if it is a component or a form. */
-    dispatch(ctx: Context, raw: RawInteraction): void;
+    /**
+     * Handles an Interaction Create event, if it is a component or a form.
+     * Returns a promise of everything being done (the function run, the
+     * person answered), or `null` when the interaction is not for this
+     * router. Nothing of the bot waits for it: `chapterjs test` does.
+     */
+    dispatch(ctx: Context, raw: RawInteraction): Promise<void> | null;
 }

package/dist/components/router.js

@@ -33,18 +33,23 @@ export class ComponentRouter {
         }
         this.#components = components;
     }
-    /** Handles an Interaction Create event, if it is a component or a form. */
+    /**
+     * Handles an Interaction Create event, if it is a component or a form.
+     * Returns a promise of everything being done (the function run, the
+     * person answered), or `null` when the interaction is not for this
+     * router. Nothing of the bot waits for it: `chapterjs test` does.
+     */
     dispatch(ctx, raw) {
         const isComponent = raw.type === InteractionType.MessageComponent;
         const isModal = raw.type === InteractionType.ModalSubmit;
         if (!isComponent && !isModal)
-            return;
+            return null;
         const data = raw.data;
         if (!data || typeof data.custom_id !== 'string')
-            return;
+            return null;
         const author = authorOf(raw);
         if (!author)
-            return;
+            return null;
         const user = ctx.entities.user(author.user);
         const { user: _user, member: _member, message: rawMessage, ...rest } = raw;
         const message = rawMessage
@@ -79,7 +84,7 @@ export class ComponentRouter {
                 message: message,
             });
         if (isComponent && !message)
-            return;
+            return null;
         // Embeds are never in the map: what is left has a `run`.
         if (!entry ||
             entry.component.kind === 'embed' ||
@@ -87,27 +92,23 @@ export class ComponentRouter {
                 SELECT_TYPES[entry.component.type] !==
                     data.component_type)) {
             // Sent before the export was renamed, removed or changed of kind.
-            refuse(interaction, 'gone', { what });
-            return;
+            return refuse(interaction, 'gone', { what });
         }
         const { component, file } = entry;
         const values = readData(component.data, parts);
         if (!values) {
             // The data of the component changed since the message was sent.
-            refuse(interaction, 'outdated', { what });
-            return;
+            return refuse(interaction, 'outdated', { what });
         }
         const placed = resolvePlace(ctx, raw, user, author.member, component.where, warning => this.#options.onWarning(file, `${name} ${warning}`));
         if (!placed.place) {
-            refuse(interaction, placed.refusal, { what });
-            return;
+            return refuse(interaction, placed.refusal, { what });
         }
         const { place } = placed;
         if (component.kind !== 'modal' &&
             component.who === 'author' &&
             rawMessage?.interaction_metadata?.user.id !== user.id) {
-            refuse(interaction, 'authorOnly', { what });
-            return;
+            return refuse(interaction, 'authorOnly', { what });
         }
         remember(interaction, {
             guild: place.guild ?? undefined,
@@ -127,8 +128,7 @@ export class ComponentRouter {
         }
         catch (error) {
             this.#options.onError(file, error);
-            refuse(interaction, 'failed', { what });
-            return;
+            return refuse(interaction, 'failed', { what });
         }
         const context = Object.freeze({
             interaction,
@@ -144,7 +144,7 @@ export class ComponentRouter {
                 ephemeral: ephemeralOf(component),
             })),
         });
-        runInteraction({
+        return runInteraction({
             interaction,
             file,
             name,

package/dist/discord/types/channel.d.ts

@@ -251,6 +251,14 @@ export interface RawForumTag {
     /** the unicode character of the emoji * */
     emoji_name: string | null;
 }
+/**
+ * A forum tag as a request gives it: a new tag has no `id` yet, an existing
+ * one keeps its own.
+ * @see https://docs.discord.com/developers/resources/channel#forum-tag-object
+ */
+export type RawForumTagInput = Omit<RawForumTag, 'id'> & {
+    id?: Snowflake;
+};
 /**
  * JSON Params (Group DM)
  * @see https://docs.discord.com/developers/resources/channel#modify-channel-json-params-group-dm
@@ -293,7 +301,7 @@ export interface ModifyGuildChannelJSONParams {
     /** channel flags combined as a bitfield. */
     flags?: number;
     /** the set of tags that can be used in a `GUILD_FORUM` or a `GUILD_MEDIA` channel; limited to 20 */
-    available_tags?: RawForumTag[];
+    available_tags?: RawForumTagInput[];
     /** the emoji to show in the add reaction button on a thread in a `GUILD_FORUM` or a `GUILD_MEDIA` channel */
     default_reaction_emoji?: RawDefaultReaction | null;
     /** the initial `rate_limit_per_user` to set on newly created threads in a channel. this field is copied to the thread at creation time and does not live update. */

package/dist/discord/types/guild.d.ts

@@ -1,9 +1,9 @@
 import type { RawApplication } from './application.js';
-import type { ChannelType, ForumLayoutType, ForumSortOrderType, RawChannel, RawDefaultReaction, RawForumTag, RawPermissionOverwrite, RawThreadMember, VideoQualityMode } from './channel.js';
+import type { ChannelType, ForumLayoutType, ForumSortOrderType, RawChannel, RawDefaultReaction, RawForumTagInput, RawPermissionOverwrite, RawThreadMember, VideoQualityMode } from './channel.js';
 import type { ISO8601Timestamp, ImageData, Locale, Snowflake } from './common.js';
 import type { RawEmoji } from './emoji.js';
 import type { OAuth2Scope } from './oauth2.js';
-import type { RawRole, RawRoleColors } from './permissions.js';
+import type { RawRole, RawRoleColorsInput } from './permissions.js';
 import type { RawSticker } from './sticker.js';
 import type { RawAvatarDecorationData, RawCollectibles, RawUser } from './user.js';
 /**
@@ -605,7 +605,7 @@ export interface CreateGuildChannelJSONParams {
     /** emoji to show in the add reaction button on a thread in a `GUILD_FORUM` or a `GUILD_MEDIA` channel */
     default_reaction_emoji?: RawDefaultReaction | null;
     /** set of tags that can be used in a `GUILD_FORUM` or a `GUILD_MEDIA` channel */
-    available_tags?: RawForumTag[] | null;
+    available_tags?: RawForumTagInput[] | null;
     /** the default sort order type used to order posts in `GUILD_FORUM` and `GUILD_MEDIA` channels */
     default_sort_order?: ForumSortOrderType | null;
     /** the default forum layout view used to display posts in `GUILD_FORUM` channels */
@@ -773,7 +773,7 @@ export interface CreateGuildRoleJSONParams {
     /** **Deprecated** RGB color value */
     color?: number;
     /** the role's colors */
-    colors?: RawRoleColors;
+    colors?: RawRoleColorsInput;
     /** whether the role should be displayed separately in the sidebar */
     hoist?: boolean;
     /** the role's icon image (if the guild has the `ROLE_ICONS` feature) */
@@ -805,7 +805,7 @@ export interface ModifyGuildRoleJSONParams {
     /** **Deprecated** RGB color value */
     color?: number;
     /** the role's colors */
-    colors?: RawRoleColors;
+    colors?: RawRoleColorsInput;
     /** whether the role should be displayed separately in the sidebar */
     hoist?: boolean;
     /** the role's icon image (if the guild has the `ROLE_ICONS` feature) */

package/dist/discord/types/permissions.d.ts

@@ -172,6 +172,12 @@ export interface RawRoleColors {
     /** the tertiary color for the role, this will turn the gradient into a holographic style */
     tertiary_color: number | null;
 }
+/**
+ * The colors of a role as a request gives them: only the primary color is
+ * needed, the two others make a gradient when given.
+ * @see https://docs.discord.com/developers/topics/permissions#role-object-role-colors-object
+ */
+export type RawRoleColorsInput = Pick<RawRoleColors, 'primary_color'> & Partial<Omit<RawRoleColors, 'primary_color'>>;
 /**
  * Role Flags
  * @see https://docs.discord.com/developers/topics/permissions#role-object-role-flags

package/dist/discord/types/poll.d.ts

@@ -27,7 +27,7 @@ export interface RawPollCreateRequest {
     /** The question of the poll. Only `text` is supported. */
     question: RawPollMedia;
     /** Each of the answers available in the poll, up to 10 */
-    answers: RawPollAnswer[];
+    answers: RawPollAnswerInput[];
     /** Number of hours the poll should be open for, up to 32 days. Defaults to 24 */
     duration?: number;
     /** Whether a user can select multiple answers. Defaults to false */
@@ -54,6 +54,12 @@ export interface RawPollMedia {
     /** The emoji of the field */
     emoji?: Partial<RawEmoji>;
 }
+/**
+ * A poll answer as a request gives it: `answer_id` is only sent as part of
+ * responses from Discord's API/Gateway.
+ * @see https://docs.discord.com/developers/resources/poll#poll-answer-object-poll-answer-object-structure
+ */
+export type RawPollAnswerInput = Omit<RawPollAnswer, 'answer_id'>;
 /**
  * Poll Answer Object Structure
  * @see https://docs.discord.com/developers/resources/poll#poll-answer-object-poll-answer-object-structure

package/dist/events/router.d.ts

@@ -36,14 +36,19 @@ export declare class EventRouter {
      * `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. */
+    /**
+     * Runs the handlers of a gateway event, once the cache reflects it.
+     * Resolves once every handler is done (what was asked to Discord first
+     * included). Nothing of the bot waits for it: `chapterjs test` does.
+     */
     dispatch<E extends GatewayDispatchEventName>(ctx: Context, event: E, data: GatewayDispatchEvents[E], extra: {
         joined: boolean;
         before: unknown[] | undefined;
-    }): void;
+    }): Promise<void>;
     /**
      * Runs the handlers of an event with what they receive, for the server
-     * it happened in (what a store per server reads).
+     * it happened in (what a store per server reads). Resolves once every
+     * handler is done.
      */
-    emit<Name extends EventName>(name: Name, context: EventContexts[Name], guildId?: string | null): void;
+    emit<Name extends EventName>(name: Name, context: EventContexts[Name], guildId?: string | null): Promise<void>;
 }

package/dist/events/router.js

@@ -79,11 +79,16 @@ export class EventRouter {
             ? source.before(ctx, data)
             : undefined);
     }
-    /** Runs the handlers of a gateway event, once the cache reflects it. */
+    /**
+     * Runs the handlers of a gateway event, once the cache reflects it.
+     * Resolves once every handler is done (what was asked to Discord first
+     * included). Nothing of the bot waits for it: `chapterjs test` does.
+     */
     dispatch(ctx, event, data, extra) {
         const sources = BY_GATEWAY_EVENT.get(event);
         if (!sources)
-            return;
+            return Promise.resolve();
+        const pending = [];
         sources.forEach((source, index) => {
             if (!this.#handlers.has(source.name))
                 return;
@@ -94,44 +99,52 @@ export class EventRouter {
                     prepared,
                 });
                 if (!built)
-                    return;
+                    return Promise.resolve();
                 // 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;
+                const emitted = [];
                 for (const context of occurrences) {
                     // `t` speaks the language of the server the event happened in.
                     const guild = guildOf?.(context);
-                    this.emit(source.name, {
+                    emitted.push(this.emit(source.name, {
                         ...context,
                         ...translation(ctx, audienceLocale({ guild })),
-                    }, guild?.id ?? null);
+                    }, guild?.id ?? null));
                 }
+                return Promise.all(emitted).then(() => { });
             };
             const preparing = source.prepare?.(ctx, data);
-            if (!preparing)
-                return deliver();
-            preparing.then(deliver, (error) => this.#onSkipped(source.name, error));
+            if (!preparing) {
+                pending.push(deliver());
+                return;
+            }
+            pending.push(preparing.then(deliver, (error) => this.#onSkipped(source.name, error)));
         });
+        return Promise.all(pending).then(() => { });
     }
     /**
      * Runs the handlers of an event with what they receive, for the server
-     * it happened in (what a store per server reads).
+     * it happened in (what a store per server reads). Resolves once every
+     * handler is done.
      */
     emit(name, context, guildId = null) {
         const handlers = this.#handlers.get(name);
         if (!handlers)
-            return;
+            return Promise.resolve();
         // Handlers can't change what the others receive.
         const frozen = Object.freeze({ ...context });
         const accepts = EVENTS[name].accepts;
+        const running = [];
         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(withGuild(guildId, () => event.handler(frozen)))).catch((error) => this.#onError(file, error));
+            running.push(new Promise(resolve => resolve(withGuild(guildId, () => event.handler(frozen)))).then(() => { }, (error) => this.#onError(file, error)));
         }
+        return Promise.all(running).then(() => { });
     }
 }

package/dist/interactions/dispatch.d.ts

@@ -89,5 +89,9 @@ export interface RunOptions {
  * seconds: when `run` takes longer, the framework says the answer is
  * coming. When `run` throws, the person gets a plain answer and the
  * developer the error with its file and line.
+ *
+ * Resolves once everything is done (the function, and the answer sent for
+ * it when it failed): nothing of the bot waits for it, `chapterjs test`
+ * does.
  */
-export declare function runInteraction(options: RunOptions): void;
+export declare function runInteraction(options: RunOptions): Promise<void>;

package/dist/interactions/dispatch.js

@@ -75,6 +75,10 @@ export function refuse(interaction, key, params) {
  * seconds: when `run` takes longer, the framework says the answer is
  * coming. When `run` throws, the person gets a plain answer and the
  * developer the error with its file and line.
+ *
+ * Resolves once everything is done (the function, and the answer sent for
+ * it when it failed): nothing of the bot waits for it, `chapterjs test`
+ * does.
  */
 export function runInteraction(options) {
     const { interaction, file, name, reporter } = options;
@@ -82,7 +86,7 @@ export function runInteraction(options) {
     sleep(reporter.deferAfter ?? 2000, undefined, { signal: stop.signal })
         .then(() => options.defer())
         .catch(() => { });
-    new Promise(resolve => resolve(withGuild(options.guildId, options.run)))
+    return new Promise(resolve => resolve(withGuild(options.guildId, options.run)))
         .then(() => {
         if (!interaction.answered) {
             reporter.onWarning(file, `${name} ${options.unanswered}`);
@@ -105,7 +109,7 @@ export function runInteraction(options) {
                 : interaction.answered
                     ? interaction.followUp({ content, ephemeral: true })
                     : interaction.reply({ content, ephemeral: true });
-        tell.catch(() => { });
+        return tell.then(() => { }, () => { });
     })
         .finally(() => stop.abort());
 }

package/dist/loader/hot.js

@@ -45,8 +45,15 @@ export function enableProjectLoader(dir, { reload }) {
                 result = nextResolve(specifier, context);
             }
             catch (error) {
-                if (!fromProject || EXTENSION.test(specifier))
+                // Not found, or a folder (Node refuses those as they are).
+                const code = error.code;
+                if (!fromProject ||
+                    (code !== 'ERR_MODULE_NOT_FOUND' &&
+                        code !== 'ERR_UNSUPPORTED_DIR_IMPORT')) {
                     throw error;
+                }
+                if (EXTENSION.test(specifier))
+                    throw missing(specifier, false);
                 // No extension: look for the file people mean.
                 for (const candidate of CANDIDATES) {
                     try {
@@ -58,7 +65,7 @@ export function enableProjectLoader(dir, { reload }) {
                     }
                 }
                 if (!result)
-                    throw error;
+                    throw missing(specifier, true);
             }
             if (hot && root !== null && result.url.startsWith(root)) {
                 return {
@@ -70,6 +77,19 @@ export function enableProjectLoader(dir, { reload }) {
         },
     });
 }
+/**
+ * The error for an import of the project that names no file: said in the
+ * words of the import, not with the absolute paths Node gives.
+ */
+function missing(specifier, tried) {
+    const name = specifier.replace(/\/$/, '').split('/').pop() ?? specifier;
+    const looked = tried
+        ? ` No ${name}.ts, ${name}.js or ${name}/index.ts is there.`
+        : '';
+    const error = new Error(`'${specifier}' does not exist.${looked} Check the path and the name of the file.`);
+    error.code = 'ERR_MODULE_NOT_FOUND';
+    return error;
+}
 /** Makes the next imports load the files again. */
 export function nextGeneration() {
     generation++;

package/dist/loader/loader.d.ts

@@ -59,6 +59,11 @@ export interface FoundFile {
 }
 /** Every source file of `src/`, in a stable order. */
 export declare function listSources(projectDir: string): Promise<FoundFile[]>;
+/**
+ * Every test file of `src/` (`*.test.ts`, `*.spec.ts`), in a stable order:
+ * what `chapterjs test` runs, and what the bot never loads.
+ */
+export declare function listTests(projectDir: string): Promise<FoundFile[]>;
 /** A file of the project, run: what it exports. */
 export interface LoadedModule {
     /** The path from the project folder: `src/ping.ts`. */
@@ -72,6 +77,8 @@ export interface LoadedSources {
 }
 /** Runs every file of `src/`. A file that fails to run never throws. */
 export declare function loadSources(projectDir: string): Promise<LoadedSources>;
+/** Runs the files given. A file that fails to run never throws. */
+export declare function loadFiles(files: readonly FoundFile[]): Promise<LoadedSources>;
 /**
  * Reads the declarations of one kind from what the files export. Every
  * export is looked at; the ones the kind recognises are read, the others

package/dist/loader/loader.js

@@ -16,7 +16,7 @@ const DECLARATION = /\.d\.m?ts$/;
 /** Tests next to the code: they are for a test runner, not for the bot. */
 const TEST = /\.(?:test|spec)\.[^.]+$/;
 /** The source files of a folder and its subfolders, in a stable order. */
-async function scan(dir) {
+async function scan(dir, tests = false) {
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true });
@@ -30,10 +30,10 @@ async function scan(dir) {
     for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
         const path = join(dir, entry.name);
         if (entry.isDirectory())
-            files.push(...(await scan(path)));
+            files.push(...(await scan(path, tests)));
         else if (SOURCE.test(entry.name) &&
             !DECLARATION.test(entry.name) &&
-            !TEST.test(entry.name)) {
+            TEST.test(entry.name) === tests) {
             files.push(path);
         }
     }
@@ -41,19 +41,29 @@ async function scan(dir) {
 }
 /** Every source file of `src/`, in a stable order. */
 export async function listSources(projectDir) {
-    const paths = await scan(join(projectDir, 'src'));
-    return paths
-        .map(path => ({
-        file: relative(projectDir, path).split(sep).join('/'),
-        path,
-    }))
-        .sort((a, b) => (a.file < b.file ? -1 : 1));
+    return found(projectDir, await scan(join(projectDir, 'src')));
 }
+/**
+ * Every test file of `src/` (`*.test.ts`, `*.spec.ts`), in a stable order:
+ * what `chapterjs test` runs, and what the bot never loads.
+ */
+export async function listTests(projectDir) {
+    return found(projectDir, await scan(join(projectDir, 'src'), true));
+}
+const found = (projectDir, paths) => paths
+    .map(path => ({
+    file: relative(projectDir, path).split(sep).join('/'),
+    path,
+}))
+    .sort((a, b) => (a.file < b.file ? -1 : 1));
 /** Runs every file of `src/`. A file that fails to run never throws. */
 export async function loadSources(projectDir) {
-    const found = await listSources(projectDir);
+    return loadFiles(await listSources(projectDir));
+}
+/** Runs the files given. A file that fails to run never throws. */
+export async function loadFiles(files) {
     const result = { modules: [], failed: [] };
-    await Promise.all(found.map(async ({ file, path }) => {
+    await Promise.all(files.map(async ({ file, path }) => {
         try {
             result.modules.push({ file, exports: await importFile(path) });
         }

package/dist/store/memory-backend.d.ts

@@ -0,0 +1,15 @@
+import { type StoreBackend, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
+/** The data of every store, in memory, forgotten with the process. */
+export declare class MemoryStoreBackend implements StoreBackend {
+    #private;
+    constructor(options?: {
+        now?: () => number;
+    });
+    get(store: string, key: StoreKeyParts): Promise<StoreEntry | undefined>;
+    set(store: string, key: StoreKeyParts, entry: StoreEntry): Promise<void>;
+    delete(store: string, key: StoreKeyParts): Promise<boolean>;
+    entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    /** Forgets everything: what a test does with its stores stays in it. */
+    clear(): void;
+    close(): Promise<void>;
+}

package/dist/store/memory-backend.js

@@ -0,0 +1,56 @@
+// A backend that keeps the data of the stores in memory and nowhere else:
+// what `chapterjs test` gives a bot under test, so a test never touches
+// the `data/` folder of the project and starts from nothing every time.
+import { alive, decodeKey, encodeKey, startsWith, } from './backend.js';
+/** The data of every store, in memory, forgotten with the process. */
+export class MemoryStoreBackend {
+    #stores = new Map();
+    #now;
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+    }
+    #store(name) {
+        let store = this.#stores.get(name);
+        if (!store) {
+            store = new Map();
+            this.#stores.set(name, store);
+        }
+        return store;
+    }
+    async get(store, key) {
+        const entry = this.#store(store).get(encodeKey(key));
+        if (!entry)
+            return undefined;
+        if (!alive(entry, this.#now())) {
+            this.#store(store).delete(encodeKey(key));
+            return undefined;
+        }
+        return entry;
+    }
+    async set(store, key, entry) {
+        this.#store(store).set(encodeKey(key), entry);
+    }
+    async delete(store, key) {
+        return this.#store(store).delete(encodeKey(key));
+    }
+    async entries(store, prefix) {
+        const now = this.#now();
+        const result = [];
+        for (const [encoded, entry] of this.#store(store)) {
+            const key = decodeKey(encoded);
+            if (!startsWith(key, prefix))
+                continue;
+            if (!alive(entry, now)) {
+                this.#store(store).delete(encoded);
+                continue;
+            }
+            result.push({ key, ...entry });
+        }
+        return result;
+    }
+    /** Forgets everything: what a test does with its stores stays in it. */
+    clear() {
+        this.#stores.clear();
+    }
+    async close() { }
+}

package/dist/store/store.js

@@ -27,12 +27,15 @@ export function bindStore(declared, bound) {
 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, or a list of texts with at least one.');
+        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;
 };

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;
+}