chapterjs 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,18 +1,55 @@
-export type { Client } from './discord/client.js';
-export type { Activity, Presence, PresenceStatus } from './discord/presence.js';
-export { definePresence, refreshPresence, type PresenceContext, type PresenceDefinition, type PresenceFunction, type PresenceInput, type PresenceSourceFunction, type PresenceStep, type PresenceWatchCleanup, } from './presence.js';
-export type { EventData, EventName } from './discord/events.js';
-export type * from './discord/types.js';
-export type { EventContext } from './context.js';
-export { defineEvent, type Event, type EventDefinition, type EventHandler, type IntentName, } from './events.js';
-export { DiscordAPIError, type FileUpload, type RequestOptions, } from './discord/rest.js';
-export { Channel, ChannelType, type CreateThreadOptions, type FetchMessagesOptions, } from './structures/Channel.js';
-export { type BanOptions, Guild } from './structures/Guild.js';
-export { type AutocompleteChoice, Interaction, type InteractionReplyOptions, InteractionType, type ModalOptions, } from './structures/Interaction.js';
-export { Member } from './structures/Member.js';
-export { type EmojiResolvable, Message } from './structures/Message.js';
-export { Reaction } from './structures/Reaction.js';
-export { Role } from './structures/Role.js';
-export { User } from './structures/User.js';
-export type { AllowedMentions, ImageOptions, MessageOptions, ReplyOptions, } from './structures/utils.js';
-export { type ButtonAppearance, type ButtonClass, type ButtonComponent, type ButtonContext, type ButtonDefinition, type ButtonOptions, type ButtonStyle, type ComponentData, type ComponentInput, defineButton, } from './components.js';
+export { command } from './commands/command.js';
+export type { AutocompleteContext, ChannelOption, CommandAutocomplete, CommandConfig, CommandContext, CommandInDm, CommandInGuild, CommandInPrivate, CommandWhere, CommandFile, CommandLocales, CommandOption, CommandOptions, CommandTranslation, Cooldown, Duration, NumberOption, OptionsSoFar, OptionTranslation, OptionValuesOf, SimpleOption, StringOption, Suggestion, } from './commands/command.js';
+export type { CommandInteraction, ComponentInteraction, DmCommandInteraction, GuildCommandInteraction, PrivateCommandInteraction, Interaction, InteractionReply, InteractionReplyOptions, ModalInteraction, } from './structures/interaction.js';
+export type { DynamicText, TextContext } from './components/component.js';
+export { button } from './components/button.js';
+export type { ButtonConfig, ButtonContext, ButtonFile, ButtonLook, ButtonStyleName, } from './components/button.js';
+export { select } from './components/select.js';
+export type { EntitySelectConfig, EntitySelectType, SelectConfig, SelectContext, SelectFile, SelectInstanceOptions, SelectLook, SelectType, StringSelectConfig, } from './components/select.js';
+export { modal } from './components/modal.js';
+export type { CheckboxField, CheckboxesField, EntityField, FieldValue, FieldValuesOf, FilesField, ModalConfig, ModalContext, ModalField, ModalFields, ModalFile, ModalInstanceOptions, ModalPrefill, NoteField, RadioField, SelectField, TextField, } from './components/modal.js';
+export { embed } from './components/embed.js';
+export type { EmbedFile } from './components/embed.js';
+export type { ComponentWhere, ComponentWho, InDm, InGuild, InPrivate, InteractiveConfig, InteractiveContext, PlaceInDm, PlaceInGuild, PlaceInPrivate, PlaceOf, } from './components/component.js';
+export type { DataField, DataInputOf, DataKind, DataShape, DataValuesOf, } from './components/custom-id.js';
+export type { OptionValue, RichOption, SelectOptions, } from './components/options.js';
+export { container, file, gallery, linkButton, premiumButton, row, section, separator, text, thumbnail, } from './components/layout.js';
+export type { ContainerOptions, LinkButtonOptions, MediaOptions, SeparatorOptions, } from './components/layout.js';
+export type { ActionRowComponent, ButtonComponent, ContainerChild, ContainerComponent, FileComponent, GalleryComponent, MessageComponent, ModalComponent, Piece, SectionComponent, SelectComponent, SeparatorComponent, TextComponent, ThumbnailComponent, } from './components/instance.js';
+export type { ContextOf, EventWhere, WhereEventOptions, EventContexts, EventFile, EventName, EventOptions, MessageEventOptions, ReactionEventOptions, } from './events/registry.js';
+export type { CategoryChannel, Channel, DMChannel, FetchMessagesOptions, ForumChannel, ForumPostOptions, ForumTag, GuildChannel, GuildChannelEditOptions, InviteCreateOptions, PermissionOverwrite, TextBasedChannel, GuildTextBasedChannel, TextChannel, ThreadChannel, ThreadCreateOptions, ThreadEditOptions, ThreadMember, VoiceChannel, } from './structures/channel.js';
+export type { GuildEmoji } from './structures/emoji.js';
+export type { AuditLog, AuditLogEntry, AutoModerationRule, Ban, ChannelCreateOptions, Guild, GuildEditOptions, RoleCreateOptions, ScheduledEvent, Sticker, VoiceState, } from './structures/guild.js';
+export type { Invite } from './structures/invite.js';
+export type { BanOptions, GuildMember, MemberEditOptions, } from './structures/member.js';
+export type { Attachment, EmojiInput, DmMessage, GuildMessage, MemberMessage, Message, PrivateMessage, MessageFlagName, Reaction, ReactionEmoji, } from './structures/message.js';
+export { language } from './messages/messages.js';
+export type { CommandsTranslations, FrameworkTexts, LanguageConfig, LanguageFile, MessagesOf, MessageText, MessageTexts, PluralText, ProjectCommands, ParamsArgs, ParamsOf, Placeholders, ProjectLocale, ProjectLocales, LocaleGiven, ProjectMessages, TranslationContext, Translator, } from './messages/messages.js';
+export { presence } from './presence/presence.js';
+export type { Activity, ActivityKind, PlainActivity, PresenceConfig, PresenceFile, PresenceStatusName, StreamingActivity, } from './presence/presence.js';
+export { task } from './tasks/task.js';
+export type { CronTaskConfig, EveryTaskConfig, TaskConfig, TaskContext, TaskFile, } from './tasks/task.js';
+export type { AssetFile, AssetOptions } from './assets/asset.js';
+export type { AllowedMentions, Embed, FileInput, MessageEditOptions, MessageInput, MessageOptions, PollInput, } from './structures/payload.js';
+export type { Role, RoleEditOptions } from './structures/role.js';
+export type { User, UserFlagName, UserPresence } from './structures/user.js';
+export type { Webhook, WebhookMessageOptions } from './structures/webhook.js';
+export type { JoinOptions, VoiceConnection } from './voice/connection.js';
+export type { AudioSource } from './voice/source.js';
+export { DiscordApiError, DiscordUnavailableError, InvalidTokenError, } from './rest/errors.js';
+export type { DiscordFieldError } from './rest/errors.js';
+export { Permissions } from './discord/permissions.js';
+export type { PermissionName, PermissionResolvable, } from './discord/permissions.js';
+export { PermissionFlags } from './discord/types/permissions.js';
+export { channelMention, commandMention, emojiMention, GuildNavigation, roleMention, timestamp, TimestampStyle, userMention, } from './discord/formatting.js';
+export type { ImageFormat, ImageOptions, ImageSize } from './discord/cdn.js';
+export { isSnowflake, snowflakeFromTimestamp, snowflakeTimestamp, } from './discord/snowflake.js';
+export { ChannelType, ForumLayoutType, ForumSortOrderType, VideoQualityMode, } from './discord/types/channel.js';
+export { Locale } from './discord/types/common.js';
+export type { Snowflake } from './discord/types/common.js';
+export { ButtonStyle, ComponentType, TextInputStyle, } from './discord/types/component.js';
+export { DefaultMessageNotificationLevel, ExplicitContentFilterLevel, PremiumTier, VerificationLevel, } from './discord/types/guild.js';
+export type { GuildFeature } from './discord/types/guild.js';
+export { AuditLogEvent } from './discord/types/audit-log.js';
+export { MessageFlags, MessageType } from './discord/types/message.js';
+export { UserFlags } from './discord/types/user.js';

package/dist/index.js

@@ -1,12 +1,38 @@
-export { definePresence, refreshPresence, } from './presence.js';
-export { defineEvent, } from './events.js';
-export { DiscordAPIError, } from './discord/rest.js';
-export { Channel, ChannelType, } from './structures/Channel.js';
-export { Guild } from './structures/Guild.js';
-export { Interaction, InteractionType, } from './structures/Interaction.js';
-export { Member } from './structures/Member.js';
-export { Message } from './structures/Message.js';
-export { Reaction } from './structures/Reaction.js';
-export { Role } from './structures/Role.js';
-export { User } from './structures/User.js';
-export { defineButton, } from './components.js';
+// The public types of ChapterJS, and everything in its API that is the same
+// wherever it is imported. What depends on the folder of the importing file
+// (`event`...) is exported at runtime by `main.ts`, and typed for each
+// folder of a project by the generated `.chapterjs/` (see
+// `loader/generated.ts`): declaring it here too would make editors offer
+// two imports of the same name.
+//
+// The public API of ChapterJS. User code gets structures from the framework
+// (in events, commands...) and never creates them: classes are exported as
+// types only, and nothing here lets user code connect to Discord or send
+// requests by itself.
+// Slash commands: what the files of src/commands/ are written with.
+export { command } from './commands/command.js';
+export { button } from './components/button.js';
+export { select } from './components/select.js';
+export { modal } from './components/modal.js';
+export { embed } from './components/embed.js';
+export { container, file, gallery, linkButton, premiumButton, row, section, separator, text, thumbnail, } from './components/layout.js';
+// Tasks: what the files of src/tasks/ are written with.
+export { language } from './messages/messages.js';
+export { presence } from './presence/presence.js';
+export { task } from './tasks/task.js';
+// Errors handlers can catch.
+export { DiscordApiError, DiscordUnavailableError, InvalidTokenError, } from './rest/errors.js';
+// Permissions.
+export { Permissions } from './discord/permissions.js';
+export { PermissionFlags } from './discord/types/permissions.js';
+// Helpers to write messages.
+export { channelMention, commandMention, emojiMention, GuildNavigation, roleMention, timestamp, TimestampStyle, userMention, } from './discord/formatting.js';
+export { isSnowflake, snowflakeFromTimestamp, snowflakeTimestamp, } from './discord/snowflake.js';
+// The values Discord uses, by name.
+export { ChannelType, ForumLayoutType, ForumSortOrderType, VideoQualityMode, } from './discord/types/channel.js';
+export { Locale } from './discord/types/common.js';
+export { ButtonStyle, ComponentType, TextInputStyle, } from './discord/types/component.js';
+export { DefaultMessageNotificationLevel, ExplicitContentFilterLevel, PremiumTier, VerificationLevel, } from './discord/types/guild.js';
+export { AuditLogEvent } from './discord/types/audit-log.js';
+export { MessageFlags, MessageType } from './discord/types/message.js';
+export { UserFlags } from './discord/types/user.js';

package/dist/interactions/cooldown.d.ts

@@ -0,0 +1,33 @@
+/** What a cooldown applies to: the person, the channel or the server. */
+export type CooldownScope = 'user' | 'channel' | 'guild';
+export declare const COOLDOWN_SCOPES: readonly CooldownScope[];
+/** How long each scope waits, in milliseconds; `0` when it does not. */
+export type CooldownLimits = Readonly<Record<CooldownScope, number>>;
+/** No cooldown at all. */
+export declare const NO_COOLDOWN: CooldownLimits;
+/** Where the last uses are kept. */
+export interface CooldownStore {
+    /** When `key` may be used again, as a timestamp; `0` when it may now. */
+    until(key: string, now: number): number;
+    /** Remembers that `key` may not be used again before `until`. */
+    set(key: string, until: number): void;
+}
+/**
+ * The default store: a `Map` in the memory of the process. It forgets
+ * what expired on its own, so it never grows with the uses of the past.
+ */
+export declare class MemoryCooldowns implements CooldownStore {
+    #private;
+    until(key: string, now: number): number;
+    set(key: string, until: number): void;
+    /** How many keys are remembered. */
+    get size(): number;
+}
+/** The ids a use is counted against, when they exist. */
+export type CooldownIds = Readonly<Partial<Record<CooldownScope, string>>>;
+/**
+ * Whether `name` may be used now by these ids, given its limits. Returns
+ * `0` and counts the use, or the time it may be used again (the latest
+ * of the scopes still waiting) and counts nothing.
+ */
+export declare function checkCooldown(store: CooldownStore, name: string, limits: CooldownLimits, ids: CooldownIds, now?: number): number;

package/dist/interactions/cooldown.js

@@ -0,0 +1,74 @@
+// Cooldowns: refusing something to a person, a channel or a server that
+// used it a moment ago. Written once for every interaction that can have
+// one (a command today). Where the last uses are kept is behind
+// `CooldownStore`, with a store in memory as default: one shared between
+// processes or machines is another implementation, and nothing else.
+export const COOLDOWN_SCOPES = [
+    'user',
+    'channel',
+    'guild',
+];
+/** No cooldown at all. */
+export const NO_COOLDOWN = Object.freeze({
+    user: 0,
+    channel: 0,
+    guild: 0,
+});
+/**
+ * The default store: a `Map` in the memory of the process. It forgets
+ * what expired on its own, so it never grows with the uses of the past.
+ */
+export class MemoryCooldowns {
+    #until = new Map();
+    #sweepAt = 1000;
+    until(key, now) {
+        const until = this.#until.get(key);
+        if (until === undefined)
+            return 0;
+        if (until <= now) {
+            this.#until.delete(key);
+            return 0;
+        }
+        return until;
+    }
+    set(key, until) {
+        this.#until.set(key, until);
+        if (this.#until.size >= this.#sweepAt)
+            this.#sweep(Date.now());
+    }
+    /** How many keys are remembered. */
+    get size() {
+        return this.#until.size;
+    }
+    /** Forgets what expired, and sweeps again when the rest doubled. */
+    #sweep(now) {
+        for (const [key, until] of this.#until) {
+            if (until <= now)
+                this.#until.delete(key);
+        }
+        this.#sweepAt = Math.max(1000, this.#until.size * 2);
+    }
+}
+/**
+ * Whether `name` may be used now by these ids, given its limits. Returns
+ * `0` and counts the use, or the time it may be used again (the latest
+ * of the scopes still waiting) and counts nothing.
+ */
+export function checkCooldown(store, name, limits, ids, now = Date.now()) {
+    const keys = [];
+    let until = 0;
+    for (const scope of COOLDOWN_SCOPES) {
+        const limit = limits[scope];
+        const id = ids[scope];
+        if (limit <= 0 || id === undefined)
+            continue;
+        const key = `${name}\0${scope}\0${id}`;
+        until = Math.max(until, store.until(key, now));
+        keys.push([key, now + limit]);
+    }
+    if (until > 0)
+        return until;
+    for (const [key, expires] of keys)
+        store.set(key, expires);
+    return 0;
+}

package/dist/interactions/dispatch.d.ts

@@ -0,0 +1,91 @@
+import type { RawGuildMember } from '../discord/types/guild.js';
+import type { RawInteraction } from '../discord/types/interaction.js';
+import type { RawUser } from '../discord/types/user.js';
+import { type FrameworkKey, type What } from '../messages/phrases.js';
+import type { TextBasedChannel } from '../structures/channel.js';
+import type { Context } from '../structures/context.js';
+import type { Guild } from '../structures/guild.js';
+import { type Interaction } from '../structures/interaction.js';
+import type { GuildMember } from '../structures/member.js';
+import type { User } from '../structures/user.js';
+/** Where something can be used: the same word for commands and components. */
+export type Where = 'guild' | 'dm' | 'both';
+/** What the developer is told. */
+export interface Reporter {
+    /** A `run` threw: reported with the file it comes from. */
+    onError: (file: string, error: unknown) => void;
+    /** Something the developer should know, that is not an error of theirs. */
+    onWarning: (file: string, message: string) => void;
+    /**
+     * After how long without an answer the framework defers, in milliseconds.
+     * Discord gives 3 seconds: the default leaves room for the request.
+     */
+    deferAfter?: number;
+}
+/** Who did it, as Discord sent it: the member in a server, the user elsewhere. */
+export declare function authorOf(raw: RawInteraction): {
+    user: RawUser;
+    member: RawGuildMember | undefined;
+} | null;
+/** Where an interaction happened, as its `run` receives it. */
+export interface Place {
+    user: User;
+    guild: Guild | null;
+    member: GuildMember | null;
+    channel: TextBasedChannel;
+    /** In a server the bot is in, with the member. */
+    inGuild: boolean;
+}
+export type Placed = {
+    place: Place;
+    refusal?: undefined;
+} | {
+    place?: undefined;
+    refusal: 'guildOnly' | 'dmOnly' | 'notHere';
+};
+/**
+ * Where the interaction was used, checked against where `what` works.
+ * Returns the place, or what to tell the person when it can't run there.
+ */
+export declare function resolvePlace(ctx: Context, raw: RawInteraction, user: User, rawMember: RawGuildMember | undefined, where: Where, warn: (message: string) => void): Placed;
+/** What `run` receives about the place, following `where`. */
+export declare function placeContext(place: Place, where: Where): Record<string, unknown>;
+/** A phrase of the framework, in the language of the person. */
+export declare function says(interaction: Interaction, key: FrameworkKey, params?: {
+    what?: What;
+    permissions?: string;
+    count?: number;
+    when?: string;
+}): string;
+/**
+ * Answers with a private message, in the language of the person, and
+ * never fails.
+ */
+export declare function refuse(interaction: Interaction, key: FrameworkKey, params?: {
+    what?: What;
+    permissions?: string;
+    count?: number;
+    when?: string;
+}): Promise<void>;
+export interface RunOptions {
+    interaction: Interaction;
+    /** The file the function comes from. */
+    file: string;
+    /** How the thing is named in messages to the developer: `/ping`, `buttons/ban`. */
+    name: string;
+    /** What it is, for the person: "command", "button", "menu", "form". */
+    what: What;
+    reporter: Reporter;
+    /** What to tell Discord when the answer takes long. */
+    defer: () => Promise<void>;
+    /** What to tell the developer when `run` finishes without answering. */
+    unanswered: string;
+    run: () => unknown;
+}
+/**
+ * Runs the function of an interaction. Discord wants an answer within 3
+ * seconds: when `run` takes longer, the framework says the answer is
+ * coming. When `run` throws, the person gets a plain answer and the
+ * developer the error with its file and line.
+ */
+export declare function runInteraction(options: RunOptions): void;

package/dist/interactions/dispatch.js

@@ -0,0 +1,110 @@
+// What every interaction shares, whatever runs for it (a command, a
+// button, a menu, a form): who did it and where, whether it is allowed
+// there, and how its function is run so that the person always gets an
+// answer and the developer always gets the error. Written once here;
+// `commands/router.ts` and `components/router.ts` add what is theirs.
+import { setTimeout as sleep } from 'node:timers/promises';
+import { phrase } from '../messages/phrases.js';
+import { DiscordApiError } from '../rest/errors.js';
+import { ctxOf } from '../structures/base.js';
+import { isUpdating } from '../structures/interaction.js';
+/** Who did it, as Discord sent it: the member in a server, the user elsewhere. */
+export function authorOf(raw) {
+    const user = raw.member?.user ?? raw.user;
+    return user ? { user, member: raw.member } : null;
+}
+/**
+ * Where the interaction was used, checked against where `what` works.
+ * Returns the place, or what to tell the person when it can't run there.
+ */
+export function resolvePlace(ctx, raw, user, rawMember, where, warn) {
+    // In a server Discord sends the member, in a private message the user.
+    const guild = raw.guild_id
+        ? (ctx.cache.guilds.get(raw.guild_id) ?? null)
+        : null;
+    const member = raw.guild_id && rawMember
+        ? ctx.entities.member(raw.guild_id, rawMember)
+        : null;
+    const inGuild = guild !== null && member !== null;
+    if (where === 'guild' && !inGuild) {
+        return { refusal: 'guildOnly' };
+    }
+    if (where === 'dm' && raw.guild_id) {
+        return { refusal: 'dmOnly' };
+    }
+    if (raw.guild_id && !inGuild) {
+        // A server the bot is not in: nothing of it is known.
+        return { refusal: 'notHere' };
+    }
+    // Discord sends the channel with the interaction: known without asking.
+    const channel = (raw.channel_id ? ctx.cache.channels.get(raw.channel_id) : undefined) ??
+        (raw.channel?.id
+            ? ctx.entities.channel(raw.channel, raw.guild_id)
+            : undefined);
+    if (!channel?.isTextBased() || (!inGuild && !channel.isDM())) {
+        warn(`was used in a channel the bot can't answer in (${channel ? `type ${channel.type}` : 'Discord did not say which'}): it did not run.`);
+        return { refusal: 'notHere' };
+    }
+    return { place: { user, guild, member, channel, inGuild } };
+}
+/** What `run` receives about the place, following `where`. */
+export function placeContext(place, where) {
+    // What a `run` receives follows where it works: nothing about a server
+    // exists for what only works in private messages.
+    return {
+        channel: place.channel,
+        ...(where === 'dm' ? {} : { guild: place.guild, member: place.member }),
+    };
+}
+/** A phrase of the framework, in the language of the person. */
+export function says(interaction, key, params) {
+    return phrase(ctxOf(interaction), interaction.locale, key, params);
+}
+/**
+ * Answers with a private message, in the language of the person, and
+ * never fails.
+ */
+export function refuse(interaction, key, params) {
+    return interaction
+        .reply({ content: says(interaction, key, params), ephemeral: true })
+        .then(() => { }, () => { });
+}
+/**
+ * Runs the function of an interaction. Discord wants an answer within 3
+ * seconds: when `run` takes longer, the framework says the answer is
+ * coming. When `run` throws, the person gets a plain answer and the
+ * developer the error with its file and line.
+ */
+export function runInteraction(options) {
+    const { interaction, file, name, reporter } = options;
+    const stop = new AbortController();
+    sleep(reporter.deferAfter ?? 2000, undefined, { signal: stop.signal })
+        .then(() => options.defer())
+        .catch(() => { });
+    new Promise(resolve => resolve(options.run()))
+        .then(() => {
+        if (!interaction.answered) {
+            reporter.onWarning(file, `${name} ${options.unanswered}`);
+        }
+    })
+        .catch((error) => {
+        reporter.onError(file, error);
+        // The person gets a plain answer, never the technical details.
+        const missingPermission = error instanceof DiscordApiError &&
+            (error.code === 50013 || error.code === 50001);
+        const content = missingPermission
+            ? says(interaction, 'missingPermission')
+            : says(interaction, 'failed', { what: options.what });
+        const tell = isUpdating(interaction)
+            ? // The pending answer is a change of a message: the bad news must
+                // not replace that message.
+                interaction.followUp({ content, ephemeral: true })
+            : interaction.deferred
+                ? interaction.edit(content)
+                : interaction.answered
+                    ? interaction.followUp({ content, ephemeral: true })
+                    : interaction.reply({ content, ephemeral: true });
+        tell.catch(() => { });
+    })
+        .finally(() => stop.abort());
+}

package/dist/loader/generated.d.ts

@@ -0,0 +1,37 @@
+/** A folder of user files in which 'chapterjs' has its own types. */
+export interface TypedFolder {
+    /** A unique name, used for file names: `events.memberJoin`. */
+    id: string;
+    /**
+     * The folder, from the project folder, with `/`. It may contain `**` to
+     * be found at any depth (inside `(group)` folders). It may also be one
+     * file (`src/messages/fr.ts`): a file whose 'chapterjs' is its own.
+     */
+    folder: string;
+    /**
+     * What the project of this folder includes on top of its declarations:
+     * `shared` (what every file of the project gets, the default) and/or
+     * `main` (what the files outside typed folders get). A folder whose
+     * files `shared` refers to (a language file, which types `t` for every
+     * other file) takes `main` alone: through `shared`, the other files of
+     * its family would be checked with its declarations.
+     */
+    includes?: readonly ('shared' | 'main')[];
+    /**
+     * The declarations 'chapterjs' has in this folder, on top of what the
+     * package exports. Written like a `.d.ts` that imports the package from
+     * `'#chapterjs'`.
+     */
+    declarations: string;
+}
+/**
+ * Writes the `.chapterjs/` folder of a project. A file whose content did
+ * not change is left alone, so editors don't reload for nothing; what an
+ * older version wrote and this one does not is removed. `shared` is what
+ * 'chapterjs' declares in every file of the project, whatever its folder:
+ * a `declare module 'chapterjs'` augmentation, importing the package from
+ * `'#chapterjs'` like the declarations of a `TypedFolder`. `main` is the
+ * same for the files outside typed folders only.
+ * @returns how many files were written
+ */
+export declare function writeGenerated(projectDir: string, folders: readonly TypedFolder[], shared?: string, main?: string): Promise<number>;

package/dist/loader/generated.js

@@ -0,0 +1,114 @@
+// The `.chapterjs/` folder of a project: what the framework writes so that
+// user files are typed from where they are, with nothing to write.
+//
+// A user file imports everything from 'chapterjs'. To give that import a
+// different type in each conventional folder (`event()` in
+// `src/events/memberJoin/` knows it receives a member), each such folder is
+// its own TypeScript project, in which 'chapterjs' resolves to a generated
+// declaration file: everything the package exports, plus what is specific
+// to the folder. The tsconfig of the user project only references this
+// folder; editors and `tsc -b` find the project of each file by themselves.
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HEADER = '// Written by ChapterJS: do not edit, it is overwritten.\n';
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** How a file of `.chapterjs/types/` imports the real package. */
+function packageSpecifier(projectDir) {
+    const installed = join(projectDir, 'node_modules', 'chapterjs');
+    const target = existsSync(installed)
+        ? installed
+        : // No node_modules (some package managers): where this code runs from.
+            fileURLToPath(new URL('../..', import.meta.url));
+    const path = relative(join(projectDir, '.chapterjs', 'types'), target);
+    return `${path.split(sep).join('/')}/dist/index.js`;
+}
+/** Every file of `.chapterjs/`, by its path inside it. */
+function generatedFiles(projectDir, folders, shared, main) {
+    const files = new Map();
+    const specifier = packageSpecifier(projectDir);
+    const types = (declarations) => `${HEADER}export * from '${specifier}';\n${declarations.replaceAll("'#chapterjs'", `'${specifier}'`)}`;
+    // The folder ignores itself: nothing to add to the project's .gitignore.
+    files.set('.gitignore', '*\n');
+    // What every file of the project gets, whatever its folder: written as
+    // an augmentation of 'chapterjs', so it adds to the package in the main
+    // project and to the generated types in the others, without a second
+    // copy of the package for editors to offer.
+    const everywhere = shared === '' ? [] : ['../types/shared.d.ts'];
+    if (shared !== '') {
+        files.set('types/shared.d.ts', `${HEADER}${shared.replaceAll("'#chapterjs'", `'${specifier}'`)}`);
+    }
+    // What only the files outside typed folders get, and the typed folders
+    // that ask for it (`includes`): the commands a language file may
+    // translate.
+    const mainOnly = main === '' ? [] : ['../types/main.d.ts'];
+    if (main !== '') {
+        files.set('types/main.d.ts', `${HEADER}${main.replaceAll("'#chapterjs'", `'${specifier}'`)}`);
+    }
+    // Files that are in no typed folder: 'chapterjs' is the package itself.
+    files.set('projects/main.json', json({
+        extends: '../../tsconfig.json',
+        include: ['../../src', ...everywhere, ...mainOnly],
+        exclude: folders.map(({ folder }) => `../../${folder}`),
+    }));
+    for (const { id, folder, declarations, includes } of folders) {
+        const more = (includes ?? ['shared']).flatMap(what => what === 'shared' ? everywhere : mainOnly);
+        files.set(`projects/${id}.json`, json({
+            extends: '../../tsconfig.json',
+            compilerOptions: { paths: { chapterjs: [`../types/${id}.d.ts`] } },
+            // The declaration file is listed too: a folder that does not exist
+            // yet is then a valid, empty project, typed as soon as it exists.
+            include: [`../../${folder}`, `../types/${id}.d.ts`, ...more],
+        }));
+        files.set(`types/${id}.d.ts`, types(declarations));
+    }
+    files.set('tsconfig.json', json({
+        files: [],
+        references: [
+            { path: './projects/main.json' },
+            ...folders.map(({ id }) => ({ path: `./projects/${id}.json` })),
+        ],
+    }));
+    return files;
+}
+/**
+ * Writes the `.chapterjs/` folder of a project. A file whose content did
+ * not change is left alone, so editors don't reload for nothing; what an
+ * older version wrote and this one does not is removed. `shared` is what
+ * 'chapterjs' declares in every file of the project, whatever its folder:
+ * a `declare module 'chapterjs'` augmentation, importing the package from
+ * `'#chapterjs'` like the declarations of a `TypedFolder`. `main` is the
+ * same for the files outside typed folders only.
+ * @returns how many files were written
+ */
+export async function writeGenerated(projectDir, folders, shared = '', main = '') {
+    const root = join(projectDir, '.chapterjs');
+    const files = generatedFiles(projectDir, folders, shared, main);
+    const existing = await readdir(root, {
+        recursive: true,
+        withFileTypes: true,
+    }).catch(() => []);
+    await Promise.all(existing
+        .filter(entry => entry.isFile())
+        .map(entry => join(entry.parentPath, entry.name))
+        .filter(path => !files.has(relative(root, path).split(sep).join('/')) &&
+        // What TypeScript itself leaves there to check faster next time,
+        // and what features remember between two runs.
+        !path.endsWith('.tsbuildinfo') &&
+        !relative(root, path).startsWith(`cache${sep}`) &&
+        // What `chapterjs build` made is not ours to remove.
+        !relative(root, path).startsWith(`build${sep}`))
+        .map(path => rm(path, { force: true })));
+    let written = 0;
+    await Promise.all([...files].map(async ([path, content]) => {
+        const target = join(root, path);
+        if ((await readFile(target, 'utf8').catch(() => null)) === content) {
+            return;
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content);
+        written++;
+    }));
+    return written;
+}

package/dist/loader/hot.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Takes over how the files under `dir` are loaded. Called once, before
+ * loading. With `reload`, `nextGeneration()` makes them load again.
+ */
+export declare function enableProjectLoader(dir: string, { reload }: {
+    reload: boolean;
+}): void;
+/** Makes the next imports load the files again. */
+export declare function nextGeneration(): void;
+/** Imports a file of the project, in its current version. */
+export declare function importFile(path: string): Promise<Record<string, unknown>>;
+/** Removes what hot reload adds to the paths shown in errors. */
+export declare function cleanPath(text: string): string;