bunqueue-client 0.1.9 → 0.2.1

package/dist/types/src/client/workflow/workflowValidation.d.ts

@@ -0,0 +1,44 @@
+import type { StepDefinition, WorkflowNode } from "./types.js";
+/**
+ * Extract step definitions from an inline builder. Inline nodes run inside one
+ * `wf:step` job, so only plain steps have executable semantics there.
+ */
+export declare function onlySteps(sub: {
+    nodes: readonly WorkflowNode[];
+}, where: string, label?: string): StepDefinition[];
+/** Why an event name cannot be used as a gate, or `null` when it can. */
+export declare function unusableEventName(event: unknown): string | null;
+/**
+ * A delivered signal is retained by event name rather than consumed, so two gates
+ * sharing a name would both be opened by one delivery.
+ */
+export declare function assertNoDuplicateWaitFor(wf: {
+    name: string;
+    nodes: readonly {
+        type: string;
+        event?: string;
+    }[];
+}): void;
+type RegistrableWorkflow = {
+    name: string;
+    nodes: readonly WorkflowNode[];
+    getStepNames(): string[];
+    getIndexedStepNames(): string[];
+};
+/**
+ * Reject both engine namespace collisions and names colliding with the
+ * `name:index` records generated by loops.
+ */
+export declare function assertNoIndexCollision(wf: RegistrableWorkflow): void;
+/**
+ * `retry` is the total number of attempts. Zero/non-integral values would make the
+ * runner skip the handler and fabricate a failure record.
+ */
+export declare function assertUsableRetry(step: string, retry: number | undefined): void;
+/** Timeout values are finite milliseconds; zero deliberately means no forward bound. */
+export declare function assertUsableTimeout(where: string, timeout: number | undefined): void;
+/** Polling delays and child deadlines cannot be disabled or spin at zero. */
+export declare function assertPositiveDuration(where: string, duration: number | undefined): void;
+/** Loop limits must bound the number of body executions exactly. */
+export declare function assertUsableIterations(where: string, maxIterations: number | undefined): void;
+export {};

package/dist/types/src/config/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * bunqueue Configuration
+ * Global config file support with defineConfig helper
+ */
+export { defineConfig } from "./types.js";
+export type { BunqueueConfig } from "./types.js";
+export { loadConfigFile } from "./loader.js";
+export { resolveServerConfig, resolveCloudConfig, resolveBackupConfig, resolveTlsServerOptions, } from "./resolve.js";
+export type { ResolvedConfig } from "./resolve.js";

package/dist/types/src/config/loader.d.ts

@@ -0,0 +1,7 @@
+/**
+ * bunqueue Config File Loader
+ * Auto-discovers and loads bunqueue.config.{ts,js,mjs}
+ */
+import type { BunqueueConfig } from "./types.js";
+/** Load config file from explicit path or auto-discover in CWD */
+export declare function loadConfigFile(explicitPath?: string): Promise<BunqueueConfig | null>;

package/dist/types/src/config/resolve.d.ts

@@ -0,0 +1,59 @@
+/**
+ * bunqueue Config Resolver
+ * Merges config file + env vars + defaults (config file wins)
+ */
+import type { BunqueueConfig } from "./types.js";
+import type { CloudConfig } from "../infrastructure/cloud/types.js";
+import type { S3BackupConfig } from "../infrastructure/backup/s3BackupConfig.js";
+/** Fully resolved server configuration */
+export interface ResolvedConfig {
+    tcpPort: number;
+    httpPort: number;
+    hostname: string;
+    tcpSocketPath: string | undefined;
+    httpSocketPath: string | undefined;
+    tlsCertFile: string | undefined;
+    tlsKeyFile: string | undefined;
+    authTokens: string[];
+    dataPath: string | undefined;
+    storageDriver: 'memory' | 'sqlite' | 'postgres';
+    postgresUrl: string | undefined;
+    postgresNamespace: string;
+    postgresBrokerId: string | undefined;
+    postgresPoolSize: number;
+    postgresLeaseDurationMs: number;
+    postgresPollIntervalMs: number;
+    postgresStatementTimeoutMs: number;
+    postgresLockTimeoutMs: number;
+    postgresIdleTransactionTimeoutMs: number;
+    postgresMaxConcurrentOperations: number;
+    postgresMaxQueuedOperations: number;
+    postgresMaxSnapshotJobs: number;
+    postgresMaxSnapshotPayloadBytes: number;
+    maxCompletedJobs: number;
+    completedRetentionMs: number | null;
+    corsOrigins: string[];
+    requireAuthForMetrics: boolean;
+    maxPrometheusQueues: number;
+    s3BackupEnabled: boolean;
+    shutdownTimeoutMs: number;
+    statsIntervalMs: number;
+}
+/** Resolve server config: config file > env vars > defaults */
+export declare function resolveServerConfig(fileConfig: BunqueueConfig | null): ResolvedConfig;
+/**
+ * Resolve server TLS options from resolved config. Returns null when TLS is
+ * not configured; throws when only one of cert/key is set (fail fast at
+ * startup rather than serving plaintext when the operator expected TLS).
+ */
+export declare function resolveTlsServerOptions(config: {
+    tlsCertFile?: string;
+    tlsKeyFile?: string;
+}): {
+    certFile: string;
+    keyFile: string;
+} | null;
+/** Resolve cloud config: config file > env vars. Returns null if disabled. */
+export declare function resolveCloudConfig(fileConfig: BunqueueConfig | null, dataPath?: string): CloudConfig | null;
+/** Resolve S3 backup config: config file > env vars */
+export declare function resolveBackupConfig(fileConfig: BunqueueConfig | null, databasePath: string): S3BackupConfig;

package/dist/types/src/config/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * bunqueue Configuration Types
+ * Global configuration file interface and defineConfig helper
+ */
+/** Global bunqueue configuration (all sections optional) */
+export interface BunqueueConfig {
+    server?: {
+        tcpPort?: number;
+        httpPort?: number;
+        host?: string;
+        tcpSocketPath?: string;
+        httpSocketPath?: string;
+        /** Path to PEM certificate file — enables native TLS on TCP + HTTP (with tlsKeyFile) */
+        tlsCertFile?: string;
+        /** Path to PEM private key file — enables native TLS on TCP + HTTP (with tlsCertFile) */
+        tlsKeyFile?: string;
+    };
+    auth?: {
+        tokens?: string[];
+        requireAuthForMetrics?: boolean;
+    };
+    storage?: {
+        /** Persistence backend. Inferred from url/dataPath when omitted. */
+        driver?: 'memory' | 'sqlite' | 'postgres';
+        dataPath?: string;
+        /** PostgreSQL connection URL. Required when driver is postgres. */
+        url?: string;
+        /** Isolates independent bunqueue installations sharing one PostgreSQL database. */
+        namespace?: string;
+        /** Stable identifier for this broker process; generated automatically when omitted. */
+        brokerId?: string;
+        poolSize?: number;
+        leaseDurationMs?: number;
+        pollIntervalMs?: number;
+        statementTimeoutMs?: number;
+        lockTimeoutMs?: number;
+        idleTransactionTimeoutMs?: number;
+        maxConcurrentOperations?: number;
+        maxQueuedOperations?: number;
+        maxSnapshotJobs?: number;
+        maxSnapshotPayloadBytes?: number;
+        /** Hot in-memory completed-job window; this is not durable retention. */
+        maxCompletedJobs?: number;
+        /** Automatic age-based completed-job retention in milliseconds; null disables it. */
+        completedRetentionMs?: number | null;
+    };
+    telemetry?: {
+        /** Maximum queue label values exposed to Prometheus; zero disables per-queue series. */
+        maxPrometheusQueues?: number;
+    };
+    cors?: {
+        origins?: string[];
+    };
+    cloud?: {
+        url?: string;
+        apiKey?: string;
+        instanceId?: string;
+    };
+    backup?: {
+        enabled?: boolean;
+        bucket?: string;
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        sessionToken?: string;
+        region?: string;
+        endpoint?: string;
+        virtualHostedStyle?: boolean;
+        interval?: number;
+        retention?: number;
+        prefix?: string;
+    };
+    timeouts?: {
+        shutdown?: number;
+        stats?: number;
+        worker?: number;
+        lock?: number;
+    };
+    webhooks?: {
+        maxRetries?: number;
+        retryDelay?: number;
+    };
+    logging?: {
+        level?: 'debug' | 'info' | 'warn' | 'error';
+        format?: 'text' | 'json';
+    };
+}
+/** Type-safe config helper for intellisense */
+export declare function defineConfig(config: BunqueueConfig): BunqueueConfig;

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

@@ -0,0 +1,14 @@
+export declare const DEFAULT_MAX_BACKOFF = 3600000;
+export declare const MAX_TIMELINE_ENTRIES = 20;
+export declare const DEFAULT_LOCK_TTL = 30000;
+export declare const JOB_DEFAULTS: {
+    readonly priority: 0;
+    readonly maxAttempts: 3;
+    readonly backoff: 1000;
+    readonly lifo: false;
+    readonly removeOnComplete: false;
+    readonly removeOnFail: false;
+    readonly stackTraceLimit: 10;
+};
+/** Upper bound accepted for `backoff`, `backoff.delay` and `backoff.maxDelay` (24 hours). */
+export declare const MAX_BACKOFF_DELAY = 86400000;

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

@@ -0,0 +1,9 @@
+import type { Job, JobId, JobInput } from "../types/jobs/model.js";
+/**
+ * Keep a caller-supplied retry-delay cap only when it is usable. Embedded and
+ * cron admission do not pass through the server validator, so a non-numeric,
+ * non-finite, negative or over-limit value is dropped and the default cap applies
+ * instead of turning the retry delay into NaN or an unbounded wait.
+ */
+export declare function parseMaxDelay(value: unknown): number | undefined;
+export declare function createJob(id: JobId, queue: string, input: JobInput, now?: number): Job;

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

@@ -0,0 +1,9 @@
+import type { Job } from "../types/jobs/model.js";
+/** Read the broker-internal admission order used by grouped FIFO lanes. */
+export declare function getGroupFifoOrder(job: Job): bigint | null;
+/** Stamp a stable order without exposing it through the public job protocol. */
+export declare function setGroupFifoOrder(job: Job, order: bigint): void;
+/** Preserve the hidden order when an immutable job replacement is created. */
+export declare function copyGroupFifoOrder(source: Job, target: Job): void;
+/** Restore a validated decimal order from SQLite extended options. */
+export declare function restoreGroupFifoOrder(job: Job, stored: string | null): void;

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

@@ -0,0 +1,7 @@
+import type { JobId, LockToken } from "../types/jobs/model.js";
+export declare function isWellFormedJobId(id: string): boolean;
+export declare function assertWellFormedJobId(id: string, name?: string): void;
+export declare function jobId(id: string): JobId;
+export declare function generateJobId(): JobId;
+export declare function lockToken(token: string): LockToken;
+export declare function generateLockToken(): LockToken;

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

@@ -0,0 +1,16 @@
+import type { Job, JobId, JobLock } from "../types/jobs/model.js";
+export declare function createJobLock(jobId: JobId, owner: string, ttl?: number, now?: number): JobLock;
+export declare function isLockExpired(lock: JobLock, now?: number): boolean;
+export declare function renewLock(lock: JobLock, newTtl?: number, now?: number): void;
+/**
+ * True when `lock` was created for an earlier processing generation of `job`,
+ * that is, the job was pulled again after the lease was granted. Stall retry
+ * deliberately keeps the previous lease as a stale-outcome guard, so a lease in
+ * `jobLocks` is not necessarily the current one.
+ *
+ * Pull stamps `startedAt` from a clock read taken before the lease is created
+ * in the same delivery, so a lease from the current pull always has
+ * `createdAt >= startedAt`. The comparison is strict: a lease created in the
+ * same millisecond as the pull belongs to the current generation.
+ */
+export declare function isLeaseFromEarlierGeneration(job: Pick<Job, 'startedAt'>, lock: Pick<JobLock, 'createdAt'>): boolean;

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

@@ -0,0 +1,18 @@
+export interface JobPayloadSource {
+    readonly name?: unknown;
+    readonly data: unknown;
+}
+export interface NormalizedJobPayload {
+    readonly name: string;
+    readonly data: unknown;
+    readonly legacy: boolean;
+}
+/** Return the stable public validation error for an invalid job name. */
+export declare function validateJobName(name: unknown): string | null;
+/**
+ * Resolve a modern payload. A missing explicit name defaults without inspecting
+ * `data`, so direct QueueManager callers can use `data.name` as an ordinary key.
+ */
+export declare function normalizeJobPayload(source: JobPayloadSource, fallback?: string): NormalizedJobPayload;
+/** Decode a pre-2.8.56 wire or persistence envelope at a known legacy boundary. */
+export declare function normalizeLegacyJobPayload(source: JobPayloadSource, fallback?: string): NormalizedJobPayload;

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

@@ -0,0 +1,23 @@
+import type { Job } from "../types/jobs/model.js";
+export declare function normalizeStacktrace(lines: readonly unknown[] | undefined, limit: number): string[] | null;
+export declare function isDelayed(job: Job, now?: number): boolean;
+export declare function isReady(job: Job, now?: number): boolean;
+export declare function isExpired(job: Job, now?: number): boolean;
+export declare function isTimedOut(job: Job, now?: number): boolean;
+export declare function calculateBackoff(job: Job): number;
+/**
+ * Wait applied when a processor throws `DelayedError`. It is always a positive
+ * finite number of milliseconds: DelayedError never counts an attempt, so a zero
+ * wait would let a processor that keeps throwing it re-pull the job in a tight
+ * loop with nothing to stop it.
+ *
+ * The base is the configured delay with no attempt growth and no jitter:
+ * `backoff.delay` for the object form, otherwise the numeric `backoff`. A base
+ * that is not a positive number (0, missing, negative or NaN) falls back to the
+ * 1000 ms default. The base is then capped at `backoff.maxDelay` when that is a
+ * positive finite number, otherwise at DEFAULT_MAX_BACKOFF. A `maxDelay` of 0
+ * means "retry failures immediately" and does not apply here, because
+ * DelayedError is not a failure: such a job waits its capped base delay.
+ */
+export declare function calculateDelayedErrorDelay(job: Pick<Job, 'backoff' | 'backoffConfig'>): number;
+export declare function canRetry(job: Job): boolean;

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

@@ -0,0 +1,3 @@
+import type { Job } from "../types/job.js";
+/** Return the most recent persisted processor failure for a job. */
+export declare function lastFailedReason(job: Pick<Job, 'timeline'>): string | undefined;

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

@@ -0,0 +1,78 @@
+/**
+ * DependencyTracker - Tracks job dependencies and parent-child relationships
+ */
+import type { Job, JobId } from "../types/job.js";
+/**
+ * Manages job dependency tracking for a shard
+ * Provides O(1) lookup when dependencies complete
+ */
+export declare class DependencyTracker {
+    /** Jobs waiting for dependencies */
+    readonly waitingDeps: Map<JobId, Job>;
+    /**
+     * Reverse index: depId -> Set of jobIds waiting for that dependency
+     * Enables O(1) lookup when a dependency completes instead of O(n) scan
+     */
+    readonly dependencyIndex: Map<JobId, Set<JobId>>;
+    /** Parent jobs waiting for children to complete */
+    readonly waitingChildren: Map<JobId, Job>;
+    /**
+     * Register a job's dependencies in the reverse index
+     * Call when adding a job to waitingDeps
+     */
+    registerDependencies(jobId: JobId, dependsOn: JobId[]): void;
+    /**
+     * Unregister a job's dependencies from the reverse index
+     * Call when removing a job from waitingDeps
+     */
+    unregisterDependencies(jobId: JobId, dependsOn: JobId[]): void;
+    /**
+     * Get jobs waiting for a specific dependency - O(1)
+     */
+    getJobsWaitingFor(depId: JobId): Set<JobId> | undefined;
+    /**
+     * Add a job that is waiting for dependencies
+     */
+    addWaitingJob(job: Job): void;
+    /**
+     * Remove a job from waiting deps
+     */
+    removeWaitingJob(jobId: JobId): Job | undefined;
+    /**
+     * Get a job waiting for dependencies
+     */
+    getWaitingJob(jobId: JobId): Job | undefined;
+    /**
+     * Check if a job is waiting for dependencies
+     */
+    isWaiting(jobId: JobId): boolean;
+    /**
+     * Add a parent job waiting for children
+     */
+    addWaitingParent(job: Job): void;
+    /**
+     * Remove a parent job from waiting
+     */
+    removeWaitingParent(jobId: JobId): Job | undefined;
+    /**
+     * Remove every dependency-gated job owned by a queue.
+     * Returns the removed ids so the caller can purge global indexes and storage.
+     */
+    removeQueue(queue: string): JobId[];
+    /**
+     * Get a parent job waiting for children
+     */
+    getWaitingParent(jobId: JobId): Job | undefined;
+    /**
+     * Check if a parent is waiting for children
+     */
+    isParentWaiting(jobId: JobId): boolean;
+    /**
+     * Get counts for debugging
+     */
+    getCounts(): {
+        waitingDeps: number;
+        dependencyIndex: number;
+        waitingChildren: number;
+    };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * DlqShard - Dead Letter Queue operations for a shard
+ */
+import type { Job, JobId } from "../types/job.js";
+import type { DlqEntry, DlqConfig, DlqFilter } from "../types/dlq.js";
+import { FailureReason } from "../types/dlq.js";
+import type { StallConfig } from "../types/stall.js";
+/** Stats callback for counter updates */
+export interface DlqStatsCallback {
+    incrementDlq(): void;
+    decrementDlq(count?: number): void;
+    onEvict?(entry: DlqEntry): void;
+}
+/**
+ * Manages Dead Letter Queue operations for a shard
+ */
+export declare class DlqShard {
+    /** Dead letter queue by queue name */
+    private readonly dlq;
+    /** DLQ configuration per queue */
+    private readonly dlqConfig;
+    /** Stall configuration per queue */
+    private readonly stallConfig;
+    /** Stats callback for counter updates */
+    private readonly stats;
+    constructor(stats: DlqStatsCallback);
+    /** Get DLQ config for queue */
+    getConfig(queue: string): DlqConfig;
+    /** Set DLQ config for queue */
+    setConfig(queue: string, config: Partial<DlqConfig>): void;
+    /** Get stall config for queue */
+    getStallConfig(queue: string): StallConfig;
+    /** Set stall config for queue */
+    setStallConfig(queue: string, config: Partial<StallConfig>): void;
+    /** Add job to DLQ with full metadata */
+    add(job: Job, reason?: FailureReason, error?: string | null): DlqEntry;
+    /** Restore an existing DlqEntry (for recovery from persistence) */
+    restoreEntry(queue: string, entry: DlqEntry): void;
+    /** Get DLQ entries (raw) */
+    getEntries(queue: string): DlqEntry[];
+    /** Get DLQ jobs (for backward compatibility) */
+    getJobs(queue: string, count?: number): Job[];
+    /** Get DLQ entries with filter */
+    getFiltered(queue: string, filter: DlqFilter): DlqEntry[];
+    /** Remove entry from DLQ by job ID */
+    remove(queue: string, jobId: JobId): DlqEntry | null;
+    /** Remove every entry with the same job ID from one queue. */
+    removeAll(queue: string, jobId: JobId): DlqEntry[];
+    /** Get entries ready for auto-retry */
+    getAutoRetryEntries(queue: string, now?: number): DlqEntry[];
+    /** Get expired entries for cleanup */
+    getExpiredEntries(queue: string, now?: number): DlqEntry[];
+    /** Remove expired entries */
+    purgeExpired(queue: string, now?: number): number;
+    /** Clear DLQ for queue */
+    clear(queue: string): number;
+    /** Get DLQ count for queue */
+    getCount(queue: string): number;
+    /** Get all queue names with DLQ entries */
+    getQueueNames(): string[];
+    /** Get queue names with persisted DLQ or stall policy. */
+    getConfiguredQueueNames(): string[];
+    /** Delete queue data */
+    deleteQueue(queue: string): number;
+    private evictUntil;
+}

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

@@ -0,0 +1,30 @@
+import { type GroupPullOptions, type GroupRateLimitOverride } from "../types/group.js";
+export interface GroupLimitStatus {
+    eligible: boolean;
+    retryAt: number | null;
+}
+/** Stored group overrides and broker-authoritative runtime rate windows. */
+export declare class GroupLimiterManager {
+    private readonly rateOverrides;
+    private readonly concurrencyOverrides;
+    private readonly windows;
+    private readonly manualRateLimits;
+    private readonly paused;
+    status(queue: string, groupId: string, defaults: GroupPullOptions | undefined, active: number, now?: number): GroupLimitStatus;
+    acquire(queue: string, groupId: string, defaults: GroupPullOptions | undefined, active: number, now?: number): boolean;
+    setRateLimit(queue: string, groupId: string, max: number, duration: number): void;
+    getRateLimit(queue: string, groupId: string): GroupRateLimitOverride | null;
+    removeRateLimit(queue: string, groupId: string): number;
+    getRateLimitTtl(queue: string, groupId: string, maxJobs?: number, now?: number): number;
+    setConcurrency(queue: string, groupId: string, concurrency: number): void;
+    getConcurrency(queue: string, groupId: string): number | null;
+    removeConcurrency(queue: string, groupId: string): number;
+    pause(queue: string, groupId: string): boolean;
+    resume(queue: string, groupId: string): boolean;
+    isPaused(queue: string, groupId: string): boolean;
+    rateLimit(queue: string, groupId: string, duration: number, now?: number): void;
+    getQueueNames(): string[];
+    clearQueue(queue: string): void;
+    pruneExpiredWindows(now?: number): void;
+    private currentWindow;
+}

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

@@ -0,0 +1,31 @@
+import { type Job } from "../types/job.js";
+export interface GroupEligibility {
+    eligible: boolean;
+    retryAt: number | null;
+}
+export interface GroupCandidate {
+    job: Job | null;
+    nextRunAt: number | null;
+}
+/** Lazy secondary ready/group indexes; the primary queue remains authoritative. */
+export declare class GroupScheduler {
+    private readonly queues;
+    private nextFifoOrder;
+    assignFifoOrder(job: Job): void;
+    observeFifoOrder(job: Job): void;
+    insert(queue: string, job: Job, primaryJobs: () => readonly Job[], now?: number): boolean;
+    remove(queue: string, job: Job): boolean;
+    isActive(queue: string): boolean;
+    peek(queue: string, now: number, eligibility: (groupId: string) => GroupEligibility, affinity?: string | null): GroupCandidate;
+    advance(queue: string, groupId: string): void;
+    getGroupJobsCount(queue: string, groupId: string): number;
+    getGroupsJobsCount(queue: string): number;
+    clearQueue(queue: string): void;
+    private createState;
+    private insertTracked;
+    private promoteDue;
+    private insertReady;
+    private demoteReady;
+    private attachLane;
+    private detachLane;
+}

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

@@ -0,0 +1,6 @@
+import type { Job } from "../types/job.js";
+import type { HeapEntry } from "../types/priorityQueue.js";
+export declare function orderedGroupClone(job: Job, runAt?: number): Job;
+export declare function nextGroupCheckAt(job: Job): number;
+export declare function compareGroupFifoEntries(left: HeapEntry, right: HeapEntry): number;
+export declare function compareGroupWakeEntries(left: HeapEntry, right: HeapEntry): number;

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

@@ -0,0 +1,68 @@
+/**
+ * LimiterManager - Rate limiting and concurrency control
+ */
+import { type QueueState } from "../types/queue.js";
+/**
+ * Manages rate limiting and concurrency for queues
+ */
+export declare class LimiterManager {
+    /** Queue state (pause, rate limit, concurrency) */
+    private readonly queueState;
+    /** Rate limiters per queue */
+    private readonly rateLimiters;
+    /** Concurrency limiters per queue */
+    private readonly concurrencyLimiters;
+    /** Get queue state */
+    getState(name: string): QueueState;
+    /** Check if queue is paused */
+    isPaused(name: string): boolean;
+    /** Pause queue */
+    pause(name: string): void;
+    /** Resume queue */
+    resume(name: string): void;
+    /**
+     * Set rate limit for queue.
+     * @param durationMs window the limit applies to (default 1000ms): `limit`
+     *   tokens refill over `durationMs`. Non-finite or non-positive → default.
+     * @param ttlMs auto-expiry: the limit clears itself after this many ms
+     *   (lazy, checked on acquire/read). Non-finite or non-positive → permanent.
+     */
+    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
+    /** Clear rate limit */
+    clearRateLimit(queue: string): void;
+    /**
+     * Drop the rate limit if its TTL has elapsed. Lazy expiry: called from the
+     * acquire path and from limit reads, so no timer is needed and an expired
+     * limit can never throttle a pull.
+     */
+    expireRateLimitIfNeeded(queue: string, now?: number): void;
+    /** Try to acquire rate limit token */
+    tryAcquireRateLimit(queue: string): boolean;
+    /** Read the active rate-limit configuration after applying lazy expiry. */
+    getRateLimit(queue: string): {
+        max: number;
+        duration: number;
+    } | null;
+    /** Read the remaining temporary-limit TTL or token-bucket cooldown. */
+    getRateLimitTtl(queue: string, maxJobs?: number): number;
+    /** Set concurrency limit for queue */
+    setConcurrency(queue: string, limit: number): void;
+    /** Clear concurrency limit */
+    clearConcurrency(queue: string): void;
+    /** Try to acquire concurrency slot */
+    tryAcquireConcurrency(queue: string): boolean;
+    /** Release concurrency slot */
+    releaseConcurrency(queue: string): void;
+    /** Read the configured global concurrency limit. */
+    getConcurrency(queue: string): number | null;
+    /** Whether all configured global concurrency slots are currently occupied. */
+    isConcurrencyMaxed(queue: string): boolean;
+    /** Get all queue names with state */
+    getQueueNames(): string[];
+    /** Get queues whose state contains an explicit policy rather than read-created defaults. */
+    getConfiguredQueueNames(now?: number): string[];
+    /** Delete queue data */
+    deleteQueue(queue: string): void;
+    /** Get the underlying state map (for backward compatibility) */
+    getStateMap(): Map<string, QueueState>;
+}

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

@@ -0,0 +1,54 @@
+import type { Job, JobId } from "../types/job.js";
+import type { HeapEntry } from "../types/priorityQueue.js";
+export interface PriorityQueueHooks {
+    onInsert(job: Job): boolean;
+    onRemove(job: Job): boolean;
+}
+export type PriorityQueueComparator = (left: HeapEntry, right: HeapEntry) => number;
+export type PriorityQueueOrder = (job: Job) => bigint | null;
+/** Indexed map-backed 4-ary heap with O(log4 n) mutations and O(1) lookup. */
+export declare class IndexedPriorityQueue {
+    private readonly hooks?;
+    private readonly compare;
+    private readonly order?;
+    private static readonly D;
+    private heap;
+    private readonly index;
+    private generation;
+    private hooksActive;
+    constructor(hooks?: PriorityQueueHooks | undefined, compare?: PriorityQueueComparator, order?: PriorityQueueOrder | undefined);
+    get size(): number;
+    get isEmpty(): boolean;
+    push(job: Job): void;
+    pop(): Job | null;
+    peek(): Job | null;
+    find(jobId: JobId): Job | null;
+    has(jobId: JobId): boolean;
+    remove(jobId: JobId): Job | null;
+    /** Update job priority - O(log n). Optionally update the LIFO tie-break flag. */
+    updatePriority(jobId: JobId, newPriority: number, newLifo?: boolean): boolean;
+    /** Update job runAt (for delay changes) - O(log n) */
+    updateRunAt(jobId: JobId, newRunAt: number): boolean;
+    values(): Job[];
+    clear(): void;
+    /**
+     * Get the ratio of stale entries in the heap
+     * Used to decide when to compact
+     */
+    getStaleRatio(): number;
+    /**
+     * Compact the heap by removing stale entries
+     * Call when stale ratio exceeds threshold (e.g., 20%)
+     * O(n) operation but reclaims memory and improves performance
+     */
+    compact(): void;
+    private heapify;
+    /** Check if compaction is needed (stale ratio > threshold) */
+    needsCompaction(threshold?: number): boolean;
+    private removeTop;
+    /** 4-ary bubbleUp: parent at floor((idx-1)/D) */
+    private bubbleUp;
+    /** 4-ary bubbleDown: children at D*idx+1 through D*idx+D */
+    private bubbleDown;
+    private swap;
+}