@ultimabase/jobs 0.0.0-stage → 0.4.0-canary.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/jobs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Jobs for UltimaBase. A run enqueued from a hook is written in the write's transaction, so it exists if and only if the write committed; it can wait a delay, or run on an `every` or `cron` schedule, and is retried until it succeeds.
+
+Documentation: [Jobs](https://ultimabase.dev/docs/jobs).

package/dist/define-job.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Standard Schema (standardschema.dev), the part a job reads. Its
+ * specification asks for the interface to be copied, not imported.
+ */
+export interface StandardSchema<I = unknown, O = I> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => unknown;
+        readonly types?: {
+            readonly input: I;
+            readonly output: O;
+        } | undefined;
+    };
+}
+type Types<S> = S extends StandardSchema<infer I, infer O> ? {
+    readonly input: I;
+    readonly output: O;
+} : never;
+/** What a job's `run` returns, which nothing reads. */
+type Done = unknown;
+/** The id of the run's row, the key that makes its effect idempotent. */
+type Facts = {
+    readonly id: string;
+};
+type Schedule = {
+    readonly input?: never;
+    readonly every?: never;
+    readonly cron?: never;
+    readonly timeZone?: never;
+};
+type InputDefinition<N, S> = Omit<Schedule, 'input'> & {
+    readonly name: N;
+    /** Validated when the run is enqueued, and stored as JSON. */
+    readonly input: S;
+    readonly run: (facts: Facts & {
+        readonly input: Types<S>['output'];
+    }) => Done;
+};
+type PlainDefinition<N> = Schedule & {
+    readonly name: N;
+    readonly run: (facts: Facts) => Done;
+};
+type EveryDefinition<N> = Omit<Schedule, 'every'> & {
+    readonly name: N;
+    /** In milliseconds. */
+    readonly every: number;
+    readonly run: (facts: Facts) => Done;
+};
+type CronDefinition<N> = Omit<Schedule, 'cron' | 'timeZone'> & {
+    readonly name: N;
+    /** Five fields: minute, hour, day of the month, month, day of the week. */
+    readonly cron: string;
+    /** An IANA time zone, such as `'Europe/Paris'`: `'UTC'` by default. */
+    readonly timeZone?: string;
+    readonly run: (facts: Facts) => Done;
+};
+/** `enqueue`'s options. */
+export interface EnqueueOptions {
+    /** In milliseconds, how long the run waits. */
+    readonly after?: number;
+}
+/** A job enqueued from server code. */
+export interface Job<N extends string, I> {
+    readonly name: N;
+    /**
+     * Writes a run in the current transaction, or alone outside one: it
+     * exists if and only if the transaction commits.
+     */
+    readonly enqueue: (...args: [I] extends [never] ? [options?: EnqueueOptions] : [input: I, options?: EnqueueOptions]) => Promise<void>;
+}
+/** A job that runs on its schedule, never enqueued. */
+export interface RecurringJob<N extends string> {
+    readonly name: N;
+}
+/** What the plugin reads of a job. */
+export interface JobRecord {
+    readonly name: string;
+    readonly input: StandardSchema | undefined;
+    /** `every <ms>` or `cron <pattern> <zone>`, for a recurring job. */
+    readonly schedule: string | undefined;
+    /** The first due time after `from`, for a recurring job. */
+    readonly next: (from: number) => number;
+    readonly run: (facts: Facts & {
+        readonly input?: unknown;
+    }) => Done;
+}
+/** A `defineJob` value's record. */
+export declare function recordOf(job: unknown): JobRecord | undefined;
+export declare function defineJob<const N extends string, const S extends StandardSchema>(definition: InputDefinition<N, S>): Job<N, Types<S>['input']>;
+export declare function defineJob<const N extends string>(definition: PlainDefinition<N>): Job<N, never>;
+export declare function defineJob<const N extends string>(definition: EveryDefinition<N> | CronDefinition<N>): RecurringJob<N>;
+export {};
+//# sourceMappingURL=define-job.d.ts.map

package/dist/define-job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-job.d.ts","sourceRoot":"","sources":["../src/define-job.ts"],"names":[],"mappings":"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"}

package/dist/define-job.js

@@ -0,0 +1,128 @@
+// `defineJob` (D-221): a job takes an input, or runs `every` milliseconds,
+// or on a `cron` pattern. A job with no schedule is enqueued, from its
+// definition, in the current transaction (D-36).
+import { Cron } from 'croner';
+import { PublicError, Refused } from 'ultimabase';
+import { checked, standardOf } from 'ultimabase/internal';
+import { JobsRun, M } from './model.js';
+import { runningOf } from './state.js';
+const records = new WeakMap();
+/** A `defineJob` value's record. */
+export function recordOf(job) {
+    return typeof job === 'object' && job !== null ? records.get(job) : undefined;
+}
+/** A positive number of milliseconds. */
+function isDuration(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+/** The next due time of a pattern croner accepts; refuses one it does not. */
+function cronNext(name, pattern, zone) {
+    if (typeof pattern !== 'string') {
+        throw new Refused(`${name}: cron is a pattern of five fields.`);
+    }
+    if (zone !== undefined && typeof zone !== 'string') {
+        throw new Refused(`${name}: timeZone is an IANA time zone.`);
+    }
+    let cron;
+    try {
+        cron = new Cron(pattern, { timezone: zone ?? 'UTC', mode: '5-part' });
+        cron.nextRun();
+    }
+    catch (error) {
+        throw new Refused(`${name}: ${String(error)}`, { cause: error });
+    }
+    return (from) => {
+        const next = cron.nextRun(new Date(from));
+        if (next === null)
+            throw new Error(`${name}: cron has no next time.`);
+        return next.getTime();
+    };
+}
+/** The record of a job's definition, checked at import. */
+function recordFor(definition) {
+    const read = (key) => Reflect.get(definition, key);
+    const [name, input, every, cron, timeZone, run] = [
+        'name',
+        'input',
+        'every',
+        'cron',
+        'timeZone',
+        'run',
+    ].map(read);
+    if (typeof name !== 'string' || name === '') {
+        throw new Refused('defineJob: name is a non-empty string.');
+    }
+    if (typeof run !== 'function')
+        throw new Refused(`${name}: run is a function.`);
+    const forms = [input, every, cron].filter((form) => form !== undefined);
+    if (forms.length > 1) {
+        throw new Refused(`${name}: a job takes one of input, every and cron.`);
+    }
+    if (timeZone !== undefined && cron === undefined) {
+        throw new Refused(`${name}: timeZone goes with cron.`);
+    }
+    if (input !== undefined && standardOf(input) === undefined) {
+        throw new Refused(`${name}: input is a Standard Schema.`);
+    }
+    if (every !== undefined && !isDuration(every)) {
+        throw new Refused(`${name}: every is a positive number of milliseconds.`);
+    }
+    const next = cron !== undefined
+        ? cronNext(name, cron, timeZone)
+        : (from) => from + Number(every);
+    // cronNext refused a pattern or a zone that is no string.
+    const schedule = cron !== undefined
+        ? `cron ${JSON.stringify(cron)} ${JSON.stringify(timeZone ?? 'UTC')}`
+        : every === undefined
+            ? undefined
+            : `every ${every}`;
+    const runs = (facts) => Reflect.apply(run, undefined, [facts]);
+    const schema = standardOf(input)?.schema;
+    return { name, input: schema, schedule, next, run: runs };
+}
+/** The input's validated value; refuses it as `VALIDATION_FAILED`. */
+async function validated(name, schema, input) {
+    const standard = standardOf(schema);
+    if (standard === undefined)
+        return input;
+    const result = await checked(standard, input, [], name);
+    if ('issues' in result) {
+        throw new PublicError('VALIDATION_FAILED', 'Invalid input.', {
+            details: { issues: result.issues },
+        });
+    }
+    return result.value;
+}
+async function enqueue(record, args) {
+    const { name, input: schema } = record;
+    const [input, options] = schema === undefined ? [undefined, args[0]] : [args[0], args[1]];
+    const after = typeof options === 'object' && options !== null
+        ? Reflect.get(options, 'after')
+        : undefined;
+    if (after !== undefined && !isDuration(after)) {
+        throw new TypeError(`${name}: after is a positive number of milliseconds.`);
+    }
+    if (runningOf(`${name}.enqueue`).jobs.get(name) !== record) {
+        throw new Error(`${name} is not in jobsPlugin's jobs.`);
+    }
+    const value = schema === undefined ? null : await validated(name, schema, input);
+    const data = {
+        job: name,
+        input: value ?? null,
+        state: 'pending',
+        dueAt: new Date(Date.now() + (after ?? 0)),
+        attempts: 0,
+    };
+    await JobsRun.create({ data }, M);
+}
+export function defineJob(definition) {
+    const record = recordFor(definition);
+    const job = Object.freeze(record.schedule === undefined
+        ? {
+            name: record.name,
+            enqueue: async (...args) => enqueue(record, args),
+        }
+        : { name: record.name });
+    records.set(job, record);
+    return job;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { EnqueueOptions, Job, RecurringJob, StandardSchema, } from './define-job.ts';
+export { defineJob } from './define-job.ts';
+export type { Jobs, JobsApi, JobsOptions } from './plugin.ts';
+export { jobsPlugin } from './plugin.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACX,cAAc,EACd,GAAG,EACH,YAAY,EACZ,cAAc,GACd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { defineJob } from './define-job.js';
+export { jobsPlugin } from './plugin.js';

package/dist/model.d.ts

@@ -0,0 +1,37 @@
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase';
+import { master } from 'ultimabase';
+export declare const M: {
+    readonly as: typeof master;
+};
+/** A run's state: waiting for its due time, or out of attempts. */
+export type RunState = 'pending' | 'failed';
+type Optional<V> = Field<V | null, {
+    readonly optional: true;
+}>;
+type RunFields = {
+    /** The job's name. */
+    readonly job: Field<string, ScalarOptions<string>>;
+    /** A recurring job's name, on its one row. */
+    readonly recurring: Field<string | null, {
+        readonly optional: true;
+        readonly unique: true;
+    }>;
+    /** A recurring job's `every` or `cron`, which tells when it changed. */
+    readonly schedule: Optional<string>;
+    readonly input: Field<unknown, {
+        readonly optional: true;
+    }, never, never, unknown, true>;
+    readonly state: Field<string, ScalarOptions<string>>;
+    readonly dueAt: Field<Date, ScalarOptions<Date>>;
+    /** The runs that failed. */
+    readonly attempts: Field<number, {
+        readonly integer: true;
+    }>;
+    /** Until when an instance holds the row. */
+    readonly lockedUntil: Optional<Date>;
+    /** The last failure's message. */
+    readonly error: Optional<string>;
+};
+export declare const JobsRun: ModelOf<'JobsRun', RunFields, []>;
+export {};
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,EAAe,MAAM,EAAE,MAAM,YAAY,CAAA;AAGhD,eAAO,MAAM,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,MAAM,CAAA;CAAmB,CAAA;AAE/D,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE3C,KAAK,QAAQ,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAE/D,KAAK,SAAS,GAAG;IAChB,sBAAsB;IACtB,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IAClD,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,KAAK,CACxB,MAAM,GAAG,IAAI,EACb;QAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;KAAE,CAClD,CAAA;IACD,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACnC,QAAQ,CAAC,KAAK,EAAE,KAAK,CACpB,OAAO,EACP;QAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,EAC3B,KAAK,EACL,KAAK,EACL,OAAO,EACP,IAAI,CACJ,CAAA;IACD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACpD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAA;IAChD,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IAC5D,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAA;IACpC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;CAChC,CAAA;AAED,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,CAuBpD,CAAA"}

package/dist/model.js

@@ -0,0 +1,27 @@
+import { defineModel, master } from 'ultimabase';
+import { runningOf } from './state.js';
+export const M = { as: master };
+export const JobsRun = defineModel({
+    name: 'JobsRun',
+    fields: (f) => ({
+        job: f.string(),
+        recurring: f.string({ optional: true, unique: true }),
+        schedule: f.string({ optional: true }),
+        input: f.json({ optional: true }),
+        state: f.string(),
+        dueAt: f.dateTime(),
+        attempts: f.number({ integer: true }),
+        lockedUntil: f.dateTime({ optional: true }),
+        error: f.string({ optional: true }),
+    }),
+    indexes: [{ fields: ['state', 'dueAt'] }],
+}).with({
+    hooks: {
+        // A run due now starts once its write committed, in this instance.
+        afterCreateCommit: ({ record }) => {
+            if (record.recurring === null && record.dueAt.getTime() <= Date.now()) {
+                runningOf('A run').kick(record.id);
+            }
+        },
+    },
+});

package/dist/plugin.d.ts

@@ -0,0 +1,20 @@
+import type { PluginOf, PluginTypes } from 'ultimabase';
+import type { Job, RecurringJob } from './define-job.ts';
+/** What `jobsPlugin` takes. */
+export interface JobsOptions {
+    readonly jobs: readonly (Job<string, never> | RecurringJob<string>)[];
+}
+/** What the jobs plugin offers other plugins, and `runJobs()`. */
+export interface JobsApi {
+    /** Runs the due rows, and those their runs enqueue, until none is due. */
+    readonly drain: () => Promise<void>;
+}
+/** The jobs plugin's types (D-57). */
+export interface Jobs extends PluginTypes {
+    readonly name: 'jobs';
+    readonly appOptions: JobsOptions;
+    readonly api: JobsApi;
+}
+/** Jobs: runs enqueued with a write, delayed or on a schedule (D-221). */
+export declare const jobsPlugin: PluginOf<Jobs>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGvD,OAAO,KAAK,EAAa,GAAG,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAOnE,+BAA+B;AAC/B,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE,CAAA;CACrE;AAED,kEAAkE;AAClE,MAAM,WAAW,OAAO;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAED,sCAAsC;AACtC,MAAM,WAAW,IAAK,SAAQ,WAAW;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAA;IAChC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACrB;AAwED,0EAA0E;AAC1E,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAqB,CAAA"}

package/dist/plugin.js

@@ -0,0 +1,77 @@
+import { definePlugin, Refused } from 'ultimabase';
+import manifest from '../package.json' with { type: 'json' };
+import { recordOf } from './define-job.js';
+import { JobsRun } from './model.js';
+import { drain, pass, schedule, settled, start } from './runner.js';
+import { runningOf, useRunning } from './state.js';
+/** Five seconds, between two looks for due rows. */
+const pollEvery = 5000;
+/** The jobs by name; refuses a value `defineJob` did not return and a name twice. */
+function jobsOf(jobs) {
+    if (!Array.isArray(jobs)) {
+        throw new Refused('jobsPlugin’s jobs is an array of defineJob values.');
+    }
+    const byName = new Map();
+    for (const job of jobs) {
+        const record = recordOf(job);
+        if (record === undefined) {
+            throw new Refused('jobsPlugin’s jobs is an array of defineJob values.');
+        }
+        if (byName.has(record.name)) {
+            throw new Refused(`jobsPlugin’s jobs name ${record.name} twice.`);
+        }
+        byName.set(record.name, record);
+    }
+    return byName;
+}
+// The poll's timer, while the application runs.
+let timer;
+let polling = false;
+/** One look for due rows, unless the last one still runs. */
+async function poll(app) {
+    if (polling)
+        return;
+    polling = true;
+    try {
+        while ((await pass(app)) > 0)
+            ;
+    }
+    catch (error) {
+        app.logger.warn({ err: error }, 'The jobs could not be read.');
+    }
+    finally {
+        polling = false;
+    }
+}
+const definition = definePlugin({
+    name: 'jobs',
+    manifest,
+    models: [JobsRun],
+    api: () => ({ drain: () => drain(runningOf('runJobs()')) }),
+    start: async ({ options, logger }) => {
+        const app = {
+            jobs: jobsOf(options.jobs),
+            logger,
+            kick: (id) => void start(app, id),
+        };
+        useRunning(app);
+        await schedule(app);
+    },
+    // What was due while no instance ran runs once now.
+    started: () => {
+        const app = runningOf('jobsPlugin');
+        void poll(app);
+        timer = setInterval(() => void poll(app), pollEvery);
+        timer.unref();
+    },
+    stopping: async () => {
+        clearInterval(timer);
+        timer = undefined;
+        await settled();
+    },
+    stop: () => {
+        useRunning(undefined);
+    },
+});
+/** Jobs: runs enqueued with a write, delayed or on a schedule (D-221). */
+export const jobsPlugin = definition.plugin;

package/dist/runner.d.ts

@@ -0,0 +1,21 @@
+import type { Running } from './state.ts';
+/** Five minutes, an instance's hold on a row. */
+export declare const lease: number;
+/** The attempts of a run before it turns `failed`. */
+export declare const attempts = 10;
+/** Ten seconds, the wait after a first failure. */
+export declare const backoff: number;
+/** Starts the row's run; a failure outside the job is logged. */
+export declare function start(app: Running, id: string): Promise<boolean>;
+/** Runs the rows due now, a batch at a time; how many it ran. */
+export declare function pass(app: Running): Promise<number>;
+/** Waits for the runs this instance started. */
+export declare function settled(): Promise<void>;
+/**
+ * Runs the due rows, and those their runs enqueue, until none is due:
+ * what `runJobs()` does.
+ */
+export declare function drain(app: Running): Promise<void>;
+/** Creates the rows of new recurring jobs, and deletes those of old ones. */
+export declare function schedule(app: Running): Promise<void>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEzC,iDAAiD;AACjD,eAAO,MAAM,KAAK,EAAE,MAAsB,CAAA;AAC1C,sDAAsD;AACtD,eAAO,MAAM,QAAQ,KAAK,CAAA;AAC1B,mDAAmD;AACnD,eAAO,MAAM,OAAO,EAAE,MAAkB,CAAA;AA4GxC,iEAAiE;AACjE,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQhE;AAED,iEAAiE;AACjE,wBAAsB,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAYxD;AAED,gDAAgD;AAChD,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7C;AAED;;;GAGG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvD;AAED,6EAA6E;AAC7E,wBAAsB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC1D"}

package/dist/runner.js

@@ -0,0 +1,168 @@
+import { JobsRun, M } from './model.js';
+/** Five minutes, an instance's hold on a row. */
+export const lease = 5 * 60 * 1000;
+/** The attempts of a run before it turns `failed`. */
+export const attempts = 10;
+/** Ten seconds, the wait after a first failure. */
+export const backoff = 10 * 1000;
+/** The rows a pass runs at once. */
+const batch = 20;
+/** The rows due at `now` that no instance holds. */
+function due(now) {
+    return {
+        state: 'pending',
+        dueAt: { lte: now },
+        OR: [{ lockedUntil: null }, { lockedUntil: { lt: now } }],
+    };
+}
+/** Whether this instance now holds the row: one update counts it. */
+async function claim(id, now) {
+    const { count } = await JobsRun.updateMany({
+        where: { AND: [{ id }, due(new Date(now))] },
+        data: { lockedUntil: new Date(now + lease) },
+    }, M);
+    return count === 1;
+}
+/** The first due time of a recurring job after `now`, on its cadence. */
+function following(job, row, now) {
+    let next = job.next(row.dueAt.getTime());
+    // Missed occurrences run once: the next is the first after now.
+    if (next <= now)
+        next = job.next(now);
+    return new Date(next);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function failed(app, row, job, error, now) {
+    const message = messageOf(error);
+    const facts = { err: error, job: row.job, run: row.id };
+    if (job?.schedule !== undefined && row.recurring !== null) {
+        app.logger.error(facts, `The job ${row.job} failed.`);
+        const dueAt = following(job, row, now);
+        const data = { dueAt, lockedUntil: null, error: message };
+        await JobsRun.update({ where: { id: row.id }, data }, M);
+        return;
+    }
+    const tried = row.attempts + 1;
+    const last = job === undefined || tried >= attempts;
+    if (last) {
+        app.logger.error(facts, `The job ${row.job} failed: its run is kept.`);
+    }
+    else {
+        app.logger.warn(facts, `The job ${row.job} failed: it runs again.`);
+    }
+    const data = {
+        attempts: tried,
+        lockedUntil: null,
+        error: message,
+        ...(last
+            ? { state: 'failed' }
+            : { dueAt: new Date(now + backoff * 2 ** (tried - 1)) }),
+    };
+    await JobsRun.update({ where: { id: row.id }, data }, M);
+}
+/** Runs the row once this instance holds it; whether it did. */
+async function runRow(app, id) {
+    const now = Date.now();
+    if (!(await claim(id, now)))
+        return false;
+    const row = await JobsRun.findUnique({ where: { id } }, M);
+    if (row === null)
+        return false;
+    const job = app.jobs.get(row.job);
+    if (job === undefined) {
+        const error = new Error(`The job ${row.job} is not in jobsPlugin's jobs.`);
+        await failed(app, row, job, error, now);
+        return true;
+    }
+    try {
+        await job.run(job.input === undefined ? { id } : { id, input: row.input });
+    }
+    catch (error) {
+        await failed(app, row, job, error, now);
+        return true;
+    }
+    if (row.recurring === null) {
+        await JobsRun.delete({ where: { id } }, M);
+    }
+    else {
+        const data = {
+            dueAt: following(job, row, now),
+            attempts: 0,
+            lockedUntil: null,
+            error: null,
+        };
+        await JobsRun.update({ where: { id }, data }, M);
+    }
+    return true;
+}
+/** The runs this instance has started and not finished. */
+const running = new Set();
+/** Starts the row's run; a failure outside the job is logged. */
+export function start(app, id) {
+    const run = runRow(app, id).catch((error) => {
+        app.logger.error({ err: error, run: id }, 'A job could not run.');
+        return false;
+    });
+    running.add(run);
+    void run.finally(() => running.delete(run));
+    return run;
+}
+/** Runs the rows due now, a batch at a time; how many it ran. */
+export async function pass(app) {
+    const rows = await JobsRun.findMany({
+        where: due(new Date()),
+        orderBy: [{ dueAt: 'asc' }],
+        take: batch,
+        select: { id: true },
+    }, M);
+    const ran = await Promise.all(rows.map((row) => start(app, row.id)));
+    return ran.filter(Boolean).length;
+}
+/** Waits for the runs this instance started. */
+export async function settled() {
+    await Promise.all(running);
+}
+/**
+ * Runs the due rows, and those their runs enqueue, until none is due:
+ * what `runJobs()` does.
+ */
+export async function drain(app) {
+    for (let passes = 0; passes < 100; passes++) {
+        await settled();
+        if ((await pass(app)) === 0 && running.size === 0)
+            return;
+    }
+    throw new Error('runJobs stopped after 100 passes: a job enqueues a run due at once each time it runs.');
+}
+/** Creates the rows of new recurring jobs, and deletes those of old ones. */
+export async function schedule(app) {
+    const now = Date.now();
+    const rows = await JobsRun.findMany({ where: { recurring: { not: null } } }, M);
+    for (const row of rows) {
+        const job = app.jobs.get(row.recurring ?? '');
+        if (job?.schedule === undefined) {
+            await JobsRun.delete({ where: { id: row.id } }, M);
+        }
+        else if (job.schedule !== row.schedule) {
+            const data = { schedule: job.schedule, dueAt: new Date(job.next(now)) };
+            await JobsRun.update({ where: { id: row.id }, data }, M);
+        }
+    }
+    const known = new Set(rows.map((row) => row.recurring));
+    for (const job of app.jobs.values()) {
+        if (job.schedule === undefined || known.has(job.name))
+            continue;
+        const create = {
+            job: job.name,
+            recurring: job.name,
+            schedule: job.schedule,
+            state: 'pending',
+            dueAt: new Date(job.next(now)),
+            attempts: 0,
+        };
+        // Another instance starting at once may have created it.
+        await JobsRun.upsert({ where: { recurring: job.name }, create, update: {} }, M);
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,12 @@
+import type { Logger } from 'ultimabase';
+import type { JobRecord } from './define-job.ts';
+export interface Running {
+    readonly jobs: ReadonlyMap<string, JobRecord>;
+    readonly logger: Logger;
+    /** Runs the row `id` now, in this instance. */
+    readonly kick: (id: string) => void;
+}
+export declare function useRunning(value: Running | undefined): void;
+/** The running plugin's state; `what` names the call that needs it. */
+export declare function runningOf(what: string): Running;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CACnC;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAE3D;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK/C"}

package/dist/state.js

@@ -0,0 +1,11 @@
+let running;
+export function useRunning(value) {
+    running = value;
+}
+/** The running plugin's state; `what` names the call that needs it. */
+export function runningOf(what) {
+    if (running === undefined) {
+        throw new Error(`${what} needs an application with jobsPlugin() started.`);
+    }
+    return running;
+}