bunqueue-client 0.1.9 → 0.2.1

package/dist/types/src/domain/types/dlq.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Dead Letter Queue Types
+ * Enhanced DLQ with metadata, auto-retry, and lifecycle management
+ */
+import type { Job } from "./job.js";
+/** Failure reason categories */
+export declare const enum FailureReason {
+    /** Job explicitly failed via fail() call */
+    ExplicitFail = "explicit_fail",
+    /** Job exceeded max attempts */
+    MaxAttemptsExceeded = "max_attempts_exceeded",
+    /** Job timed out during processing */
+    Timeout = "timeout",
+    /** Job stalled (no heartbeat) */
+    Stalled = "stalled",
+    /** Job TTL expired */
+    TtlExpired = "ttl_expired",
+    /** Worker crashed/disconnected */
+    WorkerLost = "worker_lost",
+    /** Unknown/other reason */
+    Unknown = "unknown"
+}
+/** Single attempt record */
+export interface AttemptRecord {
+    /** Attempt number (1-based) */
+    readonly attempt: number;
+    /** When this attempt started */
+    readonly startedAt: number;
+    /** When this attempt failed */
+    readonly failedAt: number;
+    /** Failure reason for this attempt */
+    readonly reason: FailureReason;
+    /** Error message if any */
+    readonly error: string | null;
+    /** Duration of this attempt in ms */
+    readonly duration: number;
+}
+/** Internal lifecycle state carried while a DLQ auto-retry is live. */
+export interface DlqRetryState {
+    readonly enteredAt: number | null;
+    readonly expiresAt: number | null;
+    readonly attempts: AttemptRecord[];
+    readonly retryCount: number;
+    readonly lastRetryAt: number | null;
+    readonly nextRetryAt: number | null;
+}
+/** Read internal DLQ state without exposing it on the public Job wire shape. */
+export declare function getDlqRetryState(job: Job): DlqRetryState | null;
+/** Restore internal DLQ state from SQLite as a non-enumerable Job property. */
+export declare function setDlqRetryState(job: Job, state: DlqRetryState | null): void;
+/** Retain a non-terminal failed attempt so a later DLQ entry has full history. */
+export declare function recordJobFailureAttempt(job: Job, reason: FailureReason, error: string | null, failedAt?: number): void;
+/** Carry a dispatched DLQ entry through its live auto-retry execution. */
+export declare function retainDlqRetryState(job: Job, entry: DlqEntry): void;
+/** DLQ Entry with full metadata */
+export interface DlqEntry {
+    /** Original job */
+    readonly job: Job;
+    /** When first moved to DLQ */
+    readonly enteredAt: number;
+    /** Last failure reason */
+    readonly reason: FailureReason;
+    /** Last error message */
+    readonly error: string | null;
+    /** Full attempt history */
+    readonly attempts: AttemptRecord[];
+    /** Number of times retried from DLQ */
+    retryCount: number;
+    /** Last retry attempt from DLQ */
+    lastRetryAt: number | null;
+    /** Next scheduled auto-retry (null = no auto-retry) */
+    nextRetryAt: number | null;
+    /** Expires at (for auto-purge) */
+    readonly expiresAt: number | null;
+}
+/** DLQ configuration per queue */
+export interface DlqConfig {
+    /** Enable auto-retry from DLQ */
+    autoRetry: boolean;
+    /** Auto-retry interval in ms (default: 1 hour) */
+    autoRetryInterval: number;
+    /** Max auto-retries before giving up (default: 3) */
+    maxAutoRetries: number;
+    /** Max age in ms before auto-purge (default: 7 days, null = never) */
+    maxAge: number | null;
+    /** Max entries per queue (default: 10000) */
+    maxEntries: number;
+}
+/** Default DLQ configuration */
+export declare const DEFAULT_DLQ_CONFIG: DlqConfig;
+/** Create a DLQ entry from a failed job */
+export declare function createDlqEntry(job: Job, reason: FailureReason, error: string | null, config?: DlqConfig, now?: number): DlqEntry;
+/** Add attempt record to existing DLQ entry */
+export declare function addAttemptRecord(entry: DlqEntry, reason: FailureReason, error: string | null): void;
+/** Check if DLQ entry is expired */
+export declare function isDlqEntryExpired(entry: DlqEntry, now?: number): boolean;
+/** Check if DLQ entry can be auto-retried */
+export declare function canAutoRetry(entry: DlqEntry, config: DlqConfig, now?: number): boolean;
+/** Schedule next auto-retry */
+export declare function scheduleNextRetry(entry: DlqEntry, config: DlqConfig): void;
+/** DLQ filter options */
+export interface DlqFilter {
+    /** Filter by failure reason */
+    reason?: FailureReason;
+    /** Filter by queue */
+    queue?: string;
+    /** Only entries older than this timestamp */
+    olderThan?: number;
+    /** Only entries newer than this timestamp */
+    newerThan?: number;
+    /** Only entries that can be retried */
+    retriable?: boolean;
+    /** Only entries that are expired */
+    expired?: boolean;
+    /** Limit results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/** DLQ statistics */
+export interface DlqStats {
+    /** Total entries */
+    total: number;
+    /** Entries by reason */
+    byReason: Record<FailureReason, number>;
+    /** Entries by queue */
+    byQueue: Record<string, number>;
+    /** Entries awaiting auto-retry */
+    pendingRetry: number;
+    /** Expired entries (awaiting cleanup) */
+    expired: number;
+    /** Oldest entry timestamp */
+    oldestEntry: number | null;
+    /** Newest entry timestamp */
+    newestEntry: number | null;
+}

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

@@ -0,0 +1,25 @@
+import type { Job, JobId, JobInput } from "./job.js";
+/** One fully-resolved job in an atomic flow commit. */
+export interface AtomicFlowJobInput {
+    readonly id: JobId;
+    readonly queue: string;
+    readonly input: JobInput;
+}
+/** Wire-neutral batch consumed by embedded and TCP FlowProducer paths. */
+export interface AtomicFlowBatchInput {
+    readonly jobs: AtomicFlowJobInput[];
+}
+/** Authoritative snapshots returned after a successful flow commit. */
+export interface AtomicFlowBatchResult {
+    readonly jobs: Job[];
+}
+export type FlowFailureMode = 'fail' | 'remove' | 'ignore' | 'continue';
+/** Durable recovery record for a terminal child failure. */
+export interface FlowFailureRecord {
+    readonly parentId: JobId;
+    readonly childId: JobId;
+    readonly childQueue: string;
+    readonly mode: FlowFailureMode;
+    readonly error: string;
+    readonly createdAt: number;
+}

package/dist/types/src/domain/types/group.d.ts

@@ -0,0 +1,26 @@
+export interface GroupRateLimit {
+    readonly max: number;
+    readonly duration: number;
+}
+/** Worker-side defaults enforced authoritatively by the broker. */
+export interface GroupPullOptions {
+    readonly concurrency?: number;
+    readonly limit?: GroupRateLimit;
+    /** Internal batch affinity: undefined means any group; null means ungrouped only. */
+    readonly affinity?: string | null;
+}
+export interface GroupRateLimitOverride extends GroupRateLimit {
+}
+export declare const MAX_GROUP_PRIORITY = 2097151;
+/** Validate the canonical string form shared by every broker and persistence backend. */
+export declare function validateGroupId(value: unknown, required?: boolean): string | null;
+export declare function assertGroupId(value: unknown): asserts value is string;
+export declare function assertOptionalGroupId(value: unknown): asserts value is string | undefined;
+export declare function validateGroupPriority(value: unknown): string | null;
+export declare function assertGroupPriority(value: unknown): void;
+/** Normalize BullMQ-compatible numeric IDs without accepting arbitrary coercion. */
+export declare function normalizeGroupId(value: unknown): string;
+export declare function validatePositiveSafeInteger(value: unknown, name: string): string | null;
+export declare function assertPositiveSafeInteger(value: unknown, name: string): asserts value is number;
+export declare function validateGroupPullOptions(options: unknown): string | null;
+export declare function assertGroupPullOptions(options: unknown): asserts options is GroupPullOptions;

package/dist/types/src/domain/types/job.d.ts

@@ -0,0 +1,8 @@
+/** Stable import surface for job types and domain operations. */
+export * from "./jobs/model.js";
+export * from "../job/constants.js";
+export * from "../job/create.js";
+export * from "../job/ids.js";
+export * from "../job/locks.js";
+export * from "../job/payload.js";
+export * from "../job/state.js";

package/dist/types/src/domain/types/jobs/model.d.ts

@@ -0,0 +1,150 @@
+export type JobId = string & {
+    readonly __brand: 'JobId';
+};
+export type LockToken = string & {
+    readonly __brand: 'LockToken';
+};
+export declare const enum JobState {
+    Waiting = "waiting",
+    Prioritized = "prioritized",
+    Delayed = "delayed",
+    Active = "active",
+    Completed = "completed",
+    Failed = "failed"
+}
+export interface RepeatConfig {
+    readonly every?: number;
+    readonly limit?: number;
+    readonly pattern?: string;
+    count: number;
+    readonly startDate?: number;
+    readonly endDate?: number;
+    readonly tz?: string;
+    readonly immediately?: boolean;
+    prevMillis?: number;
+    readonly offset?: number;
+    readonly jobId?: string;
+}
+export interface BackoffConfig {
+    readonly type: 'fixed' | 'exponential';
+    readonly delay: number;
+    readonly maxDelay?: number;
+}
+export interface JobTimelineEntry {
+    readonly state: string;
+    readonly timestamp: number;
+    readonly worker?: string;
+    readonly error?: string;
+    readonly attempt?: number;
+}
+export interface Job {
+    readonly id: JobId;
+    readonly queue: string;
+    readonly name: string;
+    readonly data: unknown;
+    readonly priority: number;
+    readonly createdAt: number;
+    readonly lifo: boolean;
+    runAt: number;
+    startedAt: number | null;
+    completedAt: number | null;
+    attempts: number;
+    readonly maxAttempts: number;
+    readonly backoff: number;
+    readonly backoffConfig: BackoffConfig | null;
+    readonly ttl: number | null;
+    readonly timeout: number | null;
+    readonly uniqueKey: string | null;
+    readonly customId: string | null;
+    readonly dependsOn: JobId[];
+    readonly parentId: JobId | null;
+    childrenIds: JobId[];
+    childrenCompleted: number;
+    readonly tags: string[];
+    readonly groupId: string | null;
+    progress: number;
+    progressMessage: string | null;
+    stacktrace: string[] | null;
+    readonly removeOnComplete: boolean;
+    readonly removeOnFail: boolean;
+    readonly repeat: RepeatConfig | null;
+    lastHeartbeat: number;
+    readonly stallTimeout: number | null;
+    stallCount: number;
+    readonly stackTraceLimit: number;
+    readonly keepLogs: number | null;
+    readonly sizeLimit: number | null;
+    readonly failParentOnFailure: boolean;
+    readonly removeDependencyOnFailure: boolean;
+    readonly continueParentOnFailure: boolean;
+    readonly ignoreDependencyOnFailure: boolean;
+    readonly deduplicationTtl: number | null;
+    readonly deduplicationExtend: boolean;
+    readonly deduplicationReplace: boolean;
+    readonly debounceId: string | null;
+    readonly debounceTtl: number | null;
+    /** Whether SQLite admission bypasses its write buffer; PostgreSQL is always transactional. */
+    readonly durable?: boolean;
+    timeline: JobTimelineEntry[];
+}
+export interface JobInput {
+    name?: string;
+    data: unknown;
+    priority?: number;
+    delay?: number;
+    maxAttempts?: number;
+    backoff?: number | BackoffConfig;
+    ttl?: number;
+    timeout?: number;
+    uniqueKey?: string;
+    customId?: string;
+    dependsOn?: JobId[];
+    childrenIds?: JobId[];
+    parentId?: JobId;
+    tags?: string[];
+    groupId?: string;
+    groupMaxSize?: number;
+    lifo?: boolean;
+    removeOnComplete?: boolean;
+    removeOnFail?: boolean;
+    stallTimeout?: number;
+    repeat?: {
+        every?: number;
+        limit?: number;
+        pattern?: string;
+        count?: number;
+        startDate?: number;
+        endDate?: number;
+        tz?: string;
+        immediately?: boolean;
+        prevMillis?: number;
+        offset?: number;
+        jobId?: string;
+    };
+    dedup?: {
+        ttl?: number;
+        extend?: boolean;
+        replace?: boolean;
+    };
+    durable?: boolean;
+    stackTraceLimit?: number;
+    keepLogs?: number;
+    sizeLimit?: number;
+    failParentOnFailure?: boolean;
+    removeDependencyOnFailure?: boolean;
+    continueParentOnFailure?: boolean;
+    ignoreDependencyOnFailure?: boolean;
+    debounceId?: string;
+    debounceTtl?: number;
+    timestamp?: number;
+}
+export interface JobLock {
+    readonly jobId: JobId;
+    readonly token: LockToken;
+    readonly owner: string;
+    readonly createdAt: number;
+    expiresAt: number;
+    lastRenewalAt: number;
+    renewalCount: number;
+    readonly ttl: number;
+}

package/dist/types/src/domain/types/metrics.d.ts

@@ -0,0 +1,16 @@
+export type QueueMetricType = 'completed' | 'failed';
+export interface QueueMetricsMeta {
+    /** Cumulative number of terminal jobs since the queue metrics were created. */
+    readonly count: number;
+    /** Timestamp of the most recently recorded terminal job. */
+    readonly prevTS: number;
+    /** Count in the most recently updated one-minute bucket. */
+    readonly prevCount: number;
+}
+export interface QueueMetrics {
+    readonly meta: QueueMetricsMeta;
+    /** One-minute job-count buckets, newest first. */
+    readonly data: number[];
+    /** Total number of available buckets before start/end pagination. */
+    readonly count: number;
+}

package/dist/types/src/domain/types/priorityQueue.d.ts

@@ -0,0 +1,13 @@
+import type { Job, JobId } from "./job.js";
+export interface HeapEntry {
+    jobId: JobId;
+    priority: number;
+    runAt: number;
+    lifo: boolean;
+    generation: bigint;
+    groupFifoOrder?: bigint;
+}
+export interface IndexedJob {
+    job: Job;
+    generation: bigint;
+}

package/dist/types/src/domain/types/protocol.d.ts

@@ -0,0 +1,5 @@
+/** Current TCP wire protocol revision advertised by the server and Bun client. */
+export declare const PROTOCOL_VERSION: 3;
+/** Capabilities implemented by protocol revision 3. */
+export declare const PROTOCOL_CAPABILITIES: readonly ["pipelining", "separate-job-name"];
+export type ProtocolCapability = (typeof PROTOCOL_CAPABILITIES)[number];

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

@@ -0,0 +1,110 @@
+/**
+ * Queue domain types
+ * Queue state and configuration
+ */
+/** Queue state configuration */
+export interface QueueState {
+    readonly name: string;
+    paused: boolean;
+    rateLimit: number | null;
+    /** Rate-limit window in ms (null = default 1000ms bucket). */
+    rateLimitDuration: number | null;
+    /** Epoch ms after which the rate limit self-expires (null = permanent). */
+    rateLimitExpiresAt: number | null;
+    concurrencyLimit: number | null;
+    activeCount: number;
+}
+/** Create default queue state */
+export declare function createQueueState(name: string): QueueState;
+/** Rate limiter using token bucket algorithm */
+export declare class RateLimiter {
+    private readonly capacity;
+    private readonly refillRate;
+    private tokens;
+    private lastRefill;
+    constructor(capacity: number, refillRate?: number);
+    /** Try to acquire a token */
+    tryAcquire(): boolean;
+    /** Refill tokens based on elapsed time */
+    private refill;
+    /** Get current token count */
+    getTokens(): number;
+    /**
+     * Milliseconds until the bucket can admit another job. When `maxJobs` is
+     * provided, report 0 until at least that many tokens have been consumed.
+     */
+    getTtl(maxJobs?: number): number;
+}
+/** Concurrency limiter */
+export declare class ConcurrencyLimiter {
+    private limit;
+    private active;
+    constructor(limit: number);
+    /** Try to acquire a slot */
+    tryAcquire(): boolean;
+    /** Release a slot */
+    release(): void;
+    /** Get active count */
+    getActive(): number;
+    /** Get limit */
+    getLimit(): number;
+    /** Update limit */
+    setLimit(limit: number): void;
+}
+/** Job location for indexing */
+export type JobLocation = {
+    type: 'queue';
+    shardIdx: number;
+    queueName: string;
+} | {
+    type: 'processing';
+    shardIdx: number;
+    queueName: string;
+} | {
+    type: 'completed';
+    queueName: string;
+} | {
+    type: 'dlq';
+    queueName: string;
+};
+/** Event types for subscribers */
+export declare const enum EventType {
+    Pushed = "pushed",
+    Pulled = "pulled",
+    Completed = "completed",
+    Failed = "failed",
+    Progress = "progress",
+    Stalled = "stalled",
+    Removed = "removed",
+    Delayed = "delayed",
+    Duplicated = "duplicated",
+    Retried = "retried",
+    WaitingChildren = "waiting-children",
+    Drained = "drained",
+    Paused = "paused",
+    Resumed = "resumed"
+}
+/** Job event for subscribers */
+export interface JobEvent {
+    readonly eventType: EventType;
+    readonly queue: string;
+    readonly jobId: string;
+    readonly timestamp: number;
+    readonly data?: unknown;
+    readonly error?: string;
+    readonly progress?: number;
+    /** Previous state (for removed, retried events) */
+    readonly prev?: string;
+    /** Delay in ms (for delayed event) */
+    readonly delay?: number;
+    /** Internal marker used to exclude retry-attempt failures from terminal metrics. */
+    readonly terminal?: boolean;
+}
+/** Webhook configuration */
+export interface Webhook {
+    readonly id: string;
+    readonly url: string;
+    readonly events: EventType[];
+    readonly queue: string | null;
+    readonly secret: string | null;
+}

package/dist/types/src/domain/types/response.d.ts

@@ -0,0 +1,3 @@
+/** Stable import surface for protocol response types and builders. */
+export * from "./responses/model.js";
+export * from "../response/builders.js";

package/dist/types/src/domain/types/responses/model.d.ts

@@ -0,0 +1,152 @@
+import type { Job, JobState } from "../job.js";
+import type { ProtocolCapability } from "../protocol.js";
+export type { ProtocolCapability } from "../protocol.js";
+interface BaseResponse {
+    readonly ok: boolean;
+    readonly reqId?: string;
+}
+export interface OkResponse extends BaseResponse {
+    readonly ok: true;
+    readonly id?: string;
+}
+export interface BatchResponse extends BaseResponse {
+    readonly ok: true;
+    readonly ids: string[];
+}
+export interface JobResponse extends BaseResponse {
+    readonly ok: true;
+    readonly job: Job;
+}
+export interface NullableJobResponse extends BaseResponse {
+    readonly ok: true;
+    readonly job: Job | null;
+}
+export interface PulledJobResponse extends BaseResponse {
+    readonly ok: true;
+    readonly job: Job | null;
+    readonly token: string | null;
+}
+export interface PulledJobsResponse extends BaseResponse {
+    readonly ok: true;
+    readonly jobs: Job[];
+    readonly tokens: string[];
+}
+export interface JobsResponse extends BaseResponse {
+    readonly ok: true;
+    readonly jobs: Job[];
+}
+export interface StateResponse extends BaseResponse {
+    readonly ok: true;
+    readonly id: string;
+    readonly state: JobState;
+}
+export interface ResultResponse extends BaseResponse {
+    readonly ok: true;
+    readonly id: string;
+    readonly result: unknown;
+}
+export interface JobCounts {
+    readonly waiting: number;
+    readonly prioritized: number;
+    readonly delayed: number;
+    readonly active: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly 'waiting-children': number;
+    readonly paused: number;
+}
+export interface JobCountsResponse extends BaseResponse {
+    readonly ok: true;
+    readonly counts: JobCounts;
+}
+export interface QueueInfo {
+    readonly name: string;
+    readonly waiting: number;
+    readonly delayed: number;
+    readonly active: number;
+    readonly paused: boolean;
+}
+export interface QueuesResponse extends BaseResponse {
+    readonly ok: true;
+    readonly queues: QueueInfo[];
+}
+export interface ProgressResponse extends BaseResponse {
+    readonly ok: true;
+    readonly progress: number;
+    readonly message: string | null;
+}
+export interface BoolResponse extends BaseResponse {
+    readonly ok: true;
+    readonly value: boolean;
+}
+export interface CountResponse extends BaseResponse {
+    readonly ok: true;
+    readonly count: number;
+    readonly ids?: string[];
+}
+export interface StatsData {
+    readonly waiting: number;
+    readonly active: number;
+    readonly delayed: number;
+    readonly dlq: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly uptime: number;
+    readonly pushPerSec: number;
+    readonly pullPerSec: number;
+}
+export interface StatsResponse extends BaseResponse {
+    readonly ok: true;
+    readonly stats: StatsData;
+}
+export interface MetricsData {
+    readonly totalPushed: number;
+    readonly totalPulled: number;
+    readonly totalCompleted: number;
+    readonly totalFailed: number;
+    readonly avgLatencyMs: number;
+    readonly avgProcessingMs: number;
+    readonly memoryUsageMb: number;
+    readonly sqliteSizeMb: number;
+    readonly activeConnections: number;
+}
+export interface MetricsResponse extends BaseResponse {
+    readonly ok: true;
+    readonly metrics: MetricsData;
+}
+export interface CronInfo {
+    readonly name: string;
+    readonly jobName?: string;
+    readonly queue: string;
+    readonly schedule: string | null;
+    readonly repeatEvery: number | null;
+    readonly nextRun: number;
+    readonly executions: number;
+    readonly maxLimit?: number | null;
+    readonly timezone?: string | null;
+    readonly priority?: number;
+}
+export interface CronResponse extends BaseResponse {
+    readonly ok: true;
+    readonly cron: CronInfo;
+}
+export interface CronListResponse extends BaseResponse {
+    readonly ok: true;
+    readonly crons: CronInfo[];
+}
+export interface ErrorResponse extends BaseResponse {
+    readonly ok: false;
+    readonly error: string;
+}
+export interface HelloResponse extends BaseResponse {
+    readonly ok: true;
+    readonly protocolVersion: number;
+    readonly capabilities: ProtocolCapability[];
+    readonly server: string;
+    readonly version: string;
+}
+export interface DataResponse<T> extends BaseResponse {
+    readonly ok: true;
+    readonly data: T;
+}
+export type Response = OkResponse | BatchResponse | JobResponse | NullableJobResponse | PulledJobResponse | PulledJobsResponse | JobsResponse | StateResponse | ResultResponse | JobCountsResponse | QueuesResponse | ProgressResponse | BoolResponse | CountResponse | StatsResponse | MetricsResponse | CronResponse | CronListResponse | HelloResponse | ErrorResponse | DataResponse<unknown>;

package/dist/types/src/domain/types/shard.d.ts

@@ -0,0 +1,4 @@
+import type { DlqEntry } from "./dlq.js";
+export interface ShardOptions {
+    onDlqEvicted?: (entry: DlqEntry) => void;
+}