chapterjs 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -1,18 +1,57 @@
-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, CommandDeclaration, CommandLocales, CommandName, 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, ButtonDeclaration, ButtonLook, ButtonStyleName, } from './components/button.js';
+export { select } from './components/select.js';
+export type { EntitySelectConfig, EntitySelectType, SelectConfig, SelectContext, SelectDeclaration, 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, ModalDeclaration, ModalInstanceOptions, ModalPrefill, NoteField, RadioField, SelectField, TextField, } from './components/modal.js';
+export { embed } from './components/embed.js';
+export type { EmbedDeclaration } 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 { event } from './events/event.js';
+export type { EventConfig, EventDeclaration } from './events/event.js';
+export type { ContextOf, EventWhere, WhereEventOptions, EventContexts, 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, LanguageDeclaration, MergedMessages, MessagesOf, MessageText, MessageTexts, PluralText, ProjectCommands, ProjectLanguageDefaults, 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, PresenceDeclaration, PresenceStatusName, StreamingActivity, } from './presence/presence.js';
+export { task } from './tasks/task.js';
+export type { CronTaskConfig, EveryTaskConfig, TaskConfig, TaskContext, TaskDeclaration, } 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,40 @@
-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';
+// What the functions of src/events/ receive, by event.
+export { event } from './events/event.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,10 @@
+/**
+ * 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. `declarations` is
+ * what 'chapterjs' has in this project on top of the package: `declare
+ * module 'chapterjs'` augmentations, importing the package from
+ * `'#chapterjs'`.
+ * @returns how many files were written
+ */
+export declare function writeGenerated(projectDir: string, declarations: string): Promise<number>;

package/dist/loader/generated.js

@@ -0,0 +1,80 @@
+// The `.chapterjs/` folder of a project: what the framework writes so that
+// the files of the project are typed from the project itself, with nothing
+// to write. Everything 'chapterjs' gives is typed by the package; what only
+// the project knows (the files of `public/`, its languages, its commands)
+// is written here as an augmentation of 'chapterjs', in one TypeScript
+// project that covers every file of `src/`. The tsconfig of the user
+// project only references this folder; editors and `tsc -b` find it 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, declarations) {
+    const files = new Map();
+    const specifier = packageSpecifier(projectDir);
+    // The folder ignores itself: nothing to add to the project's .gitignore.
+    files.set('.gitignore', '*\n');
+    // What the project adds to 'chapterjs': written as an augmentation, so
+    // the editor offers one 'chapterjs' and not a second copy of it.
+    files.set('types/project.d.ts', `${HEADER}${declarations.replaceAll("'#chapterjs'", `'${specifier}'`)}`);
+    files.set('tsconfig.json', json({
+        extends: '../tsconfig.json',
+        // The declaration file is listed too: a project without a src folder
+        // yet is then a valid, empty project.
+        include: ['../src', './types/project.d.ts'],
+    }));
+    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. `declarations` is
+ * what 'chapterjs' has in this project on top of the package: `declare
+ * module 'chapterjs'` augmentations, importing the package from
+ * `'#chapterjs'`.
+ * @returns how many files were written
+ */
+export async function writeGenerated(projectDir, declarations) {
+    const root = join(projectDir, '.chapterjs');
+    const files = generatedFiles(projectDir, declarations);
+    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;

package/dist/loader/hot.js

@@ -0,0 +1,85 @@
+// How Node loads the files of a project.
+//
+// Imports without extension: `import { greet } from '../lib/greet'` finds
+// `greet.ts` (or `greet/index.ts`), as people expect. Node alone asks for
+// the extension; writing it still works.
+//
+// Hot reload: Node keeps every imported module forever, by URL. Each reload
+// gets a new "generation" number, added to the URL of every file of the
+// project (and only of the project: packages keep their single copy). A
+// file and everything it imports from the project are then loaded again.
+import { registerHooks } from 'node:module';
+import { pathToFileURL } from 'node:url';
+const PARAM = 'chapter';
+let generation = 0;
+let root = null;
+let hot = false;
+/** What an import without extension may be, in the order it is tried. */
+const CANDIDATES = [
+    '.ts',
+    '.mts',
+    '.js',
+    '.mjs',
+    '/index.ts',
+    '/index.mts',
+    '/index.js',
+    '/index.mjs',
+];
+const EXTENSION = /\.(?:m?ts|m?js)$/;
+/**
+ * Takes over how the files under `dir` are loaded. Called once, before
+ * loading. With `reload`, `nextGeneration()` makes them load again.
+ */
+export function enableProjectLoader(dir, { reload }) {
+    if (root !== null)
+        throw new Error('The project loader is already enabled.');
+    root = pathToFileURL(dir).href.replace(/\/?$/, '/');
+    hot = reload;
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const fromProject = root !== null &&
+                context.parentURL?.startsWith(root) === true &&
+                specifier.startsWith('.');
+            let result;
+            try {
+                result = nextResolve(specifier, context);
+            }
+            catch (error) {
+                if (!fromProject || EXTENSION.test(specifier))
+                    throw error;
+                // No extension: look for the file people mean.
+                for (const candidate of CANDIDATES) {
+                    try {
+                        result = nextResolve(specifier.replace(/\/$/, '') + candidate, context);
+                        break;
+                    }
+                    catch {
+                        // Try the next one.
+                    }
+                }
+                if (!result)
+                    throw error;
+            }
+            if (hot && root !== null && result.url.startsWith(root)) {
+                return {
+                    ...result,
+                    url: `${result.url.split('?')[0]}?${PARAM}=${generation}`,
+                };
+            }
+            return result;
+        },
+    });
+}
+/** Makes the next imports load the files again. */
+export function nextGeneration() {
+    generation++;
+}
+/** Imports a file of the project, in its current version. */
+export function importFile(path) {
+    const url = pathToFileURL(path).href;
+    return import(hot ? `${url}?${PARAM}=${generation}` : url);
+}
+/** Removes what hot reload adds to the paths shown in errors. */
+export function cleanPath(text) {
+    return text.replace(new RegExp(`\\?${PARAM}=\\d+`, 'g'), '');
+}