chapterjs 0.2.2 → 0.3.0

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/memory-backend.d.ts

@@ -0,0 +1,15 @@
+import { type StoreBackend, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
+/** The data of every store, in memory, forgotten with the process. */
+export declare class MemoryStoreBackend implements StoreBackend {
+    #private;
+    constructor(options?: {
+        now?: () => number;
+    });
+    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[]>;
+    /** Forgets everything: what a test does with its stores stays in it. */
+    clear(): void;
+    close(): Promise<void>;
+}

package/dist/store/memory-backend.js

@@ -0,0 +1,56 @@
+// A backend that keeps the data of the stores in memory and nowhere else:
+// what `chapterjs test` gives a bot under test, so a test never touches
+// the `data/` folder of the project and starts from nothing every time.
+import { alive, decodeKey, encodeKey, startsWith, } from './backend.js';
+/** The data of every store, in memory, forgotten with the process. */
+export class MemoryStoreBackend {
+    #stores = new Map();
+    #now;
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+    }
+    #store(name) {
+        let store = this.#stores.get(name);
+        if (!store) {
+            store = new Map();
+            this.#stores.set(name, store);
+        }
+        return store;
+    }
+    async get(store, key) {
+        const entry = this.#store(store).get(encodeKey(key));
+        if (!entry)
+            return undefined;
+        if (!alive(entry, this.#now())) {
+            this.#store(store).delete(encodeKey(key));
+            return undefined;
+        }
+        return entry;
+    }
+    async set(store, key, entry) {
+        this.#store(store).set(encodeKey(key), entry);
+    }
+    async delete(store, key) {
+        return this.#store(store).delete(encodeKey(key));
+    }
+    async entries(store, prefix) {
+        const now = this.#now();
+        const result = [];
+        for (const [encoded, entry] of this.#store(store)) {
+            const key = decodeKey(encoded);
+            if (!startsWith(key, prefix))
+                continue;
+            if (!alive(entry, now)) {
+                this.#store(store).delete(encoded);
+                continue;
+            }
+            result.push({ key, ...entry });
+        }
+        return result;
+    }
+    /** Forgets everything: what a test does with its stores stays in it. */
+    clear() {
+        this.#stores.clear();
+    }
+    async close() { }
+}

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