bunqueue 2.8.54 → 2.8.57

package/dist/application/operations/pushDeduplication.js

@@ -0,0 +1,131 @@
+import { commitCustomIdAdmission } from './customId';
+import { admissionMetadata } from './pushAdmission';
+import { insertPreparedJobToShard, prepareJobInsertion } from './pushInsert';
+function findPendingOwner(shard, queue, ownerId) {
+    const queued = shard.getQueue(queue).find(ownerId);
+    if (queued)
+        return { job: queued, location: 'queue' };
+    const waitingDeps = shard.waitingDeps.get(ownerId);
+    if (waitingDeps)
+        return { job: waitingDeps, location: 'waiting-deps' };
+    const waitingChildren = shard.waitingChildren.get(ownerId);
+    if (waitingChildren)
+        return { job: waitingChildren, location: 'waiting-children' };
+    return undefined;
+}
+/** Inspect dedup state while deferring destructive replacement mutations. */
+export function handleDeduplication(job, input, queue, shard, ctx) {
+    if (!job.uniqueKey)
+        return { skip: false };
+    const existingEntry = shard.getUniqueKeyEntry(queue, job.uniqueKey);
+    if (!existingEntry)
+        return { skip: false };
+    if (input.dedup?.replace) {
+        if (ctx.dependencyResults.hasConsumers(existingEntry.jobId) ||
+            job.dependsOn.includes(existingEntry.jobId)) {
+            rollbackIncomingCustomId(job, ctx);
+            throw new Error(`Cannot replace deduplicated job ${String(existingEntry.jobId)} because live jobs depend on it`);
+        }
+        const replacement = findPendingOwner(shard, queue, existingEntry.jobId);
+        if (replacement)
+            return { skip: false, replacement };
+        if (ctx.jobIndex.get(existingEntry.jobId)?.type === 'processing') {
+            return { skip: false, activeOwnerId: existingEntry.jobId };
+        }
+        return { skip: false };
+    }
+    const queued = shard.getQueue(queue).find(existingEntry.jobId);
+    if (input.dedup?.extend && input.dedup.ttl) {
+        shard.extendUniqueKeyTtl(queue, job.uniqueKey, input.dedup.ttl);
+        if (queued) {
+            ctx.dashboardEmit?.('job:deduplicated', {
+                queue,
+                jobId: String(existingEntry.jobId),
+                strategy: 'extend',
+            });
+            return { skip: true, existingId: existingEntry.jobId };
+        }
+        throw new Error('Duplicate unique_key (extended TTL)');
+    }
+    if (queued || ctx.jobIndex.has(existingEntry.jobId)) {
+        ctx.broadcast({
+            eventType: "duplicated" /* EventType.Duplicated */,
+            queue,
+            jobId: existingEntry.jobId,
+            timestamp: Date.now(),
+        });
+        ctx.dashboardEmit?.('job:deduplicated', {
+            queue,
+            jobId: String(existingEntry.jobId),
+            strategy: 'default',
+        });
+        return { skip: true, existingId: existingEntry.jobId };
+    }
+    return { skip: false };
+}
+/** Commit the RAM half of a replacement after persistence has succeeded. */
+export function commitDedupReplacement(replacement, newJob, queue, shard, ctx) {
+    const oldJob = replacement.job;
+    let releasedDependencies = [];
+    if (replacement.location === 'queue') {
+        shard.getQueue(queue).remove(oldJob.id);
+        shard.decrementQueued(oldJob.id);
+        shard.removeFromTemporalIndex(oldJob.id);
+    }
+    else if (replacement.location === 'waiting-deps') {
+        shard.waitingDeps.delete(oldJob.id);
+        shard.unregisterDependencies(oldJob.id, oldJob.dependsOn);
+        releasedDependencies = oldJob.dependsOn;
+    }
+    else {
+        shard.waitingChildren.delete(oldJob.id);
+    }
+    ctx.jobIndex.delete(oldJob.id);
+    ctx.dependencyResults.releaseConsumer(oldJob.id);
+    if (oldJob.customId && ctx.customIdMap.get(oldJob.customId) === oldJob.id) {
+        ctx.customIdMap.delete(oldJob.customId);
+    }
+    if (oldJob.uniqueKey) {
+        shard.releaseUniqueKeyIfOwned(queue, oldJob.uniqueKey, oldJob.id);
+    }
+    if (newJob.uniqueKey) {
+        shard.registerUniqueKeyWithTtl(queue, newJob.uniqueKey, newJob.id, newJob.deduplicationTtl ?? undefined);
+    }
+    return releasedDependencies;
+}
+/** Defensive cleanup for callers that may have pre-published custom-ID ownership. */
+export function rollbackIncomingCustomId(job, ctx) {
+    if (job.customId && ctx.customIdMap.get(job.customId) === job.id) {
+        ctx.customIdMap.delete(job.customId);
+    }
+}
+/** Persist, detach, and insert a replacement without exposing a half-transition. */
+export function replacePendingDedupJob(replacement, newJob, input, target, options) {
+    const { ctx, customId, persist } = options;
+    const prepared = prepareJobInsertion(newJob, ctx);
+    const admission = admissionMetadata(customId, prepared);
+    if (persist)
+        persist(admission);
+    else
+        ctx.storage?.replaceJob(replacement.job.id, newJob, input.durable, admission);
+    commitCustomIdAdmission(input, customId, ctx);
+    const released = commitDedupReplacement(replacement, newJob, target.queue, target.shard, ctx);
+    insertPreparedJobToShard(newJob, target, ctx, prepared);
+    return released;
+}
+/** Persist and publish a successor while leaving its active predecessor live. */
+export function replaceActiveDedupJob(activeOwnerId, newJob, input, target, options) {
+    const { ctx, customId, persist } = options;
+    const prepared = prepareJobInsertion(newJob, ctx);
+    const admission = admissionMetadata(customId, prepared);
+    if (persist)
+        persist(admission);
+    else
+        ctx.storage?.transferActiveDedupJob(activeOwnerId, newJob, input.durable, admission);
+    commitCustomIdAdmission(input, customId, ctx);
+    if (newJob.uniqueKey) {
+        target.shard.releaseUniqueKeyIfOwned(target.queue, newJob.uniqueKey, activeOwnerId);
+        target.shard.registerUniqueKeyWithTtl(target.queue, newJob.uniqueKey, newJob.id, newJob.deduplicationTtl ?? undefined);
+    }
+    insertPreparedJobToShard(newJob, target, ctx, prepared);
+}

package/dist/application/operations/pushInsert.d.ts

@@ -4,7 +4,7 @@ import type { JobLocation } from '../../domain/types/queue';
 import type { SetLike } from '../../shared/lru';
 import type { MapLike } from '../../shared/lru';
 import type { DependencyResultTracker } from '../dependencyResultTracker';
-import { type DependencyCompletionTracker } from '../dependencyCompletions';
+import type { DependencyCompletionTracker } from '../dependencyCompletions';
 import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 export interface PushInsertContext {
     storage: SqliteStorage | null;
@@ -15,8 +15,20 @@ export interface PushInsertContext {
     jobIndex: Map<JobId, JobLocation>;
     dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
 }
+export interface PreparedJobInsertion {
+    state: 'waiting-children' | 'delayed' | 'prioritized' | 'waiting';
+    completionPins: JobId[];
+}
 /** Resolve the first externally visible state without mutating queue structures. */
 export declare function initialJobState(job: Job, ctx: Pick<PushInsertContext, 'completedJobs' | 'depCompletions'>, now?: number): 'waiting-children' | 'delayed' | 'prioritized' | 'waiting';
+/** Complete persistence-sensitive preparation before changing queue membership. */
+export declare function prepareJobInsertion(job: Job, ctx: PushInsertContext, recordTimeline?: boolean, now?: number): PreparedJobInsertion;
+/** Apply only non-throwing in-memory membership changes for a prepared job. */
+export declare function insertPreparedJobToShard(job: Job, target: {
+    queue: string;
+    shard: Shard;
+    shardIdx: number;
+}, ctx: PushInsertContext, prepared: PreparedJobInsertion): void;
 /** Insert a new job into the runnable heap or dependency wait set. */
 export declare function insertJobToShard(job: Job, target: {
     queue: string;

package/dist/application/operations/pushInsert.js

@@ -1,4 +1,3 @@
-import { pinReferencedCompletions, } from '../dependencyCompletions';
 /** Resolve the first externally visible state without mutating queue structures. */
 export function initialJobState(job, ctx, now = Date.now()) {
     const needsWaiting = job.dependsOn.length > 0 &&
@@ -9,29 +8,29 @@ export function initialJobState(job, ctx, now = Date.now()) {
         return 'delayed';
     return job.priority > 0 ? 'prioritized' : 'waiting';
 }
-/** Insert a new job into the runnable heap or dependency wait set. */
-export function insertJobToShard(job, target, ctx, recordTimeline = true) {
-    const { queue, shard, shardIdx } = target;
-    const now = Date.now();
+/** Complete persistence-sensitive preparation before changing queue membership. */
+export function prepareJobInsertion(job, ctx, recordTimeline = true, now = Date.now()) {
     const state = initialJobState(job, ctx, now);
+    const completionPins = state === 'waiting-children'
+        ? [...new Set(job.dependsOn)].filter((id) => ctx.depCompletions?.has(id) ?? false)
+        : [];
+    if (recordTimeline)
+        job.timeline.push({ state, timestamp: now });
+    return { state, completionPins };
+}
+/** Apply only non-throwing in-memory membership changes for a prepared job. */
+export function insertPreparedJobToShard(job, target, ctx, prepared) {
+    const { queue, shard, shardIdx } = target;
+    const { state } = prepared;
+    for (const id of prepared.completionPins)
+        ctx.depCompletions?.pin(id);
     if (state === 'waiting-children') {
-        pinReferencedCompletions(job.dependsOn, ctx);
         shard.waitingDeps.set(job.id, job);
         shard.registerDependencies(job.id, job.dependsOn);
-        if (recordTimeline)
-            job.timeline.push({ state, timestamp: now });
-        ctx.dashboardEmit?.('job:waiting-children', {
-            jobId: String(job.id),
-            queue,
-            dependsOn: job.dependsOn.map(String),
-        });
     }
     else {
         shard.getQueue(queue).push(job);
-        const isDelayed = job.runAt > now;
-        shard.incrementQueued(job.id, isDelayed, job.createdAt, queue, job.runAt);
-        if (recordTimeline)
-            job.timeline.push({ state, timestamp: now });
+        shard.incrementQueued(job.id, state === 'delayed', job.createdAt, queue, job.runAt);
     }
     ctx.jobIndex.set(job.id, { type: 'queue', shardIdx, queueName: queue });
     ctx.dependencyResults.registerConsumer(job.id, job.dependsOn);
@@ -40,4 +39,21 @@ export function insertJobToShard(job, target, ctx, recordTimeline = true) {
             ctx.dependencyResults.retain(dependencyId, ctx.jobResults.get(dependencyId));
         }
     }
+    if (state === 'waiting-children') {
+        try {
+            ctx.dashboardEmit?.('job:waiting-children', {
+                jobId: String(job.id),
+                queue,
+                dependsOn: job.dependsOn.map(String),
+            });
+        }
+        catch (error) {
+            console.error('[Push] Dashboard event failed after job admission', { error });
+        }
+    }
+}
+/** Insert a new job into the runnable heap or dependency wait set. */
+export function insertJobToShard(job, target, ctx, recordTimeline = true) {
+    const prepared = prepareJobInsertion(job, ctx, recordTimeline);
+    insertPreparedJobToShard(job, target, ctx, prepared);
 }

package/dist/application/operations/pushLocks.js

@@ -1,17 +1,21 @@
 import { jobId } from '../../domain/types/job';
 import { shardIndex } from '../../shared/hash';
+import { isParentLinkInput } from './parentLinkInput';
 function requiredShardIndexes(queue, inputs, jobIndex) {
     const indexes = new Set([shardIndex(queue)]);
     for (const input of inputs) {
-        if (!input.customId)
-            continue;
-        const location = jobIndex.get(jobId(input.customId));
-        if (location?.type === 'queue') {
-            indexes.add(location.shardIdx);
-        }
-        else if (location?.type === 'dlq') {
-            indexes.add(shardIndex(location.queueName));
+        if (input.customId) {
+            const location = jobIndex.get(jobId(input.customId));
+            if (location?.type === 'queue') {
+                indexes.add(location.shardIdx);
+            }
+            else if (location?.type === 'dlq') {
+                indexes.add(shardIndex(location.queueName));
+            }
         }
+        const parentLocation = input.parentId && isParentLinkInput(input) ? jobIndex.get(input.parentId) : undefined;
+        if (parentLocation?.type === 'queue')
+            indexes.add(parentLocation.shardIdx);
     }
     return [...indexes].sort((a, b) => a - b);
 }
@@ -22,7 +26,7 @@ function requiredShardIndexes(queue, inputs, jobIndex) {
  */
 export async function withPushWriteLocks(queue, inputs, ctx, fn) {
     while (true) {
-        const customIdGuard = inputs.some((input) => input.customId)
+        const customIdGuard = inputs.some((input) => input.customId || isParentLinkInput(input))
             ? await ctx.customIdLock.acquireWrite()
             : null;
         const guards = [];

package/dist/application/operations/query/collect.d.ts

@@ -0,0 +1,12 @@
+import type { Shard } from '../../../domain/queue/shard';
+import type { Job } from '../../../domain/types/job';
+import type { GetJobsContext } from '../../types/query';
+export declare function compareJobsByCreatedAt(a: Job, b: Job, asc: boolean): number;
+export declare function collectTemporalJobs(shard: Shard, queue: string, needs: {
+    waiting: boolean;
+    prioritized: boolean;
+    delayed: boolean;
+}, now?: number): Job[];
+export declare function tagState(jobs: Job[], state: string): Job[];
+export declare function collectWaitingChildrenJobs(shard: Shard, queue: string): Job[];
+export declare function collectJobsByState(queue: string, shardIndex: number, states: string[] | null, ctx: GetJobsContext, now?: number): Job[];

package/dist/application/operations/query/collect.js

@@ -0,0 +1,118 @@
+export function compareJobsByCreatedAt(a, b, asc) {
+    if (a.createdAt !== b.createdAt) {
+        return asc ? a.createdAt - b.createdAt : b.createdAt - a.createdAt;
+    }
+    if (a.id === b.id)
+        return 0;
+    if (asc)
+        return a.id < b.id ? -1 : 1;
+    return a.id > b.id ? -1 : 1;
+}
+function collectCompletedJobs(queue, ctx) {
+    const jobs = [];
+    for (const [jobId, location] of ctx.jobIndex) {
+        if (location.type === 'completed' && location.queueName === queue) {
+            const job = ctx.storage?.getJob(jobId) ?? ctx.completedJobsData?.get(jobId) ?? null;
+            if (job)
+                jobs.push(job);
+        }
+    }
+    return jobs;
+}
+function collectActiveJobs(queue, shardIndex, ctx) {
+    const jobs = [];
+    for (const job of ctx.processingShards[shardIndex].values()) {
+        if (job.queue === queue)
+            jobs.push(job);
+    }
+    for (let index = 0; index < ctx.shardCount; index++) {
+        if (index === shardIndex)
+            continue;
+        for (const job of ctx.processingShards[index].values()) {
+            if (job.queue === queue)
+                jobs.push(job);
+        }
+    }
+    return jobs;
+}
+export function collectTemporalJobs(shard, queue, needs, now = Date.now()) {
+    const { waiting: needWaiting, prioritized: needPrioritized, delayed: needDelayed } = needs;
+    const jobs = [];
+    for (const job of shard.getQueue(queue).values()) {
+        const isDelayed = job.runAt > now;
+        if (isDelayed && needDelayed) {
+            jobs.push(job);
+        }
+        else if (!isDelayed && (job.priority > 0 ? needPrioritized : needWaiting)) {
+            jobs.push(job);
+        }
+    }
+    return jobs;
+}
+export function tagState(jobs, state) {
+    for (const job of jobs)
+        job._state = state;
+    return jobs;
+}
+function tagTemporalState(jobs, now = Date.now()) {
+    for (const job of jobs) {
+        const isDelayed = job.runAt > now;
+        job._state = isDelayed
+            ? 'delayed'
+            : job.priority > 0
+                ? 'prioritized'
+                : 'waiting';
+    }
+}
+export function collectWaitingChildrenJobs(shard, queue) {
+    const jobs = [];
+    for (const job of shard.waitingDeps.values()) {
+        if (job.queue === queue)
+            jobs.push(job);
+    }
+    for (const job of shard.waitingChildren.values()) {
+        if (job.queue === queue)
+            jobs.push(job);
+    }
+    return jobs;
+}
+function resolveStateNeeds(states, paused) {
+    const want = (state) => !states || states.includes(state);
+    const suppressReady = !!states && paused;
+    return {
+        waiting: want('waiting') && !suppressReady,
+        prioritized: want('prioritized') && !suppressReady,
+        delayed: want('delayed'),
+        paused: !!states && states.includes('paused') && paused,
+        active: want('active'),
+        failed: want('failed'),
+        completed: want('completed'),
+        waitingChildren: want('waiting-children'),
+    };
+}
+function collectPausedJobs(shard, queue, now) {
+    const jobs = collectTemporalJobs(shard, queue, { waiting: true, prioritized: true, delayed: false }, now);
+    return tagState(jobs, 'paused');
+}
+export function collectJobsByState(queue, shardIndex, states, ctx, now = Date.now()) {
+    const shard = ctx.shards[shardIndex];
+    const jobs = [];
+    const needs = resolveStateNeeds(states, shard.getState(queue).paused);
+    if (needs.waiting || needs.prioritized || needs.delayed) {
+        const temporal = collectTemporalJobs(shard, queue, { waiting: needs.waiting, prioritized: needs.prioritized, delayed: needs.delayed }, now);
+        tagTemporalState(temporal, now);
+        jobs.push(...temporal);
+    }
+    if (needs.paused)
+        jobs.push(...collectPausedJobs(shard, queue, now));
+    if (needs.active)
+        jobs.push(...tagState(collectActiveJobs(queue, shardIndex, ctx), 'active'));
+    if (needs.failed)
+        jobs.push(...tagState(shard.getDlq(queue), 'failed'));
+    if (needs.completed)
+        jobs.push(...tagState(collectCompletedJobs(queue, ctx), 'completed'));
+    if (needs.waitingChildren) {
+        jobs.push(...tagState(collectWaitingChildrenJobs(shard, queue), 'waiting-children'));
+    }
+    return jobs;
+}

package/dist/application/operations/query/jobLookup.d.ts

@@ -0,0 +1,9 @@
+import type { Job, JobId } from '../../../domain/types/job';
+import type { QueryContext } from '../../types/query';
+export declare function getJob(jobId: JobId, ctx: QueryContext): Promise<Job | null>;
+export declare function getJobResult(jobId: JobId, ctx: QueryContext): unknown;
+export declare function getJobByCustomId(customId: string, ctx: QueryContext): Job | null;
+export declare function getJobProgress(jobId: JobId, ctx: QueryContext): {
+    progress: number;
+    message: string | null;
+} | null;

package/dist/application/operations/query/jobLookup.js

@@ -0,0 +1,110 @@
+import { shardIndex } from '../../../shared/hash';
+import { withReadLock } from '../../../shared/lock';
+export async function getJob(jobId, ctx) {
+    for (let pass = 0; pass < 4; pass++) {
+        const location = ctx.jobIndex.get(jobId);
+        if (!location) {
+            if (ctx.storage) {
+                const job = ctx.storage.getJob(jobId);
+                if (job)
+                    return job;
+                const dlqEntry = ctx.storage.getDlqEntry(jobId);
+                if (dlqEntry)
+                    return dlqEntry.job;
+            }
+            return ctx.completedJobsData.get(jobId) ?? null;
+        }
+        let found = null;
+        switch (location.type) {
+            case 'queue': {
+                found = await withReadLock(ctx.shardLocks[location.shardIdx], () => {
+                    const shard = ctx.shards[location.shardIdx];
+                    return (shard.getQueue(location.queueName).find(jobId) ??
+                        shard.waitingDeps.get(jobId) ??
+                        shard.waitingChildren.get(jobId) ??
+                        null);
+                });
+                break;
+            }
+            case 'processing': {
+                found = await withReadLock(ctx.processingLocks[location.shardIdx], () => {
+                    return ctx.processingShards[location.shardIdx].get(jobId) ?? null;
+                });
+                break;
+            }
+            case 'completed':
+                found = ctx.storage?.getJob(jobId) ?? ctx.completedJobsData.get(jobId) ?? null;
+                break;
+            case 'dlq': {
+                if (ctx.storage) {
+                    const dlqEntry = ctx.storage.getDlqEntry(jobId);
+                    if (dlqEntry)
+                        return dlqEntry.job;
+                    const job = ctx.storage.getJob(jobId);
+                    if (job)
+                        return job;
+                }
+                const dlqShardIdx = shardIndex(location.queueName);
+                const dlqJobs = ctx.shards[dlqShardIdx].getDlq(location.queueName);
+                found = dlqJobs.find((job) => job.id === jobId) ?? null;
+                break;
+            }
+        }
+        if (found)
+            return found;
+        if (ctx.jobIndex.get(jobId) === location)
+            return null;
+    }
+    return null;
+}
+export function getJobResult(jobId, ctx) {
+    if (ctx.jobResults.has(jobId))
+        return ctx.jobResults.get(jobId);
+    if (ctx.dependencyResults.has(jobId))
+        return ctx.dependencyResults.get(jobId);
+    const stored = ctx.storage?.getResult(jobId);
+    if (stored !== null)
+        return stored;
+    return ctx.storage?.hasResult(jobId) ? null : undefined;
+}
+export function getJobByCustomId(customId, ctx) {
+    const jobId = ctx.customIdMap.get(customId);
+    if (!jobId)
+        return null;
+    const location = ctx.jobIndex.get(jobId);
+    if (!location)
+        return null;
+    if (location.type === 'queue') {
+        const shard = ctx.shards[location.shardIdx];
+        return (shard.getQueue(location.queueName).find(jobId) ??
+            shard.waitingDeps.get(jobId) ??
+            shard.waitingChildren.get(jobId) ??
+            null);
+    }
+    if (location.type === 'processing') {
+        return ctx.processingShards[location.shardIdx].get(jobId) ?? null;
+    }
+    if (location.type === 'completed') {
+        return ctx.storage?.getJob(jobId) ?? ctx.completedJobsData.get(jobId) ?? null;
+    }
+    if (location.type === 'dlq') {
+        if (ctx.storage) {
+            const job = ctx.storage.getJob(jobId);
+            if (job)
+                return job;
+        }
+        const dlqShardIdx = shardIndex(location.queueName);
+        const dlqJobs = ctx.shards[dlqShardIdx].getDlq(location.queueName);
+        return dlqJobs.find((job) => job.id === jobId) ?? null;
+    }
+    return null;
+}
+export function getJobProgress(jobId, ctx) {
+    const location = ctx.jobIndex.get(jobId);
+    if (location?.type !== 'processing')
+        return null;
+    const job = ctx.processingShards[location.shardIdx].get(jobId);
+    if (!job)
+        return null;
+    return { progress: job.progress, message: job.progressMessage };
+}

package/dist/application/operations/query/pagination.d.ts

@@ -0,0 +1,8 @@
+import type { Job } from '../../../domain/types/job';
+import type { GetJobsContext } from '../../types/query';
+export declare function getJobs(queue: string, shardIdx: number, options: {
+    state?: string | string[];
+    start?: number;
+    end?: number;
+    asc?: boolean;
+}, ctx: GetJobsContext): Job[];

package/dist/application/operations/query/pagination.js

@@ -0,0 +1,90 @@
+import { collectJobsByState, collectTemporalJobs, collectWaitingChildrenJobs, compareJobsByCreatedAt, tagState, } from './collect';
+function querySqliteByLogicalState(storage, queue, sqlFilteredStates, opts) {
+    if (opts.excludedIds.size === 0) {
+        return storage.queryJobsByLogicalStates(queue, sqlFilteredStates, opts);
+    }
+    const pageEnd = opts.offset + opts.limit;
+    const jobs = storage.queryJobsByLogicalStates(queue, sqlFilteredStates, {
+        limit: pageEnd + opts.excludedIds.size,
+        offset: 0,
+        asc: opts.asc,
+        now: opts.now,
+    });
+    return jobs.filter((job) => !opts.excludedIds.has(job.id)).slice(opts.offset, pageEnd);
+}
+function mergePage(sqlJobs, extras, start, end, asc) {
+    const byId = new Map();
+    for (const job of sqlJobs)
+        byId.set(job.id, job);
+    for (const job of extras)
+        byId.set(job.id, job);
+    const merged = Array.from(byId.values());
+    merged.sort((a, b) => compareJobsByCreatedAt(a, b, asc));
+    return merged.slice(start, end);
+}
+export function getJobs(queue, shardIdx, options, ctx) {
+    const { state, start = 0, end = 100, asc = true } = options;
+    const states = !state
+        ? null
+        : Array.isArray(state)
+            ? state.length === 0
+                ? null
+                : state
+            : [state];
+    const limit = end - start;
+    const now = Date.now();
+    if (ctx.storage) {
+        const shard = ctx.shards[shardIdx];
+        const isPaused = shard.getState(queue).paused;
+        if (!states) {
+            const dlq = tagState(shard.getDlq(queue), 'failed');
+            if (dlq.length === 0) {
+                return ctx.storage.queryJobs(queue, { limit, offset: start, asc });
+            }
+            const all = ctx.storage.queryJobs(queue, { limit: end, offset: 0, asc });
+            return mergePage(all, dlq, start, end, asc);
+        }
+        const sqlFilteredStates = states.filter((state) => state !== 'failed' &&
+            state !== 'waiting-children' &&
+            state !== 'paused' &&
+            !(isPaused && (state === 'waiting' || state === 'prioritized')));
+        const parkedJobs = states.includes('waiting-children') || sqlFilteredStates.length > 0
+            ? collectWaitingChildrenJobs(shard, queue)
+            : [];
+        const parkedIds = new Set(parkedJobs.map((job) => job.id));
+        const extras = [];
+        if (states.includes('failed'))
+            extras.push(...tagState(shard.getDlq(queue), 'failed'));
+        if (states.includes('waiting-children')) {
+            extras.push(...tagState(parkedJobs, 'waiting-children'));
+        }
+        if (states.includes('paused') && isPaused) {
+            const pausedJobs = collectTemporalJobs(shard, queue, { waiting: true, prioritized: true, delayed: false }, now);
+            extras.push(...tagState(pausedJobs, 'paused'));
+        }
+        if (extras.length === 0) {
+            return sqlFilteredStates.length > 0
+                ? querySqliteByLogicalState(ctx.storage, queue, sqlFilteredStates, {
+                    limit,
+                    offset: start,
+                    asc,
+                    now,
+                    excludedIds: parkedIds,
+                })
+                : [];
+        }
+        const sqlJobs = sqlFilteredStates.length > 0
+            ? querySqliteByLogicalState(ctx.storage, queue, sqlFilteredStates, {
+                limit: end,
+                offset: 0,
+                asc,
+                now,
+                excludedIds: parkedIds,
+            })
+            : [];
+        return mergePage(sqlJobs, extras, start, end, asc);
+    }
+    const jobs = collectJobsByState(queue, shardIdx, states, ctx, now);
+    jobs.sort((a, b) => compareJobsByCreatedAt(a, b, asc));
+    return jobs.slice(start, end);
+}

package/dist/application/operations/query/state.d.ts

@@ -0,0 +1,4 @@
+import type { JobId } from '../../../domain/types/job';
+import { JobState } from '../../../domain/types/job';
+import type { QueryContext } from '../../types/query';
+export declare function getJobState(jobId: JobId, ctx: QueryContext): Promise<JobState | 'unknown'>;