chapterjs 0.2.3 → 0.4.0

package/README.md

@@ -0,0 +1,65 @@
+# ChapterJS
+
+**The Discord framework: ultra simple, but ultra customizable.**
+
+Drop files into `src/`, and the `chapterjs` CLI does everything else: the connection, the intents, the registration of commands, hot reload, sharding and several processes for large bots. Everything you write is typed end to end, without a single type to write.
+
+```bash
+pnpm create chapterjs my-bot
+```
+
+📖 Documentation, in English and in French: **[chapterjs.org](https://www.chapterjs.org)**
+
+## A file is what it exports
+
+```ts
+// src/commands/hello.ts
+import { command } from 'chapterjs';
+
+export default command({
+  name: 'hello',
+  description: 'Says hello to someone',
+  cooldown: '10s',
+  options: {
+    who: { type: 'user', description: 'Who to greet', required: true },
+  },
+  async run({ interaction, options }) {
+    // options.who is a User: typed from the options above.
+    await interaction.reply(`Hello ${options.who}!`);
+  },
+});
+```
+
+The framework loads every file of `src/`, wherever it is and whatever it is called, and runs what the files export: `command()`, `event()`, `button()`, `select()`, `modal()`, `embed()`, `task()`, `store()`, `ranking()`, `presence()`, `language()`. The folders are yours to organise with.
+
+## What it does
+
+- **Slash commands** with typed options, choices, autocomplete, permissions, cooldowns and translations.
+- **Events**: the intents follow from the files you write, privileged ones included, with a direct link when one must be enabled.
+- **Components**: buttons, select menus, forms and embeds, with typed `data` carried in the message and no id to write.
+- **Tasks**: every so often or with a cron, in the timezone you choose.
+- **Storage**: `store<Warning[]>({ expires: '30d' })` keeps data from one restart to the next, per server, typed, in a JSON file written for you, or in Redis with `storage: 'redis'` and a `REDIS_URL`; `ranking()` keeps a score per member in order, for leaderboards.
+- **Translated messages**: `t('welcome', { name })` speaks the language of who will read it.
+- **Voice**: join a channel and play a file, an attachment or a link, end-to-end encrypted (DAVE).
+- **Tests**: `chapterjs test` runs the bot against a Discord in memory, no token needed: every file is used once by itself, then your scenarios (`scenario('ping answers Pong', async bot => { … })`) say what the bot should answer.
+
+## Four commands
+
+- `chapterjs dev` runs the bot on a test server and reloads each file when you save it. A broken file is reported with its line and never stops the bot.
+- `chapterjs test` checks the bot without Discord, with nothing written and with your scenarios.
+- `chapterjs build` checks every file and the types, then compiles the bot into one JavaScript file.
+- `chapterjs start` runs it in production, on several processes when the bot is large.
+
+Nothing to install to run a bot: the framework only uses what Node has (Node 24 or later). Discord's rate limits, payload sizes and reconnections are handled for you.
+
+## Versions
+
+`chapterjs`, `create-chapterjs` and `create-chapter` are always released with the same version, and follow [semantic versioning](https://semver.org): what a bot's files use (the functions exported by `chapterjs`, their options, what your functions receive, the files and env vars of a project, the CLI commands) only changes in a major version. A new feature comes in a minor one, a fix in a patch. The [changelog](https://www.chapterjs.org/changelog) says what each version brings, and `chapterjs dev` tells you when a new one is out.
+
+## Contributing
+
+The source, the issues and the documentation live in [github.com/chapterjs/chapterjs](https://github.com/chapterjs/chapterjs). Read [CONTRIBUTING.md](https://github.com/chapterjs/chapterjs/blob/master/CONTRIBUTING.md) to get started.
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli/build.js

@@ -15,6 +15,7 @@ import { pathToFileURL } from 'node:url';
 import { enableProjectLoader } from '../loader/hot.js';
 import { listSources } from '../loader/loader.js';
 import { sourcesJoinVoice } from '../voice/usage.js';
+import { MemoryStoreBackend } from '../store/memory-backend.js';
 import { createProject, hasSources, writeTypes } from './project.js';
 /** Where the build of a project is, from its folder. */
 export const buildDir = (cwd) => join(cwd, '.chapterjs', 'build');
@@ -105,7 +106,18 @@ export async function build(options) {
     };
     // 1. Every file must run, one by one: each says what is wrong with it.
     enableProjectLoader(src, { reload: false });
-    const sources = createProject({ cwd, version: options.version, log });
+    // The files run once and keep nothing: a store, wherever it says it
+    // keeps its data, has nowhere to go (so a build needs no Redis).
+    const nothing = {
+        file: new MemoryStoreBackend(),
+        redis: new MemoryStoreBackend(),
+    };
+    const sources = createProject({
+        cwd,
+        version: options.version,
+        log,
+        stores: nothing,
+    });
     const failures = await sources.load();
     // 2. Types: what the editor underlines, for the whole project. Written
     // once the files ran, so a language only offers the commands they do
@@ -181,6 +193,7 @@ export async function build(options) {
         version: options.version,
         log,
         built: await loadBundle(cwd),
+        stores: nothing,
     });
     const broken = await built.load();
     if (broken.length > 0) {

package/dist/cli/cli.js

@@ -7,6 +7,7 @@ import { writeTypes } from './project.js';
 import { createLog } from './log.js';
 import { nodeTooOld } from './node-version.js';
 import { start } from './start.js';
+import { test } from './test.js';
 const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 const USAGE = `Usage: chapterjs <command>
 
@@ -14,6 +15,7 @@ Commands:
   dev     Run your bot on your dev server and reload it when you save a file
   build   Check your bot and prepare it for production
   start   Run for everyone the bot that was built
+  test    Check your bot without Discord: every file once, then your scenarios
   sync    Write the types of your project (dev does it too)
 
 Options of start:
@@ -29,19 +31,40 @@ if (tooOld) {
 const [command, ...rest] = process.argv.slice(2);
 /**
  * Ctrl+C and a stop asked by the system both end the session cleanly, so
- * the bot goes offline at once. A second one does not wait.
+ * the bot goes offline at once. A second one, pressed while the first is
+ * still being handled, does not wait.
+ *
+ * One Ctrl+C reaches the bot twice when a package manager runs it (`pnpm
+ * dev`): once from the terminal, which signals every process of the
+ * foreground group, and once forwarded by the package manager. Two signals
+ * within a second are that one Ctrl+C, not a second one.
  */
 function stopSignal() {
     const controller = new AbortController();
+    let askedAt = 0;
     for (const name of ['SIGINT', 'SIGTERM']) {
         process.on(name, () => {
-            if (controller.signal.aborted)
-                process.exit(1);
+            const now = Date.now();
+            if (controller.signal.aborted) {
+                if (now - askedAt >= 1000)
+                    process.exit(1);
+                return;
+            }
+            askedAt = now;
             controller.abort();
         });
     }
     return controller.signal;
 }
+/**
+ * Ends the process once everything printed has reached the terminal. When
+ * the output is a pipe (`pnpm test` puts one between itself and the
+ * command), writes are asynchronous on macOS and Windows: `process.exit()`
+ * right after the last line would cut it.
+ */
+function exit() {
+    process.stdout.write('', () => process.exit());
+}
 /** `--processes 4` or `--processes=4`; `null` when it is not a count. */
 function readProcesses(args) {
     const index = args.findIndex(arg => arg === '--processes' || arg.startsWith('--processes='));
@@ -66,7 +89,7 @@ if (command === 'dev') {
         signal: controller.signal,
     });
     // Nothing may keep the process alive once the bot is disconnected.
-    process.exit();
+    exit();
 }
 else if (command === 'start') {
     const processes = readProcesses(rest);
@@ -91,7 +114,7 @@ else if (command === 'start') {
             script: process.argv[1],
             args: ['start'],
         });
-        process.exit();
+        exit();
     }
 }
 else if (command === 'sync') {
@@ -108,7 +131,19 @@ else if (command === undefined || command === '--help' || command === '-h') {
 }
 else if (command === 'build') {
     process.exitCode = await build({ cwd: process.cwd(), version, log });
-    process.exit();
+    exit();
+}
+else if (command === 'test') {
+    // How long a scenario may take: only tests shorten it.
+    const scenarioTimeout = Number(process.env.CHAPTERJS_SCENARIO_TIMEOUT);
+    process.exitCode = await test({
+        cwd: process.cwd(),
+        version,
+        log,
+        ...(scenarioTimeout > 0 ? { scenarioTimeout } : {}),
+        progress: process.stdout.isTTY === true,
+    });
+    exit();
 }
 else {
     log.error(`"${command}" is not a command.\n${USAGE}`);

package/dist/cli/dev.js

@@ -16,7 +16,9 @@ import { snapshotFolder, watchFolder } from '../loader/watch.js';
 import { RestClient } from '../rest/rest.js';
 import { readDevEnv } from './env.js';
 import { describeIntents, ensureInDevGuild, ensurePrivilegedIntents, fetchApplication, } from './preflight.js';
-import { createProject, explain, hasSources, writeTypes } from './project.js';
+import { createProject, explain, hasSources, reportLooseRejections, writeTypes, } from './project.js';
+import { checkRedis, describeRedisStores, redisStores } from './redis.js';
+import { DEV_PREFIX } from '../store/redis-backend.js';
 import { checkForUpdate, describeUpdate } from './update-check.js';
 /** Runs until stopped. Resolves with the exit code of the process. */
 export async function dev(options) {
@@ -30,8 +32,16 @@ export async function dev(options) {
     }
     const { token, devGuildId } = read.env;
     const src = join(cwd, 'src');
+    // Every key written from here starts with `dev:`: a Redis shared with
+    // production, which the docs advise against, is never mixed up.
+    const redis = read.env.redis
+        ? redisStores(read.env.redis, log, { prefix: DEV_PREFIX })
+        : null;
     if (!(await hasSources(cwd, log)))
         return 1;
+    // A promise of the files left alone is an error of the file, not the end
+    // of the bot.
+    const loose = reportLooseRejections(cwd, log);
     // Asked now, said once the bot is online: the registry answers while the
     // files load and Discord is checked, so nobody waits for it.
     const update = checkForUpdate({
@@ -44,6 +54,7 @@ export async function dev(options) {
         cwd,
         version: options.version,
         log,
+        ...(redis ? { stores: { redis } } : {}),
         ...(options.deferAfter === undefined
             ? {}
             : { deferAfter: options.deferAfter }),
@@ -57,6 +68,12 @@ export async function dev(options) {
     // Now that the files ran, a language only offers the commands they do
     // not describe, and `t` is typed from the default language.
     await writeTypes(cwd, project.typesInfo());
+    // A store kept in Redis needs it now, not when someone uses the bot.
+    if (!(await checkRedis(project, redis, log))) {
+        await project.closeStores();
+        return 1;
+    }
+    let redisLine = describeRedisStores(project, redis);
     // 3. What Discord must agree with before connecting.
     const apiUrl = options.env.CHAPTERJS_API_URL;
     const rest = new RestClient({
@@ -154,6 +171,8 @@ export async function dev(options) {
         log.success(`Connected to ${guild.name} as ${self.username}`);
         log.info(`Intents computed from your files: ${describeIntents(connectedIntents)}`);
         (project.isEmpty() ? log.info : log.success)(project.summary());
+        if (redisLine)
+            log.info(redisLine);
         project.ready(bot);
         // Tasks follow the bot through reconnections: they read the current one.
         project.startTasks(() => bot);
@@ -215,6 +234,13 @@ export async function dev(options) {
                 // offer it, or not.
                 if ((await writeTypes(cwd, project.typesInfo())) > 0)
                     log.reload('Types updated');
+                // A store moved to Redis, or out of it, is said once.
+                const kept = describeRedisStores(project, redis);
+                if (kept !== redisLine) {
+                    redisLine = kept;
+                    if (kept)
+                        log.info(kept);
+                }
                 const intents = project.intents(false);
                 if ((intents & ~connectedIntents) !== 0 && bot) {
                     // Intents are given when connecting: new ones need a new session.
@@ -256,6 +282,7 @@ export async function dev(options) {
         memory.stop();
         await bot?.close();
         await project.closeStores();
+        loose();
         if (code === 0)
             log.success('Disconnected');
         return code;
@@ -267,6 +294,7 @@ export async function dev(options) {
         memory.stop();
         await bot?.close();
         await project.closeStores();
+        loose();
         if (signal.aborted)
             return 0;
         explain(error, log);

package/dist/cli/env.d.ts

@@ -1,12 +1,17 @@
+import { type RedisAddress } from '../redis/url.js';
 export interface DevEnv {
     token: string;
     devGuildId: string;
+    /** Where the stores with `storage: 'redis'` go, when `REDIS_URL` is set. */
+    redis: RedisAddress | null;
 }
 /** What `chapterjs start` runs with. */
 export interface StartEnv {
     token: string;
     /** The dev server, when the project has one: production leaves it alone. */
     devGuildId: string | null;
+    /** Where the stores with `storage: 'redis'` go, when `REDIS_URL` is set. */
+    redis: RedisAddress | null;
 }
 /**
  * Reads what `chapterjs dev` needs from the `.env` file of the project (the

package/dist/cli/env.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseEnv } from 'node:util';
 import { isSnowflake } from '../discord/snowflake.js';
+import { parseRedisUrl } from '../redis/url.js';
 /**
  * Values people leave in a `.env` copied from an example. Whole values only:
  * a real token may start with any letters.
@@ -24,6 +25,27 @@ async function readEnv(projectDir, processEnv) {
         hasFile,
     };
 }
+/**
+ * `REDIS_URL` and `REDIS_PASSWORD`, when they are there: nothing is needed
+ * unless a store asks for Redis, which the files say once they loaded.
+ */
+function redisProblem(read, where) {
+    const url = read('REDIS_URL');
+    const password = read('REDIS_PASSWORD');
+    if (url === '') {
+        if (password !== '') {
+            return {
+                problem: `${where}: REDIS_PASSWORD is set, but REDIS_URL is not.\nAdd REDIS_URL, the address of your Redis (like redis://localhost:6379), or remove REDIS_PASSWORD.`,
+            };
+        }
+        return { redis: null };
+    }
+    const parsed = parseRedisUrl(url, password);
+    if ('problem' in parsed) {
+        return { problem: `${where}: REDIS_URL ${parsed.problem}` };
+    }
+    return { redis: parsed.address };
+}
 const TOKEN_HELP = 'Copy the token of your bot from https://discord.com/developers/applications → your application → Bot → Reset Token.';
 /** What is wrong with a token, if anything. */
 function tokenProblem(token, where) {
@@ -61,7 +83,12 @@ export async function readDevEnv(projectDir, processEnv) {
     else if (!isSnowflake(devGuildId)) {
         problems.push(`.env: DEV_GUILD_ID is "${devGuildId}", which is not a server ID (an ID only has digits).\nIn Discord, right-click your test server → Copy Server ID.`);
     }
-    return problems.length > 0 ? { problems } : { env: { token, devGuildId } };
+    const redis = redisProblem(read, '.env');
+    if ('problem' in redis)
+        problems.push(redis.problem);
+    return problems.length > 0 || 'problem' in redis
+        ? { problems }
+        : { env: { token, devGuildId, redis: redis.redis } };
 }
 /**
  * Reads what `chapterjs start` needs. In production the values often come
@@ -87,7 +114,16 @@ export async function readStartEnv(projectDir, processEnv) {
     if (devGuildId !== '' && !isSnowflake(devGuildId)) {
         problems.push(`DEV_GUILD_ID is "${devGuildId}", which is not a server ID (an ID only has digits).\nRemove it, or copy it again: in Discord, right-click your test server → Copy Server ID.`);
     }
-    return problems.length > 0
+    const redis = redisProblem(read, hasFile ? '.env' : 'Environment');
+    if ('problem' in redis)
+        problems.push(redis.problem);
+    return problems.length > 0 || 'problem' in redis
         ? { problems }
-        : { env: { token, devGuildId: devGuildId === '' ? null : devGuildId } };
+        : {
+            env: {
+                token,
+                devGuildId: devGuildId === '' ? null : devGuildId,
+                redis: redis.redis,
+            },
+        };
 }

package/dist/cli/project.d.ts

@@ -1,7 +1,8 @@
 import { type CommandEntry } from '../commands/tree.js';
 import { type ComponentEntry } from '../components/router.js';
 import { type LoadedStore } from '../store/declaration.js';
-import { type StoreBackend } from '../store/backend.js';
+import { type LoadedRanking } from '../ranking/declaration.js';
+import { type StoreBackend, type StoreStorage } from '../store/backend.js';
 import { type LoadedPresence } from '../presence/declaration.js';
 import { type DeclaredCommand, type DeclaredLanguage } from '../messages/declaration.js';
 import { type LoadedMessages } from '../messages/translate.js';
@@ -9,6 +10,8 @@ import type { Locale } from '../discord/types/common.js';
 import { type TaskEntry } from '../tasks/scheduler.js';
 import { type Bot, type BotOptions } from '../core/bot.js';
 import { type GatewayIntentName } from '../discord/intents.js';
+import type { GatewayDispatchEventName } from '../discord/types/gateway-events.js';
+import type { RawInteraction } from '../discord/types/interaction.js';
 import { type LoadedEvent } from '../events/router.js';
 import { type BuiltFile, type Declaration, type FailedFile } from '../loader/loader.js';
 import type { Log } from './log.js';
@@ -29,13 +32,27 @@ export interface ProjectOptions {
      */
     joinsVoice?: boolean;
     /**
-     * Where the stores of the project keep their data. A file per store in
-     * the `data/` folder of the project by default; the first process of a
-     * cluster, through IPC, for the other processes.
+     * Where the stores of the project keep their data, by storage. `file`: a
+     * file per store in the `data/` folder of the project by default, the
+     * first process of a cluster through IPC for the other processes.
+     * `redis`: what the CLI made of `REDIS_URL`; without one, a store that
+     * asks for Redis is reported and left out.
      */
-    stores?: StoreBackend;
+    stores?: Partial<Record<StoreStorage, StoreBackend>>;
     /** Only tests change this. */
     deferAfter?: number;
+    /**
+     * Told what the bot is doing with the files, and when it is done with
+     * it: what `chapterjs test` waits for. Nothing of the bot waits.
+     */
+    observe?: ProjectObserver;
+}
+/** What `chapterjs test` watches of a running project. */
+export interface ProjectObserver {
+    /** An interaction was given to the files; `done` once they answered it. */
+    interaction?(raw: RawInteraction, done: Promise<void>): void;
+    /** A gateway event was given to the files; `done` once they handled it. */
+    event?(event: GatewayDispatchEventName, data: unknown, done: Promise<void>): void;
 }
 /** What the types of a project are written from, once its files ran. */
 export interface TypesInfo {
@@ -63,6 +80,12 @@ export interface TypesInfo {
 export declare function writeTypes(cwd: string, info?: TypesInfo): Promise<number>;
 /** The kinds of declarations a project is made of: one per feature. */
 export declare const DECLARATIONS: readonly Declaration<unknown>[];
+/** A ranking, with where it is declared. */
+export interface RankingEntry {
+    file: string;
+    export: string;
+    ranking: LoadedRanking;
+}
 /** A store, with where it is declared. */
 export interface StoreEntry {
     file: string;
@@ -97,8 +120,14 @@ export interface Project {
     readonly components: ReadonlyMap<string, ComponentEntry>;
     readonly tasks: ReadonlyMap<string, TaskEntry>;
     readonly stores: ReadonlyMap<string, StoreEntry>;
-    /** Where the stores keep their data: what a cluster serves to its other processes. */
-    readonly storeBackend: StoreBackend;
+    readonly rankings: ReadonlyMap<string, RankingEntry>;
+    /** Where the stores keep their data, by storage: what a cluster serves to its other processes. */
+    readonly storeBackends: ReadonlyMap<StoreStorage, StoreBackend>;
+    /** What is kept in Redis: the names of the stores and of the rankings, sorted. */
+    redisStores(): {
+        stores: string[];
+        rankings: string[];
+    };
     /** The presence declared, or `null` without one. */
     readonly presence: LoadedPresence | null;
     /** The languages of the project, assembled, or `null` without any. */
@@ -140,6 +169,11 @@ export interface Project {
     startTasks(current: () => Bot | null): void;
     /** Stops the tasks: nothing runs after this. */
     stopTasks(): void;
+    /**
+     * Runs one task now, as the scheduler would when its time comes, with
+     * the bot given. Resolves once it is done; an error is reported.
+     */
+    runTask(entry: TaskEntry, bot: Bot, now?: Date): Promise<void>;
     /** Looks after the memory of the bot `current` returns. */
     watchMemory(current: () => Bot | null): {
         stop(): void;
@@ -147,6 +181,14 @@ export interface Project {
     /** Writes what the stores still have to write. Nothing is kept after this. */
     closeStores(): Promise<void>;
 }
+/**
+ * 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 declare function reportLooseRejections(cwd: string, log: Log): () => void;
 /** Whether the folder is a project: it has a `src` folder. */
 export declare function hasSources(cwd: string, log: Log): Promise<boolean>;
 export declare function createProject(options: ProjectOptions): Project;