chapterjs 0.2.1 → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quentin Truffy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli/cluster.d.ts

@@ -1,3 +1,4 @@
+import type { StoreBackend } from '../store/backend.js';
 import { type IdentifyGate } from '../gateway/identify-queue.js';
 /** How many shards one process runs when nothing else is asked. */
 export declare const SHARDS_PER_PROCESS = 4;
@@ -50,6 +51,8 @@ export interface ClusterOptions {
     signal: AbortSignal;
     /** Shows a line printed by one of the processes. */
     write: (line: string) => void;
+    /** Where the data of the stores is: this process keeps it for the others. */
+    stores: StoreBackend;
     /** Every process is connected, for the first time. */
     onReady: (info: {
         guilds: number;

package/dist/cli/cluster.js

@@ -9,6 +9,7 @@
 // identify. A setup on several machines would give each process another
 // `IdentifyGate`, and nothing else here would change.
 // https://docs.discord.com/developers/events/gateway#sharding
+import { serveStores, } from '../store/ipc-backend.js';
 import { fork } from 'node:child_process';
 import { availableParallelism } from 'node:os';
 import { createInterface } from 'node:readline';
@@ -134,8 +135,10 @@ export async function runCluster(options) {
         for (const stream of [child.stdout, child.stderr]) {
             createInterface({ input: stream }).on('line', line => options.write(`[${index + 1}] ${line}`));
         }
+        const stores = serveStores(options.stores, reply => tell(child, reply));
         child.on('message', (message) => {
-            if (message.type === 'identify') {
+            stores(message);
+            if (message.type !== 'store' && message.type === 'identify') {
                 void gate.wait(message.shard).then(() => {
                     tell(child, { type: 'identify', id: message.id });
                 });

package/dist/cli/dev.js

@@ -255,6 +255,7 @@ export async function dev(options) {
         assets.close();
         memory.stop();
         await bot?.close();
+        await project.closeStores();
         if (code === 0)
             log.success('Disconnected');
         return code;
@@ -265,6 +266,7 @@ export async function dev(options) {
         assets.close();
         memory.stop();
         await bot?.close();
+        await project.closeStores();
         if (signal.aborted)
             return 0;
         explain(error, log);

package/dist/cli/project.d.ts

@@ -1,5 +1,7 @@
 import { type CommandEntry } from '../commands/tree.js';
 import { type ComponentEntry } from '../components/router.js';
+import { type LoadedStore } from '../store/declaration.js';
+import { type StoreBackend } from '../store/backend.js';
 import { type LoadedPresence } from '../presence/declaration.js';
 import { type DeclaredCommand, type DeclaredLanguage } from '../messages/declaration.js';
 import { type LoadedMessages } from '../messages/translate.js';
@@ -26,6 +28,12 @@ export interface ProjectOptions {
      * Without it, the files of `src` are read on every load.
      */
     joinsVoice?: boolean;
+    /**
+     * Where the stores of the project keep their data. A file per store in
+     * the `data/` folder of the project by default; the first process of a
+     * cluster, through IPC, for the other processes.
+     */
+    stores?: StoreBackend;
     /** Only tests change this. */
     deferAfter?: number;
 }
@@ -55,6 +63,12 @@ export interface TypesInfo {
 export declare function writeTypes(cwd: string, info?: TypesInfo): Promise<number>;
 /** The kinds of declarations a project is made of: one per feature. */
 export declare const DECLARATIONS: readonly Declaration<unknown>[];
+/** A store, with where it is declared. */
+export interface StoreEntry {
+    file: string;
+    export: string;
+    store: LoadedStore;
+}
 /** What a bot of the project is connected with. */
 export interface ConnectOptions {
     token: string;
@@ -82,6 +96,9 @@ export interface Project {
     readonly commands: ReadonlyMap<string, CommandEntry>;
     readonly components: ReadonlyMap<string, ComponentEntry>;
     readonly tasks: ReadonlyMap<string, TaskEntry>;
+    readonly stores: ReadonlyMap<string, StoreEntry>;
+    /** Where the stores keep their data: what a cluster serves to its other processes. */
+    readonly storeBackend: StoreBackend;
     /** The presence declared, or `null` without one. */
     readonly presence: LoadedPresence | null;
     /** The languages of the project, assembled, or `null` without any. */
@@ -127,6 +144,8 @@ export interface Project {
     watchMemory(current: () => Bot | null): {
         stop(): void;
     };
+    /** Writes what the stores still have to write. Nothing is kept after this. */
+    closeStores(): Promise<void>;
 }
 /** Whether the folder is a project: it has a `src` folder. */
 export declare function hasSources(cwd: string, log: Log): Promise<boolean>;

package/dist/cli/project.js

@@ -15,6 +15,9 @@ import { findConflicts } from '../commands/tree.js';
 import { componentDeclaration, findDuplicates, } from '../components/declaration.js';
 import { ComponentRouter } from '../components/router.js';
 import { taskDeclaration } from '../tasks/declaration.js';
+import { storeDeclaration } from '../store/declaration.js';
+import { setStoreBackend } from '../store/backend.js';
+import { DATA_FOLDER, FileStoreBackend } from '../store/file-backend.js';
 import { DEFAULT_PRESENCE, presenceDeclaration, } from '../presence/declaration.js';
 import { assembleMessages, commandsDeclarations, languageDeclaration, languageDefaultsDeclaration, messagesDeclarations, scanLanguages, } from '../messages/declaration.js';
 import { translation } from '../messages/translate.js';
@@ -64,6 +67,7 @@ export const DECLARATIONS = [
     commandDeclaration,
     componentDeclaration,
     taskDeclaration,
+    storeDeclaration,
     presenceDeclaration,
     languageDeclaration,
 ];
@@ -117,6 +121,9 @@ export function createProject(options) {
     const { cwd, log } = options;
     // Where `asset()` reads the files of the project from.
     setPublicDir(cwd);
+    // Where the stores keep their data, for every store of the process.
+    const storeBackend = options.stores ?? new FileStoreBackend(join(cwd, DATA_FOLDER));
+    setStoreBackend(storeBackend);
     const report = (failure) => {
         const where = locate(failure.error, cwd);
         log.error(`${where ? `${where.file}:${where.line}` : siteName(failure)} ${messageOf(failure.error)}`);
@@ -142,6 +149,7 @@ export function createProject(options) {
     let commands = new Map();
     let components = new Map();
     let tasks = new Map();
+    let stores = new Map();
     let presence = null;
     /** The files the presence was declared in, to keep it when they break. */
     let presenceFiles = new Set();
@@ -171,6 +179,10 @@ export function createProject(options) {
         get tasks() {
             return tasks;
         },
+        get stores() {
+            return stores;
+        },
+        storeBackend,
         get presence() {
             return presence;
         },
@@ -201,11 +213,12 @@ export function createProject(options) {
             // then read, kind by kind.
             const sources = built ? { modules: built, failed: [] } : await loadSources(cwd);
             const read = (declaration) => readDeclarations(sources.modules, declaration);
-            const [eventItems, commandItems, componentItems, taskItems, presenceItems, languageItems,] = [
+            const [eventItems, commandItems, componentItems, taskItems, storeItems, presenceItems, languageItems,] = [
                 read(eventDeclaration),
                 read(commandDeclaration),
                 read(componentDeclaration),
                 read(taskDeclaration),
+                read(storeDeclaration),
                 read(presenceDeclaration),
                 read(languageDeclaration),
             ];
@@ -259,6 +272,15 @@ export function createProject(options) {
             ], entry => entry.task.name, 'task');
             tasks = new Map(sameTask.valid.map(entry => [keyOf(entry), entry]));
             scheduler.set(tasks.values());
+            // Two stores with one name would share one file: the later is left out.
+            const sameStore = sameNames([
+                ...next(stores, storeItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    store: item.value,
+                })).values(),
+            ], entry => entry.store.name, 'store');
+            stores = new Map(sameStore.valid.map(entry => [keyOf(entry), entry]));
             // One presence. A second one is left out.
             const [first, ...extra] = presenceItems.loaded;
             if (first)
@@ -346,11 +368,17 @@ export function createProject(options) {
                 ...commandItems.failed,
                 ...componentItems.failed,
                 ...taskItems.failed,
+                ...storeItems.failed,
                 ...presenceItems.failed,
                 ...languageItems.failed,
                 ...badTexts,
                 ...twice,
-                ...[...conflicts, ...unique.conflicts, ...sameTask.conflicts].map(({ file, export: exported, message }) => ({
+                ...[
+                    ...conflicts,
+                    ...unique.conflicts,
+                    ...sameTask.conflicts,
+                    ...sameStore.conflicts,
+                ].map(({ file, export: exported, message }) => ({
                     file,
                     export: exported,
                     error: new TypeError(message),
@@ -375,6 +403,7 @@ export function createProject(options) {
                     ? [count(components.size, 'component', 'components')]
                     : []),
                 ...(tasks.size > 0 ? [count(tasks.size, 'task', 'tasks')] : []),
+                ...(stores.size > 0 ? [count(stores.size, 'store', 'stores')] : []),
                 ...(presence ? ['a presence'] : []),
                 ...(messages
                     ? [
@@ -387,6 +416,7 @@ export function createProject(options) {
             commands.size === 0 &&
             components.size === 0 &&
             tasks.size === 0 &&
+            stores.size === 0 &&
             presence === null &&
             messages === null,
         filesNeeding: intent => [...events.values()]
@@ -490,6 +520,7 @@ export function createProject(options) {
         stopTasks: () => scheduler.stop(),
         // The bot looks after its own memory: it remembers less before memory
         // is full, and only speaks up when it can't give up anything more.
+        closeStores: () => storeBackend.close(),
         watchMemory: current => watchMemory({
             cache: () => current()?.ctx.cache,
             onTightened: ({ members, forgotten }, { used, limit }) => log.info(`Memory was getting full (${megabytes(used)} of ${megabytes(limit)}): the bot now remembers ${members} members per server at most, and forgot ${forgotten} members and users it had not seen for the longest. Nothing changes for your code.`),

package/dist/cli/start.js

@@ -1,6 +1,7 @@
 // `chapterjs start`: runs for everyone the bot `chapterjs build` prepared.
 // Nothing is reloaded, commands are registered for every server, and a
 // large bot is spread over several processes by itself.
+import { IpcStoreBackend } from '../store/ipc-backend.js';
 import { registerCommands } from '../commands/register.js';
 import { buildCommands } from '../commands/tree.js';
 import { GLOBAL_REQUESTS_PER_SECOND } from '../discord/api.js';
@@ -54,6 +55,19 @@ export async function start(options) {
         log,
         built: files,
         joinsVoice: built.info.voice === true,
+        // A process started by another keeps no data: the first one does, for
+        // all of them.
+        ...(assignment
+            ? {
+                stores: new IpcStoreBackend({
+                    send: message => {
+                        if (process.connected)
+                            process.send?.(message);
+                    },
+                    on: listener => process.on('message', listener),
+                }),
+            }
+            : {}),
         ...(options.deferAfter === undefined
             ? {}
             : { deferAfter: options.deferAfter }),
@@ -132,14 +146,17 @@ export async function start(options) {
             signal,
             identifyInterval,
             write: options.write,
+            stores: project.storeBackend,
             onReady: ({ user, guilds }) => online(user, guilds),
             onRestart: (index, why) => log.warn(`Process ${index + 1} of ${processes} stopped by itself (${why}): starting it again. Its servers are back in a moment.`),
         });
+        await project.closeStores();
         if (code === 0)
             log.success('Disconnected');
         return code;
     }
     catch (error) {
+        await project.closeStores();
         if (signal.aborted)
             return 0;
         explain(error, log);
@@ -168,6 +185,7 @@ async function run(project, connection, stopped, connected, { tasks = true } = {
         project.stopTasks();
         memory.stop();
         await bot?.close();
+        await project.closeStores();
     }
 }
 /** The whole bot in this process. */

package/dist/commands/router.js

@@ -139,6 +139,7 @@ export class CommandRouter {
             name,
             what: 'command',
             reporter: this.#options,
+            guildId: place.guild?.id ?? null,
             defer: () => interaction.defer(),
             unanswered: 'finished without answering: the person sees "The application did not respond". Call interaction.reply() in run.',
             run: () => command.run(context),

package/dist/components/router.js

@@ -150,6 +150,7 @@ export class ComponentRouter {
             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/events/router.d.ts

@@ -41,6 +41,9 @@ export declare class EventRouter {
         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;
+    /**
+     * Runs the handlers of an event with what they receive, for the server
+     * it happened in (what a store per server reads).
+     */
+    emit<Name extends EventName>(name: Name, context: EventContexts[Name], guildId?: string | null): 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';
@@ -106,7 +107,7 @@ export class EventRouter {
                     this.emit(source.name, {
                         ...context,
                         ...translation(ctx, audienceLocale({ guild })),
-                    });
+                    }, guild?.id ?? null);
                 }
             };
             const preparing = source.prepare?.(ctx, data);
@@ -115,8 +116,11 @@ export class EventRouter {
             preparing.then(deliver, (error) => this.#onSkipped(source.name, error));
         });
     }
-    /** 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).
+     */
+    emit(name, context, guildId = null) {
         const handlers = this.#handlers.get(name);
         if (!handlers)
             return;
@@ -127,7 +131,7 @@ export class EventRouter {
             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));
+            new Promise(resolve => resolve(withGuild(guildId, () => event.handler(frozen)))).catch((error) => this.#onError(file, error));
         }
     }
 }

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;
 }
 /**

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';
@@ -81,7 +82,7 @@ export function runInteraction(options) {
     sleep(reporter.deferAfter ?? 2000, undefined, { signal: stop.signal })
         .then(() => options.defer())
         .catch(() => { });
-    new Promise(resolve => resolve(options.run()))
+    new Promise(resolve => resolve(withGuild(options.guildId, options.run)))
         .then(() => {
         if (!interaction.answered) {
             reporter.onWarning(file, `${name} ${options.unanswered}`);

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>;

package/dist/store/declaration.js

@@ -0,0 +1,53 @@
+// What a file declares with `store()`, checked when it loads, so a wrong
+// scope or expiration is explained before anything is kept; the store is
+// then bound to the name of its export, which names its data.
+import { DURATION_EXAMPLE, parseDuration } from '../util/duration.js';
+import { bindStore, isStoreDeclaration, storeStateOf, } from './store.js';
+const fail = (message) => {
+    throw new TypeError(message);
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const KEYS = ['scope', 'expires'];
+const SCOPES = ['guild', 'global'];
+/** What a name can be: a file in `data/` is called after it. */
+const NAME = /^[\w.-]+$/;
+/**
+ * A store, declared anywhere in `src/` with `store()` and exported: the
+ * name of the export is the name of the store.
+ */
+export const storeDeclaration = {
+    one: 'store',
+    many: 'stores',
+    is: isStoreDeclaration,
+    list: false,
+    read(value, { name }) {
+        const config = storeStateOf(value)?.config;
+        if (!isRecord(config)) {
+            return fail(`store() takes an object, or nothing: store<Warning[]>({ expires: '30d' }).`);
+        }
+        for (const key of Object.keys(config)) {
+            if (!KEYS.includes(key)) {
+                fail(`"${key}" is not something a store has. It can have: ${KEYS.join(', ')}.`);
+            }
+        }
+        if (!NAME.test(name)) {
+            fail(`"${name}" can't name a store: the name of the export is the name of the store and of its file in data/, made of letters, digits, _ . and -.`);
+        }
+        const scope = (config.scope ?? 'guild');
+        if (!SCOPES.includes(scope)) {
+            fail(`"scope" is 'guild' (the data is kept per server, the default) or 'global' (one set of data for the whole bot), got ${JSON.stringify(config.scope)}.`);
+        }
+        let expires = null;
+        if (config.expires !== undefined) {
+            const ms = typeof config.expires === 'string'
+                ? parseDuration(config.expires)
+                : null;
+            if (ms === null || ms < 1000) {
+                fail(`"expires" is how long a value is kept: ${DURATION_EXAMPLE}, 1 s at least. Got ${JSON.stringify(config.expires)}.`);
+            }
+            expires = ms;
+        }
+        bindStore(value, { name, scope, expires });
+        return Object.freeze({ name, scope, expires });
+    },
+};

package/dist/store/file-backend.d.ts

@@ -0,0 +1,22 @@
+import { type StoreBackend, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
+/** The folder of a project where the stores keep their files. */
+export declare const DATA_FOLDER = "data";
+export interface FileStoreBackendOptions {
+    /** How long a change waits for others before the file is written. */
+    writeDelay?: number;
+    /** How often expired entries are dropped. */
+    sweepEvery?: number;
+    now?: () => number;
+}
+/** The data of every store, one file each, loaded on first use. */
+export declare class FileStoreBackend implements StoreBackend {
+    #private;
+    constructor(dir: string, options?: FileStoreBackendOptions);
+    /** The file of a store. */
+    file(store: string): string;
+    get(store: string, key: StoreKeyParts): Promise<StoreEntry | undefined>;
+    set(store: string, key: StoreKeyParts, entry: StoreEntry): Promise<void>;
+    delete(store: string, key: StoreKeyParts): Promise<boolean>;
+    entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    close(): Promise<void>;
+}

package/dist/store/file-backend.js

@@ -0,0 +1,172 @@
+// The default backend: one JSON file per store in the `data/` folder of
+// the project, kept in memory and written back shortly after each change,
+// atomically (a temporary file, then a rename), so a crash never leaves a
+// half-written file. What is pending when the process exits is written
+// then. Expired entries are dropped when a file is read, when they are
+// asked for, and by a sweep every minute, so a file never grows forever.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { alive, decodeKey, encodeKey, startsWith, } from './backend.js';
+/** The folder of a project where the stores keep their files. */
+export const DATA_FOLDER = 'data';
+/** A name a file can be called: what an export is called. */
+const FILE_NAME = /^[\w.-]+$/;
+/** The data of every store, one file each, loaded on first use. */
+export class FileStoreBackend {
+    #dir;
+    #stores = new Map();
+    #dirty = new Set();
+    #now;
+    #writeDelay;
+    #writeTimer = null;
+    #sweeper;
+    #onExit;
+    constructor(dir, options = {}) {
+        this.#dir = dir;
+        this.#now = options.now ?? Date.now;
+        this.#writeDelay = options.writeDelay ?? 100;
+        this.#sweeper = setInterval(() => this.#sweep(), options.sweepEvery ?? 60_000);
+        this.#sweeper.unref();
+        // What was changed in the last moments is not lost with the process.
+        this.#onExit = () => this.#flush();
+        process.on('exit', this.#onExit);
+    }
+    /** The file of a store. */
+    file(store) {
+        return join(this.#dir, `${store}.json`);
+    }
+    #load(store) {
+        let entries = this.#stores.get(store);
+        if (entries)
+            return entries;
+        if (!FILE_NAME.test(store)) {
+            throw new TypeError(`"${store}" can't name a store: its name is the name of its export, made of letters, digits, _ . and -.`);
+        }
+        entries = new Map();
+        let text = null;
+        try {
+            text = readFileSync(this.file(store), 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (text !== null) {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+                if (parsed?.version !== 1 || !Array.isArray(parsed.entries)) {
+                    throw new Error('not a store file');
+                }
+            }
+            catch {
+                throw new Error(`${this.file(store)} is not a file ChapterJS wrote: fix it, or delete it to start the store empty.`);
+            }
+            const now = this.#now();
+            for (const [key, value, expiresAt] of parsed.entries) {
+                const entry = { value, expiresAt };
+                if (alive(entry, now))
+                    entries.set(encodeKey(key), entry);
+            }
+        }
+        this.#stores.set(store, entries);
+        return entries;
+    }
+    #changed(store) {
+        this.#dirty.add(store);
+        if (this.#writeTimer)
+            return;
+        this.#writeTimer = setTimeout(() => this.#flush(), this.#writeDelay);
+        this.#writeTimer.unref();
+    }
+    /** Writes every store that changed. */
+    #flush() {
+        if (this.#writeTimer) {
+            clearTimeout(this.#writeTimer);
+            this.#writeTimer = null;
+        }
+        if (this.#dirty.size === 0)
+            return;
+        mkdirSync(this.#dir, { recursive: true });
+        for (const store of this.#dirty) {
+            const entries = this.#stores.get(store);
+            if (!entries)
+                continue;
+            const file = {
+                version: 1,
+                entries: [...entries].map(([key, { value, expiresAt }]) => [
+                    decodeKey(key),
+                    value,
+                    expiresAt,
+                ]),
+            };
+            const path = this.file(store);
+            const temporary = `${path}.${process.pid}.tmp`;
+            writeFileSync(temporary, `${JSON.stringify(file)}\n`);
+            renameSync(temporary, path);
+        }
+        this.#dirty.clear();
+    }
+    #sweep() {
+        const now = this.#now();
+        for (const [store, entries] of this.#stores) {
+            let dropped = false;
+            for (const [key, entry] of entries) {
+                if (!alive(entry, now)) {
+                    entries.delete(key);
+                    dropped = true;
+                }
+            }
+            if (dropped)
+                this.#changed(store);
+        }
+    }
+    async get(store, key) {
+        const entries = this.#load(store);
+        const encoded = encodeKey(key);
+        const entry = entries.get(encoded);
+        if (!entry)
+            return undefined;
+        if (alive(entry, this.#now()))
+            return entry;
+        entries.delete(encoded);
+        this.#changed(store);
+        return undefined;
+    }
+    async set(store, key, entry) {
+        this.#load(store).set(encodeKey(key), entry);
+        this.#changed(store);
+    }
+    async delete(store, key) {
+        const entries = this.#load(store);
+        const encoded = encodeKey(key);
+        const entry = entries.get(encoded);
+        if (!entry)
+            return false;
+        entries.delete(encoded);
+        this.#changed(store);
+        return alive(entry, this.#now());
+    }
+    async entries(store, prefix) {
+        const entries = this.#load(store);
+        const now = this.#now();
+        const listed = [];
+        for (const [encoded, entry] of entries) {
+            const key = decodeKey(encoded);
+            if (!startsWith(key, prefix))
+                continue;
+            if (alive(entry, now))
+                listed.push({ key, ...entry });
+            else {
+                entries.delete(encoded);
+                this.#changed(store);
+            }
+        }
+        return listed;
+    }
+    async close() {
+        clearInterval(this.#sweeper);
+        process.off('exit', this.#onExit);
+        this.#flush();
+    }
+}

package/dist/store/ipc-backend.d.ts

@@ -0,0 +1,53 @@
+import type { StoreBackend, StoreEntry, StoreKeyParts, StoreListedEntry } from './backend.js';
+/** What a process asks the first one. */
+export type StoreRequest = {
+    type: 'store';
+    id: number;
+} & ({
+    op: 'get';
+    store: string;
+    key: StoreKeyParts;
+} | {
+    op: 'set';
+    store: string;
+    key: StoreKeyParts;
+    entry: StoreEntry;
+} | {
+    op: 'delete';
+    store: string;
+    key: StoreKeyParts;
+} | {
+    op: 'entries';
+    store: string;
+    prefix: StoreKeyParts;
+});
+/** What the first process answers. */
+export interface StoreReply {
+    type: 'store';
+    id: number;
+    result?: unknown;
+    error?: string;
+}
+/** The two ends of a channel, as a process and its child have them. */
+export interface Channel<Out, In> {
+    send(message: Out): void;
+    on(listener: (message: In) => void): void;
+}
+export declare const isStoreRequest: (message: unknown) => message is StoreRequest;
+export declare const isStoreReply: (message: unknown) => message is StoreReply;
+/** The backend of a process that is not the first: every call is a message. */
+export declare class IpcStoreBackend implements StoreBackend {
+    #private;
+    constructor(channel: Channel<StoreRequest, unknown>);
+    get(store: string, key: StoreKeyParts): Promise<StoreEntry | undefined>;
+    set(store: string, key: StoreKeyParts, entry: StoreEntry): Promise<void>;
+    delete(store: string, key: StoreKeyParts): Promise<boolean>;
+    entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    close(): Promise<void>;
+}
+/**
+ * In the first process: answers the requests of one other process with
+ * the real backend. Returns what to call with each message received from
+ * that process; a message that is not a request is ignored.
+ */
+export declare function serveStores(backend: StoreBackend, reply: (message: StoreReply) => void): (message: unknown) => void;

package/dist/store/ipc-backend.js

@@ -0,0 +1,87 @@
+// A bot split over several processes has one copy of its data: the first
+// process keeps it (with the file backend) and the others ask it over
+// IPC, the channel they already share with it. Each process then sees the
+// same thing, whichever shard a command was used on.
+export const isStoreRequest = (message) => typeof message === 'object' &&
+    message !== null &&
+    message.type === 'store' &&
+    'op' in message;
+export const isStoreReply = (message) => typeof message === 'object' &&
+    message !== null &&
+    message.type === 'store' &&
+    !('op' in message);
+/** The backend of a process that is not the first: every call is a message. */
+export class IpcStoreBackend {
+    #channel;
+    #waiting = new Map();
+    #lastId = 0;
+    constructor(channel) {
+        this.#channel = channel;
+        channel.on(message => {
+            if (!isStoreReply(message))
+                return;
+            const pending = this.#waiting.get(message.id);
+            if (!pending)
+                return;
+            this.#waiting.delete(message.id);
+            if (message.error !== undefined)
+                pending.reject(new Error(message.error));
+            else
+                pending.resolve(message.result);
+        });
+    }
+    #ask(request) {
+        const id = ++this.#lastId;
+        return new Promise((resolve, reject) => {
+            this.#waiting.set(id, {
+                resolve: resolve,
+                reject,
+            });
+            this.#channel.send({ type: 'store', id, ...request });
+        });
+    }
+    get(store, key) {
+        return this.#ask({ op: 'get', store, key });
+    }
+    set(store, key, entry) {
+        return this.#ask({ op: 'set', store, key, entry });
+    }
+    delete(store, key) {
+        return this.#ask({ op: 'delete', store, key });
+    }
+    entries(store, prefix) {
+        return this.#ask({ op: 'entries', store, prefix });
+    }
+    async close() {
+        // Nothing is kept here: the first process writes.
+    }
+}
+/**
+ * In the first process: answers the requests of one other process with
+ * the real backend. Returns what to call with each message received from
+ * that process; a message that is not a request is ignored.
+ */
+export function serveStores(backend, reply) {
+    return message => {
+        if (!isStoreRequest(message))
+            return;
+        const { id } = message;
+        const run = () => {
+            switch (message.op) {
+                case 'get':
+                    return backend.get(message.store, message.key);
+                case 'set':
+                    return backend.set(message.store, message.key, message.entry);
+                case 'delete':
+                    return backend.delete(message.store, message.key);
+                case 'entries':
+                    return backend.entries(message.store, message.prefix);
+            }
+        };
+        run().then(result => reply({ type: 'store', id, result }), (error) => reply({
+            type: 'store',
+            id,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    };
+}

package/dist/store/scope.d.ts

@@ -0,0 +1,8 @@
+/** Runs `fn` for a server (or for none, with `null`). */
+export declare function withGuild<T>(guildId: string | null, fn: () => T): T;
+/**
+ * The id of the server the current function runs for: `null` when it runs
+ * for none (a task, a private message), `undefined` outside any function
+ * the framework runs.
+ */
+export declare function currentGuildId(): string | null | undefined;

package/dist/store/scope.js

@@ -0,0 +1,20 @@
+// The server the code runs for, known to the framework and not written by
+// the user: a store per server reads it, so `warnings.get(member.id)` in a
+// command is the warnings of the server the command was used in. Set by
+// the routers around every function they run, on an asynchronous context
+// of Node, so it follows the `await`s into the files the function imports.
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** The id of the server the current function runs for, or `null` for none. */
+const scope = new AsyncLocalStorage();
+/** Runs `fn` for a server (or for none, with `null`). */
+export function withGuild(guildId, fn) {
+    return scope.run(guildId, fn);
+}
+/**
+ * The id of the server the current function runs for: `null` when it runs
+ * for none (a task, a private message), `undefined` outside any function
+ * the framework runs.
+ */
+export function currentGuildId() {
+    return scope.getStore();
+}

package/dist/store/store.d.ts

@@ -0,0 +1,115 @@
+import type { Duration } from '../commands/command.js';
+import type { Guild } from '../structures/guild.js';
+/** Where the data of a store is kept apart: per server, or one for the whole bot. */
+export type StoreScope = 'guild' | 'global';
+/** What a file gives to `store()`. */
+export interface StoreConfig {
+    /**
+     * `'guild'` (the default): the data is kept per server, and a function
+     * that runs in a server reads and writes the data of that server, with
+     * nothing to say. `'global'`: one set of data for the whole bot.
+     */
+    scope?: StoreScope;
+    /**
+     * How long a value is kept, unless `set()` says otherwise: a number and
+     * a unit, `s`, `m`, `h` or `d`, like `'10m'`, `'1d'` or `'1h30m'`. Kept
+     * forever by default.
+     */
+    expires?: Duration;
+}
+/**
+ * A key of a store: a text, or a list of texts for a key made of several
+ * parts (`[channel.id, message.id]`), which `entries()` can then list by
+ * prefix.
+ */
+export type StoreKey = string | readonly string[];
+/** What `set()` and `update()` take besides the value. */
+export interface StoreSetOptions {
+    /**
+     * How long the value is kept: a duration like `'10m'`, a `Date`, or
+     * `null` to keep it forever. The `expires` of the store by default.
+     */
+    expires?: Duration | Date | null;
+}
+/** One entry of a store, as `entries()` lists them. */
+export interface StoreEntry<T> {
+    /** The key, every part of it (the server left out for a store per server). */
+    key: readonly string[];
+    value: T;
+    /** When the value expires, or `null` when it is kept forever. */
+    expires: Date | null;
+}
+/** A store, read and written for one server or for the whole bot. */
+export interface ScopedStore<T> {
+    /** The value at `key`, or `undefined` when there is none, or it expired. */
+    get(key: StoreKey): Promise<T | undefined>;
+    /** Keeps `value` at `key`. The value must be JSON: no `Date`, `Map` or class instance. */
+    set(key: StoreKey, value: T, options?: StoreSetOptions): Promise<void>;
+    /**
+     * Reads the value at `key` and keeps what `change` returns, in one go.
+     * `change` receives `undefined` when there is no value yet. The
+     * expiration stays what it was, unless `options` say otherwise.
+     */
+    update(key: StoreKey, change: (current: T | undefined) => T, options?: StoreSetOptions): Promise<T>;
+    /** Forgets the value at `key`. `true` when there was one. */
+    delete(key: StoreKey): Promise<boolean>;
+    /**
+     * Every entry, or the ones whose key starts with `prefix`, in no
+     * particular order. Expired ones are left out.
+     */
+    entries(prefix?: StoreKey): Promise<StoreEntry<T>[]>;
+    /**
+     * How long the value at `key` is still kept, in milliseconds: `null`
+     * when it is kept forever, `undefined` when there is no value.
+     */
+    ttl(key: StoreKey): Promise<number | null | undefined>;
+}
+/** What `store()` returns: a declaration the framework finds in the exports of a file. */
+export interface Store<T> extends ScopedStore<T> {
+    /**
+     * The same store, for one server: what a task, or a function that runs
+     * outside a server, uses to read and write the data of that server.
+     */
+    in(guild: Guild | string): ScopedStore<T>;
+}
+/** A store as the loader knows it: its config, and once loaded, its name. */
+export interface StoreState {
+    readonly config: unknown;
+    /** The name of the export that declares it, once bound by the loader. */
+    name?: string;
+    /** What `read` found in the config. */
+    scope: StoreScope;
+    /** The default expiration, in ms, or `null` for never. */
+    expires: number | null;
+}
+/** The state of a declared store, if the value is one. */
+export declare function storeStateOf(value: unknown): StoreState | undefined;
+export declare const isStoreDeclaration: (value: unknown) => boolean;
+/** Binds a declared store to the name of its export. */
+export declare function bindStore(declared: unknown, bound: {
+    name: string;
+    scope: StoreScope;
+    expires: number | null;
+}): void;
+/**
+ * Refuses what would not survive a trip through JSON: a `Date` would come
+ * back as a text, a `Map` as `{}`, a class instance as a plain object.
+ */
+export declare function checkJson(value: unknown, path?: string): void;
+/**
+ * Declares a store: data the bot keeps from one restart to the next,
+ * typed by what it holds. Export the result from any file of `src/`: the
+ * name of the export is the name of the store, and its file in `data/`.
+ * Per server unless `scope: 'global'` is given, with an expiration if
+ * `expires` is.
+ *
+ * ```ts
+ * import { store } from 'chapterjs';
+ *
+ * export const warnings = store<Warning[]>({ expires: '30d' });
+ *
+ * // In a command, in a server:
+ * await warnings.update(member.id, (list = []) => [...list, warning]);
+ * ```
+ */
+export declare function store<T>(config?: StoreConfig): Store<T>;

package/dist/store/store.js

@@ -0,0 +1,200 @@
+// What a file declares with `store()`: a place to keep data from one
+// restart to the next, per server by default, typed by what it holds,
+// with an expiration if wanted. Named by its export, like a button:
+// `export const warnings = store<Warning[]>()` is the store `warnings`.
+// What `store()` returns works once the loader bound it to that name and
+// the bot runs; the data itself lives in a backend (`backend.ts`).
+import { parseDuration } from '../util/duration.js';
+import { storeBackend, } from './backend.js';
+import { currentGuildId } from './scope.js';
+const STATE = Symbol.for('chapterjs.store');
+/** The state of a declared store, if the value is one. */
+export function storeStateOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    return value[STATE];
+}
+export const isStoreDeclaration = (value) => storeStateOf(value) !== undefined;
+/** Binds a declared store to the name of its export. */
+export function bindStore(declared, bound) {
+    const state = storeStateOf(declared);
+    if (!state)
+        throw new TypeError('Not a store.');
+    state.name = bound.name;
+    state.scope = bound.scope;
+    state.expires = bound.expires;
+}
+const parts = (key) => {
+    const list = typeof key === 'string' ? [key] : [...key];
+    if (list.length === 0) {
+        throw new TypeError('A key of a store is a text, or a list of texts with at least one.');
+    }
+    for (const part of list) {
+        if (typeof part !== 'string') {
+            throw new TypeError(`A key of a store is made of texts, got ${JSON.stringify(part) ?? typeof part}. Write an id as a text: member.id, not a number.`);
+        }
+    }
+    return list;
+};
+/**
+ * Refuses what would not survive a trip through JSON: a `Date` would come
+ * back as a text, a `Map` as `{}`, a class instance as a plain object.
+ */
+export function checkJson(value, path = 'the value') {
+    if (value === undefined) {
+        throw new TypeError(`${path} is undefined: a store keeps JSON. To forget a value, use delete().`);
+    }
+    if (value === null)
+        return;
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return;
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new TypeError(`${path} is ${value}, which JSON can't hold: a store keeps JSON.`);
+            }
+            return;
+        case 'bigint':
+        case 'function':
+        case 'symbol':
+            throw new TypeError(`${path} is a ${typeof value}, which JSON can't hold: a store keeps JSON (texts, numbers, booleans, lists and plain objects).`);
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => checkJson(item, `${path}[${index}]`));
+        return;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype) {
+        const name = value.constructor?.name ??
+            'an object of a class';
+        throw new TypeError(`${path} is a ${name}, which JSON can't hold: a store keeps JSON (texts, numbers, booleans, lists and plain objects). Keep what you need of it: an id, a text, a number.`);
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined)
+            checkJson(item, `${path}.${key}`);
+    }
+}
+/** When a value set now expires, from what was asked. */
+function expiresAt(options, fallback, now) {
+    if (!options || options.expires === undefined) {
+        return fallback === null ? null : now + fallback;
+    }
+    const { expires } = options;
+    if (expires === null)
+        return null;
+    if (expires instanceof Date) {
+        const ms = expires.getTime();
+        if (!Number.isFinite(ms)) {
+            throw new TypeError('"expires" is a Date that is not a valid date.');
+        }
+        return ms;
+    }
+    const ms = typeof expires === 'string' ? parseDuration(expires) : null;
+    if (ms === null || ms < 1000) {
+        throw new TypeError(`"expires" is a duration (a number and a unit: s, m, h or d, like '10m' or '1d', 1 s at least), a Date, or null to keep the value forever. Got ${JSON.stringify(expires)}.`);
+    }
+    return now + ms;
+}
+/** The store as its functions see it: the backend, the name, the scope prefix. */
+function scoped(state, guildOf) {
+    const ready = () => {
+        if (!state.name) {
+            throw new Error('This store was not loaded by ChapterJS: a store is exported from a file of src/ (export const name = store()), and used once the bot started.');
+        }
+        const backend = storeBackend();
+        if (state.scope === 'global') {
+            return { backend, name: state.name, prefix: [] };
+        }
+        const guildId = guildOf();
+        if (!guildId) {
+            throw new Error(`${state.name} is a store per server, and this code does not run in one: use ${state.name}.in(guild) to say which server, or declare the store with scope: 'global'.`);
+        }
+        return { backend, name: state.name, prefix: [guildId] };
+    };
+    const full = (prefix, key) => [
+        ...prefix,
+        ...parts(key),
+    ];
+    const set = async (key, value, options, keep) => {
+        const { backend, name, prefix } = ready();
+        checkJson(value);
+        const now = Date.now();
+        const at = keep !== undefined && (!options || options.expires === undefined)
+            ? keep
+            : expiresAt(options, state.expires, now);
+        await backend.set(name, full(prefix, key), { value, expiresAt: at });
+    };
+    return {
+        async get(key) {
+            const { backend, name, prefix } = ready();
+            const entry = await backend.get(name, full(prefix, key));
+            return entry?.value;
+        },
+        set: (key, value, options) => set(key, value, options, undefined),
+        async update(key, change, options) {
+            const { backend, name, prefix } = ready();
+            const entry = await backend.get(name, full(prefix, key));
+            const next = change(entry?.value);
+            await set(key, next, options, entry ? entry.expiresAt : undefined);
+            return next;
+        },
+        async delete(key) {
+            const { backend, name, prefix } = ready();
+            return backend.delete(name, full(prefix, key));
+        },
+        async entries(prefixKey) {
+            const { backend, name, prefix } = ready();
+            const listed = await backend.entries(name, prefixKey === undefined ? prefix : full(prefix, prefixKey));
+            return listed.map(entry => ({
+                key: entry.key.slice(prefix.length),
+                value: entry.value,
+                expires: entry.expiresAt === null ? null : new Date(entry.expiresAt),
+            }));
+        },
+        async ttl(key) {
+            const { backend, name, prefix } = ready();
+            const entry = await backend.get(name, full(prefix, key));
+            if (!entry)
+                return undefined;
+            return entry.expiresAt === null
+                ? null
+                : Math.max(0, entry.expiresAt - Date.now());
+        },
+    };
+}
+/**
+ * Declares a store: data the bot keeps from one restart to the next,
+ * typed by what it holds. Export the result from any file of `src/`: the
+ * name of the export is the name of the store, and its file in `data/`.
+ * Per server unless `scope: 'global'` is given, with an expiration if
+ * `expires` is.
+ *
+ * ```ts
+ * import { store } from 'chapterjs';
+ *
+ * export const warnings = store<Warning[]>({ expires: '30d' });
+ *
+ * // In a command, in a server:
+ * await warnings.update(member.id, (list = []) => [...list, warning]);
+ * ```
+ */
+export function store(config = {}) {
+    const state = { config, scope: 'guild', expires: null };
+    const guildIdOf = (guild) => {
+        const id = typeof guild === 'string' ? guild : guild?.id;
+        if (typeof id !== 'string' || id === '') {
+            throw new TypeError('in() takes a server (a Guild) or its id, like warnings.in(guild) or warnings.in(guild.id).');
+        }
+        return id;
+    };
+    const declared = {
+        ...scoped(state, () => currentGuildId() ?? null),
+        in: guild => {
+            const id = guildIdOf(guild);
+            return scoped(state, () => id);
+        },
+    };
+    Object.defineProperty(declared, STATE, { value: state });
+    return declared;
+}

package/dist/tasks/scheduler.js

@@ -1,6 +1,7 @@
 // Runs the tasks of the project when they are due. Behind an interface:
 // this one keeps timers in the process; a bot on several machines would
 // share one through another implementation, with no change to the files.
+import { withGuild } from '../store/scope.js';
 import { describeSchedule, nextRun, scheduleKey } from './schedule.js';
 /** The longest a timer of Node can wait. */
 const MAX_DELAY = 2 ** 31 - 1;
@@ -98,7 +99,7 @@ export class TimerScheduler {
             return;
         }
         scheduled.running = true;
-        new Promise(resolve => resolve(scheduled.entry.task.run(Object.freeze({ ...context, now }))))
+        new Promise(resolve => resolve(withGuild(null, () => scheduled.entry.task.run(Object.freeze({ ...context, now })))))
             .catch((error) => this.#options.onError(file, error))
             .finally(() => {
             scheduled.running = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterjs",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "The Discord framework",
   "type": "module",
   "license": "MIT",