chapterjs 0.2.3 → 0.4.0

package/dist/cli/project.js

@@ -16,13 +16,14 @@ import { componentDeclaration, findDuplicates, } from '../components/declaration
 import { ComponentRouter } from '../components/router.js';
 import { taskDeclaration } from '../tasks/declaration.js';
 import { storeDeclaration } from '../store/declaration.js';
-import { setStoreBackend } from '../store/backend.js';
+import { rankingDeclaration, } from '../ranking/declaration.js';
+import { nowhereToKeep, NowhereToKeepError, setStoreBackend, STORAGES, } from '../store/backend.js';
 import { DATA_FOLDER, FileStoreBackend } from '../store/file-backend.js';
 import { DEFAULT_PRESENCE, presenceDeclaration, } from '../presence/declaration.js';
 import { assembleMessages, commandsDeclarations, languageDeclaration, languageDefaultsDeclaration, messagesDeclarations, scanLanguages, } from '../messages/declaration.js';
 import { translation } from '../messages/translate.js';
 import { translateCommand, unknownCommands } from '../messages/commands.js';
-import { TimerScheduler, } from '../tasks/scheduler.js';
+import { runTask, TimerScheduler, } from '../tasks/scheduler.js';
 import { createBot } from '../core/bot.js';
 import { watchMemory } from '../core/memory.js';
 import { GatewayIntent } from '../discord/intents.js';
@@ -68,15 +69,35 @@ export const DECLARATIONS = [
     componentDeclaration,
     taskDeclaration,
     storeDeclaration,
+    rankingDeclaration,
     presenceDeclaration,
     languageDeclaration,
 ];
+/**
+ * A promise of the files that nobody waited for (`store.set()` without
+ * `await`, in a `run` that is not `async`) rejects with nobody to tell:
+ * Node would stop the bot. Reported instead, with the file and the line,
+ * and what to write. A rejection from outside the files stays what it is:
+ * a bug of the framework, loud. Returns what stops watching.
+ */
+export function reportLooseRejections(cwd, log) {
+    const listener = (reason) => {
+        const where = locate(reason, cwd);
+        if (!where)
+            throw reason;
+        log.error(`${where.file}:${where.line} ${messageOf(reason)}\nThis call was not awaited: write await in front of it (and async before run), so that your function waits for it.`);
+    };
+    process.on('unhandledRejection', listener);
+    return () => {
+        process.off('unhandledRejection', listener);
+    };
+}
 /** Whether the folder is a project: it has a `src` folder. */
 export async function hasSources(cwd, log) {
     if ((await stat(join(cwd, 'src')).catch(() => null))?.isDirectory()) {
         return true;
     }
-    log.error('There is no src folder here.\nRun this command in the folder of your bot (the one with package.json), or create a project with "pnpm create chapter".');
+    log.error('There is no src folder here.\nRun this command in the folder of your bot (the one with package.json), or create a project with "pnpm create chapterjs".');
     return false;
 }
 /** The intents that only bring what happens in private messages. */
@@ -108,10 +129,11 @@ function sameNames(entries, nameOf, what) {
             seen.set(nameOf(entry), entry);
             return true;
         }
+        const kind = (one) => typeof what === 'string' ? what : what(one);
         conflicts.push({
             file: entry.file,
             export: entry.export,
-            message: `There is already a ${what} named ${nameOf(entry)}, in ${first.file}: the name of the export is the name of the ${what}, so rename one of them.`,
+            message: `There is already a ${kind(first)} named ${nameOf(entry)}, in ${first.file}: the name of the export is the name of the ${kind(entry)}, so rename one of them.`,
         });
         return false;
     });
@@ -121,9 +143,18 @@ export function createProject(options) {
     const { cwd, log } = options;
     // Where `asset()` reads the files of the project from.
     setPublicDir(cwd);
-    // Where the stores keep their data, for every store of the process.
-    const storeBackend = options.stores ?? new FileStoreBackend(join(cwd, DATA_FOLDER));
-    setStoreBackend(storeBackend);
+    // Where the stores keep their data, for every store of the process: a
+    // backend per storage the project has one for.
+    const storeBackends = new Map();
+    for (const storage of STORAGES) {
+        const backend = options.stores?.[storage] ??
+            (storage === 'file'
+                ? new FileStoreBackend(join(cwd, DATA_FOLDER))
+                : null);
+        setStoreBackend(storage, backend);
+        if (backend)
+            storeBackends.set(storage, backend);
+    }
     const report = (failure) => {
         const where = locate(failure.error, cwd);
         log.error(`${where ? `${where.file}:${where.line}` : siteName(failure)} ${messageOf(failure.error)}`);
@@ -150,6 +181,7 @@ export function createProject(options) {
     let components = new Map();
     let tasks = new Map();
     let stores = new Map();
+    let rankings = new Map();
     let presence = null;
     /** The files the presence was declared in, to keep it when they break. */
     let presenceFiles = new Set();
@@ -182,7 +214,20 @@ export function createProject(options) {
         get stores() {
             return stores;
         },
-        storeBackend,
+        storeBackends,
+        get rankings() {
+            return rankings;
+        },
+        redisStores: () => ({
+            stores: [...stores.values()]
+                .filter(entry => entry.store.storage === 'redis')
+                .map(entry => entry.store.name)
+                .sort(),
+            rankings: [...rankings.values()]
+                .filter(entry => entry.ranking.storage === 'redis')
+                .map(entry => entry.ranking.name)
+                .sort(),
+        }),
         get presence() {
             return presence;
         },
@@ -213,12 +258,13 @@ export function createProject(options) {
             // then read, kind by kind.
             const sources = built ? { modules: built, failed: [] } : await loadSources(cwd);
             const read = (declaration) => readDeclarations(sources.modules, declaration);
-            const [eventItems, commandItems, componentItems, taskItems, storeItems, presenceItems, languageItems,] = [
+            const [eventItems, commandItems, componentItems, taskItems, storeItems, rankingItems, presenceItems, languageItems,] = [
                 read(eventDeclaration),
                 read(commandDeclaration),
                 read(componentDeclaration),
                 read(taskDeclaration),
                 read(storeDeclaration),
+                read(rankingDeclaration),
                 read(presenceDeclaration),
                 read(languageDeclaration),
             ];
@@ -272,15 +318,34 @@ export function createProject(options) {
             ], entry => entry.task.name, 'task');
             tasks = new Map(sameTask.valid.map(entry => [keyOf(entry), entry]));
             scheduler.set(tasks.values());
-            // Two stores with one name would share one file: the later is left out.
+            const keptOf = (entry) => 'store' in entry ? entry.store : entry.ranking;
             const sameStore = sameNames([
                 ...next(stores, storeItems, item => ({
                     file: item.file,
                     export: item.export,
                     store: item.value,
                 })).values(),
-            ], entry => entry.store.name, 'store');
-            stores = new Map(sameStore.valid.map(entry => [keyOf(entry), entry]));
+                ...next(rankings, rankingItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    ranking: item.value,
+                })).values(),
+            ], entry => keptOf(entry).name, entry => ('store' in entry ? 'store' : 'ranking'));
+            // What is kept where nothing keeps it (Redis without REDIS_URL) is
+            // reported and left out: it says so itself when used.
+            const unkept = sameStore.valid.filter(entry => !storeBackends.has(keptOf(entry).storage));
+            const kept = sameStore.valid.filter(entry => !unkept.includes(entry));
+            stores = new Map(kept
+                .filter((entry) => 'store' in entry)
+                .map(entry => [keyOf(entry), entry]));
+            rankings = new Map(kept
+                .filter((entry) => 'ranking' in entry)
+                .map(entry => [keyOf(entry), entry]));
+            const nowhere = unkept.map(entry => ({
+                file: entry.file,
+                export: entry.export,
+                error: new NowhereToKeepError(nowhereToKeep(keptOf(entry).storage, keptOf(entry).name, 'store' in entry ? 'store' : 'ranking')),
+            }));
             // One presence. A second one is left out.
             const [first, ...extra] = presenceItems.loaded;
             if (first)
@@ -369,10 +434,12 @@ export function createProject(options) {
                 ...componentItems.failed,
                 ...taskItems.failed,
                 ...storeItems.failed,
+                ...rankingItems.failed,
                 ...presenceItems.failed,
                 ...languageItems.failed,
                 ...badTexts,
                 ...twice,
+                ...nowhere,
                 ...[
                     ...conflicts,
                     ...unique.conflicts,
@@ -404,6 +471,9 @@ export function createProject(options) {
                     : []),
                 ...(tasks.size > 0 ? [count(tasks.size, 'task', 'tasks')] : []),
                 ...(stores.size > 0 ? [count(stores.size, 'store', 'stores')] : []),
+                ...(rankings.size > 0
+                    ? [count(rankings.size, 'ranking', 'rankings')]
+                    : []),
                 ...(presence ? ['a presence'] : []),
                 ...(messages
                     ? [
@@ -417,11 +487,15 @@ export function createProject(options) {
             components.size === 0 &&
             tasks.size === 0 &&
             stores.size === 0 &&
+            rankings.size === 0 &&
             presence === null &&
             messages === null,
-        filesNeeding: intent => [...events.values()]
-            .filter(({ event }) => (intentsOf(event) & GatewayIntent[intent]) !== 0)
-            .map(({ file }) => file),
+        // A file declaring several events that need the intent is named once.
+        filesNeeding: intent => [
+            ...new Set([...events.values()]
+                .filter(({ event }) => (intentsOf(event) & GatewayIntent[intent]) !== 0)
+                .map(({ file }) => file)),
+        ],
         intents: (privateEvents = true) => neededIntents() & (privateEvents ? ~0 : ~PRIVATE_INTENTS),
         async connect(connection) {
             const created = createBot({
@@ -449,14 +523,17 @@ export function createProject(options) {
                 },
                 beforeDispatch: (event, data) => router.before(created.ctx, event, data),
                 onDispatch(event, data, info) {
-                    router.dispatch(created.ctx, event, data, {
+                    const handled = router.dispatch(created.ctx, event, data, {
                         joined: info.joined,
                         before: info.before,
                     });
+                    options.observe?.event?.(event, data, handled);
                     if (event === 'INTERACTION_CREATE') {
                         const interaction = data;
-                        commandRouter.dispatch(created.ctx, interaction);
-                        componentRouter.dispatch(created.ctx, interaction);
+                        const answered = commandRouter.dispatch(created.ctx, interaction) ??
+                            componentRouter.dispatch(created.ctx, interaction) ??
+                            Promise.resolve();
+                        options.observe?.interaction?.(interaction, answered);
                     }
                 },
                 onEvent(event) {
@@ -518,9 +595,16 @@ export function createProject(options) {
             });
         },
         stopTasks: () => scheduler.stop(),
+        runTask(entry, bot, now = new Date()) {
+            const user = bot.ctx.cache.users.get(bot.ctx.self.userId);
+            return runTask(entry, { user, guilds: bot.ctx.cache.guilds, ...translation(bot.ctx, null) }, now, reporter.onError);
+        },
         // The bot looks after its own memory: it remembers less before memory
         // is full, and only speaks up when it can't give up anything more.
-        closeStores: () => storeBackend.close(),
+        closeStores: async () => {
+            for (const backend of storeBackends.values())
+                await backend.close();
+        },
         watchMemory: current => watchMemory({
             cache: () => current()?.ctx.cache,
             onTightened: ({ members, forgotten }, { used, limit }) => log.info(`Memory was getting full (${megabytes(used)} of ${megabytes(limit)}): the bot now remembers ${members} members per server at most, and forgot ${forgotten} members and users it had not seen for the longest. Nothing changes for your code.`),

package/dist/cli/redis.d.ts

@@ -0,0 +1,23 @@
+import type { RedisAddress } from '../redis/url.js';
+import { RedisStoreBackend } from '../store/redis-backend.js';
+import type { Log } from './log.js';
+import type { Project } from './project.js';
+/**
+ * The backend of the stores kept in Redis. Nothing is connected until a
+ * store is used, or `checkRedis()` asks; an outage is said once with `⚠`
+ * and its end with `↻`.
+ */
+export declare function redisStores(address: RedisAddress, log: Log, options?: {
+    prefix?: string;
+}): RedisStoreBackend;
+/**
+ * The `ℹ` line naming the stores and rankings kept in Redis, or `null`
+ * without any: "The store sessions and the ranking xp are kept in Redis…".
+ */
+export declare function describeRedisStores(project: Project, backend: RedisStoreBackend | null): string | null;
+/**
+ * Makes sure Redis answers before the bot goes online, when a store is
+ * kept there: a Redis that can't be reached is an error now, not when
+ * someone uses the bot.
+ */
+export declare function checkRedis(project: Project, backend: RedisStoreBackend | null, log: Log): Promise<boolean>;

package/dist/cli/redis.js

@@ -0,0 +1,57 @@
+// What `dev` and `start` share about Redis: the backend made of
+// `REDIS_URL`, checked before Discord is reached when a store needs it,
+// and the line that says which stores are kept there.
+import { RedisClient } from '../redis/client.js';
+import { RedisStoreBackend } from '../store/redis-backend.js';
+/**
+ * The backend of the stores kept in Redis. Nothing is connected until a
+ * store is used, or `checkRedis()` asks; an outage is said once with `⚠`
+ * and its end with `↻`.
+ */
+export function redisStores(address, log, options = {}) {
+    const client = new RedisClient(address, {
+        onError: message => log.warn(message),
+        onReconnect: () => log.reload(`Redis at ${client.where} is back`),
+    });
+    return new RedisStoreBackend(client, options);
+}
+/** `a`, `a and b`, `a, b and c`. */
+const and = (items) => items.length <= 1
+    ? (items[0] ?? '')
+    : `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`;
+/**
+ * The `ℹ` line naming the stores and rankings kept in Redis, or `null`
+ * without any: "The store sessions and the ranking xp are kept in Redis…".
+ */
+export function describeRedisStores(project, backend) {
+    const { stores, rankings } = project.redisStores();
+    const total = stores.length + rankings.length;
+    if (!backend || total === 0)
+        return null;
+    const group = (one, many, names) => names.length === 0
+        ? []
+        : [`the ${names.length === 1 ? one : many} ${and(names)}`];
+    const list = and([
+        ...group('store', 'stores', stores),
+        ...group('ranking', 'rankings', rankings),
+    ]);
+    return `${list[0].toUpperCase()}${list.slice(1)} ${total === 1 ? 'is' : 'are'} kept in Redis at ${backend.client.where}`;
+}
+/**
+ * Makes sure Redis answers before the bot goes online, when a store is
+ * kept there: a Redis that can't be reached is an error now, not when
+ * someone uses the bot.
+ */
+export async function checkRedis(project, backend, log) {
+    const { stores, rankings } = project.redisStores();
+    if (!backend || stores.length + rankings.length === 0)
+        return true;
+    try {
+        await backend.client.ping();
+        return true;
+    }
+    catch (error) {
+        log.error(`${error instanceof Error ? error.message.replace(/ Trying again in \d+ s\.$/, '') : String(error)}`);
+        return false;
+    }
+}

package/dist/cli/start.js

@@ -2,6 +2,8 @@
 // Nothing is reloaded, commands are registered for every server, and a
 // large bot is spread over several processes by itself.
 import { IpcStoreBackend } from '../store/ipc-backend.js';
+import { NowhereToKeepError } from '../store/backend.js';
+import { checkRedis, describeRedisStores, redisStores } from './redis.js';
 import { registerCommands } from '../commands/register.js';
 import { buildCommands } from '../commands/tree.js';
 import { GLOBAL_REQUESTS_PER_SECOND } from '../discord/api.js';
@@ -13,7 +15,7 @@ import { connectToPrimary, planProcesses, REFUSED, runCluster, } from './cluster
 import { loadBundle, readBuild } from './build.js';
 import { readStartEnv } from './env.js';
 import { describeIntents, ensurePrivilegedIntents, fetchApplication, } from './preflight.js';
-import { createProject, explain } from './project.js';
+import { createProject, explain, reportLooseRejections, } from './project.js';
 /** Runs until stopped. Resolves with the exit code of the process. */
 export async function start(options) {
     const { cwd, log, signal } = options;
@@ -49,25 +51,30 @@ export async function start(options) {
         }
         return 1;
     }
+    // Every process reaches Redis itself: it is made to be shared.
+    const redis = read.env.redis ? redisStores(read.env.redis, log) : null;
     const project = createProject({
         cwd,
         version: options.version,
         log,
         built: files,
         joinsVoice: built.info.voice === true,
-        // A process started by another keeps no data: the first one does, for
-        // all of them.
-        ...(assignment
-            ? {
-                stores: new IpcStoreBackend({
-                    send: message => {
-                        if (process.connected)
-                            process.send?.(message);
-                    },
-                    on: listener => process.on('message', listener),
-                }),
-            }
-            : {}),
+        stores: {
+            // A process started by another keeps no file: the first one does,
+            // for all of them.
+            ...(assignment
+                ? {
+                    file: new IpcStoreBackend({
+                        send: message => {
+                            if (process.connected)
+                                process.send?.(message);
+                        },
+                        on: listener => process.on('message', listener),
+                    }),
+                }
+                : {}),
+            ...(redis ? { redis } : {}),
+        },
         ...(options.deferAfter === undefined
             ? {}
             : { deferAfter: options.deferAfter }),
@@ -77,7 +84,12 @@ export async function start(options) {
         for (const failure of failures)
             project.report(failure);
         if (!assignment) {
-            log.error(`${failures.length === 1 ? 'This file' : `These ${failures.length} files`} of the build can't run any more, so the bot was not started. Run "chapterjs build" again: it says what to fix.`);
+            // A store kept in Redis without REDIS_URL is about the environment,
+            // not the build.
+            const unkept = failures.every(failure => failure.error instanceof NowhereToKeepError);
+            log.error(unkept
+                ? 'The bot was not started. Give REDIS_URL to the bot the way your host does it (its "environment variables" or "secrets"), or in a .env file in this folder.'
+                : `${failures.length === 1 ? 'This file' : `These ${failures.length} files`} of the build can't run any more, so the bot was not started. Run "chapterjs build" again: it says what to fix.`);
         }
         return 1;
     }
@@ -94,10 +106,18 @@ export async function start(options) {
             ? { guildFilter: (id) => id !== devGuildId }
             : {}),
     };
+    // A promise of the files left alone is an error of the file, not the end
+    // of the bot: in every process, since every one runs the files.
+    const loose = reportLooseRejections(cwd, log);
     try {
         if (assignment)
             return await runShare(project, options, connection, assignment);
-        // 3. What Discord must agree with, checked once for every process.
+        // 3. What Redis, then Discord, must agree with, checked once for every
+        // process.
+        if (!(await checkRedis(project, redis, log))) {
+            await project.closeStores();
+            return 1;
+        }
         const rest = new RestClient({
             token,
             version: options.version,
@@ -132,6 +152,9 @@ export async function start(options) {
             log.success(`Online as ${user} in ${guilds} ${guilds === 1 ? 'server' : 'servers'}${split ? ` (${split})` : ''}`);
             log.info(`Intents computed from your files: ${describeIntents(intents)}`);
             (project.isEmpty() ? log.info : log.success)(project.summary());
+            const kept = describeRedisStores(project, redis);
+            if (kept)
+                log.info(kept);
         };
         if (processes === 1) {
             return await runAlone(project, options, connection, online);
@@ -146,7 +169,7 @@ export async function start(options) {
             signal,
             identifyInterval,
             write: options.write,
-            stores: project.storeBackend,
+            stores: project.storeBackends.get('file'),
             onReady: ({ user, guilds }) => online(user, guilds),
             onRestart: (index, why) => log.warn(`Process ${index + 1} of ${processes} stopped by itself (${why}): starting it again. Its servers are back in a moment.`),
         });
@@ -162,6 +185,9 @@ export async function start(options) {
         explain(error, log);
         return assignment ? REFUSED : 1;
     }
+    finally {
+        loose();
+    }
 }
 /** Runs a bot until it is stopped or Discord refuses it. */
 async function run(project, connection, stopped, connected, { tasks = true } = {}) {

package/dist/cli/test.d.ts

@@ -0,0 +1,29 @@
+import type { Log } from './log.js';
+export interface TestOptions {
+    /** The folder of the project. */
+    cwd: string;
+    /** The version of the framework. */
+    version: string;
+    log: Log;
+    /** How long a scenario may take, in milliseconds. Default: 10 s. */
+    scenarioTimeout?: number;
+    /**
+     * Whether a person is watching a terminal: the check in progress is then
+     * shown, case by case, and replaced by its result once done.
+     */
+    progress?: boolean;
+}
+/**
+ * What a terminal shows while a file is tested: `↻ Testing src/close.ts`,
+ * then one line per thing and case as it is tried. Once the file is done,
+ * those lines are erased and its result takes their place, so a report
+ * that passed reads as if nothing had moved. When nobody is watching (the
+ * output is not a terminal), nothing is shown meanwhile.
+ */
+export declare function checkProgress(enabled: boolean, log: Pick<Log, 'reload'>, write: (text: string) => void): {
+    start(title: string): void;
+    step(label: string): void;
+    clear(): void;
+};
+/** Resolves with the exit code of the process. */
+export declare function test(options: TestOptions): Promise<number>;