enqiu 0.1.0

package/dist/api.js

@@ -0,0 +1,519 @@
+import { MemoryQueue, JobCancelledError, JobExpiredError, JobFailedError, JobTimeoutError, QueueClosedError, } from "./memory.js";
+import { RedisQueue, } from "./redis.js";
+import { JobSerializationError, cloneJobValue, } from "./codec.js";
+import { MemoryScheduler } from "./memory-scheduler.js";
+const definitionMarker = Symbol("enqiu.job");
+const reservedNames = new Set(["queue", "worker"]);
+export function job(definition) {
+    if (!definition || typeof definition !== "object") {
+        throw new TypeError("job() requires a definition object");
+    }
+    if (!isStandardSchema(definition.input)) {
+        throw new TypeError("job.input must implement Standard Schema");
+    }
+    if (typeof definition.run !== "function") {
+        throw new TypeError("job.run must be a function");
+    }
+    return Object.freeze({
+        ...definition,
+        [definitionMarker]: true,
+    });
+}
+export class JobValidationError extends TypeError {
+    issues;
+    constructor(name, issues) {
+        super(`Invalid input for job "${name}": ${issues[0]?.message ?? "validation failed"}`);
+        this.name = "JobValidationError";
+        this.issues = issues;
+    }
+}
+class PublicJobHandle {
+    legacy;
+    resultPromise;
+    constructor(legacy) {
+        this.legacy = legacy;
+    }
+    get id() {
+        return this.legacy.id;
+    }
+    get name() {
+        return this.legacy.name;
+    }
+    get input() {
+        return this.legacy.input;
+    }
+    get status() {
+        return this.legacy.status;
+    }
+    get deduplicated() {
+        return this.legacy.deduplicated;
+    }
+    get result() {
+        this.resultPromise ??= this.legacy.result;
+        return this.resultPromise;
+    }
+    async cancel(reason) {
+        return this.legacy.cancel(reason);
+    }
+    async refresh() {
+        if ("refresh" in this.legacy) {
+            return this.legacy.refresh();
+        }
+        return this.legacy.snapshot();
+    }
+}
+class EnqiuFacade {
+    options;
+    api;
+    definitions = new Map();
+    memory;
+    redis;
+    memoryScheduler;
+    workerRunning;
+    constructor(definitions, options) {
+        this.options = options;
+        const handlers = {};
+        for (const [name, definition] of Object.entries(definitions)) {
+            if (reservedNames.has(name)) {
+                throw new TypeError(`"${name}" is reserved by enqiu`);
+            }
+            const normalized = normalizeDefinition(definition);
+            this.definitions.set(name, normalized);
+            handlers[name] = async (input, context) => {
+                const output = await normalized.run(input, createContext(context, options.name ?? "default", options.telemetry));
+                return cloneJobValue(output);
+            };
+        }
+        if (this.definitions.size === 0) {
+            throw new TypeError("At least one job definition is required");
+        }
+        const concurrency = options.worker === false ? 1 : options.worker?.concurrency;
+        const autoStart = options.worker === false
+            ? false
+            : options.worker?.autoStart ?? true;
+        const retry = normalizeLegacyRetry(options.retry);
+        if (options.driver) {
+            this.redis = new RedisQueue(handlers, compact({
+                driver: options.driver,
+                name: options.name,
+                worker: options.worker !== false,
+                concurrency,
+                autoStart,
+                retry: retry,
+                timeout: options.timeout,
+                historyLimit: options.historyLimit,
+                logLimit: options.logLimit,
+            }));
+            this.workerRunning = autoStart && options.worker !== false;
+        }
+        else {
+            this.memory = new MemoryQueue(handlers, compact({
+                name: options.name,
+                concurrency,
+                autoStart,
+                retry,
+                timeout: options.timeout,
+                historyLimit: options.historyLimit,
+                logLimit: options.logLimit,
+            }));
+            this.memoryScheduler = new MemoryScheduler();
+            this.workerRunning = autoStart;
+        }
+        const target = {};
+        for (const name of this.definitions.keys()) {
+            target[name] = this.createCallable(name);
+        }
+        target.queue = this.createQueueApi();
+        target.worker = this.createWorkerApi();
+        this.api = Object.freeze(target);
+        this.connectTelemetry();
+    }
+    get queue() {
+        return this.redis ?? this.memory;
+    }
+    createCallable(name) {
+        const definition = this.definitions.get(name);
+        if (!definition) {
+            throw new TypeError(`Unknown job "${name}"`);
+        }
+        const callable = async (input, options = {}) => {
+            const value = cloneJobValue(await validateInput(name, definition.schema, input));
+            const legacy = this.addLegacy(name, value, toLegacyOptions(options, definition.policy, name, value));
+            if ("accepted" in legacy) {
+                await legacy.accepted;
+            }
+            return new PublicJobHandle(legacy);
+        };
+        const bulk = async (inputs, options = {}) => {
+            if (options.ids && options.ids.length !== inputs.length) {
+                throw new RangeError("bulk ids must match the number of inputs");
+            }
+            const values = await Promise.all(inputs.map(async (input) => cloneJobValue(await validateInput(name, definition.schema, input))));
+            const handles = values.map((value, index) => {
+                const id = options.ids?.[index];
+                const submitOptions = compact({
+                    ...options,
+                    ids: undefined,
+                    id,
+                });
+                return this.addLegacy(name, value, toLegacyOptions(submitOptions, definition.policy, name, value));
+            });
+            await Promise.all(handles.map((handle) => "accepted" in handle ? handle.accepted : Promise.resolve()));
+            return handles.map((handle) => new PublicJobHandle(handle));
+        };
+        const schedule = async (options) => {
+            const value = cloneJobValue(await validateInput(name, definition.schema, options.input));
+            if (this.redis) {
+                return this.redis.upsertSchedule({
+                    ...options,
+                    input: value,
+                    jobName: name,
+                    submit: toLegacyOptions({}, definition.policy, name, value),
+                });
+            }
+            const scheduleId = options.id?.trim() || name;
+            return this.memoryScheduler.upsert({
+                ...options,
+                input: value,
+                jobName: name,
+                enqueue: async (scheduledInput, occurrence) => {
+                    const handle = await callable(scheduledInput, {
+                        id: `${this.options.name ?? "default"}:schedule:${scheduleId}:${occurrence}`,
+                    });
+                    void handle;
+                },
+            });
+        };
+        Object.defineProperties(callable, {
+            bulk: { value: bulk, enumerable: true },
+            schedule: { value: schedule, enumerable: true },
+            input: { value: definition.schema, enumerable: true },
+        });
+        return callable;
+    }
+    createQueueApi() {
+        return Object.freeze({
+            get: async (id) => (await this.queue.get(id)),
+            list: async (query = {}) => {
+                if (this.redis) {
+                    return this.redis.list(query);
+                }
+                let jobs = this.memory?.list(query.status) ?? [];
+                if (query.name) {
+                    jobs = jobs.filter((item) => item.name === query.name);
+                }
+                if (query.after !== undefined) {
+                    jobs = jobs.filter((item) => item.createdAt > query.after);
+                }
+                if (query.before !== undefined) {
+                    jobs = jobs.filter((item) => item.createdAt < query.before);
+                }
+                const limit = query.limit ?? 100;
+                return {
+                    jobs: jobs.slice(0, limit),
+                };
+            },
+            stats: async () => this.redis ? this.redis.stats() : this.memory.stats,
+            pause: async () => {
+                if (this.redis) {
+                    await this.redis.pauseQueue();
+                }
+                else {
+                    this.memory?.pause();
+                }
+            },
+            resume: async () => {
+                if (this.redis) {
+                    await this.redis.resumeQueue();
+                }
+                else {
+                    this.memory?.start();
+                }
+            },
+            setConcurrency: async (limit) => {
+                if (this.redis) {
+                    await this.redis.setGlobalConcurrency(limit);
+                    return;
+                }
+                this.memory.concurrency = limit;
+            },
+            redrive: async (id) => {
+                if (this.redis) {
+                    return new PublicJobHandle((await this.redis.redrive(id)));
+                }
+                const handle = this.memory?.retry(id);
+                if (!handle) {
+                    throw new Error(`Job "${id}" cannot be redriven`);
+                }
+                return new PublicJobHandle(handle);
+            },
+            cleanup: async (query = {}) => {
+                if (this.redis) {
+                    return this.redis.cleanup(query);
+                }
+                return (this.memory?.cleanup(compact({
+                    olderThan: query.olderThan,
+                    limit: query.limit,
+                })) ?? []);
+            },
+            on: (event, listener) => {
+                const events = this.queue;
+                return events.on(event, listener);
+            },
+        });
+    }
+    createWorkerApi() {
+        const facade = this;
+        return Object.freeze({
+            get running() {
+                return facade.workerRunning;
+            },
+            start: async (options = {}) => {
+                if (options.concurrency !== undefined) {
+                    if (facade.redis) {
+                        facade.redis.setWorkerConcurrency(options.concurrency);
+                    }
+                    else {
+                        facade.memory.concurrency =
+                            options.concurrency;
+                    }
+                }
+                facade.queue.start();
+                facade.workerRunning = true;
+            },
+            pause: async () => {
+                facade.queue.pause();
+                facade.workerRunning = false;
+            },
+            resume: async () => {
+                facade.queue.start();
+                facade.workerRunning = true;
+            },
+            onIdle: async () => facade.queue.onIdle(),
+            close: async (options) => {
+                await facade.queue.close(options);
+                facade.memoryScheduler?.close();
+                facade.workerRunning = false;
+            },
+        });
+    }
+    connectTelemetry() {
+        const telemetry = this.options.telemetry;
+        if (!telemetry) {
+            return;
+        }
+        const events = [
+            "added",
+            "started",
+            "retry",
+            "succeeded",
+            "failed",
+            "cancelled",
+            "expired",
+        ];
+        const source = this.queue;
+        for (const event of events) {
+            source.on(event, (payload) => {
+                const snapshot = "job" in Object(payload)
+                    ? payload.job
+                    : payload;
+                telemetry.emit({
+                    type: `job.${event}`,
+                    queue: this.options.name ?? "default",
+                    timestamp: Date.now(),
+                    job: snapshot,
+                });
+            });
+        }
+    }
+    addLegacy(name, value, options) {
+        if (this.redis) {
+            return this.redis.add(name, value, options);
+        }
+        return this.memory.add(name, value, options);
+    }
+}
+export function enqiu(definitions, options = {}) {
+    return new EnqiuFacade(definitions, options).api;
+}
+function normalizeDefinition(definition) {
+    if (typeof definition === "function") {
+        return {
+            schema: undefined,
+            run: definition,
+            policy: {},
+        };
+    }
+    if (!definition ||
+        typeof definition !== "object" ||
+        definition[definitionMarker] !== true) {
+        throw new TypeError("Every job must be a handler or a definition created with job()");
+    }
+    const { input, run, retry, timeout, expiresIn, concurrency, throttle, debounce, } = definition;
+    return {
+        schema: input,
+        run: run,
+        policy: compact({
+            retry,
+            timeout,
+            expiresIn,
+            concurrency,
+            throttle,
+            debounce,
+        }),
+    };
+}
+async function validateInput(name, schema, input) {
+    if (!schema) {
+        return input;
+    }
+    const result = await schema["~standard"].validate(input);
+    if (result.issues) {
+        throw new JobValidationError(name, result.issues);
+    }
+    return result.value;
+}
+function isStandardSchema(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const standard = value["~standard"];
+    return (standard?.version === 1 &&
+        typeof standard.vendor === "string" &&
+        typeof standard.validate === "function");
+}
+function normalizeLegacyRetry(value) {
+    if (typeof value === "number" || value === undefined) {
+        return value;
+    }
+    if (!Number.isInteger(value.attempts) || value.attempts < 1) {
+        throw new RangeError("retry.attempts must be a positive integer");
+    }
+    return compact({
+        retries: value.attempts - 1,
+        backoff: value.backoff,
+        when: value.when,
+    });
+}
+function toLegacyOptions(options, policy, name, input) {
+    const priority = typeof options.priority === "string"
+        ? { low: -10, normal: 0, high: 10 }[options.priority]
+        : options.priority;
+    const concurrency = policy.concurrency === undefined
+        ? undefined
+        : typeof policy.concurrency === "number"
+            ? {
+                limit: policy.concurrency,
+                key: `${name}:*`,
+            }
+            : {
+                limit: policy.concurrency.limit,
+                key: `${name}:${resolvePolicyKey("concurrency.by", policy.concurrency.by?.(input) ?? "*")}`,
+            };
+    const throttle = policy.throttle
+        ? {
+            limit: policy.throttle.limit,
+            interval: policy.throttle.per,
+            burst: policy.throttle.burst ?? policy.throttle.limit,
+            key: `${name}:${resolvePolicyKey("throttle.by", policy.throttle.by?.(input) ?? "*")}`,
+        }
+        : undefined;
+    const debounce = policy.debounce
+        ? {
+            wait: policy.debounce.wait,
+            mode: policy.debounce.mode,
+            key: resolvePolicyKey("debounce.by", policy.debounce.by(input)),
+        }
+        : undefined;
+    return compact({
+        id: options.id,
+        key: options.idempotencyKey,
+        keyRetention: options.idempotencyKey
+            ? options.idempotencyTtl ?? 24 * 60 * 60 * 1000
+            : undefined,
+        delay: options.delay,
+        priority,
+        retry: normalizeLegacyRetry(options.retry ?? policy.retry),
+        timeout: options.timeout ?? policy.timeout,
+        expiresIn: options.expiresIn ?? policy.expiresIn,
+        concurrency,
+        throttle,
+        debounce,
+        signal: options.signal,
+    });
+}
+function resolvePolicyKey(name, value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new TypeError(`${name} must return a non-empty string`);
+    }
+    return value;
+}
+function createContext(legacy, queue, telemetry) {
+    const log = createLogger(legacy, queue, telemetry);
+    return {
+        id: legacy.id,
+        name: legacy.name,
+        attempt: legacy.attempt,
+        signal: legacy.signal,
+        reportProgress: async (progress) => {
+            validateProgress(progress);
+            const safeProgress = cloneJobValue(progress);
+            legacy.progress(safeProgress);
+            telemetry?.emit({
+                type: "job.progress",
+                queue,
+                timestamp: Date.now(),
+                fields: {
+                    jobId: legacy.id,
+                    jobName: legacy.name,
+                    progress: safeProgress,
+                },
+            });
+        },
+        log,
+    };
+}
+function createLogger(context, queue, telemetry) {
+    const write = (level, message, fields) => {
+        if (!message) {
+            throw new TypeError("Job log messages must not be empty");
+        }
+        const entry = cloneJobValue({
+            timestamp: Date.now(),
+            level,
+            message,
+            ...(fields === undefined ? {} : { fields }),
+        });
+        context.log(entry);
+        telemetry?.emit({
+            type: `job.log.${level}`,
+            queue,
+            timestamp: Date.now(),
+            fields: {
+                jobId: context.id,
+                jobName: context.name,
+                message: entry.message,
+                ...(entry.fields ?? {}),
+            },
+        });
+    };
+    return Object.freeze({
+        debug: (message, fields) => write("debug", message, fields),
+        info: (message, fields) => write("info", message, fields),
+        warn: (message, fields) => write("warn", message, fields),
+        error: (message, fields) => write("error", message, fields),
+    });
+}
+function validateProgress(progress) {
+    if (!Number.isFinite(progress.completed) ||
+        !Number.isFinite(progress.total) ||
+        progress.completed < 0 ||
+        progress.total <= 0 ||
+        progress.completed > progress.total) {
+        throw new RangeError("Progress requires 0 <= completed <= total and total > 0");
+    }
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+export { JobCancelledError, JobExpiredError, JobFailedError, JobSerializationError, JobTimeoutError, QueueClosedError, };

package/dist/codec.d.ts

@@ -0,0 +1,8 @@
+export declare class JobSerializationError extends TypeError {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+/** Serialize the exact data contract shared by the memory and Redis drivers. */
+export declare function encodeJobValue(value: unknown): string;
+export declare function decodeJobValue(value: string): unknown;
+export declare function cloneJobValue<T>(value: T): T;

package/dist/codec.js

@@ -0,0 +1,74 @@
+export class JobSerializationError extends TypeError {
+    path;
+    constructor(path, reason) {
+        super(`Job data at ${path} is not JSON-safe: ${reason}`);
+        this.name = "JobSerializationError";
+        this.path = path;
+    }
+}
+/** Serialize the exact data contract shared by the memory and Redis drivers. */
+export function encodeJobValue(value) {
+    assertJsonSafe(value, "$", new Set());
+    return JSON.stringify({ value });
+}
+export function decodeJobValue(value) {
+    const envelope = JSON.parse(value);
+    return Object.prototype.hasOwnProperty.call(envelope, "value")
+        ? envelope.value
+        : undefined;
+}
+export function cloneJobValue(value) {
+    return decodeJobValue(encodeJobValue(value));
+}
+function assertJsonSafe(value, path, ancestors) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return;
+    }
+    if (value === undefined) {
+        if (path !== "$") {
+            throw new JobSerializationError(path, "undefined is only valid as a root value");
+        }
+        return;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new JobSerializationError(path, "numbers must be finite");
+        }
+        return;
+    }
+    if (typeof value === "bigint" ||
+        typeof value === "function" ||
+        typeof value === "symbol") {
+        throw new JobSerializationError(path, `${typeof value} is unsupported`);
+    }
+    if (typeof value !== "object") {
+        throw new JobSerializationError(path, "unsupported value");
+    }
+    if (ancestors.has(value)) {
+        throw new JobSerializationError(path, "circular reference");
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            if (!(index in value)) {
+                throw new JobSerializationError(`${path}[${index}]`, "sparse array entries are unsupported");
+            }
+            assertJsonSafe(value[index], `${path}[${index}]`, ancestors);
+        }
+        ancestors.delete(value);
+        return;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new JobSerializationError(path, "only plain objects and arrays are supported");
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined) {
+            throw new JobSerializationError(`${path}.${key}`, "undefined object fields are unsupported");
+        }
+        assertJsonSafe(entry, `${path}.${key}`, ancestors);
+    }
+    ancestors.delete(value);
+}

package/dist/cron.d.ts

@@ -0,0 +1,19 @@
+interface CronField {
+    readonly wildcard: boolean;
+    readonly values: ReadonlySet<number>;
+}
+export interface ParsedCron {
+    readonly expression: string;
+    readonly minute: CronField;
+    readonly hour: CronField;
+    readonly dayOfMonth: CronField;
+    readonly month: CronField;
+    readonly dayOfWeek: CronField;
+}
+export declare class CronExpressionError extends TypeError {
+    constructor(message: string);
+}
+export declare function parseCron(expression: string): ParsedCron;
+export declare function validateTimeZone(timeZone: string): string;
+export declare function nextCronOccurrence(cron: string | ParsedCron, timeZone: string, after: number): number;
+export {};