enqiu 0.1.0

package/dist/cron.js

@@ -0,0 +1,217 @@
+const monthNames = new Map([
+    ["jan", 1],
+    ["feb", 2],
+    ["mar", 3],
+    ["apr", 4],
+    ["may", 5],
+    ["jun", 6],
+    ["jul", 7],
+    ["aug", 8],
+    ["sep", 9],
+    ["oct", 10],
+    ["nov", 11],
+    ["dec", 12],
+]);
+const weekdayNames = new Map([
+    ["sun", 0],
+    ["mon", 1],
+    ["tue", 2],
+    ["wed", 3],
+    ["thu", 4],
+    ["fri", 5],
+    ["sat", 6],
+]);
+const formatters = new Map();
+export class CronExpressionError extends TypeError {
+    constructor(message) {
+        super(message);
+        this.name = "CronExpressionError";
+    }
+}
+export function parseCron(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new CronExpressionError("Cron expressions must contain five fields: minute hour day month weekday");
+    }
+    return {
+        expression,
+        minute: parseField(fields[0], 0, 59),
+        hour: parseField(fields[1], 0, 23),
+        dayOfMonth: parseField(fields[2], 1, 31),
+        month: parseField(fields[3], 1, 12, monthNames),
+        dayOfWeek: parseField(fields[4], 0, 7, weekdayNames, true),
+    };
+}
+export function validateTimeZone(timeZone) {
+    const normalized = timeZone.trim();
+    if (!normalized) {
+        throw new RangeError("timezone must not be empty");
+    }
+    try {
+        getFormatter(normalized).format(0);
+    }
+    catch {
+        throw new RangeError(`Invalid IANA timezone "${timeZone}"`);
+    }
+    return normalized;
+}
+export function nextCronOccurrence(cron, timeZone, after) {
+    if (!Number.isFinite(after)) {
+        throw new RangeError("The cron cursor must be a finite timestamp");
+    }
+    const parsed = typeof cron === "string" ? parseCron(cron) : cron;
+    const zone = validateTimeZone(timeZone);
+    const current = zonedParts(after, zone);
+    let localCursor = Date.UTC(current.year, current.month - 1, current.day, current.hour, current.minute);
+    const finalCursor = localCursor + 366 * 24 * 60 * 60 * 1000 * 5;
+    while (localCursor <= finalCursor) {
+        const date = new Date(localCursor);
+        const parts = {
+            year: date.getUTCFullYear(),
+            month: date.getUTCMonth() + 1,
+            day: date.getUTCDate(),
+            hour: date.getUTCHours(),
+            minute: date.getUTCMinutes(),
+            weekday: date.getUTCDay(),
+        };
+        if (matches(parsed, parts)) {
+            const candidates = localPartsToEpochs(parts, zone);
+            const next = candidates.find((candidate) => candidate > after);
+            if (next !== undefined) {
+                return next;
+            }
+        }
+        localCursor += 60_000;
+    }
+    throw new CronExpressionError(`Cron expression "${parsed.expression}" has no occurrence within five years`);
+}
+function parseField(source, minimum, maximum, names, normalizeSunday = false) {
+    const values = new Set();
+    const wildcard = source === "*" || source.startsWith("*/");
+    for (const segment of source.toLowerCase().split(",")) {
+        if (!segment) {
+            throw new CronExpressionError(`Invalid empty cron field in "${source}"`);
+        }
+        const [rangeSource, stepSource, extra] = segment.split("/");
+        if (extra !== undefined || rangeSource === undefined) {
+            throw new CronExpressionError(`Invalid cron field "${source}"`);
+        }
+        const step = stepSource === undefined
+            ? 1
+            : parseInteger(stepSource, "step");
+        if (step < 1) {
+            throw new CronExpressionError("Cron steps must be positive");
+        }
+        let start;
+        let end;
+        if (rangeSource === "*") {
+            start = minimum;
+            end = maximum;
+        }
+        else {
+            const range = rangeSource.split("-");
+            if (range.length > 2) {
+                throw new CronExpressionError(`Invalid cron range "${rangeSource}"`);
+            }
+            start = parseValue(range[0], names);
+            end =
+                range[1] === undefined ? start : parseValue(range[1], names);
+        }
+        if (start < minimum ||
+            start > maximum ||
+            end < minimum ||
+            end > maximum ||
+            start > end) {
+            throw new CronExpressionError(`Cron value "${rangeSource}" must be between ${minimum} and ${maximum}`);
+        }
+        for (let value = start; value <= end; value += step) {
+            values.add(normalizeSunday && value === 7 ? 0 : value);
+        }
+    }
+    return { wildcard, values };
+}
+function parseValue(source, names) {
+    const named = names?.get(source);
+    return named ?? parseInteger(source, "value");
+}
+function parseInteger(source, label) {
+    if (!/^\d+$/.test(source)) {
+        throw new CronExpressionError(`Invalid cron ${label} "${source}"`);
+    }
+    return Number.parseInt(source, 10);
+}
+function matches(cron, parts) {
+    if (!cron.minute.values.has(parts.minute) ||
+        !cron.hour.values.has(parts.hour) ||
+        !cron.month.values.has(parts.month)) {
+        return false;
+    }
+    const dayOfMonth = cron.dayOfMonth.values.has(parts.day);
+    const dayOfWeek = cron.dayOfWeek.values.has(parts.weekday);
+    if (!cron.dayOfMonth.wildcard && !cron.dayOfWeek.wildcard) {
+        return dayOfMonth || dayOfWeek;
+    }
+    return dayOfMonth && dayOfWeek;
+}
+function localPartsToEpochs(parts, timeZone) {
+    const naive = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute);
+    const guesses = new Set();
+    let candidate = naive;
+    for (let iteration = 0; iteration < 4; iteration += 1) {
+        const actual = zonedParts(candidate, timeZone);
+        const represented = Date.UTC(actual.year, actual.month - 1, actual.day, actual.hour, actual.minute);
+        candidate += naive - represented;
+        guesses.add(candidate);
+    }
+    for (const delta of [
+        -3_600_000,
+        3_600_000,
+        -7_200_000,
+        7_200_000,
+    ]) {
+        guesses.add(candidate + delta);
+    }
+    return [...guesses]
+        .filter((value) => equalLocalParts(zonedParts(value, timeZone), parts))
+        .sort((left, right) => left - right);
+}
+function equalLocalParts(left, right) {
+    return (left.year === right.year &&
+        left.month === right.month &&
+        left.day === right.day &&
+        left.hour === right.hour &&
+        left.minute === right.minute);
+}
+function zonedParts(timestamp, timeZone) {
+    const parts = getFormatter(timeZone).formatToParts(timestamp);
+    const values = new Map(parts.map((part) => [part.type, part.value]));
+    const weekday = weekdayNames.get((values.get("weekday") ?? "").toLowerCase());
+    if (weekday === undefined) {
+        throw new RangeError(`Could not resolve timezone "${timeZone}"`);
+    }
+    return {
+        year: Number(values.get("year")),
+        month: Number(values.get("month")),
+        day: Number(values.get("day")),
+        hour: Number(values.get("hour")),
+        minute: Number(values.get("minute")),
+        weekday,
+    };
+}
+function getFormatter(timeZone) {
+    let formatter = formatters.get(timeZone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            weekday: "short",
+            hourCycle: "h23",
+        });
+        formatters.set(timeZone, formatter);
+    }
+    return formatter;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { JobCancelledError, JobExpiredError, JobFailedError, JobSerializationError, JobTimeoutError, JobValidationError, QueueClosedError, job, enqiu, } from "./api.js";
+export type { AnyJobSnapshot, BulkOptions, CleanupQuery, ConcurrencyPolicy, DebouncePolicy, HandlerJobDefinition, InferSchemaInput, InferSchemaOutput, JobCallable, JobContext, JobDefinition, JobDefinitions, JobHandle, JobHandler, JobListPage, JobListQuery, JobLogger, JobPolicyOptions, JobsApi, MemoryEnqiuOptions, Progress, EnqiuOptions, QueueApi, RedisEnqiuOptions, RetryPolicy, ScheduleHandle, ScheduleOptions, ScheduleSnapshot, SchemaJobDefinition, SharedEnqiuOptions, StandardSchemaIssue, StandardSchemaV1, SubmitOptions, Telemetry, TelemetryEvent, ThrottlePolicy, WorkerApi, WorkerOptions, WorkerStartOptions, } from "./api.js";
+export { redis, type RedisCommandClient, type RedisDriver, type RedisDriverOptions, } from "./redis.js";
+export type { JobSnapshot, JobStatus, JobLogEntry, JobLogLevel, QueueEventMap, QueueStats, SerializedError, } from "./memory.js";
+export { enqiu as default } from "./api.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { JobCancelledError, JobExpiredError, JobFailedError, JobSerializationError, JobTimeoutError, JobValidationError, QueueClosedError, job, enqiu, } from "./api.js";
+export { redis, } from "./redis.js";
+export { enqiu as default } from "./api.js";

package/dist/memory-scheduler.d.ts

@@ -0,0 +1,24 @@
+import type { ScheduleHandle, ScheduleSnapshot } from "./api.js";
+export interface MemoryScheduleRegistration {
+    id?: string;
+    jobName: string;
+    cron: string;
+    timezone?: string;
+    input: unknown;
+    catchUp?: boolean;
+    enqueue(input: unknown, occurrence: number): Promise<void>;
+}
+export declare class MemoryScheduler {
+    private readonly schedules;
+    private closed;
+    upsert(registration: MemoryScheduleRegistration): Promise<ScheduleHandle>;
+    get(id: string): ScheduleSnapshot | undefined;
+    pause(id: string): void;
+    resume(id: string): void;
+    remove(id: string): void;
+    close(): void;
+    private arm;
+    private tick;
+    private require;
+    private assertOpen;
+}

package/dist/memory-scheduler.js

@@ -0,0 +1,163 @@
+import { nextCronOccurrence, parseCron, validateTimeZone, } from "./cron.js";
+export class MemoryScheduler {
+    schedules = new Map();
+    closed = false;
+    async upsert(registration) {
+        this.assertOpen();
+        parseCron(registration.cron);
+        const timezone = validateTimeZone(registration.timezone ?? "UTC");
+        const id = registration.id?.trim() || registration.jobName;
+        if (!id) {
+            throw new TypeError("schedule.id must not be empty");
+        }
+        const existing = this.schedules.get(id);
+        const now = Date.now();
+        const schedule = existing ?? {
+            id,
+            jobName: registration.jobName,
+            cron: registration.cron,
+            timezone,
+            status: "active",
+            nextRunAt: 0,
+            input: registration.input,
+            catchUp: registration.catchUp ?? false,
+            enqueue: registration.enqueue,
+            timer: undefined,
+            revision: 0,
+        };
+        if (existing && existing.jobName !== registration.jobName) {
+            throw new Error(`Schedule "${id}" already belongs to job "${existing.jobName}"`);
+        }
+        schedule.cron = registration.cron;
+        schedule.timezone = timezone;
+        schedule.input = registration.input;
+        schedule.catchUp = registration.catchUp ?? false;
+        schedule.enqueue = registration.enqueue;
+        schedule.nextRunAt = nextCronOccurrence(schedule.cron, schedule.timezone, now);
+        schedule.revision += 1;
+        this.schedules.set(id, schedule);
+        this.arm(schedule);
+        return new MemoryScheduleHandle(this, id);
+    }
+    get(id) {
+        const schedule = this.schedules.get(id);
+        return schedule ? snapshot(schedule) : undefined;
+    }
+    pause(id) {
+        const schedule = this.require(id);
+        schedule.status = "paused";
+        schedule.revision += 1;
+        clearScheduleTimer(schedule);
+    }
+    resume(id) {
+        const schedule = this.require(id);
+        schedule.status = "active";
+        schedule.nextRunAt = nextCronOccurrence(schedule.cron, schedule.timezone, Date.now());
+        schedule.revision += 1;
+        this.arm(schedule);
+    }
+    remove(id) {
+        const schedule = this.require(id);
+        clearScheduleTimer(schedule);
+        this.schedules.delete(id);
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        for (const schedule of this.schedules.values()) {
+            clearScheduleTimer(schedule);
+        }
+    }
+    arm(schedule) {
+        clearScheduleTimer(schedule);
+        if (this.closed || schedule.status !== "active") {
+            return;
+        }
+        const revision = schedule.revision;
+        const delay = Math.max(0, schedule.nextRunAt - Date.now());
+        schedule.timer = setTimeout(() => {
+            schedule.timer = undefined;
+            void this.tick(schedule.id, revision);
+        }, Math.min(delay, 2_147_483_647));
+    }
+    async tick(id, revision) {
+        const schedule = this.schedules.get(id);
+        if (!schedule ||
+            schedule.status !== "active" ||
+            schedule.revision !== revision ||
+            this.closed) {
+            return;
+        }
+        const occurrence = schedule.nextRunAt;
+        const now = Date.now();
+        schedule.nextRunAt = nextCronOccurrence(schedule.cron, schedule.timezone, schedule.catchUp ? occurrence : now);
+        schedule.revision += 1;
+        this.arm(schedule);
+        try {
+            await schedule.enqueue(schedule.input, occurrence);
+        }
+        catch {
+            // Submission failures remain observable through queue events/telemetry.
+            // A schedule must continue advancing instead of creating a hot loop.
+        }
+    }
+    require(id) {
+        const schedule = this.schedules.get(id);
+        if (!schedule) {
+            throw new Error(`Schedule "${id}" does not exist`);
+        }
+        return schedule;
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new Error("Scheduler is closed");
+        }
+    }
+}
+class MemoryScheduleHandle {
+    owner;
+    id;
+    constructor(owner, id) {
+        this.owner = owner;
+        this.id = id;
+    }
+    get nextRunAt() {
+        return this.owner.get(this.id)?.nextRunAt ?? 0;
+    }
+    async pause() {
+        this.owner.pause(this.id);
+    }
+    async resume() {
+        this.owner.resume(this.id);
+    }
+    async remove() {
+        this.owner.remove(this.id);
+    }
+    async refresh() {
+        const value = this.owner.get(this.id);
+        if (!value) {
+            throw new Error(`Schedule "${this.id}" does not exist`);
+        }
+        return value;
+    }
+}
+function snapshot(schedule) {
+    return {
+        id: schedule.id,
+        jobName: schedule.jobName,
+        cron: schedule.cron,
+        timezone: schedule.timezone,
+        status: schedule.status,
+        nextRunAt: schedule.nextRunAt,
+        input: schedule.input,
+        catchUp: schedule.catchUp,
+    };
+}
+function clearScheduleTimer(schedule) {
+    if (schedule.timer !== undefined) {
+        clearTimeout(schedule.timer);
+        schedule.timer = undefined;
+    }
+}