bunqueue-client 0.1.9 → 0.2.1

package/dist/types/src/client/queue/failWire.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared FAIL payload builder.
+ *
+ * Several client entry points move a job to `failed` (the Queue reflection API
+ * `queue.getJob(id).moveToFailed()`, the job proxies, and `moveJobToFailed`).
+ * They must all persist the stacktrace (#74) and honour `UnrecoverableError`,
+ * exactly like the worker failure path — otherwise the stack and the
+ * "do not retry" intent are silently dropped (the #111 silent-loss class).
+ * Centralising the mapping here keeps every site consistent.
+ */
+/** Build the TCP `FAIL` command for an explicit job failure. */
+export declare function buildFailCommand(id: string, error: Error, token?: string): Record<string, unknown>;
+/**
+ * Decompose an error into the trailing args of the embedded
+ * `manager.fail(jobId, error?, token?, unrecoverable?, stack?)` signature.
+ */
+export declare function failEmbeddedArgs(error: Error, token?: string): [string, string | undefined, boolean, string[] | undefined];

package/dist/types/src/client/queue/helpers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Queue Helpers
+ * Utility functions for queue operations
+ */
+import type { getSharedManager } from "../manager.js";
+import type { Shard } from "../../domain/queue/shard.js";
+import type { DlqFilter, DlqConfig as DomainDlqConfig } from "../../domain/types/dlq.js";
+import type { DlqFilter as ClientDlqFilter } from "../types.js";
+import type * as dlqOps from "../../application/dlqManager.js";
+/** Check if embedded mode should be forced (for tests) */
+export declare const FORCE_EMBEDDED: boolean;
+/** Get shard from manager (embedded mode only) */
+export declare function getShard(manager: ReturnType<typeof getSharedManager>, queue: string): Shard;
+/** Create DLQ context (embedded mode only) */
+export declare function getDlqContext(manager: ReturnType<typeof getSharedManager>): dlqOps.DlqContext;
+/** Convert client filter to domain filter */
+export declare function toDomainFilter(filter: ClientDlqFilter | undefined): DlqFilter | undefined;
+/** Convert client DLQ config to domain config */
+export declare function toDomainDlqConfig(config: Record<string, unknown>): Partial<DomainDlqConfig>;

package/dist/types/src/client/queue/job-proxy/dependencies.d.ts

@@ -0,0 +1,9 @@
+import type { TcpConnectionPool } from "../../tcpPool.js";
+export declare function computeDependencies(id: string, queueName: string, tcp: TcpConnectionPool): Promise<{
+    processed: Record<string, unknown>;
+    unprocessed: string[];
+}>;
+export declare function computeSimpleDependencies(id: string, queueName: string, embedded: boolean | undefined, tcp: TcpConnectionPool | null | undefined): Promise<{
+    processed: Record<string, unknown>;
+    unprocessed: string[];
+}>;

package/dist/types/src/client/queue/job-proxy/reflection.d.ts

@@ -0,0 +1,2 @@
+import type { JobReflectionMeta, ReflectedFields } from "../types/job.js";
+export declare function reflectFields(id: string, queueName: string, meta?: JobReflectionMeta): ReflectedFields;

package/dist/types/src/client/queue/job-proxy/simple.d.ts

@@ -0,0 +1,3 @@
+import type { Job } from "../../types.js";
+import type { SimpleJobContext } from "../types/job.js";
+export declare function createSimpleJob<T>(id: string, name: string, data: T, timestamp: number, ctx: SimpleJobContext): Job<T>;

package/dist/types/src/client/queue/job-proxy/tcp.d.ts

@@ -0,0 +1,4 @@
+import type { Job } from "../../types.js";
+import type { JobProxyContext, JobReflectionMeta } from "../types/job.js";
+/** Create a full Job proxy whose methods use the TCP transport. */
+export declare function createJobProxy<T>(id: string, name: string, data: T, ctx: JobProxyContext, meta?: JobReflectionMeta): Job<T>;

package/dist/types/src/client/queue/jobMetadata.d.ts

@@ -0,0 +1,10 @@
+import type { Job as InternalJob } from "../../domain/types/job.js";
+import type { JobReflectionMeta } from "./types/job.js";
+export interface TerminalJobView extends InternalJob {
+    returnvalue?: unknown;
+    failedReason?: string;
+}
+/** Build one public metadata shape for embedded and TCP queue reads. */
+export declare function metadataFromJob(job: TerminalJobView, embeddedResult?: unknown): JobReflectionMeta;
+/** Encode terminal values for BullMQ-compatible raw JSON output. */
+export declare function serializeReturnvalue(value: unknown): string | undefined;

package/dist/types/src/client/queue/jobMove.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Job Move Operations (BullMQ v5 compatible)
+ */
+import type { TcpConnectionPool } from "../tcpPool.js";
+interface JobMoveContext {
+    name: string;
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+    getJobState: (id: string) => Promise<'waiting' | 'prioritized' | 'delayed' | 'active' | 'completed' | 'failed' | 'waiting-children' | 'unknown'>;
+    getJobDependencies: (id: string) => Promise<{
+        processed: Record<string, unknown>;
+        unprocessed: string[];
+    }>;
+}
+/** Move job to completed state */
+export declare function moveJobToCompleted(ctx: JobMoveContext, id: string, returnValue: unknown, token?: string): Promise<unknown>;
+/** Move job to failed state */
+export declare function moveJobToFailed(ctx: JobMoveContext, id: string, error: Error, token?: string): Promise<void>;
+/** Move job back to waiting state */
+export declare function moveJobToWait(ctx: JobMoveContext, id: string, token?: string): Promise<boolean>;
+/** Move job to delayed state */
+export declare function moveJobToDelayed(ctx: JobMoveContext, id: string, timestamp: number, token?: string): Promise<void>;
+/** Move job to waiting-children state */
+export declare function moveJobToWaitingChildren(ctx: JobMoveContext, id: string, token?: string, _opts?: {
+    child?: {
+        id: string;
+        queue: string;
+    };
+}): Promise<boolean>;
+/** Wait until job has finished */
+export declare function waitJobUntilFinished(ctx: JobMoveContext, id: string, queueEvents: unknown, ttl?: number): Promise<unknown>;
+export {};

package/dist/types/src/client/queue/jobProxy.d.ts

@@ -0,0 +1,4 @@
+/** Stable Job proxy import surface. */
+export { createSimpleJob } from "./job-proxy/simple.js";
+export { createJobProxy } from "./job-proxy/tcp.js";
+export type { JobReflectionMeta, SimpleJobContext } from "./types/job.js";

package/dist/types/src/client/queue/operations/add/bulk.d.ts

@@ -0,0 +1,7 @@
+import type { Job, JobOptions } from "../../../types.js";
+import type { AddContext } from "../../types/add.js";
+export declare function addBulk<T>(context: AddContext, jobs: Array<{
+    name: string;
+    data: T;
+    opts?: JobOptions;
+}>): Promise<Job<T>[]>;

package/dist/types/src/client/queue/operations/add/payload.d.ts

@@ -0,0 +1,25 @@
+import type { JobOptions } from "../../../types.js";
+import type { ExtendedJobOptions } from "../../types/add.js";
+export declare function compact<T extends Record<string, unknown>>(object: T): T;
+export declare function parseDate(date: Date | string | number | undefined): number | undefined;
+export declare function buildRepeatOptions(repeat: NonNullable<JobOptions['repeat']>): {
+    every: number | undefined;
+    limit: number | undefined;
+    pattern: string | undefined;
+    count: number | undefined;
+    startDate: number | undefined;
+    endDate: number | undefined;
+    tz: string | undefined;
+    immediately: boolean | undefined;
+    prevMillis: number | undefined;
+    offset: number | undefined;
+    jobId: string | undefined;
+};
+export declare function buildPushPayload(queue: string, name: string, data: unknown, options: ExtendedJobOptions): Record<string, unknown>;
+export declare function resolveGroupId(options: ExtendedJobOptions): string | undefined;
+export declare function buildJobData(data: unknown, options: ExtendedJobOptions): unknown;
+export declare function reflectionMeta(options: ExtendedJobOptions): {
+    priority?: number;
+    delay?: number;
+    opts: JobOptions;
+};

package/dist/types/src/client/queue/operations/add/single.d.ts

@@ -0,0 +1,3 @@
+import type { Job, JobOptions } from "../../../types.js";
+import type { AddContext } from "../../types/add.js";
+export declare function add<T>(context: AddContext, jobName: string, data: T, options?: JobOptions): Promise<Job<T>>;

package/dist/types/src/client/queue/operations/add.d.ts

@@ -0,0 +1,2 @@
+export { addBulk } from "./add/bulk.js";
+export { add } from "./add/single.js";

package/dist/types/src/client/queue/operations/control.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Queue Control Operations
+ * pause, resume, drain, obliterate, isPaused
+ */
+import type { TcpConnectionPool } from "../../tcpPool.js";
+interface ControlContext {
+    name: string;
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+}
+/** Pause the queue */
+export declare function pause(ctx: ControlContext): void;
+/** Pause the queue and resolve once the server has processed it. */
+export declare function pauseAsync(ctx: ControlContext): Promise<void>;
+/** Resume the queue */
+export declare function resume(ctx: ControlContext): void;
+/** Resume the queue and resolve once the server has processed it. */
+export declare function resumeAsync(ctx: ControlContext): Promise<void>;
+/** Drain the queue (remove all waiting jobs) */
+export declare function drain(ctx: ControlContext): void;
+/**
+ * Drain the queue and resolve with the number of removed jobs once the
+ * server has processed it. Same ordering guarantee as obliterateAsync():
+ * jobs added after resolution cannot be caught by a late-arriving drain.
+ */
+export declare function drainAsync(ctx: ControlContext): Promise<number>;
+/** Obliterate the queue (remove all jobs and data) */
+export declare function obliterate(ctx: ControlContext): void;
+/**
+ * Obliterate the queue and resolve once the server has processed it.
+ * The fire-and-forget obliterate() gives no ordering guarantee over a
+ * multi-connection pool: a PUSH sent right after it can be processed first
+ * and then wiped. Await this variant before enqueuing follow-up jobs.
+ */
+export declare function obliterateAsync(ctx: ControlContext): Promise<void>;
+/** Check if queue is paused (sync, embedded only) */
+export declare function isPaused(ctx: ControlContext): boolean;
+/** Check if queue is paused (async, works with TCP) */
+export declare function isPausedAsync(ctx: ControlContext): Promise<boolean>;
+/** Wait until queue is ready */
+export declare function waitUntilReady(ctx: ControlContext): Promise<void>;
+export {};

package/dist/types/src/client/queue/operations/counts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Queue Count Operations
+ * getJobCounts, getWaitingCount, getDelayedCount, etc.
+ */
+import type { TcpConnectionPool } from "../../tcpPool.js";
+interface CountsContext {
+    name: string;
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+}
+export interface JobCounts {
+    waiting: number;
+    prioritized: number;
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+    paused: number;
+    'waiting-children': number;
+}
+/**
+ * Get job counts.
+ * Embedded mode returns synchronously. TCP mode delegates to the async path so
+ * callers receive the REAL server-side counts (awaitable Promise) instead of
+ * hardcoded zeros — defect: getjobcounts-tcp-zero.
+ */
+export declare function getJobCounts(ctx: CountsContext): JobCounts | Promise<JobCounts>;
+/** Get job counts (async, works with TCP) */
+export declare function getJobCountsAsync(ctx: CountsContext): Promise<JobCounts>;
+/** Get waiting job count */
+export declare function getWaitingCount(ctx: CountsContext): Promise<number>;
+/** Get active job count */
+export declare function getActiveCount(ctx: CountsContext): Promise<number>;
+/** Get completed job count */
+export declare function getCompletedCount(ctx: CountsContext): Promise<number>;
+/** Get failed job count */
+export declare function getFailedCount(ctx: CountsContext): Promise<number>;
+/** Get delayed job count */
+export declare function getDelayedCount(ctx: CountsContext): Promise<number>;
+/** Get total job count for the queue */
+export declare function count(ctx: CountsContext): number;
+/** Get total job count (async, works with TCP) */
+export declare function countAsync(ctx: CountsContext): Promise<number>;
+/** Get counts grouped by priority */
+export declare function getCountsPerPriority(ctx: CountsContext): Record<number, number>;
+/** Get counts grouped by priority (async) */
+export declare function getCountsPerPriorityAsync(ctx: CountsContext): Promise<Record<number, number>>;
+export {};

package/dist/types/src/client/queue/operations/groups.d.ts

@@ -0,0 +1,24 @@
+import type { TcpConnectionPool } from "../../tcpPool.js";
+interface GroupContext {
+    name: string;
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+    dataPath: string | undefined;
+}
+export declare function getGroupJobsCount(ctx: GroupContext, groupId: string): Promise<number>;
+export declare function getGroupsJobsCount(ctx: GroupContext, maxCount?: number): Promise<number>;
+export declare function getGroupActiveCount(ctx: GroupContext, groupId: string): Promise<number>;
+export declare function setGroupRateLimit(ctx: GroupContext, groupId: string, max: number, duration: number): Promise<void>;
+export declare function getGroupRateLimit(ctx: GroupContext, groupId: string): Promise<{
+    max: number;
+    duration: number;
+} | null>;
+export declare function removeGroupRateLimit(ctx: GroupContext, groupId: string): Promise<number>;
+export declare function getGroupRateLimitTtl(ctx: GroupContext, groupId: string, maxJobs?: number): Promise<number>;
+export declare function setGroupConcurrency(ctx: GroupContext, groupId: string, concurrency: number): Promise<void>;
+export declare function getGroupConcurrency(ctx: GroupContext, groupId: string): Promise<number | null>;
+export declare function removeGroupConcurrency(ctx: GroupContext, groupId: string): Promise<number>;
+export declare function pauseGroup(ctx: GroupContext, groupId: string): Promise<boolean>;
+export declare function resumeGroup(ctx: GroupContext, groupId: string): Promise<boolean>;
+export declare function isGroupPaused(ctx: GroupContext, groupId: string): Promise<boolean>;
+export {};

package/dist/types/src/client/queue/operations/management.d.ts

@@ -0,0 +1,51 @@
+import type { TcpConnectionPool } from "../../tcpPool.js";
+interface ManagementContext {
+    name: string;
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+}
+/** Remove a job (sync, fire-and-forget; use removeAsync to await the removal) */
+export declare function remove(ctx: ManagementContext, id: string): void;
+/** Remove a job (async) */
+export declare function removeAsync(ctx: ManagementContext, id: string): Promise<void>;
+/** Retry a specific job — BullMQ contract: failed → waiting. */
+export declare function retryJob(ctx: ManagementContext, id: string): Promise<void>;
+/** Retry jobs matching criteria */
+export declare function retryJobs(ctx: ManagementContext, opts?: {
+    state?: 'failed' | 'completed';
+    count?: number;
+    timestamp?: number;
+}): Promise<void>;
+/** Clean old jobs (sync) */
+export declare function clean(ctx: ManagementContext, grace: number, limit: number, type?: 'completed' | 'wait' | 'active' | 'paused' | 'delayed' | 'failed'): string[];
+/** Clean old jobs (async) */
+export declare function cleanAsync(ctx: ManagementContext, grace: number, limit: number, type?: 'completed' | 'wait' | 'active' | 'paused' | 'delayed' | 'failed'): Promise<string[]>;
+/** Promote delayed jobs to waiting */
+export declare function promoteJobs(ctx: ManagementContext, opts?: {
+    count?: number;
+}): Promise<number>;
+/** Promote a single job */
+export declare function promoteJob(ctx: ManagementContext, id: string): Promise<void>;
+/** Update job progress */
+export declare function updateJobProgress(ctx: ManagementContext, id: string, progress: number | object): Promise<void>;
+/** Get job logs */
+export declare function getJobLogs(ctx: ManagementContext, id: string, start?: number, end?: number): Promise<{
+    logs: string[];
+    count: number;
+}>;
+/** Add a log entry to a job */
+export declare function addJobLog(ctx: ManagementContext, id: string, logRow: string): Promise<number>;
+/** Clear job logs */
+export declare function clearJobLogs(ctx: ManagementContext, id: string, keepLogs?: number): Promise<void>;
+/** Update job data */
+export declare function updateJobData(ctx: ManagementContext, id: string, data: unknown): Promise<void>;
+/** Change job delay */
+export declare function changeJobDelay(ctx: ManagementContext, id: string, delay: number): Promise<void>;
+/** Change job priority */
+export declare function changeJobPriority(ctx: ManagementContext, id: string, opts: {
+    priority: number;
+    lifo?: boolean;
+}): Promise<void>;
+/** Extend job lock */
+export declare function extendJobLock(ctx: ManagementContext, id: string, token: string, duration: number): Promise<number>;
+export {};

package/dist/types/src/client/queue/operations/query.d.ts

@@ -0,0 +1,50 @@
+import type { TcpConnectionPool } from "../../tcpPool.js";
+import type { Job, JobStateType, GetDependenciesOpts, JobDependencies, JobDependenciesCount } from "../../types.js";
+export interface QueryContext {
+    name: string;
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+    getJobState: (id: string) => Promise<JobStateType>;
+    removeAsync: (id: string) => Promise<void>;
+    retryJob: (id: string) => Promise<void>;
+    getChildrenValues: (id: string) => Promise<Record<string, unknown>>;
+    updateJobData?: (id: string, data: unknown) => Promise<void>;
+    promoteJob?: (id: string) => Promise<void>;
+    changeJobDelay?: (id: string, delay: number) => Promise<void>;
+    changeJobPriority?: (id: string, opts: {
+        priority: number;
+        lifo?: boolean;
+    }) => Promise<void>;
+    extendJobLock?: (id: string, token: string, duration: number) => Promise<number>;
+    clearJobLogs?: (id: string, keepLogs?: number) => Promise<void>;
+    getJobDependencies?: (id: string, opts?: GetDependenciesOpts) => Promise<JobDependencies>;
+    getJobDependenciesCount?: (id: string, opts?: GetDependenciesOpts) => Promise<JobDependenciesCount>;
+    moveJobToCompleted?: (id: string, returnValue: unknown, token?: string) => Promise<unknown>;
+    moveJobToFailed?: (id: string, error: Error, token?: string) => Promise<void>;
+    moveJobToWait?: (id: string, token?: string) => Promise<boolean>;
+    moveJobToDelayed?: (id: string, timestamp: number, token?: string) => Promise<void>;
+    moveJobToWaitingChildren?: (id: string, token?: string, opts?: {
+        child?: {
+            id: string;
+            queue: string;
+        };
+    }) => Promise<boolean>;
+    waitJobUntilFinished?: (id: string, queueEvents: unknown, ttl?: number) => Promise<unknown>;
+}
+/** Get a single job by ID */
+export declare function getJob<T>(ctx: QueryContext, id: string): Promise<Job<T> | null>;
+/** Get job state by ID */
+export declare function getJobState(ctx: QueryContext, id: string): Promise<JobStateType>;
+/** Get children values for a job */
+export declare function getChildrenValues(ctx: QueryContext, id: string): Promise<Record<string, unknown>>;
+interface GetJobsOptions {
+    state?: string | string[];
+    start?: number;
+    end?: number;
+    asc?: boolean;
+}
+/** Get jobs with filtering (sync, embedded only) */
+export declare function getJobs<T>(ctx: QueryContext, options?: GetJobsOptions): Job<T>[];
+/** Get jobs with filtering (async, works with TCP) */
+export declare function getJobsAsync<T>(ctx: QueryContext, options?: GetJobsOptions): Promise<Job<T>[]>;
+export {};

package/dist/types/src/client/queue/operations/queryStates.d.ts

@@ -0,0 +1,13 @@
+/** State-specific aliases over the generic queue query operations. */
+import type { Job } from "../../types.js";
+import { type QueryContext } from "./query.js";
+export declare function getWaiting<T>(ctx: QueryContext, start?: number, end?: number): Job<T>[];
+export declare function getWaitingAsync<T>(ctx: QueryContext, start?: number, end?: number): Promise<Job<T>[]>;
+export declare function getDelayed<T>(ctx: QueryContext, start?: number, end?: number): Job<T>[];
+export declare function getDelayedAsync<T>(ctx: QueryContext, start?: number, end?: number): Promise<Job<T>[]>;
+export declare function getActive<T>(ctx: QueryContext, start?: number, end?: number): Job<T>[];
+export declare function getActiveAsync<T>(ctx: QueryContext, start?: number, end?: number): Promise<Job<T>[]>;
+export declare function getCompleted<T>(ctx: QueryContext, start?: number, end?: number): Job<T>[];
+export declare function getCompletedAsync<T>(ctx: QueryContext, start?: number, end?: number): Promise<Job<T>[]>;
+export declare function getFailed<T>(ctx: QueryContext, start?: number, end?: number): Job<T>[];
+export declare function getFailedAsync<T>(ctx: QueryContext, start?: number, end?: number): Promise<Job<T>[]>;

package/dist/types/src/client/queue/operations/queryTcpPages.d.ts

@@ -0,0 +1,14 @@
+import type { TcpConnectionPool } from "../../tcpPool.js";
+interface TcpQueryContext {
+    name: string;
+    tcp: TcpConnectionPool;
+}
+export interface TcpJobQueryOptions {
+    state?: string | string[];
+    start?: number;
+    end?: number;
+    asc?: boolean;
+}
+/** Read a finite range once, or page until exhaustion when `end` is -1. */
+export declare function fetchTcpJobRows(ctx: TcpQueryContext, options: TcpJobQueryOptions): Promise<Record<string, unknown>[] | null>;
+export {};

package/dist/types/src/client/queue/queue.d.ts

@@ -0,0 +1,12 @@
+/** BullMQ-style queue for job management. */
+import { Forwarder, type ForwardOptions } from "../forwarder.js";
+import { QueueConnection } from "./runtime/connection.js";
+/** Public Queue façade; behavior is implemented by focused runtime layers. */
+export declare class Queue<T = unknown> extends QueueConnection<T> {
+    /**
+     * Drain this queue's jobs to a remote bunqueue server (store-and-forward).
+     * Remote failures leave jobs local and deterministic remote IDs prevent
+     * duplicate delivery when a forward is retried.
+     */
+    forward(options: ForwardOptions): Forwarder;
+}

package/dist/types/src/client/queue/rateLimit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Rate Limit and Concurrency Operations
+ */
+import type { TcpConnectionPool } from "../tcpPool.js";
+interface RateLimitContext {
+    name: string;
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+}
+/** Set global concurrency limit */
+export declare function setGlobalConcurrency(ctx: RateLimitContext, concurrency: number): void;
+/** Set global concurrency limit and resolve once the server has applied it. */
+export declare function setGlobalConcurrencyAsync(ctx: RateLimitContext, concurrency: number): Promise<void>;
+/** Remove global concurrency limit */
+export declare function removeGlobalConcurrency(ctx: RateLimitContext): void;
+/** Remove global concurrency limit and resolve once the server has applied it. */
+export declare function removeGlobalConcurrencyAsync(ctx: RateLimitContext): Promise<void>;
+/** Get global concurrency limit */
+export declare function getGlobalConcurrency(ctx: RateLimitContext): Promise<number | null>;
+/**
+ * Set global rate limit: `max` jobs per `duration` ms (default 1000ms).
+ * The window is honored in both embedded and TCP modes.
+ */
+export declare function setGlobalRateLimit(ctx: RateLimitContext, max: number, duration?: number): void;
+/** Set global rate limit and resolve once the server has applied it. */
+export declare function setGlobalRateLimitAsync(ctx: RateLimitContext, max: number, duration?: number): Promise<void>;
+/** Remove global rate limit */
+export declare function removeGlobalRateLimit(ctx: RateLimitContext): void;
+/** Remove global rate limit and resolve once the server has applied it. */
+export declare function removeGlobalRateLimitAsync(ctx: RateLimitContext): Promise<void>;
+/** Get global rate limit */
+export declare function getGlobalRateLimit(ctx: RateLimitContext): Promise<{
+    max: number;
+    duration: number;
+} | null>;
+/**
+ * Set temporary rate limit with expiration. The expiry lives broker-side
+ * (RateLimit `ttl`), so it survives client exit and works identically in
+ * embedded and TCP modes — no client timer involved.
+ */
+export declare function rateLimit(ctx: RateLimitContext, expireTimeMs: number): Promise<void>;
+/** Get rate limit TTL */
+export declare function getRateLimitTtl(ctx: RateLimitContext, maxJobs?: number): Promise<number>;
+/** Check if queue is at max capacity */
+export declare function isMaxed(ctx: RateLimitContext): Promise<boolean>;
+export {};

package/dist/types/src/client/queue/runtime/compatibility.d.ts

@@ -0,0 +1,13 @@
+import * as workersOps from "../workers.js";
+import { QueueScheduling } from "./scheduling.js";
+/** BullMQ compatibility helpers plus worker and metrics inspection. */
+export declare class QueueCompatibility<T> extends QueueScheduling<T> {
+    getPrioritized(start?: number, end?: number): Promise<import("../../index.js").Job<T>[]>;
+    getPrioritizedCount(): Promise<number>;
+    getWaitingChildren(start?: number, end?: number): Promise<import("../../index.js").Job<T>[]>;
+    getWaitingChildrenCount(): Promise<number>;
+    trimEvents(maxLength: number): Promise<number>;
+    getWorkers(): Promise<workersOps.WorkerInfo[]>;
+    getWorkersCount(): Promise<number>;
+    getMetrics(type: 'completed' | 'failed', start?: number, end?: number): Promise<import("../../index.js").QueueMetrics>;
+}

package/dist/types/src/client/queue/runtime/configuration.d.ts

@@ -0,0 +1,46 @@
+import type { DlqConfig, DlqEntry, DlqFilter, DlqStats, StallConfig } from "../../types.js";
+import { QueueControl } from "./control.js";
+/** Stall, DLQ, concurrency, and rate-limit configuration. */
+export declare class QueueConfiguration<T> extends QueueControl<T> {
+    setStallConfig(config: Partial<StallConfig>): void;
+    setStallConfigAsync(config: Partial<StallConfig>): Promise<void>;
+    getStallConfig(): StallConfig;
+    getStallConfigAsync(): Promise<StallConfig>;
+    setDlqConfig(config: Partial<DlqConfig>): void;
+    setDlqConfigAsync(config: Partial<DlqConfig>): Promise<void>;
+    getDlqConfig(): DlqConfig;
+    getDlqConfigAsync(): Promise<DlqConfig>;
+    getDlq(filter?: DlqFilter): DlqEntry<T>[];
+    getDlqAsync(filter?: DlqFilter): Promise<DlqEntry<T>[]>;
+    getDlqJobsAsync(count?: number): Promise<import("../../index.js").Job<T>[]>;
+    getDlqStats(): DlqStats;
+    getDlqStatsAsync(): Promise<DlqStats>;
+    retryDlq(id?: string): number;
+    retryDlqAsync(id?: string): Promise<number>;
+    retryDlqByFilter(filter: DlqFilter): number;
+    retryDlqByFilterAsync(filter: DlqFilter): Promise<number>;
+    purgeDlq(): number;
+    purgeDlqAsync(): Promise<number>;
+    /** Remove one DLQ entry and resolve when the removal completes. */
+    removeDlqJob(id: string): Promise<boolean>;
+    /** Explicit async alias for removeDlqJob. */
+    removeDlqJobAsync(id: string): Promise<boolean>;
+    retryCompleted(id?: string): number;
+    retryCompletedAsync(id?: string): Promise<number>;
+    setGlobalConcurrency(concurrency: number): void;
+    setGlobalConcurrencyAsync(concurrency: number): Promise<void>;
+    removeGlobalConcurrency(): void;
+    removeGlobalConcurrencyAsync(): Promise<void>;
+    getGlobalConcurrency(): Promise<number | null>;
+    setGlobalRateLimit(max: number, duration?: number): void;
+    setGlobalRateLimitAsync(max: number, duration?: number): Promise<void>;
+    removeGlobalRateLimit(): void;
+    removeGlobalRateLimitAsync(): Promise<void>;
+    getGlobalRateLimit(): Promise<{
+        max: number;
+        duration: number;
+    } | null>;
+    rateLimit(expireTimeMs: number): Promise<void>;
+    getRateLimitTtl(maxJobs?: number): Promise<number>;
+    isMaxed(): Promise<boolean>;
+}

package/dist/types/src/client/queue/runtime/connection.d.ts

@@ -0,0 +1,6 @@
+import { QueueCompatibility } from "./compatibility.js";
+/** Queue batching shutdown and transport cleanup. */
+export declare class QueueConnection<T> extends QueueCompatibility<T> {
+    disconnect(): Promise<void>;
+    close(): void;
+}

package/dist/types/src/client/queue/runtime/control.d.ts

@@ -0,0 +1,41 @@
+import type { ChangePriorityOpts } from "../../types.js";
+import { QueueQueries } from "./queries.js";
+/** Queue lifecycle controls and individual job management operations. */
+export declare class QueueControl<T> extends QueueQueries<T> {
+    pause(): void;
+    pauseAsync(): Promise<void>;
+    resume(): void;
+    resumeAsync(): Promise<void>;
+    drain(): void;
+    drainAsync(): Promise<number>;
+    obliterate(): void;
+    obliterateAsync(): Promise<void>;
+    isPaused(): boolean;
+    isPausedAsync(): Promise<boolean>;
+    waitUntilReady(): Promise<void>;
+    remove(id: string): void;
+    removeAsync(id: string): Promise<void>;
+    retryJob(id: string): Promise<void>;
+    retryJobs(opts?: {
+        state?: 'failed' | 'completed';
+        count?: number;
+        timestamp?: number;
+    }): Promise<void>;
+    clean(grace: number, limit: number, type?: string): string[];
+    cleanAsync(grace: number, limit: number, type?: string): Promise<string[]>;
+    promoteJobs(opts?: {
+        count?: number;
+    }): Promise<number>;
+    promoteJob(id: string): Promise<void>;
+    updateJobProgress(id: string, progress: number | object): Promise<void>;
+    getJobLogs(id: string, start?: number, end?: number, _asc?: boolean): Promise<{
+        logs: string[];
+        count: number;
+    }>;
+    addJobLog(id: string, logRow: string, _keepLogs?: number): Promise<number>;
+    clearJobLogs(id: string, keepLogs?: number): Promise<void>;
+    updateJobData(id: string, data: unknown): Promise<void>;
+    changeJobDelay(id: string, delay: number): Promise<void>;
+    changeJobPriority(id: string, opts: ChangePriorityOpts): Promise<void>;
+    extendJobLock(id: string, token: string, duration: number): Promise<number>;
+}