chapterjs 0.1.2 → 0.2.0

package/dist/assets/asset.d.ts

@@ -0,0 +1,46 @@
+/** What can change about a file of `public/` when it is sent. */
+export interface AssetOptions {
+    /** The name the file is sent under; by default its own name. */
+    name?: string;
+    /** What the file shows, for people who can't see it. */
+    description?: string;
+    /** Hides the file until it is clicked. */
+    spoiler?: boolean;
+    /** The media type of the file (`image/png`); guessed from the name when missing. */
+    contentType?: string;
+}
+declare const brand: unique symbol;
+/**
+ * A file of the `public/` folder of the project, made by `asset()`, to put
+ * in the `files` of a message. It is read when the message is sent.
+ */
+export interface AssetFile {
+    readonly [brand]: 'asset';
+    /** The name the file is sent under, with its extension. */
+    readonly name: string;
+    /** The path of the file inside `public/`. */
+    readonly path: string;
+    /** What the file shows, for people who can't see it. */
+    readonly description?: string;
+    /** Hides the file until it is clicked. */
+    readonly spoiler?: boolean;
+    /** The media type of the file; guessed from the name when missing. */
+    readonly contentType?: string;
+}
+/** Tells `asset()` where the project is. Only the CLI calls it. */
+export declare function setPublicDir(projectDir: string): void;
+/** Whether a value was made by `asset()`. */
+export declare function isAssetFile(value: unknown): value is AssetFile;
+/**
+ * A file of the `public/` folder of the project, to send with a message:
+ * `files: [asset('photos/monday.png')]`. The file is read when the message
+ * is sent, so a missing file is an error there.
+ */
+export declare function asset(path: string, options?: AssetOptions): AssetFile;
+/** Where the file of an asset is on disk, checked to be inside `public/`. */
+export declare function assetPath(file: AssetFile): string;
+/** The error to give for an asset whose file could not be opened. */
+export declare function missingAsset(file: AssetFile, error: unknown): unknown;
+/** Reads the file of an asset, when the message is sent. */
+export declare function readAsset(file: AssetFile): Promise<Uint8Array>;
+export {};

package/dist/assets/asset.js

@@ -0,0 +1,86 @@
+// `asset()`, as user files import it from 'chapterjs': a file of the
+// `public/` folder of the project, to send with a message. Its type is
+// written per project (see `public.ts`), so the editor lists the files.
+import { readFile } from 'node:fs/promises';
+import { basename, join, normalize, sep } from 'node:path';
+import { PUBLIC_FOLDER } from './public.js';
+const ASSET = Symbol.for('chapterjs.asset');
+/** Where `public/` is: told by the CLI, which knows the project. */
+let publicDir = null;
+/** Tells `asset()` where the project is. Only the CLI calls it. */
+export function setPublicDir(projectDir) {
+    publicDir = join(projectDir, PUBLIC_FOLDER);
+}
+/** Whether a value was made by `asset()`. */
+export function isAssetFile(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[ASSET] === true);
+}
+/**
+ * A file of the `public/` folder of the project, to send with a message:
+ * `files: [asset('photos/monday.png')]`. The file is read when the message
+ * is sent, so a missing file is an error there.
+ */
+export function asset(path, options = {}) {
+    if (typeof path !== 'string' || path.trim() === '') {
+        throw new TypeError(`asset() takes the path of a file inside ${PUBLIC_FOLDER}/, like asset('photos/monday.png').`);
+    }
+    const clean = path.replace(/\\/g, '/').replace(/^\/+/, '');
+    if (clean.split('/').some(part => part === '..' || part === '')) {
+        throw new TypeError(`asset() only reads inside ${PUBLIC_FOLDER}/: ${JSON.stringify(path)} leaves it.`);
+    }
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError(`The options of asset() are an object like { description: '...' }.`);
+    }
+    for (const key of Object.keys(options)) {
+        if (!['name', 'description', 'spoiler', 'contentType'].includes(key)) {
+            throw new TypeError(`"${key}" is not an option of asset(). Options are: name, description, spoiler, contentType.`);
+        }
+    }
+    const name = options.name ?? basename(clean);
+    if (typeof name !== 'string' || name.trim() === '' || name.includes('/')) {
+        throw new TypeError(`The name of an asset is a file name with its extension, like "chart.png", got ${JSON.stringify(options.name)}.`);
+    }
+    const file = {
+        name,
+        path: clean,
+        ...(options.description !== undefined
+            ? { description: options.description }
+            : {}),
+        ...(options.spoiler ? { spoiler: true } : {}),
+        ...(options.contentType !== undefined
+            ? { contentType: options.contentType }
+            : {}),
+    };
+    // The brand is not shown by console.log, nor copied by a spread.
+    Object.defineProperty(file, ASSET, { value: true });
+    return Object.freeze(file);
+}
+/** Where the file of an asset is on disk, checked to be inside `public/`. */
+export function assetPath(file) {
+    if (!publicDir) {
+        throw new Error(`asset('${file.path}') can only be sent by a bot run with chapterjs dev or chapterjs start.`);
+    }
+    const target = join(publicDir, normalize(file.path));
+    if (!target.startsWith(publicDir + sep)) {
+        throw new Error(`asset() only reads inside ${PUBLIC_FOLDER}/: ${JSON.stringify(file.path)} leaves it.`);
+    }
+    return target;
+}
+/** The error to give for an asset whose file could not be opened. */
+export function missingAsset(file, error) {
+    return error.code === 'ENOENT'
+        ? new Error(`There is no file ${PUBLIC_FOLDER}/${file.path} in your project: put it there, or pick one of the files the editor lists in asset().`)
+        : error;
+}
+/** Reads the file of an asset, when the message is sent. */
+export async function readAsset(file) {
+    const target = assetPath(file);
+    try {
+        return await readFile(target);
+    }
+    catch (error) {
+        throw missingAsset(file, error);
+    }
+}

package/dist/assets/public.d.ts

@@ -0,0 +1,19 @@
+/** The folder, at the root of the project. */
+export declare const PUBLIC_FOLDER = "public";
+/**
+ * Every file of `public/`, as a path from it with `/`, sorted. Hidden files
+ * (starting with `.`) are left out. An absent folder is an empty list.
+ */
+export declare function listPublic(projectDir: string): Promise<string[]>;
+/**
+ * What `'chapterjs'` declares in every file of the project about `public/`:
+ * the union of its files, and `asset()` typed with it.
+ */
+export declare function publicDeclarations(paths: readonly string[]): string;
+/**
+ * Calls `onChange` when a file of `public/` is added, removed or saved.
+ * The folder may not exist yet: it is watched for as soon as it appears.
+ */
+export declare function watchPublic(projectDir: string, onChange: () => void): {
+    close(): void;
+};

package/dist/assets/public.js

@@ -0,0 +1,120 @@
+// The `public/` folder of a project: the files a bot sends (pictures,
+// documents...). Its content is listed to type `asset()`, so that the
+// editor offers every file and underlines one that does not exist.
+import { existsSync, watch } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { watchFolder } from '../loader/watch.js';
+/** The folder, at the root of the project. */
+export const PUBLIC_FOLDER = 'public';
+/**
+ * Every file of `public/`, as a path from it with `/`, sorted. Hidden files
+ * (starting with `.`) are left out. An absent folder is an empty list.
+ */
+export async function listPublic(projectDir) {
+    const root = join(projectDir, PUBLIC_FOLDER);
+    const entries = await readdir(root, {
+        recursive: true,
+        withFileTypes: true,
+    }).catch(() => []);
+    return entries
+        .filter(entry => entry.isFile())
+        .map(entry => relative(root, join(entry.parentPath, entry.name)).split(sep).join('/'))
+        .filter(path => !path.split('/').some(part => part.startsWith('.')))
+        .sort();
+}
+/**
+ * What `'chapterjs'` declares in every file of the project about `public/`:
+ * the union of its files, and `asset()` typed with it.
+ */
+export function publicDeclarations(paths) {
+    const union = paths.length === 0
+        ? 'never'
+        : paths.map(path => `\n  | ${JSON.stringify(path)}`).join('');
+    return `import type { AssetFile, AssetOptions } from '#chapterjs';
+
+declare module 'chapterjs' {
+  /**
+   * A file of the public/ folder of your project, as a path from it:
+   * \`'photos/monday.png'\`.${paths.length === 0 ? ' The folder is empty or missing: put files in it, and they are listed here.' : ''}
+   */
+  export type PublicFile = ${union.replaceAll('\n', '\n  ')};
+
+  /**
+   * A file of the public/ folder of your project, to send with a message:
+   * \`files: [asset('photos/monday.png')]\`. The editor lists the files of the
+   * folder; the file is read when the message is sent.
+   */
+  export function asset(path: PublicFile, options?: AssetOptions): AssetFile;
+}
+`;
+}
+/**
+ * Calls `onChange` when a file of `public/` is added, removed or saved.
+ * The folder may not exist yet: it is watched for as soon as it appears.
+ */
+export function watchPublic(projectDir, onChange) {
+    const root = join(projectDir, PUBLIC_FOLDER);
+    let inner = null;
+    let outer = null;
+    const watchInside = (loaded) => {
+        try {
+            inner = watchFolder(root, onChange, loaded ? { loaded } : {});
+        }
+        catch {
+            inner = null;
+        }
+    };
+    let catchUps = [];
+    const appeared = () => {
+        if (inner)
+            return;
+        // The folder was not there: what it has by the time it is watched
+        // (files copied with it, or written right after) is all new.
+        watchInside(Promise.resolve(''));
+        if (!inner)
+            return;
+        outer?.close();
+        outer = null;
+        for (const catchUp of catchUps)
+            clearTimeout(catchUp);
+        onChange();
+    };
+    // Until the folder exists, only its parent is watched, for its creation.
+    const watchForCreation = () => {
+        try {
+            outer = watch(projectDir, (_event, name) => {
+                if (name === PUBLIC_FOLDER)
+                    appeared();
+            });
+            outer.unref();
+        }
+        catch {
+            outer = null;
+        }
+        // The system takes a moment to really start watching: a folder created
+        // meanwhile is looked for a little later.
+        catchUps = [300, 1500].map(wait => {
+            const timer = setTimeout(() => {
+                if (existsSync(root))
+                    appeared();
+            }, wait);
+            timer.unref();
+            return timer;
+        });
+    };
+    // Whether the folder is there is asked, not inferred from watch()
+    // failing: on Linux, Node 24 watches a missing folder without an error.
+    if (existsSync(root))
+        watchInside();
+    if (!inner)
+        watchForCreation();
+    return {
+        close() {
+            for (const catchUp of catchUps)
+                clearTimeout(catchUp);
+            inner?.close();
+            outer?.close();
+        },
+    };
+}

package/dist/cache/cache.d.ts

@@ -0,0 +1,62 @@
+import type { Snowflake } from '../discord/types/common.js';
+import type { Channel } from '../structures/channel.js';
+import type { Guild } from '../structures/guild.js';
+import type { User } from '../structures/user.js';
+import { type CacheStore, type CacheStoreFactory } from './store.js';
+/**
+ * How many of each kind of thing are remembered. `0` disables a kind,
+ * `Infinity` keeps everything Discord sends.
+ */
+export interface CacheLimits {
+    /** Users, across every server. */
+    users: number;
+    /**
+     * Members, per server: the ones seen the most recently. The bot itself
+     * is always kept, apart from this.
+     */
+    members: number;
+    /** Messages, per channel. */
+    messages: number;
+}
+/**
+ * Messages are not kept by default: they are by far what a bot receives the
+ * most, and most bots never read an old one. A feature that needs them
+ * raises the limit.
+ */
+export declare const DEFAULT_CACHE_LIMITS: CacheLimits;
+export interface CacheOptions {
+    limits?: Partial<CacheLimits>;
+    /** Where data is stored. Default: the memory of the process. */
+    store?: CacheStoreFactory;
+}
+/**
+ * What the bot currently knows about Discord, kept up to date by events so
+ * that reading it never costs a request. Servers own what belongs to them
+ * (roles, members, emojis...): forgetting a server forgets it all.
+ */
+export declare class Cache {
+    #private;
+    readonly createStore: CacheStoreFactory;
+    readonly users: CacheStore<Snowflake, User>;
+    readonly guilds: CacheStore<Snowflake, Guild>;
+    /** Every channel the bot knows: of servers, threads and private ones. */
+    readonly channels: CacheStore<Snowflake, Channel>;
+    constructor(options?: CacheOptions);
+    /** How many of each kind are kept when memory is not a concern. */
+    get configured(): Readonly<CacheLimits>;
+    /**
+     * Changes what is kept when memory is not a concern (the files of the
+     * project changed and need more, or less). What holds right now follows,
+     * except what memory made lower: that stays as low as it is.
+     */
+    configure(limits: Partial<CacheLimits>): void;
+    /**
+     * How many of each kind are kept right now: what was configured, or less
+     * while memory is short (see `core/memory.ts`). New stores follow it.
+     */
+    get limits(): Readonly<CacheLimits>;
+    /** Changes the limits new stores follow; existing ones are resized apart. */
+    setLimits(limits: Partial<CacheLimits>): void;
+    /** Forgets everything (the session was lost and starts over). */
+    clear(): void;
+}

package/dist/cache/cache.js

@@ -0,0 +1,80 @@
+import { memoryStore, } from './store.js';
+/**
+ * Messages are not kept by default: they are by far what a bot receives the
+ * most, and most bots never read an old one. A feature that needs them
+ * raises the limit.
+ */
+export const DEFAULT_CACHE_LIMITS = {
+    users: Infinity,
+    // A server can have millions of members, and Discord recommends keeping
+    // only what the app needs: what an event comes with (the author of a
+    // message, who used a command) is kept by the event itself, whatever this
+    // limit. A feature that needs more members remembered asks for it (see
+    // `remembers` in the events).
+    // https://docs.discord.com/developers/events/gateway#tracking-state
+    members: 100,
+    messages: 0,
+};
+/**
+ * What the bot currently knows about Discord, kept up to date by events so
+ * that reading it never costs a request. Servers own what belongs to them
+ * (roles, members, emojis...): forgetting a server forgets it all.
+ */
+export class Cache {
+    #configured;
+    #limits;
+    createStore;
+    users;
+    guilds;
+    /** Every channel the bot knows: of servers, threads and private ones. */
+    channels;
+    constructor(options = {}) {
+        this.#configured = Object.freeze({
+            ...DEFAULT_CACHE_LIMITS,
+            ...options.limits,
+        });
+        this.#limits = { ...this.#configured };
+        this.createStore = options.store ?? memoryStore;
+        this.users = this.createStore({ limit: this.limits.users });
+        this.guilds = this.createStore();
+        this.channels = this.createStore();
+    }
+    /** How many of each kind are kept when memory is not a concern. */
+    get configured() {
+        return this.#configured;
+    }
+    /**
+     * Changes what is kept when memory is not a concern (the files of the
+     * project changed and need more, or less). What holds right now follows,
+     * except what memory made lower: that stays as low as it is.
+     */
+    configure(limits) {
+        const next = Object.freeze({ ...this.#configured, ...limits });
+        const now = { ...this.#limits };
+        for (const kind of Object.keys(next)) {
+            now[kind] =
+                this.#limits[kind] === this.#configured[kind]
+                    ? next[kind]
+                    : Math.min(this.#limits[kind], next[kind]);
+        }
+        this.#configured = next;
+        this.#limits = now;
+    }
+    /**
+     * How many of each kind are kept right now: what was configured, or less
+     * while memory is short (see `core/memory.ts`). New stores follow it.
+     */
+    get limits() {
+        return this.#limits;
+    }
+    /** Changes the limits new stores follow; existing ones are resized apart. */
+    setLimits(limits) {
+        this.#limits = { ...this.#limits, ...limits };
+    }
+    /** Forgets everything (the session was lost and starts over). */
+    clear() {
+        this.users.clear();
+        this.guilds.clear();
+        this.channels.clear();
+    }
+}

package/dist/cache/store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where one kind of thing is remembered (the roles of a server, the
+ * messages of a channel...). Reading is a plain `ReadonlyMap`, which is what
+ * users get; only the framework writes.
+ *
+ * Stores are synchronous on purpose: they are read on every event, in the
+ * process that received it. Sharing data between processes is the job of
+ * the layer that coordinates processes, not of the cache.
+ */
+export interface CacheStore<K, V> extends ReadonlyMap<K, V> {
+    /** How many entries it keeps at most right now. */
+    readonly limit: number;
+    /**
+     * Changes how many entries it keeps. Lowered, the entries written the
+     * longest ago leave at once; returns how many did.
+     */
+    resize(limit: number): number;
+    set(key: K, value: V): unknown;
+    delete(key: K): boolean;
+    clear(): void;
+}
+export interface CacheStoreOptions {
+    /**
+     * How many entries are kept at most: `0` keeps nothing, `Infinity` (the
+     * default) keeps everything. When full, the entry that was written the
+     * longest ago leaves: writing an entry again makes it the most recent.
+     */
+    limit?: number;
+}
+/** Creates the store of one kind of thing. A new backend is one of these. */
+export type CacheStoreFactory = <K, V>(options?: CacheStoreOptions) => CacheStore<K, V>;
+/** The default store: a `Map` in the memory of the process. */
+export declare class MemoryStore<K, V> extends Map<K, V> implements CacheStore<K, V> {
+    #private;
+    constructor({ limit }?: CacheStoreOptions);
+    get limit(): number;
+    resize(limit: number): number;
+    set(key: K, value: V): this;
+}
+/**
+ * Makes a store forget its oldest entries until `keep` are left. Returns
+ * how many it forgot.
+ */
+export declare function trimStore<K>(store: CacheStore<K, unknown>, keep: number): number;
+export declare const memoryStore: CacheStoreFactory;

package/dist/cache/store.js

@@ -0,0 +1,53 @@
+function checkLimit(limit) {
+    if (Number.isNaN(limit) || limit < 0) {
+        throw new RangeError(`A cache limit is 0 or more (or Infinity), got ${limit}.`);
+    }
+    return limit;
+}
+/** The default store: a `Map` in the memory of the process. */
+export class MemoryStore extends Map {
+    #limit;
+    constructor({ limit = Infinity } = {}) {
+        super();
+        this.#limit = checkLimit(limit);
+    }
+    get limit() {
+        return this.#limit;
+    }
+    resize(limit) {
+        this.#limit = checkLimit(limit);
+        return trimStore(this, limit);
+    }
+    set(key, value) {
+        if (this.#limit === 0)
+            return this;
+        if (this.#limit !== Infinity) {
+            // A Map iterates in insertion order: written again, an entry goes to
+            // the end, so the first key is always the one seen the longest ago.
+            if (!super.delete(key) && this.size >= this.#limit) {
+                for (const oldest of this.keys()) {
+                    this.delete(oldest);
+                    break;
+                }
+            }
+        }
+        return super.set(key, value);
+    }
+}
+/**
+ * Makes a store forget its oldest entries until `keep` are left. Returns
+ * how many it forgot.
+ */
+export function trimStore(store, keep) {
+    let extra = store.size - Math.max(0, keep);
+    if (extra <= 0)
+        return 0;
+    const forgotten = extra;
+    for (const key of [...store.keys()]) {
+        if (extra-- <= 0)
+            break;
+        store.delete(key);
+    }
+    return forgotten;
+}
+export const memoryStore = options => new MemoryStore(options);

package/dist/cli/build.d.ts

@@ -0,0 +1,41 @@
+import { type BuiltFile } from '../loader/loader.js';
+import type { Log } from './log.js';
+/** Where the build of a project is, from its folder. */
+export declare const buildDir: (cwd: string) => string;
+/** The file the whole bot is compiled into, in the build. */
+export declare const BUNDLE = "bot.js";
+/** What `build.json` says of a build. */
+export interface BuildInfo {
+    /** The version of the framework that made it. */
+    version: string;
+    /** What the files of `src` were when it was made. */
+    sources: string;
+    commands: number;
+    events: number;
+    /** Whether the files join voice channels (an intent to ask for). */
+    voice: boolean;
+}
+/** One value for everything in a folder: it changes when a file does. */
+export declare function fingerprint(dir: string): Promise<string>;
+/** The build of a project, or why there is none to run. */
+export declare function readBuild(cwd: string, version: string): Promise<{
+    info: BuildInfo;
+    stale: boolean;
+} | {
+    problem: string;
+}>;
+/**
+ * Loads the bot a build compiled: every file of the project, already run.
+ * Errors that come out of it afterwards name the file and the line of the
+ * project, not of the compiled file: Node reads the map next to it.
+ */
+export declare function loadBundle(cwd: string): Promise<BuiltFile[]>;
+export interface BuildOptions {
+    /** The folder of the project. */
+    cwd: string;
+    /** The version of the framework. */
+    version: string;
+    log: Log;
+}
+/** Resolves with the exit code of the process. */
+export declare function build(options: BuildOptions): Promise<number>;