@mycroblog/mybot 0.0.0-placeholder.0

package/dist/dispatch.js

@@ -0,0 +1,168 @@
+/** The key of the account that acted, "" for an event without one. */
+export function senderOf(account) {
+    return account?.id ?? "";
+}
+/**
+ * Runs the jobs: up to its limit at once, those of one sender one after the other in the order they came (ADR-0094
+ * §4). A notification that is queued or running is not queued again, so that the catch-up and the event stream may
+ * both bring it. run must not reject.
+ */
+export class Dispatcher {
+    #run;
+    #limit;
+    #active = 0;
+    #waiting = [];
+    #queues = new Map();
+    #queued = new Set();
+    #drains = new Set();
+    #stopping = false;
+    constructor(concurrency, run) {
+        this.#limit = Math.max(1, concurrency);
+        this.#run = run;
+    }
+    /** Queues job and reports whether it did: not after stop, and not for a notification already queued. */
+    submit(job) {
+        if (this.#stopping)
+            return false;
+        if (job.notification !== undefined) {
+            if (this.#queued.has(job.notification.id))
+                return false;
+            this.#queued.add(job.notification.id);
+        }
+        const queue = this.#queues.get(job.sender);
+        if (queue !== undefined) {
+            queue.push(job);
+            return true;
+        }
+        this.#queues.set(job.sender, [job]);
+        const drain = this.#drain(job.sender).finally(() => this.#drains.delete(drain));
+        this.#drains.add(drain);
+        return true;
+    }
+    /** Runs the queue of sender until it is empty, or the dispatcher stops. */
+    async #drain(sender) {
+        for (;;) {
+            const queue = this.#queues.get(sender);
+            const job = queue?.[0];
+            if (this.#stopping || queue === undefined || job === undefined) {
+                // The jobs that never started are left to the next catch-up.
+                this.#forgetQueue(sender);
+                return;
+            }
+            await this.#acquire();
+            // stop may have been called while the job waited for its turn.
+            const stopping = this.#isStopping();
+            try {
+                if (!stopping)
+                    await this.#run(job);
+            }
+            finally {
+                this.#release();
+            }
+            if (job.notification !== undefined)
+                this.#queued.delete(job.notification.id);
+            if (queue.length <= 1 || stopping) {
+                this.#forgetQueue(sender);
+                return;
+            }
+            queue.shift();
+        }
+    }
+    #forgetQueue(sender) {
+        for (const job of this.#queues.get(sender) ?? [])
+            if (job.notification !== undefined)
+                this.#queued.delete(job.notification.id);
+        this.#queues.delete(sender);
+    }
+    async #acquire() {
+        if (this.#active < this.#limit) {
+            this.#active++;
+            return;
+        }
+        await new Promise((resolve) => this.#waiting.push(resolve));
+    }
+    #release() {
+        const next = this.#waiting.shift();
+        if (next === undefined)
+            this.#active--;
+        else
+            next();
+    }
+    #isStopping() {
+        return this.#stopping;
+    }
+    /** Makes the dispatcher take no more jobs and start none of those queued. */
+    stop() {
+        this.#stopping = true;
+    }
+    /** Resolves when every running job has returned. */
+    async idle() {
+        while (this.#drains.size > 0)
+            await Promise.all(this.#drains);
+    }
+}
+/**
+ * Computes the position of the catch-up (ADR-0094 §3): the newest notification up to which every notification handed
+ * to the bot was processed. Handlers end out of order, so a processed notification moves the position only when no
+ * older one is still pending; while a catch-up hands out notifications, the position holds still, so that a restart
+ * in the middle of it reads them again. Notification IDs are UUIDv7 strings, whose order is the order of time.
+ */
+export class Tracker {
+    #pending = new Set();
+    /** The processed notifications above the position, in order. */
+    #done = [];
+    #holds = 0;
+    /** Marks the notification id pending. */
+    add(id) {
+        this.#pending.add(id);
+    }
+    /** Drops a pending notification that was not handed out after all. */
+    forget(id) {
+        this.#pending.delete(id);
+    }
+    /** Marks the notification id processed and returns the new position, null when it does not move. */
+    complete(id) {
+        this.#pending.delete(id);
+        const i = lowerBound(this.#done, id);
+        if (this.#done[i] !== id)
+            this.#done.splice(i, 0, id);
+        return this.#advance();
+    }
+    /** Keeps the position where it is until release. */
+    hold() {
+        this.#holds++;
+    }
+    /** Ends a hold and returns the new position, null when it does not move. */
+    release() {
+        this.#holds--;
+        return this.#advance();
+    }
+    /** Moves the position past the processed notifications older than every pending one. */
+    #advance() {
+        if (this.#holds > 0 || this.#done.length === 0)
+            return null;
+        let oldest = null;
+        for (const id of this.#pending)
+            if (oldest === null || id < oldest)
+                oldest = id;
+        const n = oldest === null ? this.#done.length : lowerBound(this.#done, oldest);
+        if (n === 0)
+            return null;
+        const position = this.#done[n - 1] ?? null;
+        this.#done = this.#done.slice(n);
+        return position;
+    }
+}
+/** The index of the first element of the sorted xs that is not less than x. */
+function lowerBound(xs, x) {
+    let lo = 0;
+    let hi = xs.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if ((xs[mid] ?? "") < x)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}

package/dist/every.d.ts

@@ -0,0 +1,55 @@
+import type { components } from "@mycroblog/mykit";
+import type { Handler } from "./context.js";
+import type { Schedule } from "./schedule.js";
+type Visibility = components["schemas"]["Visibility"];
+/**
+ * What a scheduled job does about the times it missed while the bot was stopped: "skip", the default, leaves them out,
+ * and the job runs from its next time after the start; "latest" runs, when the bot starts, the newest of the times
+ * after the job's last run in the store, once. The older ones are left out, so that a long stop never posts a pile at
+ * once. A job that never ran runs its newest past time.
+ */
+export type CatchUp = "skip" | "latest";
+/** The visibilities of the posts of a scheduled job. */
+export type EveryVisibility = Extract<Visibility, "unlisted" | "public" | "local">;
+/** The options of a scheduled job (Bot.every). */
+export type EveryOptions = {
+    /**
+     * Names the job in the store (its last run) and in the Idempotency-Key of its posts: keep it when the expression
+     * changes. Absent or "" means the expression. Two jobs of one bot cannot share a name.
+     */
+    name?: string;
+    /** The IANA time zone of the expression, such as "Asia/Tokyo"; absent or "" means UTC. */
+    timeZone?: string;
+    /** "skip" (the default) or "latest". */
+    catchUp?: CatchUp;
+    /**
+     * The visibility of the posts of Context.post: "unlisted" (the default), "public", or "local", which reaches the
+     * server of the bot and its followers alone (ADR-0017).
+     */
+    visibility?: EveryVisibility;
+};
+/** A job that Bot.every registered. */
+export type EveryJob = {
+    readonly name: string;
+    readonly schedule: Schedule;
+    readonly handler: Handler;
+    readonly catchUp: CatchUp;
+    readonly visibility: EveryVisibility;
+};
+/**
+ * The Idempotency-Key of the post of the run at (milliseconds since the Unix epoch) of the scheduled job name
+ * (ADR-0094 §5): mybot:every:<name>:<the time in RFC 3339, UTC>. Two processes of one bot that run the same time post
+ * once. Use it when posting with mykit directly.
+ */
+export declare function everyIdempotencyKey(name: string, at: number): string;
+/** The error of Context.post outside a scheduled job. */
+export declare class NotScheduledError extends Error {
+    readonly name = "NotScheduledError";
+    constructor();
+}
+/** The error of a second Context.post in one run of a scheduled job, whose Idempotency-Key would answer with the first post. */
+export declare class PostedAlreadyError extends Error {
+    readonly name = "PostedAlreadyError";
+    constructor();
+}
+export {};

package/dist/every.js

@@ -0,0 +1,22 @@
+/**
+ * The Idempotency-Key of the post of the run at (milliseconds since the Unix epoch) of the scheduled job name
+ * (ADR-0094 §5): mybot:every:<name>:<the time in RFC 3339, UTC>. Two processes of one bot that run the same time post
+ * once. Use it when posting with mykit directly.
+ */
+export function everyIdempotencyKey(name, at) {
+    return `mybot:every:${name}:${new Date(at).toISOString().replace(/\.\d+Z$/, "Z")}`;
+}
+/** The error of Context.post outside a scheduled job. */
+export class NotScheduledError extends Error {
+    name = "NotScheduledError";
+    constructor() {
+        super("mybot: post is for the handler of a scheduled job");
+    }
+}
+/** The error of a second Context.post in one run of a scheduled job, whose Idempotency-Key would answer with the first post. */
+export class PostedAlreadyError extends Error {
+    name = "PostedAlreadyError";
+    constructor() {
+        super("mybot: the run of the scheduled job posted already");
+    }
+}

package/dist/filestore.d.ts

@@ -0,0 +1,17 @@
+import { StateStore, type StoreState } from "./store.js";
+/** The file of the FileStore that a Bot uses when its options name no store. */
+export declare const defaultStatePath = "./mybot-state.json";
+/**
+ * A Store in one JSON file, the default Store of a Bot. It reads the file on first use (a missing file is an empty
+ * state, created on the first change). Every change rewrites the file: the new content goes to a temporary file in
+ * the same directory, which then replaces the file, so that a crash never leaves half of it. The file holds the
+ * refresh token: it is created readable by its owner only. The document is that of the Go library's FileStore.
+ */
+export declare class FileStore extends StateStore {
+    #private;
+    /** The file of the store. */
+    readonly path: string;
+    constructor(path?: string);
+    protected load(): Promise<StoreState>;
+    protected save(state: StoreState): Promise<void>;
+}

package/dist/filestore.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: MIT
+// FileStore, the one part of the library that touches the file system. It loads node:fs/promises on first use, with
+// a dynamic import, which Node.js, Bun, and Deno all provide (Deno needs --allow-read and --allow-write for the file),
+// so that the rest of the library runs wherever fetch does.
+import { decodeState, emptyState, encodeState, StateStore } from "./store.js";
+/** The file of the FileStore that a Bot uses when its options name no store. */
+export const defaultStatePath = "./mybot-state.json";
+/** The module name, in a variable so that the type checker, which has no Node.js types here, does not resolve it. */
+const fsModule = "node:fs/promises";
+let fsPromise = null;
+/** node:fs/promises, loaded once. */
+function fs() {
+    fsPromise ??= import(fsModule);
+    return fsPromise;
+}
+/** Whether error is the error of a missing file. */
+function notFound(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+/** The directory part of path ("." for a bare name), for either separator. */
+function dirname(path) {
+    const i = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    if (i < 0)
+        return ".";
+    return i === 0 ? path.slice(0, 1) : path.slice(0, i);
+}
+/** The last part of path. */
+function basename(path) {
+    return path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
+}
+/**
+ * A Store in one JSON file, the default Store of a Bot. It reads the file on first use (a missing file is an empty
+ * state, created on the first change). Every change rewrites the file: the new content goes to a temporary file in
+ * the same directory, which then replaces the file, so that a crash never leaves half of it. The file holds the
+ * refresh token: it is created readable by its owner only. The document is that of the Go library's FileStore.
+ */
+export class FileStore extends StateStore {
+    /** The file of the store. */
+    path;
+    #state = null;
+    /** The writes in order: each rewrites the whole file, so the last one wins. */
+    #writes = Promise.resolve();
+    constructor(path = defaultStatePath) {
+        super();
+        this.path = path;
+    }
+    load() {
+        this.#state ??= this.#read();
+        return this.#state;
+    }
+    async #read() {
+        const f = await fs();
+        let text;
+        try {
+            text = await f.readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (notFound(error))
+                return emptyState();
+            throw new Error(`mybot: read the state file ${this.path}`, { cause: error });
+        }
+        try {
+            return decodeState(text);
+        }
+        catch (error) {
+            throw new Error(`mybot: read the state file ${this.path}`, { cause: error });
+        }
+    }
+    save(state) {
+        const text = encodeState(state);
+        const write = this.#writes.then(() => this.#write(text));
+        // A failed write fails its caller, not the next write.
+        this.#writes = write.catch(() => undefined);
+        return write;
+    }
+    async #write(text) {
+        const f = await fs();
+        const tmp = `${dirname(this.path)}/.${basename(this.path)}.${crypto.randomUUID()}.tmp`;
+        try {
+            const handle = await f.open(tmp, "wx", 0o600);
+            try {
+                await handle.writeFile(text, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await f.rename(tmp, this.path);
+        }
+        catch (error) {
+            await f.rm(tmp, { force: true }).catch(() => undefined);
+            throw new Error(`mybot: write the state file ${this.path}`, { cause: error });
+        }
+    }
+}

package/dist/handler.d.ts

@@ -0,0 +1,42 @@
+import type { components } from "@mycroblog/mykit";
+import { type Handler, type Middleware } from "./context.js";
+type CredentialAccount = components["schemas"]["CredentialAccount"];
+/** Logs what the handler throws, so that one event never stops the bot. */
+export declare function recover(): Middleware;
+/**
+ * Skips the handler, the event counting as processed, for a sender whose account has the bot flag (unless the
+ * respondToBots option) and for a sender whom the bot replied to as often as the replyLimits option allows (ADR-0094
+ * §8). Events of the bot's own account never reach a handler, with or without it.
+ */
+export declare function manners(): Middleware;
+/**
+ * Makes the helpers of Context (reply, react, favourite, follow) wait for the client-side send budget of the postRate
+ * and writeRate options, and for the reset of the server's rate limit when less than a tenth of it remains (ADR-0094
+ * §6). A write that would wait longer than the maxSendWait option is dropped and logged.
+ */
+export declare function sendBudget(): Middleware;
+/**
+ * The chain that every handler runs in unless the noDefaultMiddleware option is set, outermost first: recover,
+ * manners, and sendBudget (ADR-0094 §4).
+ */
+export declare function defaultMiddleware(): Middleware[];
+/** Wraps handler in middleware, the first outermost. */
+export declare function chain(middleware: readonly Middleware[], handler: Handler): Handler;
+/** A command that onCommand registered. */
+export type Command = {
+    /** The lowercase name of the command. */
+    readonly name: string;
+    /** What the command does, for the answer of help. */
+    readonly description: string;
+};
+/** Formats the answer of the help command: a line for each command with its description. */
+export declare function defaultHelp(commands: readonly Command[]): string;
+/**
+ * Reads the command of a mention's text: the first word after the mentions of me at its start, lowercase, and the
+ * rest of the text. It is null when no word follows.
+ */
+export declare function parseCommand(text: string, me: CredentialAccount | undefined): {
+    name: string;
+    args: string;
+} | null;
+export {};

package/dist/handler.js

@@ -0,0 +1,93 @@
+import { internal } from "./context.js";
+/** Logs what the handler throws, so that one event never stops the bot. */
+export function recover() {
+    return async (ctx, next) => {
+        try {
+            await next();
+        }
+        catch (error) {
+            ctx.logger.error("mybot: the handler failed", { error });
+        }
+    };
+}
+/**
+ * Skips the handler, the event counting as processed, for a sender whose account has the bot flag (unless the
+ * respondToBots option) and for a sender whom the bot replied to as often as the replyLimits option allows (ADR-0094
+ * §8). Events of the bot's own account never reach a handler, with or without it.
+ */
+export function manners() {
+    return async (ctx, next) => {
+        const { runtime, sender } = ctx[internal];
+        if (ctx.account?.bot === true && !runtime.respondToBots) {
+            ctx.logger.debug("mybot: skipped an event of a bot", { account: ctx.account.acct });
+            return;
+        }
+        if (ctx.account !== undefined && runtime.replyLimits !== null && runtime.replies.full(sender, runtime.now())) {
+            ctx.logger.info("mybot: skipped an event of a sender at the reply limit", { account: ctx.account.acct });
+            return;
+        }
+        await next();
+    };
+}
+/**
+ * Makes the helpers of Context (reply, react, favourite, follow) wait for the client-side send budget of the postRate
+ * and writeRate options, and for the reset of the server's rate limit when less than a tenth of it remains (ADR-0094
+ * §6). A write that would wait longer than the maxSendWait option is dropped and logged.
+ */
+export function sendBudget() {
+    return async (ctx, next) => {
+        ctx[internal].budgeted = true;
+        await next();
+    };
+}
+/**
+ * The chain that every handler runs in unless the noDefaultMiddleware option is set, outermost first: recover,
+ * manners, and sendBudget (ADR-0094 §4).
+ */
+export function defaultMiddleware() {
+    return [recover(), manners(), sendBudget()];
+}
+/** Wraps handler in middleware, the first outermost. */
+export function chain(middleware, handler) {
+    return (ctx) => {
+        const step = async (i) => {
+            const mw = middleware[i];
+            if (mw === undefined) {
+                await handler(ctx);
+                return;
+            }
+            await mw(ctx, () => step(i + 1));
+        };
+        return step(0);
+    };
+}
+/** Formats the answer of the help command: a line for each command with its description. */
+export function defaultHelp(commands) {
+    return commands.map((c) => (c.description === "" ? c.name : `${c.name}: ${c.description}`)).join("\n");
+}
+/** ASCII punctuation (Unicode category P), but '_', which may follow a mention: `@bot,`. */
+const trailingPunctuation = /[!"#%&'()*,\-./:;?@[\\\]{}]+$/;
+/** Whether word is a mention of me: @username or @username@domain, without case, and with the punctuation that may follow it. */
+function mentionsMe(word, me) {
+    if (!word.startsWith("@") || me === undefined)
+        return false;
+    const handle = word.slice(1).replace(trailingPunctuation, "").toLowerCase();
+    return [me.username, me.acct, `${me.username}@${me.domain}`].some((h) => h !== "" && h.toLowerCase() === handle);
+}
+/**
+ * Reads the command of a mention's text: the first word after the mentions of me at its start, lowercase, and the
+ * rest of the text. It is null when no word follows.
+ */
+export function parseCommand(text, me) {
+    let s = text.trim();
+    for (;;) {
+        const m = /^\s*(\S+)([\s\S]*)$/.exec(s);
+        if (m === null)
+            return null;
+        const word = m[1] ?? "";
+        const rest = m[2] ?? "";
+        if (!mentionsMe(word, me))
+            return { name: word.toLowerCase(), args: rest.trim() };
+        s = rest;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { AlreadyRunningError, Bot, defaultCatchUpLimit, defaultConcurrency, defaultPollInterval, defaultProcessedRetention, defaultShutdownGrace, NotBotError, ScopeError, type BotOptions, type Mode, } from "./bot.js";
+export { defaultMaxSendWait, defaultPostRate, defaultReplyLimits, defaultWriteRate, type Rate } from "./budget.js";
+export { BudgetExceededError, Context, NoAccountError, NoStatusError, ReplyLimitError, replyIdempotencyKey, replyVisibility, type Handler, type Middleware, } from "./context.js";
+export { everyIdempotencyKey, NotScheduledError, PostedAlreadyError, type CatchUp, type EveryOptions, type EveryVisibility, } from "./every.js";
+export { defaultStatePath, FileStore } from "./filestore.js";
+export { defaultHelp, defaultMiddleware, manners, recover, sendBudget, type Command } from "./handler.js";
+export type { Logger } from "./logger.js";
+export { MemoryStore, type Store } from "./store.js";
+export { parseSchedule, Schedule, ScheduleError } from "./schedule.js";
+export { plainText } from "./text.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+// @mycroblog/mybot: build bots for mycroblog/my on the API client @mycroblog/mykit (ADR-0094). The author of a bot
+// writes the handlers of its events; the library receives the events, so that none is lost or answered twice, and
+// keeps the bot polite by default. It mirrors the Go library github.com/mycroblog/my/pkg/mybot: the same handlers,
+// options, defaults, idempotency keys, and state file.
+export { AlreadyRunningError, Bot, defaultCatchUpLimit, defaultConcurrency, defaultPollInterval, defaultProcessedRetention, defaultShutdownGrace, NotBotError, ScopeError, } from "./bot.js";
+export { defaultMaxSendWait, defaultPostRate, defaultReplyLimits, defaultWriteRate } from "./budget.js";
+export { BudgetExceededError, Context, NoAccountError, NoStatusError, ReplyLimitError, replyIdempotencyKey, replyVisibility, } from "./context.js";
+export { everyIdempotencyKey, NotScheduledError, PostedAlreadyError, } from "./every.js";
+export { defaultStatePath, FileStore } from "./filestore.js";
+export { defaultHelp, defaultMiddleware, manners, recover, sendBudget } from "./handler.js";
+export { MemoryStore } from "./store.js";
+export { parseSchedule, Schedule, ScheduleError } from "./schedule.js";
+export { plainText } from "./text.js";

package/dist/logger.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Receives the log of a bot: `console`, the default, or anything with the same four methods. The bot calls each with
+ * a message and an object of attributes, such as `logger.warn("mybot: ...", { notification: "...", error })`.
+ */
+export type Logger = {
+    debug(message: string, ...data: unknown[]): void;
+    info(message: string, ...data: unknown[]): void;
+    warn(message: string, ...data: unknown[]): void;
+    error(message: string, ...data: unknown[]): void;
+};
+/** A Logger that adds attrs to the attributes of every call to logger. */
+export declare function withAttributes(logger: Logger, attrs: Record<string, unknown>): Logger;

package/dist/logger.js

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+/** Whether value is a plain object of attributes. */
+function isAttributes(value) {
+    return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+/** A Logger that adds attrs to the attributes of every call to logger. */
+export function withAttributes(logger, attrs) {
+    const call = (level) => (message, ...data) => {
+        const [first, ...more] = data;
+        if (isAttributes(first)) {
+            logger[level](message, { ...attrs, ...first }, ...more);
+        }
+        else {
+            logger[level](message, attrs, ...data);
+        }
+    };
+    return { debug: call("debug"), info: call("info"), warn: call("warn"), error: call("error") };
+}

package/dist/schedule.d.ts

@@ -0,0 +1,36 @@
+/** The error of parseSchedule and Bot.every for an expression or a time zone that mybot does not take. */
+export declare class ScheduleError extends Error {
+    readonly name = "ScheduleError";
+}
+/**
+ * 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 declare class Schedule {
+    #private;
+    /** The expression of the schedule. */
+    readonly expr: string;
+    /** The IANA time zone of the schedule, "UTC" by default. */
+    readonly timeZone: string;
+    /** Use parseSchedule. */
+    private constructor();
+    /**
+     * 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: string, timeZone?: string): Schedule;
+    /** The first time of the schedule after at; null when there is none in the next eight years. */
+    next(at: number): number | null;
+    /** The last time of the schedule at or before at; null when there is none in the eight years before. */
+    prev(at: number): number | null;
+}
+/** Parses the cron expression expr in the IANA time zone timeZone ("" or absent is UTC): Schedule.parse. */
+export declare function parseSchedule(expr: string, timeZone?: string): Schedule;