chapterjs 0.2.2 → 0.3.0

package/dist/components/router.d.ts

@@ -14,6 +14,11 @@ export declare class ComponentRouter {
     constructor(options: ComponentRouterOptions);
     /** Replaces every component (after a load or a reload). */
     set(entries: Iterable<ComponentEntry>): void;
-    /** Handles an Interaction Create event, if it is a component or a form. */
-    dispatch(ctx: Context, raw: RawInteraction): void;
+    /**
+     * Handles an Interaction Create event, if it is a component or a form.
+     * Returns a promise of everything being done (the function run, the
+     * person answered), or `null` when the interaction is not for this
+     * router. Nothing of the bot waits for it: `chapterjs test` does.
+     */
+    dispatch(ctx: Context, raw: RawInteraction): Promise<void> | null;
 }

package/dist/components/router.js

@@ -33,18 +33,23 @@ export class ComponentRouter {
         }
         this.#components = components;
     }
-    /** Handles an Interaction Create event, if it is a component or a form. */
+    /**
+     * Handles an Interaction Create event, if it is a component or a form.
+     * Returns a promise of everything being done (the function run, the
+     * person answered), or `null` when the interaction is not for this
+     * router. Nothing of the bot waits for it: `chapterjs test` does.
+     */
     dispatch(ctx, raw) {
         const isComponent = raw.type === InteractionType.MessageComponent;
         const isModal = raw.type === InteractionType.ModalSubmit;
         if (!isComponent && !isModal)
-            return;
+            return null;
         const data = raw.data;
         if (!data || typeof data.custom_id !== 'string')
-            return;
+            return null;
         const author = authorOf(raw);
         if (!author)
-            return;
+            return null;
         const user = ctx.entities.user(author.user);
         const { user: _user, member: _member, message: rawMessage, ...rest } = raw;
         const message = rawMessage
@@ -79,7 +84,7 @@ export class ComponentRouter {
                 message: message,
             });
         if (isComponent && !message)
-            return;
+            return null;
         // Embeds are never in the map: what is left has a `run`.
         if (!entry ||
             entry.component.kind === 'embed' ||
@@ -87,27 +92,23 @@ export class ComponentRouter {
                 SELECT_TYPES[entry.component.type] !==
                     data.component_type)) {
             // Sent before the export was renamed, removed or changed of kind.
-            refuse(interaction, 'gone', { what });
-            return;
+            return refuse(interaction, 'gone', { what });
         }
         const { component, file } = entry;
         const values = readData(component.data, parts);
         if (!values) {
             // The data of the component changed since the message was sent.
-            refuse(interaction, 'outdated', { what });
-            return;
+            return refuse(interaction, 'outdated', { what });
         }
         const placed = resolvePlace(ctx, raw, user, author.member, component.where, warning => this.#options.onWarning(file, `${name} ${warning}`));
         if (!placed.place) {
-            refuse(interaction, placed.refusal, { what });
-            return;
+            return refuse(interaction, placed.refusal, { what });
         }
         const { place } = placed;
         if (component.kind !== 'modal' &&
             component.who === 'author' &&
             rawMessage?.interaction_metadata?.user.id !== user.id) {
-            refuse(interaction, 'authorOnly', { what });
-            return;
+            return refuse(interaction, 'authorOnly', { what });
         }
         remember(interaction, {
             guild: place.guild ?? undefined,
@@ -127,8 +128,7 @@ export class ComponentRouter {
         }
         catch (error) {
             this.#options.onError(file, error);
-            refuse(interaction, 'failed', { what });
-            return;
+            return refuse(interaction, 'failed', { what });
         }
         const context = Object.freeze({
             interaction,
@@ -144,12 +144,13 @@ export class ComponentRouter {
                 ephemeral: ephemeralOf(component),
             })),
         });
-        runInteraction({
+        return runInteraction({
             interaction,
             file,
             name,
             what,
             reporter: this.#options,
+            guildId: place.guild?.id ?? null,
             // Nothing changes on screen while a component is answered; a form
             // sent is like a command used.
             defer: () => interaction instanceof ComponentInteraction

package/dist/discord/types/channel.d.ts

@@ -251,6 +251,14 @@ export interface RawForumTag {
     /** the unicode character of the emoji * */
     emoji_name: string | null;
 }
+/**
+ * A forum tag as a request gives it: a new tag has no `id` yet, an existing
+ * one keeps its own.
+ * @see https://docs.discord.com/developers/resources/channel#forum-tag-object
+ */
+export type RawForumTagInput = Omit<RawForumTag, 'id'> & {
+    id?: Snowflake;
+};
 /**
  * JSON Params (Group DM)
  * @see https://docs.discord.com/developers/resources/channel#modify-channel-json-params-group-dm
@@ -293,7 +301,7 @@ export interface ModifyGuildChannelJSONParams {
     /** channel flags combined as a bitfield. */
     flags?: number;
     /** the set of tags that can be used in a `GUILD_FORUM` or a `GUILD_MEDIA` channel; limited to 20 */
-    available_tags?: RawForumTag[];
+    available_tags?: RawForumTagInput[];
     /** the emoji to show in the add reaction button on a thread in a `GUILD_FORUM` or a `GUILD_MEDIA` channel */
     default_reaction_emoji?: RawDefaultReaction | null;
     /** the initial `rate_limit_per_user` to set on newly created threads in a channel. this field is copied to the thread at creation time and does not live update. */

package/dist/discord/types/guild.d.ts

@@ -1,9 +1,9 @@
 import type { RawApplication } from './application.js';
-import type { ChannelType, ForumLayoutType, ForumSortOrderType, RawChannel, RawDefaultReaction, RawForumTag, RawPermissionOverwrite, RawThreadMember, VideoQualityMode } from './channel.js';
+import type { ChannelType, ForumLayoutType, ForumSortOrderType, RawChannel, RawDefaultReaction, RawForumTagInput, RawPermissionOverwrite, RawThreadMember, VideoQualityMode } from './channel.js';
 import type { ISO8601Timestamp, ImageData, Locale, Snowflake } from './common.js';
 import type { RawEmoji } from './emoji.js';
 import type { OAuth2Scope } from './oauth2.js';
-import type { RawRole, RawRoleColors } from './permissions.js';
+import type { RawRole, RawRoleColorsInput } from './permissions.js';
 import type { RawSticker } from './sticker.js';
 import type { RawAvatarDecorationData, RawCollectibles, RawUser } from './user.js';
 /**
@@ -605,7 +605,7 @@ export interface CreateGuildChannelJSONParams {
     /** emoji to show in the add reaction button on a thread in a `GUILD_FORUM` or a `GUILD_MEDIA` channel */
     default_reaction_emoji?: RawDefaultReaction | null;
     /** set of tags that can be used in a `GUILD_FORUM` or a `GUILD_MEDIA` channel */
-    available_tags?: RawForumTag[] | null;
+    available_tags?: RawForumTagInput[] | null;
     /** the default sort order type used to order posts in `GUILD_FORUM` and `GUILD_MEDIA` channels */
     default_sort_order?: ForumSortOrderType | null;
     /** the default forum layout view used to display posts in `GUILD_FORUM` channels */
@@ -773,7 +773,7 @@ export interface CreateGuildRoleJSONParams {
     /** **Deprecated** RGB color value */
     color?: number;
     /** the role's colors */
-    colors?: RawRoleColors;
+    colors?: RawRoleColorsInput;
     /** whether the role should be displayed separately in the sidebar */
     hoist?: boolean;
     /** the role's icon image (if the guild has the `ROLE_ICONS` feature) */
@@ -805,7 +805,7 @@ export interface ModifyGuildRoleJSONParams {
     /** **Deprecated** RGB color value */
     color?: number;
     /** the role's colors */
-    colors?: RawRoleColors;
+    colors?: RawRoleColorsInput;
     /** whether the role should be displayed separately in the sidebar */
     hoist?: boolean;
     /** the role's icon image (if the guild has the `ROLE_ICONS` feature) */

package/dist/discord/types/permissions.d.ts

@@ -172,6 +172,12 @@ export interface RawRoleColors {
     /** the tertiary color for the role, this will turn the gradient into a holographic style */
     tertiary_color: number | null;
 }
+/**
+ * The colors of a role as a request gives them: only the primary color is
+ * needed, the two others make a gradient when given.
+ * @see https://docs.discord.com/developers/topics/permissions#role-object-role-colors-object
+ */
+export type RawRoleColorsInput = Pick<RawRoleColors, 'primary_color'> & Partial<Omit<RawRoleColors, 'primary_color'>>;
 /**
  * Role Flags
  * @see https://docs.discord.com/developers/topics/permissions#role-object-role-flags

package/dist/discord/types/poll.d.ts

@@ -27,7 +27,7 @@ export interface RawPollCreateRequest {
     /** The question of the poll. Only `text` is supported. */
     question: RawPollMedia;
     /** Each of the answers available in the poll, up to 10 */
-    answers: RawPollAnswer[];
+    answers: RawPollAnswerInput[];
     /** Number of hours the poll should be open for, up to 32 days. Defaults to 24 */
     duration?: number;
     /** Whether a user can select multiple answers. Defaults to false */
@@ -54,6 +54,12 @@ export interface RawPollMedia {
     /** The emoji of the field */
     emoji?: Partial<RawEmoji>;
 }
+/**
+ * A poll answer as a request gives it: `answer_id` is only sent as part of
+ * responses from Discord's API/Gateway.
+ * @see https://docs.discord.com/developers/resources/poll#poll-answer-object-poll-answer-object-structure
+ */
+export type RawPollAnswerInput = Omit<RawPollAnswer, 'answer_id'>;
 /**
  * Poll Answer Object Structure
  * @see https://docs.discord.com/developers/resources/poll#poll-answer-object-poll-answer-object-structure

package/dist/events/router.d.ts

@@ -36,11 +36,19 @@ export declare class EventRouter {
      * `dispatch` needs back; nothing is read for events nobody listens to.
      */
     before<E extends GatewayDispatchEventName>(ctx: Context, event: E, data: GatewayDispatchEvents[E]): unknown[] | undefined;
-    /** Runs the handlers of a gateway event, once the cache reflects it. */
+    /**
+     * Runs the handlers of a gateway event, once the cache reflects it.
+     * Resolves once every handler is done (what was asked to Discord first
+     * included). Nothing of the bot waits for it: `chapterjs test` does.
+     */
     dispatch<E extends GatewayDispatchEventName>(ctx: Context, event: E, data: GatewayDispatchEvents[E], extra: {
         joined: boolean;
         before: unknown[] | undefined;
-    }): void;
-    /** Runs the handlers of an event with what they receive. */
-    emit<Name extends EventName>(name: Name, context: EventContexts[Name]): void;
+    }): Promise<void>;
+    /**
+     * Runs the handlers of an event with what they receive, for the server
+     * it happened in (what a store per server reads). Resolves once every
+     * handler is done.
+     */
+    emit<Name extends EventName>(name: Name, context: EventContexts[Name], guildId?: string | null): Promise<void>;
 }

package/dist/events/router.js

@@ -1,4 +1,5 @@
 // Delivers gateway events to the handlers of the project.
+import { withGuild } from '../store/scope.js';
 import { DEFAULT_CACHE_LIMITS } from '../cache/cache.js';
 import { GatewayIntent } from '../discord/intents.js';
 import { audienceLocale, translation } from '../messages/translate.js';
@@ -78,11 +79,16 @@ export class EventRouter {
             ? source.before(ctx, data)
             : undefined);
     }
-    /** Runs the handlers of a gateway event, once the cache reflects it. */
+    /**
+     * Runs the handlers of a gateway event, once the cache reflects it.
+     * Resolves once every handler is done (what was asked to Discord first
+     * included). Nothing of the bot waits for it: `chapterjs test` does.
+     */
     dispatch(ctx, event, data, extra) {
         const sources = BY_GATEWAY_EVENT.get(event);
         if (!sources)
-            return;
+            return Promise.resolve();
+        const pending = [];
         sources.forEach((source, index) => {
             if (!this.#handlers.has(source.name))
                 return;
@@ -93,41 +99,52 @@ export class EventRouter {
                     prepared,
                 });
                 if (!built)
-                    return;
+                    return Promise.resolve();
                 // One gateway event can be several occurrences (messages deleted
                 // together, emojis changed at once): each is delivered.
                 const occurrences = Array.isArray(built)
                     ? built
                     : [built];
                 const guildOf = EVENTS[source.name].guildOf;
+                const emitted = [];
                 for (const context of occurrences) {
                     // `t` speaks the language of the server the event happened in.
                     const guild = guildOf?.(context);
-                    this.emit(source.name, {
+                    emitted.push(this.emit(source.name, {
                         ...context,
                         ...translation(ctx, audienceLocale({ guild })),
-                    });
+                    }, guild?.id ?? null));
                 }
+                return Promise.all(emitted).then(() => { });
             };
             const preparing = source.prepare?.(ctx, data);
-            if (!preparing)
-                return deliver();
-            preparing.then(deliver, (error) => this.#onSkipped(source.name, error));
+            if (!preparing) {
+                pending.push(deliver());
+                return;
+            }
+            pending.push(preparing.then(deliver, (error) => this.#onSkipped(source.name, error)));
         });
+        return Promise.all(pending).then(() => { });
     }
-    /** Runs the handlers of an event with what they receive. */
-    emit(name, context) {
+    /**
+     * Runs the handlers of an event with what they receive, for the server
+     * it happened in (what a store per server reads). Resolves once every
+     * handler is done.
+     */
+    emit(name, context, guildId = null) {
         const handlers = this.#handlers.get(name);
         if (!handlers)
-            return;
+            return Promise.resolve();
         // Handlers can't change what the others receive.
         const frozen = Object.freeze({ ...context });
         const accepts = EVENTS[name].accepts;
+        const running = [];
         for (const { file, event } of handlers) {
             if (accepts && !accepts(frozen, event.options))
                 continue;
             // One handler failing never stops the others, nor the bot.
-            new Promise(resolve => resolve(event.handler(frozen))).catch((error) => this.#onError(file, error));
+            running.push(new Promise(resolve => resolve(withGuild(guildId, () => event.handler(frozen)))).then(() => { }, (error) => this.#onError(file, error)));
         }
+        return Promise.all(running).then(() => { });
     }
 }

package/dist/index.d.ts

@@ -29,6 +29,8 @@ 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 { store } from './store/store.js';
+export type { ScopedStore, Store, StoreConfig, StoreEntry, StoreKey, StoreScope, StoreSetOptions, } from './store/store.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';

package/dist/index.js

@@ -21,6 +21,7 @@ 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 { store } from './store/store.js';
 export { task } from './tasks/task.js';
 // Errors handlers can catch.
 export { DiscordApiError, DiscordUnavailableError, InvalidTokenError, } from './rest/errors.js';

package/dist/interactions/dispatch.d.ts

@@ -80,6 +80,8 @@ export interface RunOptions {
     defer: () => Promise<void>;
     /** What to tell the developer when `run` finishes without answering. */
     unanswered: string;
+    /** The server the function runs for: what a store per server reads. */
+    guildId: string | null;
     run: () => unknown;
 }
 /**
@@ -87,5 +89,9 @@ export interface RunOptions {
  * 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.
+ *
+ * Resolves once everything is done (the function, and the answer sent for
+ * it when it failed): nothing of the bot waits for it, `chapterjs test`
+ * does.
  */
-export declare function runInteraction(options: RunOptions): void;
+export declare function runInteraction(options: RunOptions): Promise<void>;

package/dist/interactions/dispatch.js

@@ -3,6 +3,7 @@
 // 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 { withGuild } from '../store/scope.js';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { phrase } from '../messages/phrases.js';
 import { DiscordApiError } from '../rest/errors.js';
@@ -74,6 +75,10 @@ export function refuse(interaction, key, params) {
  * 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.
+ *
+ * Resolves once everything is done (the function, and the answer sent for
+ * it when it failed): nothing of the bot waits for it, `chapterjs test`
+ * does.
  */
 export function runInteraction(options) {
     const { interaction, file, name, reporter } = options;
@@ -81,7 +86,7 @@ export function runInteraction(options) {
     sleep(reporter.deferAfter ?? 2000, undefined, { signal: stop.signal })
         .then(() => options.defer())
         .catch(() => { });
-    new Promise(resolve => resolve(options.run()))
+    return new Promise(resolve => resolve(withGuild(options.guildId, options.run)))
         .then(() => {
         if (!interaction.answered) {
             reporter.onWarning(file, `${name} ${options.unanswered}`);
@@ -104,7 +109,7 @@ export function runInteraction(options) {
                 : interaction.answered
                     ? interaction.followUp({ content, ephemeral: true })
                     : interaction.reply({ content, ephemeral: true });
-        tell.catch(() => { });
+        return tell.then(() => { }, () => { });
     })
         .finally(() => stop.abort());
 }

package/dist/loader/hot.js

@@ -45,8 +45,15 @@ export function enableProjectLoader(dir, { reload }) {
                 result = nextResolve(specifier, context);
             }
             catch (error) {
-                if (!fromProject || EXTENSION.test(specifier))
+                // Not found, or a folder (Node refuses those as they are).
+                const code = error.code;
+                if (!fromProject ||
+                    (code !== 'ERR_MODULE_NOT_FOUND' &&
+                        code !== 'ERR_UNSUPPORTED_DIR_IMPORT')) {
                     throw error;
+                }
+                if (EXTENSION.test(specifier))
+                    throw missing(specifier, false);
                 // No extension: look for the file people mean.
                 for (const candidate of CANDIDATES) {
                     try {
@@ -58,7 +65,7 @@ export function enableProjectLoader(dir, { reload }) {
                     }
                 }
                 if (!result)
-                    throw error;
+                    throw missing(specifier, true);
             }
             if (hot && root !== null && result.url.startsWith(root)) {
                 return {
@@ -70,6 +77,19 @@ export function enableProjectLoader(dir, { reload }) {
         },
     });
 }
+/**
+ * The error for an import of the project that names no file: said in the
+ * words of the import, not with the absolute paths Node gives.
+ */
+function missing(specifier, tried) {
+    const name = specifier.replace(/\/$/, '').split('/').pop() ?? specifier;
+    const looked = tried
+        ? ` No ${name}.ts, ${name}.js or ${name}/index.ts is there.`
+        : '';
+    const error = new Error(`'${specifier}' does not exist.${looked} Check the path and the name of the file.`);
+    error.code = 'ERR_MODULE_NOT_FOUND';
+    return error;
+}
 /** Makes the next imports load the files again. */
 export function nextGeneration() {
     generation++;

package/dist/loader/loader.d.ts

@@ -59,6 +59,11 @@ export interface FoundFile {
 }
 /** Every source file of `src/`, in a stable order. */
 export declare function listSources(projectDir: string): Promise<FoundFile[]>;
+/**
+ * Every test file of `src/` (`*.test.ts`, `*.spec.ts`), in a stable order:
+ * what `chapterjs test` runs, and what the bot never loads.
+ */
+export declare function listTests(projectDir: string): Promise<FoundFile[]>;
 /** A file of the project, run: what it exports. */
 export interface LoadedModule {
     /** The path from the project folder: `src/ping.ts`. */
@@ -72,6 +77,8 @@ export interface LoadedSources {
 }
 /** Runs every file of `src/`. A file that fails to run never throws. */
 export declare function loadSources(projectDir: string): Promise<LoadedSources>;
+/** Runs the files given. A file that fails to run never throws. */
+export declare function loadFiles(files: readonly FoundFile[]): Promise<LoadedSources>;
 /**
  * Reads the declarations of one kind from what the files export. Every
  * export is looked at; the ones the kind recognises are read, the others

package/dist/loader/loader.js

@@ -16,7 +16,7 @@ const DECLARATION = /\.d\.m?ts$/;
 /** Tests next to the code: they are for a test runner, not for the bot. */
 const TEST = /\.(?:test|spec)\.[^.]+$/;
 /** The source files of a folder and its subfolders, in a stable order. */
-async function scan(dir) {
+async function scan(dir, tests = false) {
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true });
@@ -30,10 +30,10 @@ async function scan(dir) {
     for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
         const path = join(dir, entry.name);
         if (entry.isDirectory())
-            files.push(...(await scan(path)));
+            files.push(...(await scan(path, tests)));
         else if (SOURCE.test(entry.name) &&
             !DECLARATION.test(entry.name) &&
-            !TEST.test(entry.name)) {
+            TEST.test(entry.name) === tests) {
             files.push(path);
         }
     }
@@ -41,19 +41,29 @@ async function scan(dir) {
 }
 /** Every source file of `src/`, in a stable order. */
 export async function listSources(projectDir) {
-    const paths = await scan(join(projectDir, 'src'));
-    return paths
-        .map(path => ({
-        file: relative(projectDir, path).split(sep).join('/'),
-        path,
-    }))
-        .sort((a, b) => (a.file < b.file ? -1 : 1));
+    return found(projectDir, await scan(join(projectDir, 'src')));
 }
+/**
+ * Every test file of `src/` (`*.test.ts`, `*.spec.ts`), in a stable order:
+ * what `chapterjs test` runs, and what the bot never loads.
+ */
+export async function listTests(projectDir) {
+    return found(projectDir, await scan(join(projectDir, 'src'), true));
+}
+const found = (projectDir, paths) => paths
+    .map(path => ({
+    file: relative(projectDir, path).split(sep).join('/'),
+    path,
+}))
+    .sort((a, b) => (a.file < b.file ? -1 : 1));
 /** Runs every file of `src/`. A file that fails to run never throws. */
 export async function loadSources(projectDir) {
-    const found = await listSources(projectDir);
+    return loadFiles(await listSources(projectDir));
+}
+/** Runs the files given. A file that fails to run never throws. */
+export async function loadFiles(files) {
     const result = { modules: [], failed: [] };
-    await Promise.all(found.map(async ({ file, path }) => {
+    await Promise.all(files.map(async ({ file, path }) => {
         try {
             result.modules.push({ file, exports: await importFile(path) });
         }

package/dist/store/backend.d.ts

@@ -0,0 +1,33 @@
+/** One value of a store, with when it expires. */
+export interface StoreEntry {
+    value: unknown;
+    /** When the value expires, in ms since the epoch, or `null` for never. */
+    expiresAt: number | null;
+}
+/** A key as the backend sees it: every part, the scope included. */
+export type StoreKeyParts = readonly string[];
+/** An entry with its key, as `entries()` lists them. */
+export interface StoreListedEntry extends StoreEntry {
+    key: StoreKeyParts;
+}
+/** What keeps the data of every store. Expired entries are never given. */
+export interface StoreBackend {
+    get(store: string, key: StoreKeyParts): Promise<StoreEntry | undefined>;
+    set(store: string, key: StoreKeyParts, entry: StoreEntry): Promise<void>;
+    delete(store: string, key: StoreKeyParts): Promise<boolean>;
+    /** The entries whose key starts with `prefix`, in no particular order. */
+    entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    /** Writes what is pending, if anything. */
+    close(): Promise<void>;
+}
+/** The map key of a key: unambiguous whatever the parts hold. */
+export declare const encodeKey: (key: StoreKeyParts) => string;
+export declare const decodeKey: (encoded: string) => string[];
+/** Whether `key` starts with every part of `prefix`. */
+export declare function startsWith(key: StoreKeyParts, prefix: StoreKeyParts): boolean;
+/** Whether an entry is still good at `now`. */
+export declare const alive: (entry: StoreEntry, now?: number) => boolean;
+/** Gives every store its backend: called by the CLI, once per process. */
+export declare function setStoreBackend(backend: StoreBackend | null): void;
+/** The backend of the process, or an error that says when stores work. */
+export declare function storeBackend(): StoreBackend;

package/dist/store/backend.js

@@ -0,0 +1,27 @@
+// Where the data of the stores is kept, behind an interface: a file per
+// store by default (`file-backend.ts`), the first process of a cluster for
+// the others (`ipc-backend.ts`), and later anything else. A backend knows
+// nothing of servers: the scope of a store is part of the key it gets.
+/** The map key of a key: unambiguous whatever the parts hold. */
+export const encodeKey = (key) => JSON.stringify(key);
+export const decodeKey = (encoded) => JSON.parse(encoded);
+/** Whether `key` starts with every part of `prefix`. */
+export function startsWith(key, prefix) {
+    if (prefix.length > key.length)
+        return false;
+    return prefix.every((part, index) => key[index] === part);
+}
+/** Whether an entry is still good at `now`. */
+export const alive = (entry, now = Date.now()) => entry.expiresAt === null || entry.expiresAt > now;
+let current = null;
+/** Gives every store its backend: called by the CLI, once per process. */
+export function setStoreBackend(backend) {
+    current = backend;
+}
+/** The backend of the process, or an error that says when stores work. */
+export function storeBackend() {
+    if (!current) {
+        throw new Error('Stores only work while the bot runs: use a store in the functions of your files (run), not when a file loads.');
+    }
+    return current;
+}

package/dist/store/declaration.d.ts

@@ -0,0 +1,15 @@
+import type { Declaration } from '../loader/loader.js';
+import { type StoreScope } from './store.js';
+/** A store, checked: what the project keeps of it. */
+export interface LoadedStore {
+    /** The name of the store: the name of the export that declares it. */
+    readonly name: string;
+    readonly scope: StoreScope;
+    /** The default expiration, in ms, or `null` for never. */
+    readonly expires: number | null;
+}
+/**
+ * A store, declared anywhere in `src/` with `store()` and exported: the
+ * name of the export is the name of the store.
+ */
+export declare const storeDeclaration: Declaration<LoadedStore>;