chapterjs 0.1.2 → 0.1.4

package/dist/tasks/schedule.js

@@ -0,0 +1,236 @@
+// When a task runs: a plain duration (`'10m'`) or a cron expression, with
+// a timezone. Written once, with no dependency: the next occurrence of a
+// cron is found by reading the clock of the timezone through `Intl`.
+import { DURATION_EXAMPLE, parseDuration } from '../util/duration.js';
+const fail = (message) => {
+    throw new TypeError(message);
+};
+/** The shortest `every` accepted, in milliseconds. */
+export const MIN_EVERY = 1000;
+/**
+ * Parses a duration: a number and a unit, `s`, `m`, `h` or `d`, like
+ * `'30s'`, `'10m'`, `'2h'`, `'1d'`. Several parts add up: `'1h30m'`.
+ */
+export function parseEvery(text) {
+    const example = `every: '10m' (${DURATION_EXAMPLE})`;
+    if (typeof text !== 'string' || text.trim() === '') {
+        return fail(`"every" says how often the task runs: ${example}.`);
+    }
+    const ms = parseDuration(text);
+    if (ms === null) {
+        return fail(`"every" is ${JSON.stringify(text)}, which is not a duration: ${example}.`);
+    }
+    if (ms < MIN_EVERY) {
+        fail(`"every" is ${JSON.stringify(text)}: a task runs at most once per second.`);
+    }
+    return { kind: 'every', text, ms };
+}
+const NAMES = {
+    months: {
+        jan: 1,
+        feb: 2,
+        mar: 3,
+        apr: 4,
+        may: 5,
+        jun: 6,
+        jul: 7,
+        aug: 8,
+        sep: 9,
+        oct: 10,
+        nov: 11,
+        dec: 12,
+    },
+    weekdays: { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 },
+};
+/** The values one field of a cron matches. */
+function parseField(text, field, low, high, expression) {
+    const values = new Set();
+    const names = NAMES[field] ?? {};
+    const read = (part) => {
+        const named = names[part.toLowerCase()];
+        if (named !== undefined)
+            return named;
+        if (!/^\d+$/.test(part)) {
+            return fail(`In cron ${JSON.stringify(expression)}, ${JSON.stringify(part)} is not a value for ${field}: use numbers from ${low} to ${high}${Object.keys(names).length ? `, or ${Object.keys(names).join(', ')}` : ''}.`);
+        }
+        const value = Number(part);
+        if (value < low || value > high) {
+            fail(`In cron ${JSON.stringify(expression)}, ${part} is out of range for ${field}: ${low} to ${high}.`);
+        }
+        return value;
+    };
+    for (const item of text.split(',')) {
+        const [range = '', stepText] = item.split('/');
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (stepText !== undefined && (!/^\d+$/.test(stepText) || step < 1)) {
+            fail(`In cron ${JSON.stringify(expression)}, "/${stepText}" is not a step: write a number, like */15.`);
+        }
+        let from;
+        let to;
+        if (range === '*') {
+            from = low;
+            to = high;
+        }
+        else if (range.includes('-')) {
+            const [a = '', b = ''] = range.split('-');
+            from = read(a);
+            to = read(b);
+            if (from > to) {
+                fail(`In cron ${JSON.stringify(expression)}, the range ${range} goes backwards.`);
+            }
+        }
+        else {
+            from = read(range);
+            to = stepText === undefined ? from : high;
+        }
+        for (let value = from; value <= to; value += step)
+            values.add(value);
+    }
+    // Sunday is 0 and 7.
+    if (field === 'weekdays' && values.has(7)) {
+        values.delete(7);
+        values.add(0);
+    }
+    return values;
+}
+/** Whether a timezone exists, as `Intl` knows them. */
+export function isTimezone(name) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: name });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The timezone of the machine. */
+export const localTimezone = () => Intl.DateTimeFormat().resolvedOptions().timeZone;
+/**
+ * Parses a cron expression: five fields, minute, hour, day of month,
+ * month and day of week, with `*`, lists, ranges, steps and names.
+ * @see https://en.wikipedia.org/wiki/Cron#Cron_expression
+ */
+export function parseCron(text, timezone) {
+    const example = `cron: '0 9 * * 1-5' (minute, hour, day of month, month, day of week)`;
+    if (typeof text !== 'string' || text.trim() === '') {
+        return fail(`"cron" says when the task runs: ${example}.`);
+    }
+    const fields = text.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        return fail(`"cron" is ${JSON.stringify(text)}, which has ${fields.length} fields: a cron has 5, ${example}.`);
+    }
+    if (timezone !== undefined &&
+        (typeof timezone !== 'string' || !isTimezone(timezone))) {
+        fail(`"timezone" is ${JSON.stringify(timezone) ?? typeof timezone}, which is not a timezone. Write one like 'Europe/Paris' or 'America/New_York'; without it, the task follows the clock of the machine (${localTimezone()}).`);
+    }
+    const [minute, hour, day, month, weekday] = fields;
+    const schedule = {
+        kind: 'cron',
+        text: text.trim(),
+        timezone: timezone ?? localTimezone(),
+        minutes: parseField(minute, 'minutes', 0, 59, text),
+        hours: parseField(hour, 'hours', 0, 23, text),
+        days: parseField(day, 'days', 1, 31, text),
+        months: parseField(month, 'months', 1, 12, text),
+        weekdays: parseField(weekday, 'weekdays', 0, 7, text),
+        anyDay: day === '*',
+        anyWeekday: weekday === '*',
+    };
+    if (!nextCron(schedule, new Date())) {
+        fail(`"cron" is ${JSON.stringify(text)}, which never happens: no day of the next 5 years matches it.`);
+    }
+    return schedule;
+}
+const formatters = new Map();
+const WEEKDAYS = NAMES.weekdays;
+/** What the clock of a timezone shows at a moment. */
+function clockOf(date, timezone) {
+    let formatter = formatters.get(timezone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone,
+            hourCycle: 'h23',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            weekday: 'short',
+        });
+        formatters.set(timezone, formatter);
+    }
+    const clock = { minute: 0, hour: 0, day: 0, month: 0, weekday: 0 };
+    for (const part of formatter.formatToParts(date)) {
+        if (part.type === 'weekday')
+            clock.weekday = WEEKDAYS[part.value.toLowerCase()];
+        else if (part.type in clock)
+            clock[part.type] = Number(part.value);
+    }
+    return clock;
+}
+const MINUTE = 60_000;
+const HOUR = 3_600_000;
+const FIVE_YEARS = 5 * 366 * 86_400_000;
+/**
+ * The next moment a cron matches, strictly after `from`; `null` when none
+ * comes in the next five years. Walks the clock of the timezone: minute
+ * by minute within a matching hour, hour by hour otherwise, so a change
+ * of daylight saving time is read, not computed.
+ */
+export function nextCron(schedule, from) {
+    // Day of month and day of week: either when both are given (as cron does).
+    const dayMatches = (clock) => {
+        const byDay = schedule.days.has(clock.day);
+        const byWeekday = schedule.weekdays.has(clock.weekday);
+        if (schedule.anyDay && schedule.anyWeekday)
+            return true;
+        if (schedule.anyDay)
+            return byWeekday;
+        if (schedule.anyWeekday)
+            return byDay;
+        return byDay || byWeekday;
+    };
+    // When clocks go back, a time of the day comes twice: a task that ran
+    // at the first one does not run again at the second.
+    const last = clockOf(from, schedule.timezone);
+    const sameTime = (clock) => clock.month === last.month &&
+        clock.day === last.day &&
+        clock.hour === last.hour &&
+        clock.minute === last.minute;
+    let at = Math.floor(from.getTime() / MINUTE) * MINUTE + MINUTE;
+    const limit = from.getTime() + FIVE_YEARS;
+    while (at <= limit) {
+        const clock = clockOf(new Date(at), schedule.timezone);
+        if (!schedule.months.has(clock.month) || !dayMatches(clock)) {
+            // Not today: to the next hour, then look again.
+            at += HOUR - clock.minute * MINUTE;
+        }
+        else if (!schedule.hours.has(clock.hour)) {
+            at += HOUR - clock.minute * MINUTE;
+        }
+        else if (!schedule.minutes.has(clock.minute) || sameTime(clock)) {
+            at += MINUTE;
+        }
+        else {
+            return new Date(at);
+        }
+    }
+    return null;
+}
+/** The next time a schedule is due, strictly after `from`. */
+export function nextRun(schedule, from) {
+    if (schedule.kind === 'every')
+        return new Date(from.getTime() + schedule.ms);
+    const next = nextCron(schedule, from);
+    if (!next) {
+        throw new Error(`The cron ${JSON.stringify(schedule.text)} never happens again.`);
+    }
+    return next;
+}
+/** What tells one schedule from another: the same key is the same timing. */
+export const scheduleKey = (schedule) => schedule.kind === 'every'
+    ? `every ${schedule.ms}`
+    : `cron ${schedule.text} ${schedule.timezone}`;
+/** The schedule in words, for the developer. */
+export const describeSchedule = (schedule) => schedule.kind === 'every'
+    ? `every ${schedule.text}`
+    : `at "${schedule.text}" (${schedule.timezone})`;

package/dist/tasks/scheduler.d.ts

@@ -0,0 +1,33 @@
+import type { TaskContext } from './task.js';
+import type { LoadedTask } from './convention.js';
+/** A task, with the file it comes from (to report its errors). */
+export interface TaskEntry {
+    file: string;
+    task: LoadedTask;
+}
+/** What runs the tasks. */
+export interface Scheduler {
+    /**
+     * Replaces the tasks (after a load or a reload). A task whose timing did
+     * not change keeps its next time; a new one is counted from now.
+     */
+    set(entries: Iterable<TaskEntry>): void;
+    /** Starts running the tasks that are due, with what `context` gives. */
+    start(context: () => Omit<TaskContext, 'now'> | null): void;
+    /** Stops everything; nothing runs after this. */
+    stop(): void;
+}
+export interface SchedulerOptions {
+    /** A `run` threw: reported with the file it comes from. */
+    onError: (file: string, error: unknown) => void;
+    /** Something the developer should know, that is not an error of theirs. */
+    onWarning: (file: string, message: string) => void;
+}
+/** Tasks run by the timers of this process. */
+export declare class TimerScheduler implements Scheduler {
+    #private;
+    constructor(options: SchedulerOptions);
+    set(entries: Iterable<TaskEntry>): void;
+    start(context: () => Omit<TaskContext, 'now'> | null): void;
+    stop(): void;
+}

package/dist/tasks/scheduler.js

@@ -0,0 +1,107 @@
+// Runs the tasks of the project when they are due. Behind an interface:
+// this one keeps timers in the process; a bot on several machines would
+// share one through another implementation, with no change to the files.
+import { describeSchedule, nextRun, scheduleKey } from './schedule.js';
+/** The longest a timer of Node can wait. */
+const MAX_DELAY = 2 ** 31 - 1;
+/** Tasks run by the timers of this process. */
+export class TimerScheduler {
+    #options;
+    #tasks = new Map();
+    #context = null;
+    constructor(options) {
+        this.#options = options;
+    }
+    set(entries) {
+        const kept = new Map();
+        const started = [];
+        for (const entry of entries) {
+            const key = scheduleKey(entry.task.schedule);
+            const previous = this.#tasks.get(entry.file);
+            if (previous && previous.key === key) {
+                // Same timing: the next time stays, only the code changes.
+                previous.entry = entry;
+                kept.set(entry.file, previous);
+                this.#tasks.delete(entry.file);
+                continue;
+            }
+            const scheduled = {
+                entry,
+                key,
+                next: nextRun(entry.task.schedule, new Date()),
+                timer: null,
+                running: false,
+            };
+            kept.set(entry.file, scheduled);
+            started.push(scheduled);
+        }
+        // What is left was removed, or changed timing: it starts over.
+        for (const old of this.#tasks.values()) {
+            if (old.timer)
+                clearTimeout(old.timer);
+        }
+        this.#tasks = kept;
+        if (this.#context) {
+            for (const scheduled of started) {
+                this.#arm(scheduled);
+                if (scheduled.entry.task.onStart)
+                    this.#run(scheduled, new Date());
+            }
+        }
+    }
+    start(context) {
+        if (this.#context)
+            return;
+        this.#context = context;
+        const now = new Date();
+        for (const scheduled of this.#tasks.values()) {
+            scheduled.next = nextRun(scheduled.entry.task.schedule, now);
+            this.#arm(scheduled);
+            if (scheduled.entry.task.onStart)
+                this.#run(scheduled, now);
+        }
+    }
+    stop() {
+        this.#context = null;
+        for (const scheduled of this.#tasks.values()) {
+            if (scheduled.timer)
+                clearTimeout(scheduled.timer);
+            scheduled.timer = null;
+        }
+    }
+    /** Waits for the next time of a task, in steps a timer can hold. */
+    #arm(scheduled) {
+        if (scheduled.timer)
+            clearTimeout(scheduled.timer);
+        const delay = scheduled.next.getTime() - Date.now();
+        scheduled.timer = setTimeout(() => {
+            if (!this.#context)
+                return;
+            if (Date.now() < scheduled.next.getTime())
+                return this.#arm(scheduled);
+            const due = scheduled.next;
+            scheduled.next = nextRun(scheduled.entry.task.schedule, due);
+            this.#arm(scheduled);
+            this.#run(scheduled, due);
+        }, Math.min(Math.max(delay, 0), MAX_DELAY));
+    }
+    /** Runs a task once, unless it is still running from the last time. */
+    #run(scheduled, now) {
+        const { file, task } = scheduled.entry;
+        if (scheduled.running) {
+            this.#options.onWarning(file, `${task.name} was still running when its next time came (${describeSchedule(task.schedule)}): that run was skipped.`);
+            return;
+        }
+        const context = this.#context?.();
+        if (!context) {
+            this.#options.onWarning(file, `${task.name} was due while the bot was not connected: that run was skipped.`);
+            return;
+        }
+        scheduled.running = true;
+        new Promise(resolve => resolve(scheduled.entry.task.run(Object.freeze({ ...context, now }))))
+            .catch((error) => this.#options.onError(file, error))
+            .finally(() => {
+            scheduled.running = false;
+        });
+    }
+}

package/dist/tasks/task.d.ts

@@ -0,0 +1,76 @@
+import type { Snowflake } from '../discord/types/common.js';
+import type { Guild } from '../structures/guild.js';
+import type { User } from '../structures/user.js';
+import type { TranslationContext } from '../messages/messages.js';
+/** What `run` receives: the bot, as the `ready` event gives it, and the time. */
+export interface TaskContext {
+    /** The bot itself. */
+    user: User;
+    /** The servers the bot is in. */
+    guilds: ReadonlyMap<Snowflake, Guild>;
+    /** When this run was due. */
+    now: Date;
+}
+interface TaskConfigBase {
+    /**
+     * Also run once as soon as the bot is connected, without waiting for the
+     * first time of the schedule.
+     */
+    onStart?: boolean;
+    /** What the task does. */
+    run: (context: TaskContext & TranslationContext) => unknown;
+}
+/** A task that runs every so often. */
+export interface EveryTaskConfig extends TaskConfigBase {
+    /**
+     * How often the task runs: a number and a unit, `s`, `m`, `h` or `d`,
+     * like `'30s'`, `'10m'`, `'2h'`, `'1d'` or `'1h30m'`. Once per second at
+     * most. Counted from when the bot connects.
+     */
+    every: string;
+    cron?: never;
+    timezone?: never;
+}
+/** A task that runs at given times. */
+export interface CronTaskConfig extends TaskConfigBase {
+    /**
+     * When the task runs, as a cron expression: minute, hour, day of month,
+     * month and day of week, like `'0 9 * * 1-5'` (9:00 on weekdays). `*`,
+     * lists (`1,15`), ranges (`1-5`), steps (`*​/15`) and names (`mon`,
+     * `jan`) work.
+     */
+    cron: string;
+    /**
+     * The timezone the cron follows, like `'Europe/Paris'`. The clock of
+     * the machine by default.
+     */
+    timezone?: string;
+    every?: never;
+}
+/** What a task file gives to `task()`: when it runs, and what it does. */
+export type TaskConfig = EveryTaskConfig | CronTaskConfig;
+/** What `task()` returns: the default export of a task file. */
+export interface TaskFile {
+    /** What the file gave to `task()`, not checked yet. */
+    readonly config: unknown;
+}
+/**
+ * Declares a task: something the bot does by itself. Export the result as
+ * the default export of a file of `src/tasks/`: the name of the file is
+ * the name of the task.
+ *
+ * ```ts
+ * import { task } from 'chapterjs';
+ *
+ * export default task({
+ *   every: '10m',
+ *   async run({ guilds }) {
+ *     console.log(`Watching ${guilds.size} servers`);
+ *   },
+ * });
+ * ```
+ */
+export declare function task(config: TaskConfig): TaskFile;
+/** Whether a value was made by `task()`. */
+export declare function isTaskFile(value: unknown): value is TaskFile;
+export {};

package/dist/tasks/task.js

@@ -0,0 +1,28 @@
+// `task()`, as the files of `src/tasks/` import it from 'chapterjs': what
+// the bot does by itself, at intervals or at given times.
+const BRAND = Symbol.for('chapterjs.task');
+/**
+ * Declares a task: something the bot does by itself. Export the result as
+ * the default export of a file of `src/tasks/`: the name of the file is
+ * the name of the task.
+ *
+ * ```ts
+ * import { task } from 'chapterjs';
+ *
+ * export default task({
+ *   every: '10m',
+ *   async run({ guilds }) {
+ *     console.log(`Watching ${guilds.size} servers`);
+ *   },
+ * });
+ * ```
+ */
+export function task(config) {
+    return Object.freeze({ [BRAND]: true, config });
+}
+/** Whether a value was made by `task()`. */
+export function isTaskFile(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[BRAND] === true);
+}

package/dist/util/case.d.ts

@@ -0,0 +1,13 @@
+type CamelKey<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Head}${Capitalize<CamelKey<Tail>>}` : S;
+/** A Discord payload type with every field name turned into camelCase. */
+export type Camelize<T> = T extends readonly (infer Item)[] ? Camelize<Item>[] : T extends object ? {
+    [K in keyof T as K extends string ? CamelKey<K> : K]: Camelize<T[K]>;
+} : T;
+/**
+ * What users write → what Discord expects. Dates become ISO8601 text,
+ * `undefined` fields are dropped.
+ */
+export declare function toSnakeCase<T>(value: Camelize<T>): T;
+/** What Discord sends → what users read. */
+export declare function toCamelCase<T>(value: T): Camelize<T>;
+export {};

package/dist/util/case.js

@@ -0,0 +1,54 @@
+// Discord names fields in snake_case, JavaScript in camelCase. Users only
+// ever write and read camelCase: these two conversions are the single place
+// where names are translated, for every feature.
+// Only real field names are converted: ids (`"123"`) and locales (`"en-US"`),
+// used as keys of some objects, must stay as they are.
+const CAMEL = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)+$/;
+const SNAKE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function convert(value, rename) {
+    if (Array.isArray(value))
+        return value.map(item => convert(item, rename));
+    if (!isPlainObject(value)) {
+        // Something that knows how to become JSON (a set of permissions...).
+        if (typeof value === 'object' &&
+            value !== null &&
+            'toJSON' in value &&
+            typeof value.toJSON === 'function' &&
+            !(value instanceof Date)) {
+            return value.toJSON();
+        }
+        if (value instanceof Date)
+            return value.toISOString();
+        return value;
+    }
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (item === undefined)
+            continue;
+        result[rename(key)] = convert(item, rename);
+    }
+    return result;
+}
+const toSnakeKey = (key) => CAMEL.test(key)
+    ? key.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`)
+    : key;
+const toCamelKey = (key) => SNAKE.test(key)
+    ? key.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase())
+    : key;
+/**
+ * What users write → what Discord expects. Dates become ISO8601 text,
+ * `undefined` fields are dropped.
+ */
+export function toSnakeCase(value) {
+    return convert(value, toSnakeKey);
+}
+/** What Discord sends → what users read. */
+export function toCamelCase(value) {
+    return convert(value, toCamelKey);
+}

package/dist/util/duration.d.ts

@@ -0,0 +1,8 @@
+/** How a duration is written, for a message that says what to write. */
+export declare const DURATION_EXAMPLE = "a number and a unit: s, m, h or d, like '30s', '2h', '1d' or '1h30m'";
+/**
+ * The milliseconds of a duration: a number and a unit, `s`, `m`, `h` or
+ * `d`. Several parts add up (`'1h30m'`), spaces and case do not matter.
+ * `null` when the text is not a duration.
+ */
+export declare function parseDuration(text: string): number | null;

package/dist/util/duration.js

@@ -0,0 +1,29 @@
+// A duration written by a user: `'30s'`, `'10m'`, `'1h30m'`. Read once here
+// for every feature that takes one (the `every` of a task, the `cooldown`
+// of a command); each feature gives its own message when it is not one.
+/** How a duration is written, for a message that says what to write. */
+export const DURATION_EXAMPLE = "a number and a unit: s, m, h or d, like '30s', '2h', '1d' or '1h30m'";
+const UNITS = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+/**
+ * The milliseconds of a duration: a number and a unit, `s`, `m`, `h` or
+ * `d`. Several parts add up (`'1h30m'`), spaces and case do not matter.
+ * `null` when the text is not a duration.
+ */
+export function parseDuration(text) {
+    const compact = text.replace(/\s+/g, '');
+    const parts = [...compact.matchAll(/(\d+(?:\.\d+)?)([smhd])/gi)];
+    const whole = parts.map(part => part[0]).join('');
+    if (parts.length === 0 || whole.toLowerCase() !== compact.toLowerCase()) {
+        return null;
+    }
+    let ms = 0;
+    for (const [, amount, unit] of parts) {
+        ms += Number(amount) * UNITS[unit.toLowerCase()];
+    }
+    return Math.round(ms);
+}

package/dist/util/websocket.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Calls `onEnd` once when a WebSocket ends, with its close code.
+ *
+ * A socket that could not connect fires `error`, then `close` with 1006.
+ * Node 22 fired only `error` and left the socket connecting forever: a
+ * `close` that has not come by the next turn of the event loop is taken as
+ * that 1006, so how a socket ends never depends on the version of Node.
+ */
+export declare function onSocketEnd(ws: WebSocket, onEnd: (code: number) => void): void;

package/dist/util/websocket.js

@@ -0,0 +1,31 @@
+/**
+ * Calls `onEnd` once when a WebSocket ends, with its close code.
+ *
+ * A socket that could not connect fires `error`, then `close` with 1006.
+ * Node 22 fired only `error` and left the socket connecting forever: a
+ * `close` that has not come by the next turn of the event loop is taken as
+ * that 1006, so how a socket ends never depends on the version of Node.
+ */
+export function onSocketEnd(ws, onEnd) {
+    let ended = false;
+    const end = (code) => {
+        if (ended)
+            return;
+        ended = true;
+        onEnd(code);
+    };
+    ws.addEventListener('close', event => end(event.code));
+    ws.addEventListener('error', () => {
+        setImmediate(() => {
+            if (ended)
+                return;
+            end(1006);
+            try {
+                ws.close();
+            }
+            catch {
+                // Already closed or never opened: nothing to release.
+            }
+        });
+    });
+}