@db3.ai/app 0.1.0-beta.1

package/dist/scheduler/ScheduledOccurrence.d.ts

@@ -0,0 +1,74 @@
+import { ActiveRecord, type FieldBuilder } from '../db/index.js';
+import type * as scheduler from './contracts/index.js';
+/**
+ * Values required to atomically claim one due scheduled occurrence.
+ */
+interface ScheduledOccurrenceClaim {
+    /** Stable registered schedule name. */
+    name: string;
+    /** Scheduled task kind. */
+    kind: scheduler.ScheduledTaskKind;
+    /** Canonical UTC minute represented by the occurrence. */
+    scheduledFor: Date;
+    /** Queue job name when known before a factory is invoked. */
+    jobName?: string;
+}
+/**
+ * Durable claim, execution state, and queue correlation for one scheduled task.
+ */
+export declare class ScheduledOccurrence extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    static labelFields: string[];
+    static comment: string;
+    /**
+     * Defines scheduler claim, queue correlation, lifecycle, and timing fields.
+     *
+     * @param field - ActiveRecord field builder.
+     * @returns Scheduled occurrence field definitions.
+     */
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").UlidField;
+        name: import("../db/index.js").StringField;
+        kind: import("../db/index.js").ChoiceStringField;
+        jobName: import("../db/index.js").StringField;
+        scheduledFor: import("../db/index.js").TimestampField;
+        status: import("../db/index.js").ChoiceStringField;
+        queueJobId: import("../db/index.js").StringField;
+        queueJobUuid: import("../db/index.js").CharUuidField;
+        attempts: import("../db/index.js").IntegerField;
+        maxTries: import("../db/index.js").IntegerField;
+        lastError: import("../db/index.js").TextField;
+        nextAttemptAt: import("../db/index.js").TimestampField;
+        claimedAt: import("../db/index.js").TimestampField;
+        dispatchedAt: import("../db/index.js").TimestampField;
+        startedAt: import("../db/index.js").TimestampField;
+        finishedAt: import("../db/index.js").TimestampField;
+        updatedAt: import("../db/index.js").TimestampField;
+    };
+    /**
+     * Atomically claims one scheduled minute using the model's unique index.
+     *
+     * @param claim - Due schedule identity and task metadata.
+     * @returns Newly claimed occurrence, or null when another process won.
+     */
+    static claim(claim: ScheduledOccurrenceClaim): Promise<ScheduledOccurrence | null>;
+    id: string | null;
+    name: string | null;
+    kind: scheduler.ScheduledTaskKind | null;
+    jobName: string | null;
+    scheduledFor: Date | null;
+    status: scheduler.ScheduledOccurrenceStatus | null;
+    queueJobId: string | null;
+    queueJobUuid: string | null;
+    attempts: number | null;
+    maxTries: number | null;
+    lastError: string | null;
+    nextAttemptAt: Date | null;
+    claimedAt: Date | null;
+    dispatchedAt: Date | null;
+    startedAt: Date | null;
+    finishedAt: Date | null;
+    updatedAt: Date | null;
+}
+export {};

package/dist/scheduler/ScheduledOccurrence.js

@@ -0,0 +1,194 @@
+import { ulid } from '@db3.ai/pure/ulid';
+import { ActiveRecord } from '../db/index.js';
+import { SCHEDULED_OCCURRENCE_STATUSES, SCHEDULED_TASK_KINDS } from './constants.js';
+const NAME_SCHEDULED_FOR_UNIQUE = 'scheduled_occurrences_name_scheduled_for_unique';
+const STATUS_SCHEDULED_FOR_INDEX = 'scheduled_occurrences_status_scheduled_for_index';
+/**
+ * Durable claim, execution state, and queue correlation for one scheduled task.
+ */
+export class ScheduledOccurrence extends ActiveRecord {
+    static table = 'scheduled_occurrences';
+    static primaryKey = 'id';
+    static labelFields = ['name', 'status'];
+    static comment = 'Durable scheduler claims and lifecycle state for registered task occurrences.';
+    /**
+     * Defines scheduler claim, queue correlation, lifecycle, and timing fields.
+     *
+     * @param field - ActiveRecord field builder.
+     * @returns Scheduled occurrence field definitions.
+     */
+    static fields(field) {
+        return {
+            id: field.ulid({
+                comment: 'Stable scheduled occurrence ULID.',
+            }),
+            name: field.string({
+                required: true,
+                length: 255,
+                maxLength: 255,
+                indexes: [{
+                        name: NAME_SCHEDULED_FOR_UNIQUE,
+                        columns: ['name', 'scheduled_for'],
+                        unique: true,
+                    }],
+                comment: 'Stable registered schedule name used for deduplication.',
+            }),
+            kind: field.choice({
+                required: true,
+                choices: SCHEDULED_TASK_KINDS,
+                length: 20,
+                maxLength: 20,
+                comment: 'Whether this occurrence dispatches a job or runs an inline call.',
+            }),
+            jobName: field.string({
+                column: 'job_name',
+                required: false,
+                length: 255,
+                maxLength: 255,
+                index: true,
+                comment: 'Durable queue job name for job occurrences.',
+            }),
+            scheduledFor: field.timestamp({
+                column: 'scheduled_for',
+                required: true,
+                precision: 0,
+                index: true,
+                comment: 'Canonical UTC minute represented by this occurrence.',
+            }),
+            status: field.choice({
+                required: true,
+                choices: SCHEDULED_OCCURRENCE_STATUSES,
+                default: 'claimed',
+                length: 20,
+                maxLength: 20,
+                indexes: [{
+                        name: STATUS_SCHEDULED_FOR_INDEX,
+                        columns: ['status', 'scheduled_for'],
+                    }],
+                comment: 'Current scheduler or queue lifecycle state.',
+            }),
+            queueJobId: field.string({
+                column: 'queue_job_id',
+                required: false,
+                length: 255,
+                maxLength: 255,
+                index: true,
+                comment: 'Driver-owned queue job id after dispatch.',
+            }),
+            queueJobUuid: field.charUuid({
+                column: 'queue_job_uuid',
+                required: false,
+                index: true,
+                comment: 'Stable queue UUID retained across job attempts.',
+            }),
+            attempts: field.integer({
+                required: true,
+                unsigned: true,
+                min: 0,
+                default: 0,
+                comment: 'Number of queue processing attempts observed.',
+            }),
+            maxTries: field.integer({
+                column: 'max_tries',
+                required: false,
+                unsigned: true,
+                min: 1,
+                comment: 'Maximum queue attempts configured for this job.',
+            }),
+            lastError: field.longText({
+                column: 'last_error',
+                required: false,
+                comment: 'Most recent dispatch, callback, retry, or terminal failure.',
+            }),
+            nextAttemptAt: field.timestamp({
+                column: 'next_attempt_at',
+                required: false,
+                precision: 0,
+                comment: 'Expected availability time after a retry or deferral.',
+            }),
+            claimedAt: field.timestamp({
+                column: 'claimed_at',
+                required: true,
+                precision: 3,
+                comment: 'Time at which a scheduler process won this occurrence claim.',
+            }),
+            dispatchedAt: field.timestamp({
+                column: 'dispatched_at',
+                required: false,
+                precision: 3,
+                comment: 'Time at which the queue accepted the scheduled job.',
+            }),
+            startedAt: field.timestamp({
+                column: 'started_at',
+                required: false,
+                precision: 3,
+                comment: 'First worker claim or inline callback start time.',
+            }),
+            finishedAt: field.timestamp({
+                column: 'finished_at',
+                required: false,
+                precision: 3,
+                comment: 'Terminal scheduler or queue completion time.',
+            }),
+            updatedAt: field.timestamp({
+                column: 'updated_at',
+                required: true,
+                precision: 3,
+                auto: 'update',
+                comment: 'Most recent lifecycle state change.',
+            }),
+        };
+    }
+    /**
+     * Atomically claims one scheduled minute using the model's unique index.
+     *
+     * @param claim - Due schedule identity and task metadata.
+     * @returns Newly claimed occurrence, or null when another process won.
+     */
+    static async claim(claim) {
+        const claimedAt = new Date();
+        const occurrence = this.create({
+            id: ulid(claimedAt),
+            name: claim.name,
+            kind: claim.kind,
+            jobName: claim.jobName,
+            scheduledFor: claim.scheduledFor,
+            status: 'claimed',
+            attempts: 0,
+            claimedAt,
+            updatedAt: claimedAt,
+        });
+        try {
+            await occurrence.save();
+            return occurrence;
+        }
+        catch (error) {
+            if (!isUniqueConstraintError(error))
+                throw error;
+            const existing = await this
+                .where({
+                name: claim.name,
+                scheduledFor: claim.scheduledFor,
+            })
+                .first();
+            if (existing)
+                return null;
+            throw error;
+        }
+    }
+}
+/**
+ * Returns whether a database error represents a unique-constraint conflict.
+ *
+ * @param error - Unknown database failure.
+ * @returns True for MariaDB, PostgreSQL, or SQLite unique conflicts.
+ */
+function isUniqueConstraintError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const code = String(error.code ?? '');
+    return code === 'ER_DUP_ENTRY'
+        || code === '23505'
+        || code === 'SQLITE_CONSTRAINT'
+        || code === 'SQLITE_CONSTRAINT_UNIQUE';
+}

package/dist/scheduler/ScheduledOccurrenceRecorder.d.ts

@@ -0,0 +1,34 @@
+import { type Database } from '../db/index.js';
+import type { QueueLifecycleEvent } from '../queue/index.js';
+/**
+ * Persists queue lifecycle events that originated from scheduled occurrences.
+ */
+export declare class ScheduledOccurrenceRecorder {
+    private readonly database;
+    /**
+     * Creates a recorder bound to one application database.
+     *
+     * @param database - Database containing scheduled occurrence records.
+     */
+    constructor(database: Database);
+    /**
+     * Applies one queue event when it references a scheduled occurrence.
+     *
+     * @param event - Queue lifecycle event emitted by the worker or dispatcher.
+     */
+    record(event: QueueLifecycleEvent): Promise<void>;
+    /**
+     * Maps one queue lifecycle event onto its persisted occurrence.
+     *
+     * @param occurrence - Scheduled occurrence being updated.
+     * @param event - Queue lifecycle event to apply.
+     */
+    private applyEvent;
+}
+/**
+ * Formats an unknown error for durable scheduler diagnostics.
+ *
+ * @param error - Unknown thrown value.
+ * @returns Stack or human-readable error text.
+ */
+export declare function errorDetails(error: unknown): string;

package/dist/scheduler/ScheduledOccurrenceRecorder.js

@@ -0,0 +1,106 @@
+import { ActiveRecord } from '../db/index.js';
+import { SCHEDULED_OCCURRENCE_ORIGIN } from './constants.js';
+import { ScheduledOccurrence } from './ScheduledOccurrence.js';
+const TERMINAL_STATUSES = new Set(['succeeded', 'failed']);
+/**
+ * Persists queue lifecycle events that originated from scheduled occurrences.
+ */
+export class ScheduledOccurrenceRecorder {
+    database;
+    /**
+     * Creates a recorder bound to one application database.
+     *
+     * @param database - Database containing scheduled occurrence records.
+     */
+    constructor(database) {
+        this.database = database;
+    }
+    /**
+     * Applies one queue event when it references a scheduled occurrence.
+     *
+     * @param event - Queue lifecycle event emitted by the worker or dispatcher.
+     */
+    async record(event) {
+        if (event.origin?.type !== SCHEDULED_OCCURRENCE_ORIGIN)
+            return;
+        await ActiveRecord.withDb(this.database.knex, async () => {
+            const occurrence = await ScheduledOccurrence.findByPk(event.origin?.id);
+            if (!occurrence) {
+                throw new Error(`Scheduled occurrence "${event.origin?.id}" was not found.`);
+            }
+            if (occurrence.status && TERMINAL_STATUSES.has(occurrence.status))
+                return;
+            this.applyEvent(occurrence, event);
+            await occurrence.save();
+        });
+    }
+    /**
+     * Maps one queue lifecycle event onto its persisted occurrence.
+     *
+     * @param occurrence - Scheduled occurrence being updated.
+     * @param event - Queue lifecycle event to apply.
+     */
+    applyEvent(occurrence, event) {
+        if (event.action === 'lease_lost')
+            return;
+        const timestamp = new Date(event.timestamp);
+        occurrence.jobName = event.jobName;
+        occurrence.queueJobId = String(event.jobId);
+        occurrence.queueJobUuid = event.jobUuid;
+        occurrence.attempts = event.attempts;
+        occurrence.maxTries = event.maxTries;
+        if (event.error !== undefined) {
+            occurrence.lastError = errorDetails(event.error);
+        }
+        switch (event.action) {
+            case 'dispatched':
+                occurrence.status = 'queued';
+                occurrence.dispatchedAt ??= timestamp;
+                break;
+            case 'claimed':
+                occurrence.status = 'running';
+                occurrence.startedAt ??= timestamp;
+                occurrence.nextAttemptAt = null;
+                break;
+            case 'released':
+                occurrence.status = 'retrying';
+                occurrence.nextAttemptAt = delayedDate(timestamp, event.delaySeconds);
+                break;
+            case 'deferred':
+                occurrence.status = 'deferred';
+                occurrence.nextAttemptAt = delayedDate(timestamp, event.delaySeconds);
+                break;
+            case 'succeeded':
+                occurrence.status = 'succeeded';
+                occurrence.nextAttemptAt = null;
+                occurrence.finishedAt = timestamp;
+                break;
+            case 'failed':
+                occurrence.status = 'failed';
+                occurrence.nextAttemptAt = null;
+                occurrence.finishedAt = timestamp;
+                break;
+        }
+    }
+}
+/**
+ * Calculates the expected next-attempt time for a delayed queue event.
+ *
+ * @param timestamp - Time at which the queue transition occurred.
+ * @param delaySeconds - Delay before the next attempt.
+ * @returns Expected next attempt time.
+ */
+function delayedDate(timestamp, delaySeconds = 0) {
+    return new Date(timestamp.getTime() + Math.max(0, delaySeconds) * 1000);
+}
+/**
+ * Formats an unknown error for durable scheduler diagnostics.
+ *
+ * @param error - Unknown thrown value.
+ * @returns Stack or human-readable error text.
+ */
+export function errorDetails(error) {
+    if (error instanceof Error)
+        return error.stack ?? error.message;
+    return String(error);
+}

package/dist/scheduler/Scheduler.d.ts

@@ -0,0 +1,76 @@
+import { type Database } from '../db/index.js';
+import { type Queue } from '../queue/index.js';
+import type * as scheduler from './contracts/index.js';
+import { ScheduledCall } from './ScheduledCall.js';
+import { ScheduledJob } from './ScheduledJob.js';
+/**
+ * Registers daily tasks, atomically claims due occurrences, and dispatches work.
+ */
+export declare class Scheduler {
+    #private;
+    private readonly database;
+    private readonly queue;
+    /**
+     * Creates a scheduler and attaches durable queue lifecycle recording.
+     *
+     * @param database - Application database containing occurrence history.
+     * @param queue - Queue used to dispatch scheduled jobs.
+     */
+    constructor(database: Database, queue: Queue);
+    /**
+     * Registers a QueueableJob class or fresh-job factory.
+     *
+     * @param source - Zero-argument job class or parameterised factory.
+     * @returns Fluent scheduled job definition.
+     */
+    job(source: scheduler.ScheduledJobSource): ScheduledJob;
+    /**
+     * Registers a short inline callback.
+     *
+     * @param callback - Callback executed directly by the scheduler worker.
+     * @returns Fluent scheduled call definition.
+     */
+    call(callback: scheduler.ScheduledCallHandler): ScheduledCall;
+    /**
+     * Returns validated normalized definitions in registration order.
+     *
+     * @returns Registered scheduler definitions.
+     */
+    definitions(): scheduler.ScheduledTaskDefinition[];
+    /**
+     * Evaluates and handles every task due for one canonical UTC minute.
+     *
+     * Due tasks run sequentially in registration order. Immediate failures are
+     * recorded and aggregated so one task cannot prevent later tasks from being
+     * considered.
+     *
+     * @param now - Instant whose UTC minute should be evaluated.
+     * @returns Structured evaluation summary.
+     */
+    runDue(now?: Date): Promise<scheduler.SchedulerRunResult>;
+    /**
+     * Detaches queue lifecycle recording owned by this scheduler instance.
+     */
+    close(): void;
+    /**
+     * Creates and dispatches one job with occurrence origin metadata.
+     *
+     * @param event - Claimed scheduled job definition.
+     * @param occurrence - Durable occurrence receiving queue events.
+     */
+    private dispatchJob;
+    /**
+     * Runs one short inline callback and records its terminal state.
+     *
+     * @param event - Claimed scheduled callback.
+     * @param occurrence - Durable occurrence to update.
+     */
+    private runCall;
+    /**
+     * Records an immediate dispatch, factory, or inline callback failure.
+     *
+     * @param occurrence - Claimed occurrence that failed.
+     * @param error - Immediate scheduler error.
+     */
+    private failOccurrence;
+}

package/dist/scheduler/Scheduler.js

@@ -0,0 +1,186 @@
+import { ActiveRecord } from '../db/index.js';
+import { isQueueableJobClass, queueableJobName } from '../queue/index.js';
+import { SCHEDULED_OCCURRENCE_ORIGIN } from './constants.js';
+import { ScheduledCall } from './ScheduledCall.js';
+import { ScheduledJob } from './ScheduledJob.js';
+import { ScheduledOccurrence } from './ScheduledOccurrence.js';
+import { ScheduledOccurrenceRecorder, errorDetails } from './ScheduledOccurrenceRecorder.js';
+import { utcMinute } from './scheduleTime.js';
+/**
+ * Registers daily tasks, atomically claims due occurrences, and dispatches work.
+ */
+export class Scheduler {
+    database;
+    queue;
+    #events = [];
+    #unsubscribeQueueEvents;
+    /**
+     * Creates a scheduler and attaches durable queue lifecycle recording.
+     *
+     * @param database - Application database containing occurrence history.
+     * @param queue - Queue used to dispatch scheduled jobs.
+     */
+    constructor(database, queue) {
+        this.database = database;
+        this.queue = queue;
+        const recorder = new ScheduledOccurrenceRecorder(database);
+        this.#unsubscribeQueueEvents = queue.events.subscribe(event => {
+            return recorder.record(event);
+        });
+    }
+    /**
+     * Registers a QueueableJob class or fresh-job factory.
+     *
+     * @param source - Zero-argument job class or parameterised factory.
+     * @returns Fluent scheduled job definition.
+     */
+    job(source) {
+        const event = new ScheduledJob(source);
+        this.#events.push(event);
+        return event;
+    }
+    /**
+     * Registers a short inline callback.
+     *
+     * @param callback - Callback executed directly by the scheduler worker.
+     * @returns Fluent scheduled call definition.
+     */
+    call(callback) {
+        const event = new ScheduledCall(callback);
+        this.#events.push(event);
+        return event;
+    }
+    /**
+     * Returns validated normalized definitions in registration order.
+     *
+     * @returns Registered scheduler definitions.
+     */
+    definitions() {
+        const definitions = this.#events.map(event => event.definition());
+        const names = new Set();
+        for (const definition of definitions) {
+            if (names.has(definition.name)) {
+                throw new Error(`Duplicate scheduled event name "${definition.name}".`);
+            }
+            names.add(definition.name);
+        }
+        return definitions;
+    }
+    /**
+     * Evaluates and handles every task due for one canonical UTC minute.
+     *
+     * Due tasks run sequentially in registration order. Immediate failures are
+     * recorded and aggregated so one task cannot prevent later tasks from being
+     * considered.
+     *
+     * @param now - Instant whose UTC minute should be evaluated.
+     * @returns Structured evaluation summary.
+     */
+    async runDue(now = new Date()) {
+        const startedAt = new Date();
+        const evaluatedFor = utcMinute(now);
+        this.definitions();
+        const dueEvents = this.#events.filter(event => event.isDue(evaluatedFor));
+        const result = {
+            evaluatedFor,
+            startedAt,
+            finishedAt: startedAt,
+            due: dueEvents.length,
+            claimed: 0,
+            dispatched: 0,
+            completed: 0,
+            skipped: 0,
+            failures: [],
+        };
+        for (const event of dueEvents) {
+            const definition = event.definition();
+            const occurrence = await ActiveRecord.withDb(this.database.knex, () => {
+                return ScheduledOccurrence.claim({
+                    name: definition.name,
+                    kind: definition.kind,
+                    scheduledFor: evaluatedFor,
+                    jobName: definition.jobName,
+                });
+            });
+            if (!occurrence) {
+                result.skipped += 1;
+                continue;
+            }
+            result.claimed += 1;
+            try {
+                if (event instanceof ScheduledJob) {
+                    await this.dispatchJob(event, occurrence);
+                    result.dispatched += 1;
+                }
+                else if (event instanceof ScheduledCall) {
+                    await this.runCall(event, occurrence);
+                    result.completed += 1;
+                }
+            }
+            catch (error) {
+                await this.failOccurrence(occurrence, error);
+                result.failures.push({
+                    name: definition.name,
+                    error: errorDetails(error),
+                });
+            }
+        }
+        result.finishedAt = new Date();
+        return result;
+    }
+    /**
+     * Detaches queue lifecycle recording owned by this scheduler instance.
+     */
+    close() {
+        this.#unsubscribeQueueEvents();
+    }
+    /**
+     * Creates and dispatches one job with occurrence origin metadata.
+     *
+     * @param event - Claimed scheduled job definition.
+     * @param occurrence - Durable occurrence receiving queue events.
+     */
+    async dispatchJob(event, occurrence) {
+        const job = event.createJob();
+        const Job = job.constructor;
+        occurrence.jobName = isQueueableJobClass(Job)
+            ? queueableJobName(Job)
+            : Job.name;
+        await ActiveRecord.withDb(this.database.knex, () => occurrence.save());
+        await this.queue.dispatch(job, {
+            origin: {
+                type: SCHEDULED_OCCURRENCE_ORIGIN,
+                id: occurrence.id,
+            },
+        });
+    }
+    /**
+     * Runs one short inline callback and records its terminal state.
+     *
+     * @param event - Claimed scheduled callback.
+     * @param occurrence - Durable occurrence to update.
+     */
+    async runCall(event, occurrence) {
+        const startedAt = new Date();
+        occurrence.status = 'running';
+        occurrence.startedAt = startedAt;
+        await ActiveRecord.withDb(this.database.knex, () => occurrence.save());
+        await event.run();
+        occurrence.status = 'succeeded';
+        occurrence.finishedAt = new Date();
+        await ActiveRecord.withDb(this.database.knex, () => occurrence.save());
+    }
+    /**
+     * Records an immediate dispatch, factory, or inline callback failure.
+     *
+     * @param occurrence - Claimed occurrence that failed.
+     * @param error - Immediate scheduler error.
+     */
+    async failOccurrence(occurrence, error) {
+        occurrence.status = 'failed';
+        occurrence.lastError = errorDetails(error);
+        occurrence.nextAttemptAt = null;
+        occurrence.finishedAt = new Date();
+        await ActiveRecord.withDb(this.database.knex, () => occurrence.save());
+    }
+}