chapterjs 0.1.2 → 0.2.0

package/dist/components/declaration.js

@@ -0,0 +1,342 @@
+// What a file declares with `button()`, `select()`, `modal()` and
+// `embed()`, checked when it loads against the limits of Discord, so a
+// mistake is explained before Discord refuses it; the component is then
+// bound to the name of its export, which is its id and what makes its
+// instances.
+import { Limits } from '../discord/api.js';
+import { checkEmbed } from '../structures/payload.js';
+import { isDynamic } from './component.js';
+import { readLook, renderButton, } from './button.js';
+import { DATA_KINDS } from './custom-id.js';
+import { isEmbedDeclaration } from './embed.js';
+import { bindComponent, componentStateOf, } from './declared.js';
+import { readField, renderModal } from './modal.js';
+import { readOptions } from './options.js';
+import { readChannelTypes, readPlaceholder, readRange, renderSelect, SELECT_TYPES, } from './select.js';
+const fail = (message) => {
+    throw new TypeError(message);
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * What the name of a component can hold: the name of an export (or of a
+ * file, for a default export), as long as a custom_id can carry it beside
+ * the data: no `:` (what separates the data), and room left for the data.
+ */
+const NAME = /^[^:\s]+$/;
+function checkKeys(what, value, allowed) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            fail(`"${key}" is not something ${what} has. It can have: ${allowed.join(', ')}.`);
+        }
+    }
+}
+function checkBoolean(what, value) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== 'boolean')
+        return fail(`${what} is true or false, got ${JSON.stringify(value) ?? typeof value}.`);
+    return value;
+}
+const PLACES = ['guild', 'dm', 'both'];
+function checkWhere(what, value) {
+    if (value === undefined)
+        return 'guild';
+    if (!PLACES.includes(value)) {
+        return fail(`"where" says where ${what} can be used: 'guild' (in servers, which is the default), 'dm' (in private messages with the bot) or 'both'. Got ${JSON.stringify(value) ?? typeof value}.`);
+    }
+    return value;
+}
+function checkWho(what, value) {
+    if (value === undefined)
+        return 'everyone';
+    if (value !== 'everyone' && value !== 'author') {
+        return fail(`"who" says who may use ${what}: 'everyone' (the default) or 'author' (only who used the command the message answers). Got ${JSON.stringify(value) ?? typeof value}.`);
+    }
+    return value;
+}
+function checkDataShape(what, value) {
+    if (value === undefined)
+        return Object.freeze({});
+    if (!isRecord(value)) {
+        return fail(`"data" of ${what} is an object from a name to a kind: data: { userId: 'string', page: 'number' }.`);
+    }
+    const kinds = DATA_KINDS.map(one => `'${one}'`).join(', ');
+    for (const [name, field] of Object.entries(value)) {
+        if (!/^[A-Za-z_$][\w$]*$/.test(name)) {
+            fail(`"${name}" can't be the name of a data of ${what}: it is how your code reads it (data.${name}), so use letters, digits and _ only.`);
+        }
+        // A kind, or a kind with a default value.
+        if (isRecord(field)) {
+            for (const key of Object.keys(field)) {
+                if (key !== 'type' && key !== 'default') {
+                    fail(`"${key}" is not something the data "${name}" of ${what} has. It can have: type, default.`);
+                }
+            }
+            if (!DATA_KINDS.includes(field.type)) {
+                fail(`The data "${name}" of ${what} has the type ${JSON.stringify(field.type) ?? typeof field.type}, which does not exist. Kinds are: ${kinds}.`);
+            }
+            if (field.default !== undefined &&
+                (typeof field.default !== field.type ||
+                    (field.type === 'number' && !Number.isFinite(field.default)))) {
+                fail(`The default value of the data "${name}" of ${what} must be a ${field.type}, got ${JSON.stringify(field.default) ?? typeof field.default}.`);
+            }
+            continue;
+        }
+        if (!DATA_KINDS.includes(field)) {
+            fail(`The data "${name}" of ${what} has the kind ${JSON.stringify(field) ?? typeof field}, which does not exist. Kinds are: ${kinds}, or { type: 'number', default: 1 } for a value with a default.`);
+        }
+    }
+    return Object.freeze({ ...value });
+}
+function checkRun(what, value, example) {
+    if (typeof value !== 'function') {
+        fail(`${what} has no "run": the function to run when someone uses it, like ${example}`);
+    }
+}
+function readButton(name, config) {
+    if (!isRecord(config)) {
+        return fail(`button() needs an object: button({ label: '...', run({ interaction }) { ... } })`);
+    }
+    const what = 'this button';
+    checkKeys('a button', config, [
+        'label',
+        'emoji',
+        'style',
+        'disabled',
+        'data',
+        'where',
+        'who',
+        'ephemeral',
+        'run',
+    ]);
+    const look = readLook(what, {
+        ...(config.label !== undefined ? { label: config.label } : {}),
+        ...(config.emoji !== undefined ? { emoji: config.emoji } : {}),
+        ...(config.style !== undefined ? { style: config.style } : {}),
+        ...(config.disabled !== undefined ? { disabled: config.disabled } : {}),
+    });
+    if (look.label === undefined && look.emoji === undefined) {
+        fail('A button needs a label or an emoji.');
+    }
+    checkRun(what, config.run, `async run({ interaction }) { await interaction.update('Done!'); }`);
+    return Object.freeze({
+        kind: 'button',
+        name,
+        look: {
+            style: look.style ?? 'primary',
+            disabled: look.disabled ?? false,
+            ...(look.label !== undefined ? { label: look.label } : {}),
+            ...(look.emoji !== undefined ? { emoji: look.emoji } : {}),
+        },
+        data: checkDataShape(what, config.data),
+        where: checkWhere(what, config.where),
+        who: checkWho(what, config.who),
+        ephemeral: checkBoolean('"ephemeral"', config.ephemeral),
+        run: config.run,
+    });
+}
+function readSelect(name, config) {
+    if (!isRecord(config)) {
+        return fail(`select() needs an object: select({ options: ['a', 'b'], run({ interaction, value }) { ... } })`);
+    }
+    const what = 'this select menu';
+    const type = (config.type ?? 'string');
+    if (!Object.hasOwn(SELECT_TYPES, type)) {
+        fail(`The type of ${what} is ${JSON.stringify(config.type)}, which does not exist. Types are: ${Object.keys(SELECT_TYPES)
+            .map(one => `'${one}'`)
+            .join(', ')}.`);
+    }
+    checkKeys('a select menu', config, [
+        'type',
+        'options',
+        'placeholder',
+        'min',
+        'max',
+        'disabled',
+        'channelTypes',
+        'data',
+        'where',
+        'who',
+        'ephemeral',
+        'run',
+    ]);
+    if (type !== 'string' && config.options !== undefined) {
+        fail(`${what} lists ${type}s: Discord fills it, so it takes no "options".`);
+    }
+    if (type !== 'channel' && config.channelTypes !== undefined) {
+        fail(`"channelTypes" is only for a menu of channels (type: 'channel').`);
+    }
+    const options = type === 'string' ? readOptions(what, config.options) : [];
+    const placeholder = readPlaceholder(what, config.placeholder);
+    checkRun(what, config.run, `async run({ interaction, values }) { ... }`);
+    return Object.freeze({
+        kind: 'select',
+        name,
+        type: type,
+        options: Object.freeze(options),
+        channelTypes: readChannelTypes(what, config.channelTypes),
+        look: {
+            ...(placeholder !== undefined ? { placeholder } : {}),
+            ...(checkBoolean('"disabled"', config.disabled)
+                ? { disabled: true }
+                : {}),
+        },
+        ...readRange(what, config, Limits.SelectValues, { min: 1, max: 1 }),
+        data: checkDataShape(what, config.data),
+        where: checkWhere(what, config.where),
+        who: checkWho(what, config.who),
+        ephemeral: checkBoolean('"ephemeral"', config.ephemeral),
+        run: config.run,
+    });
+}
+function readModal(name, config) {
+    if (!isRecord(config)) {
+        return fail(`modal() needs an object: modal({ title: '...', fields: { ... }, run({ interaction, fields }) { ... } })`);
+    }
+    const what = 'this form';
+    checkKeys('a form', config, [
+        'title',
+        'fields',
+        'data',
+        'where',
+        'ephemeral',
+        'run',
+    ]);
+    if (!isDynamic(config.title) &&
+        (typeof config.title !== 'string' ||
+            config.title.trim() === '' ||
+            config.title.length > Limits.ModalTitle)) {
+        fail(`The title of ${what} is a text of 1 to ${Limits.ModalTitle} characters.`);
+    }
+    if (!isRecord(config.fields)) {
+        fail(`"fields" of ${what} is an object whose keys are the names of the fields: fields: { reason: { type: 'text', label: 'Reason' } }`);
+    }
+    const fields = Object.entries(config.fields).map(([name, field]) => readField(name, field));
+    const inputs = fields.filter(field => field.field.type !== 'note');
+    if (fields.length === 0 || fields.length > Limits.ModalFields) {
+        fail(`${what} has ${fields.length} fields: Discord accepts between 1 and ${Limits.ModalFields}.`);
+    }
+    if (inputs.length === 0) {
+        fail(`${what} has nothing to fill in: add a field like { type: 'text', label: '...' }.`);
+    }
+    checkRun(what, config.run, `async run({ interaction, fields }) { ... }`);
+    return Object.freeze({
+        kind: 'modal',
+        name,
+        title: config.title,
+        fields: Object.freeze(fields),
+        data: checkDataShape(what, config.data),
+        where: checkWhere(what, config.where),
+        ephemeral: checkBoolean('"ephemeral"', config.ephemeral),
+        run: config.run,
+    });
+}
+/** One component, by the kind it was declared with. */
+function readOne(state, declared, { name, file, export: exported }) {
+    const what = `the ${WHAT[state.kind]} ${name}`;
+    if (!NAME.test(name)) {
+        fail(`"${name}" can't be the name of a ${WHAT[state.kind]}: the name of the export is its id, and an id has no space and no ":". Rename the export.`);
+    }
+    if (name.length > Limits.CustomId - 20) {
+        fail(`The name of ${what} is ${name.length} characters long: Discord gives ${Limits.CustomId} characters to the id of a component and its data together. Rename the export${exported === 'default' ? ` or the file ${file}` : ''} with something shorter.`);
+    }
+    switch (state.kind) {
+        case 'button': {
+            const loaded = readButton(name, state.config);
+            bindComponent(declared, {
+                name,
+                render: args => renderButton(loaded, args),
+            });
+            return loaded;
+        }
+        case 'select': {
+            const loaded = readSelect(name, state.config);
+            bindComponent(declared, {
+                name,
+                render: args => renderSelect(loaded, args),
+            });
+            return loaded;
+        }
+        case 'modal': {
+            const loaded = readModal(name, state.config);
+            bindComponent(declared, {
+                name,
+                render: args => renderModal(loaded, args),
+            });
+            return loaded;
+        }
+        default: {
+            const { config } = state;
+            if (typeof config !== 'function') {
+                if (!isRecord(config)) {
+                    fail(`embed() takes the embed itself ({ title: '...' }) or a function that returns one.`);
+                }
+                checkEmbed(config, 'this embed');
+            }
+            bindComponent(declared, {
+                name,
+                render: args => {
+                    if (typeof config === 'function')
+                        return config(...args);
+                    if (args.length > 0)
+                        fail(`${name} always looks the same: it takes no arguments.`);
+                    return config;
+                },
+            });
+            return Object.freeze({ kind: 'embed', name });
+        }
+    }
+}
+/** What each kind is called in messages. */
+export const WHAT = {
+    button: 'button',
+    select: 'select menu',
+    modal: 'form',
+    embed: 'embed',
+};
+/**
+ * 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 const componentDeclaration = {
+    one: 'component',
+    many: 'components',
+    is: value => componentStateOf(value) !== undefined,
+    list: false,
+    read(value, site) {
+        return readOne(componentStateOf(value), value, site);
+    },
+};
+/** Two components of the same kind with the same name: the later one is left out. */
+export function findDuplicates(entries) {
+    const seen = new Map();
+    const conflicts = [];
+    const valid = [...entries]
+        .sort((a, b) => a.file === b.file
+        ? a.export < b.export
+            ? -1
+            : 1
+        : a.file < b.file
+            ? -1
+            : 1)
+        .filter(entry => {
+        const key = `${entry.component.kind}:${entry.component.name}`;
+        const first = seen.get(key);
+        if (!first) {
+            seen.set(key, entry);
+            return true;
+        }
+        conflicts.push({
+            file: entry.file,
+            export: entry.export,
+            message: `There is already a ${WHAT[entry.component.kind]} named ${entry.component.name}, in ${first.file}: the name of the export is what tells a ${WHAT[entry.component.kind]} apart, so rename one of them.`,
+        });
+        return false;
+    });
+    return { valid, conflicts };
+}
+/** Whether a declaration is an embed: nothing to route. */
+export const isEmbedLoaded = (component) => component.kind === 'embed';
+export { isEmbedDeclaration };

package/dist/components/declared.d.ts

@@ -0,0 +1,29 @@
+import { type PieceKind, type Rendered } from './instance.js';
+/** The kinds of components a file declares. */
+export type ComponentKind = 'button' | 'select' | 'modal' | 'embed';
+/** A declared component as the loader knows it: what it declared, and once loaded, how to make instances. */
+export interface ComponentState {
+    readonly kind: ComponentKind;
+    readonly config: unknown;
+    /** What made it, for messages: `button()`. */
+    readonly made: string;
+    bound?: {
+        /** The name of the export that declares it: its id. */
+        name: string;
+        /** Makes an instance from what the component was called with. */
+        render: (args: readonly unknown[]) => Rendered | object;
+    };
+}
+/** The state of a declared component, if the value is one. */
+export declare function componentStateOf(value: unknown): ComponentState | undefined;
+/**
+ * Makes a declared component. `asPiece` says whether it stands for its
+ * instance by itself when it carries no data (a button, a menu, a modal:
+ * not an embed, which is only a function).
+ */
+export declare function createComponent(kind: ComponentKind, config: unknown, { asPiece, pieceKind }: {
+    asPiece: boolean;
+    pieceKind?: PieceKind;
+}): (...args: unknown[]) => unknown;
+/** Binds a declared component to its name and to what makes its instances. */
+export declare function bindComponent(declared: unknown, bound: NonNullable<ComponentState['bound']>): void;

package/dist/components/declared.js

@@ -0,0 +1,49 @@
+// What `button()`, `select()`, `modal()` and `embed()` return: a component,
+// declared in a file of the project. It is a function (called with the
+// data the component carries) that the loader recognises, checks, and binds
+// to the name of its export: that name is the custom_id. Until then it can't
+// make anything, which is how a component the framework never loaded is
+// refused.
+import { piece, pieceFunction, } from './instance.js';
+const STATE = Symbol.for('chapterjs.component.declared');
+/** The state of a declared component, if the value is one. */
+export function componentStateOf(value) {
+    if (typeof value !== 'function')
+        return undefined;
+    return value[STATE];
+}
+/**
+ * Makes a declared component. `asPiece` says whether it stands for its
+ * instance by itself when it carries no data (a button, a menu, a modal:
+ * not an embed, which is only a function).
+ */
+export function createComponent(kind, config, { asPiece, pieceKind }) {
+    const state = { kind, config, made: `${kind}()` };
+    const notBound = () => {
+        throw new Error(`This ${kind} was not loaded by ChapterJS: a ${kind} is exported from a file of src/ (export const name = ${kind}({ ... })), and used once the bot started.`);
+    };
+    const declared = (...args) => {
+        if (!state.bound)
+            return notBound();
+        const rendered = state.bound.render(args);
+        return pieceKind
+            ? piece(pieceKind, rendered.raw)
+            : rendered;
+    };
+    Object.defineProperty(declared, STATE, { value: state });
+    Object.defineProperty(declared, 'config', {
+        value: config,
+        enumerable: true,
+    });
+    if (asPiece) {
+        pieceFunction(declared, () => state.bound ? state.bound.render([]) : notBound());
+    }
+    return declared;
+}
+/** Binds a declared component to its name and to what makes its instances. */
+export function bindComponent(declared, bound) {
+    const state = componentStateOf(declared);
+    if (!state)
+        throw new TypeError('Not a component.');
+    state.bound = bound;
+}

package/dist/components/embed.d.ts

@@ -0,0 +1,29 @@
+import type { Embed } from '../structures/payload.js';
+/**
+ * What `embed()` returns: a declaration the framework finds in the exports
+ * of a file. Import it where you send a message: `embeds: [welcome({
+ * member })]`, or `embeds: [rules]` for an embed that always looks the
+ * same.
+ */
+export type EmbedDeclaration<Args extends readonly unknown[] = []> = {
+    /** What the file gave to `embed()`, not checked yet. */
+    readonly config: unknown;
+} & ((...args: Args) => Embed);
+/**
+ * Declares an embed. Export the result from any file of `src/`. Give it
+ * the embed itself when it always looks the same, or a function of what it
+ * shows:
+ *
+ * ```ts
+ * import { embed, type GuildMember } from 'chapterjs';
+ *
+ * export const welcome = embed((member: GuildMember) => ({
+ *   title: `Welcome ${member.displayName}!`,
+ *   color: 0x57f287,
+ * }));
+ * ```
+ */
+export declare function embed(definition: Embed): EmbedDeclaration<[]>;
+export declare function embed<const Args extends readonly unknown[]>(definition: (...args: Args) => Embed): EmbedDeclaration<Args>;
+/** Whether a value is a declared embed: a function to call for the embed. */
+export declare const isEmbedDeclaration: (value: unknown) => value is EmbedDeclaration<readonly unknown[]>;

package/dist/components/embed.js

@@ -0,0 +1,11 @@
+// `embed()`, as user files import it from 'chapterjs': an embed written
+// once, used in every message that needs it.
+// Static, or a function of what it shows.
+import { createComponent, componentStateOf } from './declared.js';
+export function embed(definition) {
+    return createComponent('embed', definition, {
+        asPiece: false,
+    });
+}
+/** Whether a value is a declared embed: a function to call for the embed. */
+export const isEmbedDeclaration = (value) => componentStateOf(value)?.kind === 'embed';

package/dist/components/instance.d.ts

@@ -0,0 +1,100 @@
+import type { RawActionRow, RawButton, RawContainer, RawFileComponent, RawMediaGallery, RawSection, RawSelectMenu, RawSeparator, RawTextDisplay, RawThumbnail } from '../discord/types/component.js';
+import type { RawEmoji } from '../discord/types/emoji.js';
+import type { RawInteractionCallbackModalData } from '../discord/types/interaction.js';
+import type { EmojiInput } from '../structures/message.js';
+import type { Translator } from '../messages/messages.js';
+declare const brand: unique symbol;
+/** A piece of a message made by ChapterJS: a button, a menu, a layout. */
+export interface Piece<Kind extends string> {
+    /** What kind of piece it is. Only the framework makes pieces. */
+    readonly [brand]: Kind;
+}
+/** A button: declared with `button()`, or made with `linkButton()` or `premiumButton()`. */
+export type ButtonComponent = Piece<'button'>;
+/** A select menu declared with `select()`. */
+export type SelectComponent = Piece<'select'>;
+/** A row of up to 5 buttons, or of one menu: `row()`. */
+export type ActionRowComponent = Piece<'row'>;
+/** A text: `text()`. */
+export type TextComponent = Piece<'text'>;
+/** Texts with a button or a thumbnail beside them: `section()`. */
+export type SectionComponent = Piece<'section'>;
+/** A small image beside a section: `thumbnail()`. */
+export type ThumbnailComponent = Piece<'thumbnail'>;
+/** Up to 10 images or videos: `gallery()`. */
+export type GalleryComponent = Piece<'gallery'>;
+/** An attached file shown in the message: `file()`. */
+export type FileComponent = Piece<'file'>;
+/** Space, with or without a line: `separator()`. */
+export type SeparatorComponent = Piece<'separator'>;
+/** A box around other pieces, with an optional color: `container()`. */
+export type ContainerComponent = Piece<'container'>;
+/** A form to open with `interaction.showModal()`: declared with `modal()`. */
+export type ModalComponent = Piece<'modal'>;
+/** What a container can hold. */
+export type ContainerChild = ButtonComponent | SelectComponent | ActionRowComponent | TextComponent | SectionComponent | GalleryComponent | FileComponent | SeparatorComponent;
+/**
+ * What the `components` of a message take. Buttons and menus are put in
+ * rows by the framework (5 buttons per row, a menu alone in its row);
+ * `row()` is there to choose. As soon as a message has a text, a section,
+ * a gallery, a file, a separator or a container, it is built with
+ * components only: Discord then takes no `content` and no `embeds`.
+ * @see https://docs.discord.com/developers/components/reference
+ */
+export type MessageComponent = ContainerChild | ContainerComponent;
+export type PieceKind = 'button' | 'select' | 'row' | 'text' | 'section' | 'thumbnail' | 'gallery' | 'file' | 'separator' | 'container' | 'modal';
+interface RawOf {
+    button: RawButton;
+    select: RawSelectMenu;
+    row: RawActionRow;
+    text: RawTextDisplay;
+    section: RawSection;
+    thumbnail: RawThumbnail;
+    gallery: RawMediaGallery;
+    file: RawFileComponent;
+    separator: RawSeparator;
+    container: RawContainer;
+    modal: RawInteractionCallbackModalData;
+}
+/**
+ * What a piece sends: known when the piece is made, or computed when the
+ * message is sent, with `t` in the language of who will read it (a piece
+ * whose texts are functions).
+ */
+export type Deferred<R> = R | ((t: Translator) => R);
+/** A piece as the framework sees it. */
+export interface Rendered<Kind extends PieceKind = PieceKind> {
+    kind: Kind;
+    raw: Deferred<RawOf[Kind]>;
+}
+/** A piece with what it sends, known: after `resolve()`. */
+export interface Resolved<Kind extends PieceKind = PieceKind> {
+    kind: Kind;
+    raw: RawOf[Kind];
+}
+/** What a piece sends, for the language of who will read it. */
+export declare function resolve<Kind extends PieceKind>(rendered: Rendered<Kind>, t: Translator): Resolved<Kind>;
+/**
+ * What a piece made of others sends: known now when every child is, else
+ * computed when the message is sent, from what the children send then.
+ */
+export declare function compose<R>(children: readonly Rendered[], build: (raws: readonly unknown[]) => R): Deferred<R>;
+/** Makes a piece. `raw` is frozen: a piece never changes once made. */
+export declare function piece<Kind extends PieceKind>(kind: Kind, raw: Deferred<RawOf[Kind]>): Piece<Kind>;
+/**
+ * Lets a function stand for a piece: the file of a button without data is
+ * a function (called with a look) and also the button itself. `render`
+ * is asked for the piece when the message is built.
+ */
+export declare function pieceFunction<F extends object>(target: F, render: () => Rendered): F;
+/** Whether a value is a piece made by the framework. */
+export declare function isPiece(value: unknown): value is Piece<PieceKind>;
+/** What a piece is and how it is sent. Throws on anything else. */
+export declare function renderedOf(value: unknown, where: string): Rendered;
+/**
+ * An emoji as a component takes it: a standard one (`'👍'`), a custom one as
+ * Discord writes it (`'<:name:id>'`, `'<a:name:id>'`) or one of
+ * `guild.emojis`.
+ */
+export declare function emojiOf(input: EmojiInput, what: string): Partial<RawEmoji>;
+export {};

package/dist/components/instance.js

@@ -0,0 +1,86 @@
+// What goes in the `components` of a message: pieces made by the framework
+// (a button declared with `button()`, a `row()`, a `container()`...),
+// never raw JSON. Each piece knows the Discord shape it is sent as; the
+// brand is what lets a message refuse anything else, so that no custom_id
+// is ever written by hand.
+/** What a piece sends, for the language of who will read it. */
+export function resolve(rendered, t) {
+    const { kind, raw } = rendered;
+    return { kind, raw: typeof raw === 'function' ? raw(t) : raw };
+}
+/**
+ * What a piece made of others sends: known now when every child is, else
+ * computed when the message is sent, from what the children send then.
+ */
+export function compose(children, build) {
+    if (children.every(child => typeof child.raw !== 'function')) {
+        return build(children.map(child => child.raw));
+    }
+    return (t) => build(children.map(child => resolve(child, t).raw));
+}
+const INSTANCE = Symbol.for('chapterjs.component');
+/** Makes a piece. `raw` is frozen: a piece never changes once made. */
+export function piece(kind, raw) {
+    return Object.freeze({
+        [INSTANCE]: true,
+        kind,
+        raw,
+    });
+}
+/**
+ * Lets a function stand for a piece: the file of a button without data is
+ * a function (called with a look) and also the button itself. `render`
+ * is asked for the piece when the message is built.
+ */
+export function pieceFunction(target, render) {
+    Object.defineProperty(target, INSTANCE, { value: true });
+    Object.defineProperty(target, 'kind', { get: () => render().kind });
+    Object.defineProperty(target, 'raw', { get: () => render().raw });
+    return target;
+}
+/** Whether a value is a piece made by the framework. */
+export function isPiece(value) {
+    return ((typeof value === 'object' || typeof value === 'function') &&
+        value !== null &&
+        value[INSTANCE] === true);
+}
+/** What a piece is and how it is sent. Throws on anything else. */
+export function renderedOf(value, where) {
+    if (!isPiece(value)) {
+        throw new TypeError(`${where} is not a component made by ChapterJS, got ${value === null ? 'null' : typeof value === 'object' && 'custom_id' in value ? 'an object with a custom_id' : typeof value}. Use the buttons, menus and forms declared with button(), select() and modal(), and row(), text(), section(), container()... from 'chapterjs'. Components are never written as JSON.`);
+    }
+    const { kind, raw } = value;
+    return { kind, raw };
+}
+/**
+ * An emoji as a component takes it: a standard one (`'👍'`), a custom one as
+ * Discord writes it (`'<:name:id>'`, `'<a:name:id>'`) or one of
+ * `guild.emojis`.
+ */
+export function emojiOf(input, what) {
+    if (typeof input !== 'string') {
+        const id = input.id ?? null;
+        const name = input.name ?? null;
+        if (!id && !name) {
+            throw new TypeError(`The emoji of ${what} has no name and no id.`);
+        }
+        return {
+            ...(id ? { id } : {}),
+            ...(name ? { name } : {}),
+            ...(input.animated ? { animated: true } : {}),
+        };
+    }
+    const text = input.trim();
+    const custom = /^<(a?):(\w+):(\d+)>$/.exec(text);
+    if (custom) {
+        return {
+            id: custom[3],
+            name: custom[2],
+            ...(custom[1] ? { animated: true } : {}),
+        };
+    }
+    if (text === '') {
+        throw new TypeError(`The emoji of ${what} is empty: pass one like "👍", or a custom one like "<:name:id>".`);
+    }
+    return { name: text };
+}