chapterjs 0.3.0 → 0.5.0

package/dist/voice/connection.js

@@ -218,6 +218,8 @@ export class VoiceManager {
     #secure;
     #joinTimeout;
     #endedGrace;
+    /** Why voice can't be joined here (`chapterjs test`), or `null`. */
+    #unavailable;
     constructor(ctx, gateway, options) {
         this.#ctx = ctx;
         this.#gateway = gateway;
@@ -225,6 +227,7 @@ export class VoiceManager {
         this.#secure = options.secure ?? true;
         this.#joinTimeout = options.joinTimeout ?? JOIN_TIMEOUT;
         this.#endedGrace = options.endedGrace ?? 3000;
+        this.#unavailable = options.unavailable ?? null;
     }
     /** The connection of the bot in a server, if it is in voice there. */
     connectionOf(guildId) {
@@ -249,6 +252,8 @@ export class VoiceManager {
      * same server. Resolves once audio can be sent.
      */
     async join(channel, options = {}) {
+        if (this.#unavailable !== null)
+            throw new Error(this.#unavailable);
         const guild = channel.guild;
         const me = guild.me;
         const permissions = me.permissionsIn(channel);
@@ -273,7 +278,16 @@ export class VoiceManager {
             ? existing
             : new VoiceConnection(this, guild.id, channel.id);
         this.#connections.set(guild.id, connection);
-        await this.#request(guild.id, channel, options);
+        try {
+            await this.#request(guild.id, channel, options);
+        }
+        catch (error) {
+            // Made again here: the reason comes from a timer or from leave(),
+            // whose lines are not the one of the file that asked to join.
+            throw error instanceof Error
+                ? new Error(error.message, { cause: error })
+                : error;
+        }
         if (channel.isStage)
             await this.#speakOnStage(guild.id, channel);
         return connection;

package/dist/voice/usage.d.ts

@@ -1,4 +1,5 @@
+import type { CodeUse } from '../loader/usage.js';
+/** Joining voice, as `loader/usage.ts` looks for it. */
+export declare const VOICE_USE: CodeUse;
 /** Whether some code joins a voice channel. */
 export declare function joinsVoice(code: string): boolean;
-/** Whether a file of `src/` joins a voice channel. */
-export declare function sourcesJoinVoice(cwd: string): Promise<boolean>;

package/dist/voice/usage.js

@@ -2,32 +2,20 @@
 // a bot its own voice state with the GUILD_VOICE_STATES intent, without
 // which `join()` can't finish: like every intent, it is asked for when the
 // project needs it, and only then.
-import { readdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { GatewayIntent } from '../discord/intents.js';
 /**
  * A call to `join()` without an argument or with options: what joining a
  * voice channel looks like. The `join(', ')` of a list does not match; a
  * `join()` of a list does, and only costs an intent.
  */
 const JOINS_VOICE = /\.join\(\s*(?:\)|\{)/;
-const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+/** Joining voice, as `loader/usage.ts` looks for it. */
+export const VOICE_USE = {
+    name: 'voice',
+    pattern: JOINS_VOICE,
+    intents: GatewayIntent.GuildVoiceStates,
+};
 /** Whether some code joins a voice channel. */
 export function joinsVoice(code) {
     return JOINS_VOICE.test(code);
 }
-/** Whether a file of `src/` joins a voice channel. */
-export async function sourcesJoinVoice(cwd) {
-    const src = join(cwd, 'src');
-    const entries = await readdir(src, {
-        recursive: true,
-        withFileTypes: true,
-    }).catch(() => []);
-    for (const entry of entries) {
-        if (!entry.isFile() || !SOURCE.test(entry.name))
-            continue;
-        const code = await readFile(join(entry.parentPath, entry.name), 'utf8');
-        if (joinsVoice(code))
-            return true;
-    }
-    return false;
-}

package/dist/waiting/usage.d.ts

@@ -0,0 +1,5 @@
+import type { CodeUse } from '../loader/usage.js';
+/** `waitForMessage(` or `collectMessages(`: the messages of a channel. */
+export declare const MESSAGES_USE: CodeUse;
+/** `waitForReaction(`: the reactions to a message. */
+export declare const REACTIONS_USE: CodeUse;

package/dist/waiting/usage.js

@@ -0,0 +1,19 @@
+// What waiting needs from Discord, seen in the code: messages only reach
+// the bot with the intents of messages (and their text with Message
+// Content), reactions with the intents of reactions. Clicks need none.
+// https://docs.discord.com/developers/events/gateway#gateway-intents
+import { GatewayIntent } from '../discord/intents.js';
+/** `waitForMessage(` or `collectMessages(`: the messages of a channel. */
+export const MESSAGES_USE = {
+    name: 'messages',
+    pattern: /\.(?:waitForMessage|collectMessages)\s*\(/,
+    intents: GatewayIntent.GuildMessages |
+        GatewayIntent.DirectMessages |
+        GatewayIntent.MessageContent,
+};
+/** `waitForReaction(`: the reactions to a message. */
+export const REACTIONS_USE = {
+    name: 'reactions',
+    pattern: /\.waitForReaction\s*\(/,
+    intents: GatewayIntent.GuildMessageReactions | GatewayIntent.DirectMessageReactions,
+};

package/dist/waiting/waiters.d.ts

@@ -0,0 +1,48 @@
+/** What can be waited for. */
+export type WaitKind = 'message' | 'reaction' | 'click';
+/** One wait, as a structure asks for it. */
+export interface WaitRequest {
+    readonly kind: WaitKind;
+    /** Whether what is offered is what the wait is for. */
+    match(offered: unknown): boolean;
+    /** How many to take before the wait ends: 1 to wait for one. */
+    readonly max: number;
+    /** How long it waits, in milliseconds. */
+    readonly within: number;
+}
+/**
+ * Told when a run of the files starts and stops waiting, for `chapterjs
+ * test`: a run that waits is not one to wait for.
+ */
+export interface WaitWatcher {
+    parked(run: object): void;
+    resumed(run: object): void;
+}
+/** The waits of a bot. */
+export interface Waiters {
+    /**
+     * Waits for what fits the request, until `max` were taken or the time is
+     * up: resolves with what was taken, in order (maybe nothing).
+     */
+    wait<T>(request: WaitRequest): Promise<T[]>;
+    /** Whether a wait is waiting for this kind: nothing is built otherwise. */
+    wants(kind: WaitKind): boolean;
+    /**
+     * Gives what just happened to the waits that want it. A click goes to
+     * one wait only, and nothing else runs it: returns whether one took it.
+     */
+    offer(kind: WaitKind, offered: unknown): boolean;
+    /** Ends every wait with what it has: the bot stops. */
+    close(): void;
+}
+/** The waits of a bot, in memory: the default. */
+export declare class MemoryWaiters implements Waiters {
+    #private;
+    constructor(options?: {
+        watch?: WaitWatcher;
+    });
+    wait<T>(request: WaitRequest): Promise<T[]>;
+    wants(kind: WaitKind): boolean;
+    offer(kind: WaitKind, offered: unknown): boolean;
+    close(): void;
+}

package/dist/waiting/waiters.js

@@ -0,0 +1,107 @@
+// Waiting for what comes next: the next message of a channel, a click on
+// the buttons of a message, a reaction. A function of the files asks
+// (`channel.waitForMessage()`, `message.waitForClick()`...), the bot offers
+// what Discord sends, and the first thing that fits ends the wait, or the
+// time does. One mechanism for every kind: a new kind of wait is a new
+// `WaitKind` and the place that offers it.
+//
+// Waits live in the process, behind the `Waiters` interface: everything of
+// one server reaches one process (its shard), so a wait always hears what
+// it waits for. A restart ends them: nothing is kept.
+import { currentRun } from '../store/scope.js';
+/** The kinds a single wait takes for itself: nothing else runs them. */
+const EXCLUSIVE = new Set(['click']);
+/** The waits of a bot, in memory: the default. */
+export class MemoryWaiters {
+    #pending = new Map();
+    /** How many waits each run has going. */
+    #runs = new Map();
+    #watch;
+    constructor(options = {}) {
+        this.#watch = options.watch;
+    }
+    wait(request) {
+        return new Promise((resolve, reject) => {
+            const run = currentRun();
+            const taken = [];
+            const list = this.#pending.get(request.kind) ?? new Set();
+            this.#pending.set(request.kind, list);
+            const pending = {
+                request,
+                taken,
+                run,
+                // Nothing of the bot waits for it: a wait never keeps it running.
+                timer: setTimeout(() => pending.end(), request.within).unref(),
+                end: error => {
+                    if (!list.delete(pending))
+                        return;
+                    clearTimeout(pending.timer);
+                    if (list.size === 0)
+                        this.#pending.delete(request.kind);
+                    this.#leave(run);
+                    if (error === undefined)
+                        resolve(taken);
+                    else
+                        reject(error);
+                },
+            };
+            list.add(pending);
+            this.#enter(run);
+        });
+    }
+    wants(kind) {
+        return (this.#pending.get(kind)?.size ?? 0) > 0;
+    }
+    offer(kind, offered) {
+        const list = this.#pending.get(kind);
+        if (!list)
+            return false;
+        let took = false;
+        for (const pending of [...list]) {
+            let fits;
+            try {
+                fits = pending.request.match(offered);
+            }
+            catch (error) {
+                // A test of the files that throws ends its wait with the error,
+                // thrown where the files wait: reported with their line.
+                pending.end(error ?? new Error('The test of the wait threw.'));
+                continue;
+            }
+            if (!fits)
+                continue;
+            took = true;
+            pending.taken.push(offered);
+            if (pending.taken.length >= pending.request.max)
+                pending.end();
+            if (EXCLUSIVE.has(kind))
+                break;
+        }
+        return took;
+    }
+    close() {
+        for (const list of [...this.#pending.values()]) {
+            for (const pending of [...list])
+                pending.end();
+        }
+    }
+    #enter(run) {
+        if (!run)
+            return;
+        const count = this.#runs.get(run) ?? 0;
+        this.#runs.set(run, count + 1);
+        if (count === 0)
+            this.#watch?.parked(run);
+    }
+    #leave(run) {
+        if (!run)
+            return;
+        const count = (this.#runs.get(run) ?? 1) - 1;
+        if (count > 0) {
+            this.#runs.set(run, count);
+            return;
+        }
+        this.#runs.delete(run);
+        this.#watch?.resumed(run);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterjs",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The Discord framework: ultra simple, but ultra customizable. Your files become a bot, typed end to end, with nothing to register.",
   "keywords": [
     "discord",