chapterjs 0.1.2 → 0.1.4

package/dist/commands/command.d.ts

@@ -0,0 +1,346 @@
+import type { PermissionName } from '../discord/permissions.js';
+import type { ChannelType } from '../discord/types/channel.js';
+import type { Locale } from '../discord/types/common.js';
+import type { Channel, DMChannel, GuildTextBasedChannel } from '../structures/channel.js';
+import type { Guild } from '../structures/guild.js';
+import type { DmCommandInteraction, GuildCommandInteraction, PrivateCommandInteraction } from '../structures/interaction.js';
+import type { GuildMember } from '../structures/member.js';
+import type { Attachment } from '../structures/message.js';
+import type { Role } from '../structures/role.js';
+import type { User } from '../structures/user.js';
+import type { TranslationContext } from '../messages/messages.js';
+interface OptionBase {
+    /**
+     * What the option is for, shown under its name (1-100 characters). Here
+     * when the command has its `description` here; otherwise in the default
+     * language file of `src/messages/`.
+     */
+    description?: string;
+    /** Whether the user must fill it in. By default it is optional. */
+    required?: boolean;
+}
+/** A text the user types, or picks among `choices`. */
+export interface StringOption extends OptionBase {
+    /** The kind of option: a text. */
+    type: 'string';
+    /**
+     * The only values the user can pick (25 at most): a list, or an object
+     * whose keys are what the user sees and values what your code receives.
+     */
+    choices?: readonly string[] | Readonly<Record<string, string>>;
+    /** The shortest text accepted, in characters (0 to 6000). */
+    minLength?: number;
+    /** The longest text accepted, in characters (1 to 6000). */
+    maxLength?: number;
+}
+/** A whole number (`integer`) or any number (`number`). */
+export interface NumberOption extends OptionBase {
+    /** The kind of option: a whole number, or any number. */
+    type: 'integer' | 'number';
+    /**
+     * The only values the user can pick (25 at most): a list, or an object
+     * whose keys are what the user sees and values what your code receives.
+     */
+    choices?: readonly number[] | Readonly<Record<string, number>>;
+    /** The smallest value accepted. */
+    min?: number;
+    /** The largest value accepted. */
+    max?: number;
+}
+/** A channel the user picks. */
+export interface ChannelOption extends OptionBase {
+    /** The kind of option: a channel. */
+    type: 'channel';
+    /** The kinds of channels that can be picked. By default, all of them. */
+    channelTypes?: readonly ChannelType[];
+}
+/** True or false, a user, a role, a user or a role, or a file. */
+export interface SimpleOption extends OptionBase {
+    /** The kind of option: what the user picks. */
+    type: 'boolean' | 'user' | 'role' | 'mentionable' | 'attachment';
+}
+/** One option of a command. */
+export type CommandOption = StringOption | NumberOption | ChannelOption | SimpleOption;
+/** The options of a command, by name. */
+export type CommandOptions = Readonly<Record<string, CommandOption>>;
+/** What `run` receives for an option of each type. */
+interface OptionValues {
+    string: string;
+    integer: number;
+    number: number;
+    boolean: boolean;
+    user: User;
+    role: Role;
+    channel: Channel;
+    mentionable: User | Role;
+    attachment: Attachment;
+}
+type ValueOf<Option extends CommandOption> = Option extends {
+    choices: readonly (infer Choice)[];
+} ? Choice : Option extends {
+    choices: Readonly<Record<string, infer Choice>>;
+} ? Choice : OptionValues[Option['type']];
+/**
+ * The values of the options, typed from their declaration: a required
+ * option is always there, an optional one may be `undefined`.
+ */
+export type OptionValuesOf<Options extends CommandOptions> = {
+    [Name in keyof Options]: Options[Name] extends {
+        required: true;
+    } ? ValueOf<Options[Name]> : ValueOf<Options[Name]> | undefined;
+};
+/**
+ * The options as the person has filled them in so far, while they type in
+ * one of them: every option may be missing, a `user`, `role`, `channel`,
+ * `mentionable` or `attachment` option is its id.
+ */
+export type OptionsSoFar<Options extends CommandOptions> = {
+    readonly [Name in keyof Options]?: Options[Name] extends {
+        type: 'user' | 'role' | 'channel' | 'mentionable' | 'attachment';
+    } ? string : ValueOf<Options[Name]>;
+};
+/**
+ * One suggestion for an option: a value, shown as is, or `{ name, value }`
+ * to show a text (1-100 characters) and receive another value. The value
+ * is a text (100 characters at most) for a `string` option, a number for
+ * an `integer` or `number` option.
+ */
+export type Suggestion<Value extends string | number = string | number> = Value | {
+    /** What the person sees in the list (1-100 characters). */
+    readonly name: string;
+    /** What your `run` receives when they pick it. */
+    readonly value: Value;
+};
+/** The place an `autocomplete` function receives, following `where`. */
+type AutocompletePlace<Where extends CommandWhere> = Where extends 'guild' ? Omit<CommandInGuild, 'interaction'> : Where extends 'dm' ? Omit<CommandInDm, 'interaction'> : Omit<CommandInGuild, 'interaction'> | Omit<CommandInPrivate, 'interaction'>;
+/**
+ * What an `autocomplete` function receives, each time the person types in
+ * its option. Nothing of it can be answered: the suggestions are what the
+ * function returns.
+ */
+export type AutocompleteContext<Value extends string | number | undefined = string | number | undefined, Options extends CommandOptions = CommandOptions, Where extends CommandWhere = CommandWhere> = {
+    /**
+     * What the person has typed so far in the option: a text, maybe empty,
+     * for a `string` option; for an `integer` or `number` option, a number,
+     * or `undefined` while what they typed is not one yet.
+     */
+    value: Value;
+    /** What the person has filled in so far, this option included. */
+    options: OptionsSoFar<Options>;
+    /** Who is typing. */
+    user: User;
+    /** The language of the person: suggest in it when you can. */
+    locale: Locale;
+} & TranslationContext & AutocompletePlace<Where>;
+/** What the person types in an option, as an `autocomplete` function gets it. */
+type AutocompleteValueOf<Option extends CommandOption> = Option extends {
+    type: 'string';
+} ? string : number | undefined;
+/** The names of the options that can have suggestions. */
+type Suggestable<Options extends CommandOptions> = {
+    [Name in keyof Options]: Options[Name] extends {
+        type: 'string' | 'integer' | 'number';
+    } ? Options[Name] extends {
+        choices: unknown;
+    } ? never : Name : never;
+}[keyof Options];
+/**
+ * The `autocomplete` of a command: one function per option whose
+ * suggestions come from your bot while the person types, by the name of
+ * the option. Only a `string`, `integer` or `number` option without
+ * `choices` can have one. The function returns the suggestions (25 at
+ * most, Discord shows them in that order), or a promise of them: Discord
+ * waits 3 seconds. The person may still type something else.
+ * @see https://docs.discord.com/developers/interactions/application-commands#autocomplete
+ */
+export type CommandAutocomplete<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = CommandWhere> = [Suggestable<Options>] extends [never] ? {
+    readonly [name: string]: 'No option of this command can have suggestions: only a string, integer or number option without choices can.';
+} : {
+    readonly [Name in Suggestable<Options>]?: (context: AutocompleteContext<AutocompleteValueOf<Options[Name]>, Options, Where>) => readonly Suggestion<SuggestionValueOf<Options[Name]>>[] | Promise<readonly Suggestion<SuggestionValueOf<Options[Name]>>[]>;
+};
+/** The value a suggestion carries: a text or a number, like the option. */
+type SuggestionValueOf<Option extends CommandOption> = Option extends {
+    type: 'string';
+} ? string : number;
+/** What a choice of an option is called in translations. */
+type ChoiceKeys<Option extends CommandOption> = Option extends {
+    choices: readonly (infer Choice extends string | number)[];
+} ? `${Choice}` : Option extends {
+    choices: Readonly<Record<infer Label, unknown>>;
+} ? Label & string : never;
+/** The translation of one option. Everything is optional. */
+export interface OptionTranslation<Option extends CommandOption = CommandOption> {
+    /** The name of the option in that language (same rules as a name). */
+    name?: string;
+    /** The description of the option in that language (1-100 characters). */
+    description?: string;
+    /**
+     * What each choice is called in that language. The keys are the choices
+     * as declared: the values of a list, or the keys of an object.
+     */
+    choices?: {
+        readonly [Choice in ChoiceKeys<Option>]?: string;
+    };
+}
+/**
+ * The translation of a command in one language. Everything is optional:
+ * what is not translated is shown as declared.
+ */
+export interface CommandTranslation<Options extends CommandOptions = CommandOptions> {
+    /** The name of the command in that language (same rules as a name). */
+    name?: string;
+    /** The description of the command in that language (1-100 characters). */
+    description?: string;
+    /** The translation of each option, by the name declared in `options`. */
+    options?: {
+        readonly [Name in keyof Options]?: OptionTranslation<Options[Name]>;
+    };
+}
+/** The translations of a command, by language. */
+export type CommandLocales<Options extends CommandOptions = CommandOptions> = {
+    readonly [Language in Locale]?: CommandTranslation<Options>;
+};
+/**
+ * Where a command can be used: in servers (`'guild'`), in private messages
+ * with the bot (`'dm'`), or in both.
+ * @see https://docs.discord.com/developers/interactions/application-commands#interaction-contexts
+ */
+export type CommandWhere = 'guild' | 'dm' | 'both';
+/**
+ * A duration, as a number and a unit: `s`, `m`, `h` or `d`, like `'30s'`,
+ * `'10m'`, `'2h'`, `'1d'`. Several parts add up: `'1h30m'`.
+ */
+export type Duration = `${number}${'s' | 'm' | 'h' | 'd'}${string}`;
+/**
+ * How long to wait before the command can be used again: a duration, for
+ * each person; or one per place, each optional: `user` for each person,
+ * `channel` for each channel, `guild` for each server (not for a command
+ * of private messages). Someone who uses it too soon gets a private
+ * answer saying when they can, and `run` does not run.
+ */
+export type Cooldown = Duration | {
+    /** Each person waits this long between two uses, wherever they are. */
+    readonly user?: Duration;
+    /** Each channel waits this long, whoever used it. */
+    readonly channel?: Duration;
+    /** Each server waits this long, whoever used it, wherever. */
+    readonly guild?: Duration;
+};
+/** What a command used in a server receives about where it was used. */
+export interface CommandInGuild {
+    /** The use of the command: what to answer with. */
+    interaction: GuildCommandInteraction;
+    /** The server the command was used in. */
+    guild: Guild;
+    /** Who used the command, as a member of the server. */
+    member: GuildMember;
+    /** The channel the command was used in. */
+    channel: GuildTextBasedChannel;
+}
+/**
+ * What a command that works in both places receives when it is used in a
+ * private message: `guild` is `null`, and checking it tells the rest.
+ */
+export interface CommandInPrivate {
+    /** The use of the command: what to answer with. */
+    interaction: PrivateCommandInteraction;
+    /** No server: the command was used in a private message. */
+    guild: null;
+    /** No member: the person is `user`. */
+    member: null;
+    /** The private conversation the command was used in. */
+    channel: DMChannel;
+}
+/** What a command only used in private messages receives: no server. */
+export interface CommandInDm {
+    /** The use of the command: what to answer with. */
+    interaction: DmCommandInteraction;
+    /** The private conversation the command was used in. */
+    channel: DMChannel;
+}
+/**
+ * What the `run` function of a command receives. It follows `where`: in a
+ * server, the server, the member and the channel are there; in private
+ * messages they do not exist; in both, `if (guild)` tells which one it is,
+ * for everything at once.
+ */
+export type CommandContext<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = 'guild'> = {
+    /** What the user filled in. */
+    options: OptionValuesOf<Options>;
+    /** Who used the command. */
+    user: User;
+} & TranslationContext & (Where extends 'guild' ? CommandInGuild : Where extends 'dm' ? CommandInDm : CommandInGuild | CommandInPrivate);
+/** What a command file gives to `command()`: what the command is and does. */
+export interface CommandConfig<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = 'guild'> {
+    /**
+     * What the command does, shown under its name (1-100 characters). Here,
+     * with `locales` for its translations; or left out, and every text of
+     * the command (description, options, their choices, translations) comes
+     * from the language files of `src/messages/`. One or the other.
+     */
+    description?: string;
+    /** What the user can fill in (25 options at most). */
+    options?: Options;
+    /**
+     * The command in other languages: Discord shows each person the names
+     * and descriptions of their language. Your code always receives the
+     * names declared above, whatever the language.
+     * @see https://docs.discord.com/developers/interactions/application-commands#localization
+     */
+    locales?: CommandLocales<NoInfer<Options>>;
+    /**
+     * Suggestions that come from your bot while the person types, for the
+     * options named here (a `string`, `integer` or `number` option without
+     * `choices`): each function receives what they typed and returns the
+     * suggestions. The person may still type something else.
+     */
+    autocomplete?: CommandAutocomplete<NoInfer<Options>, NoInfer<Where>>;
+    /**
+     * The permissions a member needs to use the command. Server admins can
+     * change who sees it in the server settings.
+     */
+    permissions?: readonly PermissionName[];
+    /**
+     * Where the command can be used: `'guild'` (in servers, the default),
+     * `'dm'` (in private messages with the bot) or `'both'`. What `run`
+     * receives follows it.
+     */
+    where?: Where;
+    /** Only show the command in age-restricted channels. */
+    nsfw?: boolean;
+    /** Make the answers of the command only visible to who used it. */
+    ephemeral?: boolean;
+    /**
+     * How long to wait before the command can be used again: `'10s'` for
+     * each person, or `{ user, channel, guild }` for each place. Someone who
+     * uses it too soon gets a private answer saying when they can.
+     */
+    cooldown?: Cooldown;
+    /** What to do when someone uses the command. */
+    run: (context: CommandContext<Options, Where>) => unknown;
+}
+/** What `command()` returns: the default export of a command file. */
+export interface CommandFile<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = CommandWhere> {
+    /** What the file gave to `command()`, not checked yet. */
+    readonly config: CommandConfig<Options, Where>;
+}
+/**
+ * Declares a slash command. Export the result as the default export of a
+ * file of `src/commands/`: the path of the file is the name of the command
+ * (`src/commands/mod/ban.ts` is `/mod ban`).
+ *
+ * ```ts
+ * import { command } from 'chapterjs';
+ *
+ * export default command({
+ *   description: 'Replies with Pong!',
+ *   async run({ interaction }) {
+ *     await interaction.reply('Pong!');
+ *   },
+ * });
+ * ```
+ */
+export declare function command<const Options extends CommandOptions = {}, const Where extends CommandWhere = 'guild'>(config: CommandConfig<Options, Where>): CommandFile<Options, Where>;
+/** Whether a value was made by `command()`. */
+export declare function isCommandFile(value: unknown): value is CommandFile;
+export {};

package/dist/commands/command.js

@@ -0,0 +1,28 @@
+// `command()`, as user files import it from 'chapterjs', and the types that
+// make the options a command declares typed in its `run` function.
+const BRAND = Symbol.for('chapterjs.command');
+/**
+ * Declares a slash command. Export the result as the default export of a
+ * file of `src/commands/`: the path of the file is the name of the command
+ * (`src/commands/mod/ban.ts` is `/mod ban`).
+ *
+ * ```ts
+ * import { command } from 'chapterjs';
+ *
+ * export default command({
+ *   description: 'Replies with Pong!',
+ *   async run({ interaction }) {
+ *     await interaction.reply('Pong!');
+ *   },
+ * });
+ * ```
+ */
+export function command(config) {
+    return Object.freeze({ [BRAND]: true, config });
+}
+/** Whether a value was made by `command()`. */
+export function isCommandFile(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[BRAND] === true);
+}

package/dist/commands/convention.d.ts

@@ -0,0 +1,64 @@
+import { Locale } from '../discord/types/common.js';
+import { type CooldownLimits } from '../interactions/cooldown.js';
+import type { Convention } from '../loader/loader.js';
+import { type AutocompleteContext, type CommandContext, type CommandOption, type CommandWhere, type Suggestion } from './command.js';
+/** A name or a description in other languages, as Discord takes them. */
+export type Localizations = Readonly<Partial<Record<Locale, string>>>;
+/** The translations of one option, checked. */
+export interface OptionLocales {
+    readonly names: Localizations;
+    readonly descriptions: Localizations;
+    /** For each choice (by its default name), its name in other languages. */
+    readonly choices: Readonly<Record<string, Localizations>>;
+}
+/** An option, checked, with the description it has so far. */
+export type LoadedOption = CommandOption & {
+    name: string;
+    description: string;
+};
+/** An `autocomplete` function of a file, as the router runs it. */
+export type AutocompleteFunction = (context: AutocompleteContext) => readonly Suggestion[] | Promise<readonly Suggestion[]>;
+/** A command file, checked: what the rest of the feature works with. */
+export interface LoadedCommand {
+    /** The name and description of the command in other languages. */
+    readonly names: Localizations;
+    readonly descriptions: Localizations;
+    /** The translations of the options, by option name. */
+    readonly optionLocales: Readonly<Record<string, OptionLocales>>;
+    /** `['mod', 'ban']` for `src/commands/mod/ban.ts`: `/mod ban`. */
+    readonly path: readonly string[];
+    /**
+     * Whether the file gives its own texts (`description`, `locales`). When
+     * it does not, the language files of `src/messages/` do: `description`
+     * and the descriptions of the options are empty until `project.ts`
+     * fills them in from the default language.
+     */
+    readonly described: boolean;
+    readonly description: string;
+    /** The options, required ones first as Discord wants them. */
+    readonly options: readonly LoadedOption[];
+    /** The permissions needed, as bits. */
+    readonly permissions: bigint;
+    /** Where it can be used; in servers when the file does not say. */
+    readonly where: CommandWhere;
+    readonly nsfw: boolean;
+    readonly ephemeral: boolean;
+    /** How long each person, channel and server waits between two uses. */
+    readonly cooldown: CooldownLimits;
+    /** The functions giving suggestions, by the name of their option. */
+    readonly autocomplete: Readonly<Record<string, AutocompleteFunction>>;
+    readonly run: (context: CommandContext) => unknown;
+}
+/** Checks `locales` and returns it as the dictionaries Discord takes. */
+export declare function checkLocales(locales: unknown, options: readonly LoadedOption[]): {
+    names: Localizations;
+    descriptions: Localizations;
+    optionLocales: Record<string, OptionLocales>;
+};
+/**
+ * `src/commands/`: each file is a slash command, named after its path.
+ * One folder makes a command with subcommands (`mod/ban.ts` is `/mod ban`),
+ * two make a group (`mod/roles/add.ts` is `/mod roles add`): Discord allows
+ * nothing deeper.
+ */
+export declare const commandsConvention: Convention<LoadedCommand>;