bunqueue 2.8.60 → 2.9.2

package/dist/application/postgres-queue-manager/control.js

@@ -0,0 +1,210 @@
+import { DEFAULT_DLQ_CONFIG } from '../../domain/types/dlq';
+import { DEFAULT_STALL_CONFIG } from '../../domain/types/stall';
+import { normalizePostgresRateLimit } from '../../infrastructure/persistence/postgres/rateLimit';
+import { PostgresQueueManagerMaintenance } from './maintenance';
+const PENDING_STATES = ['waiting', 'prioritized', 'delayed', 'waiting-children'];
+function normalizeDlq(current, patch) {
+    const next = { ...current };
+    if (typeof patch.autoRetry === 'boolean')
+        next.autoRetry = patch.autoRetry;
+    if (Number.isFinite(patch.autoRetryInterval)) {
+        next.autoRetryInterval = Math.max(0, Math.floor(patch.autoRetryInterval));
+    }
+    if (Number.isFinite(patch.maxAutoRetries)) {
+        next.maxAutoRetries = Math.max(0, Math.floor(patch.maxAutoRetries));
+    }
+    if (patch.maxAge === null)
+        next.maxAge = null;
+    else if (Number.isFinite(patch.maxAge)) {
+        next.maxAge = Math.max(0, Math.floor(patch.maxAge));
+    }
+    if (Number.isFinite(patch.maxEntries)) {
+        next.maxEntries = Math.max(1, Math.floor(patch.maxEntries));
+    }
+    return next;
+}
+/** Durable queue controls and policies shared by every PostgreSQL broker. */
+export class PostgresQueueManagerControl extends PostgresQueueManagerMaintenance {
+    async setGroupRateLimit(queue, groupId, max, duration) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.setGroupRateLimit(queue, groupId, max, duration);
+        });
+    }
+    async removeGroupRateLimit(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.removeGroupRateLimit(queue, groupId);
+        });
+    }
+    async setGroupConcurrency(queue, groupId, concurrency) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.setGroupConcurrency(queue, groupId, concurrency);
+        });
+    }
+    async removeGroupConcurrency(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.removeGroupConcurrency(queue, groupId);
+        });
+    }
+    pause(queue) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, { paused: true });
+            this.enqueueWrite(() => this.postgresStore.pause(queue, true));
+        });
+    }
+    resume(queue) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, { paused: false });
+            this.enqueueWrite(() => this.postgresStore.pause(queue, false));
+        });
+    }
+    async pauseDurable(queue, paused) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.pause(queue, paused);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    drain(queue) {
+        return this.operations.runSync(() => {
+            const count = this.postgresSnapshot.removeStates(queue, PENDING_STATES);
+            this.enqueueWrite(async () => {
+                await this.postgresStore.drain(queue);
+                await this.refreshQueueAfterCommit(queue);
+            });
+            return count;
+        });
+    }
+    async drainDurable(queue) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const count = await this.postgresStore.drain(queue);
+            await this.refreshQueueAfterCommit(queue);
+            return count;
+        });
+    }
+    obliterate(queue) {
+        this.operations.runSync(() => {
+            this.postgresSnapshot.removeStates(queue, [
+                ...PENDING_STATES,
+                'active',
+                'completed',
+                'failed',
+            ]);
+            this.enqueueWrite(async () => {
+                await this.postgresStore.obliterate(queue);
+                await this.refreshQueueAfterCommit(queue);
+            });
+        });
+    }
+    async obliterateDurable(queue) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.obliterate(queue);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    setRateLimit(queue, limit, durationMs, ttlMs) {
+        this.operations.runSync(() => {
+            const normalized = normalizePostgresRateLimit(durationMs, ttlMs);
+            this.setLocalQueueState(queue, {
+                rateLimit: limit,
+                rateDurationMs: normalized.durationMs,
+                rateExpiresAt: normalized.ttlMs === null ? null : Date.now() + normalized.ttlMs,
+            });
+            this.enqueueWrite(() => this.postgresStore.setRateLimit(queue, limit, normalized.durationMs, normalized.ttlMs));
+        });
+    }
+    clearRateLimit(queue) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, {
+                rateLimit: null,
+                rateDurationMs: null,
+                rateExpiresAt: null,
+            });
+            this.enqueueWrite(() => this.postgresStore.setRateLimit(queue, null, null));
+        });
+    }
+    setConcurrency(queue, limit) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, { concurrencyLimit: limit });
+            this.enqueueWrite(() => this.postgresStore.setConcurrency(queue, limit));
+        });
+    }
+    clearConcurrency(queue) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, { concurrencyLimit: null });
+            this.enqueueWrite(() => this.postgresStore.setConcurrency(queue, null));
+        });
+    }
+    async setRateLimitDurable(queue, limit, durationMs, ttlMs) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const normalized = normalizePostgresRateLimit(durationMs, ttlMs);
+            await this.postgresStore.setRateLimit(queue, limit, normalized.durationMs, normalized.ttlMs);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    async setConcurrencyDurable(queue, limit) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.setConcurrency(queue, limit);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    setStallConfig(queue, patch) {
+        this.operations.runSync(() => {
+            const config = { ...this.getStallConfig(queue), ...patch };
+            this.setLocalQueueState(queue, { stallConfig: config });
+            this.enqueueWrite(() => this.postgresStore.setStallConfig(queue, config));
+        });
+    }
+    getStallConfig(queue) {
+        return this.postgresSnapshot.queueState(queue)?.stallConfig ?? DEFAULT_STALL_CONFIG;
+    }
+    async setStallConfigDurable(queue, patch) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const state = await this.postgresStore.getQueueState(queue);
+            const config = { ...state.stallConfig, ...patch };
+            await this.postgresStore.setStallConfig(queue, config);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    setDlqConfig(queue, patch) {
+        this.operations.runSync(() => {
+            const config = normalizeDlq(this.getDlqConfig(queue), patch);
+            this.setLocalQueueState(queue, { dlqConfig: config });
+            this.enqueueWrite(() => this.postgresStore.setDlqConfig(queue, config));
+        });
+    }
+    getDlqConfig(queue) {
+        return this.postgresSnapshot.queueState(queue)?.dlqConfig ?? DEFAULT_DLQ_CONFIG;
+    }
+    async setDlqConfigDurable(queue, patch) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const state = await this.postgresStore.getQueueState(queue);
+            await this.postgresStore.setDlqConfig(queue, normalizeDlq(state.dlqConfig, patch));
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    setLocalQueueState(queue, patch) {
+        const current = this.postgresSnapshot.queueState(queue) ?? {
+            queue,
+            paused: false,
+            rateLimit: null,
+            rateDurationMs: null,
+            rateWindowStartedAt: null,
+            rateExpiresAt: null,
+            rateCount: 0,
+            concurrencyLimit: null,
+            stallConfig: DEFAULT_STALL_CONFIG,
+            dlqConfig: DEFAULT_DLQ_CONFIG,
+        };
+        this.postgresSnapshot.setQueueState({ ...current, ...patch });
+    }
+}

package/dist/application/postgres-queue-manager/deferredWrites.d.ts

@@ -0,0 +1,13 @@
+export declare function throwDeferredWriteErrors(errors: readonly unknown[], message?: string): void;
+/** Serializes fire-and-forget writes while retaining failures until an observed drain. */
+export declare class PostgresDeferredWriteQueue {
+    private accepting;
+    private tail;
+    private nextSequence;
+    private readonly failures;
+    private checkpoint;
+    enqueue(operation: () => Promise<void>): void;
+    closeAndDrain(): Promise<unknown[]>;
+    drain(): Promise<unknown[]>;
+    flush(): Promise<void>;
+}

package/dist/application/postgres-queue-manager/deferredWrites.js

@@ -0,0 +1,60 @@
+export function throwDeferredWriteErrors(errors, message = 'Multiple deferred PostgreSQL writes failed') {
+    if (errors.length === 0)
+        return;
+    if (errors.length === 1)
+        throw errors[0];
+    throw new AggregateError(errors, message);
+}
+/** Serializes fire-and-forget writes while retaining failures until an observed drain. */
+export class PostgresDeferredWriteQueue {
+    accepting = true;
+    tail = Promise.resolve();
+    nextSequence = 0;
+    failures = [];
+    checkpoint = null;
+    enqueue(operation) {
+        if (!this.accepting)
+            throw new Error('PostgreSQL queue manager is shutting down');
+        const sequence = ++this.nextSequence;
+        this.tail = this.tail.then(async () => {
+            try {
+                await operation();
+            }
+            catch (error) {
+                this.failures.push({ sequence, error });
+            }
+        });
+    }
+    closeAndDrain() {
+        this.accepting = false;
+        return this.drain();
+    }
+    async drain() {
+        const throughSequence = this.nextSequence;
+        const pending = this.checkpoint;
+        if (pending?.sequence === throughSequence)
+            return [...(await pending.result)];
+        const throughTail = this.tail;
+        const checkpoint = {
+            sequence: throughSequence,
+            result: throughTail.then(() => {
+                const firstLaterFailure = this.failures.findIndex(({ sequence }) => sequence > throughSequence);
+                const observed = firstLaterFailure === -1
+                    ? this.failures.splice(0)
+                    : this.failures.splice(0, firstLaterFailure);
+                return observed.map(({ error }) => error);
+            }),
+        };
+        this.checkpoint = checkpoint;
+        try {
+            return [...(await checkpoint.result)];
+        }
+        finally {
+            if (this.checkpoint === checkpoint)
+                this.checkpoint = null;
+        }
+    }
+    async flush() {
+        throwDeferredWriteErrors(await this.drain());
+    }
+}

package/dist/application/postgres-queue-manager/delivery.d.ts

@@ -0,0 +1,20 @@
+import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from '../../domain/types/flow';
+import { type GroupPullOptions } from '../../domain/types/group';
+import { type Job, type JobId, type JobInput } from '../../domain/types/job';
+import { PostgresQueueManagerTerminalDelivery } from './terminalDelivery';
+export declare class PostgresQueueManagerDelivery extends PostgresQueueManagerTerminalDelivery {
+    push(queue: string, input: JobInput): Promise<Job>;
+    pushBatch(queue: string, inputs: JobInput[]): Promise<JobId[]>;
+    pushFlow(batch: AtomicFlowBatchInput): Promise<AtomicFlowBatchResult>;
+    pull(queue: string, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job | null>;
+    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<{
+        job: Job | null;
+        token: string | null;
+    }>;
+    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job[]>;
+    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<{
+        jobs: Job[];
+        tokens: string[];
+    }>;
+    private claimUntil;
+}

package/dist/application/postgres-queue-manager/delivery.js

@@ -0,0 +1,83 @@
+import { assertGroupPullOptions } from '../../domain/types/group';
+import { createJob, DEFAULT_LOCK_TTL, generateJobId, jobId, } from '../../domain/types/job';
+import { validateRepeatJobInput } from '../repeatJobs';
+import { PostgresQueueManagerTerminalDelivery } from './terminalDelivery';
+export class PostgresQueueManagerDelivery extends PostgresQueueManagerTerminalDelivery {
+    async push(queue, input) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            validateRepeatJobInput(input);
+            const id = input.customId ? jobId(input.customId) : generateJobId();
+            const admitted = await this.postgresStore.insert(createJob(id, queue, input, await this.postgresStore.now()));
+            await this.refreshJob(admitted.job.id, queue);
+            return admitted.job;
+        });
+    }
+    async pushBatch(queue, inputs) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            for (const input of inputs)
+                validateRepeatJobInput(input);
+            const now = await this.postgresStore.now();
+            const jobs = inputs.map((input) => createJob(input.customId ? jobId(input.customId) : generateJobId(), queue, input, now));
+            const stored = await this.postgresStore.insertMany(jobs);
+            await this.refreshJobs(stored.map((job) => job.id), queue);
+            return stored.map((job) => job.id);
+        });
+    }
+    async pushFlow(batch) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const jobs = await this.postgresStore.insertFlow(batch);
+            await Promise.all(new Set(jobs.map((job) => job.queue))
+                .values()
+                .map((queue) => this.refreshQueueAfterCommit(queue)));
+            return { jobs };
+        });
+    }
+    async pull(queue, timeoutMs = 0, signal, groupOptions) {
+        const claims = await this.claimUntil(queue, 1, this.postgresStore.config.brokerId, timeoutMs, undefined, signal, groupOptions);
+        return claims[0]?.job ?? null;
+    }
+    // oxlint-disable-next-line max-params -- public API includes cancellation and lease policy
+    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal, groupOptions) {
+        const claims = await this.claimUntil(queue, 1, owner, timeoutMs, lockTtl, signal, groupOptions);
+        const claim = claims[0];
+        return claim ? { job: claim.job, token: claim.token } : { job: null, token: null };
+    }
+    async pullBatch(queue, count, timeoutMs = 0, signal, groupOptions) {
+        const claims = await this.claimUntil(queue, count, this.postgresStore.config.brokerId, timeoutMs, undefined, signal, groupOptions);
+        return claims.map((claim) => claim.job);
+    }
+    // oxlint-disable-next-line max-params -- public API includes cancellation and lease policy
+    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal, groupOptions) {
+        const claims = await this.claimUntil(queue, count, owner, timeoutMs, lockTtl, signal, groupOptions);
+        return {
+            jobs: claims.map((claim) => claim.job),
+            tokens: claims.map((claim) => claim.token),
+        };
+    }
+    // oxlint-disable-next-line max-params -- internal bridge mirrors the public pull contract
+    async claimUntil(queue, count, owner, timeoutMs, leaseDurationMs, signal, groupOptions) {
+        assertGroupPullOptions(groupOptions);
+        await this.postgresReady;
+        await this.flushPostgresWrites();
+        const deadline = Date.now() + Math.max(0, timeoutMs);
+        do {
+            const claims = await this.runPostgresOperation(async () => {
+                const admitted = await this.postgresStore.claim(queue, count, owner, leaseDurationMs, groupOptions);
+                for (const claim of admitted) {
+                    this.applyPostgresClaim(claim);
+                }
+                return admitted;
+            });
+            if (claims.length > 0 || timeoutMs <= 0 || signal?.aborted)
+                return claims;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return [];
+            await this.postgresStore.waitForWork(queue, Math.min(remaining, this.postgresStore.config.pollIntervalMs), signal);
+        } while (!signal?.aborted);
+        return [];
+    }
+}

package/dist/application/postgres-queue-manager/groupQueries.d.ts

@@ -0,0 +1,10 @@
+import { PostgresQueueManagerState } from './state';
+/** Database-authoritative group getters shared by every PostgreSQL broker. */
+export declare class PostgresQueueManagerGroupQueries extends PostgresQueueManagerState {
+    getGroupJobsCount(queue: string, groupId: string): Promise<number>;
+    getGroupsJobsCount(queue: string): Promise<number>;
+    getGroupActiveCount(queue: string, groupId: string): Promise<number>;
+    getGroupRateLimit(queue: string, groupId: string): Promise<import("../../domain/types/group").GroupRateLimitOverride | null>;
+    getGroupRateLimitTtl(queue: string, groupId: string, maxJobs?: number): Promise<number>;
+    getGroupConcurrency(queue: string, groupId: string): Promise<number | null>;
+}

package/dist/application/postgres-queue-manager/groupQueries.js

@@ -0,0 +1,40 @@
+import { PostgresQueueManagerState } from './state';
+/** Database-authoritative group getters shared by every PostgreSQL broker. */
+export class PostgresQueueManagerGroupQueries extends PostgresQueueManagerState {
+    async getGroupJobsCount(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupJobsCount(queue, groupId);
+        });
+    }
+    async getGroupsJobsCount(queue) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupJobsCount(queue);
+        });
+    }
+    async getGroupActiveCount(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupActiveCount(queue, groupId);
+        });
+    }
+    async getGroupRateLimit(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupRateLimit(queue, groupId);
+        });
+    }
+    async getGroupRateLimitTtl(queue, groupId, maxJobs) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupRateLimitTtl(queue, groupId, maxJobs);
+        });
+    }
+    async getGroupConcurrency(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupConcurrency(queue, groupId);
+        });
+    }
+}

package/dist/application/postgres-queue-manager/lease.d.ts

@@ -0,0 +1,13 @@
+import { type JobId, type JobLock, type LockToken } from '../../domain/types/job';
+import { PostgresQueueManagerDelivery } from './delivery';
+export declare class PostgresQueueManagerLease extends PostgresQueueManagerDelivery {
+    extendLock(id: JobId | string, token: string | null, duration: number): Promise<boolean>;
+    heartbeatDurable(id: JobId, token?: string, duration?: number): Promise<boolean>;
+    heartbeatBatchDurable(ids: JobId[], tokens?: string[]): Promise<number>;
+    jobHeartbeat(id: JobId, token?: string): boolean;
+    jobHeartbeatBatch(ids: JobId[], tokens?: string[]): number;
+    verifyLock(id: JobId, token: string): boolean;
+    renewJobLock(id: JobId, token: string, ttl?: number): boolean;
+    getLockInfo(id: JobId): JobLock | null;
+    createLock(id: JobId, _owner: string, _ttl?: number): LockToken | null;
+}

package/dist/application/postgres-queue-manager/lease.js

@@ -0,0 +1,88 @@
+import { DEFAULT_LOCK_TTL, jobId, lockToken, } from '../../domain/types/job';
+import { PostgresQueueManagerDelivery } from './delivery';
+export class PostgresQueueManagerLease extends PostgresQueueManagerDelivery {
+    async extendLock(id, token, duration) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const target = jobId(String(id));
+            const leaseToken = token ?? this.tokenFor(target);
+            if (!leaseToken)
+                return false;
+            const expiresAt = await this.postgresStore.renew(target, leaseToken, duration);
+            if (expiresAt !== null) {
+                await this.refreshJob(target);
+                return true;
+            }
+            this.forgetToken(target);
+            await this.refreshJob(target);
+            return false;
+        });
+    }
+    async heartbeatDurable(id, token, duration) {
+        return await this.runPostgresOperation(async () => {
+            const leaseToken = this.tokenFor(id, token);
+            if (!leaseToken)
+                return false;
+            return await this.extendLock(id, leaseToken, duration ?? this.postgresStore.config.leaseDurationMs);
+        });
+    }
+    async heartbeatBatchDurable(ids, tokens) {
+        return await this.runPostgresOperation(async () => {
+            const renewed = await Promise.all(ids.map((id, index) => this.heartbeatDurable(id, tokens?.[index])));
+            return renewed.filter(Boolean).length;
+        });
+    }
+    jobHeartbeat(id, token) {
+        return this.operations.runSync(() => {
+            const leaseToken = this.tokenFor(id, token);
+            const row = this.postgresSnapshot.get(id);
+            if (!leaseToken || row?.state !== 'active')
+                return false;
+            this.enqueueWrite(async () => {
+                const renewed = await this.postgresStore.renew(id, leaseToken, this.postgresStore.config.leaseDurationMs);
+                if (renewed !== null)
+                    await this.refreshJob(id);
+            });
+            return true;
+        });
+    }
+    jobHeartbeatBatch(ids, tokens) {
+        return this.operations.runSync(() => ids.reduce((count, id, index) => count + (this.jobHeartbeat(id, tokens?.[index]) ? 1 : 0), 0));
+    }
+    verifyLock(id, token) {
+        const row = this.postgresSnapshot.get(id);
+        return row?.state === 'active' && this.tokenFor(id) === token;
+    }
+    renewJobLock(id, token, ttl = DEFAULT_LOCK_TTL) {
+        return this.operations.runSync(() => {
+            if (!this.verifyLock(id, token))
+                return false;
+            this.enqueueWrite(async () => {
+                const renewed = await this.postgresStore.renew(id, token, ttl);
+                if (renewed !== null)
+                    await this.refreshJob(id);
+            });
+            return true;
+        });
+    }
+    getLockInfo(id) {
+        const row = this.postgresSnapshot.get(id);
+        const token = this.tokenFor(id);
+        if (row?.state !== 'active' || !token || row.leaseUntil === null)
+            return null;
+        return {
+            jobId: id,
+            token: lockToken(token),
+            owner: row.leaseOwner ?? this.postgresStore.config.brokerId,
+            createdAt: row.job.startedAt ?? Date.now(),
+            expiresAt: row.leaseUntil,
+            lastRenewalAt: row.job.lastHeartbeat,
+            renewalCount: row.leaseRenewals,
+            ttl: Math.max(1, row.leaseUntil - row.job.lastHeartbeat),
+        };
+    }
+    createLock(id, _owner, _ttl = DEFAULT_LOCK_TTL) {
+        const token = this.tokenFor(id);
+        return token ? lockToken(token) : null;
+    }
+}

package/dist/application/postgres-queue-manager/lifetimeMetrics.d.ts

@@ -0,0 +1,32 @@
+import { EventType } from '../../domain/types/queue';
+import type { PostgresStoreEvent } from '../../infrastructure/persistence/postgres';
+import type { PostgresLifetimeMetricsSnapshot } from '../../infrastructure/persistence/postgres/lifetimeMetrics';
+interface PostgresMetricCounters {
+    readonly totalPushed: {
+        value: bigint;
+    };
+    readonly totalPulled: {
+        value: bigint;
+    };
+    readonly totalCompleted: {
+        value: bigint;
+    };
+    readonly totalFailed: {
+        value: bigint;
+    };
+}
+interface PostgresPerQueueMetrics {
+    clear(): void;
+    get(queue: string): {
+        totalCompleted: bigint;
+        totalFailed: bigint;
+    } | undefined;
+    set(queue: string, totals: {
+        totalCompleted: bigint;
+        totalFailed: bigint;
+    }): unknown;
+}
+export declare function postgresEventType(value: string): EventType | null;
+export declare function hydratePostgresLifetimeMetrics(metrics: PostgresMetricCounters, perQueue: PostgresPerQueueMetrics, snapshot: PostgresLifetimeMetricsSnapshot): void;
+export declare function applyPostgresEventMetrics(metrics: PostgresMetricCounters, perQueue: PostgresPerQueueMetrics, event: PostgresStoreEvent, includeTerminal: boolean): void;
+export {};

package/dist/application/postgres-queue-manager/lifetimeMetrics.js

@@ -0,0 +1,53 @@
+export function postgresEventType(value) {
+    switch (value) {
+        case "pushed" /* EventType.Pushed */:
+        case "pulled" /* EventType.Pulled */:
+        case "completed" /* EventType.Completed */:
+        case "failed" /* EventType.Failed */:
+        case "progress" /* EventType.Progress */:
+        case "stalled" /* EventType.Stalled */:
+        case "removed" /* EventType.Removed */:
+        case "delayed" /* EventType.Delayed */:
+        case "duplicated" /* EventType.Duplicated */:
+        case "retried" /* EventType.Retried */:
+        case "waiting-children" /* EventType.WaitingChildren */:
+        case "drained" /* EventType.Drained */:
+        case "paused" /* EventType.Paused */:
+        case "resumed" /* EventType.Resumed */:
+            return value;
+        default:
+            return null;
+    }
+}
+export function hydratePostgresLifetimeMetrics(metrics, perQueue, snapshot) {
+    metrics.totalCompleted.value = snapshot.totalCompleted;
+    metrics.totalFailed.value = snapshot.totalFailed;
+    perQueue.clear();
+    for (const totals of snapshot.queues) {
+        perQueue.set(totals.queue, {
+            totalCompleted: totals.totalCompleted,
+            totalFailed: totals.totalFailed,
+        });
+    }
+}
+export function applyPostgresEventMetrics(metrics, perQueue, event, includeTerminal) {
+    const type = postgresEventType(event.type);
+    if (type === "pushed" /* EventType.Pushed */)
+        metrics.totalPushed.value++;
+    if (type === "pulled" /* EventType.Pulled */)
+        metrics.totalPulled.value++;
+    const completed = includeTerminal && type === "completed" /* EventType.Completed */;
+    const failed = includeTerminal && type === "failed" /* EventType.Failed */ && event.state === 'failed';
+    if (!completed && !failed)
+        return;
+    const totals = perQueue.get(event.queue) ?? { totalCompleted: 0n, totalFailed: 0n };
+    if (completed) {
+        metrics.totalCompleted.value++;
+        totals.totalCompleted++;
+    }
+    if (failed) {
+        metrics.totalFailed.value++;
+        totals.totalFailed++;
+    }
+    perQueue.set(event.queue, totals);
+}

package/dist/application/postgres-queue-manager/maintenance.d.ts

@@ -0,0 +1,14 @@
+import type { DlqFilter } from '../../domain/types/dlq';
+import type { JobId } from '../../domain/types/job';
+import { PostgresQueueManagerRelationships } from './relationships';
+/** Durable maintenance commands that cannot use the synchronous SQLite façade. */
+export declare class PostgresQueueManagerMaintenance extends PostgresQueueManagerRelationships {
+    retryDlqDurable(queue: string, id?: JobId, count?: number, filter?: DlqFilter): Promise<number>;
+    purgeDlqDurable(queue: string): Promise<number>;
+    removeDlqJobDurable(queue: string, id: JobId): Promise<boolean>;
+    retryCompletedDurable(queue: string, id?: JobId, options?: {
+        limit?: number;
+        timestamp?: number;
+    }): Promise<number>;
+    cleanDurable(queue: string, graceMs: number, state?: string, limit?: number): Promise<JobId[]>;
+}