chapterjs 0.4.0 → 0.5.0

package/dist/loader/usage.d.ts

@@ -0,0 +1,15 @@
+/** A use of the framework seen in the code, and the intents it needs. */
+export interface CodeUse {
+    /** What the use is called in `build.json`: `'voice'`, `'messages'`... */
+    readonly name: string;
+    /** What the code looks like when it does it. */
+    readonly pattern: RegExp;
+    /** The intents Discord must be asked for (`GatewayIntent` bits). */
+    readonly intents: number;
+}
+/** The uses found: for each name, the files that do it (`src/quiz.ts`). */
+export type FoundUses = Readonly<Record<string, readonly string[]>>;
+/** Reads the files of `src/` for each use. */
+export declare function scanUses(cwd: string, uses: readonly CodeUse[]): Promise<FoundUses>;
+/** The intents the uses found need. */
+export declare function usesIntents(uses: readonly CodeUse[], found: FoundUses): number;

package/dist/loader/usage.js

@@ -0,0 +1,40 @@
+// What a project does that only its code shows: no declaration says that
+// it joins voice or waits for a message, yet Discord only sends what that
+// needs with an intent. Each feature describes such a use (`CodeUse`) and
+// the files of `src/` are read for it, so the intent is asked for when the
+// project needs it, and only then, like the intents of its events.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+/** Test files are never loaded by the bot. */
+const TEST = /\.(?:test|spec)\.[^.]+$/;
+/** Reads the files of `src/` for each use. */
+export async function scanUses(cwd, uses) {
+    const found = {};
+    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) || TEST.test(entry.name)) {
+            continue;
+        }
+        if (entry.name.endsWith('.d.ts'))
+            continue;
+        const path = join(entry.parentPath, entry.name);
+        const code = await readFile(path, 'utf8').catch(() => '');
+        for (const use of uses) {
+            if (use.pattern.test(code)) {
+                (found[use.name] ??= []).push(relative(cwd, path).split('\\').join('/'));
+            }
+        }
+    }
+    for (const files of Object.values(found))
+        files.sort();
+    return found;
+}
+/** The intents the uses found need. */
+export function usesIntents(uses, found) {
+    return uses.reduce((intents, use) => (found[use.name]?.length ?? 0) > 0 ? intents | use.intents : intents, 0);
+}

package/dist/loader/watch.d.ts

@@ -4,9 +4,11 @@
  */
 export declare function snapshotFolder(dir: string): Promise<string>;
 /**
- * Calls `onChange` when files under `dir` are saved, once per burst: an
- * editor often writes a file in several steps, and saving several files at
- * once is one change.
+ * Calls `onChange` when files under `dir` are saved, once per change: an
+ * editor often writes a file in several steps, saving several files at once
+ * is one change, and the system may tell a save twice, a moment apart (macOS
+ * does for a file written then renamed over the old one). What is compared
+ * is the folder itself, so a save that changed nothing reloads nothing.
  */
 export declare function watchFolder(dir: string, onChange: () => void, { delay, loaded, }?: {
     delay?: number;

package/dist/loader/watch.js

@@ -20,13 +20,31 @@ export async function snapshotFolder(dir) {
     return files.sort().join('\n');
 }
 /**
- * Calls `onChange` when files under `dir` are saved, once per burst: an
- * editor often writes a file in several steps, and saving several files at
- * once is one change.
+ * Calls `onChange` when files under `dir` are saved, once per change: an
+ * editor often writes a file in several steps, saving several files at once
+ * is one change, and the system may tell a save twice, a moment apart (macOS
+ * does for a file written then renamed over the old one). What is compared
+ * is the folder itself, so a save that changed nothing reloads nothing.
  */
 export function watchFolder(dir, onChange, { delay = 60, loaded = snapshotFolder(dir), } = {}) {
     let timer = null;
     let closed = false;
+    /** The folder as the last load saw it. */
+    let lastSeen = loaded;
+    /** One comparison at a time, in the order the bursts ended. */
+    let comparing = Promise.resolve();
+    const compare = () => {
+        comparing = comparing.then(async () => {
+            if (closed)
+                return;
+            await watcher.refresh();
+            const [then, now] = await Promise.all([lastSeen, snapshotFolder(dir)]);
+            if (closed || then === now)
+                return;
+            lastSeen = Promise.resolve(now);
+            onChange();
+        });
+    };
     const changed = () => {
         if (closed)
             return;
@@ -34,25 +52,14 @@ export function watchFolder(dir, onChange, { delay = 60, loaded = snapshotFolder
             clearTimeout(timer);
         timer = setTimeout(() => {
             timer = null;
-            onChange();
+            compare();
         }, delay);
     };
-    const watcher = watch(dir, { recursive: true }, changed);
-    // The folder being deleted is not a reason to crash the bot.
-    watcher.on('error', () => { });
+    const watcher = watchTree(dir, changed);
     // The system takes a moment to really start watching: a file saved
     // between the load and that moment would be missed. The folder is
     // compared, a little later, with what it was when it was loaded.
-    const before = loaded;
-    const catchUps = [300, 1500].map(wait => setTimeout(() => {
-        void Promise.all([before, snapshotFolder(dir)]).then(([then, now]) => {
-            if (then !== now && lastSeen !== now) {
-                lastSeen = now;
-                changed();
-            }
-        });
-    }, wait));
-    let lastSeen = null;
+    const catchUps = [300, 1500].map(wait => setTimeout(compare, wait));
     return {
         close() {
             closed = true;
@@ -64,3 +71,67 @@ export function watchFolder(dir, onChange, { delay = 60, loaded = snapshotFolder
         },
     };
 }
+/**
+ * Calls `listener` when anything under `dir` changes. macOS and Windows watch
+ * a tree themselves. Elsewhere Node watches every file on its own, and a file
+ * written then renamed over the old one (how vim and JetBrains save) is a new
+ * file it never watches again: its next saves would be missed. So each folder
+ * is watched instead, which hears every file in it whatever replaced it, and
+ * `refresh()` follows the folders created or deleted since.
+ */
+function watchTree(dir, listener) {
+    const open = (path, recursive) => {
+        const watcher = watch(path, { recursive }, listener);
+        // A folder being deleted is not a reason to crash the bot.
+        watcher.on('error', () => { });
+        return watcher;
+    };
+    if (process.platform === 'darwin' || process.platform === 'win32') {
+        const watcher = open(dir, true);
+        return { refresh: async () => { }, close: () => watcher.close() };
+    }
+    const watchers = new Map();
+    let closed = false;
+    const refresh = async () => {
+        const entries = await readdir(dir, {
+            recursive: true,
+            withFileTypes: true,
+        }).catch(() => []);
+        if (closed)
+            return;
+        const folders = new Set([
+            dir,
+            ...entries
+                .filter(entry => entry.isDirectory())
+                .map(entry => join(entry.parentPath, entry.name)),
+        ]);
+        for (const [path, watcher] of watchers) {
+            if (folders.has(path))
+                continue;
+            watcher.close();
+            watchers.delete(path);
+        }
+        for (const path of folders) {
+            if (watchers.has(path))
+                continue;
+            try {
+                watchers.set(path, open(path, false));
+            }
+            catch {
+                // Deleted since it was listed: the next refresh forgets it.
+            }
+        }
+    };
+    // The folder itself at once, so nothing is missed while the rest is read.
+    watchers.set(dir, open(dir, false));
+    void refresh();
+    return {
+        refresh,
+        close() {
+            closed = true;
+            for (const watcher of watchers.values())
+                watcher.close();
+            watchers.clear();
+        },
+    };
+}

package/dist/messages/commands.js

@@ -25,6 +25,9 @@ export const defaultLanguageFile = (messages) => messages?.files.get(messages.de
  * already does. What is wrong is reported on the file it is wrong in.
  */
 export function translateCommand(file, command, messages) {
+    // A menu command has its name and translations in its file, always.
+    if (command.type !== 'slash')
+        return { command, failed: [] };
     const path = command.path.join(' ');
     const name = commandName(command.path);
     const failed = [];

package/dist/messages/messages.d.ts

@@ -8,6 +8,7 @@ import type { Locale } from '../discord/types/common.js';
  * out. `{count}` in a form is the number itself.
  */
 export interface PluralText {
+    /** For 0, in every language; and where a language has a form of its own for other numbers too (Arabic, Latvian). */
     zero?: string;
     one?: string;
     two?: string;

package/dist/messages/translate.js

@@ -146,7 +146,11 @@ export function fill(key, template, params, locale = 'en-US') {
         if (typeof count !== 'number') {
             throw new TypeError(`The message "${key}" is a plural: its {count} is a number, got ${JSON.stringify(count)}.`);
         }
-        const form = pluralRule(locale).select(count);
+        // A `zero` written is for 0 in every language, as people expect it
+        // ("no apple"): the rules of English never pick it by themselves.
+        const form = count === 0 && template.forms.has('zero')
+            ? 'zero'
+            : pluralRule(locale).select(count);
         template = template.forms.get(form) ?? template.forms.get('other');
     }
     let text = '';

package/dist/presence/declaration.d.ts

@@ -1,17 +1,64 @@
 import type { Declaration } from '../loader/loader.js';
 import { type RawGatewayPresenceUpdate } from '../discord/types/gateway-events.js';
+import { type ActivityKind, type PresenceContext, type PresenceStatusName } from './presence.js';
+/** The text of an activity as a file gives it: a text, or a function. */
+export type LoadedText = string | ((context: PresenceContext) => string | Promise<string>);
+/** An activity, checked. */
+export interface LoadedActivity {
+    readonly type: ActivityKind | 'streaming';
+    readonly name: LoadedText;
+    readonly url?: string;
+    /** How long it is shown, in milliseconds. */
+    readonly for: number;
+}
+/** The function of a file that gives the activities. */
+export type ActivitiesFunction = (context: PresenceContext) => unknown | Promise<unknown>;
 /** The presence, checked: what the gateway sends. */
 export interface LoadedPresence {
-    /** The Update Presence payload (also sent with Identify). */
+    readonly status: PresenceStatusName;
+    /** The activities shown in turn (none, one or several), or the function giving them. */
+    readonly activities: readonly LoadedActivity[] | ActivitiesFunction;
+    /**
+     * What the bot connects with (sent with Identify): the first activity
+     * when it is known without running anything, else the status alone.
+     */
     readonly raw: RawGatewayPresenceUpdate;
-    /** What tells one presence from another: the payload, as text. */
+    /**
+     * What tells one presence from another: what it sends, and the code of
+     * its functions, as text. The same file saved again has the same key.
+     */
     readonly key: string;
 }
+/** How long an activity is shown when the file does not say. */
+export declare const DEFAULT_FOR = 30000;
+/**
+ * The shortest time an activity may be shown. "Clients may only update
+ * their game status 5 times per 20 seconds": one every 5 seconds is
+ * always sent at once.
+ * @see https://docs.discord.com/developers/events/gateway-events#update-presence
+ */
+export declare const MIN_FOR = 5000;
 /**
  * What a bot without a presence shows: online, doing nothing. Sent when
  * the declaration is removed while the bot runs.
  */
 export declare const DEFAULT_PRESENCE: RawGatewayPresenceUpdate;
+/**
+ * What the gateway sends for a status and the activity shown, with its
+ * text. `since` and `afk` are about a person's client going idle: a bot is
+ * never away from its keyboard.
+ */
+export declare function toRaw(status: PresenceStatusName, activity: {
+    type: LoadedActivity['type'];
+    url?: string;
+} | null, name: string): RawGatewayPresenceUpdate;
+/** Checks the text of an activity a function gave, when it ran. */
+export declare function checkText(name: unknown): string;
+/**
+ * Checks a list of activities: the one of a file, or what its function
+ * gave when it ran.
+ */
+export declare function readActivities(value: unknown): LoadedActivity[];
 /**
  * The presence of the bot, declared once anywhere in `src/` with
  * `presence()` and exported.

package/dist/presence/declaration.js

@@ -1,14 +1,17 @@
 // What a file declares with `presence()`: what the bot shows under its
 // name. It is checked when it loads and turned into what the gateway
 // sends, so a wrong status or type is explained before the bot connects.
+// The activities a function gives are checked the same way when it runs
+// (`readActivities`).
 import { ActivityType, } from '../discord/types/gateway-events.js';
-import { isPresenceDeclaration } from './presence.js';
+import { DURATION_EXAMPLE, parseDuration } from '../util/duration.js';
+import { isPresenceDeclaration, } from './presence.js';
 const fail = message => {
     throw new TypeError(message);
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const KEYS = ['status', 'activity'];
-const ACTIVITY_KEYS = ['type', 'name', 'url'];
+const KEYS = ['status', 'activity', 'activities'];
+const ACTIVITY_KEYS = ['type', 'name', 'url', 'for'];
 /**
  * The statuses a file may give.
  * @see https://docs.discord.com/developers/events/gateway-events#update-presence-status-types
@@ -32,6 +35,17 @@ const TYPES = {
  * @see https://docs.discord.com/developers/events/gateway-events#activity-object-activity-types
  */
 const STREAM_URL = /^https:\/\/(?:www\.)?(?:twitch\.tv|youtube\.com)\//;
+/** How long an activity is shown when the file does not say. */
+export const DEFAULT_FOR = 30_000;
+/**
+ * The shortest time an activity may be shown. "Clients may only update
+ * their game status 5 times per 20 seconds": one every 5 seconds is
+ * always sent at once.
+ * @see https://docs.discord.com/developers/events/gateway-events#update-presence
+ */
+export const MIN_FOR = 5_000;
+/** The most activities a list may have. */
+const MAX_ACTIVITIES = 100;
 const list = (words) => words.map(word => `'${word}'`).join(', ');
 const EXAMPLE = `presence({ status: 'online', activity: { type: 'watching', name: 'over the server' } })`;
 /**
@@ -44,25 +58,86 @@ export const DEFAULT_PRESENCE = Object.freeze({
     status: 'online',
     afk: false,
 });
-/** Turns a checked config into what the gateway sends. */
-function toRaw(config) {
+/**
+ * What the gateway sends for a status and the activity shown, with its
+ * text. `since` and `afk` are about a person's client going idle: a bot is
+ * never away from its keyboard.
+ */
+export function toRaw(status, activity, name) {
     const activities = [];
-    if (config.activity) {
-        const { type, name, url } = config.activity;
+    if (activity) {
+        const { type, url } = activity;
         activities.push(type === 'custom'
             ? // A custom status shows its `state`; `name` is not shown but required.
                 { name: 'Custom Status', type: TYPES.custom, state: name }
             : { name, type: TYPES[type], ...(url ? { url } : {}) });
     }
-    // `since` and `afk` are about a person's client going idle: a bot is
-    // never away from its keyboard.
-    return {
-        since: null,
-        activities,
-        status: config.status ?? 'online',
-        afk: false,
-    };
+    return { since: null, activities, status, afk: false };
 }
+/** Checks the text of an activity a function gave, when it ran. */
+export function checkText(name) {
+    if (typeof name !== 'string' || name.trim() === '') {
+        return fail(`The "name" of the activity is the text shown under the name of the bot: it can't be empty${typeof name === 'string' ? '' : ` (got ${JSON.stringify(name) ?? typeof name})`}.`);
+    }
+    return name;
+}
+/** Checks one activity: `where` says which one, in messages. */
+function readActivity(activity, where) {
+    if (!isRecord(activity)) {
+        return fail(`${where} is what the bot is doing, an object: { type: 'playing', name: '/help' }`);
+    }
+    for (const key of Object.keys(activity)) {
+        if (!ACTIVITY_KEYS.includes(key)) {
+            fail(`"${key}" is not something an activity has. It can have: ${ACTIVITY_KEYS.join(', ')}.`);
+        }
+    }
+    const { type, name, url } = activity;
+    if (typeof type !== 'string' || !(type in TYPES)) {
+        fail(`The "type" of ${where} is ${JSON.stringify(type)}: it can be ${list(Object.keys(TYPES))}.`);
+    }
+    if (typeof name !== 'function')
+        checkText(name);
+    if (type === 'streaming') {
+        if (typeof url !== 'string' || !STREAM_URL.test(url)) {
+            fail(`A "streaming" activity needs the "url" of the stream, and Discord only accepts a https://twitch.tv/ or a https://youtube.com/ link${typeof url === 'string' ? ` (got ${JSON.stringify(url)})` : ''}.`);
+        }
+    }
+    else if (url !== undefined) {
+        fail(`"url" only goes with a "streaming" activity: a ${JSON.stringify(type)} activity has no link.`);
+    }
+    let ms = DEFAULT_FOR;
+    if (activity.for !== undefined) {
+        const parsed = typeof activity.for === 'string' ? parseDuration(activity.for) : null;
+        if (parsed === null) {
+            fail(`"for" of ${where} is how long it is shown, a duration (${DURATION_EXAMPLE}): got ${JSON.stringify(activity.for) ?? typeof activity.for}.`);
+        }
+        if (parsed < MIN_FOR) {
+            fail(`"for" of ${where} is ${JSON.stringify(activity.for)}: an activity is shown 5 seconds at least, since Discord takes 5 changes of presence per 20 seconds.`);
+        }
+        ms = parsed;
+    }
+    return Object.freeze({
+        type: type,
+        name: name,
+        ...(url === undefined ? {} : { url: url }),
+        for: ms,
+    });
+}
+/**
+ * Checks a list of activities: the one of a file, or what its function
+ * gave when it ran.
+ */
+export function readActivities(value) {
+    if (!Array.isArray(value)) {
+        return fail(`"activities" is a list of activities, like [{ type: 'playing', name: '/help', for: '30s' }]: got ${JSON.stringify(value) ?? typeof value}.`);
+    }
+    if (value.length > MAX_ACTIVITIES) {
+        fail(`"activities" has ${value.length} activities: ${MAX_ACTIVITIES} at most.`);
+    }
+    return value.map((activity, index) => readActivity(activity, `activity ${index + 1} of "activities"`));
+}
+/** A function as text, so that the same code saved again is not a change. */
+const codeOf = (value) => typeof value === 'function' ? `ƒ ${String(value)}` : value;
 /**
  * The presence of the bot, declared once anywhere in `src/` with
  * `presence()` and exported.
@@ -82,37 +157,45 @@ export const presenceDeclaration = {
                 fail(`"${key}" is not something a presence has. It can have: ${KEYS.join(', ')}.`);
             }
         }
-        const { status, activity } = config;
-        if (status !== undefined &&
-            !STATUSES.includes(status)) {
+        const { status = 'online', activity } = config;
+        if (!STATUSES.includes(status)) {
             fail(`"status" is ${JSON.stringify(status)}: it can be ${list(STATUSES)}.`);
         }
+        if (activity !== undefined && config.activities !== undefined) {
+            fail(`A presence has "activity" (one) or "activities" (several, shown in turn), not both.`);
+        }
+        let activities = [];
         if (activity !== undefined) {
             if (!isRecord(activity)) {
                 fail(`"activity" is what the bot is doing, an object: activity: { type: 'playing', name: '/help' }`);
             }
-            for (const key of Object.keys(activity)) {
-                if (!ACTIVITY_KEYS.includes(key)) {
-                    fail(`"${key}" is not something an activity has. It can have: ${ACTIVITY_KEYS.join(', ')}.`);
-                }
-            }
-            const { type, name, url } = activity;
-            if (typeof type !== 'string' || !(type in TYPES)) {
-                fail(`The "type" of the activity is ${JSON.stringify(type)}: it can be ${list(Object.keys(TYPES))}.`);
-            }
-            if (typeof name !== 'string' || name.trim() === '') {
-                fail(`The "name" of the activity is the text shown under the name of the bot: it can't be empty.`);
-            }
-            if (type === 'streaming') {
-                if (typeof url !== 'string' || !STREAM_URL.test(url)) {
-                    fail(`A "streaming" activity needs the "url" of the stream, and Discord only accepts a https://twitch.tv/ or a https://youtube.com/ link${typeof url === 'string' ? ` (got ${JSON.stringify(url)})` : ''}.`);
-                }
-            }
-            else if (url !== undefined) {
-                fail(`"url" only goes with a "streaming" activity: a ${JSON.stringify(type)} activity has no link.`);
+            activities = [readActivity(activity, 'the activity')];
+        }
+        else if (typeof config.activities === 'function') {
+            activities = config.activities;
+        }
+        else if (config.activities !== undefined) {
+            activities = readActivities(config.activities);
+            if (activities.length === 0) {
+                fail(`"activities" is empty: give it the activities to show in turn, or leave it out.`);
             }
         }
-        const raw = toRaw(config);
-        return { raw, key: JSON.stringify(raw) };
+        const first = Array.isArray(activities) ? activities[0] : undefined;
+        const raw = toRaw(status, first && typeof first.name === 'string' ? first : null, first && typeof first.name === 'string' ? first.name : '');
+        const shape = Array.isArray(activities)
+            ? activities.map(one => ({ ...one, name: codeOf(one.name) }))
+            : codeOf(activities);
+        return {
+            status: status,
+            activities,
+            raw,
+            // One activity whose text is known: told apart by what it sends, so
+            // a presence written another way but sending the same is no change.
+            key: Array.isArray(activities) &&
+                activities.length <= 1 &&
+                activities.every(one => typeof one.name === 'string' && one.for === DEFAULT_FOR)
+                ? JSON.stringify(raw)
+                : JSON.stringify({ status, activities: shape }),
+        };
     },
 };

package/dist/presence/presence.d.ts

@@ -1,3 +1,5 @@
+import type { Duration } from '../commands/command.js';
+import type { TranslationContext } from '../messages/messages.js';
 /**
  * The status of the bot: `'online'` (green), `'idle'` (orange), `'dnd'`
  * (red, "do not disturb") or `'invisible'` (shown as offline).
@@ -9,30 +11,75 @@ export type PresenceStatusName = 'online' | 'idle' | 'dnd' | 'invisible';
  * the text itself with `'custom'`.
  */
 export type ActivityKind = 'playing' | 'listening' | 'watching' | 'competing' | 'custom';
+/**
+ * What a presence function receives, each time it runs: how many servers
+ * the bot is in, and the texts of the language files in the default
+ * language.
+ */
+export type PresenceContext = {
+    /** How many servers the bot is in, all processes together. */
+    guilds: number;
+} & TranslationContext;
+/**
+ * The text of an activity: a text, or a function that gives it (maybe
+ * after a promise), run each time the activity is shown.
+ */
+export type ActivityText = string | ((context: PresenceContext) => string | Promise<string>);
+interface ActivityBase {
+    /**
+     * How long the activity is shown before the next one, at least 5
+     * seconds: `'30s'`, `'2m'`. 30 seconds by default. Alone, it is how
+     * often a `name` that is a function runs again.
+     */
+    for?: Duration;
+}
 /** An activity that is not a stream. */
-export interface PlainActivity {
+export interface PlainActivity extends ActivityBase {
     type: ActivityKind;
     /** What is shown after the type (or alone with `'custom'`). */
-    name: string;
+    name: ActivityText;
     url?: never;
 }
 /** A stream: "Streaming {name}", with a link to it. */
-export interface StreamingActivity {
+export interface StreamingActivity extends ActivityBase {
     type: 'streaming';
     /** What is shown after "Streaming". */
-    name: string;
+    name: ActivityText;
     /** The stream: Discord only accepts a `https://twitch.tv/` or a `https://youtube.com/` link. */
     url: string;
 }
 /** What the bot is doing. */
 export type Activity = PlainActivity | StreamingActivity;
-/** What a file gives to `presence()`. */
-export interface PresenceConfig {
+/**
+ * The activities shown in turn: a list, or a function that gives it (maybe
+ * after a promise, from a store for example), run again each time the
+ * list has been shown in full.
+ */
+export type Activities = readonly Activity[] | ((context: PresenceContext) => readonly Activity[] | Promise<readonly Activity[]>);
+interface PresenceBase {
     /** The status of the bot. `'online'` by default. */
     status?: PresenceStatusName;
+}
+/** A presence with one activity, or none. */
+export interface SinglePresenceConfig extends PresenceBase {
     /** What the bot is doing. Nothing by default. */
     activity?: Activity;
+    activities?: never;
+}
+/** A presence whose activities are shown in turn. */
+export interface RotatingPresenceConfig extends PresenceBase {
+    activity?: never;
+    /**
+     * Several activities, shown one after the other, each for its `for`: a
+     * list, or a function that gives it.
+     */
+    activities: Activities;
 }
+/**
+ * What a file gives to `presence()`: `activity` for one, or `activities`
+ * for several shown in turn.
+ */
+export type PresenceConfig = SinglePresenceConfig | RotatingPresenceConfig;
 /** What `presence()` returns: a declaration the framework finds in the exports of a file. */
 export interface PresenceDeclaration {
     /** What the file gave to `presence()`, not checked yet. */
@@ -51,7 +98,19 @@ export interface PresenceDeclaration {
  *   activity: { type: 'watching', name: 'over the server' },
  * });
  * ```
+ *
+ * Several activities, shown in turn, each for its own time:
+ *
+ * ```ts
+ * export default presence({
+ *   activities: [
+ *     { type: 'watching', name: 'the tickets', for: '30s' },
+ *     { type: 'playing', name: ({ guilds }) => `on ${guilds} servers`, for: '1m' },
+ *   ],
+ * });
+ * ```
  */
 export declare function presence(config: PresenceConfig): PresenceDeclaration;
 /** Whether a value was made by `presence()`. */
 export declare function isPresenceDeclaration(value: unknown): value is PresenceDeclaration;
+export {};

package/dist/presence/presence.js

@@ -15,6 +15,17 @@ const BRAND = Symbol.for('chapterjs.presence');
  *   activity: { type: 'watching', name: 'over the server' },
  * });
  * ```
+ *
+ * Several activities, shown in turn, each for its own time:
+ *
+ * ```ts
+ * export default presence({
+ *   activities: [
+ *     { type: 'watching', name: 'the tickets', for: '30s' },
+ *     { type: 'playing', name: ({ guilds }) => `on ${guilds} servers`, for: '1m' },
+ *   ],
+ * });
+ * ```
  */
 export function presence(config) {
     return Object.freeze({ [BRAND]: true, config });