snugkv-nest 0.2.0 → 0.4.0

package/README.md

@@ -95,6 +95,88 @@ Subscriptions are restored after a reconnect; messages sent while disconnected a
 - `SnugKvLocks`: `acquire(name, { ttlMs, waitMs })`, `run(name, fn)`. A lock expires on its own, and only its holder can release or extend it. It protects against crashed holders, not against the server itself failing, so keep critical sections idempotent.
 - `SnugKvRateLimiter`: `hit(key, limit, windowMs)` is a fixed window; it returns `{ allowed, count, remaining, resetMs }`.
 
+## Job queues
+
+BullMQ-style queues that run inside SnugKV (the `snugq` function library, loaded by the server by default). Needs a server version that includes it.
+
+```ts
+import { Queue, Worker, QueueEvents, FlowProducer } from 'snugkv-nest';
+
+const emails = new Queue('emails', { connection: { host: '127.0.0.1', port: 6379 } });
+await emails.add('welcome', { to: 'a@b.c' }, { attempts: 3, backoff: { type: 'exponential', delay: 1000 }, removeOnComplete: 100 });
+
+const worker = new Worker('emails', async (job) => {
+  await job.updateProgress(50);
+  return send(job.data);
+}, { connection: { host: '127.0.0.1', port: 6379 }, concurrency: 5 });
+worker.on('failed', (job, err) => console.error(job.id, err.message));
+```
+
+With Nest, register queues and mark processors; workers start and stop with the app:
+
+```ts
+SnugKvQueueModule.registerQueue({ name: 'emails' })
+
+@SnugProcessor('emails', { concurrency: 5 })
+export class EmailProcessor extends WorkerHost {
+  async process(job: Job<{ to: string }>) { /* … */ }
+
+  @OnSnugWorkerEvent('failed')
+  onFailed(job: Job, err: Error) { /* … */ }
+}
+
+constructor(@InjectSnugQueue('emails') private readonly emails: Queue) {}
+```
+
+Use `@SnugProcess('jobName')` on methods instead of `process()` to route by job name.
+
+Supported: priorities, LIFO, delayed jobs, attempts with fixed, exponential or custom backoff (`UnrecoverableError` skips retries), locks with stalled-job recovery, pause/resume, global concurrency, queue rate limits (`limiter`, `queue.setRateLimit`, `worker.rateLimit` + `RateLimitError`), custom ids and deduplication, `removeOnComplete`/`removeOnFail`, progress and logs, `QueueEvents` and `job.waitUntilFinished`, `drain`/`clean`/`obliterate`/`retryJobs`/`promoteJobs`, repeatable jobs (`upsertJobScheduler` with `every` or a cron `pattern` and `tz`), and parent/child flows (`FlowProducer`, `job.getChildrenValues()`, `failParentOnFailure`, `ignoreDependencyOnFailure`). Job data must be JSON-serialisable. Cron patterns are computed by workers, so keep one running. See the server's `docs/QUEUES.md` for the storage layout.
+
+## Flow tracing
+
+Turn on `tracing` and every activity becomes one trace you can follow across
+services: a webhook, the jobs it queues, the worker in another service that
+handles them, and every step you mark in between.
+
+```ts
+SnugKvModule.forRoot({ url: 'snugkv://localhost:6383', service: 'chain-ingest', tracing: true });
+
+@Injectable()
+export class WebhooksService {
+  // Injectable when `tracing` is on (null otherwise).
+  constructor(private readonly tracer: Tracer, @InjectSnugQueue('chain-events') private readonly q: Queue) {}
+
+  async onWebhook(body: AlchemyEvent) {
+    // A step with no trace around it starts a new trace.
+    return this.tracer.step('webhook.alchemy', { network: body.event.network }, async (span) => {
+      await this.tracer.step('dedup', {}, () => this.checkDuplicate(body));
+      await this.q.add('deposit.detected', { txHash, address }); // carries the trace
+      span.set({ transfers: body.event.activity.length });
+    });
+  }
+}
+```
+
+The worker that processes `deposit.detected` (in any service with tracing on)
+runs inside a span of the same trace. Inside it, `tracer.step()` nests further
+and `tracer.event('push.sent', { ticket })` records a step that already
+happened. A step that throws is recorded with its error and stack, and the
+error is rethrown unchanged.
+
+Spans are written in batches to the `snug:traces` stream (capped at about
+100,000 entries). Each entry has `traceId`, `spanId`, `parentId`, `service`,
+`name`, `status` (`ok` / `error`), `start`, `durationMs`, `attrs` (JSON) and,
+for failures, `error` and `stack`. Attribute keys that look like credentials
+(`token`, `secret`, `signature`, `privateKey`, `seed`, ...) are stored as
+`[redacted]`, and long strings are cut. Tracing never throws into your code:
+when the server is unreachable, spans are buffered and written later.
+
+The trace travels inside job data as a `__trace` field (plain-object data
+only) and is removed before your processor sees `job.data`.
+
+Options: `tracing: { stream, maxLen, batchSize, flushMs, maxBuffer, redact, maxAttrLength }`.
+Without Nest: `const tracer = new Tracer(client, { service: 'api' }); setTracer(tracer);`
+
 ## Messaging (streams)
 
 ## Quick start
@@ -267,4 +349,4 @@ Tests that need a server are skipped when `SNUGKV_BIN` is not set.
 
 ## License
 
-MIT
+MIT. This package is only a client. The SnugKV server it talks to is a separate project, licensed under AGPL-3.0 with a commercial licence option.

package/dist/core/index.d.ts

@@ -11,3 +11,5 @@ export * from './tx';
 export * from './cache';
 export * from './lock';
 export * from './ratelimit';
+export * from './queue';
+export * from './trace';

package/dist/core/index.js

@@ -31,4 +31,6 @@ __exportStar(require("./tx"), exports);
 __exportStar(require("./cache"), exports);
 __exportStar(require("./lock"), exports);
 __exportStar(require("./ratelimit"), exports);
+__exportStar(require("./queue"), exports);
+__exportStar(require("./trace"), exports);
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yCAAuB;AACvB,2CAA8E;AAArE,wGAAA,UAAU,OAAA;AAAE,6GAAA,eAAe,OAAA;AACpC,2CAAyB;AACzB,6CAA2B;AAC3B,8CAA4B;AAC5B,6CAA2B;AAC3B,wCAAsB;AACtB,+BAA6C;AAAzB,gGAAA,QAAQ,OAAA;AAC5B,2CAAyB;AACzB,uCAAqB;AACrB,0CAAwB;AACxB,yCAAuB;AACvB,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yCAAuB;AACvB,2CAA8E;AAArE,wGAAA,UAAU,OAAA;AAAE,6GAAA,eAAe,OAAA;AACpC,2CAAyB;AACzB,6CAA2B;AAC3B,8CAA4B;AAC5B,6CAA2B;AAC3B,wCAAsB;AACtB,+BAA6C;AAAzB,gGAAA,QAAQ,OAAA;AAC5B,2CAAyB;AACzB,uCAAqB;AACrB,0CAAwB;AACxB,yCAAuB;AACvB,8CAA4B;AAC5B,0CAAwB;AACxB,0CAAwB"}

package/dist/core/queue/cron.d.ts

@@ -0,0 +1,21 @@
+interface Field {
+    set: Set<number>;
+    star: boolean;
+}
+interface Parsed {
+    sec: Field;
+    min: Field;
+    hour: Field;
+    dom: Field;
+    month: Field;
+    dow: Field;
+    hasSeconds: boolean;
+}
+/** Parses 5 fields (minute hour day-of-month month day-of-week) or 6 with leading seconds. */
+export declare function parseCron(pattern: string): Parsed;
+/**
+ * The first time after `from` (ms since epoch) that matches the pattern, in the given IANA time zone
+ * (default UTC). Throws on a bad pattern or when nothing matches within 8 years.
+ */
+export declare function nextCronTime(pattern: string, from: number, tz?: string): number;
+export {};

package/dist/core/queue/cron.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCron = parseCron;
+exports.nextCronTime = nextCronTime;
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const DAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+function parseField(text, min, max, names, nameBase = 0) {
+    const set = new Set();
+    let star = false;
+    const value = (v) => {
+        const i = names ? names.indexOf(v.toLowerCase()) : -1;
+        const n = i >= 0 ? i + nameBase : Number(v);
+        if (!Number.isInteger(n))
+            throw new Error(`bad cron value "${v}"`);
+        return n;
+    };
+    for (const part of text.split(',')) {
+        const [range, stepText] = part.split('/');
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1)
+            throw new Error(`bad cron step in "${part}"`);
+        let lo;
+        let hi;
+        if (range === '*' || range === '?') {
+            lo = min;
+            hi = max;
+            if (stepText === undefined)
+                star = true;
+        }
+        else if (range.includes('-')) {
+            const [a, b] = range.split('-');
+            lo = value(a);
+            hi = value(b);
+        }
+        else {
+            lo = value(range);
+            hi = stepText === undefined ? lo : max;
+        }
+        if (lo < min || hi > max + (max === 6 ? 1 : 0) || lo > hi)
+            throw new Error(`cron value out of range in "${part}"`);
+        for (let v = lo; v <= hi; v += step)
+            set.add(v);
+    }
+    return { set, star };
+}
+/** Parses 5 fields (minute hour day-of-month month day-of-week) or 6 with leading seconds. */
+function parseCron(pattern) {
+    const parts = pattern.trim().split(/\s+/);
+    if (parts.length !== 5 && parts.length !== 6)
+        throw new Error(`cron pattern needs 5 or 6 fields: "${pattern}"`);
+    const hasSeconds = parts.length === 6;
+    const f = hasSeconds ? parts : ['0', ...parts];
+    const dow = parseField(f[5], 0, 6, DAYS);
+    if (dow.set.has(7)) {
+        dow.set.delete(7);
+        dow.set.add(0);
+    }
+    return {
+        sec: parseField(f[0], 0, 59),
+        min: parseField(f[1], 0, 59),
+        hour: parseField(f[2], 0, 23),
+        dom: parseField(f[3], 1, 31),
+        month: parseField(f[4], 1, 12, MONTHS, 1),
+        dow,
+        hasSeconds,
+    };
+}
+const formatters = new Map();
+function offsetMs(instant, tz) {
+    if (tz === 'UTC')
+        return 0;
+    let f = formatters.get(tz);
+    if (!f) {
+        f = new Intl.DateTimeFormat('en-US', {
+            timeZone: tz,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            second: 'numeric',
+        });
+        formatters.set(tz, f);
+    }
+    const p = {};
+    for (const part of f.formatToParts(new Date(instant)))
+        if (part.type !== 'literal')
+            p[part.type] = Number(part.value);
+    const asUtc = Date.UTC(p.year, p.month - 1, p.day, p.hour % 24, p.minute, p.second);
+    return asUtc - Math.floor(instant / 1000) * 1000;
+}
+/** Local wall-clock time of `instant` in `tz`, expressed as if it were UTC. */
+function toNaive(instant, tz) {
+    return instant + offsetMs(instant, tz);
+}
+function fromNaive(naive, tz) {
+    if (tz === 'UTC')
+        return naive;
+    const guess = naive - offsetMs(naive, tz);
+    return naive - offsetMs(guess, tz);
+}
+/**
+ * The first time after `from` (ms since epoch) that matches the pattern, in the given IANA time zone
+ * (default UTC). Throws on a bad pattern or when nothing matches within 8 years.
+ */
+function nextCronTime(pattern, from, tz = 'UTC') {
+    const c = parseCron(pattern);
+    const step = c.hasSeconds ? 1000 : 60_000;
+    let t = Math.floor(toNaive(from, tz) / step) * step + step;
+    const limit = t + 8 * 366 * 86_400_000;
+    while (t < limit) {
+        const d = new Date(t);
+        if (!c.month.set.has(d.getUTCMonth() + 1)) {
+            t = Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1);
+            continue;
+        }
+        const domOk = c.dom.set.has(d.getUTCDate());
+        const dowOk = c.dow.set.has(d.getUTCDay());
+        const dayOk = !c.dom.star && !c.dow.star ? domOk || dowOk : domOk && dowOk;
+        if (!dayOk) {
+            t = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+            continue;
+        }
+        if (!c.hour.set.has(d.getUTCHours())) {
+            t = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours() + 1);
+            continue;
+        }
+        if (!c.min.set.has(d.getUTCMinutes())) {
+            t = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours(), d.getUTCMinutes() + 1);
+            continue;
+        }
+        if (!c.sec.set.has(d.getUTCSeconds())) {
+            t += 1000;
+            continue;
+        }
+        const result = fromNaive(t, tz);
+        if (result > from)
+            return result;
+        t += step;
+    }
+    throw new Error(`cron pattern "${pattern}" never matches`);
+}
+//# sourceMappingURL=cron.js.map

package/dist/core/queue/cron.js.map

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

package/dist/core/queue/events.d.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from 'node:events';
+import { SnugKvClient, SnugKvClientOptions } from '../client';
+export interface QueueEventsOptions {
+    client?: SnugKvClient;
+    connection?: SnugKvClientOptions;
+    prefix?: string;
+    /** Where to start reading: `$` (default) only new events, or a stream id. */
+    lastEventId?: string;
+    /** How long one blocking read waits, ms. Default 10000. */
+    blockingTimeout?: number;
+    autorun?: boolean;
+}
+/**
+ * Listens to a queue's event stream: `added`, `waiting`, `delayed`, `active`, `progress`, `completed`,
+ * `failed`, `retries`, `stalled`, `removed`, `paused`, `resumed`, `duplicated`, `deduplicated`,
+ * `waiting-children`. Listeners get `(args, eventId)`; `args.jobId` names the job. Uses its own connection.
+ */
+export declare class QueueEvents extends EventEmitter {
+    readonly name: string;
+    private readonly options;
+    readonly key: string;
+    private readonly read;
+    private closing;
+    private readyPromise?;
+    constructor(name: string, options?: QueueEventsOptions);
+    /** Resolves when events are being read. */
+    waitUntilReady(): Promise<void>;
+    run(): Promise<void>;
+    private start;
+    private pump;
+    close(): Promise<void>;
+}

package/dist/core/queue/events.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueueEvents = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const node_events_1 = require("node:events");
+const client_1 = require("../client");
+const types_1 = require("./types");
+/**
+ * Listens to a queue's event stream: `added`, `waiting`, `delayed`, `active`, `progress`, `completed`,
+ * `failed`, `retries`, `stalled`, `removed`, `paused`, `resumed`, `duplicated`, `deduplicated`,
+ * `waiting-children`. Listeners get `(args, eventId)`; `args.jobId` names the job. Uses its own connection.
+ */
+class QueueEvents extends node_events_1.EventEmitter {
+    name;
+    options;
+    key;
+    read;
+    closing = false;
+    readyPromise;
+    constructor(name, options = {}) {
+        super();
+        this.name = name;
+        this.options = options;
+        this.key = `${options.prefix ?? 'snugq'}:{${name}}:events`;
+        this.read = options.client ? options.client.duplicate({ name: `queue-events:${name}` }) : new client_1.SnugKvClient({ ...options.connection, name: `queue-events:${name}` });
+        this.read.on('error', (e) => {
+            if (this.listenerCount('error') > 0)
+                this.emit('error', e);
+        });
+        if (options.autorun !== false)
+            void this.run().catch(() => undefined);
+    }
+    /** Resolves when events are being read. */
+    waitUntilReady() {
+        return this.run();
+    }
+    run() {
+        this.readyPromise ??= this.start();
+        return this.readyPromise;
+    }
+    async start() {
+        await this.read.connect(10_000);
+        let last = this.options.lastEventId ?? '$';
+        if (last === '$') {
+            const tail = (0, client_1.toEntries)(await this.read.call('XREVRANGE', this.key, '+', '-', 'COUNT', 1));
+            last = tail[0]?.id ?? '0-0';
+        }
+        void this.pump(last);
+    }
+    async pump(from) {
+        let last = from;
+        const block = this.options.blockingTimeout ?? 10_000;
+        while (!this.closing) {
+            try {
+                const raw = await this.read.call('XREAD', 'COUNT', 100, 'BLOCK', block, 'STREAMS', this.key, last);
+                if (!Array.isArray(raw))
+                    continue;
+                for (const stream of raw) {
+                    if (!Array.isArray(stream))
+                        continue;
+                    for (const e of (0, client_1.toEntries)(stream[1] ?? null)) {
+                        last = e.id;
+                        const { event, ...rest } = e.fields;
+                        if (!event)
+                            continue;
+                        this.emit(event, convert(event, rest), e.id);
+                    }
+                }
+            }
+            catch (err) {
+                if (this.closing)
+                    return;
+                if (this.listenerCount('error') > 0)
+                    this.emit('error', err);
+                await new Promise((r) => setTimeout(r, 500));
+            }
+        }
+    }
+    async close() {
+        this.closing = true;
+        this.read.close();
+        this.removeAllListeners();
+    }
+}
+exports.QueueEvents = QueueEvents;
+function convert(event, f) {
+    const out = { ...f };
+    if (event === 'completed')
+        out.returnvalue = (0, types_1.parseJson)(f.returnvalue);
+    if (event === 'progress')
+        out.data = (0, types_1.parseJson)(f.data);
+    if (f.delay !== undefined)
+        out.delay = Number(f.delay);
+    if (f.attemptsMade !== undefined)
+        out.attemptsMade = Number(f.attemptsMade);
+    return out;
+}
+//# sourceMappingURL=events.js.map

package/dist/core/queue/events.js.map

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

package/dist/core/queue/flow.d.ts

@@ -0,0 +1,35 @@
+import { SnugKvClient, SnugKvClientOptions } from '../client';
+import type { Job } from './job';
+import { JobsOptions } from './types';
+export interface FlowJob<D = any> {
+    name: string;
+    queueName: string;
+    data?: D;
+    opts?: JobsOptions;
+    /** Jobs that must finish before this one runs. */
+    children?: FlowJob[];
+}
+export interface JobNode {
+    job: Job;
+    children?: JobNode[];
+}
+export interface FlowProducerOptions {
+    client?: SnugKvClient;
+    connection?: SnugKvClientOptions;
+    prefix?: string;
+}
+/**
+ * Adds a tree of jobs in one atomic step. A parent waits (state `waiting-children`) until all its
+ * children have finished, then runs; `job.getChildrenValues()` returns what the children returned.
+ */
+export declare class FlowProducer {
+    private readonly client;
+    private readonly owns;
+    private readonly prefix;
+    private readonly queues;
+    constructor(options?: FlowProducerOptions);
+    private queue;
+    add(flow: FlowJob): Promise<JobNode>;
+    addBulk(flows: FlowJob[]): Promise<JobNode[]>;
+    close(): Promise<void>;
+}

package/dist/core/queue/flow.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowProducer = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const trace_1 = require("../trace");
+const client_1 = require("../client");
+const resp_1 = require("../resp");
+const util_1 = require("../util");
+const queue_1 = require("./queue");
+const types_1 = require("./types");
+/**
+ * Adds a tree of jobs in one atomic step. A parent waits (state `waiting-children`) until all its
+ * children have finished, then runs; `job.getChildrenValues()` returns what the children returned.
+ */
+class FlowProducer {
+    client;
+    owns;
+    prefix;
+    queues = new Map();
+    constructor(options = {}) {
+        this.owns = !options.client;
+        this.client = options.client ?? new client_1.SnugKvClient(options.connection ?? {});
+        this.prefix = options.prefix ?? 'snugq';
+    }
+    queue(name) {
+        let q = this.queues.get(name);
+        if (!q) {
+            q = new queue_1.Queue(name, { client: this.client, prefix: this.prefix });
+            this.queues.set(name, q);
+        }
+        return q;
+    }
+    async add(flow) {
+        return (await this.addBulk([flow]))[0];
+    }
+    async addBulk(flows) {
+        if (!this.client.isReady)
+            await this.client.connect(10_000);
+        const commands = [];
+        const nodes = [];
+        const walk = (f, parent) => {
+            const q = this.queue(f.queueName);
+            const id = f.opts?.jobId ?? (0, util_1.uuid)();
+            const opts = { ...f.opts, jobId: id, parent: undefined };
+            commands.push(['FCALL', 'snugq_add', 1, q.base, ...(0, types_1.jobArgs)(f.name, (0, trace_1.withTrace)(f.data ?? null), opts, { parentBase: parent?.base, parentId: parent?.id, waitChildren: (f.children?.length ?? 0) > 0 })]);
+            const node = { job: (0, queue_1.localJob)(q, id, f.name, f.data ?? null, opts, parent) };
+            if (f.children?.length)
+                node.children = f.children.map((c) => walk(c, { base: q.base, id }));
+            return node;
+        };
+        for (const f of flows)
+            nodes.push(walk(f));
+        const replies = await this.client.execBlock(commands);
+        const bad = replies.find((r) => r instanceof resp_1.RespError);
+        if (bad)
+            throw bad;
+        return nodes;
+    }
+    async close() {
+        if (this.owns)
+            this.client.close();
+    }
+}
+exports.FlowProducer = FlowProducer;
+//# sourceMappingURL=flow.js.map

package/dist/core/queue/flow.js.map

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

package/dist/core/queue/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './job';
+export * from './queue';
+export * from './worker';
+export * from './events';
+export * from './flow';
+export { nextCronTime, parseCron } from './cron';

package/dist/core/queue/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCron = exports.nextCronTime = void 0;
+__exportStar(require("./types"), exports);
+__exportStar(require("./job"), exports);
+__exportStar(require("./queue"), exports);
+__exportStar(require("./worker"), exports);
+__exportStar(require("./events"), exports);
+__exportStar(require("./flow"), exports);
+var cron_1 = require("./cron");
+Object.defineProperty(exports, "nextCronTime", { enumerable: true, get: function () { return cron_1.nextCronTime; } });
+Object.defineProperty(exports, "parseCron", { enumerable: true, get: function () { return cron_1.parseCron; } });
+//# sourceMappingURL=index.js.map

package/dist/core/queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/queue/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,wCAAsB;AACtB,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,yCAAuB;AACvB,+BAAiD;AAAxC,oGAAA,YAAY,OAAA;AAAE,iGAAA,SAAS,OAAA"}

package/dist/core/queue/job.d.ts

@@ -0,0 +1,71 @@
+import type { QueueEvents } from './events';
+import { TraceContext } from '../trace';
+import { JobsOptions, JobState, QueueLike } from './types';
+/** A job as stored on the server. Fetched jobs are snapshots; call `getState()` or `Queue.getJob()` for fresh data. */
+export declare class Job<D = any, R = any> {
+    readonly queue: QueueLike;
+    readonly id: string;
+    readonly name: string;
+    data: D;
+    readonly opts: JobsOptions;
+    readonly timestamp: number;
+    readonly delay: number;
+    readonly priority: number;
+    progress: any;
+    returnvalue: R | undefined;
+    failedReason: string | undefined;
+    stacktrace: string[];
+    attemptsMade: number;
+    stalledCounter: number;
+    processedOn: number | undefined;
+    finishedOn: number | undefined;
+    /** Lock token while a worker holds the job. */
+    token: string | undefined;
+    /** Scheduler that created this job. */
+    readonly schedulerId: string | undefined;
+    readonly parent: {
+        id: string;
+        queue: string;
+    } | undefined;
+    /** Children that have not finished. */
+    readonly pendingChildren: number;
+    /** Set by a worker. */
+    readonly raw: Record<string, string>;
+    /** Trace the job was added in, when tracing is on. */
+    readonly trace: TraceContext | undefined;
+    constructor(queue: QueueLike, id: string, raw: Record<string, string>);
+    static fromFlat(queue: QueueLike, id: string, flat: any[]): Job;
+    /** Where this job is now. */
+    getState(): Promise<JobState>;
+    updateProgress(progress: number | string | boolean | object): Promise<void>;
+    /** Adds a line to the job log. Returns the log length. */
+    log(line: string): Promise<number>;
+    updateData(data: D): Promise<void>;
+    /** Removes the job and its unfinished children. Returns false if a worker holds it. */
+    remove(): Promise<boolean>;
+    /** Puts a failed (or completed) job back in the queue. */
+    retry(state?: 'failed' | 'completed', opts?: {
+        resetAttemptsMade?: boolean;
+    }): Promise<void>;
+    /** Runs a delayed job now. */
+    promote(): Promise<void>;
+    changeDelay(delayMs: number): Promise<void>;
+    changePriority(opts: {
+        priority: number;
+        lifo?: boolean;
+    }): Promise<void>;
+    /**
+     * From a processor: delay this job until `timestamp` (ms since epoch), then throw `new DelayedError()`.
+     * It does not use up an attempt.
+     */
+    moveToDelayed(timestamp: number, token?: string): Promise<void>;
+    /** Log lines. */
+    getLogs(start?: number, end?: number): Promise<string[]>;
+    /** Results of finished children, keyed by `queue:jobId`. */
+    getChildrenValues(): Promise<Record<string, any>>;
+    /** Reasons of children that failed, keyed by `queue:jobId`. */
+    getFailedChildrenValues(): Promise<Record<string, string>>;
+    /** Resolves with the return value when the job completes; rejects when it fails. Needs a started {@link QueueEvents}. */
+    waitUntilFinished(events: QueueEvents, ttlMs?: number): Promise<R>;
+    toJSON(): Record<string, unknown>;
+}