bunqueue-client 0.1.9 → 0.2.0

package/dist/types/src/application/operations/pushDeduplication.d.ts

@@ -0,0 +1,42 @@
+import type { Shard } from "../../domain/queue/shard.js";
+import type { Job, JobId, JobInput } from "../../domain/types/job.js";
+import type { DurableAdmissionMetadata } from "../../infrastructure/persistence/sqlite.js";
+import { type AcceptedCustomId } from "./pushAdmission.js";
+import type { PushContext } from "./push.js";
+type PendingLocation = 'queue' | 'waiting-deps' | 'waiting-children';
+export interface DedupReplacement {
+    job: Job;
+    location: PendingLocation;
+}
+export interface DedupCommitOptions {
+    readonly ctx: PushContext;
+    readonly customId: AcceptedCustomId;
+    readonly persist?: (admission?: DurableAdmissionMetadata) => void;
+}
+export type DedupResult = {
+    skip: true;
+    existingId: JobId;
+} | {
+    skip: false;
+    replacement?: DedupReplacement;
+    activeOwnerId?: JobId;
+};
+/** Inspect dedup state while deferring destructive replacement mutations. */
+export declare function handleDeduplication(job: Job, input: JobInput, queue: string, shard: Shard, ctx: PushContext): DedupResult;
+/** Commit the RAM half of a replacement after persistence has succeeded. */
+export declare function commitDedupReplacement(replacement: DedupReplacement, newJob: Job, queue: string, shard: Shard, ctx: PushContext): JobId[];
+/** Defensive cleanup for callers that may have pre-published custom-ID ownership. */
+export declare function rollbackIncomingCustomId(job: Job, ctx: PushContext): void;
+/** Persist, detach, and insert a replacement without exposing a half-transition. */
+export declare function replacePendingDedupJob(replacement: DedupReplacement, newJob: Job, input: JobInput, target: {
+    queue: string;
+    shard: Shard;
+    shardIdx: number;
+}, options: DedupCommitOptions): JobId[];
+/** Persist and publish a successor while leaving its active predecessor live. */
+export declare function replaceActiveDedupJob(activeOwnerId: JobId, newJob: Job, input: JobInput, target: {
+    queue: string;
+    shard: Shard;
+    shardIdx: number;
+}, options: DedupCommitOptions): void;
+export {};

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

@@ -0,0 +1,39 @@
+import type { Shard } from "../../domain/queue/shard.js";
+import type { Job, JobId } from "../../domain/types/job.js";
+import type { JobLocation } from "../../domain/types/queue.js";
+import type { SetLike } from "../../shared/lru.js";
+import type { MapLike } from "../../shared/lru.js";
+import type { DependencyResultTracker } from "../dependencyResultTracker.js";
+import type { DependencyCompletionTracker } from "../dependencyCompletions.js";
+import type { SqliteStorage } from "../../infrastructure/persistence/sqlite.js";
+export interface PushInsertContext {
+    storage: SqliteStorage | null;
+    completedJobs: SetLike<JobId>;
+    depCompletions?: DependencyCompletionTracker;
+    jobResults: MapLike<JobId, unknown>;
+    dependencyResults: DependencyResultTracker;
+    jobIndex: Map<JobId, JobLocation>;
+    dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
+}
+export interface PreparedJobInsertion {
+    state: 'waiting-children' | 'delayed' | 'prioritized' | 'waiting';
+    completionPins: JobId[];
+}
+/** Emit only after the complete admission is persisted and published. */
+export declare function emitWaitingChildrenAdmission(job: Job, ctx: PushInsertContext): void;
+/** 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;
+    shard: Shard;
+    shardIdx: number;
+}, ctx: PushInsertContext, recordTimeline?: boolean): void;

package/dist/types/src/application/operations/pushLocks.d.ts

@@ -0,0 +1,15 @@
+import type { JobId, JobInput } from "../../domain/types/job.js";
+import type { JobLocation } from "../../domain/types/queue.js";
+import type { RWLock } from "../../shared/lock.js";
+interface PushLockContext {
+    shardLocks: RWLock[];
+    customIdLock: RWLock;
+    jobIndex: Map<JobId, JobLocation>;
+}
+/**
+ * Lock the target shard plus any shard owning a terminal custom-ID generation.
+ * The required set is rechecked after acquisition because jobIndex may change
+ * while an earlier lock is awaited.
+ */
+export declare function withPushWriteLocks<T>(queue: string, inputs: readonly JobInput[], ctx: PushLockContext, fn: (lockedShardIndexes: ReadonlySet<number>) => T): Promise<T>;
+export {};

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

@@ -0,0 +1,12 @@
+import type { Shard } from "../../../domain/queue/shard.js";
+import type { Job } from "../../../domain/types/job.js";
+import type { GetJobsContext } from "../../types/query.js";
+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/types/src/application/operations/query/jobLookup.d.ts

@@ -0,0 +1,9 @@
+import type { Job, JobId } from "../../../domain/types/job.js";
+import type { QueryContext } from "../../types/query.js";
+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/types/src/application/operations/query/pagination.d.ts

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

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

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

package/dist/types/src/application/operations/queryOperations.d.ts

@@ -0,0 +1,5 @@
+/** Stable query-operation import surface. */
+export { getJob, getJobByCustomId, getJobProgress, getJobResult } from "./query/jobLookup.js";
+export { getJobs } from "./query/pagination.js";
+export { getJobState } from "./query/state.js";
+export type { GetJobsContext, QueryContext } from "../types/query.js";

package/dist/types/src/application/operations/queueControl.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Queue Control Operations
+ * Pause, resume, drain, obliterate, clean, list queues
+ */
+import type { Job, JobId } from "../../domain/types/job.js";
+import type { Shard } from "../../domain/queue/shard.js";
+import type { SqliteStorage } from "../../infrastructure/persistence/sqlite.js";
+import type { MapLike, SetLike } from "../../shared/lru.js";
+import type { DependencyResultTracker } from "../dependencyResultTracker.js";
+/** Context for queue control operations */
+export interface QueueControlContext {
+    shards: Shard[];
+    jobIndex: Map<JobId, {
+        type: string;
+        shardIdx?: number;
+        queueName?: string;
+    }>;
+    processingShards?: Map<JobId, Job>[];
+    completedJobs?: SetLike<JobId>;
+    completedJobsData?: MapLike<JobId, Job>;
+    jobResults?: MapLike<JobId, unknown>;
+    jobResultQueues?: Map<JobId, string>;
+    jobLogs?: MapLike<JobId, unknown>;
+    jobLogQueues?: Map<JobId, string>;
+    dependencyResults: DependencyResultTracker;
+    storage: SqliteStorage | null;
+}
+/** Pause a queue */
+export declare function pauseQueue(queue: string, ctx: QueueControlContext): void;
+/** Resume a queue */
+export declare function resumeQueue(queue: string, ctx: QueueControlContext): void;
+/** Check if queue is paused */
+export declare function isQueuePaused(queue: string, ctx: QueueControlContext): boolean;
+/** Drain all waiting jobs from queue */
+export declare function drainQueue(queue: string, ctx: QueueControlContext): number;
+/** Remove all queue data */
+export declare function obliterateQueue(queue: string, ctx: QueueControlContext): JobId[];
+/** List all queue names */
+export declare function listAllQueues(ctx: QueueControlContext): string[];
+/**
+ * Clean old jobs from queue.
+ * Supported states: waiting/wait, delayed, prioritized, paused, completed, failed.
+ * State='active' is intentionally unsupported: cleaning in-flight jobs races with
+ * the worker's ack path and would leak concurrency/uniqueKey/groupId slots. Use
+ * `fail(jobId)` or `cancelJob(jobId)` to terminate an active job safely.
+ * @returns Array of removed JobIds.
+ */
+export declare function cleanQueue(queue: string, graceMs: number, ctx: QueueControlContext, state?: string, limit?: number): JobId[];
+/** Get count of jobs in queue */
+export declare function getQueueCount(queue: string, ctx: QueueControlContext): number;

package/dist/types/src/application/prometheusOperationalMetrics.d.ts

@@ -0,0 +1,31 @@
+import { type BackupMetrics } from "../infrastructure/backup/backupTelemetry.js";
+/** Runtime/storage gauges which are not part of queue state. */
+export interface SystemMetrics {
+    storageDegraded: boolean;
+    storageDiskFull: boolean;
+    sqliteDatabaseSizeBytes?: number;
+    processHeapUsedBytes: number;
+    processHeapTotalBytes: number;
+    processResidentMemoryBytes: number;
+    processCpuSeconds?: number;
+    processStartTimeSeconds?: number;
+    perQueueMetricsExported?: number;
+    perQueueMetricsOmitted?: number;
+    operational?: OperationalMetrics;
+}
+/** Server components that are owned outside QueueManager. */
+export interface OperationalMetrics {
+    backup?: BackupMetrics;
+    connections?: {
+        tcp: number;
+        websocket: number;
+        sse: number;
+    };
+}
+/** Select a deterministic bounded prefix and report exact conservation. */
+export declare function selectPrometheusQueues(queueNames: Iterable<string>, requestedLimit: number): {
+    selected: Set<string>;
+    omitted: number;
+};
+/** Append bounded operational and standard process collectors. */
+export declare function appendOperationalMetrics(lines: string[], system: SystemMetrics): void;

package/dist/types/src/application/queue-manager/ack.d.ts

@@ -0,0 +1,23 @@
+import type { JobId } from "../../domain/types/job.js";
+import { FailureReason } from "../../domain/types/dlq.js";
+import type { AckBatchOutcome, AckOutcome, CompletionOptions } from "../types/ack.js";
+import { QueueManagerDelivery } from "./delivery.js";
+export declare class QueueManagerAck extends QueueManagerDelivery {
+    ack(jobId: JobId, result?: unknown, token?: string, options?: CompletionOptions): Promise<AckOutcome>;
+    ackBatch(jobIds: JobId[], tokens?: string[]): Promise<AckBatchOutcome>;
+    ackBatchWithResults(items: Array<{
+        id: JobId;
+        result: unknown;
+        token?: string;
+    } & CompletionOptions>): Promise<AckBatchOutcome>;
+    fail(jobId: JobId, error?: string, token?: string, unrecoverable?: boolean, stack?: string[], removeOnFail?: boolean): Promise<AckOutcome>;
+    failWithReason(jobId: JobId, error: string | undefined, failureReason: FailureReason): Promise<AckOutcome>;
+    private isRetiredTimeoutOutcome;
+    private isRetiredOutcome;
+    private isQueuedTimeoutGeneration;
+    private ignoredOutcome;
+    private batchOutcome;
+    private missingJobError;
+    private retireTimedOutGeneration;
+    private failWithOptions;
+}

package/dist/types/src/application/queue-manager/configuration.d.ts

@@ -0,0 +1,27 @@
+import type { JobId, JobLock } from "../../domain/types/job.js";
+import type { JobLogEntry } from "../../domain/types/worker.js";
+import type { StallConfig } from "../../domain/types/stall.js";
+import type { DlqConfig } from "../../domain/types/dlq.js";
+import { QueueManagerLimits } from "./limits.js";
+export declare class QueueManagerConfiguration extends QueueManagerLimits {
+    getDeduplicationJobId(queue: string, key: string): string | null;
+    removeDeduplicationKey(queue: string, key: string): Promise<number>;
+    removeJobDeduplicationKey(id: string): Promise<boolean>;
+    getAllJobResults(): Map<JobId, unknown>;
+    getAllJobLogs(): Map<JobId, JobLogEntry[]>;
+    getAllJobLocks(): Map<JobId, JobLock>;
+    setStallConfig(queue: string, config: Record<string, unknown>): void;
+    getStallConfig(queue: string): StallConfig;
+    setDlqConfig(queue: string, config: Record<string, unknown>): void;
+    getDlqConfig(queue: string): DlqConfig;
+    getCloudTelemetry(queueNames: string[]): {
+        perQueue: Record<string, {
+            uniqueKeys: number;
+            activeGroups: number;
+            waitingDeps: number;
+            waitingChildren: number;
+        }>;
+        eventSubscribers: number;
+        pendingDepChecks: number;
+    };
+}

package/dist/types/src/application/queue-manager/context.d.ts

@@ -0,0 +1,5 @@
+import type { ContextCallbacks, ContextDependencies } from "../contextFactory.js";
+import type { QueueManagerRuntime, QueueManagerStateView } from "../types/index.js";
+export declare function managerRuntime(value: unknown): QueueManagerRuntime;
+export declare function createContextDependencies(state: QueueManagerStateView): ContextDependencies;
+export declare function createContextCallbacks(runtime: QueueManagerRuntime): ContextCallbacks;

package/dist/types/src/application/queue-manager/control.d.ts

@@ -0,0 +1,20 @@
+import type { JobId } from "../../domain/types/job.js";
+import { QueueManagerQueries } from "./queries.js";
+export declare class QueueManagerControl extends QueueManagerQueries {
+    pause(queue: string): void;
+    resume(queue: string): void;
+    isPaused(queue: string): boolean;
+    drain(queue: string): number;
+    obliterate(queue: string): void;
+    protected onQueueAdmissionsDrained(queue: string): void;
+    private hasLiveQueueProjection;
+    protected purgeQueueMetadata(queue: string): void;
+    private dependencyReferencesAfterObliterate;
+    listQueues(): string[];
+    protected registerQueueName(queue: string): void;
+    protected unregisterQueueName(queue: string): void;
+    protected releaseCompletionPins(dependencyIds: Iterable<JobId>): void;
+    protected reconcileCompletionPins(): void;
+    clean(queue: string, graceMs: number, state?: string, limit?: number): JobId[];
+    protected persistQueueState(_queue: string): void;
+}

package/dist/types/src/application/queue-manager/delivery.d.ts

@@ -0,0 +1,33 @@
+import type { Job, JobId, JobInput, JobLock } from "../../domain/types/job.js";
+import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from "../../domain/types/flow.js";
+import type { GroupPullOptions } from "../../domain/types/group.js";
+import { QueueManagerState } from "./state.js";
+export declare class QueueManagerDelivery extends QueueManagerState {
+    push(queue: string, input: JobInput): Promise<Job>;
+    pushBatch(queue: string, inputs: JobInput[]): Promise<JobId[]>;
+    pushFlow(batch: AtomicFlowBatchInput): Promise<AtomicFlowBatchResult>;
+    pull(queue: string, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job | null>;
+    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<{
+        job: Job | null;
+        token: string | null;
+    }>;
+    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job[]>;
+    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<{
+        jobs: Job[];
+        tokens: string[];
+    }>;
+    protected throwIfOwnershipConflict(jobId: JobId, lockCtx: {
+        jobLocks: Map<JobId, JobLock>;
+    }): void;
+    /** Require the exact current lease token whenever a lock record exists. */
+    protected assertLeaseToken(jobId: JobId, token: string | undefined, lockCtx: {
+        jobLocks: Map<JobId, JobLock>;
+    }): void;
+    protected isExpiredButOwned(jobId: JobId, token: string, lockCtx: {
+        jobLocks: Map<JobId, JobLock>;
+    }): boolean;
+    protected isStallRetried(jobId: JobId): boolean;
+    /** Match a late outcome to the exact cron lease retired by lock expiry. */
+    protected isRetiredCronOutcome(jobId: JobId, token: string | undefined): boolean;
+    protected completeStallRetriedJob(jobId: JobId, result: unknown, removeOnComplete?: boolean): Promise<boolean>;
+}

package/dist/types/src/application/queue-manager/dependencies.d.ts

@@ -0,0 +1,8 @@
+import type { JobId } from "../../domain/types/job.js";
+import { QueueManagerFlowOptions } from "./flow-options.js";
+export declare class QueueManagerDependencies extends QueueManagerFlowOptions {
+    getFailedChildrenValues(parentJobId: JobId): Promise<Record<string, string>>;
+    getIgnoredChildrenFailures(parentJobId: JobId): Promise<Record<string, string>>;
+    removeChildDependency(childJobId: JobId): Promise<boolean>;
+    removeUnprocessedChildren(parentJobId: JobId): Promise<void>;
+}

package/dist/types/src/application/queue-manager/dependency-runtime.d.ts

@@ -0,0 +1,8 @@
+import type { JobId } from "../../domain/types/job.js";
+import { QueueManagerServices } from "./services.js";
+export declare class QueueManagerDependencyRuntime extends QueueManagerServices {
+    protected onJobsCompleted(completedIds: JobId[]): void;
+    protected scheduleDependencyFlush(): void;
+    protected runDependencyFlush(): Promise<void>;
+    protected hasPendingDeps(): boolean;
+}

package/dist/types/src/application/queue-manager/flow-failures.d.ts

@@ -0,0 +1,18 @@
+import type { Shard } from "../../domain/queue/shard.js";
+import type { DlqEntry } from "../../domain/types/dlq.js";
+import type { Job, JobId } from "../../domain/types/job.js";
+import type { JobLocation } from "../../domain/types/queue.js";
+import type { SetLike } from "../../shared/lru.js";
+import { QueueManagerDependencyRuntime } from "./dependency-runtime.js";
+export declare class QueueManagerFlowFailures extends QueueManagerDependencyRuntime {
+    protected onDlqEvicted(entry: DlqEntry): void;
+    getJobIndex(): Map<JobId, JobLocation>;
+    getCompletedJobs(): SetLike<JobId>;
+    getDepCompletions(): SetLike<JobId>;
+    getShards(): Shard[];
+    protected onJobCompleted(completedId: JobId): void;
+    protected onJobFailed(failedId: JobId): void;
+    protected checkFlowCompleted(completedId: JobId): Promise<void>;
+    protected failParentOnChildFailure(childJob: Job, error: string | undefined): Promise<void>;
+    protected moveParentToFailed(parentId: JobId, childJob: Job, error: string | undefined): Promise<void>;
+}

package/dist/types/src/application/queue-manager/flow-options.d.ts

@@ -0,0 +1,8 @@
+import type { Job, JobId } from "../../domain/types/job.js";
+import { QueueManagerFlowFailures } from "./flow-failures.js";
+export declare class QueueManagerFlowOptions extends QueueManagerFlowFailures {
+    protected onChildDependencyOption(childJob: Job, error: string | undefined): Promise<void>;
+    protected continueParentOnChildFailure(childJob: Job, error: string | undefined): Promise<void>;
+    protected promoteParentAfterChildFailure(parentId: JobId, parentJob: Job, index: number): Promise<void>;
+    protected removeChildFromParentDeps(childJob: Job, error: string | undefined, storeIgnored: boolean): Promise<void>;
+}

package/dist/types/src/application/queue-manager/job-management.d.ts

@@ -0,0 +1,17 @@
+import type { JobId } from "../../domain/types/job.js";
+import { QueueManagerConfiguration } from "./configuration.js";
+export declare class QueueManagerJobManagement extends QueueManagerConfiguration {
+    cancel(jobId: JobId): Promise<boolean>;
+    updateProgress(jobId: JobId, progress: number, message?: string): Promise<boolean>;
+    updateJobData(jobId: JobId, data: unknown): Promise<boolean>;
+    changePriority(jobId: JobId, priority: number, lifo?: boolean): Promise<boolean>;
+    promote(jobId: JobId): Promise<boolean>;
+    promoteJobs(queue: string, count?: number): Promise<number>;
+    moveToDelayed(jobId: JobId, delay: number, token?: string): Promise<boolean>;
+    changeDelay(jobId: JobId, delay: number, token?: string): Promise<boolean>;
+    moveActiveToWait(jobId: JobId, token?: string): Promise<boolean>;
+    changeWaitingDelay(jobId: JobId, delay: number): Promise<boolean>;
+    moveToWaitingChildren(jobId: JobId, token?: string): Promise<boolean>;
+    extendLock(jobId: JobId | string, token: string | null, duration: number): Promise<boolean>;
+    discard(jobId: JobId, token?: string): Promise<boolean>;
+}

package/dist/types/src/application/queue-manager/lifecycle.d.ts

@@ -0,0 +1,4 @@
+import { QueueManagerDependencies } from "./dependencies.js";
+export declare class QueueManagerLifecycle extends QueueManagerDependencies {
+    shutdown(): void;
+}

package/dist/types/src/application/queue-manager/limits.d.ts

@@ -0,0 +1,58 @@
+import type { Job, JobId } from "../../domain/types/job.js";
+import type { DlqEntry, DlqFilter, DlqStats } from "../../domain/types/dlq.js";
+import { QueueManagerControl } from "./control.js";
+import { type GroupRateLimitOverride } from "../../domain/types/group.js";
+export declare class QueueManagerLimits extends QueueManagerControl {
+    getGroupJobsCount(queue: string, groupId: string): number | Promise<number>;
+    getGroupsJobsCount(queue: string): number | Promise<number>;
+    getGroupActiveCount(queue: string, groupId: string): number | Promise<number>;
+    setGroupRateLimit(queue: string, groupId: string, max: number, duration: number): void | Promise<void>;
+    getGroupRateLimit(queue: string, groupId: string): GroupRateLimitOverride | null | Promise<GroupRateLimitOverride | null>;
+    removeGroupRateLimit(queue: string, groupId: string): number | Promise<number>;
+    getGroupRateLimitTtl(queue: string, groupId: string, maxJobs?: number): number | Promise<number>;
+    setGroupConcurrency(queue: string, groupId: string, concurrency: number): void | Promise<void>;
+    getGroupConcurrency(queue: string, groupId: string): number | null | Promise<number | null>;
+    removeGroupConcurrency(queue: string, groupId: string): number | Promise<number>;
+    pauseGroup(queue: string, groupId: string): boolean | Promise<boolean>;
+    resumeGroup(queue: string, groupId: string): boolean | Promise<boolean>;
+    isGroupPaused(queue: string, groupId: string): boolean | Promise<boolean>;
+    rateLimitGroup(queue: string, groupId: string, duration: number): void | Promise<void>;
+    getCountsPerPriority(queue: string): Record<number, number>;
+    getJobs(queue: string, options?: {
+        state?: string | string[];
+        start?: number;
+        end?: number;
+        asc?: boolean;
+    }): Job[];
+    getDlq(queue: string, count?: number): Job[];
+    getDlqEntries(queue: string, filter?: DlqFilter): DlqEntry[];
+    getDlqCount(queue: string): number;
+    getDlqStats(queue: string): DlqStats;
+    retryDlq(queue: string, jobId?: JobId, limit?: number): number;
+    retryDlqByFilter(queue: string, filter: DlqFilter): number;
+    purgeDlq(queue: string): number;
+    /** Remove one terminal DLQ job without re-enqueuing it. */
+    removeDlqJob(queue: string, jobId: JobId): boolean;
+    retryCompleted(queue: string, jobId?: JobId, options?: {
+        limit?: number;
+        timestamp?: number;
+    }): number;
+    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
+    clearRateLimit(queue: string): void;
+    setConcurrency(queue: string, limit: number): void;
+    clearConcurrency(queue: string): void;
+    protected persistQueueState(queue: string): void;
+    getQueueLimits(queue: string): {
+        rateLimit: number | null;
+        concurrencyLimit: number | null;
+    };
+    getQueueLimitStatus(queue: string, maxJobs?: number): {
+        rateLimit: {
+            max: number;
+            duration: number;
+        } | null;
+        rateLimitTtl: number;
+        concurrencyLimit: number | null;
+        maxed: boolean;
+    };
+}

package/dist/types/src/application/queue-manager/locks.d.ts

@@ -0,0 +1,21 @@
+import type { JobId, JobLock, LockToken } from "../../domain/types/job.js";
+import { QueueManagerAck } from "./ack.js";
+export declare class QueueManagerLocks extends QueueManagerAck {
+    jobHeartbeat(jobId: JobId, token?: string): boolean;
+    jobHeartbeatBatch(jobIds: JobId[], tokens?: string[]): number;
+    removeLock(jobId: JobId): void;
+    createLock(jobId: JobId, owner: string, ttl?: number): LockToken | null;
+    verifyLock(jobId: JobId, token: string): boolean;
+    renewJobLock(jobId: JobId, token: string, newTtl?: number): boolean;
+    renewJobLockBatch(items: Array<{
+        id: JobId;
+        token: string;
+        ttl?: number;
+    }>): string[];
+    releaseLock(jobId: JobId, token?: string): boolean;
+    getLockInfo(jobId: JobId): JobLock | null;
+    registerClientJob(clientId: string, jobId: JobId): void;
+    unregisterClientJob(clientId: string | undefined, jobId: JobId): void;
+    releaseClientJobs(clientId: string): Promise<number>;
+    forceReleaseClientJobs(clientId: string): number;
+}

package/dist/types/src/application/queue-manager/observability.d.ts

@@ -0,0 +1,16 @@
+import type { JobId } from "../../domain/types/job.js";
+import type { JobLogEntry } from "../../domain/types/worker.js";
+import { type OperationalMetrics } from "../metricsExporter.js";
+import * as statsMgr from "../statsManager.js";
+import type { QueueMetricType } from "../../domain/types/metrics.js";
+import { QueueManagerStats } from "./stats.js";
+export declare class QueueManagerObservability extends QueueManagerStats {
+    getQueueMetrics(queue: string, type: QueueMetricType, start?: number, end?: number): import("../../client/index.js").QueueMetrics;
+    trimQueueEvents(queue: string, maxLength: number): number;
+    addLog(jobId: JobId, message: string, level?: 'info' | 'warn' | 'error'): boolean;
+    getLogs(jobId: JobId): JobLogEntry[];
+    clearLogs(jobId: JobId, keepLogs?: number): void;
+    getPerQueueStats(): Map<string, statsMgr.PerQueueStats>;
+    getPrometheusMetrics(): string;
+    setOperationalMetricsProvider(provider: () => OperationalMetrics): void;
+}

package/dist/types/src/application/queue-manager/queries.d.ts

@@ -0,0 +1,24 @@
+import type { Job, JobId } from "../../domain/types/job.js";
+import { QueueManagerLocks } from "./locks.js";
+export declare class QueueManagerQueries extends QueueManagerLocks {
+    getJob(jobId: JobId): Promise<Job | null>;
+    getJobState(jobId: JobId): Promise<string>;
+    getResult(jobId: JobId): unknown;
+    /** Distinguish a completed generation from a valid undefined result. */
+    getCompletionAsync(jobId: JobId): Promise<{
+        found: boolean;
+        result: unknown;
+    }>;
+    /** Async result port used by transports; memory and SQLite remain synchronous internally. */
+    getResultAsync(jobId: JobId): Promise<unknown>;
+    getChildrenValues(parentJobId: JobId): Promise<Record<string, unknown>>;
+    updateJobParent(childJobId: JobId, parentJobId: JobId): Promise<void>;
+    getJobByCustomId(customId: string): Job | null;
+    getProgress(jobId: JobId): {
+        progress: number;
+        message: string | null;
+    } | null;
+    count(queue: string): number;
+    protected moveParentToFailed(_parentId: JobId, _childJob: Job, _error: string | undefined): Promise<void>;
+    protected onChildDependencyOption(_childJob: Job, _error: string | undefined): Promise<void>;
+}

package/dist/types/src/application/queue-manager/repeat.d.ts

@@ -0,0 +1,4 @@
+import type { Job } from "../../domain/types/job.js";
+import type { QueueManagerRuntime } from "../types/index.js";
+/** Schedule one successor after a successful repeat generation. */
+export declare function handleRepeat(runtime: QueueManagerRuntime, job: Job): void;

package/dist/types/src/application/queue-manager/services.d.ts

@@ -0,0 +1,19 @@
+import type { CronJob, CronJobInput } from "../../domain/types/cron.js";
+import type { JobId } from "../../domain/types/job.js";
+import type { JobEvent } from "../../domain/types/queue.js";
+import type { CreateWorkerOptions } from "../../domain/types/worker.js";
+import { QueueManagerObservability } from "./observability.js";
+export declare class QueueManagerServices extends QueueManagerObservability {
+    addCron(input: CronJobInput): CronJob;
+    protected removeOrphanedCronJob(queue: string, uniqueKey: string): void;
+    removeCron(name: string): boolean;
+    getCron(name: string): CronJob | undefined;
+    listCrons(): CronJob[];
+    setDashboardEmit(fn: (event: string, data: Record<string, unknown>) => void): void;
+    emitDashboardEvent(event: string, data: Record<string, unknown>): void;
+    subscribe(callback: (event: JobEvent) => void): () => void;
+    waitForJobCompletion(jobId: JobId, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    registerWorker(name: string, queues: string[], concurrency?: number, options?: CreateWorkerOptions): import("../../domain/types/worker.js").Worker;
+    unregisterWorker(workerId: string): boolean;
+    unregisterWorkersByClientId(clientId: string): number;
+}