@mycroblog/mybot 0.0.0-placeholder.0

package/dist/schedule.js

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: MIT
+import { Cron } from "croner";
+const fields = [
+    { name: "minute", lo: 0, hi: 59 },
+    { name: "hour", lo: 0, hi: 23 },
+    { name: "day of the month", lo: 1, hi: 31 },
+    { name: "month", lo: 1, hi: 12 },
+    { name: "day of the week", lo: 0, hi: 7 },
+];
+/** The most days of each month, February in a leap year. */
+const daysIn = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/** How far next and prev look: eight years hold every day of the month and of the week in every combination. */
+const searchSpan = (8 * 366 + 1) * 24 * 3_600_000;
+const digits = /^[0-9]+$/;
+/** The error of parseSchedule and Bot.every for an expression or a time zone that mybot does not take. */
+export class ScheduleError extends Error {
+    name = "ScheduleError";
+}
+/** Parses a number of a field, digits alone. */
+function value(text, f) {
+    const v = Number(text);
+    if (!digits.test(text) || v < f.lo || v > f.hi)
+        throw new Error(`the ${f.name} "${text}" is not a number from ${String(f.lo)} to ${String(f.hi)}`);
+    return v;
+}
+/** Parses one field into the set of its values, as the Go library does. */
+function parseField(field, f) {
+    const set = new Set();
+    for (const part of field.split(",")) {
+        const slash = part.indexOf("/");
+        const range = slash < 0 ? part : part.slice(0, slash);
+        const stepText = slash < 0 ? null : part.slice(slash + 1);
+        let from = f.lo;
+        let to = f.hi;
+        if (range === "*") {
+            // every value
+        }
+        else if (range.includes("-")) {
+            const dash = range.indexOf("-");
+            from = value(range.slice(0, dash), f);
+            to = value(range.slice(dash + 1), f);
+            if (from > to)
+                throw new Error(`the ${f.name} range "${range}" runs backwards`);
+        }
+        else {
+            if (stepText !== null)
+                throw new Error(`the ${f.name} step "${part}" needs * or a range before the /`);
+            from = to = value(range, f);
+        }
+        let step = 1;
+        if (stepText !== null) {
+            const n = Number(stepText);
+            const most = f.hi - f.lo + 1;
+            if (!digits.test(stepText) || n < 1 || n > most)
+                throw new Error(`the ${f.name} step "${stepText}" is not a number from 1 to ${String(most)}`);
+            step = n;
+        }
+        for (let v = from; v <= to; v += step)
+            set.add(v);
+    }
+    return set;
+}
+/** The wall-clock hour and minute of at in timeZone. */
+function wallClock(format, at) {
+    let hour = -1;
+    let minute = -1;
+    for (const p of format.formatToParts(at)) {
+        if (p.type === "hour")
+            hour = Number(p.value) % 24;
+        else if (p.type === "minute")
+            minute = Number(p.value);
+    }
+    return { hour, minute };
+}
+/**
+ * A parsed cron expression of five fields, minute hour day-of-month month day-of-week, in a time zone (ADR-0094 §5).
+ * Each field is *, a number, a range a-b, a step * /n or a-b/n, or a list of those separated by commas; the day of the
+ * week is 0-7, where 0 and 7 are Sunday. When both the day of the month and the day of the week are other than *, a
+ * day matches when either does, as in cron. A field of seconds, the aliases such as @daily, names of months and days,
+ * and the other extensions of some crons (?, L, W, #) are refused: mybot takes the same expressions as the Go library,
+ * and uses croner to compute the times alone.
+ *
+ * The times of a Schedule are wall-clock times of its time zone: one that a daylight saving time change skips does not
+ * happen, and one that the change repeats happens once, at its first occurrence. Times are milliseconds since the Unix
+ * epoch.
+ */
+export class Schedule {
+    /** The expression of the schedule. */
+    expr;
+    /** The IANA time zone of the schedule, "UTC" by default. */
+    timeZone;
+    #cron;
+    #hours;
+    #minutes;
+    #format;
+    /** Use parseSchedule. */
+    constructor(expr, timeZone, hours, minutes) {
+        this.expr = expr;
+        this.timeZone = timeZone;
+        this.#hours = hours;
+        this.#minutes = minutes;
+        this.#format = new Intl.DateTimeFormat("en-US", { timeZone, hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
+        // legacyMode: a day matches when the day of the month or the day of the week does, as in cron.
+        this.#cron = new Cron(expr, { paused: true, mode: "5-part", timezone: timeZone, legacyMode: true });
+    }
+    /**
+     * Parses the cron expression expr in the IANA time zone timeZone, such as "Asia/Tokyo"; "" or absent is UTC. It
+     * throws a ScheduleError for an expression or a time zone it does not take.
+     */
+    static parse(expr, timeZone = "") {
+        const tz = timeZone === "" ? "UTC" : timeZone;
+        try {
+            new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        }
+        catch {
+            throw new ScheduleError(`mybot: the time zone "${timeZone}" is no IANA time zone`);
+        }
+        if (expr.trim().startsWith("@")) {
+            throw new ScheduleError(`mybot: the cron expression "${expr}": aliases such as @daily are not supported: write the five fields`);
+        }
+        const parts = expr.split(/\s+/).filter((p) => p !== "");
+        if (parts.length === 6) {
+            throw new ScheduleError(`mybot: the cron expression "${expr}": a field of seconds is not supported: write the five fields minute hour day month weekday`);
+        }
+        if (parts.length !== 5) {
+            throw new ScheduleError(`mybot: the cron expression "${expr}" has ${String(parts.length)} fields, not the five minute hour day month weekday`);
+        }
+        let sets;
+        try {
+            sets = parts.map((p, i) => parseField(p, fields[i]));
+        }
+        catch (error) {
+            throw new ScheduleError(`mybot: the cron expression "${expr}": ${error.message}`);
+        }
+        const [minutes, hours, dom, months] = sets;
+        // A day exists unless the day of the month alone decides, and no month has it: "0 0 30 2 *".
+        if (parts[2] !== "*" && parts[4] === "*" && ![...months].some((m) => [...dom].some((d) => d <= (daysIn[m] ?? 0)))) {
+            throw new ScheduleError(`mybot: the cron expression "${expr}" names no day that exists`);
+        }
+        try {
+            return new Schedule(parts.join(" "), tz, hours, minutes);
+        }
+        catch (error) {
+            throw new ScheduleError(`mybot: the cron expression "${expr}": ${error.message}`);
+        }
+    }
+    /** Whether at is a wall-clock time of the schedule, and not one that croner moved out of a skipped hour. */
+    #onTime(at) {
+        const { hour, minute } = wallClock(this.#format, at);
+        return this.#hours.has(hour) && this.#minutes.has(minute);
+    }
+    /** The first time of the schedule after at; null when there is none in the next eight years. */
+    next(at) {
+        const end = at + searchSpan;
+        let from = at;
+        for (;;) {
+            const d = this.#cron.nextRun(new Date(from));
+            if (d === null || d.getTime() > end)
+                return null;
+            const t = d.getTime();
+            if (this.#onTime(t))
+                return t;
+            from = t;
+        }
+    }
+    /** The last time of the schedule at or before at; null when there is none in the eight years before. */
+    prev(at) {
+        const end = at - searchSpan;
+        // previousRuns finds the times before a reference in whole seconds: one second on includes at itself.
+        let ref = Math.floor(at / 1000) * 1000 + 1000;
+        for (;;) {
+            const d = this.#cron.previousRuns(1, new Date(ref))[0];
+            if (d === undefined || d.getTime() < end)
+                return null;
+            const t = d.getTime();
+            if (t <= at && this.#onTime(t))
+                return t;
+            // croner moved a skipped time after the gap, and finds it again from any reference in the gap: step back a
+            // minute at least, which passes over no time of the schedule, whose times are whole minutes.
+            ref = Math.min(ref - 60_000, t);
+        }
+    }
+}
+/** Parses the cron expression expr in the IANA time zone timeZone ("" or absent is UTC): Schedule.parse. */
+export function parseSchedule(expr, timeZone = "") {
+    return Schedule.parse(expr, timeZone);
+}

package/dist/store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Keeps what a bot must remember across restarts (ADR-0094 §6): the notifications it processed, the position of the
+ * catch-up, the last runs of the scheduled jobs, and the rotated refresh token. MemoryStore and FileStore are the
+ * implementations of the library; implement Store to keep the state elsewhere, such as in a database. One Store
+ * serves one bot process: it needs no locking between processes. Times are milliseconds since the Unix epoch.
+ */
+export type Store = {
+    /** Whether the notification id was recorded by markProcessed (and not forgotten since). */
+    isProcessed(id: string): Promise<boolean>;
+    /** Records that the notification id was processed at at. */
+    markProcessed(id: string, at: number): Promise<void>;
+    /** Drops the records of the notifications processed before before. */
+    forgetProcessed(before: number): Promise<void>;
+    /**
+     * The ID of the newest notification up to which every notification was processed, null when there is none yet. The
+     * catch-up reads the notifications back to it.
+     */
+    position(): Promise<string | null>;
+    /** Sets the position. */
+    setPosition(id: string): Promise<void>;
+    /** When the scheduled job name last ran, null when it never did. */
+    lastRun(name: string): Promise<number | null>;
+    /** Records when the scheduled job name ran. */
+    setLastRun(name: string, at: number): Promise<void>;
+    /** The refresh token saved by setRefreshToken, null when there is none. */
+    refreshToken(): Promise<string | null>;
+    /** Saves the refresh token that a renewal returned. The previous one no longer works. */
+    setRefreshToken(token: string): Promise<void>;
+};
+/**
+ * The state of a MemoryStore and the JSON document of a FileStore: the same document as the FileStore of the Go
+ * library, with the times as RFC 3339 strings, so that a bot can move between the two.
+ */
+export type StoreState = {
+    processed: Map<string, number>;
+    position: string | null;
+    lastRuns: Map<string, number>;
+    refreshToken: string | null;
+};
+/** An empty state. */
+export declare function emptyState(): StoreState;
+/** The state as the JSON document of a FileStore. */
+export declare function encodeState(s: StoreState): string;
+/** Reads the JSON document of a FileStore. */
+export declare function decodeState(text: string): StoreState;
+/** A Store in memory that calls save after every change; the base of MemoryStore and FileStore. */
+export declare abstract class StateStore implements Store {
+    #private;
+    /** Resolves to the state, once it has been read. */
+    protected abstract load(): Promise<StoreState>;
+    /** Persists the state after a change. */
+    protected abstract save(state: StoreState): Promise<void>;
+    isProcessed(id: string): Promise<boolean>;
+    markProcessed(id: string, at: number): Promise<void>;
+    forgetProcessed(before: number): Promise<void>;
+    position(): Promise<string | null>;
+    setPosition(id: string): Promise<void>;
+    lastRun(name: string): Promise<number | null>;
+    setLastRun(name: string, at: number): Promise<void>;
+    refreshToken(): Promise<string | null>;
+    setRefreshToken(token: string): Promise<void>;
+}
+/**
+ * A Store in memory, for tests. Everything is lost when the process ends, the rotated refresh token too: the next
+ * start uses the refresh token of the options again, which the server has seen used and so revokes. A bot that runs
+ * for real, all the time or started again and again, uses a FileStore or a Store of its own.
+ */
+export declare class MemoryStore extends StateStore {
+    #private;
+    protected load(): Promise<StoreState>;
+    protected save(): Promise<void>;
+}

package/dist/store.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+/** An empty state. */
+export function emptyState() {
+    return { processed: new Map(), position: null, lastRuns: new Map(), refreshToken: null };
+}
+/** The state as the JSON document of a FileStore. */
+export function encodeState(s) {
+    const doc = {
+        processed: Object.fromEntries([...s.processed].map(([id, at]) => [id, new Date(at).toISOString()])),
+    };
+    if (s.position !== null && s.position !== "")
+        doc["position"] = s.position;
+    if (s.lastRuns.size > 0)
+        doc["last_runs"] = Object.fromEntries([...s.lastRuns].map(([name, at]) => [name, new Date(at).toISOString()]));
+    if (s.refreshToken !== null && s.refreshToken !== "")
+        doc["refresh_token"] = s.refreshToken;
+    return JSON.stringify(doc, null, 2) + "\n";
+}
+/** Reads a map of RFC 3339 times. */
+function decodeTimes(value, field) {
+    const out = new Map();
+    if (value === undefined || value === null)
+        return out;
+    if (typeof value !== "object")
+        throw new Error(`mybot: the field ${field} of the state is no object`);
+    for (const [k, v] of Object.entries(value)) {
+        // The Go library writes nanoseconds, which not every runtime's Date.parse reads: milliseconds are enough.
+        const at = typeof v === "string" ? Date.parse(v.replace(/(\.\d{3})\d+/, "$1")) : Number.NaN;
+        if (Number.isNaN(at))
+            throw new Error(`mybot: the field ${field} of the state has a time that is no RFC 3339 string`);
+        out.set(k, at);
+    }
+    return out;
+}
+/** Reads the JSON document of a FileStore. */
+export function decodeState(text) {
+    const doc = JSON.parse(text);
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        throw new Error("mybot: the state is no JSON object");
+    const d = doc;
+    const str = (v, field) => {
+        if (v === undefined || v === null || v === "")
+            return null;
+        if (typeof v !== "string")
+            throw new Error(`mybot: the field ${field} of the state is no string`);
+        return v;
+    };
+    return {
+        processed: decodeTimes(d["processed"], "processed"),
+        position: str(d["position"], "position"),
+        lastRuns: decodeTimes(d["last_runs"], "last_runs"),
+        refreshToken: str(d["refresh_token"], "refresh_token"),
+    };
+}
+/** A Store in memory that calls save after every change; the base of MemoryStore and FileStore. */
+export class StateStore {
+    /** Applies f to the state and saves it. */
+    async #change(f) {
+        const s = await this.load();
+        f(s);
+        await this.save(s);
+    }
+    async isProcessed(id) {
+        return (await this.load()).processed.has(id);
+    }
+    markProcessed(id, at) {
+        return this.#change((s) => s.processed.set(id, at));
+    }
+    async forgetProcessed(before) {
+        const s = await this.load();
+        if (![...s.processed.values()].some((at) => at < before))
+            return;
+        await this.#change((st) => {
+            for (const [id, at] of st.processed)
+                if (at < before)
+                    st.processed.delete(id);
+        });
+    }
+    async position() {
+        return (await this.load()).position;
+    }
+    setPosition(id) {
+        return this.#change((s) => {
+            s.position = id;
+        });
+    }
+    async lastRun(name) {
+        return (await this.load()).lastRuns.get(name) ?? null;
+    }
+    setLastRun(name, at) {
+        return this.#change((s) => s.lastRuns.set(name, at));
+    }
+    async refreshToken() {
+        return (await this.load()).refreshToken;
+    }
+    setRefreshToken(token) {
+        return this.#change((s) => {
+            s.refreshToken = token;
+        });
+    }
+}
+/**
+ * A Store in memory, for tests. Everything is lost when the process ends, the rotated refresh token too: the next
+ * start uses the refresh token of the options again, which the server has seen used and so revokes. A bot that runs
+ * for real, all the time or started again and again, uses a FileStore or a Store of its own.
+ */
+export class MemoryStore extends StateStore {
+    #state = emptyState();
+    load() {
+        return Promise.resolve(this.#state);
+    }
+    save() {
+        return Promise.resolve();
+    }
+}

package/dist/testing/clock.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A clock that moves only when the test moves it, for the scheduled jobs (Bot.every), the send budget, and the reply
+ * limits. Its now and sleep are the options of the same names of a bot, which Server.options sets. Times are
+ * milliseconds since the Unix epoch.
+ */
+export declare class Clock {
+    #private;
+    /** A clock at the time at. */
+    constructor(at: number);
+    /** The time of the clock: the option now of a bot. */
+    readonly now: () => number;
+    /**
+     * Waits until the clock has moved on by ms, or rejects with the reason of signal when it aborts first: the option
+     * sleep of a bot. It resolves at once for ms <= 0.
+     */
+    readonly sleep: (ms: number, signal: AbortSignal) => Promise<void>;
+    /** Moves the clock on by ms and wakes the sleepers whose time came. */
+    advance(ms: number): void;
+    /** Moves the clock to at, which must not be before now, and wakes the sleepers whose time came. */
+    set(at: number): void;
+    /** How many sleep on the clock. */
+    get sleepers(): number;
+    /**
+     * Waits until at least n sleep on the clock, such as a bot's scheduled jobs waiting for their next time, so that a
+     * following advance wakes them. It rejects when signal aborts first, after 10 seconds by default.
+     */
+    waitForSleepers(n: number, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** Resolves when cond holds, checked whenever a listener of listeners is called, or rejects when signal aborts. */
+export declare function waitFor(listeners: Set<() => void>, cond: () => boolean, signal: AbortSignal, what: string): Promise<void>;

package/dist/testing/clock.js

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+/**
+ * A clock that moves only when the test moves it, for the scheduled jobs (Bot.every), the send budget, and the reply
+ * limits. Its now and sleep are the options of the same names of a bot, which Server.options sets. Times are
+ * milliseconds since the Unix epoch.
+ */
+export class Clock {
+    #now;
+    #waiters = [];
+    #listeners = new Set();
+    /** A clock at the time at. */
+    constructor(at) {
+        this.#now = at;
+    }
+    /** The time of the clock: the option now of a bot. */
+    now = () => this.#now;
+    /**
+     * Waits until the clock has moved on by ms, or rejects with the reason of signal when it aborts first: the option
+     * sleep of a bot. It resolves at once for ms <= 0.
+     */
+    sleep = (ms, signal) => {
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        if (ms <= 0)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                this.#waiters = this.#waiters.filter((w) => w !== waiter);
+                this.#notify();
+                reject(signal.reason);
+            };
+            const waiter = {
+                until: this.#now + ms,
+                resolve: () => {
+                    signal.removeEventListener("abort", onAbort);
+                    resolve();
+                },
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            this.#waiters.push(waiter);
+            this.#notify();
+        });
+    };
+    /** Moves the clock on by ms and wakes the sleepers whose time came. */
+    advance(ms) {
+        this.#set(this.#now + ms);
+    }
+    /** Moves the clock to at, which must not be before now, and wakes the sleepers whose time came. */
+    set(at) {
+        if (at < this.#now)
+            throw new Error("mybot/testing: Clock.set to a time before now");
+        this.#set(at);
+    }
+    #set(at) {
+        this.#now = at;
+        const due = this.#waiters.filter((w) => w.until <= at);
+        this.#waiters = this.#waiters.filter((w) => w.until > at);
+        for (const w of due)
+            w.resolve();
+        this.#notify();
+    }
+    #notify() {
+        for (const listener of this.#listeners)
+            listener();
+    }
+    /** How many sleep on the clock. */
+    get sleepers() {
+        return this.#waiters.length;
+    }
+    /**
+     * Waits until at least n sleep on the clock, such as a bot's scheduled jobs waiting for their next time, so that a
+     * following advance wakes them. It rejects when signal aborts first, after 10 seconds by default.
+     */
+    waitForSleepers(n, { signal = AbortSignal.timeout(10_000) } = {}) {
+        return waitFor(this.#listeners, () => this.#waiters.length >= n, signal, `${String(n)} sleepers on the clock`);
+    }
+}
+/** Resolves when cond holds, checked whenever a listener of listeners is called, or rejects when signal aborts. */
+export function waitFor(listeners, cond, signal, what) {
+    if (cond())
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const done = () => {
+            listeners.delete(check);
+            signal.removeEventListener("abort", onAbort);
+        };
+        const check = () => {
+            if (!cond())
+                return;
+            done();
+            resolve();
+        };
+        const onAbort = () => {
+            done();
+            reject(new Error(`mybot/testing: gave up waiting for ${what}`, { cause: signal.reason }));
+        };
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        listeners.add(check);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { Clock } from "./clock.js";
+export { domain, quietLogger, Server, token, type Post, type Reaction, type ServerOptions, type WaitOptions } from "./server.js";

package/dist/testing/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// @mycroblog/mybot/testing: test bots of @mycroblog/mybot without a server (ADR-0094 §10), as mybottest does for the
+// Go library. Server is a fake server of the client API behind a fetch; the test sends the bot notifications with
+// inject and checks what it posted with posted or waitPosted. Its Clock moves only when the test moves it, so that a
+// test runs the scheduled jobs (Bot.every) at once.
+export { Clock } from "./clock.js";
+export { domain, quietLogger, Server, token } from "./server.js";