chapterjs 0.1.2 → 0.2.0

package/dist/components/button.js

@@ -0,0 +1,106 @@
+// `button()`, as user files import it from 'chapterjs': what the button
+// looks like, what it carries, and what to do when it is clicked.
+// https://docs.discord.com/developers/components/reference#button
+import { Limits } from '../discord/api.js';
+import { ButtonStyle, ComponentType, } from '../discord/types/component.js';
+import { isDynamic, resolveText } from './component.js';
+import { checkData, encodeCustomId, } from './custom-id.js';
+import { createComponent } from './declared.js';
+import { emojiOf } from './instance.js';
+export const BUTTON_STYLES = {
+    primary: ButtonStyle.Primary,
+    secondary: ButtonStyle.Secondary,
+    success: ButtonStyle.Success,
+    danger: ButtonStyle.Danger,
+};
+/**
+ * Declares a button. Export the result from any file of `src/`: the name
+ * of the export is what tells the button apart, so you never write an id.
+ *
+ * ```ts
+ * import { button } from 'chapterjs';
+ *
+ * export const confirm = button({
+ *   label: 'Confirm',
+ *   style: 'success',
+ *   async run({ interaction }) {
+ *     await interaction.update({ content: 'Confirmed!', components: [] });
+ *   },
+ * });
+ * ```
+ */
+export function button(config) {
+    return createComponent('button', config, {
+        asPiece: true,
+        pieceKind: 'button',
+    });
+}
+const fail = (message) => {
+    throw new TypeError(message);
+};
+/** Checks what a message gives to change the look of a button. */
+export function readLook(what, look) {
+    if (look === undefined)
+        return {};
+    if (typeof look !== 'object' || look === null || Array.isArray(look)) {
+        fail(`The look of ${what} is an object like { disabled: true }.`);
+    }
+    const given = look;
+    for (const key of Object.keys(given)) {
+        if (!['label', 'emoji', 'style', 'disabled'].includes(key)) {
+            fail(`"${key}" is not something the look of ${what} has. It can have: label, emoji, style, disabled.`);
+        }
+    }
+    if (given.label !== undefined && !isDynamic(given.label)) {
+        if (typeof given.label !== 'string' ||
+            given.label.trim() === '' ||
+            given.label.length > Limits.ButtonLabel) {
+            fail(`The label of ${what} is a text of 1 to ${Limits.ButtonLabel} characters.`);
+        }
+    }
+    if (given.style !== undefined &&
+        !Object.hasOwn(BUTTON_STYLES, given.style)) {
+        fail(`The style of ${what} is 'primary', 'secondary', 'success' or 'danger', got ${JSON.stringify(given.style)}.`);
+    }
+    if (given.disabled !== undefined && typeof given.disabled !== 'boolean') {
+        fail(`"disabled" of ${what} is true or false.`);
+    }
+    if (given.emoji !== undefined)
+        emojiOf(given.emoji, what);
+    return given;
+}
+/** The button as Discord takes it, for the data and the look given. */
+export function renderButton(loaded, args) {
+    const hasData = Object.keys(loaded.data).length > 0;
+    const { name } = loaded;
+    if (args.length > (hasData ? 2 : 1)) {
+        fail(`${name} takes ${hasData ? 'its data, then a look' : 'a look'} at most: ${hasData ? `${name}({ ... }, { disabled: true })` : `${name}({ disabled: true })`}.`);
+    }
+    const values = checkData(name, loaded.data, hasData ? args[0] : undefined);
+    const look = {
+        ...loaded.look,
+        ...readLook(name, hasData ? args[1] : args[0]),
+    };
+    const base = {
+        type: ComponentType.Button,
+        style: BUTTON_STYLES[look.style],
+        custom_id: encodeCustomId(loaded.name, loaded.data, values),
+    };
+    if (look.emoji !== undefined)
+        base.emoji = emojiOf(look.emoji, name);
+    if (look.disabled)
+        base.disabled = true;
+    const { label } = look;
+    if (label === undefined)
+        return { kind: 'button', raw: base };
+    if (!isDynamic(label))
+        return { kind: 'button', raw: { ...base, label } };
+    // The label is computed when the message is sent, for who will read it.
+    return {
+        kind: 'button',
+        raw: t => ({
+            ...base,
+            label: resolveText(`The label of ${name}`, label, { t, data: values }, { max: Limits.ButtonLabel }),
+        }),
+    };
+}

package/dist/components/component.d.ts

@@ -0,0 +1,140 @@
+import type { DMChannel, GuildTextBasedChannel } from '../structures/channel.js';
+import type { Guild } from '../structures/guild.js';
+import type { Interaction } from '../structures/interaction.js';
+import type { GuildMember } from '../structures/member.js';
+import type { Message } from '../structures/message.js';
+import type { User } from '../structures/user.js';
+import type { DataShape, DataValuesOf } from './custom-id.js';
+import type { Translator } from '../messages/messages.js';
+/**
+ * What a text of a component is computed from when it is a function: `t`
+ * in the language of who will read the message, and the data the
+ * component carries.
+ */
+export interface TextContext<Data extends DataShape = DataShape> {
+    /** The texts of the language files, in the language of who will read the message. */
+    t: Translator;
+    /** What the component carries, as declared in `data`. */
+    data: [DataShape] extends [Data] ? Record<string, string | number | boolean> : DataValuesOf<Data>;
+}
+/**
+ * A text shown by a component: written as is, or computed when the
+ * message is sent, from `t` and the data of the component.
+ */
+export type DynamicText<Data extends DataShape = DataShape> = string | ((context: TextContext<Data>) => string);
+/** Whether a text is computed when the message is sent. */
+export declare const isDynamic: (value: unknown) => value is (context: TextContext) => string;
+/**
+ * Checks a text of a component, now when it is written, or when the
+ * message is sent when it is a function: `resolve` is then what to check.
+ * Returns the text, or `undefined` when there is none and none is needed.
+ */
+export declare function checkDynamicText(what: string, value: unknown, { min, max, required, }: {
+    min?: number;
+    max: number;
+    required?: boolean;
+}): void;
+/** A text given by a file or computed, within the limits of Discord. */
+export declare function checkTextValue(what: string, value: unknown, { min, max }: {
+    min?: number;
+    max: number;
+}): string;
+/** The text of a component when the message is sent. */
+export declare function resolveText(what: string, value: DynamicText | undefined, context: TextContext, limits: {
+    min?: number;
+    max: number;
+}): string | undefined;
+/**
+ * Where a component can be used: in messages of servers (`'guild'`), in
+ * private messages with the bot (`'dm'`), or in both. A component is where
+ * the message that holds it is: this says where your code expects it.
+ */
+export type ComponentWhere = 'guild' | 'dm' | 'both';
+/**
+ * Who may use a component: `'everyone'` who sees the message (the
+ * default), or only the `'author'`, the person who used the command the
+ * message answers. Anyone else gets a private refusal.
+ */
+export type ComponentWho = 'everyone' | 'author';
+/** What every interactive component declares, besides what it looks like. */
+export interface InteractiveConfig<Data extends DataShape, Where extends ComponentWhere> {
+    /**
+     * What the component carries from the message that shows it to the code
+     * that runs when it is used: a name and a kind for each value
+     * (`{ userId: 'string', page: 'number' }`). Given when the component is
+     * put in a message, received typed in `run`. Discord keeps it in the
+     * component itself, so it survives restarts.
+     */
+    data?: Data;
+    /**
+     * Where the component can be used: `'guild'` (in servers, the default),
+     * `'dm'` (in private messages with the bot) or `'both'`. What `run`
+     * receives follows it.
+     */
+    where?: Where;
+    /**
+     * Who may use it: `'everyone'` (the default) or only the `'author'` of
+     * the command the message answers.
+     */
+    who?: ComponentWho;
+    /**
+     * Make the answers of the component only visible to who used it. On a
+     * message only the person sees (an ephemeral answer), they already are.
+     */
+    ephemeral?: boolean;
+}
+/** A server, as an interaction used in one sees it. */
+export type InGuild<I extends Interaction> = I & {
+    readonly guildId: string;
+    readonly guild: Guild;
+    readonly member: GuildMember;
+    readonly channel: GuildTextBasedChannel;
+};
+/** A private message, for something that also works in servers. */
+export type InPrivate<I extends Interaction> = I & {
+    readonly guildId: null;
+    readonly guild: null;
+    readonly member: null;
+    readonly channel: DMChannel;
+};
+/** A private message, for something that only works there: no server at all. */
+export type InDm<I extends Interaction> = Omit<I, 'guildId' | 'guild' | 'member' | 'channel'> & {
+    readonly channel: DMChannel;
+};
+/** What `run` receives about the place, in a server. */
+export interface PlaceInGuild<I extends Interaction> {
+    interaction: InGuild<I>;
+    /** The server it was used in. */
+    guild: Guild;
+    /** Who used it, as a member of the server. */
+    member: GuildMember;
+    /** The channel it was used in. */
+    channel: GuildTextBasedChannel;
+}
+/** What `run` receives about the place, in a private message, when it also works in servers. */
+export interface PlaceInPrivate<I extends Interaction> {
+    interaction: InPrivate<I>;
+    /** No server: it was used in a private message. */
+    guild: null;
+    /** No member: the person is `user`. */
+    member: null;
+    /** The private conversation it was used in. */
+    channel: DMChannel;
+}
+/** What `run` receives about the place, when it only works in private messages. */
+export interface PlaceInDm<I extends Interaction> {
+    interaction: InDm<I>;
+    /** The private conversation it was used in. */
+    channel: DMChannel;
+}
+/** What `run` receives about where it was used, following `where`. */
+export type PlaceOf<Where extends ComponentWhere, I extends Interaction> = Where extends 'guild' ? PlaceInGuild<I> : Where extends 'dm' ? PlaceInDm<I> : PlaceInGuild<I> | PlaceInPrivate<I>;
+/** What every interactive component gives to its `run`, besides the place. */
+export interface InteractiveContext<Data extends DataShape> {
+    /** Who used it. */
+    user: User;
+    /** The message the component is on. */
+    message: Message;
+    /** What the component carries, as declared in `data`. */
+    data: DataValuesOf<Data>;
+}

package/dist/components/component.js

@@ -0,0 +1,39 @@
+// What every interactive component (button, menu, form) shares: where it
+// works, who may use it, what it carries, and what its `run` receives
+// about the place it was used in.
+/** Whether a text is computed when the message is sent. */
+export const isDynamic = (value) => typeof value === 'function';
+/**
+ * Checks a text of a component, now when it is written, or when the
+ * message is sent when it is a function: `resolve` is then what to check.
+ * Returns the text, or `undefined` when there is none and none is needed.
+ */
+export function checkDynamicText(what, value, { min = 1, max, required = false, }) {
+    if (value === undefined) {
+        if (required)
+            throw new TypeError(`${what} is missing.`);
+        return;
+    }
+    if (isDynamic(value))
+        return;
+    checkTextValue(what, value, { min, max });
+}
+/** A text given by a file or computed, within the limits of Discord. */
+export function checkTextValue(what, value, { min = 1, max }) {
+    if (typeof value !== 'string') {
+        throw new TypeError(`${what} is a text${min === 1 ? ` of 1 to ${max} characters` : ''}, got ${typeof value}.`);
+    }
+    if (value.length < min ||
+        value.length > max ||
+        (min > 0 && value.trim() === '')) {
+        throw new RangeError(`${what} is ${value.length} characters long: Discord accepts between ${min} and ${max}.`);
+    }
+    return value;
+}
+/** The text of a component when the message is sent. */
+export function resolveText(what, value, context, limits) {
+    if (value === undefined)
+        return undefined;
+    const text = isDynamic(value) ? value(context) : value;
+    return checkTextValue(isDynamic(value) ? `${what}, as its function returned it,` : what, text, limits);
+}

package/dist/components/custom-id.d.ts

@@ -0,0 +1,72 @@
+/** The kinds of values a component can carry in its `data`. */
+export type DataKind = 'string' | 'number' | 'boolean';
+/**
+ * One value a component carries: its kind, or its kind with a default
+ * value, which makes it optional where the component is put in a message.
+ */
+export type DataField = DataKind | {
+    type: 'string';
+    default?: string;
+} | {
+    type: 'number';
+    default?: number;
+} | {
+    type: 'boolean';
+    default?: boolean;
+};
+/** What a component carries: a name for each value, and its kind. */
+export type DataShape = Readonly<Record<string, DataField>>;
+/** The kind of a field, however it was written. */
+type KindOf<Field extends DataField> = Field extends DataKind ? Field : Field extends {
+    type: infer Kind;
+} ? Kind : never;
+type ValueOf<Field extends DataField> = KindOf<Field> extends 'string' ? string : KindOf<Field> extends 'number' ? number : boolean;
+/** The names of the fields that have a default value. */
+type WithDefault<Shape extends DataShape> = {
+    [Name in keyof Shape]: Shape[Name] extends {
+        default: {};
+    } ? Name : never;
+}[keyof Shape];
+/**
+ * The values of a `data` declaration, typed from it: what `run` and the
+ * texts of the component receive. A value with a default is always there.
+ */
+export type DataValuesOf<Shape extends DataShape> = {
+    [Name in keyof Shape]: ValueOf<Shape[Name]>;
+};
+/**
+ * What a message gives to a component: the values of its `data`, those
+ * with a default value being optional.
+ */
+export type DataInputOf<Shape extends DataShape> = {
+    [Name in Exclude<keyof Shape, WithDefault<Shape>>]: ValueOf<Shape[Name]>;
+} & {
+    [Name in WithDefault<Shape>]?: ValueOf<Shape[Name]>;
+};
+export declare const DATA_KINDS: readonly DataKind[];
+/** The kind of a field, however it was written. */
+export declare const kindOf: (field: DataField) => DataKind;
+/** The default value of a field, if it has one. */
+export declare const defaultOf: (field: DataField) => string | number | boolean | undefined;
+/** Whether a component can be put in a message without data. */
+export declare const needsNoData: (shape: DataShape) => boolean;
+/** Checks the values a file gives to a component against its `data`. */
+export declare function checkData(what: string, shape: DataShape, values: unknown): Record<string, string | number | boolean>;
+/**
+ * The `custom_id` of a component: its name, then its values in the order
+ * of the declaration. Discord accepts 100 characters: when the data does
+ * not fit, the error says by how much.
+ */
+export declare function encodeCustomId(name: string, shape: DataShape, values: Record<string, string | number | boolean>): string;
+/** The name and the encoded values of a `custom_id` the framework wrote. */
+export declare function decodeCustomId(id: string): {
+    name: string;
+    parts: string[];
+};
+/**
+ * The values a `custom_id` carries, typed as the component declares them.
+ * `null` when they do not match the declaration: the file changed since the
+ * message was sent.
+ */
+export declare function readData(shape: DataShape, parts: readonly string[]): Record<string, string | number | boolean> | null;
+export {};

package/dist/components/custom-id.js

@@ -0,0 +1,128 @@
+// The `custom_id` of a component is never written by users: it is the name
+// of the export that declares the component (`ban`), followed by the data
+// the component carries, encoded by the framework. Stateless by design: it
+// survives a restart, and every process of the bot reads it the same way.
+// https://docs.discord.com/developers/components/reference#anatomy-of-a-component-custom-id
+import { Limits } from '../discord/api.js';
+export const DATA_KINDS = ['string', 'number', 'boolean'];
+/** The kind of a field, however it was written. */
+export const kindOf = (field) => typeof field === 'string' ? field : field.type;
+/** The default value of a field, if it has one. */
+export const defaultOf = (field) => typeof field === 'string' ? undefined : field.default;
+/** Whether a component can be put in a message without data. */
+export const needsNoData = (shape) => Object.values(shape).every(field => defaultOf(field) !== undefined);
+/** Fields are separated by `:`; a `:` or a `\` inside a value is escaped. */
+const SEPARATOR = ':';
+const escape = (value) => value.replace(/[\\:]/g, char => `\\${char}`);
+/**
+ * Splits on the separators that are not escaped, and unescapes the rest.
+ * Written by hand: a regular expression would need lookbehinds that count.
+ */
+function split(encoded) {
+    const parts = [];
+    let current = '';
+    for (let index = 0; index < encoded.length; index++) {
+        const char = encoded[index];
+        if (char === '\\' && index + 1 < encoded.length) {
+            current += encoded[++index];
+        }
+        else if (char === SEPARATOR) {
+            parts.push(current);
+            current = '';
+        }
+        else
+            current += char;
+    }
+    parts.push(current);
+    return parts;
+}
+/** Checks the values a file gives to a component against its `data`. */
+export function checkData(what, shape, values) {
+    const names = Object.keys(shape);
+    if (names.length === 0) {
+        if (values !== undefined) {
+            throw new TypeError(`${what} carries no data: it is used as is, without arguments.`);
+        }
+        return {};
+    }
+    const example = `${what}({ ${names
+        .filter(name => defaultOf(shape[name]) === undefined)
+        .map(name => `${name}: ${kindOf(shape[name]) === 'string' ? "'...'" : kindOf(shape[name]) === 'number' ? '1' : 'true'}`)
+        .join(', ')} })`;
+    // Every value has a default: the component is used as is, or with some.
+    if (values === undefined && needsNoData(shape))
+        values = {};
+    if (typeof values !== 'object' || values === null || Array.isArray(values)) {
+        throw new TypeError(`${what} needs its data: write ${example}.`);
+    }
+    const given = values;
+    for (const key of Object.keys(given)) {
+        if (!Object.hasOwn(shape, key)) {
+            throw new TypeError(`"${key}" is not in the data of ${what}. Its data is: ${names.join(', ')}.`);
+        }
+    }
+    const result = {};
+    for (const name of names) {
+        const fallback = defaultOf(shape[name]);
+        const value = given[name] === undefined ? fallback : given[name];
+        const kind = kindOf(shape[name]);
+        const got = JSON.stringify(value) ?? typeof value;
+        if (typeof value !== kind ||
+            (kind === 'number' && !Number.isFinite(value))) {
+            throw new TypeError(`The data "${name}" of ${what} is a ${kind}, got ${got}.`);
+        }
+        result[name] = value;
+    }
+    return result;
+}
+/**
+ * The `custom_id` of a component: its name, then its values in the order
+ * of the declaration. Discord accepts 100 characters: when the data does
+ * not fit, the error says by how much.
+ */
+export function encodeCustomId(name, shape, values) {
+    const parts = [name];
+    for (const field of Object.keys(shape))
+        parts.push(escape(String(values[field])));
+    const id = parts.join(SEPARATOR);
+    if (id.length > Limits.CustomId) {
+        throw new RangeError(`The data of ${name} is ${id.length - name.length - 1} characters long once encoded, and Discord leaves ${Limits.CustomId - name.length - 1} for it (its id is ${name}, ${name.length} characters, out of ${Limits.CustomId}). Carry less: an id instead of a name, or a shorter export name.`);
+    }
+    return id;
+}
+/** The name and the encoded values of a `custom_id` the framework wrote. */
+export function decodeCustomId(id) {
+    const [name = '', ...parts] = split(id);
+    return { name, parts };
+}
+/**
+ * The values a `custom_id` carries, typed as the component declares them.
+ * `null` when they do not match the declaration: the file changed since the
+ * message was sent.
+ */
+export function readData(shape, parts) {
+    const names = Object.keys(shape);
+    if (parts.length !== names.length)
+        return null;
+    const values = {};
+    for (const [index, name] of names.entries()) {
+        const part = parts[index];
+        switch (kindOf(shape[name])) {
+            case 'number': {
+                const number = Number(part);
+                if (part.trim() === '' || !Number.isFinite(number))
+                    return null;
+                values[name] = number;
+                break;
+            }
+            case 'boolean':
+                if (part !== 'true' && part !== 'false')
+                    return null;
+                values[name] = part === 'true';
+                break;
+            default:
+                values[name] = part;
+        }
+    }
+    return values;
+}

package/dist/components/declaration.d.ts

@@ -0,0 +1,42 @@
+import type { Declaration } from '../loader/loader.js';
+import { type LoadedButton } from './button.js';
+import { isEmbedDeclaration } from './embed.js';
+import { type ComponentKind } from './declared.js';
+import { type LoadedModal } from './modal.js';
+import { type LoadedSelect } from './select.js';
+/** An embed, checked (when it is static). */
+export interface LoadedEmbed {
+    readonly kind: 'embed';
+    /** The name of the export that declares it. */
+    readonly name: string;
+}
+/** A component, checked: what the router works with. */
+export type LoadedComponent = LoadedButton | LoadedSelect | LoadedModal | LoadedEmbed;
+/** What each kind is called in messages. */
+export declare const WHAT: Record<ComponentKind, string>;
+/**
+ * A component (a button, a select menu, a form or an embed), declared
+ * anywhere in `src/` with `button()`, `select()`, `modal()` or `embed()`,
+ * and exported: the name of the export is its id, so a file may declare
+ * several, each under its own export.
+ */
+export declare const componentDeclaration: Declaration<LoadedComponent>;
+/** Two components of the same kind with the same name: the later one is left out. */
+export declare function findDuplicates<T extends {
+    file: string;
+    export: string;
+    component: {
+        kind: ComponentKind;
+        name: string;
+    };
+}>(entries: readonly T[]): {
+    valid: T[];
+    conflicts: {
+        file: string;
+        export: string;
+        message: string;
+    }[];
+};
+/** Whether a declaration is an embed: nothing to route. */
+export declare const isEmbedLoaded: (component: LoadedComponent) => component is LoadedEmbed;
+export { isEmbedDeclaration };