chapterjs 0.2.3 → 0.4.0

package/dist/interactions/dispatch.js

@@ -75,6 +75,10 @@ export function refuse(interaction, key, params) {
  * seconds: when `run` takes longer, the framework says the answer is
  * coming. When `run` throws, the person gets a plain answer and the
  * developer the error with its file and line.
+ *
+ * Resolves once everything is done (the function, and the answer sent for
+ * it when it failed): nothing of the bot waits for it, `chapterjs test`
+ * does.
  */
 export function runInteraction(options) {
     const { interaction, file, name, reporter } = options;
@@ -82,7 +86,7 @@ export function runInteraction(options) {
     sleep(reporter.deferAfter ?? 2000, undefined, { signal: stop.signal })
         .then(() => options.defer())
         .catch(() => { });
-    new Promise(resolve => resolve(withGuild(options.guildId, options.run)))
+    return new Promise(resolve => resolve(withGuild(options.guildId, options.run)))
         .then(() => {
         if (!interaction.answered) {
             reporter.onWarning(file, `${name} ${options.unanswered}`);
@@ -105,7 +109,7 @@ export function runInteraction(options) {
                 : interaction.answered
                     ? interaction.followUp({ content, ephemeral: true })
                     : interaction.reply({ content, ephemeral: true });
-        tell.catch(() => { });
+        return tell.then(() => { }, () => { });
     })
         .finally(() => stop.abort());
 }

package/dist/loader/hot.js

@@ -45,8 +45,15 @@ export function enableProjectLoader(dir, { reload }) {
                 result = nextResolve(specifier, context);
             }
             catch (error) {
-                if (!fromProject || EXTENSION.test(specifier))
+                // Not found, or a folder (Node refuses those as they are).
+                const code = error.code;
+                if (!fromProject ||
+                    (code !== 'ERR_MODULE_NOT_FOUND' &&
+                        code !== 'ERR_UNSUPPORTED_DIR_IMPORT')) {
                     throw error;
+                }
+                if (EXTENSION.test(specifier))
+                    throw missing(specifier, false);
                 // No extension: look for the file people mean.
                 for (const candidate of CANDIDATES) {
                     try {
@@ -58,7 +65,7 @@ export function enableProjectLoader(dir, { reload }) {
                     }
                 }
                 if (!result)
-                    throw error;
+                    throw missing(specifier, true);
             }
             if (hot && root !== null && result.url.startsWith(root)) {
                 return {
@@ -70,6 +77,19 @@ export function enableProjectLoader(dir, { reload }) {
         },
     });
 }
+/**
+ * The error for an import of the project that names no file: said in the
+ * words of the import, not with the absolute paths Node gives.
+ */
+function missing(specifier, tried) {
+    const name = specifier.replace(/\/$/, '').split('/').pop() ?? specifier;
+    const looked = tried
+        ? ` No ${name}.ts, ${name}.js or ${name}/index.ts is there.`
+        : '';
+    const error = new Error(`'${specifier}' does not exist.${looked} Check the path and the name of the file.`);
+    error.code = 'ERR_MODULE_NOT_FOUND';
+    return error;
+}
 /** Makes the next imports load the files again. */
 export function nextGeneration() {
     generation++;

package/dist/loader/loader.d.ts

@@ -59,6 +59,11 @@ export interface FoundFile {
 }
 /** Every source file of `src/`, in a stable order. */
 export declare function listSources(projectDir: string): Promise<FoundFile[]>;
+/**
+ * Every test file of `src/` (`*.test.ts`, `*.spec.ts`), in a stable order:
+ * what `chapterjs test` runs, and what the bot never loads.
+ */
+export declare function listTests(projectDir: string): Promise<FoundFile[]>;
 /** A file of the project, run: what it exports. */
 export interface LoadedModule {
     /** The path from the project folder: `src/ping.ts`. */
@@ -72,6 +77,8 @@ export interface LoadedSources {
 }
 /** Runs every file of `src/`. A file that fails to run never throws. */
 export declare function loadSources(projectDir: string): Promise<LoadedSources>;
+/** Runs the files given. A file that fails to run never throws. */
+export declare function loadFiles(files: readonly FoundFile[]): Promise<LoadedSources>;
 /**
  * Reads the declarations of one kind from what the files export. Every
  * export is looked at; the ones the kind recognises are read, the others

package/dist/loader/loader.js

@@ -16,7 +16,7 @@ const DECLARATION = /\.d\.m?ts$/;
 /** Tests next to the code: they are for a test runner, not for the bot. */
 const TEST = /\.(?:test|spec)\.[^.]+$/;
 /** The source files of a folder and its subfolders, in a stable order. */
-async function scan(dir) {
+async function scan(dir, tests = false) {
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true });
@@ -30,10 +30,10 @@ async function scan(dir) {
     for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
         const path = join(dir, entry.name);
         if (entry.isDirectory())
-            files.push(...(await scan(path)));
+            files.push(...(await scan(path, tests)));
         else if (SOURCE.test(entry.name) &&
             !DECLARATION.test(entry.name) &&
-            !TEST.test(entry.name)) {
+            TEST.test(entry.name) === tests) {
             files.push(path);
         }
     }
@@ -41,19 +41,29 @@ async function scan(dir) {
 }
 /** Every source file of `src/`, in a stable order. */
 export async function listSources(projectDir) {
-    const paths = await scan(join(projectDir, 'src'));
-    return paths
-        .map(path => ({
-        file: relative(projectDir, path).split(sep).join('/'),
-        path,
-    }))
-        .sort((a, b) => (a.file < b.file ? -1 : 1));
+    return found(projectDir, await scan(join(projectDir, 'src')));
 }
+/**
+ * Every test file of `src/` (`*.test.ts`, `*.spec.ts`), in a stable order:
+ * what `chapterjs test` runs, and what the bot never loads.
+ */
+export async function listTests(projectDir) {
+    return found(projectDir, await scan(join(projectDir, 'src'), true));
+}
+const found = (projectDir, paths) => paths
+    .map(path => ({
+    file: relative(projectDir, path).split(sep).join('/'),
+    path,
+}))
+    .sort((a, b) => (a.file < b.file ? -1 : 1));
 /** Runs every file of `src/`. A file that fails to run never throws. */
 export async function loadSources(projectDir) {
-    const found = await listSources(projectDir);
+    return loadFiles(await listSources(projectDir));
+}
+/** Runs the files given. A file that fails to run never throws. */
+export async function loadFiles(files) {
     const result = { modules: [], failed: [] };
-    await Promise.all(found.map(async ({ file, path }) => {
+    await Promise.all(files.map(async ({ file, path }) => {
         try {
             result.modules.push({ file, exports: await importFile(path) });
         }

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