chapterjs 0.3.0 → 0.5.0

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

package/dist/presence/rotation.d.ts

@@ -0,0 +1,32 @@
+import type { RawGatewayPresenceUpdate } from '../discord/types/gateway-events.js';
+import { type LoadedActivity, type LoadedPresence } from './declaration.js';
+import type { PresenceContext } from './presence.js';
+export interface RotationOptions {
+    /** Sends a presence to the bot of the moment. */
+    apply(raw: RawGatewayPresenceUpdate): void;
+    /** What the functions receive, or `null` while there is no bot to show it. */
+    context(): PresenceContext | null;
+    /** A function of the file threw, or gave something wrong. Said once until it changes. */
+    onError(error: unknown): void;
+    /** The clock, in milliseconds (tests). */
+    now?: () => number;
+}
+/**
+ * Which activity of a list the clock says to show, and how long until the
+ * next one.
+ */
+export declare function activityAt(activities: readonly LoadedActivity[], now: number): {
+    index: number;
+    left: number;
+};
+/** The presence of the project, shown in turn while it is started. */
+export declare class PresenceRotation {
+    #private;
+    constructor(options: RotationOptions);
+    /** Changes the presence (a load, a reload): shown at once when started. */
+    set(presence: LoadedPresence | null): void;
+    /** Starts showing the presence. */
+    start(): void;
+    /** Stops: nothing runs after this. */
+    stop(): void;
+}

package/dist/presence/rotation.js

@@ -0,0 +1,167 @@
+// Shows the activities of the presence in turn, each for its `for`, and
+// runs the functions of the file when their activity comes: the text of an
+// activity, or the list itself.
+//
+// Which activity is shown is read from the clock: the list is a cycle
+// starting at the epoch, so every process of a large bot shows the same
+// activity at the same time, with nothing to coordinate.
+import { checkText, DEFAULT_FOR, DEFAULT_PRESENCE, readActivities, toRaw, } from './declaration.js';
+/** How long to wait for a bot before trying again. */
+const NO_BOT_RETRY = 1_000;
+/**
+ * Which activity of a list the clock says to show, and how long until the
+ * next one.
+ */
+export function activityAt(activities, now) {
+    const cycle = activities.reduce((sum, one) => sum + one.for, 0);
+    let position = now % cycle;
+    for (const [index, activity] of activities.entries()) {
+        if (position < activity.for) {
+            return { index, left: activity.for - position };
+        }
+        position -= activity.for;
+    }
+    // Not reached: the position is below the cycle.
+    return { index: 0, left: activities[0].for };
+}
+/** The presence of the project, shown in turn while it is started. */
+export class PresenceRotation {
+    #options;
+    #now;
+    #presence = null;
+    #started = false;
+    #timer;
+    /** Each tick has its number: one started since then makes it give up. */
+    #generation = 0;
+    /** The list a function gave last, and until when it is used. */
+    #list = null;
+    #listUntil = 0;
+    /** The last text of each activity a function gave, by its place. */
+    #texts = new Map();
+    /** What was said last of each function (`list`, or the place of an activity). */
+    #problems = new Map();
+    constructor(options) {
+        this.#options = options;
+        this.#now = options.now ?? Date.now;
+    }
+    /** Changes the presence (a load, a reload): shown at once when started. */
+    set(presence) {
+        this.#presence = presence;
+        this.#list = null;
+        this.#texts.clear();
+        this.#problems.clear();
+        if (this.#started)
+            void this.#tick();
+    }
+    /** Starts showing the presence. */
+    start() {
+        this.#started = true;
+        void this.#tick();
+    }
+    /** Stops: nothing runs after this. */
+    stop() {
+        this.#started = false;
+        this.#generation++;
+        clearTimeout(this.#timer);
+    }
+    /** What is shown right now, as the gateway sends it: one step of the cycle. */
+    async #tick() {
+        const generation = ++this.#generation;
+        clearTimeout(this.#timer);
+        const current = () => this.#started && generation === this.#generation;
+        const presence = this.#presence;
+        if (!presence) {
+            this.#options.apply(DEFAULT_PRESENCE);
+            return;
+        }
+        const context = this.#options.context();
+        if (!context) {
+            this.#later(NO_BOT_RETRY);
+            return;
+        }
+        let activities;
+        if (typeof presence.activities === 'function') {
+            if (this.#list === null || this.#now() >= this.#listUntil) {
+                try {
+                    const given = await presence.activities(context);
+                    if (!current())
+                        return;
+                    this.#list = readActivities(given);
+                    this.#texts.clear();
+                    this.#problems.delete('list');
+                }
+                catch (error) {
+                    if (!current())
+                        return;
+                    this.#problem('list', error);
+                    // The last good list stays; none at all shows the status alone.
+                    this.#list ??= [];
+                }
+                const cycle = this.#list.reduce((sum, one) => sum + one.for, 0);
+                this.#listUntil = this.#now() + (cycle || DEFAULT_FOR);
+            }
+            activities = this.#list;
+        }
+        else {
+            activities = presence.activities;
+        }
+        if (activities.length === 0) {
+            this.#options.apply(toRaw(presence.status, null, ''));
+            // A function may give activities later.
+            if (typeof presence.activities === 'function') {
+                this.#later(this.#listUntil - this.#now());
+            }
+            return;
+        }
+        const { index, left } = activityAt(activities, this.#now());
+        const activity = activities[index];
+        let text;
+        if (typeof activity.name === 'function') {
+            try {
+                text = checkText(await activity.name(context));
+                if (!current())
+                    return;
+                this.#texts.set(index, text);
+                this.#problems.delete(`name ${index}`);
+            }
+            catch (error) {
+                if (!current())
+                    return;
+                this.#problem(`name ${index}`, error);
+                text = this.#texts.get(index);
+            }
+        }
+        else {
+            text = activity.name;
+        }
+        if (text !== undefined) {
+            this.#options.apply(toRaw(presence.status, activity, text));
+        }
+        const moves = activities.length > 1 ||
+            typeof activity.name === 'function' ||
+            typeof presence.activities === 'function';
+        if (moves) {
+            // A list that ends before this activity does is asked again then.
+            const until = typeof presence.activities === 'function'
+                ? Math.min(left, Math.max(0, this.#listUntil - this.#now()))
+                : left;
+            this.#later(until);
+        }
+    }
+    #later(ms) {
+        if (!this.#started)
+            return;
+        // At least 1 ms: a list asked again on the very boundary.
+        this.#timer = setTimeout(() => void this.#tick(), Math.max(1, ms));
+        // Nothing of the bot waits for it: the gateway keeps the process up.
+        this.#timer.unref();
+    }
+    /** Says what went wrong with a function, once until it changes. */
+    #problem(what, error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (this.#problems.get(what) === message)
+            return;
+        this.#problems.set(what, message);
+        this.#options.onError(error);
+    }
+}

package/dist/ranking/declaration.d.ts

@@ -0,0 +1,12 @@
+import type { Declaration } from '../loader/loader.js';
+import { type StoreStorage } from '../store/backend.js';
+import type { StoreScope } from '../store/store.js';
+import { type RankingOrder } from './ranking.js';
+/** A ranking, checked: what the project keeps of it. */
+export interface LoadedRanking {
+    readonly name: string;
+    readonly scope: StoreScope;
+    readonly storage: StoreStorage;
+    readonly order: RankingOrder;
+}
+export declare const rankingDeclaration: Declaration<LoadedRanking>;

package/dist/ranking/declaration.js

@@ -0,0 +1,48 @@
+// What a file declares with `ranking()`, checked when it loads, so a wrong
+// scope, storage or order is explained before any score is kept; the
+// ranking is then bound to the name of its export.
+import { STORAGES } from '../store/backend.js';
+import { bindRanking, isRankingDeclaration, rankingStateOf, } from './ranking.js';
+const fail = (message) => {
+    throw new TypeError(message);
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const KEYS = ['scope', 'storage', 'order'];
+const SCOPES = ['guild', 'global'];
+const ORDERS = ['highest', 'lowest'];
+/** A name can name a file in `data/`, like a store's. */
+const NAME = /^[\w.-]+$/;
+export const rankingDeclaration = {
+    one: 'ranking',
+    many: 'rankings',
+    is: isRankingDeclaration,
+    list: false,
+    read(value, { name }) {
+        const config = rankingStateOf(value)?.config;
+        if (!isRecord(config)) {
+            return fail("ranking() takes an object, or nothing: ranking({ order: 'lowest' }).");
+        }
+        for (const key of Object.keys(config)) {
+            if (!KEYS.includes(key)) {
+                fail(`"${key}" is not something a ranking has. It can have: ${KEYS.join(', ')}.`);
+            }
+        }
+        if (!NAME.test(name)) {
+            fail(`"${name}" can't name a ranking: the name of the export is the name of the ranking and of its file in data/, made of letters, digits, _ . and -.`);
+        }
+        const scope = (config.scope ?? 'guild');
+        if (!SCOPES.includes(scope)) {
+            fail(`"scope" is 'guild' (a ranking per server, the default) or 'global' (one ranking for the whole bot), got ${JSON.stringify(config.scope)}.`);
+        }
+        const storage = (config.storage ?? 'file');
+        if (!STORAGES.includes(storage)) {
+            fail(`"storage" is 'file' (a file in data/, the default) or 'redis' (the Redis of REDIS_URL in .env), got ${JSON.stringify(config.storage)}.`);
+        }
+        const order = (config.order ?? 'highest');
+        if (!ORDERS.includes(order)) {
+            fail(`"order" is 'highest' (the highest score first, the default) or 'lowest' (the lowest first), got ${JSON.stringify(config.order)}.`);
+        }
+        bindRanking(value, { name, scope, storage, order });
+        return Object.freeze({ name, scope, storage, order });
+    },
+};

package/dist/ranking/ranking.d.ts

@@ -0,0 +1,102 @@
+import type { Guild } from '../structures/guild.js';
+import { type StoreStorage } from '../store/backend.js';
+import { type RankingOrder } from '../store/ranking-backend.js';
+import type { StoreScope } from '../store/store.js';
+export type { RankingOrder };
+/** What a file gives to `ranking()`. */
+export interface RankingConfig {
+    /**
+     * `'guild'` (the default): a ranking per server, and a function that
+     * runs in a server reads and writes the ranking of that server, with
+     * nothing to say. `'global'`: one ranking for the whole bot.
+     */
+    scope?: StoreScope;
+    /**
+     * Where the scores are kept: `'file'` (the default), a file in the
+     * `data/` folder of the project, or `'redis'`, the Redis of `REDIS_URL`
+     * in `.env`, where a ranking is a sorted set.
+     */
+    storage?: StoreStorage;
+    /**
+     * Which end comes first: `'highest'` (the default), the highest score
+     * first, or `'lowest'`, the lowest first (a time, a number of tries).
+     */
+    order?: RankingOrder;
+}
+/** A member of a ranking, as `top()` lists them. */
+export interface RankingEntry {
+    /** The id given to `add()` or `set()`: a member, or anything else. */
+    id: string;
+    score: number;
+    /** Where it is, from 1. Equal scores are ordered by id. */
+    rank: number;
+}
+/** A ranking, for one server or for the whole bot. */
+export interface ScopedRanking {
+    /**
+     * Adds `points` (negative to take away) to the score of `id`, starting
+     * from 0, in one go: nothing added meanwhile is lost, even by another
+     * process. Resolves with the new score.
+     */
+    add(id: string, points: number): Promise<number>;
+    /** Sets the score of `id`, whatever it was. */
+    set(id: string, score: number): Promise<void>;
+    /** The score of `id`, or `undefined` when it has none. */
+    score(id: string): Promise<number | undefined>;
+    /** Where `id` is, from 1, or `undefined` when it has no score. */
+    rankOf(id: string): Promise<number | undefined>;
+    /**
+     * The first `count` (10 by default) members, after skipping `skip` (0
+     * by default): `top(10, 10)` is the second page.
+     */
+    top(count?: number, skip?: number): Promise<RankingEntry[]>;
+    /** Forgets the score of `id`. `true` when it had one. */
+    remove(id: string): Promise<boolean>;
+    /** How many members have a score. */
+    size(): Promise<number>;
+    /** Forgets every score. Resolves with how many there were. */
+    clear(): Promise<number>;
+}
+/** What `ranking()` returns: a declaration the framework finds in the exports of a file. */
+export interface Ranking extends ScopedRanking {
+    /**
+     * The same ranking, for one server: what a task, or a function that
+     * runs outside a server, uses to read and write the ranking of that
+     * server.
+     */
+    in(guild: Guild | string): ScopedRanking;
+}
+/** A ranking as the loader knows it: its config, and once loaded, its name. */
+export interface RankingState {
+    readonly config: unknown;
+    name?: string;
+    scope: StoreScope;
+    storage: StoreStorage;
+    order: RankingOrder;
+}
+export declare function rankingStateOf(value: unknown): RankingState | undefined;
+export declare const isRankingDeclaration: (value: unknown) => boolean;
+/** Binds a declared ranking to the name of its export. */
+export declare function bindRanking(declared: unknown, bound: {
+    name: string;
+    scope: StoreScope;
+    storage: StoreStorage;
+    order: RankingOrder;
+}): void;
+/**
+ * Declares a ranking: a score per member, kept in order from one restart
+ * to the next. Export the result from any file of `src/`: the name of the
+ * export is the name of the ranking. Per server unless `scope: 'global'`
+ * is given, the highest score first unless `order: 'lowest'` is.
+ *
+ * ```ts
+ * import { ranking } from 'chapterjs';
+ *
+ * export const xp = ranking();
+ *
+ * // In an event of a message, in a server:
+ * await xp.add(message.author.id, 10);
+ * const best = await xp.top(10);
+ * ```
+ */
+export declare function ranking(config?: RankingConfig): Ranking;

package/dist/ranking/ranking.js

@@ -0,0 +1,129 @@
+// What a file declares with `ranking()`: scores per member, kept in order,
+// per server by default, from one restart to the next. Named by its
+// export, like a store: `export const xp = ranking()` is the ranking `xp`.
+// Its scores live where its `storage` says, through the rankings of that
+// backend (`store/ranking-backend.ts`): sorted sets in Redis, entries of
+// the store backend anywhere else.
+import { storeBackend } from '../store/backend.js';
+import { rankingsOf, } from '../store/ranking-backend.js';
+import { currentGuildId, guildIdOf, scopeParts } from '../store/scope.js';
+const STATE = Symbol.for('chapterjs.ranking');
+export function rankingStateOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    return value[STATE];
+}
+export const isRankingDeclaration = (value) => rankingStateOf(value) !== undefined;
+/** Binds a declared ranking to the name of its export. */
+export function bindRanking(declared, bound) {
+    const state = rankingStateOf(declared);
+    if (!state)
+        throw new TypeError('Not a ranking.');
+    Object.assign(state, bound);
+}
+const checkId = (id) => {
+    if (typeof id !== 'string' || id === '') {
+        throw new TypeError(`The id of a member of a ranking is a text that is not empty, got ${JSON.stringify(id) ?? typeof id}. Write an id as a text: member.id, not a number.`);
+    }
+    return id;
+};
+const checkScore = (value, what) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new TypeError(`${what} is a number, got ${JSON.stringify(value) ?? typeof value}.`);
+    }
+    return value;
+};
+const checkCount = (value, what) => {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new TypeError(`${what} is a whole number, 0 or more, got ${JSON.stringify(value) ?? typeof value}.`);
+    }
+    return value;
+};
+/** The ranking as its functions see it: the backend, the name, the scope. */
+function scoped(state, guildOf) {
+    const ready = () => {
+        if (!state.name) {
+            throw new Error('This ranking was not loaded by ChapterJS: a ranking is exported from a file of src/ (export const name = ranking()), and used once the bot started.');
+        }
+        return {
+            backend: rankingsOf(storeBackend(state.storage, state.name)),
+            name: state.name,
+            scope: scopeParts('ranking', state.name, state.scope, guildOf),
+        };
+    };
+    return {
+        async add(id, points) {
+            const { backend, name, scope } = ready();
+            return backend.add(name, scope, checkId(id), checkScore(points, 'What add() adds'));
+        },
+        async set(id, score) {
+            const { backend, name, scope } = ready();
+            await backend.set(name, scope, checkId(id), checkScore(score, 'The score set()'));
+        },
+        async score(id) {
+            const { backend, name, scope } = ready();
+            return backend.score(name, scope, checkId(id));
+        },
+        async rankOf(id) {
+            const { backend, name, scope } = ready();
+            const rank = await backend.rank(name, scope, checkId(id), state.order);
+            return rank === undefined ? undefined : rank + 1;
+        },
+        async top(count = 10, skip = 0) {
+            const { backend, name, scope } = ready();
+            checkCount(count, 'How many top() lists');
+            checkCount(skip, 'How many top() skips');
+            const ranked = await backend.range(name, scope, state.order, skip, count);
+            return ranked.map((entry, index) => ({
+                id: entry.id,
+                score: entry.score,
+                rank: skip + index + 1,
+            }));
+        },
+        async remove(id) {
+            const { backend, name, scope } = ready();
+            return backend.remove(name, scope, checkId(id));
+        },
+        async size() {
+            const { backend, name, scope } = ready();
+            return backend.size(name, scope);
+        },
+        async clear() {
+            const { backend, name, scope } = ready();
+            return backend.clear(name, scope);
+        },
+    };
+}
+/**
+ * Declares a ranking: a score per member, kept in order from one restart
+ * to the next. Export the result from any file of `src/`: the name of the
+ * export is the name of the ranking. Per server unless `scope: 'global'`
+ * is given, the highest score first unless `order: 'lowest'` is.
+ *
+ * ```ts
+ * import { ranking } from 'chapterjs';
+ *
+ * export const xp = ranking();
+ *
+ * // In an event of a message, in a server:
+ * await xp.add(message.author.id, 10);
+ * const best = await xp.top(10);
+ * ```
+ */
+export function ranking(config = {}) {
+    const state = {
+        config,
+        scope: 'guild',
+        storage: 'file',
+        order: 'highest',
+    };
+    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/redis/client.d.ts

@@ -0,0 +1,36 @@
+import { type RedisReply } from './protocol.js';
+import { type RedisAddress } from './url.js';
+export interface RedisClientOptions {
+    /** The connection could not be made, or was lost: said once per outage. */
+    onError?: (message: string) => void;
+    /** The connection is back after an outage. */
+    onReconnect?: () => void;
+    /** How long a connection attempt may take. */
+    connectTimeout?: number;
+    /** The first wait before trying again, doubled each time up to `maxRetryDelay`. */
+    retryDelay?: number;
+    maxRetryDelay?: number;
+}
+/** One connection to Redis, which only opens when a command needs it. */
+export declare class RedisClient {
+    #private;
+    readonly address: RedisAddress;
+    constructor(address: RedisAddress, options?: RedisClientOptions);
+    /** `host:port` and the database, for messages. */
+    get where(): string;
+    /** Whether a command sent now goes out at once. */
+    get connected(): boolean;
+    /**
+     * Sends a command and resolves with its reply. An error reply (`-ERR`)
+     * rejects with a `RedisError`; a connection that fails or is lost
+     * rejects with what happened, in plain words.
+     */
+    send(...args: readonly (string | number)[]): Promise<RedisReply>;
+    /**
+     * Makes sure Redis answers: the connection is opened, logged in and on
+     * the right database, or the reason it can't be is thrown.
+     */
+    ping(): Promise<void>;
+    /** Ends the connection; every command sent from now on fails. */
+    close(): Promise<void>;
+}