bunqueue-client 0.1.9 → 0.2.1

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

@@ -0,0 +1,147 @@
+/**
+ * Bunqueue Simple Mode — Type definitions
+ */
+import type { Job, JobOptions, Processor, ConnectionOptions, QueueOptions, WorkerOptions, RateLimiterOptions } from "../types.js";
+/** Middleware function: receives job and next(), returns result */
+export type BunqueueMiddleware<T = unknown, R = unknown> = (job: Job<T>, next: () => Promise<R>) => Promise<R>;
+/** Retry strategy for advanced backoff */
+export type RetryStrategy = 'fixed' | 'exponential' | 'jitter' | 'fibonacci' | 'custom';
+/** Advanced retry configuration */
+export interface RetryConfig {
+    /** Max attempts (default: 3) */
+    maxAttempts?: number;
+    /** Base delay in ms (default: 1000) */
+    delay?: number;
+    /** Strategy (default: exponential) */
+    strategy?: RetryStrategy;
+    /** Custom backoff function: attempt → delay in ms */
+    customBackoff?: (attempt: number, error: Error) => number;
+    /** Only retry if this returns true */
+    retryIf?: (error: Error, attempt: number) => boolean;
+}
+/** Circuit breaker configuration */
+export interface CircuitBreakerConfig {
+    /** Max consecutive failures before opening (default: 5) */
+    threshold?: number;
+    /** Time in ms before half-open retry (default: 30000) */
+    resetTimeout?: number;
+    /** Callback when circuit opens */
+    onOpen?: (failures: number) => void;
+    /** Callback when circuit closes */
+    onClose?: () => void;
+    /** Callback on half-open probe */
+    onHalfOpen?: () => void;
+}
+/** Circuit breaker state */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/** Event trigger rule */
+export interface TriggerRule<T = unknown> {
+    /** Job name that triggers this rule */
+    on: string;
+    /** Event type (default: completed) */
+    event?: 'completed' | 'failed';
+    /** Job name to create */
+    create: string;
+    /** Data builder from the triggering job */
+    data: (result: unknown, job: Job<T>) => T;
+    /** Optional job options */
+    opts?: JobOptions;
+    /** Optional condition */
+    condition?: (result: unknown, job: Job<T>) => boolean;
+}
+/** Priority aging configuration */
+export interface PriorityAgingConfig {
+    /** Check interval in ms (default: 60000) */
+    interval?: number;
+    /** Min age in ms before boost (default: 60000) */
+    minAge?: number;
+    /** Priority boost per interval (default: 1) */
+    boost?: number;
+    /** Max priority cap (default: 100) */
+    maxPriority?: number;
+    /** Max jobs to scan per tick (default: 100) */
+    maxScan?: number;
+}
+/** Batch processor function */
+export type BatchProcessor<T = unknown, R = unknown> = (jobs: Array<Job<T>>) => Promise<R[]>;
+/** Batch processing configuration */
+export interface BatchConfig<T = unknown, R = unknown> {
+    /** Batch size (default: 10) */
+    size: number;
+    /** Max wait in ms before flushing partial batch (default: 5000) */
+    timeout?: number;
+    /** Batch processor function */
+    processor: BatchProcessor<T, R>;
+}
+/** Job TTL configuration */
+export interface JobTtlConfig {
+    /** Default TTL in ms (0 = no TTL) */
+    defaultTtl?: number;
+    /** Per-job-name TTL overrides */
+    perName?: Record<string, number>;
+}
+/** Deduplication configuration for Simple Mode */
+export interface BunqueueDeduplicationConfig {
+    /** Default deduplication TTL in ms (default: 3600000 = 1 hour) */
+    ttl?: number;
+    /** Extend TTL when duplicate arrives (default: false) */
+    extend?: boolean;
+    /** Replace data when duplicate arrives in delayed state (default: false) */
+    replace?: boolean;
+}
+/** Debounce configuration for Simple Mode */
+export interface BunqueueDebounceConfig {
+    /** Default debounce TTL in ms */
+    ttl: number;
+}
+/** DLQ configuration for Simple Mode */
+export interface BunqueueDlqConfig {
+    /** Enable auto-retry from DLQ (default: false) */
+    autoRetry?: boolean;
+    /** Auto-retry interval in ms (default: 3600000 = 1 hour) */
+    autoRetryInterval?: number;
+    /** Max auto-retries (default: 3) */
+    maxAutoRetries?: number;
+    /** Max age before auto-purge in ms (default: 604800000 = 7 days) */
+    maxAge?: number | null;
+    /** Max entries per queue (default: 10000) */
+    maxEntries?: number;
+}
+/** Bunqueue options */
+export interface BunqueueOptions<T = unknown, R = unknown> {
+    processor?: Processor<T, R>;
+    routes?: Record<string, Processor<T, R>>;
+    batch?: BatchConfig<T, R>;
+    concurrency?: number;
+    connection?: ConnectionOptions;
+    embedded?: boolean;
+    dataPath?: string;
+    defaultJobOptions?: JobOptions;
+    autorun?: boolean;
+    heartbeatInterval?: number;
+    batchSize?: number;
+    pollTimeout?: number;
+    autoBatch?: QueueOptions['autoBatch'];
+    limiter?: WorkerOptions['limiter'];
+    removeOnComplete?: WorkerOptions['removeOnComplete'];
+    removeOnFail?: WorkerOptions['removeOnFail'];
+    retry?: RetryConfig;
+    circuitBreaker?: CircuitBreakerConfig;
+    ttl?: JobTtlConfig;
+    priorityAging?: PriorityAgingConfig;
+    /** Job deduplication defaults — applied via defaultJobOptions */
+    deduplication?: BunqueueDeduplicationConfig;
+    /** Job debouncing defaults — applied via defaultJobOptions */
+    debounce?: BunqueueDebounceConfig;
+    /** Rate limiting for the worker */
+    rateLimit?: RateLimiterOptions;
+    /** Dead letter queue auto-management */
+    dlq?: BunqueueDlqConfig;
+    /**
+     * Namespace prefix prepended to the queue name on the server. Lets multiple
+     * environments (e.g. `dev:`, `prod:`) share the same broker without their
+     * jobs, workers, cron schedulers, stats, or DLQ overlapping. Forwarded to
+     * both the internal Queue and Worker. See `QueueOptions.prefixKey`.
+     */
+    prefixKey?: string;
+}

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

@@ -0,0 +1,73 @@
+import type { SchedulerInfo } from "./queue/scheduler.js";
+import type { DlqConfig, DlqEntry, DlqFilter, DlqStats, Job, JobOptions } from "./types.js";
+import { BunqueueRuntime } from "./bunqueue/runtime.js";
+import type { CircuitState, TriggerRule } from "./bunqueue/types.js";
+export type { BatchConfig, BatchProcessor, BunqueueDebounceConfig, BunqueueDeduplicationConfig, BunqueueDlqConfig, BunqueueMiddleware, BunqueueOptions, CircuitBreakerConfig, JobTtlConfig, PriorityAgingConfig, RetryConfig, RetryStrategy, TriggerRule, } from "./bunqueue/types.js";
+/** Simplified all-in-one Queue and Worker façade. */
+export declare class Bunqueue<T = unknown, R = unknown> extends BunqueueRuntime<T, R> {
+    add(name: string, data: T, options?: JobOptions): Promise<Job<T>>;
+    addBulk(jobs: Array<{
+        name: string;
+        data: T;
+        opts?: JobOptions;
+    }>): Promise<Job<T>[]>;
+    getJob(id: string): Promise<Job<T> | null>;
+    getJobCounts(): import("./queue/operations/counts.js").JobCounts | Promise<import("./queue/operations/counts.js").JobCounts>;
+    getJobCountsAsync(): Promise<import("./queue/operations/counts.js").JobCounts>;
+    count(): number;
+    countAsync(): Promise<number>;
+    cron(id: string, pattern: string, data?: T, options?: {
+        timezone?: string;
+        limit?: number;
+        jobOpts?: JobOptions;
+    }): Promise<SchedulerInfo | null>;
+    every(id: string, intervalMs: number, data?: T, options?: {
+        limit?: number;
+        jobOpts?: JobOptions;
+    }): Promise<SchedulerInfo | null>;
+    removeCron(id: string): Promise<boolean>;
+    listCrons(): Promise<SchedulerInfo[]>;
+    cancel(jobId: string, gracePeriodMs?: number): void;
+    isCancelled(jobId: string): boolean;
+    getSignal(jobId: string): AbortSignal | null;
+    getCircuitState(): CircuitState;
+    resetCircuit(): void;
+    trigger(rule: TriggerRule<T>): this;
+    setDefaultTtl(ttlMs: number): void;
+    setNameTtl(name: string, ttlMs: number): void;
+    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>[]>;
+    getDlqStats(): DlqStats;
+    getDlqStatsAsync(): Promise<DlqStats>;
+    retryDlq(id?: string): number;
+    retryDlqAsync(id?: string): Promise<number>;
+    purgeDlq(): number;
+    purgeDlqAsync(): Promise<number>;
+    setGlobalRateLimit(max: number, duration?: number): void;
+    setGlobalRateLimitAsync(max: number, duration?: number): Promise<void>;
+    removeGlobalRateLimit(): void;
+    removeGlobalRateLimitAsync(): Promise<void>;
+    on(event: 'ready' | 'drained' | 'closed', listener: () => void): this;
+    on(event: 'active', listener: (job: Job<T>) => void): this;
+    on(event: 'completed', listener: (job: Job<T>, result: R) => void): this;
+    on(event: 'failed', listener: (job: Job<T>, error: Error) => void): this;
+    on(event: 'progress', listener: (job: Job<T> | null, progress: number) => void): this;
+    on(event: 'stalled', listener: (jobId: string, reason: string) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'ready' | 'drained' | 'closed', listener: () => void): this;
+    once(event: 'completed', listener: (job: Job<T>, result: R) => void): this;
+    once(event: 'failed', listener: (job: Job<T>, error: Error) => void): this;
+    off(event: any, listener: (...args: any[]) => void): this;
+    pause(): void;
+    resume(): void;
+    pauseAsync(): Promise<void>;
+    resumeAsync(): Promise<void>;
+    close(force?: boolean): Promise<void>;
+    isRunning(): boolean;
+    isPaused(): boolean;
+    isClosed(): boolean;
+}

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

@@ -0,0 +1,5 @@
+import type { DlqEntry as InternalDlqEntry } from "../domain/types/dlq.js";
+import type { DlqEntry, Job } from "./types.js";
+import type { CreatePublicJobOptions, PublicJobMethodContext } from "./jobConversionTypes.js";
+/** Convert authoritative DLQ metadata while retaining live public Job methods. */
+export declare function convertDlqEntry<T>(entry: InternalDlqEntry, methods: PublicJobMethodContext, buildJob: (options: CreatePublicJobOptions) => Job<T>): DlqEntry<T>;

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

@@ -0,0 +1,24 @@
+/**
+ * BullMQ-compatible error classes
+ *
+ * UnrecoverableError - Skip all retries, go directly to failed/DLQ
+ * DelayedError - Move job back to delayed state instead of failing
+ */
+/**
+ * Throw this error in a processor to skip all retries.
+ * The job will go directly to failed/DLQ regardless of the attempts setting.
+ */
+export declare class UnrecoverableError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Throw this error in a processor to move the job back to delayed state.
+ * The job will not count as failed — it will be re-delayed for later processing.
+ */
+export declare class DelayedError extends Error {
+    constructor(message?: string);
+}
+/** Marker thrown after a processor manually rate-limits and requeues its group. */
+export declare class RateLimitError extends Error {
+    constructor(message?: string);
+}

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

@@ -0,0 +1,85 @@
+/**
+ * QueueEvents - BullMQ-style event listener
+ */
+import { EventEmitter } from 'events';
+import { type JobEvent } from "../domain/types/queue.js";
+import type { ActiveEvent, CompletedEvent, DelayedEvent, DrainedEvent, DuplicatedEvent, FailedEvent, ProgressEvent, QueueEventsOptions, RemovedEvent, RetriedEvent, StalledEvent, WaitingChildrenEvent, WaitingEvent } from "./types/events.js";
+export type { ActiveEvent, CompletedEvent, DelayedEvent, DrainedEvent, DuplicatedEvent, FailedEvent, ProgressEvent, QueueEventsOptions, RemovedEvent, RetriedEvent, StalledEvent, WaitingChildrenEvent, WaitingEvent, } from "./types/events.js";
+/**
+ * QueueEvents class for listening to queue events
+ * Provides a way to listen to events without processing jobs
+ *
+ * BullMQ v5 compatible events:
+ * - waiting: job added to queue
+ * - active: job started processing
+ * - completed: job completed successfully
+ * - failed: job failed
+ * - progress: job progress updated
+ * - stalled: job stalled (no heartbeat)
+ * - removed: job removed from queue
+ * - delayed: job moved to delayed state
+ * - duplicated: duplicate job detected
+ * - retried: job retried
+ * - waiting-children: job waiting for children to complete
+ * - drained: queue has no more waiting jobs
+ * - error: error occurred
+ *
+ * @template R - Type of the job result (for 'completed' event)
+ * @template P - Type of the progress data (for 'progress' event)
+ */
+export declare class QueueEvents<R = unknown, P = unknown> extends EventEmitter {
+    readonly name: string;
+    private running;
+    private unsubscribe;
+    private subscription;
+    private ready;
+    private readonly queueKey;
+    private readonly options;
+    constructor(name: string, options?: QueueEventsOptions);
+    on(event: 'waiting', listener: (data: WaitingEvent) => void): this;
+    on(event: 'active', listener: (data: ActiveEvent) => void): this;
+    on(event: 'completed', listener: (data: CompletedEvent<R>) => void): this;
+    on(event: 'failed', listener: (data: FailedEvent) => void): this;
+    on(event: 'progress', listener: (data: ProgressEvent<P>) => void): this;
+    on(event: 'stalled', listener: (data: StalledEvent) => void): this;
+    on(event: 'removed', listener: (data: RemovedEvent) => void): this;
+    on(event: 'delayed', listener: (data: DelayedEvent) => void): this;
+    on(event: 'duplicated', listener: (data: DuplicatedEvent) => void): this;
+    on(event: 'retried', listener: (data: RetriedEvent) => void): this;
+    on(event: 'waiting-children', listener: (data: WaitingChildrenEvent) => void): this;
+    on(event: 'drained', listener: (data: DrainedEvent) => void): this;
+    on(event: 'paused' | 'resumed', listener: (data: Record<string, never>) => void): this;
+    on(event: 'error', listener: (error: Error, event?: JobEvent) => void): this;
+    once(event: 'waiting', listener: (data: WaitingEvent) => void): this;
+    once(event: 'active', listener: (data: ActiveEvent) => void): this;
+    once(event: 'completed', listener: (data: CompletedEvent<R>) => void): this;
+    once(event: 'failed', listener: (data: FailedEvent) => void): this;
+    once(event: 'progress', listener: (data: ProgressEvent<P>) => void): this;
+    once(event: 'stalled', listener: (data: StalledEvent) => void): this;
+    once(event: 'removed', listener: (data: RemovedEvent) => void): this;
+    once(event: 'delayed', listener: (data: DelayedEvent) => void): this;
+    once(event: 'duplicated', listener: (data: DuplicatedEvent) => void): this;
+    once(event: 'retried', listener: (data: RetriedEvent) => void): this;
+    once(event: 'waiting-children', listener: (data: WaitingChildrenEvent) => void): this;
+    once(event: 'drained', listener: (data: DrainedEvent) => void): this;
+    once(event: 'paused' | 'resumed', listener: (data: Record<string, never>) => void): this;
+    once(event: 'error', listener: (error: Error, event?: JobEvent) => void): this;
+    private dispatchEvent;
+    private start;
+    private emitTransportError;
+    /** Emit an error event (can be called externally) */
+    emitError(error: Error): void;
+    /**
+     * Wait until the QueueEvents is ready to receive events.
+     * In embedded mode, this resolves immediately.
+     * BullMQ v5 compatible.
+     */
+    waitUntilReady(): Promise<void>;
+    /**
+     * Disconnect from the event stream.
+     * Alias for close() for BullMQ v5 compatibility.
+     */
+    disconnect(): Promise<void>;
+    /** Close the event listener and remove all listeners */
+    close(): void;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * FlowProducer - Job chaining and pipelines
+ * BullMQ v5 compatible
+ */
+import { EventEmitter } from 'events';
+import type { FlowProducerOptions, FlowStep, FlowResult, FlowJob, JobNode, GetFlowOpts, FlowOpts } from "./flowTypes.js";
+import { type RuntimeResult } from "./flowResults.js";
+export type { FlowProducerOptions, FlowStep, FlowResult, FlowJob, JobNode, GetFlowOpts, FlowOpts, } from "./flowTypes.js";
+/**
+ * FlowProducer creates job flows with automatic dependencies.
+ *
+ * @example
+ * ```typescript
+ * const flow = new FlowProducer();
+ *
+ * // Simple chain: A → B → C
+ * const { jobIds } = await flow.addChain([
+ *   { name: 'fetch', queueName: 'pipeline', data: { url: '...' } },
+ *   { name: 'process', queueName: 'pipeline', data: {} },
+ *   { name: 'store', queueName: 'pipeline', data: {} },
+ * ]);
+ *
+ * // Parallel then merge
+ * const result = await flow.addBulkThen(
+ *   [
+ *     { name: 'task1', queueName: 'parallel', data: { id: 1 } },
+ *     { name: 'task2', queueName: 'parallel', data: { id: 2 } },
+ *   ],
+ *   { name: 'merge', queueName: 'final', data: {} }
+ * );
+ * ```
+ */
+export declare class FlowProducer extends EventEmitter {
+    closing: Promise<void> | null;
+    private readonly embedded;
+    private readonly tcp;
+    private readonly useSharedPool;
+    constructor(opts?: FlowProducerOptions);
+    /** Get push context for helper functions */
+    private get pushCtx();
+    /** Close the connection pool (only if using dedicated pool) */
+    close(): Promise<void>;
+    /** Disconnect from the server (BullMQ v5 compatible). Alias for close(). */
+    disconnect(): Promise<void>;
+    /** Wait until the FlowProducer is ready (BullMQ v5 compatible). */
+    waitUntilReady(): Promise<void>;
+    /** Add a flow (BullMQ v5 compatible). Children are processed BEFORE their parent. */
+    add<T = unknown>(flow: FlowJob<T>, opts?: FlowOpts): Promise<JobNode<T>>;
+    /** Add multiple flows (BullMQ v5 compatible). */
+    addBulk<T = unknown>(flows: FlowJob<T>[]): Promise<JobNode<T>[]>;
+    /** Get a flow tree starting from a job (BullMQ v5 compatible). */
+    getFlow<T = unknown>(opts: GetFlowOpts): Promise<JobNode<T> | null>;
+    /** Add a chain of jobs. Jobs execute sequentially: step[0] → step[1] → ... */
+    addChain<T = unknown>(steps: FlowStep<T>[]): Promise<FlowResult>;
+    /** Add parallel jobs that converge to a final job. */
+    addBulkThen<T = unknown>(parallel: FlowStep<T>[], final: FlowStep<T>): Promise<{
+        parallelIds: string[];
+        finalId: string;
+    }>;
+    /** Add a tree of jobs where children depend on parent. */
+    addTree<T = unknown>(root: FlowStep<T>): Promise<FlowResult>;
+    /** Get the result of a completed parent job in embedded or TCP mode. */
+    getParentResult<R = unknown>(parentId: string): RuntimeResult<R | undefined>;
+    /** Get results from multiple parent jobs in input order in either runtime. */
+    getParentResults<R = unknown>(parentIds: string[]): RuntimeResult<Map<string, R>>;
+    /** Build callbacks that wire flow job methods to actual management operations */
+    private buildCallbacks;
+    private buildPlannedNode;
+    private indexSnapshots;
+}

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

@@ -0,0 +1,9 @@
+import type { Job as DomainJob } from "../domain/types/job.js";
+import type { AtomicFlowBatchInput } from "../domain/types/flow.js";
+import type { TcpConnectionPool } from "./tcpPool.js";
+export interface AtomicFlowContext {
+    readonly embedded: boolean;
+    readonly tcp: TcpConnectionPool | null;
+}
+/** Execute the same one-command atomic primitive in embedded and TCP modes. */
+export declare function commitFlow(ctx: AtomicFlowContext, batch: AtomicFlowBatchInput): Promise<DomainJob[]>;

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

@@ -0,0 +1,28 @@
+import type { ChangePriorityOpts } from "./types.js";
+import { type FlowJobRuntime } from "./flowJobTypes.js";
+/** Core state, mutation, and dependency methods exposed by a FlowProducer Job. */
+export declare function buildFlowJobCoreMethods(runtime: FlowJobRuntime): {
+    updateProgress: (progress: number | object) => Promise<void>;
+    log: (message: string) => Promise<void>;
+    getState: () => Promise<import("./types.js").JobStateType>;
+    remove: () => Promise<void>;
+    retry: () => Promise<void>;
+    getChildrenValues: <R = unknown>() => Promise<Record<string, R>>;
+    isWaiting: () => Promise<boolean>;
+    isActive: () => Promise<boolean>;
+    isDelayed: () => Promise<boolean>;
+    isCompleted: () => Promise<boolean>;
+    isFailed: () => Promise<boolean>;
+    isWaitingChildren: () => Promise<boolean>;
+    updateData: (data: unknown) => Promise<void>;
+    promote: () => Promise<void>;
+    changeDelay: (delay: number) => Promise<void>;
+    changePriority: (opts: ChangePriorityOpts) => Promise<void>;
+    extendLock: (token: string, duration: number) => Promise<number>;
+    clearLogs: (keepLogs?: number) => Promise<void>;
+    getDependencies: () => Promise<import("./flowJobDependencies.js").FlowDependencies>;
+    getDependenciesCount: () => Promise<{
+        processed: number;
+        unprocessed: number;
+    }>;
+};

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

@@ -0,0 +1,7 @@
+import type { TcpConnectionPool } from "./tcpPool.js";
+export interface FlowDependencies {
+    processed: Record<string, unknown>;
+    unprocessed: string[];
+}
+/** Resolve dependency keys using the actual queue of every child. */
+export declare function getFlowDependencies(id: string, queueName: string, embedded: boolean, tcp: TcpConnectionPool | null): Promise<FlowDependencies>;

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

@@ -0,0 +1,24 @@
+/**
+ * Flow Job Factory
+ * Creates BullMQ-compatible Job objects backed by FlowProducer transports.
+ */
+import type { Job as DomainJob } from "../domain/types/job.js";
+import type { FlowJobCallbacks } from "./flowJobTypes.js";
+import type { Job } from "./types.js";
+export type { FlowJobCallbacks } from "./flowJobTypes.js";
+/** Decode historical flow envelopes for callers that only have the data field. */
+export declare function extractUserDataFromInternal(data: Record<string, unknown>): unknown;
+/** Resolve a stored flow node while preserving a modern user `data.name` field. */
+export declare function extractFlowJobPayload(job: {
+    readonly name?: unknown;
+    readonly data?: unknown;
+}): {
+    name: string;
+    data: unknown;
+};
+interface FlowJobObjectOptions {
+    callbacks?: FlowJobCallbacks;
+    snapshot?: DomainJob;
+}
+/** Create a Job object for a newly committed or fetched flow node. */
+export declare function createFlowJobObject<T>(id: string, name: string, data: T, queueName: string, factoryOptions?: FlowJobObjectOptions): Job<T>;

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

@@ -0,0 +1,16 @@
+import { type FlowJobRuntime } from "./flowJobTypes.js";
+/** Lifecycle and failure-inspection methods exposed by a FlowProducer Job. */
+export declare function buildFlowJobMoveMethods(runtime: FlowJobRuntime): {
+    moveToCompleted: (returnValue: unknown, token?: string) => Promise<null>;
+    moveToFailed: (error: Error, token?: string) => Promise<void>;
+    moveToWait: (token?: string) => Promise<boolean>;
+    moveToDelayed: (timestamp: number, token?: string) => Promise<undefined>;
+    moveToWaitingChildren: (token?: string) => Promise<boolean>;
+    waitUntilFinished: (_queueEvents: unknown, ttl?: number) => Promise<unknown>;
+    discard: () => void;
+    getFailedChildrenValues: () => Promise<Record<string, string>>;
+    getIgnoredChildrenFailures: () => Promise<Record<string, string>>;
+    removeChildDependency: () => Promise<boolean>;
+    removeDeduplicationKey: () => Promise<boolean>;
+    removeUnprocessedChildren: () => Promise<undefined>;
+};

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

@@ -0,0 +1,29 @@
+import type { JobStateType } from "./types.js";
+import type { TcpConnectionPool } from "./tcpPool.js";
+/** Callbacks used to wire FlowProducer Job mutations to the selected transport. */
+export interface FlowJobCallbacks {
+    embedded?: boolean;
+    tcp?: TcpConnectionPool | null;
+    updateData?: (id: string, data: unknown) => Promise<void>;
+    updateProgress?: (id: string, progress: number | object) => Promise<void>;
+    log?: (id: string, message: string) => Promise<void>;
+    promote?: (id: string) => Promise<void>;
+    remove?: (id: string) => Promise<void>;
+    changePriority?: (id: string, opts: {
+        priority: number;
+        lifo?: boolean;
+    }) => Promise<void>;
+    changeDelay?: (id: string, delay: number) => Promise<void>;
+    clearLogs?: (id: string, keepLogs?: number) => Promise<void>;
+    retry?: (id: string) => Promise<void>;
+    getState?: (id: string) => Promise<string>;
+}
+export interface FlowJobRuntime {
+    id: string;
+    queueName: string;
+    callbacks?: FlowJobCallbacks;
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+    getState: () => Promise<JobStateType>;
+}
+export declare function assertFlowTcpOk(response: Record<string, unknown>, operation: string): void;

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

@@ -0,0 +1,16 @@
+import { type JobId } from "../domain/types/job.js";
+import type { AtomicFlowBatchInput } from "../domain/types/flow.js";
+import type { FlowStep } from "./flowTypes.js";
+export declare function planChain<T>(steps: FlowStep<T>[]): {
+    batch: AtomicFlowBatchInput;
+    ids: JobId[];
+};
+export declare function planBulkThen<T>(parallel: FlowStep<T>[], final: FlowStep<T>): {
+    batch: AtomicFlowBatchInput;
+    parallelIds: JobId[];
+    finalId: JobId;
+};
+export declare function planTree<T>(root: FlowStep<T>): {
+    batch: AtomicFlowBatchInput;
+    ids: JobId[];
+};

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

@@ -0,0 +1,10 @@
+import type { JobInput, JobId } from "../domain/types/job.js";
+import type { JobOptions } from "./types.js";
+/** Options intentionally unsupported by BullMQ-compatible atomic flows. */
+export declare function assertAtomicFlowOptions(opts: JobOptions): void;
+/** Convert public JobOptions into the domain input used by the atomic broker command. */
+export declare function flowJobInput(name: string, data: unknown, opts: JobOptions, links?: {
+    parentId?: JobId;
+    dependsOn?: JobId[];
+    childrenIds?: JobId[];
+}): JobInput;

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

@@ -0,0 +1,16 @@
+import { type JobId } from "../domain/types/job.js";
+import type { AtomicFlowBatchInput } from "../domain/types/flow.js";
+import type { FlowJob, FlowOpts } from "./flowTypes.js";
+export interface PlannedFlowNode<T> {
+    readonly id: JobId;
+    readonly name: string;
+    readonly queueName: string;
+    readonly data: T | undefined;
+    readonly children?: PlannedFlowNode<T>[];
+}
+export interface FlowPlan<T> {
+    readonly batch: AtomicFlowBatchInput;
+    readonly roots: PlannedFlowNode<T>[];
+}
+/** Compile one or more trees into a fully-resolved graph before contacting the broker. */
+export declare function planFlows<T>(flows: FlowJob<T>[], options?: FlowOpts): FlowPlan<T>;

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

@@ -0,0 +1,27 @@
+/**
+ * Flow Push Operations
+ * Handles job push logic for FlowProducer
+ */
+import type { TcpConnectionPool } from "./tcpPool.js";
+import type { JobOptions } from "./types.js";
+export interface PushContext {
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+}
+/** Push a job via embedded manager or TCP */
+export declare function pushJob(ctx: PushContext, queueName: string, data: unknown, opts?: JobOptions, dependsOn?: string[]): Promise<string>;
+export interface PushWithParentOpts {
+    queueName: string;
+    name?: string;
+    data: unknown;
+    opts: JobOptions;
+    parentRef: {
+        id: string;
+        queue: string;
+    } | null;
+    childIds: string[];
+}
+/** Push a job with parent/children tracking */
+export declare function pushJobWithParent(ctx: PushContext, params: PushWithParentOpts): Promise<string>;
+/** Cleanup jobs that were created before a failure occurred */
+export declare function cleanupJobs(ctx: PushContext, jobIds: string[]): Promise<void>;

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

@@ -0,0 +1,10 @@
+import type { FlowJobCallbacks } from "./flowJobTypes.js";
+import type { GetFlowOpts, JobNode } from "./flowTypes.js";
+import type { TcpConnectionPool } from "./tcpPool.js";
+export interface FlowReaderContext {
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+    buildCallbacks: (queueName: string) => FlowJobCallbacks;
+}
+/** Read a flow without silently truncating transport or topology errors. */
+export declare function readFlow<T>(context: FlowReaderContext, opts: GetFlowOpts): Promise<JobNode<T> | null>;

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

@@ -0,0 +1,11 @@
+import type { TcpConnectionPool } from "./tcpPool.js";
+interface FlowResultContext {
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+}
+export type RuntimeResult<T> = T | Promise<T>;
+/** Keep the embedded call synchronous while providing the same result over TCP. */
+export declare function getParentResult<R>(ctx: FlowResultContext, parentId: string): RuntimeResult<R | undefined>;
+/** Resolve parent results in input order and preserve falsy completed values. */
+export declare function getParentResults<R>(ctx: FlowResultContext, parentIds: string[]): RuntimeResult<Map<string, R>>;
+export {};